@tanstack/hotkeys 0.8.0 → 0.10.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="./media/header_hotkeys.png" alt="TanStack Hotkeys" />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/hotkeys.png"
+      alt="TanStack Hotkeys"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />

package/dist/{manager.utils.js → _event-target.js}

@@ -1,25 +1,4 @@
-//#region src/manager.utils.ts
-/**
-* Default options for hotkey/sequence registration.
-* Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
-*/
-const defaultHotkeyOptions = {
-	preventDefault: true,
-	stopPropagation: true,
-	eventType: "keydown",
-	enabled: true,
-	ignoreInputs: true,
-	conflictBehavior: "warn"
-};
-/**
-* Computes the default ignoreInputs value based on the hotkey.
-* Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
-*/
-function getDefaultIgnoreInputs(parsedHotkey) {
-	if (parsedHotkey.ctrl || parsedHotkey.meta) return false;
-	if (parsedHotkey.key === "Escape") return false;
-	return true;
-}
+//#region src/_event-target.ts
 /**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
@@ -86,24 +65,6 @@ function isEventForTarget(event, target) {
 	}
 	return false;
 }
-/**
-* Handles conflicts between registrations based on conflict behavior.
-*
-* @param conflictingId - The ID of the conflicting registration
-* @param keyDisplay - Display string for the conflicting key/sequence (for error messages)
-* @param conflictBehavior - How to handle the conflict
-* @param unregister - Function to unregister by ID
-*/
-function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
-	if (conflictBehavior === "allow") return;
-	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers will be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
-		return;
-	}
-	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);
-	unregister(conflictingId);
-}
 
 //#endregion
-export { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, isEventForTarget, isInputElement, shouldIgnoreInputEvent };
-//# sourceMappingURL=manager.utils.js.map
+export { getActiveElementForListenerTarget, isEventForTarget, isInputElement, shouldIgnoreInputEvent };

package/dist/_keyboard-event.js

@@ -0,0 +1,75 @@
+import { PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+
+//#region src/_keyboard-event.ts
+/** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */
+function normalizeKeyboardEvent(event, platform) {
+	let altGraph = false;
+	try {
+		altGraph = platform !== "mac" && typeof event.getModifierState === "function" && event.getModifierState("AltGraph");
+	} catch {}
+	const key = (event.key || "").normalize("NFC");
+	return {
+		key: normalizeKeyName(key),
+		code: event.code || "",
+		ctrl: Boolean(event.ctrlKey),
+		shift: Boolean(event.shiftKey),
+		alt: Boolean(event.altKey),
+		meta: Boolean(event.metaKey),
+		altGraph,
+		location: event.location,
+		isComposing: Boolean(event.isComposing) || key === "Process" || key === "Unidentified"
+	};
+}
+/**
+* Maps familiar positions to compatibility fallback keys for the logical matcher.
+* This assumes conventional positions, not the active layout; never use it to
+* turn recorded physical bindings into logical bindings or display labels.
+*/
+function codeToLogicalKey(code) {
+	if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase();
+	if (/^Digit[0-9]$/i.test(code)) return code.slice(5);
+	if (/^Numpad[0-9]$/i.test(code)) return code.slice(6);
+	const punctuation = PUNCTUATION_CODE_MAP[code];
+	if (punctuation) return punctuation;
+	return {
+		NumpadAdd: "+",
+		NumpadSubtract: "-",
+		NumpadMultiply: "*",
+		NumpadDivide: "/",
+		NumpadDecimal: ".",
+		NumpadEnter: "Enter",
+		Space: "Space"
+	}[code];
+}
+/** Tests for one Unicode code point, including characters represented by a surrogate pair. */
+function isPrintableKey(key) {
+	return key !== "" && Array.from(key).length === 1;
+}
+/** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
+function splitHotkeyParts(hotkey) {
+	if (!hotkey.endsWith("+")) return hotkey.split("+");
+	const parts = hotkey.slice(0, -1).split("+");
+	if (parts.at(-1) === "") parts.pop();
+	parts.push("+");
+	return parts;
+}
+/** Identifies ASCII letters whose layout-produced value takes precedence over positional fallbacks. */
+function isAsciiLetter(key) {
+	return /^[A-Za-z]$/.test(key);
+}
+/** Identifies a single Latin-script character, including accented letters. */
+function isLatinLetter(key) {
+	return /^\p{Script_Extensions=Latin}$/u.test(key);
+}
+/** Compares letters without case, preserving accents and avoiding expansions such as ß → SS. */
+function keysEqual(left, right) {
+	if (/^\p{Letter}$/u.test(left) && /^\p{Letter}$/u.test(right)) return left.localeCompare(right, void 0, { sensitivity: "accent" }) === 0;
+	return left === right;
+}
+/** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */
+function assertLogicalKey(key) {
+	if (/^\[.*\]$/s.test(key.trim())) throw new Error("Logical key must not contain a bracketed physical code. Use the code field instead.");
+}
+
+//#endregion
+export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent, splitHotkeyParts };

