@tanstack/hotkeys 0.19.0 → 0.21.0

package/dist/constants.js

@@ -1,4 +1,4 @@
-import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.js";
+import { EDITING_KEY_NAMES, LOGICAL_ONLY_NAMED_KEYS, NAVIGATION_KEY_NAMES, SHARED_NAMED_KEYS } from "./_named-keys.js";
 
 //#region src/constants.ts
 /**
@@ -80,34 +80,7 @@ const MODIFIER_ALIASES = {
 * Used for validation and type checking. Letter keys are matched case-insensitively
 * in hotkey matching, but normalized to uppercase in canonical form.
 */
-const LETTER_KEYS = /* @__PURE__ */ new Set([
-	"A",
-	"B",
-	"C",
-	"D",
-	"E",
-	"F",
-	"G",
-	"H",
-	"I",
-	"J",
-	"K",
-	"L",
-	"M",
-	"N",
-	"O",
-	"P",
-	"Q",
-	"R",
-	"S",
-	"T",
-	"U",
-	"V",
-	"W",
-	"X",
-	"Y",
-	"Z"
-]);
+const LETTER_KEYS = /* @__PURE__ */ new Set("ABCDEFGHIJKLMNOPQRSTUVWXYZ");
 /**
 * Set of all valid number keys (0-9).
 *
@@ -115,50 +88,14 @@ const LETTER_KEYS = /* @__PURE__ */ new Set([
 * so they're excluded from Shift-based hotkey combinations to avoid
 * layout-dependent behavior.
 */
-const NUMBER_KEYS = /* @__PURE__ */ new Set([
-	"0",
-	"1",
-	"2",
-	"3",
-	"4",
-	"5",
-	"6",
-	"7",
-	"8",
-	"9"
-]);
+const NUMBER_KEYS = /* @__PURE__ */ new Set("0123456789");
 /**
 * Set of all valid function keys (F1-F24).
 *
 * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
 * Alt+F4 to close windows) and application-specific commands.
 */
-const FUNCTION_KEYS = /* @__PURE__ */ new Set([
-	"F1",
-	"F2",
-	"F3",
-	"F4",
-	"F5",
-	"F6",
-	"F7",
-	"F8",
-	"F9",
-	"F10",
-	"F11",
-	"F12",
-	"F13",
-	"F14",
-	"F15",
-	"F16",
-	"F17",
-	"F18",
-	"F19",
-	"F20",
-	"F21",
-	"F22",
-	"F23",
-	"F24"
-]);
+const FUNCTION_KEYS = /* @__PURE__ */ new Set(Array.from({ length: 24 }, (_, i) => `F${i + 1}`));
 /**
 * Set of all valid navigation keys for cursor movement and document navigation.
 *
@@ -166,16 +103,7 @@ const FUNCTION_KEYS = /* @__PURE__ */ new Set([
 * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or
 * navigation shortcuts (Alt+ArrowLeft for back).
 */
-const NAVIGATION_KEYS = /* @__PURE__ */ new Set([
-	"ArrowUp",
-	"ArrowDown",
-	"ArrowLeft",
-	"ArrowRight",
-	"Home",
-	"End",
-	"PageUp",
-	"PageDown"
-]);
+const NAVIGATION_KEYS = /* @__PURE__ */ new Set(NAVIGATION_KEY_NAMES);
 /**
 * Set of all valid editing and special keys.
 *
@@ -183,14 +111,7 @@ const NAVIGATION_KEYS = /* @__PURE__ */ new Set([
 * special actions (Escape, Space). These keys are frequently combined with modifiers
 * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).
 */
-const EDITING_KEYS = /* @__PURE__ */ new Set([
-	"Enter",
-	"Escape",
-	"Space",
-	"Tab",
-	"Backspace",
-	"Delete"
-]);
+const EDITING_KEYS = /* @__PURE__ */ new Set(EDITING_KEY_NAMES);
 /**
 * Set of all valid punctuation keys commonly used in keyboard shortcuts.
 *
@@ -203,40 +124,7 @@ const EDITING_KEYS = /* @__PURE__ */ new Set([
 * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),
 * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
 */
-const PUNCTUATION_KEYS = /* @__PURE__ */ new Set([
-	"/",
-	"[",
-	"]",
-	"\\",
-	"=",
-	"-",
-	",",
-	".",
-	";",
-	"`",
-	"'",
-	"+",
-	"?",
-	"!",
-	"@",
-	"#",
-	"$",
-	"%",
-	"^",
-	"&",
-	"*",
-	"(",
-	")",
-	"_",
-	"{",
-	"}",
-	"|",
-	":",
-	"\"",
-	"<",
-	">",
-	"~"
-]);
+const PUNCTUATION_KEYS = /* @__PURE__ */ new Set("/[]\\=-,.;`'+?!@#$%^&*()_{}|:\"<>~");
 /**
 * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
 *
@@ -259,12 +147,15 @@ const PUNCTUATION_CODE_MAP = {
 	Semicolon: ";",
 	Slash: "/"
 };
+function union(...groups) {
+	return new Set(groups.flatMap((group) => [...group]));
+}
 /**
 * Set of all valid non-modifier keys.
 *
-* This is the union of all key type sets (letters, numbers, function keys, navigation,
-* editing, and punctuation). Used primarily for validation to check if a key string
-* is recognized and will have type-safe autocomplete support.
+* This is the union of all key type sets (letters, numbers, function keys,
+* navigation, editing, punctuation, and other named keys): every key with
+* type-safe autocomplete support.
 *
 * @see {@link LETTER_KEYS}
 * @see {@link NUMBER_KEYS}
@@ -273,52 +164,23 @@ const PUNCTUATION_CODE_MAP = {
 * @see {@link EDITING_KEYS}
 * @see {@link PUNCTUATION_KEYS}
 */
-const ALL_KEYS = /* @__PURE__ */ new Set([
-	...LETTER_KEYS,
-	...NUMBER_KEYS,
-	...FUNCTION_KEYS,
-	...NAVIGATION_KEYS,
-	...EDITING_KEYS,
-	...PUNCTUATION_KEYS,
-	...SHARED_NAMED_KEYS,
-	...LOGICAL_ONLY_NAMED_KEYS
-]);
-/**
-* Maps lowercase key names and aliases to their canonical form, so lookups
-* are case-insensitive: `'esc'`, `'Esc'`, and `'ESCAPE'` all become `'Escape'`.
-* Canonical names come from {@link ALL_KEYS}, so validation and normalization
-* share one spelling for every key.
-*/
-const CANONICAL_KEY_NAMES = /* @__PURE__ */ new Map([
-	...Array.from(ALL_KEYS, (key) => [key.toLowerCase(), key]),
-	["plus", "+"],
-	["esc", "Escape"],
-	["return", "Enter"],
-	[" ", "Space"],
-	["spacebar", "Space"],
-	["del", "Delete"],
-	["up", "ArrowUp"],
-	["down", "ArrowDown"],
-	["left", "ArrowLeft"],
-	["right", "ArrowRight"],
-	["pgup", "PageUp"],
-	["pgdn", "PageDown"]
-]);
+const ALL_KEYS = /* @__PURE__ */ union(LETTER_KEYS, NUMBER_KEYS, FUNCTION_KEYS, NAVIGATION_KEYS, EDITING_KEYS, PUNCTUATION_KEYS, SHARED_NAMED_KEYS, LOGICAL_ONLY_NAMED_KEYS);
 /** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 function isSingleLetterKey(key) {
 	return /^\p{Letter}$/u.test(key);
 }
 /**
-* Normalizes a key name to its canonical form.
+* Normalizes a key name from a `KeyboardEvent` or a hotkey: single letters
+* become uppercase, and the space character becomes `Space`. Other names are
+* returned as written, because key names are case-sensitive.
 *
-* @param key - The key name to normalize (can be an alias, lowercase, etc.)
+* @param key - The key name to normalize
 * @returns The canonical key name
 *
 * @example
 * ```ts
-* normalizeKeyName('esc') // 'Escape'
 * normalizeKeyName('a') // 'A'
-* normalizeKeyName('f1') // 'F1'
+* normalizeKeyName(' ') // 'Space'
 * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
 * ```
 */
@@ -328,7 +190,7 @@ function normalizeKeyName(key) {
 		const upper = key.toUpperCase();
 		return upper.length === 1 ? upper : key;
 	}
-	return CANONICAL_KEY_NAMES.get(key.toLowerCase()) ?? key;
+	return key === " " ? "Space" : key;
 }
 
 //#endregion

package/dist/format.d.ts

@@ -1,3 +1,4 @@
+import { CanonicalModifier } from "./key.types.js";
 import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
 //#region src/format.d.ts
 /**
@@ -17,8 +18,11 @@ import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
 export declare function formatHotkey(parsed: ParsedHotkeyChord): string;
 export declare function formatHotkey(parsed: ReadonlyArray<ParsedHotkeyChord>): Array<string>;
 export declare function formatHotkey(parsed: ParsedHotkeyChord | ReadonlyArray<ParsedHotkeyChord>): string | Array<string>;
-/** A single chord to display: a string, raw object, or parsed hotkey. */
-export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkeyChord | (string & {});
+/**
+ * A single chord to display: a hotkey string, which includes single keys, a
+ * modifier on its own, a raw object such as `{ key }`, or a parsed hotkey.
+ */
+export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkeyChord | CanonicalModifier;
 /** A hotkey to display: a chord or a sequence of chords. */
 export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChord>;
 /**
@@ -35,7 +39,10 @@ export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChor
  * Sequence steps are formatted individually and joined with `sequenceSeparator`
  * (a space by default).
  *
- * @param hotkey - A logical or physical string, raw object, ParsedHotkeyChord, or sequence
+ * A key reported by a `KeyboardEvent`, such as a held key from
+ * `KeyStateTracker`, can be outside the key types: pass it as `{ key }`.
+ *
+ * @param hotkey - A logical or physical hotkey string, raw object, ParsedHotkeyChord, or sequence
  * @param options - Formatting options
  * @returns Display text, or individual key labels when parts is true (one array per step for sequences)
  *
@@ -50,6 +57,12 @@ export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChor
  * formatForDisplay('Escape')
  * // Returns: 'Esc' (on all platforms)
  *
+ * formatForDisplay('Shift', { platform: 'mac' })
+ * // Returns: '⇧'
+ *
+ * formatForDisplay({ key: heldKey })
+ * // A key from a KeyboardEvent, such as a held key
+ *
  * formatForDisplay(['G', 'H'])
  * // Returns: 'G H'
  * ```

package/dist/format.js

@@ -45,20 +45,25 @@ function formatChordParts(hotkey, options) {
 		};
 		segments.sort((a, b) => modifierIndex(a) - modifierIndex(b));
 	}
-	return segments.map((segment) => {
-		const modifier = modifierAlias(segment);
-		if (modifier) return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];
-		const code = physicalCodeOf(segment);
-		const label = options.keyLabels?.[code ?? segment];
-		if (label !== void 0) return label;
-		const numpad = code?.startsWith("Numpad") ?? false;
-		let displayKey = code ?? segment;
-		const mappedKey = code ? options.layoutMap?.get(code) : void 0;
-		if (mappedKey) displayKey = normalizeKeyName(mappedKey);
-		else if (code) displayKey = numpad ? code.slice(6) : codeToLogicalKey(code) ?? code;
-		const display = (keySymbols ? KEY_DISPLAY_SYMBOLS : PUNCTUATION_KEY_DISPLAY_LABELS)[displayKey] ?? displayKey;
-		return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
-	});
+	return segments.map((segment) => formatKey(segment, platform, modifierSymbols, keySymbols, options));
+}
+/** Own properties only, so names such as `toString` never read Object.prototype. */
+function lookup(table, name) {
+	return table && Object.hasOwn(table, name) ? table[name] : void 0;
+}
+function formatKey(segment, platform, modifierSymbols, keySymbols, options) {
+	const modifier = modifierAlias(segment);
+	if (modifier) return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];
+	const code = physicalCodeOf(segment);
+	const label = lookup(options.keyLabels, code ?? segment);
+	if (label !== void 0) return label;
+	const numpad = code?.startsWith("Numpad") ?? false;
+	let displayKey = code ?? segment;
+	const mappedKey = code ? options.layoutMap?.get(code) : void 0;
+	if (mappedKey) displayKey = normalizeKeyName(mappedKey);
+	else if (code) displayKey = numpad ? code.slice(6) : codeToLogicalKey(code) ?? code;
+	const display = lookup(keySymbols ? KEY_DISPLAY_SYMBOLS : PUNCTUATION_KEY_DISPLAY_LABELS, displayKey) ?? displayKey;
+	return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
 }
 
 //#endregion

package/dist/hint.d.ts

@@ -11,11 +11,12 @@ export interface HeldModifierOptions {
  * By default, any nonempty subset of the binding's modifiers qualifies; an
  * unrelated modifier hides the hint. `exact` requires every binding modifier.
  * Nonmodifier keys are ignored. This does not check registration or focus.
- * A sequence reveals its hint from its first step.
+ * A sequence reveals its hint from its first step. Returns false for no
+ * hotkey (`undefined`, `null`, or `''`).
  *
  * @example
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
  */
-export declare function matchesHeldModifiers(hotkey: RegisterableHotkey, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;
+export declare function matchesHeldModifiers(hotkey: RegisterableHotkey | null | undefined, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;
 //#endregion

package/dist/hint.js

@@ -7,13 +7,15 @@ import { isHotkeySequence, parseHotkey } from "./parse.js";
 * By default, any nonempty subset of the binding's modifiers qualifies; an
 * unrelated modifier hides the hint. `exact` requires every binding modifier.
 * Nonmodifier keys are ignored. This does not check registration or focus.
-* A sequence reveals its hint from its first step.
+* A sequence reveals its hint from its first step. Returns false for no
+* hotkey (`undefined`, `null`, or `''`).
 *
 * @example
 * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
 * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
 */
 function matchesHeldModifiers(hotkey, heldKeys, options = {}) {
+	if (!hotkey) return false;
 	if (heldKeys.includes("AltGraph")) return false;
 	const held = [...new Set(heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)))];
 	const first = isHotkeySequence(hotkey) ? hotkey[0] : hotkey;

package/dist/hotkey-manager.d.ts

@@ -1,6 +1,6 @@
+import { Store } from "./_store.js";
 import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
-import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
 /** An element, document, or window that hotkeys can listen on. */
 export type Target = HTMLElement | Document | Window;
@@ -366,15 +366,6 @@ export declare class HotkeyManager {
    * Resets the progress of every in-progress sequence.
    */
   resetSequenceProgress(): void;
-  /**
-   * Triggers a registration's callback programmatically from devtools.
-   * 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
-   */
-  triggerRegistration(id: string): boolean;
   /**
    * Gets the number of registered hotkeys, chords and sequences.
    */
@@ -394,10 +385,11 @@ export declare class HotkeyManager {
    * only while focus is inside that element. An app hotkey matches
    * registrations by id, so custom hotkeys apply.
    *
-   * @param hotkey - A chord, sequence, or app hotkey
+   * @param hotkey - A chord, sequence, or app hotkey. No hotkey
+   *   (`undefined`, `null`, or `''`) returns false.
    * @returns True if a registration that can fire exists
    */
-  hasActiveRegistration(hotkey: RegisterableHotkey | AppHotkey): boolean;
+  hasActiveRegistration(hotkey: RegisterableHotkey | AppHotkey | null | undefined): boolean;
   /**
    * Destroys the manager and removes all listeners.
    */

package/dist/hotkey-manager.js

@@ -1,16 +1,16 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isKeyNameShape, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
+import { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
 import { getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
+import { createStore } from "./_store.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
-import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
-import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
 /** Whether a registration can fire now. Without a manager, scopes don't apply. */
@@ -57,6 +57,13 @@ function chordString(chord, parsed) {
 function generateId() {
 	return `hotkey_${++registrationIdCounter}`;
 }
+/** Defaults for a registration of the given kind. */
+function registrationDefaults(kind) {
+	return {
+		...defaultHotkeyOptions,
+		...kind === "sequence" ? { timeout: DEFAULT_SEQUENCE_TIMEOUT } : { requireReset: false }
+	};
+}
 /** Drops options that do not apply to a registration's kind. */
 function optionsForKind(kind, options) {
 	if (kind === "chord") {
@@ -127,14 +134,14 @@ var HotkeyManager = class HotkeyManager {
 	* }
 	* ```
 	*/
-	registrations = new Store(/* @__PURE__ */ new Map());
+	registrations = createStore(/* @__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);
+	appHotkeys = createStore(null);
 	/** Active scopes. Subscribe to show which hotkeys are suspended. */
-	scopes = new Store({
+	scopes = createStore({
 		active: [],
 		exclusive: null,
 		allowed: [],
@@ -194,7 +201,7 @@ var HotkeyManager = class HotkeyManager {
 		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.`);
+		if (process.env.NODE_ENV !== "production" && 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",
@@ -296,6 +303,7 @@ var HotkeyManager = class HotkeyManager {
 		this.registrations.setState((prev) => new Map(prev));
 	}
 	register(input, callback, options = {}) {
+		if (input == null) throw new Error("A hotkey is required. Skip registration when there is no hotkey.");
 		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) {
@@ -319,15 +327,14 @@ var HotkeyManager = class HotkeyManager {
 		const platform = options.platform ?? this.#platform;
 		const target = options.target ?? document;
 		const sequence = isHotkeySequence(hotkey);
+		const kind = sequence ? "sequence" : "chord";
 		const common = {
 			id,
 			callback,
 			options: {
-				...defaultHotkeyOptions,
-				...sequence ? { timeout: DEFAULT_SEQUENCE_TIMEOUT } : { requireReset: false },
-				...optionsForKind(sequence ? "sequence" : "chord", options),
-				platform,
-				ignoreInputs: options.ignoreInputs ?? "auto"
+				...registrationDefaults(kind),
+				...optionsForKind(kind, definedOptions(options)),
+				platform
 			},
 			target,
 			triggerCount: 0,
@@ -353,6 +360,11 @@ var HotkeyManager = class HotkeyManager {
 				parsedChord
 			};
 		}
+		const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
+		if (!steps.every(chordHasKey)) throw new Error(`Hotkey '${formatForMessage(registration.hotkey)}' has no key. Skip registration when there is no hotkey.`);
+		if (process.env.NODE_ENV !== "production") {
+			for (const { key } of steps) if (key !== void 0 && !isKeyNameShape(key)) console.warn(`Unknown key '${key}' in '${formatForMessage(registration.hotkey)}'. Key names are case-sensitive, such as 'Escape' and 'F1', so this hotkey may never fire.`);
+		}
 		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));
@@ -376,10 +388,15 @@ var HotkeyManager = class HotkeyManager {
 				manager.registrations.setState((prev) => {
 					const reg = prev.get(id);
 					if (!reg) return prev;
-					const options = {
-						...reg.options,
-						...optionsForKind(reg.kind, newOptions)
+					const defaults = {
+						...registrationDefaults(reg.kind),
+						platform: reg.options.platform
 					};
+					const options = { ...reg.options };
+					const entries = Object.entries(optionsForKind(reg.kind, newOptions));
+					for (const [key, value] of entries) if (value !== void 0) options[key] = value;
+					else if (key in defaults) options[key] = defaults[key];
+					else delete options[key];
 					if (optionsEqual(reg.options, options)) return prev;
 					const capture = !!reg.options.capture;
 					if (capture !== !!options.capture) {
@@ -662,31 +679,6 @@ var HotkeyManager = class HotkeyManager {
 		this.#notify();
 	}
 	/**
-	* Triggers a registration's callback programmatically from devtools.
-	* 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
-	*/
-	triggerRegistration(id) {
-		const registration = this.registrations.state.get(id);
-		if (!registration) return false;
-		const context = this.#callbackContext(registration);
-		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,
-			shiftKey: parsed.shift,
-			altKey: parsed.alt,
-			metaKey: parsed.meta,
-			bubbles: true,
-			cancelable: true
-		});
-		this.#fire(registration, syntheticEvent, context);
-		return true;
-	}
-	/**
 	* Gets the number of registered hotkeys, chords and sequences.
 	*/
 	getRegistrationCount() {
@@ -710,10 +702,12 @@ var HotkeyManager = class HotkeyManager {
 	* only while focus is inside that element. An app hotkey matches
 	* registrations by id, so custom hotkeys apply.
 	*
-	* @param hotkey - A chord, sequence, or app hotkey
+	* @param hotkey - A chord, sequence, or app hotkey. No hotkey
+	*   (`undefined`, `null`, or `''`) returns false.
 	* @returns True if a registration that can fire exists
 	*/
 	hasActiveRegistration(hotkey) {
+		if (!hotkey) return false;
 		const id = typeof hotkey === "object" && "~appHotkey" in hotkey ? hotkey.id : void 0;
 		for (const registration of this.registrations.state.values()) if (this.#isLive(registration) && targetHasFocus(registration.target) && (id === void 0 ? areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) : registration.options.appHotkeyId === id)) return true;
 		return false;

package/dist/hotkey-recorder.d.ts

@@ -1,6 +1,6 @@
+import { Store } from "./_store.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';

package/dist/hotkey-recorder.js

@@ -1,12 +1,11 @@
 import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { normalizeKeyboardEvent, splitChordParts } from "./_keyboard-event.js";
 import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
-import { validateHotkey } from "./validate.js";
 import { isTypingEvent } from "./_event-target.js";
+import { createStore } from "./_store.js";
 import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
 import { findHotkeyConflicts } from "./conflicts.js";
 import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
-import { Store } from "@tanstack/store";
 
 //#region src/hotkey-recorder.ts
 const initialState = {
@@ -49,7 +48,7 @@ const initialState = {
 * ```
 */
 var HotkeyRecorder = class {
-	store = new Store(initialState);
+	store = createStore(initialState);
 	#keydownHandler = null;
 	#optionsSource;
 	#optionOverrides = {};
@@ -156,11 +155,10 @@ var HotkeyRecorder = class {
 			}
 			const chord = hotkeyChordFromKeydown(event, platform, options.recordBy);
 			if (chord === null) return;
-			const validation = validateHotkey(chord);
-			if (!validation.valid) {
+			if (splitChordParts(chord).some((part) => !part.trim())) {
 				options.onReject?.({
 					reason: "invalid",
-					message: validation.errors.join("; "),
+					message: "Whitespace keys cannot be recorded",
 					hotkey: chord
 				});
 				return;

package/dist/key-state-tracker.d.ts

@@ -1,4 +1,4 @@
-import { Store } from "@tanstack/store";
+import { Store } from "./_store.js";
 //#region src/key-state-tracker.d.ts
 /**
  * State interface for the KeyStateTracker.

package/dist/key-state-tracker.js

@@ -1,5 +1,5 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
-import { Store } from "@tanstack/store";
+import { createStore } from "./_store.js";
 
 //#region src/key-state-tracker.ts
 /**
@@ -51,7 +51,7 @@ var KeyStateTracker = class KeyStateTracker {
 	* The TanStack Store instance containing the tracker state.
 	* Use this to subscribe to state changes or access current state.
 	*/
-	store = new Store(getDefaultKeyStateTrackerState());
+	store = createStore(getDefaultKeyStateTrackerState());
 	#heldEntries = /* @__PURE__ */ new Map();
 	/** Window listeners as `[type, listener, capture]`, removed together on destroy. */
 	#listeners = [];

package/dist/match.js

@@ -4,6 +4,7 @@ import { normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isHotkeySequence, isModifierKey, parseHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
+import { chordHasKey } from "./_registration.js";
 
 //#region src/match.ts
 /**
@@ -36,7 +37,9 @@ import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 * ```
 */
 function matchesKeyboardEvent(event, chord, platform = detectPlatform()) {
-	return matchKeyboardEvent(event, chord, platform).matched;
+	const parsed = typeof chord === "string" ? parseHotkey(chord, platform) : chord;
+	if (!chordHasKey(parsed)) return false;
+	return matchKeyboardEvent(event, parsed, platform).matched;
 }
 /**
 * Creates a keyboard event handler that calls the callback when the chord