@tanstack/vue-hotkeys 0.16.0 → 0.17.0

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/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 { 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 manager = getHotkeyManager();
+	const registrations = useSelector(manager.registrations, (state) => state);
 	const held = useSelector(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/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 { getHotkeyManager } from "@tanstack/hotkeys";
+import { useSelector } from "@tanstack/vue-store";
+
+//#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 useSelector(getHotkeyManager().scopes, (state) => state);
+}
+
+//#endregion
+export { useHotkeyScopesState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-hotkeys",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "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.18.0",
     "@tanstack/vue-store": "^0.11.2"
   },
   "devDependencies": {

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`.