zidane-ui 0.0.0-stage → 9.0.2

package/dist/keybindings/headless/index.d.ts

@@ -0,0 +1,7 @@
+import { DEFAULT_KEYBINDINGS, KEYBINDING_DEFS, KEYBINDING_DEF_BY_ACTION, KeyAction, KeyBindingDef, KeyBindings, ParsedBinding, bindingAlternatives, parseBindingSpec, parseBindingSpecs } from "./catalog.js";
+import { KeyCommandRegistry, KeyCommandSlot, KeyCommands, createKeyCommandRegistry } from "./commands.js";
+import { KeyOverrides, KeybindingsHost } from "./host.js";
+import { KeybindingOverridesState, createKeybindingOverrides, filterOverrides, getMergedKeybindings } from "./overrides.js";
+import { KEYSCOPE_ATTR, KeyScope, bindingAllowedIn, isTypingFocused, isTypingTarget, keyScopeOf } from "./key-scope.js";
+import { DEFAULT_KEYBINDINGS_LABELS, KeybindingsLabels } from "./labels.js";
+export { DEFAULT_KEYBINDINGS, DEFAULT_KEYBINDINGS_LABELS, KEYBINDING_DEFS, KEYBINDING_DEF_BY_ACTION, KEYSCOPE_ATTR, KeyAction, KeyBindingDef, KeyBindings, KeyCommandRegistry, KeyCommandSlot, KeyCommands, KeyOverrides, KeyScope, KeybindingOverridesState, KeybindingsHost, KeybindingsLabels, type ParsedBinding, bindingAllowedIn, bindingAlternatives, createKeyCommandRegistry, createKeybindingOverrides, filterOverrides, getMergedKeybindings, isTypingFocused, isTypingTarget, keyScopeOf, parseBindingSpec, parseBindingSpecs };

package/dist/keybindings/headless/index.js

@@ -0,0 +1,6 @@
+import { DEFAULT_KEYBINDINGS, KEYBINDING_DEFS, KEYBINDING_DEF_BY_ACTION, bindingAlternatives, parseBindingSpec, parseBindingSpecs } from "./catalog.js";
+import { createKeyCommandRegistry } from "./commands.js";
+import { createKeybindingOverrides, filterOverrides, getMergedKeybindings } from "./overrides.js";
+import { KEYSCOPE_ATTR, bindingAllowedIn, isTypingFocused, isTypingTarget, keyScopeOf } from "./key-scope.js";
+import { DEFAULT_KEYBINDINGS_LABELS } from "./labels.js";
+export { DEFAULT_KEYBINDINGS, DEFAULT_KEYBINDINGS_LABELS, KEYBINDING_DEFS, KEYBINDING_DEF_BY_ACTION, KEYSCOPE_ATTR, bindingAllowedIn, bindingAlternatives, createKeyCommandRegistry, createKeybindingOverrides, filterOverrides, getMergedKeybindings, isTypingFocused, isTypingTarget, keyScopeOf, parseBindingSpec, parseBindingSpecs };

package/dist/keybindings/headless/key-scope.d.ts

@@ -0,0 +1,37 @@
+import { ParsedBinding } from "zidane/chat/pure";
+//#region src/keybindings/headless/key-scope.d.ts
+/** Who owns a key press: the code editor, a text field, an open menu, or the app. */
+type KeyScope = 'editor' | 'input' | 'menu' | 'app';
+/** The attribute an editor host sets (`data-zg-keyscope="editor"`) to own its keys. */
+declare const KEYSCOPE_ATTR = "data-zg-keyscope";
+/**
+ * Who owns a key press, from its composed path.
+ *
+ * @param event - The key event.
+ */
+declare function keyScopeOf(event: Event): KeyScope;
+/**
+ * True when the key press belongs to a surface the user is typing in.
+ *
+ * @param event - The key event.
+ */
+declare function isTypingTarget(event: Event): boolean;
+/**
+ * True when the focused element takes the user's typing, so moving focus
+ * would swallow keystrokes. Walks into shadow roots (the editor's host is
+ * `document.activeElement` while its inner content holds the caret).
+ */
+declare function isTypingFocused(): boolean;
+/**
+ * Whether an app-level binding may fire under `scope`. In the editor,
+ * `ctrl+<letter>` without shift belongs to the editor (movement and
+ * editing chords); everything with shift, meta or a non-letter key is an
+ * app intent (settings, panels, zoom).
+ *
+ * @param scope - Who owns the press.
+ * @param spec - The binding.
+ * @param action - The binding's action (`closeTab` fires everywhere).
+ */
+declare function bindingAllowedIn(scope: KeyScope, spec: ParsedBinding, action?: string): boolean;
+//#endregion
+export { KEYSCOPE_ATTR, KeyScope, bindingAllowedIn, isTypingFocused, isTypingTarget, keyScopeOf };

