@tanstack/svelte-hotkeys 0.12.1 → 0.14.0

package/dist/createHotkeySequence.svelte.d.ts

@@ -1,65 +0,0 @@
-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;
-}
-/**
- * Register a global keyboard shortcut sequence for the current component.
- *
- * Each step may include modifiers. You can chain the same modifier across
- * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
- * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
- * advance the sequence or reset progress.
- *
- * @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 })
- *
- *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
- *   createHotkeySequence(['Shift+R', 'Shift+T'], () => {
- *     nextAction()
- *   })
- * </script>
- *
- * <div>
- *   ....
- * </div>
- * ```
- */
-export declare function createHotkeySequence(sequence: MaybeGetter<HotkeySequence>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeySequenceOptions>): void;
-/**
- * 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 declare function createHotkeySequenceAttachment(sequence: MaybeGetter<HotkeySequence>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeySequenceOptions>): Attachment<HTMLElement>;

package/dist/createHotkeySequence.svelte.js

@@ -1,149 +0,0 @@
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
-import { onDestroy } from 'svelte';
-import { getDefaultHotkeysOptions } from './HotkeysCtx';
-import { resolveMaybeGetter } from './internal.svelte';
-function registerHotkeySequence(target, sequence, callback, mergedOptions) {
-    return getSequenceManager().register(sequence, callback, {
-        ...mergedOptions,
-        target,
-    });
-}
-/**
- * Register a global keyboard shortcut sequence for the current component.
- *
- * Each step may include modifiers. You can chain the same modifier across
- * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
- * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
- * advance the sequence or reset progress.
- *
- * @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 })
- *
- *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
- *   createHotkeySequence(['Shift+R', 'Shift+T'], () => {
- *     nextAction()
- *   })
- * </script>
- *
- * <div>
- *   ....
- * </div>
- * ```
- */
-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 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;
-        }
-    });
-}
-/**
- * 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, 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;
-            }
-            registration = registerHotkeySequence(element, resolvedSequence, callback, mergedOptions);
-            lastSequenceKey = sequenceKey;
-        });
-        return () => {
-            if (registration?.isActive) {
-                registration.unregister();
-            }
-        };
-    };
-}

package/dist/createHotkeySequenceRecorder.svelte.d.ts

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

@@ -1,65 +0,0 @@
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys';
-import { onDestroy } from 'svelte';
-import { getDefaultHotkeysOptions } from './HotkeysCtx';
-import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte';
-class SvelteHotkeySequenceRecorderState {
-    #recorder;
-    #subscribe;
-    constructor(options) {
-        this.#recorder = new HotkeySequenceRecorder(options);
-        this.#subscribe = createStoreSubscriber(this.#recorder.store);
-    }
-    get isRecording() {
-        this.#subscribe();
-        return this.#recorder.store.state.isRecording;
-    }
-    get steps() {
-        this.#subscribe();
-        return this.#recorder.store.state.steps;
-    }
-    get recordedSequence() {
-        this.#subscribe();
-        return this.#recorder.store.state.recordedSequence;
-    }
-    setOptions(options) {
-        this.#recorder.setOptions(options);
-    }
-    // Keep the recorder receiver when used directly as an event handler.
-    startRecording = () => {
-        this.#recorder.start();
-    };
-    // Keep the recorder receiver when used directly as an event handler.
-    stopRecording = () => {
-        this.#recorder.stop();
-    };
-    // Keep the recorder receiver when used directly as an event handler.
-    cancelRecording = () => {
-        this.#recorder.cancel();
-    };
-    // Keep the recorder receiver when used directly as an event handler.
-    commitRecording = () => {
-        this.#recorder.commit();
-    };
-    destroy() {
-        this.#recorder.destroy();
-    }
-}
-/**
- * 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

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

@@ -1,189 +0,0 @@
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
-import { onDestroy } from 'svelte';
-import { SvelteMap, SvelteSet } from 'svelte/reactivity';
-import { getDefaultHotkeysOptions } from './HotkeysCtx';
-import { resolveMaybeGetter } from './internal.svelte';
-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);
-        };
-    };
-}