@tanstack/hotkeys 0.8.0 → 0.10.0

package/src/hotkey-recorder.ts

@@ -1,272 +0,0 @@
-import { Store } from '@tanstack/store'
-import { detectPlatform } from './constants'
-import { isInputElement } from './manager.utils'
-import { hotkeyChordFromKeydown } from './recorder-chord'
-import type { Hotkey } from './hotkey'
-
-/**
- * State interface for the HotkeyRecorder.
- */
-export interface HotkeyRecorderState {
-  /** Whether recording is currently active */
-  isRecording: boolean
-  /** The currently recorded hotkey (for live preview) */
-  recordedHotkey: Hotkey | null
-}
-
-/**
- * Options for configuring a HotkeyRecorder instance.
- */
-export interface HotkeyRecorderOptions {
-  /** Callback when a hotkey is successfully recorded */
-  onRecord: (hotkey: Hotkey) => void
-  /** Optional callback when recording is cancelled (Escape pressed) */
-  onCancel?: () => void
-  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */
-  onClear?: () => void
-  /**
-   * Whether to ignore keyboard events from input-like elements (text inputs,
-   * textarea, select, contenteditable). When true, typing in inputs passes
-   * through normally instead of being captured as a hotkey recording.
-   * Escape always works regardless of this setting.
-   * @default true
-   */
-  ignoreInputs?: boolean
-}
-
-/**
- * Framework-agnostic class for recording keyboard shortcuts.
- *
- * This class handles all the complexity of capturing keyboard events,
- * converting them to hotkey strings, and handling edge cases like
- * Escape to cancel or Backspace/Delete to clear.
- *
- * State Management:
- * - Uses TanStack Store for reactive state management
- * - State can be accessed via `recorder.store.state` when using the class directly
- * - When using framework adapters (React), use `useSelector` hooks for reactive state
- *
- * @example
- * ```ts
- * const recorder = new HotkeyRecorder({
- *   onRecord: (hotkey) => {
- *     console.log('Recorded:', hotkey)
- *   },
- *   onCancel: () => {
- *     console.log('Recording cancelled')
- *   },
- * })
- *
- * // Start recording
- * recorder.start()
- *
- * // Access state directly
- * console.log(recorder.store.state.isRecording) // true
- *
- * // Subscribe to changes with TanStack Store
- * const unsubscribe = recorder.store.subscribe(() => {
- *   console.log('Recording:', recorder.store.state.isRecording)
- * })
- *
- * // Cleanup
- * recorder.destroy()
- * unsubscribe()
- * ```
- */
-export class HotkeyRecorder {
-  /**
-   * The TanStack Store instance containing the recorder state.
-   * Use this to subscribe to state changes or access current state.
-   */
-  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({
-    isRecording: false,
-    recordedHotkey: null,
-  })
-
-  #keydownHandler: ((event: KeyboardEvent) => void) | null = null
-  #options: HotkeyRecorderOptions
-  #platform: 'mac' | 'windows' | 'linux'
-
-  constructor(options: HotkeyRecorderOptions) {
-    this.#options = options
-    this.#platform = detectPlatform()
-  }
-
-  /**
-   * Updates the recorder options, including callbacks.
-   * This allows framework adapters to sync callback changes without recreating the recorder.
-   */
-  setOptions(options: Partial<HotkeyRecorderOptions>): void {
-    this.#options = {
-      ...this.#options,
-      ...options,
-    }
-  }
-
-  /**
-   * Start recording a new hotkey.
-   *
-   * Sets up a keydown event listener that captures keyboard events
-   * and converts them to hotkey strings. Recording continues until
-   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.
-   */
-  start(): void {
-    // Prevent starting recording if already recording
-    if (this.#keydownHandler) {
-      return
-    }
-
-    // Update store state
-    this.store.setState(() => ({
-      isRecording: true,
-      recordedHotkey: null,
-    }))
-
-    // Create keydown handler
-    const handler = (event: KeyboardEvent) => {
-      // Check if we're still recording (handler might be called after stop/cancel)
-      if (!this.#keydownHandler) {
-        return
-      }
-
-      // If ignoreInputs is enabled (default) and focus is in an input element,
-      // let the event pass through so the user can type normally.
-      // Escape is the exception — it should always cancel recording.
-      if (this.#options.ignoreInputs !== false) {
-        const activeEl =
-          typeof document !== 'undefined' ? document.activeElement : null
-        if (isInputElement(activeEl) && event.key !== 'Escape') {
-          return
-        }
-      }
-
-      event.preventDefault()
-      event.stopPropagation()
-
-      // Handle Escape to cancel
-      if (event.key === 'Escape') {
-        this.cancel()
-        return
-      }
-
-      // Handle Backspace/Delete to clear shortcut
-      if (event.key === 'Backspace' || event.key === 'Delete') {
-        if (
-          !event.ctrlKey &&
-          !event.shiftKey &&
-          !event.altKey &&
-          !event.metaKey
-        ) {
-          this.#options.onClear?.()
-          this.#options.onRecord('' as Hotkey)
-          this.stop()
-          return
-        }
-      }
-
-      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)
-      if (finalHotkey === null) {
-        return
-      }
-
-      // Remove listener FIRST to prevent any additional events
-      const handlerToRemove = this.#keydownHandler as
-        | ((event: KeyboardEvent) => void)
-        | null
-      if (handlerToRemove) {
-        this.#removeListener(handlerToRemove)
-        this.#keydownHandler = null
-      }
-
-      // Update store state immediately
-      this.store.setState(() => ({
-        isRecording: false,
-        recordedHotkey: finalHotkey,
-      }))
-
-      // Call callback AFTER listener is removed and state is set
-      this.#options.onRecord(finalHotkey)
-    }
-
-    this.#keydownHandler = handler
-    this.#addListener(handler)
-  }
-
-  /**
-   * Stop recording (same as cancel, but doesn't call onCancel).
-   *
-   * Removes the event listener and resets the recording state.
-   */
-  stop(): void {
-    // Remove event listener immediately
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-
-    // Update store state
-    this.store.setState(() => ({
-      isRecording: false,
-      recordedHotkey: null,
-    }))
-  }
-
-  /**
-   * Cancel recording without saving.
-   *
-   * Removes the event listener, resets the recording state, and calls
-   * the onCancel callback if provided.
-   */
-  cancel(): void {
-    // Remove event listener immediately
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-
-    // Update store state
-    this.store.setState(() => ({
-      isRecording: false,
-      recordedHotkey: null,
-    }))
-
-    // Call cancel callback
-    this.#options.onCancel?.()
-  }
-
-  /**
-   * Adds the keydown event listener to the document.
-   */
-  #addListener(handler: (event: KeyboardEvent) => void): void {
-    if (typeof document === 'undefined') {
-      return // SSR safety
-    }
-
-    document.addEventListener('keydown', handler, true)
-  }
-
-  /**
-   * Removes the keydown event listener from the document.
-   */
-  #removeListener(handler: (event: KeyboardEvent) => void): void {
-    if (typeof document === 'undefined') {
-      return
-    }
-
-    document.removeEventListener('keydown', handler, true)
-  }
-
-  /**
-   * Clean up event listeners and reset state.
-   *
-   * Call this when you're done with the recorder to ensure
-   * all event listeners are properly removed.
-   */
-  destroy(): void {
-    this.stop()
-    this.store.setState(() => ({
-      isRecording: false,
-      recordedHotkey: null,
-    }))
-  }
-}

