@tanstack/svelte-hotkeys 0.15.1 → 0.17.0

package/dist/getHotkeyHint.svelte.d.ts

@@ -5,9 +5,10 @@ export interface SvelteHotkeyHint {
 }
 /**
  * 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 { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey, } from '@tanstack/hotkeys';
 import { getHotkeysContext } from './HotkeysCtx';
 import { resolveMaybeGetter } from './internal.svelte';
 /**
  * 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/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';
+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/index.d.ts

@@ -4,6 +4,7 @@ export * from './createHotkeys.svelte';
 export * from './createHotkeyRecorder.svelte';
 export * from './getHeldKeys.svelte';
 export * from './getHotkeyRegistrations.svelte';
+export * from './getHotkeyScopesState.svelte';
 export * from './getHeldKeyCodesMap.svelte';
 export * from './getIsKeyHeld.svelte';
 export * from './getAppHotkeys.svelte';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './createHotkeys.svelte';
 export * from './createHotkeyRecorder.svelte';
 export * from './getHeldKeys.svelte';
 export * from './getHotkeyRegistrations.svelte';
+export * from './getHotkeyScopesState.svelte';
 export * from './getHeldKeyCodesMap.svelte';
 export * from './getIsKeyHeld.svelte';
 export * from './getAppHotkeys.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -20,7 +20,8 @@
     "keys",
     "hotkeys",
     "keyboard",
-    "shortcuts"
+    "shortcuts",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -36,10 +37,11 @@
   },
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.16.1"
+    "@tanstack/hotkeys": "0.18.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^3.0.0",

package/skills/svelte-hotkeys/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: svelte-hotkeys
+description: >-
+  Use when adding or fixing keyboard shortcuts in a Svelte 5 app with
+  @tanstack/svelte-hotkeys: createHotkey and createHotkeys, getter options,
+  createHotkeyAttachment for element hotkeys, HotkeysProvider and
+  setHotkeysContext scopes, app hotkey getters, recorders, held-key and hint
+  getters, or replacing svelte:window keydown handlers.
+metadata:
+  purpose: >-
+    Svelte 5 bindings for TanStack Hotkeys: getters, attachments, providers,
+    and the Svelte-specific reactivity mistakes to avoid.
+  type: framework
+  framework: svelte
+  library: '@tanstack/svelte-hotkeys'
+  library_version: '0.15.0'
+sources:
+  - src/createHotkey.svelte.ts
+  - src/createHotkeys.svelte.ts
+  - src/HotkeysCtx.ts
+  - src/HotkeysProvider.svelte
+  - src/getAppHotkeys.svelte.ts
+  - src/createHotkeyRecorder.svelte.ts
+  - TanStack/hotkeys:docs/framework/svelte/quick-start.md
+  - TanStack/hotkeys:docs/framework/svelte/guides/hotkeys-provider-and-scopes.md
+requires:
+  - '@tanstack/hotkeys#hotkeys-core'
+---
+
+# TanStack Hotkeys in Svelte
+
+Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).
+
+```svelte
+<script lang="ts">
+  import {
+    createHotkey,
+    createHotkeyAttachment,
+  } from '@tanstack/svelte-hotkeys'
+
+  let isDirty = $state(false)
+
+  createHotkey(
+    'Mod+S',
+    () => save(),
+    () => ({ enabled: isDirty }),
+  )
+  const closeOnEscape = createHotkeyAttachment('Escape', () => closePanel())
+</script>
+
+<div tabindex="0" {@attach closeOnEscape} oninput={() => (isDirty = true)}>
+  Panel
+</div>
+```
+
+## 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, `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`.
+
+No provider is required. Call these at the top level of a component's `<script>`.
+
+## Pitfalls
+
+- **Pass options as a getter.** `{ enabled: isDirty }` is read once, during initialization, so the hotkey never follows the state. Use `() => ({ enabled: isDirty })`. The hotkey and `createHotkeys`' definitions also accept getters.
+- **Don't destructure the returned objects.** `const { held } = getIsKeyHeld('Shift')` copies the value once. Keep the object and read `shift.held`, `recorder.isRecording`, or `appHotkeys.current` where you use it.
+- **Use attachments for element hotkeys.** The `target` option takes only `document` or `window`.
+- **Call `setHotkeysContext` before creating the component's hotkeys.** It applies to the component itself, so a hotkey created first lands in the outer scope, which an exclusive context then suspends. It reads its options once; for `enabled` or `exclusive` that change, wrap the component in `<HotkeysProvider>`. Give each open dialog its own scope name.
+- **The callback isn't tracked.** Read state and props inside it.
+- **Call the functions directly.** A `createShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, getter options, and app hotkeys.
+
+When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Svelte](references/app-hotkeys.md).
+
+## API discovery and docs
+
+Signatures: `node_modules/@tanstack/svelte-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/svelte/guides/<page>.md`, such as `hotkeys`, `hotkeys-provider-and-scopes`, or `app-hotkeys`. Devtools: `hotkeysDevtoolsPlugin()` from `@tanstack/svelte-hotkeys-devtools` in `@tanstack/svelte-devtools`.

package/skills/svelte-hotkeys/references/app-hotkeys.md

@@ -0,0 +1,79 @@
+# App hotkeys in Svelte
+
+The `@tanstack/hotkeys#app-hotkeys` skill owns the rules. This is the Svelte wiring.
+
+```ts
+// app-hotkeys.ts
+import { defineAppHotkeys } from '@tanstack/svelte-hotkeys'
+
+export const appHotkeys = defineAppHotkeys({
+  'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' } },
+  'help.shortcuts': { hotkey: 'Mod+/', meta: { name: 'Keyboard shortcuts' } },
+})
+
+declare module '@tanstack/svelte-hotkeys' {
+  interface Register {
+    appHotkeys: typeof appHotkeys
+  }
+}
+```
+
+```svelte
+<!-- App.svelte -->
+<script lang="ts">
+  import { HotkeysProvider } from '@tanstack/svelte-hotkeys'
+  import type { CustomHotkeys } from '@tanstack/svelte-hotkeys'
+  import { appHotkeys } from './app-hotkeys'
+  import AppContent from './AppContent.svelte'
+
+  const saved: CustomHotkeys = JSON.parse(
+    localStorage.getItem('hotkeys') ?? '{}',
+  )
+</script>
+
+<HotkeysProvider
+  {appHotkeys}
+  customHotkeys={saved}
+  onCustomHotkeysChange={(custom) =>
+    localStorage.setItem('hotkeys', JSON.stringify(custom))}
+>
+  <AppContent />
+</HotkeysProvider>
+```
+
+Read app hotkeys inside a getter so registrations follow rebinding: `createHotkey(() => appHotkeys.current['doc.save'], save)`, with `const appHotkeys = getAppHotkeys()`. Build a cheat sheet from `getAppHotkeyList().current`.
+
+A settings row records with `createHotkeyRecorder` and saves through `getCustomHotkeys`:
+
+```svelte
+<script lang="ts">
+  import {
+    createHotkeyRecorder,
+    formatForDisplay,
+    getAppHotkeys,
+    getCustomHotkeys,
+  } from '@tanstack/svelte-hotkeys'
+  import type { AppHotkeyId } from '@tanstack/svelte-hotkeys'
+
+  let { id }: { id: AppHotkeyId } = $props()
+  const appHotkeys = getAppHotkeys()
+  const custom = getCustomHotkeys()
+  const appHotkey = $derived(appHotkeys.current[id])
+
+  const recorder = createHotkeyRecorder(() => ({
+    maxSteps: Infinity,
+    validate: (hotkey) => {
+      const [conflict] = custom.findConflicts(id, hotkey)
+      return conflict ? `Used by ${conflict.meta?.name ?? conflict.id}` : true
+    },
+    onRecord: (hotkey) => custom.setCustomHotkey(id, hotkey),
+    onClear: () => custom.setCustomHotkey(id, null),
+  }))
+</script>
+
+{appHotkey.meta?.name}: {appHotkey.hotkey
+  ? formatForDisplay(appHotkey.hotkey)
+  : 'Unassigned'}
+<button onclick={recorder.startRecording}>Change</button>
+<button onclick={() => custom.resetCustomHotkey(id)}>Reset</button>
+```