@tanstack/svelte-hotkeys 0.9.1 → 0.11.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="./media/header_hotkeys.png" alt="TanStack Hotkeys" />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/hotkeys.png"
+      alt="TanStack Hotkeys"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />

package/dist/createHotkeyRecorder.svelte.js

@@ -54,6 +54,18 @@ class SvelteHotkeyRecorderState {
     constructor(options) {
         _SvelteHotkeyRecorderState_recorder.set(this, void 0);
         _SvelteHotkeyRecorderState_subscribe.set(this, void 0);
+        // Keep the recorder receiver when used directly as an event handler.
+        this.startRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").start();
+        };
+        // Keep the recorder receiver when used directly as an event handler.
+        this.stopRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").stop();
+        };
+        // Keep the recorder receiver when used directly as an event handler.
+        this.cancelRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").cancel();
+        };
         __classPrivateFieldSet(this, _SvelteHotkeyRecorderState_recorder, new HotkeyRecorder(options), "f");
         __classPrivateFieldSet(this, _SvelteHotkeyRecorderState_subscribe, createStoreSubscriber(__classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").store), "f");
     }
@@ -68,15 +80,6 @@ class SvelteHotkeyRecorderState {
     setOptions(options) {
         __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").setOptions(options);
     }
-    startRecording() {
-        __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").start();
-    }
-    stopRecording() {
-        __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").stop();
-    }
-    cancelRecording() {
-        __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").cancel();
-    }
     destroy() {
         __classPrivateFieldGet(this, _SvelteHotkeyRecorderState_recorder, "f").destroy();
     }

package/dist/createHotkeySequenceRecorder.svelte.js

@@ -18,6 +18,22 @@ class SvelteHotkeySequenceRecorderState {
     constructor(options) {
         _SvelteHotkeySequenceRecorderState_recorder.set(this, void 0);
         _SvelteHotkeySequenceRecorderState_subscribe.set(this, void 0);
+        // Keep the recorder receiver when used directly as an event handler.
+        this.startRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").start();
+        };
+        // Keep the recorder receiver when used directly as an event handler.
+        this.stopRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").stop();
+        };
+        // Keep the recorder receiver when used directly as an event handler.
+        this.cancelRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").cancel();
+        };
+        // Keep the recorder receiver when used directly as an event handler.
+        this.commitRecording = () => {
+            __classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").commit();
+        };
         __classPrivateFieldSet(this, _SvelteHotkeySequenceRecorderState_recorder, new HotkeySequenceRecorder(options), "f");
         __classPrivateFieldSet(this, _SvelteHotkeySequenceRecorderState_subscribe, createStoreSubscriber(__classPrivateFieldGet(this, _SvelteHotkeySequenceRecorderState_recorder, "f").store), "f");
     }
@@ -36,18 +52,6 @@ class SvelteHotkeySequenceRecorderState {
     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();
     }

package/dist/getHotkeyHint.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys';
+import type { MaybeGetter } from './internal.svelte';
+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 bindings and options.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+export declare function getHotkeyHint(hotkey: MaybeGetter<RegisterableHotkey>, options?: MaybeGetter<HeldModifierOptions>): SvelteHotkeyHint;

package/dist/getHotkeyHint.svelte.js

@@ -0,0 +1,36 @@
+import { createSubscriber } from 'svelte/reactivity';
+import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys';
+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 bindings and options.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+export function getHotkeyHint(hotkey, options = {}) {
+    const tracker = getKeyStateTracker();
+    // Resolve current reactive arguments without caching a stale binding.
+    const read = () => matchesHeldModifiers(resolveMaybeGetter(hotkey), tracker.store.state.heldKeys, resolveMaybeGetter(options));
+    let previous = false;
+    // Notify Svelte only when visibility changes, not for every unrelated held key.
+    const subscribe = createSubscriber((update) => {
+        previous = read();
+        const subscription = tracker.store.subscribe(() => {
+            const next = read();
+            if (next !== previous) {
+                previous = next;
+                update();
+            }
+        });
+        return () => subscription.unsubscribe();
+    });
+    return {
+        /** Reads visibility and subscribes the current reactive consumer when needed. */
+        get visible() {
+            subscribe();
+            previous = read();
+            return previous;
+        },
+    };
+}

