npm - @tanstack/hotkeys - Versions diffs - 0.4.0 → 0.4.2 - Mend

@tanstack/hotkeys 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md CHANGED Viewed

@@ -44,7 +44,7 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 - Type-safe bindings — template strings (`Mod+Shift+S`, `Escape`) or parsed objects for full control
 - Flexible options — `keydown`/`keyup`, `preventDefault`, `stopPropagation`, conditional enabled, `requireReset`
 - Cross-platform Mod — maps to Cmd on macOS and Ctrl on Windows/Linux
-- Batteries included — validation + matching, sequences (Vim-style), key-state tracking, recorder UI helpers, React hooks, and devtools (in progress)
+- Batteries included — validation + matching, sequences (Vim-style), key-state tracking, recorder UI helpers, framework adapters, and devtools
 ### <a href="https://tanstack.com/hotkeys">Read the docs →</a>
@@ -57,8 +57,8 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > - [**Preact Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/preact/preact-hotkeys)
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)
 > - [**Angular Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/angular/reference)
-> - Svelte Hotkeys – needs a contributor!
-> - Vue Hotkeys – needs a contributor!
+> - [**Vue Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/vue/reference)
+> - [**Svelte Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference)
 ## Get Involved

package/dist/constants.cjs CHANGED Viewed

@@ -243,9 +243,31 @@ const PUNCTUATION_KEYS = new Set([
 	"-",
 	",",
 	".",
+	";",
 	"`"
 ]);
 /**
+* Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
+*
+* On macOS, holding the Option (Alt) key transforms punctuation keys into special characters
+* (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.
+* However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables
+* falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`
+* fallbacks for letters and digits.
+*/
+const PUNCTUATION_CODE_MAP = {
+	Minus: "-",
+	Equal: "=",
+	Slash: "/",
+	BracketLeft: "[",
+	BracketRight: "]",
+	Backslash: "\\",
+	Comma: ",",
+	Period: ".",
+	Backquote: "`",
+	Semicolon: ";"
+};
+/**
 * Set of all valid non-modifier keys.
 *
 * This is the union of all key type sets (letters, numbers, function keys, navigation,
@@ -352,7 +374,10 @@ function isSingleLetterKey(key) {
 }
 function normalizeKeyName(key) {
 	if (key in KEY_ALIASES) return KEY_ALIASES[key];
-	if (isSingleLetterKey(key)) return key.toUpperCase();
+	if (isSingleLetterKey(key)) {
+		const upper = key.toUpperCase();
+		return upper.length === 1 ? upper : key;
+	}
 	const upperKey = key.toUpperCase();
 	if (/^F([1-9]|1[0-2])$/.test(upperKey)) return upperKey;
 	return key;
@@ -439,6 +464,7 @@ exports.MODIFIER_KEYS = MODIFIER_KEYS;
 exports.MODIFIER_ORDER = MODIFIER_ORDER;
 exports.NAVIGATION_KEYS = NAVIGATION_KEYS;
 exports.NUMBER_KEYS = NUMBER_KEYS;
+exports.PUNCTUATION_CODE_MAP = PUNCTUATION_CODE_MAP;
 exports.PUNCTUATION_KEYS = PUNCTUATION_KEYS;
 exports.STANDARD_MODIFIER_LABELS = STANDARD_MODIFIER_LABELS;
 exports.detectPlatform = detectPlatform;

package/dist/constants.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"constants.cjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n CanonicalModifier,\n EditingKey,\n FunctionKey,\n LetterKey,\n NavigationKey,\n NumberKey,\n PunctuationKey,\n} from './hotkey'\n\n// =============================================================================\n// Platform Detection\n// =============================================================================\n\n/*\n Detects the current platform based on browser navigator properties.\n \n Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n \n @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n \n @example\n * ```ts\n * const platform = detectPlatform() // 'mac' \| 'windows' \| 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n /\nexport function detectPlatform(): 'mac' \| 'windows' \| 'linux' {\n if (typeof navigator === 'undefined') {\n return 'linux' // Default for SSR\n }\n\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const platform = navigator.platform?.toLowerCase() ?? ''\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n if (platform.includes('mac') \|\| userAgent.includes('mac')) {\n return 'mac'\n }\n if (platform.includes('win') \|\| userAgent.includes('win')) {\n return 'windows'\n }\n return 'linux'\n}\n\n// =============================================================================\n// Modifier Aliases\n// =============================================================================\n\n/\n Canonical order for modifiers in normalized hotkey strings.\n \n Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n \n Order: Control → Alt → Shift → Meta\n \n @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n /\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n 'Control',\n 'Alt',\n 'Shift',\n 'Meta',\n]\n\n/\n Set of canonical modifier key names for fast lookup.\n \n Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n /\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/\n Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n \n This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n \n The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n /\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier \| 'Mod'> = {\n // Control variants\n Control: 'Control',\n Ctrl: 'Control',\n control: 'Control',\n ctrl: 'Control',\n\n // Shift variants\n Shift: 'Shift',\n shift: 'Shift',\n\n // Alt variants\n Alt: 'Alt',\n Option: 'Alt',\n alt: 'Alt',\n option: 'Alt',\n\n // Meta/Command variants\n Command: 'Meta',\n Cmd: 'Meta',\n Meta: 'Meta',\n command: 'Meta',\n cmd: 'Meta',\n meta: 'Meta',\n\n // Platform-adaptive (resolved at runtime)\n CommandOrControl: 'Mod',\n Mod: 'Mod',\n commandorcontrol: 'Mod',\n mod: 'Mod',\n}\n\n/\n Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n \n The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n \n This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n \n @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n \n @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n /\nexport function resolveModifier(\n modifier: CanonicalModifier \| 'Mod',\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): CanonicalModifier {\n if (modifier === 'Mod') {\n return platform === 'mac' ? 'Meta' : 'Control'\n }\n return modifier\n}\n\n// =============================================================================\n// Valid Keys\n// =============================================================================\n\n/\n Set of all valid letter keys (A-Z).\n \n Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n /\nexport const LETTER_KEYS = new Set<LetterKey>([\n 'A',\n 'B',\n 'C',\n 'D',\n 'E',\n 'F',\n 'G',\n 'H',\n 'I',\n 'J',\n 'K',\n 'L',\n 'M',\n 'N',\n 'O',\n 'P',\n 'Q',\n 'R',\n 'S',\n 'T',\n 'U',\n 'V',\n 'W',\n 'X',\n 'Y',\n 'Z',\n])\n\n/\n Set of all valid number keys (0-9).\n \n Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n /\nexport const NUMBER_KEYS = new Set<NumberKey>([\n '0',\n '1',\n '2',\n '3',\n '4',\n '5',\n '6',\n '7',\n '8',\n '9',\n])\n\n/\n Set of all valid function keys (F1-F12).\n \n Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n /\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n 'F1',\n 'F2',\n 'F3',\n 'F4',\n 'F5',\n 'F6',\n 'F7',\n 'F8',\n 'F9',\n 'F10',\n 'F11',\n 'F12',\n])\n\n/\n Set of all valid navigation keys for cursor movement and document navigation.\n \n Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n /\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n 'ArrowUp',\n 'ArrowDown',\n 'ArrowLeft',\n 'ArrowRight',\n 'Home',\n 'End',\n 'PageUp',\n 'PageDown',\n])\n\n/\n Set of all valid editing and special keys.\n \n Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n /\nexport const EDITING_KEYS = new Set<EditingKey>([\n 'Enter',\n 'Escape',\n 'Space',\n 'Tab',\n 'Backspace',\n 'Delete',\n])\n\n/\n Set of all valid punctuation keys commonly used in keyboard shortcuts.\n \n These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n \n Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n /\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n '/',\n '[',\n ']',\n '\\\\',\n '=',\n '-',\n ',',\n '.',\n '`',\n])\n\n/\n Set of all valid non-modifier keys.\n \n This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n \n @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n /\nexport const ALL_KEYS = new Set([\n ...LETTER_KEYS,\n ...NUMBER_KEYS,\n ...FUNCTION_KEYS,\n ...NAVIGATION_KEYS,\n ...EDITING_KEYS,\n ...PUNCTUATION_KEYS,\n])\n\n/\n Maps key name aliases to their canonical form.\n \n Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n \n This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n /\nconst KEY_ALIASES: Record<string, string> = {\n // Escape variants\n Esc: 'Escape',\n esc: 'Escape',\n escape: 'Escape',\n\n // Enter variants\n Return: 'Enter',\n return: 'Enter',\n enter: 'Enter',\n\n // Space variants\n ' ': 'Space',\n space: 'Space',\n Spacebar: 'Space',\n spacebar: 'Space',\n\n // Tab variants\n tab: 'Tab',\n\n // Backspace variants\n backspace: 'Backspace',\n\n // Delete variants\n Del: 'Delete',\n del: 'Delete',\n delete: 'Delete',\n\n // Arrow key variants\n Up: 'ArrowUp',\n up: 'ArrowUp',\n arrowup: 'ArrowUp',\n Down: 'ArrowDown',\n down: 'ArrowDown',\n arrowdown: 'ArrowDown',\n Left: 'ArrowLeft',\n left: 'ArrowLeft',\n arrowleft: 'ArrowLeft',\n Right: 'ArrowRight',\n right: 'ArrowRight',\n arrowright: 'ArrowRight',\n\n // Navigation variants\n home: 'Home',\n end: 'End',\n pageup: 'PageUp',\n pagedown: 'PageDown',\n PgUp: 'PageUp',\n PgDn: 'PageDown',\n pgup: 'PageUp',\n pgdn: 'PageDown',\n}\n\n/\n Normalizes a key name to its canonical form.\n \n Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n \n Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n \n @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n \n @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n /\nexport function isSingleLetterKey(key: string): boolean {\n return /^\\p{Letter}$/u.test(key)\n}\n\nexport function normalizeKeyName(key: string): string {\n // Check aliases first\n if (key in KEY_ALIASES) {\n return KEY_ALIASES[key]!\n }\n\n // Check if it's a single letter (normalize to uppercase)\n if (isSingleLetterKey(key)) {\n return key.toUpperCase()\n }\n\n // Check if it's a function key (normalize case)\n const upperKey = key.toUpperCase()\n if (/^F([1-9]\|1[0-2])$/.test(upperKey)) {\n return upperKey\n }\n\n return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/\n Modifier key symbols for macOS display.\n \n Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n \n @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n /\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {\n Control: '⌃',\n Alt: '⌥',\n Shift: '⇧',\n Meta: '⌘',\n}\n\n/\n Modifier key labels for Windows/Linux display.\n \n Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n \n @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n /\nexport const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {\n Control: 'Ctrl',\n Alt: 'Alt',\n Shift: 'Shift',\n Meta: 'Win',\n}\n\n/\n Special key symbols for display formatting.\n \n Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n \n @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS: Record<string, string> = {\n ArrowUp: '↑',\n ArrowDown: '↓',\n ArrowLeft: '←',\n ArrowRight: '→',\n Enter: '↵',\n Escape: 'Esc',\n Backspace: '⌫',\n Delete: '⌦',\n Tab: '⇥',\n Space: '␣',\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"constants.cjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n CanonicalModifier,\n EditingKey,\n FunctionKey,\n LetterKey,\n NavigationKey,\n NumberKey,\n PunctuationKey,\n} from './hotkey'\n\n// =============================================================================\n// Platform Detection\n// =============================================================================\n\n/*\n Detects the current platform based on browser navigator properties.\n \n Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n \n @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n \n @example\n * ```ts\n * const platform = detectPlatform() // 'mac' \| 'windows' \| 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n /\nexport function detectPlatform(): 'mac' \| 'windows' \| 'linux' {\n if (typeof navigator === 'undefined') {\n return 'linux' // Default for SSR\n }\n\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const platform = navigator.platform?.toLowerCase() ?? ''\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n if (platform.includes('mac') \|\| userAgent.includes('mac')) {\n return 'mac'\n }\n if (platform.includes('win') \|\| userAgent.includes('win')) {\n return 'windows'\n }\n return 'linux'\n}\n\n// =============================================================================\n// Modifier Aliases\n// =============================================================================\n\n/\n Canonical order for modifiers in normalized hotkey strings.\n \n Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n \n Order: Control → Alt → Shift → Meta\n \n @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n /\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n 'Control',\n 'Alt',\n 'Shift',\n 'Meta',\n]\n\n/\n Set of canonical modifier key names for fast lookup.\n \n Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n /\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/\n Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n \n This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n \n The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n /\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier \| 'Mod'> = {\n // Control variants\n Control: 'Control',\n Ctrl: 'Control',\n control: 'Control',\n ctrl: 'Control',\n\n // Shift variants\n Shift: 'Shift',\n shift: 'Shift',\n\n // Alt variants\n Alt: 'Alt',\n Option: 'Alt',\n alt: 'Alt',\n option: 'Alt',\n\n // Meta/Command variants\n Command: 'Meta',\n Cmd: 'Meta',\n Meta: 'Meta',\n command: 'Meta',\n cmd: 'Meta',\n meta: 'Meta',\n\n // Platform-adaptive (resolved at runtime)\n CommandOrControl: 'Mod',\n Mod: 'Mod',\n commandorcontrol: 'Mod',\n mod: 'Mod',\n}\n\n/\n Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n \n The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n \n This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n \n @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n \n @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n /\nexport function resolveModifier(\n modifier: CanonicalModifier \| 'Mod',\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): CanonicalModifier {\n if (modifier === 'Mod') {\n return platform === 'mac' ? 'Meta' : 'Control'\n }\n return modifier\n}\n\n// =============================================================================\n// Valid Keys\n// =============================================================================\n\n/\n Set of all valid letter keys (A-Z).\n \n Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n /\nexport const LETTER_KEYS = new Set<LetterKey>([\n 'A',\n 'B',\n 'C',\n 'D',\n 'E',\n 'F',\n 'G',\n 'H',\n 'I',\n 'J',\n 'K',\n 'L',\n 'M',\n 'N',\n 'O',\n 'P',\n 'Q',\n 'R',\n 'S',\n 'T',\n 'U',\n 'V',\n 'W',\n 'X',\n 'Y',\n 'Z',\n])\n\n/\n Set of all valid number keys (0-9).\n \n Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n /\nexport const NUMBER_KEYS = new Set<NumberKey>([\n '0',\n '1',\n '2',\n '3',\n '4',\n '5',\n '6',\n '7',\n '8',\n '9',\n])\n\n/\n Set of all valid function keys (F1-F12).\n \n Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n /\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n 'F1',\n 'F2',\n 'F3',\n 'F4',\n 'F5',\n 'F6',\n 'F7',\n 'F8',\n 'F9',\n 'F10',\n 'F11',\n 'F12',\n])\n\n/\n Set of all valid navigation keys for cursor movement and document navigation.\n \n Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n /\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n 'ArrowUp',\n 'ArrowDown',\n 'ArrowLeft',\n 'ArrowRight',\n 'Home',\n 'End',\n 'PageUp',\n 'PageDown',\n])\n\n/\n Set of all valid editing and special keys.\n \n Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n /\nexport const EDITING_KEYS = new Set<EditingKey>([\n 'Enter',\n 'Escape',\n 'Space',\n 'Tab',\n 'Backspace',\n 'Delete',\n])\n\n/\n Set of all valid punctuation keys commonly used in keyboard shortcuts.\n \n These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n \n Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n /\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n '/',\n '[',\n ']',\n '\\\\',\n '=',\n '-',\n ',',\n '.',\n ';',\n '`',\n])\n\n/\n Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.\n \n On macOS, holding the Option (Alt) key transforms punctuation keys into special characters\n * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.\n * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables\n * falling back to `event.code` for punctuation keys, similar to the existing `Key`/`Digit`\n * fallbacks for letters and digits.\n /\nexport const PUNCTUATION_CODE_MAP: Record<string, string> = {\n Minus: '-',\n Equal: '=',\n Slash: '/',\n BracketLeft: '[',\n BracketRight: ']',\n Backslash: '\\\\',\n Comma: ',',\n Period: '.',\n Backquote: '`',\n Semicolon: ';',\n}\n\n/\n Set of all valid non-modifier keys.\n \n This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n \n @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n /\nexport const ALL_KEYS = new Set([\n ...LETTER_KEYS,\n ...NUMBER_KEYS,\n ...FUNCTION_KEYS,\n ...NAVIGATION_KEYS,\n ...EDITING_KEYS,\n ...PUNCTUATION_KEYS,\n])\n\n/\n Maps key name aliases to their canonical form.\n \n Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n \n This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n /\nconst KEY_ALIASES: Record<string, string> = {\n // Escape variants\n Esc: 'Escape',\n esc: 'Escape',\n escape: 'Escape',\n\n // Enter variants\n Return: 'Enter',\n return: 'Enter',\n enter: 'Enter',\n\n // Space variants\n ' ': 'Space',\n space: 'Space',\n Spacebar: 'Space',\n spacebar: 'Space',\n\n // Tab variants\n tab: 'Tab',\n\n // Backspace variants\n backspace: 'Backspace',\n\n // Delete variants\n Del: 'Delete',\n del: 'Delete',\n delete: 'Delete',\n\n // Arrow key variants\n Up: 'ArrowUp',\n up: 'ArrowUp',\n arrowup: 'ArrowUp',\n Down: 'ArrowDown',\n down: 'ArrowDown',\n arrowdown: 'ArrowDown',\n Left: 'ArrowLeft',\n left: 'ArrowLeft',\n arrowleft: 'ArrowLeft',\n Right: 'ArrowRight',\n right: 'ArrowRight',\n arrowright: 'ArrowRight',\n\n // Navigation variants\n home: 'Home',\n end: 'End',\n pageup: 'PageUp',\n pagedown: 'PageDown',\n PgUp: 'PageUp',\n PgDn: 'PageDown',\n pgup: 'PageUp',\n pgdn: 'PageDown',\n}\n\n/\n Normalizes a key name to its canonical form.\n \n Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n \n Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n \n @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n \n @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n /\nexport function isSingleLetterKey(key: string): boolean {\n return /^\\p{Letter}$/u.test(key)\n}\n\nexport function normalizeKeyName(key: string): string {\n // Check aliases first\n if (key in KEY_ALIASES) {\n return KEY_ALIASES[key]!\n }\n\n if (isSingleLetterKey(key)) {\n const upper = key.toUpperCase()\n // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences\n // ('SS'). Avoid changing the string length so the rest of the matching\n // logic can rely on a stable single-character key value.\n return upper.length === 1 ? upper : key\n }\n\n // Check if it's a function key (normalize case)\n const upperKey = key.toUpperCase()\n if (/^F([1-9]\|1[0-2])$/.test(upperKey)) {\n return upperKey\n }\n\n return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/\n Modifier key symbols for macOS display.\n \n Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n \n @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n /\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {\n Control: '⌃',\n Alt: '⌥',\n Shift: '⇧',\n Meta: '⌘',\n}\n\n/\n Modifier key labels for Windows/Linux display.\n \n Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n \n @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n /\nexport const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {\n Control: 'Ctrl',\n Alt: 'Alt',\n Shift: 'Shift',\n Meta: 'Win',\n}\n\n/\n Special key symbols for display formatting.\n \n Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n \n @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS: Record<string, string> = {\n ArrowUp: '↑',\n ArrowDown: '↓',\n ArrowLeft: '←',\n ArrowRight: '→',\n Enter: '↵',\n Escape: 'Esc',\n Backspace: '⌫',\n Delete: '⌦',\n Tab: '⇥',\n Space: '␣',\n}\n"],"mappings":"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"}

package/dist/constants.d.cts CHANGED Viewed

@@ -133,6 +133,16 @@ declare const EDITING_KEYS: Set<EditingKey>;
  * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
  */
 declare const PUNCTUATION_KEYS: Set<PunctuationKey>;
