@tanstack/hotkeys 0.4.3 → 0.6.0

package/src/format.ts

@@ -1,12 +1,26 @@
 import {
   KEY_DISPLAY_SYMBOLS,
+  LINUX_MODIFIER_LABELS,
+  MAC_MODIFIER_LABELS,
   MAC_MODIFIER_SYMBOLS,
+  MODIFIER_ALIASES,
   MODIFIER_ORDER,
-  STANDARD_MODIFIER_LABELS,
+  PUNCTUATION_KEY_DISPLAY_LABELS,
+  WINDOWS_MODIFIER_LABELS,
   detectPlatform,
 } from './constants'
-import { parseHotkey } from './parse'
-import type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'
+import {
+  isModifierKey,
+  normalizeHotkeyFromParsed,
+  normalizeRegisterableHotkey,
+} from './parse'
+import type {
+  CanonicalModifier,
+  FormatDisplayOptions,
+  Hotkey,
+  ParsedHotkey,
+  RegisterableHotkey,
+} from './hotkey'
 
 /**
  * Converts a hotkey sequence array to a display string.
@@ -55,8 +69,8 @@ export function formatHotkey(parsed: ParsedHotkey): string {
 /**
  * Formats a hotkey for display in a user interface.
  *
- * On macOS, uses symbols (⌘⇧S).
- * On Windows/Linux, uses text (Ctrl+Shift+S).
+ * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
+ * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
  *
  * @param hotkey - The hotkey string or ParsedHotkey to format
  * @param options - Formatting options
@@ -65,7 +79,7 @@ export function formatHotkey(parsed: ParsedHotkey): string {
  * @example
  * ```ts
  * formatForDisplay('Mod+Shift+S', { platform: 'mac' })
- * // Returns: '⇧⌘S'
+ * // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)
  *
  * formatForDisplay('Mod+Shift+S', { platform: 'windows' })
  * // Returns: 'Ctrl+Shift+S'
@@ -75,203 +89,51 @@ export function formatHotkey(parsed: ParsedHotkey): string {
  * ```
  */
 export function formatForDisplay(
-  hotkey: Hotkey | (string & {}) | ParsedHotkey,
+  hotkey: RegisterableHotkey | (string & {}),
   options: FormatDisplayOptions = {},
 ): string {
   const platform = options.platform ?? detectPlatform()
-  const parsed =
-    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
-
-  if (platform === 'mac') {
-    return formatForMac(parsed)
-  }
-
-  return formatForStandard(parsed)
-}
-
-/**
- * Formats a hotkey for macOS display using symbols.
- */
-function formatForMac(parsed: ParsedHotkey): string {
-  const parts: Array<string> = []
-
-  // Add modifiers in macOS order (typically Control, Option, Shift, Command)
-  // But we'll use our canonical order and just use symbols
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(MAC_MODIFIER_SYMBOLS[modifier])
-    }
-  }
-
-  // Add the key (use symbol if available, otherwise the key itself)
-  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key
-  parts.push(keyDisplay)
-
-  // On Mac, modifiers are typically concatenated without separators
-  return parts.join('')
-}
-
-/**
- * Formats a hotkey for Windows/Linux display using text labels.
- */
-function formatForStandard(parsed: ParsedHotkey): string {
-  const parts: Array<string> = []
-
-  // Add modifiers in canonical order
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(STANDARD_MODIFIER_LABELS[modifier])
-    }
-  }
-
-  // Add the key (use symbol/short form if available)
-  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key
-  parts.push(keyDisplay)
-
-  // On Windows/Linux, use + as separator
-  return parts.join('+')
+  const useSymbols = options.useSymbols ?? true
+  const normalizedHotkey = normalizeRegisterableHotkey(
+    hotkey as RegisterableHotkey,
+    platform,
+  )
+  return normalizedHotkey
+    .split('+')
+    .map((segment) => {
+      if (isModifierKey(segment)) {
+        const modifierToken = (MODIFIER_ALIASES[segment] ??
+          MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'
+        return platform === 'mac'
+          ? useSymbols
+            ? MAC_MODIFIER_SYMBOLS[modifierToken]
+            : MAC_MODIFIER_LABELS[modifierToken]
+          : platform === 'windows'
+            ? WINDOWS_MODIFIER_LABELS[modifierToken]
+            : LINUX_MODIFIER_LABELS[modifierToken]
+      } else {
+        const keyDisplaySymbol =
+          useSymbols &&
+          KEY_DISPLAY_SYMBOLS[segment as keyof typeof KEY_DISPLAY_SYMBOLS]
+        if (keyDisplaySymbol) return keyDisplaySymbol
+
+        const punctuationKeyDisplayLabel =
+          !useSymbols &&
+          PUNCTUATION_KEY_DISPLAY_LABELS[
+            segment as keyof typeof PUNCTUATION_KEY_DISPLAY_LABELS
+          ]
+        return punctuationKeyDisplayLabel || segment
+      }
+    })
+    .join(platform === 'mac' && useSymbols ? ' ' : '+')
 }
 
 /**
- * Formats a hotkey using platform-agnostic labels.
- * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.
- *
- * @param hotkey - The hotkey string or ParsedHotkey to format
- * @param platform - The target platform
- * @returns A formatted string with platform-appropriate labels
+ * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
  */
 export function formatWithLabels(
-  hotkey: Hotkey | (string & {}),
-  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
-): string {
-  const parsed =
-    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
-  const parts: Array<string> = []
-
-  // Custom labels for more readable output
-  const labels: Record<string, string> = {
-    Control: 'Ctrl',
-    Alt: platform === 'mac' ? 'Option' : 'Alt',
-    Shift: 'Shift',
-    Meta: platform === 'mac' ? 'Cmd' : 'Win',
-  }
-
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(labels[modifier] ?? modifier)
-    }
-  }
-
-  // Add the key
-  parts.push(parsed.key)
-
-  return parts.join('+')
-}
-
-// =============================================================================
-// Debugging Display Labels
-// =============================================================================
-
-/**
- * Maps canonical modifier names to debugging-friendly labels per platform.
- */
-const MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {
-  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },
-  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },
-  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },
-}
-
-/**
- * Options for formatting a single key for debugging display.
- */
-export interface FormatKeyDebuggingOptions {
-  /** The target platform. Defaults to auto-detection. */
-  platform?: 'mac' | 'windows' | 'linux'
-  /**
-   * Whether the input value comes from `event.key` or `event.code`.
-   *
-   * - `'key'` (default): Applies rich platform-aware formatting (modifier
-   *   labels, special-key symbols, etc.).
-   * - `'code'`: Returns the value unchanged — physical key codes like
-   *   `"MetaLeft"` or `"KeyA"` are already descriptive for debugging.
-   */
-  source?: 'key' | 'code'
-}
-
-/**
- * Formats a single key name for debugging/devtools display.
- *
- * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,
- * this function formats individual key names (from `event.key`) with rich
- * platform-aware labels suitable for debugging tools and developer-facing displays.
- *
- * Features:
- * - Modifier keys show their platform role (e.g., "Mod (Cmd)" for Meta on Mac)
- * - On macOS, modifier keys are prefixed with their symbol (e.g., "⌘ Mod (Cmd)")
- * - Special keys use display symbols (ArrowUp -> "↑", Escape -> "Esc")
- * - Regular keys pass through unchanged
- *
- * @param key - A single key name (e.g., "Meta", "Shift", "ArrowUp", "A")
- * @param options - Formatting options
- * @returns A formatted label suitable for debugging display
- *
- * @example
- * ```ts
- * // On macOS:
- * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'
- * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'
- * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'
- * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'
- *
- * // On Windows:
- * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'
- * formatKeyForDebuggingDisplay('Meta')    // 'Win'
- *
- * // Special keys (all platforms):
- * formatKeyForDebuggingDisplay('ArrowUp') // '↑'
- * formatKeyForDebuggingDisplay('Escape')  // 'Esc'
- * formatKeyForDebuggingDisplay('Space')   // '␣'
- *
- * // Regular keys pass through:
- * formatKeyForDebuggingDisplay('A')       // 'A'
- *
- * // With source: 'code', values pass through unchanged:
- * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'
- * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'
- * ```
- */
-export function formatKeyForDebuggingDisplay(
-  key: string,
-  options: FormatKeyDebuggingOptions = {},
+  hotkey: RegisterableHotkey,
+  options: Omit<FormatDisplayOptions, 'useSymbols'> = {},
 ): string {
-  // For event.code values, pass through unchanged — they're already
-  // descriptive for debugging (e.g. "MetaLeft", "KeyA", "ShiftRight").
-  if (options.source === 'code') {
-    return key
-  }
-
-  const platform = options.platform ?? detectPlatform()
-
-  // Check if it's a modifier key
-  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]
-  if (modLabel) {
-    // On Mac, prefix modifier labels with their symbol
-    if (platform === 'mac') {
-      const symbol =
-        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]
-      if (symbol) {
-        return `${symbol} ${modLabel}`
-      }
-    }
-    return modLabel
-  }
-
-  // Check if it's a special key with a display symbol
-  const symbol = KEY_DISPLAY_SYMBOLS[key]
-  if (symbol) {
-    return symbol
-  }
-
-  // Regular key — pass through
-  return key
+  return formatForDisplay(hotkey, { ...options, useSymbols: false })
 }

