@tanstack/hotkeys 0.9.0 → 0.10.0

package/src/hotkey-sequence-recorder.ts

@@ -1,410 +0,0 @@
-import { Store } from '@tanstack/store'
-import { findHotkeyConflicts } from './conflicts'
-import {
-  beginRecording,
-  captureRecordingEvent,
-  endRecording,
-} from './_recording-guard'
-import { chordRejection, hotkeyChordFromKeydown } from './_recorder-chord'
-import { normalizeKeyboardEvent } from './_keyboard-event'
-import { isModifierKey, parseHotkey } from './parse'
-import { validateHotkey } from './validate'
-import { detectPlatform } from './platform'
-import { shouldIgnoreInputEvent } from './_event-target'
-import type {
-  HotkeySequenceRecorderValidationContext,
-  RecorderOptions,
-} from './recorder-options'
-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 extends RecorderOptions {
-  /** Validate the completed sequence. Rejection preserves the steps for editing. */
-  validate?: (
-    sequence: HotkeySequence,
-    context: HotkeySequenceRecorderValidationContext,
-  ) => boolean | string
-  /** Callback when a sequence is successfully recorded */
-  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',
-}
-
-/** Resolves the Enter policy, with commitKeys: none overriding the legacy boolean. */
-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'
-  #events: Array<KeyboardEvent> = []
-  #idleTimer: ReturnType<typeof setTimeout> | null = null
-
-  constructor(options: HotkeySequenceRecorderOptions) {
-    this.#options = {
-      ...defaultHotkeySequenceRecorderOptions,
-      ...options,
-    }
-    this.#platform = detectPlatform()
-  }
-
-  /** Merges current callbacks and options without discarding recorded steps. */
-  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {
-    this.#options = {
-      ...defaultHotkeySequenceRecorderOptions,
-      ...this.#options,
-      ...options,
-    }
-  }
-
-  /** Cancels a pending idle commit so it cannot fire after editing or stopping. */
-  #clearIdleTimer(): void {
-    if (this.#idleTimer !== null) {
-      clearTimeout(this.#idleTimer)
-      this.#idleTimer = null
-    }
-  }
-
-  /** Restarts optional idle commit after a step is recorded or edited. */
-  #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)
-  }
-
-  /** Publishes edited steps while preserving the remaining recorder state. */
-  #patchSteps(updater: (prev: HotkeySequence) => HotkeySequence): void {
-    this.store.setState((s) => ({
-      ...s,
-      steps: updater(s.steps),
-    }))
-  }
-
-  /** Starts a fresh recording; repeated starts during an active session are ignored. */
-  start(): void {
-    if (this.#keydownHandler) {
-      return
-    }
-
-    this.#clearIdleTimer()
-    this.#events = []
-    beginRecording(this)
-    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 &&
-        event.key !== 'Escape' &&
-        shouldIgnoreInputEvent(event, document, document)
-      )
-        return
-
-      const platform = this.#options.platform ?? this.#platform
-      if (normalizeKeyboardEvent(event, platform).isComposing) return
-      captureRecordingEvent(event)
-      event.preventDefault()
-      event.stopPropagation()
-      if (event.repeat) return
-
-      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.stop()
-            this.#options.onClear?.()
-            return
-          }
-          this.#events.pop()
-          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
-      }
-
-      if (isModifierKey(event.key) || event.key === 'AltGraph') return
-      const rejection = chordRejection(event, { ...this.#options, platform })
-      if (rejection) {
-        this.#options.onReject?.(rejection)
-        return
-      }
-      const finalHotkey = hotkeyChordFromKeydown(
-        event,
-        platform,
-        this.#options.recordBy,
-      )
-      if (finalHotkey === null) {
-        return
-      }
-
-      const validation = validateHotkey(finalHotkey)
-      if (!validation.valid) {
-        this.#options.onReject?.({
-          reason: 'invalid',
-          message: validation.errors.join('; '),
-          hotkey: finalHotkey,
-        })
-        return
-      }
-      this.#events.push(event)
-      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]
-    const platform = this.#options.platform ?? this.#platform
-    this.#clearIdleTimer()
-    const accepted = this.#options.validate?.(sequence, {
-      events: [...this.#events],
-      parsedSequence: sequence.map((step) => parseHotkey(step, platform)),
-    })
-    if (accepted !== undefined && accepted !== true) {
-      this.#options.onReject?.({
-        reason: 'validation',
-        message:
-          typeof accepted === 'string'
-            ? accepted
-            : 'This sequence is not allowed.',
-        sequence,
-      })
-      return
-    }
-    if (this.#options.detectConflicts) {
-      const conflicts = findHotkeyConflicts(sequence, {
-        ...(typeof this.#options.detectConflicts === 'object'
-          ? this.#options.detectConflicts
-          : {}),
-        platform,
-        events: this.#events,
-      })
-      if (conflicts.length) {
-        this.#options.onReject?.({
-          reason: 'conflict',
-          message: 'This sequence conflicts with a registered binding.',
-          sequence,
-          conflicts,
-        })
-        return
-      }
-    }
-    endRecording(this)
-    this.#events = []
-
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: sequence,
-    }))
-
-    this.#options.onRecord(sequence)
-  }
-
-  /** Stops and discards in-progress steps without invoking onCancel. */
-  stop(): void {
-    endRecording(this)
-    this.#events = []
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-  }
-
-  /** Stops, discards in-progress steps, and notifies onCancel. */
-  cancel(): void {
-    endRecording(this)
-    this.#events = []
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-    this.#options.onCancel?.()
-  }
-
-  /** Captures keydowns before application handlers, with an SSR-safe document check. */
-  #addListener(handler: (event: KeyboardEvent) => void): void {
-    if (typeof document === 'undefined') {
-      return
-    }
-    document.addEventListener('keydown', handler, true)
-  }
-
-  /** Detaches the capture listener when recording ends. */
-  #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,
-    }))
-  }
-}

