@tanstack/hotkeys 0.20.0 → 0.21.0

package/dist/_registration.d.ts

@@ -0,0 +1,14 @@
+//#region src/_registration.d.ts
+/**
+ * Merges option layers left to right. A key set to `undefined` keeps the
+ * earlier layer's value, so an unset option keeps its default. Getters are
+ * read once.
+ */
+export declare function definedOptions<T extends object>(...layers: ReadonlyArray<object | undefined>): T;
+/**
+ * Merges options over defaults for an API whose `setOptions` treats
+ * `undefined` as "clear". An unset option takes its default, or stays
+ * `undefined` to clear an earlier value when it has no default.
+ */
+export declare function withDefaults<T extends object>(defaults: object | undefined, options: T | undefined): T;
+//#endregion

package/dist/_registration.js

@@ -16,6 +16,37 @@ const defaultHotkeyOptions = {
 	scope: GLOBAL_SCOPE
 };
 /**
+* Merges option layers left to right. A key set to `undefined` keeps the
+* earlier layer's value, so an unset option keeps its default. Getters are
+* read once.
+*/
+function definedOptions(...layers) {
+	const result = {};
+	for (const layer of layers) {
+		if (!layer) continue;
+		for (const key of Object.keys(layer)) {
+			const value = layer[key];
+			if (value !== void 0) result[key] = value;
+		}
+	}
+	return result;
+}
+/**
+* Merges options over defaults for an API whose `setOptions` treats
+* `undefined` as "clear". An unset option takes its default, or stays
+* `undefined` to clear an earlier value when it has no default.
+*/
+function withDefaults(defaults, options) {
+	return {
+		...options,
+		...definedOptions(defaults, options)
+	};
+}
+/** Whether a parsed chord has a key. An empty one would match key-less events. */
+function chordHasKey(chord) {
+	return chord.code !== void 0 || !!chord.key;
+}
+/**
 * Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).
 * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
 */
@@ -50,4 +81,4 @@ function optionsEqual(left, right) {
 }
 
 //#endregion
-export { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };
+export { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual, withDefaults };

package/dist/adapter.d.ts

@@ -3,6 +3,7 @@ import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, Regist
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
 import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
+import { definedOptions, withDefaults } from "./_registration.js";
 //#region src/adapter.d.ts
 /**
  * A hotkey and its callback, with optional per-binding options. Chords accept
@@ -16,6 +17,11 @@ export type HotkeyDefinition = {
   hotkey: RegisterableHotkeySequence;
   callback: HotkeyCallback;
   options?: HotkeySequenceOptions;
+} | {
+  /** No hotkey. Registers nothing. */
+  hotkey: null | undefined;
+  callback: HotkeyCallback;
+  options?: HotkeyChordOptions & HotkeySequenceOptions;
 };
 /** Options shared by every definition. Each option applies only to the kinds that support it. */
 export type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOptions;
