@tanstack/hotkeys 0.4.3 → 0.6.0

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './hotkey-manager'
 export * from './key-state-tracker'
 export * from './match'
 export * from './parse'
-export * from './recorder'
+export * from './hotkey-recorder'
+export * from './hotkey-sequence-recorder'
 export * from './sequence-manager'
 export * from './validate'

package/src/parse.ts

@@ -11,6 +11,7 @@ import type {
   Key,
   ParsedHotkey,
   RawHotkey,
+  RegisterableHotkey,
 } from './hotkey'
 
 /**
@@ -137,53 +138,110 @@ export function rawHotkeyToParsedHotkey(
   }
 }
 
+/**
+ * Serializes a parsed hotkey to the canonical string form used for registration
+ * and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;
+ * otherwise full `Control+Alt+Shift+Meta` order.
+ */
+function normalizedHotkeyStringFromParsed(
+  parsed: ParsedHotkey,
+  platform: 'mac' | 'windows' | 'linux',
+): Hotkey {
+  const canUseMod =
+    platform === 'mac'
+      ? parsed.meta && !parsed.ctrl
+      : parsed.ctrl && !parsed.meta
+
+  const parts: Array<string> = []
+
+  if (canUseMod) {
+    parts.push('Mod')
+    if (parsed.alt) {
+      parts.push('Alt')
+    }
+    if (parsed.shift) {
+      parts.push('Shift')
+    }
+  } else {
+    for (const modifier of MODIFIER_ORDER) {
+      if (parsed.modifiers.includes(modifier)) {
+        parts.push(modifier)
+      }
+    }
+  }
+
+  parts.push(normalizeKeyName(parsed.key))
+  return parts.join('+') as Hotkey
+}
+
 /**
  * Normalizes a hotkey string to its canonical form.
  *
- * The canonical form uses:
- * - Full modifier names (Control, Alt, Shift, Meta)
- * - Modifiers in order: Control+Alt+Shift+Meta
- * - Uppercase letters for single-character keys
- * - Proper casing for special keys (Escape, not escape)
+ * - When `Mod` is allowed for the platform (Command on Mac without Control;
+ *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
+ *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
+ * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
+ * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
  *
  * @param hotkey - The hotkey string to normalize
- * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
  * @returns The normalized hotkey string
  *
  * @example
  * ```ts
- * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
- * normalizeHotkey('ctrl+a') // 'Control+A'
+ * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
+ * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
  * normalizeHotkey('esc') // 'Escape'
  * ```
  */
 export function normalizeHotkey(
   hotkey: Key | (string & {}),
   platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
-): string {
-  const parsed = parseHotkey(hotkey, platform)
-  const parts: Array<string> = []
-
-  // Add modifiers in canonical order
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(modifier)
-    }
-  }
+): Hotkey {
+  return normalizedHotkeyStringFromParsed(
+    parseHotkey(hotkey, platform),
+    platform,
+  )
+}
 
-  // Add the key
-  parts.push(parsed.key)
+/**
+ * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
+ */
+export function normalizeHotkeyFromParsed(
+  parsed: ParsedHotkey,
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): Hotkey {
+  return normalizedHotkeyStringFromParsed(parsed, platform)
+}
 
-  return parts.join('+')
+/**
+ * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+ * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+ */
+export function normalizeRegisterableHotkey(
+  hotkey: RegisterableHotkey,
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): Hotkey {
+  return typeof hotkey === 'string'
+    ? normalizeHotkey(hotkey, platform)
+    : normalizeHotkeyFromParsed(
+        rawHotkeyToParsedHotkey(hotkey, platform),
+        platform,
+      )
 }
 
 /**
- * Checks if a string represents a modifier key.
+ * Checks if a string is a recognized modifier token (including aliases).
+ *
+ * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
+ * spellings like `OS` / `Win` match the same alias table.
  *
- * @param key - The string to check
+ * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-export function isModifier(key: string): boolean {
+export function isModifierKey(
+  key: Key | (string & {}),
+): key is keyof typeof MODIFIER_ALIASES {
   return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES
 }
 
@@ -226,72 +284,16 @@ export function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {
 }
 
 /**
- * Converts a KeyboardEvent directly to a hotkey string.
- *
- * This is a convenience function that combines `parseKeyboardEvent()` and formatting.
- * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
- * and is suitable for use with `useHotkey()` and other hotkey functions.
- *
- * @param event - The KeyboardEvent to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
+ * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   const hotkey = keyboardEventToHotkey(event)
- *   console.log(hotkey) // 'Control+Shift+S'
- *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
- * })
- * ```
- */
-export function keyboardEventToHotkey(event: KeyboardEvent): Hotkey {
-  const parsed = parseKeyboardEvent(event)
-
-  // Build hotkey string in canonical order (same as formatHotkey)
-  const parts: Array<string> = []
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(modifier)
-    }
-  }
-  parts.push(parsed.key)
-
-  return parts.join('+') as Hotkey
-}
-
-/**
- * Checks if a KeyboardEvent represents a modifier-only key press.
- *
- * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
- * that don't have an associated character or action key. This is useful
- * for filtering out modifier key presses when recording shortcuts.
- *
- * @param event - The KeyboardEvent to check
- * @returns True if the event represents a modifier-only key
- *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   if (isModifierKey(event)) {
- *     console.log('Modifier key pressed, waiting for action key...')
- *     return
- *   }
- *   // Process non-modifier key
- * })
- * ```
+ * @param event - The keyboard event (typically `keydown`)
+ * @param platform - Target platform for `Mod` eligibility
  */