package/dist/keybindings/headless/key-scope.js

@@ -0,0 +1,70 @@
+//#region src/keybindings/headless/key-scope.ts
+/** The attribute an editor host sets (`data-zg-keyscope="editor"`) to own its keys. */
+const KEYSCOPE_ATTR = "data-zg-keyscope";
+const MENU_SELECTOR = "[role=\"menu\"], [role=\"listbox\"], [role=\"dialog\"], [data-radix-popper-content-wrapper]";
+/**
+* Who owns a key press, from its composed path.
+*
+* @param event - The key event.
+*/
+function keyScopeOf(event) {
+	let inner = null;
+	for (const node of event.composedPath()) {
+		if (!(node instanceof HTMLElement)) continue;
+		if (node.getAttribute("data-zg-keyscope") === "editor") return "editor";
+		if (inner) continue;
+		const tag = node.tagName;
+		if (tag === "INPUT" || tag === "TEXTAREA" || node.isContentEditable) inner = "input";
+		else if (node.matches(MENU_SELECTOR)) inner = "menu";
+	}
+	return inner ?? "app";
+}
+/**
+* True when the key press belongs to a surface the user is typing in.
+*
+* @param event - The key event.
+*/
+function isTypingTarget(event) {
+	const scope = keyScopeOf(event);
+	return scope === "editor" || scope === "input";
+}
+/** Tags that take typed input; a focused webview or iframe owns its own keys. */
+const TYPING_TAGS = /* @__PURE__ */ new Set([
+	"INPUT",
+	"TEXTAREA",
+	"SELECT",
+	"WEBVIEW",
+	"IFRAME"
+]);
+/**
+* True when the focused element takes the user's typing, so moving focus
+* would swallow keystrokes. Walks into shadow roots (the editor's host is
+* `document.activeElement` while its inner content holds the caret).
+*/
+function isTypingFocused() {
+	let el = document.activeElement;
+	while (el) {
+		if (el instanceof HTMLElement) {
+			if (el.closest(`[data-zg-keyscope="editor"]`) || el.isContentEditable || TYPING_TAGS.has(el.tagName)) return true;
+		}
+		el = el.shadowRoot?.activeElement ?? null;
+	}
+	return false;
+}
+/**
+* Whether an app-level binding may fire under `scope`. In the editor,
+* `ctrl+<letter>` without shift belongs to the editor (movement and
+* editing chords); everything with shift, meta or a non-letter key is an
+* app intent (settings, panels, zoom).
+*
+* @param scope - Who owns the press.
+* @param spec - The binding.
+* @param action - The binding's action (`closeTab` fires everywhere).
+*/
+function bindingAllowedIn(scope, spec, action) {
+	if (scope !== "editor") return true;
+	if (action === "closeTab") return true;
+	return !(spec.ctrl && !spec.shift && !spec.meta && !spec.alt && /^[a-z]$/i.test(spec.name));
+}
+//#endregion
+export { KEYSCOPE_ATTR, bindingAllowedIn, isTypingFocused, isTypingTarget, keyScopeOf };

package/dist/keybindings/headless/labels.d.ts

@@ -0,0 +1,15 @@
+//#region src/keybindings/headless/labels.d.ts
+/**
+ * The keybindings components' strings. One flat dictionary an app overrides
+ * with `<LabelsProvider>` or the `labels` prop of `KeybindingsProvider`.
+ * Keys you leave out keep the default English label.
+ */
+/** The default English strings of the keybindings components. */
+declare const DEFAULT_KEYBINDINGS_LABELS: {
+  /** Between two alternative chords of one binding (`⌃W or ⌘W`). */
+  keyHintOr: string;
+};
+/** The shape of the keybindings label dictionary. */
+type KeybindingsLabels = typeof DEFAULT_KEYBINDINGS_LABELS;
+//#endregion
+export { DEFAULT_KEYBINDINGS_LABELS, KeybindingsLabels };