+/**
+ * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
+ *
+ * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters
+ * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.
+ * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables
+ * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`
+ * fallbacks for letters and digits.
+ */
+declare const PUNCTUATION_CODE_MAP: Record<string, string>;
 /**
  * Set of all valid non-modifier keys.
  *
@@ -223,5 +233,5 @@ declare const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string>;
  */
 declare const KEY_DISPLAY_SYMBOLS: Record<string, string>;
 //#endregion
-export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier };
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier };
 //# sourceMappingURL=constants.d.cts.map

package/dist/constants.d.ts CHANGED Viewed

@@ -133,6 +133,16 @@ declare const EDITING_KEYS: Set<EditingKey>;
  * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
  */
 declare const PUNCTUATION_KEYS: Set<PunctuationKey>;
+/**
+ * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
+ *
+ * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters
+ * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.
+ * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables
+ * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`
+ * fallbacks for letters and digits.
+ */
+declare const PUNCTUATION_CODE_MAP: Record<string, string>;
 /**
  * Set of all valid non-modifier keys.
  *
@@ -223,5 +233,5 @@ declare const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string>;
  */
 declare const KEY_DISPLAY_SYMBOLS: Record<string, string>;
 //#endregion
-export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier };
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier };
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js CHANGED Viewed