-export function isModifierKey(event: KeyboardEvent): boolean {
-  const key = event.key
-  return (
-    key === 'Control' ||
-    key === 'Shift' ||
-    key === 'Alt' ||
-    key === 'Meta' ||
-    key === 'Command' ||
-    key === 'OS' ||
-    key === 'Win'
-  )
+export function normalizeHotkeyFromEvent(
+  event: KeyboardEvent,
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): Hotkey {
+  return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform)
 }
 
 /**
@@ -319,50 +321,8 @@ export function hasNonModifierKey(
     typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
 
   // Check if the key part is actually a modifier
-  const keyIsModifier = isModifier(parsed.key)
+  const keyIsModifier = isModifierKey(parsed.key)
 
   // A valid hotkey must have a non-modifier key
   return !keyIsModifier && parsed.key.length > 0
 }
-
-/**
- * Converts a hotkey string to use 'Mod' format for portability.
- *
- * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
- * This enables cross-platform hotkey definitions that work consistently.
- *
- * @param hotkey - The hotkey string to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns The hotkey string with 'Mod' format applied
- *
- * @example
- * ```ts
- * convertToModFormat('Meta+S', 'mac') // 'Mod+S'
- * convertToModFormat('Control+S', 'windows') // 'Mod+S'
- * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
- * ```
- */
-export function convertToModFormat(
-  hotkey: Hotkey | (string & {}),
-  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
-): Hotkey {
-  const parsed = parseHotkey(hotkey, platform)
-
-  // Only convert if we have exactly one primary modifier
-  if (platform === 'mac' && parsed.meta && !parsed.ctrl) {
-    // Convert Meta to Mod on Mac
-    const parts = hotkey.split('+')
-    return parts
-      .map((part) => (part === 'Meta' ? 'Mod' : part))
-      .join('+') as Hotkey
-  } else if (platform !== 'mac' && parsed.ctrl && !parsed.meta) {
-    // Convert Control to Mod on Windows/Linux
-    const parts = hotkey.split('+')
-    return parts
-      .map((part) => (part === 'Control' ? 'Mod' : part))
-      .join('+') as Hotkey
-  }
-
-  // No conversion needed
-  return hotkey as Hotkey
-}

package/src/recorder-chord.ts

@@ -0,0 +1,25 @@
+import { normalizeKeyName } from './constants'
+import {
+  hasNonModifierKey,
+  isModifierKey,
+  normalizeHotkeyFromEvent,
+} from './parse'
+import type { Hotkey } from './hotkey'
+
+/**
+ * Parses a keydown event into a single normalized hotkey chord, or null if
+ * the event should be ignored (modifier-only or invalid).
+ */
+export function hotkeyChordFromKeydown(
+  event: KeyboardEvent,
+  platform: 'mac' | 'windows' | 'linux',
+): Hotkey | null {
+  if (isModifierKey(normalizeKeyName(event.key))) {
+    return null
+  }
+  const finalHotkey = normalizeHotkeyFromEvent(event, platform)
+  if (!hasNonModifierKey(finalHotkey, platform)) {
+    return null
+  }
+  return finalHotkey
+}

package/src/sequence-manager.ts