package/dist/keybindings/headless/labels.js

@@ -0,0 +1,12 @@
+//#region src/keybindings/headless/labels.ts
+/**
+* The keybindings components' strings. One flat dictionary an app overrides
+* with `<LabelsProvider>` or the `labels` prop of `KeybindingsProvider`.
+* Keys you leave out keep the default English label.
+*/
+/** The default English strings of the keybindings components. */
+const DEFAULT_KEYBINDINGS_LABELS = { 
+/** Between two alternative chords of one binding (`⌃W or ⌘W`). */
+keyHintOr: "or" };
+//#endregion
+export { DEFAULT_KEYBINDINGS_LABELS };

package/dist/keybindings/headless/overrides.d.ts

@@ -0,0 +1,34 @@
+import { Readable } from "../../chat/headless/store.js";
+import { KeyBindings } from "./catalog.js";
+import { KeyOverrides } from "./host.js";
+//#region src/keybindings/headless/overrides.d.ts
+/**
+ * The known actions of a stored map, each with a non-empty spec. Entries a future build wrote are dropped, so the
+ * matcher never parses them.
+ *
+ * @param raw - What was stored (anything).
+ */
+declare function filterOverrides(raw: unknown): KeyOverrides;
+/** A host's overrides store and the read that fills it. */
+interface KeybindingOverridesState {
+  /** The overrides: `{}` until read. */
+  overrides: Readable<KeyOverrides>;
+  /** Reads them, keeps the known actions and announces them (also when unchanged). A failed read is none. */
+  refresh(): Promise<void>;
+}
+/**
+ * The overrides store over a read: what a host's `overrides` and `refresh` are.
+ *
+ * @param read - Reads the stored map (rejects or answers nothing when there is none).
+ */
+declare function createKeybindingOverrides(read: () => Promise<unknown>): KeybindingOverridesState;
+/**
+ * The bindings in effect: `DEFAULT_KEYBINDINGS` with the host's overrides on top.
+ *
+ * @param host - The host whose overrides apply; none: the defaults.
+ */
+declare function getMergedKeybindings(host?: {
+  overrides: Readable<KeyOverrides>;
+} | null): KeyBindings;
+//#endregion
+export { KeybindingOverridesState, createKeybindingOverrides, filterOverrides, getMergedKeybindings };

package/dist/keybindings/headless/overrides.js

@@ -0,0 +1,55 @@
+import { DEFAULT_KEYBINDINGS } from "./catalog.js";
+import { writable } from "../../chat/headless/store.js";
+//#region src/keybindings/headless/overrides.ts
+/**
+* The overrides model every `KeybindingsHost` shares: read the stored map,
+* keep the known actions, announce it, and layer it over the defaults.
+*/
+/**
+* The known actions of a stored map, each with a non-empty spec. Entries a future build wrote are dropped, so the
+* matcher never parses them.
+*
+* @param raw - What was stored (anything).
+*/
+function filterOverrides(raw) {
+	const next = raw && typeof raw === "object" ? raw : void 0;
+	const filtered = {};
+	for (const action of Object.keys(DEFAULT_KEYBINDINGS)) {
+		const spec = next?.[action];
+		if (typeof spec === "string" && spec.trim()) filtered[action] = spec;
+	}
+	return filtered;
+}
+/**
+* The overrides store over a read: what a host's `overrides` and `refresh` are.
+*
+* @param read - Reads the stored map (rejects or answers nothing when there is none).
+*/
+function createKeybindingOverrides(read) {
+	const store = writable({});
+	return {
+		overrides: store,
+		async refresh() {
+			let next;
+			try {
+				next = filterOverrides(await read());
+			} catch {
+				next = {};
+			}
+			store.set(next);
+		}
+	};
+}
+/**
+* The bindings in effect: `DEFAULT_KEYBINDINGS` with the host's overrides on top.
+*
+* @param host - The host whose overrides apply; none: the defaults.
+*/
+function getMergedKeybindings(host) {
+	return {
+		...DEFAULT_KEYBINDINGS,
+		...host?.overrides.get()
+	};
+}
+//#endregion
+export { createKeybindingOverrides, filterOverrides, getMergedKeybindings };

