@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/hotkey.d.cts

@@ -0,0 +1,278 @@
+//#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;
+/**
+ * Keys that can be tracked as "held" (pressed down).
+ * Includes both modifier keys and regular keys.
+ */
+type HeldKey = CanonicalModifier | Key;
+/**
+ * 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 ⌘)
+ * - **Windows/Linux**: Resolves to `Control` (Ctrl 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}`;
+/**
+ * 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)
+ * - `Mod+Control` and `Mod+Meta` are excluded because they create duplicate modifiers:
+ *   - `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}`;
+/**
+ * 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)
+ * - `Mod+Control+Shift` and `Mod+Shift+Meta` are excluded because they create duplicate modifiers:
+ *   - `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}`;
+/**
+ * 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.
+ *
+ * **Why no `Mod` combinations?**
+ * Since `Mod` resolves to either `Control` (Windows/Linux) or `Meta` (macOS), any
+ * four-modifier combination with `Mod` would create duplicate modifiers on one platform.
+ * For example:
+ * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
+ * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
+ */
+type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
+/**
+ * A type-safe hotkey string.
+ *
+ * Provides autocomplete for:
+ * - All single keys (letters, numbers, function keys, navigation, editing, punctuation)
+ * - Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
+ * - Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
+ * - Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
+ * - Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)
+ *
+ * ## Modifier Names
+ *
+ * Use canonical modifier names:
+ * - `Control` (not Ctrl) - The Control key
+ * - `Alt` (not Option) - The Alt key (Option on macOS)
+ * - `Meta` (not Command/Cmd) - The Meta/Command key (macOS only)
+ * - `Shift` - The Shift key
+ *
+ * ## Platform-Adaptive `Mod` Modifier
+ *
+ * The `Mod` modifier is a special platform-adaptive modifier that automatically resolves
+ * to the "primary modifier" on each platform:
+ *
+ * - **macOS**: `Mod` → `Meta` (Command key ⌘)
+ * - **Windows/Linux**: `Mod` → `Control` (Ctrl key)
+ *
+ * This enables cross-platform hotkey definitions that work correctly on all platforms
+ * without platform-specific code. The `Mod` modifier is resolved at runtime based on
+ * the detected platform.
+ *
+ * **When to use `Mod` vs platform-specific modifiers:**
+ * - Use `Mod` for cross-platform shortcuts (e.g., `Mod+S` for save)
+ * - Use `Meta` or `Control` when you need platform-specific behavior
+ * - Use `Mod` when you want your shortcuts to follow platform conventions automatically
+ *
+ * **Limitations:**
+ * - `Mod+Control` and `Mod+Meta` combinations are not allowed (they create duplicate
+ *   modifiers on one platform)
+ * - In four-modifier combinations, only canonical modifiers are allowed (no `Mod`)
+ *
+ * @example
+ * ```ts
+ * // Cross-platform shortcuts (recommended)
+ * const save: Hotkey = 'Mod+S'           // Command+S on Mac, Ctrl+S on Windows/Linux
+ * const saveAs: Hotkey = 'Mod+Shift+S'   // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
+ * const comment: Hotkey = 'Mod+/'       // Command+/ on Mac, Ctrl+/ elsewhere
+ *
+ * // Platform-specific shortcuts
+ * const macOnly: Hotkey = 'Meta+S'       // Command+S on Mac only
+ * 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 */
+  ctrl: boolean;
+  /** Whether the Shift key is required */
+  shift: boolean;
+  /** Whether the Alt key is required */
+  alt: boolean;
+  /** Whether the Meta (Command) key is required */
+  meta: boolean;
+  /** List of canonical modifier names that are required, in canonical order */
+  modifiers: Array<CanonicalModifier>;
+}
+/**
+ * A raw hotkey object for programmatic registration.
+ *
+ * Like `ParsedHotkey` but without `modifiers` (derived from booleans)
+ * and with optional modifier booleans (default to `false` when omitted).
+ * Use with `HotkeyManager.register()` and `useHotkey()` when you prefer
+ * object form over a string.
+ *
+ * The `mod` modifier is platform-adaptive: Command on macOS, Control on Windows/Linux.
+ * Pass `platform` when converting to ParsedHotkey (e.g., via `options.platform`).
+ *
+ * @example
+ * ```ts
+ * useHotkey({ key: 'S', mod: true }, handler)             // Mod+S (cross-platform)
+ * useHotkey({ key: 'S', ctrl: true }, handler)            // Control+S
+ * 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
+ * ```
+ */
+interface RawHotkey {
+  /** 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. */
+  ctrl?: boolean;
+  /** Whether the Shift key is required. Defaults to false. */
+  shift?: boolean;
+  /** Whether the Alt key is required. Defaults to false. */
+  alt?: boolean;
+  /** Whether the Meta (Command) key is required. Defaults to false. */
+  meta?: boolean;
+}
+/**
+ * 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';
+}
+/**
+ * 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>;
+}
+/**
+ * Context passed to hotkey callbacks along with the keyboard event.
+ */
+interface HotkeyCallbackContext {
+  /** The original hotkey string that was registered */
+  hotkey: Hotkey;
+  /** The parsed representation of the hotkey */
+  parsedHotkey: ParsedHotkey;
+}
+/**
+ * Callback function type for hotkey handlers.
+ *
+ * @param event - The keyboard event that triggered the hotkey
+ * @param context - Additional context including the hotkey and parsed hotkey
+ *
+ * @example
+ * ```ts
+ * const handler: HotkeyCallback = (event, { hotkey, parsedHotkey }) => {
+ *   console.log(`Hotkey ${hotkey} was pressed`)
+ *   console.log(`Modifiers:`, parsedHotkey.modifiers)
+ * }
+ * ```
+ */
+type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
+//#endregion
+export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
+//# sourceMappingURL=hotkey.d.cts.map

