@tanstack/hotkeys 0.15.0 → 0.16.0

package/dist/parse.d.ts

@@ -1,56 +1,42 @@
 import { Key } from "./key.types.js";
-import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkey, RawHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
-import { MODIFIER_ALIASES } from "./constants.js";
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 //#region src/parse.d.ts
+type Platform = 'mac' | 'windows' | 'linux';
+/** A chord in any form: a string, a chord object, or an already-parsed chord. */
+type AnyChord = RegisterableHotkeyChord | ParsedHotkeyChord | (string & {});
 /**
  * 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;
+export declare function isHotkeySequence<T extends RegisterableHotkey>(hotkey: T): hotkey is Extract<T, ReadonlyArray<unknown>>;
 /**
  * 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;
+export declare function simplifyHotkey<T extends RegisterableHotkey>(hotkey: T): T extends HotkeySequence ? Hotkey : T extends RegisterableHotkeySequence ? RegisterableHotkey : T;
 /**
- * Parses a hotkey string into its component parts.
+ * Parses a hotkey, resolving `Mod` for the platform. A chord, written as a
+ * string or an object, returns one parsed chord. A sequence returns one
+ * parsed chord per step. Physical tokens such as `[KeyQ]` keep `code`; they
+ * never become a logical Q.
  *
- * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
+ * @param hotkey - A chord string such as `'Mod+S'`, a chord object, or a sequence
  * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns A ParsedHotkey with either logical key or physical code and modifier flags
  *
  * @example
  * ```ts
- * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
- * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
- * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * parseHotkey('Mod+S', 'mac') // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ * parseHotkey({ key: 'S', mod: true }, 'windows') // { key: 'S', ctrl: true, ..., modifiers: ['Control'] }
+ * parseHotkey(['G', 'Shift+G']) // [{ key: 'G', ... }, { key: 'G', shift: true, ... }]
  * ```
  */
