@tanstack/alpine-hotkeys 0.4.1 → 0.6.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/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.4.1",
+  "version": "0.6.0",
   "description": "Alpine adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -17,7 +17,8 @@
   "keywords": [
     "alpine",
     "tanstack",
-    "hotkeys"
+    "hotkeys",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -30,10 +31,11 @@
     "node": ">=20"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.16.1",
+    "@tanstack/hotkeys": "0.18.0",
     "@tanstack/store": "^0.11.2"
   },
   "devDependencies": {

package/skills/alpine-hotkeys/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: alpine-hotkeys
+description: >-
+  Use when adding or fixing keyboard shortcuts in an Alpine.js app with
+  @tanstack/alpine-hotkeys: createHotkeysScope owners, the $hotkeys magic and
+  hotkeysPlugin, getter options, element targets with $refs, scopes activated
+  from the hotkey manager, app hotkeys, recorders, and held keys, or replacing
+  @keydown.window handlers.
+metadata:
+  purpose: >-
+    Alpine bindings for TanStack Hotkeys: per-component owners, the $hotkeys
+    magic, getter options, manager-activated scopes, and the Alpine-specific
+    mistakes to avoid.
+  type: framework
+  framework: alpine
+  library: '@tanstack/alpine-hotkeys'
+  library_version: '0.4.0'
+sources:
+  - src/createHotkeysScope.ts
+  - src/hotkeysPlugin.ts
+  - src/scope.ts
+  - src/createHotkey.ts
+  - src/createAppHotkeys.ts
+  - TanStack/hotkeys:docs/framework/alpine/quick-start.md
+  - TanStack/hotkeys:docs/framework/alpine/guides/app-hotkeys.md
+requires:
+  - '@tanstack/hotkeys#hotkeys-core'
+---
+
+# TanStack Hotkeys in Alpine
+
+Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).
+
+```ts no-check
+import Alpine from 'alpinejs'
+import { createHotkeysScope } from '@tanstack/alpine-hotkeys'
+
+Alpine.data('panel', () => ({
+  dirty: false,
+  hotkeys: createHotkeysScope(),
+  init() {
+    this.hotkeys.createHotkey(
+      'Mod+S',
+      () => save(),
+      () => ({ enabled: this.dirty }),
+    )
+    this.hotkeys.createHotkey(
+      'Escape',
+      () => closePanel(),
+      () => ({ target: this.$refs.panel }),
+    )
+  },
+  destroy() {
+    this.hotkeys.destroy()
+  },
+}))
+```
+
+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())"`.
+
+## API
+
+| API                                                 | What it's for                                                                                             |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `Alpine.plugin(hotkeysPlugin)`                      | Install the `$hotkeys` magic, an owner that's 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, `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`.
+
+## Pitfalls
+
+- **Destroy each owner.** Owners aren't tied to Alpine's lifecycle, so without `this.hotkeys.destroy()` in `destroy()`, a removed component's hotkeys keep firing. Create one owner per component instance, inside the `Alpine.data` factory.
+- **`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.
+- 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).
+
+## API discovery and docs
+
+Signatures: `node_modules/@tanstack/alpine-hotkeys/dist/types.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/alpine/guides/<page>.md`, such as `hotkeys` or `app-hotkeys`.

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

@@ -0,0 +1,74 @@
+# App hotkeys in Alpine
+
+The `@tanstack/hotkeys#app-hotkeys` skill owns the rules. This is the Alpine wiring.
+
+```ts
+// app-hotkeys.ts
+import { defineAppHotkeys } from '@tanstack/alpine-hotkeys'
+
+export const appHotkeys = defineAppHotkeys({
+  'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' } },
+  'help.shortcuts': { hotkey: 'Mod+/', meta: { name: 'Keyboard shortcuts' } },
+})
+
+declare module '@tanstack/alpine-hotkeys' {
+  interface Register {
+    appHotkeys: typeof appHotkeys
+  }
+}
+```
+
+```ts
+// main.ts, before Alpine.start()
+import { provideAppHotkeys } from '@tanstack/alpine-hotkeys'
+import { appHotkeys } from './app-hotkeys'
+
+provideAppHotkeys(appHotkeys, {
+  customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+  onCustomHotkeysChange: (custom) =>
+    localStorage.setItem('hotkeys', JSON.stringify(custom)),
+})
+```
+
+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`:
+
+```ts
+import Alpine from 'alpinejs'
+import { 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({
+    maxSteps: Infinity,
+    validate: (hotkey) => {
+      const [conflict] = custom.findConflicts(id, hotkey)
+      return conflict ? `Used by ${conflict.meta?.name ?? conflict.id}` : true
+    },
+    onRecord: (hotkey) => custom.setCustomHotkey(id, hotkey),
+    onClear: () => custom.setCustomHotkey(id, null),
+  })
+
+  return {
+    recorder,
+    get label() {
+      const { meta, hotkey } = appHotkeys.value[id]
+      return `${meta?.name}: ${hotkey ? formatForDisplay(hotkey) : 'Unassigned'}`
+    },
+    reset: () => custom.resetCustomHotkey(id),
+    destroy: () => hotkeys.destroy(),
+  }
+})
+```
+
+```html
+<div x-data="shortcutRow('doc.save')">
+  <span x-text="label"></span>
+  <button @click="recorder.startRecording()">Change</button>
+  <button @click="reset()">Reset</button>
+</div>
+```