@@ -23,7 +29,8 @@ export type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOpt
 export declare function createHotkeyBindings(): {
   /**
    * Registers new definitions, updates existing ones in place, and removes
-   * stale ones. Definitions with an empty sequence or a null target are skipped.
+   * stale ones. Definitions with no hotkey (undefined, null, empty string, or
+   * empty sequence) or a null target are skipped.
    */
   update(definitions: ReadonlyArray<HotkeyDefinition>, commonOptions?: HotkeyBindingsCommonOptions): void;
   destroy(): void;
@@ -79,9 +86,10 @@ export type AdapterHotkeyDefinition<TTarget> = {
 } | {
   /**
    * A hotkey whose kind is not known statically, such as user data typed
-   * `Hotkey`. Accepts only shared options.
+   * `Hotkey`. Accepts only shared options. `undefined`, `null`, and `''`
+   * register nothing, for an optional shortcut.
    */
-  hotkey: RegisterableHotkey;
+  hotkey: RegisterableHotkey | null | undefined;
   callback: HotkeyCallback;
   options?: AdapterHotkeyOptions<TTarget>;
 };
@@ -96,7 +104,7 @@ export interface PrepareHotkeyDefinitionsOptions<TTarget> {
   /**
    * Resolves a framework target, such as a ref. Return `undefined` for the
    * document or `null` to skip registration until the target exists.
-   * Without it, targets pass through and `null` means document.
+   * Without it, targets pass through, so `null` skips registration.
    */
   resolveTarget?: (target: TTarget) => Target | null | undefined;
 }
@@ -163,4 +171,4 @@ export declare function getHotkeysProviderScopeKey(options: {
  */
 export declare function activateHotkeysProviderScope(key: string): () => void;
 //#endregion
-export { type Store, createAppHotkeysStore, createStore };
+export { type Store, createAppHotkeysStore, createStore, definedOptions, withDefaults };

package/dist/adapter.js

@@ -1,7 +1,7 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeHotkey } from "./parse.js";
+import { isHotkeySequence, normalizeHotkey, parseHotkey } from "./parse.js";
+import { chordHasKey, defaultHotkeyOptions, definedOptions, withDefaults } from "./_registration.js";
 import { createStore } from "./_store.js";
-import { defaultHotkeyOptions } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
@@ -13,24 +13,23 @@ function createHotkeyBindings() {
 	return {
 		/**
 		* Registers new definitions, updates existing ones in place, and removes
-		* stale ones. Definitions with an empty sequence or a null target are skipped.
+		* stale ones. Definitions with no hotkey (undefined, null, empty string, or
+		* empty sequence) or a null target are skipped.
 		*/
 		update(definitions, commonOptions = {}) {
 			const prepared = [];
 			definitions.forEach((definition, index) => {
-				const merged = {
-					...commonOptions,
-					...definition.options
-				};
+				const merged = definedOptions(commonOptions, definition.options);
 				const options = {
 					...defaultHotkeyOptions,
 					...merged,
-					ignoreInputs: merged.ignoreInputs ?? "auto",
 					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
 					platform: merged.platform ?? detectPlatform()
 				};
-				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
-				const hotkey = normalizeHotkey(definition.hotkey, options.platform);
+				if (!options.target || !definition.hotkey || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
+				const parsed = parseHotkey(definition.hotkey, options.platform);
+				if (!(Array.isArray(parsed) ? parsed : [parsed]).every(chordHasKey)) return;
+				const hotkey = normalizeHotkey(parsed, options.platform);
 				if (isHotkeySequence(hotkey)) delete options.requireReset;
 				else delete options.timeout;
 				prepared.push({
@@ -89,13 +88,8 @@ function prepareHotkeyDefinitions(definitions, options = {}) {
 			declared = getAppHotkeyRegistrationOptions(appHotkey);
 			hotkey = appHotkey.hotkey ?? [];
 		}
-		const { target, ...merged } = {
-			...options.defaults,
-			...declared,
-			...options.commonOptions,
-			...definition.options
-		};
-		const resolved = target === void 0 ? void 0 : options.resolveTarget ? options.resolveTarget(target) : target ?? void 0;
+		const { target, ...merged } = definedOptions(options.defaults, declared, options.commonOptions, definition.options);
+		const resolved = target === void 0 ? void 0 : options.resolveTarget ? options.resolveTarget(target) : target;
 		return {
 			hotkey,
 			callback: definition.callback,
@@ -136,14 +130,10 @@ function subscribePublishedAppHotkeys(onChange) {
 function mergeHotkeysProviderDefaults(parent, own, scope) {
 	return {
 		hotkey: {
-			...parent?.hotkey,
-			...own?.hotkey,
+			...definedOptions(parent?.hotkey, own?.hotkey),
 			...scope && { scope }
 		},
-		hotkeyRecorder: {
-			...parent?.hotkeyRecorder,
-			...own?.hotkeyRecorder
-		}
+		hotkeyRecorder: definedOptions(parent?.hotkeyRecorder, own?.hotkeyRecorder)
 	};
 }
 /**
@@ -173,4 +163,4 @@ function activateHotkeysProviderScope(key) {
 }
 
 //#endregion
-export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };
+export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };

package/dist/app-hotkeys.d.ts

@@ -135,7 +135,13 @@ export interface AppHotkeysState<T extends AppHotkeys = AppHotkeys> {
 }
 /** Options for `AppHotkeysStore`. */
 export interface AppHotkeysStoreOptions<T extends AppHotkeys = AppHotkeys> {
-  /** Starting custom hotkeys, such as saved data. Invalid entries are ignored with a warning. */
+  /**
+   * The user's saved custom hotkeys. Invalid entries are ignored with a
+   * warning. Passing a different value to `setOptions` later, such as data
+   * that finished loading or another user's data, replaces the current
+   * custom hotkeys. `undefined` leaves them unchanged; a change to `null`
+   * clears them.
+   */
   customHotkeys?: CustomHotkeys<T> | null;
   /** Called with the custom hotkeys after every change, ready to save. */
   onCustomHotkeysChange?: (customHotkeys: CustomHotkeys<T>) => void;
@@ -165,8 +171,17 @@ export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
   get appHotkeys(): T;
   /** The user's hotkeys that differ from the defaults. */
   get customHotkeys(): CustomHotkeys<T>;
-  /** Updates callbacks and other options without resetting custom hotkeys. */
-  setOptions(options: Omit<AppHotkeysStoreOptions<T>, 'customHotkeys'>): void;
+  /**
+   * Updates options. Providers call it with their props on every update.
+   *
+   * When `customHotkeys` differs from the value last passed in, it replaces
+   * the current custom hotkeys. An equal value, such as the same saved data
+   * parsed again, keeps changes the user made since. `undefined` changes
+   * nothing, such as while saved data loads; `null` clears them, such as on
+   * sign-out. Replacing does not call `onCustomHotkeysChange`, because the
+   * data came from the app.
+   */
+  setOptions(options: AppHotkeysStoreOptions<T>): void;
   /**
    * Replaces the declarations, for example after hot module replacement.
    * Custom hotkeys for ids that still exist are kept.

package/dist/app-hotkeys.js

@@ -1,9 +1,9 @@
 import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
+import { GLOBAL_SCOPE } from "./_registration.js";
 import { areHotkeysEqual } from "./match.js";
 import { createStore } from "./_store.js";
-import { GLOBAL_SCOPE } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { setAppHotkeysStoreFactory } from "./_app-hotkeys-factory.js";
 
@@ -88,6 +88,31 @@ function sanitizeCustomHotkeys(appHotkeys, saved) {
 	}
 	return result;
 }
+/** Whether two saved values hold the same data. Nothing saved equals `{}`. */
+function sameSavedValue(left, right) {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) || Array.isArray(right)) return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((step, i) => Object.is(step, right[i]));
+	if (typeof left !== "object" || typeof right !== "object") return false;
+	if (left === null || right === null) return false;
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && sameSavedValue(left[key], right[key]));
+}
+/** Copies saved custom hotkeys, so later changes made in place are detected. */
+function copySavedCustomHotkeys(saved) {
+	if (typeof saved !== "object" || saved === null) return saved;
+	const copy = {};
+	for (const [id, value] of Object.entries(saved)) copy[id] = Array.isArray(value) ? [...value] : value;
+	return copy;
+}
+/** Whether two saved custom hotkeys objects hold the same data. */
+function sameSavedCustomHotkeys(left, right) {
+	return sameSavedValue(left === void 0 ? {} : left, right === void 0 ? {} : right);
+}
+/** Whether two sanitized custom hotkeys objects bind the same hotkeys. */
+function sameCustomHotkeys(left, right, platform) {
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && hotkeysEqual(left[key] ?? null, right[key] ?? null, platform));
+}
 /** Whether two app hotkeys can apply at the same time. */
 function scopesOverlap(a, b) {
 	const left = a.scope ?? "global";
@@ -121,9 +146,12 @@ var AppHotkeysStore = class {
 	store;
 	#declarations;
 	#options;
+	/** The `customHotkeys` option last passed in, compared by value. */
+	#savedCustomHotkeys;
 	constructor(appHotkeys, options = {}) {
 		this.#declarations = appHotkeys;
 		this.#options = options;
+		this.#savedCustomHotkeys = copySavedCustomHotkeys(options.customHotkeys);
 		const customHotkeys = sanitizeCustomHotkeys(appHotkeys, options.customHotkeys);
 		this.store = createStore({
 			appHotkeys: applyCustomHotkeys(appHotkeys, customHotkeys),
@@ -141,12 +169,31 @@ var AppHotkeysStore = class {
 	get customHotkeys() {
 		return this.store.state.customHotkeys;
 	}
-	/** Updates callbacks and other options without resetting custom hotkeys. */
+	/**
+	* Updates options. Providers call it with their props on every update.
+	*
+	* When `customHotkeys` differs from the value last passed in, it replaces
+	* the current custom hotkeys. An equal value, such as the same saved data
+	* parsed again, keeps changes the user made since. `undefined` changes
+	* nothing, such as while saved data loads; `null` clears them, such as on
+	* sign-out. Replacing does not call `onCustomHotkeysChange`, because the
+	* data came from the app.
+	*/
 	setOptions(options) {
+		const { customHotkeys, ...rest } = options;
 		this.#options = {
 			...this.#options,
-			...options
+			...rest
 		};
+		if (customHotkeys === void 0) return;
+		if (sameSavedCustomHotkeys(customHotkeys, this.#savedCustomHotkeys)) return;
+		this.#savedCustomHotkeys = copySavedCustomHotkeys(customHotkeys);
+		const next = sanitizeCustomHotkeys(this.#declarations, customHotkeys);
+		if (sameCustomHotkeys(next, this.store.state.customHotkeys, this.#platform)) return;
+		this.store.setState(() => ({
+			appHotkeys: applyCustomHotkeys(this.#declarations, next),
+			customHotkeys: next
+		}));
 	}
 	/**
 	* Replaces the declarations, for example after hot module replacement.

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

@@ -385,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

@@ -4,13 +4,13 @@ import { isKeyNameShape, keysEqual, normalizeKeyboardEvent } from "./_keyboard-e
 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";
 
 //#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") {
@@ -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,8 +360,9 @@ 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") {
-			const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
 			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);
@@ -380,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) {
@@ -689,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/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/app-hotkeys/SKILL.md

@@ -46,12 +46,11 @@ export const appHotkeys = defineAppHotkeys({
 })
 ```
 
-Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup.
+Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup. Pass saved data that loads later to `store.setOptions({ customHotkeys })` on the returned store; providers apply a changed `customHotkeys` prop themselves. `undefined` leaves custom hotkeys unchanged while data loads; `null` clears them, such as on sign-out.
 
 ## Pitfalls
 
 - **Register the app hotkey, not its value.** Pass `appHotkeys['doc.save']`. Passing `.hotkey` registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as `'inactive'`.
-- **The provider reads `customHotkeys` once.** When saved shortcuts load asynchronously, render the provider after they arrive, or key it by user. Change shortcuts afterwards through the adapter's custom hotkeys API, not by updating the prop.
 - **Save what `onCustomHotkeysChange` receives.** It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.
 - **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are dropped with a warning, so renaming an id discards users' customizations.
 - **`setCustomHotkey` returns conflicts and changes nothing when there are any.** Check the result before reporting success, or reject the key press earlier by calling `findConflicts` in the recorder's `validate`.