@tanstack/hotkeys 0.7.1 → 0.9.0

package/dist/hotkey-recorder.js

@@ -1,6 +1,11 @@
-import { detectPlatform } from "./constants.js";
-import { isInputElement } from "./manager.utils.js";
-import { hotkeyChordFromKeydown } from "./recorder-chord.js";
+import { detectPlatform } from "./platform.js";
+import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isModifierKey, parseHotkey } from "./parse.js";
+import { validateHotkey } from "./validate.js";
+import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
+import { shouldIgnoreInputEvent } from "./_event-target.js";
+import { findHotkeyConflicts } from "./conflicts.js";
+import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-recorder.ts
@@ -14,7 +19,7 @@ import { Store } from "@tanstack/store";
 * 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 `useStore` hooks for reactive state
+* - When using framework adapters (React), use `useSelector` hooks for reactive state
 *
 * @example
 * ```ts
@@ -74,31 +79,80 @@ var HotkeyRecorder = class {
 	*/
 	start() {
 		if (this.#keydownHandler) return;
+		beginRecording(this);
 		this.store.setState(() => ({
 			isRecording: true,
 			recordedHotkey: null
 		}));
 		const handler = (event) => {
 			if (!this.#keydownHandler) return;
-			if (this.#options.ignoreInputs !== false) {
-				if (isInputElement(typeof document !== "undefined" ? document.activeElement : null) && event.key !== "Escape") return;
-			}
+			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) {
-					this.#options.onClear?.();
-					this.#options.onRecord("");
 					this.stop();
+					this.#options.onClear?.();
 					return;
 				}
 			}
-			const finalHotkey = hotkeyChordFromKeydown(event, this.#platform);
+			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;
+			}
+			const accepted = this.#options.validate?.(finalHotkey, {
+				event,
+				parsedHotkey: parseHotkey(finalHotkey, platform)
+			});
+			if (accepted !== void 0 && accepted !== true) {
+				this.#options.onReject?.({
+					reason: "validation",
+					message: typeof accepted === "string" ? accepted : "This shortcut is not allowed.",
+					hotkey: finalHotkey
+				});
+				return;
+			}
+			if (this.#options.detectConflicts) {
+				const conflicts = findHotkeyConflicts(finalHotkey, {
+					...typeof this.#options.detectConflicts === "object" ? this.#options.detectConflicts : {},
+					platform,
+					events: [event]
+				});
+				if (conflicts.length) {
+					this.#options.onReject?.({
+						reason: "conflict",
+						message: "This shortcut conflicts with a registered binding.",
+						hotkey: finalHotkey,
+						conflicts
+					});
+					return;
+				}
+			}
+			endRecording(this);
 			const handlerToRemove = this.#keydownHandler;
 			if (handlerToRemove) {
 				this.#removeListener(handlerToRemove);
@@ -119,6 +173,7 @@ var HotkeyRecorder = class {
 	* Removes the event listener and resets the recording state.
 	*/
 	stop() {
+		endRecording(this);
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;
@@ -135,6 +190,7 @@ var HotkeyRecorder = class {
 	* the onCancel callback if provided.
 	*/
 	cancel() {
+		endRecording(this);
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;

package/dist/hotkey-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { isInputElement } from './manager.utils'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\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 hotkey recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\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      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAI,MAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKA,UAAW;AAChB,QAAKC,WAAY,gBAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKD,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKE,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAMF,OAAI,MAAKF,QAAS,iBAAiB,OAGjC;QAAI,eADF,OAAO,aAAa,cAAc,SAAS,gBAAgB,KACjC,IAAI,MAAM,QAAQ,SAC5C;;AAIJ,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKA,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;GAIJ,MAAM,cAAc,uBAAuB,OAAO,MAAKC,SAAU;AACjE,OAAI,gBAAgB,KAClB;GAIF,MAAM,kBAAkB,MAAKC;AAG7B,OAAI,iBAAiB;AACnB,UAAKC,eAAgB,gBAAgB;AACrC,UAAKD,iBAAkB;;AAIzB,QAAK,MAAM,gBAAgB;IACzB,aAAa;IACb,gBAAgB;IACjB,EAAE;AAGH,SAAKF,QAAS,SAAS,YAAY;;AAGrC,QAAKE,iBAAkB;AACvB,QAAKE,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKF,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKF,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}
+{"version":3,"file":"hotkey-recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { findHotkeyConflicts } from './conflicts'\nimport {\n  beginRecording,\n  captureRecordingEvent,\n  endRecording,\n} from './_recording-guard'\nimport { chordRejection, hotkeyChordFromKeydown } from './_recorder-chord'\nimport { normalizeKeyboardEvent } from './_keyboard-event'\nimport { isModifierKey, parseHotkey } from './parse'\nimport { validateHotkey } from './validate'\nimport { detectPlatform } from './platform'\nimport { shouldIgnoreInputEvent } from './_event-target'\nimport type {\n  HotkeyRecorderValidationContext,\n  RecorderOptions,\n} from './recorder-options'\nimport type { Hotkey } from './hotkey.types'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions extends RecorderOptions {\n  /** Return true to accept, or false/a message to reject while staying in recording mode. */\n  validate?: (\n    hotkey: Hotkey,\n    context: HotkeyRecorderValidationContext,\n  ) => boolean | string\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\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 hotkey recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useSelector` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    beginRecording(this)\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\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 (\n        this.#options.ignoreInputs !== false &&\n        event.key !== 'Escape' &&\n        shouldIgnoreInputEvent(event, document, document)\n      )\n        return\n\n      const platform = this.#options.platform ?? this.#platform\n      if (normalizeKeyboardEvent(event, platform).isComposing) return\n      captureRecordingEvent(event)\n      event.preventDefault()\n      event.stopPropagation()\n      if (event.repeat) return\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.stop()\n          this.#options.onClear?.()\n          return\n        }\n      }\n\n      if (isModifierKey(event.key) || event.key === 'AltGraph') return\n      const rejection = chordRejection(event, { ...this.#options, platform })\n      if (rejection) {\n        this.#options.onReject?.(rejection)\n        return\n      }\n      const finalHotkey = hotkeyChordFromKeydown(\n        event,\n        platform,\n        this.#options.recordBy,\n      )\n      if (finalHotkey === null) {\n        return\n      }\n\n      const validation = validateHotkey(finalHotkey)\n      if (!validation.valid) {\n        this.#options.onReject?.({\n          reason: 'invalid',\n          message: validation.errors.join('; '),\n          hotkey: finalHotkey,\n        })\n        return\n      }\n      const accepted = this.#options.validate?.(finalHotkey, {\n        event,\n        parsedHotkey: parseHotkey(finalHotkey, platform),\n      })\n      if (accepted !== undefined && accepted !== true) {\n        this.#options.onReject?.({\n          reason: 'validation',\n          message:\n            typeof accepted === 'string'\n              ? accepted\n              : 'This shortcut is not allowed.',\n          hotkey: finalHotkey,\n        })\n        return\n      }\n      if (this.#options.detectConflicts) {\n        const conflicts = findHotkeyConflicts(finalHotkey, {\n          ...(typeof this.#options.detectConflicts === 'object'\n            ? this.#options.detectConflicts\n            : {}),\n          platform,\n          events: [event],\n        })\n        if (conflicts.length) {\n          this.#options.onReject?.({\n            reason: 'conflict',\n            message: 'This shortcut conflicts with a registered binding.',\n            hotkey: finalHotkey,\n            conflicts,\n          })\n          return\n        }\n      }\n      endRecording(this)\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    endRecording(this)\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    endRecording(this)\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":"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"}

package/dist/hotkey-sequence-recorder.cjs

@@ -1,6 +1,11 @@
-const require_constants = require('./constants.cjs');
-const require_manager_utils = require('./manager.utils.cjs');
-const require_recorder_chord = require('./recorder-chord.cjs');
+const require_platform = require('./platform.cjs');
+const require__keyboard_event = require('./_keyboard-event.cjs');
+const require_parse = require('./parse.cjs');
+const require_validate = require('./validate.cjs');
+const require__recording_guard = require('./_recording-guard.cjs');
+const require__event_target = require('./_event-target.cjs');
+const require_conflicts = require('./conflicts.cjs');
+const require__recorder_chord = require('./_recorder-chord.cjs');
 let _tanstack_store = require("@tanstack/store");
 
 //#region src/hotkey-sequence-recorder.ts
@@ -8,6 +13,7 @@ const defaultHotkeySequenceRecorderOptions = {
 	commitOnEnter: true,
 	commitKeys: "enter"
 };
+/** Resolves the Enter policy, with commitKeys: none overriding the legacy boolean. */
 function resolvedCommitOnEnter(options) {
 	if (options.commitKeys === "none") return false;
 	return options.commitOnEnter !== false;
@@ -23,6 +29,7 @@ var HotkeySequenceRecorder = class {
 	#keydownHandler = null;
 	#options;
 	#platform;
+	#events = [];
 	#idleTimer = null;
 	constructor(options) {
 		this.store = new _tanstack_store.Store({
@@ -34,8 +41,9 @@ var HotkeySequenceRecorder = class {
 			...defaultHotkeySequenceRecorderOptions,
 			...options
 		};
-		this.#platform = require_constants.detectPlatform();
+		this.#platform = require_platform.detectPlatform();
 	}
+	/** Merges current callbacks and options without discarding recorded steps. */
 	setOptions(options) {
 		this.#options = {
 			...defaultHotkeySequenceRecorderOptions,
@@ -43,12 +51,14 @@ var HotkeySequenceRecorder = class {
 			...options
 		};
 	}
+	/** Cancels a pending idle commit so it cannot fire after editing or stopping. */
 	#clearIdleTimer() {
 		if (this.#idleTimer !== null) {
 			clearTimeout(this.#idleTimer);
 			this.#idleTimer = null;
 		}
 	}
+	/** Restarts optional idle commit after a step is recorded or edited. */
 	#scheduleIdleTimer() {
 		this.#clearIdleTimer();
 		const ms = this.#options.idleTimeoutMs;
@@ -60,15 +70,19 @@ var HotkeySequenceRecorder = class {
 			if (this.store.state.steps.length >= 1) this.commit();
 		}, ms);
 	}
+	/** Publishes edited steps while preserving the remaining recorder state. */
 	#patchSteps(updater) {
 		this.store.setState((s) => ({
 			...s,
 			steps: updater(s.steps)
 		}));
 	}
+	/** Starts a fresh recording; repeated starts during an active session are ignored. */
 	start() {
 		if (this.#keydownHandler) return;
 		this.#clearIdleTimer();
+		this.#events = [];
+		require__recording_guard.beginRecording(this);
 		this.store.setState(() => ({
 			isRecording: true,
 			steps: [],
@@ -76,11 +90,13 @@ var HotkeySequenceRecorder = class {
 		}));
 		const handler = (event) => {
 			if (!this.#keydownHandler) return;
-			if (this.#options.ignoreInputs !== false) {
-				if (require_manager_utils.isInputElement(typeof document !== "undefined" ? document.activeElement : null) && event.key !== "Escape") return;
-			}
+			if (this.#options.ignoreInputs !== false && event.key !== "Escape" && require__event_target.shouldIgnoreInputEvent(event, document, document)) return;
+			const platform = this.#options.platform ?? this.#platform;
+			if (require__keyboard_event.normalizeKeyboardEvent(event, platform).isComposing) return;
+			require__recording_guard.captureRecordingEvent(event);
 			event.preventDefault();
 			event.stopPropagation();
+			if (event.repeat) return;
 			if (event.key === "Escape") {
 				this.cancel();
 				return;
@@ -88,11 +104,11 @@ var HotkeySequenceRecorder = class {
 			if (event.key === "Backspace" || event.key === "Delete") {
 				if (!event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey) {
 					if (this.store.state.steps.length === 0) {
+						this.stop();
 						this.#options.onClear?.();
-						this.#options.onRecord([]);
-						this.#finishWithoutCommitCallback();
 						return;
 					}
+					this.#events.pop();
 					this.#patchSteps((prev) => prev.slice(0, -1));
 					if (this.store.state.steps.length === 0) this.#clearIdleTimer();
 					else this.#scheduleIdleTimer();
@@ -105,8 +121,27 @@ var HotkeySequenceRecorder = class {
 				return;
 			}
 			if (enterCommits && this.store.state.steps.length === 0) return;
-			const finalHotkey = require_recorder_chord.hotkeyChordFromKeydown(event, this.#platform);
+			if (require_parse.isModifierKey(event.key) || event.key === "AltGraph") return;
+			const rejection = require__recorder_chord.chordRejection(event, {
+				...this.#options,
+				platform
+			});
+			if (rejection) {
+				this.#options.onReject?.(rejection);
+				return;
+			}
+			const finalHotkey = require__recorder_chord.hotkeyChordFromKeydown(event, platform, this.#options.recordBy);
 			if (finalHotkey === null) return;
+			const validation = require_validate.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();
 		};
@@ -120,6 +155,38 @@ var HotkeySequenceRecorder = class {
 		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) => require_parse.parseHotkey(step, platform))
+		});
+		if (accepted !== void 0 && 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 = require_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;
+			}
+		}
+		require__recording_guard.endRecording(this);
+		this.#events = [];
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;
@@ -132,19 +199,10 @@ var HotkeySequenceRecorder = class {
 		}));
 		this.#options.onRecord(sequence);
 	}
-	#finishWithoutCommitCallback() {
-		if (this.#keydownHandler) {
-			this.#removeListener(this.#keydownHandler);
-			this.#keydownHandler = null;
-		}
-		this.#clearIdleTimer();
-		this.store.setState(() => ({
-			isRecording: false,
-			steps: [],
-			recordedSequence: null
-		}));
-	}
+	/** Stops and discards in-progress steps without invoking onCancel. */
 	stop() {
+		require__recording_guard.endRecording(this);
+		this.#events = [];
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;
@@ -156,7 +214,10 @@ var HotkeySequenceRecorder = class {
 			recordedSequence: null
 		}));
 	}
+	/** Stops, discards in-progress steps, and notifies onCancel. */
 	cancel() {
+		require__recording_guard.endRecording(this);
+		this.#events = [];
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;
@@ -169,10 +230,12 @@ var HotkeySequenceRecorder = class {
 		}));
 		this.#options.onCancel?.();
 	}
+	/** Captures keydowns before application handlers, with an SSR-safe document check. */
 	#addListener(handler) {
 		if (typeof document === "undefined") return;
 		document.addEventListener("keydown", handler, true);
 	}
