@tanstack/hotkeys 0.8.0 → 0.10.0

package/dist/hotkey-sequence-recorder.d.cts

@@ -1,79 +0,0 @@
-import { HotkeySequence } from "./sequence-manager.cjs";
-import { Store } from "@tanstack/store";
-
-//#region src/hotkey-sequence-recorder.d.ts
-/**
- * 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).
- */
-type HotkeySequenceRecorderCommitKeys = 'enter' | 'none';
-/**
- * State interface for the HotkeySequenceRecorder.
- */
-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.
- */
-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;
-}
-/**
- * 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.
- */
-declare class HotkeySequenceRecorder {
-  #private;
-  readonly store: Store<HotkeySequenceRecorderState>;
-  constructor(options: HotkeySequenceRecorderOptions);
-  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
-  start(): void;
-  /**
-   * Commit the current steps as a sequence. No-op if fewer than one step.
-   */
-  commit(): void;
-  stop(): void;
-  cancel(): void;
-  destroy(): void;
-}
-//#endregion
-export { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState };
-//# sourceMappingURL=hotkey-sequence-recorder.d.cts.map

package/dist/hotkey-sequence-recorder.js.map

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

package/dist/hotkey.d.cts

@@ -1,301 +0,0 @@
-//#region src/hotkey.d.ts
-/**
- * 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
- */
-type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
-/**
- * Canonical modifier names that map to KeyboardEvent properties.
- */
-type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
-/**
- * Letter keys A-Z (case-insensitive in matching).
- */
-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.
- */
-type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-/**
- * Function keys F1-F12.
- */
-type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12';
-/**
- * Navigation keys for cursor movement.
- */
-type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
-/**
- * Editing and special keys.
- */
-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).
- */
-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.
- */
-type Key = NonPunctuationKey | PunctuationKey;
-/**
- * Includes both modifier keys and regular keys.
- */
-type IndividualKey = CanonicalModifier | Key;
-/**
- * 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
- * ```
- */
-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
- * ```
- */
-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
- * ```
- */
-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`).
- */
-type RegisterableHotkey = Hotkey | RawHotkey;
-/**
- * Options for formatting hotkeys for display.
- */
-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;
-  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
-  separatorToken?: string | null;
-}
-/**
- * Result of validating a hotkey string.
- */
-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.
- */
-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)
- * }
- * ```
- */
-type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
-/**
- * Metadata for hotkey and sequence registrations.
- * Includes `name` and `description` by default. Extend via declaration merging:
- *
- * @example
- * ```ts
- * declare module '@tanstack/hotkeys' {
- *   interface HotkeyMeta {
- *     category?: string
- *     icon?: string
- *   }
- * }
- * ```
- */
-interface HotkeyMeta {
-  /** Human-readable name for this hotkey (e.g., "Save Document") */
-  name?: string;
-  /** Description of what this hotkey does */
-  description?: string;
-}
-//#endregion
-export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
-//# sourceMappingURL=hotkey.d.cts.map

package/dist/index.cjs