package/src/hotkey.types.ts

@@ -1,269 +0,0 @@
-import type { CanonicalModifier, Key, LogicalKey } from './key.types'
-
-// =============================================================================
-// Hotkey Types
-// =============================================================================
-
-/**
- * Single modifier + key combinations.
- * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
- *
- * 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.
- */
-export type SingleModifierHotkey =
-  | `Control+${Key}`
-  | `Alt+${Key}`
-  | `Shift+${Key}`
-  | `Meta+${Key}`
-  | `Mod+${Key}`
-
-/**
- * Two modifier + key combinations.
- *
- * **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)
- */
-export type TwoModifierHotkey =
-  | `Control+Alt+${Key}`
-  | `Control+Shift+${Key}`
-  | `Control+Meta+${Key}`
-  | `Alt+Shift+${Key}`
-  | `Alt+Meta+${Key}`
-  | `Shift+Meta+${Key}`
-  | `Mod+Alt+${Key}`
-  | `Mod+Shift+${Key}`
-
-/**
- * Three modifier + key combinations.
- *
- * **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)
- */
-export type ThreeModifierHotkey =
-  | `Control+Alt+Shift+${Key}`
-  | `Control+Alt+Meta+${Key}`
-  | `Control+Shift+Meta+${Key}`
-  | `Alt+Shift+Meta+${Key}`
-  | `Mod+Alt+Shift+${Key}`
-
-/**
- * Four modifier + key combinations.
- *
- * 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
- */
-export type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`
-
-/**
- * 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
-
-/** Resolved modifier flags shared by both parsed binding variants. */
-export interface ParsedModifiers {
-  /** Whether Control is required. */
-  ctrl: boolean
-  /** Whether Shift is required. */
-  shift: boolean
-  /** Whether Alt is required. */
-  alt: boolean
-  /** Whether Meta (Command) is required. */
-  meta: boolean
-  /** 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.
- *
- * 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
- * useHotkey({ code: 'KeyW', mod: true }, handler)           // Physical Mod+KeyW
- * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
- * ```
- */
-/** Modifier flags shared by logical-key and physical-code registrations. */
-export interface RawModifiers {
-  /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
-  /** 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
-}
-
-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
-
-/**
- * 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
-
-/**
- * Metadata for hotkey and sequence registrations.
- * Includes `name`, `description`, and `group` by default. Extend via declaration merging:
- *
- * @example
- * ```ts
- * declare module '@tanstack/hotkeys' {
- *   interface HotkeyMeta {
- *     category?: string
- *     icon?: string
- *   }
- * }
- * ```
- */
-export interface HotkeyMeta {
-  /** Human-readable name for this hotkey (e.g., "Save Document") */
-  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,17 +0,0 @@
-export * from './constants'
-export * from './display-labels'
-export * from './platform'
-export * from './key.types'
-export * from './hotkey.types'
-export * from './format'
-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 './recorder-options'
-export * from './hotkey-recorder'
-export * from './hotkey-sequence-recorder'