-export declare function parseHotkey(hotkey: HotkeyChord | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+export declare function parseHotkey(hotkey: AnyChord, platform?: Platform): ParsedHotkeyChord;
+export declare function parseHotkey(hotkey: ReadonlyArray<AnyChord>, platform?: Platform): Array<ParsedHotkeyChord>;
+export declare function parseHotkey(hotkey: AnyChord | ReadonlyArray<AnyChord>, platform?: Platform): ParsedHotkeyChord | Array<ParsedHotkeyChord>;
 /**
- * Converts a RawHotkey object to a ParsedHotkey.
- * Optional modifier booleans default to false; modifiers array is derived from them.
- * When `mod` is true, it is resolved to Control or Meta based on platform.
- *
- * @param raw - The raw hotkey object
- * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns A ParsedHotkey suitable for matching and formatting
- *
- * @example
- * ```ts
- * rawHotkeyToParsedHotkey({ key: 'Escape' })
- * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
- *
- * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
- * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
- *
- * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
- * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
- * ```
- */
-export declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
-/**
- * Normalizes a hotkey string to its canonical form.
+ * Normalizes a hotkey to its canonical string form. Accepts a chord string, a
+ * chord object, a parsed chord, or a sequence of any of these. Each sequence
+ * step is normalized, and a one-step sequence becomes its chord.
  *
  * - When `Mod` is allowed for the platform (Command on Mac without Control;
  *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
@@ -58,29 +44,20 @@ export declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac'
  * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
  * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
  *
- * @param hotkey - The hotkey string to normalize
+ * @param hotkey - The hotkey to normalize
  * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
- * @returns The normalized hotkey string
  *
  * @example
  * ```ts
  * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
  * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
- * normalizeHotkey('esc') // 'Escape'
+ * normalizeHotkey({ key: 's', mod: true }) // 'Mod+S'
+ * normalizeHotkey(['g', 'shift+g']) // ['G', 'Shift+G']
+ * normalizeHotkey(parseKeyboardEvent(event)) // The chord the event pressed
  * ```
  */
-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'): HotkeyChord;
-/**
- * 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;
+export declare function normalizeHotkey(hotkey: AnyChord, platform?: Platform): HotkeyChord;
+export declare function normalizeHotkey(hotkey: AnyChord | ReadonlyArray<AnyChord>, platform?: Platform): Hotkey;
 /**
  * Checks if a string is a recognized modifier token (including aliases).
  *
@@ -90,16 +67,14 @@ export declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey,
  * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-export declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
+export declare function isModifierKey(key: Key | (string & {})): boolean;
 /**
- * Parses a KeyboardEvent into a ParsedHotkey object.
- *
- * This function extracts the key and modifier state from a keyboard event
- * and converts it into the same format used by `parseHotkey()`.
+ * Parses a KeyboardEvent into the chord it pressed, in the same format as
+ * `parseHotkey()`. Pass the result to `normalizeHotkey` for its canonical string.
  *
  * @param event - The KeyboardEvent to parse
  * @param platform - The target platform for resolving modifiers (defaults to auto-detection)
- * @returns A ParsedHotkey object representing the keyboard event
+ * @returns The parsed chord for the keyboard event
  *
  * @example
  * ```ts
@@ -109,23 +84,16 @@ export declare function isModifierKey(key: Key | (string & {})): key is keyof ty
  * })
  * ```
  */
-export declare function parseKeyboardEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+export declare function parseKeyboardEvent(event: KeyboardEvent, platform?: Platform): ParsedHotkeyChord;
 /**
- * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
+ * Checks if a chord contains at least one non-modifier key.
  *
- * @param event - The keyboard event (typically `keydown`)
- * @param platform - Target platform for `Mod` eligibility
- */
-export declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
-/**
- * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
- *
- * This is useful for validating that a recorded hotkey is complete and not
+ * This is useful for validating that a recorded chord is complete and not
  * just a combination of modifiers without an action key.
  *
- * @param hotkey - The hotkey string or ParsedHotkey to check
+ * @param chord - The chord string or parsed chord to check
  * @param platform - The target platform for parsing (defaults to auto-detection)
- * @returns True if the hotkey contains at least one non-modifier key
+ * @returns True if the chord contains at least one non-modifier key
  *
  * @example
  * ```ts
@@ -134,10 +102,5 @@ export declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?
  * hasNonModifierKey(parseHotkey('Mod+A')) // true
  * ```
  */
-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: RegisterableHotkeyChord, platform?: "mac" | "windows" | "linux"): ParsedHotkey;
+export declare function hasNonModifierKey(chord: HotkeyChord | ParsedHotkeyChord | (string & {}), platform?: Platform): boolean;
 //#endregion

package/dist/parse.js

@@ -1,8 +1,25 @@
-import { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
+import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { assertLogicalKey, normalizeKeyboardEvent, splitHotkeyParts } from "./_keyboard-event.js";
+import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
 //#region src/parse.ts
+/** Builds a ParsedHotkeyChord, listing held modifiers in canonical order. */
+function toParsedChord(identity, ctrl, shift, alt, meta) {
+	const held = {
+		Control: ctrl,
+		Alt: alt,
+		Shift: shift,
+		Meta: meta
+	};
+	return {
+		...identity,
+		ctrl,
+		shift,
+		alt,
+		meta,
+		modifiers: MODIFIER_ORDER.filter((modifier) => held[modifier])
+	};
+}
 /**
 * Whether a hotkey is a sequence. Use this instead of `Array.isArray`, which
 * does not narrow readonly arrays.
@@ -13,29 +30,15 @@ function isHotkeySequence(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')
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey with either logical key or physical code and modifier flags
-*
-* @example
-* ```ts
-* parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
-* parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
-* parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
-* ```
-*/
-function parseHotkey(hotkey, platform = detectPlatform()) {
-	const parts = splitHotkeyParts(hotkey);
+function parseChordString(chord, platform) {
+	const parts = splitChordParts(chord);
 	const modifiers = /* @__PURE__ */ new Set();
 	let key = "";
 	for (let i = 0; i < parts.length; i++) {
 		const part = parts[i].trim();
 		if (i === parts.length - 1) key = normalizeKeyName(part);
 		else {
-			const alias = MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()];
+			const alias = modifierAlias(part);
 			if (alias) {
 				const resolved = resolveModifier(alias, platform);
 				modifiers.add(resolved);
@@ -43,71 +46,31 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 		}
 	}
 	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
-	const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(key)?.[1];
-	return {
-		...code !== void 0 ? { code } : { key },
-		ctrl: modifiers.has("Control"),
-		shift: modifiers.has("Shift"),
-		alt: modifiers.has("Alt"),
-		meta: modifiers.has("Meta"),
-		modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m))
-	};
+	const code = physicalCodeOf(key);
+	return toParsedChord(code !== void 0 ? { code } : { key }, modifiers.has("Control"), modifiers.has("Shift"), modifiers.has("Alt"), modifiers.has("Meta"));
 }
