@tanstack/hotkeys 0.8.0 → 0.10.0

package/dist/sequence-manager.js

@@ -1,8 +1,13 @@
-import { detectPlatform, normalizeKeyName } from "./constants.js";
+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 { matchesKeyboardEvent } from "./match.js";
-import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, isEventForTarget, shouldIgnoreInputEvent } from "./manager.utils.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
@@ -19,12 +24,6 @@ function generateSequenceId() {
 	return `sequence_${++sequenceIdCounter}`;
 }
 /**
-* Returns a canonical string for sequence conflict comparison.
-*/
-function sequenceKey(sequence) {
-	return sequence.join("|");
-}
-/**
 * Manages keyboard sequence matching for Vim-style shortcuts.
 *
 * This class allows registering multi-key sequences like 'g g' or 'd d'
@@ -68,12 +67,16 @@ function toRegistrationView(reg) {
 }
 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.registrations = new Store(/* @__PURE__ */ new Map());
 		this.#platform = detectPlatform();
 	}
 	/**
@@ -110,7 +113,7 @@ var SequenceManager = class SequenceManager {
 		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(sequence, target);
+		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);
@@ -154,7 +157,10 @@ var SequenceManager = class SequenceManager {
 			},
 			setOptions: (newOptions) => {
 				const reg = manager.#registrations.get(id);
-				if (reg) {
+				if (reg && !optionsEqual(reg.options, {
+					...reg.options,
+					...newOptions
+				})) {
 					reg.options = {
 						...reg.options,
 						...newOptions
@@ -233,10 +239,23 @@ var SequenceManager = class SequenceManager {
 	* 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;
@@ -253,9 +272,24 @@ var SequenceManager = class SequenceManager {
 			}
 			const expectedHotkey = registration.parsedSequence[registration.currentIndex];
 			if (!expectedHotkey) continue;
-			if (matchesKeyboardEvent(event, expectedHotkey, registration.options.platform)) {
+			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++;
+				registration.currentIndex = candidate.nextIndex;
 				if (registration.currentIndex >= registration.parsedSequence.length) {
 					if (registration.options.preventDefault) event.preventDefault();
 					if (registration.options.stopPropagation) event.stopPropagation();
@@ -270,21 +304,16 @@ var SequenceManager = class SequenceManager {
 					registration.callback(event, context);
 				} else this.#syncRegistrationView(registration);
 			} else if (registration.currentIndex > 0) {
-				const firstHotkey = registration.parsedSequence[0];
-				if (matchesKeyboardEvent(event, firstHotkey, registration.options.platform)) {
-					registration.currentIndex = 1;
-					registration.lastKeyTime = now;
-				} else registration.currentIndex = 0;
+				registration.currentIndex = 0;
 				this.#syncRegistrationView(registration);
 			}
 		}
 	}
 	/**
-	* Finds an existing registration with the same sequence and target.
+	* Compares resolved step identities without changing the supplied sequence strings.
 	*/
-	#findConflictingSequence(sequence, target) {
-		const key = sequenceKey(sequence);
-		for (const registration of this.#registrations.values()) if (sequenceKey(registration.sequence) === key && registration.target === target) return registration;
+	#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;
 	}
 	/**
@@ -310,7 +339,7 @@ var SequenceManager = class SequenceManager {
 		const lastParsed = registration.parsedSequence[registration.parsedSequence.length - 1];
 		if (!lastParsed) return false;
 		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
-			key: lastParsed.key,
+			...lastParsed.code !== void 0 ? { code: lastParsed.code } : { key: lastParsed.key },
 			ctrlKey: lastParsed.ctrl,
 			shiftKey: lastParsed.shift,
 			altKey: lastParsed.alt,
@@ -380,6 +409,7 @@ function createSequenceMatcher(sequence, options = {}) {
 	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];
@@ -391,10 +421,12 @@ function createSequenceMatcher(sequence, options = {}) {
 					currentIndex = 0;
 					return true;
 				}
-			} else if (currentIndex > 0) if (matchesKeyboardEvent(event, parsedSequence[0], platform)) {
-				currentIndex = 1;
-				lastKeyTime = now;
-			} else currentIndex = 0;
+			} else if (currentIndex > 0) {
+				if (matchesKeyboardEvent(event, parsedSequence[0], platform)) {
+					currentIndex = 1;
+					lastKeyTime = now;
+				} else currentIndex = 0;
+			}
 			return false;
 		},
 		reset() {
@@ -408,5 +440,4 @@ function createSequenceMatcher(sequence, options = {}) {
 }
 
 //#endregion
-export { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager };
-//# sourceMappingURL=sequence-manager.js.map
+export { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager };

package/dist/validate.d.ts

@@ -1,5 +1,4 @@
-import { Hotkey, ValidationResult } from "./hotkey.js";
-
+import { Hotkey } from "./hotkey.types.js";
 //#region src/validate.d.ts
 /**
  * Validates a hotkey string and returns any warnings or errors.
@@ -21,7 +20,7 @@ import { Hotkey, ValidationResult } from "./hotkey.js";
  * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
  * ```
  */
