@tanstack/alpine-hotkeys 0.6.0 → 0.7.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/alpine-hotkeys",
-  "version": "0.6.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.18.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,13 +58,13 @@ 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. |