-/**
-* Converts a RawHotkey object to a ParsedHotkey.
-* Optional modifier booleans default to false; modifiers array is derived from them.
-* When `mod` is true, it is resolved to Control or Meta based on platform.
-*
-* @param raw - The raw hotkey object
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey suitable for matching and formatting
-*
-* @example
-* ```ts
-* rawHotkeyToParsedHotkey({ key: 'Escape' })
-* // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
-*
-* rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
-* // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
-*
-* rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
-* // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
-* ```
-*/
-function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
-	if (raw.code === void 0) assertLogicalKey(raw.key);
-	let ctrl = raw.ctrl ?? false;
-	const shift = raw.shift ?? false;
-	const alt = raw.alt ?? false;
-	let meta = raw.meta ?? false;
-	if (raw.mod) {
+/** Resolves a chord object's modifiers. Omitted modifiers are false. */
+function parseChordObject(chord, platform) {
+	if (chord.code === void 0) assertLogicalKey(chord.key);
+	let ctrl = chord.ctrl ?? false;
+	const shift = chord.shift ?? false;
+	const alt = chord.alt ?? false;
+	let meta = chord.meta ?? false;
+	if (chord.mod) {
 		if (resolveModifier("Mod", platform) === "Control") ctrl = true;
 		else meta = true;
 	}
-	const modifiers = MODIFIER_ORDER.filter((m) => {
-		switch (m) {
-			case "Control": return ctrl;
-			case "Shift": return shift;
-			case "Alt": return alt;
-			case "Meta": return meta;
-			default: return false;
-		}
-	});
-	return {
-		...raw.code !== void 0 ? { code: raw.code } : { key: normalizeKeyName(raw.key) },
-		ctrl,
-		shift,
-		alt,
-		meta,
-		modifiers
-	};
+	return toParsedChord(chord.code !== void 0 ? { code: chord.code } : { key: normalizeKeyName(chord.key) }, ctrl, shift, alt, meta);
+}
+function parseChord(chord, platform) {
+	return typeof chord === "string" ? parseChordString(chord, platform) : parseChordObject(chord, platform);
 }
 /**
-* Serializes a parsed hotkey to the canonical string form used for registration
-* and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;
-* otherwise full `Control+Alt+Shift+Meta` order.
+* The canonical string for a parsed chord: `Mod` first when the platform
+* allows, then `Alt`, then `Shift`; otherwise full `Control+Alt+Shift+Meta`
+* order.
 */
-function normalizedHotkeyStringFromParsed(parsed, platform) {
+function normalizeParsedChord(parsed, platform) {
 	if (parsed.code === void 0) assertLogicalKey(parsed.key);
 	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
 	const parts = [];
@@ -119,41 +82,15 @@ function normalizedHotkeyStringFromParsed(parsed, platform) {
 	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : normalizeKeyName(parsed.key));
 	return parts.join("+");
 }
-/**
-* Normalizes a hotkey string to its canonical form.
-*
-* - When `Mod` is allowed for the platform (Command on Mac without Control;
-*   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
-*   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
-* - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
-* - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
-*
-* @param hotkey - The hotkey string to normalize
-* @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
-* @returns The normalized hotkey string
-*
-* @example
-* ```ts
-* normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
-* normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
-* normalizeHotkey('esc') // 'Escape'
-* ```
-*/
-function normalizeHotkey(hotkey, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseHotkey(hotkey, platform), platform);
-}
-/**
-* Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
-*/
-function normalizeHotkeyFromParsed(parsed, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parsed, platform);
+function parseHotkey(hotkey, platform = detectPlatform()) {
+	return Array.isArray(hotkey) ? hotkey.map((step) => parseChord(step, platform)) : parseChord(hotkey, platform);
 }
-function normalizeRegisterableHotkey(hotkey, platform = detectPlatform()) {
-	if (isHotkeySequence(hotkey)) {
-		const steps = hotkey.map((step) => normalizeHotkey(step, platform));
+function normalizeHotkey(hotkey, platform = detectPlatform()) {
+	if (Array.isArray(hotkey)) {
+		const steps = hotkey.map((step) => normalizeParsedChord(parseChord(step, platform), platform));
 		return steps.length === 1 ? steps[0] : steps;
 	}
-	return typeof hotkey === "string" ? normalizeHotkey(hotkey, platform) : normalizeHotkeyFromParsed(rawHotkeyToParsedHotkey(hotkey, platform), platform);
+	return normalizeParsedChord(parseChord(hotkey, platform), platform);
 }
 /**
 * Checks if a string is a recognized modifier token (including aliases).
@@ -165,17 +102,15 @@ function normalizeRegisterableHotkey(hotkey, platform = detectPlatform()) {
 * @returns True if the string is a recognized modifier
 */
 function isModifierKey(key) {
-	return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES;
+	return modifierAlias(key) !== void 0;
 }
 /**
-* Parses a KeyboardEvent into a ParsedHotkey object.
-*
-* This function extracts the key and modifier state from a keyboard event
-* and converts it into the same format used by `parseHotkey()`.
+* Parses a KeyboardEvent into the chord it pressed, in the same format as
+* `parseHotkey()`. Pass the result to `normalizeHotkey` for its canonical string.
 *
 * @param event - The KeyboardEvent to parse
 * @param platform - The target platform for resolving modifiers (defaults to auto-detection)
-* @returns A ParsedHotkey object representing the keyboard event
+* @returns The parsed chord for the keyboard event
 *
 * @example
 * ```ts
@@ -190,38 +125,17 @@ function parseKeyboardEvent(event, platform) {
 	const ctrl = normalized.altGraph ? false : normalized.ctrl;
 	const alt = normalized.altGraph ? false : normalized.alt;
 	const shift = normalized.shift;
-	const modifiers = [];
-	if (ctrl) modifiers.push("Control");
-	if (alt) modifiers.push("Alt");
-	if (shift) modifiers.push("Shift");
-	if (normalized.meta) modifiers.push("Meta");
-	return {
-		key: normalized.key,
-		ctrl,
-		shift,
-		alt,
-		meta: normalized.meta,
-		modifiers
-	};
+	return toParsedChord({ key: normalized.key }, ctrl, shift, alt, normalized.meta);
 }
 /**
-* Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
+* Checks if a chord contains at least one non-modifier key.
 *
-* @param event - The keyboard event (typically `keydown`)
-* @param platform - Target platform for `Mod` eligibility
-*/
-function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event, platform), platform);
-}
-/**
-* Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
-*
-* This is useful for validating that a recorded hotkey is complete and not
+* This is useful for validating that a recorded chord is complete and not
 * just a combination of modifiers without an action key.
 *
-* @param hotkey - The hotkey string or ParsedHotkey to check
+* @param chord - The chord string or parsed chord to check
 * @param platform - The target platform for parsing (defaults to auto-detection)
-* @returns True if the hotkey contains at least one non-modifier key
+* @returns True if the chord contains at least one non-modifier key
 *
 * @example
 * ```ts
@@ -230,18 +144,11 @@ function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
 * hasNonModifierKey(parseHotkey('Mod+A')) // true
 * ```
 */
