@tanstack/svelte-hotkeys 0.11.0 → 0.12.0

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/getHotkeyHint.svelte.ts

@@ -1,51 +0,0 @@
-import { createSubscriber } from 'svelte/reactivity'
-import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'
-import { resolveMaybeGetter } from './internal.svelte'
-import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'
-import type { MaybeGetter } from './internal.svelte'
-
-export interface SvelteHotkeyHint {
-  readonly visible: boolean
-}
-
-/**
- * Returns an object with a reactive `visible` getter indicating whether held modifiers reveal this shortcut.
- * Pass getters to track changing bindings and options.
- * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
- * every modifier. Combine with the action's enabled state before showing a badge.
- * This helper does not register a shortcut or check whether its target is focused.
- */
-export function getHotkeyHint(
-  hotkey: MaybeGetter<RegisterableHotkey>,
-  options: MaybeGetter<HeldModifierOptions> = {},
-): SvelteHotkeyHint {
-  const tracker = getKeyStateTracker()
-  // Resolve current reactive arguments without caching a stale binding.
-  const read = () =>
-    matchesHeldModifiers(
-      resolveMaybeGetter(hotkey),
-      tracker.store.state.heldKeys,
-      resolveMaybeGetter(options),
-    )
-  let previous = false
-  // Notify Svelte only when visibility changes, not for every unrelated held key.
-  const subscribe = createSubscriber((update) => {
-    previous = read()
-    const subscription = tracker.store.subscribe(() => {
-      const next = read()
-      if (next !== previous) {
-        previous = next
-        update()
-      }
-    })
-    return () => subscription.unsubscribe()
-  })
-  return {
-    /** Reads visibility and subscribes the current reactive consumer when needed. */
-    get visible() {
-      subscribe()
-      previous = read()
-      return previous
-    },
-  }
-}

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

package/src/getIsKeyHeld.svelte.ts

@@ -1,68 +0,0 @@
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import { createStoreSubscriber } from './internal.svelte'
-import type { IndividualKey } from '@tanstack/hotkeys'
-
-export interface SvelteHeldKeyState {
-  readonly held: boolean
-}
-
-class HeldKeyState implements SvelteHeldKeyState {
-  #tracker = getKeyStateTracker()
-  #normalizedKey: string
-  #subscribe = createStoreSubscriber(this.#tracker.store)
-
-  constructor(key: IndividualKey) {
-    this.#normalizedKey = key.toLowerCase()
-  }
-
-  get held(): boolean {
-    this.#subscribe()
-    return this.#tracker.store.state.heldKeys.some(
-      (heldKey) => heldKey.toLowerCase() === this.#normalizedKey,
-    )
-  }
-}
-
-/**
- * Svelte function that returns reactive access to whether a specific key is currently being held.
- *
- * This function uses the global KeyStateTracker and updates whenever keys are pressed
- * or released.
- *
- * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
- * @returns Object with a reactive `held` property
- *
- * @example
- * ```svelte
- * <script>
- *   import { getIsKeyHeld } from '@tanstack/svelte-hotkeys'
- *
- *   const isShiftHeld = getIsKeyHeld('Shift')
- * </script>
- *
- * <div>
- *   {isShiftHeld.held ? 'Shift is pressed!' : 'Press Shift'}
- * </div>
- * ```
- *
- * @example
- * ```svelte
- * <script>
- *   import { getIsKeyHeld } from '@tanstack/svelte-hotkeys'
- *
- *   const isCtrlHeld = getIsKeyHeld('Control')
- *   const isShiftHeld = getIsKeyHeld('Shift')
- *   const isAltHeld = getIsKeyHeld('Alt')
- * </script>
- *
- * <div>
- *   <span style:opacity={isCtrlHeld.held ? 1 : 0.3}>Ctrl</span>
- *   <span style:opacity={isShiftHeld.held ? 1 : 0.3}>Shift</span>
- *   <span style:opacity={isAltHeld.held ? 1 : 0.3}>Alt</span>
- * </div>
- * ```
- */
-
-export function getIsKeyHeld(key: IndividualKey): SvelteHeldKeyState {
-  return new HeldKeyState(key)
-}

package/src/index.ts

@@ -1,22 +0,0 @@
-// Re-export everything from the core package
-export * from '@tanstack/hotkeys'
-
-export * from './createHotkey.svelte'
-export * from './createHotkeys.svelte'
-export * from './createHotkeySequence.svelte'
-export * from './createHotkeySequences.svelte'
-export * from './createHotkeyRecorder.svelte'
-export * from './createHotkeySequenceRecorder.svelte'
-export * from './getHeldKeys.svelte'
-export * from './getHotkeyRegistrations.svelte'
-export * from './getHeldKeyCodesMap.svelte'
-export * from './getIsKeyHeld.svelte'
-export { default as HotkeysProvider } from './HotkeysProvider.svelte'
-export {
-  DEFAULT_OPTIONS,
-  getDefaultHotkeysOptions,
-  getHotkeysContext,
-  setHotkeysContext,
-} from './HotkeysCtx'
-export type { HotkeysProviderOptions, HotkeysProviderProps } from './HotkeysCtx'
-export * from './getHotkeyHint.svelte'

package/src/internal.svelte.ts

@@ -1,26 +0,0 @@
-import { createSubscriber } from 'svelte/reactivity'
-
-export type MaybeGetter<T> = T | (() => T)
-
-interface SubscribableStore<TState> {
-  state: TState
-  subscribe: (
-    listener: () => void,
-  ) => (() => void) | { unsubscribe: () => void }
-}
-
-export function resolveMaybeGetter<T>(value: MaybeGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : value
-}
-
-export function createStoreSubscriber<TState>(
-  store: SubscribableStore<TState>,
-): () => void {
-  return createSubscriber((update) => {
-    const subscription = store.subscribe(update)
-
-    return typeof subscription === 'function'
-      ? subscription
-      : () => subscription.unsubscribe()
-  })
-}