@tanstack/react-hotkeys 0.6.0 → 0.8.0

package/src/useHotkeySequences.ts

@@ -0,0 +1,206 @@
+import { useEffect, useRef } from 'react'
+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
+}
+
+/**
+ * React 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) {
+        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()
+    }
+  }, [])
+
+  for (let i = 0; i < definitions.length; i++) {
+    const def = definitions[i]!
+    const seqStr = sequenceStrings[i]!
+    const registrationKey = `${i}:${seqStr}`
+    const handle = registrationsRef.current.get(registrationKey)?.handle
+
+    if (handle?.isActive && def.sequence.length > 0) {
+      handle.callback = def.callback
+      const mergedOptions = {
+        ...defaultOptions,
+        ...commonOptions,
+        ...def.options,
+      } as UseHotkeySequenceOptions
+      const { target: _target, ...optionsWithoutTarget } = mergedOptions
+      handle.setOptions(optionsWithoutTarget)
+    }
+  }
+}

package/src/useHotkeys.ts

@@ -1,9 +1,8 @@
 import { useEffect, useRef } from 'react'
 import {
   detectPlatform,
-  formatHotkey,
   getHotkeyManager,
-  rawHotkeyToParsedHotkey,
+  normalizeRegisterableHotkey,
 } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
 import { isRef } from './utils'
@@ -40,7 +39,10 @@ export interface UseHotkeyDefinition {
  * Callbacks and options are synced on every render to avoid stale closures.
  *
  * @param hotkeys - Array of hotkey definitions to register
- * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` 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
@@ -90,9 +92,7 @@ export function useHotkeys(
   const managerRef = useRef(manager)
 
   const hotkeyStrings = hotkeys.map((def) =>
-    typeof def.hotkey === 'string'
-      ? def.hotkey
-      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),
+    normalizeRegisterableHotkey(def.hotkey, platform),
   )
 
   hotkeysRef.current = hotkeys
@@ -101,19 +101,6 @@ export function useHotkeys(
   defaultOptionsRef.current = defaultOptions
   managerRef.current = manager
 
-  // Stable serialized keys for effect dependencies
-  const hotkeyKey = hotkeyStrings.join('\0')
-  const enabledKey = hotkeys
-    .map((def) => {
-      const merged = {
-        ...defaultOptions,
-        ...commonOptions,
-        ...def.options,
-      }
-      return merged.enabled ?? true
-    })
-    .join('\0')
-
   useEffect(() => {
     const prevRegistrations = registrationsRef.current
     const nextRegistrations = new Map<string, RegistrationRecord>()
@@ -187,7 +174,9 @@ export function useHotkeys(
     }
 
     registrationsRef.current = nextRegistrations
+  })
 
+  useEffect(() => {
     return () => {
       for (const { handle } of registrationsRef.current.values()) {
         if (handle.isActive) {
@@ -196,7 +185,7 @@ export function useHotkeys(
       }
       registrationsRef.current = new Map()
     }
-  }, [hotkeyKey, enabledKey])
+  }, [])
 
   // Sync callbacks and options on EVERY render (outside useEffect)
   for (let i = 0; i < hotkeys.length; i++) {