@tanstack/solid-hotkeys 0.10.0 → 0.12.0

package/src/createHotkeyRegistrations.ts

@@ -1,45 +0,0 @@
-import { useSelector } from '@tanstack/solid-store'
-import {
-  getHotkeyManager,
-  getSequenceManager,
-  toHotkeyRegistrationView,
-} from '@tanstack/hotkeys'
-import type {
-  HotkeyRegistrationView,
-  SequenceRegistrationView,
-} from '@tanstack/hotkeys'
-
-/**
- * Return type for createHotkeyRegistrations.
- */
-export interface HotkeyRegistrationsResult {
-  /** Accessor for all registered hotkeys (public view, no callbacks) */
-  hotkeys: () => Array<HotkeyRegistrationView>
-  /** Accessor for all registered sequences */
-  sequences: () => Array<SequenceRegistrationView>
-}
-
-/**
- * Solid primitive that reactively reads all hotkey and sequence registrations
- * from the singleton managers.
- *
- * This is a standalone primitive that does NOT require the HotkeysProvider.
- * It subscribes to both HotkeyManager and SequenceManager stores and
- * triggers reactivity when registrations change.
- *
- * @returns Object with `hotkeys` and `sequences` signal accessors
- */
-export function createHotkeyRegistrations(): 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/createHotkeySequence.ts

@@ -1,155 +0,0 @@
-import { createEffect, onCleanup, untrack } from 'solid-js'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceOptions,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-
-export interface CreateHotkeySequenceOptions extends Omit<
-  SequenceOptions,
-  'target'
-> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a direct DOM element, an accessor, or null. Defaults to document.
-   */
-  target?: HTMLElement | Document | Window | null
-}
-
-/**
- * SolidJS primitive for registering a keyboard shortcut sequence (Vim-style).
- *
- * This primitive 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 (or accessor function)
- * @param callback - Function to call when the sequence is completed
- * @param options - Options for the sequence behavior (or accessor function)
- *
- * @example
- * ```tsx
- * function VimEditor() {
- *   // 'g g' to go to top
- *   createHotkeySequence(['G', 'G'], () => {
- *     scrollToTop()
- *   })
- *
- *   // 'd d' to delete line
- *   createHotkeySequence(['D', 'D'], () => {
- *     deleteLine()
- *   })
- *
- *   // 'd i w' to delete inner word
- *   createHotkeySequence(['D', 'I', 'W'], () => {
- *     deleteInnerWord()
- *   }, { timeout: 500 })
- *
- *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
- *   createHotkeySequence(['Shift+R', 'Shift+T'], () => {
- *     nextAction()
- *   })
- *
- *   return <div>...</div>
- * }
- * ```
- */
-export function createHotkeySequence(
-  sequence: HotkeySequence | (() => HotkeySequence),
-  callback: HotkeyCallback,
-  options:
-    | CreateHotkeySequenceOptions
-    | (() => CreateHotkeySequenceOptions) = {},
-): void {
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getSequenceManager()
-
-  let registration: SequenceRegistrationHandle | null = null
-  let lastSequenceKey: string | null = null
-  let lastTarget: HTMLElement | Document | Window | null = null
-
-  onCleanup(() => {
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-    lastSequenceKey = null
-    lastTarget = null
-  })
-
-  createEffect(() => {
-    // Resolve reactive values
-    const resolvedSequence =
-      typeof sequence === 'function' ? sequence() : sequence
-    const resolvedOptions = typeof options === 'function' ? options() : options
-
-    const mergedOptions = {
-      ...defaultOptions.hotkeySequence,
-      ...resolvedOptions,
-    } as CreateHotkeySequenceOptions
-
-    // Extract options without target (target is handled separately)
-    const { target: _target, ...optionsWithoutTarget } = mergedOptions
-
-    // Resolve target: when explicitly provided (even as null), use it and skip if null.
-    // When not provided, default to document. Matches createHotkey.
-    const resolvedTarget =
-      'target' in mergedOptions
-        ? (mergedOptions.target ?? null)
-        : typeof document !== 'undefined'
-          ? document
-          : null
-
-    if (resolvedSequence.length === 0 || !resolvedTarget) {
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-      lastSequenceKey = null
-      lastTarget = null
-      return
-    }
-
-    const sequenceKey = formatHotkeySequence(resolvedSequence)
-
-    // Untrack store mutations so that registering/updating the sequence doesn't
-    // create a circular reactive dependency when createHotkeyRegistrations
-    // subscribes to the same store.
-    untrack(() => {
-      if (
-        registration?.isActive &&
-        lastSequenceKey === sequenceKey &&
-        lastTarget === resolvedTarget
-      ) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-        return
-      }
-
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-
-      registration = manager.register(resolvedSequence, callback, {
-        ...mergedOptions,
-        target: resolvedTarget,
-      })
-
-      if (registration.isActive) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-      }
-
-      lastSequenceKey = sequenceKey
-      lastTarget = resolvedTarget
-    })
-  })
-}

