[core] fix(HotkeyParser): use e.code to get physical keys

packages/core/src/components/hotkeys/hotkeyParser.ts

@@ -61,18 +61,9 @@ export const CONFIG_ALIASES: KeyMap = {
     space: " ",
 };
 
+/** Key mapping used in getKeyCombo() implementation for physical keys which are not alphabet characters or digits. */
 export const SHIFT_KEYS: KeyMap = {
     "~": "`",
-    "!": "1",
-    "@": "2",
-    "#": "3",
-    $: "4",
-    "%": "5",
-    "^": "6",
-    "&": "7",
-    "*": "8",
-    "(": "9",
-    ")": "0",
     _: "-",
     "+": "=",
     "{": "[",
@@ -130,7 +121,10 @@ export const parseKeyCombo = (combo: string): KeyCombo => {
 };
 
 /**
- * Converts a keyboard event into a valid combo prop string
+ * Interprets a keyboard event as a valid KeyCoboTag `combo` prop string value.
+ *
+ * Note that this function is only used in the docs example and tests; it is not used by `useHotkeys()` or any
+ * Blueprint consumers that we are currently aware of.
  */
 export const getKeyComboString = (e: KeyboardEvent): string => {
     const comboParts = [] as string[];
@@ -149,32 +143,57 @@ export const getKeyComboString = (e: KeyboardEvent): string => {
         comboParts.push("meta");
     }
 
-    if (e.key !== undefined) {
-        if (e.key === " ") {
-            // special case for "space" key, which would otherwise be printed as illegible whitespace
+    const key = maybeGetKeyFromEventCode(e);
+    if (key !== undefined) {
+        comboParts.push(key);
+    } else {
+        if (e.code === "Space") {
             comboParts.push("space");
         } else if (MODIFIER_KEYS.has(e.key)) {
             // do nothing
-        } else {
+        } else if (e.shiftKey && SHIFT_KEYS[e.key] !== undefined) {
+            comboParts.push(SHIFT_KEYS[e.key]);
+        } else if (e.key !== undefined) {
             comboParts.push(e.key.toLowerCase());
         }
     }
 
     return comboParts.join(" + ");
 };
 
+const KEY_CODE_PREFIX = "Key";
+const DIGIT_CODE_PREFIX = "Digit";
+
+function maybeGetKeyFromEventCode(e: KeyboardEvent) {
+    if (e.code == null) {
+        return undefined;
+    }
+
+    if (e.code.startsWith(KEY_CODE_PREFIX)) {
+        // Code looks like "KeyA", etc.
+        return e.code.substring(KEY_CODE_PREFIX.length).toLowerCase();
+    } else if (e.code.startsWith(DIGIT_CODE_PREFIX)) {
+        // Similar to previous case: code looks like "Digit1", etc.
+        return e.code.substring(DIGIT_CODE_PREFIX.length).toLowerCase();
+    }
+
+    return undefined;
+}
+
 /**
- * Determines the key combo object from the given keyboard event. Again, a key
- * combo includes zero or more modifiers (represented by a bitmask) and one
- * action key, which we determine from the `e.key` property of the keyboard
- * event.
+ * Determines the key combo object from the given keyboard event. A key combo includes zero or more modifiers
+ * (represented by a bitmask) and one physical key. For most keys, we prefer dealing with the `code` property of the
+ * event, since this is not altered by keyboard layout or the state of modifier keys. Fall back to using the `key`
+ * property.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code
  */
 export const getKeyCombo = (e: KeyboardEvent): KeyCombo => {
     let key: string | undefined;
     if (MODIFIER_KEYS.has(e.key)) {
-        // keep key undefined
+        // Leave local variable `key` undefined
     } else {
-        key = e.key?.toLowerCase();
+        key = maybeGetKeyFromEventCode(e) ?? e.key?.toLowerCase();
     }
 
     let modifiers = 0;

packages/core/src/components/hotkeys/hotkeys-target2.md

@@ -75,13 +75,19 @@ event handlers with the `handleKeyDown` and `handleKeyUp` functions in the child
 you will likely have to set a non-negative `tabIndex` on the DOM node to which these local event handlers are
 bound for them to work correctly.
 
-__HotkeysTarget2__ takes an optional `options: UseHotkeysOptions` prop which can customize some of the hook's
-default behavior.
+<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
+
+See the [useHotkeys hook documentation](#core/hooks/use-hotkeys.key-combos) to understand the semantics of "key combos":
+how they are configured and how they will appear in the global dialog.
+
+</div>
 
 @## Props interface
 
 @interface HotkeysTarget2Props
 
-@interface HotkeyConfig
-
 @interface UseHotkeysOptions
+
+@## Hotkey configuration
+
+@interface HotkeyConfig

packages/core/src/components/hotkeys/hotkeysTarget2.tsx

@@ -54,7 +54,7 @@ export const HotkeysTarget2 = ({ children, hotkeys, options }: HotkeysTarget2Pro
                 console.error(Errors.HOTKEYS_TARGET_CHILDREN_LOCAL_HOTKEYS);
             }
         }
-    }, [hotkeys]);
+    }, [hotkeys, children]);
 
     if (typeof children === "function") {
         return children({ handleKeyDown, handleKeyUp });

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

@@ -23,7 +23,7 @@ export interface HotkeyConfig {
     allowInInput?: boolean;
 
     /**
-     * Hotkey combination string, such as "space" or "cmd+n".
+     * Hotkey combination string (AKA "key combo"), such as "space" or "cmd+n".
      */
     combo: string;
 

packages/core/src/hooks/hotkeys/use-hotkeys.md

@@ -20,7 +20,7 @@ The `useHotkeys` hook adds hotkey / keyboard shortcut interactions to your appli
 Compared to the deprecated [Hotkeys API](#core/legacy/hotkeys-legacy), it works with function components and its
 corresponding [context provider](#core/context/hotkeys-provider) allows more customization of the hotkeys dialog.
 
-Focus on the piano below to try its hotkeys. The global hotkeys dialog can be shown using the "?" key.
+Focus on the piano below to try its hotkeys. The global hotkeys dialog can be shown using the <kbd>?</kbd> key.
 
 @reactExample UseHotkeysExample
 
@@ -74,8 +74,71 @@ and configure the <kbd>?</kbd> key to open the generated hotkeys dialog, but it
 event handlers with the returned `handleKeyDown` and `handleKeyUp` functions. The hook takes an optional
 second parameter which can customize some of its default behavior.
 
+@## Hook options
+
 @interface UseHotkeysOptions
 
 @method useHotkeys
 
+@## Hotkey configuration
+
 @interface HotkeyConfig
+
+@## Key combos
+
+Each hotkey must be assigned a key combo that will trigger its events. A key combo consists of zero or more modifier
+keys (`alt`, `ctrl`, `shift`, `meta`, `cmd`) and exactly one action key, such as `A`, `return`, or `up`.
+
+Some key combos have aliases. For example, `shift + 1` can equivalently be expressed as `!` and `cmd` is equal to
+`meta`. However, normal alphabetic characters do not have this aliasing, so `X` is equivalent to `x` but is not
+equivalent to `shift + x`.
+
+Examples of valid key combos:
+
+-   `cmd+plus`
+-   `!` or, equivalently `shift+1`
+-   `return` or, equivalently `enter`
+-   `alt + shift + x`
+-   `ctrl + left`
+
+Note that spaces are ignored.
+
+### Named keys
+
+-   `plus`
+-   `minus`
+-   `backspace`
+-   `tab`
+-   `enter`
+-   `capslock`
+-   `esc`
+-   `space`
+-   `pageup`
+-   `pagedown`
+-   `end`
+-   `home`
+-   `left`
+-   `up`
+-   `right`
+-   `down`
+-   `ins`
+-   `del`
+
+### Aliased keys
+
+-   `option` &rarr; `alt`
+-   `cmd` &rarr; `meta`
+-   `command` &rarr; `meta`
+-   `return` &rarr; `enter`
+-   `escape` &rarr; `esc`
+-   `win` &rarr; `meta`
+
+The special modifier `mod` will choose the OS-preferred modifier key: `cmd` for macOS and iOS, or `ctrl` for Windows
+and Linux.
+
+@## Key combo tester
+
+Below is a little widget to quickly help you try out hotkey combos and see how they will appear in the dialog. See the
+[Key combos section](#core/hooks/use-hotkeys.key-combos) above for more info.
+
+@reactExample HotkeyTesterExample

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

@@ -81,43 +81,41 @@ export function useHotkeys(keys: readonly HotkeyConfig[], options: UseHotkeysOpt
         if (!state.hasProvider) {
             console.warn(HOTKEYS_PROVIDER_NOT_FOUND);
         }
-    }, []);
+    }, [state.hasProvider]);
 
     // we can still bind the hotkeys if there is no HotkeysProvider, they just won't show up in the dialog
     React.useEffect(() => {
         const payload = [...globalKeys.map(k => k.config), ...localKeys.map(k => k.config)];
         dispatch({ type: "ADD_HOTKEYS", payload });
         return () => dispatch({ type: "REMOVE_HOTKEYS", payload });
-    }, [keys]);
+    }, [dispatch, globalKeys, localKeys]);
 
