@tanstack/alpine-hotkeys 0.5.0 → 0.7.0

package/dist/createHotkeyHint.js

@@ -1,12 +1,14 @@
 import { read } from "./scope.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/createHotkeyHint.ts
 function createHotkeyHint(scope, hotkey, options = {}) {
+	const manager = getHotkeyManager();
+	const registrations = scope.select(manager.registrations, (state) => state);
 	return scope.select(getKeyStateTracker().store, (state) => {
 		const value = read(hotkey);
 		const resolved = isAppHotkey(value) ? resolveAppHotkey(value, scope.appHotkeys()).hotkey : value;
-		return resolved !== null && matchesHeldModifiers(resolved, state.heldKeys, read(options));
+		return resolved !== null && matchesHeldModifiers(resolved, state.heldKeys, read(options)) && registrations.value.size > 0 && manager.hasActiveRegistration(value);
 	});
 }
 

package/dist/createHotkeyScopesState.js

@@ -0,0 +1,9 @@
+import { getHotkeyManager } from "@tanstack/hotkeys";
+
+//#region src/createHotkeyScopesState.ts
+function createHotkeyScopesState(scope) {
+	return scope.select(getHotkeyManager().scopes, (state) => state);
+}
+
+//#endregion
+export { createHotkeyScopesState };

package/dist/createHotkeysScope.js

@@ -6,6 +6,7 @@ import { createHeldKeyCodes } from "./createHeldKeyCodes.js";
 import { createKeyHold } from "./createKeyHold.js";
 import { createHotkeyHint } from "./createHotkeyHint.js";
 import { createHotkeyRegistrations } from "./createHotkeyRegistrations.js";
+import { createHotkeyScopesState } from "./createHotkeyScopesState.js";
 import { createHotkeyRecorder } from "./createHotkeyRecorder.js";
 import { createAppHotkeyList, createAppHotkeys, createCustomHotkeys } from "./createAppHotkeys.js";
 
