@tanstack/vue-hotkeys 0.16.0 → 0.17.1

package/dist/HotkeysProviderContext.d.ts

@@ -63,6 +63,11 @@ export interface ProvideHotkeysContextOptions {
  * ```
  */
 export declare function provideHotkeysContext(options?: ProvideHotkeysContextOptions): void;
+/**
+ * The nearest context, or `null`. Outside a component, such as in a bare
+ * `effectScope`, there is no context to read, so this skips `inject` and its
+ * warning.
+ */
 export declare function useHotkeysContext(): HotkeysContextValue | null;
 export declare function useDefaultHotkeysOptions(): HotkeysProviderOptions;
 //#endregion

package/dist/HotkeysProviderContext.js

@@ -1,5 +1,5 @@
 import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
-import { computed, inject, onMounted, onScopeDispose, provide, toValue, watch } from "vue";
+import { computed, hasInjectionContext, inject, onMounted, onScopeDispose, provide, toValue, watch } from "vue";
 import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/HotkeysProviderContext.ts
@@ -62,11 +62,16 @@ function provideHotkeysContext(options = {}) {
 	};
 	provide(HotkeysContext, contextValue);
 }
+/**
+* The nearest context, or `null`. Outside a component, such as in a bare
+* `effectScope`, there is no context to read, so this skips `inject` and its
+* warning.
+*/
 function useHotkeysContext() {
-	return inject(HotkeysContext, null);
+	return hasInjectionContext() ? inject(HotkeysContext, null) : null;
 }
 function useDefaultHotkeysOptions() {
-	return inject(HotkeysContext, null)?.defaultOptions ?? DEFAULT_OPTIONS;
+	return useHotkeysContext()?.defaultOptions ?? DEFAULT_OPTIONS;
 }
 
 //#endregion

package/dist/defaultOptions.js

@@ -1,5 +1,6 @@
 import { useHotkeysContext } from "./HotkeysProviderContext.js";
-import { Store, useSelector } from "@tanstack/vue-store";
+import { useStoreSelector } from "./useStoreSelector.js";
+import { shallowRef } from "vue";
 
 //#region src/defaultOptions.ts
 /** Captures the context once and reads current defaults inside reactive computations. */
@@ -7,7 +8,6 @@ function useDefaultHotkeysOptionsSource() {
 	const context = useHotkeysContext();
 	return () => context?.defaultOptions ?? {};
 }
-const NO_APP_HOTKEYS = new Store(null);
 /**
 * The provider's app hotkeys store and a ref that tracks its state, so
 * watchers re-run when app hotkeys or custom hotkeys change.
@@ -16,7 +16,7 @@ function useAppHotkeysStoreSource() {
 	const store = useHotkeysContext()?.appHotkeysStore ?? null;
 	return {
 		store,
-		state: useSelector(store?.store ?? NO_APP_HOTKEYS, (value) => value)
+		state: store ? useStoreSelector(store.store, (value) => value) : shallowRef(null)
 	};
 }
 

package/dist/index.d.ts

@@ -7,7 +7,8 @@ import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { VueHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
+import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
 import { UseCustomHotkeysResult, useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, ProvideHotkeysContextOptions, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, VueHotkeyRecorder, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, ProvideHotkeysContextOptions, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, VueHotkeyRecorder, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -7,9 +7,10 @@ import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
+import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
 import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useHeldKeyCodes.js

@@ -1,5 +1,5 @@
+import { useStoreSelector } from "./useStoreSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHeldKeyCodes.ts
 /**
@@ -30,7 +30,7 @@ import { useSelector } from "@tanstack/vue-store";
 */
 function useHeldKeyCodes() {
 	const tracker = getKeyStateTracker();
-	return useSelector(tracker.store, (state) => state.heldCodes);
+	return useStoreSelector(tracker.store, (state) => state.heldCodes);
 }
 
 //#endregion

package/dist/useHeldKeys.js

@@ -1,5 +1,5 @@
+import { useStoreSelector } from "./useStoreSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHeldKeys.ts
 /**
@@ -28,7 +28,7 @@ import { useSelector } from "@tanstack/vue-store";
 */
 function useHeldKeys() {
 	const tracker = getKeyStateTracker();
-	return useSelector(tracker.store, (state) => state.heldKeys);
+	return useStoreSelector(tracker.store, (state) => state.heldKeys);
 }
 
 //#endregion

package/dist/useHotkeyHint.d.ts

@@ -3,10 +3,11 @@ import { ComputedRef, MaybeRefOrGetter } from "vue";
 //#region src/useHotkeyHint.d.ts
 /**
  * Returns a computed ref indicating whether held modifiers reveal this shortcut.
- * Pass refs or 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.
+ * The hint shows only while the hotkey can fire: some registration of it is
+ * enabled and in an active scope. Pass refs or 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 useHotkeyHint(hotkey: MaybeRefOrGetter<RegisterableHotkey | AppHotkey>, options?: MaybeRefOrGetter<HeldModifierOptions>): ComputedRef<boolean>;
 //#endregion

package/dist/useHotkeyHint.js

@@ -1,24 +1,27 @@
+import { useStoreSelector } from "./useStoreSelector.js";
 import { useAppHotkeysStoreSource } from "./defaultOptions.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { computed, toValue } from "vue";
-import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHotkeyHint.ts
 /**
 * Returns a computed ref indicating whether held modifiers reveal this shortcut.
-* Pass refs or 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.
+* The hint shows only while the hotkey can fire: some registration of it is
+* enabled and in an active scope. Pass refs or 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.
 */
 function useHotkeyHint(hotkey, options = {}) {
 	const appHotkeys = useAppHotkeysStoreSource();
-	const held = useSelector(getKeyStateTracker().store, (state) => state.heldKeys);
+	const manager = getHotkeyManager();
+	const registrations = useStoreSelector(manager.registrations, (state) => state);
+	const held = useStoreSelector(getKeyStateTracker().store, (state) => state.heldKeys);
 	return computed(() => {
 		appHotkeys.state.value;
 		const value = toValue(hotkey);
 		const resolved = isAppHotkey(value) ? resolveAppHotkey(value, appHotkeys.store).hotkey : value;
-		return resolved !== null && matchesHeldModifiers(resolved, held.value, toValue(options));
+		return resolved !== null && matchesHeldModifiers(resolved, held.value, toValue(options)) && registrations.value.size > 0 && manager.hasActiveRegistration(value);
 	});
 }
 

package/dist/useHotkeyRecorder.js

@@ -1,7 +1,7 @@
+import { useStoreSelector } from "./useStoreSelector.js";
 import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { onScopeDispose, toValue, watch } from "vue";
-import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHotkeyRecorder.ts
 function useHotkeyRecorder(options) {
@@ -11,9 +11,9 @@ function useHotkeyRecorder(options) {
 		...toValue(options)
 	});
 	const recorder = new HotkeyRecorder(resolve());
-	const isRecording = useSelector(recorder.store, (state) => state.isRecording);
-	const steps = useSelector(recorder.store, (state) => state.steps);
-	const recordedHotkey = useSelector(recorder.store, (state) => state.recordedHotkey);
+	const isRecording = useStoreSelector(recorder.store, (state) => state.isRecording);
+	const steps = useStoreSelector(recorder.store, (state) => state.steps);
+	const recordedHotkey = useStoreSelector(recorder.store, (state) => state.recordedHotkey);
 	const stopWatcher = watch(resolve, (resolved) => recorder.setOptions(resolved));
 	onScopeDispose(() => {
 		stopWatcher();

package/dist/useHotkeyRegistrations.js

@@ -1,5 +1,5 @@
+import { useStoreSelector } from "./useStoreSelector.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHotkeyRegistrations.ts
 /**
@@ -23,7 +23,7 @@ import { useSelector } from "@tanstack/vue-store";
 * ```
 */
 function useHotkeyRegistrations() {
-	return useSelector(getHotkeyManager().registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView));
+	return useStoreSelector(getHotkeyManager().registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView));
 }
 
 //#endregion

