@tanstack/svelte-hotkeys 0.10.0 → 0.12.0

package/src/createHotkey.svelte.ts

@@ -1,179 +0,0 @@
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { onDestroy } from 'svelte'
-import { getDefaultHotkeysOptions } from './HotkeysCtx'
-import { resolveMaybeGetter } from './internal.svelte'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyOptions,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-import type { MaybeGetter } from './internal.svelte'
-import type { Attachment } from 'svelte/attachments'
-
-export interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
-  target?: Document | Window // not html elements, use attachment instead
-}
-
-function registerHotkey(
-  target: HTMLElement | Document | Window,
-  hotkey: RegisterableHotkey,
-  callback: HotkeyCallback,
-  mergedOptions: CreateHotkeyOptions,
-) {
-  return getHotkeyManager().register(
-    normalizeRegisterableHotkey(
-      hotkey,
-      mergedOptions.platform ?? detectPlatform(),
-    ),
-    callback,
-    {
-      ...mergedOptions,
-      target,
-    },
-  )
-}
-
-/**
- * Register a global hotkey for the current component.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkey } from '@tanstack/svelte-hotkeys'
- *
- *   createHotkey('Mod+S', () => {
- *     console.log('Mod+S pressed')
- *   })
- * </script>
- * ```
- */
-export function createHotkey(
-  hotkey: MaybeGetter<RegisterableHotkey>,
-  callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeyOptions> = {},
-): void {
-  let registration: HotkeyRegistrationHandle | null = null
-  let lastHotkeyStr: Hotkey | null = null
-
-  $effect(() => {
-    if (typeof document === 'undefined') {
-      return
-    }
-
-    const resolvedHotkey = resolveMaybeGetter(hotkey)
-    const resolvedOptions = resolveMaybeGetter(options)
-    const mergedOptions = {
-      ...getDefaultHotkeysOptions().hotkey,
-      ...resolvedOptions,
-    } as CreateHotkeyOptions
-
-    const hotkeyStr = normalizeRegisterableHotkey(
-      resolvedHotkey,
-      mergedOptions.platform ?? detectPlatform(),
-    )
-    const { target: _t, ...optionsWithoutTarget } = mergedOptions
-
-    if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
-      registration.callback = callback
-      registration.setOptions(optionsWithoutTarget)
-      return
-    }
-
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-
-    registration = registerHotkey(
-      document,
-      resolvedHotkey,
-      callback,
-      mergedOptions,
-    )
-    lastHotkeyStr = hotkeyStr
-  })
-
-  onDestroy(() => {
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-  })
-}
-
-/**
- * Create an attachment for element-scoped hotkeys.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeyAttachment } from '@tanstack/svelte-hotkeys'
- *
- *   let count = $state(0)
- *   const saveHotkey = createHotkeyAttachment('Mod+S', () => {
- *     count++
- *   })
- *
- * </script>
- *
- * <div tabindex="0" {@attach saveHotkey}>
- *   Count: {count}
- * </div>
- * ```
- */
-export function createHotkeyAttachment(
-  hotkey: MaybeGetter<RegisterableHotkey>,
-  callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeyOptions> = {},
-): Attachment<HTMLElement> {
-  return (element) => {
-    let registration: HotkeyRegistrationHandle | null = null
-    let lastHotkeyStr: Hotkey | null = null
-
-    $effect(() => {
-      const resolvedHotkey = resolveMaybeGetter(hotkey)
-      const resolvedOptions = resolveMaybeGetter(options)
-      const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkey,
-        ...resolvedOptions,
-      } as CreateHotkeyOptions
-
-      const hotkeyStr = normalizeRegisterableHotkey(
-        resolvedHotkey,
-        mergedOptions.platform ?? detectPlatform(),
-      )
-      const { target: _t, ...optionsWithoutTarget } = mergedOptions
-
-      if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-        return
-      }
-
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-
-      registration = registerHotkey(
-        element,
-        resolvedHotkey,
-        callback,
-        mergedOptions,
-      )
-      lastHotkeyStr = hotkeyStr
-    })
-
-    return () => {
-      if (registration?.isActive) {
-        registration.unregister()
-      }
-    }
-  }
-}

package/src/createHotkeyRecorder.svelte.ts

@@ -1,118 +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)
-  }
-
-  startRecording(): void {
-    this.#recorder.start()
-  }
-
-  stopRecording(): void {
-    this.#recorder.stop()
-  }
-
-  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,93 +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)
-  }
-
-  startRecording(): void {
-    this.#recorder.start()
-  }
-
-  stopRecording(): void {
-    this.#recorder.stop()
-  }
-
-  cancelRecording(): void {
-    this.#recorder.cancel()
-  }
-
-  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
-}