@tanstack/preact-hotkeys 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-hotkeys",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Preact adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@tanstack/preact-store": "^0.11.2",
-    "@tanstack/hotkeys": "0.5.0"
+    "@tanstack/hotkeys": "0.6.0"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.5",

package/src/index.ts

@@ -11,5 +11,6 @@ export * from './useHeldKeys'
 export * from './useHeldKeyCodes'
 export * from './useKeyHold'
 export * from './useHotkeySequence'
+export * from './useHotkeySequences'
 export * from './useHotkeyRecorder'
 export * from './useHotkeySequenceRecorder'

package/src/useHotkey.ts

@@ -1,15 +1,13 @@
 import { useEffect, useRef } from 'preact/hooks'
 import {
   detectPlatform,
-  formatHotkey,
   getHotkeyManager,
-  rawHotkeyToParsedHotkey,
+  normalizeRegisterableHotkey,
 } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
 import { isRef } from './utils'
 import type { RefObject } from 'preact'
 import type {
-  Hotkey,
   HotkeyCallback,
   HotkeyOptions,
   HotkeyRegistrationHandle,
@@ -44,7 +42,8 @@ export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
  *
  * @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
+ * @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
@@ -119,10 +118,7 @@ export function useHotkey(
 
   // Normalize to hotkey string
   const platform = mergedOptions.platform ?? detectPlatform()
-  const hotkeyString: Hotkey =
-    typeof hotkey === 'string'
-      ? hotkey
-      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)
+  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)
 
   // Extract options without target (target is handled separately)
   const { target: _target, ...optionsWithoutTarget } = mergedOptions
@@ -136,6 +132,12 @@ export function useHotkey(
 
     // 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
     }
 
@@ -175,7 +177,7 @@ export function useHotkey(
         registrationRef.current = null
       }
     }
-  }, [hotkeyString, options.enabled])
+  }, [hotkeyString])
 
   // Sync callback and options on EVERY render (outside useEffect)
   // This avoids stale closures - the callback always has access to latest state

package/src/useHotkeySequence.ts

@@ -41,7 +41,8 @@ export interface UseHotkeySequenceOptions extends Omit<
  *
  * @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
+ * @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
@@ -89,11 +90,13 @@ export function useHotkeySequence(
   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)
@@ -106,7 +109,13 @@ export function useHotkeySequence(
   const { target: _target, ...optionsWithoutTarget } = mergedOptions
 
   useEffect(() => {
-    if (sequence.length === 0) {
+    if (sequenceRef.current.length === 0) {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+      prevTargetRef.current = null
+      prevSequenceRef.current = null
       return
     }
 
@@ -118,6 +127,12 @@ export function useHotkeySequence(
 
     // 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
     }
 
@@ -140,7 +155,7 @@ export function useHotkeySequence(
     // Register if needed (no active registration)
     if (!registrationRef.current || !registrationRef.current.isActive) {
       registrationRef.current = managerRef.current.register(
-        sequence,
+        sequenceRef.current,
         (event, context) => callbackRef.current(event, context),
         {
           ...optionsRef.current,
@@ -160,7 +175,7 @@ export function useHotkeySequence(
         registrationRef.current = null
       }
     }
-  }, [hotkeySequenceString, mergedOptions.enabled, sequence])
+  }, [hotkeySequenceString])
 
   // Sync callback and options on EVERY render (outside useEffect)
   if (registrationRef.current?.isActive) {

package/src/useHotkeySequences.ts

@@ -0,0 +1,206 @@
+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) {
+        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 'preact/hooks'
 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,18 +101,6 @@ export function useHotkeys(
   defaultOptionsRef.current = defaultOptions
   managerRef.current = manager
 
-  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>()
@@ -186,7 +174,9 @@ export function useHotkeys(
     }
 
     registrationsRef.current = nextRegistrations
+  })
 
+  useEffect(() => {
     return () => {
       for (const { handle } of registrationsRef.current.values()) {
         if (handle.isActive) {
@@ -195,7 +185,7 @@ export function useHotkeys(
       }
       registrationsRef.current = new Map()
     }
-  }, [hotkeyKey, enabledKey])
+  }, [])
 
   for (let i = 0; i < hotkeys.length; i++) {
     const def = hotkeys[i]!