-    const invokeNamedCallbackIfComboRecognized = (
-        global: boolean,
-        combo: KeyCombo,
-        callbackName: "onKeyDown" | "onKeyUp",
-        e: KeyboardEvent,
-    ) => {
-        const isTextInput = elementIsTextInput(e.target as HTMLElement);
-        for (const key of global ? globalKeys : localKeys) {
-            const {
-                allowInInput = false,
-                disabled = false,
-                preventDefault = false,
-                stopPropagation = false,
-            } = key.config;
-            const shouldIgnore = (isTextInput && !allowInInput) || disabled;
-            if (!shouldIgnore && comboMatches(key.combo, combo)) {
-                if (preventDefault) {
-                    e.preventDefault();
-                }
-                if (stopPropagation) {
-                    // set a flag just for unit testing. not meant to be referenced in feature work.
-                    (e as any).isPropagationStopped = true;
-                    e.stopPropagation();
+    const invokeNamedCallbackIfComboRecognized = React.useCallback(
+        (global: boolean, combo: KeyCombo, callbackName: "onKeyDown" | "onKeyUp", e: KeyboardEvent) => {
+            const isTextInput = elementIsTextInput(e.target as HTMLElement);
+            for (const key of global ? globalKeys : localKeys) {
+                const {
+                    allowInInput = false,
+                    disabled = false,
+                    preventDefault = false,
+                    stopPropagation = false,
+                } = key.config;
+                const shouldIgnore = (isTextInput && !allowInInput) || disabled;
+                if (!shouldIgnore && comboMatches(key.combo, combo)) {
+                    if (preventDefault) {
+                        e.preventDefault();
+                    }
+                    if (stopPropagation) {
+                        // set a flag just for unit testing. not meant to be referenced in feature work.
+                        (e as any).isPropagationStopped = true;
+                        e.stopPropagation();
+                    }
+                    key.config[callbackName]?.(e);
                 }
-                key.config[callbackName]?.(e);
             }
-        }
-    };
+        },
+        [globalKeys, localKeys],
+    );
 
     const handleGlobalKeyDown = React.useCallback(
         (e: KeyboardEvent) => {
@@ -130,22 +128,22 @@ export function useHotkeys(keys: readonly HotkeyConfig[], options: UseHotkeysOpt
                 invokeNamedCallbackIfComboRecognized(true, getKeyCombo(e), "onKeyDown", e);
             }
         },
-        [globalKeys],
+        [dispatch, invokeNamedCallbackIfComboRecognized, showDialogKeyCombo],
     );
     const handleGlobalKeyUp = React.useCallback(
         (e: KeyboardEvent) => invokeNamedCallbackIfComboRecognized(true, getKeyCombo(e), "onKeyUp", e),
-        [globalKeys],
+        [invokeNamedCallbackIfComboRecognized],
     );
 
     const handleLocalKeyDown = React.useCallback(
         (e: React.KeyboardEvent<HTMLElement>) =>
             invokeNamedCallbackIfComboRecognized(false, getKeyCombo(e.nativeEvent), "onKeyDown", e.nativeEvent),
-        [localKeys],
+        [invokeNamedCallbackIfComboRecognized],
     );
     const handleLocalKeyUp = React.useCallback(
         (e: React.KeyboardEvent<HTMLElement>) =>
             invokeNamedCallbackIfComboRecognized(false, getKeyCombo(e.nativeEvent), "onKeyUp", e.nativeEvent),
-        [localKeys],
+        [invokeNamedCallbackIfComboRecognized],
     );
 
     React.useEffect(() => {

packages/core/src/legacy/hotkeys-legacy.md

@@ -112,65 +112,3 @@ focused on an element that has any hotkeys, those will be shown as well.
 
 If you would like to change the style of the dialog (for example, to apply the
 dark theme class), call the `setHotkeysDialogProps` function with `IDialogProps`.
-
-@## Key combos
-
-Each hotkey must be assigned a key combo that will trigger its events. A key
-combo consists of zero or more modifier keys (`alt`, `ctrl`, `shift`, `meta`,
-`cmd`) and exactly one action key, such as `A`, `return`, or `up`.
-
-Some key combos have aliases. For example, `shift + 1` can equivalently be
-expressed as `!` and `cmd` is equal to `meta`. However, normal alphabetic
-characters do not have this aliasing, so `X` is equivalent to `x` but is not
-equivalent to `shift + x`.
-
-Examples of valid key combos:
-
--   `cmd+plus`
--   `!` or, equivalently `shift+1`
--   `return` or, equivalently `enter`
--   `alt + shift + x`
--   `ctrl + left`
-
-Note that spaces are ignored.
-
-### Named keys
-
--   `plus`
--   `minus`
--   `backspace`
--   `tab`
--   `enter`
--   `capslock`
--   `esc`
--   `space`
--   `pageup`
--   `pagedown`
--   `end`
--   `home`
--   `left`
--   `up`
--   `right`
--   `down`
--   `ins`
--   `del`
-
-### Aliased keys
-
--   `option` → `alt`
--   `cmd` → `meta`
--   `command` → `meta`
--   `return` → `enter`
--   `escape` → `esc`
--   `win` → `meta`
-
-The special modifier `mod` will choose the OS-preferred modifier key — `cmd`
-for macOS and iOS, or `ctrl` for Windows and Linux.
-
-### Hotkey tester
-
-Below is a little widget to quickly help you try out hotkey combos and see how
-they will look in the dialog. See the key combos section above for more about
-specifying key combo props.
-
-@reactExample HotkeyTesterExample