package/dist/_match.js

@@ -0,0 +1,48 @@
+import { detectPlatform } from "./platform.js";
+import { codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { parseHotkey } from "./parse.js";
+
+//#region src/_match.ts
+/** Matches an event and reports the winning candidate and release identity. */
+function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	const normalized = normalizeKeyboardEvent(event, platform);
+	const noMatch = {
+		matched: false,
+		score: 0
+	};
+	if (normalized.isComposing && (parsed.code !== void 0 || isPrintableKey(parsed.key))) return noMatch;
+	if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch;
+	if (parsed.code !== void 0) {
+		if (!modifiersMatch(normalized, parsed, false)) return noMatch;
+		return normalized.code === parsed.code ? matched("code", 3) : noMatch;
+	}
+	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 (!modifiersMatch(normalized, parsed, false)) return noMatch;
+	const fallbackKey = codeToLogicalKey(normalized.code);
+	return fallbackKey !== void 0 && keysEqual(fallbackKey, parsed.key) ? matched("fallback", 1) : noMatch;
+	function matched(source, score) {
+		return {
+			matched: true,
+			score,
+			source,
+			identity: {
+				key: normalized.key,
+				code: normalized.code
+			}
+		};
+	}
+}
+/** 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;
+	const alt = event.altGraph ? false : event.alt;
+	if (ctrl !== parsed.ctrl || alt !== parsed.alt || event.meta !== parsed.meta) return false;
+	return event.shift === parsed.shift || allowImplicitShift && event.shift;
+}
+
+//#endregion
+export { matchKeyboardEvent };

package/dist/_named-keys.d.ts

@@ -0,0 +1,6 @@
+//#region src/_named-keys.d.ts
+/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
+export declare const SHARED_NAMED_KEYS: readonly ["CapsLock", "ContextMenu", "Convert", "KanaMode", "NonConvert", "Help", "Insert", "NumLock", "Fn", "FnLock", "PrintScreen", "ScrollLock", "Pause", "BrowserBack", "BrowserFavorites", "BrowserForward", "BrowserHome", "BrowserRefresh", "BrowserSearch", "BrowserStop", "Eject", "LaunchMail", "MediaPlayPause", "MediaStop", "MediaTrackNext", "MediaTrackPrevious", "Power", "AudioVolumeDown", "AudioVolumeMute", "AudioVolumeUp", "WakeUp", "Hyper", "Super", "Again", "Copy", "Cut", "Find", "Open", "Paste", "Props", "Select", "Undo", "Hiragana", "Katakana"];
+/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
+export declare const LOGICAL_ONLY_NAMED_KEYS: readonly ["Clear", "Cancel", "Standby", "LaunchApplication1", "LaunchApplication2", "LaunchMediaPlayer", "HangulMode", "HanjaMode", "Zenkaku", "Hankaku", "ZenkakuHankaku"];
+//#endregion

package/dist/_named-keys.js

@@ -0,0 +1,65 @@
+//#region src/_named-keys.ts
+/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
+const SHARED_NAMED_KEYS = [
+	"CapsLock",
+	"ContextMenu",
+	"Convert",
+	"KanaMode",
+	"NonConvert",
+	"Help",
+	"Insert",
+	"NumLock",
+	"Fn",
+	"FnLock",
+	"PrintScreen",
+	"ScrollLock",
+	"Pause",
+	"BrowserBack",
+	"BrowserFavorites",
+	"BrowserForward",
+	"BrowserHome",
+	"BrowserRefresh",
+	"BrowserSearch",
+	"BrowserStop",
+	"Eject",
+	"LaunchMail",
+	"MediaPlayPause",
+	"MediaStop",
+	"MediaTrackNext",
+	"MediaTrackPrevious",
+	"Power",
+	"AudioVolumeDown",
+	"AudioVolumeMute",
+	"AudioVolumeUp",
+	"WakeUp",
+	"Hyper",
+	"Super",
+	"Again",
+	"Copy",
+	"Cut",
+	"Find",
+	"Open",
+	"Paste",
+	"Props",
+	"Select",
+	"Undo",
+	"Hiragana",
+	"Katakana"
+];
+/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
+const LOGICAL_ONLY_NAMED_KEYS = [
+	"Clear",
+	"Cancel",
+	"Standby",
+	"LaunchApplication1",
+	"LaunchApplication2",
+	"LaunchMediaPlayer",
+	"HangulMode",
+	"HanjaMode",
+	"Zenkaku",
+	"Hankaku",
+	"ZenkakuHankaku"
+];
+
+//#endregion
+export { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS };

package/dist/_recorder-chord.js

@@ -0,0 +1,42 @@
+import { normalizeKeyName } from "./constants.js";
+import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isModifierKey, normalizeHotkeyFromParsed, parseKeyboardEvent } from "./parse.js";
+
+//#region src/_recorder-chord.ts
+/**
+* Converts a keydown to a replayable chord, preserving physical codes by default.
+* Returns null for composition, modifier-only input, or unusable physical input.
+* Key mode retains the produced character; neither mode guesses layout letters.
+*/
+function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
+	const normalized = normalizeKeyboardEvent(event, platform);
+	if (normalized.isComposing || isModifierKey(normalizeKeyName(event.key)) || event.key === "AltGraph") return null;
+	if (recordBy === "code" && (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) || event.code === "Unidentified" || normalized.altGraph)) return null;
+	const parsed = parseKeyboardEvent(event, platform);
+	if (recordBy === "code") {
+		const { key: _key, code: _code, ...modifiers } = parsed;
+		return normalizeHotkeyFromParsed({
+			...modifiers,
+			code: event.code
+		}, platform);
+	}
+	return parsed.key ? normalizeHotkeyFromParsed(parsed, platform) : null;
+}
+/**
+* Explains why a physical chord cannot be recorded before syntax/policy checks.
+* Logical mode deliberately accepts produced characters instead of requiring a code.
+*/
+function chordRejection(event, options) {
+	if (options.recordBy === "key") return void 0;
+	if (normalizeKeyboardEvent(event, options.platform).altGraph) return {
+		reason: "alt-graph",
+		message: "AltGraph character entry cannot be recorded as a physical shortcut. Use key mode for characters."
+	};
+	if (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) || event.code === "Unidentified") return {
+		reason: "missing-code",
+		message: "This event has no usable physical key code."
+	};
+}
+
+//#endregion
+export { chordRejection, hotkeyChordFromKeydown };

