@tanstack/hotkeys 0.12.1 → 0.13.0

package/dist/_event-target.js

@@ -1,4 +1,21 @@
+import { normalizeKeyName } from "./constants.js";
+
 //#region src/_event-target.ts
+function isNode(target) {
+	return typeof target?.nodeType === "number";
+}
+function isElement(target) {
+	return isNode(target) && target.nodeType === 1;
+}
+function isWindow(target) {
+	return "document" in target;
+}
+/** 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;
+}
 /**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
@@ -12,15 +29,13 @@
 * Mod+S and Escape fire when the user has tabbed to a form button.
 */
 function isInputElement(element) {
-	if (!element) return false;
-	if (element instanceof HTMLInputElement) {
+	if (!isElement(element)) return false;
+	if (element.localName === "input") {
 		const type = element.type.toLowerCase();
-		if (type === "button" || type === "submit" || type === "reset") return false;
-		return true;
+		return type !== "button" && type !== "submit" && type !== "reset";
 	}
-	if (element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) return true;
-	if (element instanceof HTMLElement && element.isContentEditable) return true;
-	return false;
+	if (element.localName === "textarea" || element.localName === "select") return true;
+	return element.isContentEditable === true;
 }
 /**
 * Returns the focused element for the document associated with where hotkey
@@ -30,41 +45,150 @@ function isInputElement(element) {
 */
 function getActiveElementForListenerTarget(target) {
 	if (typeof document === "undefined") return null;
-	if (typeof Document !== "undefined" && target instanceof Document || typeof Node !== "undefined" && target.nodeType === Node.DOCUMENT_NODE) return target.activeElement;
-	if (typeof HTMLElement !== "undefined" && target instanceof HTMLElement) return target.ownerDocument.activeElement ?? null;
-	return target.document.activeElement ?? null;
+	return getTargetDocument(target).activeElement;
 }
+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 whether an event should be ignored because it originated from an
-* input-like element other than the registration target.
-*
-* This checks:
-* - the currently focused element for the listener target
-* - the event's composed path (for shadow DOM)
-* - the event target as a final fallback
+* 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/).
 */
-function shouldIgnoreInputEvent(event, listenerTarget, registrationTarget) {
+function getOwnedKeys(element) {
+	const orientation = element.getAttribute("aria-orientation");
+	switch (element.getAttribute("role")?.trim().split(/\s+/)[0]) {
+		case "button":
+		case "tab":
+		case "option":
+		case "treeitem":
+		case "menuitem":
+		case "menuitemcheckbox":
+		case "menuitemradio": return ACTIVATION;
+		case "link": return ["Enter"];
+		case "checkbox":
+		case "switch":
+		case "radio": return ["Space"];
+		case "menu":
+		case "menubar":
+		case "tree": return [
+			...ARROWS,
+			...EDGES,
+			...ACTIVATION,
+			TYPEAHEAD
+		];
+		case "listbox": return [
+			...orientation === "horizontal" ? HORIZONTAL : VERTICAL,
+			...EDGES,
+			...ACTIVATION,
+			TYPEAHEAD
+		];
+		case "combobox": return [
+			...VERTICAL,
+			...EDGES,
+			...ACTIVATION,
+			TYPEAHEAD
+		];
+		case "tablist": return [
+			...orientation === "vertical" ? VERTICAL : HORIZONTAL,
+			...EDGES,
+			...ACTIVATION
+		];
+		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
+		];
+	}
+	switch (element.localName) {
+		case "button":
+		case "summary": return ACTIVATION;
+		case "input": {
+			const type = element.type;
+			return type === "button" || type === "submit" || type === "reset" ? ACTIVATION : [];
+		}
+		case "a":
+		case "area": return element.hasAttribute("href") ? ["Enter"] : [];
+	}
+	return [];
+}
+/**
+* Whether a control handles this key itself. Ctrl, Meta, and Alt combinations
+* 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) {
+	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);
+}
+/**
+* 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.
+*/
+function someElementInsideTarget(event, listenerTarget, registrationTarget, test) {
+	const scoped = !isWindow(registrationTarget) && registrationTarget.nodeType !== 9;
 	const focused = getActiveElementForListenerTarget(listenerTarget);
-	if (focused && isInputElement(focused) && focused !== registrationTarget) return true;
-	if (event.composedPath().some((element) => isInputElement(element) && element !== registrationTarget)) return true;
-	return isInputElement(event.target) && event.target !== registrationTarget;
+	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;
+}
+/**
+* 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));
+}
+/**
+* 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.
+*/
+function isTypingEvent(event, target) {
+	return someElementInsideTarget(event, target, target, isInputElement);
 }
 /**
 * Checks if an event is for the given target (originated from or bubbled to it).
 *
-* For document/window targets, also accepts document.documentElement as currentTarget
-* to handle Brave and other browsers where currentTarget may be documentElement
-* instead of document when listeners are attached to document.
+* 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.
 */
 function isEventForTarget(event, target) {
-	if (target === document || target === window) return event.currentTarget === target || event.currentTarget === document.documentElement;
-	if (target === window) return event.currentTarget === window || event.currentTarget === document || event.currentTarget === document.documentElement;
-	if (target instanceof HTMLElement) {
-		if (event.currentTarget === target) return true;
-		if (event.target instanceof Node && target.contains(event.target)) return true;
-	}
-	return false;
+	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);
 }
 
 //#endregion
