@tanstack/hotkeys 0.19.0 → 0.20.0

package/dist/_app-hotkeys-factory.d.ts

@@ -0,0 +1,5 @@
+import { AppHotkeys, AppHotkeysStore, AppHotkeysStoreOptions } from "./app-hotkeys.js";
+//#region src/_app-hotkeys-factory.d.ts
+/** Creates the store for app hotkeys from `defineAppHotkeys`. */
+export declare function createAppHotkeysStore<T extends AppHotkeys>(appHotkeys: T, options: AppHotkeysStoreOptions<T>): AppHotkeysStore<T>;
+//#endregion

package/dist/_app-hotkeys-factory.js

@@ -0,0 +1,13 @@
+//#region src/_app-hotkeys-factory.ts
+let factory;
+function setAppHotkeysStoreFactory(create) {
+	factory = create;
+}
+/** Creates the store for app hotkeys from `defineAppHotkeys`. */
+function createAppHotkeysStore(appHotkeys, options) {
+	if (!factory) throw new Error("[hotkeys] App hotkeys must come from defineAppHotkeys.");
+	return factory(appHotkeys, options);
+}
+
+//#endregion
+export { createAppHotkeysStore, setAppHotkeysStoreFactory };

package/dist/_keyboard-event.js

@@ -34,9 +34,8 @@ function codeToLogicalKey(code) {
 	if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase();
 	if (/^Digit[0-9]$/i.test(code)) return code.slice(5);
 	if (/^Numpad[0-9]$/i.test(code)) return code.slice(6);
-	const punctuation = PUNCTUATION_CODE_MAP[code];
-	if (punctuation) return punctuation;
-	return {
+	if (Object.hasOwn(PUNCTUATION_CODE_MAP, code)) return PUNCTUATION_CODE_MAP[code];
+	const named = {
 		NumpadAdd: "+",
 		NumpadSubtract: "-",
 		NumpadMultiply: "*",
@@ -44,7 +43,8 @@ function codeToLogicalKey(code) {
 		NumpadDecimal: ".",
 		NumpadEnter: "Enter",
 		Space: "Space"
-	}[code];
+	};
+	return Object.hasOwn(named, code) ? named[code] : void 0;
 }
 /**
 * Whether AltGr changed what a key typed, as in AltGr+Q typing `@`. False when
@@ -102,6 +102,14 @@ function keysEqual(left, right) {
 function assertLogicalKey(key) {
 	if (/^\[.*\]$/s.test(key.trim())) throw new Error("Logical key must not contain a bracketed physical code. Use the code field instead.");
 }
+/**
+* Whether a key is written like a key the library knows: one character,
+* F1-F24, or a capitalized name such as `Escape`. Key names are
+* case-sensitive, so `escape` and `f1` don't qualify.
+*/
+function isKeyNameShape(key) {
+	return /^(?:.|F(?:[1-9]|1\d|2[0-4])|[A-Z][a-z][A-Za-z\d]*)$/su.test(key);
+}
 
 //#endregion
-export { altGraphTypedCharacter, assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };
+export { altGraphTypedCharacter, assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isKeyNameShape, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };

package/dist/_named-keys.js

@@ -60,6 +60,26 @@ const LOGICAL_ONLY_NAMED_KEYS = [
 	"Hankaku",
 	"ZenkakuHankaku"
 ];
+/** Arrow, Home/End, and PageUp/PageDown keys. */
+const NAVIGATION_KEY_NAMES = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown"
+];
+/** Editing and special keys. */
+const EDITING_KEY_NAMES = [
+	"Enter",
+	"Escape",
+	"Space",
+	"Tab",
+	"Backspace",
+	"Delete"
+];
 
 //#endregion
-export { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS };
+export { EDITING_KEY_NAMES, LOGICAL_ONLY_NAMED_KEYS, NAVIGATION_KEY_NAMES, SHARED_NAMED_KEYS };

package/dist/_registration.js