package/dist/_recording-guard.js

@@ -0,0 +1,55 @@
+import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
+
+//#region src/_recording-guard.ts
+const sessions = /* @__PURE__ */ new Set();
+const captured = /* @__PURE__ */ new WeakSet();
+const pending = /* @__PURE__ */ new Map();
+let listening = false;
+const identity = (event) => event.code || `key:${event.key}`;
+/** Consumes recorded key releases and removes guards for completed chords. */
+function release(event) {
+	if (pending.delete(identity(event))) captured.add(event);
+	if (MODIFIER_KEYS.has(normalizeKeyName(event.key))) {
+		for (const [id, key] of pending) if (!MODIFIER_KEYS.has(key)) pending.delete(id);
+	}
+	cleanup();
+}
+/** Clears pending releases when focus loss prevents the browser from delivering them. */
+function blur() {
+	pending.clear();
+	cleanup();
+}
+/** Detaches shared listeners once neither active sessions nor pending releases need them. */
+function cleanup() {
+	if (listening && sessions.size === 0 && pending.size === 0) {
+		document.removeEventListener("keyup", release, true);
+		window.removeEventListener("blur", blur);
+		listening = false;
+	}
+}
+/** Pauses application shortcut dispatch and starts tracking releases for this recorder. */
+function beginRecording(owner) {
+	sessions.add(owner);
+	if (!listening && typeof document !== "undefined") {
+		document.addEventListener("keyup", release, true);
+		window.addEventListener("blur", blur);
+		listening = true;
+	}
+}
+/** Ends a session while retaining guards for keys still held after commit or cancellation. */
+function endRecording(owner) {
+	sessions.delete(owner);
+	cleanup();
+}
+/** Marks a consumed keydown and guards subsequent repeats and its release. */
+function captureRecordingEvent(event) {
+	captured.add(event);
+	pending.set(identity(event), normalizeKeyName(event.key));
+}
+/** Whether managers should suppress callbacks for this recording session or captured chord. */
+function isRecordingEvent(event) {
+	return sessions.size > 0 || captured.has(event) || pending.has(identity(event));
+}
+
+//#endregion
+export { beginRecording, captureRecordingEvent, endRecording, isRecordingEvent };