@@ -1,6 +1,6 @@
 import { Store } from '@tanstack/store'
 import { formatHotkeySequence } from './format'
-import { detectPlatform } from './constants'
+import { detectPlatform, normalizeKeyName } from './constants'
 import { isModifierKey, parseHotkey } from './parse'
 import { matchesKeyboardEvent } from './match'
 import {
@@ -49,8 +49,9 @@ export type HotkeySequence = Array<Hotkey>
 
 /**
  * Default timeout between keys in a sequence (in milliseconds).
+ * Exported for consumers that display sequence state (e.g. devtools).
  */
-const DEFAULT_SEQUENCE_TIMEOUT = 1000
+export const DEFAULT_SEQUENCE_TIMEOUT = 1000
 
 let sequenceIdCounter = 0
 
@@ -70,7 +71,7 @@ function sequenceKey(sequence: HotkeySequence): string {
 
 /**
  * View of a sequence registration for devtools display.
- * Excludes internal matching state (currentIndex, lastKeyTime).
+ * Progress fields reflect an in-progress match (between first key and completion or timeout).
  */
 export interface SequenceRegistrationView {
   id: string
@@ -78,6 +79,10 @@ export interface SequenceRegistrationView {
   options: SequenceOptions
   target: Target
   triggerCount: number
+  /** 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
 }
 
 /**
@@ -147,12 +152,16 @@ export interface SequenceRegistrationHandle {
 function toRegistrationView(
   reg: SequenceRegistration,
 ): SequenceRegistrationView {
+  const len = reg.parsedSequence.length
+  const inProgress = reg.currentIndex > 0 && reg.currentIndex < len
   return {
     id: reg.id,
     sequence: reg.sequence,
     options: reg.options,
     target: reg.target,
     triggerCount: reg.triggerCount,
+    matchedStepCount: inProgress ? reg.currentIndex : 0,
+    partialMatchLastKeyTime: inProgress ? reg.lastKeyTime : 0,
   }
 }
 
@@ -201,6 +210,12 @@ export class SequenceManager {
     }
   }
 
+  #syncRegistrationView(registration: SequenceRegistration): void {
+    this.registrations.setState((prev) =>
+      new Map(prev).set(registration.id, toRegistrationView(registration)),
+    )
+  }
+
   /**
    * Registers a hotkey sequence handler.
    *
@@ -419,7 +434,7 @@ export class SequenceManager {
     eventType: 'keydown' | 'keyup',
   ): void {
     // Skip modifier-only events so pressing e.g. Shift before Shift+C does not reset the sequence.
-    if (isModifierKey(event)) {
+    if (isModifierKey(normalizeKeyName(event.key))) {
       return
     }
 
@@ -467,6 +482,7 @@ export class SequenceManager {
         now - registration.lastKeyTime > timeout
       ) {
         registration.currentIndex = 0
+        this.#syncRegistrationView(registration)
       }
 
       const expectedHotkey =
@@ -501,9 +517,14 @@ export class SequenceManager {
               ]!,
           }
 
-          registration.callback(event, context)
-
+          registration.triggerCount++
           registration.currentIndex = 0
+
+          this.#syncRegistrationView(registration)
+
+          registration.callback(event, context)
+        } else {
+          this.#syncRegistrationView(registration)
         }
       } else if (registration.currentIndex > 0) {
         const firstHotkey = registration.parsedSequence[0]!
@@ -519,6 +540,7 @@ export class SequenceManager {
         } else {
           registration.currentIndex = 0
         }
+        this.#syncRegistrationView(registration)
       }
     }
   }
@@ -549,6 +571,7 @@ export class SequenceManager {
     for (const registration of this.#registrations.values()) {
       registration.currentIndex = 0
       registration.lastKeyTime = 0
+      this.#syncRegistrationView(registration)
     }
   }
 
@@ -586,9 +609,7 @@ export class SequenceManager {
 
     registration.triggerCount++
 
-    this.registrations.setState((prev) =>
-      new Map(prev).set(id, toRegistrationView(registration)),
-    )
+    this.#syncRegistrationView(registration)
 
     const context: HotkeyCallbackContext = {
       hotkey: registration.sequence.join(' ') as Hotkey,

package/dist/recorder.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"recorder.cjs","names":["Store","#options","#platform","detectPlatform","#keydownHandler","isModifierKey","convertToModFormat","keyboardEventToHotkey","hasNonModifierKey","#removeListener","#addListener"],"sources":["../src/recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport {\n  convertToModFormat,\n  hasNonModifierKey,\n  isModifierKey,\n  keyboardEventToHotkey,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      // Ignore pure modifier keys (wait for a non-modifier key)\n      if (isModifierKey(event)) {\n        return\n      }\n\n      // Convert event to hotkey string using library function\n      const hotkey = keyboardEventToHotkey(event)\n\n      // Always convert to Mod format for portability\n      const finalHotkey = convertToModFormat(hotkey, this.#platform)\n\n      // Validate: must have at least one non-modifier key\n      if (hasNonModifierKey(finalHotkey, this.#platform)) {\n        // Remove listener FIRST to prevent any additional events\n        const handlerToRemove = this.#keydownHandler as\n          | ((event: KeyboardEvent) => void)\n          | null\n        if (handlerToRemove) {\n          this.#removeListener(handlerToRemove)\n          this.#keydownHandler = null\n        }\n\n        // Update store state immediately\n        this.store.setState(() => ({\n          isRecording: false,\n          recordedHotkey: finalHotkey,\n        }))\n\n        // Call callback AFTER listener is removed and state is set\n        this.#options.onRecord(finalHotkey)\n      }\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAIA,sBAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKC,UAAW;AAChB,QAAKC,WAAYC,kCAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKF,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKG,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAGF,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKH,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;AAKJ,OAAII,4BAAc,MAAM,CACtB;GAOF,MAAM,cAAcC,iCAHLC,oCAAsB,MAAM,EAGI,MAAKL,SAAU;AAG9D,OAAIM,gCAAkB,aAAa,MAAKN,SAAU,EAAE;IAElD,MAAM,kBAAkB,MAAKE;AAG7B,QAAI,iBAAiB;AACnB,WAAKK,eAAgB,gBAAgB;AACrC,WAAKL,iBAAkB;;AAIzB,SAAK,MAAM,gBAAgB;KACzB,aAAa;KACb,gBAAgB;KACjB,EAAE;AAGH,UAAKH,QAAS,SAAS,YAAY;;;AAIvC,QAAKG,iBAAkB;AACvB,QAAKM,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKN,gBAAiB;AACxB,SAAKK,eAAgB,MAAKL,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKK,eAAgB,MAAKL,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKH,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}

package/dist/recorder.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport {\n  convertToModFormat,\n  hasNonModifierKey,\n  isModifierKey,\n  keyboardEventToHotkey,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      // Ignore pure modifier keys (wait for a non-modifier key)\n      if (isModifierKey(event)) {\n        return\n      }\n\n      // Convert event to hotkey string using library function\n      const hotkey = keyboardEventToHotkey(event)\n\n      // Always convert to Mod format for portability\n      const finalHotkey = convertToModFormat(hotkey, this.#platform)\n\n      // Validate: must have at least one non-modifier key\n      if (hasNonModifierKey(finalHotkey, this.#platform)) {\n        // Remove listener FIRST to prevent any additional events\n        const handlerToRemove = this.#keydownHandler as\n          | ((event: KeyboardEvent) => void)\n          | null\n        if (handlerToRemove) {\n          this.#removeListener(handlerToRemove)\n          this.#keydownHandler = null\n        }\n\n        // Update store state immediately\n        this.store.setState(() => ({\n          isRecording: false,\n          recordedHotkey: finalHotkey,\n        }))\n\n        // Call callback AFTER listener is removed and state is set\n        this.#options.onRecord(finalHotkey)\n      }\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAI,MAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKA,UAAW;AAChB,QAAKC,WAAY,gBAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKD,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKE,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAGF,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKF,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;AAKJ,OAAI,cAAc,MAAM,CACtB;GAOF,MAAM,cAAc,mBAHL,sBAAsB,MAAM,EAGI,MAAKC,SAAU;AAG9D,OAAI,kBAAkB,aAAa,MAAKA,SAAU,EAAE;IAElD,MAAM,kBAAkB,MAAKC;AAG7B,QAAI,iBAAiB;AACnB,WAAKC,eAAgB,gBAAgB;AACrC,WAAKD,iBAAkB;;AAIzB,SAAK,MAAM,gBAAgB;KACzB,aAAa;KACb,gBAAgB;KACjB,EAAE;AAGH,UAAKF,QAAS,SAAS,YAAY;;;AAIvC,QAAKE,iBAAkB;AACvB,QAAKE,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKF,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKF,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}