@tanstack/svelte-hotkeys 0.5.1 → 0.7.0

package/dist/HotkeysCtx.d.ts

@@ -1,10 +1,11 @@
-import type { HotkeyRecorderOptions } from '@tanstack/hotkeys';
+import type { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } 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>;
+    hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
     hotkeySequence?: Partial<CreateHotkeySequenceOptions>;
 }
 export interface HotkeysProviderProps {

package/dist/createHotkey.svelte.js

@@ -1,4 +1,5 @@
 import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey, } from '@tanstack/hotkeys';
+import { onDestroy } from 'svelte';
 import { getDefaultHotkeysOptions } from './HotkeysCtx';
 import { resolveMaybeGetter } from './internal.svelte';
 function normalizeHotkey(hotkey, options) {
@@ -7,14 +8,8 @@ function normalizeHotkey(hotkey, options) {
         ? hotkey
         : formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform));
 }
-function registerHotkey(target, hotkey, callback, options) {
-    const resolvedHotkey = resolveMaybeGetter(hotkey);
-    const resolvedOptions = resolveMaybeGetter(options);
-    const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkey,
-        ...resolvedOptions,
-    };
-    return getHotkeyManager().register(normalizeHotkey(resolvedHotkey, mergedOptions), callback, {
+function registerHotkey(target, hotkey, callback, mergedOptions) {
+    return getHotkeyManager().register(normalizeHotkey(hotkey, mergedOptions), callback, {
         ...mergedOptions,
         target,
     });
@@ -34,14 +29,37 @@ function registerHotkey(target, hotkey, callback, options) {
  * ```
  */
 export function createHotkey(hotkey, callback, options = {}) {
+    let registration = null;
+    let lastHotkeyStr = null;
     $effect(() => {
         if (typeof document === 'undefined') {
             return;
         }
-        const registration = registerHotkey(document, hotkey, callback, options);
-        return () => {
-            registration.unregister();
+        const resolvedHotkey = resolveMaybeGetter(hotkey);
+        const resolvedOptions = resolveMaybeGetter(options);
+        const mergedOptions = {
+            ...getDefaultHotkeysOptions().hotkey,
+            ...resolvedOptions,
         };
+        const hotkeyStr = normalizeHotkey(resolvedHotkey, mergedOptions);
+        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;
+        }
     });
 }
 /**
@@ -67,11 +85,27 @@ export function createHotkey(hotkey, callback, options = {}) {
 export function createHotkeyAttachment(hotkey, callback, options = {}) {
     return (element) => {
         let registration = null;
+        let lastHotkeyStr = null;
         $effect(() => {
+            const resolvedHotkey = resolveMaybeGetter(hotkey);
+            const resolvedOptions = resolveMaybeGetter(options);
+            const mergedOptions = {
+                ...getDefaultHotkeysOptions().hotkey,
+                ...resolvedOptions,
+            };
+            const hotkeyStr = normalizeHotkey(resolvedHotkey, mergedOptions);
+            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, hotkey, callback, options);
+            registration = registerHotkey(element, resolvedHotkey, callback, mergedOptions);
+            lastHotkeyStr = hotkeyStr;
         });
         return () => {
             if (registration?.isActive) {

package/dist/createHotkeySequence.svelte.js

@@ -1,14 +1,9 @@
-import { getSequenceManager } from '@tanstack/hotkeys';
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
+import { onDestroy } from 'svelte';
 import { getDefaultHotkeysOptions } from './HotkeysCtx';
 import { resolveMaybeGetter } from './internal.svelte';
-function registerHotkeySequence(target, sequence, callback, options) {
-    const resolvedSequence = resolveMaybeGetter(sequence);
-    const resolvedOptions = resolveMaybeGetter(options);
-    const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkeySequence,
-        ...resolvedOptions,
-    };
-    return getSequenceManager().register(resolvedSequence, callback, {
+function registerHotkeySequence(target, sequence, callback, mergedOptions) {
+    return getSequenceManager().register(sequence, callback, {
         ...mergedOptions,
         target,
     });
@@ -53,18 +48,45 @@ function registerHotkeySequence(target, sequence, callback, options) {
  * ```
  */
 export function createHotkeySequence(sequence, callback, options = {}) {
+    let registration = null;
+    let lastSequenceKey = null;
     $effect(() => {
         if (typeof document === 'undefined') {
             return;
         }
         const resolvedSequence = resolveMaybeGetter(sequence);
+        const resolvedOptions = resolveMaybeGetter(options);
+        const mergedOptions = {
+            ...getDefaultHotkeysOptions().hotkeySequence,
+            ...resolvedOptions,
+        };
+        const { target: _t, ...optionsWithoutTarget } = mergedOptions;
         if (resolvedSequence.length === 0) {
+            if (registration?.isActive) {
+                registration.unregister();
+                registration = null;
+            }
+            lastSequenceKey = null;
             return;
         }
-        const registration = registerHotkeySequence(document, resolvedSequence, callback, options);
-        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;
+        }
     });
 }
 /**
@@ -88,16 +110,35 @@ export function createHotkeySequence(sequence, callback, options = {}) {
 export function createHotkeySequenceAttachment(sequence, callback, options = {}) {
     return (element) => {
         let registration = null;
+        let lastSequenceKey = null;
         $effect(() => {
             const resolvedSequence = resolveMaybeGetter(sequence);
+            const resolvedOptions = resolveMaybeGetter(options);
+            const mergedOptions = {
+                ...getDefaultHotkeysOptions().hotkeySequence,
+                ...resolvedOptions,
+            };
+            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;
             }
-            if (resolvedSequence.length === 0) {
-                return;
-            }
-            registration = registerHotkeySequence(element, resolvedSequence, callback, options);
+            registration = registerHotkeySequence(element, resolvedSequence, callback, mergedOptions);
+            lastSequenceKey = sequenceKey;
         });
         return () => {
             if (registration?.isActive) {

package/dist/createHotkeySequenceRecorder.svelte.d.ts

@@ -0,0 +1,15 @@
+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;
+}
+/**
+ * Svelte helper for recording multi-chord sequences (Vim-style shortcuts).
+ */
+export declare function createHotkeySequenceRecorder(options: MaybeGetter<HotkeySequenceRecorderOptions>): SvelteHotkeySequenceRecorder;

package/dist/createHotkeySequenceRecorder.svelte.js

@@ -0,0 +1,74 @@
+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 _SvelteHotkeySequenceRecorderState_recorder, _SvelteHotkeySequenceRecorderState_subscribe;
+import { HotkeySequenceRecorder } from '@tanstack/hotkeys';
+import { onDestroy } from 'svelte';
+import { getDefaultHotkeysOptions } from './HotkeysCtx';
+import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte';
+class SvelteHotkeySequenceRecorderState {
+    constructor(options) {
+        _SvelteHotkeySequenceRecorderState_recorder.set(this, void 0);
+        _SvelteHotkeySequenceRecorderState_subscribe.set(this, void 0);
+        __classPrivateFieldSet(this, _SvelteHotkeySequenceRecorderState_recorder, new HotkeySequenceRecorder(options), "f");
+        __classPrivateFieldSet(this, _SvelteHotkeySequenceRecorderState_subscribe, createStoreSubscriber(__classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").store), "f");
+    }
+    get isRecording() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_subscribe, "f").call(this);
+        return __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").store.state.isRecording;
+    }
+    get steps() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_subscribe, "f").call(this);
+        return __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").store.state.steps;
+    }
+    get recordedSequence() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_subscribe, "f").call(this);
+        return __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").store.state.recordedSequence;
+    }
+    setOptions(options) {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").setOptions(options);
+    }
+    startRecording() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").start();
+    }
+    stopRecording() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").stop();
+    }
+    cancelRecording() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").cancel();
+    }
+    commitRecording() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").commit();
+    }
+    destroy() {
+        __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").destroy();
+    }
+}
+_SvelteHotkeySequenceRecorderState_recorder = new WeakMap(), _SvelteHotkeySequenceRecorderState_subscribe = new WeakMap();
+/**
+ * Svelte helper for recording multi-chord sequences (Vim-style shortcuts).
+ */
+export function createHotkeySequenceRecorder(options) {
+    const recorder = new SvelteHotkeySequenceRecorderState({
+        ...getDefaultHotkeysOptions().hotkeySequenceRecorder,
+        ...resolveMaybeGetter(options),
+    });
+    $effect(() => {
+        recorder.setOptions({
+            ...getDefaultHotkeysOptions().hotkeySequenceRecorder,
+            ...resolveMaybeGetter(options),
+        });
+    });
+    onDestroy(() => {
+        recorder.destroy();
+    });
+    return recorder;
+}