package/dist/_registration.js

@@ -0,0 +1,49 @@
+//#region src/_registration.ts
+/**
+* Default options for hotkey/sequence registration.
+* Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
+*/
+const defaultHotkeyOptions = {
+	preventDefault: true,
+	stopPropagation: true,
+	eventType: "keydown",
+	enabled: true,
+	ignoreInputs: true,
+	conflictBehavior: "warn"
+};
+/**
+* Computes the default ignoreInputs value based on the hotkey.
+* Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
+*/
+function getDefaultIgnoreInputs(parsedHotkey) {
+	if (parsedHotkey.ctrl || parsedHotkey.meta) return false;
+	if (parsedHotkey.key === "Escape" || parsedHotkey.code === "Escape") return false;
+	return true;
+}
+/**
+* Handles conflicts between registrations based on conflict behavior.
+*
+* @param conflictingId - The ID of the conflicting registration
+* @param keyDisplay - Display string for the conflicting key/sequence (for error messages)
+* @param conflictBehavior - How to handle the conflict
+* @param unregister - Function to unregister by ID
+*/
+function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
+	if (conflictBehavior === "allow") return;
+	if (conflictBehavior === "warn") {
+		console.warn(`'${keyDisplay}' is already registered. Multiple handlers will be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
+		return;
+	}
+	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);
+	unregister(conflictingId);
+}
+/** Compare updates without publishing unchanged options, including fresh metadata objects. */
+function optionsEqual(left, right) {
+	const a = left;
+	const b = right;
+	const keys = Object.keys(a);
+	return keys.length === Object.keys(b).length && keys.every((key) => key === "meta" && a[key] && b[key] ? optionsEqual(a[key], b[key]) : Object.is(a[key], b[key]));
+}
+
+//#endregion
+export { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };

package/dist/conflicts.d.ts

@@ -0,0 +1,36 @@
+import { RegisterableHotkey } from "./hotkey.types.js";
+import { HotkeyRegistrationView } from "./hotkey-manager.js";
+import { SequenceRegistrationView } from "./sequence-manager.js";
+//#region src/conflicts.d.ts
+export type HotkeyConflict = {
+  type: 'hotkey';
+  registration: HotkeyRegistrationView;
+} | {
+  type: 'sequence';
+  registration: SequenceRegistrationView;
+};
+export interface HotkeyConflictOptions {
+  /** Intended registration target. Defaults to document; disjoint targets are excluded. */
+  target?: HTMLElement | Document | Window;
+  /** Check all targets instead of overlapping targets. Default: overlapping. */
+  scope?: 'overlapping' | 'all';
+  /** Intended event type. Default: keydown. */
+  eventType?: 'keydown' | 'keyup';
+  /** Include disabled registrations. Default: false. */
+  includeDisabled?: boolean;
+  /** IDs of registrations being edited. */
+  excludeIds?: ReadonlyArray<string>;
+  /** Additional app-specific exclusions, such as all instances of one action. */
+  exclude?: (registration: HotkeyRegistrationView | SequenceRegistrationView) => boolean;
+  /** Platform used to resolve Mod in the candidate. Registrations retain their own platform. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Source events allow detecting physical/logical overlap on the recorded layout. */
+  events?: ReadonlyArray<KeyboardEvent>;
+}
+/**
+ * Find equivalent bindings and sequence-prefix conflicts in the live registry.
+ * With source events, also checks observed logical/physical overlap. Does not
+ * discover unmounted handlers, external listeners, or other keyboard layouts.
+ */
+export declare function findHotkeyConflicts(candidate: RegisterableHotkey | ReadonlyArray<RegisterableHotkey>, options?: HotkeyConflictOptions): Array<HotkeyConflict>;
+//#endregion

package/dist/conflicts.js

@@ -0,0 +1,54 @@
+import { detectPlatform } from "./platform.js";
+import { keysEqual } from "./_keyboard-event.js";
+import { parseRegisterableHotkey } from "./parse.js";
+import { matchesKeyboardEvent } from "./match.js";
+import { getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { getSequenceManager } from "./sequence-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 (!("contains" in a) || !("contains" in b)) return true;
+	return a.contains(b) || b.contains(a);
+}
+/**
+* Find equivalent bindings and sequence-prefix conflicts in the live registry.
+* With source events, also checks observed logical/physical overlap. Does not
+* discover unmounted handlers, external listeners, or other keyboard layouts.
+*/
+function findHotkeyConflicts(candidate, options = {}) {
+	const steps = Array.isArray(candidate) ? candidate : [candidate];
+	if (steps.length === 0) return [];
+	const platform = options.platform ?? detectPlatform();
+	const parsed = steps.map((step) => parseRegisterableHotkey(step, platform));
+	const target = options.target ?? (typeof document === "undefined" ? void 0 : document);
+	const conflicts = [];
+	const matches = (registration, bindings) => {
+		if (!options.includeDisabled && registration.options.enabled === false || (registration.options.eventType ?? "keydown") !== (options.eventType ?? "keydown") || options.excludeIds?.includes(registration.id) || options.exclude?.(registration) || options.scope !== "all" && target && !targetsOverlap(target, registration.target)) return false;
+		return parsed.slice(0, Math.min(parsed.length, bindings.length)).every((a, index) => {
+			const b = parseRegisterableHotkey(bindings[index], registration.options.platform);
+			const same = a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : keysEqual(a.key, b.key));
+			const event = options.events?.[index];
+			return same || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
+		});
+	};
+	for (const registration of getHotkeyManager().registrations.state.values()) if (matches(registration, [registration.hotkey])) conflicts.push({
+		type: "hotkey",
+		registration: toHotkeyRegistrationView(registration)
+	});
+	for (const registration of getSequenceManager().registrations.state.values()) if (matches(registration, registration.sequence)) conflicts.push({
+		type: "sequence",
+		registration
+	});
+	return conflicts;
+}
+
+//#endregion
+export { findHotkeyConflicts };