@tanstack/hotkeys 0.17.0 → 0.19.0

package/dist/_event-target.js

@@ -1,67 +1,169 @@
 import { normalizeKeyName } from "./constants.js";
 
 //#region src/_event-target.ts
-function isNode(target) {
-	return typeof target?.nodeType === "number";
+function isElement(node) {
+	return node?.nodeType === 1;
 }
-function isElement(target) {
-	return isNode(target) && target.nodeType === 1;
-}
-function isWindow(target) {
-	return "document" in target;
+/** Whether a target is a document or window, which receive every key press in their document. */
+function isDocumentLevel(target) {
+	return "document" in target || target.nodeType === 9;
 }
 /** Returns the document a listener target belongs to, in any frame. */
 function getTargetDocument(target) {
-	if (isWindow(target)) return target.document;
-	if (target.nodeType === 9) return target;
-	return target.ownerDocument;
+	return "document" in target ? target.document : target.ownerDocument ?? target;
+}
+/** The focused element, looking inside open shadow roots. */
+function getDeepActiveElement(doc) {
+	let active = doc.activeElement;
+	while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+	return active;
+}
+/** The next node a key event bubbles to: a slot, a shadow host, or the parent. */
+function composedParent(node) {
+	return node.assignedSlot ?? node.parentNode ?? (node.host || null);
 }
 /**
-* Checks if an element is an input-like element that should be ignored for hotkeys.
-*
-* This includes:
-* - HTMLInputElement (all input types except button, submit, reset)
-* - HTMLTextAreaElement
-* - HTMLSelectElement
-* - Elements with contentEditable enabled
+* Whether key presses reach a listener on `target` right now. Document and
+* window listeners receive every key press in their document. An element
+* receives them only while focus is inside it, including inside a shadow
+* root it contains or on content slotted into it.
+*/
+function targetHasFocus(target) {
+	if (isDocumentLevel(target)) return true;
+	for (let node = getDeepActiveElement(target.ownerDocument); node; node = composedParent(node)) if (node === target) return true;
+	return false;
+}
+const VERTICAL = ["ArrowUp", "ArrowDown"];
+const HORIZONTAL = ["ArrowLeft", "ArrowRight"];
+const ENTER = ["Enter"];
+const SPACE = ["Space"];
+const ACTIVATION = ["Enter", "Space"];
+const TYPEAHEAD = "typeahead";
+const MENU = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"Enter",
+	"Space",
+	TYPEAHEAD
+];
+const COMBOBOX = [
+	"ArrowUp",
+	"ArrowDown",
+	"Home",
+	"End",
+	"Enter",
+	"Space",
+	TYPEAHEAD
+];
+const GRID = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown",
+	"Enter",
+	"Space"
+];
+const RADIOS = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Space"
+];
+const NAVIGATION = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown"
+];
+const SPIN = [
+	"ArrowUp",
+	"ArrowDown",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown"
+];
+const CARET = [
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End"
+];
+/**
+* Input types that aren't text fields, with the keys each one keeps. Browsers
+* report unknown types as `'text'`.
+*/
+const INPUT_KEYS = {
+	button: ACTIVATION,
+	submit: ACTIVATION,
+	reset: ACTIVATION,
+	image: ACTIVATION,
+	color: ACTIVATION,
+	file: ACTIVATION,
+	checkbox: SPACE,
+	radio: RADIOS,
+	range: NAVIGATION
+};
+function getRole(element) {
+	return element.getAttribute("role")?.trim().split(/\s+/)[0];
+}
+/**
+* Checks if an element is a text field that hotkeys should not type over:
+* - text-entry `<input>` types (text, number, date, and similar) that aren't read-only
+* - `<textarea>` elements that aren't read-only, and `<select>` elements
+* - elements with `role="textbox"` or `role="searchbox"`
+* - contenteditable elements
 *
-* Button-type inputs (button, submit, reset) are excluded so hotkeys like
-* Mod+S and Escape fire when the user has tabbed to a form button.
+* Checkbox, radio, range, color, file, and button-type inputs are not text
+* fields. Hotkeys skip only the keys those controls use themselves.
 */
 function isInputElement(element) {
 	if (!isElement(element)) return false;
-	if (element.localName === "input") {
-		const type = element.type.toLowerCase();
-		return type !== "button" && type !== "submit" && type !== "reset";
+	switch (element.localName) {
+		case "input": {
+			const input = element;
+			return !INPUT_KEYS[input.type] && !input.readOnly;
+		}
+		case "textarea": return !element.readOnly;
+		case "select": return true;
 	}
-	if (element.localName === "textarea" || element.localName === "select") return true;
-	return element.isContentEditable === true;
+	const role = getRole(element);
+	return role === "textbox" || role === "searchbox" || element.isContentEditable;
 }
 /**
-* Returns the focused element for the document associated with where hotkey
-* listeners are attached (listener root). Use this instead of the global
-* `document.activeElement` so registrations scoped to an iframe (or another
-* document) read focus from the correct tree.
+* Whether the focused custom element may be a text field whose contents can't
+* be seen from outside:
+* - a host with focus inside a closed shadow root. Without a `tabindex` it
+*   can't hold focus itself, and an open root would have shown the focused
+*   element inside it.
+* - a form-associated element without a `role` attribute naming another control
 */
-function getActiveElementForListenerTarget(target) {
-	if (typeof document === "undefined") return null;
-	return getTargetDocument(target).activeElement;
+function isHiddenTextField(element) {
+	if (!element.localName.includes("-")) return false;
+	return element.constructor.formAssociated === true ? !element.hasAttribute("role") : !element.hasAttribute("tabindex");
 }
-const VERTICAL = ["ArrowUp", "ArrowDown"];
-const HORIZONTAL = ["ArrowLeft", "ArrowRight"];
-const ARROWS = [...VERTICAL, ...HORIZONTAL];
-const EDGES = ["Home", "End"];
-const PAGES = ["PageUp", "PageDown"];
-const ACTIVATION = ["Enter", "Space"];
-const TYPEAHEAD = "typeahead";
 /**
 * Returns the keys a control handles itself: activation for buttons and
 * links, and navigation for ARIA widgets, following the WAI-ARIA Authoring
 * Practices keyboard patterns (https://www.w3.org/WAI/ARIA/apg/patterns/).
+* Editable text fields never get here: they block every key that types text.
 */
 function getOwnedKeys(element) {
 	const orientation = element.getAttribute("aria-orientation");
-	switch (element.getAttribute("role")?.trim().split(/\s+/)[0]) {
+	switch (getRole(element)) {
 		case "button":
 		case "tab":
 		case "option":
@@ -69,64 +171,47 @@ function getOwnedKeys(element) {
 		case "menuitem":
 		case "menuitemcheckbox":
 		case "menuitemradio": return ACTIVATION;
-		case "link": return ["Enter"];
+		case "link": return ENTER;
 		case "checkbox":
 		case "switch":
-		case "radio": return ["Space"];
+		case "radio": return SPACE;
 		case "menu":
 		case "menubar":
-		case "tree": return [
-			...ARROWS,
-			...EDGES,
-			...ACTIVATION,
-			TYPEAHEAD
-		];
+		case "tree": return MENU;
 		case "listbox": return [
 			...orientation === "horizontal" ? HORIZONTAL : VERTICAL,
-			...EDGES,
-			...ACTIVATION,
-			TYPEAHEAD
-		];
-		case "combobox": return [
-			...VERTICAL,
-			...EDGES,
-			...ACTIVATION,
+			"Home",
+			"End",
+			"Enter",
+			"Space",
 			TYPEAHEAD
 		];
+		case "combobox": return COMBOBOX;
 		case "tablist": return [
 			...orientation === "vertical" ? VERTICAL : HORIZONTAL,
-			...EDGES,
-			...ACTIVATION
+			"Home",
+			"End",
+			"Enter",
+			"Space"
 		];
-		case "toolbar": return [...orientation === "vertical" ? VERTICAL : HORIZONTAL, ...EDGES];
-		case "grid":
-		case "treegrid": return [
-			...ARROWS,
-			...EDGES,
-			...PAGES,
-			...ACTIVATION
-		];
-		case "radiogroup": return [...ARROWS, "Space"];
-		case "slider": return [
-			...ARROWS,
-			...EDGES,
-			...PAGES
-		];
-		case "spinbutton": return [
-			...VERTICAL,
-			...EDGES,
-			...PAGES
+		case "toolbar": return [
+			...orientation === "vertical" ? VERTICAL : HORIZONTAL,
+			"Home",
+			"End"
 		];
+		case "grid":
+		case "treegrid": return GRID;
+		case "radiogroup": return RADIOS;
+		case "slider": return NAVIGATION;
+		case "spinbutton": return SPIN;
 	}
 	switch (element.localName) {
 		case "button":
 		case "summary": return ACTIVATION;
-		case "input": {
-			const type = element.type;
-			return type === "button" || type === "submit" || type === "reset" ? ACTIVATION : [];
-		}
+		case "input": return INPUT_KEYS[element.type] ?? CARET;
+		case "textarea": return NAVIGATION;
 		case "a":
-		case "area": return element.hasAttribute("href") ? ["Enter"] : [];
+		case "area": return element.hasAttribute("href") ? ENTER : [];
 	}
 	return [];
 }
@@ -139,56 +224,60 @@ function ownsKey(element, event, key) {
 	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) && /^\S$/u.test(event.key);
+	return owned.includes(key) || owned.includes(TYPEAHEAD) && /^.$/u.test(event.key);
 }
 /**
-* Whether the focused element or an element on the event's path passes `test`.
-* Only elements inside the registration target count: walking outward from
-* the event's origin stops at the registration target, so a hotkey targeted
-* at a control, or at an element inside it, is not blocked by that control.
+* Finds the first element on the event's way out that blocks it, walking out
+* from the focused element. A key event starts there in a browser. One sent
+* by a test may start at an ancestor of the focused element or at the
+* document, and the walk from focus passes through those too. Only an event
+* that starts where focus can't be seen, such as inside a closed shadow root,
+* uses its own path.
 */
-function someElementInsideTarget(event, listenerTarget, registrationTarget, test) {
-	const scoped = !isWindow(registrationTarget) && registrationTarget.nodeType !== 9;
-	const focused = getActiveElementForListenerTarget(listenerTarget);
-	if (focused && focused !== registrationTarget && (!scoped || registrationTarget.contains(focused)) && test(focused)) return true;
-	const path = event.composedPath();
-	for (const element of path.length > 0 ? path : [event.target]) {
-		if (element === registrationTarget) break;
-		if (isElement(element) && test(element)) return true;
-	}
-	return false;
+function findBlocker(event, doc, test) {
+	const focused = getDeepActiveElement(doc);
+	let elements = [];
+	for (let node = focused; node; node = composedParent(node)) if (isElement(node)) elements.push(node);
+	const origin = event.composedPath()[0];
+	if (isElement(origin) && !elements.includes(origin)) elements = event.composedPath().filter(isElement);
+	const index = elements.findIndex((element) => test(element) || element === focused && isHiddenTextField(element));
+	return {
+		elements,
+		index
+	};
 }
-/**
-* Returns whether a hotkey should skip an event because a focused control
-* inside the registration target handles the key itself:
-* - text inputs, textareas, selects, and contenteditable elements (typing)
-* - buttons, links, and `<summary>` elements (Enter and Space activation)
-* - ARIA widgets such as menus, listboxes, tabs, and grids (navigation keys)
-*/
-function shouldIgnoreInputEvent(event, listenerTarget, registrationTarget) {
-	const key = normalizeKeyName(event.key);
-	return someElementInsideTarget(event, listenerTarget, registrationTarget, (element) => isInputElement(element) || ownsKey(element, event, key));
+/** Whether the blocking element is inside `target`. A target never blocks itself. */
+function blocks({ elements, index }, target) {
+	return index >= 0 && (isDocumentLevel(target) || index < elements.indexOf(target));
 }
+const ignoreCache = /* @__PURE__ */ new WeakMap();
 /**
-* Returns whether an event comes from a text input, textarea, select, or
-* contenteditable element in the target's document. Unlike
-* `shouldIgnoreInputEvent`, buttons, links, and ARIA widgets don't count.
+* Returns whether a hotkey on `target` should skip an event because a control
+* inside the target handles the key itself:
+* - text fields, including ARIA text roles and custom elements that hide one (typing)
+* - buttons, links, `<summary>`, and button-like inputs (Enter and Space activation)
+* - checkbox, radio, and range inputs, and ARIA widgets such as menus,
+*   listboxes, tabs, and grids (the keys they use)
+*
+* A hotkey targeted at a control receives that control's keys.
 */
-function isTypingEvent(event, target) {
-	return someElementInsideTarget(event, target, target, isInputElement);
+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));
+		ignoreCache.set(event, blocker);
+	}
+	return blocks(blocker, target);
 }
 /**
-* Checks if an event is for the given target (originated from or bubbled to it).
-*
-* For document/window targets, also accepts the document's root element as
-* currentTarget to handle Brave and other browsers where currentTarget may be
-* documentElement instead of document when listeners are attached to document.
+* Returns whether an event comes from a text field inside `target`, as
+* `isInputElement` and hidden custom text fields define them. Buttons, links,
+* and other controls don't count.
 */
-function isEventForTarget(event, target) {
-	if (event.currentTarget === target) return true;
-	if (isWindow(target) || target.nodeType === 9) return event.currentTarget === getTargetDocument(target).documentElement;
-	return isNode(event.target) && target.contains(event.target);
+function isTypingEvent(event, target) {
+	return blocks(findBlocker(event, getTargetDocument(target), isInputElement), target);
 }
 
 //#endregion
-export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent };
+export { getTargetDocument, isDocumentLevel, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };

package/dist/_match.js

@@ -22,7 +22,7 @@ function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 	const direct = keysEqual(normalized.key, parsed.key);
 	const implicitShift = direct && isPrintableKey(normalized.key) && !/^\p{Letter}$/u.test(normalized.key) && !parsed.shift;
 	if (direct && modifiersMatch(normalized, parsed, implicitShift)) return matched("key", implicitShift ? 2 : 3);
-	if (isAsciiLetter(normalized.key) || isLatinLetter(normalized.key) && normalized.code.startsWith("Key") && !normalized.alt) return noMatch;
+	if (!positionStandsIn(normalized)) return noMatch;
 	if (normalized.altGraph) return noMatch;
 	if (!modifiersMatch(normalized, parsed, false)) return noMatch;
 	const fallbackKey = codeToLogicalKey(normalized.code);
@@ -39,6 +39,28 @@ function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 		};
 	}
 }
