@tanstack/hotkeys 0.20.0 → 0.22.0

package/dist/_keyboard-event.js

@@ -22,7 +22,7 @@ function normalizeKeyboardEvent(event, platform) {
 		meta: Boolean(event.metaKey),
 		altGraph: altGraph && !controlAlt,
 		location: event.location,
-		isComposing: Boolean(event.isComposing) || key === "Process" || key === "Unidentified"
+		isComposing: Boolean(event.isComposing) || event.keyCode === 229 || key === "Process" || key === "Unidentified"
 	};
 }
 /**
@@ -93,10 +93,15 @@ function isAsciiLetter(key) {
 function isLatinLetter(key) {
 	return /^\p{Script_Extensions=Latin}$/u.test(key);
 }
+let collator;
 /** Compares letters without case, preserving accents and avoiding expansions such as ß → SS. */
 function keysEqual(left, right) {
-	if (/^\p{Letter}$/u.test(left) && /^\p{Letter}$/u.test(right)) return left.localeCompare(right, void 0, { sensitivity: "accent" }) === 0;
-	return left === right;
+	if (left === right) return true;
+	if (/^\p{Letter}$/u.test(left) && /^\p{Letter}$/u.test(right)) {
+		collator ??= new Intl.Collator(void 0, { sensitivity: "accent" });
+		return collator.compare(left, right) === 0;
+	}
+	return false;
 }
 /** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */
 function assertLogicalKey(key) {

package/dist/_match.js

@@ -11,7 +11,7 @@ function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 		matched: false,
 		score: 0
 	};
