@tanstack/hotkeys 0.15.1 → 0.16.0

package/README.md

@@ -51,7 +51,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is in beta. We are actively developing the library and are open to feedback and contributions.
 
 Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
 

package/dist/_keyboard-event.js

@@ -62,7 +62,7 @@ function physicalCodeOf(token) {
 	return token.startsWith("[") && token.endsWith("]") && isCodeName(token.slice(1, -1)) ? token.slice(1, -1) : void 0;
 }
 /** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
-function splitHotkeyParts(hotkey) {
+function splitChordParts(hotkey) {
 	if (!hotkey.endsWith("+")) return hotkey.split("+");
 	const parts = hotkey.slice(0, -1).split("+");
 	if (parts.at(-1) === "") parts.pop();
@@ -88,4 +88,4 @@ function assertLogicalKey(key) {
 }
 
 //#endregion
-export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitHotkeyParts };
+export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };

package/dist/_match.js

@@ -50,9 +50,9 @@ function modifiersMatch(event, parsed, allowImplicitShift) {
 * same physical code or (case-insensitively) the same logical key. A code and
 * a key never match, even when one keyboard event could produce both.
 */
-function parsedHotkeysEqual(a, b) {
+function parsedChordsEqual(a, b) {
 	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));
 }
 
 //#endregion
-export { matchKeyboardEvent, parsedHotkeysEqual };
+export { matchKeyboardEvent, parsedChordsEqual };

package/dist/_recorder-chord.js

@@ -1,6 +1,6 @@
 import { normalizeKeyName } from "./constants.js";
 import { isCodeName, normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isModifierKey, normalizeHotkeyFromParsed, parseKeyboardEvent } from "./parse.js";
+import { isModifierKey, normalizeHotkey, parseKeyboardEvent } from "./parse.js";
 
 //#region src/_recorder-chord.ts
 /**
@@ -15,12 +15,12 @@ function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
 	const parsed = parseKeyboardEvent(event, platform);
 	if (recordBy === "code") {
 		const { key: _key, code: _code, ...modifiers } = parsed;
-		return normalizeHotkeyFromParsed({
+		return normalizeHotkey({
 			...modifiers,
 			code: event.code
 		}, platform);
 	}
-	return parsed.key ? normalizeHotkeyFromParsed(parsed, platform) : null;
+	return parsed.key ? normalizeHotkey(parsed, platform) : null;
 }
 /**
 * Explains why a physical chord cannot be recorded before syntax/policy checks.

package/dist/_registration.js

@@ -1,4 +1,6 @@
 //#region src/_registration.ts
+/** The scope of hotkeys that do not name one. It is always active unless an exclusive scope is active. */
+const GLOBAL_SCOPE = "global";
 /**
 * Default options for hotkey/sequence registration.
 * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
@@ -10,15 +12,16 @@ const defaultHotkeyOptions = {
 	eventType: "keydown",
 	enabled: true,
 	ignoreInputs: "auto",
-	conflictBehavior: "warn"
+	conflictBehavior: "warn",
+	scope: GLOBAL_SCOPE
 };
 /**
 * Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).
 * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
 */
