@tanstack/hotkeys 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -21,7 +21,8 @@
     "keyboard",
     "shortcuts",
     "keybindings",
-    "typescript"
+    "typescript",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -35,7 +36,8 @@
     "node": ">=20"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
     "@tanstack/store": "^0.11.2"

package/skills/app-hotkeys/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: app-hotkeys
+description: >-
+  Use when an app built with TanStack Hotkeys needs a keyboard shortcut cheat
+  sheet or help dialog, a command palette whose commands may have shortcuts, a
+  settings screen where users rebind, unbind, or reset shortcuts, recording the
+  shortcut a user presses, conflict checks between shortcuts, or saving custom
+  shortcuts to storage.
+metadata:
+  purpose: >-
+    Declare every shortcut once with defineAppHotkeys, then build cheat sheets,
+    rebinding, conflict checks, and persistence from those declarations instead
+    of a parallel shortcut registry.
+  type: core
+  library: '@tanstack/hotkeys'
+  library_version: '0.16.0'
+sources:
+  - src/app-hotkeys.ts
+  - src/hotkey-recorder.ts
+  - src/conflicts.ts
+  - TanStack/hotkeys:docs/framework/react/guides/app-hotkeys.md
+  - TanStack/hotkeys:docs/framework/react/guides/cheat-sheet-ui-helpers.md
+  - TanStack/hotkeys:docs/framework/react/guides/custom-hotkey-recording.md
+  - 'TanStack/hotkeys:packages/react-hotkeys/tests/skills/shortcut-settings/**'
+requires:
+  - hotkeys-core
+---
+
+# App hotkeys
+
+This skill builds on `hotkeys-core`. The adapter skill's app hotkeys reference shows the wiring in your framework.
+
+App hotkeys are the library's shortcut catalog. Use them instead of a separate shortcut config, context, or hand-written cheat sheet. One module declares every shortcut. The root provider holds the user's custom hotkeys. Components register the declared app hotkeys with their callbacks. Plain hotkeys with `meta` are enough when a list only needs what is mounted right now.
+
+```ts
+import { defineAppHotkeys } from '@tanstack/hotkeys'
+
+export const appHotkeys = defineAppHotkeys({
+  'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' }, scope: 'document' },
+  'comment.post': {
+    hotkey: 'Mod+S',
+    meta: { name: 'Post comment' },
+    scope: 'comments',
+  },
+  'theme.toggle': { hotkey: null, meta: { name: 'Toggle theme' } },
+})
+```
+
+Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup.
+
+## Pitfalls
+
+- **Register the app hotkey, not its value.** Pass `appHotkeys['doc.save']`. Passing `.hotkey` registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as `'inactive'`.
+- **The provider reads `customHotkeys` once.** When saved shortcuts load asynchronously, render the provider after they arrive, or key it by user. Change shortcuts afterwards through the adapter's custom hotkeys API, not by updating the prop.
+- **Save what `onCustomHotkeysChange` receives.** It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.
+- **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are dropped with a warning, so renaming an id discards users' customizations.
+- **`setCustomHotkey` returns conflicts and changes nothing when there are any.** Check the result before reporting success, or reject the key press earlier by calling `findConflicts` in the recorder's `validate`.
+- **Declare scopes on app hotkeys that share keys.** An app hotkey without a scope, or in `'global'`, conflicts with every other app hotkey on the same keys, so rebinding is rejected.
+- **Conflict checks treat physical and logical bindings as different.** A recorded `Mod+[KeyP]` doesn't conflict with a declared `Mod+P`, although Command+P runs both. Declaring rebindable defaults in the recorder's form, such as `Mod+[KeyP]`, makes them comparable.
+- **A cheat sheet dialog usually gets an exclusive scope.** Register the hotkey that opened it inside the dialog too, so the same keys close it.
+
+When building the "press a new shortcut" control, read [recording](references/recording.md).

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

@@ -0,0 +1,9 @@
+# Recording a shortcut
+
+Use the adapter's recorder instead of a `keydown` listener that builds a string. The recorder already handles the hard parts:
+
+- It pauses registered hotkeys while recording, so pressing `Mod+S` to record it doesn't save. Leave your hotkeys enabled.
+- It records `Mod` rather than Command or Control, and key positions such as `Mod+[KeyS]`, so Option+S records `Alt+[KeyS]` instead of `ß`. Save the recorded value as it is; `formatForDisplay` hides the brackets.
+- Escape cancels. Backspace or Delete removes the last step, or with nothing recorded calls `onClear`, which changes nothing on its own: decide whether clearing unbinds (`setCustomHotkey(id, null)`) or resets (`resetCustomHotkey(id)`).
+- With `maxSteps: Infinity`, the user can record a sequence, which commits on Enter or after `idleTimeoutMs`.
+- `detectConflicts: true` checks only hotkeys registered right now. For app hotkeys, call `findConflicts(id, hotkey)` in `validate` and return a message to reject; a rejected recording keeps listening.

package/skills/hotkeys-core/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: hotkeys-core
+description: >-
+  Use when adding, fixing, or reviewing keyboard shortcuts with TanStack
+  Hotkeys: replacing keydown listeners or another shortcut library, deciding
+  when a hotkey works (enabled, scopes, targets), dialogs that own the
+  keyboard, sequences, or testing hotkeys. Load the framework adapter's skill
+  with it.
+metadata:
+  purpose: >-
+    Framework-neutral rules for TanStack Hotkeys: the work the library already
+    does, how hotkeys turn on and off, and the pitfalls that don't surface as
+    errors.
+  type: core
+  library: '@tanstack/hotkeys'
+  library_version: '0.16.0'
+sources:
+  - src/hotkey-manager.ts
+  - src/match.ts
+  - TanStack/hotkeys:docs/guides/sensible-defaults.md
+  - TanStack/hotkeys:docs/framework/react/guides/hotkeys.md
+  - TanStack/hotkeys:docs/framework/react/guides/sequences.md
+  - TanStack/hotkeys:docs/framework/react/guides/hotkeys-provider-and-scopes.md
+  - 'TanStack/hotkeys:packages/react-hotkeys/tests/skills/editor-shortcuts/**'
+---
+
+# TanStack Hotkeys
+
+The library owns the keyboard. Register every shortcut with your framework adapter's hotkey API, such as `useHotkey`, `createHotkey`, `injectHotkey`, or `@hotkey`, in the component that owns the action. Import everything from the adapter package; it re-exports `@tanstack/hotkeys`. The adapter's skill covers its bindings.
+
+## Use the library instead of rebuilding it
+
+| Instead of                                                            | Use                                                                                                                                           |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| A `keydown` listener that checks `event.key`, `metaKey`, or `ctrlKey` | A registered hotkey such as `'Mod+S'`. Inside a widget's own key handler, `matchesKeyboardEvent(event, 'Mod+Enter')`.                         |
+| `isMac` checks and `⌘`/`Ctrl` label maps                              | `Mod` in the hotkey, and `formatForDisplay(hotkey)` for labels                                                                                |
+| Skipping events from text fields, calling `preventDefault`            | The defaults: single keys and Shift/Alt chords are skipped while typing, `Mod` chords and `Escape` still fire, and matched keys are prevented |
+| A shortcut registry, service, context, or wrapper hook                | The adapter API, called where each action lives. For one list of every shortcut, load `@tanstack/hotkeys#app-hotkeys`.                        |
+| A "shortcuts enabled" flag or topmost-dialog tracking                 | Scopes, with `exclusive` for dialogs                                                                                                          |
+| A hand-written shortcut list for a help dialog                        | `meta: { name }` and the adapter's registrations list, or app hotkeys                                                                         |
+| `keydown`/`keyup` state that tracks held keys                         | The adapter's held-key and hint APIs                                                                                                          |
+| Capturing the next key press for a settings screen                    | The adapter's recorder                                                                                                                        |
+
+A workaround loses what the library tracks: scopes stop suspending it, recorders stop pausing it, devtools stop listing it, and layout and platform handling disappear.
+
+## Turn hotkeys on and off
+
+Use the first mechanism that fits:
+
+1. **Lifetime.** A hotkey registered in a component exists while that component is mounted. A dialog's `Escape` belongs in the dialog.
+2. **`enabled`.** A condition inside a mounted component.
+3. **Scope.** A group that turns on and off together, such as a dialog, pane, or tab. An `exclusive` scope suspends every other scope, including global hotkeys, while it is active.
+4. **`target`.** Only while focus is inside one element, which must be focusable (`tabindex="0"`).
+
+When nesting scopes, stacking dialogs, or keeping some hotkeys working during an exclusive scope, read [scopes](references/scopes.md).
+
+## Pitfalls
+
+- **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. To skip the action, keep the hotkey enabled and return early from the callback.
+- **Modifiers match exactly.** `ArrowDown` never fires while Shift is held, so register `Shift+ArrowDown` instead of checking `event.shiftKey`. Shift that a symbol needs is the exception: `?` matches Shift+/.
+- **Chords repeat while held.** Set `requireReset: true` on toggles, or holding the keys flickers them.
+- **Letters follow the typed character.** For position-based controls such as WASD, use physical bindings such as `'[KeyW]'`. Keep letters for mnemonic commands such as `Mod+S`.
+- **Each open exclusive scope needs its own name.** A reusable dialog with a fixed scope name breaks when one dialog opens another: both share one scope and both handle `Escape`. Build the name per instance.
+- **A chord on a sequence's first key runs every time the sequence starts.** With `G` and `['G', 'G']`, the first `G` runs the chord. Later keys belong to the sequence. To show "waiting for the next key", read `matchedStepCount` from the adapter's registrations list.
+- **Single-character shortcuts need an off switch.** For WCAG 2.1.4, `K`, `?`, and `['G', 'H']` need a user setting passed as `enabled`, or an app hotkey users can remap.
+- **react-hotkeys-hook names don't carry over.** `useHotkeys` and `HotkeysProvider` share names, not signatures: there's no dependency array, `preventDefault` is on by default, and sequences are arrays. Remove the old library, so two libraries don't handle the same keys.
+- **Install only the adapter.** A separately installed `@tanstack/hotkeys` at another version is a second copy, and scopes don't apply across copies.
+
+When writing tests for hotkeys, read [testing](references/testing.md).
+
+## API discovery
+
+Read the installed declarations for exact signatures: the adapter's `dist/*.d.ts`, then the core's `hotkey.types.d.ts` (hotkey strings) and `hotkey-manager.d.ts` (`HotkeyOptions`). With pnpm, the core package sits beside the adapter: `ls "$(realpath node_modules/@tanstack/react-hotkeys)/../hotkeys/dist"`, using your adapter's name.