package/dist/hotkey.d.ts

@@ -0,0 +1,278 @@
+//#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;
+/**
+ * Keys that can be tracked as "held" (pressed down).
+ * Includes both modifier keys and regular keys.
+ */
+type HeldKey = CanonicalModifier | Key;
+/**
+ * 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 ⌘)
+ * - **Windows/Linux**: Resolves to `Control` (Ctrl 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}`;
+/**
+ * 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)
+ * - `Mod+Control` and `Mod+Meta` are excluded because they create duplicate modifiers:
+ *   - `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}`;
+/**
+ * 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)
+ * - `Mod+Control+Shift` and `Mod+Shift+Meta` are excluded because they create duplicate modifiers:
+ *   - `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}`;
+/**
+ * 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.
+ *
+ * **Why no `Mod` combinations?**
+ * Since `Mod` resolves to either `Control` (Windows/Linux) or `Meta` (macOS), any
+ * four-modifier combination with `Mod` would create duplicate modifiers on one platform.
+ * For example:
+ * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
+ * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
+ */
+type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
+/**
+ * A type-safe hotkey string.
+ *
+ * Provides autocomplete for:
+ * - All single keys (letters, numbers, function keys, navigation, editing, punctuation)
+ * - Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
+ * - Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
+ * - Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
+ * - Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)
+ *
+ * ## Modifier Names
+ *
+ * Use canonical modifier names:
+ * - `Control` (not Ctrl) - The Control key
+ * - `Alt` (not Option) - The Alt key (Option on macOS)
+ * - `Meta` (not Command/Cmd) - The Meta/Command key (macOS only)
+ * - `Shift` - The Shift key
+ *
+ * ## Platform-Adaptive `Mod` Modifier
+ *
+ * The `Mod` modifier is a special platform-adaptive modifier that automatically resolves
+ * to the "primary modifier" on each platform:
+ *
+ * - **macOS**: `Mod` → `Meta` (Command key ⌘)
+ * - **Windows/Linux**: `Mod` → `Control` (Ctrl key)
+ *
+ * This enables cross-platform hotkey definitions that work correctly on all platforms
+ * without platform-specific code. The `Mod` modifier is resolved at runtime based on
+ * the detected platform.
+ *
+ * **When to use `Mod` vs platform-specific modifiers:**
+ * - Use `Mod` for cross-platform shortcuts (e.g., `Mod+S` for save)
+ * - Use `Meta` or `Control` when you need platform-specific behavior
+ * - Use `Mod` when you want your shortcuts to follow platform conventions automatically
+ *
+ * **Limitations:**
+ * - `Mod+Control` and `Mod+Meta` combinations are not allowed (they create duplicate
+ *   modifiers on one platform)
+ * - In four-modifier combinations, only canonical modifiers are allowed (no `Mod`)
+ *
+ * @example
+ * ```ts
+ * // Cross-platform shortcuts (recommended)
+ * const save: Hotkey = 'Mod+S'           // Command+S on Mac, Ctrl+S on Windows/Linux
+ * const saveAs: Hotkey = 'Mod+Shift+S'   // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
+ * const comment: Hotkey = 'Mod+/'       // Command+/ on Mac, Ctrl+/ elsewhere
+ *
+ * // Platform-specific shortcuts
+ * const macOnly: Hotkey = 'Meta+S'       // Command+S on Mac only
+ * 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 */
+  ctrl: boolean;
+  /** Whether the Shift key is required */
+  shift: boolean;
+  /** Whether the Alt key is required */
+  alt: boolean;
+  /** Whether the Meta (Command) key is required */
+  meta: boolean;
+  /** List of canonical modifier names that are required, in canonical order */
+  modifiers: Array<CanonicalModifier>;
+}
+/**
+ * A raw hotkey object for programmatic registration.
+ *
+ * Like `ParsedHotkey` but without `modifiers` (derived from booleans)
+ * and with optional modifier booleans (default to `false` when omitted).
+ * Use with `HotkeyManager.register()` and `useHotkey()` when you prefer
+ * object form over a string.
+ *
+ * The `mod` modifier is platform-adaptive: Command on macOS, Control on Windows/Linux.
+ * Pass `platform` when converting to ParsedHotkey (e.g., via `options.platform`).
+ *
+ * @example
+ * ```ts
+ * useHotkey({ key: 'S', mod: true }, handler)             // Mod+S (cross-platform)
+ * useHotkey({ key: 'S', ctrl: true }, handler)            // Control+S
+ * 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
+ * ```
+ */
+interface RawHotkey {
+  /** 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. */
+  ctrl?: boolean;
+  /** Whether the Shift key is required. Defaults to false. */
+  shift?: boolean;
+  /** Whether the Alt key is required. Defaults to false. */
+  alt?: boolean;
+  /** Whether the Meta (Command) key is required. Defaults to false. */
+  meta?: boolean;
+}
+/**
+ * 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';
+}
+/**
+ * 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>;
+}
+/**
+ * Context passed to hotkey callbacks along with the keyboard event.
+ */
+interface HotkeyCallbackContext {
+  /** The original hotkey string that was registered */
+  hotkey: Hotkey;
+  /** The parsed representation of the hotkey */
+  parsedHotkey: ParsedHotkey;
+}
+/**
+ * Callback function type for hotkey handlers.
+ *
+ * @param event - The keyboard event that triggered the hotkey
+ * @param context - Additional context including the hotkey and parsed hotkey
+ *
+ * @example
+ * ```ts
+ * const handler: HotkeyCallback = (event, { hotkey, parsedHotkey }) => {
+ *   console.log(`Hotkey ${hotkey} was pressed`)
+ *   console.log(`Modifiers:`, parsedHotkey.modifiers)
+ * }
+ * ```
+ */
+type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
+//#endregion
+export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
+//# sourceMappingURL=hotkey.d.ts.map

