[core] Allow disabling the useHotkeys help dialog (#8127)

Author: ggdouglas

packages/core/src/components/hotkeys/useHotkeys.stories.tsx

@@ -0,0 +1,116 @@
+/* !
+ * (c) Copyright 2026 Palantir Technologies Inc. All rights reserved.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { storybookLayoutDecorator } from "@storybook-common";
+import { useMemo, useState } from "react";
+
+import { Flex } from "@blueprintjs/labs";
+
+import { type HotkeyConfig, useHotkeys, type UseHotkeysOptions } from "../../hooks";
+import { Code } from "../html/html";
+
+import { KeyComboTag } from "./keyComboTag";
+
+interface UseHotkeysStoryProps {
+    showDialogKeyCombo?: UseHotkeysOptions["showDialogKeyCombo"];
+}
+
+function UseHotkeysStory({ showDialogKeyCombo }: UseHotkeysStoryProps) {
+    const [lastFired, setLastFired] = useState<string>();
+
+    const hotkeys = useMemo<readonly HotkeyConfig[]>(
+        () => [
+            {
+                combo: "mod + c",
+                global: true,
+                group: "Edit",
+                label: "Copy",
+                onKeyDown: () => setLastFired("Copy"),
+            },
+            {
+                combo: "mod + v",
+                global: true,
+                group: "Edit",
+                label: "Paste",
+                onKeyDown: () => setLastFired("Paste"),
+            },
+            {
+                combo: "mod + z",
+                global: true,
+                group: "Edit",
+                label: "Undo",
+                onKeyDown: () => setLastFired("Undo"),
+            },
+            {
+                combo: "mod + shift + z",
+                global: true,
+                group: "Edit",
+                label: "Redo",
+                onKeyDown: () => setLastFired("Redo"),
+            },
+        ],
+        [],
+    );
+
+    useHotkeys(hotkeys, { showDialogKeyCombo });
+
+    return (
+        <Flex flexDirection="column" gap={4} style={{ width: 320 }}>
+            <Flex alignItems="center" gap={3}>
+                <span>Dialog trigger:</span>
+                {showDialogKeyCombo === false ? (
+                    <KeyComboTag combo="(disabled)" />
+                ) : (
+                    <KeyComboTag combo={showDialogKeyCombo ?? "?"} />
+                )}
+            </Flex>
+            <Flex flexDirection="column" gap={2}>
+                {hotkeys.map(({ combo, label }) => (
+                    <Flex key={combo} alignItems="center" gap={3}>
+                        <div style={{ minWidth: 140 }}>
+                            <KeyComboTag combo={combo} />
+                        </div>
+                        <span>{label}</span>
+                    </Flex>
+                ))}
+            </Flex>
+            <Flex alignItems="center" gap={3}>
+                <span>Last fired:</span>
+                <Code>{lastFired ?? "(none)"}</Code>
+            </Flex>
+        </Flex>
+    );
+}
+
+const meta: Meta<typeof UseHotkeysStory> = {
+    title: "Core/Hotkeys/useHotkeys",
+    component: UseHotkeysStory,
+    decorators: [storybookLayoutDecorator],
+    args: {
+        showDialogKeyCombo: "?",
+    },
+    argTypes: {
+        showDialogKeyCombo: {
+            description:
+                "Key combo that opens the built-in help dialog. Pass `false` to disable the trigger entirely; the dialog can still be opened programmatically via `HotkeysContext`.",
+            control: { type: "radio" },
+            options: ["?", "shift + h", "Disabled (false)"],
+            mapping: {
+                "?": "?",
+                "shift + h": "shift + h",
+                "Disabled (false)": false,
+            },
+        },
+    },
+} satisfies Meta<typeof UseHotkeysStory>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Registers Copy, Paste, Undo, and Redo as global hotkeys. Use the
+ * `showDialogKeyCombo` control to customize or disable the help dialog trigger.
+ */
+export const Default: Story = {};

packages/core/src/hooks/hotkeys/useHotkeys.ts

@@ -33,11 +33,13 @@ export interface UseHotkeysOptions {
     document?: Document;
 
     /**
-     * The key combo which will trigger the hotkeys dialog to open.
+     * The key combo which will trigger the hotkeys dialog to open. Pass `false`
+     * to disable the built-in trigger entirely; the dialog can still be opened
+     * programmatically via {@link HotkeysContext}.
      *
      * @default "?"
      */
-    showDialogKeyCombo?: string;
+    showDialogKeyCombo?: string | false;
 }
 
 export interface UseHotkeysReturnValue {
@@ -120,14 +122,16 @@ export function useHotkeys(keys: readonly HotkeyConfig[], options: UseHotkeysOpt
 
     const handleGlobalKeyDown = useCallback(
         (e: KeyboardEvent) => {
-            // special case for global keydown: if '?' is pressed, open the hotkeys dialog
             const combo = getKeyCombo(e);
-            const isTextInput = elementIsTextInput(e.target as HTMLElement);
-            if (!isTextInput && comboMatches(parseKeyCombo(showDialogKeyCombo), combo)) {
-                dispatch({ type: "OPEN_DIALOG" });
-            } else {
-                invokeNamedCallbackIfComboRecognized(true, getKeyCombo(e), "onKeyDown", e);
+            // special case for global keydown: if the dialog combo is pressed, open the hotkeys dialog
+            if (showDialogKeyCombo !== false) {
+                const isTextInput = elementIsTextInput(e.target as HTMLElement);
+                if (!isTextInput && comboMatches(parseKeyCombo(showDialogKeyCombo), combo)) {
+                    dispatch({ type: "OPEN_DIALOG" });
+                    return;
+                }
             }
+            invokeNamedCallbackIfComboRecognized(true, combo, "onKeyDown", e);
         },
         [dispatch, invokeNamedCallbackIfComboRecognized, showDialogKeyCombo],
     );

packages/core/src/hooks/useHotkeys.test.tsx

@@ -33,9 +33,16 @@ interface TestComponentProps extends TestComponentContainerProps {
 interface TestComponentContainerProps {
     bindExtraKeys?: boolean;
     isInputReadOnly?: boolean;
+    showDialogKeyCombo?: string | false;
 }
 
-const TestComponent: React.FC<TestComponentProps> = ({ bindExtraKeys, isInputReadOnly, onKeyA, onKeyB }) => {
+const TestComponent: React.FC<TestComponentProps> = ({
+    bindExtraKeys,
+    isInputReadOnly,
+    onKeyA,
+    onKeyB,
+    showDialogKeyCombo,
+}) => {
     const hotkeys = useMemo(() => {
         const keys = [
             {
@@ -68,7 +75,7 @@ const TestComponent: React.FC<TestComponentProps> = ({ bindExtraKeys, isInputRea
         return keys;
     }, [bindExtraKeys, onKeyA, onKeyB]);
 
-    const { handleKeyDown, handleKeyUp } = useHotkeys(hotkeys);
+    const { handleKeyDown, handleKeyUp } = useHotkeys(hotkeys, { showDialogKeyCombo });
 
     return (
         <div onKeyDown={handleKeyDown} onKeyUp={handleKeyUp}>
@@ -195,4 +202,31 @@ describe("useHotkeys", () => {
             expect(warnSpy).not.toHaveBeenCalled();
         });
     });
+
+    describe("showDialogKeyCombo", () => {
+        it("opens the help dialog when the default combo (?) is pressed", async () => {
+            const user = userEvent.setup();
+            render(
+                <HotkeysProvider>
+                    <TestComponentContainer />
+                </HotkeysProvider>,
+            );
+            expect(screen.queryByRole("dialog")).toBeNull();
+            screen.getByTestId("target-outside-component").focus();
+            await user.keyboard("{Shift>}/{/Shift}");
+            expect(await screen.findByRole("dialog")).toBeInTheDocument();
+        });
+
+        it("does not open the help dialog when showDialogKeyCombo is false", async () => {
+            const user = userEvent.setup();
+            render(
+                <HotkeysProvider>
+                    <TestComponentContainer showDialogKeyCombo={false} />
+                </HotkeysProvider>,
+            );
+            screen.getByTestId("target-outside-component").focus();
+            await user.keyboard("{Shift>}/{/Shift}");
+            expect(screen.queryByRole("dialog")).toBeNull();
+        });
+    });
 });