@tanstack/hotkeys 0.4.2 → 0.5.0

package/src/hotkey-sequence-recorder.ts

@@ -0,0 +1,308 @@
+import { Store } from '@tanstack/store'
+import { detectPlatform } from './constants'
+import { hotkeyChordFromKeydown } from './recorder-chord'
+import type { HotkeySequence } from './sequence-manager'
+
+/**
+ * How the user can commit a recorded sequence from the keyboard.
+ * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.
+ * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).
+ */
+export type HotkeySequenceRecorderCommitKeys = 'enter' | 'none'
+
+/**
+ * State interface for the HotkeySequenceRecorder.
+ */
+export interface HotkeySequenceRecorderState {
+  /** Whether recording is currently active */
+  isRecording: boolean
+  /** Chords captured so far in the current recording session */
+  steps: HotkeySequence
+  /** The last successfully committed sequence, or null if none / after starting a new session */
+  recordedSequence: HotkeySequence | null
+}
+
+/**
+ * Options for configuring a HotkeySequenceRecorder instance.
+ */
+export interface HotkeySequenceRecorderOptions {
+  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+  onRecord: (sequence: HotkeySequence) => void
+  /** Optional callback when recording is cancelled (Escape pressed) */
+  onCancel?: () => void
+  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */
+  onClear?: () => void
+  /**
+   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.
+   * @default true
+   */
+  commitOnEnter?: boolean
+  /**
+   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).
+   * @default 'enter'
+   */
+  commitKeys?: HotkeySequenceRecorderCommitKeys
+  /**
+   * Milliseconds of inactivity after the **last completed chord** before auto-committing.
+   * The timer does not run while waiting for the first chord (`steps.length === 0`).
+   */
+  idleTimeoutMs?: number
+}
+
+const defaultHotkeySequenceRecorderOptions: Pick<
+  HotkeySequenceRecorderOptions,
+  'commitOnEnter' | 'commitKeys'
+> = {
+  commitOnEnter: true,
+  commitKeys: 'enter',
+}
+
+function resolvedCommitOnEnter(
+  options: HotkeySequenceRecorderOptions,
+): boolean {
+  if (options.commitKeys === 'none') {
+    return false
+  }
+  return options.commitOnEnter !== false
+}
+
+/**
+ * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
+ * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
+ * **Backspace/Delete** to remove the last step or clear when empty.
+ */
+export class HotkeySequenceRecorder {
+  readonly store: Store<HotkeySequenceRecorderState> =
+    new Store<HotkeySequenceRecorderState>({
+      isRecording: false,
+      steps: [],
+      recordedSequence: null,
+    })
+
+  #keydownHandler: ((event: KeyboardEvent) => void) | null = null
+  #options: HotkeySequenceRecorderOptions
+  #platform: 'mac' | 'windows' | 'linux'
+  #idleTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(options: HotkeySequenceRecorderOptions) {
+    this.#options = {
+      ...defaultHotkeySequenceRecorderOptions,
+      ...options,
+    }
+    this.#platform = detectPlatform()
+  }
+
+  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {
+    this.#options = {
+      ...defaultHotkeySequenceRecorderOptions,
+      ...this.#options,
+      ...options,
+    }
+  }
+
+  #clearIdleTimer(): void {
+    if (this.#idleTimer !== null) {
+      clearTimeout(this.#idleTimer)
+      this.#idleTimer = null
+    }
+  }
+
+  #scheduleIdleTimer(): void {
+    this.#clearIdleTimer()
+    const ms = this.#options.idleTimeoutMs
+    if (ms === undefined || ms <= 0) {
+      return
+    }
+    const steps = this.store.state.steps
+    if (steps.length === 0) {
+      return
+    }
+    this.#idleTimer = setTimeout(() => {
+      this.#idleTimer = null
+      if (!this.#keydownHandler) {
+        return
+      }
+      if (this.store.state.steps.length >= 1) {
+        this.commit()
+      }
+    }, ms)
+  }
+
+  #patchSteps(updater: (prev: HotkeySequence) => HotkeySequence): void {
+    this.store.setState((s) => ({
+      ...s,
+      steps: updater(s.steps),
+    }))
+  }
+
+  start(): void {
+    if (this.#keydownHandler) {
+      return
+    }
+
+    this.#clearIdleTimer()
+    this.store.setState(() => ({
+      isRecording: true,
+      steps: [],
+      recordedSequence: null,
+    }))
+
+    const handler = (event: KeyboardEvent) => {
+      if (!this.#keydownHandler) {
+        return
+      }
+
+      event.preventDefault()
+      event.stopPropagation()
+
+      if (event.key === 'Escape') {
+        this.cancel()
+        return
+      }
+
+      if (event.key === 'Backspace' || event.key === 'Delete') {
+        if (
+          !event.ctrlKey &&
+          !event.shiftKey &&
+          !event.altKey &&
+          !event.metaKey
+        ) {
+          const steps = this.store.state.steps
+          if (steps.length === 0) {
+            this.#options.onClear?.()
+            this.#options.onRecord([])
+            this.#finishWithoutCommitCallback()
+            return
+          }
+          this.#patchSteps((prev) => prev.slice(0, -1))
+          const next = this.store.state.steps
+          if (next.length === 0) {
+            this.#clearIdleTimer()
+          } else {
+            this.#scheduleIdleTimer()
+          }
+          return
+        }
+      }
+
+      const enterCommits =
+        resolvedCommitOnEnter(this.#options) &&
+        event.key === 'Enter' &&
+        !event.ctrlKey &&
+        !event.shiftKey &&
+        !event.altKey &&
+        !event.metaKey
+
+      if (enterCommits && this.store.state.steps.length >= 1) {
+        this.commit()
+        return
+      }
+
+      if (enterCommits && this.store.state.steps.length === 0) {
+        return
+      }
+
+      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)
+      if (finalHotkey === null) {
+        return
+      }
+
+      this.#patchSteps((prev) => [...prev, finalHotkey])
+      this.#scheduleIdleTimer()
+    }
+
+    this.#keydownHandler = handler
+    this.#addListener(handler)
+  }
+
+  /**
+   * Commit the current steps as a sequence. No-op if fewer than one step.
+   */
+  commit(): void {
+    const steps = this.store.state.steps
+    if (steps.length < 1) {
+      return
+    }
+
+    const sequence = [...steps]
+
+    if (this.#keydownHandler) {
+      this.#removeListener(this.#keydownHandler)
+      this.#keydownHandler = null
+    }
+    this.#clearIdleTimer()
+
+    this.store.setState(() => ({
+      isRecording: false,
+      steps: [],
+      recordedSequence: sequence,
+    }))
+
+    this.#options.onRecord(sequence)
+  }
+
+  #finishWithoutCommitCallback(): void {
+    if (this.#keydownHandler) {
+      this.#removeListener(this.#keydownHandler)
+      this.#keydownHandler = null
+    }
+    this.#clearIdleTimer()
+    this.store.setState(() => ({
+      isRecording: false,
+      steps: [],
+      recordedSequence: null,
+    }))
+  }
+
+  stop(): void {
+    if (this.#keydownHandler) {
+      this.#removeListener(this.#keydownHandler)
+      this.#keydownHandler = null
+    }
+    this.#clearIdleTimer()
+    this.store.setState(() => ({
+      isRecording: false,
+      steps: [],
+      recordedSequence: null,
+    }))
+  }
+
+  cancel(): void {
+    if (this.#keydownHandler) {
+      this.#removeListener(this.#keydownHandler)
+      this.#keydownHandler = null
+    }
+    this.#clearIdleTimer()
+    this.store.setState(() => ({
+      isRecording: false,
+      steps: [],
+      recordedSequence: null,
+    }))
+    this.#options.onCancel?.()
+  }
+
+  #addListener(handler: (event: KeyboardEvent) => void): void {
+    if (typeof document === 'undefined') {
+      return
+    }
+    document.addEventListener('keydown', handler, true)
+  }
+
+  #removeListener(handler: (event: KeyboardEvent) => void): void {
+    if (typeof document === 'undefined') {
+      return
+    }
+    document.removeEventListener('keydown', handler, true)
+  }
+
+  destroy(): void {
+    this.stop()
+    this.store.setState(() => ({
+      isRecording: false,
+      steps: [],
+      recordedSequence: null,
+    }))
+  }
+}

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/recorder-chord.ts

