@tanstack/hotkeys 0.15.1 → 0.16.0

package/dist/parse.d.ts

@@ -1,61 +1,42 @@
 import { Key } from "./key.types.js";
-import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkey, RawHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.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;
-/**
- * Same canonical string as {@link normalizeHotkey}, but from an already-parsed
- * hotkey: `Mod` first when the platform allows, then `Alt`, then `Shift`;
- * otherwise full `Control+Alt+Shift+Meta` order.
- */
-export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
-/**
- * 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`,
@@ -63,25 +44,20 @@ export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform
  * - 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;
-/**
- * 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).
  *
@@ -93,14 +69,12 @@ export declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey,
  */
 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
@@ -110,23 +84,16 @@ export declare function isModifierKey(key: Key | (string & {})): boolean;
  * })
  * ```
  */
-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
@@ -135,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,10 +1,10 @@
 import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitHotkeyParts } from "./_keyboard-event.js";
+import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
 //#region src/parse.ts
-/** Builds a ParsedHotkey, listing held modifiers in canonical order. */
-function toParsedHotkey(identity, ctrl, shift, alt, meta) {
+/** Builds a ParsedHotkeyChord, listing held modifiers in canonical order. */
+function toParsedChord(identity, ctrl, shift, alt, meta) {
 	const held = {
 		Control: ctrl,
 		Alt: alt,
@@ -30,22 +30,8 @@ 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++) {
@@ -61,47 +47,30 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 	}
 	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
 	const code = physicalCodeOf(key);
-	return toParsedHotkey(code !== void 0 ? { code } : { key }, modifiers.has("Control"), modifiers.has("Shift"), modifiers.has("Alt"), modifiers.has("Meta"));
+	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;
 	}
-	return toParsedHotkey(raw.code !== void 0 ? { code: raw.code } : { key: normalizeKeyName(raw.key) }, ctrl, shift, alt, meta);
+	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);
 }
 /**
-* Same canonical string as {@link normalizeHotkey}, but from an already-parsed
-* hotkey: `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 normalizeHotkeyFromParsed(parsed, platform = detectPlatform()) {
+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 = [];
@@ -113,35 +82,15 @@ function normalizeHotkeyFromParsed(parsed, platform = detectPlatform()) {
 	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 normalizeHotkeyFromParsed(parseHotkey(hotkey, platform), 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).
@@ -156,14 +105,12 @@ function isModifierKey(key) {
 	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
@@ -178,26 +125,17 @@ function parseKeyboardEvent(event, platform) {
 	const ctrl = normalized.altGraph ? false : normalized.ctrl;
 	const alt = normalized.altGraph ? false : normalized.alt;
 	const shift = normalized.shift;
-	return toParsedHotkey({ key: normalized.key }, ctrl, shift, alt, normalized.meta);
+	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 normalizeHotkeyFromParsed(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
@@ -206,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, normalizeKeyName } from "./constants.js";
-import { modifierAlias, physicalCodeOf, splitHotkeyParts } from "./_keyboard-event.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: [],

package/package.json

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