@tanstack/preact-hotkeys 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -3,10 +3,11 @@ import { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefau
 import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.js";
 import { PreactHotkeyRecorder, 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";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -3,6 +3,7 @@ import { useHotkeys } from "./useHotkeys.js";
 import { useHotkey } from "./useHotkey.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";
 import { useHeldKeys } from "./useHeldKeys.js";
@@ -11,4 +12,4 @@ import { useKeyHold } from "./useKeyHold.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useHotkeyHint.d.ts

@@ -2,12 +2,12 @@ import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/ho
 //#region src/useHotkeyHint.d.ts
 /**
  * Returns a boolean indicating whether held modifiers reveal this shortcut.
- * Only visibility changes from held-key updates cause a rerender.
- * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
- * every modifier. A sequence reveals its hint from its first step, and an app
- * hotkey uses its effective hotkey (false while unbound). 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.
+ * The hint shows only while the hotkey can fire: some registration of it is
+ * enabled and in an active scope. An app hotkey matches its registrations by
+ * id and uses its effective hotkey (false while unbound).
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact`
+ * requires every modifier. A sequence reveals its hint from its first step.
+ * Only visibility changes cause a rerender. This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
  */
 export declare function useHotkeyHint(hotkey: RegisterableHotkey | AppHotkey, options?: HeldModifierOptions): boolean;
 //#endregion

package/dist/useHotkeyHint.js

@@ -1,21 +1,24 @@
 import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHotkeyHint.ts
 /**
 * Returns a boolean indicating whether held modifiers reveal this shortcut.
-* Only visibility changes from held-key updates cause a rerender.
-* Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
-* every modifier. A sequence reveals its hint from its first step, and an app
-* hotkey uses its effective hotkey (false while unbound). 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.
+* The hint shows only while the hotkey can fire: some registration of it is
+* enabled and in an active scope. An app hotkey matches its registrations by
+* id and uses its effective hotkey (false while unbound).
+* Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact`
+* requires every modifier. A sequence reveals its hint from its first step.
+* Only visibility changes cause a rerender. This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
 */
 function useHotkeyHint(hotkey, options = {}) {
 	const store = useAppHotkeysStoreState();
 	const resolved = isAppHotkey(hotkey) ? resolveAppHotkey(hotkey, store).hotkey : hotkey;
-	return useSelector(getKeyStateTracker().store, (state) => resolved !== null && matchesHeldModifiers(resolved, state.heldKeys, options));
+	const manager = getHotkeyManager();
+	const active = useSelector(manager.registrations, () => resolved !== null && manager.hasActiveRegistration(hotkey));
+	const held = useSelector(getKeyStateTracker().store, (state) => resolved !== null && matchesHeldModifiers(resolved, state.heldKeys, options));
+	return active && held;
 }
 
 //#endregion

package/dist/useHotkeyScopesState.d.ts

@@ -0,0 +1,20 @@
+import { HotkeyScopesState } from "@tanstack/hotkeys";
+//#region src/useHotkeyScopesState.d.ts
+/**
+ * Preact hook that returns the hotkey manager's scope state: the active
+ * scopes, the exclusive scope that owns the keyboard, and the scopes it
+ * allows or suspends. Re-renders when scopes activate or release.
+ *
+ * @returns The current scope state
+ *
+ * @example
+ * ```tsx
+ * function KeyboardOwner() {
+ *   const { exclusive } = useHotkeyScopesState()
+ *
+ *   return exclusive ? <p>Shortcuts belong to {exclusive}</p> : null
+ * }
+ * ```
+ */
+export declare function useHotkeyScopesState(): HotkeyScopesState;
+//#endregion

package/dist/useHotkeyScopesState.js

@@ -0,0 +1,26 @@
+import { getHotkeyManager } from "@tanstack/hotkeys";
+import { useSelector } from "@tanstack/preact-store";
+
+//#region src/useHotkeyScopesState.ts
+/**
+* Preact hook that returns the hotkey manager's scope state: the active
+* scopes, the exclusive scope that owns the keyboard, and the scopes it
+* allows or suspends. Re-renders when scopes activate or release.
+*
+* @returns The current scope state
+*
+* @example
+* ```tsx
+* function KeyboardOwner() {
+*   const { exclusive } = useHotkeyScopesState()
+*
+*   return exclusive ? <p>Shortcuts belong to {exclusive}</p> : null
+* }
+* ```
+*/
+function useHotkeyScopesState() {
+	return useSelector(getHotkeyManager().scopes, (state) => state);
+}
+
+//#endregion
+export { useHotkeyScopesState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-hotkeys",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Preact adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.17.0",
+    "@tanstack/hotkeys": "0.18.0",
     "@tanstack/preact-store": "^0.13.5"
   },
   "devDependencies": {

package/skills/preact-hotkeys/SKILL.md

@@ -45,22 +45,23 @@ export function SaveButton({ onSave }: { onSave: () => void }) {
 
 ## API
 
-| API                                       | What it's for                                                                                                                |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `useHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey while the component is mounted.                                                  |
-| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a list built from data, in one call.                                                            |
-| `<HotkeysProvider>`                       | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it.             |
-| `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 the declared app hotkeys with the user's custom hotkeys applied, to pass to the register API.                            |
-| `useAppHotkeyList()`                      | List every app hotkey with its status, including ones whose components aren't mounted, 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, for a settings screen.                                                          |
-| `useHotkeyRegistrations()`                | List every registered hotkey with its options and `meta`, for a cheat sheet of what's mounted.                               |
-| `useHotkeyHint(hotkey, options?)`         | Get whether held modifiers should reveal a shortcut's hint, such as labels that appear while Mod is held.                    |
-| `useKeyHold(key)`                         | Get whether one key is held, such as Shift for a range-select mode.                                                          |
-| `useHeldKeys()`                           | Get every key that's held right now.                                                                                         |
-| `useHeldKeyCodes()`                       | Map 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.                                                                                                                                                          |
+| `useHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a list built from data, in one call.                                                                                                                                                                    |
+| `<HotkeysProvider>`                       | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it.                                                                                                                     |
+| `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 the declared app hotkeys with the user's custom hotkeys applied, to pass to the register API.                                                                                                                                    |
+| `useAppHotkeyList()`                      | List every app hotkey with its status, including ones whose components aren't mounted, 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, for a settings screen.                                                                                                                                                                  |
+| `useHotkeyRegistrations()`                | List every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope), for a cheat sheet of what's mounted.                                                                              |
+| `useHotkeyScopesState()`                  | Get the active scopes and the exclusive scope that owns the keyboard.                                                                                                                                                                |
+| `useHotkeyHint(hotkey, options?)`         | Get whether held modifiers should reveal a shortcut's hint, such as labels that appear while Mod is held. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |
+| `useKeyHold(key)`                         | Get whether one key is held, such as Shift for a range-select mode.                                                                                                                                                                  |
+| `useHeldKeys()`                           | Get every key that's held right now.                                                                                                                                                                                                 |
+| `useHeldKeyCodes()`                       | Map each held key to its physical `event.code`.                                                                                                                                                                                      |
 
 The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.