@tanstack/hotkeys 0.15.0 → 0.16.0

package/dist/hotkey-manager.js

@@ -1,14 +1,15 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
+import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
-import { matchKeyboardEvent } from "./_match.js";
+import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
 import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { TargetListeners } from "./_target-listeners.js";
+import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
-import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
+import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
@@ -24,7 +25,7 @@ function toHotkeyRegistrationView(reg) {
 		...base,
 		kind: "chord",
 		hotkey: reg.hotkey,
-		parsedHotkey: reg.parsedHotkey,
+		parsedChord: reg.parsedChord,
 		options: reg.options
 	};
 	const length = reg.parsedSequence.length;
@@ -40,6 +41,10 @@ function toHotkeyRegistrationView(reg) {
 	};
 }
 let registrationIdCounter = 0;
+/** The string a chord registers as: strings as written, objects formatted from their parsed form. */
+function chordString(chord, parsed) {
+	return typeof chord === "string" ? chord : formatHotkey(parsed);
+}
 /**
 * Generates a unique ID for hotkey registrations.
 */
@@ -57,7 +62,7 @@ function optionsForKind(kind, options) {
 }
 /** Steps with Mod already resolved for the registration's platform. */
 function resolvedSteps(registration) {
-	return registration.kind === "chord" ? [registration.parsedHotkey] : registration.parsedSequence;
+	return registration.kind === "chord" ? [registration.parsedChord] : registration.parsedSequence;
 }
 /** Whether a registration skips keys that focused controls use, resolving `'auto'`. */
 function ignoresInputs(registration) {
@@ -65,7 +70,7 @@ function ignoresInputs(registration) {
 	return ignoreInputs === "auto" ? getDefaultIgnoreInputs(resolvedSteps(registration)[0]) : ignoreInputs;
 }
 function sameResolvedSteps(left, right) {
-	return left.length === right.length && left.every((step, index) => areHotkeysEqual(step, right[index]));
+	return left.length === right.length && left.every((step, index) => parsedChordsEqual(step, right[index]));
 }
 function formatForMessage(hotkey) {
 	return isHotkeySequence(hotkey) ? hotkey.join(" ") : hotkey;
@@ -97,7 +102,6 @@ function formatForMessage(hotkey) {
 * ```
 */
 var HotkeyManager = class HotkeyManager {
-	static #instance = null;
 	/**
 	* The TanStack Store containing all hotkey registrations, chords and sequences.
 	* Use this to subscribe to registration changes or access current registrations.
@@ -123,12 +127,27 @@ var HotkeyManager = class HotkeyManager {
 	* devtools can list declared hotkeys that are not registered.
 	*/
 	appHotkeys = new Store(null);
+	/** Active scopes. Subscribe to show which hotkeys are suspended. */
+	scopes = new Store({
+		active: [],
+		exclusive: null,
+		allowed: [],
+		suspended: []
+	});
 	#platform;
+	#scopeActivations = /* @__PURE__ */ new Set();
+	#scopeActivationCount = 0;
+	/** Active scopes, lowest precedence first, derived from activations. */
+	#scopeOrder = [];
+	/** Scopes that can fire while a scope is exclusive, or `null` when none is. */
+	#liveScopes = null;
 	#listeners = new TargetListeners((...args) => this.#processTargetEvent(...args));
 	/** Events that continue a sequence in progress, decided before any listener runs. */
 	#sequenceOwned = /* @__PURE__ */ new WeakMap();
 	/** Physical keys whose keydown a sequence owned, so their repeats and keyup are owned too. */
 	#sequenceOwnedKeys = /* @__PURE__ */ new Set();
+	/** Timers that clear a sequence's progress once its timeout passes. */
+	#sequenceResetTimers = /* @__PURE__ */ new Map();
 	constructor() {
 		this.#platform = detectPlatform();
 	}
@@ -136,17 +155,122 @@ var HotkeyManager = class HotkeyManager {
 	* Gets the singleton instance of HotkeyManager.
 	*/
 	static getInstance() {
-		if (!HotkeyManager.#instance) HotkeyManager.#instance = new HotkeyManager();
-		return HotkeyManager.#instance;
+		return managerRef.current ??= new HotkeyManager();
 	}
 	/**
 	* Resets the singleton instance. Useful for testing.
 	*/
 	static resetInstance() {
-		if (HotkeyManager.#instance) {
-			HotkeyManager.#instance.destroy();
-			HotkeyManager.#instance = null;
+		managerRef.current?.destroy();
+		managerRef.current = null;
+	}
+	/**
+	* Activates a scope until the returned function is called. Activations are
+	* counted, so a scope stays active until every activation is released.
+	* Framework providers call this while mounted.
+	*
+	* When active scopes share a hotkey, a nested scope takes precedence over
+	* its ancestors, and otherwise the most recently activated scope wins. The
+	* same order picks the exclusive scope when several are active, and only
+	* that scope's `allow` list applies.
+	*
+	* @example
+	* ```ts
+	* const release = manager.activateScope('dialog', { exclusive: true })
+	* // Only hotkeys with scope 'dialog', or scopes nested in it, fire now.
+	* release()
+	*
+	* manager.activateScope('dialog', { exclusive: { allow: ['global'] } })
+	* // Hotkeys with scope 'global' fire too.
+	* ```
+	*/
+	activateScope(scope, options = {}) {
+		if (scope === "global") return () => {};
+		const { exclusive } = options;
+		const allow = exclusive ? exclusive === true ? [] : exclusive.allow : null;
+		if (allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`Exclusive hotkey scope '${scope}' is already active. Hotkeys from both activations will fire; give each a unique scope.`);
+		const activation = {
+			scope,
+			parent: options.parent ?? "global",
+			allow,
+			order: ++this.#scopeActivationCount
+		};
+		this.#scopeActivations.add(activation);
+		this.#updateScopes();
+		return () => {
+			if (this.#scopeActivations.delete(activation)) this.#updateScopes();
+		};
+	}
+	/**
+	* Whether hotkeys in a scope can fire: the scope is `'global'` or
+	* activated, and either no scope is exclusive or this scope is the
+	* exclusive one, nested in it, or allowed by it.
+	*/
+	isScopeActive(scope = GLOBAL_SCOPE) {
+		if (this.#liveScopes) return this.#liveScopes.has(scope);
+		return scope === "global" || this.#scopeOrder.includes(scope);
+	}
+	/** Higher for scopes with higher precedence; `'global'` is 0. */
+	#scopeRank(scope = GLOBAL_SCOPE) {
+		return this.#scopeOrder.indexOf(scope) + 1;
+	}
+	/** Recomputes scope precedence and publishes it. */
+	#updateScopes() {
+		const parents = /* @__PURE__ */ new Map();
+		const latest = /* @__PURE__ */ new Map();
+		for (const activation of this.#scopeActivations) {
+			parents.set(activation.scope, activation.parent);
+			latest.set(activation.scope, Math.max(latest.get(activation.scope) ?? 0, activation.order));
+		}
+		const depth = (scope) => {
+			let result = 0;
+			const seen = /* @__PURE__ */ new Set();
+			for (let current = parents.get(scope); current !== void 0 && !seen.has(current); current = parents.get(current)) {
+				seen.add(current);
+				result++;
+			}
+			return result;
+		};
+		const since = /* @__PURE__ */ new Map();
+		for (const [scope, order] of latest) {
+			const seen = /* @__PURE__ */ new Set();
+			for (let current = scope; current !== void 0 && !seen.has(current); current = parents.get(current)) {
+				seen.add(current);
+				const own = latest.get(current);
+				if (own !== void 0) since.set(current, Math.min(since.get(current) ?? own, order));
+			}
+		}
+		const compare = (a, b) => since.get(a) - since.get(b) || depth(a) - depth(b) || latest.get(a) - latest.get(b);
+		this.#scopeOrder = [...latest.keys()].sort(compare);
+		const exclusive = [...this.#scopeActivations].filter((activation) => activation.allow).sort((a, b) => compare(a.scope, b.scope) || a.order - b.order).pop();
+		const activated = [GLOBAL_SCOPE, ...this.#scopeOrder];
+		let allowed = [];
+		this.#liveScopes = null;
+		if (exclusive?.allow) {
+			const { allow } = exclusive;
+			const isNested = (scope) => {
+				const seen = /* @__PURE__ */ new Set();
+				for (let current = scope; current !== void 0 && !seen.has(current); current = parents.get(current)) {
+					if (current === exclusive.scope) return true;
+					seen.add(current);
+				}
+				return false;
+			};
+			allowed = activated.filter((scope) => !isNested(scope) && allow.includes(scope));
+			this.#liveScopes = /* @__PURE__ */ new Set([...activated.filter(isNested), ...allowed]);
 		}
+		const live = this.#liveScopes;
+		this.scopes.setState(() => ({
+			active: this.#scopeOrder,
+			exclusive: exclusive?.scope ?? null,
+			allowed,
+			suspended: live ? activated.filter((scope) => !live.has(scope)) : []
+		}));
+		this.#notify();
+	}
+	/** Whether a registration can fire now: enabled, in an active scope. */
+	#isLive(registration) {
+		return registration.options.enabled !== false && this.isScopeActive(registration.options.scope);
 	}
 	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
 	#notify() {
@@ -175,44 +299,39 @@ var HotkeyManager = class HotkeyManager {
 		const id = generateId();
 		const platform = options.platform ?? this.#platform;
 		const target = options.target ?? document;
-		let registration;
-		if (isHotkeySequence(hotkey)) registration = {
-			kind: "sequence",
+		const sequence = isHotkeySequence(hotkey);
+		const common = {
 			id,
-			hotkey,
-			parsedSequence: hotkey.map((step) => parseHotkey(step, platform)),
 			callback,
 			options: {
 				...defaultHotkeyOptions,
-				timeout: DEFAULT_SEQUENCE_TIMEOUT,
-				...optionsForKind("sequence", options),
+				...sequence ? { timeout: DEFAULT_SEQUENCE_TIMEOUT } : { requireReset: false },
+				...optionsForKind(sequence ? "sequence" : "chord", options),
 				platform,
 				ignoreInputs: options.ignoreInputs ?? "auto"
 			},
 			target,
-			currentIndex: 0,
-			lastKeyTime: 0,
 			triggerCount: 0,
 			hasFired: false
 		};
-		else {
-			const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
+		let registration;
+		if (sequence) {
+			const parsedSequence = parseHotkey(hotkey, platform);
 			registration = {
+				...common,
+				kind: "sequence",
+				hotkey: hotkey.map((step, index) => chordString(step, parsedSequence[index])),
+				parsedSequence,
+				currentIndex: 0,
+				lastKeyTime: 0
+			};
+		} else {
+			const parsedChord = parseHotkey(hotkey, platform);
+			registration = {
+				...common,
 				kind: "chord",
-				id,
-				hotkey: typeof hotkey === "string" ? hotkey : formatHotkey(parsedHotkey),
-				parsedHotkey,
-				callback,
-				options: {
-					...defaultHotkeyOptions,
-					requireReset: false,
-					...optionsForKind("chord", options),
-					platform,
-					ignoreInputs: options.ignoreInputs ?? "auto"
-				},
-				target,
-				hasFired: false,
-				triggerCount: 0
+				hotkey: chordString(hotkey, parsedChord),
+				parsedChord
 			};
 		}
 		const conflicting = this.#findConflictingRegistration(registration);
@@ -272,6 +391,35 @@ var HotkeyManager = class HotkeyManager {
 			return next;
 		});
 		this.#listeners.remove(target, !!registration.options.capture, id);
+		this.#clearSequenceReset(id);
+	}
+	/**
+	* Clears a sequence's progress, and notifies subscribers, once its timeout
+	* passes without another step. Key presses check the timeout too, so this
+	* only keeps views such as `matchedStepCount` current.
+	*/
+	#scheduleSequenceReset(id, delay) {
+		this.#clearSequenceReset(id);
+		this.#sequenceResetTimers.set(id, setTimeout(() => {
+			this.#sequenceResetTimers.delete(id);
+			const registration = this.registrations.state.get(id);
+			if (registration?.kind !== "sequence" || registration.currentIndex === 0) return;
+			const timeout = registration.options.timeout ?? 1e3;
+			const remaining = registration.lastKeyTime + timeout - Date.now();
+			if (remaining >= 0) {
+				this.#scheduleSequenceReset(id, remaining + 1);
+				return;
+			}
+			registration.currentIndex = 0;
+			registration.lastKeyTime = 0;
+			this.#notify();
+		}, delay));
+	}
+	#clearSequenceReset(id) {
+		const timer = this.#sequenceResetTimers.get(id);
+		if (timer === void 0) return;
+		clearTimeout(timer);
+		this.#sequenceResetTimers.delete(id);
 	}
 	/** Registrations of one kind in the listener phase, in registration order. */
 	#registrationsIn(ids, capture, kind) {
@@ -308,30 +456,31 @@ var HotkeyManager = class HotkeyManager {
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
-			const result = matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
+			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
 			if (result.matched) {
 				matches.set(registration.id, result);
 				bestScore = Math.max(bestScore, result.score);
 			}
 		}
+		let bestRank = -1;
+		for (const registration of registrations) if (matches.get(registration.id)?.score === bestScore) bestRank = Math.max(bestRank, this.#scopeRank(registration.options.scope));
 		for (const snapshot of registrations) {
 			const match = matches.get(snapshot.id);
-			if (!match?.matched || match.score !== bestScore) continue;
+			if (!match?.matched || match.score !== bestScore || this.#scopeRank(snapshot.options.scope) !== bestRank) continue;
 			const registration = this.#currentIn(snapshot, capture);
 			if (!registration) continue;
+			this.#consume(registration, event);
 			if (eventType === "keyup") {
-				this.#executeCallback(registration, event);
+				this.#fire(registration, event);
 				continue;
 			}
-			if (registration.options.preventDefault) event.preventDefault();
-			if (registration.options.stopPropagation) event.stopPropagation();
 			if (!registration.options.requireReset || !registration.hasFired) {
 				if (registration.options.requireReset) {
 					registration.hasFired = true;
 					registration.activeMatch = match.identity;
 				}
-				this.#executeCallback(registration, event);
+				this.#fire(registration, event);
 			}
 		}
 	}
@@ -357,7 +506,7 @@ var HotkeyManager = class HotkeyManager {
 		const path = event.composedPath();
 		const now = Date.now();
 		for (const registration of this.registrations.state.values()) {
-			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !registration.options.enabled || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
+			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
 			const target = registration.target;
 			if (path.includes(target.nodeType === 1 ? target : getTargetDocument(target)) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
 		}
@@ -369,6 +518,7 @@ var HotkeyManager = class HotkeyManager {
 			let changed = false;
 			for (const registration of registrations) if (registration.currentIndex > 0) {
 				registration.currentIndex = 0;
+				this.#clearSequenceReset(registration.id);
 				changed = true;
 			}
 			if (changed) this.#notify();
@@ -381,7 +531,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!isEventForTarget(event, target) || !registration.options.enabled || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
+			if (!isEventForTarget(event, target) || !this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -410,67 +560,69 @@ var HotkeyManager = class HotkeyManager {
 				registration.currentIndex = candidate.nextIndex;
 				changed = true;
 				if (registration.currentIndex >= registration.parsedSequence.length) {
-					if (registration.options.preventDefault) event.preventDefault();
-					if (registration.options.stopPropagation) event.stopPropagation();
+					this.#consume(registration, event);
 					registration.currentIndex = 0;
 					completed.push(registration);
-				}
+				} else if (registration.options.preventDefault) event.preventDefault();
 			} else if (registration.currentIndex > 0) {
 				registration.currentIndex = 0;
 				changed = true;
 			}
 		}
+		for (const registration of registrations) {
+			if (!candidates.has(registration.id)) continue;
+			if (registration.currentIndex > 0) {
+				const timeout = registration.options.timeout ?? 1e3;
+				this.#scheduleSequenceReset(registration.id, timeout + 1);
+			} else this.#clearSequenceReset(registration.id);
+		}
 		if (changed && completed.length === 0) this.#notify();
 		for (const snapshot of completed) {
 			const registration = this.#currentIn(snapshot, capture);
-			if (registration) this.#executeCallback(registration, event);
+			if (registration) this.#fire(registration, event);
 		}
 	}
-	/**
-	* Executes a hotkey callback with proper event handling.
-	*/
-	#executeCallback(registration, event) {
+	/** Applies a matched registration's preventDefault and stopPropagation options. */
+	#consume(registration, event) {
 		if (registration.options.preventDefault) event.preventDefault();
 		if (registration.options.stopPropagation) event.stopPropagation();
+	}
+	/** Counts a trigger, notifies subscribers (such as devtools), and runs the callback. */
+	#fire(registration, event, context = this.#callbackContext(registration)) {
 		registration.triggerCount++;
 		if (registration.kind === "sequence") registration.hasFired = true;
 		this.#notify();
-		registration.callback(event, this.#callbackContext(registration));
+		registration.callback(event, context);
 	}
 	#callbackContext(registration) {
-		return {
+		return registration.kind === "chord" ? {
+			kind: "chord",
+			hotkey: registration.hotkey,
+			parsedChord: registration.parsedChord
+		} : {
+			kind: "sequence",
 			hotkey: registration.hotkey,
-			parsedHotkey: registration.kind === "chord" ? registration.parsedHotkey : registration.parsedSequence[registration.parsedSequence.length - 1]
+			parsedSequence: registration.parsedSequence
 		};
 	}
 	/**
-	* Finds an existing registration on the same target whose steps resolve to
-	* the same identity. Each side keeps its own platform, so `Mod+S` on macOS
+	* Finds an existing registration on the same target and scope whose steps
+	* resolve to the same identity. Each side keeps its own platform, so `Mod+S` on macOS
 	* and `Mod+S` on Windows are different bindings.
 	*/
 	#findConflictingRegistration(candidate) {
 		const steps = resolvedSteps(candidate);
-		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
+		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && registration.options.scope === candidate.options.scope && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
 		return null;
 	}
 	/**
 	* Determines if a registration should be reset based on the keyup event.
 	*/
 	#shouldResetRegistration(registration, event) {
-		const parsed = registration.parsedHotkey;
+		const parsed = registration.parsedChord;
 		const releasedKey = normalizeKeyName(event.key);
 		if (registration.activeMatch?.code && event.code === registration.activeMatch.code) return true;
-		if (parsed.code !== void 0) {
-			if (event.code === parsed.code) return true;
-		} else {
-			const parsedKeyNormalized = parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key;
-			if ((releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey) === parsedKeyNormalized) return true;
-		}
-		if (parsed.ctrl && releasedKey === "Control") return true;
-		if (parsed.shift && releasedKey === "Shift") return true;
-		if (parsed.alt && releasedKey === "Alt") return true;
-		if (parsed.meta && releasedKey === "Meta") return true;
-		return false;
+		return (parsed.code !== void 0 ? event.code === parsed.code : keysEqual(releasedKey, parsed.key)) || parsed.modifiers.includes(releasedKey);
 	}
 	/**
 	* Resets the progress of every in-progress sequence.
@@ -480,6 +632,8 @@ var HotkeyManager = class HotkeyManager {
 			registration.currentIndex = 0;
 			registration.lastKeyTime = 0;
 		}
+		for (const timer of this.#sequenceResetTimers.values()) clearTimeout(timer);
+		this.#sequenceResetTimers.clear();
 		this.#notify();
 	}
 	/**
@@ -494,7 +648,7 @@ var HotkeyManager = class HotkeyManager {
 		const registration = this.registrations.state.get(id);
 		if (!registration) return false;
 		const context = this.#callbackContext(registration);
-		const parsed = context.parsedHotkey;
+		const parsed = registration.kind === "chord" ? registration.parsedChord : registration.parsedSequence[registration.parsedSequence.length - 1];
 		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
 			...parsed.code !== void 0 ? { code: parsed.code } : { key: parsed.key },
 			ctrlKey: parsed.ctrl,
@@ -504,10 +658,7 @@ var HotkeyManager = class HotkeyManager {
 			bubbles: true,
 			cancelable: true
 		});
-		registration.triggerCount++;
-		if (registration.kind === "sequence") registration.hasFired = true;
-		this.#notify();
-		registration.callback(syntheticEvent, context);
+		this.#fire(registration, syntheticEvent, context);
 		return true;
 	}
 	/**
@@ -531,6 +682,8 @@ var HotkeyManager = class HotkeyManager {
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {
+		for (const timer of this.#sequenceResetTimers.values()) clearTimeout(timer);
+		this.#sequenceResetTimers.clear();
 		this.#listeners.destroy();
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
 		this.appHotkeys.setState(() => null);

package/dist/hotkey-recorder.d.ts

@@ -1,7 +1,47 @@
-import { Hotkey, HotkeyChord, HotkeySequence } from "./hotkey.types.js";
-import { HotkeyRecorderValidationContext, RecorderOptions } from "./recorder-options.js";
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } from "./hotkey.types.js";
+import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-recorder.d.ts
+/** Event property used to record a binding. Physical codes are the default. */
+export type RecorderKeyMode = 'code' | 'key';
+export interface RecorderRejection {
+  reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation';
+  message: string;
+  /** The rejected chord or sequence, when one was recorded. */
+  hotkey?: Hotkey;
+  conflicts?: Array<HotkeyConflict>;
+}
+export interface RecorderOptions {
+  /** Physical code recording is the default. Choose key to record logical characters. */
+  recordBy?: RecorderKeyMode;
+  /** Platform used for Mod and AltGraph handling. Defaults to platform detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Opt in to live-registry conflicts, including sequence prefixes. Default: false. */
+  detectConflicts?: boolean | HotkeyConflictOptions;
+  /** Rejected candidates leave recording active. */
+  onReject?: (rejection: RecorderRejection) => void;
+}
+/** Validation context for a recorded chord. */
+export interface HotkeyChordRecorderValidationContext {
+  kind: 'chord';
+  /** The event that recorded the chord. */
+  event: KeyboardEvent;
+  /** The chord with `Mod` resolved for the recorder's platform. */
+  parsedChord: ParsedHotkeyChord;
+}
+/** Validation context for a recorded sequence. */
+export interface HotkeySequenceRecorderValidationContext {
+  kind: 'sequence';
+  /** The event that recorded each step. */
+  events: ReadonlyArray<KeyboardEvent>;
+  /** Each step with `Mod` resolved for the recorder's platform. */
+  parsedSequence: Array<ParsedHotkeyChord>;
+}
+/**
+ * Validation context for a recorded chord or sequence. Narrow with `kind` to
+ * read `parsedChord` or `parsedSequence`.
+ */
+export type HotkeyRecorderValidationContext = HotkeyChordRecorderValidationContext | HotkeySequenceRecorderValidationContext;
 /**
  * State interface for the HotkeyRecorder.
  */
@@ -35,7 +75,7 @@ export interface HotkeyChordRecorderOptions extends HotkeyRecorderBaseOptions {
   /** Maximum number of chords to record. Default: 1 */
   maxSteps?: 1;
   /** Return true to accept, or false/a message to reject while staying in recording mode. */
-  validate?: (hotkey: HotkeyChord, context: HotkeyRecorderValidationContext) => boolean | string;
+  validate?: (hotkey: HotkeyChord, context: HotkeyChordRecorderValidationContext) => boolean | string;
   /** Callback when a chord is successfully recorded */
   onRecord: (hotkey: HotkeyChord) => void;
 }
@@ -83,7 +123,7 @@ export type HotkeyRecorderOptions = HotkeyChordRecorderOptions | HotkeySequenceR
  * })
  *
  * const sequenceRecorder = new HotkeyRecorder({
- *   maxSteps: 3,
+ *   maxSteps: Infinity,
  *   onRecord: (hotkey) => {
  *     console.log('Recorded:', hotkey) // 'Mod+S' or ['G', 'H']
  *   },

package/dist/hotkey-recorder.js

@@ -37,7 +37,7 @@ const initialState = {
 * })
 *
 * const sequenceRecorder = new HotkeyRecorder({
-*   maxSteps: 3,
+*   maxSteps: Infinity,
 *   onRecord: (hotkey) => {
 *     console.log('Recorded:', hotkey) // 'Mod+S' or ['G', 'H']
 *   },
@@ -198,13 +198,17 @@ var HotkeyRecorder = class {
 			}
 			options.onReject?.(rejection);
 		};
-		const parsedSequence = steps.map((step) => parseHotkey(step, platform));
-		const accepted = options.validate?.(hotkey, {
+		const parsedSequence = parseHotkey(steps, platform);
+		const context = steps.length === 1 ? {
+			kind: "chord",
 			event: this.#events[this.#events.length - 1],
-			parsedHotkey: parsedSequence[parsedSequence.length - 1],
+			parsedChord: parsedSequence[0]
+		} : {
+			kind: "sequence",
 			events: [...this.#events],
 			parsedSequence
-		});
+		};
+		const accepted = options.validate?.(hotkey, context);
 		if (accepted !== void 0 && accepted !== true) {
 			rejectAndKeepRecording({
 				reason: "validation",