@tanstack/hotkeys 0.23.0 → 0.25.0

package/dist/constants.d.ts

@@ -1,5 +1,4 @@
 import { CanonicalModifier, EditingKey, FunctionKey, LetterKey, NavigationKey, NumberKey, PunctuationKey } from "./key.types.js";
-//#region src/constants.d.ts
 /**
  * Canonical order for modifiers in normalized hotkey strings.
  *
@@ -118,7 +117,7 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
  * @see {@link EDITING_KEYS}
  * @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>;
+export declare const ALL_KEYS: Set<LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey | "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">;
 /** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 export declare function isSingleLetterKey(key: string): boolean;
 /**
@@ -136,5 +135,4 @@ export declare function isSingleLetterKey(key: string): boolean;
  * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
  * ```
  */
-export declare function normalizeKeyName(key: string): string;
-//#endregion
+export declare function normalizeKeyName(key: string): string;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import { EDITING_KEY_NAMES, LOGICAL_ONLY_NAMED_KEYS, NAVIGATION_KEY_NAMES, SHARED_NAMED_KEYS } from "./_named-keys.js";
 
-//#region src/constants.ts
+// src/constants.ts
 /**
 * Canonical order for modifiers in normalized hotkey strings.
 *
@@ -193,5 +193,4 @@ function normalizeKeyName(key) {
 	return key === " " ? "Space" : key;
 }
 
-//#endregion
 export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName };

package/dist/display-labels.d.ts

@@ -1,5 +1,4 @@
 import { CanonicalModifier } from "./key.types.js";
-//#region src/display-labels.d.ts
 /**
  * Modifier key symbols for macOS display.
  *
@@ -86,5 +85,4 @@ export declare const KEY_DISPLAY_SYMBOLS: {
   readonly Delete: "⌦";
   readonly Tab: "⇥";
   readonly Space: "␣";
-};
-//#endregion
+};

package/dist/display-labels.js

@@ -1,4 +1,4 @@
-//#region src/display-labels.ts
+// src/display-labels.ts
 /**
 * Modifier key symbols for macOS display.
 *
@@ -108,5 +108,4 @@ const KEY_DISPLAY_SYMBOLS = {
 	Space: "␣"
 };
 
-//#endregion
 export { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS };

package/dist/format.d.ts

@@ -1,6 +1,5 @@
-import { CanonicalModifier } from "./key.types.js";
 import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
-//#region src/format.d.ts
+import { CanonicalModifier } from "./key.types.js";
 /**
  * Converts a parsed hotkey back to a string, with each platform modifier
  * spelled out, such as `Control+Shift+S`. A parsed chord returns a string, and
@@ -105,5 +104,4 @@ export interface FormatDisplayOptions {
   separatorToken?: string | null;
   /** Separator between sequence steps. Default: a space. */
   sequenceSeparator?: string;
-}
-//#endregion
+}

package/dist/format.js

@@ -1,11 +1,11 @@
+import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { warnServerPlatform } from "./_server.js";
 import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