@@ -35,7 +35,7 @@ function getDefaultIgnoreInputs(parsedChord) {
 function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
 	if (conflictBehavior === "allow") return;
 	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers may be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
+		if (process.env.NODE_ENV !== "production") console.warn(`'${keyDisplay}' is already registered. Multiple handlers may be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
 		return;
 	}
 	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);

package/dist/_store.d.ts

@@ -0,0 +1,14 @@
+import { Store as Store$1 } from "./vendor/@tanstack/store/dist/store.js";
+//#region src/_store.d.ts
+/**
+ * The part of TanStack Store's `Store` that TanStack Hotkeys uses. Its stores
+ * work with TanStack Store's framework adapters, such as `useSelector` from
+ * `@tanstack/react-store`.
+ */
+export type Store<T> = Pick<Store$1<T>, 'state' | 'get' | 'setState' | 'subscribe'>;
+/**
+ * Creates a store. Listeners run synchronously after each change, and an
+ * update to an equal value (by `Object.is`) notifies no one.
+ */
+export declare function createStore<T>(initialState: T): Store<T>;
+//#endregion

package/dist/_store.js

@@ -0,0 +1,43 @@
+//#region src/_store.ts
+const queue = /* @__PURE__ */ new Set();
+function notify(listeners) {
+	for (const listener of listeners) queue.add(listener);
+	for (const listener of queue) {
+		queue.delete(listener);
+		listener();
+	}
+}
+/**
+* Creates a store. Listeners run synchronously after each change, and an
+* update to an equal value (by `Object.is`) notifies no one.
+*/
+function createStore(initialState) {
+	let state = initialState;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		get state() {
+			return state;
+		},
+		get: () => state,
+		setState(updater) {
+			const next = updater(state);
+			if (Object.is(state, next)) return;
+			state = next;
+			notify(listeners);
+		},
+		subscribe(observerOrFn) {
+			const listener = () => {
+				if (typeof observerOrFn === "function") observerOrFn(state);
+				else observerOrFn.next?.(state);
+			};
+			listeners.add(listener);
+			return { unsubscribe() {
+				listeners.delete(listener);
+				queue.delete(listener);
+			} };
+		}
+	};
+}
+
+//#endregion
+export { createStore };

package/dist/adapter.d.ts

@@ -1,6 +1,8 @@
+import { Store, createStore } from "./_store.js";
 import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 //#region src/adapter.d.ts
 /**
  * A hotkey and its callback, with optional per-binding options. Chords accept
@@ -160,4 +162,5 @@ export declare function getHotkeysProviderScopeKey(options: {
  * Returns a function that releases the activation.
  */
 export declare function activateHotkeysProviderScope(key: string): () => void;
-//#endregion
+//#endregion
+export { type Store, createAppHotkeysStore, createStore };

package/dist/adapter.js

@@ -1,7 +1,9 @@
 import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, normalizeHotkey } from "./parse.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";
 
 //#region src/adapter.ts
@@ -171,4 +173,4 @@ function activateHotkeysProviderScope(key) {
 }
 
 //#endregion
-export { activateHotkeysProviderScope, createHotkeyBindings, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };
+export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };

package/dist/app-hotkeys.d.ts

@@ -1,6 +1,6 @@
+import { Store } from "./_store.js";
 import { Hotkey, HotkeyChord, HotkeyMeta, HotkeySequence } from "./hotkey.types.js";
 import { HotkeyChordOptions, HotkeyRegistrationView, HotkeySequenceOptions } from "./hotkey-manager.js";
-import { Store } from "@tanstack/store";
 //#region src/app-hotkeys.d.ts
 type Platform = 'mac' | 'windows' | 'linux';
 type DeclaredOptionKeys = 'capture' | 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';

package/dist/app-hotkeys.js

@@ -2,9 +2,10 @@ import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
 import { areHotkeysEqual } from "./match.js";
+import { createStore } from "./_store.js";
 import { GLOBAL_SCOPE } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
-import { Store } from "@tanstack/store";
+import { setAppHotkeysStoreFactory } from "./_app-hotkeys-factory.js";
 
 //#region src/app-hotkeys.ts
 /**
@@ -22,6 +23,7 @@ import { Store } from "@tanstack/store";
 * ```
 */
 function defineAppHotkeys(definitions) {
+	setAppHotkeysStoreFactory((appHotkeys, options) => new AppHotkeysStore(appHotkeys, options));
 	const result = {};
 	for (const [id, input] of Object.entries(definitions)) {
 		const hotkey = input.hotkey === null ? null : simplifyHotkey(input.hotkey);
@@ -73,13 +75,13 @@ function sanitizeCustomHotkeys(appHotkeys, saved) {
 	if (typeof saved !== "object" || saved === null) return result;
 	for (const [id, value] of Object.entries(saved)) {
 		if (value === void 0) continue;
-		if (!(id in appHotkeys)) {
-			console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
+		if (!Object.hasOwn(appHotkeys, id)) {
+			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
 			continue;
 		}
 		const hotkey = parseCustomHotkey(value);
 		if (hotkey === void 0) {
-			console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
+			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
 			continue;
 		}
 		result[id] = hotkey;
@@ -123,7 +125,7 @@ var AppHotkeysStore = class {
 		this.#declarations = appHotkeys;
 		this.#options = options;
 		const customHotkeys = sanitizeCustomHotkeys(appHotkeys, options.customHotkeys);
-		this.store = new Store({
+		this.store = createStore({
 			appHotkeys: applyCustomHotkeys(appHotkeys, customHotkeys),
 			customHotkeys
 		});
@@ -161,7 +163,8 @@ var AppHotkeysStore = class {
 	}
 	/** Effective app hotkey for an id, or `undefined` when it is not declared. */
 	get(id) {
-		return this.store.state.appHotkeys[id];
+		const { appHotkeys } = this.store.state;
+		return Object.hasOwn(appHotkeys, id) ? appHotkeys[id] : void 0;
 	}
 	/**
 	* Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
@@ -169,7 +172,7 @@ var AppHotkeysStore = class {
 	* hotkeys are equal or one sequence starts with the other.
 	*/
 	findConflicts(id, hotkey) {
-		const self = this.store.state.appHotkeys[id];
+		const self = this.get(id);
 		if (!self) return [];
 		const candidate = simplifyHotkey(hotkey);
 		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && scopesOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
@@ -181,9 +184,9 @@ var AppHotkeysStore = class {
 	* @returns Conflicting app hotkeys. When any exist, nothing changes.
 	*/
 	setCustomHotkey(id, hotkey) {
-		const appHotkey = this.store.state.appHotkeys[id];
+		const appHotkey = this.get(id);
 		if (!appHotkey) {
-			console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
+			if (process.env.NODE_ENV !== "production") console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
 			return [];
 		}
 		const next = hotkey === null ? null : simplifyHotkey(hotkey);

package/dist/constants.d.ts

@@ -107,9 +107,9 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
 /**
  * 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}
@@ -122,16 +122,17 @@ export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "Kan
 /** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 export declare function isSingleLetterKey(key: string): boolean;
 /**
- * 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)
  * ```
  */

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/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.
    */

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 { 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. */
@@ -127,14 +127,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 +194,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",
@@ -353,6 +353,10 @@ var HotkeyManager = class HotkeyManager {
 				parsedChord
 			};
 		}
+		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));
@@ -662,31 +666,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() {

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

@@ -42,8 +42,8 @@ export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationRes
  */
 export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
 /**
- * Validates a hotkey and logs warnings to the console.
- * Useful for development-time feedback.
+ * Validates a hotkey and logs errors and warnings to the console.
+ * Useful for development-time feedback. Logs nothing in production builds.
  *
  * @param hotkey - The hotkey string to validate
  * @returns True if the hotkey is valid (may still have warnings)

package/dist/validate.js

@@ -1,5 +1,4 @@
-import { ALL_KEYS, normalizeKeyName } from "./constants.js";
-import { modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { isKeyNameShape, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
 //#region src/validate.ts
 /**
@@ -62,17 +61,13 @@ function validateChord(hotkey) {
 	const keyPart = parts[parts.length - 1];
 	for (const modifier of modifierParts) if (!modifierAlias(modifier)) errors.push(`Unknown modifier: '${modifier}'`);
 	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && physicalCodeOf(keyPart) === void 0) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
-	if (!isKnownKey(normalizeKeyName(keyPart))) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	if (physicalCodeOf(keyPart) === void 0 && !isKeyNameShape(keyPart)) warnings.push(`Unknown key: '${keyPart}'. Key names are case-sensitive, such as 'Escape' and 'F1'.`);
 	return {
 		valid: errors.length === 0,
 		warnings,
 		errors
 	};
 }
-/** Physical codes, single characters, and named keys are known. */
-function isKnownKey(key) {
-	return physicalCodeOf(key) !== void 0 || Array.from(key).length === 1 || ALL_KEYS.has(key);
-}
 /**
 * Validates a hotkey and throws an error if invalid.
 * Useful for development-time validation.
@@ -91,8 +86,8 @@ function assertValidHotkey(hotkey) {
 	if (!result.valid) throw new Error(`Invalid hotkey '${String(hotkey)}': ${result.errors.join(", ")}`);
 }
 /**
-* Validates a hotkey and logs warnings to the console.
-* Useful for development-time feedback.
+* Validates a hotkey and logs errors and warnings to the console.
+* Useful for development-time feedback. Logs nothing in production builds.
 *
 * @param hotkey - The hotkey string to validate
 * @returns True if the hotkey is valid (may still have warnings)
@@ -106,8 +101,10 @@ function assertValidHotkey(hotkey) {
 */
 function checkHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (result.errors.length > 0) console.error(`Hotkey '${String(hotkey)}' errors:`, result.errors.join("; "));
-	if (result.warnings.length > 0) console.warn(`Hotkey '${String(hotkey)}' warnings:`, result.warnings.join("; "));
+	if (process.env.NODE_ENV !== "production") {
+		if (result.errors.length > 0) console.error(`Hotkey '${String(hotkey)}' errors:`, result.errors.join("; "));
+		if (result.warnings.length > 0) console.warn(`Hotkey '${String(hotkey)}' warnings:`, result.warnings.join("; "));
+	}
 	return result.valid;
 }
 

package/dist/vendor/@tanstack/store/dist/store.d.ts

@@ -0,0 +1,23 @@
+import { Observer, Subscription } from "./types.js";
+//#region ../../node_modules/.pnpm/@tanstack+store@0.11.2/node_modules/@tanstack/store/dist/store.d.ts
+//#region src/store.d.ts
+type StoreAction = (...args: Array<any>) => any;
+type StoreActionMap = Record<string, StoreAction>;
+type StoreActionsFactory<T, TActions extends StoreActionMap> = (store: {
+  setState: Store<T>['setState'];
+  get: Store<T>['get'];
+}) => TActions;
+type NonFunction<T> = T extends ((...args: Array<any>) => any) ? never : T;
+declare class Store<T, TActions extends StoreActionMap = never> {
+  private atom;
+  readonly actions: TActions;
+  constructor(getValue: (prev?: NoInfer<T>) => T);
+  constructor(initialValue: T);
+  constructor(initialValue: NonFunction<T>, actionsFactory: StoreActionsFactory<T, TActions>);
+  setState(updater: (prev: T) => T): void;
+  get state(): T;
+  get(): T;
+  subscribe(observerOrFn: Observer<T> | ((value: T) => void)): Subscription;
+}
+//#endregion
+export { Store, StoreAction, StoreActionMap, StoreActionsFactory };

package/dist/vendor/@tanstack/store/dist/types.d.ts

@@ -0,0 +1,11 @@
+//#region ../../node_modules/.pnpm/@tanstack+store@0.11.2/node_modules/@tanstack/store/dist/types.d.ts
+type Observer<T> = {
+  next?: (value: T) => void;
+  error?: (err: unknown) => void;
+  complete?: () => void;
+};
+interface Subscription {
+  unsubscribe: () => void;
+}
+//#endregion
+export { Observer, Subscription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -39,9 +39,12 @@
     "dist",
     "skills"
   ],
-  "dependencies": {
+  "devDependencies": {
     "@tanstack/store": "^0.11.2"
   },
+  "inlinedDependencies": {
+    "@tanstack/store": "0.11.2"
+  },
   "scripts": {
     "clean": "premove ./build ./dist",
     "lint": "eslint ./src",

package/skills/hotkeys-core/SKILL.md

@@ -33,7 +33,7 @@ The library owns the keyboard. Register every shortcut with your framework adapt
 | Instead of                                                            | Use                                                                                                                                           |
 | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | A `keydown` listener that checks `event.key`, `metaKey`, or `ctrlKey` | A registered hotkey such as `'Mod+S'`. Inside a widget's own key handler, `matchesKeyboardEvent(event, 'Mod+Enter')`.                         |
-| `isMac` checks and `⌘`/`Ctrl` label maps                              | `Mod` in the hotkey, and `formatForDisplay(hotkey)` for labels                                                                                |
+| `isMac` checks and `⌘`/`Ctrl` label maps                              | `Mod` in the hotkey, `formatForDisplay(hotkey)` for labels, or `formatForDisplay({ key })` for held keys                                      |
 | Skipping events from text fields, calling `preventDefault`            | The defaults: single keys and Shift/Alt chords are skipped while typing, `Mod` chords and `Escape` still fire, and matched keys are prevented |
 | A shortcut registry, service, context, or wrapper hook                | The adapter API, called where each action lives. For one list of every shortcut, load `@tanstack/hotkeys#app-hotkeys`.                        |
 | A "shortcuts enabled" flag or topmost-dialog tracking                 | Scopes, with `exclusive` for dialogs                                                                                                          |
@@ -59,6 +59,7 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 - **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. Add `preventDefault: 'always'` to keep the action blocked while the hotkey can't fire, whether it's disabled or its scope is off. Skip it for hotkeys turned off to give the key back to the browser, such as `Mod+C`, `Mod+Z`, `Tab`, or single keys behind a user's off switch. Don't keep the hotkey enabled and return early from the callback; the hotkey would also stay `active` in app hotkey lists and show its hint.
 - **Modifiers match exactly.** `ArrowDown` never fires while Shift is held, so register `Shift+ArrowDown` instead of checking `event.shiftKey`. Shift that a symbol needs is the exception: `?` matches Shift+/.
 - **Chords repeat while held.** Set `requireReset: true` on toggles, or holding the keys flickers them.
+- **Key names are case-sensitive.** Write `Escape`, `ArrowUp`, `F1`, and `+` as the types spell them; `escape`, `Esc`, `f1`, and `Plus` never match. Only letters match in any case. Hotkeys from plain JavaScript or saved data skip the types, so check them with `validateHotkey`.
 - **Letters follow the typed character.** For position-based controls such as WASD, use physical bindings such as `'[KeyW]'`. Keep letters for mnemonic commands such as `Mod+S`.
 - **Each open exclusive scope needs its own name.** A reusable dialog with a fixed scope name breaks when one dialog opens another: both share one scope and both handle `Escape`. Build the name per instance.
 - **A chord on a sequence's first key runs every time the sequence starts.** With `G` and `['G', 'G']`, the first `G` runs the chord. Later keys belong to the sequence. To show "waiting for the next key", read `matchedStepCount` from the adapter's registrations list.