package/dist/keybindings/index.d.ts

@@ -0,0 +1,7 @@
+import { KeyCommandsProvider, KeyCommandsProviderProps, useKeyCommandActions, useKeyCommandRegistry, useKeyCommands } from "./KeyCommands.js";
+import { FooterHint, FooterHintProps, KeyHint, KeyHintProps } from "./KeyHint.js";
+import { KeybindingHandlers, KeybindingsProvider, KeybindingsProviderProps, bindKeyListeners, useKeybindings, useKeybindingsHost, useMergedKeybindings } from "./KeybindingsProvider.js";
+import { useHelpKey } from "./useHelpKey.js";
+import { matchesBinding } from "./match.js";
+import { useKeybindingsLabels } from "./useKeybindingsLabels.js";
+export { FooterHint, FooterHintProps, KeyCommandsProvider, KeyCommandsProviderProps, KeyHint, KeyHintProps, KeybindingHandlers, KeybindingsProvider, KeybindingsProviderProps, bindKeyListeners, matchesBinding, useHelpKey, useKeyCommandActions, useKeyCommandRegistry, useKeyCommands, useKeybindings, useKeybindingsHost, useKeybindingsLabels, useMergedKeybindings };

package/dist/keybindings/index.js

@@ -0,0 +1,7 @@
+import { matchesBinding } from "./match.js";
+import { KeybindingsProvider, bindKeyListeners, useKeybindings, useKeybindingsHost, useMergedKeybindings } from "./KeybindingsProvider.js";
+import { KeyCommandsProvider, useKeyCommandActions, useKeyCommandRegistry, useKeyCommands } from "./KeyCommands.js";
+import { useKeybindingsLabels } from "./useKeybindingsLabels.js";
+import { FooterHint, KeyHint } from "./KeyHint.js";
+import { useHelpKey } from "./useHelpKey.js";
+export { FooterHint, KeyCommandsProvider, KeyHint, KeybindingsProvider, bindKeyListeners, matchesBinding, useHelpKey, useKeyCommandActions, useKeyCommandRegistry, useKeyCommands, useKeybindings, useKeybindingsHost, useKeybindingsLabels, useMergedKeybindings };

package/dist/keybindings/load-once.d.ts

@@ -0,0 +1,6 @@
+import { KeybindingsHost } from "./headless/host.js";
+//#region src/keybindings/load-once.d.ts
+/** Reads a host's overrides the first time a dispatcher under it mounts. Internal: not exported from the entry. */
+declare function loadOnce(host: KeybindingsHost | null): void;
+//#endregion
+export { loadOnce };

package/dist/keybindings/load-once.js

@@ -0,0 +1,11 @@
+//#region src/keybindings/load-once.ts
+/** Hosts whose overrides were read once already (by the first dispatcher under them). */
+const loaded = /* @__PURE__ */ new WeakSet();
+/** Reads a host's overrides the first time a dispatcher under it mounts. Internal: not exported from the entry. */
+function loadOnce(host) {
+	if (!host || loaded.has(host)) return;
+	loaded.add(host);
+	host.refresh();
+}
+//#endregion
+export { loadOnce };

package/dist/keybindings/match.d.ts

@@ -0,0 +1,12 @@
+import { ParsedBinding } from "zidane/chat/pure";
+//#region src/keybindings/match.d.ts
+/**
+ * Whether a key event fires a binding. All declared modifiers must be pressed and no others, so `'o'` does not match
+ * `ctrl+o` and `'ctrl+o'` does not match `ctrl+shift+o`. A spec with alternatives (`ctrl+w | cmd+w`) matches any.
+ *
+ * @param event - The key event.
+ * @param spec - A spec string, or one parsed chord.
+ */
+declare function matchesBinding(event: KeyboardEvent, spec: string | ParsedBinding): boolean;
+//#endregion
+export { matchesBinding };

package/dist/keybindings/match.js