package/src/hotkey-sequence-recorder.ts

@@ -1,328 +0,0 @@
-import { Store } from '@tanstack/store'
-import { detectPlatform } from './constants'
-import { isInputElement } from './manager.utils'
-import { hotkeyChordFromKeydown } from './recorder-chord'
-import type { HotkeySequence } from './sequence-manager'
-
-/**
- * How the user can commit a recorded sequence from the keyboard.
- * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.
- * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).
- */
-export type HotkeySequenceRecorderCommitKeys = 'enter' | 'none'
-
-/**
- * State interface for the HotkeySequenceRecorder.
- */
-export interface HotkeySequenceRecorderState {
-  /** Whether recording is currently active */
-  isRecording: boolean
-  /** Chords captured so far in the current recording session */
-  steps: HotkeySequence
-  /** The last successfully committed sequence, or null if none / after starting a new session */
-  recordedSequence: HotkeySequence | null
-}
-
-/**
- * Options for configuring a HotkeySequenceRecorder instance.
- */
-export interface HotkeySequenceRecorderOptions {
-  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
-  onRecord: (sequence: HotkeySequence) => void
-  /** Optional callback when recording is cancelled (Escape pressed) */
-  onCancel?: () => void
-  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */
-  onClear?: () => void
-  /**
-   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.
-   * @default true
-   */
-  commitOnEnter?: boolean
-  /**
-   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).
-   * @default 'enter'
-   */
-  commitKeys?: HotkeySequenceRecorderCommitKeys
-  /**
-   * Milliseconds of inactivity after the **last completed chord** before auto-committing.
-   * The timer does not run while waiting for the first chord (`steps.length === 0`).
-   */
-  idleTimeoutMs?: number
-  /**
-   * Whether to ignore keyboard events from input-like elements (text inputs,
-   * textarea, select, contenteditable). When true, typing in inputs passes
-   * through normally instead of being captured as a sequence recording.
-   * Escape always works regardless of this setting.
-   * @default true
-   */
-  ignoreInputs?: boolean
-}
-
-const defaultHotkeySequenceRecorderOptions: Pick<
-  HotkeySequenceRecorderOptions,
-  'commitOnEnter' | 'commitKeys'
-> = {
-  commitOnEnter: true,
-  commitKeys: 'enter',
-}
-
-function resolvedCommitOnEnter(
-  options: HotkeySequenceRecorderOptions,
-): boolean {
-  if (options.commitKeys === 'none') {
-    return false
-  }
-  return options.commitOnEnter !== false
-}
-
-/**
- * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
- *
- * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
- * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
- * **Backspace/Delete** to remove the last step or clear when empty.
- */
-export class HotkeySequenceRecorder {
-  readonly store: Store<HotkeySequenceRecorderState> =
-    new Store<HotkeySequenceRecorderState>({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    })
-
-  #keydownHandler: ((event: KeyboardEvent) => void) | null = null
-  #options: HotkeySequenceRecorderOptions
-  #platform: 'mac' | 'windows' | 'linux'
-  #idleTimer: ReturnType<typeof setTimeout> | null = null
-
-  constructor(options: HotkeySequenceRecorderOptions) {
-    this.#options = {
-      ...defaultHotkeySequenceRecorderOptions,
-      ...options,
-    }
-    this.#platform = detectPlatform()
-  }
-
-  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {
-    this.#options = {
-      ...defaultHotkeySequenceRecorderOptions,
-      ...this.#options,
-      ...options,
-    }
-  }
-
-  #clearIdleTimer(): void {
-    if (this.#idleTimer !== null) {
-      clearTimeout(this.#idleTimer)
-      this.#idleTimer = null
-    }
-  }
-
-  #scheduleIdleTimer(): void {
-    this.#clearIdleTimer()
-    const ms = this.#options.idleTimeoutMs
-    if (ms === undefined || ms <= 0) {
-      return
-    }
-    const steps = this.store.state.steps
-    if (steps.length === 0) {
-      return
-    }
-    this.#idleTimer = setTimeout(() => {
-      this.#idleTimer = null
-      if (!this.#keydownHandler) {
-        return
-      }
-      if (this.store.state.steps.length >= 1) {
-        this.commit()
-      }
-    }, ms)
-  }
-
-  #patchSteps(updater: (prev: HotkeySequence) => HotkeySequence): void {
-    this.store.setState((s) => ({
-      ...s,
-      steps: updater(s.steps),
-    }))
-  }
-
-  start(): void {
-    if (this.#keydownHandler) {
-      return
-    }
-
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: true,
-      steps: [],
-      recordedSequence: null,
-    }))
-
-    const handler = (event: KeyboardEvent) => {
-      if (!this.#keydownHandler) {
-        return
-      }
-
-      // If ignoreInputs is enabled (default) and focus is in an input element,
-      // let the event pass through so the user can type normally.
-      // Escape is the exception — it should always cancel recording.
-      if (this.#options.ignoreInputs !== false) {
-        const activeEl =
-          typeof document !== 'undefined' ? document.activeElement : null
-        if (isInputElement(activeEl) && event.key !== 'Escape') {
-          return
-        }
-      }
-
-      event.preventDefault()
-      event.stopPropagation()
-
-      if (event.key === 'Escape') {
-        this.cancel()
-        return
-      }
-
-      if (event.key === 'Backspace' || event.key === 'Delete') {
-        if (
-          !event.ctrlKey &&
-          !event.shiftKey &&
-          !event.altKey &&
-          !event.metaKey
-        ) {
-          const steps = this.store.state.steps
-          if (steps.length === 0) {
-            this.#options.onClear?.()
-            this.#options.onRecord([])
-            this.#finishWithoutCommitCallback()
-            return
-          }
-          this.#patchSteps((prev) => prev.slice(0, -1))
-          const next = this.store.state.steps
-          if (next.length === 0) {
-            this.#clearIdleTimer()
-          } else {
-            this.#scheduleIdleTimer()
-          }
-          return
-        }
-      }
-
-      const enterCommits =
-        resolvedCommitOnEnter(this.#options) &&
-        event.key === 'Enter' &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        !event.altKey &&
-        !event.metaKey
-
-      if (enterCommits && this.store.state.steps.length >= 1) {
-        this.commit()
-        return
-      }
-
-      if (enterCommits && this.store.state.steps.length === 0) {
-        return
-      }
-
-      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)
-      if (finalHotkey === null) {
-        return
-      }
-
-      this.#patchSteps((prev) => [...prev, finalHotkey])
-      this.#scheduleIdleTimer()
-    }
-
-    this.#keydownHandler = handler
-    this.#addListener(handler)
-  }
-
-  /**
-   * Commit the current steps as a sequence. No-op if fewer than one step.
-   */
-  commit(): void {
-    const steps = this.store.state.steps
-    if (steps.length < 1) {
-      return
-    }
-
-    const sequence = [...steps]
-
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: sequence,
-    }))
-
-    this.#options.onRecord(sequence)
-  }
-
-  #finishWithoutCommitCallback(): void {
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-  }
-
-  stop(): void {
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-  }
-
-  cancel(): void {
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-    this.#options.onCancel?.()
-  }
-
-  #addListener(handler: (event: KeyboardEvent) => void): void {
-    if (typeof document === 'undefined') {
-      return
-    }
-    document.addEventListener('keydown', handler, true)
-  }
-
-  #removeListener(handler: (event: KeyboardEvent) => void): void {
-    if (typeof document === 'undefined') {
-      return
-    }
-    document.removeEventListener('keydown', handler, true)
-  }
-
-  destroy(): void {
-    this.stop()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-  }
-}