@tanstack/react-hotkeys 0.0.1 → 0.0.3

package/src/index.ts

@@ -0,0 +1,13 @@
+// Re-export everything from the core package
+export * from '@tanstack/hotkeys'
+
+// provider
+export * from './HotkeysProvider'
+
+// React-specific exports
+export * from './useHotkey'
+export * from './useHeldKeys'
+export * from './useHeldKeyCodes'
+export * from './useKeyHold'
+export * from './useHotkeySequence'
+export * from './useHotkeyRecorder'

package/src/useHeldKeyCodes.ts

@@ -0,0 +1,33 @@
+import { useStore } from '@tanstack/react-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+
+/**
+ * React hook that returns a map of currently held key names to their physical `event.code` values.
+ *
+ * This is useful for debugging which physical key was pressed (e.g. distinguishing
+ * left vs right Shift via "ShiftLeft" / "ShiftRight").
+ *
+ * @returns Record mapping normalized key names to their `event.code` values
+ *
+ * @example
+ * ```tsx
+ * function KeyDebugDisplay() {
+ *   const heldKeys = useHeldKeys()
+ *   const heldCodes = useHeldKeyCodes()
+ *
+ *   return (
+ *     <div>
+ *       {heldKeys.map((key) => (
+ *         <kbd key={key}>
+ *           {key} <small>{heldCodes[key]}</small>
+ *         </kbd>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useHeldKeyCodes(): Record<string, string> {
+  const tracker = getKeyStateTracker()
+  return useStore(tracker.store, (state) => state.heldCodes)
+}

package/src/useHeldKeys.ts

@@ -0,0 +1,29 @@
+import { useStore } from '@tanstack/react-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+
+/**
+ * React hook that returns an array of currently held keyboard keys.
+ *
+ * This hook uses `useStore` from `@tanstack/react-store` to subscribe
+ * to the global KeyStateTracker and updates whenever keys are pressed
+ * or released.
+ *
+ * @returns Array of currently held key names
+ *
+ * @example
+ * ```tsx
+ * function KeyDisplay() {
+ *   const heldKeys = useHeldKeys()
+ *
+ *   return (
+ *     <div>
+ *       Currently pressed: {heldKeys.join(' + ') || 'None'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useHeldKeys(): Array<string> {
+  const tracker = getKeyStateTracker()
+  return useStore(tracker.store, (state) => state.heldKeys)
+}

package/src/useHotkey.ts

@@ -0,0 +1,191 @@
+import { useEffect, useRef } from 'react'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type {
+  Hotkey,
+  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
+ *
+ * @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: Hotkey =
+    typeof hotkey === 'string'
+      ? hotkey
+      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)
+
+  // 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) {
+      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, options.enabled])
+
+  // 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)
+  }
+}
+
+/**
+ * Type guard to check if a value is a React ref-like object.
+ */
+function isRef(value: unknown): value is React.RefObject<HTMLElement | null> {
+  return value !== null && typeof value === 'object' && 'current' in value
+}

package/src/useHotkeyRecorder.ts

@@ -0,0 +1,101 @@
+import { useEffect, useRef } from 'react'
+import { useStore } 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 useStore (same pattern as useHeldKeys)
+  const isRecording = useStore(
+    recorderRef.current.store,
+    (state) => state.isRecording,
+  )
+  const recordedHotkey = useStore(
+    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/useHotkeySequence.ts

@@ -0,0 +1,92 @@
+import { useEffect, useRef } from 'react'
+import { getSequenceManager } from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type {
+  HotkeyCallback,
+  HotkeySequence,
+  SequenceOptions,
+} from '@tanstack/hotkeys'
+
+export interface UseHotkeySequenceOptions extends Omit<
+  SequenceOptions,
+  'enabled'
+> {
+  /** Whether the sequence is enabled. Defaults to true. */
+  enabled?: boolean
+}
+
+/**
+ * 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.
+ *
+ * @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
+ *
+ * @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 })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function useHotkeySequence(
+  sequence: HotkeySequence,
+  callback: HotkeyCallback,
+  options: UseHotkeySequenceOptions = {},
+): void {
+  const mergedOptions = {
+    ...useDefaultHotkeysOptions().hotkeySequence,
+    ...options,
+  } as UseHotkeySequenceOptions
+
+  const { enabled = true, ...sequenceOptions } = mergedOptions
+
+  // Extract options for stable dependencies
+  const { timeout, platform } = sequenceOptions
+
+  // Use refs to keep callback stable
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  // Serialize sequence for dependency comparison
+  const sequenceKey = sequence.join('|')
+
+  useEffect(() => {
+    if (!enabled || sequence.length === 0) {
+      return
+    }
+
+    const manager = getSequenceManager()
+
+    // Build options object conditionally to avoid overwriting manager defaults with undefined
+    const registerOptions: SequenceOptions = { enabled: true }
+    if (timeout !== undefined) registerOptions.timeout = timeout
+    if (platform !== undefined) registerOptions.platform = platform
+
+    const unregister = manager.register(
+      sequence,
+      (event, context) => callbackRef.current(event, context),
+      registerOptions,
+    )
+
+    return unregister
+  }, [enabled, sequence, sequenceKey, timeout, platform])
+}

package/src/useKeyHold.ts

@@ -0,0 +1,52 @@
+import { useStore } from '@tanstack/react-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import type { HeldKey } from '@tanstack/hotkeys'
+
+/**
+ * React hook that returns whether a specific key is currently being held.
+ *
+ * This hook uses `useStore` from `@tanstack/react-store` to subscribe
+ * to the global KeyStateTracker and uses a selector to determine if
+ * the specified key is held.
+ *
+ * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
+ * @returns True if the key is currently held down
+ *
+ * @example
+ * ```tsx
+ * function ShiftIndicator() {
+ *   const isShiftHeld = useKeyHold('Shift')
+ *
+ *   return (
+ *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
+ *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ModifierIndicators() {
+ *   const ctrl = useKeyHold('Control')
+ *   const shift = useKeyHold('Shift')
+ *   const alt = useKeyHold('Alt')
+ *
+ *   return (
+ *     <div>
+ *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
+ *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
+ *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useKeyHold(key: HeldKey): boolean {
+  const tracker = getKeyStateTracker()
+  const normalizedKey = key.toLowerCase()
+
+  return useStore(tracker.store, (state) =>
+    state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),
+  )
+}