package/dist/useHotkeyScopesState.d.ts

@@ -0,0 +1,25 @@
+import { HotkeyScopesState } from "@tanstack/hotkeys";
+import { Ref } from "vue";
+//#region src/useHotkeyScopesState.d.ts
+/**
+ * Vue composable that returns a ref of 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 Reactive ref of the current scope state
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useHotkeyScopesState } from '@tanstack/vue-hotkeys'
+ *
+ * const scopes = useHotkeyScopesState()
+ * </script>
+ *
+ * <template>
+ *   <p v-if="scopes.exclusive">Shortcuts belong to {{ scopes.exclusive }}</p>
+ * </template>
+ * ```
+ */
+export declare function useHotkeyScopesState(): Ref<HotkeyScopesState>;
+//#endregion

package/dist/useHotkeyScopesState.js

@@ -0,0 +1,30 @@
+import { useStoreSelector } from "./useStoreSelector.js";
+import { getHotkeyManager } from "@tanstack/hotkeys";
+
+//#region src/useHotkeyScopesState.ts
+/**
+* Vue composable that returns a ref of 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 Reactive ref of the current scope state
+*
+* @example
+* ```vue
+* <script setup>
+* import { useHotkeyScopesState } from '@tanstack/vue-hotkeys'
+*
+* const scopes = useHotkeyScopesState()
+* <\/script>
+*
+* <template>
+*   <p v-if="scopes.exclusive">Shortcuts belong to {{ scopes.exclusive }}</p>
+* </template>
+* ```
+*/
+function useHotkeyScopesState() {
+	return useStoreSelector(getHotkeyManager().scopes, (state) => state);
+}
+
+//#endregion
+export { useHotkeyScopesState };

