@tanstack/react-hotkeys 0.10.0 → 0.12.0

package/src/useHotkey.ts

@@ -1,187 +0,0 @@
-import { useEffect, useRef } from 'react'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import { isRef } from './utils'
-import type {
-  HotkeyCallback,
-  HotkeyOptions,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a React ref, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?:
-    | React.RefObject<HTMLElement | null>
-    | HTMLElement
-    | Document
-    | Window
-    | null
-}
-
-/**
- * React hook for registering a keyboard hotkey.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * The callback receives both the keyboard event and a context object
- * containing the hotkey string and parsed hotkey.
- *
- * This hook syncs the callback and options on every render to avoid
- * stale closures. This means
- * callbacks that reference React state will always have access to
- * the latest values.
- *
- * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
- * @param callback - The function to call when the hotkey is pressed
- * @param options - Options for the hotkey 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 SaveButton() {
- *   const [count, setCount] = useState(0)
- *
- *   // Callback always has access to latest count value
- *   useHotkey('Mod+S', (event, { hotkey }) => {
- *     console.log(`Save triggered, count is ${count}`)
- *     handleSave()
- *   })
- *
- *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Modal({ isOpen, onClose }) {
- *   // enabled option is synced on every render
- *   useHotkey('Escape', () => {
- *     onClose()
- *   }, { enabled: isOpen })
- *
- *   if (!isOpen) return null
- *   return <div className="modal">...</div>
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Editor() {
- *   const editorRef = useRef<HTMLDivElement>(null)
- *
- *   // Scoped to a specific element
- *   useHotkey('Mod+S', () => {
- *     save()
- *   }, { target: editorRef })
- *
- *   return <div ref={editorRef}>...</div>
- * }
- * ```
- */
-export function useHotkey(
-  hotkey: RegisterableHotkey,
-  callback: HotkeyCallback,
-  options: UseHotkeyOptions = {},
-): void {
-  const mergedOptions = {
-    ...useDefaultHotkeysOptions().hotkey,
-    ...options,
-  } as UseHotkeyOptions
-
-  const manager = getHotkeyManager()
-
-  // Stable ref for registration handle
-  const registrationRef = useRef<HotkeyRegistrationHandle | 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)
-
-  // Update refs on every render
-  callbackRef.current = callback
-  optionsRef.current = mergedOptions
-  managerRef.current = manager
-
-  // Track previous target and hotkey to detect changes requiring re-registration
-  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)
-  const prevHotkeyRef = useRef<string | null>(null)
-
-  // Normalize to hotkey string
-  const platform = mergedOptions.platform ?? detectPlatform()
-  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)
-
-  // Extract options without target (target is handled separately)
-  const { target: _target, ...optionsWithoutTarget } = mergedOptions
-
-  useEffect(() => {
-    // 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
-      prevHotkeyRef.current = null
-      return
-    }
-
-    // Check if we need to re-register (target or hotkey changed)
-    const targetChanged =
-      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget
-    const hotkeyChanged =
-      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString
-
-    // If we have an active registration and target/hotkey changed, unregister first
-    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
-      registrationRef.current.unregister()
-      registrationRef.current = null
-    }
-
-    // Register if needed (no active registration)
-    // Use refs to access current values without adding them to dependencies
-    if (!registrationRef.current || !registrationRef.current.isActive) {
-      registrationRef.current = managerRef.current.register(
-        hotkeyString,
-        callbackRef.current,
-        {
-          ...optionsRef.current,
-          target: resolvedTarget,
-        },
-      )
-    }
-
-    // Update tracking refs
-    prevTargetRef.current = resolvedTarget
-    prevHotkeyRef.current = hotkeyString
-
-    // Cleanup on unmount
-    return () => {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-    }
-  }, [hotkeyString])
-
-  // Sync callback and options on EVERY render (outside useEffect)
-  // This avoids stale closures - the callback always has access to latest state
-  if (registrationRef.current?.isActive) {
-    registrationRef.current.callback = callback
-    registrationRef.current.setOptions(optionsWithoutTarget)
-  }
-}

package/src/useHotkeyRecorder.ts

@@ -1,101 +0,0 @@
-import { useEffect, useRef } from 'react'
-import { useSelector } from '@tanstack/react-store'
-import { HotkeyRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
-
-export interface ReactHotkeyRecorder {
-  /** 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
-}
-
-/**
- * React 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,
-): ReactHotkeyRecorder {
-  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,67 +0,0 @@
-import { useSelector } from '@tanstack/react-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>
-}
-
-/**
- * React 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
- *
- * @example
- * ```tsx
- * function ShortcutPalette() {
- *   const { hotkeys, sequences } = useHotkeyRegistrations()
- *
- *   return (
- *     <ul>
- *       {hotkeys.map((reg) => (
- *         <li key={reg.id}>
- *           {reg.options.meta?.name ?? reg.hotkey}
- *         </li>
- *       ))}
- *       {sequences.map((reg) => (
- *         <li key={reg.id}>
- *           {reg.options.meta?.name ?? reg.sequence.join(' ')}
- *         </li>
- *       ))}
- *     </ul>
- *   )
- * }
- * ```
- */
-export function useHotkeyRegistrations(): HotkeyRegistrationsResult {
-  const hotkeyManager = getHotkeyManager()
-  const sequenceManager = getSequenceManager()
-
-  const hotkeys = useSelector(hotkeyManager.registrations, (state) =>
-    Array.from(state.values()).map(toHotkeyRegistrationView),
-  )
-
-  const sequences = useSelector(sequenceManager.registrations, (state) =>
-    Array.from(state.values()),
-  )
-
-  return { hotkeys, sequences }
-}

package/src/useHotkeySequence.ts

@@ -1,187 +0,0 @@
-import { useEffect, useRef } from 'react'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import { isRef } from './utils'
-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 React ref, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?:
-    | React.RefObject<HTMLElement | null>
-    | HTMLElement
-    | Document
-    | Window
-    | null
-}
-
-/**
- * React 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
-
-    // Cleanup on unmount
-    return () => {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-    }
-  }, [hotkeySequenceString])
-
-  // Sync callback and options on EVERY render (outside 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,70 +0,0 @@
-import { useEffect, useRef } from 'react'
-import { useSelector } from '@tanstack/react-store'
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type {
-  HotkeySequence,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-
-export interface ReactHotkeySequenceRecorder {
-  /** Whether recording is currently active */
-  isRecording: boolean
-  /** Chords captured in the current session */
-  steps: HotkeySequence
-  /** Last committed sequence */
-  recordedSequence: HotkeySequence | null
-  startRecording: () => void
-  stopRecording: () => void
-  cancelRecording: () => void
-  /** Commit current steps (no-op if empty) */
-  commitRecording: () => void
-}
-
-/**
- * React hook for recording multi-chord sequences (Vim-style shortcuts).
- *
- * @param options - Configuration options for the hotkey sequence recorder
- */
-export function useHotkeySequenceRecorder(
-  options: HotkeySequenceRecorderOptions,
-): ReactHotkeySequenceRecorder {
-  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(),
-  }
-}