@tanstack/hotkeys 0.8.0 → 0.10.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
@@ -44,14 +49,18 @@ import { Store } from "@tanstack/store";
 * ```
 */
 var HotkeyRecorder = class {
+	/**
+	* The TanStack Store instance containing the recorder state.
+	* Use this to subscribe to state changes or access current state.
+	*/
+	store = new Store({
+		isRecording: false,
+		recordedHotkey: null
+	});
 	#keydownHandler = null;
 	#options;
 	#platform;
 	constructor(options) {
-		this.store = new Store({
-			isRecording: false,
-			recordedHotkey: null
-		});
 		this.#options = options;
 		this.#platform = detectPlatform();
 	}
@@ -74,31 +83,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 +177,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 +194,7 @@ var HotkeyRecorder = class {
 	* the onCancel callback if provided.
 	*/
 	cancel() {
+		endRecording(this);
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;
@@ -175,5 +235,4 @@ var HotkeyRecorder = class {
 };
 
 //#endregion
-export { HotkeyRecorder };
-//# sourceMappingURL=hotkey-recorder.js.map
+export { HotkeyRecorder };

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

@@ -1,17 +1,17 @@
 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
 /**
  * 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';
+export type HotkeySequenceRecorderCommitKeys = 'enter' | 'none';
 /**
  * State interface for the HotkeySequenceRecorder.
  */
-interface HotkeySequenceRecorderState {
+export interface HotkeySequenceRecorderState {
   /** Whether recording is currently active */
   isRecording: boolean;
   /** Chords captured so far in the current recording session */
@@ -22,8 +22,10 @@ interface HotkeySequenceRecorderState {
 /**
  * Options for configuring a HotkeySequenceRecorder instance.
  */
-interface HotkeySequenceRecorderOptions {
-  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+export interface HotkeySequenceRecorderOptions extends RecorderOptions {
+  /** Validate the completed sequence. Rejection preserves the steps for editing. */
+  validate?: (sequence: HotkeySequence, context: HotkeySequenceRecorderValidationContext) => boolean | string;
+  /** Callback when a sequence is successfully recorded */
   onRecord: (sequence: HotkeySequence) => void;
   /** Optional callback when recording is cancelled (Escape pressed) */
   onCancel?: () => void;
@@ -60,20 +62,22 @@ interface HotkeySequenceRecorderOptions {
  * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
  * **Backspace/Delete** to remove the last step or clear when empty.
  */
-declare class HotkeySequenceRecorder {
+export 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;
 }
-//#endregion
-export { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState };
-//# sourceMappingURL=hotkey-sequence-recorder.d.ts.map
+//#endregion

package/dist/hotkey-sequence-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-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;
@@ -20,22 +26,24 @@ function resolvedCommitOnEnter(options) {
 * **Backspace/Delete** to remove the last step or clear when empty.
 */
 var HotkeySequenceRecorder = class {
+	store = new Store({
+		isRecording: false,
+		steps: [],
+		recordedSequence: null
+	});
 	#keydownHandler = null;
 	#options;
 	#platform;
+	#events = [];
 	#idleTimer = null;
 	constructor(options) {
-		this.store = new Store({
-			isRecording: false,
-			steps: [],
-			recordedSequence: null
-		});
 		this.#options = {
 			...defaultHotkeySequenceRecorderOptions,
 			...options
 		};
 		this.#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 = [];
+		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 (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;
@@ -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 = 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;
+			}
+			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) => 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 = findHotkeyConflicts(sequence, {
+				...typeof this.#options.detectConflicts === "object" ? this.#options.detectConflicts : {},
+				platform,
+				events: this.#events
+			});
+			if (conflicts.length) {
+				this.#options.onReject?.({
+					reason: "conflict",
+					message: "This sequence conflicts with a registered binding.",
+					sequence,
+					conflicts
+				});
+				return;
+			}
+		}
+		endRecording(this);
+		this.#events = [];
 		if (this.#keydownHandler) {
 			this.#removeListener(this.#keydownHandler);
 			this.#keydownHandler = null;
@@ -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() {
+		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() {
+		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);
@@ -188,5 +251,4 @@ var HotkeySequenceRecorder = class {
 };
 
 //#endregion
-export { HotkeySequenceRecorder };
-//# sourceMappingURL=hotkey-sequence-recorder.js.map
+export { HotkeySequenceRecorder };