@@ -0,0 +1,33 @@
+import { PUNCTUATION_CODES, typesStandIn } from "../components/keyboard-layout.js";
+import { canonicalKeyName, parseBindingSpecs } from "zidane/chat/pure";
+//#region src/keybindings/match.ts
+/**
+* Matches a DOM `KeyboardEvent` against a binding spec.
+*/
+/**
+* Whether a key event fires a binding. All declared modifiers must be pressed and no others, so `'o'` does not match
+* `ctrl+o` and `'ctrl+o'` does not match `ctrl+shift+o`. A spec with alternatives (`ctrl+w | cmd+w`) matches any.
+*
+* @param event - The key event.
+* @param spec - A spec string, or one parsed chord.
+*/
+function matchesBinding(event, spec) {
+	if (typeof spec === "string") return parseBindingSpecs(spec).some((parsed) => matchesBinding(event, parsed));
+	const parsed = spec;
+	if (parsed.ctrl !== event.ctrlKey) return false;
+	if (parsed.shift !== event.shiftKey) return false;
+	if (parsed.alt !== event.altKey) return false;
+	if (parsed.meta !== event.metaKey) return false;
+	return canonicalKeyName(event.key) === parsed.name || matchesPhysicalKey(event, parsed.name);
+}
+/**
+* A punctuation key by its physical position (`event.code`), for layouts
+* where it types a stand-in there (`typesStandIn`, the rule keycap labels
+* share). Decided by the event alone, so a keypress matches the same way
+* every time; the keyboard layout map only labels keycaps.
+*/
+function matchesPhysicalKey(event, name) {
+	return PUNCTUATION_CODES[name]?.includes(event.code) === true && typesStandIn(event.key);
+}
+//#endregion
+export { matchesBinding };

package/dist/keybindings/testing/contract.d.ts

@@ -0,0 +1,37 @@
+import { KeybindingsHost } from "../headless/host.js";
+//#region src/keybindings/testing/contract.d.ts
+/** An optional `KeybindingsHost` member. */
+type KeybindingsHostCapability = 'save' | 'openInEditor' | 'location';
+/** What the backend behind the host holds. */
+interface KeybindingsHostContractBackend {
+  /** The stored overrides (action → spec, unknown actions and empty specs included), or `null`: none stored. */
+  stored: Readonly<Record<string, string>> | null;
+}
+/** Reads the backend and changes it from outside. */
+interface KeybindingsHostContractControl {
+  /** The overrides stored now, or `null`. */
+  stored(): Readonly<Record<string, string>> | null;
+  /** The user edited the stored overrides (`null` removes them). The host reads them on its next `refresh`. */
+  store(overrides: Readonly<Record<string, string>> | null): void;
+}
+/** A host built over a backend, the backend's control, and how to tear them down. */
+interface KeybindingsHostHarness {
+  /** The host under test. */
+  host: KeybindingsHost;
+  /** Reads and changes the backend. */
+  control: KeybindingsHostContractControl;
+  /** Closes listeners after each test. */
+  dispose?(): void;
+}
+/** Builds a fresh host (and its backend) for one test. */
+type KeybindingsHostHarnessFactory = (backend: KeybindingsHostContractBackend) => KeybindingsHostHarness | Promise<KeybindingsHostHarness>;
+/**
+ * Declares the shared `KeybindingsHost` suite for one implementation.
+ *
+ * @param name - The implementation's name, shown in the suite title.
+ * @param makeHarness - Builds a fresh host over a backend that holds what it is given, once per test.
+ * @param capabilities - The optional members the host offers. Every other optional member must be undefined.
+ */
+declare function describeKeybindingsHostContract(name: string, makeHarness: KeybindingsHostHarnessFactory, capabilities: readonly KeybindingsHostCapability[]): void;
+//#endregion
+export { KeybindingsHostCapability, KeybindingsHostContractBackend, KeybindingsHostContractControl, KeybindingsHostHarness, KeybindingsHostHarnessFactory, describeKeybindingsHostContract };

package/dist/keybindings/testing/contract.js

