@tanstack/hotkeys 0.18.0 → 0.19.0

package/dist/_event-target.js

@@ -1,78 +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);
 }
 /**
 * 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.
+* root it contains or on content slotted into it.
 */
 function targetHasFocus(target) {
-	if (isWindow(target) || target.nodeType === 9) return true;
-	const active = target.getRootNode().activeElement;
-	return !!active && target.contains(active);
+	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"
+];
 /**
-* 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
+* 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":
@@ -80,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
-		];
-		case "toolbar": return [...orientation === "vertical" ? VERTICAL : HORIZONTAL, ...EDGES];
-		case "grid":
-		case "treegrid": return [
-			...ARROWS,
-			...EDGES,
-			...PAGES,
-			...ACTIVATION
+			"Home",
+			"End",
+			"Enter",
+			"Space"
 		];
-		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 [];
 }
@@ -150,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, targetHasFocus };
+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/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, targetHasFocus } 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";
@@ -286,7 +286,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, registration.target)) continue;
+			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;
@@ -477,7 +477,7 @@ var HotkeyManager = class HotkeyManager {
 		let reserved = false;
 		for (const registration of registrations) {
 			const live = this.#isLive(registration);
-			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			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;
 			if (!live) {
@@ -533,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;
 	}
@@ -556,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;

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/package.json

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