@tanstack/svelte-hotkeys 0.14.4 → 0.15.0

package/README.md

@@ -51,7 +51,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is in beta. We are actively developing the library and are open to feedback and contributions.
 
 Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
 

package/dist/HotkeysCtx.d.ts

@@ -1,5 +1,6 @@
 import { AppHotkeysStore } from '@tanstack/hotkeys';
 import type { AppHotkeys, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
+import type { HotkeysProviderScopeProps } from '@tanstack/hotkeys/adapter';
 import type { CreateHotkeyCommonOptions } from './createHotkey.svelte';
 import type { Snippet } from 'svelte';
 export interface HotkeysProviderOptions {
@@ -12,7 +13,8 @@ export interface HotkeysProviderOptions {
     hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
 }
 /** Options for `setHotkeysContext` and props for `HotkeysProvider`. */
-export interface HotkeysContextOptions {
+export interface HotkeysContextOptions extends HotkeysProviderScopeProps {
+    /** Merged with the parent context's defaults. */
     defaultOptions?: HotkeysProviderOptions;
     /**
      * Every app hotkey, from `defineAppHotkeys`. Read when the context is set;
@@ -33,11 +35,19 @@ export interface HotkeysProviderProps extends HotkeysContextOptions {
 export declare const DEFAULT_OPTIONS: HotkeysProviderOptions;
 interface HotkeysContextValue {
     readonly appHotkeysStore: AppHotkeysStore | null;
+    /** Merged with every ancestor's defaults, including `hotkey.scope`. */
     readonly defaultOptions: HotkeysProviderOptions;
+    /** Whether this context and every ancestor are enabled. */
+    readonly enabled: boolean;
 }
 /**
  * Sets the hotkeys context for descendants. `HotkeysProvider` calls this; call
- * it directly in a root component's script instead of rendering the provider.
+ * it directly in a component's script instead of rendering the provider.
+ *
+ * Nest contexts to create hotkey scopes. A nested context inherits app
+ * hotkeys and merges default options. With `scope`, its hotkeys fire only
+ * while the component is mounted and enabled; with `exclusive`, only its
+ * hotkeys fire.
  *
  * @example
  * ```svelte

package/dist/HotkeysCtx.js

@@ -1,10 +1,17 @@
 import { createContext, onMount } from 'svelte';
 import { AppHotkeysStore, publishAppHotkeysStore } from '@tanstack/hotkeys';
+import { getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, } from '@tanstack/hotkeys/adapter';
+import { activateScopeWhileMounted } from './internal.svelte';
 export const DEFAULT_OPTIONS = {};
 const [useHotkeysContext, setHotkeysContextValue] = createContext();
 /**
  * Sets the hotkeys context for descendants. `HotkeysProvider` calls this; call
- * it directly in a root component's script instead of rendering the provider.
+ * it directly in a component's script instead of rendering the provider.
+ *
+ * Nest contexts to create hotkey scopes. A nested context inherits app
+ * hotkeys and merges default options. With `scope`, its hotkeys fire only
+ * while the component is mounted and enabled; with `exclusive`, only its
+ * hotkeys fire.
  *
  * @example
  * ```svelte
@@ -23,6 +30,7 @@ export function setHotkeysContext(options = {}) {
 }
 /** Sets the context from a getter, so default options stay reactive. */
 export function setHotkeysContextSource(source) {
+    const parent = getHotkeysContext();
     const { appHotkeys, customHotkeys } = source();
     const store = appHotkeys
         ? new AppHotkeysStore(appHotkeys, {
@@ -33,12 +41,28 @@ export function setHotkeysContextSource(source) {
     // Publish the store so devtools can list declared hotkeys.
     if (store)
         onMount(() => publishAppHotkeysStore(store));
-    return setHotkeysContextValue({
-        appHotkeysStore: store,
+    const context = setHotkeysContextValue({
+        appHotkeysStore: store ?? parent?.appHotkeysStore ?? null,
         get defaultOptions() {
-            return source().defaultOptions ?? DEFAULT_OPTIONS;
+            const { defaultOptions, scope } = source();
+            return mergeHotkeysProviderDefaults(parent?.defaultOptions, defaultOptions, scope);
+        },
+        get enabled() {
+            return (parent?.enabled ?? true) && source().enabled !== false;
         },
     });
+    // Compared by value, so a new `exclusive` object does not reactivate the
+    // scope and lose its precedence.
+    activateScopeWhileMounted(() => {
+        const { scope, exclusive } = source();
+        return getHotkeysProviderScopeKey({
+            scope,
+            exclusive,
+            active: context.enabled,
+            parent: parent?.defaultOptions.hotkey?.scope,
+        });
+    });
+    return context;
 }
 export function getHotkeysContext() {
     try {

package/dist/HotkeysProvider.svelte

@@ -9,6 +9,9 @@
     appHotkeys,
     customHotkeys,
     onCustomHotkeysChange,
+    scope,
+    exclusive,
+    enabled,
   }: HotkeysProviderProps = $props()
 
   const context = setHotkeysContextSource(() => ({
@@ -16,6 +19,9 @@
     appHotkeys,
     customHotkeys,
     onCustomHotkeysChange,
+    scope,
+    exclusive,
+    enabled,
   }))
 
   // Keep declarations current (for example after hot module replacement).

package/dist/createHotkey.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { Attachment } from 'svelte/attachments';
-import type { AppHotkey, HotkeyCallback, RegisterableHotkey } from '@tanstack/hotkeys';
+import type { AppHotkey, HotkeyCallback, HotkeyCallbackContextFor, RegisterableHotkey } from '@tanstack/hotkeys';
 import type { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from '@tanstack/hotkeys/adapter';
 import type { MaybeGetter } from './internal.svelte';
 /** The document or window to listen on. Use an attachment for elements. */
@@ -37,7 +37,7 @@ export type CreateAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterApp
  * ```
  */
 export declare function createHotkey<T extends AppHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateAppHotkeyOptions<T>>): void;
-export declare function createHotkey<T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeyOptionsFor<T>>): void;
+export declare function createHotkey<const T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeGetter<CreateHotkeyOptionsFor<T>>): void;
 /**
  * Create an attachment for an element-scoped hotkey: a chord, a sequence, or
  * an app hotkey that listens on the attached element.
@@ -52,4 +52,4 @@ export declare function createHotkey<T extends RegisterableHotkey>(hotkey: Maybe
  * ```
  */
 export declare function createHotkeyAttachment<T extends AppHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateAppHotkeyOptions<T>>): Attachment<HTMLElement>;
-export declare function createHotkeyAttachment<T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeyOptionsFor<T>>): Attachment<HTMLElement>;
+export declare function createHotkeyAttachment<const T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeGetter<CreateHotkeyOptionsFor<T>>): Attachment<HTMLElement>;

package/dist/createHotkeyRecorder.svelte.d.ts

@@ -27,7 +27,7 @@ export interface SvelteHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
  * ```svelte
  * <script lang="ts">
  *   const recorder = createHotkeyRecorder({ onRecord: (hotkey) => (shortcut = hotkey) })
- *   const sequenceRecorder = createHotkeyRecorder({ maxSteps: 3, onRecord: save })
+ *   const sequenceRecorder = createHotkeyRecorder({ maxSteps: Infinity, onRecord: save })
  * </script>
  *
  * <button onclick={recorder.startRecording}>

package/dist/createHotkeys.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { Attachment } from 'svelte/attachments';
-import type { AppHotkey, HotkeyCallback, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from '@tanstack/hotkeys';
+import type { AppHotkey, HotkeyCallback, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from '@tanstack/hotkeys';
 import type { MaybeGetter } from './internal.svelte';
 import type { CreateAppHotkeyOptions, CreateHotkeyChordOptions, CreateHotkeyCommonOptions, CreateHotkeyOptions, CreateHotkeySequenceOptions } from './createHotkey.svelte';
 /**
@@ -8,15 +8,15 @@ import type { CreateAppHotkeyOptions, CreateHotkeyChordOptions, CreateHotkeyComm
  * kind accept only shared options.
  */
 export type CreateHotkeyDefinition = {
-    /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+    /** A chord string such as `'Mod+S'`, or a chord object */
     hotkey: MaybeGetter<RegisterableHotkeyChord>;
     /** The function to call when the hotkey is pressed */
     callback: HotkeyCallback;
     /** Per-hotkey options (merged on top of commonOptions) */
     options?: MaybeGetter<CreateHotkeyChordOptions>;
 } | {
-    /** A sequence such as `['G', 'G']` */
-    hotkey: MaybeGetter<HotkeySequence>;
+    /** A sequence such as `['G', 'G']`, with each step a string or an object */
+    hotkey: MaybeGetter<RegisterableHotkeySequence>;
     callback: HotkeyCallback;
     options?: MaybeGetter<CreateHotkeySequenceOptions>;
 } | {

package/dist/getAppHotkeys.svelte.d.ts

@@ -10,8 +10,8 @@ export interface SvelteAppHotkeys {
  * @example
  * ```svelte
  * <script lang="ts">
- *   const hotkeys = getAppHotkeys()
- *   createHotkey(() => hotkeys.current['doc.save'], () => save())
+ *   const appHotkeys = getAppHotkeys()
+ *   createHotkey(() => appHotkeys.current['doc.save'], () => save())
  * </script>
  * ```
  */

package/dist/getAppHotkeys.svelte.js

@@ -18,8 +18,8 @@ function requireStore(name) {
  * @example
  * ```svelte
  * <script lang="ts">
- *   const hotkeys = getAppHotkeys()
- *   createHotkey(() => hotkeys.current['doc.save'], () => save())
+ *   const appHotkeys = getAppHotkeys()
+ *   createHotkey(() => appHotkeys.current['doc.save'], () => save())
  * </script>
  * ```
  */

package/dist/internal.svelte.d.ts

@@ -13,4 +13,9 @@ export declare function createStoreSubscriber<TState>(store: SubscribableStore<T
  * hotkeys store, so it re-runs when app hotkeys or custom hotkeys change.
  */
 export declare function createAppHotkeysSubscriber(store: AppHotkeysStore | null): () => void;
+/**
+ * Activates a provider's scope while the component is mounted, and again
+ * whenever the key from `getHotkeysProviderScopeKey` changes.
+ */
+export declare function activateScopeWhileMounted(getKey: () => string | null): void;
 export {};

package/dist/internal.svelte.js

@@ -1,4 +1,5 @@
 import { createSubscriber } from 'svelte/reactivity';
+import { activateHotkeysProviderScope } from '@tanstack/hotkeys/adapter';
 export function resolveMaybeGetter(value) {
     return typeof value === 'function' ? value() : value;
 }
@@ -18,3 +19,11 @@ const noop = () => { };
 export function createAppHotkeysSubscriber(store) {
     return store ? createStoreSubscriber(store.store) : noop;
 }
+/**
+ * Activates a provider's scope while the component is mounted, and again
+ * whenever the key from `getHotkeysProviderScopeKey` changes.
+ */
+export function activateScopeWhileMounted(getKey) {
+    const key = $derived(getKey());
+    $effect(() => (key ? activateHotkeysProviderScope(key) : undefined));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.15.0"
+    "@tanstack/hotkeys": "0.16.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^3.0.0",