@tanstack/hotkeys 0.9.0 → 0.10.0

package/src/key-state-tracker.ts

@@ -1,261 +0,0 @@
-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(),
-  )
-
-  #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
-
-  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)
-      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)
-      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
-      // 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 [entryIdentity, entry] of this.#heldEntries) {
-          if (!MODIFIER_KEYS.has(entry.key)) {
-            this.#heldEntries.delete(entryIdentity)
-          }
-        }
-      }
-
-      this.#syncState()
-    }
-
-    // Clear all keys when window loses focus (keys might be released while not focused)
-    this.#blurListener = () => {
-      if (this.#heldEntries.size > 0) {
-        this.#heldEntries.clear()
-        this.#syncState()
-      }
-    }
-
-    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(): 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,
-      heldCodes,
-    }))
-  }
-
-  /**
-   * Removes the keyboard event listeners.
-   */
-  #removeListeners(): void {
-    if (typeof document === 'undefined') {
-      return
-    }
-
-    if (this.#keydownListener) {
-      document.removeEventListener('keydown', this.#keydownListener, true)
-      this.#keydownListener = null
-    }
-
-    if (this.#keyupListener) {
-      document.removeEventListener('keyup', this.#keyupListener, true)
-      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 Array.from(this.#heldEntries.values()).some(
-      (entry) => entry.key === 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.#heldEntries.clear()
-    this.store.setState(() => getDefaultKeyStateTrackerState())
-  }
-}
-
-/**
- * Gets the singleton KeyStateTracker instance.
- * Convenience function for accessing the tracker.
- */
-export function getKeyStateTracker(): KeyStateTracker {
-  return KeyStateTracker.getInstance()
-}

package/src/key.types.ts

@@ -1,268 +0,0 @@
-import type { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from './_named-keys'
-
-/**
- * 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
-}