@tanstack/hotkeys 0.15.0 → 0.16.0

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_ALIASES, MODIFIER_ORDER, PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+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, splitHotkeyParts } from "./_keyboard-event.js";
-import { isModifierKey, 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);
@@ -55,23 +46,16 @@ function formatChordParts(hotkey, options) {
 		segments.sort((a, b) => modifierIndex(a) - modifierIndex(b));
 	}
 	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];
-		}
-		const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(segment)?.[1];
+		const modifier = modifierAlias(segment);
+		if (modifier) return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];
+		const code = physicalCodeOf(segment);
 		const label = options.keyLabels?.[code ?? segment];
 		if (label !== void 0) return label;
 		const numpad = code?.startsWith("Numpad") ?? false;
 		let displayKey = code ?? segment;
 		const mappedKey = code ? options.layoutMap?.get(code) : void 0;
 		if (mappedKey) displayKey = normalizeKeyName(mappedKey);
-		else if (code) {
-			if (/^Key[A-Z]$/.test(code)) displayKey = code.slice(3);
-			else if (/^Digit[0-9]$/.test(code)) displayKey = code.slice(5);
-			else if (numpad) displayKey = code.slice(6);
-			else displayKey = PUNCTUATION_CODE_MAP[code] ?? code;
-		}
+		else if (code) displayKey = numpad ? code.slice(6) : codeToLogicalKey(code) ?? code;
 		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;
 	});

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);
 }
 

package/dist/hotkey-manager.d.ts