package/src/hotkey-manager.ts

@@ -27,7 +27,11 @@ export type { ConflictBehavior }
 export interface HotkeyOptions {
   /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
   conflictBehavior?: ConflictBehavior
-  /** Whether the hotkey is enabled. Defaults to true */
+  /**
+   * Soft-disable: when `false`, the callback does not run but the registration
+   * stays in `HotkeyManager` (and in devtools). Toggling this should update the
+   * existing handle via `setOptions` rather than unregistering. Defaults to `true`.
+   */
   enabled?: boolean
   /** The event type to listen for. Defaults to 'keydown' */
   eventType?: 'keydown' | 'keyup'

package/src/{recorder.ts → hotkey-recorder.ts}

@@ -1,11 +1,6 @@
 import { Store } from '@tanstack/store'
 import { detectPlatform } from './constants'
-import {
-  convertToModFormat,
-  hasNonModifierKey,
-  isModifierKey,
-  keyboardEventToHotkey,
-} from './parse'
+import { hotkeyChordFromKeydown } from './recorder-chord'
 import type { Hotkey } from './hotkey'
 
 /**
@@ -149,37 +144,28 @@ export class HotkeyRecorder {
         }
       }
 
-      // Ignore pure modifier keys (wait for a non-modifier key)
-      if (isModifierKey(event)) {
+      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)
+      if (finalHotkey === null) {
         return
       }
 
-      // Convert event to hotkey string using library function
-      const hotkey = keyboardEventToHotkey(event)
-
-      // Always convert to Mod format for portability
-      const finalHotkey = convertToModFormat(hotkey, this.#platform)
-
-      // Validate: must have at least one non-modifier key
-      if (hasNonModifierKey(finalHotkey, this.#platform)) {
-        // 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
-        }
+      // 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,
-        }))
+      // 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)
-      }
+      // Call callback AFTER listener is removed and state is set
+      this.#options.onRecord(finalHotkey)
     }
 
     this.#keydownHandler = handler

package/src/hotkey-sequence-recorder.ts

@@ -0,0 +1,308 @@
+import { Store } from '@tanstack/store'
+import { detectPlatform } from './constants'
+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
+}
+
+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
+      }
+
+      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,
+    }))
+  }
+}

package/src/hotkey.ts

@@ -368,6 +368,8 @@ export type RegisterableHotkey = Hotkey | RawHotkey
 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
 }
 
 /**