@tanstack/hotkeys 0.11.0 → 0.12.0

package/dist/hotkey-manager.js

@@ -1,29 +1,42 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { parseHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
+import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent } from "./_match.js";
-import { areHotkeysEqual } from "./match.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
 import { isRecordingEvent } from "./_recording-guard.js";
 import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
-/**
-* Creates a public view from an internal registration,
-* stripping the callback function.
-*/
+/** Creates a public view from an internal registration, stripping the callback. */
 function toHotkeyRegistrationView(reg) {
-	return {
-		hotkey: reg.hotkey,
+	const base = {
 		id: reg.id,
-		options: reg.options,
-		parsedHotkey: reg.parsedHotkey,
 		target: reg.target,
 		triggerCount: reg.triggerCount,
 		hasFired: reg.hasFired
 	};
+	if (reg.kind === "chord") return {
+		...base,
+		kind: "chord",
+		hotkey: reg.hotkey,
+		parsedHotkey: reg.parsedHotkey,
+		options: reg.options
+	};
+	const length = reg.parsedSequence.length;
+	const inProgress = reg.currentIndex > 0 && reg.currentIndex < length;
+	return {
+		...base,
+		kind: "sequence",
+		hotkey: reg.hotkey,
+		parsedSequence: reg.parsedSequence,
+		options: reg.options,
+		matchedStepCount: inProgress ? reg.currentIndex : 0,
+		partialMatchLastKeyTime: inProgress ? reg.lastKeyTime : 0
+	};
 }
 let registrationIdCounter = 0;
 /**
@@ -32,29 +45,55 @@ let registrationIdCounter = 0;
 function generateId() {
 	return `hotkey_${++registrationIdCounter}`;
 }
+/** Drops options that do not apply to a registration's kind. */
+function optionsForKind(kind, options) {
+	if (kind === "chord") {
+		const { timeout: _timeout, ...rest } = options;
+		return rest;
+	}
+	const { requireReset: _requireReset, ...rest } = options;
+	return rest;
+}
+/** Steps with Mod already resolved for the registration's platform. */
+function resolvedSteps(registration) {
+	return registration.kind === "chord" ? [registration.parsedHotkey] : registration.parsedSequence;
+}
+function sameResolvedSteps(left, right) {
+	return left.length === right.length && left.every((step, index) => areHotkeysEqual(step, right[index]));
+}
+function formatForMessage(hotkey) {
+	return isHotkeySequence(hotkey) ? hotkey.join(" ") : hotkey;
+}
 /**
-* Singleton manager for hotkey registrations.
+* Singleton manager for hotkey registrations, including sequences.
 *
-* This class provides a centralized way to register and manage keyboard hotkeys.
-* It uses a single event listener for efficiency, regardless of how many hotkeys
-* are registered.
+* This class provides a centralized way to register and manage keyboard
+* hotkeys. It attaches one keydown and one keyup listener per target,
+* regardless of how many hotkeys are registered.
+*
+* Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
+* pressed within the timeout. Modifier-only events (Shift, Control, Alt, or
+* Meta alone) neither advance nor reset a sequence, so chained modifier chords
+* such as `['Shift+R', 'Shift+T']` work.
 *
 * @example
 * ```ts
 * const manager = HotkeyManager.getInstance()
 *
-* const unregister = manager.register('Mod+S', (event, context) => {
+* const save = manager.register('Mod+S', (event, context) => {
 *   console.log('Save triggered!')
 * })
+* const top = manager.register(['G', 'G'], () => scrollToTop(), { timeout: 500 })
 *
 * // Later, to unregister:
-* unregister()
+* save.unregister()
+* top.unregister()
 * ```
 */
 var HotkeyManager = class HotkeyManager {
 	static #instance = null;
 	/**
-	* The TanStack Store containing all hotkey registrations.
+	* The TanStack Store containing all hotkey registrations, chords and sequences.
 	* Use this to subscribe to registration changes or access current registrations.
 	*
 	* @example
@@ -73,6 +112,11 @@ var HotkeyManager = class HotkeyManager {
 	* ```
 	*/
 	registrations = new Store(/* @__PURE__ */ new Map());
+	/**
+	* The app hotkeys store published by a framework provider, so tools such as
+	* devtools can list declared hotkeys that are not registered.
+	*/
+	appHotkeys = new Store(null);
 	#platform;
 	#targetListeners = /* @__PURE__ */ new Map();
 	#targetRegistrations = /* @__PURE__ */ new Map();
@@ -95,32 +139,13 @@ var HotkeyManager = class HotkeyManager {
 			HotkeyManager.#instance = null;
 		}
 	}
-	/**
-	* Registers a hotkey handler and returns a handle for updating the registration.
-	*
-	* The returned handle allows updating the callback and options without
-	* re-registering, which is useful for avoiding stale closures in React.
-	*
-	* @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object
-	* @param callback - The function to call when the hotkey is pressed
-	* @param options - Options for the hotkey behavior
-	* @returns A handle for managing the registration
-	*
-	* @example
-	* ```ts
-	* const handle = manager.register('Mod+S', callback)
-	*
-	* // Update callback without re-registering (avoids stale closures)
-	* handle.callback = newCallback
-	*
-	* // Update options
-	* handle.setOptions({ enabled: false })
-	*
-	* // Unregister when done
-	* handle.unregister()
-	* ```
-	*/
-	register(hotkey, callback, options = {}) {
+	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
+	#notify() {
+		this.registrations.setState((prev) => new Map(prev));
+	}
+	register(input, callback, options = {}) {
+		const hotkey = simplifyHotkey(input);
+		if (isHotkeySequence(hotkey) && hotkey.length === 0) throw new Error("Sequence must contain at least one hotkey");
 		if (typeof document === "undefined" && !options.target) {
 			let currentCallback = callback;
 			return {
@@ -140,29 +165,51 @@ var HotkeyManager = class HotkeyManager {
 		}
 		const id = generateId();
 		const platform = options.platform ?? this.#platform;
-		const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
-		const hotkeyStr = typeof hotkey === "string" ? hotkey : formatHotkey(parsedHotkey);
 		const target = options.target ?? document;
-		const conflictBehavior = options.conflictBehavior ?? "warn";
-		const conflictingRegistration = this.#findConflictingRegistration(hotkeyStr, target);
-		if (conflictingRegistration) handleConflict(conflictingRegistration.id, hotkeyStr, conflictBehavior, (id) => this.#unregister(id));
-		const resolvedIgnoreInputs = options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey);
-		const registration = {
-			id,
-			hotkey: hotkeyStr,
-			parsedHotkey,
-			callback,
-			options: {
-				...defaultHotkeyOptions,
-				requireReset: false,
-				...options,
-				platform,
-				ignoreInputs: resolvedIgnoreInputs
-			},
-			hasFired: false,
-			triggerCount: 0,
-			target
-		};
+		let registration;
+		if (isHotkeySequence(hotkey)) {
+			const parsedSequence = hotkey.map((step) => parseHotkey(step, platform));
+			registration = {
+				kind: "sequence",
+				id,
+				hotkey,
+				parsedSequence,
+				callback,
+				options: {
+					...defaultHotkeyOptions,
+					timeout: DEFAULT_SEQUENCE_TIMEOUT,
+					...optionsForKind("sequence", options),
+					platform,
+					ignoreInputs: options.ignoreInputs ?? getDefaultIgnoreInputs(parsedSequence[0])
+				},
+				target,
+				currentIndex: 0,
+				lastKeyTime: 0,
+				triggerCount: 0,
+				hasFired: false
+			};
+		} else {
+			const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
+			registration = {
+				kind: "chord",
+				id,
+				hotkey: typeof hotkey === "string" ? hotkey : formatHotkey(parsedHotkey),
+				parsedHotkey,
+				callback,
+				options: {
+					...defaultHotkeyOptions,
+					requireReset: false,
+					...optionsForKind("chord", options),
+					platform,
+					ignoreInputs: options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)
+				},
+				target,
+				hasFired: false,
+				triggerCount: 0
+			};
+		}
+		const conflicting = this.#findConflictingRegistration(registration);
+		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
 		this.registrations.setState((prev) => new Map(prev).set(id, registration));
 		if (!this.#targetRegistrations.has(target)) this.#targetRegistrations.set(target, /* @__PURE__ */ new Set());
 		this.#targetRegistrations.get(target).add(id);
@@ -185,21 +232,16 @@ var HotkeyManager = class HotkeyManager {
 			setOptions: (newOptions) => {
 				manager.registrations.setState((prev) => {
 					const reg = prev.get(id);
-					if (reg && !optionsEqual(reg.options, {
+					if (!reg) return prev;
+					const options = {
 						...reg.options,
-						...newOptions
-					})) {
-						const next = new Map(prev);
-						next.set(id, {
-							...reg,
-							options: {
-								...reg.options,
-								...newOptions
-							}
-						});
-						return next;
-					}
-					return prev;
+						...optionsForKind(reg.kind, newOptions)
+					};
+					if (optionsEqual(reg.options, options)) return prev;
+					return new Map(prev).set(id, {
+						...reg,
+						options
+					});
 				});
 			},
 			get isActive() {
@@ -231,13 +273,13 @@ var HotkeyManager = class HotkeyManager {
 	#ensureListenersForTarget(target) {
 		if (typeof document === "undefined") return;
 		if (this.#targetListeners.has(target)) return;
-		const keydownHandler = this.#createTargetKeyDownHandler(target);
-		const keyupHandler = this.#createTargetKeyUpHandler(target);
-		target.addEventListener("keydown", keydownHandler);
-		target.addEventListener("keyup", keyupHandler);
+		const keydown = (event) => this.#processTargetEvent(event, target, "keydown");
+		const keyup = (event) => this.#processTargetEvent(event, target, "keyup");
+		target.addEventListener("keydown", keydown);
+		target.addEventListener("keyup", keyup);
 		this.#targetListeners.set(target, {
-			keydown: keydownHandler,
-			keyup: keyupHandler
+			keydown,
+			keyup
 		});
 	}
 	/**
@@ -252,94 +294,146 @@ var HotkeyManager = class HotkeyManager {
 		this.#targetListeners.delete(target);
 		this.#targetRegistrations.delete(target);
 	}
+	/** Registrations of one kind on a target, in registration order. */
+	#registrationsOn(target, kind) {
+		const result = [];
+		for (const id of this.#targetRegistrations.get(target) ?? []) {
+			const registration = this.registrations.state.get(id);
+			if (registration?.kind === kind) result.push(registration);
+		}
+		return result;
+	}
 	/**
 	* Processes keyboard events for a specific target and event type.
+	* Chords and sequences match independently; both may fire for one event.
 	*/
 	#processTargetEvent(event, target, eventType) {
-		if (eventType === "keyup") for (const id of this.#targetRegistrations.get(target) ?? []) {
-			const registration = this.registrations.state.get(id);
-			if (registration?.hasFired && this.#shouldResetRegistration(registration, event)) {
+		this.#processChords(event, target, eventType);
+		this.#processSequences(event, target, eventType);
+	}
+	#processChords(event, target, eventType) {
+		const registrations = this.#registrationsOn(target, "chord");
+		if (eventType === "keyup") {
+			for (const registration of registrations) if (registration.hasFired && this.#shouldResetRegistration(registration, event)) {
 				registration.hasFired = false;
 				registration.activeMatch = void 0;
 			}
 		}
 		if (isRecordingEvent(event)) return;
-		const targetRegs = this.#targetRegistrations.get(target);
-		if (!targetRegs) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
-		for (const id of targetRegs) {
-			const registration = this.registrations.state.get(id);
-			if (!registration || !registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+		for (const registration of registrations) {
+			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target)) continue;
 			const result = matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
 			if (result.matched) {
-				matches.set(id, result);
+				matches.set(registration.id, result);
 				bestScore = Math.max(bestScore, result.score);
 			}
 		}
-		for (const id of targetRegs) {
-			const registration = this.registrations.state.get(id);
-			if (!registration) continue;
-			if (!isEventForTarget(event, target)) continue;
-			if (!registration.options.enabled) continue;
-			if (registration.options.ignoreInputs !== false) {
-				if (shouldIgnoreInputEvent(event, target, registration.target)) continue;
+		for (const registration of registrations) {
+			const match = matches.get(registration.id);
+			if (!match?.matched || match.score !== bestScore) continue;
+			if (eventType === "keyup") {
+				this.#executeCallback(registration, event);
+				continue;
 			}
-			if (eventType === "keydown") {
-				if (registration.options.eventType !== "keydown") continue;
-				const match = matches.get(id);
-				if (match?.matched && match.score === bestScore) {
+			if (registration.options.preventDefault) event.preventDefault();
+			if (registration.options.stopPropagation) event.stopPropagation();
+			if (!registration.options.requireReset || !registration.hasFired) {
+				this.#executeCallback(registration, event);
+				if (registration.options.requireReset) {
+					registration.hasFired = true;
+					registration.activeMatch = match.identity;
+				}
+			}
+		}
+	}
+	#processSequences(event, target, eventType) {
+		const registrations = this.#registrationsOn(target, "sequence");
+		if (registrations.length === 0) return;
+		if (isRecordingEvent(event)) {
+			let changed = false;
+			for (const registration of registrations) if (registration.currentIndex > 0) {
+				registration.currentIndex = 0;
+				changed = true;
+			}
+			if (changed) this.#notify();
+			return;
+		}
+		if (event.type === "keydown" && event.repeat || normalizeKeyboardEvent(event).isComposing) return;
+		if (isModifierKey(normalizeKeyName(event.key))) return;
+		const now = Date.now();
+		let changed = false;
+		const candidates = /* @__PURE__ */ new Map();
+		let bestScore = 0;
+		for (const registration of registrations) {
+			if (!isEventForTarget(event, target) || !registration.options.enabled || registration.options.ignoreInputs !== false && 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;
+				changed = true;
+			}
+			const expected = registration.parsedSequence[registration.currentIndex];
+			if (!expected) continue;
+			let match = matchKeyboardEvent(event, expected, registration.options.platform);
+			let nextIndex = registration.currentIndex + 1;
+			if (!match.matched && registration.currentIndex > 0) {
+				match = matchKeyboardEvent(event, registration.parsedSequence[0], registration.options.platform);
+				nextIndex = 1;
+			}
+			candidates.set(registration.id, {
+				score: match.score,
+				nextIndex
+			});
+			bestScore = Math.max(bestScore, match.score);
+		}
+		const completed = [];
+		for (const registration of registrations) {
+			const candidate = candidates.get(registration.id);
+			if (!candidate) continue;
+			if (candidate.score > 0 && candidate.score === bestScore) {
+				registration.lastKeyTime = now;
+				registration.currentIndex = candidate.nextIndex;
+				changed = true;
+				if (registration.currentIndex >= registration.parsedSequence.length) {
 					if (registration.options.preventDefault) event.preventDefault();
 					if (registration.options.stopPropagation) event.stopPropagation();
-					if (!registration.options.requireReset || !registration.hasFired) {
-						this.#executeHotkeyCallback(registration, event);
-						if (registration.options.requireReset) {
-							registration.hasFired = true;
-							registration.activeMatch = match.identity;
-						}
-					}
+					registration.currentIndex = 0;
+					completed.push(registration);
 				}
-			} else if (registration.options.eventType === "keyup") {
-				const match = matches.get(id);
-				if (match?.matched && match.score === bestScore) this.#executeHotkeyCallback(registration, event);
+			} else if (registration.currentIndex > 0) {
+				registration.currentIndex = 0;
+				changed = true;
 			}
 		}
+		if (changed && completed.length === 0) this.#notify();
+		for (const registration of completed) this.#executeCallback(registration, event);
 	}
 	/**
 	* Executes a hotkey callback with proper event handling.
 	*/
-	#executeHotkeyCallback(registration, event) {
+	#executeCallback(registration, event) {
 		if (registration.options.preventDefault) event.preventDefault();
 		if (registration.options.stopPropagation) event.stopPropagation();
 		registration.triggerCount++;
-		this.registrations.setState((prev) => new Map(prev));
-		const context = {
-			hotkey: registration.hotkey,
-			parsedHotkey: registration.parsedHotkey
-		};
-		registration.callback(event, context);
-	}
-	/**
-	* Creates a keydown handler for a specific target.
-	*/
-	#createTargetKeyDownHandler(target) {
-		return (event) => {
-			this.#processTargetEvent(event, target, "keydown");
-		};
+		if (registration.kind === "sequence") registration.hasFired = true;
+		this.#notify();
+		registration.callback(event, this.#callbackContext(registration));
 	}
-	/**
-	* Creates a keyup handler for a specific target.
-	*/
-	#createTargetKeyUpHandler(target) {
-		return (event) => {
-			this.#processTargetEvent(event, target, "keyup");
+	#callbackContext(registration) {
+		return {
+			hotkey: registration.hotkey,
+			parsedHotkey: registration.kind === "chord" ? registration.parsedHotkey : registration.parsedSequence[registration.parsedSequence.length - 1]
 		};
 	}
 	/**
-	* Finds an existing registration with the same hotkey and target.
+	* 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
+	* and `Mod+S` on Windows are different bindings.
 	*/
-	#findConflictingRegistration(hotkey, target) {
-		for (const registration of this.registrations.state.values()) if (areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) && registration.target === target) return registration;
+	#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;
 		return null;
 	}
 	/**
@@ -362,8 +456,19 @@ var HotkeyManager = class HotkeyManager {
 		return false;
 	}
 	/**
+	* Resets the progress of every in-progress sequence.
+	*/
+	resetSequenceProgress() {
+		for (const registration of this.registrations.state.values()) if (registration.kind === "sequence") {
+			registration.currentIndex = 0;
+			registration.lastKeyTime = 0;
+		}
+		this.#notify();
+	}
+	/**
 	* Triggers a registration's callback programmatically from devtools.
-	* Creates a synthetic KeyboardEvent and invokes the callback.
+	* Creates a synthetic KeyboardEvent from the chord (or a sequence's last step)
+	* and invokes the callback.
 	*
 	* @param id - The registration ID to trigger
 	* @returns True if the registration was found and triggered
@@ -371,7 +476,8 @@ var HotkeyManager = class HotkeyManager {
 	triggerRegistration(id) {
 		const registration = this.registrations.state.get(id);
 		if (!registration) return false;
-		const parsed = registration.parsedHotkey;
+		const context = this.#callbackContext(registration);
+		const parsed = context.parsedHotkey;
 		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
 			...parsed.code !== void 0 ? { code: parsed.code } : { key: parsed.key },
 			ctrlKey: parsed.ctrl,
@@ -382,15 +488,13 @@ var HotkeyManager = class HotkeyManager {
 			cancelable: true
 		});
 		registration.triggerCount++;
-		this.registrations.setState((prev) => new Map(prev));
-		registration.callback(syntheticEvent, {
-			hotkey: registration.hotkey,
-			parsedHotkey: registration.parsedHotkey
-		});
+		if (registration.kind === "sequence") registration.hasFired = true;
+		this.#notify();
+		registration.callback(syntheticEvent, context);
 		return true;
 	}
 	/**
-	* Gets the number of registered hotkeys.
+	* Gets the number of registered hotkeys, chords and sequences.
 	*/
 	getRegistrationCount() {
 		return this.registrations.state.size;
@@ -398,14 +502,12 @@ var HotkeyManager = class HotkeyManager {
 	/**
 	* Checks if a specific hotkey is registered.
 	*
-	* @param hotkey - The hotkey string to check
+	* @param hotkey - The chord or sequence to check
 	* @param target - Optional target element to match (if provided, both hotkey and target must match)
 	* @returns True if a matching registration exists
 	*/
 	isRegistered(hotkey, target) {
-		for (const registration of this.registrations.state.values()) if (areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform)) {
-			if (target === void 0 || registration.target === target) return true;
-		}
+		for (const registration of this.registrations.state.values()) if (areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) && (target === void 0 || registration.target === target)) return true;
 		return false;
 	}
 	/**
@@ -414,6 +516,7 @@ var HotkeyManager = class HotkeyManager {
 	destroy() {
 		for (const target of this.#targetListeners.keys()) this.#removeListenersForTarget(target);
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
+		this.appHotkeys.setState(() => null);
 		this.#targetListeners.clear();
 		this.#targetRegistrations.clear();
 	}