@tanstack/hotkeys 0.11.0 → 0.12.0

package/dist/index.js

@@ -1,16 +1,15 @@
 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";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
-import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
+import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
+import { formatForDisplay, formatHotkey } from "./format.js";
 import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-import { areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
 import { matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
 import { findHotkeyConflicts } from "./conflicts.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";
-import { HotkeySequenceRecorder } from "./hotkey-sequence-recorder.js";
 
-export { ALL_KEYS, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, HotkeySequenceRecorder, 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, SequenceManager, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, resolveModifier, 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, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, provideAppHotkeys, publishAppHotkeysStore, rawHotkeyToParsedHotkey, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/match.d.ts

@@ -1,4 +1,4 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
+import { HotkeyCallback, HotkeyChord, HotkeySequence, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 //#region src/match.d.ts
 export interface KeyboardEventMatch {
   matched: boolean;
@@ -38,7 +38,7 @@ export interface KeyboardEventMatch {
  * })
  * ```
  */
-export declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: Hotkey | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
+export declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: HotkeyChord | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
 /**
  * Options for creating a hotkey handler.
  */
@@ -68,8 +68,8 @@ export interface CreateHotkeyHandlerOptions {
  * document.addEventListener('keydown', handler)
  * ```
  */
-export declare function createHotkeyHandler(hotkey: Hotkey | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
-export type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback; };
+export declare function createHotkeyHandler(hotkey: HotkeyChord | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+export type MultiHotkeyHandler = { [K in HotkeyChord]?: HotkeyCallback; };
 /**
  * Creates a handler that matches multiple hotkeys.
  *
@@ -90,9 +90,42 @@ export type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback; };
  */
 export declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
 /**
- * Compares normalized binding identity, including all four modifiers.
+ * Compares normalized hotkey identity, including all four modifiers.
+ * Sequences are equal when every step is equal; a one-step sequence equals its chord.
  * Aliases resolve on the supplied platform. A physical code and a logical key
  * remain distinct even when one keyboard event could match both.
  */
 export declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): boolean;
+/** Default timeout between sequence steps (in milliseconds). */
+export declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
+/**
+ * Creates a simple sequence matcher for one-off use.
+ *
+ * This is a low-level helper that does not support ignoreInputs, target,
+ * or other HotkeyOptions. Callers must handle input filtering themselves
+ * if attaching to document.
+ *
+ * @param sequence - The sequence of hotkeys to match
+ * @param options - Options including timeout
+ * @returns An object with match() and reset() methods
+ *
+ * @example
+ * ```ts
+ * const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })
+ *
+ * document.addEventListener('keydown', (event) => {
+ *   if (matcher.match(event)) {
+ *     console.log('Sequence matched!')
+ *   }
+ * })
+ * ```
+ */
+export declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
+  timeout?: number;
+  platform?: 'mac' | 'windows' | 'linux';
+}): {
+  match: (event: KeyboardEvent) => boolean;
+  reset: () => void;
+  getProgress: () => number;
+};
 //#endregion

package/dist/match.js

@@ -1,6 +1,7 @@
+import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { keysEqual } from "./_keyboard-event.js";
-import { parseHotkey, parseRegisterableHotkey } from "./parse.js";
+import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isHotkeySequence, isModifierKey, parseHotkey, parseRegisterableHotkey } from "./parse.js";
 import { matchKeyboardEvent } from "./_match.js";
 
 //#region src/match.ts
@@ -126,15 +127,82 @@ function formatParsedHotkey(parsed) {
 	return parts.join("+");
 }
 /**
-* Compares normalized binding identity, including all four modifiers.
+* Compares normalized hotkey identity, including all four modifiers.
+* Sequences are equal when every step is equal; a one-step sequence equals its chord.
 * Aliases resolve on the supplied platform. A physical code and a logical key
 * remain distinct even when one keyboard event could match both.
 */
 function areHotkeysEqual(left, right, platform = detectPlatform()) {
+	const a = isHotkeySequence(left) ? left : [left];
+	const b = isHotkeySequence(right) ? right : [right];
+	return a.length === b.length && a.every((step, index) => areChordsEqual(step, b[index], platform));
+}
+function areChordsEqual(left, right, platform) {
 	const a = parseRegisterableHotkey(left, platform);
 	const b = parseRegisterableHotkey(right, platform);
 	return 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));
 }
