@tanstack/svelte-hotkeys 0.10.0 → 0.12.0

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)
-    }
-  }
-}

package/src/createHotkeys.svelte.ts

@@ -1,276 +0,0 @@
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { onDestroy } from 'svelte'
-import { SvelteMap, SvelteSet } from 'svelte/reactivity'
-import { getDefaultHotkeysOptions } from './HotkeysCtx'
-import { resolveMaybeGetter } from './internal.svelte'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-import type { CreateHotkeyOptions } from './createHotkey.svelte'
-import type { MaybeGetter } from './internal.svelte'
-import type { Attachment } from 'svelte/attachments'
-
-/**
- * A single hotkey definition for use with `createHotkeys`.
- */
-export interface CreateHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: MaybeGetter<RegisterableHotkey>
-  /** The function to call when the hotkey is pressed */
-  callback: HotkeyCallback
-  /** Per-hotkey options (merged on top of commonOptions) */
-  options?: MaybeGetter<CreateHotkeyOptions>
-}
-
-type RegistrationRecord = {
-  handle: HotkeyRegistrationHandle
-  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 hotkeys for the current component.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeys } from '@tanstack/svelte-hotkeys'
- *
- *   createHotkeys([
- *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
- *     { hotkey: 'Escape', callback: () => close() },
- *   ])
- * </script>
- * ```
- */
-export function createHotkeys(
-  hotkeys: MaybeGetter<Array<CreateHotkeyDefinition>>,
-  commonOptions: MaybeGetter<CreateHotkeyOptions> = {},
-): void {
-  const registrations = new SvelteMap<string, RegistrationRecord>()
-
-  onDestroy(() => {
-    cleanupRegistrations(registrations)
-  })
-
-  $effect(() => {
-    if (typeof document === 'undefined') {
-      return
-    }
-
-    const resolvedHotkeys = resolveMaybeGetter(hotkeys)
-    const resolvedCommonOptions = resolveMaybeGetter(commonOptions)
-    const nextKeys = new SvelteSet<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 resolvedHotkey = resolveMaybeGetter(def.hotkey)
-      const resolvedDefOptions = def.options
-        ? resolveMaybeGetter(def.options)
-        : {}
-
-      const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkey,
-        ...resolvedCommonOptions,
-        ...resolvedDefOptions,
-      } as CreateHotkeyOptions
-
-      const resolvedTarget =
-        mergedOptions.target ??
-        (typeof document !== 'undefined' ? document : null)
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const hotkeyString = normalizeRegisterableHotkey(
-        resolvedHotkey,
-        mergedOptions.platform ?? detectPlatform(),
-      )
-      const registrationKey = `${i}:${hotkeyString}`
-      nextKeys.add(registrationKey)
-      prepared.push({
-        registrationKey,
-        def,
-        mergedOptions,
-        hotkeyString,
-        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 = getHotkeyManager().register(
-        p.hotkeyString,
-        p.def.callback,
-        {
-          ...optionsWithoutTarget,
-          target: p.resolvedTarget,
-        },
-      )
-      registrations.set(p.registrationKey, {
-        handle,
-        target: p.resolvedTarget,
-      })
-    }
-  })
-}
-
-/**
- * Create an attachment for element-scoped multi-hotkey registration.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeysAttachment } from '@tanstack/svelte-hotkeys'
- *
- *   const editorKeys = createHotkeysAttachment([
- *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
- *   ])
- * </script>
- *
- * <div tabindex="0" {@attach editorKeys}>
- *   Editor content
- * </div>
- * ```
- */
-export function createHotkeysAttachment(
-  hotkeys: MaybeGetter<Array<CreateHotkeyDefinition>>,
-  commonOptions: MaybeGetter<CreateHotkeyOptions> = {},
-): Attachment<HTMLElement> {
-  return (element) => {
-    const registrations = new SvelteMap<string, RegistrationRecord>()
-
-    $effect(() => {
-      const resolvedHotkeys = resolveMaybeGetter(hotkeys)
-      const resolvedCommonOptions = resolveMaybeGetter(commonOptions)
-      const nextKeys = new SvelteSet<string>()
-      const prepared: Array<{
-        registrationKey: string
-        def: CreateHotkeyDefinition
-        mergedOptions: CreateHotkeyOptions
-        hotkeyString: Hotkey
-      }> = []
-
-      for (let i = 0; i < resolvedHotkeys.length; i++) {
-        const def = resolvedHotkeys[i]!
-        const resolvedHotkey = resolveMaybeGetter(def.hotkey)
-        const resolvedDefOptions = def.options
-          ? resolveMaybeGetter(def.options)
-          : {}
-
-        const mergedOptions = {
-          ...getDefaultHotkeysOptions().hotkey,
-          ...resolvedCommonOptions,
-          ...resolvedDefOptions,
-        } as CreateHotkeyOptions
-
-        const hotkeyString = normalizeRegisterableHotkey(
-          resolvedHotkey,
-          mergedOptions.platform ?? detectPlatform(),
-        )
-        const registrationKey = `${i}:${hotkeyString}`
-        nextKeys.add(registrationKey)
-        prepared.push({
-          registrationKey,
-          def,
-          mergedOptions,
-          hotkeyString,
-        })
-      }
-
-      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.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 = getHotkeyManager().register(
-          p.hotkeyString,
-          p.def.callback,
-          {
-            ...optionsWithoutTarget,
-            target: element,
-          },
-        )
-        registrations.set(p.registrationKey, { handle, target: element })
-      }
-    })
-
-    return () => {
-      cleanupRegistrations(registrations)
-    }
-  }
-}