@@ -1,63 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_constants = require('./constants.cjs');
-const require_parse = require('./parse.cjs');
-const require_format = require('./format.cjs');
-const require_match = require('./match.cjs');
-const require_hotkey_manager = require('./hotkey-manager.cjs');
-const require_key_state_tracker = require('./key-state-tracker.cjs');
-const require_hotkey_recorder = require('./hotkey-recorder.cjs');
-const require_hotkey_sequence_recorder = require('./hotkey-sequence-recorder.cjs');
-const require_sequence_manager = require('./sequence-manager.cjs');
-const require_validate = require('./validate.cjs');
-
-exports.ALL_KEYS = require_constants.ALL_KEYS;
-exports.DEFAULT_SEQUENCE_TIMEOUT = require_sequence_manager.DEFAULT_SEQUENCE_TIMEOUT;
-exports.EDITING_KEYS = require_constants.EDITING_KEYS;
-exports.FUNCTION_KEYS = require_constants.FUNCTION_KEYS;
-exports.HotkeyManager = require_hotkey_manager.HotkeyManager;
-exports.HotkeyRecorder = require_hotkey_recorder.HotkeyRecorder;
-exports.HotkeySequenceRecorder = require_hotkey_sequence_recorder.HotkeySequenceRecorder;
-exports.KEY_DISPLAY_SYMBOLS = require_constants.KEY_DISPLAY_SYMBOLS;
-exports.KeyStateTracker = require_key_state_tracker.KeyStateTracker;
-exports.LETTER_KEYS = require_constants.LETTER_KEYS;
-exports.LINUX_MODIFIER_LABELS = require_constants.LINUX_MODIFIER_LABELS;
-exports.MAC_MODIFIER_LABELS = require_constants.MAC_MODIFIER_LABELS;
-exports.MAC_MODIFIER_SYMBOLS = require_constants.MAC_MODIFIER_SYMBOLS;
-exports.MODIFIER_ALIASES = require_constants.MODIFIER_ALIASES;
-exports.MODIFIER_KEYS = require_constants.MODIFIER_KEYS;
-exports.MODIFIER_ORDER = require_constants.MODIFIER_ORDER;
-exports.NAVIGATION_KEYS = require_constants.NAVIGATION_KEYS;
-exports.NUMBER_KEYS = require_constants.NUMBER_KEYS;
-exports.PUNCTUATION_CODE_MAP = require_constants.PUNCTUATION_CODE_MAP;
-exports.PUNCTUATION_KEYS = require_constants.PUNCTUATION_KEYS;
-exports.PUNCTUATION_KEY_DISPLAY_LABELS = require_constants.PUNCTUATION_KEY_DISPLAY_LABELS;
-exports.SequenceManager = require_sequence_manager.SequenceManager;
-exports.WINDOWS_MODIFIER_LABELS = require_constants.WINDOWS_MODIFIER_LABELS;
-exports.assertValidHotkey = require_validate.assertValidHotkey;
-exports.checkHotkey = require_validate.checkHotkey;
-exports.createHotkeyHandler = require_match.createHotkeyHandler;
-exports.createMultiHotkeyHandler = require_match.createMultiHotkeyHandler;
-exports.createSequenceMatcher = require_sequence_manager.createSequenceMatcher;
-exports.detectPlatform = require_constants.detectPlatform;
-exports.formatForDisplay = require_format.formatForDisplay;
-exports.formatHotkey = require_format.formatHotkey;
-exports.formatHotkeySequence = require_format.formatHotkeySequence;
-exports.formatWithLabels = require_format.formatWithLabels;
-exports.getHotkeyManager = require_hotkey_manager.getHotkeyManager;
-exports.getKeyStateTracker = require_key_state_tracker.getKeyStateTracker;
-exports.getSequenceManager = require_sequence_manager.getSequenceManager;
-exports.hasNonModifierKey = require_parse.hasNonModifierKey;
-exports.isModifierKey = require_parse.isModifierKey;
-exports.isSingleLetterKey = require_constants.isSingleLetterKey;
-exports.matchesKeyboardEvent = require_match.matchesKeyboardEvent;
-exports.normalizeHotkey = require_parse.normalizeHotkey;
-exports.normalizeHotkeyFromEvent = require_parse.normalizeHotkeyFromEvent;
-exports.normalizeHotkeyFromParsed = require_parse.normalizeHotkeyFromParsed;
-exports.normalizeKeyName = require_constants.normalizeKeyName;
-exports.normalizeRegisterableHotkey = require_parse.normalizeRegisterableHotkey;
-exports.parseHotkey = require_parse.parseHotkey;
-exports.parseKeyboardEvent = require_parse.parseKeyboardEvent;
-exports.rawHotkeyToParsedHotkey = require_parse.rawHotkeyToParsedHotkey;
-exports.resolveModifier = require_constants.resolveModifier;
-exports.toHotkeyRegistrationView = require_hotkey_manager.toHotkeyRegistrationView;
-exports.validateHotkey = require_validate.validateHotkey;

package/dist/index.d.cts

@@ -1,13 +0,0 @@
-import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult } from "./hotkey.cjs";
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.cjs";
-import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.cjs";
-import { ConflictBehavior } from "./manager.utils.cjs";
-import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.cjs";
-import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.cjs";
-import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.cjs";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.cjs";
-import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./hotkey-recorder.cjs";
-import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager } from "./sequence-manager.cjs";
-import { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState } from "./hotkey-sequence-recorder.cjs";
-import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.cjs";
-export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, WINDOWS_MODIFIER_LABELS, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };