@tanstack/hotkeys 0.0.1 → 0.1.0

package/src/recorder.ts

@@ -0,0 +1,266 @@
+import { Store } from '@tanstack/store'
+import { detectPlatform } from './constants'
+import {
+  convertToModFormat,
+  hasNonModifierKey,
+  isModifierKey,
+  keyboardEventToHotkey,
+} from './parse'
+import type { Hotkey } from './hotkey'
+
+/**
+ * State interface for the HotkeyRecorder.
+ */
+export interface HotkeyRecorderState {
+  /** Whether recording is currently active */
+  isRecording: boolean
+  /** The currently recorded hotkey (for live preview) */
+  recordedHotkey: Hotkey | null
+}
+
+/**
+ * Options for configuring a HotkeyRecorder instance.
+ */
+export interface HotkeyRecorderOptions {
+  /** Callback when a hotkey is successfully recorded */
+  onRecord: (hotkey: Hotkey) => void
+  /** Optional callback when recording is cancelled (Escape pressed) */
+  onCancel?: () => void
+  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */
+  onClear?: () => void
+}
+
+/**
+ * Framework-agnostic class for recording keyboard shortcuts.
+ *
+ * This class handles all the complexity of capturing keyboard events,
+ * converting them to hotkey strings, and handling edge cases like
+ * Escape to cancel or Backspace/Delete to clear.
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - State can be accessed via `recorder.store.state` when using the class directly
+ * - When using framework adapters (React), use `useStore` hooks for reactive state
+ *
+ * @example
+ * ```ts
+ * const recorder = new HotkeyRecorder({
+ *   onRecord: (hotkey) => {
+ *     console.log('Recorded:', hotkey)
+ *   },
+ *   onCancel: () => {
+ *     console.log('Recording cancelled')
+ *   },
+ * })
+ *
+ * // Start recording
+ * recorder.start()
+ *
+ * // Access state directly
+ * console.log(recorder.store.state.isRecording) // true
+ *
+ * // Subscribe to changes with TanStack Store
+ * const unsubscribe = recorder.store.subscribe(() => {
+ *   console.log('Recording:', recorder.store.state.isRecording)
+ * })
+ *
+ * // Cleanup
+ * recorder.destroy()
+ * unsubscribe()
+ * ```
+ */
+export class HotkeyRecorder {
+  /**
+   * The TanStack Store instance containing the recorder state.
+   * Use this to subscribe to state changes or access current state.
+   */
+  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({
+    isRecording: false,
+    recordedHotkey: null,
+  })
+
+  #keydownHandler: ((event: KeyboardEvent) => void) | null = null
+  #options: HotkeyRecorderOptions
+  #platform: 'mac' | 'windows' | 'linux'
+
+  constructor(options: HotkeyRecorderOptions) {
+    this.#options = options
+    this.#platform = detectPlatform()
+  }
+
+  /**
+   * Updates the recorder options, including callbacks.
+   * This allows framework adapters to sync callback changes without recreating the recorder.
+   */
+  setOptions(options: Partial<HotkeyRecorderOptions>): void {
+    this.#options = {
+      ...this.#options,
+      ...options,
+    }
+  }
+
+  /**
+   * Start recording a new hotkey.
+   *
+   * Sets up a keydown event listener that captures keyboard events
+   * and converts them to hotkey strings. Recording continues until
+   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.
+   */
+  start(): void {
+    // Prevent starting recording if already recording
+    if (this.#keydownHandler) {
+      return
+    }
+
+    // Update store state
+    this.store.setState(() => ({
+      isRecording: true,
+      recordedHotkey: null,
+    }))
+
+    // Create keydown handler
+    const handler = (event: KeyboardEvent) => {
+      // Check if we're still recording (handler might be called after stop/cancel)
+      if (!this.#keydownHandler) {
+        return
+      }
+
+      event.preventDefault()
+      event.stopPropagation()
+
+      // Handle Escape to cancel
+      if (event.key === 'Escape') {
+        this.cancel()
+        return
+      }
+
+      // Handle Backspace/Delete to clear shortcut
+      if (event.key === 'Backspace' || event.key === 'Delete') {
+        if (
+          !event.ctrlKey &&
+          !event.shiftKey &&
+          !event.altKey &&
+          !event.metaKey
+        ) {
+          this.#options.onClear?.()
+          this.#options.onRecord('' as Hotkey)
+          this.stop()
+          return
+        }
+      }
+
+      // Ignore pure modifier keys (wait for a non-modifier key)
+      if (isModifierKey(event)) {
+        return
+      }
+
+      // Convert event to hotkey string using library function
+      const hotkey = keyboardEventToHotkey(event)
+
+      // Always convert to Mod format for portability
+      const finalHotkey = convertToModFormat(hotkey, this.#platform)
+
+      // Validate: must have at least one non-modifier key
+      if (hasNonModifierKey(finalHotkey, this.#platform)) {
+        // Remove listener FIRST to prevent any additional events
+        const handlerToRemove = this.#keydownHandler as
+          | ((event: KeyboardEvent) => void)
+          | null
+        if (handlerToRemove) {
+          this.#removeListener(handlerToRemove)
+          this.#keydownHandler = null
+        }
+
+        // Update store state immediately
+        this.store.setState(() => ({
+          isRecording: false,
+          recordedHotkey: finalHotkey,
+        }))
+
+        // Call callback AFTER listener is removed and state is set
+        this.#options.onRecord(finalHotkey)
+      }
+    }
+
+    this.#keydownHandler = handler
+    this.#addListener(handler)
+  }
+
+  /**
+   * Stop recording (same as cancel, but doesn't call onCancel).
+   *
+   * Removes the event listener and resets the recording state.
+   */
+  stop(): void {
+    // Remove event listener immediately
+    if (this.#keydownHandler) {
+      this.#removeListener(this.#keydownHandler)
+      this.#keydownHandler = null
+    }
+
+    // Update store state
+    this.store.setState(() => ({
+      isRecording: false,
+      recordedHotkey: null,
+    }))
+  }
+
+  /**
+   * Cancel recording without saving.
+   *
+   * Removes the event listener, resets the recording state, and calls
+   * the onCancel callback if provided.
+   */
+  cancel(): void {
+    // Remove event listener immediately
+    if (this.#keydownHandler) {
+      this.#removeListener(this.#keydownHandler)
+      this.#keydownHandler = null
+    }
+
+    // Update store state
+    this.store.setState(() => ({
+      isRecording: false,
+      recordedHotkey: null,
+    }))
+
+    // Call cancel callback
+    this.#options.onCancel?.()
+  }
+
+  /**
+   * Adds the keydown event listener to the document.
+   */
+  #addListener(handler: (event: KeyboardEvent) => void): void {
+    if (typeof document === 'undefined') {
+      return // SSR safety
+    }
+
+    document.addEventListener('keydown', handler, true)
+  }
+
+  /**
+   * Removes the keydown event listener from the document.
+   */
+  #removeListener(handler: (event: KeyboardEvent) => void): void {
+    if (typeof document === 'undefined') {
+      return
+    }
+
+    document.removeEventListener('keydown', handler, true)
+  }
+
+  /**
+   * Clean up event listeners and reset state.
+   *
+   * Call this when you're done with the recorder to ensure
+   * all event listeners are properly removed.
+   */
+  destroy(): void {
+    this.stop()
+    this.store.setState(() => ({
+      isRecording: false,
+      recordedHotkey: null,
+    }))
+  }
+}

