@tanstack/hotkeys 0.11.0 → 0.12.0

package/dist/hotkey-manager.d.ts

@@ -1,8 +1,11 @@
-import { ConflictBehavior, Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
+import { ConflictBehavior, HotkeyCallback, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
+import { AppHotkeysStore } from "./app-hotkeys.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
+/** An element, document, or window that hotkeys can listen on. */
+export type Target = HTMLElement | Document | Window;
 /**
- * Options for registering a hotkey.
+ * Options shared by chords and sequences.
  */
 export interface HotkeyOptions {
   /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
@@ -15,71 +18,103 @@ export interface HotkeyOptions {
   enabled?: boolean;
   /** The event type to listen for. Defaults to 'keydown' */
   eventType?: 'keydown' | 'keyup';
-  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */
+  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on the hotkey (the first step of a sequence): true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */
   ignoreInputs?: boolean;
   /** The target platform for resolving 'Mod' */
   platform?: 'mac' | 'windows' | 'linux';
   /** Prevent the default browser action when the hotkey matches. Defaults to true */
   preventDefault?: boolean;
-  /** If true, only trigger once until all keys are released. Default: false */
-  requireReset?: boolean;
   /** Stop event propagation when the hotkey matches. Defaults to true */
   stopPropagation?: boolean;
   /** The DOM element to attach the event listener to. Defaults to document. */
-  target?: HTMLElement | Document | Window | null;
+  target?: Target | null;
   /** Optional metadata (name, description, custom fields via declaration merging) */
   meta?: HotkeyMeta;
+  /** Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`. */
+  appHotkeyId?: string;
+}
+/** Options for a single chord such as `'Mod+S'`. */
+export interface HotkeyChordOptions extends HotkeyOptions {
+  /** If true, only trigger once until all keys are released. Default: false */
+  requireReset?: boolean;
+}
+/** Options for a sequence such as `['G', 'G']`. */
+export interface HotkeySequenceOptions extends HotkeyOptions {
+  /** Maximum time between steps in milliseconds. Default: 1000 */
+  timeout?: number;
 }
 /**
- * A registered hotkey handler in the HotkeyManager.
+ * The options type for a hotkey: chord options for chords (including one-step
+ * tuples), sequence options for sequences.
  */
-export interface HotkeyRegistration {
+export type HotkeyOptionsFor<T extends RegisterableHotkey> = [T] extends [never] ? HotkeyChordOptions & HotkeySequenceOptions : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordOptions : T extends HotkeySequence ? HotkeySequenceOptions : HotkeyChordOptions;
+interface RegistrationBase<TOptions extends HotkeyOptions> {
+  /** Unique identifier for this registration */
+  id: string;
   /** The callback to invoke */
   callback: HotkeyCallback;
-  /** Whether this registration has fired and needs reset (for requireReset) */
+  /** Resolved options for this registration */
+  options: TOptions;
+  /** The resolved target element for this registration */
+  target: Target;
+  /** How many times this registration's callback has been triggered */
+  triggerCount: number;
+  /** Whether this registration has fired (and, for requireReset chords, needs a reset) */
   hasFired: boolean;
+}
+/** A registered chord in the HotkeyManager. */
+export interface HotkeyChordRegistration extends RegistrationBase<HotkeyChordOptions> {
+  kind: 'chord';
+  hotkey: HotkeyChord;
+  parsedHotkey: ParsedHotkey;
   /** The concrete key/code that activated a requireReset registration. */
   activeMatch?: {
     key: string;
     code: string;
   };
-  /** The original hotkey string */
-  hotkey: Hotkey;
-  /** Unique identifier for this registration */
-  id: string;
-  /** Options for this registration */
-  options: HotkeyOptions;
-  /** The parsed hotkey */
-  parsedHotkey: ParsedHotkey;
-  /** The resolved target element for this registration */
-  target: HTMLElement | Document | Window;
-  /** How many times this registration's callback has been triggered */
-  triggerCount: number;
 }
-/**
- * Public view of a hotkey registration for display and introspection.
- * Omits the callback function which is an internal implementation detail.
- */
-export interface HotkeyRegistrationView {
-  /** The original hotkey string */
-  hotkey: Hotkey;
-  /** Unique identifier for this registration */
+/** A registered sequence in the HotkeyManager. */
+export interface HotkeySequenceRegistration extends RegistrationBase<HotkeySequenceOptions> {
+  kind: 'sequence';
+  hotkey: HotkeySequence;
+  parsedSequence: Array<ParsedHotkey>;
+  /** Steps matched in the current attempt */
+  currentIndex: number;
+  /** `Date.now()` when the last step in the current attempt matched */
+  lastKeyTime: number;
+}
+/** A registered hotkey in the HotkeyManager. */
+export type HotkeyRegistration = HotkeyChordRegistration | HotkeySequenceRegistration;
+interface RegistrationViewBase {
   id: string;
-  /** Options for this registration */
-  options: HotkeyOptions;
-  /** The parsed hotkey */
-  parsedHotkey: ParsedHotkey;
-  /** The resolved target element for this registration */
-  target: HTMLElement | Document | Window;
-  /** How many times this registration's callback has been triggered */
+  target: Target;
   triggerCount: number;
-  /** Whether this registration has fired and needs reset (for requireReset) */
   hasFired: boolean;
 }
+/** Public view of a chord registration, without its callback. */
+export interface HotkeyChordRegistrationView extends RegistrationViewBase {
+  kind: 'chord';
+  hotkey: HotkeyChord;
+  parsedHotkey: ParsedHotkey;
+  options: HotkeyChordOptions;
+}
+/** Public view of a sequence registration, without its callback. */
+export interface HotkeySequenceRegistrationView extends RegistrationViewBase {
+  kind: 'sequence';
+  hotkey: HotkeySequence;
+  parsedSequence: Array<ParsedHotkey>;
+  options: HotkeySequenceOptions;
+  /** Steps matched in the current attempt (0 when idle or just completed). */
+  matchedStepCount: number;
+  /** `Date.now()` when the last step in the current attempt matched; 0 if none. */
+  partialMatchLastKeyTime: number;
+}
 /**
- * Creates a public view from an internal registration,
- * stripping the callback function.
+ * Public view of a hotkey registration for display and introspection.
+ * Narrow with `kind` to read chord- or sequence-specific fields.
  */
+export type HotkeyRegistrationView = HotkeyChordRegistrationView | HotkeySequenceRegistrationView;
+/** Creates a public view from an internal registration, stripping the callback. */
 export declare function toHotkeyRegistrationView(reg: HotkeyRegistration): HotkeyRegistrationView;
 /**
  * A handle returned from HotkeyManager.register() that allows updating
@@ -95,16 +130,11 @@ export declare function toHotkeyRegistrationView(reg: HotkeyRegistration): Hotke
  * // Update options without re-registering
  * handle.setOptions({ enabled: false })
  *
- * // Check if still active
- * if (handle.isActive) {
- *   // ...
- * }
- *
  * // Unregister when done
  * handle.unregister()
  * ```
  */
-export interface HotkeyRegistrationHandle {
+export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = HotkeyChordOptions | HotkeySequenceOptions> {
   /**
    * The callback function. Can be set directly to update without re-registering.
    * This avoids stale closures when the callback references React state.
@@ -118,33 +148,40 @@ export interface HotkeyRegistrationHandle {
    * Update options (merged with existing options).
    * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
    */
-  setOptions: (options: Partial<HotkeyOptions>) => void;
+  setOptions: (options: Partial<TOptions>) => void;
   /** Unregister this hotkey */
   unregister: () => void;
 }
 /**
- * Singleton manager for hotkey registrations.
+ * Singleton manager for hotkey registrations, including sequences.
  *
- * This class provides a centralized way to register and manage keyboard hotkeys.
- * It uses a single event listener for efficiency, regardless of how many hotkeys
- * are registered.
+ * This class provides a centralized way to register and manage keyboard
+ * hotkeys. It attaches one keydown and one keyup listener per target,
+ * regardless of how many hotkeys are registered.
+ *
+ * Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
+ * pressed within the timeout. Modifier-only events (Shift, Control, Alt, or
+ * Meta alone) neither advance nor reset a sequence, so chained modifier chords
+ * such as `['Shift+R', 'Shift+T']` work.
  *
  * @example
  * ```ts
  * const manager = HotkeyManager.getInstance()
  *
- * const unregister = manager.register('Mod+S', (event, context) => {
+ * const save = manager.register('Mod+S', (event, context) => {
  *   console.log('Save triggered!')
  * })
+ * const top = manager.register(['G', 'G'], () => scrollToTop(), { timeout: 500 })
  *
  * // Later, to unregister:
- * unregister()
+ * save.unregister()
+ * top.unregister()
  * ```
  */
 export declare class HotkeyManager {
   #private;
   /**
-   * The TanStack Store containing all hotkey registrations.
+   * The TanStack Store containing all hotkey registrations, chords and sequences.
    * Use this to subscribe to registration changes or access current registrations.
    *
    * @example
@@ -163,6 +200,11 @@ export declare class HotkeyManager {
    * ```
    */
   readonly registrations: Store<Map<string, HotkeyRegistration>>;
+  /**
+   * The app hotkeys store published by a framework provider, so tools such as
+   * devtools can list declared hotkeys that are not registered.
+   */
+  readonly appHotkeys: Store<AppHotkeysStore | null>;
   private constructor();
   /**
    * Gets the singleton instance of HotkeyManager.
@@ -175,10 +217,14 @@ export declare class HotkeyManager {
   /**
    * 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']`).
+   * 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 - The hotkey string (e.g., 'Mod+S') or RawHotkey object
+   * @param hotkey - A chord string, RawHotkey 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
@@ -197,27 +243,32 @@ export declare class HotkeyManager {
    * handle.unregister()
    * ```
    */
-  register(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: HotkeyOptions): HotkeyRegistrationHandle;
+  register<T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback, options?: HotkeyOptionsFor<T>): HotkeyRegistrationHandle<HotkeyOptionsFor<T>>;
+  /**
+   * Resets the progress of every in-progress sequence.
+   */
+  resetSequenceProgress(): void;
   /**
    * Triggers a registration's callback programmatically from devtools.
-   * Creates a synthetic KeyboardEvent and invokes the callback.
+   * Creates a synthetic KeyboardEvent from the chord (or a sequence's last step)
+   * and invokes the callback.
    *
    * @param id - The registration ID to trigger
    * @returns True if the registration was found and triggered
    */
   triggerRegistration(id: string): boolean;
   /**
-   * Gets the number of registered hotkeys.
+   * Gets the number of registered hotkeys, chords and sequences.
    */
   getRegistrationCount(): number;
   /**
    * Checks if a specific hotkey is registered.
    *
-   * @param hotkey - The hotkey string to check
+   * @param hotkey - The chord or sequence to check
    * @param target - Optional target element to match (if provided, both hotkey and target must match)
    * @returns True if a matching registration exists
    */
-  isRegistered(hotkey: Hotkey, target?: HTMLElement | Document | Window): boolean;
+  isRegistered(hotkey: RegisterableHotkey, target?: Target): boolean;
   /**
    * Destroys the manager and removes all listeners.
    */