@tanstack/preact-hotkeys 0.11.0 → 0.12.0

package/src/useHotkeyRecorder.ts

@@ -1,101 +0,0 @@
-import { useEffect, useRef } from 'preact/hooks'
-import { useSelector } from '@tanstack/preact-store'
-import { HotkeyRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
-
-export interface PreactHotkeyRecorder {
-  /** Whether recording is currently active */
-  isRecording: boolean
-  /** The currently recorded hotkey (for live preview) */
-  recordedHotkey: Hotkey | null
-  /** Start recording a new hotkey */
-  startRecording: () => void
-  /** Stop recording (same as cancel) */
-  stopRecording: () => void
-  /** Cancel recording without saving */
-  cancelRecording: () => void
-}
-
-/**
- * Preact hook for recording keyboard shortcuts.
- *
- * This hook provides a thin wrapper around the framework-agnostic `HotkeyRecorder`
- * class, managing 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.
- *
- * @param options - Configuration options for the recorder
- * @returns An object with recording state and control functions
- *
- * @example
- * ```tsx
- * function ShortcutSettings() {
- *   const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')
- *
- *   const recorder = useHotkeyRecorder({
- *     onRecord: (hotkey) => {
- *       setShortcut(hotkey)
- *     },
- *     onCancel: () => {
- *       console.log('Recording cancelled')
- *     },
- *   })
- *
- *   return (
- *     <div>
- *       <button onClick={recorder.startRecording}>
- *         {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
- *       </button>
- *       {recorder.recordedHotkey && (
- *         <div>Recording: {recorder.recordedHotkey}</div>
- *       )}
- *     </div>
- *   )
- * }
- * ```
- */
-export function useHotkeyRecorder(
-  options: HotkeyRecorderOptions,
-): PreactHotkeyRecorder {
-  const mergedOptions = {
-    ...useDefaultHotkeysOptions().hotkeyRecorder,
-    ...options,
-  } as HotkeyRecorderOptions
-
-  const recorderRef = useRef<HotkeyRecorder | null>(null)
-
-  // Create recorder instance once
-  if (!recorderRef.current) {
-    recorderRef.current = new HotkeyRecorder(mergedOptions)
-  }
-
-  // Sync options on every render (same pattern as useHotkey)
-  // This ensures callbacks always have access to latest values
-  recorderRef.current.setOptions(mergedOptions)
-
-  // Subscribe to recorder state using useSelector (same pattern as useHeldKeys)
-  const isRecording = useSelector(
-    recorderRef.current.store,
-    (state) => state.isRecording,
-  )
-  const recordedHotkey = useSelector(
-    recorderRef.current.store,
-    (state) => state.recordedHotkey,
-  )
-
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      recorderRef.current?.destroy()
-    }
-  }, [])
-
-  return {
-    isRecording,
-    recordedHotkey,
-    startRecording: () => recorderRef.current?.start(),
-    stopRecording: () => recorderRef.current?.stop(),
-    cancelRecording: () => recorderRef.current?.cancel(),
-  }
-}

package/src/useHotkeyRegistrations.ts

@@ -1,51 +0,0 @@
-import { useMemo } from 'preact/hooks'
-import { useSelector } from '@tanstack/preact-store'
-import {
-  getHotkeyManager,
-  getSequenceManager,
-  toHotkeyRegistrationView,
-} from '@tanstack/hotkeys'
-import type {
-  HotkeyRegistrationView,
-  SequenceRegistrationView,
-} from '@tanstack/hotkeys'
-
-/**
- * Return type for useHotkeyRegistrations.
- */
-export interface HotkeyRegistrationsResult {
-  /** All registered hotkeys (public view, no callbacks) */
-  hotkeys: Array<HotkeyRegistrationView>
-  /** All registered sequences */
-  sequences: Array<SequenceRegistrationView>
-}
-
-/**
- * Preact hook that reactively reads all hotkey and sequence registrations
- * from the singleton managers.
- *
- * This is a standalone hook that does NOT require the HotkeysProvider.
- * It subscribes to both HotkeyManager and SequenceManager stores and
- * re-renders when registrations change.
- *
- * @returns Object with `hotkeys` and `sequences` arrays
- */
-export function useHotkeyRegistrations(): HotkeyRegistrationsResult {
-  const hotkeyManager = getHotkeyManager()
-  const sequenceManager = getSequenceManager()
-
-  // Select stable store snapshots before deriving arrays; fresh selector arrays
-  // make Preact's external-store subscription render continuously.
-  const hotkeyState = useSelector(hotkeyManager.registrations)
-  const sequenceState = useSelector(sequenceManager.registrations)
-  const hotkeys = useMemo(
-    () => Array.from(hotkeyState.values()).map(toHotkeyRegistrationView),
-    [hotkeyState],
-  )
-  const sequences = useMemo(
-    () => Array.from(sequenceState.values()),
-    [sequenceState],
-  )
-
-  return { hotkeys, sequences }
-}