package/dist/index.d.ts

@@ -12,3 +12,4 @@ export * from './getIsKeyHeld.svelte';
 export { default as HotkeysProvider } from './HotkeysProvider.svelte';
 export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx';
 export type { HotkeysProviderOptions, HotkeysProviderProps } from './HotkeysCtx';
+export * from './getHotkeyHint.svelte';

package/dist/index.js

@@ -12,3 +12,4 @@ export * from './getHeldKeyCodesMap.svelte';
 export * from './getIsKeyHeld.svelte';
 export { default as HotkeysProvider } from './HotkeysProvider.svelte';
 export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx';
+export * from './getHotkeyHint.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -40,14 +40,14 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.7.1"
+    "@tanstack/hotkeys": "0.9.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
-    "@typescript-eslint/parser": "^8.57.2",
-    "eslint-plugin-svelte": "^3.16.0",
-    "svelte": "^5.55.0"
+    "@typescript-eslint/parser": "^8.59.0",
+    "eslint-plugin-svelte": "^3.17.1",
+    "svelte": "^5.55.5"
   },
   "peerDependencies": {
     "svelte": "^5.25.0"

package/src/createHotkeyRecorder.svelte.ts

@@ -78,15 +78,18 @@ class SvelteHotkeyRecorderState implements SvelteHotkeyRecorder {
     this.#recorder.setOptions(options)
   }
 
-  startRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  startRecording = (): void => {
     this.#recorder.start()
   }
 
-  stopRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  stopRecording = (): void => {
     this.#recorder.stop()
   }
 
-  cancelRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  cancelRecording = (): void => {
     this.#recorder.cancel()
   }
 

package/src/createHotkeySequenceRecorder.svelte.ts

@@ -46,19 +46,23 @@ class SvelteHotkeySequenceRecorderState implements SvelteHotkeySequenceRecorder
     this.#recorder.setOptions(options)
   }
 
-  startRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  startRecording = (): void => {
     this.#recorder.start()
   }
 
-  stopRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  stopRecording = (): void => {
     this.#recorder.stop()
   }
 
-  cancelRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  cancelRecording = (): void => {
     this.#recorder.cancel()
   }
 
-  commitRecording(): void {
+  // Keep the recorder receiver when used directly as an event handler.
+  commitRecording = (): void => {
     this.#recorder.commit()
   }
 

package/src/getHotkeyHint.svelte.ts

@@ -0,0 +1,51 @@
+import { createSubscriber } from 'svelte/reactivity'
+import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'
+import { resolveMaybeGetter } from './internal.svelte'
+import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'
+import type { MaybeGetter } from './internal.svelte'
+
+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 bindings and options.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+export function getHotkeyHint(
+  hotkey: MaybeGetter<RegisterableHotkey>,
+  options: MaybeGetter<HeldModifierOptions> = {},
+): SvelteHotkeyHint {
+  const tracker = getKeyStateTracker()
+  // Resolve current reactive arguments without caching a stale binding.
+  const read = () =>
+    matchesHeldModifiers(
+      resolveMaybeGetter(hotkey),
+      tracker.store.state.heldKeys,
+      resolveMaybeGetter(options),
+    )
+  let previous = false
+  // Notify Svelte only when visibility changes, not for every unrelated held key.
+  const subscribe = createSubscriber((update) => {
+    previous = read()
+    const subscription = tracker.store.subscribe(() => {
+      const next = read()
+      if (next !== previous) {
+        previous = next
+        update()
+      }
+    })
+    return () => subscription.unsubscribe()
+  })
+  return {
+    /** Reads visibility and subscribes the current reactive consumer when needed. */
+    get visible() {
+      subscribe()
+      previous = read()
+      return previous
+    },
+  }
+}

package/src/index.ts

@@ -19,3 +19,4 @@ export {
   setHotkeysContext,
 } from './HotkeysCtx'
 export type { HotkeysProviderOptions, HotkeysProviderProps } from './HotkeysCtx'
+export * from './getHotkeyHint.svelte'