-	if (normalized.isComposing && (parsed.code !== void 0 || isPrintableKey(parsed.key))) return noMatch;
+	if (normalized.isComposing) return noMatch;
 	if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch;
 	if (normalized.altGraph && !altGraphTypedCharacter(normalized)) return noMatch;
 	if (parsed.code !== void 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 || 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/_target-listeners.js

@@ -9,11 +9,7 @@ var TargetListeners = class {
 	}
 	add(target, capture, id) {
 		if (typeof document === "undefined") return;
-		let phases = this.#targets.get(target);
-		if (!phases) {
-			phases = /* @__PURE__ */ new Map();
-			this.#targets.set(target, phases);
-		}
+		const phases = this.#targets.get(target) ?? /* @__PURE__ */ new Map();
 		let group = phases.get(capture);
 		if (!group) {
 			const ids = /* @__PURE__ */ new Set();
@@ -41,9 +37,10 @@ var TargetListeners = class {
 				keydown: listener("keydown"),
 				keyup: listener("keyup")
 			};
-			phases.set(capture, group);
 			target.addEventListener("keydown", group.keydown, capture);
 			target.addEventListener("keyup", group.keyup, capture);
+			phases.set(capture, group);
+			this.#targets.set(target, phases);
 		}
 		group.ids.add(id);
 	}

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,31 @@ function chordString(chord, parsed) {
 function generateId() {
 	return `hotkey_${++registrationIdCounter}`;
 }
+/** A handle for a registration that listens for nothing. */
+function inactiveHandle(callback) {
+	let currentCallback = callback;
+	return {
+		id: generateId(),
+		unregister: () => {},
+		get callback() {
+			return currentCallback;
+		},
+		set callback(newCallback) {
+			currentCallback = newCallback;
+		},
+		setOptions: () => {},
+		get isActive() {
+			return false;
+		}
+	};
+}
+/** 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") {
@@ -297,37 +322,19 @@ var HotkeyManager = class HotkeyManager {
 	}
 	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 {
-				id: generateId(),
-				unregister: () => {},
-				get callback() {
-					return currentCallback;
-				},
-				set callback(newCallback) {
-					currentCallback = newCallback;
-				},
-				setOptions: () => {},
-				get isActive() {
-					return false;
-				}
-			};
-		}
+		if (hotkey == null || isHotkeySequence(hotkey) && hotkey.length === 0 || typeof document === "undefined" && !options.target) return inactiveHandle(callback);
 		const id = generateId();
 		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,14 +360,15 @@ var HotkeyManager = class HotkeyManager {
 				parsedChord
 			};
 		}
+		const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
+		if (!steps.every(chordHasKey)) return inactiveHandle(callback);
 		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);
 		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));
 		this.#listeners.add(target, !!registration.options.capture, id);
+		this.registrations.setState((prev) => new Map(prev).set(id, registration));
 		const manager = this;
 		return {
 			get id() {
@@ -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) {
@@ -504,7 +517,7 @@ var HotkeyManager = class HotkeyManager {
 				this.#fire(registration, event);
 				continue;
 			}
-			if (!registration.options.requireReset || !registration.hasFired) {
+			if (!registration.options.requireReset || !registration.hasFired || !event.repeat) {
 				if (registration.options.requireReset) {
 					registration.hasFired = true;
 					registration.activeMatch = match.identity;
@@ -635,13 +648,13 @@ var HotkeyManager = class HotkeyManager {
 		};
 	}
 	/**
-	* Finds an existing registration on the same target and scope whose steps
+	* Finds an existing registration on the same target, scope, and event type 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(candidate) {
 		const steps = resolvedSteps(candidate);
-		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && registration.options.scope === candidate.options.scope && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
+		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && registration.options.scope === candidate.options.scope && registration.options.eventType === candidate.options.eventType && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
 		return null;
 	}
 	/**
@@ -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/key-state-tracker.js

@@ -100,11 +100,14 @@ var KeyStateTracker = class KeyStateTracker {
 				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#reconcileModifiers(event);
-			if (MODIFIER_KEYS.has(key)) {
-				for (const [entryIdentity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
-			}
+			if (MODIFIER_KEYS.has(key)) this.#releaseNonModifiers();
 			this.#syncState();
 		};
+		const onContextMenu = (event) => {
+			if (event.defaultPrevented || !event.isTrusted) return;
+			const reconciled = this.#reconcileModifiers(event);
+			if (this.#releaseNonModifiers() || reconciled) this.#syncState();
+		};
 		const onMouse = (event) => {
 			if (this.#reconcileModifiers(event)) this.#syncState();
 		};
@@ -139,6 +142,16 @@ var KeyStateTracker = class KeyStateTracker {
 				"blur",
 				onBlur,
 				false
+			],
+			[
+				"contextmenu",
+				onContextMenu,
+				false
+			],
+			[
+				"visibilitychange",
+				() => document.hidden && onBlur(),
+				false
 			]
 		];
 		for (const [type, listener, capture] of this.#listeners) window.addEventListener(type, listener, capture);
@@ -159,6 +172,15 @@ var KeyStateTracker = class KeyStateTracker {
 		}
 		return changed;
 	}
+	/** Forgets every held key that isn't a modifier. Returns whether any was held. */
+	#releaseNonModifiers() {
+		let changed = false;
+		for (const [identity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) {
+			this.#heldEntries.delete(identity);
+			changed = true;
+		}
+		return changed;
+	}
 	/**
 	* Syncs the internal Set to the Store state.
 	*/

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/dist/validate.d.ts

@@ -50,9 +50,13 @@ export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
  *
  * @example
  * ```ts
- * checkHotkey('Alt+C')
- * // Console: Warning: Alt+C may not work reliably on macOS...
+ * checkHotkey('Control+escape')
+ * // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
  * // Returns: true
+ *
+ * checkHotkey('Ctl+K')
+ * // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+ * // Returns: false
  * ```
  */
 export declare function checkHotkey(hotkey: ValidatableHotkey): boolean;

package/dist/validate.js

@@ -94,9 +94,13 @@ function assertValidHotkey(hotkey) {
 *
 * @example
 * ```ts
-* checkHotkey('Alt+C')
-* // Console: Warning: Alt+C may not work reliably on macOS...
+* checkHotkey('Control+escape')
+* // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
 * // Returns: true
+*
+* checkHotkey('Ctl+K')
+* // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+* // Returns: false
 * ```
 */
 function checkHotkey(hotkey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.20.0",
+  "version": "0.22.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`.

package/skills/hotkeys-core/references/testing.md

@@ -4,4 +4,4 @@
 - **Reset between tests.** Call `HotkeyManager.resetInstance()`, plus `KeyStateTracker.resetInstance()` for held-key tests, in `afterEach`. Registrations and scope activations otherwise outlive a test that fails before unmounting.
 - **Dispatch real events.** Use `new KeyboardEvent('keydown', { key: 's', code: 'KeyS', metaKey: true, bubbles: true, cancelable: true })`. Physical bindings such as `[KeyS]` match only `code`. Check `event.defaultPrevented` to assert the browser action was blocked.
 - **Dispatch where focus is.** For a hotkey with a `target`, or to test typing in a field, focus the element and dispatch on it with `bubbles: true`.
-- **Repeats and sequences.** `repeat: true` simulates holding a key; it fires chords again unless they set `requireReset`, and it never advances a sequence. Use fake timers to test a sequence's `timeout` (1000 ms by default).
+- **Repeats and sequences.** `repeat: true` simulates holding a key; it fires chords again unless they set `requireReset`, and it never advances a sequence. A keydown without `repeat` is a new press, so it fires a `requireReset` chord even without a keyup in between. Use fake timers to test a sequence's `timeout` (1000 ms by default).