@@ -242,9 +242,31 @@ const PUNCTUATION_KEYS = new Set([
 	"-",
 	",",
 	".",
+	";",
 	"`"
 ]);
 /**
+* Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
+*
+* On macOS, holding the Option (Alt) key transforms punctuation keys into special characters
+* (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.
+* However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables
+* falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`
+* fallbacks for letters and digits.
+*/
+const PUNCTUATION_CODE_MAP = {
+	Minus: "-",
+	Equal: "=",
+	Slash: "/",
+	BracketLeft: "[",
+	BracketRight: "]",
+	Backslash: "\\",
+	Comma: ",",
+	Period: ".",
+	Backquote: "`",
+	Semicolon: ";"
+};
+/**
 * Set of all valid non-modifier keys.
 *
 * This is the union of all key type sets (letters, numbers, function keys, navigation,
@@ -351,7 +373,10 @@ function isSingleLetterKey(key) {
 }
 function normalizeKeyName(key) {
 	if (key in KEY_ALIASES) return KEY_ALIASES[key];
-	if (isSingleLetterKey(key)) return key.toUpperCase();
+	if (isSingleLetterKey(key)) {
+		const upper = key.toUpperCase();
+		return upper.length === 1 ? upper : key;
+	}
 	const upperKey = key.toUpperCase();
 	if (/^F([1-9]|1[0-2])$/.test(upperKey)) return upperKey;
 	return key;
@@ -427,5 +452,5 @@ const KEY_DISPLAY_SYMBOLS = {
 };
 //#endregion
-export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier };
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier };
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n CanonicalModifier,\n EditingKey,\n FunctionKey,\n LetterKey,\n NavigationKey,\n NumberKey,\n PunctuationKey,\n} from './hotkey'\n\n// =============================================================================\n// Platform Detection\n// =============================================================================\n\n/*\n Detects the current platform based on browser navigator properties.\n \n Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n \n @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n \n @example\n * ```ts\n * const platform = detectPlatform() // 'mac' \| 'windows' \| 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n /\nexport function detectPlatform(): 'mac' \| 'windows' \| 'linux' {\n if (typeof navigator === 'undefined') {\n return 'linux' // Default for SSR\n }\n\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const platform = navigator.platform?.toLowerCase() ?? ''\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n if (platform.includes('mac') \|\| userAgent.includes('mac')) {\n return 'mac'\n }\n if (platform.includes('win') \|\| userAgent.includes('win')) {\n return 'windows'\n }\n return 'linux'\n}\n\n// =============================================================================\n// Modifier Aliases\n// =============================================================================\n\n/\n Canonical order for modifiers in normalized hotkey strings.\n \n Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n \n Order: Control → Alt → Shift → Meta\n \n @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n /\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n 'Control',\n 'Alt',\n 'Shift',\n 'Meta',\n]\n\n/\n Set of canonical modifier key names for fast lookup.\n \n Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n /\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/\n Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n \n This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n \n The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n /\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier \| 'Mod'> = {\n // Control variants\n Control: 'Control',\n Ctrl: 'Control',\n control: 'Control',\n ctrl: 'Control',\n\n // Shift variants\n Shift: 'Shift',\n shift: 'Shift',\n\n // Alt variants\n Alt: 'Alt',\n Option: 'Alt',\n alt: 'Alt',\n option: 'Alt',\n\n // Meta/Command variants\n Command: 'Meta',\n Cmd: 'Meta',\n Meta: 'Meta',\n command: 'Meta',\n cmd: 'Meta',\n meta: 'Meta',\n\n // Platform-adaptive (resolved at runtime)\n CommandOrControl: 'Mod',\n Mod: 'Mod',\n commandorcontrol: 'Mod',\n mod: 'Mod',\n}\n\n/\n Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n \n The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n \n This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n \n @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n \n @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n /\nexport function resolveModifier(\n modifier: CanonicalModifier \| 'Mod',\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): CanonicalModifier {\n if (modifier === 'Mod') {\n return platform === 'mac' ? 'Meta' : 'Control'\n }\n return modifier\n}\n\n// =============================================================================\n// Valid Keys\n// =============================================================================\n\n/\n Set of all valid letter keys (A-Z).\n \n Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n /\nexport const LETTER_KEYS = new Set<LetterKey>([\n 'A',\n 'B',\n 'C',\n 'D',\n 'E',\n 'F',\n 'G',\n 'H',\n 'I',\n 'J',\n 'K',\n 'L',\n 'M',\n 'N',\n 'O',\n 'P',\n 'Q',\n 'R',\n 'S',\n 'T',\n 'U',\n 'V',\n 'W',\n 'X',\n 'Y',\n 'Z',\n])\n\n/\n Set of all valid number keys (0-9).\n \n Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n /\nexport const NUMBER_KEYS = new Set<NumberKey>([\n '0',\n '1',\n '2',\n '3',\n '4',\n '5',\n '6',\n '7',\n '8',\n '9',\n])\n\n/\n Set of all valid function keys (F1-F12).\n \n Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n /\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n 'F1',\n 'F2',\n 'F3',\n 'F4',\n 'F5',\n 'F6',\n 'F7',\n 'F8',\n 'F9',\n 'F10',\n 'F11',\n 'F12',\n])\n\n/\n Set of all valid navigation keys for cursor movement and document navigation.\n \n Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n /\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n 'ArrowUp',\n 'ArrowDown',\n 'ArrowLeft',\n 'ArrowRight',\n 'Home',\n 'End',\n 'PageUp',\n 'PageDown',\n])\n\n/\n Set of all valid editing and special keys.\n \n Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n /\nexport const EDITING_KEYS = new Set<EditingKey>([\n 'Enter',\n 'Escape',\n 'Space',\n 'Tab',\n 'Backspace',\n 'Delete',\n])\n\n/\n Set of all valid punctuation keys commonly used in keyboard shortcuts.\n \n These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n \n Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n /\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n '/',\n '[',\n ']',\n '\\\\',\n '=',\n '-',\n ',',\n '.',\n '`',\n])\n\n/\n Set of all valid non-modifier keys.\n \n This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n \n @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n /\nexport const ALL_KEYS = new Set([\n ...LETTER_KEYS,\n ...NUMBER_KEYS,\n ...FUNCTION_KEYS,\n ...NAVIGATION_KEYS,\n ...EDITING_KEYS,\n ...PUNCTUATION_KEYS,\n])\n\n/\n Maps key name aliases to their canonical form.\n \n Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n \n This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n /\nconst KEY_ALIASES: Record<string, string> = {\n // Escape variants\n Esc: 'Escape',\n esc: 'Escape',\n escape: 'Escape',\n\n // Enter variants\n Return: 'Enter',\n return: 'Enter',\n enter: 'Enter',\n\n // Space variants\n ' ': 'Space',\n space: 'Space',\n Spacebar: 'Space',\n spacebar: 'Space',\n\n // Tab variants\n tab: 'Tab',\n\n // Backspace variants\n backspace: 'Backspace',\n\n // Delete variants\n Del: 'Delete',\n del: 'Delete',\n delete: 'Delete',\n\n // Arrow key variants\n Up: 'ArrowUp',\n up: 'ArrowUp',\n arrowup: 'ArrowUp',\n Down: 'ArrowDown',\n down: 'ArrowDown',\n arrowdown: 'ArrowDown',\n Left: 'ArrowLeft',\n left: 'ArrowLeft',\n arrowleft: 'ArrowLeft',\n Right: 'ArrowRight',\n right: 'ArrowRight',\n arrowright: 'ArrowRight',\n\n // Navigation variants\n home: 'Home',\n end: 'End',\n pageup: 'PageUp',\n pagedown: 'PageDown',\n PgUp: 'PageUp',\n PgDn: 'PageDown',\n pgup: 'PageUp',\n pgdn: 'PageDown',\n}\n\n/\n Normalizes a key name to its canonical form.\n \n Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n \n Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n \n @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n \n @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n /\nexport function isSingleLetterKey(key: string): boolean {\n return /^\\p{Letter}$/u.test(key)\n}\n\nexport function normalizeKeyName(key: string): string {\n // Check aliases first\n if (key in KEY_ALIASES) {\n return KEY_ALIASES[key]!\n }\n\n // Check if it's a single letter (normalize to uppercase)\n if (isSingleLetterKey(key)) {\n return key.toUpperCase()\n }\n\n // Check if it's a function key (normalize case)\n const upperKey = key.toUpperCase()\n if (/^F([1-9]\|1[0-2])$/.test(upperKey)) {\n return upperKey\n }\n\n return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/\n Modifier key symbols for macOS display.\n \n Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n \n @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n /\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {\n Control: '⌃',\n Alt: '⌥',\n Shift: '⇧',\n Meta: '⌘',\n}\n\n/\n Modifier key labels for Windows/Linux display.\n \n Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n \n @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n /\nexport const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {\n Control: 'Ctrl',\n Alt: 'Alt',\n Shift: 'Shift',\n Meta: 'Win',\n}\n\n/\n Special key symbols for display formatting.\n \n Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n \n @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS: Record<string, string> = {\n ArrowUp: '↑',\n ArrowDown: '↓',\n ArrowLeft: '←',\n ArrowRight: '→',\n Enter: '↵',\n Escape: 'Esc',\n Backspace: '⌫',\n Delete: '⌦',\n Tab: '⇥',\n Space: '␣',\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA6BA,SAAgB,iBAA8C;AAC5D,KAAI,OAAO,cAAc,YACvB,QAAO;CAIT,MAAM,WAAW,UAAU,UAAU,aAAa,IAAI;CAEtD,MAAM,YAAY,UAAU,WAAW,aAAa,IAAI;AAExD,KAAI,SAAS,SAAS,MAAM,IAAI,UAAU,SAAS,MAAM,CACvD,QAAO;AAET,KAAI,SAAS,SAAS,MAAM,IAAI,UAAU,SAAS,MAAM,CACvD,QAAO;AAET,QAAO;;;;;;;;;;;;;;;;AAqBT,MAAa,iBAA2C;CACtD;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,gBAAgB,IAAI,IAAY,eAAe;;;;;;;;;;;;;;;;;;;;AAqB5D,MAAa,mBAA8D;CAEzE,SAAS;CACT,MAAM;CACN,SAAS;CACT,MAAM;CAGN,OAAO;CACP,OAAO;CAGP,KAAK;CACL,QAAQ;CACR,KAAK;CACL,QAAQ;CAGR,SAAS;CACT,KAAK;CACL,MAAM;CACN,SAAS;CACT,KAAK;CACL,MAAM;CAGN,kBAAkB;CAClB,KAAK;CACL,kBAAkB;CAClB,KAAK;CACN;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,gBACd,UACA,WAAwC,gBAAgB,EACrC;AACnB,KAAI,aAAa,MACf,QAAO,aAAa,QAAQ,SAAS;AAEvC,QAAO;;;;;;;;AAaT,MAAa,cAAc,IAAI,IAAe;CAC5C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;AASF,MAAa,cAAc,IAAI,IAAe;CAC5C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;AAQF,MAAa,gBAAgB,IAAI,IAAiB;CAChD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;AASF,MAAa,kBAAkB,IAAI,IAAmB;CACpD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;AASF,MAAa,eAAe,IAAI,IAAgB;CAC9C;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;;;;;;AAcF,MAAa,mBAAmB,IAAI,IAAoB;CACtD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;;;;;;;;AAgBF,MAAa,WAAW,IAAI,IAAI;CAC9B,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACJ,CAAC;;;;;;;;;;;;;;;;;;;;AAqBF,MAAM,cAAsC;CAE1C,KAAK;CACL,KAAK;CACL,QAAQ;CAGR,QAAQ;CACR,QAAQ;CACR,OAAO;CAGP,KAAK;CACL,OAAO;CACP,UAAU;CACV,UAAU;CAGV,KAAK;CAGL,WAAW;CAGX,KAAK;CACL,KAAK;CACL,QAAQ;CAGR,IAAI;CACJ,IAAI;CACJ,SAAS;CACT,MAAM;CACN,MAAM;CACN,WAAW;CACX,MAAM;CACN,MAAM;CACN,WAAW;CACX,OAAO;CACP,OAAO;CACP,YAAY;CAGZ,MAAM;CACN,KAAK;CACL,QAAQ;CACR,UAAU;CACV,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACP;;;;;;;;;;;;;;;;;;;;;;;;;AA0BD,SAAgB,kBAAkB,KAAsB;AACtD,QAAO,gBAAgB,KAAK,IAAI;;AAGlC,SAAgB,iBAAiB,KAAqB;AAEpD,KAAI,OAAO,YACT,QAAO,YAAY;AAIrB,KAAI,kBAAkB,IAAI,CACxB,QAAO,IAAI,aAAa;CAI1B,MAAM,WAAW,IAAI,aAAa;AAClC,KAAI,oBAAoB,KAAK,SAAS,CACpC,QAAO;AAGT,QAAO;;;;;;;;;;;;;;;;;AAsBT,MAAa,uBAA0D;CACrE,SAAS;CACT,KAAK;CACL,OAAO;CACP,MAAM;CACP;;;;;;;;;;;;;;;;AAiBD,MAAa,2BAA8D;CACzE,SAAS;CACT,KAAK;CACL,OAAO;CACP,MAAM;CACP;;;;;;;;;;;;;;;;AAiBD,MAAa,sBAA8C;CACzD,SAAS;CACT,WAAW;CACX,WAAW;CACX,YAAY;CACZ,OAAO;CACP,QAAQ;CACR,WAAW;CACX,QAAQ;CACR,KAAK;CACL,OAAO;CACR"}
1	+ {"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n CanonicalModifier,\n EditingKey,\n FunctionKey,\n LetterKey,\n NavigationKey,\n NumberKey,\n PunctuationKey,\n} from './hotkey'\n\n// =============================================================================\n// Platform Detection\n// =============================================================================\n\n/*\n Detects the current platform based on browser navigator properties.\n \n Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n \n @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n \n @example\n * ```ts\n * const platform = detectPlatform() // 'mac' \| 'windows' \| 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n /\nexport function detectPlatform(): 'mac' \| 'windows' \| 'linux' {\n if (typeof navigator === 'undefined') {\n return 'linux' // Default for SSR\n }\n\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const platform = navigator.platform?.toLowerCase() ?? ''\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n if (platform.includes('mac') \|\| userAgent.includes('mac')) {\n return 'mac'\n }\n if (platform.includes('win') \|\| userAgent.includes('win')) {\n return 'windows'\n }\n return 'linux'\n}\n\n// =============================================================================\n// Modifier Aliases\n// =============================================================================\n\n/\n Canonical order for modifiers in normalized hotkey strings.\n \n Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n \n Order: Control → Alt → Shift → Meta\n \n @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n /\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n 'Control',\n 'Alt',\n 'Shift',\n 'Meta',\n]\n\n/\n Set of canonical modifier key names for fast lookup.\n \n Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n /\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/\n Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n \n This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n \n The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n /\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier \| 'Mod'> = {\n // Control variants\n Control: 'Control',\n Ctrl: 'Control',\n control: 'Control',\n ctrl: 'Control',\n\n // Shift variants\n Shift: 'Shift',\n shift: 'Shift',\n\n // Alt variants\n Alt: 'Alt',\n Option: 'Alt',\n alt: 'Alt',\n option: 'Alt',\n\n // Meta/Command variants\n Command: 'Meta',\n Cmd: 'Meta',\n Meta: 'Meta',\n command: 'Meta',\n cmd: 'Meta',\n meta: 'Meta',\n\n // Platform-adaptive (resolved at runtime)\n CommandOrControl: 'Mod',\n Mod: 'Mod',\n commandorcontrol: 'Mod',\n mod: 'Mod',\n}\n\n/\n Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n \n The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n \n This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n \n @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n \n @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n /\nexport function resolveModifier(\n modifier: CanonicalModifier \| 'Mod',\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): CanonicalModifier {\n if (modifier === 'Mod') {\n return platform === 'mac' ? 'Meta' : 'Control'\n }\n return modifier\n}\n\n// =============================================================================\n// Valid Keys\n// =============================================================================\n\n/\n Set of all valid letter keys (A-Z).\n \n Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n /\nexport const LETTER_KEYS = new Set<LetterKey>([\n 'A',\n 'B',\n 'C',\n 'D',\n 'E',\n 'F',\n 'G',\n 'H',\n 'I',\n 'J',\n 'K',\n 'L',\n 'M',\n 'N',\n 'O',\n 'P',\n 'Q',\n 'R',\n 'S',\n 'T',\n 'U',\n 'V',\n 'W',\n 'X',\n 'Y',\n 'Z',\n])\n\n/\n Set of all valid number keys (0-9).\n \n Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n /\nexport const NUMBER_KEYS = new Set<NumberKey>([\n '0',\n '1',\n '2',\n '3',\n '4',\n '5',\n '6',\n '7',\n '8',\n '9',\n])\n\n/\n Set of all valid function keys (F1-F12).\n \n Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n /\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n 'F1',\n 'F2',\n 'F3',\n 'F4',\n 'F5',\n 'F6',\n 'F7',\n 'F8',\n 'F9',\n 'F10',\n 'F11',\n 'F12',\n])\n\n/\n Set of all valid navigation keys for cursor movement and document navigation.\n \n Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n /\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n 'ArrowUp',\n 'ArrowDown',\n 'ArrowLeft',\n 'ArrowRight',\n 'Home',\n 'End',\n 'PageUp',\n 'PageDown',\n])\n\n/\n Set of all valid editing and special keys.\n \n Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n /\nexport const EDITING_KEYS = new Set<EditingKey>([\n 'Enter',\n 'Escape',\n 'Space',\n 'Tab',\n 'Backspace',\n 'Delete',\n])\n\n/\n Set of all valid punctuation keys commonly used in keyboard shortcuts.\n \n These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n \n Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n /\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n '/',\n '[',\n ']',\n '\\\\',\n '=',\n '-',\n ',',\n '.',\n ';',\n '`',\n])\n\n/\n Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.\n \n On macOS, holding the Option (Alt) key transforms punctuation keys into special characters\n * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.\n * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables\n * falling back to `event.code` for punctuation keys, similar to the existing `Key`/`Digit`\n * fallbacks for letters and digits.\n /\nexport const PUNCTUATION_CODE_MAP: Record<string, string> = {\n Minus: '-',\n Equal: '=',\n Slash: '/',\n BracketLeft: '[',\n BracketRight: ']',\n Backslash: '\\\\',\n Comma: ',',\n Period: '.',\n Backquote: '`',\n Semicolon: ';',\n}\n\n/\n Set of all valid non-modifier keys.\n \n This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n \n @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n /\nexport const ALL_KEYS = new Set([\n ...LETTER_KEYS,\n ...NUMBER_KEYS,\n ...FUNCTION_KEYS,\n ...NAVIGATION_KEYS,\n ...EDITING_KEYS,\n ...PUNCTUATION_KEYS,\n])\n\n/\n Maps key name aliases to their canonical form.\n \n Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n \n This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n \n @remarks Case-insensitive lookups are supported via lowercase variants\n \n @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n /\nconst KEY_ALIASES: Record<string, string> = {\n // Escape variants\n Esc: 'Escape',\n esc: 'Escape',\n escape: 'Escape',\n\n // Enter variants\n Return: 'Enter',\n return: 'Enter',\n enter: 'Enter',\n\n // Space variants\n ' ': 'Space',\n space: 'Space',\n Spacebar: 'Space',\n spacebar: 'Space',\n\n // Tab variants\n tab: 'Tab',\n\n // Backspace variants\n backspace: 'Backspace',\n\n // Delete variants\n Del: 'Delete',\n del: 'Delete',\n delete: 'Delete',\n\n // Arrow key variants\n Up: 'ArrowUp',\n up: 'ArrowUp',\n arrowup: 'ArrowUp',\n Down: 'ArrowDown',\n down: 'ArrowDown',\n arrowdown: 'ArrowDown',\n Left: 'ArrowLeft',\n left: 'ArrowLeft',\n arrowleft: 'ArrowLeft',\n Right: 'ArrowRight',\n right: 'ArrowRight',\n arrowright: 'ArrowRight',\n\n // Navigation variants\n home: 'Home',\n end: 'End',\n pageup: 'PageUp',\n pagedown: 'PageDown',\n PgUp: 'PageUp',\n PgDn: 'PageDown',\n pgup: 'PageUp',\n pgdn: 'PageDown',\n}\n\n/\n Normalizes a key name to its canonical form.\n \n Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n \n Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n \n @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n \n @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n /\nexport function isSingleLetterKey(key: string): boolean {\n return /^\\p{Letter}$/u.test(key)\n}\n\nexport function normalizeKeyName(key: string): string {\n // Check aliases first\n if (key in KEY_ALIASES) {\n return KEY_ALIASES[key]!\n }\n\n if (isSingleLetterKey(key)) {\n const upper = key.toUpperCase()\n // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences\n // ('SS'). Avoid changing the string length so the rest of the matching\n // logic can rely on a stable single-character key value.\n return upper.length === 1 ? upper : key\n }\n\n // Check if it's a function key (normalize case)\n const upperKey = key.toUpperCase()\n if (/^F([1-9]\|1[0-2])$/.test(upperKey)) {\n return upperKey\n }\n\n return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/\n Modifier key symbols for macOS display.\n \n Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n \n @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n /\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {\n Control: '⌃',\n Alt: '⌥',\n Shift: '⇧',\n Meta: '⌘',\n}\n\n/\n Modifier key labels for Windows/Linux display.\n \n Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n \n @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n /\nexport const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {\n Control: 'Ctrl',\n Alt: 'Alt',\n Shift: 'Shift',\n Meta: 'Win',\n}\n\n/\n Special key symbols for display formatting.\n \n Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n \n @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS: Record<string, string> = {\n ArrowUp: '↑',\n ArrowDown: '↓',\n ArrowLeft: '←',\n ArrowRight: '→',\n Enter: '↵',\n Escape: 'Esc',\n Backspace: '⌫',\n Delete: '⌦',\n Tab: '⇥',\n Space: '␣',\n}\n"],"mappings":"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"}

package/dist/hotkey.d.cts CHANGED Viewed

@@ -37,7 +37,7 @@ type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
  * These are the literal characters as they appear in KeyboardEvent.key
  * (layout-dependent, typically US keyboard layout).
  */