@@ -0,0 +1,26 @@
+import {
+  convertToModFormat,
+  hasNonModifierKey,
+  isModifierKey,
+  keyboardEventToHotkey,
+} 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(event)) {
+    return null
+  }
+  const hotkey = keyboardEventToHotkey(event)
+  const finalHotkey = convertToModFormat(hotkey, platform)
+  if (!hasNonModifierKey(finalHotkey, platform)) {
+    return null
+  }
+  return finalHotkey
+}

package/src/sequence-manager.ts

@@ -1,7 +1,7 @@
 import { Store } from '@tanstack/store'
 import { formatHotkeySequence } from './format'
 import { detectPlatform } from './constants'
-import { parseHotkey } from './parse'
+import { isModifierKey, parseHotkey } from './parse'
 import { matchesKeyboardEvent } from './match'
 import {
   defaultHotkeyOptions,
@@ -32,19 +32,26 @@ export interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
 /**
  * A sequence of hotkeys for Vim-style shortcuts.
  *
+ * Each element is one step (a `Hotkey` string). Steps may include modifiers;
+ * the same modifier can appear on consecutive steps (e.g. `Shift+R` then
+ * `Shift+T`). Modifier-only key events do not advance or reset matching—see
+ * `SequenceManager`.
+ *
  * @example
  * ```ts
  * const gotoTop: HotkeySequence = ['G', 'G']  // gg
  * const deleteLine: HotkeySequence = ['D', 'D']  // dd
  * const deleteWord: HotkeySequence = ['D', 'I', 'W']  // diw
+ * const chainedShift: HotkeySequence = ['Shift+R', 'Shift+T']
  * ```
  */
 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
 
@@ -64,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
@@ -72,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
 }
 
 /**
@@ -117,6 +128,11 @@ export interface SequenceRegistrationHandle {
  * that trigger callbacks when the full sequence is pressed within
  * a configurable timeout.
  *
+ * Modifier-only `keydown` / `keyup` events (Shift, Control, Alt, or Meta
+ * alone) are not processed: they neither match a step nor reset progress.
+ * That supports chained modifier chords (e.g. `Shift+R` then `Shift+T`) when
+ * the user presses a modifier alone between steps.
+ *
  * @example
  * ```ts
  * const matcher = SequenceManager.getInstance()
@@ -136,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,
   }
 }
 
@@ -190,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.
    *
@@ -407,6 +433,11 @@ export class SequenceManager {
     target: Target,
     eventType: 'keydown' | 'keyup',
   ): void {
+    // Skip modifier-only events so pressing e.g. Shift before Shift+C does not reset the sequence.
+    if (isModifierKey(event)) {
+      return
+    }
+
     const targetRegs = this.#targetRegistrations.get(target)
     if (!targetRegs) {
       return
@@ -451,6 +482,7 @@ export class SequenceManager {
         now - registration.lastKeyTime > timeout
       ) {
         registration.currentIndex = 0
+        this.#syncRegistrationView(registration)
       }
 
       const expectedHotkey =
@@ -485,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]!
@@ -503,6 +540,7 @@ export class SequenceManager {
         } else {
           registration.currentIndex = 0
         }
+        this.#syncRegistrationView(registration)
       }
     }
   }
@@ -533,6 +571,7 @@ export class SequenceManager {
     for (const registration of this.#registrations.values()) {
       registration.currentIndex = 0
       registration.lastKeyTime = 0
+      this.#syncRegistrationView(registration)
     }
   }
 
@@ -570,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"}