@tanstack/svelte-hotkeys 0.0.1

package/src/createHotkeySequence.svelte.ts

@@ -0,0 +1,136 @@
+import { getSequenceManager } from '@tanstack/hotkeys'
+import { getDefaultHotkeysOptions } from './HotkeysCtx'
+import { resolveMaybeGetter } from './internal.svelte'
+import type {
+  HotkeyCallback,
+  HotkeySequence,
+  SequenceOptions,
+} 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: MaybeGetter<HotkeySequence>,
+  callback: HotkeyCallback,
+  options: MaybeGetter<CreateHotkeySequenceOptions>,
+) {
+  const resolvedSequence = resolveMaybeGetter(sequence)
+  const resolvedOptions = resolveMaybeGetter(options)
+  const mergedOptions = {
+    ...getDefaultHotkeysOptions().hotkeySequence,
+    ...resolvedOptions,
+  } as CreateHotkeySequenceOptions
+
+  return getSequenceManager().register(resolvedSequence, callback, {
+    ...mergedOptions,
+    target,
+  })
+}
+
+/**
+ * Register a global keyboard shortcut sequence for the current component.
+ *
+ * @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 })
+ * </script>
+ *
+ * <div>
+ *   ....
+ * </div>
+ * ```
+ */
+export function createHotkeySequence(
+  sequence: MaybeGetter<HotkeySequence>,
+  callback: HotkeyCallback,
+  options: MaybeGetter<CreateHotkeySequenceOptions> = {},
+): void {
+  $effect(() => {
+    if (typeof document === 'undefined') {
+      return
+    }
+
+    const resolvedSequence = resolveMaybeGetter(sequence)
+    if (resolvedSequence.length === 0) {
+      return
+    }
+
+    const registration = registerHotkeySequence(
+      document,
+      resolvedSequence,
+      callback,
+      options,
+    )
+
+    return () => {
+      registration.unregister()
+    }
+  })
+}
+
+/**
+ * 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) => {
+    const resolvedSequence = resolveMaybeGetter(sequence)
+
+    if (resolvedSequence.length === 0) {
+      return
+    }
+
+    const registration = registerHotkeySequence(
+      element,
+      resolvedSequence,
+      callback,
+      options,
+    )
+
+    return () => {
+      registration.unregister()
+    }
+  }
+}

package/src/getHeldKeyCodesMap.svelte.ts

@@ -0,0 +1,44 @@
+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

@@ -0,0 +1,40 @@
+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/getIsKeyHeld.svelte.ts

@@ -0,0 +1,68 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import { createStoreSubscriber } from './internal.svelte'
+import type { HeldKey } from '@tanstack/hotkeys'
+
+export interface SvelteHeldKeyState {
+  readonly held: boolean
+}
+
+class HeldKeyState implements SvelteHeldKeyState {
+  #tracker = getKeyStateTracker()
+  #normalizedKey: string
+  #subscribe = createStoreSubscriber(this.#tracker.store)
+
+  constructor(key: HeldKey) {
+    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: HeldKey): SvelteHeldKeyState {
+  return new HeldKeyState(key)
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Re-export everything from the core package
+export * from '@tanstack/hotkeys'
+
+export * from './createHotkey.svelte'
+export * from './createHotkeySequence.svelte'
+export * from './createHotkeyRecorder.svelte'
+export * from './getHeldKeys.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'

package/src/internal.svelte.ts

@@ -0,0 +1,26 @@
+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()
+  })
+}