@tanstack/hotkeys 0.11.0 → 0.12.1

package/dist/sequence-manager.js

@@ -1,443 +0,0 @@
-import { normalizeKeyName } from "./constants.js";
-import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isModifierKey, parseHotkey } from "./parse.js";
-import { formatHotkeySequence } from "./format.js";
-import { matchKeyboardEvent } from "./_match.js";
-import { areHotkeysEqual, matchesKeyboardEvent } 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/sequence-manager.ts
-/**
-* Default timeout between keys in a sequence (in milliseconds).
-* Exported for consumers that display sequence state (e.g. devtools).
-*/
-const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
-let sequenceIdCounter = 0;
-/**
-* Generates a unique ID for sequence registrations.
-*/
-function generateSequenceId() {
-	return `sequence_${++sequenceIdCounter}`;
-}
-/**
-* Manages keyboard sequence matching for Vim-style shortcuts.
-*
-* This class allows registering multi-key sequences like 'g g' or 'd d'
-* that trigger callbacks when the full sequence is pressed within
-* a configurable timeout.
-*
-* Modifier-only `keydown` / `keyup` events (Shift, Control, Alt, or Meta
-* alone) are not processed: they neither match a step nor reset progress.
-* That supports chained modifier chords (e.g. `Shift+R` then `Shift+T`) when
-* the user presses a modifier alone between steps.
-*
-* @example
-* ```ts
-* const matcher = SequenceManager.getInstance()
-*
-* // Register 'g g' to go to top
-* const unregister = matcher.register(['G', 'G'], (event, context) => {
-*   scrollToTop()
-* }, { timeout: 500 })
-*
-* // Later, to unregister:
-* unregister()
-* ```
-*/
-/**
-* Builds a devtools view from an internal registration.
-*/
-function toRegistrationView(reg) {
-	const len = reg.parsedSequence.length;
-	const inProgress = reg.currentIndex > 0 && reg.currentIndex < len;
-	return {
-		id: reg.id,
-		sequence: reg.sequence,
-		options: reg.options,
-		target: reg.target,
-		triggerCount: reg.triggerCount,
-		hasFired: reg.hasFired,
-		matchedStepCount: inProgress ? reg.currentIndex : 0,
-		partialMatchLastKeyTime: inProgress ? reg.lastKeyTime : 0
-	};
-}
-var SequenceManager = class SequenceManager {
-	static #instance = null;
-	/**
-	* The TanStack Store containing sequence registration views for devtools.
-	* Subscribe to this to observe registration changes.
-	*/
-	registrations = new Store(/* @__PURE__ */ new Map());
-	#registrations = /* @__PURE__ */ new Map();
-	#targetListeners = /* @__PURE__ */ new Map();
-	#targetRegistrations = /* @__PURE__ */ new Map();
-	#platform;
-	constructor() {
-		this.#platform = detectPlatform();
-	}
-	/**
-	* Gets the singleton instance of SequenceManager.
-	*/
-	static getInstance() {
-		if (!SequenceManager.#instance) SequenceManager.#instance = new SequenceManager();
-		return SequenceManager.#instance;
-	}
-	/**
-	* Resets the singleton instance. Useful for testing.
-	*/
-	static resetInstance() {
-		if (SequenceManager.#instance) {
-			SequenceManager.#instance.destroy();
-			SequenceManager.#instance = null;
-		}
-	}
-	#syncRegistrationView(registration) {
-		this.registrations.setState((prev) => new Map(prev).set(registration.id, toRegistrationView(registration)));
-	}
-	/**
-	* Registers a hotkey sequence handler.
-	*
-	* @param sequence - Array of hotkey strings that form the sequence
-	* @param callback - Function to call when the sequence is completed
-	* @param options - Options for the sequence behavior
-	* @returns A handle to update or unregister the sequence
-	*/
-	register(sequence, callback, options = {}) {
-		if (sequence.length === 0) throw new Error("Sequence must contain at least one hotkey");
-		const id = generateSequenceId();
-		const platform = options.platform ?? this.#platform;
-		const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform));
-		const target = options.target ?? (typeof document !== "undefined" ? document : {});
-		const conflictBehavior = options.conflictBehavior ?? "warn";
-		const conflictingRegistration = this.#findConflictingSequence(parsedSequence, target);
-		if (conflictingRegistration) handleConflict(conflictingRegistration.id, formatHotkeySequence(sequence), conflictBehavior, (regId) => this.#unregister(regId));
-		const firstStep = parsedSequence[0];
-		const resolvedIgnoreInputs = options.ignoreInputs ?? getDefaultIgnoreInputs(firstStep);
-		const registration = {
-			id,
-			sequence,
-			parsedSequence,
-			callback,
-			options: {
-				...defaultHotkeyOptions,
-				timeout: DEFAULT_SEQUENCE_TIMEOUT,
-				...options,
-				platform,
-				ignoreInputs: resolvedIgnoreInputs
-			},
-			target,
-			currentIndex: 0,
-			lastKeyTime: 0,
-			triggerCount: 0,
-			hasFired: false
-		};
-		this.#registrations.set(id, registration);
-		this.registrations.setState((prev) => new Map(prev).set(id, toRegistrationView(registration)));
-		if (!this.#targetRegistrations.has(target)) this.#targetRegistrations.set(target, /* @__PURE__ */ new Set());
-		this.#targetRegistrations.get(target).add(id);
-		this.#ensureListenersForTarget(target);
-		const manager = this;
-		return {
-			get id() {
-				return id;
-			},
-			get isActive() {
-				return manager.#registrations.has(id);
-			},
-			get callback() {
-				return manager.#registrations.get(id)?.callback ?? callback;
-			},
-			set callback(newCallback) {
-				const reg = manager.#registrations.get(id);
-				if (reg) reg.callback = newCallback;
-			},
-			setOptions: (newOptions) => {
-				const reg = manager.#registrations.get(id);
-				if (reg && !optionsEqual(reg.options, {
-					...reg.options,
-					...newOptions
-				})) {
-					reg.options = {
-						...reg.options,
-						...newOptions
-					};
-					manager.registrations.setState((prev) => new Map(prev).set(id, toRegistrationView(reg)));
-				}
-			},
-			unregister: () => {
-				manager.#unregister(id);
-			}
-		};
-	}
-	/**
-	* Unregisters a sequence by its registration ID.
-	*/
-	#unregister(id) {
-		const registration = this.#registrations.get(id);
-		if (!registration) return;
-		const target = registration.target;
-		this.#registrations.delete(id);
-		this.registrations.setState((prev) => {
-			const next = new Map(prev);
-			next.delete(id);
-			return next;
-		});
-		const targetRegs = this.#targetRegistrations.get(target);
-		if (targetRegs) {
-			targetRegs.delete(id);
-			if (targetRegs.size === 0) this.#removeListenersForTarget(target);
-		}
-	}
-	/**
-	* Ensures event listeners are attached for a specific target.
-	*/
-	#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);
-		this.#targetListeners.set(target, {
-			keydown: keydownHandler,
-			keyup: keyupHandler
-		});
-	}
-	/**
-	* Removes event listeners for a specific target.
-	*/
-	#removeListenersForTarget(target) {
-		if (typeof document === "undefined") return;
-		const listeners = this.#targetListeners.get(target);
-		if (!listeners) return;
-		target.removeEventListener("keydown", listeners.keydown);
-		target.removeEventListener("keyup", listeners.keyup);
-		this.#targetListeners.delete(target);
-		this.#targetRegistrations.delete(target);
-	}
-	/**
-	* Creates a keydown handler for a specific target.
-	*/
-	#createTargetKeyDownHandler(target) {
-		return (event) => {
-			this.#processTargetEvent(event, target, "keydown");
-		};
-	}
-	/**
-	* Creates a keyup handler for a specific target.
-	*/
-	#createTargetKeyUpHandler(target) {
-		return (event) => {
-			this.#processTargetEvent(event, target, "keyup");
-		};
-	}
-	/**
-	* Processes keyboard events for a specific target and event type.
-	*/
-	#processTargetEvent(event, target, eventType) {
-		if (isRecordingEvent(event)) {
-			for (const id of this.#targetRegistrations.get(target) ?? []) {
-				const registration = this.#registrations.get(id);
-				if (registration && registration.currentIndex > 0) {
-					registration.currentIndex = 0;
-					this.#syncRegistrationView(registration);
-				}
-			}
-			return;
-		}
-		if (event.type === "keydown" && event.repeat || normalizeKeyboardEvent(event).isComposing) return;
-		if (isModifierKey(normalizeKeyName(event.key))) return;
-		const targetRegs = this.#targetRegistrations.get(target);
-		if (!targetRegs) return;
-		const now = Date.now();
-		const candidates = /* @__PURE__ */ new Map();
-		let bestScore = 0;
-		registrationIds: for (const id of targetRegs) {
-			const registration = this.#registrations.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 registrationIds;
-			}
-			if (registration.options.eventType !== eventType) continue;
-			const timeout = registration.options.timeout ?? 1e3;
-			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
-				registration.currentIndex = 0;
-				this.#syncRegistrationView(registration);
-			}
-			const expectedHotkey = registration.parsedSequence[registration.currentIndex];
-			if (!expectedHotkey) continue;
-			let match = matchKeyboardEvent(event, expectedHotkey, 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(id, {
-				score: match.score,
-				nextIndex
-			});
-			bestScore = Math.max(bestScore, match.score);
-		}
-		for (const [id, candidate] of candidates) {
-			const registration = this.#registrations.get(id);
-			if (!registration || !registration.options.enabled) continue;
-			if (candidate.score > 0 && candidate.score === bestScore) {
-				registration.lastKeyTime = now;
-				registration.currentIndex = candidate.nextIndex;
-				if (registration.currentIndex >= registration.parsedSequence.length) {
-					if (registration.options.preventDefault) event.preventDefault();
-					if (registration.options.stopPropagation) event.stopPropagation();
-					const context = {
-						hotkey: registration.sequence.join(" "),
-						parsedHotkey: registration.parsedSequence[registration.parsedSequence.length - 1]
-					};
-					registration.triggerCount++;
-					registration.hasFired = true;
-					registration.currentIndex = 0;
-					this.#syncRegistrationView(registration);
-					registration.callback(event, context);
-				} else this.#syncRegistrationView(registration);
-			} else if (registration.currentIndex > 0) {
-				registration.currentIndex = 0;
-				this.#syncRegistrationView(registration);
-			}
-		}
-	}
-	/**
-	* Compares resolved step identities without changing the supplied sequence strings.
-	*/
-	#findConflictingSequence(parsedSequence, target) {
-		for (const registration of this.#registrations.values()) if (registration.target === target && registration.parsedSequence.length === parsedSequence.length && parsedSequence.every((step, index) => areHotkeysEqual(step, registration.parsedSequence[index]))) return registration;
-		return null;
-	}
-	/**
-	* Resets all sequence progress.
-	*/
-	resetAll() {
-		for (const registration of this.#registrations.values()) {
-			registration.currentIndex = 0;
-			registration.lastKeyTime = 0;
-			this.#syncRegistrationView(registration);
-		}
-	}
-	/**
-	* Triggers a sequence's callback programmatically from devtools.
-	* Creates a synthetic KeyboardEvent from the last key in the sequence.
-	*
-	* @param id - The registration ID to trigger
-	* @returns True if the registration was found and triggered
-	*/
-	triggerSequence(id) {
-		const registration = this.#registrations.get(id);
-		if (!registration) return false;
-		const lastParsed = registration.parsedSequence[registration.parsedSequence.length - 1];
-		if (!lastParsed) return false;
-		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
-			...lastParsed.code !== void 0 ? { code: lastParsed.code } : { key: lastParsed.key },
-			ctrlKey: lastParsed.ctrl,
-			shiftKey: lastParsed.shift,
-			altKey: lastParsed.alt,
-			metaKey: lastParsed.meta,
-			bubbles: true,
-			cancelable: true
-		});
-		registration.triggerCount++;
-		registration.hasFired = true;
-		this.#syncRegistrationView(registration);
-		const context = {
-			hotkey: registration.sequence.join(" "),
-			parsedHotkey: lastParsed
-		};
-		registration.callback(syntheticEvent, context);
-		return true;
-	}
-	/**
-	* Gets the number of registered sequences.
-	*/
-	getRegistrationCount() {
-		return this.#registrations.size;
-	}
-	/**
-	* Destroys the manager and removes all listeners.
-	*/
-	destroy() {
-		for (const target of this.#targetListeners.keys()) this.#removeListenersForTarget(target);
-		this.#registrations.clear();
-		this.registrations.setState(() => /* @__PURE__ */ new Map());
-	}
-};
-/**
-* Gets the singleton SequenceManager instance.
-* Convenience function for accessing the manager.
-*/
-function getSequenceManager() {
-	return SequenceManager.getInstance();
-}
-/**
-* Creates a simple sequence matcher for one-off use.
-*
-* This is a low-level helper that does not support ignoreInputs, target,
-* or other HotkeyOptions. Callers must handle input filtering themselves
-* if attaching to document.
-*
-* @param sequence - The sequence of hotkeys to match
-* @param options - Options including timeout
-* @returns An object with match() and reset() methods
-*
-* @example
-* ```ts
-* const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })
-*
-* document.addEventListener('keydown', (event) => {
-*   if (matcher.match(event)) {
-*     console.log('Sequence matched!')
-*   }
-* })
-* ```
-*/
-function createSequenceMatcher(sequence, options = {}) {
-	const platform = options.platform ?? detectPlatform();
-	const timeout = options.timeout ?? 1e3;
-	const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform));
-	let currentIndex = 0;
-	let lastKeyTime = 0;
-	return {
-		match(event) {
-			if (event.type === "keydown" && event.repeat || normalizeKeyboardEvent(event, platform).isComposing || isModifierKey(normalizeKeyName(event.key))) return false;
-			const now = Date.now();
-			if (currentIndex > 0 && now - lastKeyTime > timeout) currentIndex = 0;
-			const expected = parsedSequence[currentIndex];
-			if (!expected) return false;
-			if (matchesKeyboardEvent(event, expected, platform)) {
-				lastKeyTime = now;
-				currentIndex++;
-				if (currentIndex >= parsedSequence.length) {
-					currentIndex = 0;
-					return true;
-				}
-			} else if (currentIndex > 0) {
-				if (matchesKeyboardEvent(event, parsedSequence[0], platform)) {
-					currentIndex = 1;
-					lastKeyTime = now;
-				} else currentIndex = 0;
-			}
-			return false;
-		},
-		reset() {
-			currentIndex = 0;
-			lastKeyTime = 0;
-		},
-		getProgress() {
-			return currentIndex;
-		}
-	};
-}
-
-//#endregion
-export { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager };