@tanstack/hotkeys 0.0.1 → 0.1.0

package/src/hotkey.ts

@@ -0,0 +1,411 @@
+/**
+ * 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
+
+/**
+ * Keys that can be tracked as "held" (pressed down).
+ * Includes both modifier keys and regular keys.
+ */
+export type HeldKey = CanonicalModifier | Key
+
+// =============================================================================
+// Hotkey Types
+// =============================================================================
+
+/**
+ * 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
+ * ```
+ */
+export 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
+ * ```
+ */
+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 */
+  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
+ * ```
+ */
+export 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`).
+ */
+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'
+}
+
+/**
+ * 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.
+ */
+export 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)
+ * }
+ * ```
+ */
+export type HotkeyCallback = (
+  event: KeyboardEvent,
+  context: HotkeyCallbackContext,
+) => void

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './constants'
+export * from './format'
+export * from './hotkey'
+export * from './hotkey-manager'
+export * from './key-state-tracker'
+export * from './match'
+export * from './parse'
+export * from './recorder'
+export * from './sequence'
+export * from './validate'

package/src/key-state-tracker.ts

@@ -0,0 +1,249 @@
+import { Store } from '@tanstack/store'
+import { MODIFIER_KEYS, normalizeKeyName } from './constants'
+
+/**
+ * State interface for the KeyStateTracker.
+ */
+export interface KeyStateTrackerState {
+  /**
+   * Array of currently held key names (normalized, e.g. "Control", "A").
+   */
+  heldKeys: Array<string>
+  /**
+   * Map from normalized key name to the physical `event.code` (e.g. "KeyA", "ShiftLeft").
+   * Useful for debugging which physical key was pressed.
+   */
+  heldCodes: Record<string, string>
+}
+
+/**
+ * Returns the default state for KeyStateTracker.
+ */
+function getDefaultKeyStateTrackerState(): KeyStateTrackerState {
+  return {
+    heldKeys: [],
+    heldCodes: {},
+  }
+}
+
+/**
+ * Singleton tracker for currently held keyboard keys.
+ *
+ * This class maintains a list of all keys currently being pressed,
+ * which is useful for:
+ * - Displaying currently held keys to users
+ * - Custom shortcut recording for rebinding
+ * - Complex chord detection
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - State can be accessed via `tracker.store.state` when using the class directly
+ * - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state
+ *
+ * @example
+ * ```ts
+ * const tracker = KeyStateTracker.getInstance()
+ *
+ * // Access state directly
+ * console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']
+ *
+ * // Subscribe to changes with TanStack Store
+ * const unsubscribe = tracker.store.subscribe(() => {
+ *   console.log('Currently held:', tracker.store.state.heldKeys)
+ * })
+ *
+ * // Check current state
+ * console.log(tracker.getHeldKeys()) // ['Control', 'Shift']
+ * console.log(tracker.isKeyHeld('Control')) // true
+ *
+ * // Cleanup
+ * unsubscribe()
+ * ```
+ */
+export class KeyStateTracker {
+  static #instance: KeyStateTracker | null = null
+
+  /**
+   * The TanStack Store instance containing the tracker state.
+   * Use this to subscribe to state changes or access current state.
+   */
+  readonly store: Store<KeyStateTrackerState> = new Store(
+    getDefaultKeyStateTrackerState(),
+  )
+
+  #heldKeysSet: Set<string> = new Set()
+  #heldCodesMap: Map<string, string> = new Map()
+  #keydownListener: ((event: KeyboardEvent) => void) | null = null
+  #keyupListener: ((event: KeyboardEvent) => void) | null = null
+  #blurListener: (() => void) | null = null
+
+  private constructor() {
+    this.#setupListeners()
+  }
+
+  /**
+   * Gets the singleton instance of KeyStateTracker.
+   */
+  static getInstance(): KeyStateTracker {
+    if (!KeyStateTracker.#instance) {
+      KeyStateTracker.#instance = new KeyStateTracker()
+    }
+    return KeyStateTracker.#instance
+  }
+
+  /**
+   * Resets the singleton instance. Useful for testing.
+   */
+  static resetInstance(): void {
+    if (KeyStateTracker.#instance) {
+      KeyStateTracker.#instance.destroy()
+      KeyStateTracker.#instance = null
+    }
+  }
+
+  /**
+   * Sets up the keyboard event listeners.
+   */
+  #setupListeners(): void {
+    if (typeof document === 'undefined') {
+      return // SSR safety
+    }
+
+    this.#keydownListener = (event: KeyboardEvent) => {
+      const key = normalizeKeyName(event.key)
+      if (!this.#heldKeysSet.has(key)) {
+        this.#heldKeysSet.add(key)
+        this.#heldCodesMap.set(key, 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)
+      }
+
+      // When a modifier key is released, clear any non-modifier keys still
+      // marked as held. On macOS, the OS intercepts modifier+key combos
+      // (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)
+          }
+        }
+      }
+
+      this.#syncState()
+    }
+
+    // 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()
+        this.#syncState()
+      }
+    }
+
+    document.addEventListener('keydown', this.#keydownListener)
+    document.addEventListener('keyup', this.#keyupListener)
+    window.addEventListener('blur', this.#blurListener)
+  }
+
+  /**
+   * Syncs the internal Set to the Store state.
+   */
+  #syncState(): void {
+    this.store.setState(() => ({
+      heldKeys: Array.from(this.#heldKeysSet),
+      heldCodes: Object.fromEntries(this.#heldCodesMap),
+    }))
+  }
+
+  /**
+   * Removes the keyboard event listeners.
+   */
+  #removeListeners(): void {
+    if (typeof document === 'undefined') {
+      return
+    }
+
+    if (this.#keydownListener) {
+      document.removeEventListener('keydown', this.#keydownListener)
+      this.#keydownListener = null
+    }
+
+    if (this.#keyupListener) {
+      document.removeEventListener('keyup', this.#keyupListener)
+      this.#keyupListener = null
+    }
+
+    if (this.#blurListener) {
+      window.removeEventListener('blur', this.#blurListener)
+      this.#blurListener = null
+    }
+  }
+
+  /**
+   * Gets an array of currently held key names.
+   *
+   * @returns Array of key names currently being pressed
+   */
+  getHeldKeys(): Array<string> {
+    return this.store.state.heldKeys
+  }
+
+  /**
+   * Checks if a specific key is currently being held.
+   *
+   * @param key - The key name to check (case-insensitive)
+   * @returns True if the key is currently held
+   */
+  isKeyHeld(key: string): boolean {
+    const normalizedKey = normalizeKeyName(key)
+    return this.#heldKeysSet.has(normalizedKey)
+  }
+
+  /**
+   * Checks if any of the given keys are currently held.
+   *
+   * @param keys - Array of key names to check
+   * @returns True if any of the keys are currently held
+   */
+  isAnyKeyHeld(keys: Array<string>): boolean {
+    return keys.some((key) => this.isKeyHeld(key))
+  }
+
+  /**
+   * Checks if all of the given keys are currently held.
+   *
+   * @param keys - Array of key names to check
+   * @returns True if all of the keys are currently held
+   */
+  areAllKeysHeld(keys: Array<string>): boolean {
+    return keys.every((key) => this.isKeyHeld(key))
+  }
+
+  /**
+   * Destroys the tracker and removes all listeners.
+   */
+  destroy(): void {
+    this.#removeListeners()
+    this.#heldKeysSet.clear()
+    this.#heldCodesMap.clear()
+    this.store.setState(() => getDefaultKeyStateTrackerState())
+  }
+}
+
+/**
+ * Gets the singleton KeyStateTracker instance.
+ * Convenience function for accessing the tracker.
+ */
+export function getKeyStateTracker(): KeyStateTracker {
+  return KeyStateTracker.getInstance()
+}