@tanstack/svelte-hotkeys 0.16.0 → 0.17.1

package/dist/HotkeysCtx.d.ts

@@ -1,7 +1,7 @@
 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 { CreateHotkeyCommonOptions } from './createHotkey.svelte.js';
 import type { Snippet } from 'svelte';
 export interface HotkeysProviderOptions {
     /**

package/dist/HotkeysCtx.js

@@ -1,7 +1,7 @@
 import { createContext, onMount } from 'svelte';
 import { AppHotkeysStore, publishAppHotkeysStore } from '@tanstack/hotkeys';
 import { getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, } from '@tanstack/hotkeys/adapter';
-import { activateScopeWhileMounted } from './internal.svelte';
+import { activateScopeWhileMounted } from './internal.svelte.js';
 export const DEFAULT_OPTIONS = {};
 const [useHotkeysContext, setHotkeysContextValue] = createContext();
 /**

package/dist/HotkeysProvider.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
-  import { setHotkeysContextSource } from './HotkeysCtx'
+  import { setHotkeysContextSource } from './HotkeysCtx.js'
 
-  import type { HotkeysProviderProps } from './HotkeysCtx'
+  import type { HotkeysProviderProps } from './HotkeysCtx.js'
 
   let {
     children,

package/dist/HotkeysProvider.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { HotkeysProviderProps } from './HotkeysCtx';
+import type { HotkeysProviderProps } from './HotkeysCtx.js';
 declare const HotkeysProvider: import("svelte").Component<HotkeysProviderProps, {}, "">;
 type HotkeysProvider = ReturnType<typeof HotkeysProvider>;
 export default HotkeysProvider;

package/dist/createHotkey.svelte.d.ts

@@ -1,7 +1,7 @@
 import type { Attachment } from 'svelte/attachments';
 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';
+import type { MaybeGetter } from './internal.svelte.js';
 /** The document or window to listen on. Use an attachment for elements. */
 export type CreateHotkeyTarget = Document | Window;
 /** Options shared by chords and sequences. */

package/dist/createHotkey.svelte.js

@@ -1,4 +1,4 @@
-import { createHotkeys, createHotkeysAttachment } from './createHotkeys.svelte';
+import { createHotkeys, createHotkeysAttachment, } from './createHotkeys.svelte.js';
 export function createHotkey(hotkey, callback, options = {}) {
     createHotkeys([{ hotkey, callback, options }]);
 }

package/dist/createHotkeyRecorder.svelte.js

@@ -1,7 +1,6 @@
 import { HotkeyRecorder } from '@tanstack/hotkeys';
-import { onDestroy } from 'svelte';
-import { getDefaultHotkeysOptions } from './HotkeysCtx';
-import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte';
+import { getDefaultHotkeysOptions } from './HotkeysCtx.js';
+import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte.js';
 class SvelteHotkeyRecorderState {
     #recorder;
     #subscribe;
@@ -51,8 +50,9 @@ export function createHotkeyRecorder(options) {
     $effect(() => {
         recorder.setOptions(resolve());
     });
-    onDestroy(() => {
-        recorder.destroy();
-    });
+    // Unlike onDestroy, an effect teardown also runs when an $effect.root that
+    // owns the recorder is destroyed. $effect.pre runs now, so the teardown is
+    // in place even if the root is destroyed before effects flush.
+    $effect.pre(() => () => recorder.destroy());
     return recorder;
 }

package/dist/createHotkeys.svelte.d.ts

@@ -1,7 +1,7 @@
 import type { Attachment } from 'svelte/attachments';
 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';
+import type { MaybeGetter } from './internal.svelte.js';
+import type { CreateAppHotkeyOptions, CreateHotkeyChordOptions, CreateHotkeyCommonOptions, CreateHotkeyOptions, CreateHotkeySequenceOptions } from './createHotkey.svelte.js';
 /**
  * One hotkey for `createHotkeys`. The hotkey and options may be getters.
  * Chords accept `requireReset`; sequences accept `timeout`; hotkeys of unknown

package/dist/createHotkeys.svelte.js

@@ -1,7 +1,6 @@
 import { createHotkeyBindings, prepareHotkeyDefinitions, } from '@tanstack/hotkeys/adapter';
-import { onDestroy } from 'svelte';
-import { getHotkeysContext } from './HotkeysCtx';
-import { createAppHotkeysSubscriber, resolveMaybeGetter, } from './internal.svelte';
+import { getHotkeysContext } from './HotkeysCtx.js';
+import { createAppHotkeysSubscriber, resolveMaybeGetter, } from './internal.svelte.js';
 /**
  * Registers definitions in an effect. With an element, every hotkey listens on
  * that element; otherwise each uses its own target (document by default).
@@ -55,7 +54,9 @@ function bindHotkeys(hotkeys, commonOptions, element) {
  */
 export function createHotkeys(hotkeys, commonOptions = {}) {
     const bindings = bindHotkeys(hotkeys, commonOptions);
-    onDestroy(() => bindings.destroy());
+    // Unlike onDestroy, an effect teardown also runs when an $effect.root that
+    // owns these hotkeys is destroyed.
+    $effect(() => () => bindings.destroy());
 }
 /**
  * Create an attachment for element-scoped hotkeys: chords, sequences, and app

package/dist/getAppHotkeys.svelte.js

@@ -1,6 +1,6 @@
-import { getHotkeysContext } from './HotkeysCtx';
-import { createStoreSubscriber } from './internal.svelte';
-import { getHotkeyRegistrations } from './getHotkeyRegistrations.svelte';
+import { getHotkeysContext } from './HotkeysCtx.js';
+import { createStoreSubscriber } from './internal.svelte.js';
+import { getHotkeyRegistrations } from './getHotkeyRegistrations.svelte.js';
 function requireStore(name) {
     const store = getHotkeysContext()?.appHotkeysStore;
     if (!store) {

package/dist/getHeldKeyCodesMap.svelte.js

@@ -1,5 +1,5 @@
 import { getKeyStateTracker } from '@tanstack/hotkeys';
-import { createStoreSubscriber } from './internal.svelte';
+import { createStoreSubscriber } from './internal.svelte.js';
 class HeldKeyCodesMapState {
     #tracker = getKeyStateTracker();
     #subscribe = createStoreSubscriber(this.#tracker.store);

package/dist/getHeldKeys.svelte.js

@@ -1,5 +1,5 @@
 import { getKeyStateTracker } from '@tanstack/hotkeys';
-import { createStoreSubscriber } from './internal.svelte';
+import { createStoreSubscriber } from './internal.svelte.js';
 class HeldKeysState {
     #tracker = getKeyStateTracker();
     #subscribe = createStoreSubscriber(this.#tracker.store);

package/dist/getHotkeyHint.svelte.d.ts

@@ -1,13 +1,14 @@
 import type { AppHotkey, HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys';
-import type { MaybeGetter } from './internal.svelte';
+import type { MaybeGetter } from './internal.svelte.js';
 export interface SvelteHotkeyHint {
     readonly visible: boolean;
 }
 /**
  * Returns an object with a reactive `visible` getter indicating whether held
- * modifiers reveal this shortcut. Pass getters to track changing hotkeys and
- * options. A sequence reveals its hint from its first step, and an app hotkey
- * uses its effective hotkey (false while unbound). This helper does not
- * register a shortcut or check whether its target is focused.
+ * modifiers reveal this shortcut. The hint shows only while the hotkey can
+ * fire: some registration of it is enabled and in an active scope. Pass
+ * getters to track changing hotkeys and options. A sequence reveals its hint
+ * from its first step, and an app hotkey matches its registrations by id and
+ * uses its effective hotkey (false while unbound). This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
  */
 export declare function getHotkeyHint(hotkey: MaybeGetter<RegisterableHotkey | AppHotkey>, options?: MaybeGetter<HeldModifierOptions>): SvelteHotkeyHint;

package/dist/getHotkeyHint.svelte.js

@@ -1,16 +1,18 @@
 import { createSubscriber } from 'svelte/reactivity';
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey, } from '@tanstack/hotkeys';
-import { getHotkeysContext } from './HotkeysCtx';
-import { resolveMaybeGetter } from './internal.svelte';
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey, } from '@tanstack/hotkeys';
+import { getHotkeysContext } from './HotkeysCtx.js';
+import { resolveMaybeGetter } from './internal.svelte.js';
 /**
  * Returns an object with a reactive `visible` getter indicating whether held
- * modifiers reveal this shortcut. Pass getters to track changing hotkeys and
- * options. A sequence reveals its hint from its first step, and an app hotkey
- * uses its effective hotkey (false while unbound). This helper does not
- * register a shortcut or check whether its target is focused.
+ * modifiers reveal this shortcut. The hint shows only while the hotkey can
+ * fire: some registration of it is enabled and in an active scope. Pass
+ * getters to track changing hotkeys and options. A sequence reveals its hint
+ * from its first step, and an app hotkey matches its registrations by id and
+ * uses its effective hotkey (false while unbound). This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
  */
 export function getHotkeyHint(hotkey, options = {}) {
     const tracker = getKeyStateTracker();
+    const manager = getHotkeyManager();
     const store = getHotkeysContext()?.appHotkeysStore ?? null;
     // Resolve current reactive arguments without caching a stale hotkey.
     const read = () => {
@@ -19,7 +21,8 @@ export function getHotkeyHint(hotkey, options = {}) {
             ? resolveAppHotkey(value, store).hotkey
             : value;
         return (resolved !== null &&
-            matchesHeldModifiers(resolved, tracker.store.state.heldKeys, resolveMaybeGetter(options)));
+            matchesHeldModifiers(resolved, tracker.store.state.heldKeys, resolveMaybeGetter(options)) &&
+            manager.hasActiveRegistration(value));
     };
     let previous = false;
     // Notify Svelte only when visibility changes, not for every unrelated held key.
@@ -33,9 +36,11 @@ export function getHotkeyHint(hotkey, options = {}) {
             }
         };
         const keys = tracker.store.subscribe(check);