@@ -1,4 +1,4 @@
-import { ConflictBehavior, HotkeyCallback, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
+import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { AppHotkeysStore } from "./app-hotkeys.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
@@ -39,14 +39,30 @@ export interface HotkeyOptions {
   ignoreInputs?: boolean | 'auto';
   /** The target platform for resolving 'Mod' */
   platform?: 'mac' | 'windows' | 'linux';
-  /** Prevent the default browser action when the hotkey matches. Defaults to true */
+  /**
+   * Prevent the default browser action when the hotkey matches. For a
+   * sequence, every step that advances it does. Defaults to true
+   */
   preventDefault?: boolean;
-  /** Stop event propagation when the hotkey matches. Defaults to true */
+  /**
+   * Stop event propagation when the hotkey matches. For a sequence, only the
+   * last step does, so earlier steps reach other listeners. Defaults to true
+   */
   stopPropagation?: boolean;
   /** The DOM element to attach the event listener to. Defaults to document. */
   target?: Target | null;
   /** Optional metadata (name, description, custom fields via declaration merging) */
   meta?: HotkeyMeta;
+  /**
+   * Scope this hotkey belongs to. Defaults to `'global'`, which is always
+   * active. Other scopes are active while activated with
+   * `HotkeyManager.activateScope`, which framework providers do while
+   * mounted. While an exclusive scope is active, only its hotkeys, those of
+   * scopes nested in it, and those of scopes it allows fire.
+   * When active scopes share a hotkey on the same target, the most recently
+   * activated scope handles it.
+   */
+  scope?: string;
   /** Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`. */
   appHotkeyId?: string;
 }
@@ -64,7 +80,7 @@ export interface HotkeySequenceOptions extends HotkeyOptions {
  * The options type for a hotkey: chord options for chords (including one-step
  * tuples), sequence options for sequences.
  */
-export type HotkeyOptionsFor<T extends RegisterableHotkey> = [T] extends [never] ? HotkeyChordOptions & HotkeySequenceOptions : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordOptions : T extends HotkeySequence ? HotkeySequenceOptions : HotkeyChordOptions;
+export type HotkeyOptionsFor<T extends RegisterableHotkey> = [T] extends [never] ? HotkeyChordOptions & HotkeySequenceOptions : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordOptions : T extends RegisterableHotkeySequence ? HotkeySequenceOptions : HotkeyChordOptions;
 interface RegistrationBase<TOptions extends HotkeyOptions> {
   /** Unique identifier for this registration */
   id: string;
@@ -83,7 +99,7 @@ interface RegistrationBase<TOptions extends HotkeyOptions> {
 export interface HotkeyChordRegistration extends RegistrationBase<HotkeyChordOptions> {
   kind: 'chord';
   hotkey: HotkeyChord;
-  parsedHotkey: ParsedHotkey;
+  parsedChord: ParsedHotkeyChord;
   /** The concrete key/code that activated a requireReset registration. */
   activeMatch?: {
     key: string;
@@ -94,7 +110,7 @@ export interface HotkeyChordRegistration extends RegistrationBase<HotkeyChordOpt
 export interface HotkeySequenceRegistration extends RegistrationBase<HotkeySequenceOptions> {
   kind: 'sequence';
   hotkey: HotkeySequence;
-  parsedSequence: Array<ParsedHotkey>;
+  parsedSequence: Array<ParsedHotkeyChord>;
   /** Steps matched in the current attempt */
   currentIndex: number;
   /** `Date.now()` when the last step in the current attempt matched */
@@ -112,14 +128,14 @@ interface RegistrationViewBase {
 export interface HotkeyChordRegistrationView extends RegistrationViewBase {
   kind: 'chord';
   hotkey: HotkeyChord;
-  parsedHotkey: ParsedHotkey;
+  parsedChord: ParsedHotkeyChord;
   options: HotkeyChordOptions;
 }
 /** Public view of a sequence registration, without its callback. */
 export interface HotkeySequenceRegistrationView extends RegistrationViewBase {
   kind: 'sequence';
   hotkey: HotkeySequence;
-  parsedSequence: Array<ParsedHotkey>;
+  parsedSequence: Array<ParsedHotkeyChord>;
   options: HotkeySequenceOptions;
   /** Steps matched in the current attempt (0 when idle or just completed). */
   matchedStepCount: number;
@@ -172,6 +188,44 @@ export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = Hotke
   /** Unregister this hotkey */
   unregister: () => void;
 }
+/** Active hotkey scopes, published on `HotkeyManager.scopes`. */
+export interface HotkeyScopesState {
+  /**
+   * Activated scopes, lowest precedence first. `'global'` is always active
+   * and not listed.
+   */
+  active: ReadonlyArray<string>;
+  /** The exclusive scope that owns the keyboard, or `null` when none is active. */
+  exclusive: string | null;
+  /**
+   * Scopes the exclusive scope allows that are active, possibly including
+   * `'global'`. Empty when no scope is exclusive.
+   */
+  allowed: ReadonlyArray<string>;
+  /**
+   * Scopes that are active but cannot fire because another scope is
+   * exclusive, possibly including `'global'`.
+   */
+  suspended: ReadonlyArray<string>;
+}
+/** Options for `HotkeyManager.activateScope`. */
+export interface ActivateHotkeyScopeOptions {
+  /**
+   * Suspend every other scope, including `'global'`, until this activation is
+   * released. Scopes nested in this one stay active. Pass `{ allow }` to keep
+   * other scopes active too, such as `{ allow: ['global'] }`. An allowed scope
+   * still has to be activated, except `'global'`.
+   */
+  exclusive?: boolean | {
+    allow: ReadonlyArray<string>;
+  };
+  /**
+   * The scope this one is nested in. A nested scope takes precedence over its
+   * ancestors even when it was activated first, as nested providers are when
+   * their effects run child-first. Defaults to `'global'`.
+   */
+  parent?: string;
+}
 /**
  * Singleton manager for hotkey registrations, including sequences.
  *
@@ -225,6 +279,8 @@ export declare class HotkeyManager {
    * devtools can list declared hotkeys that are not registered.
    */
   readonly appHotkeys: Store<AppHotkeysStore | null>;
+  /** Active scopes. Subscribe to show which hotkeys are suspended. */
+  readonly scopes: Store<HotkeyScopesState>;
   private constructor();
   /**
    * Gets the singleton instance of HotkeyManager.
@@ -234,17 +290,44 @@ export declare class HotkeyManager {
    * Resets the singleton instance. Useful for testing.
    */
   static resetInstance(): void;
+  /**
+   * Activates a scope until the returned function is called. Activations are
+   * counted, so a scope stays active until every activation is released.
+   * Framework providers call this while mounted.
+   *
+   * When active scopes share a hotkey, a nested scope takes precedence over
+   * its ancestors, and otherwise the most recently activated scope wins. The
+   * same order picks the exclusive scope when several are active, and only
+   * that scope's `allow` list applies.
+   *
+   * @example
+   * ```ts
+   * const release = manager.activateScope('dialog', { exclusive: true })
+   * // Only hotkeys with scope 'dialog', or scopes nested in it, fire now.
+   * release()
+   *
+   * manager.activateScope('dialog', { exclusive: { allow: ['global'] } })
+   * // Hotkeys with scope 'global' fire too.
+   * ```
+   */
+  activateScope(scope: string, options?: ActivateHotkeyScopeOptions): () => void;
+  /**
+   * Whether hotkeys in a scope can fire: the scope is `'global'` or
+   * activated, and either no scope is exclusive or this scope is the
+   * exclusive one, nested in it, or allowed by it.
+   */
+  isScopeActive(scope?: string): boolean;
   /**
    * Registers a hotkey handler and returns a handle for updating the registration.
    *
-   * Pass a chord (`'Mod+S'` or a RawHotkey object) or a sequence (`['G', 'G']`).
+   * Pass a chord (`'Mod+S'` or a RawHotkeyChord object) or a sequence (`['G', 'G']`).
    * A one-step sequence registers as its chord. Chords accept `requireReset`;
    * sequences accept `timeout`.
    *
    * The returned handle allows updating the callback and options without
    * re-registering, which is useful for avoiding stale closures in React.
    *
-   * @param hotkey - A chord string, RawHotkey object, or sequence
+   * @param hotkey - A chord string, RawHotkeyChord object, or sequence
    * @param callback - The function to call when the hotkey is pressed
    * @param options - Options for the hotkey behavior
    * @returns A handle for managing the registration
@@ -263,7 +346,7 @@ export declare class HotkeyManager {
    * handle.unregister()
    * ```
    */
-  register<T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback, options?: HotkeyOptionsFor<T>): HotkeyRegistrationHandle<HotkeyOptionsFor<T>>;
+  register<const T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: HotkeyOptionsFor<T>): HotkeyRegistrationHandle<HotkeyOptionsFor<T>>;
   /**
    * Resets the progress of every in-progress sequence.
    */