@@ -0,0 +1,101 @@
+import { DEFAULT_KEYBINDINGS } from "../headless/catalog.js";
+import { getMergedKeybindings } from "../headless/overrides.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+//#region src/keybindings/testing/contract.ts
+/**
+* What every `KeybindingsHost` implementation does alike, as a vitest suite: the in-memory fixture
+* (`createFixtureKeybindingsHost`), the browser one (`createBrowserKeybindingsHost`), the desktop app's.
+*
+* An implementation's test calls {@link describeKeybindingsHostContract} with a harness factory. The
+* contract hands it a {@link KeybindingsHostContractBackend}: the overrides stored (or none at all).
+* The harness builds the host over a backend that holds them, and returns a
+* {@link KeybindingsHostContractControl} that reads the backend and changes it from outside (the user
+* edited the file). The capabilities list says which optional members the host offers: the suite
+* checks the others are left out (undefined, never a throwing stub) and skips what needs them.
+*
+*   describeKeybindingsHostContract('createBrowserKeybindingsHost', (backend) => ({ host, control }), [
+*     'save',
+*   ]);
+*/
+const CAPABILITIES = [
+	"save",
+	"openInEditor",
+	"location"
+];
+const STORED = {
+	openPalette: "cmd+p",
+	closeTab: "  ",
+	notAnAction: "ctrl+q"
+};
+/**
+* Declares the shared `KeybindingsHost` suite for one implementation.
+*
+* @param name - The implementation's name, shown in the suite title.
+* @param makeHarness - Builds a fresh host over a backend that holds what it is given, once per test.
+* @param capabilities - The optional members the host offers. Every other optional member must be undefined.
+*/
+function describeKeybindingsHostContract(name, makeHarness, capabilities) {
+	const has = (capability) => capabilities.includes(capability);
+	describe(`KeybindingsHost contract: ${name}`, () => {
+		const cleanup = [];
+		afterEach(() => {
+			for (const done of cleanup.splice(0).reverse()) done();
+		});
+		const setup = async (stored = STORED) => {
+			const harness = await makeHarness({ stored });
+			cleanup.push(() => harness.dispose?.());
+			return harness;
+		};
+		it("offers exactly its capabilities; the members it leaves out are undefined", async () => {
+			const { host } = await setup();
+			expect(typeof host.overrides.get).toBe("function");
+			expect(typeof host.refresh).toBe("function");
+			for (const capability of CAPABILITIES) expect(typeof host[capability], capability).toBe(has(capability) ? "function" : "undefined");
+		});
+		it("reads nothing until refreshed, then the known actions with a spec", async () => {
+			const { host } = await setup();
+			expect(host.overrides.get()).toEqual({});
+			await host.refresh();
+			expect(host.overrides.get()).toEqual({ openPalette: "cmd+p" });
+			expect(getMergedKeybindings(host)).toEqual({
+				...DEFAULT_KEYBINDINGS,
+				openPalette: "cmd+p"
+			});
+		});
+		it("reads none when nothing is stored, and never rejects", async () => {
+			const { host } = await setup(null);
+			await expect(host.refresh()).resolves.toBeUndefined();
+			expect(host.overrides.get()).toEqual({});
+		});
+		it("a refresh picks up an edit and tells subscribers, also when nothing changed", async () => {
+			const { host, control } = await setup();
+			const seen = vi.fn();
+			cleanup.push(host.overrides.subscribe(seen));
+			await host.refresh();
+			expect(seen).toHaveBeenCalledTimes(1);
+			control.store({ toggleSidebar: "ctrl+b" });
+			await host.refresh();
+			expect(host.overrides.get()).toEqual({ toggleSidebar: "ctrl+b" });
+			expect(seen).toHaveBeenCalledTimes(2);
+			control.store(null);
+			await host.refresh();
+			expect(host.overrides.get()).toEqual({});
+		});
+		it.skipIf(!has("save"))("save replaces the stored overrides and the store follows", async () => {
+			const { host, control } = await setup();
+			await host.save({ newSession: "cmd+n" });
+			expect(host.overrides.get()).toEqual({ newSession: "cmd+n" });
+			expect(control.stored()).toEqual({ newSession: "cmd+n" });
+		});
+		it.skipIf(!has("location"))("says where the overrides live", async () => {
+			const { host } = await setup();
+			expect(typeof await host.location()).toBe("string");
+		});
+		it.skipIf(!has("openInEditor"))("opens them in an editor", async () => {
+			const { host } = await setup();
+			await expect(host.openInEditor()).resolves.toBeUndefined();
+		});
+	});
+}
+//#endregion
+export { describeKeybindingsHostContract };

