@tanstack/hotkeys 0.7.1 → 0.9.0

package/src/{hotkey.ts → hotkey.types.ts}

@@ -1,157 +1,4 @@
-/**
- * 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-F12.
- */
-export type FunctionKey =
-  | 'F1'
-  | 'F2'
-  | 'F3'
-  | 'F4'
-  | 'F5'
-  | 'F6'
-  | 'F7'
-  | 'F8'
-  | 'F9'
-  | 'F10'
-  | 'F11'
-  | 'F12'
-
-/**
- * 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'
-
-/**
- * Punctuation keys commonly used in keyboard shortcuts.
- * These are the literal characters as they appear in KeyboardEvent.key
- * (layout-dependent, typically US keyboard layout).
- */
-export 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.
- */
-export type Key = NonPunctuationKey | PunctuationKey
-
-/**
- * Includes both modifier keys and regular keys.
- */
-export type IndividualKey = CanonicalModifier | Key
+import type { CanonicalModifier, Key, LogicalKey } from './key.types'
 
 // =============================================================================
 // Hotkey Types
@@ -160,7 +7,6 @@ export type IndividualKey = 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 ⌘)
@@ -169,16 +15,15 @@ export 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 =
+export type SingleModifierHotkey =
   | `Control+${Key}`
   | `Alt+${Key}`
-  | `Shift+${NonPunctuationKey}`
+  | `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)
@@ -186,19 +31,18 @@ type SingleModifierHotkey =
  *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type TwoModifierHotkey =
+export type TwoModifierHotkey =
   | `Control+Alt+${Key}`
-  | `Control+Shift+${NonPunctuationKey}`
+  | `Control+Shift+${Key}`
   | `Control+Meta+${Key}`
-  | `Alt+Shift+${NonPunctuationKey}`
+  | `Alt+Shift+${Key}`
   | `Alt+Meta+${Key}`
-  | `Shift+Meta+${NonPunctuationKey}`
+  | `Shift+Meta+${Key}`
   | `Mod+Alt+${Key}`
-  | `Mod+Shift+${NonPunctuationKey}`
+  | `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)
@@ -206,16 +50,15 @@ type TwoModifierHotkey =
  *   - `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}`
+export type ThreeModifierHotkey =
+  | `Control+Alt+Shift+${Key}`
   | `Control+Alt+Meta+${Key}`
-  | `Control+Shift+Meta+${NonPunctuationKey}`
-  | `Alt+Shift+Meta+${NonPunctuationKey}`
-  | `Mod+Alt+Shift+${NonPunctuationKey}`
+  | `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.
  *
@@ -226,7 +69,7 @@ type ThreeModifierHotkey =
  * - `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.
@@ -287,39 +130,35 @@ export type Hotkey =
   | 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
- * ```
- */
-export 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 */
+/** 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.
  *
@@ -338,11 +177,13 @@ export 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
  * ```
  */
-export 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. */
@@ -355,36 +196,16 @@ export interface RawHotkey {
   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`).
  */
 export type RegisterableHotkey = Hotkey | RawHotkey
 
-/**
- * Options for formatting hotkeys for display.
- */
-export 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.
- */
-export 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.
  */
@@ -416,7 +237,7 @@ export type HotkeyCallback = (
 
 /**
  * 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
@@ -433,4 +254,16 @@ export interface HotkeyMeta {
   name?: string
   /** Description of what this hotkey does */
   description?: string
+  /** Optional display group. Does not affect matching or scope. */
+  group?: string
 }
+
+/**
+ * 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'

package/src/index.ts

@@ -1,11 +1,17 @@
 export * from './constants'
+export * from './display-labels'
+export * from './platform'
+export * from './key.types'
+export * from './hotkey.types'
 export * from './format'
-export * from './hotkey'
+export * from './parse'
+export * from './validate'
+export * from './match'
+export * from './hint'
+export * from './conflicts'
 export * from './hotkey-manager'
+export * from './sequence-manager'
 export * from './key-state-tracker'
-export * from './match'
-export * from './parse'
+export * from './recorder-options'
 export * from './hotkey-recorder'
 export * from './hotkey-sequence-recorder'
-export * from './sequence-manager'
-export * from './validate'

package/src/key-state-tracker.ts

@@ -71,8 +71,7 @@ export class KeyStateTracker {
     getDefaultKeyStateTrackerState(),
   )
 
-  #heldKeysSet: Set<string> = new Set()
-  #heldCodesMap: Map<string, string> = new Map()
+  #heldEntries: Map<string, { key: string; code: string }> = new Map()
   #keydownListener: ((event: KeyboardEvent) => void) | null = null
   #keyupListener: ((event: KeyboardEvent) => void) | null = null
   #blurListener: (() => void) | null = null
@@ -111,18 +110,23 @@ export class KeyStateTracker {
 
     this.#keydownListener = (event: KeyboardEvent) => {
       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: KeyboardEvent) => {
       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)
+
+      // Code-less keyup events can only be paired by their logical key.
+      if (!event.code) {
+        for (const [entryIdentity, entry] of this.#heldEntries) {
+          if (entry.key === key) this.#heldEntries.delete(entryIdentity)
+        }
       }
 
       // When a modifier key is released, clear any non-modifier keys still
@@ -130,10 +134,9 @@ export class KeyStateTracker {
       // (e.g. Cmd+S) and swallows the keyup event for the non-modifier key,
       // leaving it permanently stuck in the held set.
       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)
           }
         }
       }
@@ -143,15 +146,14 @@ export class KeyStateTracker {
 
     // Clear all keys when window loses focus (keys might be released while not focused)
     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)
   }
 
@@ -159,9 +161,18 @@ export class KeyStateTracker {
    * Syncs the internal Set to the Store state.
    */
   #syncState(): void {
+    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,
     }))
   }
 
@@ -174,12 +185,12 @@ export class KeyStateTracker {
     }
 
     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
     }
 
@@ -206,7 +217,9 @@ export class KeyStateTracker {
    */
   isKeyHeld(key: string): boolean {
     const normalizedKey = normalizeKeyName(key)
-    return this.#heldKeysSet.has(normalizedKey)
+    return Array.from(this.#heldEntries.values()).some(
+      (entry) => entry.key === normalizedKey,
+    )
   }
 
   /**
@@ -234,8 +247,7 @@ export class KeyStateTracker {
    */
   destroy(): void {
     this.#removeListeners()
-    this.#heldKeysSet.clear()
-    this.#heldCodesMap.clear()
+    this.#heldEntries.clear()
     this.store.setState(() => getDefaultKeyStateTrackerState())
   }
 }