package/src/useHotkeySequence.ts

@@ -1,192 +0,0 @@
-import { useEffect, useRef } from 'preact/hooks'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import { isRef } from './utils'
-import type { RefObject } from 'preact'
-import type {
-  HotkeyCallback,
-  HotkeyCallbackContext,
-  HotkeySequence,
-  SequenceOptions,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-
-export interface UseHotkeySequenceOptions extends Omit<
-  SequenceOptions,
-  'target'
-> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a Preact ref, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?:
-    | RefObject<HTMLElement | null>
-    | HTMLElement
-    | Document
-    | Window
-    | null
-}
-
-/**
- * Preact hook for registering a keyboard shortcut sequence (Vim-style).
- *
- * This hook allows you to register multi-key sequences like 'g g' or 'd d'
- * that trigger when the full sequence is pressed within a timeout.
- *
- * Each step may include modifiers. You can chain the same modifier across
- * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
- * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
- * advance the sequence or reset progress.
- *
- * @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. `enabled: false` keeps the registration (visible in devtools)
- *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
- *
- * @example
- * ```tsx
- * function VimEditor() {
- *   // 'g g' to go to top
- *   useHotkeySequence(['G', 'G'], () => {
- *     scrollToTop()
- *   })
- *
- *   // 'd d' to delete line
- *   useHotkeySequence(['D', 'D'], () => {
- *     deleteLine()
- *   })
- *
- *   // 'd i w' to delete inner word
- *   useHotkeySequence(['D', 'I', 'W'], () => {
- *     deleteInnerWord()
- *   }, { timeout: 500 })
- *
- *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
- *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
- *     nextAction()
- *   })
- *
- *   return <div>...</div>
- * }
- * ```
- */
-export function useHotkeySequence(
-  sequence: HotkeySequence,
-  callback: HotkeyCallback,
-  options: UseHotkeySequenceOptions = {},
-): void {
-  const mergedOptions = {
-    ...useDefaultHotkeysOptions().hotkeySequence,
-    ...options,
-  } as UseHotkeySequenceOptions
-
-  const manager = getSequenceManager()
-
-  // Stable ref for registration handle
-  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)
-
-  // Refs to capture current values for use in effect without adding dependencies
-  const callbackRef = useRef(callback)
-  const optionsRef = useRef(mergedOptions)
-  const managerRef = useRef(manager)
-  const sequenceRef = useRef(sequence)
-
-  // Update refs on every render
-  callbackRef.current = callback
-  optionsRef.current = mergedOptions
-  managerRef.current = manager
-  sequenceRef.current = sequence
-
-  // Track previous target and sequence to detect changes requiring re-registration
-  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)
-  const prevSequenceRef = useRef<string | null>(null)
-
-  // Normalize to hotkey sequence string (join with spaces)
-  const hotkeySequenceString = formatHotkeySequence(sequence)
-
-  // Extract options without target (target is handled separately)
-  const { target: _target, ...optionsWithoutTarget } = mergedOptions
-
-  useEffect(() => {
-    if (sequenceRef.current.length === 0) {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-      prevTargetRef.current = null
-      prevSequenceRef.current = null
-      return
-    }
-
-    // Resolve target inside the effect so refs are already attached after mount
-    const resolvedTarget = isRef(optionsRef.current.target)
-      ? optionsRef.current.target.current
-      : (optionsRef.current.target ??
-        (typeof document !== 'undefined' ? document : null))
-
-    // Skip if no valid target (SSR or ref still null)
-    if (!resolvedTarget) {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-      prevTargetRef.current = null
-      prevSequenceRef.current = null
-      return
-    }
-
-    // Check if we need to re-register (target or sequence changed)
-    const targetChanged =
-      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget
-    const sequenceChanged =
-      prevSequenceRef.current !== null &&
-      prevSequenceRef.current !== hotkeySequenceString
-
-    // If we have an active registration and target/sequence changed, unregister first
-    if (
-      registrationRef.current?.isActive &&
-      (targetChanged || sequenceChanged)
-    ) {
-      registrationRef.current.unregister()
-      registrationRef.current = null
-    }
-
-    // Register if needed (no active registration)
-    if (!registrationRef.current || !registrationRef.current.isActive) {
-      registrationRef.current = managerRef.current.register(
-        sequenceRef.current,
-        (event, context) => callbackRef.current(event, context),
-        {
-          ...optionsRef.current,
-          target: resolvedTarget,
-        },
-      )
-    }
-
-    // Update tracking refs
-    prevTargetRef.current = resolvedTarget
-    prevSequenceRef.current = hotkeySequenceString
-  })
-
-  useEffect(() => {
-    // Cleanup on unmount
-    return () => {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-    }
-  }, [])
-
-  // Publish option changes after commit, never during render.
-  useEffect(() => {
-    if (registrationRef.current?.isActive) {
-      registrationRef.current.callback = (
-        event: KeyboardEvent,
-        context: HotkeyCallbackContext,
-      ) => callbackRef.current(event, context)
-      registrationRef.current.setOptions(optionsWithoutTarget)
-    }
-  })
-}