package/src/sequence.ts

@@ -0,0 +1,391 @@
+import { detectPlatform } from './constants'
+import { parseHotkey } from './parse'
+import { matchesKeyboardEvent } from './match'
+import type { HotkeyOptions } from './hotkey-manager'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyCallbackContext,
+  ParsedHotkey,
+} from './hotkey'
+
+/**
+ * Options for hotkey sequence matching.
+ */
+export interface SequenceOptions extends HotkeyOptions {
+  /** Timeout between keys in milliseconds. Default: 1000 */
+  timeout?: number
+}
+
+/**
+ * A sequence of hotkeys for Vim-style shortcuts.
+ *
+ * @example
+ * ```ts
+ * const gotoTop: HotkeySequence = ['G', 'G']  // gg
+ * const deleteLine: HotkeySequence = ['D', 'D']  // dd
+ * const deleteWord: HotkeySequence = ['D', 'I', 'W']  // diw
+ * ```
+ */
+export type HotkeySequence = Array<Hotkey>
+
+/**
+ * Default timeout between keys in a sequence (in milliseconds).
+ */
+const DEFAULT_SEQUENCE_TIMEOUT = 1000
+
+let sequenceIdCounter = 0
+
+/**
+ * Generates a unique ID for sequence registrations.
+ */
+function generateSequenceId(): string {
+  return `sequence_${++sequenceIdCounter}`
+}
+
+/**
+ * Internal representation of a sequence registration.
+ */
+interface SequenceRegistration {
+  id: string
+  sequence: HotkeySequence
+  parsedSequence: Array<ParsedHotkey>
+  callback: HotkeyCallback
+  options: SequenceOptions
+  currentIndex: number
+  lastKeyTime: number
+}
+
+/**
+ * Manages keyboard sequence matching for Vim-style shortcuts.
+ *
+ * This class allows registering multi-key sequences like 'g g' or 'd d'
+ * that trigger callbacks when the full sequence is pressed within
+ * a configurable timeout.
+ *
+ * @example
+ * ```ts
+ * const matcher = SequenceManager.getInstance()
+ *
+ * // Register 'g g' to go to top
+ * const unregister = matcher.register(['G', 'G'], (event, context) => {
+ *   scrollToTop()
+ * }, { timeout: 500 })
+ *
+ * // Later, to unregister:
+ * unregister()
+ * ```
+ */
+export class SequenceManager {
+  static #instance: SequenceManager | null = null
+
+  #registrations: Map<string, SequenceRegistration> = new Map()
+  #keydownListener: ((event: KeyboardEvent) => void) | null = null
+  #platform: 'mac' | 'windows' | 'linux'
+
+  private constructor() {
+    this.#platform = detectPlatform()
+  }
+
+  /**
+   * Gets the singleton instance of SequenceManager.
+   */
+  static getInstance(): SequenceManager {
+    if (!SequenceManager.#instance) {
+      SequenceManager.#instance = new SequenceManager()
+    }
+    return SequenceManager.#instance
+  }
+
+  /**
+   * Resets the singleton instance. Useful for testing.
+   */
+  static resetInstance(): void {
+    if (SequenceManager.#instance) {
+      SequenceManager.#instance.destroy()
+      SequenceManager.#instance = null
+    }
+  }
+
+  /**
+   * Registers a hotkey sequence handler.
+   *
+   * @param sequence - Array of hotkey strings that form the sequence
+   * @param callback - Function to call when the sequence is completed
+   * @param options - Options for the sequence behavior
+   * @returns A function to unregister the sequence
+   */
+  register(
+    sequence: HotkeySequence,
+    callback: HotkeyCallback,
+    options: SequenceOptions = {},
+  ): () => void {
+    if (sequence.length === 0) {
+      throw new Error('Sequence must contain at least one hotkey')
+    }
+
+    const id = generateSequenceId()
+    const platform = options.platform ?? this.#platform
+    const parsedSequence = sequence.map((hotkey) =>
+      parseHotkey(hotkey, platform),
+    )
+
+    const registration: SequenceRegistration = {
+      id,
+      sequence,
+      parsedSequence,
+      callback,
+      options: {
+        timeout: DEFAULT_SEQUENCE_TIMEOUT,
+        preventDefault: true,
+        stopPropagation: true,
+        enabled: true,
+        ...options,
+        platform,
+      },
+      currentIndex: 0,
+      lastKeyTime: 0,
+    }
+
+    this.#registrations.set(id, registration)
+    this.#ensureListener()
+
+    return () => {
+      this.#unregister(id)
+    }
+  }
+
+  /**
+   * Unregisters a sequence by its registration ID.
+   */
+  #unregister(id: string): void {
+    this.#registrations.delete(id)
+
+    if (this.#registrations.size === 0) {
+      this.#removeListener()
+    }
+  }
+
+  /**
+   * Ensures the keydown listener is attached.
+   */
+  #ensureListener(): void {
+    if (typeof document === 'undefined') {
+      return // SSR safety
+    }
+
+    if (!this.#keydownListener) {
+      this.#keydownListener = this.#handleKeyDown.bind(this)
+      document.addEventListener('keydown', this.#keydownListener)
+    }
+  }
+
+  /**
+   * Removes the keydown listener.
+   */
+  #removeListener(): void {
+    if (typeof document === 'undefined') {
+      return
+    }
+
+    if (this.#keydownListener) {
+      document.removeEventListener('keydown', this.#keydownListener)
+      this.#keydownListener = null
+    }
+  }
+
+  /**
+   * Handles keydown events for sequence matching.
+   */
+  #handleKeyDown(event: KeyboardEvent): void {
+    const now = Date.now()
+
+    for (const registration of this.#registrations.values()) {
+      if (!registration.options.enabled) {
+        continue
+      }
+
+      const timeout = registration.options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT
+
+      // Check if sequence has timed out
+      if (
+        registration.currentIndex > 0 &&
+        now - registration.lastKeyTime > timeout
+      ) {
+        // Reset the sequence
+        registration.currentIndex = 0
+      }
+
+      const expectedHotkey =
+        registration.parsedSequence[registration.currentIndex]
+      if (!expectedHotkey) {
+        continue
+      }
+
+      // Check if current key matches the expected key in sequence
+      if (
+        matchesKeyboardEvent(
+          event,
+          expectedHotkey,
+          registration.options.platform,
+        )
+      ) {
+        registration.lastKeyTime = now
+        registration.currentIndex++
+
+        // Check if sequence is complete
+        if (registration.currentIndex >= registration.parsedSequence.length) {
+          // Sequence complete!
+          if (registration.options.preventDefault) {
+            event.preventDefault()
+          }
+          if (registration.options.stopPropagation) {
+            event.stopPropagation()
+          }
+
+          const context: HotkeyCallbackContext = {
+            hotkey: registration.sequence.join(' ') as Hotkey,
+            parsedHotkey:
+              registration.parsedSequence[
+                registration.parsedSequence.length - 1
+              ]!,
+          }
+
+          registration.callback(event, context)
+
+          // Reset for next sequence
+          registration.currentIndex = 0
+        }
+      } else if (registration.currentIndex > 0) {
+        // Key didn't match and we were in the middle of a sequence
+        // Check if it matches the start of the sequence (for overlapping sequences)
+        const firstHotkey = registration.parsedSequence[0]!
+        if (
+          matchesKeyboardEvent(
+            event,
+            firstHotkey,
+            registration.options.platform,
+          )
+        ) {
+          registration.currentIndex = 1
+          registration.lastKeyTime = now
+        } else {
+          // Reset the sequence
+          registration.currentIndex = 0
+        }
+      }
+    }
+  }
+
+  /**
+   * Resets all sequence progress.
+   */
+  resetAll(): void {
+    for (const registration of this.#registrations.values()) {
+      registration.currentIndex = 0
+      registration.lastKeyTime = 0
+    }
+  }
+
+  /**
+   * Gets the number of registered sequences.
+   */
+  getRegistrationCount(): number {
+    return this.#registrations.size
+  }
+
+  /**
+   * Destroys the manager and removes all listeners.
+   */
+  destroy(): void {
+    this.#removeListener()
+    this.#registrations.clear()
+  }
+}
+
+/**
+ * Gets the singleton SequenceManager instance.
+ * Convenience function for accessing the manager.
+ */
+export function getSequenceManager(): SequenceManager {
+  return SequenceManager.getInstance()
+}
+
+/**
+ * Creates a simple sequence matcher for one-off use.
+ *
+ * @param sequence - The sequence of hotkeys to match
+ * @param options - Options including timeout
+ * @returns An object with match() and reset() methods
+ *
+ * @example
+ * ```ts
+ * const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })
+ *
+ * document.addEventListener('keydown', (event) => {
+ *   if (matcher.match(event)) {
+ *     console.log('Sequence matched!')
+ *   }
+ * })
+ * ```
+ */
+export function createSequenceMatcher(
+  sequence: HotkeySequence,
+  options: { timeout?: number; platform?: 'mac' | 'windows' | 'linux' } = {},
+): {
+  match: (event: KeyboardEvent) => boolean
+  reset: () => void
+  getProgress: () => number
+} {
+  const platform = options.platform ?? detectPlatform()
+  const timeout = options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT
+  const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform))
+
+  let currentIndex = 0
+  let lastKeyTime = 0
+
+  return {
+    match(event: KeyboardEvent): boolean {
+      const now = Date.now()
+
+      // Check timeout
+      if (currentIndex > 0 && now - lastKeyTime > timeout) {
+        currentIndex = 0
+      }
+
+      const expected = parsedSequence[currentIndex]
+      if (!expected) {
+        return false
+      }
+
+      if (matchesKeyboardEvent(event, expected, platform)) {
+        lastKeyTime = now
+        currentIndex++
+
+        if (currentIndex >= parsedSequence.length) {
+          currentIndex = 0
+          return true
+        }
+      } else if (currentIndex > 0) {
+        // Check if it matches start of sequence
+        if (matchesKeyboardEvent(event, parsedSequence[0]!, platform)) {
+          currentIndex = 1
+          lastKeyTime = now
+        } else {
+          currentIndex = 0
+        }
+      }
+
+      return false
+    },
+
+    reset(): void {
+      currentIndex = 0
+      lastKeyTime = 0
+    },
+
+    getProgress(): number {
+      return currentIndex
+    },
+  }
+}