@tanstack/react-hotkeys 0.11.0 → 0.12.1

package/src/useHotkeySequences.ts

@@ -1,192 +0,0 @@
-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) {
-        // 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()
-    }
-  }, [])
-}

package/src/useHotkeys.ts

@@ -1,193 +0,0 @@
-import { useEffect, useRef } from 'react'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import { isRef } from './utils'
-import type { UseHotkeyOptions } from './useHotkey'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-/**
- * A single hotkey definition for use with `useHotkeys`.
- */
-export interface UseHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: RegisterableHotkey
-  /** The function to call when the hotkey is pressed */
-  callback: HotkeyCallback
-  /** Per-hotkey options (merged on top of commonOptions) */
-  options?: UseHotkeyOptions
-}
-
-/**
- * React hook for registering multiple keyboard hotkeys at once.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * Accepts a dynamic array of hotkey definitions, making it safe to use
- * with 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.
- *
- * @param hotkeys - Array of hotkey definitions to register
- * @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
- * function Editor() {
- *   useHotkeys([
- *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
- *     { hotkey: 'Escape', callback: () => close() },
- *   ])
- * }
- * ```
- *
- * @example
- * ```tsx
- * function MenuShortcuts({ items }) {
- *   // Dynamic hotkeys from data -- safe because it's a single hook call
- *   useHotkeys(
- *     items.map((item) => ({
- *       hotkey: item.shortcut,
- *       callback: item.action,
- *       options: { enabled: item.enabled },
- *     })),
- *     { preventDefault: true },
- *   )
- * }
- * ```
- */
-export function useHotkeys(
-  hotkeys: Array<UseHotkeyDefinition>,
-  commonOptions: UseHotkeyOptions = {},
-): void {
-  type RegistrationRecord = {
-    handle: HotkeyRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = useDefaultHotkeysOptions().hotkey
-  const manager = getHotkeyManager()
-  const platform =
-    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()
-
-  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())
-  const hotkeysRef = useRef(hotkeys)
-  const hotkeyStringsRef = useRef<Array<Hotkey>>([])
-  const commonOptionsRef = useRef(commonOptions)
-  const defaultOptionsRef = useRef(defaultOptions)
-  const managerRef = useRef(manager)
-
-  const hotkeyStrings = hotkeys.map((def) =>
-    normalizeRegisterableHotkey(def.hotkey, platform),
-  )
-
-  hotkeysRef.current = hotkeys
-  hotkeyStringsRef.current = hotkeyStrings
-  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 hotkeysRef.current)[number]
-      hotkeyStr: Hotkey
-      mergedOptions: UseHotkeyOptions
-      resolvedTarget: Document | HTMLElement | Window
-    }> = []
-
-    for (let i = 0; i < hotkeysRef.current.length; i++) {
-      const def = hotkeysRef.current[i]!
-      const hotkeyStr = hotkeyStringsRef.current[i]!
-      const mergedOptions = {
-        ...defaultOptionsRef.current,
-        ...commonOptionsRef.current,
-        ...def.options,
-      } as UseHotkeyOptions
-
-      const resolvedTarget = isRef(mergedOptions.target)
-        ? mergedOptions.target.current
-        : (mergedOptions.target ??
-          (typeof document !== 'undefined' ? document : null))
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const registrationKey = `${i}:${hotkeyStr}`
-      rows.push({
-        registrationKey,
-        def,
-        hotkeyStr,
-        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, hotkeyStr, 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(hotkeyStr, 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()
-    }
-  }, [])
-}

package/src/useKeyHold.ts

@@ -1,52 +0,0 @@
-import { useSelector } from '@tanstack/react-store'
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import type { IndividualKey } from '@tanstack/hotkeys'
-
-/**
- * React hook that returns whether a specific key is currently being held.
- *
- * This hook uses `useSelector` 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: IndividualKey): boolean {
-  const tracker = getKeyStateTracker()
-  const normalizedKey = key.toLowerCase()
-
-  return useSelector(tracker.store, (state) =>
-    state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),
-  )
-}

package/src/utils.ts

@@ -1,10 +0,0 @@
-import type React from 'react'
-
-/**
- * Type guard to check if a value is a React ref-like object.
- */
-export function isRef(
-  value: unknown,
-): value is React.RefObject<HTMLElement | null> {
-  return value !== null && typeof value === 'object' && 'current' in value
-}