+/** Default timeout between sequence steps (in milliseconds). */
+const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
+/**
+* Creates a simple sequence matcher for one-off use.
+*
+* This is a low-level helper that does not support ignoreInputs, target,
+* or other HotkeyOptions. Callers must handle input filtering themselves
+* if attaching to document.
+*
+* @param sequence - The sequence of hotkeys to match
+* @param options - Options including timeout
+* @returns An object with match() and reset() methods
+*
+* @example
+* ```ts
+* const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })
+*
+* document.addEventListener('keydown', (event) => {
+*   if (matcher.match(event)) {
+*     console.log('Sequence matched!')
+*   }
+* })
+* ```
+*/
+function createSequenceMatcher(sequence, options = {}) {
+	const platform = options.platform ?? detectPlatform();
+	const timeout = options.timeout ?? 1e3;
+	const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform));
+	let currentIndex = 0;
+	let lastKeyTime = 0;
+	return {
+		match(event) {
+			if (event.type === "keydown" && event.repeat || normalizeKeyboardEvent(event, platform).isComposing || isModifierKey(normalizeKeyName(event.key))) return false;
+			const now = Date.now();
+			if (currentIndex > 0 && now - lastKeyTime > timeout) currentIndex = 0;
+			const expected = parsedSequence[currentIndex];
+			if (!expected) return false;
+			if (matchesKeyboardEvent(event, expected, platform)) {
+				lastKeyTime = now;
+				currentIndex++;
+				if (currentIndex >= parsedSequence.length) {
+					currentIndex = 0;
+					return true;
+				}
+			} else if (currentIndex > 0) {
+				if (matchesKeyboardEvent(event, parsedSequence[0], platform)) {
+					currentIndex = 1;
+					lastKeyTime = now;
+				} else currentIndex = 0;
+			}
+			return false;
+		},
+		reset() {
+			currentIndex = 0;
+			lastKeyTime = 0;
+		},
+		getProgress() {
+			return currentIndex;
+		}
+	};
+}
 
 //#endregion
