@tanstack/angular-hotkeys 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -6,7 +6,8 @@ import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
 import { injectKeyHold } from "./injectKeyHold.js";
 import { AngularHotkeyRecorder, injectHotkeyRecorder } from "./injectHotkeyRecorder.js";
 import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
+import { injectHotkeyScopesState } from "./injectHotkeyScopesState.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
 import { InjectCustomHotkeysResult, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { AngularHotkeyRecorder, HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, InjectAppHotkeyOptions, InjectCustomHotkeysResult, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, MaybeGetter, ProvideHotkeysOptions, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { AngularHotkeyRecorder, HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, InjectAppHotkeyOptions, InjectCustomHotkeysResult, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, MaybeGetter, ProvideHotkeysOptions, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/index.js

@@ -6,9 +6,10 @@ import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
 import { injectKeyHold } from "./injectKeyHold.js";
 import { injectHotkeyRecorder } from "./injectHotkeyRecorder.js";
 import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
+import { injectHotkeyScopesState } from "./injectHotkeyScopesState.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
 import { injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/injectHotkeyHint.d.ts

@@ -3,10 +3,11 @@ import { Signal } from "@angular/core";
 //#region src/injectHotkeyHint.d.ts
 /**
  * Returns a signal 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.
+ * 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 injectHotkeyHint(hotkey: RegisterableHotkey | AppHotkey | (() => RegisterableHotkey | AppHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions)): Signal<boolean>;
 //#endregion

package/dist/injectHotkeyHint.js

@@ -1,24 +1,27 @@
 import { injectHotkeysContext } from "./hotkeys-provider.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { computed } from "@angular/core";
 import { injectSelector } from "@tanstack/angular-store";
 
 //#region src/injectHotkeyHint.ts
 /**
 * Returns a signal 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.
+* 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.
 */
 function injectHotkeyHint(hotkey, options = {}) {
 	const context = injectHotkeysContext();
+	const manager = getHotkeyManager();
+	const registrations = injectSelector(manager.registrations, (state) => state);
 	const held = injectSelector(getKeyStateTracker().store, (state) => state.heldKeys);
 	return computed(() => {
 		context.appHotkeysState();
 		const value = typeof hotkey === "function" ? hotkey() : hotkey;
 		const resolved = isAppHotkey(value) ? resolveAppHotkey(value, context.appHotkeysStore).hotkey : value;
-		return resolved !== null && matchesHeldModifiers(resolved, held(), typeof options === "function" ? options() : options);
+		return resolved !== null && matchesHeldModifiers(resolved, held(), typeof options === "function" ? options() : options) && registrations().size > 0 && manager.hasActiveRegistration(value);
 	});
 }
 

package/dist/injectHotkeyScopesState.d.ts

@@ -0,0 +1,27 @@
+import { HotkeyScopesState } from "@tanstack/hotkeys";
+import { Signal } from "@angular/core";
+//#region src/injectHotkeyScopesState.d.ts
+/**
+ * Angular inject-based API that returns a signal 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 Signal of the current scope state
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     @if (scopes().exclusive; as exclusive) {
+ *       <p>Shortcuts belong to {{ exclusive }}</p>
+ *     }
+ *   `,
+ * })
+ * export class KeyboardOwnerComponent {
+ *   scopes = injectHotkeyScopesState()
+ * }
+ * ```
+ */
+export declare function injectHotkeyScopesState(): Signal<HotkeyScopesState>;
+//#endregion

package/dist/injectHotkeyScopesState.js

@@ -0,0 +1,32 @@
+import { getHotkeyManager } from "@tanstack/hotkeys";
+import { injectSelector } from "@tanstack/angular-store";
+
+//#region src/injectHotkeyScopesState.ts
+/**
+* Angular inject-based API that returns a signal 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 Signal of the current scope state
+*
+* @example
+* ```ts
+* @Component({
+*   template: `
+*     @if (scopes().exclusive; as exclusive) {
+*       <p>Shortcuts belong to {{ exclusive }}</p>
+*     }
+*   `,
+* })
+* export class KeyboardOwnerComponent {
+*   scopes = injectHotkeyScopesState()
+* }
+* ```
+*/
+function injectHotkeyScopesState() {
+	return injectSelector(getHotkeyManager().scopes, (state) => state);
+}
+
+//#endregion
+export { injectHotkeyScopesState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-hotkeys",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Angular adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -38,7 +38,7 @@
   ],
   "dependencies": {
     "@tanstack/angular-store": "^0.11.2",
-    "@tanstack/hotkeys": "0.17.0"
+    "@tanstack/hotkeys": "0.18.0"
   },
   "peerDependencies": {
     "@angular/common": ">=19.0.0",

package/skills/angular-hotkeys/SKILL.md

@@ -64,22 +64,23 @@ export class PanelComponent {
 
 ## API
 
-| API                                          | What it's for                                                                                                                        |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `injectHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey for the component's or service's lifetime; options can be a function that reads signals. |
-| `injectHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a function returning a list built from data, in one call.                                               |
-| `provideHotkeys(options)`                    | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys in the app config or a component's `providers`.   |
-| `injectHotkeysContext()`                     | Read the nearest provided defaults and enabled state, or `null` without a provider.                                                  |
-| `injectDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                           |
-| `injectAppHotkeys()`                         | Get a signal of the declared app hotkeys with the user's custom hotkeys applied.                                                     |
-| `injectAppHotkeyList()`                      | Get a signal listing every app hotkey with its status, for a cheat sheet or settings screen.                                         |
-| `injectCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                |
-| `injectHotkeyRecorder(options)`              | Record a chord or sequence the user presses, for a settings screen.                                                                  |
-| `injectHotkeyRegistrations()`                | Get a signal listing every registered hotkey with its options and `meta`.                                                            |
-| `injectHotkeyHint(hotkey, options?)`         | Get a signal of whether held modifiers should reveal a shortcut's hint.                                                              |
-| `injectKeyHold(key)`                         | Get a signal of whether one key is held.                                                                                             |
-| `injectHeldKeys()`                           | Get a signal of every key that's held right now.                                                                                     |
-| `injectHeldKeyCodes()`                       | Get a signal mapping each held key to its physical `event.code`.                                                                     |
+| API                                          | What it's for                                                                                                                                                                                      |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `injectHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey for the component's or service's lifetime; options can be a function that reads signals.                                                               |
+| `injectHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a function returning a list built from data, in one call.                                                                                                             |
+| `provideHotkeys(options)`                    | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys in the app config or a component's `providers`.                                                                 |
+| `injectHotkeysContext()`                     | Read the nearest provided defaults and enabled state, or `null` without a provider.                                                                                                                |
+| `injectDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                         |
+| `injectAppHotkeys()`                         | Get a signal of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
+| `injectAppHotkeyList()`                      | Get a signal listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
+| `injectCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                              |
+| `injectHotkeyRecorder(options)`              | Record a chord or sequence the user presses, for a settings screen.                                                                                                                                |
+| `injectHotkeyRegistrations()`                | Get a signal listing every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope).                                                                 |
+| `injectHotkeyScopesState()`                  | Get a signal of the active scopes and the exclusive scope that owns the keyboard.                                                                                                                  |
+| `injectHotkeyHint(hotkey, options?)`         | Get a signal 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. |
+| `injectKeyHold(key)`                         | Get a signal of whether one key is held.                                                                                                                                                           |
+| `injectHeldKeys()`                           | Get a signal of every key that's held right now.                                                                                                                                                   |
+| `injectHeldKeyCodes()`                       | Get a signal mapping each held key to its physical `event.code`.                                                                                                                                   |
 
 The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.