@inklu/keys 1.1.0 → 1.2.0

package/README.md

@@ -73,6 +73,17 @@ function Dialog({ isOpen }) {
 }
 ```
 
+`exclusive` is a barrier: it silences the whole app beneath it. To claim only a few keys, drop it and give those commands a `scope` instead — see below.
+
+### When two commands share a key
+
+Exactly one command runs per keypress. The winner is:
+
+1. The command in a named scope, over a global one. `"*"` counts as global here — it means "survives barriers", not "belongs to a region of the UI".
+2. Failing that, the one registered later. Registration order tracks mount order, so the most recently opened surface claims the key.
+
+A winner whose `when()` currently returns `false` steps aside rather than swallowing the keypress. This is how `Escape` closes the dialog when one is open and the panel otherwise, without making the dialog `exclusive`. Two commands sharing a chord *in the same scope* can never separate, so that case warns in development.
+
 ## 4. Rebinding
 
 Overrides are layered over defaults.
@@ -84,6 +95,19 @@ commands.keymap.set("palette.open", null);        // unbind
 commands.keymap.reset("palette.open");            // reset to default
 ```
 
+To rebind a command you did not define — one a package shipped — pass `bindings` when creating the registry. An unknown id is a compile error, and `reset` returns here rather than to the definition's `keys`:
+
+```ts
+createCommands(commands, {
+  bindings: {
+    "palette.open": "Mod+P", // replace the shipped default
+    "doc.publish": null,     // ship it unbound
+  },
+});
+```
+
+These are defaults, applied before persisted overrides load, so a user's own rebinding still wins.
+
 In React, use the `useRebind` hook for a capture flow:
 
 ```tsx
@@ -97,6 +121,7 @@ const rebind = useRebind(commands, "palette.open");
 ## API Summary
 
 - `createCommands(definitions, options)` - creates the registry
+  - `options`: `{ bindings, platform, target, persist, display, onRun, onError }`
 - `useMountCommands(commands)` - starts listening
 - `useShortcut(commands, id)` - gets display tokens and aria for rendering
 - `useScope(commands, name, active, { exclusive })` - isolates command execution

package/dist/{attributes-lCPeoWII.d.ts → attributes-DbxlLdrb.d.ts}

@@ -143,7 +143,25 @@ interface CommandKeymap<Id extends string = string> {
 //#endregion
 //#region src/registry.d.ts
 /** Configuration options for a commands registry. */
-interface CommandsOptions {
+interface CommandsOptions<Id extends string = string> {
+  /**
+   * Replaces the default `keys` a command was defined with, keyed by command
+   * id. Lets an app rebind commands it did not define — a package ships the
+   * behaviour, the app decides which key reaches it — and an unknown id is a
+   * compile error rather than a silent no-op. `null` ships the command with
+   * no default binding at all.
+   *
+   * These are defaults, applied before persisted overrides load, so a user's
+   * own rebinding still wins.
+   *
+   * @example
+   * ```ts
+   * createCommands(commands, {
+   *   bindings: { "palette.open": "Mod+P", "doc.publish": null },
+   * });
+   * ```
+   */
+  bindings?: Partial<Record<Id, BindingInput | null>>;
   /** Platform for modifier resolution and display formatting. Defaults to auto-detection. */
   platform?: Platform;
   /** Target element for key events. Defaults to `document`. */
@@ -260,7 +278,7 @@ interface Commands<Id extends string = string> {
  * });
  * ```
  */
