@tanstack/hotkeys 0.8.0 → 0.10.0

package/dist/{hotkey.d.ts → hotkey.types.d.ts}

@@ -1,66 +1,8 @@
-//#region src/hotkey.d.ts
-/**
- * All supported modifier key names, including aliases.
- * - Control/Ctrl: The Control key
- * - Shift: The Shift key
- * - Alt/Option: The Alt key (Option on macOS)
- * - Command/Cmd: The Command key (macOS only)
- * - CommandOrControl/Mod: Command on macOS, Control on other platforms
- */
-type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
-/**
- * Canonical modifier names that map to KeyboardEvent properties.
- */
-type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
-/**
- * Letter keys A-Z (case-insensitive in matching).
- */
-type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
-/**
- * Number keys 0-9.
- */
-type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-/**
- * Function keys F1-F12.
- */
-type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12';
-/**
- * Navigation keys for cursor movement.
- */
-type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
-/**
- * Editing and special keys.
- */
-type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
-/**
- * Punctuation keys commonly used in keyboard shortcuts.
- * These are the literal characters as they appear in KeyboardEvent.key
- * (layout-dependent, typically US keyboard layout).
- */
-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.
- *
- * Excludes NumberKey (Shift+1 produces '!' on US layout) and PunctuationKey
- * (Shift+',' produces '<' on US layout).
- *
- * Used in hotkey type definitions to prevent layout-dependent issues when Shift
- * is part of the modifier combination.
- */
-type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey;
-/**
- * All supported non-modifier keys.
- */
-type Key = NonPunctuationKey | PunctuationKey;
-/**
- * Includes both modifier keys and regular keys.
- */
-type IndividualKey = CanonicalModifier | Key;
+import { CanonicalModifier, Key, LogicalKey } from "./key.types.js";
+//#region src/hotkey.types.d.ts
 /**
  * Single modifier + key combinations.
  * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
- * Shift combinations exclude PunctuationKey to avoid layout-dependent issues.
  *
  * The `Mod` modifier is platform-adaptive:
  * - **macOS**: Resolves to `Meta` (Command key ⌘)
@@ -69,10 +11,9 @@ type IndividualKey = CanonicalModifier | Key;
  * This enables cross-platform hotkey definitions that automatically adapt to the platform.
  * For example, `Mod+S` becomes `Command+S` on Mac and `Ctrl+S` on Windows/Linux.
  */
-type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctuationKey}` | `Meta+${Key}` | `Mod+${Key}`;
+export type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${Key}` | `Meta+${Key}` | `Mod+${Key}`;
 /**
  * Two modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * **Platform-adaptive `Mod` combinations:**
  * - `Mod+Alt` and `Mod+Shift` are included (safe on all platforms)
@@ -80,10 +21,9 @@ type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctu
  *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationKey}` | `Control+Meta+${Key}` | `Alt+Shift+${NonPunctuationKey}` | `Alt+Meta+${Key}` | `Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+${Key}` | `Mod+Shift+${NonPunctuationKey}`;
+export type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${Key}` | `Control+Meta+${Key}` | `Alt+Shift+${Key}` | `Alt+Meta+${Key}` | `Shift+Meta+${Key}` | `Mod+Alt+${Key}` | `Mod+Shift+${Key}`;
 /**
  * Three modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * **Platform-adaptive `Mod` combinations:**
  * - `Mod+Alt+Shift` is included (safe on all platforms)
@@ -91,10 +31,9 @@ type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationK
  *   - `Mod+Control+Shift` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Shift+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${NonPunctuationKey}` | `Alt+Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+Shift+${NonPunctuationKey}`;
+export type ThreeModifierHotkey = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${Key}` | `Alt+Shift+Meta+${Key}` | `Mod+Alt+Shift+${Key}`;
 /**
  * Four modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * Only the canonical `Control+Alt+Shift+Meta` combination is included.
  *
@@ -105,7 +44,7 @@ type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+A
  * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
  * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
  */
