@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/hotkey-manager.d.cts

@@ -0,0 +1,207 @@
+import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.cjs";
+import { Store } from "@tanstack/store";
+
+//#region src/hotkey-manager.d.ts
+/**
+ * Behavior when registering a hotkey that conflicts with an existing registration.
+ *
+ * - `'warn'` - Log a warning to the console but allow both registrations (default)
+ * - `'error'` - Throw an error and prevent the new registration
+ * - `'replace'` - Unregister the existing hotkey and register the new one
+ * - `'allow'` - Allow multiple registrations of the same hotkey without warning
+ */
+type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
+/**
+ * Options for registering a hotkey.
+ */
+interface HotkeyOptions {
+  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
+  conflictBehavior?: ConflictBehavior;
+  /** Whether the hotkey is enabled. Defaults to true */
+  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 */
+  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;
+}
+/**
+ * A registered hotkey handler in the HotkeyManager.
+ */
+interface HotkeyRegistration {
+  /** The callback to invoke */
+  callback: HotkeyCallback;
+  /** Whether this registration has fired and needs reset (for requireReset) */
+  hasFired: boolean;
+  /** 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;
+}
+/**
+ * A handle returned from HotkeyManager.register() that allows updating
+ * the callback and options without re-registering the hotkey.
+ *
+ * @example
+ * ```ts
+ * const handle = manager.register('Mod+S', callback, options)
+ *
+ * // Update callback without re-registering (avoids stale closures)
+ * handle.callback = newCallback
+ *
+ * // Update options without re-registering
+ * handle.setOptions({ enabled: false })
+ *
+ * // Check if still active
+ * if (handle.isActive) {
+ *   // ...
+ * }
+ *
+ * // Unregister when done
+ * handle.unregister()
+ * ```
+ */
+interface HotkeyRegistrationHandle {
+  /**
+   * The callback function. Can be set directly to update without re-registering.
+   * This avoids stale closures when the callback references React state.
+   */
+  callback: HotkeyCallback;
+  /** Unique identifier for this registration */
+  readonly id: string;
+  /** Check if this registration is still active (not unregistered) */
+  readonly isActive: boolean;
+  /**
+   * Update options (merged with existing options).
+   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
+   */
+  setOptions: (options: Partial<HotkeyOptions>) => void;
+  /** Unregister this hotkey */
+  unregister: () => void;
+}
+/**
+ * Singleton manager for hotkey registrations.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const manager = HotkeyManager.getInstance()
+ *
+ * const unregister = manager.register('Mod+S', (event, context) => {
+ *   console.log('Save triggered!')
+ * })
+ *
+ * // Later, to unregister:
+ * unregister()
+ * ```
+ */
+declare class HotkeyManager {
+  #private;
+  /**
+   * The TanStack Store containing all hotkey registrations.
+   * Use this to subscribe to registration changes or access current registrations.
+   *
+   * @example
+   * ```ts
+   * const manager = HotkeyManager.getInstance()
+   *
+   * // Subscribe to registration changes
+   * const unsubscribe = manager.registrations.subscribe(() => {
+   *   console.log('Registrations changed:', manager.registrations.state.size)
+   * })
+   *
+   * // Access current registrations
+   * for (const [id, reg] of manager.registrations.state) {
+   *   console.log(reg.hotkey, reg.options.enabled)
+   * }
+   * ```
+   */
+  readonly registrations: Store<Map<string, HotkeyRegistration>>;
+  private constructor();
+  /**
+   * Gets the singleton instance of HotkeyManager.
+   */
+  static getInstance(): HotkeyManager;
+  /**
+   * Resets the singleton instance. Useful for testing.
+   */
+  static resetInstance(): void;
+  /**
+   * Registers a hotkey handler and returns a handle for updating the registration.
+   *
+   * 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 callback - The function to call when the hotkey is pressed
+   * @param options - Options for the hotkey behavior
+   * @returns A handle for managing the registration
+   *
+   * @example
+   * ```ts
+   * const handle = manager.register('Mod+S', callback)
+   *
+   * // Update callback without re-registering (avoids stale closures)
+   * handle.callback = newCallback
+   *
+   * // Update options
+   * handle.setOptions({ enabled: false })
+   *
+   * // Unregister when done
+   * handle.unregister()
+   * ```
+   */
+  register(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: HotkeyOptions): HotkeyRegistrationHandle;
+  /**
+   * Triggers a registration's callback programmatically from devtools.
+   * Creates a synthetic KeyboardEvent 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.
+   */
+  getRegistrationCount(): number;
+  /**
+   * Checks if a specific hotkey is registered.
+   *
+   * @param hotkey - The hotkey string 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;
+  /**
+   * Destroys the manager and removes all listeners.
+   */
+  destroy(): void;
+}
+/**
+ * Gets the singleton HotkeyManager instance.
+ * Convenience function for accessing the manager.
+ */
+declare function getHotkeyManager(): HotkeyManager;
+//#endregion
+export { ConflictBehavior, HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
+//# sourceMappingURL=hotkey-manager.d.cts.map

package/dist/hotkey-manager.d.ts

@@ -0,0 +1,207 @@
+import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
+import { Store } from "@tanstack/store";
+
+//#region src/hotkey-manager.d.ts
+/**
+ * Behavior when registering a hotkey that conflicts with an existing registration.
+ *
+ * - `'warn'` - Log a warning to the console but allow both registrations (default)
+ * - `'error'` - Throw an error and prevent the new registration
+ * - `'replace'` - Unregister the existing hotkey and register the new one
+ * - `'allow'` - Allow multiple registrations of the same hotkey without warning
+ */
+type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
+/**
+ * Options for registering a hotkey.
+ */
+interface HotkeyOptions {
+  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
+  conflictBehavior?: ConflictBehavior;
+  /** Whether the hotkey is enabled. Defaults to true */
+  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 */
+  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;
+}
+/**
+ * A registered hotkey handler in the HotkeyManager.
+ */
+interface HotkeyRegistration {
+  /** The callback to invoke */
+  callback: HotkeyCallback;
+  /** Whether this registration has fired and needs reset (for requireReset) */
+  hasFired: boolean;
+  /** 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;
+}
+/**
+ * A handle returned from HotkeyManager.register() that allows updating
+ * the callback and options without re-registering the hotkey.
+ *
+ * @example
+ * ```ts
+ * const handle = manager.register('Mod+S', callback, options)
+ *
+ * // Update callback without re-registering (avoids stale closures)
+ * handle.callback = newCallback
+ *
+ * // Update options without re-registering
+ * handle.setOptions({ enabled: false })
+ *
+ * // Check if still active
+ * if (handle.isActive) {
+ *   // ...
+ * }
+ *
+ * // Unregister when done
+ * handle.unregister()
+ * ```
+ */
+interface HotkeyRegistrationHandle {
+  /**
+   * The callback function. Can be set directly to update without re-registering.
+   * This avoids stale closures when the callback references React state.
+   */
+  callback: HotkeyCallback;
+  /** Unique identifier for this registration */
+  readonly id: string;
+  /** Check if this registration is still active (not unregistered) */
+  readonly isActive: boolean;
+  /**
+   * Update options (merged with existing options).
+   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
+   */
+  setOptions: (options: Partial<HotkeyOptions>) => void;
+  /** Unregister this hotkey */
+  unregister: () => void;
+}
+/**
+ * Singleton manager for hotkey registrations.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const manager = HotkeyManager.getInstance()
+ *
+ * const unregister = manager.register('Mod+S', (event, context) => {
+ *   console.log('Save triggered!')
+ * })
+ *
+ * // Later, to unregister:
+ * unregister()
+ * ```
+ */
+declare class HotkeyManager {
+  #private;
+  /**
+   * The TanStack Store containing all hotkey registrations.
+   * Use this to subscribe to registration changes or access current registrations.
+   *
+   * @example
+   * ```ts
+   * const manager = HotkeyManager.getInstance()
+   *
+   * // Subscribe to registration changes
+   * const unsubscribe = manager.registrations.subscribe(() => {
+   *   console.log('Registrations changed:', manager.registrations.state.size)
+   * })
+   *
+   * // Access current registrations
+   * for (const [id, reg] of manager.registrations.state) {
+   *   console.log(reg.hotkey, reg.options.enabled)
+   * }
+   * ```
+   */
+  readonly registrations: Store<Map<string, HotkeyRegistration>>;
+  private constructor();
+  /**
+   * Gets the singleton instance of HotkeyManager.
+   */
+  static getInstance(): HotkeyManager;
+  /**
+   * Resets the singleton instance. Useful for testing.
+   */
+  static resetInstance(): void;
+  /**
+   * Registers a hotkey handler and returns a handle for updating the registration.
+   *
+   * 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 callback - The function to call when the hotkey is pressed
+   * @param options - Options for the hotkey behavior
+   * @returns A handle for managing the registration
+   *
+   * @example
+   * ```ts
+   * const handle = manager.register('Mod+S', callback)
+   *
+   * // Update callback without re-registering (avoids stale closures)
+   * handle.callback = newCallback
+   *
+   * // Update options
+   * handle.setOptions({ enabled: false })
+   *
+   * // Unregister when done
+   * handle.unregister()
+   * ```
+   */
+  register(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: HotkeyOptions): HotkeyRegistrationHandle;
+  /**
+   * Triggers a registration's callback programmatically from devtools.
+   * Creates a synthetic KeyboardEvent 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.
+   */
+  getRegistrationCount(): number;
+  /**
+   * Checks if a specific hotkey is registered.
+   *
+   * @param hotkey - The hotkey string 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;
+  /**
+   * Destroys the manager and removes all listeners.
+   */
+  destroy(): void;
+}
+/**
+ * Gets the singleton HotkeyManager instance.
+ * Convenience function for accessing the manager.
+ */
+declare function getHotkeyManager(): HotkeyManager;
+//#endregion
+export { ConflictBehavior, HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
+//# sourceMappingURL=hotkey-manager.d.ts.map