-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>>;
+declare function createCommands<const T extends { [K in keyof T]: CommandDefinition & Record<Exclude<keyof T[K], keyof CommandDefinition>, never>; }>(definitions: T, options?: CommandsOptions<Extract<keyof T, string>>): Commands<Extract<keyof T, string>>;
 /**
  * Extracts command ID union from a Commands registry type.
  *

package/dist/attributes.d.ts

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

package/dist/{index-WDNLK0dX.d.ts → index-D4UoKAQU.d.ts}

@@ -1,4 +1,4 @@
-import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-lCPeoWII.js";
+import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-DbxlLdrb.js";
 import { Hotkey } from "@tanstack/hotkeys";
 //#region src/bindings.d.ts
 /**

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-lCPeoWII.js";
-import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-WDNLK0dX.js";
+import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-DbxlLdrb.js";
+import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-D4UoKAQU.js";
 export { ALWAYS_SCOPE, type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandle, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictOptions, type DisplayOptions, type Hotkey, type HotkeySequence, type KeymapPersistence, type KeymapStorage, type ObserveOptions, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/index.js

@@ -1,3 +1,3 @@
 import { observe } from "./attributes.js";
-import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, t as createCommands, u as validateBinding } from "./src-B305icXC.js";
+import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, t as createCommands, u as validateBinding } from "./src-DyFUgmho.js";
 export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-lCPeoWII.js";
-import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-WDNLK0dX.js";
+import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-DbxlLdrb.js";
+import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-D4UoKAQU.js";
 //#region src/react/hooks.d.ts
 /**
  * Mounts a commands registry for the lifecycle of the component.

package/dist/react.js

@@ -1,6 +1,6 @@
 "use client";
 import { observe } from "./attributes.js";
-import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, l as toBindings, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, s as bindingSignature, t as createCommands, u as validateBinding } from "./src-B305icXC.js";
+import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, l as toBindings, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, s as bindingSignature, t as createCommands, u as validateBinding } from "./src-DyFUgmho.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 //#region src/react/hooks.ts

package/dist/{src-B305icXC.js → src-DyFUgmho.js}

@@ -340,7 +340,7 @@ var Binder = class {
 		this.#bound.clear();
 	}
 	#register(id, binding, signature, definition, enabled) {
-		const callback = (event) => this.#handle(id, binding, event);
+		const callback = (event) => this.#handle(id, binding, signature, event);
 		const options = {
 			preventDefault: false,
 			stopPropagation: false,
@@ -370,8 +370,18 @@ var Binder = class {
 			return null;
 		}
 	}
-	#handle(id, binding, event) {
+	/**
+	* One keypress can reach several registrations (see `conflictBehavior`
+	* above), so every candidate asks the registry whether it won before doing
+	* anything observable. Arbitration comes before `preventDefault` on
+	* purpose: a losing command must leave the event exactly as it found it,
+	* or a command declaring `preventDefault: false` would still have the
+	* browser's default action cancelled by whichever rival happened to be
+	* registered alongside it.
+	*/
+	#handle(id, binding, signature, event) {
 		if (!this.#host.canRun(id)) return;
+		if (!this.#host.claims(id, signature)) return;
 		const definition = this.#host.getDefinition(id);
 		if (!definition) return;
 		if (definition.preventDefault !== false) event.preventDefault();
@@ -394,7 +404,7 @@ var Keymap = class {
 	constructor(persistence) {
 		this.#persistence = persistence;
 	}
-	/** Sets a command's default bindings. */
+	/** Sets a command's default bindings. `null` leaves the command unbound. */
 	setDefault(loose, input) {
 		const id = loose;
 		const bindings = toBindings(input);
@@ -573,6 +583,7 @@ var CommandRegistry = class {
 	#pendingSubscription = null;
 	#snapshot = null;
 	#index = null;
+	#ownerIndex = null;
 	#mounts = 0;
 	#hydrated = false;
 	#barrier = false;
@@ -584,6 +595,7 @@ var CommandRegistry = class {
 			getBindings: (id) => this.#keymap.get(id),
 			canRun: (id) => this.canRun(id),
 			isReachable: (id) => this.#isReachable(id),
+			claims: (id, signature) => this.#claims(id, signature),
 			platform: () => this.#platform(),
 			execute: (id, context) => {
 				this.#execute(id, context);
@@ -808,7 +820,9 @@ var CommandRegistry = class {
 		const definition = this.#definition(id);
 		if (!definition) return;
 		this.#enabled.set(id, definition.enabled !== false);
-		this.#keymap.setDefault(id, definition.keys);
+		const overrides = this.#options.bindings;
+		const keys = overrides && Object.hasOwn(overrides, id) ? overrides[id] : definition.keys;
+		this.#keymap.setDefault(id, keys);
 	}
 	#drop(id) {
 		this.#stacks.delete(id);
@@ -822,6 +836,57 @@ var CommandRegistry = class {
 		if (!(this.#enabled.get(id) ?? false)) return false;
 		return this.#scopes.isActive(this.#definition(id)?.scope);
 	}
+	/**
+	* Decides which of several commands sharing one binding gets to run.
+	*
+	* Without this every registration for the pressed chord fires, so two
+	* commands bound to `Mod+S` in overlapping scopes both ran and the only
+	* defence was a dev-time console warning. Exclusive scopes could not fix
+	* it either: a barrier shadows *every* global command, not just the one
+	* colliding, so "Esc closes the dialog, and the panel otherwise" forced
+	* the whole dialog to become exclusive.
+	*
+	* Ranking, highest first:
+	*
+	*   1. A command in a named scope beats a global one. `ALWAYS_SCOPE` is
+	*      global for this purpose — it means "survives barriers", not
+	*      "belongs to some region of the UI".
+	*   2. Later registration beats earlier. Registration order tracks mount
+	*      order, so the most recently opened surface claims the key — the
+	*      same intuition that makes `add()` stack definitions per id.
+	*
+	* Guards are evaluated live rather than baked into the ranking, so a
+	* winner whose `when()` currently returns false steps aside instead of
+	* swallowing the keypress.
+	*/
+	#claims(id, signature) {
+		const candidates = this.#owners().get(signature);
+		if (!candidates || candidates.length < 2) return true;
+		for (const candidate of candidates) {
+			if (candidate !== id && !this.canRun(candidate)) continue;
+			return candidate === id;
+		}
+		return false;
+	}
+	/** Binding signature → command ids that share it, ranked by `#claims`. */
+	#owners() {
+		if (this.#ownerIndex) return this.#ownerIndex;
+		const platform = this.#platform();
+		const index = /* @__PURE__ */ new Map();
+		for (const id of this.#order) for (const binding of this.#keymap.get(id)) {
+			const signature = bindingSignature(binding, platform);
+			const ids = index.get(signature);
+			if (ids) ids.unshift(id);
+			else index.set(signature, [id]);
+		}
+		for (const ids of index.values()) if (ids.length > 1) ids.sort((a, b) => this.#scopeRank(b) - this.#scopeRank(a));
+		this.#ownerIndex = index;
+		return index;
+	}
+	#scopeRank(id) {
+		const scope = this.#definition(id)?.scope;
+		return scope === void 0 || scope === "*" ? 0 : 1;
+	}
 	#execute(id, context) {
 		const definition = this.#definition(id);
 		if (!definition) return;
@@ -894,6 +959,7 @@ var CommandRegistry = class {
 	#invalidate() {
 		this.#snapshot = null;
 		this.#index = null;
+		this.#ownerIndex = null;
 		for (const listener of this.#listeners) listener();
 	}
 	#warnAboutConflicts() {
@@ -908,10 +974,10 @@ var CommandRegistry = class {
 					seen.set(key, id);
 					continue;
 				}
-				collisions.push(`${formatBinding(binding, this.#displayOptions())} — "${owner}" and "${id}"`);
+				collisions.push(`${formatBinding(binding, this.#displayOptions())} — "${id}" shadows "${owner}"`);
 			}
 		}
-		if (collisions.length > 0) console.warn(`[@inklu/keys] ${collisions.length} conflicting binding(s):\n  ${collisions.join("\n  ")}`);
+		if (collisions.length > 0) console.warn(`[@inklu/keys] ${collisions.length} unreachable binding(s) — same chord, same scope:\n  ${collisions.join("\n  ")}`);
 	}
 	#warnAboutBindings(id) {
 		for (const binding of this.#keymap.get(id)) {
@@ -921,9 +987,17 @@ var CommandRegistry = class {
 			console.warn(`[@inklu/keys] "${id}" has an unrecognized binding ${describeBinding(binding)}, which resolves to "${resolved}". ${errors.join("; ")}.`);
 		}
 	}
+	/** Catches ids in `options.bindings` that TypeScript could not — plain JS, or a runtime-only command. */
+	#warnAboutUnknownOverrides() {
+		const overrides = this.#options.bindings;
+		if (!overrides) return;
+		const unknown = Object.keys(overrides).filter((id) => !this.#stacks.has(id));
+		if (unknown.length > 0) console.warn(`[@inklu/keys] bindings override ${unknown.map((id) => `"${id}"`).join(", ")}, which ${unknown.length === 1 ? "is not a registered command" : "are not registered commands"}.`);
+	}
 	#audit() {
 		if (!isDevelopment()) return;
 		for (const id of this.#order) this.#warnAboutBindings(id);
+		this.#warnAboutUnknownOverrides();
 		this.#warnAboutConflicts();
 	}
 	#auditAdded(id) {
@@ -933,7 +1007,10 @@ var CommandRegistry = class {
 		for (const conflict of this.conflicts(this.#keymap.get(id), {
 			ignore: id,
 			scope
-		})) console.warn(`[@inklu/keys] "${id}" binds ${conflict.display}, which "${conflict.id}" already uses.`);
+		})) {
+			const winner = this.#scopeRank(conflict.id) > this.#scopeRank(id) ? conflict.id : id;
+			console.warn(`[@inklu/keys] "${id}" binds ${conflict.display}, which "${conflict.id}" already uses. While both are runnable the key goes to "${winner}".`);
+		}
 	}
 };
 function describeBinding(binding) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklu/keys",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A command system for the web — typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding, and platform-aware display.",
   "keywords": [
     "keyboard",