package/src/createHotkeySequenceRecorder.ts

@@ -1,66 +0,0 @@
-import { createEffect, onCleanup } from 'solid-js'
-import { useSelector } from '@tanstack/solid-store'
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type {
-  HotkeySequence,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-
-export interface SolidHotkeySequenceRecorder {
-  isRecording: () => boolean
-  steps: () => HotkeySequence
-  recordedSequence: () => HotkeySequence | null
-  startRecording: () => void
-  stopRecording: () => void
-  cancelRecording: () => void
-  commitRecording: () => void
-}
-
-/**
- * SolidJS primitive for recording multi-chord sequences (Vim-style shortcuts).
- */
-export function createHotkeySequenceRecorder(
-  options:
-    | HotkeySequenceRecorderOptions
-    | (() => HotkeySequenceRecorderOptions),
-): SolidHotkeySequenceRecorder {
-  const defaultOptions = useDefaultHotkeysOptions()
-
-  const resolvedOptions = typeof options === 'function' ? options() : options
-  const mergedOptions = {
-    ...defaultOptions.hotkeySequenceRecorder,
-    ...resolvedOptions,
-  } as HotkeySequenceRecorderOptions
-
-  const recorder = new HotkeySequenceRecorder(mergedOptions)
-
-  const isRecording = useSelector(recorder.store, (state) => state.isRecording)
-  const steps = useSelector(recorder.store, (state) => state.steps)
-  const recordedSequence = useSelector(
-    recorder.store,
-    (state) => state.recordedSequence,
-  )
-
-  createEffect(() => {
-    const resolved = typeof options === 'function' ? options() : options
-    recorder.setOptions({
-      ...defaultOptions.hotkeySequenceRecorder,
-      ...resolved,
-    } as HotkeySequenceRecorderOptions)
-  })
-
-  onCleanup(() => {
-    recorder.destroy()
-  })
-
-  return {
-    isRecording,
-    steps,
-    recordedSequence,
-    startRecording: () => recorder.start(),
-    stopRecording: () => recorder.stop(),
-    cancelRecording: () => recorder.cancel(),
-    commitRecording: () => recorder.commit(),
-  }
-}

package/src/createHotkeySequences.ts

@@ -1,181 +0,0 @@
-import { createEffect, onCleanup, untrack } from 'solid-js'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type { CreateHotkeySequenceOptions } from './createHotkeySequence'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-
-/**
- * A single sequence definition for use with `createHotkeySequences`.
- */
-export interface CreateHotkeySequenceDefinition {
-  /** 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?: CreateHotkeySequenceOptions
-}
-
-/**
- * SolidJS primitive for registering multiple keyboard shortcut sequences at once (Vim-style).
- *
- * Uses the singleton SequenceManager. Accepts a dynamic array of definitions, or accessors,
- * so you can react to variable-length lists.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * Definitions with an empty `sequence` are skipped (no registration).
- *
- * @param sequences - Array of sequence definitions, or accessor returning them
- * @param commonOptions - Shared options for all sequences, or accessor
- *
- * @example
- * ```tsx
- * function VimPalette() {
- *   createHotkeySequences([
- *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
- *     { sequence: ['D', 'D'], callback: () => deleteLine() },
- *   ])
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Dynamic(props) {
- *   createHotkeySequences(
- *     () => props.items.map((item) => ({
- *       sequence: item.chords,
- *       callback: item.action,
- *       options: { enabled: item.enabled },
- *     })),
- *     { preventDefault: true },
- *   )
- * }
- * ```
- */
-export function createHotkeySequences(
-  sequences:
-    | Array<CreateHotkeySequenceDefinition>
-    | (() => Array<CreateHotkeySequenceDefinition>),
-  commonOptions:
-    | CreateHotkeySequenceOptions
-    | (() => CreateHotkeySequenceOptions) = {},
-): void {
-  type RegistrationRecord = {
-    handle: SequenceRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getSequenceManager()
-
-  const registrations = new Map<string, RegistrationRecord>()
-
-  onCleanup(() => {
-    for (const { handle } of registrations.values()) {
-      if (handle.isActive) {
-        handle.unregister()
-      }
-    }
-    registrations.clear()
-  })
-
-  createEffect(() => {
-    const resolved = typeof sequences === 'function' ? sequences() : sequences
-    const resolvedCommonOptions =
-      typeof commonOptions === 'function' ? commonOptions() : commonOptions
-
-    const nextKeys = new Set<string>()
-    const prepared: Array<{
-      registrationKey: string
-      def: CreateHotkeySequenceDefinition
-      mergedOptions: CreateHotkeySequenceOptions
-      sequenceString: string
-      resolvedTarget: Document | HTMLElement | Window
-    }> = []
-
-    for (let i = 0; i < resolved.length; i++) {
-      const def = resolved[i]!
-      const resolvedDefOptions = def.options ?? {}
-
-      const mergedOptions = {
-        ...defaultOptions.hotkeySequence,
-        ...resolvedCommonOptions,
-        ...resolvedDefOptions,
-      } as CreateHotkeySequenceOptions
-
-      if (def.sequence.length === 0) {
-        continue
-      }
-
-      const sequenceString = formatHotkeySequence(def.sequence)
-
-      const resolvedTarget =
-        'target' in mergedOptions
-          ? (mergedOptions.target ?? null)
-          : typeof document !== 'undefined'
-            ? document
-            : null
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const registrationKey = `${i}:${sequenceString}`
-      nextKeys.add(registrationKey)
-      prepared.push({
-        registrationKey,
-        def,
-        mergedOptions,
-        sequenceString,
-        resolvedTarget,
-      })
-    }
-
-    // Untrack store mutations so that registering/updating sequences doesn't
-    // create a circular reactive dependency when createHotkeyRegistrations
-    // subscribes to the same store.
-    untrack(() => {
-      for (const [key, record] of [...registrations.entries()]) {
-        if (!nextKeys.has(key)) {
-          if (record.handle.isActive) {
-            record.handle.unregister()
-          }
-          registrations.delete(key)
-        }
-      }
-
-      for (const p of prepared) {
-        const existing = registrations.get(p.registrationKey)
-        if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
-          existing.handle.callback = p.def.callback
-          const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-          existing.handle.setOptions(optionsWithoutTarget)
-          continue
-        }
-
-        if (existing) {
-          if (existing.handle.isActive) {
-            existing.handle.unregister()
-          }
-          registrations.delete(p.registrationKey)
-        }
-
-        const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-        const handle = manager.register(p.def.sequence, p.def.callback, {
-          ...optionsWithoutTarget,
-          target: p.resolvedTarget,
-        })
-        registrations.set(p.registrationKey, {
-          handle,
-          target: p.resolvedTarget,
-        })
-      }
-    })
-  })
-}

package/src/createHotkeys.ts

@@ -1,187 +0,0 @@
-import { createEffect, onCleanup, untrack } from 'solid-js'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import type { CreateHotkeyOptions } from './createHotkey'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-/**
- * A single hotkey definition for use with `createHotkeys`.
- */
-export interface CreateHotkeyDefinition {
-  /** 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?: CreateHotkeyOptions
-}
-
-/**
- * SolidJS primitive 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.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * @param hotkeys - Array of hotkey definitions, or accessor returning them
- * @param commonOptions - Shared options applied to all hotkeys, or accessor
- *
- * @example
- * ```tsx
- * function Editor() {
- *   createHotkeys([
- *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
- *     { hotkey: 'Escape', callback: () => close() },
- *   ])
- * }
- * ```
- *
- * @example
- * ```tsx
- * function MenuShortcuts(props) {
- *   createHotkeys(
- *     () => props.items.map((item) => ({
- *       hotkey: item.shortcut,
- *       callback: item.action,
- *       options: { enabled: item.enabled },
- *     })),
- *     { preventDefault: true },
- *   )
- * }
- * ```
- */
-export function createHotkeys(
-  hotkeys:
-    | Array<CreateHotkeyDefinition>
-    | (() => Array<CreateHotkeyDefinition>),
-  commonOptions: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},
-): void {
-  type RegistrationRecord = {
-    handle: HotkeyRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getHotkeyManager()
-
-  const registrations = new Map<string, RegistrationRecord>()
-
-  // Clean up only when this component/scope disposes — not before every effect
-  // re-run. An inner `onCleanup` inside `createEffect` runs whenever reactive
-  // deps change (e.g. dynamic hotkey list), which unregistered every hotkey and
-  // re-registered them, flooding the manager store and could freeze the tab.
-  onCleanup(() => {
-    for (const { handle } of registrations.values()) {
-      if (handle.isActive) {
-        handle.unregister()
-      }
-    }
-    registrations.clear()
-  })
-
-  createEffect(() => {
-    const resolvedHotkeys = typeof hotkeys === 'function' ? hotkeys() : hotkeys
-    const resolvedCommonOptions =
-      typeof commonOptions === 'function' ? commonOptions() : commonOptions
-
-    const nextKeys = new Set<string>()
-    const prepared: Array<{
-      registrationKey: string
-      def: CreateHotkeyDefinition
-      mergedOptions: CreateHotkeyOptions
-      hotkeyString: Hotkey
-      resolvedTarget: Document | HTMLElement | Window
-    }> = []
-
-    for (let i = 0; i < resolvedHotkeys.length; i++) {
-      const def = resolvedHotkeys[i]!
-      const resolvedDefOptions = def.options ?? {}
-
-      const mergedOptions = {
-        ...defaultOptions.hotkey,
-        ...resolvedCommonOptions,
-        ...resolvedDefOptions,
-      } as CreateHotkeyOptions
-
-      const platform = mergedOptions.platform ?? detectPlatform()
-      const hotkeyString = normalizeRegisterableHotkey(def.hotkey, platform)
-
-      const resolvedTarget =
-        'target' in mergedOptions
-          ? (mergedOptions.target ?? null)
-          : typeof document !== 'undefined'
-            ? document
-            : null
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const registrationKey = `${i}:${hotkeyString}`
-      nextKeys.add(registrationKey)
-      prepared.push({
-        registrationKey,
-        def,
-        mergedOptions,
-        hotkeyString,
-        resolvedTarget,
-      })
-    }
-
-    // Untrack store mutations so that registering/updating hotkeys doesn't
-    // create a circular reactive dependency when createHotkeyRegistrations
-    // subscribes to the same store.
-    untrack(() => {
-      // Drop stale keys first so list index shifts don't briefly double-register
-      // the same hotkey+target (conflictBehavior: 'warn' + devtools can loop).
-      for (const [key, record] of [...registrations.entries()]) {
-        if (!nextKeys.has(key)) {
-          if (record.handle.isActive) {
-            record.handle.unregister()
-          }
-          registrations.delete(key)
-        }
-      }
-
-      for (const p of prepared) {
-        const existing = registrations.get(p.registrationKey)
-        if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
-          existing.handle.callback = p.def.callback
-          const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-          existing.handle.setOptions(optionsWithoutTarget)
-          continue
-        }
-
-        if (existing) {
-          if (existing.handle.isActive) {
-            existing.handle.unregister()
-          }
-          registrations.delete(p.registrationKey)
-        }
-
-        const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-        const handle = manager.register(p.hotkeyString, p.def.callback, {
-          ...optionsWithoutTarget,
-          target: p.resolvedTarget,
-        })
-        registrations.set(p.registrationKey, {
-          handle,
-          target: p.resolvedTarget,
-        })
-      }
-    })
-  })
-}

package/src/createKeyHold.ts

@@ -1,59 +0,0 @@
-import { createMemo } from 'solid-js'
-import { useSelector } from '@tanstack/solid-store'
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import type { IndividualKey } from '@tanstack/hotkeys'
-
-/**
- * SolidJS primitive that returns whether a specific key is currently being held.
- *
- * This primitive uses `useSelector` from `@tanstack/solid-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') - can be an accessor function
- * @returns Signal accessor that returns true if the key is currently held down
- *
- * @example
- * ```tsx
- * function ShiftIndicator() {
- *   const isShiftHeld = createKeyHold('Shift')
- *
- *   return (
- *     <div style={{ opacity: isShiftHeld() ? 1 : 0.5 }}>
- *       {isShiftHeld() ? 'Shift is pressed!' : 'Press Shift'}
- *     </div>
- *   )
- * }
- * ```
- *
- * @example
- * ```tsx
- * function ModifierIndicators() {
- *   const ctrl = createKeyHold('Control')
- *   const shift = createKeyHold('Shift')
- *   const alt = createKeyHold('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 createKeyHold(
-  key: IndividualKey | (() => IndividualKey),
-): () => boolean {
-  const tracker = getKeyStateTracker()
-  const heldKeysSelector = useSelector(tracker.store, (state) => state.heldKeys)
-
-  return createMemo(() => {
-    const resolvedKey = typeof key === 'function' ? key() : key
-    const normalizedKey = resolvedKey.toLowerCase()
-    return heldKeysSelector().some(
-      (heldKey) => heldKey.toLowerCase() === normalizedKey,
-    )
-  })
-}