-type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | '`';
+type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`';
 /**
  * Keys that don't change their value when Shift is pressed.
  * These keys produce the same `KeyboardEvent.key` value whether Shift is held or not.

package/dist/hotkey.d.ts CHANGED Viewed

@@ -37,7 +37,7 @@ type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
  * These are the literal characters as they appear in KeyboardEvent.key
  * (layout-dependent, typically US keyboard layout).
  */
-type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | '`';
+type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`';
 /**
  * Keys that don't change their value when Shift is pressed.
  * These keys produce the same `KeyboardEvent.key` value whether Shift is held or not.

package/dist/index.cjs CHANGED Viewed

@@ -23,6 +23,7 @@ exports.MODIFIER_KEYS = require_constants.MODIFIER_KEYS;
 exports.MODIFIER_ORDER = require_constants.MODIFIER_ORDER;
 exports.NAVIGATION_KEYS = require_constants.NAVIGATION_KEYS;
 exports.NUMBER_KEYS = require_constants.NUMBER_KEYS;
+exports.PUNCTUATION_CODE_MAP = require_constants.PUNCTUATION_CODE_MAP;
 exports.PUNCTUATION_KEYS = require_constants.PUNCTUATION_KEYS;
 exports.STANDARD_MODIFIER_LABELS = require_constants.STANDARD_MODIFIER_LABELS;
 exports.SequenceManager = require_sequence_manager.SequenceManager;

package/dist/index.d.cts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult } from "./hotkey.cjs";
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.cjs";
+import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.cjs";
 import { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.cjs";
 import { ConflictBehavior } from "./manager.utils.cjs";
 import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager } from "./hotkey-manager.cjs";
@@ -9,4 +9,4 @@ import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keybo
 import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./recorder.cjs";
 import { HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager } from "./sequence-manager.cjs";
 import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.cjs";
-export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FormatKeyDebuggingOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LetterKey, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_KEYS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, STANDARD_MODIFIER_LABELS, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FormatKeyDebuggingOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LetterKey, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, STANDARD_MODIFIER_LABELS, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };

package/dist/index.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult } from "./hotkey.js";
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
+import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
 import { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.js";
 import { ConflictBehavior } from "./manager.utils.js";
 import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager } from "./hotkey-manager.js";
@@ -9,4 +9,4 @@ import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keybo
 import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./recorder.js";
 import { HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
 import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FormatKeyDebuggingOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LetterKey, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_KEYS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, STANDARD_MODIFIER_LABELS, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FormatKeyDebuggingOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LetterKey, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, STANDARD_MODIFIER_LABELS, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };

package/dist/index.js CHANGED Viewed

@@ -1,4 +1,4 @@
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
+import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
 import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
 import { formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.js";
 import { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
@@ -8,4 +8,4 @@ import { HotkeyRecorder } from "./recorder.js";
 import { SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
 import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, SequenceManager, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, SequenceManager, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };

package/dist/match.cjs CHANGED Viewed

@@ -6,8 +6,9 @@ const require_parse = require('./parse.cjs');
 * Checks if a KeyboardEvent matches a hotkey.
 *
 * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
-* for letter keys and digit keys (0-9) when `key` produces special characters
-* (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+* for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
+* characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
+* Letter keys are matched case-insensitively.
 *
 * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
 * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
@@ -39,17 +40,18 @@ function matchesKeyboardEvent(event, hotkey, platform = require_constants.detect
 	const hotkeyKey = parsed.key;
 	if (eventKey !== "Dead" && eventKey.length === 1 && hotkeyKey.length === 1) {
 		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
-		if (require_constants.isSingleLetterKey(eventKey)) return false;
+		if (require_constants.isSingleLetterKey(eventKey) && (/^[A-Za-z]$/.test(eventKey) || !event.altKey)) return false;
 	}
-	if (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1) {
-		if (event.code?.startsWith("Key")) {
+	if (event.code && (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1)) {
+		if (event.code.startsWith("Key")) {
 			const codeLetter = event.code.slice(3);
 			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
 		}
-		if (event.code?.startsWith("Digit")) {
+		if (event.code.startsWith("Digit")) {
 			const codeDigit = event.code.slice(5);
 			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
 		}
+		if (event.code in require_constants.PUNCTUATION_CODE_MAP) return require_constants.PUNCTUATION_CODE_MAP[event.code] === hotkeyKey;
 		return false;
 	}
 	return eventKey === hotkeyKey;

package/dist/match.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"match.cjs","names":["detectPlatform","parseHotkey","normalizeKeyName","isSingleLetterKey"],"sources":["../src/match.ts"],"sourcesContent":["import {\n detectPlatform,\n isSingleLetterKey,\n normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyCallbackContext,\n ParsedHotkey,\n} from './hotkey'\n\n/*\n Checks if a KeyboardEvent matches a hotkey.\n \n Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys and digit keys (0-9) when `key` produces special characters\n * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.\n \n Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n \n @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n \n @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n * if (matchesKeyboardEvent(event, 'Mod+S')) {\n * event.preventDefault()\n * handleSave()\n * }\n * })\n * ```\n /\nexport function matchesKeyboardEvent(\n event: KeyboardEvent,\n hotkey: Hotkey \| ParsedHotkey,\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): boolean {\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n // Check modifiers\n if (event.ctrlKey !== parsed.ctrl) {\n return false\n }\n if (event.shiftKey !== parsed.shift) {\n return false\n }\n if (event.altKey !== parsed.alt) {\n return false\n }\n if (event.metaKey !== parsed.meta) {\n return false\n }\n\n // Check key (case-insensitive for letters)\n const eventKey = normalizeKeyName(event.key)\n const hotkeyKey = parsed.key\n\n // For single-character keys (not dead keys), try direct event.key match first\n if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n return true\n }\n\n // If event.key is already a letter, trust the keyboard layout.\n // Do NOT fall through to the event.code fallback, which matches based on\n // physical key position and would break non-QWERTY layouts (Dvorak, Colemak,\n // AZERTY, etc.). The code fallback is only needed when event.key produces a\n // non-letter character (e.g., '†' from Option+T on macOS).\n if (isSingleLetterKey(eventKey)) {\n return false\n }\n }\n\n // Fallback to event.code for dead keys or single-char mismatches where\n // event.key is a non-letter special character.\n // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n if (\n eventKey === 'Dead' \|\|\n (eventKey.length === 1 && hotkeyKey.length === 1)\n ) {\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- event.code can be undefined in older browsers/mobile\n if (event.code?.startsWith('Key')) {\n const codeLetter = event.code.slice(3)\n if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n }\n }\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- event.code can be undefined in older browsers/mobile\n if (event.code?.startsWith('Digit')) {\n const codeDigit = event.code.slice(5)\n if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n return codeDigit === hotkeyKey\n }\n }\n return false\n }\n\n // For special keys, compare exactly (after normalization)\n return eventKey === hotkeyKey\n}\n\n/\n Options for creating a hotkey handler.\n /\nexport interface CreateHotkeyHandlerOptions {\n /* Prevent the default browser action when the hotkey matches. Defaults to true /\n preventDefault?: boolean\n /* Stop event propagation when the hotkey matches. Defaults to true /\n stopPropagation?: boolean\n /* The target platform for resolving 'Mod' /\n platform?: 'mac' \| 'windows' \| 'linux'\n}\n\n/\n Creates a keyboard event handler that calls the callback when the hotkey matches.\n \n @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n * console.log(`${hotkey} was pressed`)\n * handleSave()\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createHotkeyHandler(\n hotkey: Hotkey \| ParsedHotkey,\n callback: HotkeyCallback,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n const hotkeyString: Hotkey =\n typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n const context: HotkeyCallbackContext = {\n hotkey: hotkeyString,\n parsedHotkey: parsed,\n }\n\n return (event: KeyboardEvent) => {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n callback(event, context)\n }\n }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/\n Creates a handler that matches multiple hotkeys.\n \n @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n * 'Mod+S': (event, { hotkey }) => handleSave(),\n * 'Mod+Z': (event, { hotkey }) => handleUndo(),\n * 'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createMultiHotkeyHandler(\n handlers: MultiHotkeyHandler,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n // Pre-parse all hotkeys for efficiency\n const parsedHandlers = Object.entries(handlers)\n .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n .map(([hotkey, handler]) => {\n const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n const context: HotkeyCallbackContext = {\n hotkey: hotkey as Hotkey,\n parsedHotkey: parsed,\n }\n return { parsed, handler, context }\n })\n\n return (event: KeyboardEvent) => {\n for (const { parsed, handler, context } of parsedHandlers) {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n handler(event, context)\n return // Only handle the first match\n }\n }\n }\n}\n\n/\n Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n const parts: Array<string> = []\n\n if (parsed.ctrl) parts.push('Control')\n if (parsed.alt) parts.push('Alt')\n if (parsed.shift) parts.push('Shift')\n if (parsed.meta) parts.push('Meta')\n parts.push(parsed.key)\n\n return parts.join('+') as Hotkey\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,qBACd,OACA,QACA,WAAwCA,kCAAgB,EAC/C;CACT,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;AAG/D,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;AAET,KAAI,MAAM,aAAa,OAAO,MAC5B,QAAO;AAET,KAAI,MAAM,WAAW,OAAO,IAC1B,QAAO;AAET,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;CAIT,MAAM,WAAWC,mCAAiB,MAAM,IAAI;CAC5C,MAAM,YAAY,OAAO;AAGzB,KAAI,aAAa,UAAU,SAAS,WAAW,KAAK,UAAU,WAAW,GAAG;AAC1E,MAAI,SAAS,aAAa,KAAK,UAAU,aAAa,CACpD,QAAO;AAQT,MAAIC,oCAAkB,SAAS,CAC7B,QAAO;;AAQX,KACE,aAAa,UACZ,SAAS,WAAW,KAAK,UAAU,WAAW,GAC/C;AAEA,MAAI,MAAM,MAAM,WAAW,MAAM,EAAE;GACjC,MAAM,aAAa,MAAM,KAAK,MAAM,EAAE;AACtC,OAAI,WAAW,WAAW,KAAK,aAAa,KAAK,WAAW,CAC1D,QAAO,WAAW,aAAa,KAAK,UAAU,aAAa;;AAI/D,MAAI,MAAM,MAAM,WAAW,QAAQ,EAAE;GACnC,MAAM,YAAY,MAAM,KAAK,MAAM,EAAE;AACrC,OAAI,UAAU,WAAW,KAAK,UAAU,KAAK,UAAU,CACrD,QAAO,cAAc;;AAGzB,SAAO;;AAIT,QAAO,aAAa;;;;;;;;;;;;;;;;;;;;AAiCtB,SAAgB,oBACd,QACA,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAYH,kCAAgB;CAErD,MAAM,eACJ,OAAO,WAAW,WAAW,SAAS,mBAAmB,OAAO;CAClE,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,iBAAiB,GAAG;CAEvE,MAAM,UAAiC;EACrC,QAAQ;EACR,cAAc;EACf;AAED,SAAQ,UAAyB;AAC/B,MAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,YAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,yBACd,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAYD,kCAAgB;CAGrD,MAAM,iBAAiB,OAAO,QAAQ,SAAS,CAC5C,QAAQ,UAA6C,QAAQ,MAAM,GAAG,CAAC,CACvE,KAAK,CAAC,QAAQ,aAAa;EAC1B,MAAM,SAASC,0BAAY,QAAkB,iBAAiB;AAK9D,SAAO;GAAE;GAAQ;GAAS,SAJa;IAC7B;IACR,cAAc;IACf;GACkC;GACnC;AAEJ,SAAQ,UAAyB;AAC/B,OAAK,MAAM,EAAE,QAAQ,SAAS,aAAa,eACzC,KAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,WAAQ,OAAO,QAAQ;AACvB;;;;;;;;AAUR,SAAS,mBAAmB,QAA8B;CACxD,MAAM,QAAuB,EAAE;AAE/B,KAAI,OAAO,KAAM,OAAM,KAAK,UAAU;AACtC,KAAI,OAAO,IAAK,OAAM,KAAK,MAAM;AACjC,KAAI,OAAO,MAAO,OAAM,KAAK,QAAQ;AACrC,KAAI,OAAO,KAAM,OAAM,KAAK,OAAO;AACnC,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI"}
1	+ {"version":3,"file":"match.cjs","names":["detectPlatform","parseHotkey","normalizeKeyName","isSingleLetterKey","PUNCTUATION_CODE_MAP"],"sources":["../src/match.ts"],"sourcesContent":["import {\n PUNCTUATION_CODE_MAP,\n detectPlatform,\n isSingleLetterKey,\n normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyCallbackContext,\n ParsedHotkey,\n} from './hotkey'\n\n/*\n Checks if a KeyboardEvent matches a hotkey.\n \n Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n \n Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n \n @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n \n @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n * if (matchesKeyboardEvent(event, 'Mod+S')) {\n * event.preventDefault()\n * handleSave()\n * }\n * })\n * ```\n /\nexport function matchesKeyboardEvent(\n event: KeyboardEvent,\n hotkey: Hotkey \| ParsedHotkey,\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): boolean {\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n // Check modifiers\n if (event.ctrlKey !== parsed.ctrl) {\n return false\n }\n if (event.shiftKey !== parsed.shift) {\n return false\n }\n if (event.altKey !== parsed.alt) {\n return false\n }\n if (event.metaKey !== parsed.meta) {\n return false\n }\n\n // Check key (case-insensitive for letters)\n const eventKey = normalizeKeyName(event.key)\n const hotkeyKey = parsed.key\n\n // For single-character keys (not dead keys), try direct event.key match first\n if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n return true\n }\n\n // If event.key is a letter, we usually trust the keyboard layout.\n // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).\n // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).\n //\n // For non-ASCII letters WITH Alt held down: fall through to the event.code\n // fallback. macOS Option+letter combinations produce non-ASCII letters as\n // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but\n // event.code still reflects the physical key. We want Alt+A to match even\n // when Option+A fires event.key='å'.\n if (\n isSingleLetterKey(eventKey) &&\n (/^[A-Za-z]$/.test(eventKey) \|\| !event.altKey)\n ) {\n return false\n }\n }\n\n // Fallback to event.code for dead keys or single-char mismatches where\n // event.key is a non-letter special character.\n // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n if (\n event.code &&\n (eventKey === 'Dead' \|\| (eventKey.length === 1 && hotkeyKey.length === 1))\n ) {\n // fallback for letter keys (common with mac option + letter)\n if (event.code.startsWith('Key')) {\n const codeLetter = event.code.slice(3)\n if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n }\n }\n\n // fallback for number keys (common with mac option + num)\n if (event.code.startsWith('Digit')) {\n const codeDigit = event.code.slice(5)\n if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n return codeDigit === hotkeyKey\n }\n }\n // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).\n // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),\n // but event.code still reports the physical key.\n if (event.code in PUNCTUATION_CODE_MAP) {\n return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey\n }\n\n return false\n }\n\n // For special keys, compare exactly (after normalization)\n return eventKey === hotkeyKey\n}\n\n/\n Options for creating a hotkey handler.\n /\nexport interface CreateHotkeyHandlerOptions {\n /* Prevent the default browser action when the hotkey matches. Defaults to true /\n preventDefault?: boolean\n /* Stop event propagation when the hotkey matches. Defaults to true /\n stopPropagation?: boolean\n /* The target platform for resolving 'Mod' /\n platform?: 'mac' \| 'windows' \| 'linux'\n}\n\n/\n Creates a keyboard event handler that calls the callback when the hotkey matches.\n \n @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n * console.log(`${hotkey} was pressed`)\n * handleSave()\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createHotkeyHandler(\n hotkey: Hotkey \| ParsedHotkey,\n callback: HotkeyCallback,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n const hotkeyString: Hotkey =\n typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n const context: HotkeyCallbackContext = {\n hotkey: hotkeyString,\n parsedHotkey: parsed,\n }\n\n return (event: KeyboardEvent) => {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n callback(event, context)\n }\n }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/\n Creates a handler that matches multiple hotkeys.\n \n @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n * 'Mod+S': (event, { hotkey }) => handleSave(),\n * 'Mod+Z': (event, { hotkey }) => handleUndo(),\n * 'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createMultiHotkeyHandler(\n handlers: MultiHotkeyHandler,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n // Pre-parse all hotkeys for efficiency\n const parsedHandlers = Object.entries(handlers)\n .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n .map(([hotkey, handler]) => {\n const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n const context: HotkeyCallbackContext = {\n hotkey: hotkey as Hotkey,\n parsedHotkey: parsed,\n }\n return { parsed, handler, context }\n })\n\n return (event: KeyboardEvent) => {\n for (const { parsed, handler, context } of parsedHandlers) {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n handler(event, context)\n return // Only handle the first match\n }\n }\n }\n}\n\n/\n Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n const parts: Array<string> = []\n\n if (parsed.ctrl) parts.push('Control')\n if (parsed.alt) parts.push('Alt')\n if (parsed.shift) parts.push('Shift')\n if (parsed.meta) parts.push('Meta')\n parts.push(parsed.key)\n\n return parts.join('+') as Hotkey\n}\n"],"mappings":"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"}

package/dist/match.d.cts CHANGED Viewed

@@ -5,8 +5,9 @@ import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.cjs";
  * Checks if a KeyboardEvent matches a hotkey.
  *
  * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
- * for letter keys and digit keys (0-9) when `key` produces special characters
- * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+ * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
+ * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
+ * Letter keys are matched case-insensitively.
  *
  * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
  * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,

package/dist/match.d.ts CHANGED Viewed

@@ -5,8 +5,9 @@ import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.js";
  * Checks if a KeyboardEvent matches a hotkey.
  *
  * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
- * for letter keys and digit keys (0-9) when `key` produces special characters
- * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+ * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
+ * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
+ * Letter keys are matched case-insensitively.
  *
  * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
  * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,

package/dist/match.js CHANGED Viewed

@@ -1,4 +1,4 @@
-import { detectPlatform, isSingleLetterKey, normalizeKeyName } from "./constants.js";
+import { PUNCTUATION_CODE_MAP, detectPlatform, isSingleLetterKey, normalizeKeyName } from "./constants.js";
 import { parseHotkey } from "./parse.js";
 //#region src/match.ts
@@ -6,8 +6,9 @@ import { parseHotkey } from "./parse.js";
 * Checks if a KeyboardEvent matches a hotkey.
 *
 * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
-* for letter keys and digit keys (0-9) when `key` produces special characters
-* (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+* for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
+* characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
+* Letter keys are matched case-insensitively.
 *
 * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
 * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
@@ -39,17 +40,18 @@ function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 	const hotkeyKey = parsed.key;
 	if (eventKey !== "Dead" && eventKey.length === 1 && hotkeyKey.length === 1) {
 		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
-		if (isSingleLetterKey(eventKey)) return false;
+		if (isSingleLetterKey(eventKey) && (/^[A-Za-z]$/.test(eventKey) || !event.altKey)) return false;
 	}
-	if (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1) {
-		if (event.code?.startsWith("Key")) {
+	if (event.code && (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1)) {
+		if (event.code.startsWith("Key")) {
 			const codeLetter = event.code.slice(3);
 			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
 		}
-		if (event.code?.startsWith("Digit")) {
+		if (event.code.startsWith("Digit")) {
 			const codeDigit = event.code.slice(5);
 			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
 		}
+		if (event.code in PUNCTUATION_CODE_MAP) return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey;
 		return false;
 	}
 	return eventKey === hotkeyKey;

package/dist/match.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"match.js","names":[],"sources":["../src/match.ts"],"sourcesContent":["import {\n detectPlatform,\n isSingleLetterKey,\n normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyCallbackContext,\n ParsedHotkey,\n} from './hotkey'\n\n/*\n Checks if a KeyboardEvent matches a hotkey.\n \n Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys and digit keys (0-9) when `key` produces special characters\n * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.\n \n Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n \n @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n \n @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n * if (matchesKeyboardEvent(event, 'Mod+S')) {\n * event.preventDefault()\n * handleSave()\n * }\n * })\n * ```\n /\nexport function matchesKeyboardEvent(\n event: KeyboardEvent,\n hotkey: Hotkey \| ParsedHotkey,\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): boolean {\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n // Check modifiers\n if (event.ctrlKey !== parsed.ctrl) {\n return false\n }\n if (event.shiftKey !== parsed.shift) {\n return false\n }\n if (event.altKey !== parsed.alt) {\n return false\n }\n if (event.metaKey !== parsed.meta) {\n return false\n }\n\n // Check key (case-insensitive for letters)\n const eventKey = normalizeKeyName(event.key)\n const hotkeyKey = parsed.key\n\n // For single-character keys (not dead keys), try direct event.key match first\n if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n return true\n }\n\n // If event.key is already a letter, trust the keyboard layout.\n // Do NOT fall through to the event.code fallback, which matches based on\n // physical key position and would break non-QWERTY layouts (Dvorak, Colemak,\n // AZERTY, etc.). The code fallback is only needed when event.key produces a\n // non-letter character (e.g., '†' from Option+T on macOS).\n if (isSingleLetterKey(eventKey)) {\n return false\n }\n }\n\n // Fallback to event.code for dead keys or single-char mismatches where\n // event.key is a non-letter special character.\n // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n if (\n eventKey === 'Dead' \|\|\n (eventKey.length === 1 && hotkeyKey.length === 1)\n ) {\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- event.code can be undefined in older browsers/mobile\n if (event.code?.startsWith('Key')) {\n const codeLetter = event.code.slice(3)\n if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n }\n }\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- event.code can be undefined in older browsers/mobile\n if (event.code?.startsWith('Digit')) {\n const codeDigit = event.code.slice(5)\n if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n return codeDigit === hotkeyKey\n }\n }\n return false\n }\n\n // For special keys, compare exactly (after normalization)\n return eventKey === hotkeyKey\n}\n\n/\n Options for creating a hotkey handler.\n /\nexport interface CreateHotkeyHandlerOptions {\n /* Prevent the default browser action when the hotkey matches. Defaults to true /\n preventDefault?: boolean\n /* Stop event propagation when the hotkey matches. Defaults to true /\n stopPropagation?: boolean\n /* The target platform for resolving 'Mod' /\n platform?: 'mac' \| 'windows' \| 'linux'\n}\n\n/\n Creates a keyboard event handler that calls the callback when the hotkey matches.\n \n @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n * console.log(`${hotkey} was pressed`)\n * handleSave()\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createHotkeyHandler(\n hotkey: Hotkey \| ParsedHotkey,\n callback: HotkeyCallback,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n const hotkeyString: Hotkey =\n typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n const context: HotkeyCallbackContext = {\n hotkey: hotkeyString,\n parsedHotkey: parsed,\n }\n\n return (event: KeyboardEvent) => {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n callback(event, context)\n }\n }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/\n Creates a handler that matches multiple hotkeys.\n \n @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n * 'Mod+S': (event, { hotkey }) => handleSave(),\n * 'Mod+Z': (event, { hotkey }) => handleUndo(),\n * 'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createMultiHotkeyHandler(\n handlers: MultiHotkeyHandler,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n // Pre-parse all hotkeys for efficiency\n const parsedHandlers = Object.entries(handlers)\n .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n .map(([hotkey, handler]) => {\n const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n const context: HotkeyCallbackContext = {\n hotkey: hotkey as Hotkey,\n parsedHotkey: parsed,\n }\n return { parsed, handler, context }\n })\n\n return (event: KeyboardEvent) => {\n for (const { parsed, handler, context } of parsedHandlers) {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n handler(event, context)\n return // Only handle the first match\n }\n }\n }\n}\n\n/\n Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n const parts: Array<string> = []\n\n if (parsed.ctrl) parts.push('Control')\n if (parsed.alt) parts.push('Alt')\n if (parsed.shift) parts.push('Shift')\n if (parsed.meta) parts.push('Meta')\n parts.push(parsed.key)\n\n return parts.join('+') as Hotkey\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,qBACd,OACA,QACA,WAAwC,gBAAgB,EAC/C;CACT,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;AAG/D,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;AAET,KAAI,MAAM,aAAa,OAAO,MAC5B,QAAO;AAET,KAAI,MAAM,WAAW,OAAO,IAC1B,QAAO;AAET,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;CAIT,MAAM,WAAW,iBAAiB,MAAM,IAAI;CAC5C,MAAM,YAAY,OAAO;AAGzB,KAAI,aAAa,UAAU,SAAS,WAAW,KAAK,UAAU,WAAW,GAAG;AAC1E,MAAI,SAAS,aAAa,KAAK,UAAU,aAAa,CACpD,QAAO;AAQT,MAAI,kBAAkB,SAAS,CAC7B,QAAO;;AAQX,KACE,aAAa,UACZ,SAAS,WAAW,KAAK,UAAU,WAAW,GAC/C;AAEA,MAAI,MAAM,MAAM,WAAW,MAAM,EAAE;GACjC,MAAM,aAAa,MAAM,KAAK,MAAM,EAAE;AACtC,OAAI,WAAW,WAAW,KAAK,aAAa,KAAK,WAAW,CAC1D,QAAO,WAAW,aAAa,KAAK,UAAU,aAAa;;AAI/D,MAAI,MAAM,MAAM,WAAW,QAAQ,EAAE;GACnC,MAAM,YAAY,MAAM,KAAK,MAAM,EAAE;AACrC,OAAI,UAAU,WAAW,KAAK,UAAU,KAAK,UAAU,CACrD,QAAO,cAAc;;AAGzB,SAAO;;AAIT,QAAO,aAAa;;;;;;;;;;;;;;;;;;;;AAiCtB,SAAgB,oBACd,QACA,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAY,gBAAgB;CAErD,MAAM,eACJ,OAAO,WAAW,WAAW,SAAS,mBAAmB,OAAO;CAClE,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,iBAAiB,GAAG;CAEvE,MAAM,UAAiC;EACrC,QAAQ;EACR,cAAc;EACf;AAED,SAAQ,UAAyB;AAC/B,MAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,YAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,yBACd,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAY,gBAAgB;CAGrD,MAAM,iBAAiB,OAAO,QAAQ,SAAS,CAC5C,QAAQ,UAA6C,QAAQ,MAAM,GAAG,CAAC,CACvE,KAAK,CAAC,QAAQ,aAAa;EAC1B,MAAM,SAAS,YAAY,QAAkB,iBAAiB;AAK9D,SAAO;GAAE;GAAQ;GAAS,SAJa;IAC7B;IACR,cAAc;IACf;GACkC;GACnC;AAEJ,SAAQ,UAAyB;AAC/B,OAAK,MAAM,EAAE,QAAQ,SAAS,aAAa,eACzC,KAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,WAAQ,OAAO,QAAQ;AACvB;;;;;;;;AAUR,SAAS,mBAAmB,QAA8B;CACxD,MAAM,QAAuB,EAAE;AAE/B,KAAI,OAAO,KAAM,OAAM,KAAK,UAAU;AACtC,KAAI,OAAO,IAAK,OAAM,KAAK,MAAM;AACjC,KAAI,OAAO,MAAO,OAAM,KAAK,QAAQ;AACrC,KAAI,OAAO,KAAM,OAAM,KAAK,OAAO;AACnC,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI"}
1	+ {"version":3,"file":"match.js","names":[],"sources":["../src/match.ts"],"sourcesContent":["import {\n PUNCTUATION_CODE_MAP,\n detectPlatform,\n isSingleLetterKey,\n normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyCallbackContext,\n ParsedHotkey,\n} from './hotkey'\n\n/*\n Checks if a KeyboardEvent matches a hotkey.\n \n Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n \n Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n \n @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n \n @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n * if (matchesKeyboardEvent(event, 'Mod+S')) {\n * event.preventDefault()\n * handleSave()\n * }\n * })\n * ```\n /\nexport function matchesKeyboardEvent(\n event: KeyboardEvent,\n hotkey: Hotkey \| ParsedHotkey,\n platform: 'mac' \| 'windows' \| 'linux' = detectPlatform(),\n): boolean {\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n // Check modifiers\n if (event.ctrlKey !== parsed.ctrl) {\n return false\n }\n if (event.shiftKey !== parsed.shift) {\n return false\n }\n if (event.altKey !== parsed.alt) {\n return false\n }\n if (event.metaKey !== parsed.meta) {\n return false\n }\n\n // Check key (case-insensitive for letters)\n const eventKey = normalizeKeyName(event.key)\n const hotkeyKey = parsed.key\n\n // For single-character keys (not dead keys), try direct event.key match first\n if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n return true\n }\n\n // If event.key is a letter, we usually trust the keyboard layout.\n // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).\n // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).\n //\n // For non-ASCII letters WITH Alt held down: fall through to the event.code\n // fallback. macOS Option+letter combinations produce non-ASCII letters as\n // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but\n // event.code still reflects the physical key. We want Alt+A to match even\n // when Option+A fires event.key='å'.\n if (\n isSingleLetterKey(eventKey) &&\n (/^[A-Za-z]$/.test(eventKey) \|\| !event.altKey)\n ) {\n return false\n }\n }\n\n // Fallback to event.code for dead keys or single-char mismatches where\n // event.key is a non-letter special character.\n // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n if (\n event.code &&\n (eventKey === 'Dead' \|\| (eventKey.length === 1 && hotkeyKey.length === 1))\n ) {\n // fallback for letter keys (common with mac option + letter)\n if (event.code.startsWith('Key')) {\n const codeLetter = event.code.slice(3)\n if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n }\n }\n\n // fallback for number keys (common with mac option + num)\n if (event.code.startsWith('Digit')) {\n const codeDigit = event.code.slice(5)\n if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n return codeDigit === hotkeyKey\n }\n }\n // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).\n // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),\n // but event.code still reports the physical key.\n if (event.code in PUNCTUATION_CODE_MAP) {\n return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey\n }\n\n return false\n }\n\n // For special keys, compare exactly (after normalization)\n return eventKey === hotkeyKey\n}\n\n/\n Options for creating a hotkey handler.\n /\nexport interface CreateHotkeyHandlerOptions {\n /* Prevent the default browser action when the hotkey matches. Defaults to true /\n preventDefault?: boolean\n /* Stop event propagation when the hotkey matches. Defaults to true /\n stopPropagation?: boolean\n /* The target platform for resolving 'Mod' /\n platform?: 'mac' \| 'windows' \| 'linux'\n}\n\n/\n Creates a keyboard event handler that calls the callback when the hotkey matches.\n \n @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n * console.log(`${hotkey} was pressed`)\n * handleSave()\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createHotkeyHandler(\n hotkey: Hotkey \| ParsedHotkey,\n callback: HotkeyCallback,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n const hotkeyString: Hotkey =\n typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n const parsed =\n typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n const context: HotkeyCallbackContext = {\n hotkey: hotkeyString,\n parsedHotkey: parsed,\n }\n\n return (event: KeyboardEvent) => {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n callback(event, context)\n }\n }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/\n Creates a handler that matches multiple hotkeys.\n \n @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n \n @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n * 'Mod+S': (event, { hotkey }) => handleSave(),\n * 'Mod+Z': (event, { hotkey }) => handleUndo(),\n * 'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n \n document.addEventListener('keydown', handler)\n * ```\n /\nexport function createMultiHotkeyHandler(\n handlers: MultiHotkeyHandler,\n options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n const { preventDefault = true, stopPropagation = true, platform } = options\n const resolvedPlatform = platform ?? detectPlatform()\n\n // Pre-parse all hotkeys for efficiency\n const parsedHandlers = Object.entries(handlers)\n .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n .map(([hotkey, handler]) => {\n const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n const context: HotkeyCallbackContext = {\n hotkey: hotkey as Hotkey,\n parsedHotkey: parsed,\n }\n return { parsed, handler, context }\n })\n\n return (event: KeyboardEvent) => {\n for (const { parsed, handler, context } of parsedHandlers) {\n if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n if (preventDefault) {\n event.preventDefault()\n }\n if (stopPropagation) {\n event.stopPropagation()\n }\n handler(event, context)\n return // Only handle the first match\n }\n }\n }\n}\n\n/\n Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n const parts: Array<string> = []\n\n if (parsed.ctrl) parts.push('Control')\n if (parsed.alt) parts.push('Alt')\n if (parsed.shift) parts.push('Shift')\n if (parsed.meta) parts.push('Meta')\n parts.push(parsed.key)\n\n return parts.join('+') as Hotkey\n}\n"],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/constants.ts CHANGED Viewed

@@ -297,9 +297,32 @@ export const PUNCTUATION_KEYS = new Set<PunctuationKey>([
   '-',
   ',',
   '.',
+  ';',
   '`',
 ])
+/**
+ * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
+ *
+ * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters
+ * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.
+ * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables
+ * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`
+ * fallbacks for letters and digits.
+ */
+export const PUNCTUATION_CODE_MAP: Record<string, string> = {
+  Minus: '-',
+  Equal: '=',
+  Slash: '/',
+  BracketLeft: '[',
+  BracketRight: ']',
+  Backslash: '\\',
+  Comma: ',',
+  Period: '.',
+  Backquote: '`',
+  Semicolon: ';',
+}
 /**
  * Set of all valid non-modifier keys.
  *
@@ -429,9 +452,12 @@ export function normalizeKeyName(key: string): string {
     return KEY_ALIASES[key]!
   }
-  // Check if it's a single letter (normalize to uppercase)
   if (isSingleLetterKey(key)) {
-    return key.toUpperCase()
+    const upper = key.toUpperCase()
+    // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences
+    // ('SS'). Avoid changing the string length so the rest of the matching
+    // logic can rely on a stable single-character key value.
+    return upper.length === 1 ? upper : key
   }
   // Check if it's a function key (normalize case)

package/src/hotkey.ts CHANGED Viewed

@@ -123,6 +123,7 @@ export type PunctuationKey =
   | '-'
   | ','
   | '.'
+  | ';'
   | '`'
 /**

package/src/match.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import {
+  PUNCTUATION_CODE_MAP,
   detectPlatform,
   isSingleLetterKey,
   normalizeKeyName,
@@ -15,8 +16,9 @@ import type {
  * Checks if a KeyboardEvent matches a hotkey.
  *
  * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
- * for letter keys and digit keys (0-9) when `key` produces special characters
- * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+ * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
+ * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
+ * Letter keys are matched case-insensitively.
  *
  * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
  * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
@@ -70,12 +72,19 @@ export function matchesKeyboardEvent(
       return true
     }
-    // If event.key is already a letter, trust the keyboard layout.
-    // Do NOT fall through to the event.code fallback, which matches based on
-    // physical key position and would break non-QWERTY layouts (Dvorak, Colemak,
-    // AZERTY, etc.). The code fallback is only needed when event.key produces a
-    // non-letter character (e.g., '†' from Option+T on macOS).
-    if (isSingleLetterKey(eventKey)) {
+    // If event.key is a letter, we usually trust the keyboard layout.
+    // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).
+    // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).
+    //
+    // For non-ASCII letters WITH Alt held down: fall through to the event.code
+    // fallback. macOS Option+letter combinations produce non-ASCII letters as
+    // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but
+    // event.code still reflects the physical key. We want Alt+A to match even
+    // when Option+A fires event.key='å'.
+    if (
+      isSingleLetterKey(eventKey) &&
+      (/^[A-Za-z]$/.test(eventKey) || !event.altKey)
+    ) {
       return false
     }
   }
@@ -85,23 +94,31 @@ export function matchesKeyboardEvent(
   // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'
   // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'
   if (
-    eventKey === 'Dead' ||
-    (eventKey.length === 1 && hotkeyKey.length === 1)
+    event.code &&
+    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))
   ) {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- event.code can be undefined in older browsers/mobile
-    if (event.code?.startsWith('Key')) {
+    // fallback for letter keys (common with mac option + letter)
+    if (event.code.startsWith('Key')) {
       const codeLetter = event.code.slice(3)
       if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {
         return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()
       }
     }
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- event.code can be undefined in older browsers/mobile
-    if (event.code?.startsWith('Digit')) {
+    // fallback for number keys (common with mac option + num)
+    if (event.code.startsWith('Digit')) {
       const codeDigit = event.code.slice(5)
       if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {
         return codeDigit === hotkeyKey
       }
     }
+    // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).
+    // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),
+    // but event.code still reports the physical key.
+    if (event.code in PUNCTUATION_CODE_MAP) {
+      return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey
+    }
     return false
   }