-export { getActiveElementForListenerTarget, isEventForTarget, isInputElement, shouldIgnoreInputEvent };
+export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent };

package/dist/_registration.js

@@ -8,11 +8,11 @@ const defaultHotkeyOptions = {
 	stopPropagation: true,
 	eventType: "keydown",
 	enabled: true,
-	ignoreInputs: true,
+	ignoreInputs: "auto",
 	conflictBehavior: "warn"
 };
 /**
-* Computes the default ignoreInputs value based on the hotkey.
+* Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).
 * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
 */
 function getDefaultIgnoreInputs(parsedHotkey) {

package/dist/adapter.js

@@ -1,6 +1,6 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeRegisterableHotkey, parseHotkey } from "./parse.js";
-import { defaultHotkeyOptions, getDefaultIgnoreInputs } from "./_registration.js";
+import { isHotkeySequence, normalizeRegisterableHotkey } from "./parse.js";
+import { defaultHotkeyOptions } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
 
@@ -23,14 +23,12 @@ function createHotkeyBindings() {
 				const options = {
 					...defaultHotkeyOptions,
 					...merged,
-					ignoreInputs: merged.ignoreInputs,
+					ignoreInputs: merged.ignoreInputs ?? "auto",
 					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
 					platform: merged.platform ?? detectPlatform()
 				};
 				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
 				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
-				const first = isHotkeySequence(hotkey) ? hotkey[0] : hotkey;
-				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(first, options.platform));
 				if (isHotkeySequence(hotkey)) delete options.requireReset;
 				else delete options.timeout;
 				prepared.push({

package/dist/conflicts.js

@@ -2,18 +2,14 @@ import { detectPlatform } from "./platform.js";
 import { keysEqual } from "./_keyboard-event.js";
 import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
 import { matchesKeyboardEvent } from "./match.js";
+import { getTargetDocument } from "./_event-target.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 
 //#region 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;
-	const documentOf = (target) => {
-		if ("document" in target) return target.document;
-		if (target.nodeType === 9) return target;
-		return target.ownerDocument;
-	};
-	if (documentOf(a) !== documentOf(b)) return false;
+	if (getTargetDocument(a) !== getTargetDocument(b)) return false;
 	if (!("contains" in a) || !("contains" in b)) return true;
 	return a.contains(b) || b.contains(a);
 }

package/dist/hotkey-manager.d.ts

@@ -18,8 +18,17 @@ export interface HotkeyOptions {
   enabled?: boolean;
   /** The event type to listen for. Defaults to 'keydown' */
   eventType?: 'keydown' | 'keyup';
-  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on the hotkey (the first step of a sequence): true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */
-  ignoreInputs?: boolean;
+  /**
+   * Skip keys that a focused control inside the target uses itself: typing in
+   * text inputs, textarea, select, and contenteditable; Enter/Space on buttons
+   * and summary elements; Enter on links; and navigation keys in ARIA widgets
+   * such as menus, listboxes, tabs, and grids. A hotkey targeted at the control
+   * itself still receives them. Defaults to `'auto'`, which chooses from the
+   * hotkey (the first step of a sequence): true for single keys and Shift/Alt
+   * combos; false for Ctrl/Meta shortcuts and Escape. Set false to handle keys
+   * even in these controls.
+   */
+  ignoreInputs?: boolean | 'auto';
   /** The target platform for resolving 'Mod' */
   platform?: 'mac' | 'windows' | 'linux';
   /** Prevent the default browser action when the hotkey matches. Defaults to true */

package/dist/hotkey-manager.js

@@ -5,9 +5,9 @@ import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey,
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
+import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { isRecordingEvent } from "./_recording-guard.js";
 import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
-import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
@@ -58,6 +58,11 @@ function optionsForKind(kind, options) {
 function resolvedSteps(registration) {
 	return registration.kind === "chord" ? [registration.parsedHotkey] : registration.parsedSequence;
 }
+/** Whether a registration skips keys that focused controls use, resolving `'auto'`. */
+function ignoresInputs(registration) {
+	const { ignoreInputs = "auto" } = registration.options;
+	return ignoreInputs === "auto" ? getDefaultIgnoreInputs(resolvedSteps(registration)[0]) : ignoreInputs;
+}
 function sameResolvedSteps(left, right) {
 	return left.length === right.length && left.every((step, index) => areHotkeysEqual(step, right[index]));
 }
@@ -167,28 +172,26 @@ var HotkeyManager = class HotkeyManager {
 		const platform = options.platform ?? this.#platform;
 		const target = options.target ?? document;
 		let registration;
-		if (isHotkeySequence(hotkey)) {
-			const parsedSequence = hotkey.map((step) => parseHotkey(step, platform));
-			registration = {
-				kind: "sequence",
-				id,
-				hotkey,
-				parsedSequence,
-				callback,
-				options: {
-					...defaultHotkeyOptions,
-					timeout: DEFAULT_SEQUENCE_TIMEOUT,
-					...optionsForKind("sequence", options),
-					platform,
-					ignoreInputs: options.ignoreInputs ?? getDefaultIgnoreInputs(parsedSequence[0])
-				},
-				target,
-				currentIndex: 0,
-				lastKeyTime: 0,
-				triggerCount: 0,
-				hasFired: false
-			};
-		} else {
+		if (isHotkeySequence(hotkey)) registration = {
+			kind: "sequence",
+			id,
+			hotkey,
+			parsedSequence: hotkey.map((step) => parseHotkey(step, platform)),
+			callback,
+			options: {
+				...defaultHotkeyOptions,
+				timeout: DEFAULT_SEQUENCE_TIMEOUT,
+				...optionsForKind("sequence", options),
+				platform,
+				ignoreInputs: options.ignoreInputs ?? "auto"
+			},
+			target,
+			currentIndex: 0,
+			lastKeyTime: 0,
+			triggerCount: 0,
+			hasFired: false
+		};
+		else {
 			const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
 			registration = {
 				kind: "chord",
@@ -201,7 +204,7 @@ var HotkeyManager = class HotkeyManager {
 					requireReset: false,
 					...optionsForKind("chord", options),
 					platform,
-					ignoreInputs: options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)
+					ignoreInputs: options.ignoreInputs ?? "auto"
 				},
 				target,
 				hasFired: false,
@@ -323,7 +326,7 @@ var HotkeyManager = class HotkeyManager {
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
 			const result = matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
 			if (result.matched) {
 				matches.set(registration.id, result);
@@ -367,7 +370,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!isEventForTarget(event, target) || !registration.options.enabled || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
+			if (!isEventForTarget(event, target) || !registration.options.enabled || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;

package/dist/hotkey-recorder.js

@@ -2,8 +2,8 @@ import { detectPlatform } from "./platform.js";
 import { normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
+import { isTypingEvent } from "./_event-target.js";
 import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
-import { shouldIgnoreInputEvent } from "./_event-target.js";
 import { findHotkeyConflicts } from "./conflicts.js";
 import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
 import { Store } from "@tanstack/store";
@@ -111,7 +111,7 @@ var HotkeyRecorder = class {
 		}));
 		const handler = (event) => {
 			if (!this.#keydownHandler) return;
-			if (this.#options.ignoreInputs !== false && event.key !== "Escape" && shouldIgnoreInputEvent(event, document, document)) return;
+			if (this.#options.ignoreInputs !== false && event.key !== "Escape" && isTypingEvent(event, document)) return;
 			const platform = this.#options.platform ?? this.#platform;
 			if (normalizeKeyboardEvent(event, platform).isComposing) return;
 			captureRecordingEvent(event);

package/package.json

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