@tanstack/svelte-hotkeys 0.0.1

package/dist/getHeldKeys.svelte.js

@@ -0,0 +1,42 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _HeldKeysState_tracker, _HeldKeysState_subscribe;
+import { getKeyStateTracker } from '@tanstack/hotkeys';
+import { createStoreSubscriber } from './internal.svelte';
+class HeldKeysState {
+    constructor() {
+        _HeldKeysState_tracker.set(this, getKeyStateTracker());
+        _HeldKeysState_subscribe.set(this, createStoreSubscriber(__classPrivateFieldGet(this, _HeldKeysState_tracker, "f").store));
+    }
+    get keys() {
+        __classPrivateFieldGet(this, _HeldKeysState_subscribe, "f").call(this);
+        return __classPrivateFieldGet(this, _HeldKeysState_tracker, "f").store.state.heldKeys;
+    }
+}
+_HeldKeysState_tracker = new WeakMap(), _HeldKeysState_subscribe = new WeakMap();
+/**
+ * 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() {
+    return new HeldKeysState();
+}

package/dist/getIsKeyHeld.svelte.d.ts

@@ -0,0 +1,44 @@
+import type { HeldKey } from '@tanstack/hotkeys';
+export interface SvelteHeldKeyState {
+    readonly held: boolean;
+}
+/**
+ * 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 declare function getIsKeyHeld(key: HeldKey): SvelteHeldKeyState;

package/dist/getIsKeyHeld.svelte.js

@@ -0,0 +1,69 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _HeldKeyState_tracker, _HeldKeyState_normalizedKey, _HeldKeyState_subscribe;
+import { getKeyStateTracker } from '@tanstack/hotkeys';
+import { createStoreSubscriber } from './internal.svelte';
+class HeldKeyState {
+    constructor(key) {
+        _HeldKeyState_tracker.set(this, getKeyStateTracker());
+        _HeldKeyState_normalizedKey.set(this, void 0);
+        _HeldKeyState_subscribe.set(this, createStoreSubscriber(__classPrivateFieldGet(this, _HeldKeyState_tracker, "f").store));
+        __classPrivateFieldSet(this, _HeldKeyState_normalizedKey, key.toLowerCase(), "f");
+    }
+    get held() {
+        __classPrivateFieldGet(this, _HeldKeyState_subscribe, "f").call(this);
+        return __classPrivateFieldGet(this, _HeldKeyState_tracker, "f").store.state.heldKeys.some((heldKey) => heldKey.toLowerCase() === __classPrivateFieldGet(this, _HeldKeyState_normalizedKey, "f"));
+    }
+}
+_HeldKeyState_tracker = new WeakMap(), _HeldKeyState_normalizedKey = new WeakMap(), _HeldKeyState_subscribe = new WeakMap();
+/**
+ * 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) {
+    return new HeldKeyState(key);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+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/dist/index.js

@@ -0,0 +1,10 @@
+// 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';

package/dist/internal.svelte.d.ts

@@ -0,0 +1,10 @@
+export type MaybeGetter<T> = T | (() => T);
+interface SubscribableStore<TState> {
+    state: TState;
+    subscribe: (listener: () => void) => (() => void) | {
+        unsubscribe: () => void;
+    };
+}
+export declare function resolveMaybeGetter<T>(value: MaybeGetter<T>): T;
+export declare function createStoreSubscriber<TState>(store: SubscribableStore<TState>): () => void;
+export {};

package/dist/internal.svelte.js

@@ -0,0 +1,12 @@
+import { createSubscriber } from 'svelte/reactivity';
+export function resolveMaybeGetter(value) {
+    return typeof value === 'function' ? value() : value;
+}
+export function createStoreSubscriber(store) {
+    return createSubscriber((update) => {
+        const subscription = store.subscribe(update);
+        return typeof subscription === 'function'
+            ? subscription
+            : () => subscription.unsubscribe();
+    });
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tanstack/svelte-hotkeys",
+  "version": "0.0.1",
+  "description": "Svelte adapter for TanStack Hotkeys",
+  "author": "Kunal Rao",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/svelte-hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/kunalrao"
+  },
+  "keywords": [
+    "svelte",
+    "tanstack",
+    "keys",
+    "hotkeys",
+    "keyboard",
+    "shortcuts"
+  ],
+  "scripts": {
+    "clean": "premove ./dist ./coverage",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:build": "publint --strict",
+    "build": "svelte-package --input ./src --output ./dist"
+  },
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "svelte": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/hotkeys": "workspace:*"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint-plugin-svelte": "^3.15.0",
+    "svelte": "^5.53.7"
+  },
+  "peerDependencies": {
+    "svelte": "^5.25.0"
+  }
+}

package/src/HotkeysCtx.ts

@@ -0,0 +1,57 @@
+import { createContext } from 'svelte'
+import type { HotkeyRecorderOptions } from '@tanstack/hotkeys'
+import type { CreateHotkeyOptions } from './createHotkey.svelte'
+import type { Snippet } from 'svelte'
+import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte'
+
+export interface HotkeysProviderOptions {
+  hotkey?: Partial<CreateHotkeyOptions>
+  hotkeyRecorder?: Partial<HotkeyRecorderOptions>
+  hotkeySequence?: Partial<CreateHotkeySequenceOptions>
+}
+
+export interface HotkeysProviderProps {
+  children: Snippet
+  defaultOptions?: HotkeysProviderOptions
+}
+
+export const DEFAULT_OPTIONS: HotkeysProviderOptions = {}
+
+interface HotkeysContextValue {
+  defaultOptions: HotkeysProviderOptions
+}
+
+const [useHotkeysContext, setHotkeysContextValue] =
+  createContext<HotkeysContextValue | null>()
+
+export function setHotkeysContext(
+  defaultOptions: HotkeysProviderOptions = DEFAULT_OPTIONS,
+): HotkeysContextValue {
+  return setHotkeysContextValue({
+    get defaultOptions() {
+      return defaultOptions
+    },
+  })!
+}
+
+export function setHotkeysContextSource(
+  defaultOptions: () => HotkeysProviderOptions,
+): HotkeysContextValue {
+  return setHotkeysContextValue({
+    get defaultOptions() {
+      return defaultOptions()
+    },
+  })!
+}
+
+export function getHotkeysContext(): HotkeysContextValue | null {
+  try {
+    return useHotkeysContext()
+  } catch {
+    return null
+  }
+}
+
+export function getDefaultHotkeysOptions(): HotkeysProviderOptions {
+  return getHotkeysContext()?.defaultOptions ?? DEFAULT_OPTIONS
+}

package/src/HotkeysProvider.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import { DEFAULT_OPTIONS, setHotkeysContextSource } from './HotkeysCtx'
+
+  import type { HotkeysProviderProps } from './HotkeysCtx'
+
+  let { children, defaultOptions = DEFAULT_OPTIONS }: HotkeysProviderProps =
+    $props()
+
+  setHotkeysContextSource(() => defaultOptions)
+</script>
+
+{@render children()}

package/src/createHotkey.svelte.ts

@@ -0,0 +1,120 @@
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { getDefaultHotkeysOptions } from './HotkeysCtx'
+import { resolveMaybeGetter } from './internal.svelte'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyOptions,
+  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 normalizeHotkey(
+  hotkey: RegisterableHotkey,
+  options: CreateHotkeyOptions,
+): Hotkey {
+  const platform = options.platform ?? detectPlatform()
+
+  return typeof hotkey === 'string'
+    ? hotkey
+    : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)
+}
+
+function registerHotkey(
+  target: HTMLElement | Document | Window,
+  hotkey: MaybeGetter<RegisterableHotkey>,
+  callback: HotkeyCallback,
+  options: MaybeGetter<CreateHotkeyOptions>,
+) {
+  const resolvedHotkey = resolveMaybeGetter(hotkey)
+  const resolvedOptions = resolveMaybeGetter(options)
+  const mergedOptions = {
+    ...getDefaultHotkeysOptions().hotkey,
+    ...resolvedOptions,
+  } as CreateHotkeyOptions
+
+  return getHotkeyManager().register(
+    normalizeHotkey(resolvedHotkey, mergedOptions),
+    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 {
+  $effect(() => {
+    if (typeof document === 'undefined') {
+      return
+    }
+
+    const registration = registerHotkey(document, hotkey, callback, options)
+
+    return () => {
+      registration.unregister()
+    }
+  })
+}
+
+/**
+ * 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) => {
+    const registration = registerHotkey(element, hotkey, callback, options)
+
+    return () => {
+      registration.unregister()
+    }
+  }
+}

package/src/createHotkeyRecorder.svelte.ts

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