+        const registrations = manager.registrations.subscribe(check);
         const custom = store?.store.subscribe(check);
         return () => {
             keys.unsubscribe();
+            registrations.unsubscribe();
             custom?.unsubscribe();
         };
     });

package/dist/getHotkeyRegistrations.svelte.js

@@ -1,5 +1,5 @@
 import { getHotkeyManager, toHotkeyRegistrationView } from '@tanstack/hotkeys';
-import { createStoreSubscriber } from './internal.svelte';
+import { createStoreSubscriber } from './internal.svelte.js';
 class HotkeyRegistrationsState {
     #manager = getHotkeyManager();
     #subscribe = createStoreSubscriber(this.#manager.registrations);

package/dist/getHotkeyScopesState.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { HotkeyScopesState } from '@tanstack/hotkeys';
+export interface SvelteHotkeyScopesState {
+    readonly state: HotkeyScopesState;
+}
+/**
+ * Svelte function that returns reactive access to the hotkey manager's scope
+ * state: the active scopes, the exclusive scope that owns the keyboard, and
+ * the scopes it allows or suspends. Updates when scopes activate or release.
+ *
+ * @returns Object with a reactive `state` property
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getHotkeyScopesState } from '@tanstack/svelte-hotkeys'
+ *
+ *   const scopes = getHotkeyScopesState()
+ * </script>
+ * {#if scopes.state.exclusive}
+ *   <p>Shortcuts belong to {scopes.state.exclusive}</p>
+ * {/if}
+ * ```
+ */
+export declare function getHotkeyScopesState(): SvelteHotkeyScopesState;

package/dist/getHotkeyScopesState.svelte.js

@@ -0,0 +1,32 @@
+import { getHotkeyManager } from '@tanstack/hotkeys';
+import { createStoreSubscriber } from './internal.svelte.js';
+class HotkeyScopesStateReader {
+    #store = getHotkeyManager().scopes;
+    #subscribe = createStoreSubscriber(this.#store);
+    get state() {
+        this.#subscribe();
+        return this.#store.state;
+    }
+}
+/**
+ * Svelte function that returns reactive access to the hotkey manager's scope
+ * state: the active scopes, the exclusive scope that owns the keyboard, and
+ * the scopes it allows or suspends. Updates when scopes activate or release.
+ *
+ * @returns Object with a reactive `state` property
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getHotkeyScopesState } from '@tanstack/svelte-hotkeys'
+ *
+ *   const scopes = getHotkeyScopesState()
+ * </script>
+ * {#if scopes.state.exclusive}
+ *   <p>Shortcuts belong to {scopes.state.exclusive}</p>
+ * {/if}
+ * ```
+ */
+export function getHotkeyScopesState() {
+    return new HotkeyScopesStateReader();
+}

package/dist/getIsKeyHeld.svelte.js

@@ -1,5 +1,5 @@
 import { getKeyStateTracker } from '@tanstack/hotkeys';
-import { createStoreSubscriber } from './internal.svelte';
+import { createStoreSubscriber } from './internal.svelte.js';
 class HeldKeyState {
     #tracker = getKeyStateTracker();
     #normalizedKey;

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 export * from '@tanstack/hotkeys';
-export * from './createHotkey.svelte';
-export * from './createHotkeys.svelte';
-export * from './createHotkeyRecorder.svelte';
-export * from './getHeldKeys.svelte';
-export * from './getHotkeyRegistrations.svelte';
-export * from './getHeldKeyCodesMap.svelte';
-export * from './getIsKeyHeld.svelte';
-export * from './getAppHotkeys.svelte';
+export * from './createHotkey.svelte.js';
+export * from './createHotkeys.svelte.js';
+export * from './createHotkeyRecorder.svelte.js';
+export * from './getHeldKeys.svelte.js';
+export * from './getHotkeyRegistrations.svelte.js';
+export * from './getHotkeyScopesState.svelte.js';
+export * from './getHeldKeyCodesMap.svelte.js';
+export * from './getIsKeyHeld.svelte.js';
+export * from './getAppHotkeys.svelte.js';
 export { default as HotkeysProvider } from './HotkeysProvider.svelte';
-export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx';
-export type { HotkeysContextOptions, HotkeysProviderOptions, HotkeysProviderProps, } from './HotkeysCtx';
-export * from './getHotkeyHint.svelte';
+export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx.js';
+export type { HotkeysContextOptions, HotkeysProviderOptions, HotkeysProviderProps, } from './HotkeysCtx.js';
+export * from './getHotkeyHint.svelte.js';

package/dist/index.js

@@ -1,13 +1,14 @@
 // Re-export everything from the core package
 export * from '@tanstack/hotkeys';
-export * from './createHotkey.svelte';
-export * from './createHotkeys.svelte';
-export * from './createHotkeyRecorder.svelte';
-export * from './getHeldKeys.svelte';
-export * from './getHotkeyRegistrations.svelte';
-export * from './getHeldKeyCodesMap.svelte';
-export * from './getIsKeyHeld.svelte';
-export * from './getAppHotkeys.svelte';
+export * from './createHotkey.svelte.js';
+export * from './createHotkeys.svelte.js';
+export * from './createHotkeyRecorder.svelte.js';
+export * from './getHeldKeys.svelte.js';
+export * from './getHotkeyRegistrations.svelte.js';
+export * from './getHotkeyScopesState.svelte.js';
+export * from './getHeldKeyCodesMap.svelte.js';
+export * from './getIsKeyHeld.svelte.js';
+export * from './getAppHotkeys.svelte.js';
 export { default as HotkeysProvider } from './HotkeysProvider.svelte';
-export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx';
-export * from './getHotkeyHint.svelte';
+export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx.js';
+export * from './getHotkeyHint.svelte.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.17.0"
+    "@tanstack/hotkeys": "0.19.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^3.0.0",
@@ -51,7 +51,7 @@
     "svelte": "^5.57.1"
   },
   "peerDependencies": {
-    "svelte": "^5.25.0"
+    "svelte": "^5.40.0"
   },
   "engines": {
     "node": ">=20"

package/skills/svelte-hotkeys/SKILL.md

@@ -55,25 +55,26 @@ Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack
 
 ## API
 
-| API                                                    | What it's for                                                                                                                    |
-| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| `createHotkey(hotkey, callback, options?)`             | Register one chord, sequence, or app hotkey on the document while the component is mounted; pass getters for values that change. |
-| `createHotkeys(definitions, commonOptions?)`           | Register several hotkeys on the document, or a getter of a list built from data.                                                 |
-| `createHotkeyAttachment(hotkey, callback, options?)`   | Create an attachment for `{@attach}` that listens on one element.                                                                |
-| `createHotkeysAttachment(definitions, commonOptions?)` | Create an attachment that registers several hotkeys on one element.                                                              |
-| `<HotkeysProvider>`                                    | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it.                 |
-| `setHotkeysContext(options)`                           | Set the same options from a component's script instead of rendering `HotkeysProvider`; they apply to that component too.         |
-| `getHotkeysContext()`                                  | Read the nearest context's merged defaults and enabled state, or `null` outside one.                                             |
-| `getDefaultHotkeysOptions()`                           | Read the default options merged from every context above.                                                                        |
-| `getAppHotkeys()`                                      | Read `.current`, the declared app hotkeys with the user's custom hotkeys applied.                                                |
-| `getAppHotkeyList()`                                   | Read `.current`, every app hotkey with its status, for a cheat sheet or settings screen.                                         |
-| `getCustomHotkeys()`                                   | Read the user's custom hotkeys from `.current`, change or reset them, and check a new one for conflicts.                         |
-| `createHotkeyRecorder(options)`                        | Record a chord or sequence the user presses, for a settings screen.                                                              |
-| `getHotkeyRegistrations()`                             | Read `.hotkeys`, every registered hotkey with its options and `meta`.                                                            |
-| `getHotkeyHint(hotkey, options?)`                      | Read `.visible`, whether held modifiers should reveal a shortcut's hint.                                                         |
-| `getIsKeyHeld(key)`                                    | Read `.held`, whether one key is held.                                                                                           |
-| `getHeldKeys()`                                        | Read `.keys`, every key that's held right now.                                                                                   |
-| `getHeldKeyCodesMap()`                                 | Read `.codes`, which maps each held key to its physical `event.code`.                                                            |
+| API                                                    | What it's for                                                                                                                                                                                       |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createHotkey(hotkey, callback, options?)`             | Register one chord, sequence, or app hotkey on the document while the component is mounted; pass getters for values that change.                                                                    |
+| `createHotkeys(definitions, commonOptions?)`           | Register several hotkeys on the document, or a getter of a list built from data.                                                                                                                    |
+| `createHotkeyAttachment(hotkey, callback, options?)`   | Create an attachment for `{@attach}` that listens on one element.                                                                                                                                   |
+| `createHotkeysAttachment(definitions, commonOptions?)` | Create an attachment that registers several hotkeys on one element.                                                                                                                                 |
+| `<HotkeysProvider>`                                    | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it.                                                                                    |
+| `setHotkeysContext(options)`                           | Set the same options from a component's script instead of rendering `HotkeysProvider`; they apply to that component too.                                                                            |
+| `getHotkeysContext()`                                  | Read the nearest context's merged defaults and enabled state, or `null` outside one.                                                                                                                |
+| `getDefaultHotkeysOptions()`                           | Read the default options merged from every context above.                                                                                                                                           |
+| `getAppHotkeys()`                                      | Read `.current`, the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
+| `getAppHotkeyList()`                                   | Read `.current`, every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                            |
+| `getCustomHotkeys()`                                   | Read the user's custom hotkeys from `.current`, change or reset them, and check a new one for conflicts.                                                                                            |
+| `createHotkeyRecorder(options)`                        | Record a chord or sequence the user presses, for a settings screen.                                                                                                                                 |
+| `getHotkeyRegistrations()`                             | Read `.hotkeys`, every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope).                                                                      |
+| `getHotkeyScopesState()`                               | Read `.state`, the active scopes and the exclusive scope that owns the keyboard.                                                                                                                    |
+| `getHotkeyHint(hotkey, options?)`                      | Read `.visible`, whether held modifiers should reveal a shortcut's hint. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |
+| `getIsKeyHeld(key)`                                    | Read `.held`, whether one key is held.                                                                                                                                                              |
+| `getHeldKeys()`                                        | Read `.keys`, every key that's held right now.                                                                                                                                                      |
+| `getHeldKeyCodesMap()`                                 | Read `.codes`, which maps each held key to its physical `event.code`.                                                                                                                               |
 
 The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.