package/src/getHeldKeyCodesMap.svelte.ts

@@ -1,44 +0,0 @@
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import { createStoreSubscriber } from './internal.svelte'
-
-export interface SvelteHeldKeyCodesMap {
-  readonly codes: Record<string, string>
-}
-
-class HeldKeyCodesMapState implements SvelteHeldKeyCodesMap {
-  #tracker = getKeyStateTracker()
-  #subscribe = createStoreSubscriber(this.#tracker.store)
-
-  get codes(): Record<string, string> {
-    this.#subscribe()
-    return this.#tracker.store.state.heldCodes
-  }
-}
-
-/**
- * Svelte function that returns reactive access to the map of currently held key names
- * to their physical `event.code` values.
- *
- * This is useful for debugging which physical key was pressed (e.g. distinguishing
- * left vs right Shift via "ShiftLeft" / "ShiftRight").
- *
- * @returns Object with a reactive `codes` property
- *
- * ```svelte
- * <script>
- *   import { getHeldKeyCodesMap } from '@tanstack/svelte-hotkeys'
- *   const heldKeyCodesMap = getHeldKeyCodesMap()
- * </script>
- *
- * <div>
- *   {#each Object.entries(heldKeyCodesMap.codes) as [key, code]}
- *     <kbd>
- *       {key} <small>{code}</small>
- *     </kbd>
- *   {/each}
- *  </div>
- * ```
- */
-export function getHeldKeyCodesMap(): SvelteHeldKeyCodesMap {
-  return new HeldKeyCodesMapState()
-}

package/src/getHeldKeys.svelte.ts

@@ -1,40 +0,0 @@
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import { createStoreSubscriber } from './internal.svelte'
-
-export interface SvelteHeldKeys {
-  readonly keys: Array<string>
-}
-
-class HeldKeysState implements SvelteHeldKeys {
-  #tracker = getKeyStateTracker()
-  #subscribe = createStoreSubscriber(this.#tracker.store)
-
-  get keys(): Array<string> {
-    this.#subscribe()
-    return this.#tracker.store.state.heldKeys
-  }
-}
-
-/**
- * Svelte function that returns reactive access to currently held keyboard keys.
- *
- * This function uses the global KeyStateTracker and updates whenever keys are pressed
- * or released.
- *
- * @returns Object with a reactive `keys` property
- *
- * @example
- * ```svelte
- * <script>
- *   import { getHeldKeys } from '@tanstack/svelte-hotkeys'
- *
- *   const heldKeys = getHeldKeys()
- * </script>
- * <div>
- *   Currently pressed: {heldKeys.keys.join(' + ') || 'None'}
- * </div>
- * ```
- */
-export function getHeldKeys(): SvelteHeldKeys {
-  return new HeldKeysState()
-}

package/src/getHotkeyRegistrations.svelte.ts

@@ -1,60 +0,0 @@
-import {
-  getHotkeyManager,
-  getSequenceManager,
-  toHotkeyRegistrationView,
-} from '@tanstack/hotkeys'
-import { createStoreSubscriber } from './internal.svelte'
-import type {
-  HotkeyRegistrationView,
-  SequenceRegistrationView,
-} from '@tanstack/hotkeys'
-
-export interface SvelteHotkeyRegistrations {
-  readonly hotkeys: Array<HotkeyRegistrationView>
-  readonly sequences: Array<SequenceRegistrationView>
-}
-
-class HotkeyRegistrationsState implements SvelteHotkeyRegistrations {
-  #hotkeyManager = getHotkeyManager()
-  #sequenceManager = getSequenceManager()
-  #subscribeHotkeys = createStoreSubscriber(this.#hotkeyManager.registrations)
-  #subscribeSequences = createStoreSubscriber(
-    this.#sequenceManager.registrations,
-  )
-
-  get hotkeys(): Array<HotkeyRegistrationView> {
-    this.#subscribeHotkeys()
-    return Array.from(this.#hotkeyManager.registrations.state.values()).map(
-      toHotkeyRegistrationView,
-    )
-  }
-
-  get sequences(): Array<SequenceRegistrationView> {
-    this.#subscribeSequences()
-    return Array.from(this.#sequenceManager.registrations.state.values())
-  }
-}
-
-/**
- * Svelte function that returns reactive access to all hotkey and sequence
- * registrations from the singleton managers.
- *
- * This is a standalone function that does NOT require the HotkeysProvider.
- *
- * @returns Object with reactive `hotkeys` and `sequences` properties
- *
- * @example
- * ```svelte
- * <script>
- *   import { getHotkeyRegistrations } from '@tanstack/svelte-hotkeys'
- *
- *   const registrations = getHotkeyRegistrations()
- * </script>
- * {#each registrations.hotkeys as reg}
- *   <div>{reg.options.meta?.name} — {reg.triggerCount} triggers</div>
- * {/each}
- * ```
- */
-export function getHotkeyRegistrations(): SvelteHotkeyRegistrations {
-  return new HotkeyRegistrationsState()
-}