-declare function validateHotkey(hotkey: Hotkey | (string & {})): ValidationResult;
+export declare function validateHotkey(hotkey: Hotkey | (string & {})): ValidationResult;
 /**
  * Validates a hotkey and throws an error if invalid.
  * Useful for development-time validation.
@@ -35,7 +34,7 @@ declare function validateHotkey(hotkey: Hotkey | (string & {})): ValidationResul
  * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
  * ```
  */
-declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
+export declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
 /**
  * Validates a hotkey and logs warnings to the console.
  * Useful for development-time feedback.
@@ -50,7 +49,16 @@ declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
  * // Returns: true
  * ```
  */
-declare function checkHotkey(hotkey: Hotkey | (string & {})): boolean;
-//#endregion
-export { assertValidHotkey, checkHotkey, validateHotkey };
-//# sourceMappingURL=validate.d.ts.map
+export declare function checkHotkey(hotkey: Hotkey | (string & {})): boolean;
+/**
+ * Result of validating a hotkey string.
+ */
+export interface ValidationResult {
+  /** Whether the hotkey is valid (can still have warnings) */
+  valid: boolean;
+  /** Warning messages about potential issues */
+  warnings: Array<string>;
+  /** Error messages about invalid syntax */
+  errors: Array<string>;
+}
+//#endregion

package/dist/validate.js

@@ -1,4 +1,5 @@
-import { ALL_KEYS, MODIFIER_ALIASES } from "./constants.js";
+import { ALL_KEYS, MODIFIER_ALIASES, normalizeKeyName } from "./constants.js";
+import { splitHotkeyParts } from "./_keyboard-event.js";
 
 //#region src/validate.ts
 /**
@@ -29,7 +30,7 @@ function validateHotkey(hotkey) {
 		warnings: [],
 		errors: ["Hotkey cannot be empty"]
 	};
-	const parts = hotkey.split("+").map((p) => p.trim());
+	const parts = splitHotkeyParts(hotkey).map((p) => p.trim());
 	if (parts.length === 0 || parts.some((p) => p === "")) return {
 		valid: false,
 		warnings: [],
@@ -38,7 +39,8 @@ function validateHotkey(hotkey) {
 	const modifierParts = parts.slice(0, -1);
 	const keyPart = parts[parts.length - 1];
 	for (const modifier of modifierParts) if (!(MODIFIER_ALIASES[modifier] ?? MODIFIER_ALIASES[modifier.toLowerCase()])) errors.push(`Unknown modifier: '${modifier}'`);
-	if (!isKnownKey(normalizeKeyForValidation(keyPart)) && !isKnownKey(keyPart)) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && !/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(keyPart)) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
+	if (!isKnownKey(normalizeKeyName(keyPart)) && !isKnownKey(keyPart)) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
 	return {
 		valid: errors.length === 0,
 		warnings,
@@ -46,17 +48,11 @@ function validateHotkey(hotkey) {
 	};
 }
 /**
-* Normalizes a key for validation checking.
-*/
-function normalizeKeyForValidation(key) {
-	if (key.length === 1 && /^[a-zA-Z]$/.test(key)) return key.toUpperCase();
-	if (/^f([1-9]|1[0-2])$/i.test(key)) return key.toUpperCase();
-	return key;
-}
-/**
 * Checks if a key is in the known keys set.
 */
 function isKnownKey(key) {
+	if (/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(key)) return true;
+	if (Array.from(key).length === 1) return true;
 	if (ALL_KEYS.has(key)) return true;
 	if (key.length === 1 && ALL_KEYS.has(key.toUpperCase())) return true;
 	return key in {
@@ -110,5 +106,4 @@ function checkHotkey(hotkey) {
 }
 
 //#endregion
-export { assertValidHotkey, checkHotkey, validateHotkey };
-//# sourceMappingURL=validate.js.map
+export { assertValidHotkey, checkHotkey, validateHotkey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -24,26 +24,20 @@
     "typescript"
   ],
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.cts",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
+    ".": "./dist/index.js",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "files": [
-    "dist/",
-    "src"
+    "dist"
   ],
   "dependencies": {
-    "@tanstack/store": "^0.11.0"
+    "@tanstack/store": "^0.11.1"
   },
   "scripts": {
     "clean": "premove ./build ./dist",
@@ -53,6 +47,7 @@
     "test:lib": "vitest",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc",
-    "build": "tsdown"
+    "build": "tsdown",
+    "test:build": "publint --strict && node ../../scripts/verify-package.ts"
   }
 }