@tanstack/hotkeys 0.23.0 → 0.25.0

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

@@ -1,5 +1,3 @@
 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
+export declare function createAppHotkeysStore<T extends AppHotkeys>(appHotkeys: T, options: AppHotkeysStoreOptions<T>): AppHotkeysStore<T>;

package/dist/_app-hotkeys-factory.js

@@ -1,13 +1,12 @@
-//#region src/_app-hotkeys-factory.ts
+// 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.");
+	if (!factory) throw new Error("[hotkeys] App hotkeys must come from defineAppHotkeys");
 	return factory(appHotkeys, options);
 }
 
-//#endregion
 export { createAppHotkeysStore, setAppHotkeysStoreFactory };

package/dist/_event-target.js

@@ -1,6 +1,7 @@
+import { codeToLogicalKey } from "./_keyboard-event.js";
 import { normalizeKeyName } from "./constants.js";
 
-//#region src/_event-target.ts
+// src/_event-target.ts
 function isElement(node) {
 	return node?.nodeType === 1;
 }
@@ -220,11 +221,11 @@ function getOwnedKeys(element) {
 * are never owned; Enter and Space are owned only without modifiers, while
 * navigation and typeahead keys allow Shift (for example, to extend a selection).
 */
-function ownsKey(element, event, key) {
+function ownsKey(element, event, key, produced) {
 	if (event.ctrlKey || event.metaKey || event.altKey) return false;
 	const owned = getOwnedKeys(element);
 	if (key === "Enter" || key === "Space") return !event.shiftKey && owned.includes(key);
-	return owned.includes(key) || owned.includes(TYPEAHEAD) && /^.$/u.test(event.key);
+	return owned.includes(key) || owned.includes(TYPEAHEAD) && /^.$/u.test(produced);
 }
 /**
 * Finds the first element on the event's way out that blocks it, walking out
@@ -250,6 +251,38 @@ function findBlocker(event, doc, test) {
 function blocks({ elements, index }, target) {
 	return index >= 0 && (isDocumentLevel(target) || index < elements.indexOf(target));
 }
+/** Open modal dialogs and popovers that close on Escape, per event. */
+const layerCache = /* @__PURE__ */ new WeakMap();
+/** Whether `node` is `layer` or inside it, across shadow roots. */
+function isInside(node, layer) {
+	for (; node; node = composedParent(node)) if (node === layer) return true;
+	return false;
+}
+/**
+* Returns whether Escape will close a modal `<dialog>` or an open popover that
+* `target` isn't inside. The browser closes it only when Escape's keydown
+* isn't prevented, so hotkeys outside it leave Escape alone.
+*/
+function closesNativeLayer(event, target) {
+	if (event.type !== "keydown" || event.key !== "Escape") return false;
+	let layers = layerCache.get(event);
+	if (!layers) {
+		const doc = getTargetDocument(target);
+		const focused = getDeepActiveElement(doc);
+		const query = (selector) => {
+			try {
+				return [...doc.querySelectorAll(selector)];
+			} catch {
+				return [];
+			}
+		};
+		const dialogs = query("dialog:modal");
+		const holding = dialogs.filter((dialog) => isInside(focused, dialog));
+		layers = [...holding.length ? holding : dialogs, ...query(":popover-open").filter((layer) => layer.popover !== "manual")];
+		layerCache.set(event, layers);
+	}
+	return layers.some((layer) => isDocumentLevel(target) || !isInside(target, layer));
+}
 const ignoreCache = /* @__PURE__ */ new WeakMap();
 /**
 * Returns whether a hotkey on `target` should skip an event because a control
@@ -264,8 +297,9 @@ const ignoreCache = /* @__PURE__ */ new WeakMap();
 function shouldIgnoreInputEvent(event, target) {
 	let blocker = ignoreCache.get(event);
 	if (!blocker) {
-		const key = normalizeKeyName(event.key);
-		blocker = findBlocker(event, getTargetDocument(target), (element) => isInputElement(element) || ownsKey(element, event, key));
+		const produced = event.key === "Unidentified" ? codeToLogicalKey(event.code) ?? event.code : event.key;
+		const key = normalizeKeyName(produced);
+		blocker = findBlocker(event, getTargetDocument(target), (element) => isInputElement(element) || ownsKey(element, event, key, produced));
 		ignoreCache.set(event, blocker);
 	}
 	return blocks(blocker, target);
@@ -279,5 +313,4 @@ function isTypingEvent(event, target) {
 	return blocks(findBlocker(event, getTargetDocument(target), isInputElement), target);
 }
 
-//#endregion
-export { getTargetDocument, isDocumentLevel, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };
+export { closesNativeLayer, getTargetDocument, isDocumentLevel, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };

package/dist/_keyboard-event.js

@@ -1,6 +1,6 @@
 import { MODIFIER_ALIASES, PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
 
-//#region src/_keyboard-event.ts
+// src/_keyboard-event.ts
 /** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */
 function normalizeKeyboardEvent(event, platform) {
 	let altGraph = false;
@@ -22,7 +22,7 @@ function normalizeKeyboardEvent(event, platform) {
 		meta: Boolean(event.metaKey),
 		altGraph: altGraph && !controlAlt,
 		location: event.location,
-		isComposing: Boolean(event.isComposing) || event.keyCode === 229 || key === "Process" || key === "Unidentified"
+		isComposing: Boolean(event.isComposing) || event.keyCode === 229 || key === "Process" || key === "Unidentified" && (!event.code || event.code === "Unidentified" || isModifierCode(event.code))
 	};
 }
 /**
@@ -77,6 +77,10 @@ function isCodeName(code) {
 function physicalCodeOf(token) {
 	return token.startsWith("[") && token.endsWith("]") && isCodeName(token.slice(1, -1)) ? token.slice(1, -1) : void 0;
 }
+/** Whether a `KeyboardEvent.code` is a modifier key, such as `ShiftLeft`. */
+function isModifierCode(code) {
+	return /^(Control|Shift|Alt|Meta)(Left|Right)$/.test(code);
+}
 /** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
 function splitChordParts(hotkey) {
 	if (!hotkey.endsWith("+")) return hotkey.split("+");
@@ -105,7 +109,7 @@ function keysEqual(left, right) {
 }
 /** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */
 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.");
+	if (/^\[.*\]$/s.test(key.trim())) throw new Error(`[hotkeys] Put '${key}' in the code field, not key`);
 }
 /**
 * Whether a key is written like a key the library knows: one character,
@@ -116,5 +120,4 @@ 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, isKeyNameShape, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };
+export { altGraphTypedCharacter, assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isKeyNameShape, isLatinLetter, isModifierCode, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };

package/dist/_manager-ref.js

@@ -1,4 +1,4 @@
-//#region src/_manager-ref.ts
+// 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
@@ -6,5 +6,4 @@
 */
 const managerRef = { current: null };
 
-//#endregion
 export { managerRef };

package/dist/_match.js

@@ -1,8 +1,8 @@
-import { detectPlatform } from "./platform.js";
 import { altGraphTypedCharacter, codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { parseHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/_match.ts
+// src/_match.ts
 /** Matches an event and reports the winning candidate and release identity. */
 function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
@@ -44,6 +44,8 @@ function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 * output that can't name a shortcut falls back:
 * - non-Latin letters and symbols, such as Russian `ы` or macOS Option's `–`
 * - dead keys
+* - `Unidentified` keys, except on letter positions, which layouts such as
+*   AZERTY rearrange. Chrome on Linux Wayland reports Ctrl+` this way.
 * - anything on the digit row, where AZERTY types `&` and `é` for 1 and 2
 * - ASCII symbols typed with Shift, such as `!` for Shift+1
 * - Latin letters on punctuation keys with Control or Command, so German
@@ -54,6 +56,7 @@ function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 * sits. AZERTY's `+` on the US `/` position is `+`, not `/`.
 */
 function positionStandsIn({ key, code, ctrl, meta, shift, alt }) {
+	if (key === "Unidentified") return !code.startsWith("Key");
 	if (key !== "Dead" && !isPrintableKey(key)) return false;
 	if (code.startsWith("Digit")) return true;
 	if (isAsciiLetter(key)) return false;
@@ -77,5 +80,4 @@ 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, parsedChordsEqual };

package/dist/_named-keys.d.ts

@@ -1,6 +1,4 @@
-//#region src/_named-keys.d.ts
 /** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
 export declare const SHARED_NAMED_KEYS: readonly ["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"];
 /** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
-export declare const LOGICAL_ONLY_NAMED_KEYS: readonly ["Clear", "Cancel", "Standby", "LaunchApplication1", "LaunchApplication2", "LaunchMediaPlayer", "HangulMode", "HanjaMode", "Zenkaku", "Hankaku", "ZenkakuHankaku"];
-//#endregion
+export declare const LOGICAL_ONLY_NAMED_KEYS: readonly ["Clear", "Cancel", "Standby", "LaunchApplication1", "LaunchApplication2", "LaunchMediaPlayer", "HangulMode", "HanjaMode", "Zenkaku", "Hankaku", "ZenkakuHankaku"];

package/dist/_named-keys.js

@@ -1,4 +1,4 @@
-//#region src/_named-keys.ts
+// src/_named-keys.ts
 /** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
 const SHARED_NAMED_KEYS = [
 	"CapsLock",
@@ -81,5 +81,4 @@ const EDITING_KEY_NAMES = [
 	"Delete"
 ];
 
-//#endregion
 export { EDITING_KEY_NAMES, LOGICAL_ONLY_NAMED_KEYS, NAVIGATION_KEY_NAMES, SHARED_NAMED_KEYS };

package/dist/_recorder-chord.js

@@ -1,11 +1,12 @@
-import { normalizeKeyName } from "./constants.js";
 import { isCodeName, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { normalizeKeyName } from "./constants.js";
 import { isModifierKey, normalizeHotkey, parseKeyboardEvent } from "./parse.js";
 
-//#region src/_recorder-chord.ts
+// src/_recorder-chord.ts
 /**
 * Converts a keydown to a replayable chord, preserving physical codes by default.
-* Returns null for composition, modifier-only input, or unusable physical input.
+* Returns null for composition, modifier-only input, unusable physical input,
+* or an `Unidentified` key in key mode.
 * Key mode retains the produced character; neither mode guesses layout letters.
 */
 function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
@@ -20,7 +21,7 @@ function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
 			code: event.code
 		}, platform);
 	}
-	return parsed.key ? normalizeHotkey(parsed, platform) : null;
+	return parsed.key && parsed.key !== "Unidentified" ? normalizeHotkey(parsed, platform) : null;
 }
 /**
 * Explains why a physical chord cannot be recorded before syntax/policy checks.
@@ -28,19 +29,12 @@ function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
 */
 function chordRejection(event, options) {
 	if (options.recordBy === "key") return void 0;
-	if (normalizeKeyboardEvent(event, options.platform).altGraph) return {
-		reason: "alt-graph",
-		message: "AltGraph character entry cannot be recorded as a physical shortcut. Use key mode for characters."
-	};
-	if (!hasUsableCode(event)) return {
-		reason: "missing-code",
-		message: "This event has no usable physical key code."
-	};
+	if (normalizeKeyboardEvent(event, options.platform).altGraph) return { reason: "alt-graph" };
+	if (!hasUsableCode(event)) return { reason: "missing-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/_recording-guard.js

@@ -1,6 +1,6 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 
-//#region src/_recording-guard.ts
+// src/_recording-guard.ts
 const sessions = /* @__PURE__ */ new Set();
 const captured = /* @__PURE__ */ new WeakSet();
 const pending = /* @__PURE__ */ new Map();
@@ -51,5 +51,4 @@ function isRecordingEvent(event) {
 	return sessions.size > 0 || captured.has(event) || pending.has(identity(event));
 }
 
-//#endregion
 export { beginRecording, captureRecordingEvent, endRecording, isRecordingEvent };

package/dist/_registration.d.ts

@@ -1,4 +1,3 @@
-//#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
@@ -10,5 +9,4 @@ export declare function definedOptions<T extends object>(...layers: ReadonlyArra
  * `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
+export declare function withDefaults<T extends object>(defaults: object | undefined, options: T | undefined): T;

package/dist/_registration.js

@@ -1,4 +1,6 @@
-//#region src/_registration.ts
+import { isModifierCode, modifierAlias } from "./_keyboard-event.js";
+
+// 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";
 /**
@@ -42,9 +44,13 @@ function withDefaults(defaults, options) {
 		...definedOptions(defaults, options)
 	};
 }
-/** Whether a parsed chord has a key. An empty one would match key-less events. */
+/**
+* Whether a parsed chord has a key that isn't a modifier. A chord without one
+* registers nothing: an empty key would match key-less events, and a
+* modifier-only chord isn't supported.
+*/
 function chordHasKey(chord) {
-	return !!(chord.code || chord.key);
+	return chord.code !== void 0 ? !!chord.code && !isModifierCode(chord.code) : !!chord.key && !modifierAlias(chord.key);
 }
 /**
 * Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).
@@ -66,10 +72,10 @@ function getDefaultIgnoreInputs(parsedChord) {
 function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
 	if (conflictBehavior === "allow") return;
 	if (conflictBehavior === "warn") {
-		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.`);
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") console.warn(`[hotkeys] '${keyDisplay}' is already registered`);
 		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.`);
+	if (conflictBehavior === "error") throw new Error(`[hotkeys] '${keyDisplay}' is already registered`);
 	unregister(conflictingId);
 }
 /** Compare updates without publishing unchanged options, including fresh metadata objects. */
@@ -80,5 +86,4 @@ function optionsEqual(left, right) {
 	return keys.length === Object.keys(b).length && keys.every((key) => key === "meta" && a[key] && b[key] ? optionsEqual(a[key], b[key]) : Object.is(a[key], b[key]));
 }
 
-//#endregion
 export { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual, withDefaults };

package/dist/_server.js

@@ -1,4 +1,4 @@
-//#region src/_server.ts
+// src/_server.ts
 const SERVER_AGENT = /^(?:Node\.js\/|Deno\/|Bun\/|Cloudflare-Workers)/;
 /** Whether this runs on a server: no `navigator`, or a server runtime's. */
 function isServerRuntime() {
@@ -11,11 +11,10 @@ let warned = false;
 * users on macOS and Windows after hydration.
 */
 function warnServerPlatform() {
-	if (process.env.NODE_ENV !== "production" && !warned && isServerRuntime()) {
+	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && !warned && isServerRuntime()) {
 		warned = true;
-		console.warn("[TanStack Hotkeys] A hotkey label was formatted during server rendering without a platform, so it uses 'linux'. Mac and Windows users get a different label after hydration. Read the platform from the request with `detectPlatform(userAgent)`, set it as the `platform` of your hotkeys provider or scope, and format labels with your adapter's formatter, such as `useFormatForDisplay`. Or render the labels only in the browser. See the server rendering section of the Displaying Hotkeys guide.");
+		console.warn("[hotkeys] Server-rendered label uses 'linux'. Set the provider's platform with detectPlatform(userAgent)");
 	}
 }
 
-//#endregion
 export { isServerRuntime, warnServerPlatform };

package/dist/_store.d.ts

@@ -1,5 +1,4 @@
 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
@@ -10,5 +9,4 @@ export type Store<T> = Pick<Store$1<T>, 'state' | 'get' | 'setState' | 'subscrib
  * 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
+export declare function createStore<T>(initialState: T): Store<T>;

package/dist/_store.js

@@ -1,4 +1,4 @@
-//#region src/_store.ts
+// src/_store.ts
 const queue = /* @__PURE__ */ new Set();
 function notify(listeners) {
 	for (const listener of listeners) queue.add(listener);
@@ -39,5 +39,4 @@ function createStore(initialState) {
 	};
 }
 
-//#endregion
 export { createStore };

package/dist/_target-listeners.js

@@ -1,4 +1,4 @@
-//#region src/_target-listeners.ts
+// src/_target-listeners.ts
 /** Shares keyboard listeners within each target and capture phase. */
 var TargetListeners = class {
 	dispatch;
@@ -7,10 +7,19 @@ var TargetListeners = class {
 	constructor(dispatch) {
 		this.dispatch = dispatch;
 	}
-	add(target, capture, id) {
+	/**
+	* Adds a registration to the target's shared listener. With `last`, an
+	* existing listener moves after listeners added since it, such as one a
+	* framework attached later to delegate key events.
+	*/
+	add(target, capture, id, last = false) {
 		if (typeof document === "undefined") return;
 		const phases = this.#targets.get(target) ?? /* @__PURE__ */ new Map();
 		let group = phases.get(capture);
+		if (group && last) for (const type of ["keydown", "keyup"]) {
+			target.removeEventListener(type, group[type], capture);
+			target.addEventListener(type, group[type], capture);
+		}
 		if (!group) {
 			const ids = /* @__PURE__ */ new Set();
 			const listener = (eventType) => (rawEvent) => {
@@ -66,5 +75,4 @@ var TargetListeners = class {
 	}
 };
 
-//#endregion
 export { TargetListeners };

package/dist/adapter.d.ts

@@ -1,11 +1,10 @@
-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 { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
+import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { HotkeyPlatform } from "./platform.js";
+import { Store, createStore } from "./_store.js";
 import { definedOptions, withDefaults } from "./_registration.js";
 import { createAppHotkeysStore } from "@tanstack/hotkeys";
-//#region src/adapter.d.ts
 /**
  * A hotkey and its callback, with optional per-binding options. Chords accept
  * `requireReset`; sequences accept `timeout`.
@@ -26,8 +25,12 @@ export type HotkeyDefinition = {
 };
 /** Options shared by every definition. Each option applies only to the kinds that support it. */
 export type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOptions;
-/** Reconciles adapter registrations while retaining handles for option updates. */
-export declare function createHotkeyBindings(): {
+/**
+ * Reconciles adapter registrations while retaining handles for option updates.
+ * Adapters for frameworks that delegate key events, such as React, pass
+ * `{ afterDelegatedHandlers: true }`.
+ */
+export declare function createHotkeyBindings(adapterOptions?: Pick<HotkeyOptions, 'afterDelegatedHandlers'>): {
   /**
    * Registers new definitions, updates existing ones in place, and removes
    * stale ones. Definitions with no hotkey (undefined, null, empty string, or
@@ -37,7 +40,7 @@ export declare function createHotkeyBindings(): {
   destroy(): void;
 };
 /** Options with a framework-specific target, such as a ref. */
-export type WithTarget<TOptions, TTarget> = Omit<TOptions, 'target' | 'appHotkeyId'> & {
+export type WithTarget<TOptions, TTarget> = Omit<TOptions, 'target' | 'appHotkeyId' | 'afterDelegatedHandlers'> & {
   /** The element to listen on. Defaults to document. */
   target?: TTarget;
 };
@@ -180,5 +183,4 @@ export declare function getHotkeysProviderScopeKey(options: {
  * Returns a function that releases the activation.
  */
 export declare function activateHotkeysProviderScope(key: string): () => void;
-//#endregion
 export { type Store, createAppHotkeysStore, createStore, definedOptions, withDefaults };

package/dist/adapter.js

@@ -1,11 +1,15 @@
-import { warnServerPlatform } from "./_server.js";
 import { chordHasKey, defaultHotkeyOptions, definedOptions, withDefaults } from "./_registration.js";
+import { warnServerPlatform } from "./_server.js";
 import { createStore } from "./_store.js";
 import { createAppHotkeysStore, detectPlatform, getAppHotkeyRegistrationOptions, getHotkeyManager, isAppHotkey, isHotkeySequence, normalizeHotkey, parseHotkey, resolveAppHotkey } from "@tanstack/hotkeys";
 
-//#region src/adapter.ts
-/** Reconciles adapter registrations while retaining handles for option updates. */
-function createHotkeyBindings() {
+// src/adapter.ts
+/**
+* Reconciles adapter registrations while retaining handles for option updates.
+* Adapters for frameworks that delegate key events, such as React, pass
+* `{ afterDelegatedHandlers: true }`.
+*/
+function createHotkeyBindings(adapterOptions = {}) {
 	const registrations = /* @__PURE__ */ new Map();
 	return {
 		/**
@@ -20,6 +24,7 @@ function createHotkeyBindings() {
 				const options = {
 					...defaultHotkeyOptions,
 					...merged,
+					...adapterOptions,
 					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
 					platform: merged.platform ?? detectPlatform()
 				};
@@ -173,5 +178,4 @@ function activateHotkeysProviderScope(key) {
 	});
 }
 
-//#endregion
 export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, getServerPlatformSnapshot, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };

package/dist/app-hotkeys.d.ts

@@ -1,7 +1,6 @@
 import { Store } from "./_store.js";
-import { Hotkey, HotkeyChord, HotkeyMeta, HotkeySequence } from "./hotkey.types.js";
 import { HotkeyChordOptions, HotkeyRegistrationView, HotkeySequenceOptions } from "./hotkey-manager.js";
-//#region src/app-hotkeys.d.ts
+import { Hotkey, HotkeyChord, HotkeyMeta, HotkeySequence } from "./hotkey.types.js";
 type Platform = 'mac' | 'windows' | 'linux';
 type DeclaredOptionKeys = 'capture' | 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
 /** Declared options for an app hotkey whose default is a chord. */
@@ -136,8 +135,8 @@ export interface AppHotkeysState<T extends AppHotkeys = AppHotkeys> {
 /** Options for `AppHotkeysStore`. */
 export interface AppHotkeysStoreOptions<T extends AppHotkeys = AppHotkeys> {
   /**
-   * The user's saved custom hotkeys. Invalid entries are ignored with a
-   * warning. Passing a different value to `setOptions` later, such as data
+   * The user's saved custom hotkeys. Unknown ids and invalid entries are
+   * ignored. 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.
@@ -254,4 +253,4 @@ export declare function provideAppHotkeys<T extends AppHotkeys>(appHotkeys: T, o
   store: AppHotkeysStore<T>;
   dispose: () => void;
 };
-//#endregion
+export {};

package/dist/app-hotkeys.js

@@ -1,13 +1,13 @@
-import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, simplifyHotkey } from "./parse.js";
-import { validateHotkey } from "./validate.js";
+import { setAppHotkeysStoreFactory } from "./_app-hotkeys-factory.js";
 import { GLOBAL_SCOPE } from "./_registration.js";
-import { areHotkeysEqual } from "./match.js";
 import { createStore } from "./_store.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
-import { setAppHotkeysStoreFactory } from "./_app-hotkeys-factory.js";
+import { areHotkeysEqual } from "./match.js";
+import { isHotkeySequence, simplifyHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
+import { validateHotkey } from "./validate.js";
 
-//#region src/app-hotkeys.ts
+// src/app-hotkeys.ts
 /**
 * Declares every app hotkey up front, without registering any, so cheat
 * sheets and settings screens can list hotkeys whose components have not
@@ -69,22 +69,15 @@ function applyCustomHotkeys(appHotkeys, customHotkeys) {
 	}
 	return result;
 }
-/** Keeps only valid custom hotkeys for known ids, warning about the rest. */
+/** Keeps only valid custom hotkeys for known ids and silently drops the rest. */
 function sanitizeCustomHotkeys(appHotkeys, saved) {
 	const result = {};
 	if (typeof saved !== "object" || saved === null) return result;
 	for (const [id, value] of Object.entries(saved)) {
 		if (value === void 0) continue;
-		if (!Object.hasOwn(appHotkeys, id)) {
-			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
-			continue;
-		}
+		if (!Object.hasOwn(appHotkeys, id)) continue;
 		const hotkey = parseCustomHotkey(value);
-		if (hotkey === void 0) {
-			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
-			continue;
-		}
-		result[id] = hotkey;
+		if (hotkey !== void 0) result[id] = hotkey;
 	}
 	return result;
 }
@@ -232,10 +225,7 @@ var AppHotkeysStore = class {
 	*/
 	setCustomHotkey(id, hotkey) {
 		const appHotkey = this.get(id);
-		if (!appHotkey) {
-			if (process.env.NODE_ENV !== "production") console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
-			return [];
-		}
+		if (!appHotkey) return [];
 		const next = hotkey === null ? null : simplifyHotkey(hotkey);
 		if (next !== null) {
 			const conflicts = this.findConflicts(id, next);
@@ -346,5 +336,4 @@ function provideAppHotkeys(appHotkeys, options = {}) {
 	};
 }
 
-//#endregion
 export { AppHotkeysStore, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey };

package/dist/conflicts.d.ts

@@ -1,6 +1,5 @@
-import { RegisterableHotkey } from "./hotkey.types.js";
 import { HotkeyRegistrationView } from "./hotkey-manager.js";
-//#region src/conflicts.d.ts
+import { RegisterableHotkey } from "./hotkey.types.js";
 /** A live registration that overlaps a candidate hotkey. */
 export interface HotkeyConflict {
   registration: HotkeyRegistrationView;
@@ -28,5 +27,4 @@ export interface HotkeyConflictOptions {
  * With source events, also checks observed logical/physical overlap. Does not
  * discover unmounted handlers, external listeners, or other keyboard layouts.
  */
-export declare function findHotkeyConflicts(candidate: RegisterableHotkey, options?: HotkeyConflictOptions): Array<HotkeyConflict>;
-//#endregion
+export declare function findHotkeyConflicts(candidate: RegisterableHotkey, options?: HotkeyConflictOptions): Array<HotkeyConflict>;

package/dist/conflicts.js

@@ -1,12 +1,12 @@
-import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, parseHotkey } from "./parse.js";
-import { parsedChordsEqual } from "./_match.js";
-import { matchesKeyboardEvent } from "./match.js";
 import { getTargetDocument } from "./_event-target.js";
 import { managerRef } from "./_manager-ref.js";
+import { parsedChordsEqual } from "./_match.js";
 import { toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { matchesKeyboardEvent } from "./match.js";
+import { isHotkeySequence, parseHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/conflicts.ts
+// src/conflicts.ts
 /** Whether two targets share a document and one contains the other (or is its window). */
 function targetsOverlap(a, b) {
 	if (a === b) return true;
@@ -42,5 +42,4 @@ function findHotkeyConflicts(candidate, options = {}) {
 	return conflicts;
 }
 
-//#endregion
 export { findHotkeyConflicts };