package/skills/hotkeys-core/references/scopes.md

@@ -0,0 +1,11 @@
+# Scopes
+
+- A scope is a name, not an instance. Two mounted providers with the same scope share it, and it stays active until both are gone.
+- Hotkeys outside every scoped provider are in `'global'`, which is always active unless an exclusive scope suspends it.
+- When hotkeys in two active scopes match the same key, a nested scope beats the scopes around it; otherwise the most recently activated scope wins. Only the winning scope's hotkeys run.
+- The same hotkey in two scopes is not a duplicate, so there's no conflict warning.
+- An `exclusive` scope suspends every other scope except scopes nested in it and those in `exclusive: { allow: ['global'] }`. With several exclusive scopes active, the one with the highest precedence owns the keyboard, so a dialog opened from a dialog suspends the first until it closes.
+- A provider with `enabled: false` turns off its scope and every scope nested in it while staying mounted, for tabs and panes that stay rendered.
+- A hotkey's `scope` option, or an app hotkey's declared `scope`, overrides the provider's.
+- Scopes follow the component tree, not the DOM, so a portaled dialog keeps its scope.
+- The hotkey that opens an exclusive dialog is suspended with the rest of the page. To close the dialog with the same keys, register that hotkey inside the dialog too.

package/skills/hotkeys-core/references/testing.md

@@ -0,0 +1,7 @@
+# Testing hotkeys
+
+- **Set the platform.** Test DOMs don't report a real platform (happy-dom on macOS detects `windows`), so `Mod` changes meaning between machines. Pass `platform: 'mac'` in the provider's `defaultOptions.hotkey`, or on the hotkey.
+- **Reset between tests.** Call `HotkeyManager.resetInstance()`, plus `KeyStateTracker.resetInstance()` for held-key tests, in `afterEach`. Registrations and scope activations otherwise outlive a test that fails before unmounting.
+- **Dispatch real events.** Use `new KeyboardEvent('keydown', { key: 's', code: 'KeyS', metaKey: true, bubbles: true, cancelable: true })`. Physical bindings such as `[KeyS]` match only `code`. Check `event.defaultPrevented` to assert the browser action was blocked.
+- **Dispatch where focus is.** For a hotkey with a `target`, or to test typing in a field, focus the element and dispatch on it with `bubbles: true`.
+- **Repeats and sequences.** `repeat: true` simulates holding a key; it fires chords again unless they set `requireReset`, and it never advances a sequence. Use fake timers to test a sequence's `timeout` (1000 ms by default).