package/dist/keybindings/testing/index.d.ts

@@ -0,0 +1,2 @@
+import { FixtureKeybindingsControl, FixtureKeybindingsHost, FixtureKeybindingsOptions, createFixtureKeybindingsHost } from "../headless/fixture-host.js";
+export { FixtureKeybindingsControl, FixtureKeybindingsHost, FixtureKeybindingsOptions, createFixtureKeybindingsHost };

package/dist/keybindings/testing/index.js

@@ -0,0 +1 @@
+export { createFixtureKeybindingsHost } from "../headless/fixture-host.js";

package/dist/keybindings/useHelpKey.d.ts

@@ -0,0 +1,10 @@
+//#region src/keybindings/useHelpKey.d.ts
+/**
+ * Calls `onOpen` on a bare `?` outside fields. The listener attaches once; both callbacks are read at press time.
+ *
+ * @param onOpen - Opens the shortcut reference. Absent: nothing listens.
+ * @param blocked - Whether something else owns input now (a modal is open).
+ */
+declare function useHelpKey(onOpen: (() => void) | undefined, blocked?: () => boolean): void;
+//#endregion
+export { useHelpKey };

package/dist/keybindings/useHelpKey.js

@@ -0,0 +1,41 @@
+import { isTypingTarget } from "./headless/key-scope.js";
+import { useEffect, useRef } from "react";
+//#region src/keybindings/useHelpKey.ts
+/**
+* `?` opens the shortcut reference. A plain window listener, not a catalog
+* action: `?` is a convenience outside the shared catalog. `e.key === '?'`
+* covers `Shift+/` on every layout (the browser resolves the layout before
+* the keydown lands). Typing `?` in a field never opens it, and neither does
+* a press while a modal is open (`blocked`), so a bare `?` never swaps a
+* modal out mid-edit.
+*/
+/**
+* Calls `onOpen` on a bare `?` outside fields. The listener attaches once; both callbacks are read at press time.
+*
+* @param onOpen - Opens the shortcut reference. Absent: nothing listens.
+* @param blocked - Whether something else owns input now (a modal is open).
+*/
+function useHelpKey(onOpen, blocked) {
+	const latest = useRef({
+		onOpen,
+		blocked
+	});
+	latest.current = {
+		onOpen,
+		blocked
+	};
+	const on = Boolean(onOpen);
+	useEffect(() => {
+		if (!on) return void 0;
+		const onKey = (e) => {
+			if (e.key !== "?" || latest.current.blocked?.()) return;
+			if (isTypingTarget(e)) return;
+			e.preventDefault();
+			latest.current.onOpen?.();
+		};
+		window.addEventListener("keydown", onKey);
+		return () => window.removeEventListener("keydown", onKey);
+	}, [on]);
+}
+//#endregion
+export { useHelpKey };

package/dist/keybindings/useKeybindingsLabels.d.ts

@@ -0,0 +1,6 @@
+import { KeybindingsLabels } from "./headless/labels.js";
+//#region src/keybindings/useKeybindingsLabels.d.ts
+/** Returns the keybindings components' strings: the defaults merged with any overrides. */
+declare function useKeybindingsLabels(): KeybindingsLabels;
+//#endregion
+export { useKeybindingsLabels };

package/dist/keybindings/useKeybindingsLabels.js

@@ -0,0 +1,18 @@
+import { useLabels } from "../labels.js";
+import { DEFAULT_KEYBINDINGS_LABELS } from "./headless/labels.js";
+import { useMemo } from "react";
+//#region src/keybindings/useKeybindingsLabels.ts
+/**
+* The keybindings components' labels: the defaults, overridable through
+* `<LabelsProvider>` or `KeybindingsProvider`'s `labels`.
+*/
+/** Returns the keybindings components' strings: the defaults merged with any overrides. */
+function useKeybindingsLabels() {
+	const overrides = useLabels();
+	return useMemo(() => ({
+		...DEFAULT_KEYBINDINGS_LABELS,
+		...overrides
+	}), [overrides]);
+}
+//#endregion
+export { useKeybindingsLabels };