+	/** Detaches the capture listener when recording ends. */
 	#removeListener(handler) {
 		if (typeof document === "undefined") return;
 		document.removeEventListener("keydown", handler, true);

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

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

@@ -1,4 +1,5 @@
 import { HotkeySequence } from "./sequence-manager.cjs";
+import { HotkeySequenceRecorderValidationContext, RecorderOptions } from "./recorder-options.cjs";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-sequence-recorder.d.ts
@@ -22,8 +23,10 @@ interface HotkeySequenceRecorderState {
 /**
  * Options for configuring a HotkeySequenceRecorder instance.
  */
-interface HotkeySequenceRecorderOptions {
-  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+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;
@@ -64,13 +67,17 @@ declare class HotkeySequenceRecorder {
   #private;
   readonly store: Store<HotkeySequenceRecorderState>;
   constructor(options: HotkeySequenceRecorderOptions);
+  /** Merges current callbacks and options without discarding recorded steps. */
   setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
+  /** Starts a fresh recording; repeated starts during an active session are ignored. */
   start(): void;
   /**
    * Commit the current steps as a sequence. No-op if fewer than one step.
    */
   commit(): void;
+  /** Stops and discards in-progress steps without invoking onCancel. */
   stop(): void;
+  /** Stops, discards in-progress steps, and notifies onCancel. */
   cancel(): void;
   destroy(): void;
 }

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

@@ -1,4 +1,5 @@
 import { HotkeySequence } from "./sequence-manager.js";
+import { HotkeySequenceRecorderValidationContext, RecorderOptions } from "./recorder-options.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-sequence-recorder.d.ts
@@ -22,8 +23,10 @@ interface HotkeySequenceRecorderState {
 /**
  * Options for configuring a HotkeySequenceRecorder instance.
  */
-interface HotkeySequenceRecorderOptions {
-  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+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;
@@ -64,13 +67,17 @@ declare class HotkeySequenceRecorder {
   #private;
   readonly store: Store<HotkeySequenceRecorderState>;
   constructor(options: HotkeySequenceRecorderOptions);
+  /** Merges current callbacks and options without discarding recorded steps. */
   setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
+  /** Starts a fresh recording; repeated starts during an active session are ignored. */
   start(): void;
   /**
    * Commit the current steps as a sequence. No-op if fewer than one step.
    */
   commit(): void;
+  /** Stops and discards in-progress steps without invoking onCancel. */
   stop(): void;
+  /** Stops, discards in-progress steps, and notifies onCancel. */
   cancel(): void;
   destroy(): void;
 }