@tanstack/hotkeys 0.15.0 → 0.16.0

package/README.md

@@ -51,7 +51,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is in beta. We are actively developing the library and are open to feedback and contributions.
 
 Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
 

package/dist/_keyboard-event.js

@@ -1,4 +1,4 @@
-import { PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+import { MODIFIER_ALIASES, PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
 
 //#region src/_keyboard-event.ts
 /** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */
@@ -45,8 +45,24 @@ function codeToLogicalKey(code) {
 function isPrintableKey(key) {
 	return key !== "" && Array.from(key).length === 1;
 }
+/**
+* Resolves a modifier token or alias case-insensitively: `ctrl` → `Control`,
+* `cmd` → `Meta`, `mod` → `Mod`. Returns undefined for anything else.
+*/
+function modifierAlias(token) {
+	const lower = token.toLowerCase();
+	return Object.hasOwn(MODIFIER_ALIASES, lower) ? MODIFIER_ALIASES[lower] : void 0;
+}
+/** Whether a string has the shape of a `KeyboardEvent.code`, such as `KeyS`. */
+function isCodeName(code) {
+	return /^[A-Za-z][A-Za-z0-9]*$/.test(code);
+}
+/** The code inside a physical token: `[KeyS]` → `KeyS`. Undefined for anything else. */
+function physicalCodeOf(token) {
+	return token.startsWith("[") && token.endsWith("]") && isCodeName(token.slice(1, -1)) ? token.slice(1, -1) : void 0;
+}
 /** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
-function splitHotkeyParts(hotkey) {
+function splitChordParts(hotkey) {
 	if (!hotkey.endsWith("+")) return hotkey.split("+");
 	const parts = hotkey.slice(0, -1).split("+");
 	if (parts.at(-1) === "") parts.pop();
@@ -72,4 +88,4 @@ function assertLogicalKey(key) {
 }
 
 //#endregion
-export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent, splitHotkeyParts };
+export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };

package/dist/_manager-ref.js

@@ -0,0 +1,10 @@
+//#region src/_manager-ref.ts
+/**
+* The HotkeyManager singleton, once created. Code that only reads the live
+* registry, such as conflict checks, reads this instead of importing the
+* manager, so a recorder bundle does not include hotkey dispatch.
+*/
+const managerRef = { current: null };
+
+//#endregion
+export { managerRef };

package/dist/_match.js

@@ -45,6 +45,14 @@ function modifiersMatch(event, parsed, allowImplicitShift) {
 	if (ctrl !== parsed.ctrl || alt !== parsed.alt || event.meta !== parsed.meta) return false;
 	return event.shift === parsed.shift || allowImplicitShift && event.shift;
 }
+/**
+* Whether two parsed chords have the same identity: equal modifiers, and the
+* same physical code or (case-insensitively) the same logical key. A code and
+* a key never match, even when one keyboard event could produce both.
+*/
+function parsedChordsEqual(a, b) {
+	return a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : keysEqual(a.key, b.key));
+}
 
 //#endregion
-export { matchKeyboardEvent };
+export { matchKeyboardEvent, parsedChordsEqual };

package/dist/_recorder-chord.js

@@ -1,6 +1,6 @@
 import { normalizeKeyName } from "./constants.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isModifierKey, normalizeHotkeyFromParsed, parseKeyboardEvent } from "./parse.js";
+import { isCodeName, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isModifierKey, normalizeHotkey, parseKeyboardEvent } from "./parse.js";
 
 //#region src/_recorder-chord.ts
 /**
@@ -11,16 +11,16 @@ import { isModifierKey, normalizeHotkeyFromParsed, parseKeyboardEvent } from "./
 function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
 	const normalized = normalizeKeyboardEvent(event, platform);
 	if (normalized.isComposing || isModifierKey(normalizeKeyName(event.key)) || event.key === "AltGraph") return null;
-	if (recordBy === "code" && (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) || event.code === "Unidentified" || normalized.altGraph)) return null;
+	if (recordBy === "code" && (!hasUsableCode(event) || normalized.altGraph)) return null;
 	const parsed = parseKeyboardEvent(event, platform);
 	if (recordBy === "code") {
 		const { key: _key, code: _code, ...modifiers } = parsed;
-		return normalizeHotkeyFromParsed({
+		return normalizeHotkey({
 			...modifiers,
 			code: event.code
 		}, platform);
 	}
-	return parsed.key ? normalizeHotkeyFromParsed(parsed, platform) : null;
+	return parsed.key ? normalizeHotkey(parsed, platform) : null;
 }
 /**
 * Explains why a physical chord cannot be recorded before syntax/policy checks.
@@ -32,11 +32,15 @@ function chordRejection(event, options) {
 		reason: "alt-graph",
 		message: "AltGraph character entry cannot be recorded as a physical shortcut. Use key mode for characters."
 	};
-	if (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) || event.code === "Unidentified") return {
+	if (!hasUsableCode(event)) return {
 		reason: "missing-code",
 		message: "This event has no usable physical key code."
 	};
 }
+/** Whether the event reports a real physical key code to record. */
+function hasUsableCode(event) {
+	return isCodeName(event.code) && event.code !== "Unidentified";
+}
 
 //#endregion
 export { chordRejection, hotkeyChordFromKeydown };

package/dist/_registration.js

@@ -1,4 +1,6 @@
 //#region src/_registration.ts
+/** The scope of hotkeys that do not name one. It is always active unless an exclusive scope is active. */
+const GLOBAL_SCOPE = "global";
 /**
 * Default options for hotkey/sequence registration.
 * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
@@ -10,15 +12,16 @@ const defaultHotkeyOptions = {
 	eventType: "keydown",
 	enabled: true,
 	ignoreInputs: "auto",
-	conflictBehavior: "warn"
+	conflictBehavior: "warn",
+	scope: GLOBAL_SCOPE
 };
 /**
 * 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.
 */
-function getDefaultIgnoreInputs(parsedHotkey) {
-	if (parsedHotkey.ctrl || parsedHotkey.meta) return false;
-	if (parsedHotkey.key === "Escape" || parsedHotkey.code === "Escape") return false;
+function getDefaultIgnoreInputs(parsedChord) {
+	if (parsedChord.ctrl || parsedChord.meta) return false;
+	if (parsedChord.key === "Escape" || parsedChord.code === "Escape") return false;
 	return true;
 }
 /**
@@ -47,4 +50,4 @@ function optionsEqual(left, right) {
 }
 
 //#endregion
-export { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };
+export { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };

package/dist/adapter.d.ts

@@ -1,5 +1,5 @@
-import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
-import { HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.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";
 //#region src/adapter.d.ts
 /**
@@ -11,7 +11,7 @@ export type HotkeyDefinition = {
   callback: HotkeyCallback;
   options?: HotkeyChordOptions;
 } | {
-  hotkey: HotkeySequence;
+  hotkey: RegisterableHotkeySequence;
   callback: HotkeyCallback;
   options?: HotkeySequenceOptions;
 };
@@ -55,15 +55,15 @@ export type AdapterAppHotkeyOptions<T extends AppHotkey, TTarget> = Omit<[T['def
  * accept only shared options.
  */
 export type AdapterHotkeyDefinition<TTarget> = {
-  /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+  /** A chord string such as `'Mod+S'`, or a chord object */
   hotkey: RegisterableHotkeyChord;
   /** The function to call when the hotkey is pressed */
   callback: HotkeyCallback;
   /** Per-hotkey options (merged on top of common options) */
   options?: AdapterChordOptions<TTarget>;
 } | {
-  /** A sequence such as `['G', 'G']` */
-  hotkey: HotkeySequence;
+  /** A sequence such as `['G', 'G']`, with each step a string or an object */
+  hotkey: RegisterableHotkeySequence;
   callback: HotkeyCallback;
   options?: AdapterSequenceOptions<TTarget>;
 } | {
@@ -113,4 +113,51 @@ export declare function prepareHotkeyDefinitions<TTarget>(definitions: ReadonlyA
  * unsubscribe function.
  */
 export declare function subscribePublishedAppHotkeys(onChange: () => void): () => void;
+/** Scope props shared by framework providers. */
+export interface HotkeysProviderScopeProps {
+  /**
+   * Scope for hotkeys registered inside this provider, active while it is
+   * mounted and enabled. Defaults to the parent provider's scope, or
+   * `'global'` at the root. App hotkeys that declare a scope keep it.
+   */
+  scope?: string;
+  /**
+   * While mounted and enabled, suspend hotkeys in every other scope,
+   * including `'global'`, except scopes of nested providers. Pass
+   * `{ allow: [...] }` to keep other scopes active, such as `'global'`. Use
+   * with `scope`, for dialogs and other overlays.
+   */
+  exclusive?: ActivateHotkeyScopeOptions['exclusive'];
+  /**
+   * Set false to deactivate this provider's scope, and the scopes of
+   * providers nested in it, without unmounting. Defaults to true.
+   */
+  enabled?: boolean;
+}
+/**
+ * Merges a provider's default options over its parent's. A provider with a
+ * `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+ */
+export declare function mergeHotkeysProviderDefaults<T extends {
+  hotkey?: object;
+  hotkeyRecorder?: object;
+}>(parent: T | undefined, own: T | undefined, scope: string | undefined): T;
+/**
+ * A key for a provider's scope activation, or `null` when the scope should not
+ * be active. Equal keys mean the same activation, so adapters reactivate only
+ * when the key changes, not when an inline `exclusive` object is recreated.
+ */
+export declare function getHotkeysProviderScopeKey(options: {
+  scope: string | undefined;
+  exclusive: ActivateHotkeyScopeOptions['exclusive'];
+  /** Whether this provider and every ancestor are enabled. */
+  active: boolean;
+  /** The parent provider's scope. */
+  parent: string | undefined;
+}): string | null;
+/**
+ * Activates the scope described by a key from `getHotkeysProviderScopeKey`.
+ * Returns a function that releases the activation.
+ */
+export declare function activateHotkeysProviderScope(key: string): () => void;
 //#endregion

package/dist/adapter.js

@@ -1,5 +1,5 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeRegisterableHotkey } from "./parse.js";
+import { isHotkeySequence, normalizeHotkey } from "./parse.js";
 import { defaultHotkeyOptions } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
@@ -28,7 +28,7 @@ function createHotkeyBindings() {
 					platform: merged.platform ?? detectPlatform()
 				};
 				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
-				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
+				const hotkey = normalizeHotkey(definition.hotkey, options.platform);
 				if (isHotkeySequence(hotkey)) delete options.requireReset;
 				else delete options.timeout;
 				prepared.push({
@@ -127,6 +127,48 @@ function subscribePublishedAppHotkeys(onChange) {
 		inner?.unsubscribe();
 	};
 }
+/**
+* Merges a provider's default options over its parent's. A provider with a
+* `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+*/
+function mergeHotkeysProviderDefaults(parent, own, scope) {
+	return {
+		hotkey: {
+			...parent?.hotkey,
+			...own?.hotkey,
+			...scope && { scope }
+		},
+		hotkeyRecorder: {
+			...parent?.hotkeyRecorder,
+			...own?.hotkeyRecorder
+		}
+	};
+}
+/**
+* A key for a provider's scope activation, or `null` when the scope should not
+* be active. Equal keys mean the same activation, so adapters reactivate only
+* when the key changes, not when an inline `exclusive` object is recreated.
+*/
+function getHotkeysProviderScopeKey(options) {
+	const { scope, exclusive, active, parent } = options;
+	if (!scope || !active) return null;
+	return JSON.stringify([
+		scope,
+		typeof exclusive === "object" ? exclusive.allow : !!exclusive,
+		parent ?? null
+	]);
+}
+/**
+* Activates the scope described by a key from `getHotkeysProviderScopeKey`.
+* Returns a function that releases the activation.
+*/
+function activateHotkeysProviderScope(key) {
+	const [scope, exclusive, parent] = JSON.parse(key);
+	return getHotkeyManager().activateScope(scope, {
+		exclusive: Array.isArray(exclusive) ? { allow: exclusive } : exclusive,
+		parent: parent ?? void 0
+	});
+}
 
 //#endregion
-export { createHotkeyBindings, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };
+export { activateHotkeysProviderScope, createHotkeyBindings, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };

package/dist/app-hotkeys.d.ts

@@ -17,11 +17,12 @@ export interface AppHotkeyInput {
   /** Display metadata for cheat sheets and settings screens. */
   meta?: HotkeyMeta;
   /**
-   * Label for where this hotkey applies, such as `'editor'`. App hotkeys with
-   * different contexts may share a hotkey; one without a context conflicts with
-   * any app hotkey that shares its hotkey. It does not affect matching.
+   * Scope this hotkey fires in, such as `'editor'`. Overrides the scope of the
+   * provider it registers under. App hotkeys in different scopes may share a
+   * hotkey; one in the `'global'` scope conflicts with any app hotkey that
+   * shares its hotkey.
    */
-  context?: string;
+  scope?: string;
   /**
    * Options that describe the hotkey itself. Chord defaults accept
    * `requireReset`; sequence defaults accept `timeout`.
@@ -45,7 +46,7 @@ export interface AppHotkey<TId extends string = string, TDefault extends HotkeyC
   /** Hotkey declared in `defineAppHotkeys`. */
   readonly defaultHotkey: TDefault;
   readonly meta?: HotkeyMeta;
-  readonly context?: string;
+  readonly scope?: string;
   readonly options?: AppHotkeyOptions;
 }
 /** A map of app hotkeys keyed by id. */
@@ -110,11 +111,12 @@ export declare function isCustomHotkey(appHotkey: AppHotkey, platform?: Platform
 /**
  * Status of an app hotkey in the running app.
  * - `'active'`: at least one enabled registration
+ * - `'suspended'`: has an enabled registration, but none in an active scope
  * - `'disabled'`: registered, but every registration has `enabled: false`
  * - `'inactive'`: has a hotkey, but nothing has registered it
  * - `'unbound'`: no hotkey assigned
  */
-export type AppHotkeyStatus = 'active' | 'disabled' | 'inactive' | 'unbound';
+export type AppHotkeyStatus = 'active' | 'suspended' | 'disabled' | 'inactive' | 'unbound';
 /** One row of an app hotkey cheat sheet. */
 export interface AppHotkeyListItem<T extends AppHotkey = AppHotkey> {
   appHotkey: T;
@@ -174,7 +176,7 @@ export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
   get(id: string): AppHotkey | undefined;
   /**
    * Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
-   * collide when their contexts match or either has no context, and their
+   * collide when their scopes match or either is `'global'`, and their
    * hotkeys are equal or one sequence starts with the other.
    */
   findConflicts(id: keyof T & string, hotkey: Hotkey): Array<AppHotkey>;
@@ -203,12 +205,13 @@ export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
 export declare function resolveAppHotkey(appHotkey: AppHotkey, store: AppHotkeysStore | null | undefined): AppHotkey;
 /**
  * Options that adapters pass to the manager when registering an app hotkey:
- * declared options, meta, and the app hotkey id. The manager drops options
+ * declared options, scope, meta, and the app hotkey id. The manager drops options
  * that do not apply to the effective hotkey's kind.
  */
 export declare function getAppHotkeyRegistrationOptions(appHotkey: AppHotkey): AppHotkeyOptions & {
   meta?: HotkeyMeta;
   appHotkeyId: string;
+  scope?: string;
 };
 /**
  * Publishes a provider's store on the HotkeyManager so devtools can list

package/dist/app-hotkeys.js

@@ -2,6 +2,7 @@ import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
 import { areHotkeysEqual } from "./match.js";
+import { GLOBAL_SCOPE } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { Store } from "@tanstack/store";
 
@@ -30,7 +31,7 @@ function defineAppHotkeys(definitions) {
 			hotkey,
 			defaultHotkey: hotkey,
 			meta: input.meta,
-			context: input.context,
+			scope: input.scope,
 			options: input.options
 		};
 	}
@@ -86,8 +87,10 @@ function sanitizeCustomHotkeys(appHotkeys, saved) {
 	return result;
 }
 /** Whether two app hotkeys can apply at the same time. */
-function contextsOverlap(a, b) {
-	return a.context === void 0 || b.context === void 0 || a.context === b.context;
+function scopesOverlap(a, b) {
+	const left = a.scope ?? "global";
+	const right = b.scope ?? "global";
+	return left === "global" || right === "global" || left === right;
 }
 /** Whether two hotkeys collide: equal chords, or one sequence starts with the other. */
 function hotkeysOverlap(left, right, platform) {
@@ -162,14 +165,14 @@ var AppHotkeysStore = class {
 	}
 	/**
 	* Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
-	* collide when their contexts match or either has no context, and their
+	* collide when their scopes match or either is `'global'`, and their
 	* hotkeys are equal or one sequence starts with the other.
 	*/
 	findConflicts(id, hotkey) {
 		const self = this.store.state.appHotkeys[id];
 		if (!self) return [];
 		const candidate = simplifyHotkey(hotkey);
-		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && contextsOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
+		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && scopesOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
 	}
 	/**
 	* Sets the user's hotkey for an app hotkey. `null` unbinds it. A hotkey
@@ -224,11 +227,13 @@ var AppHotkeysStore = class {
 			if (list) list.push(registration);
 			else byId.set(id, [registration]);
 		}
+		const manager = getHotkeyManager();
 		return Object.values(this.store.state.appHotkeys).map((appHotkey) => {
 			const registered = byId.get(appHotkey.id) ?? [];
+			const enabled = registered.filter((r) => r.options.enabled !== false);
 			return {
 				appHotkey,
-				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : registered.some((r) => r.options.enabled !== false) ? "active" : "disabled",
+				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : enabled.length === 0 ? "disabled" : enabled.some((r) => manager.isScopeActive(r.options.scope)) ? "active" : "suspended",
 				isCustom: isCustomHotkey(appHotkey, this.#platform),
 				registrations: registered
 			};
@@ -245,12 +250,13 @@ function resolveAppHotkey(appHotkey, store) {
 }
 /**
 * Options that adapters pass to the manager when registering an app hotkey:
-* declared options, meta, and the app hotkey id. The manager drops options
+* declared options, scope, meta, and the app hotkey id. The manager drops options
 * that do not apply to the effective hotkey's kind.
 */
 function getAppHotkeyRegistrationOptions(appHotkey) {
 	return {
 		...appHotkey.options,
+		...appHotkey.scope !== void 0 && { scope: appHotkey.scope },
 		meta: appHotkey.meta,
 		appHotkeyId: appHotkey.id
 	};

package/dist/conflicts.js

@@ -1,9 +1,10 @@
 import { detectPlatform } from "./platform.js";
-import { keysEqual } from "./_keyboard-event.js";
-import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
+import { isHotkeySequence, parseHotkey } from "./parse.js";
+import { parsedChordsEqual } from "./_match.js";
 import { matchesKeyboardEvent } from "./match.js";
 import { getTargetDocument } from "./_event-target.js";
-import { getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { managerRef } from "./_manager-ref.js";
+import { toHotkeyRegistrationView } from "./hotkey-manager.js";
 
 //#region src/conflicts.ts
 /** Whether two targets share a document and one contains the other (or is its window). */
@@ -22,19 +23,19 @@ function findHotkeyConflicts(candidate, options = {}) {
 	const steps = isHotkeySequence(candidate) ? candidate : [candidate];
 	if (steps.length === 0) return [];
 	const platform = options.platform ?? detectPlatform();
-	const parsed = steps.map((step) => parseRegisterableHotkey(step, platform));
+	const parsed = steps.map((step) => parseHotkey(step, platform));
 	const target = options.target ?? (typeof document === "undefined" ? void 0 : document);
 	const conflicts = [];
 	const matches = (registration, bindings) => {
 		if (!options.includeDisabled && registration.options.enabled === false || (registration.options.eventType ?? "keydown") !== (options.eventType ?? "keydown") || options.excludeIds?.includes(registration.id) || options.exclude?.(registration) || options.scope !== "all" && target && !targetsOverlap(target, registration.target)) return false;
 		return parsed.slice(0, Math.min(parsed.length, bindings.length)).every((a, index) => {
-			const b = parseRegisterableHotkey(bindings[index], registration.options.platform);
-			const same = a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : keysEqual(a.key, b.key));
+			const b = parseHotkey(bindings[index], registration.options.platform);
 			const event = options.events?.[index];
-			return same || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
+			return parsedChordsEqual(a, b) || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
 		});
 	};
-	for (const registration of getHotkeyManager().registrations.state.values()) {
+	const registrations = managerRef.current?.registrations.state.values() ?? [];
+	for (const registration of registrations) {
 		const view = toHotkeyRegistrationView(registration);
 		if (matches(view, view.kind === "sequence" ? view.hotkey : [view.hotkey])) conflicts.push({ registration: view });
 	}

package/dist/constants.d.ts

@@ -119,30 +119,7 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
  * @see {@link PUNCTUATION_KEYS}
  */
 export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "KanaMode" | "NonConvert" | "Help" | "Insert" | "NumLock" | "Fn" | "FnLock" | "PrintScreen" | "ScrollLock" | "Pause" | "BrowserBack" | "BrowserFavorites" | "BrowserForward" | "BrowserHome" | "BrowserRefresh" | "BrowserSearch" | "BrowserStop" | "Eject" | "LaunchMail" | "MediaPlayPause" | "MediaStop" | "MediaTrackNext" | "MediaTrackPrevious" | "Power" | "AudioVolumeDown" | "AudioVolumeMute" | "AudioVolumeUp" | "WakeUp" | "Hyper" | "Super" | "Again" | "Copy" | "Cut" | "Find" | "Open" | "Paste" | "Props" | "Select" | "Undo" | "Hiragana" | "Katakana" | "Clear" | "Cancel" | "Standby" | "LaunchApplication1" | "LaunchApplication2" | "LaunchMediaPlayer" | "HangulMode" | "HanjaMode" | "Zenkaku" | "Hankaku" | "ZenkakuHankaku" | LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey>;
-/**
- * Normalizes a key name to its canonical form.
- *
- * Converts various key name formats (aliases, case variations) into the standard
- * canonical names used throughout the library. This enables a more forgiving API
- * where users can write keys in different ways and still get correct behavior.
- *
- * Normalization rules:
- * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
- * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
- * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
- * 4. Other keys → returned as-is (already canonical or unknown)
- *
- * @param key - The key name to normalize (can be an alias, lowercase, etc.)
- * @returns The canonical key name
- *
- * @example
- * ```ts
- * normalizeKeyName('esc') // 'Escape'
- * normalizeKeyName('a') // 'A'
- * normalizeKeyName('f1') // 'F1'
- * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
- * ```
- */
+/** 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.

package/dist/constants.js

@@ -28,7 +28,7 @@ const MODIFIER_ORDER = [
 * a modifier is released so we can clear non-modifier keys whose keyup events
 * may have been swallowed by the OS (e.g. macOS Cmd+key combos).
 */
-const MODIFIER_KEYS = new Set(MODIFIER_ORDER);
+const MODIFIER_KEYS = /* @__PURE__ */ new Set(MODIFIER_ORDER);
 /**
 * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.
 *
@@ -283,89 +283,28 @@ const ALL_KEYS = /* @__PURE__ */ new Set([
 	...SHARED_NAMED_KEYS,
 	...LOGICAL_ONLY_NAMED_KEYS
 ]);
-const CANONICAL_KEY_NAMES = new Map(Array.from(ALL_KEYS, (key) => [key.toLowerCase(), key]));
 /**
-* Maps key name aliases to their canonical form.
-*
-* Handles common variations and alternative names for keys to provide a more
-* forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and
-* they'll all normalize to 'Escape'.
-*
-* This map is used internally by `normalizeKeyName()` to convert user input
-* into the canonical key names used throughout the library.
-*
-* @remarks Case-insensitive lookups are supported via lowercase variants
-*
-* @example
-* ```ts
-* KEY_ALIASES['Esc'] // 'Escape'
-* KEY_ALIASES['Del'] // 'Delete'
-* KEY_ALIASES['Up'] // 'ArrowUp'
-* ```
-*/
-const KEY_ALIASES = {
-	Plus: "+",
-	plus: "+",
-	Esc: "Escape",
-	esc: "Escape",
-	escape: "Escape",
-	Return: "Enter",
-	return: "Enter",
-	enter: "Enter",
-	" ": "Space",
-	space: "Space",
-	Spacebar: "Space",
-	spacebar: "Space",
-	tab: "Tab",
-	backspace: "Backspace",
-	Del: "Delete",
-	del: "Delete",
-	delete: "Delete",
-	Up: "ArrowUp",
-	up: "ArrowUp",
-	arrowup: "ArrowUp",
-	Down: "ArrowDown",
-	down: "ArrowDown",
-	arrowdown: "ArrowDown",
-	Left: "ArrowLeft",
-	left: "ArrowLeft",
-	arrowleft: "ArrowLeft",
-	Right: "ArrowRight",
-	right: "ArrowRight",
-	arrowright: "ArrowRight",
-	home: "Home",
-	end: "End",
-	pageup: "PageUp",
-	pagedown: "PageDown",
-	PgUp: "PageUp",
-	PgDn: "PageDown",
-	pgup: "PageUp",
-	pgdn: "PageDown"
-};
-/**
-* Normalizes a key name to its canonical form.
-*
-* Converts various key name formats (aliases, case variations) into the standard
-* canonical names used throughout the library. This enables a more forgiving API
-* where users can write keys in different ways and still get correct behavior.
-*
-* Normalization rules:
-* 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
-* 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
-* 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
-* 4. Other keys → returned as-is (already canonical or unknown)
-*
-* @param key - The key name to normalize (can be an alias, lowercase, etc.)
-* @returns The canonical key name
-*
-* @example
-* ```ts
-* normalizeKeyName('esc') // 'Escape'
-* normalizeKeyName('a') // 'A'
-* normalizeKeyName('f1') // 'F1'
-* normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
-* ```
+* 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"]
+]);
+/** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 function isSingleLetterKey(key) {
 	return /^\p{Letter}$/u.test(key);
 }
@@ -385,7 +324,6 @@ function isSingleLetterKey(key) {
 */
 function normalizeKeyName(key) {
 	if (!key) return "";
-	if (key in KEY_ALIASES) return KEY_ALIASES[key];
 	if (isSingleLetterKey(key)) {
 		const upper = key.toUpperCase();
 		return upper.length === 1 ? upper : key;