+/**
+* Whether a key's conventional position may stand in for what it typed. Only
+* output that can't name a shortcut falls back:
+* - non-Latin letters and symbols, such as Russian `ы` or macOS Option's `–`
+* - dead keys
+* - 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
+*   Cmd+ü still fires `Mod+[` (German types `[` with Option)
+*
+* A named key (`End` from a NumLock-off numpad), any other ASCII character,
+* or a Latin letter typed on its own is the key the user meant, wherever it
+* sits. AZERTY's `+` on the US `/` position is `+`, not `/`.
+*/
+function positionStandsIn({ key, code, ctrl, meta, shift, alt }) {
+	if (key !== "Dead" && !isPrintableKey(key)) return false;
+	if (code.startsWith("Digit")) return true;
+	if (isAsciiLetter(key)) return false;
+	if (/^[!-~]$/.test(key)) return shift;
+	if (!isLatinLetter(key) || alt) return true;
+	return (ctrl || meta) && !code.startsWith("Key");
+}
 /** Compares modifiers, excluding synthetic AltGr flags and optionally allowing Shift used to type a glyph. */
 function modifiersMatch(event, parsed, allowImplicitShift) {
 	const ctrl = event.altGraph ? false : event.ctrl;

package/dist/app-hotkeys.js

@@ -227,13 +227,12 @@ 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);
+			const has = (status) => registered.some((r) => r.status === status);
 			return {
 				appHotkey,
-				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : enabled.length === 0 ? "disabled" : enabled.some((r) => manager.isScopeActive(r.options.scope)) ? "active" : "suspended",
+				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : has("active") ? "active" : has("suspended") ? "suspended" : "disabled",
 				isCustom: isCustomHotkey(appHotkey, this.#platform),
 				registrations: registered
 			};

package/dist/hotkey-manager.d.ts

@@ -1,5 +1,5 @@
 import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
-import { AppHotkeysStore } from "./app-hotkeys.js";
+import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
 /** An element, document, or window that hotkeys can listen on. */
@@ -41,9 +41,14 @@ export interface HotkeyOptions {
   platform?: 'mac' | 'windows' | 'linux';
   /**
    * Prevent the default browser action when the hotkey matches. For a
-   * sequence, every step that advances it does. Defaults to true
+   * sequence, every step that advances it does. Defaults to true.
+   *
+   * `'always'` also prevents it while a chord can't fire because it is
+   * disabled or its scope is inactive or suspended, unless another hotkey
+   * handles the key. It never stops propagation for such a chord. Sequences
+   * treat `'always'` as `true`.
    */
-  preventDefault?: boolean;
+  preventDefault?: boolean | 'always';
   /**
    * Stop event propagation when the hotkey matches. For a sequence, only the
    * last step does, so earlier steps reach other listeners. Defaults to true
@@ -118,8 +123,18 @@ export interface HotkeySequenceRegistration extends RegistrationBase<HotkeySeque
 }
 /** A registered hotkey in the HotkeyManager. */
 export type HotkeyRegistration = HotkeyChordRegistration | HotkeySequenceRegistration;
+/**
+ * Whether a registration is on. Focus isn't checked: a registration on an
+ * element also needs focus inside that element to fire.
+ * - `'active'`: enabled, and its scope is active
+ * - `'suspended'`: enabled, but its scope is inactive or suspended by an exclusive scope
+ * - `'disabled'`: registered with `enabled: false`
+ */
+export type HotkeyRegistrationStatus = 'active' | 'suspended' | 'disabled';
 interface RegistrationViewBase {
   id: string;
+  /** Whether the registration is enabled and in an active scope. */
+  status: HotkeyRegistrationStatus;
   target: Target;
   triggerCount: number;
   hasFired: boolean;
@@ -372,6 +387,17 @@ export declare class HotkeyManager {
    * @returns True if a matching registration exists
    */
   isRegistered(hotkey: RegisterableHotkey, target?: Target): boolean;
+  /**
+   * Checks whether a hotkey can fire now: at least one registration is
+   * enabled, in an active scope, and listening where key presses go. A
+   * registration on `document` or `window` always is; one on an element is
+   * only while focus is inside that element. An app hotkey matches
+   * registrations by id, so custom hotkeys apply.
+   *
+   * @param hotkey - A chord, sequence, or app hotkey
+   * @returns True if a registration that can fire exists
+   */
+  hasActiveRegistration(hotkey: RegisterableHotkey | AppHotkey): boolean;
   /**
    * Destroys the manager and removes all listeners.
    */

package/dist/hotkey-manager.js

@@ -5,7 +5,7 @@ import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
+import { getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
@@ -13,10 +13,16 @@ import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConfl
 import { Store } from "@tanstack/store";
 
 //#region 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";
+	return manager?.isScopeActive(options.scope) === false ? "suspended" : "active";
+}
 /** Creates a public view from an internal registration, stripping the callback. */
 function toHotkeyRegistrationView(reg) {
 	const base = {
 		id: reg.id,
+		status: getRegistrationStatus(reg.options, managerRef.current),
 		target: reg.target,
 		triggerCount: reg.triggerCount,
 		hasFired: reg.hasFired
@@ -270,7 +276,20 @@ var HotkeyManager = class HotkeyManager {
 	}
 	/** Whether a registration can fire now: enabled, in an active scope. */
 	#isLive(registration) {
-		return registration.options.enabled !== false && this.isScopeActive(registration.options.scope);
+		return getRegistrationStatus(registration.options, this) === "active";
+	}
+	/**
+	* Whether a hotkey that can fire would handle this key on any listener the
+	* event reaches, including other targets and phases. A sequence counts when
+	* the key matches its next step or its first step.
+	*/
+	#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 ((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;
 	}
 	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
 	#notify() {
@@ -455,14 +474,20 @@ var HotkeyManager = class HotkeyManager {
 		if (isRecordingEvent(event) || this.#sequenceOwned.get(event)) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
+		let reserved = false;
 		for (const registration of registrations) {
-			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			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) {
-				matches.set(registration.id, result);
-				bestScore = Math.max(bestScore, result.score);
+			if (!result.matched) continue;
+			if (!live) {
+				reserved = true;
+				continue;
 			}
+			matches.set(registration.id, result);
+			bestScore = Math.max(bestScore, result.score);
 		}
+		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) event.preventDefault();
 		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) {
@@ -508,7 +533,7 @@ var HotkeyManager = class HotkeyManager {
 		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;
 			const target = registration.target;
-			if (path.includes(target.nodeType === 1 ? target : getTargetDocument(target)) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
+			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;
 		}
 		return false;
 	}
@@ -531,7 +556,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!isEventForTarget(event, target) || !this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
+			if (!this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target) || registration.options.eventType !== eventType) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -679,6 +704,21 @@ var HotkeyManager = class HotkeyManager {
 		return false;
 	}
 	/**
+	* Checks whether a hotkey can fire now: at least one registration is
+	* enabled, in an active scope, and listening where key presses go. A
+	* registration on `document` or `window` always is; one on an element is
+	* only while focus is inside that element. An app hotkey matches
+	* registrations by id, so custom hotkeys apply.
+	*
+	* @param hotkey - A chord, sequence, or app hotkey
+	* @returns True if a registration that can fire exists
+	*/
+	hasActiveRegistration(hotkey) {
+		const id = typeof hotkey === "object" && "~appHotkey" in hotkey ? hotkey.id : void 0;
+		for (const registration of this.registrations.state.values()) if (this.#isLive(registration) && targetHasFocus(registration.target) && (id === void 0 ? areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) : registration.options.appHotkeyId === id)) return true;
+		return false;
+	}
+	/**
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {

package/dist/hotkey-recorder.js

@@ -101,7 +101,7 @@ var HotkeyRecorder = class {
 	* and records chords according to `maxSteps`.
 	*/
 	start() {
-		if (this.#keydownHandler) return;
+		if (this.#keydownHandler || typeof document === "undefined") return;
 		this.#clearIdleTimer();
 		this.#events = [];
 		beginRecording(this);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
 import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
-import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { 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 } 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";
@@ -13,4 +13,4 @@ import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
-export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/hotkeys-core/SKILL.md

@@ -56,7 +56,7 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 
 ## Pitfalls
 
-- **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. To skip the action, keep the hotkey enabled and return early from the callback.
+- **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. Add `preventDefault: 'always'` to keep the action blocked while the hotkey can't fire, whether it's disabled or its scope is off. Skip it for hotkeys turned off to give the key back to the browser, such as `Mod+C`, `Mod+Z`, `Tab`, or single keys behind a user's off switch. Don't keep the hotkey enabled and return early from the callback; the hotkey would also stay `active` in app hotkey lists and show its hint.
 - **Modifiers match exactly.** `ArrowDown` never fires while Shift is held, so register `Shift+ArrowDown` instead of checking `event.shiftKey`. Shift that a symbol needs is the exception: `?` matches Shift+/.
 - **Chords repeat while held.** Set `requireReset: true` on toggles, or holding the keys flickers them.
 - **Letters follow the typed character.** For position-based controls such as WASD, use physical bindings such as `'[KeyW]'`. Keep letters for mnemonic commands such as `Mod+S`.

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

@@ -9,3 +9,5 @@
 - A hotkey's `scope` option, or an app hotkey's declared `scope`, overrides the provider's.
 - Scopes follow the component tree, not the DOM, so a portaled dialog keeps its scope.
 - The hotkey that opens an exclusive dialog is suspended with the rest of the page. To close the dialog with the same keys, register that hotkey inside the dialog too.
+- To show which scope owns the keyboard, use the adapter's scope state API, such as `useHotkeyScopesState()` in React. Don't subscribe to `manager.scopes` by hand.
+- To list only hotkeys that are on, filter the adapter's registrations by `status === 'active'`. `'suspended'` means the hotkey's scope is inactive or suspended, and `'disabled'` means `enabled: false`.