@tanstack/svelte-hotkeys 0.11.0 → 0.12.0

package/src/createHotkeyRecorder.svelte.ts

@@ -1,121 +0,0 @@
-import { HotkeyRecorder } from '@tanstack/hotkeys'
-import { onDestroy } from 'svelte'
-import { getDefaultHotkeysOptions } from './HotkeysCtx'
-import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte'
-import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
-import type { MaybeGetter } from './internal.svelte'
-
-export interface SvelteHotkeyRecorder {
-  /** Whether recording is currently active */
-  readonly isRecording: boolean
-  /** The currently recorded hotkey (for live preview) */
-  readonly recordedHotkey: Hotkey | null
-  /** Start recording a new hotkey */
-  startRecording: () => void
-  /** Stop recording (same as cancel) */
-  stopRecording: () => void
-  /** Cancel recording without saving */
-  cancelRecording: () => void
-}
-
-/**
- * Svelte function for recording keyboard shortcuts.
- *
- * This function 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
- * ```svelte
- * <script>
- *   import { createHotkeyRecorder } from '@tanstack/svelte-hotkeys'
- *
- *   const recorder = createHotkeyRecorder({
- *     onRecord: (hotkey) => {
- *       console.log('Recorded:', hotkey) // e.g., "Mod+Shift S"
- *     },
- *     onCancel: () => {
- *       console.log('Recording cancelled')
- *     },
- *   })
- * </script>
- *
- * <div>
- *   <button onclick={recorder.startRecording}>
- *     {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
- *   </button>
- *   {#if recorder.recordedHotkey}
- *     <div>Recording: {recorder.recordedHotkey}</div>
- *   {/if}
- * </div>
- * ```
- */
-
-class SvelteHotkeyRecorderState implements SvelteHotkeyRecorder {
-  #recorder: HotkeyRecorder
-  #subscribe: () => void
-
-  constructor(options: HotkeyRecorderOptions) {
-    this.#recorder = new HotkeyRecorder(options)
-    this.#subscribe = createStoreSubscriber(this.#recorder.store)
-  }
-
-  get isRecording(): boolean {
-    this.#subscribe()
-    return this.#recorder.store.state.isRecording
-  }
-
-  get recordedHotkey(): Hotkey | null {
-    this.#subscribe()
-    return this.#recorder.store.state.recordedHotkey
-  }
-
-  setOptions(options: HotkeyRecorderOptions): void {
-    this.#recorder.setOptions(options)
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  startRecording = (): void => {
-    this.#recorder.start()
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  stopRecording = (): void => {
-    this.#recorder.stop()
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  cancelRecording = (): void => {
-    this.#recorder.cancel()
-  }
-
-  destroy(): void {
-    this.#recorder.destroy()
-  }
-}
-
-export function createHotkeyRecorder(
-  options: MaybeGetter<HotkeyRecorderOptions>,
-): SvelteHotkeyRecorder {
-  const recorder = new SvelteHotkeyRecorderState({
-    ...getDefaultHotkeysOptions().hotkeyRecorder,
-    ...resolveMaybeGetter(options),
-  } as HotkeyRecorderOptions)
-
-  $effect(() => {
-    recorder.setOptions({
-      ...getDefaultHotkeysOptions().hotkeyRecorder,
-      ...resolveMaybeGetter(options),
-    } as HotkeyRecorderOptions)
-  })
-
-  onDestroy(() => {
-    recorder.destroy()
-  })
-
-  return recorder
-}

package/src/createHotkeySequence.svelte.ts

@@ -1,207 +0,0 @@
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { onDestroy } from 'svelte'
-import { getDefaultHotkeysOptions } from './HotkeysCtx'
-import { resolveMaybeGetter } from './internal.svelte'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceOptions,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-import type { MaybeGetter } from './internal.svelte'
-import type { Attachment } from 'svelte/attachments'
-
-export interface CreateHotkeySequenceOptions extends Omit<
-  SequenceOptions,
-  'target'
-> {
-  target?: Document | Window // not html elements, use attachment instead
-}
-
-function registerHotkeySequence(
-  target: HTMLElement | Document | Window,
-  sequence: HotkeySequence,
-  callback: HotkeyCallback,
-  mergedOptions: CreateHotkeySequenceOptions,
-) {
-  return getSequenceManager().register(sequence, callback, {
-    ...mergedOptions,
-    target,
-  })
-}
-
-/**
- * Register a global keyboard shortcut sequence for the current component.
- *
- * 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.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeySequence } from '@tanstack/svelte-hotkeys'
- *
- *   // Scroll to top when 'G G' is pressed
- *   createHotkeySequence(['G', 'G'], () => {
- *     scrollToTop()
- *   })
- *
- *   // Delete line when 'D D' is pressed
- *   createHotkeySequence(['D', 'D'], () => {
- *     deleteLine()
- *   })
- *
- *   // Delete inner word when 'D I W' is pressed
- *   createHotkeySequence(['D', 'I', 'W'], () => {
- *     deleteInnerWord()
- *   }, { timeout: 500 })
- *
- *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
- *   createHotkeySequence(['Shift+R', 'Shift+T'], () => {
- *     nextAction()
- *   })
- * </script>
- *
- * <div>
- *   ....
- * </div>
- * ```
- */
-export function createHotkeySequence(
-  sequence: MaybeGetter<HotkeySequence>,
-  callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeySequenceOptions> = {},
-): void {
-  let registration: SequenceRegistrationHandle | null = null
-  let lastSequenceKey: string | null = null
-
-  $effect(() => {
-    if (typeof document === 'undefined') {
-      return
-    }
-
-    const resolvedSequence = resolveMaybeGetter(sequence)
-    const resolvedOptions = resolveMaybeGetter(options)
-    const mergedOptions = {
-      ...getDefaultHotkeysOptions().hotkeySequence,
-      ...resolvedOptions,
-    } as CreateHotkeySequenceOptions
-
-    const { target: _t, ...optionsWithoutTarget } = mergedOptions
-
-    if (resolvedSequence.length === 0) {
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-      lastSequenceKey = null
-      return
-    }
-
-    const sequenceKey = formatHotkeySequence(resolvedSequence)
-
-    if (registration?.isActive && lastSequenceKey === sequenceKey) {
-      registration.callback = callback
-      registration.setOptions(optionsWithoutTarget)
-      return
-    }
-
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-
-    registration = registerHotkeySequence(
-      document,
-      resolvedSequence,
-      callback,
-      mergedOptions,
-    )
-    lastSequenceKey = sequenceKey
-  })
-
-  onDestroy(() => {
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-  })
-}
-
-/**
- * Create an attachment for element-scoped keyboard sequences.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeySequenceAttachment } from '@tanstack/svelte-hotkeys'
- *
- *   const vimKeys = createHotkeySequenceAttachment(['G', 'G'], () => {
- *     scrollToTop()
- *   })
- * </script>
- *
- * <div tabindex="0" {@attach vimKeys}>
- *   Focus here and press g then g
- * </div>
- * ```
- */
-export function createHotkeySequenceAttachment(
-  sequence: MaybeGetter<HotkeySequence>,
-  callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeySequenceOptions> = {},
-): Attachment<HTMLElement> {
-  return (element) => {
-    let registration: SequenceRegistrationHandle | null = null
-    let lastSequenceKey: string | null = null
-
-    $effect(() => {
-      const resolvedSequence = resolveMaybeGetter(sequence)
-      const resolvedOptions = resolveMaybeGetter(options)
-      const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkeySequence,
-        ...resolvedOptions,
-      } as CreateHotkeySequenceOptions
-
-      const { target: _t, ...optionsWithoutTarget } = mergedOptions
-
-      if (resolvedSequence.length === 0) {
-        if (registration?.isActive) {
-          registration.unregister()
-          registration = null
-        }
-        lastSequenceKey = null
-        return
-      }
-
-      const sequenceKey = formatHotkeySequence(resolvedSequence)
-
-      if (registration?.isActive && lastSequenceKey === sequenceKey) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-        return
-      }
-
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-
-      registration = registerHotkeySequence(
-        element,
-        resolvedSequence,
-        callback,
-        mergedOptions,
-      )
-      lastSequenceKey = sequenceKey
-    })
-
-    return () => {
-      if (registration?.isActive) {
-        registration.unregister()
-      }
-    }
-  }
-}

package/src/createHotkeySequenceRecorder.svelte.ts

@@ -1,97 +0,0 @@
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
-import { onDestroy } from 'svelte'
-import { getDefaultHotkeysOptions } from './HotkeysCtx'
-import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte'
-import type {
-  HotkeySequence,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-import type { MaybeGetter } from './internal.svelte'
-
-export interface SvelteHotkeySequenceRecorder {
-  readonly isRecording: boolean
-  readonly steps: HotkeySequence
-  readonly recordedSequence: HotkeySequence | null
-  startRecording: () => void
-  stopRecording: () => void
-  cancelRecording: () => void
-  commitRecording: () => void
-}
-
-class SvelteHotkeySequenceRecorderState implements SvelteHotkeySequenceRecorder {
-  #recorder: HotkeySequenceRecorder
-  #subscribe: () => void
-
-  constructor(options: HotkeySequenceRecorderOptions) {
-    this.#recorder = new HotkeySequenceRecorder(options)
-    this.#subscribe = createStoreSubscriber(this.#recorder.store)
-  }
-
-  get isRecording(): boolean {
-    this.#subscribe()
-    return this.#recorder.store.state.isRecording
-  }
-
-  get steps(): HotkeySequence {
-    this.#subscribe()
-    return this.#recorder.store.state.steps
-  }
-
-  get recordedSequence(): HotkeySequence | null {
-    this.#subscribe()
-    return this.#recorder.store.state.recordedSequence
-  }
-
-  setOptions(options: HotkeySequenceRecorderOptions): void {
-    this.#recorder.setOptions(options)
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  startRecording = (): void => {
-    this.#recorder.start()
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  stopRecording = (): void => {
-    this.#recorder.stop()
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  cancelRecording = (): void => {
-    this.#recorder.cancel()
-  }
-
-  // Keep the recorder receiver when used directly as an event handler.
-  commitRecording = (): void => {
-    this.#recorder.commit()
-  }
-
-  destroy(): void {
-    this.#recorder.destroy()
-  }
-}
-
-/**
- * Svelte helper for recording multi-chord sequences (Vim-style shortcuts).
- */
-export function createHotkeySequenceRecorder(
-  options: MaybeGetter<HotkeySequenceRecorderOptions>,
-): SvelteHotkeySequenceRecorder {
-  const recorder = new SvelteHotkeySequenceRecorderState({
-    ...getDefaultHotkeysOptions().hotkeySequenceRecorder,
-    ...resolveMaybeGetter(options),
-  } as HotkeySequenceRecorderOptions)
-
-  $effect(() => {
-    recorder.setOptions({
-      ...getDefaultHotkeysOptions().hotkeySequenceRecorder,
-      ...resolveMaybeGetter(options),
-    } as HotkeySequenceRecorderOptions)
-  })
-
-  onDestroy(() => {
-    recorder.destroy()
-  })
-
-  return recorder
-}

package/src/createHotkeySequences.svelte.ts

@@ -1,274 +0,0 @@
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { onDestroy } from 'svelte'
-import { SvelteMap, SvelteSet } from 'svelte/reactivity'
-import { getDefaultHotkeysOptions } from './HotkeysCtx'
-import { resolveMaybeGetter } from './internal.svelte'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte'
-import type { MaybeGetter } from './internal.svelte'
-import type { Attachment } from 'svelte/attachments'
-
-/**
- * A single sequence definition for use with `createHotkeySequences`.
- */
-export interface CreateHotkeySequenceDefinition {
-  /** Array of hotkey strings that form the sequence */
-  sequence: MaybeGetter<HotkeySequence>
-  /** The function to call when the sequence is completed */
-  callback: HotkeyCallback
-  /** Per-sequence options (merged on top of commonOptions) */
-  options?: MaybeGetter<CreateHotkeySequenceOptions>
-}
-
-type RegistrationRecord = {
-  handle: SequenceRegistrationHandle
-  target: Document | HTMLElement | Window
-}
-
-function cleanupRegistrations(
-  registrations:
-    | Map<string, RegistrationRecord>
-    | SvelteMap<string, RegistrationRecord>,
-) {
-  for (const { handle } of registrations.values()) {
-    if (handle.isActive) {
-      handle.unregister()
-    }
-  }
-  registrations.clear()
-}
-
-/**
- * Register multiple global keyboard shortcut sequences for the current component.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeySequences } from '@tanstack/svelte-hotkeys'
- *
- *   createHotkeySequences([
- *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
- *     { sequence: ['D', 'D'], callback: () => deleteLine() },
- *   ])
- * </script>
- * ```
- */
-export function createHotkeySequences(
-  definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>,
-  commonOptions: MaybeGetter<CreateHotkeySequenceOptions> = {},
-): void {
-  const registrations = new SvelteMap<string, RegistrationRecord>()
-
-  onDestroy(() => {
-    cleanupRegistrations(registrations)
-  })
-
-  $effect(() => {
-    if (typeof document === 'undefined') {
-      return
-    }
-
-    const resolvedDefinitions = resolveMaybeGetter(definitions)
-    const resolvedCommonOptions = resolveMaybeGetter(commonOptions)
-    const nextKeys = new SvelteSet<string>()
-    const prepared: Array<{
-      registrationKey: string
-      def: CreateHotkeySequenceDefinition
-      mergedOptions: CreateHotkeySequenceOptions
-      sequenceString: string
-      resolvedSequence: HotkeySequence
-      resolvedTarget: Document | HTMLElement | Window
-    }> = []
-
-    for (let i = 0; i < resolvedDefinitions.length; i++) {
-      const def = resolvedDefinitions[i]!
-      const resolvedSequence = resolveMaybeGetter(def.sequence)
-      if (resolvedSequence.length === 0) {
-        continue
-      }
-
-      const resolvedDefOptions = def.options
-        ? resolveMaybeGetter(def.options)
-        : {}
-
-      const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkeySequence,
-        ...resolvedCommonOptions,
-        ...resolvedDefOptions,
-      } as CreateHotkeySequenceOptions
-
-      const resolvedTarget =
-        mergedOptions.target ??
-        (typeof document !== 'undefined' ? document : null)
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const sequenceString = formatHotkeySequence(resolvedSequence)
-      const registrationKey = `${i}:${sequenceString}`
-      nextKeys.add(registrationKey)
-      prepared.push({
-        registrationKey,
-        def,
-        mergedOptions,
-        sequenceString,
-        resolvedSequence,
-        resolvedTarget,
-      })
-    }
-
-    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)
-      const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-
-      if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
-        existing.handle.callback = p.def.callback
-        existing.handle.setOptions(optionsWithoutTarget)
-        continue
-      }
-
-      if (existing?.handle.isActive) {
-        existing.handle.unregister()
-      }
-      if (existing) {
-        registrations.delete(p.registrationKey)
-      }
-
-      const handle = getSequenceManager().register(
-        p.resolvedSequence,
-        p.def.callback,
-        {
-          ...optionsWithoutTarget,
-          target: p.resolvedTarget,
-        },
-      )
-      registrations.set(p.registrationKey, {
-        handle,
-        target: p.resolvedTarget,
-      })
-    }
-  })
-}
-
-/**
- * Create an attachment for element-scoped multi-sequence registration.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeySequencesAttachment } from '@tanstack/svelte-hotkeys'
- *
- *   const vim = createHotkeySequencesAttachment([
- *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
- *     { sequence: ['D', 'D'], callback: () => deleteLine() },
- *   ])
- * </script>
- *
- * <div tabindex="0" {@attach vim}>Editor</div>
- * ```
- */
-export function createHotkeySequencesAttachment(
-  definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>,
-  commonOptions: MaybeGetter<CreateHotkeySequenceOptions> = {},
-): Attachment<HTMLElement> {
-  return (element) => {
-    const registrations = new SvelteMap<string, RegistrationRecord>()
-
-    $effect(() => {
-      const resolvedDefinitions = resolveMaybeGetter(definitions)
-      const resolvedCommonOptions = resolveMaybeGetter(commonOptions)
-      const nextKeys = new SvelteSet<string>()
-      const prepared: Array<{
-        registrationKey: string
-        def: CreateHotkeySequenceDefinition
-        mergedOptions: CreateHotkeySequenceOptions
-        sequenceString: string
-        resolvedSequence: HotkeySequence
-      }> = []
-
-      for (let i = 0; i < resolvedDefinitions.length; i++) {
-        const def = resolvedDefinitions[i]!
-        const resolvedSequence = resolveMaybeGetter(def.sequence)
-        if (resolvedSequence.length === 0) {
-          continue
-        }
-
-        const resolvedDefOptions = def.options
-          ? resolveMaybeGetter(def.options)
-          : {}
-
-        const mergedOptions = {
-          ...getDefaultHotkeysOptions().hotkeySequence,
-          ...resolvedCommonOptions,
-          ...resolvedDefOptions,
-        } as CreateHotkeySequenceOptions
-
-        const sequenceString = formatHotkeySequence(resolvedSequence)
-        const registrationKey = `${i}:${sequenceString}`
-        nextKeys.add(registrationKey)
-        prepared.push({
-          registrationKey,
-          def,
-          mergedOptions,
-          sequenceString,
-          resolvedSequence,
-        })
-      }
-
-      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)
-        const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-
-        if (existing?.handle.isActive && existing.target === element) {
-          existing.handle.callback = p.def.callback
-          existing.handle.setOptions(optionsWithoutTarget)
-          continue
-        }
-
-        if (existing?.handle.isActive) {
-          existing.handle.unregister()
-        }
-        if (existing) {
-          registrations.delete(p.registrationKey)
-        }
-
-        const handle = getSequenceManager().register(
-          p.resolvedSequence,
-          p.def.callback,
-          {
-            ...optionsWithoutTarget,
-            target: element,
-          },
-        )
-        registrations.set(p.registrationKey, { handle, target: element })
-      }
-    })
-
-    return () => {
-      cleanupRegistrations(registrations)
-    }
-  }
-}