@tanstack/hotkeys 0.10.1 → 0.12.0

package/dist/app-hotkeys.js

@@ -0,0 +1,295 @@
+import { detectPlatform } from "./platform.js";
+import { isHotkeySequence, simplifyHotkey } from "./parse.js";
+import { validateHotkey } from "./validate.js";
+import { areHotkeysEqual } from "./match.js";
+import { getHotkeyManager } from "./hotkey-manager.js";
+import { Store } from "@tanstack/store";
+
+//#region src/app-hotkeys.ts
+/**
+* Declares every app hotkey up front, without registering any, so cheat
+* sheets and settings screens can list hotkeys whose components have not
+* mounted. Pass the result to `HotkeysProvider` as `appHotkeys`.
+*
+* @example
+* ```ts
+* export const appHotkeys = defineAppHotkeys({
+*   'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save', group: 'Document' } },
+*   'nav.home': { hotkey: ['G', 'H'], meta: { name: 'Go home' }, options: { timeout: 800 } },
+*   'palette.open': { hotkey: null, meta: { name: 'Command palette' } },
+* })
+* ```
+*/
+function defineAppHotkeys(definitions) {
+	const result = {};
+	for (const [id, input] of Object.entries(definitions)) {
+		const hotkey = input.hotkey === null ? null : simplifyHotkey(input.hotkey);
+		result[id] = {
+			"~appHotkey": true,
+			id,
+			hotkey,
+			defaultHotkey: hotkey,
+			meta: input.meta,
+			context: input.context,
+			options: input.options
+		};
+	}
+	return result;
+}
+/** Whether a value is an app hotkey created by `defineAppHotkeys`. */
+function isAppHotkey(value) {
+	return typeof value === "object" && value !== null && value["~appHotkey"] === true;
+}
+function hotkeysEqual(left, right, platform) {
+	if (left === null || right === null) return left === right;
+	return areHotkeysEqual(left, right, platform);
+}
+/** Whether an app hotkey's effective hotkey differs from its default. */
+function isCustomHotkey(appHotkey, platform = detectPlatform()) {
+	return !hotkeysEqual(appHotkey.hotkey, appHotkey.defaultHotkey, platform);
+}
+/** Parses a saved custom hotkey. Returns `undefined` when it is not a valid hotkey. */
+function parseCustomHotkey(value) {
+	if (value === null) return null;
+	return (typeof value === "string" || Array.isArray(value) && value.every((step) => typeof step === "string")) && validateHotkey(value).valid ? simplifyHotkey(value) : void 0;
+}
+/** Applies custom hotkeys to declarations. Unchanged entries keep their identity. */
+function applyCustomHotkeys(appHotkeys, customHotkeys) {
+	const custom = customHotkeys;
+	const result = {};
+	for (const [id, appHotkey] of Object.entries(appHotkeys)) {
+		const hotkey = custom[id] === void 0 ? appHotkey.defaultHotkey : custom[id];
+		result[id] = hotkey === appHotkey.hotkey ? appHotkey : {
+			...appHotkey,
+			hotkey
+		};
+	}
+	return result;
+}
+/** Keeps only valid custom hotkeys for known ids, warning about the rest. */
+function sanitizeCustomHotkeys(appHotkeys, saved) {
+	const result = {};
+	if (typeof saved !== "object" || saved === null) return result;
+	for (const [id, value] of Object.entries(saved)) {
+		if (value === void 0) continue;
+		if (!(id in appHotkeys)) {
+			console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
+			continue;
+		}
+		const hotkey = parseCustomHotkey(value);
+		if (hotkey === void 0) {
+			console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
+			continue;
+		}
+		result[id] = hotkey;
+	}
+	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;
+}
+/** Whether two hotkeys collide: equal chords, or one sequence starts with the other. */
+function hotkeysOverlap(left, right, platform) {
+	const a = isHotkeySequence(left) ? left : [left];
+	const b = isHotkeySequence(right) ? right : [right];
+	const length = Math.min(a.length, b.length);
+	for (let i = 0; i < length; i++) if (!areHotkeysEqual(a[i], b[i], platform)) return false;
+	return true;
+}
+/**
+* Holds declared app hotkeys and the user's custom hotkeys. Framework
+* providers create one and expose it through hooks; devtools read it from
+* `HotkeyManager.appHotkeys`.
+*
+* @example
+* ```ts
+* const store = new AppHotkeysStore(appHotkeys, {
+*   customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+*   onCustomHotkeysChange: (custom) =>
+*     localStorage.setItem('hotkeys', JSON.stringify(custom)),
+* })
+* store.setCustomHotkey('doc.save', 'Mod+Shift+S')
+* ```
+*/
+var AppHotkeysStore = class {
+	store;
+	#declarations;
+	#options;
+	constructor(appHotkeys, options = {}) {
+		this.#declarations = appHotkeys;
+		this.#options = options;
+		const customHotkeys = sanitizeCustomHotkeys(appHotkeys, options.customHotkeys);
+		this.store = new Store({
+			appHotkeys: applyCustomHotkeys(appHotkeys, customHotkeys),
+			customHotkeys
+		});
+	}
+	get #platform() {
+		return this.#options.platform ?? detectPlatform();
+	}
+	/** Effective app hotkeys. */
+	get appHotkeys() {
+		return this.store.state.appHotkeys;
+	}
+	/** The user's hotkeys that differ from the defaults. */
+	get customHotkeys() {
+		return this.store.state.customHotkeys;
+	}
+	/** Updates callbacks and other options without resetting custom hotkeys. */
+	setOptions(options) {
+		this.#options = {
+			...this.#options,
+			...options
+		};
+	}
+	/**
+	* Replaces the declarations, for example after hot module replacement.
+	* Custom hotkeys for ids that still exist are kept.
+	*/
+	setAppHotkeys(appHotkeys) {
+		if (appHotkeys === this.#declarations) return;
+		this.#declarations = appHotkeys;
+		const customHotkeys = sanitizeCustomHotkeys(appHotkeys, this.store.state.customHotkeys);
+		this.store.setState(() => ({
+			appHotkeys: applyCustomHotkeys(appHotkeys, customHotkeys),
+			customHotkeys
+		}));
+	}
+	/** Effective app hotkey for an id, or `undefined` when it is not declared. */
+	get(id) {
+		return this.store.state.appHotkeys[id];
+	}
+	/**
+	* Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
+	* collide when their contexts match or either has no context, 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));
+	}
+	/**
+	* Sets the user's hotkey for an app hotkey. `null` unbinds it. A hotkey
+	* equal to the default removes the customization.
+	*
+	* @returns Conflicting app hotkeys. When any exist, nothing changes.
+	*/
+	setCustomHotkey(id, hotkey) {
+		const appHotkey = this.store.state.appHotkeys[id];
+		if (!appHotkey) {
+			console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
+			return [];
+		}
+		const next = hotkey === null ? null : simplifyHotkey(hotkey);
+		if (next !== null) {
+			const conflicts = this.findConflicts(id, next);
+			if (conflicts.length > 0) return conflicts;
+		}
+		const { [id]: _previous, ...rest } = this.store.state.customHotkeys;
+		this.#commit(hotkeysEqual(next, appHotkey.defaultHotkey, this.#platform) ? rest : {
+			...rest,
+			[id]: next
+		});
+		return [];
+	}
+	/** Restores the default hotkey for an app hotkey. */
+	resetCustomHotkey(id) {
+		const { [id]: _previous, ...rest } = this.store.state.customHotkeys;
+		this.#commit(rest);
+	}
+	/** Restores every default hotkey. */
+	resetCustomHotkeys() {
+		this.#commit({});
+	}
+	#commit(customHotkeys) {
+		this.store.setState(() => ({
+			appHotkeys: applyCustomHotkeys(this.#declarations, customHotkeys),
+			customHotkeys
+		}));
+		this.#options.onCustomHotkeysChange?.(customHotkeys);
+	}
+	/**
+	* Joins app hotkeys with live registrations, in declaration order.
+	* Adapters call this with the manager's registration views.
+	*/
+	getList(registrations) {
+		const byId = /* @__PURE__ */ new Map();
+		for (const registration of registrations) {
+			const id = registration.options.appHotkeyId;
+			if (id === void 0) continue;
+			const list = byId.get(id);
+			if (list) list.push(registration);
+			else byId.set(id, [registration]);
+		}
+		return Object.values(this.store.state.appHotkeys).map((appHotkey) => {
+			const registered = byId.get(appHotkey.id) ?? [];
+			return {
+				appHotkey,
+				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : registered.some((r) => r.options.enabled !== false) ? "active" : "disabled",
+				isCustom: isCustomHotkey(appHotkey, this.#platform),
+				registrations: registered
+			};
+		});
+	}
+};
+/**
+* Returns the provider's version of an app hotkey, so custom hotkeys apply
+* even when a component imports the declaration directly. Falls back to the
+* given app hotkey when no store declares it.
+*/
+function resolveAppHotkey(appHotkey, store) {
+	return store?.get(appHotkey.id) ?? 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
+* that do not apply to the effective hotkey's kind.
+*/
+function getAppHotkeyRegistrationOptions(appHotkey) {
+	return {
+		...appHotkey.options,
+		meta: appHotkey.meta,
+		appHotkeyId: appHotkey.id
+	};
+}
+/**
+* Publishes a provider's store on the HotkeyManager so devtools can list
+* declared hotkeys. Returns a cleanup function that unpublishes it if it is
+* still the published store.
+*/
+function publishAppHotkeysStore(store) {
+	const manager = getHotkeyManager();
+	manager.appHotkeys.setState(() => store);
+	return () => {
+		if (manager.appHotkeys.state === store) manager.appHotkeys.setState(() => null);
+	};
+}
+/**
+* Creates an app hotkeys store and publishes it on the HotkeyManager, for
+* adapters without a provider component (such as Lit and Alpine). Hotkey
+* APIs in those adapters resolve app hotkeys and custom hotkeys from the
+* published store. Call it once at startup. Returns the store and a function
+* that unpublishes it.
+*
+* @example
+* ```ts
+* provideAppHotkeys(appHotkeys, {
+*   customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+*   onCustomHotkeysChange: (custom) =>
+*     localStorage.setItem('hotkeys', JSON.stringify(custom)),
+* })
+* ```
+*/
+function provideAppHotkeys(appHotkeys, options = {}) {
+	const store = new AppHotkeysStore(appHotkeys, options);
+	return {
+		store,
+		dispose: publishAppHotkeysStore(store)
+	};
+}
+
+//#endregion
+export { AppHotkeysStore, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey };

package/dist/conflicts.d.ts

@@ -1,14 +1,10 @@
 import { RegisterableHotkey } from "./hotkey.types.js";
 import { HotkeyRegistrationView } from "./hotkey-manager.js";
-import { SequenceRegistrationView } from "./sequence-manager.js";
 //#region src/conflicts.d.ts
-export type HotkeyConflict = {
-  type: 'hotkey';
+/** A live registration that overlaps a candidate hotkey. */
+export interface HotkeyConflict {
   registration: HotkeyRegistrationView;
-} | {
-  type: 'sequence';
-  registration: SequenceRegistrationView;
-};
+}
 export interface HotkeyConflictOptions {
   /** Intended registration target. Defaults to document; disjoint targets are excluded. */
   target?: HTMLElement | Document | Window;
@@ -21,7 +17,7 @@ export interface HotkeyConflictOptions {
   /** IDs of registrations being edited. */
   excludeIds?: ReadonlyArray<string>;
   /** Additional app-specific exclusions, such as all instances of one action. */
-  exclude?: (registration: HotkeyRegistrationView | SequenceRegistrationView) => boolean;
+  exclude?: (registration: HotkeyRegistrationView) => boolean;
   /** Platform used to resolve Mod in the candidate. Registrations retain their own platform. */
   platform?: 'mac' | 'windows' | 'linux';
   /** Source events allow detecting physical/logical overlap on the recorded layout. */
@@ -32,5 +28,5 @@ export interface HotkeyConflictOptions {
  * With source events, also checks observed logical/physical overlap. Does not
  * discover unmounted handlers, external listeners, or other keyboard layouts.
  */
-export declare function findHotkeyConflicts(candidate: RegisterableHotkey | ReadonlyArray<RegisterableHotkey>, options?: HotkeyConflictOptions): Array<HotkeyConflict>;
+export declare function findHotkeyConflicts(candidate: RegisterableHotkey, options?: HotkeyConflictOptions): Array<HotkeyConflict>;
 //#endregion

package/dist/conflicts.js

@@ -1,9 +1,8 @@
 import { detectPlatform } from "./platform.js";
 import { keysEqual } from "./_keyboard-event.js";
-import { parseRegisterableHotkey } from "./parse.js";
+import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
 import { matchesKeyboardEvent } from "./match.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
-import { getSequenceManager } from "./sequence-manager.js";
 
 //#region src/conflicts.ts
 /** Whether two targets share a document and one contains the other (or is its window). */
@@ -24,7 +23,7 @@ function targetsOverlap(a, b) {
 * discover unmounted handlers, external listeners, or other keyboard layouts.
 */
 function findHotkeyConflicts(candidate, options = {}) {
-	const steps = Array.isArray(candidate) ? candidate : [candidate];
+	const steps = isHotkeySequence(candidate) ? candidate : [candidate];
 	if (steps.length === 0) return [];
 	const platform = options.platform ?? detectPlatform();
 	const parsed = steps.map((step) => parseRegisterableHotkey(step, platform));
@@ -39,14 +38,10 @@ function findHotkeyConflicts(candidate, options = {}) {
 			return same || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
 		});
 	};
-	for (const registration of getHotkeyManager().registrations.state.values()) if (matches(registration, [registration.hotkey])) conflicts.push({
-		type: "hotkey",
-		registration: toHotkeyRegistrationView(registration)
-	});
-	for (const registration of getSequenceManager().registrations.state.values()) if (matches(registration, registration.sequence)) conflicts.push({
-		type: "sequence",
-		registration
-	});
+	for (const registration of getHotkeyManager().registrations.state.values()) {
+		const view = toHotkeyRegistrationView(registration);
+		if (matches(view, view.kind === "sequence" ? view.hotkey : [view.hotkey])) conflicts.push({ registration: view });
+	}
 	return conflicts;
 }
 

package/dist/constants.d.ts

@@ -118,7 +118,7 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
  * @see {@link EDITING_KEYS}
  * @see {@link PUNCTUATION_KEYS}
  */
-export declare const ALL_KEYS: Set<LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey | "CapsLock" | "ContextMenu" | "Convert" | "KanaMode" | "NonConvert" | "Help" | "Insert" | "NumLock" | "Fn" | "FnLock" | "PrintScreen" | "ScrollLock" | "Pause" | "BrowserBack" | "BrowserFavorites" | "BrowserForward" | "BrowserHome" | "BrowserRefresh" | "BrowserSearch" | "BrowserStop" | "Eject" | "LaunchMail" | "MediaPlayPause" | "MediaStop" | "MediaTrackNext" | "MediaTrackPrevious" | "Power" | "AudioVolumeDown" | "AudioVolumeMute" | "AudioVolumeUp" | "WakeUp" | "Hyper" | "Super" | "Again" | "Copy" | "Cut" | "Find" | "Open" | "Paste" | "Props" | "Select" | "Undo" | "Hiragana" | "Katakana" | "Clear" | "Cancel" | "Standby" | "LaunchApplication1" | "LaunchApplication2" | "LaunchMediaPlayer" | "HangulMode" | "HanjaMode" | "Zenkaku" | "Hankaku" | "ZenkakuHankaku">;
+export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "KanaMode" | "NonConvert" | "Help" | "Insert" | "NumLock" | "Fn" | "FnLock" | "PrintScreen" | "ScrollLock" | "Pause" | "BrowserBack" | "BrowserFavorites" | "BrowserForward" | "BrowserHome" | "BrowserRefresh" | "BrowserSearch" | "BrowserStop" | "Eject" | "LaunchMail" | "MediaPlayPause" | "MediaStop" | "MediaTrackNext" | "MediaTrackPrevious" | "Power" | "AudioVolumeDown" | "AudioVolumeMute" | "AudioVolumeUp" | "WakeUp" | "Hyper" | "Super" | "Again" | "Copy" | "Cut" | "Find" | "Open" | "Paste" | "Props" | "Select" | "Undo" | "Hiragana" | "Katakana" | "Clear" | "Cancel" | "Standby" | "LaunchApplication1" | "LaunchApplication2" | "LaunchMediaPlayer" | "HangulMode" | "HanjaMode" | "Zenkaku" | "Hankaku" | "ZenkakuHankaku" | LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey>;
 /**
  * Normalizes a key name to its canonical form.
  *

package/dist/format.d.ts

@@ -1,19 +1,5 @@
-import { Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
+import { ParsedHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
 //#region src/format.d.ts
-/**
- * Joins stored sequence steps with spaces, preserving physical code tokens.
- * For user-facing labels, call formatForDisplay on each step instead.
- *
- * @param sequence - Array of hotkey strings that form the sequence
- * @returns A space-separated string (e.g. ['G','G'] → 'G G')
- *
- * @example
- * ```ts
- * formatHotkeySequence(['G', 'G'])      // 'G G'
- * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
- * ```
- */
-export declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
 /**
  * Converts a ParsedHotkey back to a hotkey string.
  *
@@ -27,7 +13,10 @@ export declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
  * ```
  */
 export declare function formatHotkey(parsed: ParsedHotkey): string;
-export type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
+/** A single chord to display: a string, raw object, or parsed hotkey. */
+export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkey | (string & {});
+/** A hotkey to display: a chord or a sequence of chords. */
+export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChord>;
 /**
  * Formats a hotkey for display in a user interface.
  *
@@ -39,10 +28,12 @@ export type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
  * `[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
  * or change matching. Supply a resolved `layoutMap` for layout-aware labels;
  * `keyLabels` overrides both layout entries and fallback labels.
+ * Sequence steps are formatted individually and joined with `sequenceSeparator`
+ * (a space by default).
  *
- * @param hotkey - A logical or physical string, raw binding, or ParsedHotkey
+ * @param hotkey - A logical or physical string, raw object, ParsedHotkey, or sequence
  * @param options - Formatting options
- * @returns Display text, or individual key labels when parts is true
+ * @returns Display text, or individual key labels when parts is true (one array per step for sequences)
  *
  * @example
  * ```ts
@@ -54,19 +45,21 @@ export type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
  *
  * formatForDisplay('Escape')
  * // Returns: 'Esc' (on all platforms)
+ *
+ * formatForDisplay(['G', 'H'])
+ * // Returns: 'G H'
  * ```
  */
-export declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions & {
+export declare function formatForDisplay(hotkey: ReadonlyArray<DisplayHotkeyChord>, options: FormatDisplayOptions & {
+  parts: true;
+}): Array<Array<string>>;
+export declare function formatForDisplay(hotkey: DisplayHotkeyChord, options: FormatDisplayOptions & {
   parts: true;
 }): Array<string>;
 export declare function formatForDisplay(hotkey: DisplayHotkey, options?: FormatDisplayOptions & {
   parts?: false;
 }): string;
-export declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions): string | Array<string>;
-/**
- * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
- */
-export declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'>): string;
+export declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions): string | Array<string> | Array<Array<string>>;
 /**
  * Options for formatting hotkeys for display.
  */
@@ -93,5 +86,7 @@ export interface FormatDisplayOptions {
   keyLabels?: Readonly<Record<string, string>>;
   /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
   separatorToken?: string | null;
+  /** Separator between sequence steps. Default: a space. */
+  sequenceSeparator?: string;
 }
 //#endregion

package/dist/format.js

@@ -6,22 +6,6 @@ import { isModifierKey, normalizeHotkeyFromParsed, normalizeRegisterableHotkey }
 
 //#region src/format.ts
 /**
-* Joins stored sequence steps with spaces, preserving physical code tokens.
-* For user-facing labels, call formatForDisplay on each step instead.
-*
-* @param sequence - Array of hotkey strings that form the sequence
-* @returns A space-separated string (e.g. ['G','G'] → 'G G')
-*
-* @example
-* ```ts
-* formatHotkeySequence(['G', 'G'])      // 'G G'
-* formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
-* ```
-*/
-function formatHotkeySequence(sequence) {
-	return sequence.join(" ");
-}
-/**
 * Converts a ParsedHotkey back to a hotkey string.
 *
 * @param parsed - The parsed hotkey object
@@ -41,11 +25,26 @@ function formatHotkey(parsed) {
 	return parts.join("+");
 }
 function formatForDisplay(hotkey, options = {}) {
+	if (Array.isArray(hotkey)) {
+		const steps = hotkey.map((step) => formatChordParts(step, options));
+		return options.parts ? steps : steps.map((parts) => parts.join(chordSeparator(options))).join(options.sequenceSeparator ?? " ");
+	}
+	const parts = formatChordParts(hotkey, options);
+	return options.parts ? parts : parts.join(chordSeparator(options));
+}
+function modifierSymbolsEnabled(options) {
+	const symbols = options.useSymbols ?? true;
+	return typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
+}
+function chordSeparator(options) {
+	const platform = options.platform ?? detectPlatform();
+	return options.separatorToken ?? (platform === "mac" && modifierSymbolsEnabled(options) ? " " : "+");
+}
+function formatChordParts(hotkey, options) {
 	const platform = options.platform ?? detectPlatform();
 	const symbols = options.useSymbols ?? true;
-	const modifierSymbols = typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
+	const modifierSymbols = modifierSymbolsEnabled(options);
 	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;
-	const separator = options.separatorToken ?? (platform === "mac" && modifierSymbols ? " " : "+");
 	const normalized = typeof hotkey === "object" && "modifiers" in hotkey ? normalizeHotkeyFromParsed(hotkey, platform) : normalizeRegisterableHotkey(hotkey, platform);
 	const segments = splitHotkeyParts(normalized);
 	if (platform === "mac") {
@@ -55,7 +54,7 @@ function formatForDisplay(hotkey, options = {}) {
 		};
 		segments.sort((a, b) => modifierIndex(a) - modifierIndex(b));
 	}
-	const parts = segments.map((segment) => {
+	return segments.map((segment) => {
 		if (isModifierKey(segment)) {
 			const modifier = MODIFIER_ALIASES[segment] ?? MODIFIER_ALIASES[segment.toLowerCase()];
 			return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];
@@ -76,17 +75,7 @@ function formatForDisplay(hotkey, options = {}) {
 		const display = (keySymbols ? KEY_DISPLAY_SYMBOLS : PUNCTUATION_KEY_DISPLAY_LABELS)[displayKey] ?? displayKey;
 		return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
 	});
-	return options.parts ? parts : parts.join(separator);
-}
-/**
-* @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
-*/
-function formatWithLabels(hotkey, options = {}) {
-	return formatForDisplay(hotkey, {
-		...options,
-		useSymbols: false
-	});
 }
 
 //#endregion
-export { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
+export { formatForDisplay, formatHotkey };

package/dist/hint.d.ts

@@ -11,6 +11,7 @@ export interface HeldModifierOptions {
  * By default, any nonempty subset of the binding's modifiers qualifies; an
  * unrelated modifier hides the hint. `exact` requires every binding modifier.
  * Nonmodifier keys are ignored. This does not check registration or focus.
+ * A sequence reveals its hint from its first step.
  *
  * @example
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true

package/dist/hint.js

@@ -1,5 +1,5 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
-import { parseRegisterableHotkey } from "./parse.js";
+import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
 
 //#region src/hint.ts
 /**
@@ -7,6 +7,7 @@ import { parseRegisterableHotkey } from "./parse.js";
 * By default, any nonempty subset of the binding's modifiers qualifies; an
 * unrelated modifier hides the hint. `exact` requires every binding modifier.
 * Nonmodifier keys are ignored. This does not check registration or focus.
+* A sequence reveals its hint from its first step.
 *
 * @example
 * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
@@ -15,7 +16,9 @@ import { parseRegisterableHotkey } from "./parse.js";
 function matchesHeldModifiers(hotkey, heldKeys, options = {}) {
 	if (heldKeys.includes("AltGraph")) return false;
 	const held = [...new Set(heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)))];
-	const { modifiers } = parseRegisterableHotkey(hotkey, options.platform);
+	const first = isHotkeySequence(hotkey) ? hotkey[0] : hotkey;
+	if (first === void 0) return false;
+	const { modifiers } = parseRegisterableHotkey(first, options.platform);
 	return held.length > 0 && held.every((key) => modifiers.includes(key)) && (!options.exact || held.length === modifiers.length);
 }