package/src/useHotkeySequenceRecorder.ts

@@ -1,64 +0,0 @@
-import { useEffect, useRef } from 'preact/hooks'
-import { useSelector } from '@tanstack/preact-store'
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type {
-  HotkeySequence,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-
-export interface PreactHotkeySequenceRecorder {
-  isRecording: boolean
-  steps: HotkeySequence
-  recordedSequence: HotkeySequence | null
-  startRecording: () => void
-  stopRecording: () => void
-  cancelRecording: () => void
-  commitRecording: () => void
-}
-
-/**
- * Preact hook for recording multi-chord sequences (Vim-style shortcuts).
- */
-export function useHotkeySequenceRecorder(
-  options: HotkeySequenceRecorderOptions,
-): PreactHotkeySequenceRecorder {
-  const mergedOptions = {
-    ...useDefaultHotkeysOptions().hotkeySequenceRecorder,
-    ...options,
-  } as HotkeySequenceRecorderOptions
-
-  const recorderRef = useRef<HotkeySequenceRecorder | null>(null)
-
-  if (!recorderRef.current) {
-    recorderRef.current = new HotkeySequenceRecorder(mergedOptions)
-  }
-
-  recorderRef.current.setOptions(mergedOptions)
-
-  const isRecording = useSelector(
-    recorderRef.current.store,
-    (state) => state.isRecording,
-  )
-  const steps = useSelector(recorderRef.current.store, (state) => state.steps)
-  const recordedSequence = useSelector(
-    recorderRef.current.store,
-    (state) => state.recordedSequence,
-  )
-
-  useEffect(() => {
-    return () => {
-      recorderRef.current?.destroy()
-    }
-  }, [])
-
-  return {
-    isRecording,
-    steps,
-    recordedSequence,
-    startRecording: () => recorderRef.current?.start(),
-    stopRecording: () => recorderRef.current?.stop(),
-    cancelRecording: () => recorderRef.current?.cancel(),
-    commitRecording: () => recorderRef.current?.commit(),
-  }
-}

package/src/useHotkeySequences.ts

@@ -1,192 +0,0 @@
-import { useEffect, useRef } from 'preact/hooks'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import { isRef } from './utils'
-import type { UseHotkeySequenceOptions } from './useHotkeySequence'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-
-/**
- * A single sequence definition for use with `useHotkeySequences`.
- */
-export interface UseHotkeySequenceDefinition {
-  /** Array of hotkey strings that form the sequence */
-  sequence: HotkeySequence
-  /** The function to call when the sequence is completed */
-  callback: HotkeyCallback
-  /** Per-sequence options (merged on top of commonOptions) */
-  options?: UseHotkeySequenceOptions
-}
-
-/**
- * Preact hook for registering multiple keyboard shortcut sequences at once (Vim-style).
- *
- * Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
- * register variable-length lists without violating the rules of hooks.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * Callbacks and options are synced on every render to avoid stale closures.
- *
- * Definitions with an empty `sequence` are skipped (no registration).
- *
- * @param definitions - Array of sequence definitions to register
- * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
- *   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
- *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
- *   via `setOptions` (no unregister/re-register churn).
- *
- * @example
- * ```tsx
- * function VimPalette() {
- *   useHotkeySequences([
- *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
- *     { sequence: ['D', 'D'], callback: () => deleteLine() },
- *     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
- *   ])
- * }
- * ```
- *
- * @example
- * ```tsx
- * function DynamicSequences({ items }) {
- *   useHotkeySequences(
- *     items.map((item) => ({
- *       sequence: item.chords,
- *       callback: item.action,
- *       options: { enabled: item.enabled },
- *     })),
- *     { preventDefault: true },
- *   )
- * }
- * ```
- */
-export function useHotkeySequences(
-  definitions: Array<UseHotkeySequenceDefinition>,
-  commonOptions: UseHotkeySequenceOptions = {},
-): void {
-  type RegistrationRecord = {
-    handle: SequenceRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = useDefaultHotkeysOptions().hotkeySequence
-  const manager = getSequenceManager()
-
-  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())
-  const definitionsRef = useRef(definitions)
-  const sequenceStringsRef = useRef<Array<string>>([])
-  const commonOptionsRef = useRef(commonOptions)
-  const defaultOptionsRef = useRef(defaultOptions)
-  const managerRef = useRef(manager)
-
-  const sequenceStrings = definitions.map((def) =>
-    formatHotkeySequence(def.sequence),
-  )
-
-  definitionsRef.current = definitions
-  sequenceStringsRef.current = sequenceStrings
-  commonOptionsRef.current = commonOptions
-  defaultOptionsRef.current = defaultOptions
-  managerRef.current = manager
-
-  useEffect(() => {
-    const prevRegistrations = registrationsRef.current
-    const nextRegistrations = new Map<string, RegistrationRecord>()
-
-    const rows: Array<{
-      registrationKey: string
-      def: (typeof definitionsRef.current)[number]
-      seq: HotkeySequence
-      seqStr: string
-      mergedOptions: UseHotkeySequenceOptions
-      resolvedTarget: Document | HTMLElement | Window
-    }> = []
-
-    for (let i = 0; i < definitionsRef.current.length; i++) {
-      const def = definitionsRef.current[i]!
-      const seqStr = sequenceStringsRef.current[i]!
-      const seq = def.sequence
-      if (seq.length === 0) {
-        continue
-      }
-
-      const mergedOptions = {
-        ...defaultOptionsRef.current,
-        ...commonOptionsRef.current,
-        ...def.options,
-      } as UseHotkeySequenceOptions
-
-      const resolvedTarget = isRef(mergedOptions.target)
-        ? mergedOptions.target.current
-        : (mergedOptions.target ??
-          (typeof document !== 'undefined' ? document : null))
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const registrationKey = `${i}:${seqStr}`
-      rows.push({
-        registrationKey,
-        def,
-        seq,
-        seqStr,
-        mergedOptions,
-        resolvedTarget,
-      })
-    }
-
-    const nextKeys = new Set(rows.map((r) => r.registrationKey))
-
-    for (const [key, record] of prevRegistrations) {
-      if (!nextKeys.has(key) && record.handle.isActive) {
-        record.handle.unregister()
-      }
-    }
-
-    for (const row of rows) {
-      const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row
-
-      const existing = prevRegistrations.get(registrationKey)
-      if (existing?.handle.isActive && existing.target === resolvedTarget) {
-        // Publish callback/options only after commit, never during render.
-        existing.handle.callback = def.callback
-        const { target: _target, ...optionsWithoutTarget } = mergedOptions
-        existing.handle.setOptions(optionsWithoutTarget)
-        nextRegistrations.set(registrationKey, existing)
-        continue
-      }
-
-      if (existing?.handle.isActive) {
-        existing.handle.unregister()
-      }
-
-      const handle = managerRef.current.register(seq, def.callback, {
-        ...mergedOptions,
-        target: resolvedTarget,
-      })
-      nextRegistrations.set(registrationKey, {
-        handle,
-        target: resolvedTarget,
-      })
-    }
-
-    registrationsRef.current = nextRegistrations
-  })
-
-  useEffect(() => {
-    return () => {
-      for (const { handle } of registrationsRef.current.values()) {
-        if (handle.isActive) {
-          handle.unregister()
-        }
-      }
-      registrationsRef.current = new Map()
-    }
-  }, [])
-}