-type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
+export type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`;
 /**
  * A type-safe hotkey string.
  *
@@ -158,39 +97,36 @@ type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
  * const windowsOnly: Hotkey = 'Control+S' // Ctrl+S on Windows/Linux only
  * ```
  */
-type Hotkey = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
-/**
- * A parsed representation of a hotkey string.
- *
- * This interface provides a flexible fallback when the `Hotkey` type doesn't
- * fit your use case. You can pass a `ParsedHotkey` directly to hotkey functions
- * instead of a hotkey string, allowing for more dynamic or complex scenarios
- * that aren't covered by the type-safe `Hotkey` union.
- *
- * @example
- * ```ts
- * // Type-safe hotkey string
- * useHotkey('Mod+S', handler)
- *
- * // Fallback: parsed hotkey for dynamic scenarios
- * const parsed = parseHotkey(userInput)
- * useHotkey(parsed, handler) // Works even if userInput isn't in Hotkey type
- * ```
- */
-interface ParsedHotkey {
-  /** The non-modifier key (e.g., 'S', 'Escape', 'F1', '/', '['). Can be any string for flexibility. */
-  key: Key | (string & {});
-  /** Whether the Control key is required */
+export type Hotkey = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
+/** Resolved modifier flags shared by both parsed binding variants. */
+export interface ParsedModifiers {
+  /** Whether Control is required. */
   ctrl: boolean;
-  /** Whether the Shift key is required */
+  /** Whether Shift is required. */
   shift: boolean;
-  /** Whether the Alt key is required */
+  /** Whether Alt is required. */
   alt: boolean;
-  /** Whether the Meta (Command) key is required */
+  /** Whether Meta (Command) is required. */
   meta: boolean;
-  /** List of canonical modifier names that are required, in canonical order */
+  /** Required modifiers in canonical order. */
   modifiers: Array<CanonicalModifier>;
 }
+/**
+ * A parsed binding matches either a logical key or a physical code, never both.
+ * Check `code !== undefined` to narrow to a physical binding. Its logical
+ * character is unknown without a keyboard event and is not stored in `key`.
+ *
+ * @example
+ * parseHotkey('Alt+S') // { key: 'S', alt: true, ... }
+ * parseHotkey('Alt+[KeyS]') // { code: 'KeyS', alt: true, ... } — no key property
+ */
+export type ParsedHotkey = ParsedModifiers & ({
+  key: LogicalKey | (string & {});
+  code?: never;
+} | {
+  code: string;
+  key?: never;
+});
 /**
  * A raw hotkey object for programmatic registration.
  *
@@ -209,11 +145,13 @@ interface ParsedHotkey {
  * useHotkey({ key: 'Escape' }, handler)                   // Escape (no modifiers)
  * useHotkey({ key: 'A', shift: true, meta: true }, handler) // Shift+Meta+A
  * useHotkey({ key: 'S', mod: true, shift: true }, handler)  // Mod+Shift+S
+ * useHotkey({ code: 'KeyW', mod: true }, handler)           // Physical Mod+KeyW
+ * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
  * ```
  */
-interface RawHotkey {
+/** Modifier flags shared by logical-key and physical-code registrations. */
+export interface RawModifiers {
   /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
-  key: Key | (string & {});
   /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
   mod?: boolean;
   /** Whether the Control key is required. Defaults to false. */
@@ -225,37 +163,22 @@ interface RawHotkey {
   /** Whether the Meta (Command) key is required. Defaults to false. */
   meta?: boolean;
 }
+export type RawHotkey = ({
+  key: LogicalKey | (string & {});
+  code?: never;
+} & RawModifiers) | ({
+  code: string;
+  key?: never;
+} & RawModifiers);
 /**
  * A hotkey that can be passed to `HotkeyManager.register()` and `useHotkey()`.
  * Either a type-safe string (`Hotkey`) or a raw object (`RawHotkey`).
  */
-type RegisterableHotkey = Hotkey | RawHotkey;
-/**
- * Options for formatting hotkeys for display.
- */
-interface FormatDisplayOptions {
-  /** The target platform. Defaults to auto-detection. */
-  platform?: 'mac' | 'windows' | 'linux';
-  /** Whether to use symbols for the display. Defaults to true. */
-  useSymbols?: boolean;
-  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
-  separatorToken?: string | null;
-}
-/**
- * Result of validating a hotkey string.
- */
-interface ValidationResult {
-  /** Whether the hotkey is valid (can still have warnings) */
-  valid: boolean;
-  /** Warning messages about potential issues */
-  warnings: Array<string>;
-  /** Error messages about invalid syntax */
-  errors: Array<string>;
-}
+export type RegisterableHotkey = Hotkey | RawHotkey;
 /**
  * Context passed to hotkey callbacks along with the keyboard event.
  */
-interface HotkeyCallbackContext {
+export interface HotkeyCallbackContext {
   /** The original hotkey string that was registered */
   hotkey: Hotkey;
   /** The parsed representation of the hotkey */
@@ -275,10 +198,10 @@ interface HotkeyCallbackContext {
  * }
  * ```
  */
-type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
+export type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
 /**
  * Metadata for hotkey and sequence registrations.
- * Includes `name` and `description` by default. Extend via declaration merging:
+ * Includes `name`, `description`, and `group` by default. Extend via declaration merging:
  *
  * @example
  * ```ts
@@ -290,12 +213,21 @@ type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) =>
  * }
  * ```
  */
-interface HotkeyMeta {
+export interface HotkeyMeta {
   /** Human-readable name for this hotkey (e.g., "Save Document") */
   name?: string;
   /** Description of what this hotkey does */
   description?: string;
+  /** Optional display group. Does not affect matching or scope. */
+  group?: string;
 }
-//#endregion
-export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
-//# sourceMappingURL=hotkey.d.ts.map
+/**
+ * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
+ *
+ * - `'warn'` - Log a warning to the console but allow both registrations (default)
+ * - `'error'` - Throw an error and prevent the new registration
+ * - `'replace'` - Unregister the existing registration and register the new one
+ * - `'allow'` - Allow multiple registrations without warning
+ */
+export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
+//#endregion

package/dist/index.d.ts

@@ -1,13 +1,18 @@
-import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, 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, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
-import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
-import { ConflictBehavior } from "./manager.utils.js";
+import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
+import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
+import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
+import { detectPlatform, resolveModifier } from "./platform.js";
+import { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey } from "./hotkey.types.js";
+import { DisplayHotkey, FormatDisplayOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
+import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
+import { ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
+import { CreateHotkeyHandlerOptions, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, Target, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
+import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
-import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { HotkeyRecorderValidationContext, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.js";
 import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./hotkey-recorder.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
 import { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState } from "./hotkey-sequence-recorder.js";
-import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, WINDOWS_MODIFIER_LABELS, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, DisplayHotkey, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkey, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, HotkeySequenceRecorderValidationContext, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkey, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, SingleModifierHotkey, Target, ThreeModifierHotkey, TwoModifierHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };

package/dist/index.js

@@ -1,12 +1,16 @@
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
+import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
+import { detectPlatform, resolveModifier } from "./platform.js";
+import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
 import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
-import { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
+import { areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
+import { findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorder } from "./hotkey-recorder.js";
 import { HotkeySequenceRecorder } from "./hotkey-sequence-recorder.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
-import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
 
-export { ALL_KEYS, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, HotkeySequenceRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, SequenceManager, WINDOWS_MODIFIER_LABELS, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, HotkeySequenceRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, SequenceManager, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };

package/dist/key-state-tracker.d.ts

@@ -1,10 +1,9 @@
 import { Store } from "@tanstack/store";
-
 //#region src/key-state-tracker.d.ts
 /**
  * State interface for the KeyStateTracker.
  */
-interface KeyStateTrackerState {
+export interface KeyStateTrackerState {
   /**
    * Array of currently held key names (normalized, e.g. "Control", "A").
    */
@@ -49,7 +48,7 @@ interface KeyStateTrackerState {
  * unsubscribe()
  * ```
  */
-declare class KeyStateTracker {
+export declare class KeyStateTracker {
   #private;
   /**
    * The TanStack Store instance containing the tracker state.
@@ -101,7 +100,5 @@ declare class KeyStateTracker {
  * Gets the singleton KeyStateTracker instance.
  * Convenience function for accessing the tracker.
  */
-declare function getKeyStateTracker(): KeyStateTracker;
-//#endregion
-export { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker };
-//# sourceMappingURL=key-state-tracker.d.ts.map
+export declare function getKeyStateTracker(): KeyStateTracker;
+//#endregion

package/dist/key-state-tracker.js

@@ -47,13 +47,16 @@ function getDefaultKeyStateTrackerState() {
 */
 var KeyStateTracker = class KeyStateTracker {
 	static #instance = null;
-	#heldKeysSet = /* @__PURE__ */ new Set();
-	#heldCodesMap = /* @__PURE__ */ new Map();
+	/**
+	* The TanStack Store instance containing the tracker state.
+	* Use this to subscribe to state changes or access current state.
+	*/
+	store = new Store(getDefaultKeyStateTrackerState());
+	#heldEntries = /* @__PURE__ */ new Map();
 	#keydownListener = null;
 	#keyupListener = null;
 	#blurListener = null;
 	constructor() {
-		this.store = new Store(getDefaultKeyStateTrackerState());
 		this.#setupListeners();
 	}
 	/**
@@ -79,44 +82,46 @@ var KeyStateTracker = class KeyStateTracker {
 		if (typeof document === "undefined") return;
 		this.#keydownListener = (event) => {
 			const key = normalizeKeyName(event.key);
-			if (!this.#heldKeysSet.has(key)) {
-				this.#heldKeysSet.add(key);
-				this.#heldCodesMap.set(key, event.code);
+			const identity = event.code || `key:${key}`;
+			if (!this.#heldEntries.has(identity)) {
+				this.#heldEntries.set(identity, {
+					key,
+					code: event.code
+				});
 				this.#syncState();
 			}
 		};
 		this.#keyupListener = (event) => {
 			const key = normalizeKeyName(event.key);
-			if (this.#heldKeysSet.has(key)) {
-				this.#heldKeysSet.delete(key);
-				this.#heldCodesMap.delete(key);
+			const identity = event.code || `key:${key}`;
+			this.#heldEntries.delete(identity);
+			if (!event.code) {
+				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
 			if (MODIFIER_KEYS.has(key)) {
-				for (const heldKey of this.#heldKeysSet) if (!MODIFIER_KEYS.has(heldKey)) {
-					this.#heldKeysSet.delete(heldKey);
-					this.#heldCodesMap.delete(heldKey);
-				}
+				for (const [entryIdentity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#syncState();
 		};
 		this.#blurListener = () => {
-			if (this.#heldKeysSet.size > 0) {
-				this.#heldKeysSet.clear();
-				this.#heldCodesMap.clear();
+			if (this.#heldEntries.size > 0) {
+				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		document.addEventListener("keydown", this.#keydownListener);
-		document.addEventListener("keyup", this.#keyupListener);
+		document.addEventListener("keydown", this.#keydownListener, true);
+		document.addEventListener("keyup", this.#keyupListener, true);
 		window.addEventListener("blur", this.#blurListener);
 	}
 	/**
 	* Syncs the internal Set to the Store state.
 	*/
 	#syncState() {
+		const heldKeys = Array.from(new Set(Array.from(this.#heldEntries.values(), (entry) => entry.key)));
+		const heldCodes = Object.fromEntries(Array.from(this.#heldEntries.values(), (entry) => [entry.key, entry.code]));
 		this.store.setState(() => ({
-			heldKeys: Array.from(this.#heldKeysSet),
-			heldCodes: Object.fromEntries(this.#heldCodesMap)
+			heldKeys,
+			heldCodes
 		}));
 	}
 	/**
@@ -125,11 +130,11 @@ var KeyStateTracker = class KeyStateTracker {
 	#removeListeners() {
 		if (typeof document === "undefined") return;
 		if (this.#keydownListener) {
-			document.removeEventListener("keydown", this.#keydownListener);
+			document.removeEventListener("keydown", this.#keydownListener, true);
 			this.#keydownListener = null;
 		}
 		if (this.#keyupListener) {
-			document.removeEventListener("keyup", this.#keyupListener);
+			document.removeEventListener("keyup", this.#keyupListener, true);
 			this.#keyupListener = null;
 		}
 		if (this.#blurListener) {
@@ -153,7 +158,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	isKeyHeld(key) {
 		const normalizedKey = normalizeKeyName(key);
-		return this.#heldKeysSet.has(normalizedKey);
+		return Array.from(this.#heldEntries.values()).some((entry) => entry.key === normalizedKey);
 	}
 	/**
 	* Checks if any of the given keys are currently held.
@@ -178,8 +183,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	destroy() {
 		this.#removeListeners();
-		this.#heldKeysSet.clear();
-		this.#heldCodesMap.clear();
+		this.#heldEntries.clear();
 		this.store.setState(() => getDefaultKeyStateTrackerState());
 	}
 };
@@ -192,5 +196,4 @@ function getKeyStateTracker() {
 }
 
 //#endregion
-export { KeyStateTracker, getKeyStateTracker };
-//# sourceMappingURL=key-state-tracker.js.map
+export { KeyStateTracker, getKeyStateTracker };

package/dist/key.types.d.ts

@@ -0,0 +1,79 @@
+import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.js";
+//#region src/key.types.d.ts
+/**
+ * All supported modifier key names, including aliases.
+ * - Control/Ctrl: The Control key
+ * - Shift: The Shift key
+ * - Alt/Option: The Alt key (Option on macOS)
+ * - Command/Cmd: The Command key (macOS only)
+ * - CommandOrControl/Mod: Command on macOS, Control on other platforms
+ */
+export type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
+/**
+ * Canonical modifier names that map to KeyboardEvent properties.
+ */
+export type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
+/**
+ * Letter keys A-Z (case-insensitive in matching).
+ */
+export type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+/**
+ * Number keys 0-9.
+ */
+export type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/**
+ * Function keys F1-F24, supported as both logical keys and physical codes.
+ */
+export type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24';
+/**
+ * Navigation keys for cursor movement.
+ */
+export type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
+/**
+ * Editing and special keys.
+ */
+export type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
+/**
+ * Printable punctuation glyphs used in keyboard shortcuts. Matching uses the
+ * final KeyboardEvent.key glyph, independent of which layout produced it.
+ */
+export type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`' | "'" | '+' | '?' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '_' | '{' | '}' | '|' | ':' | '"' | '<' | '>' | '~';
+/** Additional named logical keys, including media, browser, lock, and input-mode keys. */
+export type NamedKey = (typeof SHARED_NAMED_KEYS)[number] | (typeof LOGICAL_ONLY_NAMED_KEYS)[number];
+/** Supported logical key names other than printable punctuation. */
+export type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey | NamedKey;
+/**
+ * Supported physical KeyboardEvent.code names, independent of keyboard layout.
+ * Letter, digit, numpad, and sided modifier names use finite template unions.
+ * `Unidentified` is excluded because it cannot identify a physical key.
+ *
+ * @see https://www.w3.org/TR/uievents-code/
+ */
+export type PhysicalKeyCode = `Key${LetterKey}` | `Digit${NumberKey}` | `Numpad${NumberKey}` | `${'Alt' | 'Control' | 'Meta' | 'Shift'}${'Left' | 'Right'}` | EditingKey | NavigationKey | FunctionKey | (typeof SHARED_NAMED_KEYS)[number] | 'Backquote' | 'Backslash' | 'BracketLeft' | 'BracketRight' | 'Comma' | 'Equal' | 'IntlBackslash' | 'IntlRo' | 'IntlYen' | 'Minus' | 'Period' | 'Quote' | 'Semicolon' | 'Slash' | `Lang${1 | 2 | 3 | 4 | 5}` | `Numpad${'Add' | 'Backspace' | 'Clear' | 'ClearEntry' | 'Comma' | 'Decimal' | 'Divide' | 'Enter' | 'Equal' | 'Hash' | 'MemoryAdd' | 'MemoryClear' | 'MemoryRecall' | 'MemoryStore' | 'MemorySubtract' | 'Multiply' | 'ParenLeft' | 'ParenRight' | 'Star' | 'Subtract'}` | 'LaunchApp1' | 'LaunchApp2' | 'MediaSelect' | 'Sleep' | 'Turbo' | 'Abort' | 'Resume' | 'Suspend';
+/**
+ * An explicit physical key token. All codes use brackets, including names such
+ * as `[Enter]` that also exist as logical keys. Invalid code names are rejected
+ * by TypeScript, and supported names are available in autocomplete.
+ */
+export type PhysicalKey = `[${PhysicalKeyCode}]`;
+/** Supported logical key names, excluding bracketed physical-code syntax. */
+export type LogicalKey = NonPunctuationKey | PunctuationKey;
+/** All supported logical keys and bracketed physical key tokens. */
+export type Key = LogicalKey | PhysicalKey;
+/**
+ * Includes both modifier keys and regular keys.
+ */
+export type IndividualKey = CanonicalModifier | Key;
+/** Keyboard event properties normalized for internal matching and recording. */
+export interface NormalizedKeyboardEvent {
+  key: string;
+  code: string;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+  meta: boolean;
+  altGraph: boolean;
+  location: number;
+  isComposing: boolean;
+}
+//#endregion

package/dist/match.d.ts

@@ -1,10 +1,19 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.js";
-
+import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 //#region src/match.d.ts
+export interface KeyboardEventMatch {
+  matched: boolean;
+  score: 0 | 1 | 2 | 3;
+  source?: 'key' | 'code' | 'fallback';
+  identity?: {
+    key: string;
+    code: string;
+  };
+}
 /**
  * Checks if a KeyboardEvent matches a hotkey.
  *
- * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+ * Logical bindings use `event.key`, with a fallback to `code`
  * 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.
@@ -29,11 +38,11 @@ import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.js";
  * })
  * ```
  */
-declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: Hotkey | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
+export declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: Hotkey | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
 /**
  * Options for creating a hotkey handler.
  */
-interface CreateHotkeyHandlerOptions {
+export interface CreateHotkeyHandlerOptions {
   /** Prevent the default browser action when the hotkey matches. Defaults to true */
   preventDefault?: boolean;
   /** Stop event propagation when the hotkey matches. Defaults to true */
@@ -59,8 +68,8 @@ interface CreateHotkeyHandlerOptions {
  * document.addEventListener('keydown', handler)
  * ```
  */
-declare function createHotkeyHandler(hotkey: Hotkey | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
-type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
+export declare function createHotkeyHandler(hotkey: Hotkey | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+export type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback; };
 /**
  * Creates a handler that matches multiple hotkeys.
  *
@@ -79,7 +88,11 @@ type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
  * document.addEventListener('keydown', handler)
  * ```
  */
-declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
-//#endregion
-export { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
-//# sourceMappingURL=match.d.ts.map
+export declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+/**
+ * Compares normalized binding identity, including all four modifiers.
+ * Aliases resolve on the supplied platform. A physical code and a logical key
+ * remain distinct even when one keyboard event could match both.
+ */
+export declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): boolean;
+//#endregion