-export { areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+export { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, matchesKeyboardEvent };

package/dist/parse.d.ts

@@ -1,7 +1,17 @@
 import { Key } from "./key.types.js";
-import { Hotkey, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.types.js";
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkey, RawHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
 import { MODIFIER_ALIASES } from "./constants.js";
 //#region src/parse.d.ts
+/**
+ * Whether a hotkey is a sequence. Use this instead of `Array.isArray`, which
+ * does not narrow readonly arrays.
+ */
+export declare function isHotkeySequence(hotkey: RegisterableHotkey): hotkey is HotkeySequence;
+/**
+ * Collapses a one-step sequence to its chord without otherwise changing the hotkey.
+ * Registration APIs treat `['Mod+S']` exactly like `'Mod+S'`.
+ */
+export declare function simplifyHotkey<T extends RegisterableHotkey>(hotkey: T): T extends HotkeySequence ? Hotkey : T;
 /**
  * Parses a hotkey string into its component parts.
  *
@@ -16,7 +26,7 @@ import { MODIFIER_ALIASES } from "./constants.js";
  * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
  * ```
  */
-export declare function parseHotkey(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+export declare function parseHotkey(hotkey: HotkeyChord | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
 /**
  * Converts a RawHotkey object to a ParsedHotkey.
  * Optional modifier booleans default to false; modifiers array is derived from them.
@@ -59,15 +69,17 @@ export declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac'
  * normalizeHotkey('esc') // 'Escape'
  * ```
  */
-export declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
 /**
  * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
  */
-export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
 /**
- * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+ * Normalizes a chord (string or {@link RawHotkey} object) or a sequence to canonical form.
+ * Each sequence step is normalized, and a one-step sequence becomes its chord.
  * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
  */
+export declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkeyChord, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
 export declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Checks if a string is a recognized modifier token (including aliases).
@@ -104,7 +116,7 @@ export declare function parseKeyboardEvent(event: KeyboardEvent, platform?: 'mac
  * @param event - The keyboard event (typically `keydown`)
  * @param platform - Target platform for `Mod` eligibility
  */
-export declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
 /**
  * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
  *
@@ -122,10 +134,10 @@ export declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?
  * hasNonModifierKey(parseHotkey('Mod+A')) // true
  * ```
  */
-export declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
+export declare function hasNonModifierKey(hotkey: HotkeyChord | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
 /**
  * Parses a string or raw binding, resolving Mod for the supplied platform.
  * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
  */
-export declare function parseRegisterableHotkey(hotkey: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): ParsedHotkey;
+export declare function parseRegisterableHotkey(hotkey: RegisterableHotkeyChord, platform?: "mac" | "windows" | "linux"): ParsedHotkey;
 //#endregion

package/dist/parse.js

@@ -4,6 +4,16 @@ import { assertLogicalKey, normalizeKeyboardEvent, splitHotkeyParts } from "./_k
 
 //#region src/parse.ts
 /**
+* Whether a hotkey is a sequence. Use this instead of `Array.isArray`, which
+* does not narrow readonly arrays.
+*/
+function isHotkeySequence(hotkey) {
+	return Array.isArray(hotkey);
+}
+function simplifyHotkey(hotkey) {
+	return isHotkeySequence(hotkey) && hotkey.length === 1 ? hotkey[0] : hotkey;
+}
+/**
 * Parses a hotkey string into its component parts.
 *
 * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
@@ -138,11 +148,11 @@ function normalizeHotkey(hotkey, platform = detectPlatform()) {
 function normalizeHotkeyFromParsed(parsed, platform = detectPlatform()) {
 	return normalizedHotkeyStringFromParsed(parsed, platform);
 }
-/**
-* Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
-* Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
-*/
 function normalizeRegisterableHotkey(hotkey, platform = detectPlatform()) {
+	if (isHotkeySequence(hotkey)) {
+		const steps = hotkey.map((step) => normalizeHotkey(step, platform));
+		return steps.length === 1 ? steps[0] : steps;
+	}
 	return typeof hotkey === "string" ? normalizeHotkey(hotkey, platform) : normalizeHotkeyFromParsed(rawHotkeyToParsedHotkey(hotkey, platform), platform);
 }
 /**
@@ -234,4 +244,4 @@ function parseRegisterableHotkey(hotkey, platform = detectPlatform()) {
 }
 
 //#endregion
-export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, simplifyHotkey };

package/dist/recorder-options.d.ts

@@ -6,8 +6,8 @@ export type RecorderKeyMode = 'code' | 'key';
 export interface RecorderRejection {
   reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation';
   message: string;
+  /** The rejected chord or sequence, when one was recorded. */
   hotkey?: Hotkey;
-  sequence?: Array<Hotkey>;
   conflicts?: Array<HotkeyConflict>;
 }
 export interface RecorderOptions {
@@ -20,12 +20,15 @@ export interface RecorderOptions {
   /** Rejected candidates leave recording active. */
   onReject?: (rejection: RecorderRejection) => void;
 }
+/** Validation context for a recorded chord or sequence. */
 export interface HotkeyRecorderValidationContext {
+  /** The event that recorded the last chord. */
   event: KeyboardEvent;
+  /** The last chord, parsed. */
   parsedHotkey: ParsedHotkey;
-}
-export interface HotkeySequenceRecorderValidationContext {
+  /** The event that recorded each step. */
   events: ReadonlyArray<KeyboardEvent>;
+  /** Every step, parsed. */
   parsedSequence: ReadonlyArray<ParsedHotkey>;
 }
 //#endregion

package/dist/validate.d.ts

@@ -1,7 +1,10 @@
 import { Hotkey } from "./hotkey.types.js";
 //#region src/validate.d.ts
+/** A hotkey to validate: a chord string, a sequence, or untyped input such as saved data. */
+export type ValidatableHotkey = Hotkey | (string & {}) | ReadonlyArray<string>;
 /**
- * Validates a hotkey string and returns any warnings or errors.
+ * Validates a hotkey and returns any warnings or errors.
+ * Sequences are validated step by step, and messages name the failing step.
  *
  * Checks for:
  * - Valid syntax (modifier+...+key format)
@@ -18,9 +21,12 @@ import { Hotkey } from "./hotkey.types.js";
  *
  * validateHotkey('')
  * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+ *
+ * validateHotkey(['G', 'Foo+H'])
+ * // { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
  * ```
  */
-export declare function validateHotkey(hotkey: Hotkey | (string & {})): ValidationResult;
+export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationResult;
 /**
  * Validates a hotkey and throws an error if invalid.
  * Useful for development-time validation.
@@ -34,7 +40,7 @@ export declare function validateHotkey(hotkey: Hotkey | (string & {})): Validati
  * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
  * ```
  */
-export declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
+export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
 /**
  * Validates a hotkey and logs warnings to the console.
  * Useful for development-time feedback.
@@ -49,7 +55,7 @@ export declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
  * // Returns: true
  * ```
  */
-export declare function checkHotkey(hotkey: Hotkey | (string & {})): boolean;
+export declare function checkHotkey(hotkey: ValidatableHotkey): boolean;
 /**
  * Result of validating a hotkey string.
  */

package/dist/validate.js

@@ -3,7 +3,8 @@ import { splitHotkeyParts } from "./_keyboard-event.js";
 
 //#region src/validate.ts
 /**
-* Validates a hotkey string and returns any warnings or errors.
+* Validates a hotkey and returns any warnings or errors.
+* Sequences are validated step by step, and messages name the failing step.
 *
 * Checks for:
 * - Valid syntax (modifier+...+key format)
@@ -20,9 +21,30 @@ import { splitHotkeyParts } from "./_keyboard-event.js";
 *
 * validateHotkey('')
 * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+*
+* validateHotkey(['G', 'Foo+H'])
+* // { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
 * ```
 */
 function validateHotkey(hotkey) {
+	if (typeof hotkey !== "string") {
+		if (hotkey.length === 0) return {
+			valid: false,
+			warnings: [],
+			errors: ["Sequence cannot be empty"]
+		};
+		if (hotkey.length === 1) return validateChord(hotkey[0]);
+		const results = hotkey.map(validateChord);
+		const prefixed = (key) => results.flatMap((result, i) => result[key].map((message) => `Step ${i + 1}: ${message}`));
+		return {
+			valid: results.every((result) => result.valid),
+			warnings: prefixed("warnings"),
+			errors: prefixed("errors")
+		};
+	}
+	return validateChord(hotkey);
+}
+function validateChord(hotkey) {
 	const warnings = [];
 	const errors = [];
 	if (!hotkey || hotkey.trim() === "") return {
@@ -82,7 +104,7 @@ function isKnownKey(key) {
 */
 function assertValidHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (!result.valid) throw new Error(`Invalid hotkey '${hotkey}': ${result.errors.join(", ")}`);
+	if (!result.valid) throw new Error(`Invalid hotkey '${String(hotkey)}': ${result.errors.join(", ")}`);
 }
 /**
 * Validates a hotkey and logs warnings to the console.
@@ -100,8 +122,8 @@ function assertValidHotkey(hotkey) {
 */
 function checkHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (result.errors.length > 0) console.error(`Hotkey '${hotkey}' errors:`, result.errors.join("; "));
-	if (result.warnings.length > 0) console.warn(`Hotkey '${hotkey}' warnings:`, result.warnings.join("; "));
+	if (result.errors.length > 0) console.error(`Hotkey '${String(hotkey)}' errors:`, result.errors.join("; "));
+	if (result.warnings.length > 0) console.warn(`Hotkey '${String(hotkey)}' warnings:`, result.warnings.join("; "));
 	return result.valid;
 }
 

package/package.json

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

package/dist/hotkey-sequence-recorder.d.ts

@@ -1,84 +0,0 @@
-import { HotkeySequence } from "./sequence-manager.js";
-import { HotkeySequenceRecorderValidationContext, RecorderOptions } from "./recorder-options.js";
-import { Store } from "@tanstack/store";
-//#region src/hotkey-sequence-recorder.d.ts
-/**
- * How the user can commit a recorded sequence from the keyboard.
- * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.
- * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).
- */
-export type HotkeySequenceRecorderCommitKeys = 'enter' | 'none';
-/**
- * State interface for the HotkeySequenceRecorder.
- */
-export interface HotkeySequenceRecorderState {
-  /** Whether recording is currently active */
-  isRecording: boolean;
-  /** Chords captured so far in the current recording session */
-  steps: HotkeySequence;
-  /** The last successfully committed sequence, or null if none / after starting a new session */
-  recordedSequence: HotkeySequence | null;
-}
-/**
- * Options for configuring a HotkeySequenceRecorder instance.
- */
-export interface HotkeySequenceRecorderOptions extends RecorderOptions {
-  /** Validate the completed sequence. Rejection preserves the steps for editing. */
-  validate?: (sequence: HotkeySequence, context: HotkeySequenceRecorderValidationContext) => boolean | string;
-  /** Callback when a sequence is successfully recorded */
-  onRecord: (sequence: HotkeySequence) => void;
-  /** Optional callback when recording is cancelled (Escape pressed) */
-  onCancel?: () => void;
-  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */
-  onClear?: () => void;
-  /**
-   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.
-   * @default true
-   */
-  commitOnEnter?: boolean;
-  /**
-   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).
-   * @default 'enter'
-   */
-  commitKeys?: HotkeySequenceRecorderCommitKeys;
-  /**
-   * Milliseconds of inactivity after the **last completed chord** before auto-committing.
-   * The timer does not run while waiting for the first chord (`steps.length === 0`).
-   */
-  idleTimeoutMs?: number;
-  /**
-   * Whether to ignore keyboard events from input-like elements (text inputs,
-   * textarea, select, contenteditable). When true, typing in inputs passes
-   * through normally instead of being captured as a sequence recording.
-   * Escape always works regardless of this setting.
-   * @default true
-   */
-  ignoreInputs?: boolean;
-}
-/**
- * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
- *
- * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
- * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
- * **Backspace/Delete** to remove the last step or clear when empty.
- */
-export declare class HotkeySequenceRecorder {
-  #private;
-  readonly store: Store<HotkeySequenceRecorderState>;
-  /** Options may be a getter to read current configuration during an active session. */
-  constructor(options: HotkeySequenceRecorderOptions | (() => HotkeySequenceRecorderOptions));
-  /** Merges current callbacks and options without discarding recorded steps. */
-  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
-  /** Starts a fresh recording; repeated starts during an active session are ignored. */
-  start(): void;
-  /**
-   * Commit the current steps as a sequence. No-op if fewer than one step.
-   */
-  commit(): void;
-  /** Stops and discards in-progress steps without invoking onCancel. */
-  stop(): void;
-  /** Stops, discards in-progress steps, and notifies onCancel. */
-  cancel(): void;
-  destroy(): void;
-}
-//#endregion