package/dist/useKeyHold.d.ts

@@ -4,9 +4,8 @@ import { MaybeRefOrGetter, Ref } from "vue";
 /**
  * Vue composable that returns a reactive ref indicating whether a specific key is currently being held.
  *
- * This composable uses `useSelector` from `@tanstack/vue-store` to subscribe
- * to the global KeyStateTracker and uses a selector to determine if
- * the specified key is held.
+ * Reads the held keys from the global KeyStateTracker. The key may be a ref
+ * or getter; the result follows it without waiting for a key event.
  *
  * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
  * @returns Reactive ref that is true if the key is currently held down

package/dist/useKeyHold.js

@@ -1,14 +1,12 @@
-import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { unref } from "vue";
-import { useSelector } from "@tanstack/vue-store";
+import { useHeldKeys } from "./useHeldKeys.js";
+import { computed, toValue } from "vue";
 
 //#region src/useKeyHold.ts
 /**
 * Vue composable that returns a reactive ref indicating whether a specific key is currently being held.
 *
-* This composable uses `useSelector` from `@tanstack/vue-store` to subscribe
-* to the global KeyStateTracker and uses a selector to determine if
-* the specified key is held.
+* Reads the held keys from the global KeyStateTracker. The key may be a ref
+* or getter; the result follows it without waiting for a key event.
 *
 * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
 * @returns Reactive ref that is true if the key is currently held down
@@ -48,11 +46,10 @@ import { useSelector } from "@tanstack/vue-store";
 * ```
 */
 function useKeyHold(key) {
-	const tracker = getKeyStateTracker();
-	return useSelector(tracker.store, (state) => {
-		const keyValue = unref(key);
-		const normalizedKey = (typeof keyValue === "string" ? keyValue : String(keyValue)).toLowerCase();
-		return state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey);
+	const heldKeys = useHeldKeys();
+	return computed(() => {
+		const target = toValue(key).toLowerCase();
+		return heldKeys.value.some((heldKey) => heldKey.toLowerCase() === target);
 	});
 }
 

package/dist/useStoreSelector.js

@@ -0,0 +1,15 @@
+import { shallowRef } from "vue";
+import { useSelector } from "@tanstack/vue-store";
+
+//#region src/useStoreSelector.ts
+/**
+* `useSelector` that does not subscribe during server rendering. Vue never
+* disposes component scopes on the server, so a subscription to a shared
+* store would never be released. The server gets the current value instead.
+*/
+function useStoreSelector(source, selector) {
+	return typeof document === "undefined" ? shallowRef(selector(source.get())) : useSelector(source, selector);
+}
+
+//#endregion
+export { useStoreSelector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-hotkeys",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Vue adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.17.0",
+    "@tanstack/hotkeys": "0.19.0",
     "@tanstack/vue-store": "^0.11.2"
   },
   "devDependencies": {
@@ -47,7 +47,7 @@
     "vue": "^3.5.43"
   },
   "peerDependencies": {
-    "vue": ">=3.0.0"
+    "vue": ">=3.3.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/skills/vue-hotkeys/SKILL.md

@@ -52,23 +52,24 @@ useHotkey('Escape', () => closePanel(), { target: panel })
 
 ## API
 
-| API                                       | What it's for                                                                                                                          |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `useHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey while the component is mounted; the hotkey and options can be refs or getters.             |
-| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a ref or getter of a list built from data, in one call.                                                   |
-| `<HotkeysProvider>`                       | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for its children, and emit `custom-hotkeys-change`. |
-| `provideHotkeysContext(options)`          | Provide the same options from a component's setup instead of rendering `HotkeysProvider`; they apply to its children.                  |
-| `useHotkeysContext()`                     | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider.                                           |
-| `useDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                             |
-| `useAppHotkeys()`                         | Get a computed ref of the declared app hotkeys with the user's custom hotkeys applied.                                                 |
-| `useAppHotkeyList()`                      | Get a computed ref listing every app hotkey with its status, for a cheat sheet or settings screen.                                     |
-| `useCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                  |
-| `useHotkeyRecorder(options)`              | Record a chord or sequence the user presses; destructure the refs it returns.                                                          |
-| `useHotkeyRegistrations()`                | Get a ref listing every registered hotkey with its options and `meta`.                                                                 |
-| `useHotkeyHint(hotkey, options?)`         | Get a computed ref of whether held modifiers should reveal a shortcut's hint.                                                          |
-| `useKeyHold(key)`                         | Get a ref of whether one key is held.                                                                                                  |
-| `useHeldKeys()`                           | Get a ref of every key that's held right now.                                                                                          |
-| `useHeldKeyCodes()`                       | Get a ref mapping each held key to its physical `event.code`.                                                                          |
+| API                                       | What it's for                                                                                                                                                                                            |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey while the component is mounted; the hotkey and options can be refs or getters.                                                                               |
+| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a ref or getter of a list built from data, in one call.                                                                                                                     |
+| `<HotkeysProvider>`                       | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for its children, and emit `custom-hotkeys-change`.                                                                   |
+| `provideHotkeysContext(options)`          | Provide the same options from a component's setup instead of rendering `HotkeysProvider`; they apply to its children.                                                                                    |
+| `useHotkeysContext()`                     | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider.                                                                                                             |
+| `useDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                               |
+| `useAppHotkeys()`                         | Get a computed ref of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
+| `useAppHotkeyList()`                      | Get a computed ref listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
+| `useCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                                    |
+| `useHotkeyRecorder(options)`              | Record a chord or sequence the user presses; destructure the refs it returns.                                                                                                                            |
+| `useHotkeyRegistrations()`                | Get a ref listing every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope).                                                                          |
+| `useHotkeyScopesState()`                  | Get a ref of the active scopes and the exclusive scope that owns the keyboard.                                                                                                                           |
+| `useHotkeyHint(hotkey, options?)`         | Get a computed ref of 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. |
+| `useKeyHold(key)`                         | Get a ref of whether one key is held.                                                                                                                                                                    |
+| `useHeldKeys()`                           | Get a ref of every key that's held right now.                                                                                                                                                            |
+| `useHeldKeyCodes()`                       | Get a ref mapping each held key to its physical `event.code`.                                                                                                                                            |
 
 The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.