@@ -25,6 +26,7 @@ function createHotkeysScope(defaultOptions = {}) {
 		createKeyHold: (...args) => createKeyHold(scope, ...args),
 		createHotkeyHint: (...args) => createHotkeyHint(scope, ...args),
 		createHotkeyRegistrations: (...args) => createHotkeyRegistrations(scope, ...args),
+		createHotkeyScopesState: () => createHotkeyScopesState(scope),
 		createHotkeyRecorder: ((options) => createHotkeyRecorder(scope, options)),
 		createAppHotkeys: () => createAppHotkeys(scope),
 		createAppHotkeyList: () => createAppHotkeyList(scope),

package/dist/hotkeysPlugin.d.ts

@@ -1,5 +1,9 @@
 import Alpine from "alpinejs";
 //#region src/hotkeysPlugin.d.ts
-/** Installs $hotkeys, whose registrations and subscriptions belong to its element. */
+/**
+ * Installs $hotkeys, whose registrations and subscriptions belong to its
+ * element. Every hotkeys scope, including ones from `createHotkeysScope`, uses
+ * the Alpine instance passed here.
+ */
 export declare function hotkeysPlugin(alpine: typeof Alpine): void;
 //#endregion

package/dist/hotkeysPlugin.js

@@ -1,8 +1,14 @@
+import { setAlpine } from "./scope.js";
 import { createHotkeysScope } from "./createHotkeysScope.js";
 
 //#region src/hotkeysPlugin.ts
-/** Installs $hotkeys, whose registrations and subscriptions belong to its element. */
+/**
+* Installs $hotkeys, whose registrations and subscriptions belong to its
+* element. Every hotkeys scope, including ones from `createHotkeysScope`, uses
+* the Alpine instance passed here.
+*/
 function hotkeysPlugin(alpine) {
+	setAlpine(alpine);
 	const scopes = /* @__PURE__ */ new WeakMap();
 	alpine.magic("hotkeys", (element, { cleanup }) => {
 		let scope = scopes.get(element);

package/dist/scope.js

@@ -1,8 +1,17 @@
 import { getHotkeyManager } from "@tanstack/hotkeys";
-import Alpine from "alpinejs";
 import { subscribePublishedAppHotkeys } from "@tanstack/hotkeys/adapter";
 
 //#region src/scope.ts
+let pluginAlpine;
+/** Records the Alpine instance passed to `hotkeysPlugin`. */
+function setAlpine(alpine) {
+	pluginAlpine = alpine;
+}
+function getAlpine() {
+	const alpine = pluginAlpine ?? globalThis.Alpine;
+	if (!alpine) throw new Error("[TanStack Hotkeys] Alpine was not found. Call Alpine.plugin(hotkeysPlugin) before Alpine.start(), or set window.Alpine.");
+	return alpine;
+}
 function read(value) {
 	return typeof value === "function" ? value() : value;
 }
@@ -14,14 +23,15 @@ function createScope(defaultOptions) {
 	}
 	function effect(callback) {
 		assertActive();
-		const runner = Alpine.effect(() => {
+		const alpine = getAlpine();
+		const runner = alpine.effect(() => {
 			if (!destroyed) callback();
 		});
-		cleanups.add(() => Alpine.release(runner));
+		cleanups.add(() => alpine.release(runner));
 	}
 	function select(store, selector) {
 		assertActive();
-		const state = Alpine.reactive({ snapshot: store.state });
+		const state = getAlpine().reactive({ snapshot: store.state });
 		const subscription = store.subscribe(() => {
 			state.snapshot = store.state;
 		});
@@ -37,7 +47,7 @@ function createScope(defaultOptions) {
 	*/
 	function appHotkeys() {
 		if (!appHotkeysState) {
-			const state = Alpine.reactive({ version: 0 });
+			const state = getAlpine().reactive({ version: 0 });
 			appHotkeysState = state;
 			cleanups.add(subscribePublishedAppHotkeys(() => state.version++));
 		}
@@ -64,4 +74,4 @@ function createScope(defaultOptions) {
 }
 
 //#endregion
-export { createScope, read };
+export { createScope, read, setAlpine };

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { AppHotkey, AppHotkeyListItem, CustomHotkeys, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorderOptions, IndividualKey, RegisterableHotkey, RegisteredAppHotkeys, Target } from "@tanstack/hotkeys";
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceRecorderOptions, IndividualKey, RegisterableHotkey, RegisteredAppHotkeys, Target } from "@tanstack/hotkeys";
 import { AdapterAppHotkeyOptions, AdapterCommonOptions, AdapterHotkeyDefinition, AdapterOptionsFor } from "@tanstack/hotkeys/adapter";
 //#region src/types.d.ts
 /** A reactive value. Read `.value` where the framework tracks dependencies. */
@@ -87,6 +87,8 @@ export interface AlpineHotkeys {
   createHotkeyHint: (hotkey: MaybeGetter<RegisterableHotkey | AppHotkey>, options?: MaybeGetter<HeldModifierOptions>) => AlpineHotkeyState<boolean>;
   /** Read live registrations, including disabled entries. */
   createHotkeyRegistrations: () => HotkeyRegistrationsResult;
+  /** Read the active, exclusive, allowed, and suspended scopes through `.value`. */
+  createHotkeyScopesState: () => AlpineHotkeyState<HotkeyScopesState>;
   /** Create a recorder whose options can follow Alpine state. */
   createHotkeyRecorder: AlpineCreateHotkeyRecorder;
   /** Read the effective app hotkeys from `provideAppHotkeys` through `.value`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/alpine-hotkeys",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Alpine adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.17.0",
+    "@tanstack/hotkeys": "0.19.0",
     "@tanstack/store": "^0.11.2"
   },
   "devDependencies": {
@@ -43,7 +43,7 @@
     "alpinejs": "^3.17.4"
   },
   "peerDependencies": {
-    "alpinejs": "^3.15.12"
+    "alpinejs": "^3.13.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/skills/alpine-hotkeys/SKILL.md

@@ -33,7 +33,9 @@ Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack
 
 ```ts no-check
 import Alpine from 'alpinejs'
-import { createHotkeysScope } from '@tanstack/alpine-hotkeys'
+import { createHotkeysScope, hotkeysPlugin } from '@tanstack/alpine-hotkeys'
+
+Alpine.plugin(hotkeysPlugin) // before Alpine.start()
 
 Alpine.data('panel', () => ({
   dirty: false,
@@ -56,33 +58,34 @@ Alpine.data('panel', () => ({
 }))
 ```
 
-For markup-only components, install `Alpine.plugin(hotkeysPlugin)` before `Alpine.start()` and use the `$hotkeys` magic, which is destroyed with its element: `x-init="$hotkeys.createHotkey('Mod+S', () => save())"`.
+Install `Alpine.plugin(hotkeysPlugin)` before `Alpine.start()`. It gives the adapter the app's Alpine instance; without it, the adapter falls back to `window.Alpine` and throws when neither exists. The plugin also adds the `$hotkeys` magic for markup-only components, which is destroyed with its element: `x-init="$hotkeys.createHotkey('Mod+S', () => save())"`.
 
 ## API
 
 | API                                                 | What it's for                                                                                             |
 | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `Alpine.plugin(hotkeysPlugin)`                      | Install the `$hotkeys` magic, an owner that's destroyed with its element.                                 |
+| `Alpine.plugin(hotkeysPlugin)`                      | Give the adapter the app's Alpine, and install the `$hotkeys` magic, an owner destroyed with its element. |
 | `createHotkeysScope(defaults?)`                     | Create an owner for one `Alpine.data` component, with optional default options.                           |
 | `provideAppHotkeys(appHotkeys, options?)`           | Declare app hotkeys and load the user's custom hotkeys once at startup, since Alpine has no provider.     |
 | `getHotkeyManager().activateScope(scope, options?)` | Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off. |
 
 Each owner has these methods. Read their state through `.value`, or `.hotkeys` for registrations.
 
-| Method                                       | What it's for                                                                                      |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `createHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey until the owner is destroyed; options can be a getter. |
-| `createHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a getter of a list built from data, in one call.                      |
-| `createHotkeyRecorder(options)`              | Record a chord or sequence the user presses, for a settings screen.                                |
-| `createAppHotkeys()`                         | Get the declared app hotkeys with the user's custom hotkeys applied.                               |
-| `createAppHotkeyList()`                      | List every app hotkey with its status, for a cheat sheet or settings screen.                       |
-| `createCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.              |
-| `createHotkeyRegistrations()`                | List every registered hotkey with its options and `meta`.                                          |
-| `createHotkeyHint(hotkey, options?)`         | Get whether held modifiers should reveal a shortcut's hint.                                        |
-| `createKeyHold(key)`                         | Get whether one key is held.                                                                       |
-| `createHeldKeys()`                           | Get every key that's held right now.                                                               |
-| `createHeldKeyCodes()`                       | Map each held key to its physical `event.code`.                                                    |
-| `destroy()`                                  | Release every hotkey, subscription, and recorder the owner created.                                |
+| Method                                       | What it's for                                                                                                                                                                          |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey until the owner is destroyed; options can be a getter.                                                                                     |
+| `createHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a getter of a list built from data, in one call.                                                                                                          |
+| `createHotkeyRecorder(options)`              | Record a chord or sequence the user presses, for a settings screen.                                                                                                                    |
+| `createAppHotkeys()`                         | Get the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
+| `createAppHotkeyList()`                      | List every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                           |
+| `createCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                  |
+| `createHotkeyRegistrations()`                | List every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope).                                                                     |
+| `createHotkeyScopesState()`                  | Get the active scopes and the exclusive scope that owns the keyboard.                                                                                                                  |
+| `createHotkeyHint(hotkey, options?)`         | Get 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. |
+| `createKeyHold(key)`                         | Get whether one key is held.                                                                                                                                                           |
+| `createHeldKeys()`                           | Get every key that's held right now.                                                                                                                                                   |
+| `createHeldKeyCodes()`                       | Map each held key to its physical `event.code`.                                                                                                                                        |
+| `destroy()`                                  | Release every hotkey, subscription, and recorder the owner created.                                                                                                                    |
 
 The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.