@tanstack/alpine-hotkeys 0.9.0 → 0.10.0

package/dist/createHotkeyRecorder.d.ts

@@ -0,0 +1,15 @@
+import { AlpineHotkeyRecorder, AlpineHotkeys } from "./types.js";
+import "./scope.js";
+import { HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+//#region src/createHotkeyRecorder.d.ts
+/**
+ * Creates a recorder owned by a `createHotkeysScope` owner. It uses the
+ * owner's `hotkeyRecorder` defaults, and options can follow Alpine state.
+ * `maxSteps` (default 1) selects chords or sequences.
+ */
+export declare function createHotkeyRecorder(owner: AlpineHotkeys, options: HotkeyChordRecorderOptions): AlpineHotkeyRecorder<HotkeyChord>;
+export declare function createHotkeyRecorder(owner: AlpineHotkeys, options: HotkeySequenceRecorderOptions): AlpineHotkeyRecorder;
+export declare function createHotkeyRecorder(owner: AlpineHotkeys, options: () => HotkeySequenceRecorderOptions): AlpineHotkeyRecorder;
+export declare function createHotkeyRecorder(owner: AlpineHotkeys, options: () => HotkeyChordRecorderOptions): AlpineHotkeyRecorder<HotkeyChord>;
+export declare function createHotkeyRecorder(owner: AlpineHotkeys, options: () => HotkeyRecorderOptions): AlpineHotkeyRecorder;
+//#endregion

package/dist/createHotkeyRecorder.js

@@ -1,9 +1,12 @@
-import { read } from "./scope.js";
+import { read, scopeOf } from "./scope.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/createHotkeyRecorder.ts
-function createHotkeyRecorder(scope, options) {
+function createHotkeyRecorder(owner, options) {
+	return createRecorder(scopeOf(owner), options);
+}
+function createRecorder(scope, options) {
 	scope.assertActive();
 	const instance = new HotkeyRecorder(() => withDefaults(scope.defaultOptions().hotkeyRecorder, read(options)));
 	const state = scope.select(instance.store, (value) => value);
@@ -28,4 +31,4 @@ function createHotkeyRecorder(scope, options) {
 }
 
 //#endregion
-export { createHotkeyRecorder };
+export { createHotkeyRecorder, createRecorder };

package/dist/createHotkeys.js

@@ -6,12 +6,17 @@ function createHotkeys(scope, definitions, options = {}) {
 	scope.assertActive();
 	const bindings = createHotkeyBindings();
 	scope.addCleanup(bindings.destroy);
-	scope.effect(() => bindings.update(prepareHotkeyDefinitions(read(definitions), {
-		appHotkeysStore: scope.appHotkeys(),
-		defaults: scope.defaultOptions().hotkey,
-		commonOptions: read(options),
-		resolveTarget: (target) => target
-	})));
+	try {
+		scope.effect(() => bindings.update(prepareHotkeyDefinitions(read(definitions), {
+			appHotkeysStore: scope.appHotkeys(),
+			defaults: scope.defaultOptions().hotkey,
+			commonOptions: read(options),
+			resolveTarget: (target) => target
+		})));
+	} catch (error) {
+		bindings.destroy();
+		throw error;
+	}
 }
 
 //#endregion

package/dist/createHotkeysScope.js

@@ -1,4 +1,4 @@
-import { createScope } from "./scope.js";
+import { createScope, ownerScopes } from "./scope.js";
 import { createHotkeys } from "./createHotkeys.js";
 import { createHotkey } from "./createHotkey.js";
 import { createHeldKeys } from "./createHeldKeys.js";
@@ -7,7 +7,6 @@ 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";
 
 //#region src/createHotkeysScope.ts
@@ -18,7 +17,7 @@ import { createAppHotkeyList, createAppHotkeys, createCustomHotkeys } from "./cr
 */
 function createHotkeysScope(defaultOptions = {}) {
 	const scope = createScope(defaultOptions);
-	return {
+	const owner = {
 		createHotkey: (...args) => createHotkey(scope, ...args),
 		createHotkeys: (...args) => createHotkeys(scope, ...args),
 		createHeldKeys: (...args) => createHeldKeys(scope, ...args),
@@ -27,12 +26,13 @@ function createHotkeysScope(defaultOptions = {}) {
 		createHotkeyHint: (...args) => createHotkeyHint(scope, ...args),
 		createHotkeyRegistrations: (...args) => createHotkeyRegistrations(scope, ...args),
 		createHotkeyScopesState: () => createHotkeyScopesState(scope),
-		createHotkeyRecorder: ((options) => createHotkeyRecorder(scope, options)),
 		createAppHotkeys: () => createAppHotkeys(scope),
 		createAppHotkeyList: () => createAppHotkeyList(scope),
 		createCustomHotkeys: () => createCustomHotkeys(scope),
 		destroy: scope.destroy
 	};
+	ownerScopes.set(owner, scope);
+	return owner;
 }
 
 //#endregion

package/dist/hotkeyRecorderPlugin.d.ts

@@ -0,0 +1,9 @@
+import Alpine from "alpinejs";
+//#region src/hotkeyRecorderPlugin.d.ts
+/**
+ * Installs $hotkeyRecorder, a function that creates recorders owned by its
+ * element. It is separate from `hotkeysPlugin`, so apps that don't record
+ * hotkeys don't ship the recorder.
+ */
+export declare function hotkeyRecorderPlugin(alpine: typeof Alpine): void;
+//#endregion

package/dist/hotkeyRecorderPlugin.js

@@ -0,0 +1,29 @@
+import { createScope, setAlpine } from "./scope.js";
+import { createRecorder } from "./createHotkeyRecorder.js";
+
+//#region src/hotkeyRecorderPlugin.ts
+/**
+* Installs $hotkeyRecorder, a function that creates recorders owned by its
+* element. It is separate from `hotkeysPlugin`, so apps that don't record
+* hotkeys don't ship the recorder.
+*/
+function hotkeyRecorderPlugin(alpine) {
+	setAlpine(alpine);
+	const owners = /* @__PURE__ */ new WeakMap();
+	alpine.magic("hotkeyRecorder", (element, { cleanup }) => {
+		let create = owners.get(element);
+		if (!create) {
+			const scope = createScope({});
+			create = ((options) => createRecorder(scope, options));
+			owners.set(element, create);
+			cleanup(() => {
+				scope.destroy();
+				owners.delete(element);
+			});
+		}
+		return create;
+	});
+}
+
+//#endregion
+export { hotkeyRecorderPlugin };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { AlpineAppHotkeyOptions, AlpineCreateHotkey, AlpineCreateHotkeyRecorder, AlpineCustomHotkeys, AlpineHotkeyCommonOptions, AlpineHotkeyDefinition, AlpineHotkeyOptionsFor, AlpineHotkeyRecorder, AlpineHotkeyState, AlpineHotkeyTarget, AlpineHotkeys, DefaultHotkeysOptions, HotkeyRegistrationsResult, MaybeGetter } from "./types.js";
 import { createHotkeysScope } from "./createHotkeysScope.js";
 import { hotkeysPlugin } from "./hotkeysPlugin.js";
+import { createHotkeyRecorder } from "./createHotkeyRecorder.js";
+import { hotkeyRecorderPlugin } from "./hotkeyRecorderPlugin.js";
 export * from "@tanstack/hotkeys";
-export { AlpineAppHotkeyOptions, AlpineCreateHotkey, AlpineCreateHotkeyRecorder, AlpineCustomHotkeys, AlpineHotkeyCommonOptions, AlpineHotkeyDefinition, AlpineHotkeyOptionsFor, AlpineHotkeyRecorder, AlpineHotkeyState, AlpineHotkeyTarget, AlpineHotkeys, DefaultHotkeysOptions, HotkeyRegistrationsResult, MaybeGetter, createHotkeysScope, hotkeysPlugin };
+export { AlpineAppHotkeyOptions, AlpineCreateHotkey, AlpineCreateHotkeyRecorder, AlpineCustomHotkeys, AlpineHotkeyCommonOptions, AlpineHotkeyDefinition, AlpineHotkeyOptionsFor, AlpineHotkeyRecorder, AlpineHotkeyState, AlpineHotkeyTarget, AlpineHotkeys, DefaultHotkeysOptions, HotkeyRegistrationsResult, MaybeGetter, createHotkeyRecorder, createHotkeysScope, hotkeyRecorderPlugin, hotkeysPlugin };

package/dist/index.js

@@ -1,6 +1,8 @@
 import { createHotkeysScope } from "./createHotkeysScope.js";
 import { hotkeysPlugin } from "./hotkeysPlugin.js";
+import { createHotkeyRecorder } from "./createHotkeyRecorder.js";
+import { hotkeyRecorderPlugin } from "./hotkeyRecorderPlugin.js";
 
 export * from "@tanstack/hotkeys"
 
-export { createHotkeysScope, hotkeysPlugin };
+export { createHotkeyRecorder, createHotkeysScope, hotkeyRecorderPlugin, hotkeysPlugin };

package/dist/scope.d.ts

@@ -0,0 +1,4 @@
+import "./types.js";
+import "@tanstack/hotkeys";
+import "@tanstack/hotkeys/adapter";
+import Alpine from "alpinejs";

package/dist/scope.js

@@ -12,6 +12,15 @@ function getAlpine() {
 	if (!alpine) throw new Error("[TanStack Hotkeys] Alpine was not found. Call Alpine.plugin(hotkeysPlugin) before Alpine.start(), or set window.Alpine.");
 	return alpine;
 }
+/** The internal scope behind each `createHotkeysScope` owner. */
+const ownerScopes = /* @__PURE__ */ new WeakMap();
+/**
+* Returns an owner's scope. Alpine data wraps stored objects in reactive
+* proxies, so `this.hotkeys` can be a proxy of the owner.
+*/
+function scopeOf(owner) {
+	return ownerScopes.get(getAlpine().raw(owner));
+}
 function read(value) {
 	return typeof value === "function" ? value() : value;
 }
@@ -24,9 +33,22 @@ function createScope(defaultOptions) {
 	function effect(callback) {
 		assertActive();
 		const alpine = getAlpine();
+		let error;
+		let first = true;
 		const runner = alpine.effect(() => {
-			if (!destroyed) callback();
+			if (destroyed) return;
+			try {
+				callback();
+			} catch (e) {
+				if (first) error = e;
+				else reportError(e);
+			}
 		});
+		first = false;
+		if (error) {
+			alpine.release(runner);
+			throw error;
+		}
 		cleanups.add(() => alpine.release(runner));
 	}
 	function select(store, selector) {
@@ -74,4 +96,4 @@ function createScope(defaultOptions) {
 }
 
 //#endregion
-export { createScope, read, setAlpine };
+export { createScope, ownerScopes, read, scopeOf, setAlpine };

package/dist/types.d.ts

@@ -60,7 +60,7 @@ export interface AlpineCreateHotkey {
   <T extends AppHotkey>(hotkey: MaybeGetter<T | null | undefined>, callback: HotkeyCallback, options?: MaybeGetter<AlpineAppHotkeyOptions<T>>): void;
   <const T extends RegisterableHotkey>(hotkey: MaybeGetter<T | null | undefined>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeGetter<AlpineHotkeyOptionsFor<T>>): void;
 }
-/** Creates a recorder; `maxSteps` (default 1) selects chords or sequences. */
+/** `$hotkeyRecorder`: creates a recorder; `maxSteps` (default 1) selects chords or sequences. */
 export interface AlpineCreateHotkeyRecorder {
   (options: HotkeyChordRecorderOptions): AlpineHotkeyRecorder<HotkeyChord>;
   (options: HotkeySequenceRecorderOptions): AlpineHotkeyRecorder;
@@ -68,7 +68,7 @@ export interface AlpineCreateHotkeyRecorder {
   (options: () => HotkeyChordRecorderOptions): AlpineHotkeyRecorder<HotkeyChord>;
   (options: () => HotkeyRecorderOptions): AlpineHotkeyRecorder;
 }
-/** Registrations, recorders, and reactive state owned by one Alpine component. */
+/** Registrations and reactive state owned by one Alpine component. */
 export interface AlpineHotkeys {
   /**
    * Register one hotkey: a chord such as `'Mod+S'`, a sequence such as
@@ -93,8 +93,6 @@ export interface AlpineHotkeys {
   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`. */
   createAppHotkeys: () => AlpineHotkeyState<RegisteredAppHotkeys>;
   /** Read every app hotkey with its live status through `.value`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/alpine-hotkeys",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Alpine adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.21.0"
+    "@tanstack/hotkeys": "0.22.1"
   },
   "devDependencies": {
     "@types/alpinejs": "^3.17.0",

package/skills/alpine-hotkeys/SKILL.md

@@ -18,6 +18,8 @@ metadata:
 sources:
   - src/createHotkeysScope.ts
   - src/hotkeysPlugin.ts
+  - src/createHotkeyRecorder.ts
+  - src/hotkeyRecorderPlugin.ts
   - src/scope.ts
   - src/createHotkey.ts
   - src/createAppHotkeys.ts
@@ -62,12 +64,14 @@ Install `Alpine.plugin(hotkeysPlugin)` before `Alpine.start()`. It gives the ada
 
 ## API
 
-| API                                                 | What it's for                                                                                             |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `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. |
+| API                                                 | What it's for                                                                                                                         |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                       |
+| `createHotkeyRecorder(owner, options)`              | Record a chord or sequence the user presses, for a settings screen. The owner destroys it and supplies its `hotkeyRecorder` defaults. |
+| `Alpine.plugin(hotkeyRecorderPlugin)`               | Install the `$hotkeyRecorder(options)` magic, which creates recorders destroyed with their element.                                   |
+| `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.
 
@@ -75,7 +79,6 @@ Each owner has these methods. Read their state through `.value`, or `.hotkeys` f
 | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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.                                                                                                  |
@@ -95,6 +98,8 @@ The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `ma
 - **`createHotkeysScope` isn't a hotkey scope.** It only owns registrations and sets defaults. For a dialog, activate a real scope in `init()` with `release = getHotkeyManager().activateScope(name, { exclusive: true })`, pass `{ scope: name }` to the dialog's hotkeys, and call `release()` in `destroy()`. Give each open dialog its own name.
 - **Pass options as a getter.** `{ enabled: this.dirty }` is read once. Use `() => ({ enabled: this.dirty })`.
 - **Use either `$hotkeys` or your own owner for a hotkey, not both.** Otherwise it registers twice.
+- **Call `create*` in `x-init` or `init()`, and read `.value` anywhere.** Calling `create*` inside a reactive expression such as `x-text="$hotkeys.createHeldKeys().value"` creates a new subscription on every evaluation.
+- **Owners have no `createHotkeyRecorder` method** since v0.10.0. Call `createHotkeyRecorder(this.hotkeys, options)`, so apps that don't record don't ship the recorder.
 - With server rendering, load the adapter only in the browser.
 
 When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Alpine](references/app-hotkeys.md).

package/skills/alpine-hotkeys/references/app-hotkeys.md

@@ -32,18 +32,22 @@ provideAppHotkeys(appHotkeys, {
 
 The app hotkey methods throw until `provideAppHotkeys` has run. When saved shortcuts come from a server, await them first. Register inside a getter so registrations follow rebinding: `this.hotkeys.createHotkey(() => appHotkeys.value['doc.save'], save)`, with `const appHotkeys = this.hotkeys.createAppHotkeys()`. Build a cheat sheet from `createAppHotkeyList().value`.
 
-A settings row records with the owner's `createHotkeyRecorder`:
+A settings row records with `createHotkeyRecorder` on its owner:
 
 ```ts
 import Alpine from 'alpinejs'
-import { createHotkeysScope, formatForDisplay } from '@tanstack/alpine-hotkeys'
+import {
+  createHotkeyRecorder,
+  createHotkeysScope,
+  formatForDisplay,
+} from '@tanstack/alpine-hotkeys'
 import type { AppHotkeyId } from '@tanstack/alpine-hotkeys'
 
 Alpine.data('shortcutRow', (id: AppHotkeyId) => {
   const hotkeys = createHotkeysScope()
   const appHotkeys = hotkeys.createAppHotkeys()
   const custom = hotkeys.createCustomHotkeys()
-  const recorder = hotkeys.createHotkeyRecorder({
+  const recorder = createHotkeyRecorder(hotkeys, {
     maxSteps: Infinity,
     validate: (hotkey) => {
       const [conflict] = custom.findConflicts(id, hotkey)