-import { warnServerPlatform } from "./_server.js";
-import { detectPlatform } from "./platform.js";
-import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 import { normalizeHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/format.ts
+// src/format.ts
 function formatHotkey(parsed) {
 	return Array.isArray(parsed) ? parsed.map((step) => formatParsedChord(step)) : formatParsedChord(parsed);
 }
@@ -72,5 +72,4 @@ function formatKey(segment, platform, modifierSymbols, keySymbols, options) {
 	return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
 }
 
-//#endregion
 export { formatForDisplay, formatHotkey };

package/dist/hint.d.ts

@@ -1,5 +1,4 @@
 import { RegisterableHotkey } from "./hotkey.types.js";
-//#region src/hint.d.ts
 export interface HeldModifierOptions {
   /** Resolve Mod for this platform. Defaults to platform detection. */
   platform?: 'mac' | 'windows' | 'linux';
@@ -18,5 +17,4 @@ export interface HeldModifierOptions {
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
  */
-export declare function matchesHeldModifiers(hotkey: RegisterableHotkey | null | undefined, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;
-//#endregion
+export declare function matchesHeldModifiers(hotkey: RegisterableHotkey | null | undefined, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;

package/dist/hint.js

@@ -1,7 +1,7 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 import { isHotkeySequence, parseHotkey } from "./parse.js";
 
-//#region src/hint.ts
+// src/hint.ts
 /**
 * Returns whether held modifiers should reveal a shortcut hint.
 * By default, any nonempty subset of the binding's modifiers qualifies; an
@@ -24,5 +24,4 @@ function matchesHeldModifiers(hotkey, heldKeys, options = {}) {
 	return held.length > 0 && held.every((key) => modifiers.includes(key)) && (!options.exact || held.length === modifiers.length);
 }
 
-//#endregion
 export { matchesHeldModifiers };

package/dist/hotkey-manager.d.ts

@@ -1,7 +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";
-//#region src/hotkey-manager.d.ts
+import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 /** An element, document, or window that hotkeys can listen on. */
 export type Target = HTMLElement | Document | Window;
 /**
@@ -24,8 +23,19 @@ export interface HotkeyOptions {
    * existing handle via `setOptions` rather than unregistering. Defaults to `true`.
    */
   enabled?: boolean;
-  /** The event type to listen for. Defaults to 'keydown' */
+  /**
+   * The event type to listen for. Defaults to 'keydown'. A 'keyup' chord fires
+   * when its key or one of its modifiers is released, whichever comes first,
+   * unless another key was pressed in between. `preventDefault` applies to
+   * its keydown too.
+   */
   eventType?: 'keydown' | 'keyup';
+  /**
+   * Skip a key press that a listener outside TanStack Hotkeys already handled
+   * by calling `preventDefault()`, such as a component library's dialog that
+   * closes on Escape. Defaults to `false`.
+   */
+  ignoreDefaultPrevented?: boolean;
   /**
    * Skip keys that a focused control inside the target uses itself: typing in
    * text inputs, textarea, select, and contenteditable; Enter/Space on buttons
@@ -70,6 +80,16 @@ export interface HotkeyOptions {
   scope?: string;
   /** Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`. */
   appHotkeyId?: string;
+  /**
+   * Run after key handlers that a framework calls from one listener on its
+   * root or the document, such as React's `onKeyDown`, so handlers inside the
+   * target run first and can stop the hotkey. An element target then listens
+   * on its document, or on its closed shadow root, instead of the element. A
+   * stop by an earlier listener there skips the hotkey. Applies only to the
+   * bubble phase.
+   * Adapters for frameworks that delegate key events set this.
+   */
+  afterDelegatedHandlers?: boolean;
 }
 /** Options for a single chord such as `'Mod+S'`. */
 export interface HotkeyChordOptions extends HotkeyOptions {
@@ -400,5 +420,4 @@ export declare class HotkeyManager {
  * Convenience function for accessing the manager.
  */
 export declare function getHotkeyManager(): HotkeyManager;
-//#endregion
 export type { ConflictBehavior };

package/dist/hotkey-manager.js

@@ -1,18 +1,18 @@
-import { normalizeKeyName } from "./constants.js";
-import { detectPlatform } from "./platform.js";
+import { closesNativeLayer, getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { isKeyNameShape, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
-import { formatHotkey } from "./format.js";
+import { managerRef } from "./_manager-ref.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
+import { isRecordingEvent } from "./_recording-guard.js";
 import { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { createStore } from "./_store.js";
 import { TargetListeners } from "./_target-listeners.js";
-import { managerRef } from "./_manager-ref.js";
-import { isRecordingEvent } from "./_recording-guard.js";
+import { normalizeKeyName } from "./constants.js";
+import { formatHotkey } from "./format.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
+import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/hotkey-manager.ts
+// src/hotkey-manager.ts
 /** Whether a registration can fire now. Without a manager, scopes don't apply. */
 function getRegistrationStatus(options, manager) {
 	if (options.enabled === false) return "disabled";
@@ -91,6 +91,23 @@ function optionsForKind(kind, options) {
 	const { requireReset: _requireReset, ...rest } = options;
 	return rest;
 }
+/**
+* Where a registration listens: its target, or for an element target that
+* runs after delegated handlers in the bubble phase, the node where handlers
+* delegated around it have already run. That is its document, unless the
+* element is in a closed shadow root, which hides it from listeners outside,
+* or in a tree outside any document, which events never leave.
+*/
+function listenerTarget({ target, options }) {
+	if (!options.afterDelegatedHandlers || options.capture || isDocumentLevel(target)) return target;
+	let root = target.getRootNode();
+	while ("host" in root && root.mode === "open") root = root.host.getRootNode();
+	return root;
+}
+/** Whether a registration's shared listener moves after listeners added before it joins. */
+function movesAfterDelegatedHandlers(options) {
+	return !!options.afterDelegatedHandlers && !options.capture;
+}
 /** Steps with Mod already resolved for the registration's platform. */
 function resolvedSteps(registration) {
 	return registration.kind === "chord" ? [registration.parsedChord] : registration.parsedSequence;
@@ -173,8 +190,20 @@ var HotkeyManager = class HotkeyManager {
 	/** Scopes that can fire while a scope is exclusive, or `null` when none is. */
 	#liveScopes = null;
 	#listeners = new TargetListeners((...args) => this.#processTargetEvent(...args));
+	/** Where each registration listens, kept so cleanup finds a target that moved documents. */
+	#listenerTargets = /* @__PURE__ */ new Map();
 	/** Events that continue a sequence in progress, decided before any listener runs. */
 	#sequenceOwned = /* @__PURE__ */ new WeakMap();
+	/**
+	* Keyup chords whose keydown matched. Releasing one of the chord's
+	* modifiers fires them, because the key's own keyup may come after the
+	* modifier's or, on macOS while Command is held, not at all. `null` marks a
+	* press that another key cancelled or that `ignoreDefaultPrevented`
+	* skipped, so its release doesn't fire.
+	*/
+	#pendingReleases = /* @__PURE__ */ new Map();
+	/** Events this manager prevented, so its own prevention never skips a hotkey. */
+	#prevented = /* @__PURE__ */ new WeakSet();
 	/** Physical keys whose keydown a sequence owned, so their repeats and keyup are owned too. */
 	#sequenceOwnedKeys = /* @__PURE__ */ new Set();
 	/** Timers that clear a sequence's progress once its timeout passes. */
@@ -219,7 +248,7 @@ var HotkeyManager = class HotkeyManager {
 		if (scope === "global") return () => {};
 		const { exclusive } = options;
 		const allow = exclusive ? exclusive === true ? [] : exclusive.allow : null;
-		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.`);
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`[hotkeys] Exclusive scope '${scope}' is already active`);
 		const activation = {
 			scope,
 			parent: options.parent ?? "global",
@@ -250,7 +279,7 @@ var HotkeyManager = class HotkeyManager {
 		const parents = /* @__PURE__ */ new Map();
 		const latest = /* @__PURE__ */ new Map();
 		for (const activation of this.#scopeActivations) {
-			parents.set(activation.scope, activation.parent);
+			if (activation.parent !== activation.scope) parents.set(activation.scope, activation.parent);
 			latest.set(activation.scope, Math.max(latest.get(activation.scope) ?? 0, activation.order));
 		}
 		const depth = (scope) => {
@@ -311,7 +340,7 @@ var HotkeyManager = class HotkeyManager {
 	#handledByLiveHotkey(event, eventType) {
 		const path = event.composedPath();
 		for (const registration of this.registrations.state.values()) {
-			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target)) continue;
+			if (!this.#isLive(registration) || registration.options.eventType !== eventType || this.#skips(registration, event) || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target)) continue;
 			if ((registration.kind === "chord" ? [registration.parsedChord] : [registration.parsedSequence[registration.currentIndex], registration.parsedSequence[0]]).some((step) => matchKeyboardEvent(event, step, registration.options.platform).matched)) return true;
 		}
 		return false;
@@ -362,12 +391,14 @@ var HotkeyManager = class HotkeyManager {
 		}
 		const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
 		if (!steps.every(chordHasKey)) return inactiveHandle(callback);
-		if (process.env.NODE_ENV !== "production") {
-			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.`);
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			for (const { key } of steps) if (key !== void 0 && !isKeyNameShape(key)) console.warn(`[hotkeys] Unknown key '${key}' in '${formatForMessage(registration.hotkey)}' (names are case-sensitive)`);
 		}
 		const conflicting = this.#findConflictingRegistration(registration);
 		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
-		this.#listeners.add(target, !!registration.options.capture, id);
+		const listenOn = listenerTarget(registration);
+		this.#listeners.add(listenOn, !!registration.options.capture, id, movesAfterDelegatedHandlers(registration.options));
+		this.#listenerTargets.set(id, listenOn);
 		this.registrations.setState((prev) => new Map(prev).set(id, registration));
 		const manager = this;
 		return {
@@ -399,10 +430,16 @@ var HotkeyManager = class HotkeyManager {
 					else delete options[key];
 					if (optionsEqual(reg.options, options)) return prev;
 					const capture = !!reg.options.capture;
-					if (capture !== !!options.capture) {
-						manager.#listeners.remove(reg.target, capture, id);
-						manager.#listeners.add(reg.target, !!options.capture, id);
-					}
+					const from = manager.#listenerTargets.get(id) ?? reg.target;
+					const to = listenerTarget({
+						target: reg.target,
+						options
+					});
+					if (capture !== !!options.capture || from !== to) {
+						manager.#listeners.remove(from, capture, id);
+						manager.#listeners.add(to, !!options.capture, id, movesAfterDelegatedHandlers(options));
+						manager.#listenerTargets.set(id, to);
+					} else if (movesAfterDelegatedHandlers(options) && !movesAfterDelegatedHandlers(reg.options)) manager.#listeners.add(to, capture, id, true);
 					return new Map(prev).set(id, {
 						...reg,
 						options
@@ -420,13 +457,14 @@ var HotkeyManager = class HotkeyManager {
 	#unregister(id) {
 		const registration = this.registrations.state.get(id);
 		if (!registration) return;
-		const target = registration.target;
 		this.registrations.setState((prev) => {
 			const next = new Map(prev);
 			next.delete(id);
 			return next;
 		});
-		this.#listeners.remove(target, !!registration.options.capture, id);
+		this.#listeners.remove(this.#listenerTargets.get(id) ?? registration.target, !!registration.options.capture, id);
+		this.#listenerTargets.delete(id);
+		this.#pendingReleases.delete(id);
 		this.#clearSequenceReset(id);
 	}
 	/**
@@ -478,6 +516,30 @@ var HotkeyManager = class HotkeyManager {
 	*/
 	#processTargetEvent(event, target, eventType, capture, ids, first) {
 		if (first) this.#sequenceOwned.set(event, this.#isOwnedBySequence(event, eventType));
+		if (capture) {
+			this.#processRound(event, target, eventType, capture, ids);
+			return;
+		}
+		const rounds = /* @__PURE__ */ new Map();
+		for (const id of ids) {
+			const registration = this.registrations.state.get(id);
+			if (!registration) continue;
+			const round = rounds.get(registration.target) ?? /* @__PURE__ */ new Set();
+			rounds.set(registration.target, round.add(id));
+		}
+		const path = rounds.size > 1 || !rounds.has(target) ? event.composedPath() : [];
+		const order = [...rounds.keys()].filter((other) => other === target || path.includes(other)).sort((a, b) => a === target ? 1 : b === target ? -1 : path.indexOf(a) - path.indexOf(b));
+		const arrivedStopped = event.cancelBubble;
+		for (const roundTarget of order) {
+			const round = /* @__PURE__ */ new Set();
+			for (const id of rounds.get(roundTarget)) {
+				const delegated = this.registrations.state.get(id)?.options.afterDelegatedHandlers;
+				if (!event.cancelBubble || !delegated && arrivedStopped) round.add(id);
+			}
+			this.#processRound(event, roundTarget, eventType, capture, round);
+		}
+	}
+	#processRound(event, target, eventType, capture, ids) {
 		this.#processChords(event, target, eventType, capture, this.#registrationsIn(ids, capture, "chord"));
 		this.#processSequences(event, target, eventType, capture, this.#registrationsIn(ids, capture, "sequence"));
 	}
@@ -488,15 +550,47 @@ var HotkeyManager = class HotkeyManager {
 				registration.activeMatch = void 0;
 			}
 		}
+		if (eventType === "keydown" && !event.repeat) {
+			for (const { id } of registrations) if (this.#pendingReleases.get(id)) this.#pendingReleases.set(id, null);
+		}
 		if (isRecordingEvent(event) || this.#sequenceOwned.get(event)) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		let reserved = false;
+		const eventKey = normalizeKeyName(event.key);
 		for (const registration of registrations) {
 			const live = this.#isLive(registration);
-			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) continue;
-			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
-			if (!result.matched) continue;
+			const { eventType: firesOn, preventDefault } = registration.options;
+			const press = eventType === "keydown" && firesOn === "keyup";
+			const skipped = this.#skips(registration, event);
+			const { parsedChord, id } = registration;
+			const { platform } = registration.options;
+			let result;
+			let released;
+			if (eventType === "keyup" && firesOn === "keyup" && this.#pendingReleases.has(id)) {
+				result = matchKeyboardEvent(event, parsedChord, platform);
+				if (result.matched || parsedChord.modifiers.includes(eventKey) && !event.getModifierState(eventKey)) {
+					released = this.#pendingReleases.get(id);
+					this.#pendingReleases.delete(id);
+				}
+			}
+			if (!live && preventDefault !== "always" || firesOn !== eventType && !press || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) continue;
+			result ??= matchKeyboardEvent(event, parsedChord, platform);
+			if (press) {
+				if (result.matched) {
+					if (skipped) this.#pendingReleases.set(id, null);
+					else {
+						if (preventDefault) this.#prevent(event);
+						if (live) this.#pendingReleases.set(id, result);
+					}
+				}
+				continue;
+			}
+			if (released !== void 0) {
+				if (!released || skipped) continue;
+				if (!result.matched) result = released;
+			}
+			if (skipped || !result.matched) continue;
 			if (!live) {
 				reserved = true;
 				continue;
@@ -504,7 +598,7 @@ var HotkeyManager = class HotkeyManager {
 			matches.set(registration.id, result);
 			bestScore = Math.max(bestScore, result.score);
 		}
-		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) event.preventDefault();
+		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) this.#prevent(event);
 		let bestRank = -1;
 		for (const registration of registrations) if (matches.get(registration.id)?.score === bestScore) bestRank = Math.max(bestRank, this.#scopeRank(registration.options.scope));
 		for (const snapshot of registrations) {
@@ -548,7 +642,7 @@ var HotkeyManager = class HotkeyManager {
 		const path = event.composedPath();
 		const now = Date.now();
 		for (const registration of this.registrations.state.values()) {
-			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
+			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || this.#skips(registration, event) || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
 			const target = registration.target;
 			if (path.includes(isDocumentLevel(target) ? getTargetDocument(target) : target) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
 		}
@@ -573,7 +667,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target) || registration.options.eventType !== eventType) continue;
+			if (!this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target) || registration.options.eventType !== eventType || this.#skips(registration, event)) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -605,7 +699,7 @@ var HotkeyManager = class HotkeyManager {
 					this.#consume(registration, event);
 					registration.currentIndex = 0;
 					completed.push(registration);
-				} else if (registration.options.preventDefault) event.preventDefault();
+				} else if (registration.options.preventDefault) this.#prevent(event);
 			} else if (registration.currentIndex > 0) {
 				registration.currentIndex = 0;
 				changed = true;
@@ -624,9 +718,21 @@ var HotkeyManager = class HotkeyManager {
 			if (registration) this.#fire(registration, event);
 		}
 	}
+	#prevent(event) {
+		if (!event.defaultPrevented) this.#prevented.add(event);
+		event.preventDefault();
+	}
+	/**
+	* Whether the registration skips the event: Escape belongs to an open modal
+	* dialog or popover outside its target, or another listener prevented the
+	* event and the registration skips such events.
+	*/
+	#skips(registration, event) {
+		return closesNativeLayer(event, registration.target) || !!registration.options.ignoreDefaultPrevented && event.defaultPrevented && !this.#prevented.has(event);
+	}
 	/** Applies a matched registration's preventDefault and stopPropagation options. */
 	#consume(registration, event) {
-		if (registration.options.preventDefault) event.preventDefault();
+		if (registration.options.preventDefault) this.#prevent(event);
 		if (registration.options.stopPropagation) event.stopPropagation();
 	}
 	/** Counts a trigger, notifies subscribers (such as devtools), and runs the callback. */
@@ -634,7 +740,9 @@ var HotkeyManager = class HotkeyManager {
 		registration.triggerCount++;
 		if (registration.kind === "sequence") registration.hasFired = true;
 		this.#notify();
+		const prevented = event.defaultPrevented;
 		registration.callback(event, context);
+		if (!prevented && event.defaultPrevented) this.#prevented.add(event);
 	}
 	#callbackContext(registration) {
 		return registration.kind === "chord" ? {
@@ -719,6 +827,7 @@ var HotkeyManager = class HotkeyManager {
 		for (const timer of this.#sequenceResetTimers.values()) clearTimeout(timer);
 		this.#sequenceResetTimers.clear();
 		this.#listeners.destroy();
+		this.#listenerTargets.clear();
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
 		this.appHotkeys.setState(() => null);
 	}
@@ -731,5 +840,4 @@ function getHotkeyManager() {
 	return HotkeyManager.getInstance();
 }
 
-//#endregion
 export { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView };

package/dist/hotkey-recorder.d.ts

@@ -1,12 +1,24 @@
 import { Store } from "./_store.js";
-import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } from "./hotkey.types.js";
 import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
-//#region src/hotkey-recorder.d.ts
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } from "./hotkey.types.js";
 /** Event property used to record a binding. Physical codes are the default. */
 export type RecorderKeyMode = 'code' | 'key';
+/**
+ * Why the recorder rejected a key press or a recording:
+ *
+ * - `'alt-graph'`: AltGr typed a character, which physical recording can't
+ *   record. Record by key to accept characters.
+ * - `'missing-code'`: the event has no usable physical key code.
+ * - `'whitespace'`: the key is a whitespace character, which a hotkey can't
+ *   hold.
+ * - `'validation'`: your `validate` callback rejected the recording.
+ * - `'conflict'`: the recording conflicts with registered hotkeys.
+ */
+export type RecorderRejectionReason = 'alt-graph' | 'missing-code' | 'whitespace' | 'validation' | 'conflict';
 export interface RecorderRejection {
-  reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation';
-  message: string;
+  reason: RecorderRejectionReason;
+  /** The message your `validate` callback returned, when it returned one. */
+  message?: string;
   /** The rejected chord or sequence, when one was recorded. */
   hotkey?: Hotkey;
   conflicts?: Array<HotkeyConflict>;
@@ -74,7 +86,7 @@ interface HotkeyRecorderBaseOptions extends RecorderOptions {
 export interface HotkeyChordRecorderOptions extends HotkeyRecorderBaseOptions {
   /** Maximum number of chords to record. Default: 1 */
   maxSteps?: 1;
-  /** Return true to accept, or false/a message to reject while staying in recording mode. */
+  /** Return true to accept, or false or a message to reject while staying in recording mode. The message is passed to `onReject`. */
   validate?: (hotkey: HotkeyChord, context: HotkeyChordRecorderValidationContext) => boolean | string;
   /** Callback when a chord is successfully recorded */
   onRecord: (hotkey: HotkeyChord) => void;
@@ -86,7 +98,7 @@ export interface HotkeyChordRecorderOptions extends HotkeyRecorderBaseOptions {
 export interface HotkeySequenceRecorderOptions extends HotkeyRecorderBaseOptions {
   /** Maximum number of chords to record. Reaching it commits automatically. Use `Infinity` for no limit. */
   maxSteps: number;
-  /** Return true to accept, or false/a message to reject while staying in recording mode. */
+  /** Return true to accept, or false or a message to reject while staying in recording mode. The message is passed to `onReject`. */
   validate?: (hotkey: Hotkey, context: HotkeyRecorderValidationContext) => boolean | string;
   /** Callback when a hotkey is successfully recorded */
   onRecord: (hotkey: Hotkey) => void;
@@ -178,4 +190,4 @@ export declare class HotkeyRecorder {
    */
   destroy(): void;
 }
-//#endregion
+export {};

package/dist/hotkey-recorder.js

@@ -1,13 +1,13 @@
-import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent, splitChordParts } from "./_keyboard-event.js";
-import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { isTypingEvent } from "./_event-target.js";
-import { createStore } from "./_store.js";
+import { normalizeKeyboardEvent, splitChordParts } from "./_keyboard-event.js";
+import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
 import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
+import { createStore } from "./_store.js";
 import { findHotkeyConflicts } from "./conflicts.js";
-import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
+import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/hotkey-recorder.ts
+// src/hotkey-recorder.ts
 const initialState = {
 	isRecording: false,
 	steps: [],
@@ -157,8 +157,7 @@ var HotkeyRecorder = class {
 			if (chord === null) return;
 			if (splitChordParts(chord).some((part) => !part.trim())) {
 				options.onReject?.({
-					reason: "invalid",
-					message: "Whitespace keys cannot be recorded",
+					reason: "whitespace",
 					hotkey: chord
 				});
 				return;
@@ -211,7 +210,7 @@ var HotkeyRecorder = class {
 		if (accepted !== void 0 && accepted !== true) {
 			rejectAndKeepRecording({
 				reason: "validation",
-				message: typeof accepted === "string" ? accepted : `This ${single ? "shortcut" : "sequence"} is not allowed.`,
+				...typeof accepted === "string" && { message: accepted },
 				hotkey
 			});
 			return;
@@ -225,7 +224,6 @@ var HotkeyRecorder = class {
 			if (conflicts.length) {
 				rejectAndKeepRecording({
 					reason: "conflict",
-					message: `This ${single ? "shortcut" : "sequence"} conflicts with a registered hotkey.`,
 					hotkey,
 					conflicts
 				});
@@ -286,5 +284,4 @@ var HotkeyRecorder = class {
 	}
 };
 
-//#endregion
 export { HotkeyRecorder };

package/dist/hotkey.types.d.ts

@@ -1,5 +1,4 @@
 import { CanonicalModifier, Key, LogicalKey } from "./key.types.js";
-//#region src/hotkey.types.d.ts
 /**
  * Single modifier + key combinations.
  * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
@@ -269,5 +268,4 @@ export interface HotkeyMeta {
  * - `'replace'` - Unregister the existing registration and register the new one
  * - `'allow'` - Allow multiple registrations without warning
  */
-export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
-//#endregion
+export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';