@inklu/keys 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# @inklu/keys
+
+Keyboard shortcut management for the web. Define commands once, bind keys to them separately, and let users remap anything.
+
+Built on [TanStack Hotkeys](https://tanstack.com/hotkeys) for key matching, which means typed hotkey strings, portable `Mod` bindings, layout-aware parsing and a single document listener no matter how many commands you register. `@inklu/keys` adds what an application needs on top: a registry, scopes, conflict detection, persistence, rebinding, and shortcuts a screen reader can read.
+
+```bash
+pnpm add @inklu/keys
+```
+
+## The idea
+
+A **command** is an addressable thing your app can do — it has an id, a title and a handler. A **binding** is a key that triggers it. Keeping them apart is what makes the rest possible: the same command runs from the keyboard, a palette, a menu item or code, and a user can rebind it without you touching its definition.
+
+```ts
+import { createCommands, seq } from "@inklu/keys";
+
+export const commands = createCommands({
+  "palette.open": {
+    title: "Open command palette",
+    keys: "Mod+K",
+    run: () => setPaletteOpen(true),
+  },
+  "doc.save": {
+    title: "Save document",
+    keys: "Mod+S",
+    when: () => isDirty(),
+    run: () => save(),
+  },
+  "nav.inbox": {
+    title: "Go to inbox",
+    keys: seq("G", "I"), // press G, then I
+    run: () => navigate("/inbox"),
+  },
+});
+
+commands.mount(); // start listening; returns a function to stop
+```
+
+Ids are inferred from the object, so `commands.run("doc.save")` autocompletes and a typo is a type error. So is a typo in a definition — `key:` instead of `keys:` would otherwise bind nothing at all, silently.
+
+`Mod` resolves to <kbd>⌘</kbd> on macOS and <kbd>Ctrl</kbd> everywhere else, so you write a shortcut once.
+
+### What this is not
+
+This is not a command-palette toolkit. There is no palette component, no fuzzy matcher, no ranking, and no `group` or `description` on a command — a command is an id, a title, a handler and its keys, and that is the whole of it. Filtering commands is your app's business and every app wants it slightly differently. This package gives you the list, current shortcuts and current state; sorting it is three lines you own:
+
+```ts
+const results = commands.filter((command) =>
+  command.title.toLowerCase().includes(query.toLowerCase()),
+);
+```
+
+## React
+
+```tsx
+import { useCommands, useMountCommands } from "@inklu/keys/react";
+import { commands } from "./commands";
+
+function App() {
+  useMountCommands(commands);
+  return <Shortcuts />;
+}
+
+function Shortcuts() {
+  const list = useCommands(commands);
+
+  return list.map((command) => (
+    <button
+      key={command.id}
+      onClick={() => commands.run(command.id)}
+      aria-keyshortcuts={command.aria || undefined}
+    >
+      {command.title}
+      {command.tokens[0]?.map((token, i) => <kbd key={i}>{token}</kbd>)}
+    </button>
+  ));
+}
+```
+
+`useMountCommands` starts listening in an effect, so nothing touches the DOM during render and the registry is safe to create at module scope in a server-rendered app.
+
+**Every hook takes the registry as its first argument.** There is no provider and no context: you already have the registry by importing it, and passing it explicitly is what keeps the ids typed — through context they widen to `string` and `useShortcut("typo")` stops being an error.
+
+| Hook | What it gives you |
+| :--- | :--- |
+| `useMountCommands(commands)` | Starts listening for as long as the component lives |
+| `useCommands(commands)` | Every command, with live shortcuts and state |
+| `useCommand(commands, id)` | One command's live state |
+| `useShortcut(commands, id)` | `{ display, tokens, aria }`, ready to render |
+| `useScope(commands, name, active, { exclusive })` | Activates a scope while a component is mounted |
+| `useRegisterCommand(commands, id, definition)` | A command that exists only while a feature is on screen |
+| `useRebind(commands, id)` | The "press the keys you want" flow, with conflicts |
+| `useHeldKeys()` | The keys physically down right now |
+
+## Server rendering
+
+There is no `navigator` on the server, so a shortcut has to be written for *some* platform before the browser can be asked. The registry writes `Ctrl+K` on the server and in the first client render, then settles on the real platform at `mount()` and re-renders. A Mac user sees `⌘K` a frame later instead of a hydration mismatch.
+
+Pin `platform` if you know better, and nothing ever changes:
+
+```ts
+createCommands(definitions, { platform: "mac" });
+```
+
+## Accessibility
+
+Every command carries an `aria` string — the value for [`aria-keyshortcuts`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts), which is what a screen reader announces. It is deliberately not the display string: the attribute wants resolved key *names*, so `Mod+K` becomes `Meta+K` on macOS and `Control+K` elsewhere, never `⌘K`.
+
+```tsx
+<button aria-keyshortcuts={command.aria || undefined}>Save</button>
+```
+
+Sequences produce `""`. The attribute separates *alternatives* with spaces, so emitting `seq("G","I")` as `"G I"` would announce "press G or I" — the opposite of what it means. There is no way to express a sequence, so the package says nothing rather than something false.
+
+If you render shortcuts as `<kbd>⌘</kbd>`, give the control an accessible name too — a screen reader reads that glyph by its Unicode name, not as "Command".
+
+## Scopes
+
+A scope decides whether a command is reachable. Push one while a dialog is open and it shadows the rest of the app, so you do not end up writing `if (!modalOpen)` in twenty different handlers.
+
+```ts
+const release = commands.pushScope("dialog", { exclusive: true });
+// …everything below this barrier stops responding
+release();
+```
+
+In React that is `useScope("dialog", isOpen, { exclusive: true })`.
+
+`exclusive` is a **barrier, not a filter**: everything at or above the topmost barrier stays reachable, everything below it goes quiet. That is what lets a menu opened inside a dialog keep working while the page behind the dialog does not. Commands scoped `"*"` always fire.
+
+Scoping is resolved when a scope is pushed or released, never per keystroke — an open dialog costs one pass over the registrations rather than a check on every key the user presses.
+
+## Rebinding
+
+Bindings live in a keymap, layered as defaults plus user overrides, so "reset to default" is exact rather than approximate.
+
+```ts
+commands.keymap.set("palette.open", "Mod+P");     // remap
+commands.keymap.add("palette.open", "Control+P"); // an additional key
+commands.keymap.set("palette.open", null);        // unbind, but keep the command
+commands.keymap.reset("palette.open");            // forget the override, back to the default
+commands.keymap.reset();                          // …for every command
+```
+
+`set(id, null)` and `reset(id)` are different on purpose: the first records an explicit "no keys" that survives, the second forgets that the user chose anything at all.
+
+Persist them by handing the registry a storage getter:
+
+```ts
+createCommands(definitions, {
+  persist: { storage: () => localStorage },
+});
+```
+
+A getter is the only accepted form, so nothing touches `localStorage` at module scope and the package stays safe to import on the server. Overrides that no longer parse — a hand-edited value, a key that was renamed — are skipped rather than thrown on, so one bad row cannot lock a user out of their own shortcuts.
+
+**Overrides are user data.** They are keyed by command id and outlive the command: unregistering a feature drops its defaults but keeps the key someone chose, so a panel that comes and goes does not quietly reset it. Only `keymap.reset(id)` forgets one.
+
+### Conflicts
+
+```ts
+commands.conflicts("Mod+K", { ignore: "palette.open" });
+// → [{ id: "search.open", display: "⌘K", scope: undefined }]
+```
+
+Two commands only conflict when their scopes can be active at the same time, so the same key may safely mean different things in different places. A global command conflicts with every scope, because it stays reachable inside them.
+
+In development the registry reports collisions itself: once at startup for the initial map, and again whenever a command is added at runtime, which in a React app is where most of them come from. It also warns about bindings the key parser cannot read — a mistyped modifier is otherwise silent, because the parser drops the part it does not recognize and `"Mdo+K"` quietly becomes a bare `K`.
+
+### Recording
+
+```tsx
+const rebind = useRebind("palette.open");
+
+<button onClick={rebind.start}>
+  {rebind.recording ? "Press keys…" : rebind.display}
+</button>;
+{rebind.overridden && <button onClick={rebind.reset}>Reset</button>}
+{rebind.conflicts.length > 0 && <p>Also used by {rebind.conflicts[0].id}</p>}
+```
+
+`display`, `tokens` and `overridden` come from the command itself rather than from the last capture, so a rebind made anywhere else in the app still shows up here.
+
+Commands are suppressed while recording, so capturing `Mod+K` does not also fire whatever `Mod+K` is currently bound to.
+
+## Markup
+
+For pages that are not React, `@inklu/keys/attributes` wires the DOM to a registry with one delegated listener:
+
+```html
+<button data-command="palette.open">
+  Search <kbd data-command-keys="palette.open"></kbd>
+</button>
+```
+
+```ts
+import { observe } from "@inklu/keys/attributes";
+const dispose = observe(commands);
+```
+
+Elements with `data-command-keys` are filled with the current shortcut and stay in sync when it is rebound. Elements with `data-command` also get `aria-keyshortcuts` set for free.
+
+## Behaviour worth knowing
+
+**Typing in inputs.** Bare keys and Shift/Alt combos are ignored while the user is in an `input`, `textarea` or contenteditable; Ctrl/Meta shortcuts and `Escape` still fire. So `Mod+K` works from inside your search box, and `/` does not. Override per command with `ignoreInputs`.
+
+**Consuming the event.** A command calls `preventDefault()` only when it actually runs. A command that is disabled, out of scope, or blocked by `when` leaves the key alone for the browser and for other handlers. Opt out with `preventDefault: false`. Propagation is never stopped — the matcher already prevents other hotkeys from firing, and halting the DOM event too would silently break delegation in your app.
+
+**`when` is a guard, not state.** It is checked immediately before running and is not observed, so it will not re-render anything. Use `setEnabled` or scopes for state that should be visible in the UI — `command.reachable` reflects both.
+
+**Why didn't my shortcut fire?** `commands.whyNotRun(id)` returns `"disabled"`, `"out-of-scope"`, `"guarded"`, `"unknown"`, or `null` when it would have run.
+
+**Knowing what ran.** `onRun` is called for every command, whatever triggered it — that is the hook for recent-command ordering, analytics or an activity log, so a command's own `run` does not have to report on itself.
+
+```ts
+createCommands(definitions, {
+  onRun: ({ id, source }) => recents.push(id),
+});
+```
+
+**Async commands.** `run` may be async. Nothing awaits it — a keystroke is fire-and-forget — but a rejection still reaches `onError` rather than the unhandled-rejection channel. If you need to await, do it inside your own handler.
+
+**One way to write a binding.** A chord is a string, `"Mod+K"`. A sequence is `seq("G", "I")`. An array means alternatives — `keys: ["Mod+K", "/"]` binds two different keys to one command. There is no object form of a chord and no inline `"G I"` string, so nothing has to normalize a binding before it can compare, format or store one.
+
+## API
+
+```ts
+createCommands(definitions, options)  // → Commands
+commands.list()                       // → readonly Command[], stable identity
+commands.get(id)
+commands.run(id, options?)            // → boolean
+commands.canRun(id) / commands.whyNotRun(id)
+commands.setEnabled(id, enabled)
+commands.add(id, definition)          // → { run, dispose }
+commands.remove(id)                   // keeps the user's override
+commands.pushScope(name, { exclusive })  // → release()
+commands.conflicts(binding, { ignore, scope })
+commands.display(id) / commands.tokens(id)   // "" / [] when unbound
+commands.mount()                      // → stop()
+commands.subscribe(listener)          // → unsubscribe()
+commands.destroy()
+commands.keymap                       // get / set / add / reset / export / import
+```
+
+`list()` returns the same array until something actually changes, so it can go straight into `useSyncExternalStore`. Each `Command` carries `title`, `scope`, `bindings`, `display`, `tokens`, `aria`, `enabled`, `reachable` and `overridden`.
+
+`display(id)` and `tokens(id)` take a command id. To format a binding you are holding directly — one out of `conflicts()`, say — `formatBinding` and `bindingTokens` are exported for that, and every `Conflict` already carries its own `display`.
+
+`CommandId<typeof commands>` is the id union, for typing values that travel alongside the registry:
+
+```ts
+export type AppCommandId = CommandId<typeof commands>;
+```
+
+## License
+
+MIT © nkurunziza-saddy

package/dist/attributes-lCPeoWII.d.ts

@@ -0,0 +1,285 @@
+import { FormatDisplayOptions, Hotkey as Hotkey$1, HotkeySequence } from "@tanstack/hotkeys";
+//#region src/types.d.ts
+/** A single hotkey chord, e.g. `"Mod+K"`. */
+type Chord = Hotkey$1;
+/** A sequence of chords pressed in order, e.g. `G` then `I`. */
+interface SequenceBinding {
+  readonly sequence: HotkeySequence;
+}
+/** A hotkey chord or sequence that triggers a command. */
+type Binding = Chord | SequenceBinding;
+/** One binding or an array of alternative bindings. */
+type BindingInput = Binding | ReadonlyArray<Binding>;
+/** JSON-serializable form of a binding. */
+type SerializedBinding = string | Array<string>;
+/** Trigger source for a command. */
+type CommandSource = "keyboard" | "api" | "dom";
+/** Context passed to a command's `run` handler. */
+interface CommandContext<Id extends string = string> {
+  /** ID of the command being run. */
+  readonly id: Id;
+  /** How the command was triggered. */
+  readonly source: CommandSource;
+  /** Originating DOM event, if triggered by user interaction. */
+  readonly event?: Event;
+  /** Specific binding that triggered the command. */
+  readonly binding?: Binding;
+  /**
+   * The commands registry instance.
+   *
+   * @example
+   * ```ts
+   * run: ({ commands }) => {
+   *   commands.setEnabled("doc.publish", false);
+   *   commands.run("doc.save");
+   * }
+   * ```
+   */
+  readonly commands: Commands<Id>;
+}
+/** Definition of a command and its default configuration. */
+interface CommandDefinition {
+  /** Human-readable title. */
+  title: string;
+  /** Default key binding(s). */
+  keys?: BindingInput;
+  /** Scope required for this command to fire. Omit for global, or `"*"` to bypass exclusive scopes. */
+  scope?: string;
+  /** Guard function evaluated before running. */
+  when?: () => boolean;
+  /** Whether the command is enabled. Defaults to `true`. */
+  enabled?: boolean;
+  /** Prevent default event behavior when run. Defaults to `true`. */
+  preventDefault?: boolean;
+  /** Whether to ignore events in form inputs/textareas/contenteditable. */
+  ignoreInputs?: boolean;
+  /** Require key release before firing again (prevents auto-repeat). Defaults to `false`. */
+  requireReset?: boolean;
+  /** Timeout in milliseconds between sequence steps. Defaults to `1000`. */
+  sequenceTimeout?: number;
+  /** Handler executed when the command runs. */
+  run: (context: CommandContext) => void | Promise<void>;
+}
+/** Resolved command snapshot including effective bindings, display tokens, and reachability. */
+interface Command<Id extends string = string> {
+  readonly id: Id;
+  readonly title: string;
+  readonly scope?: string;
+  /** Active bindings after user overrides. */
+  readonly bindings: ReadonlyArray<Binding>;
+  /** Formatted display strings for active bindings. */
+  readonly display: ReadonlyArray<string>;
+  /** Formatted tokens per binding for rendering `<kbd>` elements. */
+  readonly tokens: ReadonlyArray<ReadonlyArray<string>>;
+  /** Value for `aria-keyshortcuts` attribute. */
+  readonly aria: string;
+  /** Whether the command is enabled. */
+  readonly enabled: boolean;
+  /** Whether the command is enabled and in an active scope. */
+  readonly reachable: boolean;
+  /** Whether the command has a user keymap override. */
+  readonly overridden: boolean;
+}
+/** Supported platforms for hotkey resolution and display formatting. */
+type Platform = "mac" | "windows" | "linux";
+/** Storage interface for persisting keymap overrides. */
+interface KeymapStorage {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+}
+/** Configuration for persisting keymap overrides. */
+interface KeymapPersistence {
+  /** Storage key name. Defaults to `"inklu.keys"`. */
+  key?: string;
+  /** Getter returning the storage implementation lazily. */
+  storage: () => KeymapStorage | null;
+}
+/** Details of a conflict between commands with identical bindings in overlapping scopes. */
+interface Conflict<Id extends string = string> {
+  /** ID of the conflicting command. */
+  readonly id: Id;
+  /** Shared binding. */
+  readonly binding: Binding;
+  /** Formatted display representation of the binding. */
+  readonly display: string;
+  /** Overlapping scope where conflict occurs, if any. */
+  readonly scope?: string;
+}
+/** Options for activating a scope. */
+interface ScopeOptions {
+  /** Shadow commands in lower scopes, including global commands. */
+  exclusive?: boolean;
+}
+//#endregion
+//#region src/display.d.ts
+/** Display options for formatting hotkeys. */
+type DisplayOptions = FormatDisplayOptions;
+/** Formats a binding for display on the target platform (e.g. `⌘K` or `Ctrl+K`). */
+declare function formatBinding(binding: Binding, options?: DisplayOptions): string;
+/** Splits a binding into display tokens for rendering `<kbd>` elements. */
+declare function bindingTokens(binding: Binding, options?: DisplayOptions): Array<string>;
+/** Generates an `aria-keyshortcuts` attribute string for a binding. */
+declare function ariaKeyShortcuts(binding: Binding, platform?: Platform): string;
+//#endregion
+//#region src/keymap.d.ts
+/** Persisted map of command IDs to serialized bindings. */
+type SerializedKeymap = Record<string, Array<SerializedBinding>>;
+/** Keymap interface for querying, modifying, and persisting keybindings. */
+interface CommandKeymap<Id extends string = string> {
+  /** Active bindings in effect (user overrides if present, otherwise defaults). */
+  get(id: Id | (string & {})): ReadonlyArray<Binding>;
+  /** Rebinds a command. Passing `null` unbinds it without restoring the default. */
+  set(id: Id | (string & {}), input: BindingInput | null): void;
+  /** Appends an additional binding to a command. */
+  add(id: Id | (string & {}), input: BindingInput): void;
+  /** Resets user overrides back to defaults for a specific command or all commands. */
+  reset(id?: Id | (string & {})): void;
+  /** Exports user overrides as JSON-serializable data. */
+  export(): SerializedKeymap;
+  /** Imports user overrides, replacing current overrides and saving to storage. */
+  import(data: unknown): void;
+}
+//#endregion
+//#region src/registry.d.ts
+/** Configuration options for a commands registry. */
+interface CommandsOptions {
+  /** Platform for modifier resolution and display formatting. Defaults to auto-detection. */
+  platform?: Platform;
+  /** Target element for key events. Defaults to `document`. */
+  target?: HTMLElement | Document | Window | null;
+  /** Persistence configuration for user keymap overrides. */
+  persist?: KeymapPersistence;
+  /** Display options for rendering shortcuts. */
+  display?: DisplayOptions;
+  /**
+   * Callback fired whenever a command runs.
+   *
+   * @example
+   * ```ts
+   * createCommands(definitions, {
+   *   onRun: ({ id }) => logRun(id),
+   * });
+   * ```
+   */
+  onRun?: (context: CommandContext) => void;
+  /** Error handler called when a command execution fails. Defaults to `console.error`. */
+  onError?: (error: unknown, context: CommandContext) => void;
+}
+/** Options passed when manually running a command. */
+interface RunOptions {
+  /** Trigger source. Defaults to `"api"`. */
+  source?: CommandSource;
+  /** Originating DOM event. */
+  event?: Event;
+}
+/** Options for conflict detection. */
+interface ConflictOptions<Id extends string = string> {
+  /** Command ID to ignore during conflict checking. */
+  ignore?: Id;
+  /** Scope to evaluate conflicts in. Defaults to global. */
+  scope?: string;
+}
+/** Reason why a command cannot run. */
+type RunBlockReason = "unknown" | "disabled" | "out-of-scope" | "guarded";
+/** Represents a partially completed key sequence. */
+interface PendingSequence<Id extends string = string> {
+  /** Command ID. */
+  readonly id: Id;
+  /** Sequence binding being typed. */
+  readonly binding: SequenceBinding;
+  /** Number of steps matched so far. */
+  readonly matched: number;
+  /** Total steps in the sequence. */
+  readonly total: number;
+  /** Formatted remaining steps. */
+  readonly remaining: ReadonlyArray<string>;
+}
+/** Handle for a dynamically registered runtime command. */
+interface CommandHandle {
+  /** Runs the command. Returns `true` if executed. */
+  run: (options?: RunOptions) => boolean;
+  /** Disposes and unregisters the command. */
+  dispose: () => void;
+}
+/** Public interface for the commands registry. */
+interface Commands<Id extends string = string> {
+  /** Keymap holding default and user bindings. */
+  readonly keymap: CommandKeymap<Id>;
+  /** Retrieves a command's snapshot, or `undefined` if unregistered. */
+  get(id: Id | (string & {})): Command<Id> | undefined;
+  /** Returns all registered commands in definition order. */
+  list(): ReadonlyArray<Command<Id>>;
+  /** Runs a command by ID. Returns `true` if executed. */
+  run(id: Id, options?: RunOptions): boolean;
+  /** Checks whether a command can run currently. */
+  canRun(id: Id | (string & {})): boolean;
+  /** Returns why a command cannot run, or `null` if executable. */
+  whyNotRun(id: Id | (string & {})): RunBlockReason | null;
+  /** Enables or disables a command. */
+  setEnabled(id: Id | (string & {}), enabled: boolean): void;
+  /** Registers a command at runtime. */
+  add(id: Id | (string & {}), definition: CommandDefinition): CommandHandle;
+  /** Removes a command registration. */
+  remove(id: Id | (string & {})): void;
+  /** Activates a scope until the returned disposal function is called. */
+  pushScope(name: string, options?: ScopeOptions): () => void;
+  /** Finds conflicting commands that share the given binding in overlapping scopes. */
+  conflicts(binding: BindingInput, options?: ConflictOptions<Id>): Array<Conflict<Id>>;
+  /** Formats a command's primary binding for display. */
+  display(id: Id | (string & {})): string;
+  /** Splits a command's primary binding into `<kbd>` tokens. */
+  tokens(id: Id | (string & {})): Array<string>;
+  /** Returns currently active partially-typed sequences. */
+  pending(): ReadonlyArray<PendingSequence<Id>>;
+  /** Subscribes to sequence progress changes. */
+  subscribePending(listener: () => void): () => void;
+  /** Starts listening for key events. Returns an unmount function. */
+  mount(): () => void;
+  /** Subscribes to registry changes. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** Tears down listeners and clears all command registrations. */
+  destroy(): void;
+}
+/**
+ * Creates a command registry.
+ *
+ * @example
+ * ```ts
+ * export const commands = createCommands({
+ *   "palette.open": {
+ *     title: "Open command palette",
+ *     keys: "Mod+K",
+ *     run: () => setPaletteOpen(true),
+ *   },
+ *   "nav.inbox": {
+ *     title: "Go to inbox",
+ *     keys: seq("G", "I"),
+ *     run: () => navigate("/inbox"),
+ *   },
+ * });
+ * ```
+ */
+declare function createCommands<const T extends { [K in keyof T]: CommandDefinition & Record<Exclude<keyof T[K], keyof CommandDefinition>, never>; }>(definitions: T, options?: CommandsOptions): Commands<Extract<keyof T, string>>;
+/**
+ * Extracts command ID union from a Commands registry type.
+ *
+ * @example
+ * ```ts
+ * export const commands = createCommands({ … });
+ * export type AppCommandId = CommandId<typeof commands>;
+ * ```
+ */
+type CommandId<C> = C extends Commands<infer Id> ? Id : never;
+//#endregion
+//#region src/attributes.d.ts
+interface ObserveOptions {
+  /** Root document or element to delegate from. Defaults to `document`. */
+  root?: Document | Element;
+}
+/**
+ * Wires a commands registry to DOM data attributes. Returns a cleanup function.
+ */
+declare function observe<Id extends string>(registry: Commands<Id>, options?: ObserveOptions): () => void;
+//#endregion
+export { Platform as A, CommandDefinition as C, HotkeySequence as D, Hotkey$1 as E, SequenceBinding as M, SerializedBinding as N, KeymapPersistence as O, CommandContext as S, Conflict as T, formatBinding as _, Commands as a, Chord as b, PendingSequence as c, createCommands as d, CommandKeymap as f, bindingTokens as g, ariaKeyShortcuts as h, CommandId as i, ScopeOptions as j, KeymapStorage as k, RunBlockReason as l, DisplayOptions as m, observe as n, CommandsOptions as o, SerializedKeymap as p, CommandHandle as r, ConflictOptions as s, ObserveOptions as t, RunOptions as u, Binding as v, CommandSource as w, Command as x, BindingInput as y };

package/dist/attributes.d.ts

@@ -0,0 +1,2 @@
+import { n as observe, t as ObserveOptions } from "./attributes-lCPeoWII.js";
+export { ObserveOptions, observe };

package/dist/attributes.js

@@ -0,0 +1,72 @@
+//#region src/attributes.ts
+const COMMAND_ATTRIBUTE = "data-command";
+const KEYS_ATTRIBUTE = "data-command-keys";
+/**
+* Wires a commands registry to DOM data attributes. Returns a cleanup function.
+*/
+function observe(registry, options = {}) {
+	if (typeof document === "undefined") return () => {};
+	const root = options.root ?? document;
+	const onClick = (event) => {
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		const id = target.closest(`[${COMMAND_ATTRIBUTE}]`)?.getAttribute(COMMAND_ATTRIBUTE);
+		if (!id) return;
+		registry.run(id, {
+			source: "dom",
+			event
+		});
+	};
+	const paintElement = (element) => {
+		const keysId = element.getAttribute(KEYS_ATTRIBUTE);
+		if (keysId) {
+			const display = registry.display(keysId);
+			if (element.textContent !== display) element.textContent = display;
+		}
+		const commandId = element.getAttribute(COMMAND_ATTRIBUTE);
+		if (commandId) {
+			const aria = registry.get(commandId)?.aria ?? "";
+			if (aria) element.setAttribute("aria-keyshortcuts", aria);
+			else element.removeAttribute("aria-keyshortcuts");
+		}
+	};
+	const paintWithin = (scope) => {
+		if (scope instanceof Element) paintElement(scope);
+		for (const element of scope.querySelectorAll(`[${KEYS_ATTRIBUTE}],[${COMMAND_ATTRIBUTE}]`)) paintElement(element);
+	};
+	const painted = () => registry.list().map((command) => `${command.id} ${command.display[0] ?? ""} ${command.aria}`).join(" ");
+	root.addEventListener("click", onClick);
+	paintWithin(root);
+	let lastPainted = painted();
+	const unsubscribe = registry.subscribe(() => {
+		const next = painted();
+		if (next === lastPainted) return;
+		lastPainted = next;
+		paintWithin(root);
+	});
+	let observer;
+	if (typeof MutationObserver !== "undefined") {
+		observer = new MutationObserver((mutations) => {
+			for (const mutation of mutations) {
+				if (mutation.type === "attributes" && mutation.target instanceof Element) {
+					paintElement(mutation.target);
+					continue;
+				}
+				for (const node of mutation.addedNodes) if (node instanceof Element) paintWithin(node);
+			}
+		});
+		observer.observe(root instanceof Document ? root.documentElement : root, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [COMMAND_ATTRIBUTE, KEYS_ATTRIBUTE]
+		});
+	}
+	return () => {
+		root.removeEventListener("click", onClick);
+		unsubscribe();
+		observer?.disconnect();
+	};
+}
+//#endregion
+export { observe };