-function hasNonModifierKey(hotkey, platform = detectPlatform()) {
-	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+function hasNonModifierKey(chord, platform = detectPlatform()) {
+	const parsed = typeof chord === "string" ? parseChordString(chord, platform) : chord;
 	if (parsed.code !== void 0) return parsed.code.length > 0 && !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code);
 	return !isModifierKey(parsed.key) && parsed.key.length > 0;
 }
-/**
-* Parses a string or raw binding, resolving Mod for the supplied platform.
-* Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
-*/
-function parseRegisterableHotkey(hotkey, platform = detectPlatform()) {
-	return typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
-}
 
 //#endregion
-export { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, simplifyHotkey };
+export { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey };

package/dist/validate.js

@@ -1,5 +1,5 @@
-import { ALL_KEYS, MODIFIER_ALIASES, normalizeKeyName } from "./constants.js";
-import { splitHotkeyParts } from "./_keyboard-event.js";
+import { ALL_KEYS, normalizeKeyName } from "./constants.js";
+import { modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
 //#region src/validate.ts
 /**
@@ -52,7 +52,7 @@ function validateChord(hotkey) {
 		warnings: [],
 		errors: ["Hotkey cannot be empty"]
 	};
-	const parts = splitHotkeyParts(hotkey).map((p) => p.trim());
+	const parts = splitChordParts(hotkey).map((p) => p.trim());
 	if (parts.length === 0 || parts.some((p) => p === "")) return {
 		valid: false,
 		warnings: [],
@@ -60,34 +60,18 @@ function validateChord(hotkey) {
 	};
 	const modifierParts = parts.slice(0, -1);
 	const keyPart = parts[parts.length - 1];
-	for (const modifier of modifierParts) if (!(MODIFIER_ALIASES[modifier] ?? MODIFIER_ALIASES[modifier.toLowerCase()])) errors.push(`Unknown modifier: '${modifier}'`);
-	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && !/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(keyPart)) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
-	if (!isKnownKey(normalizeKeyName(keyPart)) && !isKnownKey(keyPart)) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	for (const modifier of modifierParts) if (!modifierAlias(modifier)) errors.push(`Unknown modifier: '${modifier}'`);
+	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && physicalCodeOf(keyPart) === void 0) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
+	if (!isKnownKey(normalizeKeyName(keyPart))) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
 	return {
 		valid: errors.length === 0,
 		warnings,
 		errors
 	};
 }
-/**
-* Checks if a key is in the known keys set.
-*/
+/** Physical codes, single characters, and named keys are known. */
 function isKnownKey(key) {
-	if (/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(key)) return true;
-	if (Array.from(key).length === 1) return true;
-	if (ALL_KEYS.has(key)) return true;
-	if (key.length === 1 && ALL_KEYS.has(key.toUpperCase())) return true;
-	return key in {
-		Esc: true,
-		Return: true,
-		Space: true,
-		" ": true,
-		Del: true,
-		Up: true,
-		Down: true,
-		Left: true,
-		Right: true
-	};
+	return physicalCodeOf(key) !== void 0 || Array.from(key).length === 1 || ALL_KEYS.has(key);
 }
 /**
 * Validates a hotkey and throws an error if invalid.

package/package.json

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

package/dist/recorder-options.d.ts

@@ -1,34 +0,0 @@
-import { Hotkey, ParsedHotkey } from "./hotkey.types.js";
-import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
-//#region src/recorder-options.d.ts
-/** Event property used to record a binding. Physical codes are the default. */
-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;
-  conflicts?: Array<HotkeyConflict>;
-}
-export interface RecorderOptions {
-  /** Physical code recording is the default. Choose key to record logical characters. */
-  recordBy?: RecorderKeyMode;
-  /** Platform used for Mod and AltGraph handling. Defaults to platform detection. */
-  platform?: 'mac' | 'windows' | 'linux';
-  /** Opt in to live-registry conflicts, including sequence prefixes. Default: false. */
-  detectConflicts?: boolean | HotkeyConflictOptions;
-  /** 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;
-  /** The event that recorded each step. */
-  events: ReadonlyArray<KeyboardEvent>;
-  /** Every step, parsed. */
-  parsedSequence: ReadonlyArray<ParsedHotkey>;
-}
-//#endregion