-function getDefaultIgnoreInputs(parsedHotkey) {
-	if (parsedHotkey.ctrl || parsedHotkey.meta) return false;
-	if (parsedHotkey.key === "Escape" || parsedHotkey.code === "Escape") return false;
+function getDefaultIgnoreInputs(parsedChord) {
+	if (parsedChord.ctrl || parsedChord.meta) return false;
+	if (parsedChord.key === "Escape" || parsedChord.code === "Escape") return false;
 	return true;
 }
 /**
@@ -47,4 +50,4 @@ function optionsEqual(left, right) {
 }
 
 //#endregion
-export { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };
+export { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };

package/dist/adapter.d.ts

@@ -1,5 +1,5 @@
-import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
-import { HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.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";
 //#region src/adapter.d.ts
 /**
@@ -11,7 +11,7 @@ export type HotkeyDefinition = {
   callback: HotkeyCallback;
   options?: HotkeyChordOptions;
 } | {
-  hotkey: HotkeySequence;
+  hotkey: RegisterableHotkeySequence;
   callback: HotkeyCallback;
   options?: HotkeySequenceOptions;
 };
@@ -55,15 +55,15 @@ export type AdapterAppHotkeyOptions<T extends AppHotkey, TTarget> = Omit<[T['def
  * accept only shared options.
  */
 export type AdapterHotkeyDefinition<TTarget> = {
-  /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+  /** A chord string such as `'Mod+S'`, or a chord object */
   hotkey: RegisterableHotkeyChord;
   /** The function to call when the hotkey is pressed */
   callback: HotkeyCallback;
   /** Per-hotkey options (merged on top of common options) */
   options?: AdapterChordOptions<TTarget>;
 } | {
-  /** A sequence such as `['G', 'G']` */
-  hotkey: HotkeySequence;
+  /** A sequence such as `['G', 'G']`, with each step a string or an object */
+  hotkey: RegisterableHotkeySequence;
   callback: HotkeyCallback;
   options?: AdapterSequenceOptions<TTarget>;
 } | {
@@ -113,4 +113,51 @@ export declare function prepareHotkeyDefinitions<TTarget>(definitions: ReadonlyA
  * unsubscribe function.
  */
 export declare function subscribePublishedAppHotkeys(onChange: () => void): () => void;
+/** Scope props shared by framework providers. */
+export interface HotkeysProviderScopeProps {
+  /**
+   * Scope for hotkeys registered inside this provider, active while it is
+   * mounted and enabled. Defaults to the parent provider's scope, or
+   * `'global'` at the root. App hotkeys that declare a scope keep it.
+   */
+  scope?: string;
+  /**
+   * While mounted and enabled, suspend hotkeys in every other scope,
+   * including `'global'`, except scopes of nested providers. Pass
+   * `{ allow: [...] }` to keep other scopes active, such as `'global'`. Use
+   * with `scope`, for dialogs and other overlays.
+   */
+  exclusive?: ActivateHotkeyScopeOptions['exclusive'];
+  /**
+   * Set false to deactivate this provider's scope, and the scopes of
+   * providers nested in it, without unmounting. Defaults to true.
+   */
+  enabled?: boolean;
+}
+/**
+ * Merges a provider's default options over its parent's. A provider with a
+ * `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+ */
+export declare function mergeHotkeysProviderDefaults<T extends {
+  hotkey?: object;
+  hotkeyRecorder?: object;
+}>(parent: T | undefined, own: T | undefined, scope: string | undefined): T;
+/**
+ * A key for a provider's scope activation, or `null` when the scope should not
+ * be active. Equal keys mean the same activation, so adapters reactivate only
+ * when the key changes, not when an inline `exclusive` object is recreated.
+ */
+export declare function getHotkeysProviderScopeKey(options: {
+  scope: string | undefined;
+  exclusive: ActivateHotkeyScopeOptions['exclusive'];
+  /** Whether this provider and every ancestor are enabled. */
+  active: boolean;
+  /** The parent provider's scope. */
+  parent: string | undefined;
+}): string | null;
+/**
+ * Activates the scope described by a key from `getHotkeysProviderScopeKey`.
+ * Returns a function that releases the activation.
+ */
+export declare function activateHotkeysProviderScope(key: string): () => void;
 //#endregion

package/dist/adapter.js

@@ -1,5 +1,5 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeRegisterableHotkey } from "./parse.js";
+import { isHotkeySequence, normalizeHotkey } from "./parse.js";
 import { defaultHotkeyOptions } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
@@ -28,7 +28,7 @@ function createHotkeyBindings() {
 					platform: merged.platform ?? detectPlatform()
 				};
 				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
-				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
+				const hotkey = normalizeHotkey(definition.hotkey, options.platform);
 				if (isHotkeySequence(hotkey)) delete options.requireReset;
 				else delete options.timeout;
 				prepared.push({
@@ -127,6 +127,48 @@ function subscribePublishedAppHotkeys(onChange) {
 		inner?.unsubscribe();
 	};
 }
+/**
+* Merges a provider's default options over its parent's. A provider with a
+* `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+*/
+function mergeHotkeysProviderDefaults(parent, own, scope) {
+	return {
+		hotkey: {
+			...parent?.hotkey,
+			...own?.hotkey,
+			...scope && { scope }
+		},
+		hotkeyRecorder: {
+			...parent?.hotkeyRecorder,
+			...own?.hotkeyRecorder
+		}
+	};
+}
+/**
+* A key for a provider's scope activation, or `null` when the scope should not
+* be active. Equal keys mean the same activation, so adapters reactivate only
+* when the key changes, not when an inline `exclusive` object is recreated.
+*/
+function getHotkeysProviderScopeKey(options) {
+	const { scope, exclusive, active, parent } = options;
+	if (!scope || !active) return null;
+	return JSON.stringify([
+		scope,
+		typeof exclusive === "object" ? exclusive.allow : !!exclusive,
+		parent ?? null
+	]);
+}
+/**
+* Activates the scope described by a key from `getHotkeysProviderScopeKey`.
+* Returns a function that releases the activation.
+*/
+function activateHotkeysProviderScope(key) {
+	const [scope, exclusive, parent] = JSON.parse(key);
+	return getHotkeyManager().activateScope(scope, {
+		exclusive: Array.isArray(exclusive) ? { allow: exclusive } : exclusive,
+		parent: parent ?? void 0
+	});
+}
 
 //#endregion
-export { createHotkeyBindings, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };
+export { activateHotkeysProviderScope, createHotkeyBindings, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };

package/dist/app-hotkeys.d.ts

@@ -17,11 +17,12 @@ export interface AppHotkeyInput {
   /** Display metadata for cheat sheets and settings screens. */
   meta?: HotkeyMeta;
   /**
-   * Label for where this hotkey applies, such as `'editor'`. App hotkeys with
-   * different contexts may share a hotkey; one without a context conflicts with
-   * any app hotkey that shares its hotkey. It does not affect matching.
+   * Scope this hotkey fires in, such as `'editor'`. Overrides the scope of the
+   * provider it registers under. App hotkeys in different scopes may share a
+   * hotkey; one in the `'global'` scope conflicts with any app hotkey that
+   * shares its hotkey.
    */
-  context?: string;
+  scope?: string;
   /**
    * Options that describe the hotkey itself. Chord defaults accept
    * `requireReset`; sequence defaults accept `timeout`.
@@ -45,7 +46,7 @@ export interface AppHotkey<TId extends string = string, TDefault extends HotkeyC
   /** Hotkey declared in `defineAppHotkeys`. */
   readonly defaultHotkey: TDefault;
   readonly meta?: HotkeyMeta;
-  readonly context?: string;
+  readonly scope?: string;
   readonly options?: AppHotkeyOptions;
 }
 /** A map of app hotkeys keyed by id. */
@@ -110,11 +111,12 @@ export declare function isCustomHotkey(appHotkey: AppHotkey, platform?: Platform
 /**
  * Status of an app hotkey in the running app.
  * - `'active'`: at least one enabled registration
+ * - `'suspended'`: has an enabled registration, but none in an active scope
  * - `'disabled'`: registered, but every registration has `enabled: false`
  * - `'inactive'`: has a hotkey, but nothing has registered it
  * - `'unbound'`: no hotkey assigned
  */
-export type AppHotkeyStatus = 'active' | 'disabled' | 'inactive' | 'unbound';
+export type AppHotkeyStatus = 'active' | 'suspended' | 'disabled' | 'inactive' | 'unbound';
 /** One row of an app hotkey cheat sheet. */
 export interface AppHotkeyListItem<T extends AppHotkey = AppHotkey> {
   appHotkey: T;
@@ -174,7 +176,7 @@ export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
   get(id: string): AppHotkey | undefined;
   /**
    * Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
-   * collide when their contexts match or either has no context, and their
+   * collide when their scopes match or either is `'global'`, and their
    * hotkeys are equal or one sequence starts with the other.
    */
   findConflicts(id: keyof T & string, hotkey: Hotkey): Array<AppHotkey>;
@@ -203,12 +205,13 @@ export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
 export declare function resolveAppHotkey(appHotkey: AppHotkey, store: AppHotkeysStore | null | undefined): AppHotkey;
 /**
  * Options that adapters pass to the manager when registering an app hotkey:
- * declared options, meta, and the app hotkey id. The manager drops options
+ * declared options, scope, meta, and the app hotkey id. The manager drops options
  * that do not apply to the effective hotkey's kind.
  */
 export declare function getAppHotkeyRegistrationOptions(appHotkey: AppHotkey): AppHotkeyOptions & {
   meta?: HotkeyMeta;
   appHotkeyId: string;
+  scope?: string;
 };
 /**
  * Publishes a provider's store on the HotkeyManager so devtools can list

package/dist/app-hotkeys.js

@@ -2,6 +2,7 @@ import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
 import { areHotkeysEqual } from "./match.js";
+import { GLOBAL_SCOPE } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { Store } from "@tanstack/store";
 
@@ -30,7 +31,7 @@ function defineAppHotkeys(definitions) {
 			hotkey,
 			defaultHotkey: hotkey,
 			meta: input.meta,
-			context: input.context,
+			scope: input.scope,
 			options: input.options
 		};
 	}
@@ -86,8 +87,10 @@ function sanitizeCustomHotkeys(appHotkeys, saved) {
 	return result;
 }
 /** Whether two app hotkeys can apply at the same time. */
-function contextsOverlap(a, b) {
-	return a.context === void 0 || b.context === void 0 || a.context === b.context;
+function scopesOverlap(a, b) {
+	const left = a.scope ?? "global";
+	const right = b.scope ?? "global";
+	return left === "global" || right === "global" || left === right;
 }
 /** Whether two hotkeys collide: equal chords, or one sequence starts with the other. */
 function hotkeysOverlap(left, right, platform) {
@@ -162,14 +165,14 @@ var AppHotkeysStore = class {
 	}
 	/**
 	* Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
-	* collide when their contexts match or either has no context, and their
+	* collide when their scopes match or either is `'global'`, and their
 	* hotkeys are equal or one sequence starts with the other.
 	*/
 	findConflicts(id, hotkey) {
 		const self = this.store.state.appHotkeys[id];
 		if (!self) return [];
 		const candidate = simplifyHotkey(hotkey);
-		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && contextsOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
+		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && scopesOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
 	}
 	/**
 	* Sets the user's hotkey for an app hotkey. `null` unbinds it. A hotkey
@@ -224,11 +227,13 @@ var AppHotkeysStore = class {
 			if (list) list.push(registration);
 			else byId.set(id, [registration]);
 		}
+		const manager = getHotkeyManager();
 		return Object.values(this.store.state.appHotkeys).map((appHotkey) => {
 			const registered = byId.get(appHotkey.id) ?? [];
+			const enabled = registered.filter((r) => r.options.enabled !== false);
 			return {
 				appHotkey,
-				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : registered.some((r) => r.options.enabled !== false) ? "active" : "disabled",
+				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : enabled.length === 0 ? "disabled" : enabled.some((r) => manager.isScopeActive(r.options.scope)) ? "active" : "suspended",
 				isCustom: isCustomHotkey(appHotkey, this.#platform),
 				registrations: registered
 			};
@@ -245,12 +250,13 @@ function resolveAppHotkey(appHotkey, store) {
 }
 /**
 * Options that adapters pass to the manager when registering an app hotkey:
-* declared options, meta, and the app hotkey id. The manager drops options
+* declared options, scope, meta, and the app hotkey id. The manager drops options
 * that do not apply to the effective hotkey's kind.
 */
 function getAppHotkeyRegistrationOptions(appHotkey) {
 	return {
 		...appHotkey.options,
+		...appHotkey.scope !== void 0 && { scope: appHotkey.scope },
 		meta: appHotkey.meta,
 		appHotkeyId: appHotkey.id
 	};

package/dist/conflicts.js

@@ -1,6 +1,6 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
-import { parsedHotkeysEqual } from "./_match.js";
+import { isHotkeySequence, parseHotkey } from "./parse.js";
+import { parsedChordsEqual } from "./_match.js";
 import { matchesKeyboardEvent } from "./match.js";
 import { getTargetDocument } from "./_event-target.js";
 import { managerRef } from "./_manager-ref.js";
@@ -23,15 +23,15 @@ function findHotkeyConflicts(candidate, options = {}) {
 	const steps = isHotkeySequence(candidate) ? candidate : [candidate];
 	if (steps.length === 0) return [];
 	const platform = options.platform ?? detectPlatform();
-	const parsed = steps.map((step) => parseRegisterableHotkey(step, platform));
+	const parsed = steps.map((step) => parseHotkey(step, platform));
 	const target = options.target ?? (typeof document === "undefined" ? void 0 : document);
 	const conflicts = [];
 	const matches = (registration, bindings) => {
 		if (!options.includeDisabled && registration.options.enabled === false || (registration.options.eventType ?? "keydown") !== (options.eventType ?? "keydown") || options.excludeIds?.includes(registration.id) || options.exclude?.(registration) || options.scope !== "all" && target && !targetsOverlap(target, registration.target)) return false;
 		return parsed.slice(0, Math.min(parsed.length, bindings.length)).every((a, index) => {
-			const b = parseRegisterableHotkey(bindings[index], registration.options.platform);
+			const b = parseHotkey(bindings[index], registration.options.platform);
 			const event = options.events?.[index];
-			return parsedHotkeysEqual(a, b) || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
+			return parsedChordsEqual(a, b) || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
 		});
 	};
 	const registrations = managerRef.current?.registrations.state.values() ?? [];

package/dist/format.d.ts

@@ -1,20 +1,24 @@
-import { ParsedHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
+import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
 //#region src/format.d.ts
 /**
- * Converts a ParsedHotkey back to a hotkey string.
+ * Converts a parsed hotkey back to a string, with each platform modifier
+ * spelled out, such as `Control+Shift+S`. A parsed chord returns a string, and
+ * a parsed sequence returns one string per step. To get `Mod` back where the
+ * platform allows it, use `normalizeHotkey` instead.
  *
- * @param parsed - The parsed hotkey object
- * @returns A hotkey string in canonical form
+ * @param parsed - A parsed chord, or the parsed steps of a sequence
  *
  * @example
  * ```ts
- * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
- * // Returns: 'Control+Shift+S'
+ * formatHotkey(parseHotkey('Mod+Shift+S', 'windows')) // 'Control+Shift+S'
+ * formatHotkey(parseHotkey(['G', 'Mod+K'], 'mac')) // ['G', 'Meta+K']
  * ```
  */
-export declare function formatHotkey(parsed: ParsedHotkey): string;
+export declare function formatHotkey(parsed: ParsedHotkeyChord): string;
+export declare function formatHotkey(parsed: ReadonlyArray<ParsedHotkeyChord>): Array<string>;
+export declare function formatHotkey(parsed: ParsedHotkeyChord | ReadonlyArray<ParsedHotkeyChord>): string | Array<string>;
 /** A single chord to display: a string, raw object, or parsed hotkey. */
-export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkey | (string & {});
+export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkeyChord | (string & {});
 /** A hotkey to display: a chord or a sequence of chords. */
 export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChord>;
 /**
@@ -31,7 +35,7 @@ export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChor
  * Sequence steps are formatted individually and joined with `sequenceSeparator`
  * (a space by default).
  *
- * @param hotkey - A logical or physical string, raw object, ParsedHotkey, or sequence
+ * @param hotkey - A logical or physical string, raw object, ParsedHotkeyChord, or sequence
  * @param options - Formatting options
  * @returns Display text, or individual key labels when parts is true (one array per step for sequences)
  *

package/dist/format.js

@@ -1,23 +1,14 @@
 import { MODIFIER_ORDER, 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 } from "./platform.js";
-import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitHotkeyParts } from "./_keyboard-event.js";
-import { normalizeHotkeyFromParsed, normalizeRegisterableHotkey } from "./parse.js";
+import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { normalizeHotkey } from "./parse.js";
 
 //#region src/format.ts
-/**
-* Converts a ParsedHotkey back to a hotkey string.
-*
-* @param parsed - The parsed hotkey object
-* @returns A hotkey string in canonical form
-*
-* @example
-* ```ts
-* formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
-* // Returns: 'Control+Shift+S'
-* ```
-*/
 function formatHotkey(parsed) {
+	return Array.isArray(parsed) ? parsed.map((step) => formatParsedChord(step)) : formatParsedChord(parsed);
+}
+function formatParsedChord(parsed) {
 	if (parsed.code === void 0) assertLogicalKey(parsed.key);
 	const parts = [];
 	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
@@ -45,8 +36,8 @@ function formatChordParts(hotkey, options) {
 	const symbols = options.useSymbols ?? true;
 	const modifierSymbols = modifierSymbolsEnabled(options);
 	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;
-	const normalized = typeof hotkey === "object" && "modifiers" in hotkey ? normalizeHotkeyFromParsed(hotkey, platform) : normalizeRegisterableHotkey(hotkey, platform);
-	const segments = splitHotkeyParts(normalized);
+	const normalized = normalizeHotkey(hotkey, platform);
+	const segments = splitChordParts(normalized);
 	if (platform === "mac") {
 		const modifierIndex = (segment) => {
 			const index = MODIFIER_ORDER.indexOf(segment === "Mod" ? "Meta" : segment);

package/dist/hint.js

@@ -1,5 +1,5 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
-import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
+import { isHotkeySequence, parseHotkey } from "./parse.js";
 
 //#region src/hint.ts
 /**
@@ -18,7 +18,7 @@ function matchesHeldModifiers(hotkey, heldKeys, options = {}) {
 	const held = [...new Set(heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)))];
 	const first = isHotkeySequence(hotkey) ? hotkey[0] : hotkey;
 	if (first === void 0) return false;
-	const { modifiers } = parseRegisterableHotkey(first, options.platform);
+	const { modifiers } = parseHotkey(first, options.platform);
 	return held.length > 0 && held.every((key) => modifiers.includes(key)) && (!options.exact || held.length === modifiers.length);
 }