package/dist/index.cjs

@@ -0,0 +1,54 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_constants = require('./constants.cjs');
+const require_parse = require('./parse.cjs');
+const require_format = require('./format.cjs');
+const require_match = require('./match.cjs');
+const require_hotkey_manager = require('./hotkey-manager.cjs');
+const require_key_state_tracker = require('./key-state-tracker.cjs');
+const require_recorder = require('./recorder.cjs');
+const require_sequence = require('./sequence.cjs');
+const require_validate = require('./validate.cjs');
+
+exports.ALL_KEYS = require_constants.ALL_KEYS;
+exports.EDITING_KEYS = require_constants.EDITING_KEYS;
+exports.FUNCTION_KEYS = require_constants.FUNCTION_KEYS;
+exports.HotkeyManager = require_hotkey_manager.HotkeyManager;
+exports.HotkeyRecorder = require_recorder.HotkeyRecorder;
+exports.KEY_DISPLAY_SYMBOLS = require_constants.KEY_DISPLAY_SYMBOLS;
+exports.KeyStateTracker = require_key_state_tracker.KeyStateTracker;
+exports.LETTER_KEYS = require_constants.LETTER_KEYS;
+exports.MAC_MODIFIER_SYMBOLS = require_constants.MAC_MODIFIER_SYMBOLS;
+exports.MODIFIER_ALIASES = require_constants.MODIFIER_ALIASES;
+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_KEYS = require_constants.PUNCTUATION_KEYS;
+exports.STANDARD_MODIFIER_LABELS = require_constants.STANDARD_MODIFIER_LABELS;
+exports.SequenceManager = require_sequence.SequenceManager;
+exports.assertValidHotkey = require_validate.assertValidHotkey;
+exports.checkHotkey = require_validate.checkHotkey;
+exports.convertToModFormat = require_parse.convertToModFormat;
+exports.createHotkeyHandler = require_match.createHotkeyHandler;
+exports.createMultiHotkeyHandler = require_match.createMultiHotkeyHandler;
+exports.createSequenceMatcher = require_sequence.createSequenceMatcher;
+exports.detectPlatform = require_constants.detectPlatform;
+exports.formatForDisplay = require_format.formatForDisplay;
+exports.formatHotkey = require_format.formatHotkey;
+exports.formatKeyForDebuggingDisplay = require_format.formatKeyForDebuggingDisplay;
+exports.formatWithLabels = require_format.formatWithLabels;
+exports.getHotkeyManager = require_hotkey_manager.getHotkeyManager;
+exports.getKeyStateTracker = require_key_state_tracker.getKeyStateTracker;
+exports.getSequenceManager = require_sequence.getSequenceManager;
+exports.hasNonModifierKey = require_parse.hasNonModifierKey;
+exports.isModifier = require_parse.isModifier;
+exports.isModifierKey = require_parse.isModifierKey;
+exports.keyboardEventToHotkey = require_parse.keyboardEventToHotkey;
+exports.matchesKeyboardEvent = require_match.matchesKeyboardEvent;
+exports.normalizeHotkey = require_parse.normalizeHotkey;
+exports.normalizeKeyName = require_constants.normalizeKeyName;
+exports.parseHotkey = require_parse.parseHotkey;
+exports.parseKeyboardEvent = require_parse.parseKeyboardEvent;
+exports.rawHotkeyToParsedHotkey = require_parse.rawHotkeyToParsedHotkey;
+exports.resolveModifier = require_constants.resolveModifier;
+exports.validateHotkey = require_validate.validateHotkey;

package/dist/index.d.cts

@@ -0,0 +1,11 @@
+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, normalizeKeyName, resolveModifier } from "./constants.cjs";
+import { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.cjs";
+import { ConflictBehavior, HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager } from "./hotkey-manager.cjs";
+import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.cjs";
+import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.cjs";
+import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.cjs";
+import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./recorder.cjs";
+import { HotkeySequence, SequenceManager, SequenceOptions, createSequenceMatcher, getSequenceManager } from "./sequence.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, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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, normalizeKeyName, resolveModifier } from "./constants.js";
+import { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.js";
+import { ConflictBehavior, HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager } from "./hotkey-manager.js";
+import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
+import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./recorder.js";
+import { HotkeySequence, SequenceManager, SequenceOptions, createSequenceMatcher, getSequenceManager } from "./sequence.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, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };

package/dist/index.js

@@ -0,0 +1,11 @@
+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, normalizeKeyName, resolveModifier } from "./constants.js";
+import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.js";
+import { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { HotkeyManager, getHotkeyManager } from "./hotkey-manager.js";
+import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
+import { HotkeyRecorder } from "./recorder.js";
+import { SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence.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, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };