@tanstack/hotkeys 0.21.0 → 0.22.1

package/dist/_keyboard-event.js

@@ -22,7 +22,7 @@ function normalizeKeyboardEvent(event, platform) {
 		meta: Boolean(event.metaKey),
 		altGraph: altGraph && !controlAlt,
 		location: event.location,
-		isComposing: Boolean(event.isComposing) || key === "Process" || key === "Unidentified"
+		isComposing: Boolean(event.isComposing) || event.keyCode === 229 || key === "Process" || key === "Unidentified"
 	};
 }
 /**
@@ -93,10 +93,15 @@ function isAsciiLetter(key) {
 function isLatinLetter(key) {
 	return /^\p{Script_Extensions=Latin}$/u.test(key);
 }
+let collator;
 /** 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;
+	if (left === right) return true;
+	if (/^\p{Letter}$/u.test(left) && /^\p{Letter}$/u.test(right)) {
+		collator ??= new Intl.Collator(void 0, { sensitivity: "accent" });
+		return collator.compare(left, right) === 0;
+	}
+	return false;
 }
 /** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */
 function assertLogicalKey(key) {

package/dist/_match.js

@@ -11,7 +11,7 @@ function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 		matched: false,
 		score: 0
 	};
-	if (normalized.isComposing && (parsed.code !== void 0 || isPrintableKey(parsed.key))) return noMatch;
+	if (normalized.isComposing) return noMatch;
 	if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch;
 	if (normalized.altGraph && !altGraphTypedCharacter(normalized)) return noMatch;
 	if (parsed.code !== void 0) {

package/dist/_registration.js

@@ -44,7 +44,7 @@ function withDefaults(defaults, options) {
 }
 /** Whether a parsed chord has a key. An empty one would match key-less events. */
 function chordHasKey(chord) {
-	return chord.code !== void 0 || !!chord.key;
+	return !!(chord.code || chord.key);
 }
 /**
 * Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).

package/dist/_target-listeners.js

@@ -9,11 +9,7 @@ var TargetListeners = class {
 	}
 	add(target, capture, id) {
 		if (typeof document === "undefined") return;
-		let phases = this.#targets.get(target);
-		if (!phases) {
-			phases = /* @__PURE__ */ new Map();
-			this.#targets.set(target, phases);
-		}
+		const phases = this.#targets.get(target) ?? /* @__PURE__ */ new Map();
 		let group = phases.get(capture);
 		if (!group) {
 			const ids = /* @__PURE__ */ new Set();
@@ -41,9 +37,10 @@ var TargetListeners = class {
 				keydown: listener("keydown"),
 				keyup: listener("keyup")
 			};
-			phases.set(capture, group);
 			target.addEventListener("keydown", group.keydown, capture);
 			target.addEventListener("keyup", group.keyup, capture);
+			phases.set(capture, group);
+			this.#targets.set(target, phases);
 		}
 		group.ids.add(id);
 	}

package/dist/adapter.d.ts

@@ -2,8 +2,8 @@ import { Store, createStore } from "./_store.js";
 import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
-import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 import { definedOptions, withDefaults } from "./_registration.js";
+import { createAppHotkeysStore } from "@tanstack/hotkeys";
 //#region src/adapter.d.ts
 /**
  * A hotkey and its callback, with optional per-binding options. Chords accept

package/dist/adapter.js

@@ -1,10 +1,6 @@
-import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeHotkey, parseHotkey } from "./parse.js";
 import { chordHasKey, defaultHotkeyOptions, definedOptions, withDefaults } from "./_registration.js";
 import { createStore } from "./_store.js";
-import { getHotkeyManager } from "./hotkey-manager.js";
-import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
-import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
+import { createAppHotkeysStore, detectPlatform, getAppHotkeyRegistrationOptions, getHotkeyManager, isAppHotkey, isHotkeySequence, normalizeHotkey, parseHotkey, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/adapter.ts
 /** Reconciles adapter registrations while retaining handles for option updates. */

package/dist/hotkey-manager.js

@@ -57,6 +57,24 @@ function chordString(chord, parsed) {
 function generateId() {
 	return `hotkey_${++registrationIdCounter}`;
 }
+/** A handle for a registration that listens for nothing. */
+function inactiveHandle(callback) {
+	let currentCallback = callback;
+	return {
+		id: generateId(),
+		unregister: () => {},
+		get callback() {
+			return currentCallback;
+		},
+		set callback(newCallback) {
+			currentCallback = newCallback;
+		},
+		setOptions: () => {},
+		get isActive() {
+			return false;
+		}
+	};
+}
 /** Defaults for a registration of the given kind. */
 function registrationDefaults(kind) {
 	return {
@@ -303,26 +321,8 @@ var HotkeyManager = class HotkeyManager {
 		this.registrations.setState((prev) => new Map(prev));
 	}
 	register(input, callback, options = {}) {
-		if (input == null) throw new Error("A hotkey is required. Skip registration when there is no hotkey.");
 		const hotkey = simplifyHotkey(input);
-		if (isHotkeySequence(hotkey) && hotkey.length === 0) throw new Error("Sequence must contain at least one hotkey");
-		if (typeof document === "undefined" && !options.target) {
-			let currentCallback = callback;
-			return {
-				id: generateId(),
-				unregister: () => {},
-				get callback() {
-					return currentCallback;
-				},
-				set callback(newCallback) {
-					currentCallback = newCallback;
-				},
-				setOptions: () => {},
-				get isActive() {
-					return false;
-				}
-			};
-		}
+		if (hotkey == null || isHotkeySequence(hotkey) && hotkey.length === 0 || typeof document === "undefined" && !options.target) return inactiveHandle(callback);
 		const id = generateId();
 		const platform = options.platform ?? this.#platform;
 		const target = options.target ?? document;
@@ -361,14 +361,14 @@ var HotkeyManager = class HotkeyManager {
 			};
 		}
 		const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
-		if (!steps.every(chordHasKey)) throw new Error(`Hotkey '${formatForMessage(registration.hotkey)}' has no key. Skip registration when there is no hotkey.`);
+		if (!steps.every(chordHasKey)) return inactiveHandle(callback);
 		if (process.env.NODE_ENV !== "production") {
 			for (const { key } of steps) if (key !== void 0 && !isKeyNameShape(key)) console.warn(`Unknown key '${key}' in '${formatForMessage(registration.hotkey)}'. Key names are case-sensitive, such as 'Escape' and 'F1', so this hotkey may never fire.`);
 		}
 		const conflicting = this.#findConflictingRegistration(registration);
 		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
-		this.registrations.setState((prev) => new Map(prev).set(id, registration));
 		this.#listeners.add(target, !!registration.options.capture, id);
+		this.registrations.setState((prev) => new Map(prev).set(id, registration));
 		const manager = this;
 		return {
 			get id() {
@@ -517,7 +517,7 @@ var HotkeyManager = class HotkeyManager {
 				this.#fire(registration, event);
 				continue;
 			}
-			if (!registration.options.requireReset || !registration.hasFired) {
+			if (!registration.options.requireReset || !registration.hasFired || !event.repeat) {
 				if (registration.options.requireReset) {
 					registration.hasFired = true;
 					registration.activeMatch = match.identity;
@@ -648,13 +648,13 @@ var HotkeyManager = class HotkeyManager {
 		};
 	}
 	/**
-	* Finds an existing registration on the same target and scope whose steps
+	* Finds an existing registration on the same target, scope, and event type whose steps
 	* resolve to the same identity. Each side keeps its own platform, so `Mod+S` on macOS
 	* and `Mod+S` on Windows are different bindings.
 	*/
 	#findConflictingRegistration(candidate) {
 		const steps = resolvedSteps(candidate);
-		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && registration.options.scope === candidate.options.scope && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
+		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && registration.options.scope === candidate.options.scope && registration.options.eventType === candidate.options.eventType && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
 		return null;
 	}
 	/**

package/dist/index.d.ts

@@ -13,4 +13,5 @@ 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, 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 };
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.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, 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, createAppHotkeysStore, 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/dist/index.js

@@ -8,8 +8,9 @@ import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, cr
 import { matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { findHotkeyConflicts } from "./conflicts.js";
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 import { AppHotkeysStore, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorder } from "./hotkey-recorder.js";
 
-export { ALL_KEYS, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, 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, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, 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/dist/key-state-tracker.js

@@ -100,11 +100,14 @@ var KeyStateTracker = class KeyStateTracker {
 				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#reconcileModifiers(event);
-			if (MODIFIER_KEYS.has(key)) {
-				for (const [entryIdentity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
-			}
+			if (MODIFIER_KEYS.has(key)) this.#releaseNonModifiers();
 			this.#syncState();
 		};
+		const onContextMenu = (event) => {
+			if (event.defaultPrevented || !event.isTrusted) return;
+			const reconciled = this.#reconcileModifiers(event);
+			if (this.#releaseNonModifiers() || reconciled) this.#syncState();
+		};
 		const onMouse = (event) => {
 			if (this.#reconcileModifiers(event)) this.#syncState();
 		};
@@ -139,6 +142,16 @@ var KeyStateTracker = class KeyStateTracker {
 				"blur",
 				onBlur,
 				false
+			],
+			[
+				"contextmenu",
+				onContextMenu,
+				false
+			],
+			[
+				"visibilitychange",
+				() => document.hidden && onBlur(),
+				false
 			]
 		];
 		for (const [type, listener, capture] of this.#listeners) window.addEventListener(type, listener, capture);
@@ -159,6 +172,15 @@ var KeyStateTracker = class KeyStateTracker {
 		}
 		return changed;
 	}
+	/** Forgets every held key that isn't a modifier. Returns whether any was held. */
+	#releaseNonModifiers() {
+		let changed = false;
+		for (const [identity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) {
+			this.#heldEntries.delete(identity);
+			changed = true;
+		}
+		return changed;
+	}
 	/**
 	* Syncs the internal Set to the Store state.
 	*/

package/dist/validate.d.ts

@@ -50,9 +50,13 @@ export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
  *
  * @example
  * ```ts
- * checkHotkey('Alt+C')
- * // Console: Warning: Alt+C may not work reliably on macOS...
+ * checkHotkey('Control+escape')
+ * // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
  * // Returns: true
+ *
+ * checkHotkey('Ctl+K')
+ * // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+ * // Returns: false
  * ```
  */
 export declare function checkHotkey(hotkey: ValidatableHotkey): boolean;

package/dist/validate.js

@@ -94,9 +94,13 @@ function assertValidHotkey(hotkey) {
 *
 * @example
 * ```ts
-* checkHotkey('Alt+C')
-* // Console: Warning: Alt+C may not work reliably on macOS...
+* checkHotkey('Control+escape')
+* // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
 * // Returns: true
+*
+* checkHotkey('Ctl+K')
+* // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+* // Returns: false
 * ```
 */
 function checkHotkey(hotkey) {

package/package.json

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

package/skills/hotkeys-core/SKILL.md

@@ -50,7 +50,7 @@ Use the first mechanism that fits:
 1. **Lifetime.** A hotkey registered in a component exists while that component is mounted. A dialog's `Escape` belongs in the dialog.
 2. **`enabled`.** A condition inside a mounted component.
 3. **Scope.** A group that turns on and off together, such as a dialog, pane, or tab. An `exclusive` scope suspends every other scope, including global hotkeys, while it is active.
-4. **`target`.** Only while focus is inside one element, which must be focusable (`tabindex="0"`).
+4. **`target`.** Only while focus is on one element or inside it. If nothing there can take focus, give the element `tabindex="0"`.
 
 When nesting scopes, stacking dialogs, or keeping some hotkeys working during an exclusive scope, read [scopes](references/scopes.md).
 

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

@@ -4,4 +4,4 @@
 - **Reset between tests.** Call `HotkeyManager.resetInstance()`, plus `KeyStateTracker.resetInstance()` for held-key tests, in `afterEach`. Registrations and scope activations otherwise outlive a test that fails before unmounting.
 - **Dispatch real events.** Use `new KeyboardEvent('keydown', { key: 's', code: 'KeyS', metaKey: true, bubbles: true, cancelable: true })`. Physical bindings such as `[KeyS]` match only `code`. Check `event.defaultPrevented` to assert the browser action was blocked.
 - **Dispatch where focus is.** For a hotkey with a `target`, or to test typing in a field, focus the element and dispatch on it with `bubbles: true`.
-- **Repeats and sequences.** `repeat: true` simulates holding a key; it fires chords again unless they set `requireReset`, and it never advances a sequence. Use fake timers to test a sequence's `timeout` (1000 ms by default).
+- **Repeats and sequences.** `repeat: true` simulates holding a key; it fires chords again unless they set `requireReset`, and it never advances a sequence. A keydown without `repeat` is a new press, so it fires a `requireReset` chord even without a keyup in between. Use fake timers to test a sequence's `timeout` (1000 ms by default).