package/dist/createHotkeySequences.svelte.d.ts

@@ -0,0 +1,49 @@
+import type { HotkeyCallback, HotkeySequence } 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>;
+}
+/**
+ * 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 declare function createHotkeySequences(definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>, commonOptions?: MaybeGetter<CreateHotkeySequenceOptions>): void;
+/**
+ * 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 declare function createHotkeySequencesAttachment(definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>, commonOptions?: MaybeGetter<CreateHotkeySequenceOptions>): Attachment<HTMLElement>;

package/dist/createHotkeySequences.svelte.js

@@ -0,0 +1,189 @@
+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';
+function cleanupRegistrations(registrations) {
+    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, commonOptions = {}) {
+    const registrations = new SvelteMap();
+    onDestroy(() => {
+        cleanupRegistrations(registrations);
+    });
+    $effect(() => {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        const resolvedDefinitions = resolveMaybeGetter(definitions);
+        const resolvedCommonOptions = resolveMaybeGetter(commonOptions);
+        const nextKeys = new SvelteSet();
+        const prepared = [];
+        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,
+            };
+            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, commonOptions = {}) {
+    return (element) => {
+        const registrations = new SvelteMap();
+        $effect(() => {
+            const resolvedDefinitions = resolveMaybeGetter(definitions);
+            const resolvedCommonOptions = resolveMaybeGetter(commonOptions);
+            const nextKeys = new SvelteSet();
+            const prepared = [];
+            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,
+                };
+                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/dist/index.d.ts

@@ -2,7 +2,9 @@ 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 './getHeldKeyCodesMap.svelte';
 export * from './getIsKeyHeld.svelte';

package/dist/index.js

@@ -3,7 +3,9 @@ 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 './getHeldKeyCodesMap.svelte';
 export * from './getIsKeyHeld.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.4.3"
+    "@tanstack/hotkeys": "0.5.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",

package/src/HotkeysCtx.ts

@@ -1,5 +1,8 @@
 import { createContext } from 'svelte'
-import type { HotkeyRecorderOptions } from '@tanstack/hotkeys'
+import type {
+  HotkeyRecorderOptions,
+  HotkeySequenceRecorderOptions,
+} from '@tanstack/hotkeys'
 import type { CreateHotkeyOptions } from './createHotkey.svelte'
 import type { Snippet } from 'svelte'
 import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte'
@@ -7,6 +10,7 @@ import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte'
 export interface HotkeysProviderOptions {
   hotkey?: Partial<CreateHotkeyOptions>
   hotkeyRecorder?: Partial<HotkeyRecorderOptions>
+  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>
   hotkeySequence?: Partial<CreateHotkeySequenceOptions>
 }
 

package/src/createHotkey.svelte.ts

@@ -4,12 +4,14 @@ import {
   getHotkeyManager,
   rawHotkeyToParsedHotkey,
 } 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'
@@ -32,19 +34,12 @@ function normalizeHotkey(
 
 function registerHotkey(
   target: HTMLElement | Document | Window,
-  hotkey: MaybeGetter<RegisterableHotkey>,
+  hotkey: RegisterableHotkey,
   callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeyOptions>,
+  mergedOptions: CreateHotkeyOptions,
 ) {
-  const resolvedHotkey = resolveMaybeGetter(hotkey)
-  const resolvedOptions = resolveMaybeGetter(options)
-  const mergedOptions = {
-    ...getDefaultHotkeysOptions().hotkey,
-    ...resolvedOptions,
-  } as CreateHotkeyOptions
-
   return getHotkeyManager().register(
-    normalizeHotkey(resolvedHotkey, mergedOptions),
+    normalizeHotkey(hotkey, mergedOptions),
     callback,
     {
       ...mergedOptions,
@@ -72,15 +67,48 @@ export function createHotkey(
   callback: HotkeyCallback,
   options: MaybeGetter<CreateHotkeyOptions> = {},
 ): void {
+  let registration: HotkeyRegistrationHandle | null = null
+  let lastHotkeyStr: Hotkey | null = null
+
   $effect(() => {
     if (typeof document === 'undefined') {
       return
     }
 
-    const registration = registerHotkey(document, hotkey, callback, options)
+    const resolvedHotkey = resolveMaybeGetter(hotkey)
+    const resolvedOptions = resolveMaybeGetter(options)
+    const mergedOptions = {
+      ...getDefaultHotkeysOptions().hotkey,
+      ...resolvedOptions,
+    } as CreateHotkeyOptions
 
-    return () => {
+    const hotkeyStr = normalizeHotkey(resolvedHotkey, mergedOptions)
+    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
     }
   })
 }
@@ -111,14 +139,38 @@ export function createHotkeyAttachment(
   options: MaybeGetter<CreateHotkeyOptions> = {},
 ): Attachment<HTMLElement> {
   return (element) => {
-    let registration: ReturnType<typeof registerHotkey> | null = null
+    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 = normalizeHotkey(resolvedHotkey, mergedOptions)
+      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, hotkey, callback, options)
+      registration = registerHotkey(
+        element,
+        resolvedHotkey,
+        callback,
+        mergedOptions,
+      )
+      lastHotkeyStr = hotkeyStr
     })
 
     return () => {

package/src/createHotkeySequence.svelte.ts

@@ -1,10 +1,12 @@
-import { getSequenceManager } from '@tanstack/hotkeys'
+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'
@@ -18,18 +20,11 @@ export interface CreateHotkeySequenceOptions extends Omit<
 
 function registerHotkeySequence(
   target: HTMLElement | Document | Window,
-  sequence: MaybeGetter<HotkeySequence>,
+  sequence: HotkeySequence,
   callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeySequenceOptions>,
+  mergedOptions: CreateHotkeySequenceOptions,
 ) {
-  const resolvedSequence = resolveMaybeGetter(sequence)
-  const resolvedOptions = resolveMaybeGetter(options)
-  const mergedOptions = {
-    ...getDefaultHotkeysOptions().hotkeySequence,
-    ...resolvedOptions,
-  } as CreateHotkeySequenceOptions
-
-  return getSequenceManager().register(resolvedSequence, callback, {
+  return getSequenceManager().register(sequence, callback, {
     ...mergedOptions,
     target,
   })
@@ -79,25 +74,58 @@ export function createHotkeySequence(
   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 registration = registerHotkeySequence(
+    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,
-      options,
+      mergedOptions,
     )
+    lastSequenceKey = sequenceKey
+  })
 
-    return () => {
+  onDestroy(() => {
+    if (registration?.isActive) {
       registration.unregister()
+      registration = null
     }
   })
 }
@@ -126,26 +154,48 @@ export function createHotkeySequenceAttachment(
   options: MaybeGetter<CreateHotkeySequenceOptions> = {},
 ): Attachment<HTMLElement> {
   return (element) => {
-    let registration: ReturnType<typeof registerHotkeySequence> | null = null
+    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
 
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
+      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,
-        options,
+        mergedOptions,
       )
+      lastSequenceKey = sequenceKey
     })
 
     return () => {

package/src/createHotkeySequenceRecorder.svelte.ts

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

package/src/createHotkeySequences.svelte.ts

@@ -0,0 +1,274 @@
+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/index.ts

@@ -4,7 +4,9 @@ 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 './getHeldKeyCodesMap.svelte'
 export * from './getIsKeyHeld.svelte'