@kerfjs/ui 4.4.1 → 4.5.0-beta.1

package/dist/wire-sidebar.js

@@ -0,0 +1,128 @@
+import { effect, delegate } from 'kerfjs';
+
+// src/wire-sidebar.ts
+var FOCUSABLE = 'a[href],area[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+function focusables(panel) {
+  return [...panel.querySelectorAll(FOCUSABLE)];
+}
+function defaultStorage() {
+  try {
+    return globalThis.localStorage ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function wireSidebar(root, { panels, deviceClass, storage = defaultStorage() }) {
+  const ownerDocument = root.ownerDocument;
+  const byAction = new Map(panels.map((panel) => [panel.toggleAction, panel]));
+  const returnFocus = /* @__PURE__ */ new Map();
+  const disposers = [];
+  for (const panel of panels) {
+    if (!panel.storageKey || !storage) continue;
+    const stored = storage.getItem(panel.storageKey);
+    if (stored === "true" || stored === "false")
+      panel.collapsed.value = stored === "true";
+    disposers.push(
+      effect(() => {
+        storage.setItem(panel.storageKey, String(panel.collapsed.value));
+      })
+    );
+  }
+  const panelElement = (id) => root.querySelector(`[data-collapsible-panel="${id}"]`);
+  const collapse = (panel) => {
+    if (panel.collapsed.value) return;
+    panel.collapsed.value = true;
+  };
+  disposers.push(
+    delegate(root, "click", "[data-action]", (_event, element) => {
+      const trigger = element;
+      const panel = byAction.get(trigger.dataset.action ?? "");
+      if (!panel) return;
+      returnFocus.set(panel.id, trigger);
+      panel.collapsed.value = !panel.collapsed.value;
+    })
+  );
+  for (const panel of panels) {
+    let previous = panel.collapsed.value;
+    disposers.push(
+      effect(() => {
+        const collapsed = panel.collapsed.value;
+        if (collapsed === previous) return;
+        previous = collapsed;
+        const element = panelElement(panel.id);
+        if (!collapsed && element) {
+          (focusables(element)[0] ?? element).focus();
+        } else if (collapsed) {
+          returnFocus.get(panel.id)?.focus();
+        }
+      })
+    );
+  }
+  if (deviceClass) {
+    let backdrop;
+    const openPanel = () => panels.find((panel) => !panel.collapsed.value);
+    const removeBackdrop = () => {
+      backdrop?.remove();
+      backdrop = void 0;
+    };
+    disposers.push(
+      effect(() => {
+        const compact = deviceClass.value.compact;
+        const open = compact ? openPanel() : void 0;
+        root.dataset.collapsibleOverlay = String(compact);
+        if (compact && open) {
+          if (!backdrop) {
+            backdrop = ownerDocument.createElement("button");
+            backdrop.type = "button";
+            backdrop.className = "kui-collapsible-panel__backdrop";
+            backdrop.setAttribute("aria-label", "Close");
+            backdrop.addEventListener("click", () => collapse(open));
+            const element = panelElement(open.id);
+            element?.parentElement?.insertBefore(backdrop, element);
+          }
+        } else {
+          removeBackdrop();
+          if (!compact) delete root.dataset.collapsibleOverlay;
+        }
+      })
+    );
+    const onKeydown = (event) => {
+      if (!deviceClass.value.compact) return;
+      const open = openPanel();
+      if (!open) return;
+      if (event.key === "Escape") {
+        event.preventDefault();
+        collapse(open);
+        return;
+      }
+      if (event.key !== "Tab") return;
+      const element = panelElement(open.id);
+      if (!element) return;
+      const items = focusables(element);
+      if (items.length === 0) return;
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = ownerDocument.activeElement;
+      if (event.shiftKey && active === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    ownerDocument.addEventListener("keydown", onKeydown);
+    disposers.push(
+      () => ownerDocument.removeEventListener("keydown", onKeydown)
+    );
+    disposers.push(removeBackdrop);
+  }
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose();
+    delete root.dataset.collapsibleOverlay;
+  };
+}
+
+export { wireSidebar };
+
+//# sourceMappingURL=wire-sidebar.js.map

package/dist/wire-sidebar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-sidebar.ts"],"names":[],"mappings":"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","file":"wire-sidebar.js","sourcesContent":["import { delegate, effect, type ReadonlySignal, type Signal } from 'kerfjs';\n\nimport type { DeviceClass } from './device-class.js';\n\n/** Minimal `localStorage`-shaped store, so the persistence hook is testable. */\nexport interface SidebarStorage {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n}\n\nexport interface WireSidebarPanel {\n  /** The panel id — matches `CollapsiblePanel`'s `id` and a toggle's `panelId`. */\n  id: string;\n  /** The app-owned collapsed signal. `wireSidebar` reads it (focus, overlay) and\n   *  writes it (toggle, Escape, backdrop, persistence). */\n  collapsed: Signal<boolean>;\n  /** `data-action` value the panel's toggle button(s) carry. */\n  toggleAction: string;\n  /** When set, the collapsed state is loaded from and saved to `storage` under\n   *  this key (a persistence hook), so the panel remembers its state. */\n  storageKey?: string;\n}\n\nexport interface WireSidebarOptions {\n  panels: readonly WireSidebarPanel[];\n  /**\n   * When provided, the sidebar adopts a compact **overlay** presentation while\n   * `deviceClass.compact` is true: an open panel floats over the content with a\n   * dismissable backdrop, Escape and backdrop-click collapse it, and focus is\n   * trapped within the open panel (the ARIA dialog pattern). Without it the panel\n   * is always inline.\n   */\n  deviceClass?: ReadonlySignal<DeviceClass>;\n  /** Persistence store (default `globalThis.localStorage`, if present). */\n  storage?: SidebarStorage;\n}\n\nconst FOCUSABLE =\n  'a[href],area[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\nfunction focusables(panel: HTMLElement): HTMLElement[] {\n  // Focus only ever targets an OPEN panel, so the selector (which already drops\n  // disabled controls and tabindex=\"-1\") is sufficient without a layout-based\n  // visibility check that a headless DOM can't answer.\n  return [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];\n}\n\nfunction defaultStorage(): SidebarStorage | undefined {\n  try {\n    return globalThis.localStorage ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The reusable sidebar-semantics layer for {@link CollapsiblePanel}s: toggle\n * delegation with focus restore, focus-into on open, an optional compact overlay\n * (backdrop + Escape + focus trap) driven by {@link deviceClass}, and an optional\n * persistence hook. The app owns each `collapsed` signal and the layout; this wire\n * owns the interaction. Returns a disposer. See `docs/24-collapsible-panel.md`.\n */\nexport function wireSidebar(\n  root: HTMLElement,\n  { panels, deviceClass, storage = defaultStorage() }: WireSidebarOptions,\n): () => void {\n  const ownerDocument = root.ownerDocument;\n  const byAction = new Map(panels.map((panel) => [panel.toggleAction, panel]));\n  const returnFocus = new Map<string, HTMLElement>();\n  const disposers: Array<() => void> = [];\n\n  // Persistence: seed from storage, then mirror on change.\n  for (const panel of panels) {\n    if (!panel.storageKey || !storage) continue;\n    const stored = storage.getItem(panel.storageKey);\n    if (stored === 'true' || stored === 'false')\n      panel.collapsed.value = stored === 'true';\n    disposers.push(\n      effect(() => {\n        storage.setItem(panel.storageKey!, String(panel.collapsed.value));\n      }),\n    );\n  }\n\n  const panelElement = (id: string): HTMLElement | null =>\n    root.querySelector<HTMLElement>(`[data-collapsible-panel=\"${id}\"]`);\n\n  const collapse = (panel: WireSidebarPanel): void => {\n    if (panel.collapsed.value) return;\n    panel.collapsed.value = true;\n  };\n\n  // Toggle delegation. The trigger is remembered so focus restores to it on close.\n  disposers.push(\n    delegate(root, 'click', '[data-action]', (_event, element) => {\n      const trigger = element as HTMLElement;\n      const panel = byAction.get(trigger.dataset.action ?? '');\n      if (!panel) return;\n      returnFocus.set(panel.id, trigger);\n      panel.collapsed.value = !panel.collapsed.value;\n    }),\n  );\n\n  // Focus: move into the panel when it opens; restore to the trigger when it closes.\n  for (const panel of panels) {\n    let previous = panel.collapsed.value;\n    disposers.push(\n      effect(() => {\n        const collapsed = panel.collapsed.value;\n        if (collapsed === previous) return;\n        previous = collapsed;\n        const element = panelElement(panel.id);\n        if (!collapsed && element) {\n          (focusables(element)[0] ?? element).focus();\n        } else if (collapsed) {\n          returnFocus.get(panel.id)?.focus();\n        }\n      }),\n    );\n  }\n\n  // Compact overlay: a dismissable backdrop + Escape + focus trap while compact\n  // and a panel is open.\n  if (deviceClass) {\n    let backdrop: HTMLButtonElement | undefined;\n    const openPanel = (): WireSidebarPanel | undefined =>\n      panels.find((panel) => !panel.collapsed.value);\n    const removeBackdrop = (): void => {\n      backdrop?.remove();\n      backdrop = undefined;\n    };\n    disposers.push(\n      effect(() => {\n        const compact = deviceClass.value.compact;\n        const open = compact ? openPanel() : undefined;\n        root.dataset.collapsibleOverlay = String(compact);\n        if (compact && open) {\n          if (!backdrop) {\n            backdrop = ownerDocument.createElement('button');\n            backdrop.type = 'button';\n            backdrop.className = 'kui-collapsible-panel__backdrop';\n            backdrop.setAttribute('aria-label', 'Close');\n            backdrop.addEventListener('click', () => collapse(open));\n            const element = panelElement(open.id);\n            element?.parentElement?.insertBefore(backdrop, element);\n          }\n        } else {\n          removeBackdrop();\n          if (!compact) delete root.dataset.collapsibleOverlay;\n        }\n      }),\n    );\n\n    const onKeydown = (event: KeyboardEvent): void => {\n      if (!deviceClass.value.compact) return;\n      const open = openPanel();\n      if (!open) return;\n      if (event.key === 'Escape') {\n        event.preventDefault();\n        collapse(open);\n        return;\n      }\n      if (event.key !== 'Tab') return;\n      const element = panelElement(open.id);\n      if (!element) return;\n      const items = focusables(element);\n      if (items.length === 0) return;\n      const first = items[0]!;\n      const last = items[items.length - 1]!;\n      const active = ownerDocument.activeElement;\n      if (event.shiftKey && active === first) {\n        event.preventDefault();\n        last.focus();\n      } else if (!event.shiftKey && active === last) {\n        event.preventDefault();\n        first.focus();\n      }\n    };\n    ownerDocument.addEventListener('keydown', onKeydown);\n    disposers.push(() =>\n      ownerDocument.removeEventListener('keydown', onKeydown),\n    );\n    disposers.push(removeBackdrop);\n  }\n\n  return () => {\n    for (const dispose of disposers.splice(0)) dispose();\n    delete root.dataset.collapsibleOverlay;\n  };\n}\n"]}

package/dist/wire-tab-bars.d.ts

@@ -1,3 +1,6 @@
+import { TabActivation } from './tab-bar.js';
+import 'kerfjs';
+
 type TabReorderSource = 'pointer' | 'keyboard';
 type TabDropPosition = 'before' | 'after';
 interface TabReorder {
@@ -7,11 +10,24 @@ interface TabReorder {
     position: TabDropPosition;
     source: TabReorderSource;
 }
+
 interface WireTabBarsOptions {
     onReorder: (change: TabReorder) => void;
+    /**
+     * How arrow / Home / End keys activate tabs (default `'automatic'`):
+     * - `'automatic'` moves roving focus **and** selects the focused tab (clicks it).
+     * - `'manual'` moves roving focus only; the user selects with Enter / Space / click
+     *   (the ARIA Tabs manual-activation pattern). Use this when activation is a heavy or
+     *   side-effecting action (e.g. a tab that loads a project) so arrowing through the
+     *   strip doesn't trigger it on every tab.
+     *
+     * A per-bar `data-tab-activation="manual" | "automatic"` attribute (see the `TabBar`
+     * `activation` prop) overrides this option for that strip.
+     */
+    activation?: TabActivation;
 }
 declare function reorderTabs<T>(items: readonly T[], getId: (item: T) => string, sourceId: string, targetId: string, position: TabDropPosition): T[];
 /** Wire reordering and keyboard navigation while leaving controlled state in the application. */
-declare function wireTabBars(root: HTMLElement | Document, { onReorder }: WireTabBarsOptions): () => void;
+declare function wireTabBars(root: HTMLElement | Document, { onReorder, activation }: WireTabBarsOptions): () => void;
 
-export { type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
+export { TabActivation, type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };

package/dist/wire-tab-bars.js

@@ -1,3 +1,3 @@
-export { reorderTabs, wireTabBars } from './chunk-MQIZAD4A.js';
+export { reorderTabs, wireTabBars } from './chunk-UKKSMZYT.js';
 
 //# sourceMappingURL=wire-tab-bars.js.map

package/dist/wire-tab-scaffold.d.ts

@@ -0,0 +1,11 @@
+interface WireTabScaffoldOptions {
+    /** Invoked with the selected tab id when a bottom-bar tab is activated. */
+    onSelect: (tabId: string) => void;
+}
+/**
+ * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its
+ * id (the app then updates its controlled `active`). Returns a disposer.
+ */
+declare function wireTabScaffold(root: Element, options: WireTabScaffoldOptions): () => void;
+
+export { type WireTabScaffoldOptions, wireTabScaffold };

package/dist/wire-tab-scaffold.js

@@ -0,0 +1,21 @@
+import { delegate } from 'kerfjs';
+
+// src/wire-tab-scaffold.ts
+function wireTabScaffold(root, options) {
+  const section = root.matches('[data-component="tab-scaffold"]') ? root : root.querySelector('[data-component="tab-scaffold"]');
+  if (!(section instanceof HTMLElement)) return () => {
+  };
+  return delegate(
+    section,
+    "click",
+    "[data-tab-scaffold-tab]",
+    (_event, target) => {
+      const tabId = target.getAttribute("data-tab-scaffold-tab");
+      if (tabId) options.onSelect(tabId);
+    }
+  );
+}
+
+export { wireTabScaffold };
+
+//# sourceMappingURL=wire-tab-scaffold.js.map

package/dist/wire-tab-scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-tab-scaffold.ts"],"names":[],"mappings":";;;AAWO,SAAS,eAAA,CACd,MACA,OAAA,EACY;AACZ,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,CAAQ,iCAAiC,IAC1D,IAAA,GACA,IAAA,CAAK,cAAc,iCAAiC,CAAA;AACxD,EAAA,IAAI,EAAE,OAAA,YAAmB,WAAA,CAAA,EAAc,OAAO,MAAM;AAAA,EAAC,CAAA;AACrD,EAAA,OAAO,QAAA;AAAA,IACL,OAAA;AAAA,IACA,OAAA;AAAA,IACA,yBAAA;AAAA,IACA,CAAC,QAAQ,MAAA,KAAW;AAClB,MAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,YAAA,CAAa,uBAAuB,CAAA;AACzD,MAAA,IAAI,KAAA,EAAO,OAAA,CAAQ,QAAA,CAAS,KAAK,CAAA;AAAA,IACnC;AAAA,GACF;AACF","file":"wire-tab-scaffold.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireTabScaffoldOptions {\n  /** Invoked with the selected tab id when a bottom-bar tab is activated. */\n  onSelect: (tabId: string) => void;\n}\n\n/**\n * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its\n * id (the app then updates its controlled `active`). Returns a disposer.\n */\nexport function wireTabScaffold(\n  root: Element,\n  options: WireTabScaffoldOptions,\n): () => void {\n  const section = root.matches('[data-component=\"tab-scaffold\"]')\n    ? root\n    : root.querySelector('[data-component=\"tab-scaffold\"]');\n  if (!(section instanceof HTMLElement)) return () => {};\n  return delegate(\n    section,\n    'click',\n    '[data-tab-scaffold-tab]',\n    (_event, target) => {\n      const tabId = target.getAttribute('data-tab-scaffold-tab');\n      if (tabId) options.onSelect(tabId);\n    },\n  );\n}\n"]}

package/dist/wire-token-search-fields.d.ts

@@ -0,0 +1,111 @@
+import { Signal } from 'kerfjs';
+
+interface TokenSearchSubmit {
+    id: string;
+    editor: HTMLElement;
+}
+/** Reported to {@link WireTokenSearchFieldsOptions.onEdit} on every editor input. */
+interface TokenSearchEdit extends TokenSearchSubmit {
+    /**
+     * The `InputEvent` that mutated the editor — read `event.inputType` / `event.data`
+     * to gate commit behavior (e.g. only parse a chip on whitespace-terminated input)
+     * without keeping a separate `input` listener.
+     */
+    event: InputEvent;
+}
+/** Reported when adjacent-token keyboard deletion asks the app to drop a chip. */
+interface TokenSearchTokenRemoval {
+    id: string;
+    /** The `data-token-value` of the token the app should remove from its state. */
+    value: string;
+    editor: HTMLElement;
+    /** `'backward'` = the token before the caret (Backspace); `'forward'` = after (Delete). */
+    direction: 'backward' | 'forward';
+}
+/**
+ * Opt-in keyboard behavior for the atomic token chips. Off unless `keyboard` is
+ * set; each piece defaults on once opted in. The helper never mutates app state:
+ * a removal is reported through {@link TokenSearchKeyboardOptions.onRemoveToken}
+ * for the caller to apply, while caret movement past a chip is a pure ephemeral
+ * mechanic the helper performs itself.
+ */
+interface TokenSearchKeyboardBaseOptions {
+    /**
+     * From a collapsed caret with no selection, Backspace removes the token
+     * immediately before it and Delete the token immediately after — reported via
+     * `onRemoveToken` — instead of deleting a character. Default: true.
+     */
+    /**
+     * ArrowRight moves the caret past a trailing atomic token so text typed next
+     * lands after the chip. Default: true.
+     */
+    moveCaretPastToken?: boolean;
+}
+type TokenSearchKeyboardOptions = TokenSearchKeyboardBaseOptions & ({
+    removeAdjacentToken?: true;
+    /** Apply the reported removal to your controlled state, then re-render. */
+    onRemoveToken: (removal: TokenSearchTokenRemoval) => void;
+} | {
+    removeAdjacentToken: false;
+    onRemoveToken?: never;
+});
+/**
+ * Managed collapsible behavior for the iconic TokenSearchField. Every piece is on
+ * by default; disable a specific one to own it in the app. Provide `signals` to
+ * drive app-owned `expanded` signals per field id instead of helper-created ones.
+ */
+interface TokenSearchCollapsibleOptions {
+    /** Expand the field and focus its editor when the iconic trigger is activated. Default: true. */
+    expandOnActivate?: boolean;
+    /** Collapse the field when focus leaves it while it is empty. Default: true. */
+    collapseOnEmptyBlur?: boolean;
+    /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
+    collapseOnEscape?: boolean;
+    /** Focus the editor on expand/controlled clear and the trigger on Escape-collapse. Default: true. */
+    manageFocus?: boolean;
+    /**
+     * Keep an empty field expanded when focus moves to a caller-owned surface
+     * rendered outside the field — a suggestions dropdown, date picker, or help
+     * popover shown beside it. Return true for any focus target that must NOT
+     * trigger collapse-on-empty-blur. An element carrying `data-token-search-keep-open`
+     * (or any node inside one) is always exempt, so this predicate is only needed
+     * for surfaces you cannot mark declaratively.
+     */
+    keepOpenOn?: (target: Node | null) => boolean;
+    /** App-owned `expanded` signals keyed by field id; adopted instead of helper-created. */
+    signals?: Readonly<Record<string, Signal<boolean>>>;
+}
+interface WireTokenSearchFieldsOptions {
+    onSubmit?: (submission: TokenSearchSubmit) => void;
+    /** Fired on every editor `input`, after the browser mutates it, so a caller can drop its own `input` listener. */
+    onEdit?: (edit: TokenSearchEdit) => void;
+    /** Managed collapsible transient behavior. `true`/omitted = on with defaults; `false` = fully off. */
+    collapsible?: boolean | TokenSearchCollapsibleOptions;
+    /** Opt-in atomic-chip keyboard behavior (off by default). */
+    keyboard?: false | TokenSearchKeyboardOptions;
+}
+/**
+ * The value returned from {@link wireTokenSearchFields}: call it (or `dispose()`) to
+ * tear down. When collapsible behavior is managed, it also exposes the transient
+ * `expanded` state per field id so the app can read it in render, hand in its own
+ * signal, or drive it imperatively.
+ */
+interface TokenSearchFieldsHandle {
+    (): void;
+    dispose(): void;
+    /** The managed `expanded` signal for a field id (adopted or helper-created); undefined when unmanaged. */
+    expanded(id: string): Signal<boolean> | undefined;
+    /** Expand the field (and, when focus is managed, focus its editor). */
+    open(id: string): void;
+    /** Collapse the field (and, when focus is managed, restore focus to its trigger). */
+    close(id: string): void;
+}
+/**
+ * Wire every TokenSearchField under `root`: submit on Enter, preserve the caret across
+ * controlled token deletion, and (by default) manage the collapsible field's transient
+ * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
+ * exposes the managed `expanded` state per field id.
+ */
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+
+export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };

package/dist/wire-token-search-fields.js

@@ -0,0 +1,5 @@
+export { wireTokenSearchFields } from './chunk-OJWWHFH3.js';
+
+
+
+//# sourceMappingURL=wire-token-search-fields.js.map

package/dist/wire-token-search-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-token-search-fields.js"}

package/dist/workbench.d.ts

@@ -0,0 +1,33 @@
+import { SafeHtml } from 'kerfjs';
+
+/** A collapsible Workbench panel — a side rail or the bottom drawer. */
+interface WorkbenchPanel {
+    content: SafeHtml;
+    /** Whether the panel is currently collapsed (the app owns this). */
+    collapsed?: boolean;
+    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    size?: number;
+    /** Accessible name for the panel region. */
+    label?: string;
+}
+interface WorkbenchProps {
+    id: string;
+    label: string;
+    /** The central work area. */
+    main: SafeHtml;
+    leftRail?: WorkbenchPanel;
+    rightRail?: WorkbenchPanel;
+    bottomDrawer?: WorkbenchPanel;
+    className?: string;
+}
+/**
+ * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
+ * bottom drawer around a central work area (any absent). Collapsing snaps the
+ * panel's track to zero in one reflow while its fixed-size content slides out via
+ * a composited transform — the instant-width / sliding-content technique, so the
+ * work area relayouts once, not per frame. The app owns each `collapsed` flag;
+ * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
+ */
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, }: WorkbenchProps): SafeHtml;
+
+export { Workbench, type WorkbenchPanel, type WorkbenchProps };

package/dist/workbench.js

@@ -0,0 +1,64 @@
+import { jsxs, jsx } from 'kerfjs/jsx-runtime';
+
+// src/workbench.tsx
+function Workbench({
+  id,
+  label,
+  main,
+  leftRail,
+  rightRail,
+  bottomDrawer,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      class: `kui-workbench ${className}`.trim(),
+      id,
+      "data-component": "workbench",
+      "aria-label": label,
+      children: [
+        leftRail && /* @__PURE__ */ jsx(
+          "aside",
+          {
+            class: "kui-workbench__rail kui-workbench__rail--left",
+            "data-workbench-rail": "left",
+            "data-collapsed": String(leftRail.collapsed ?? false),
+            "aria-label": leftRail.label || void 0,
+            style: leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : void 0,
+            children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: leftRail.content })
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { class: "kui-workbench__center", children: [
+          /* @__PURE__ */ jsx("div", { class: "kui-workbench__main", "data-workbench-main": true, children: main }),
+          bottomDrawer && /* @__PURE__ */ jsx(
+            "section",
+            {
+              class: "kui-workbench__drawer",
+              "data-workbench-drawer": true,
+              "data-collapsed": String(bottomDrawer.collapsed ?? false),
+              "aria-label": bottomDrawer.label || void 0,
+              style: bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : void 0,
+              children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: bottomDrawer.content })
+            }
+          )
+        ] }),
+        rightRail && /* @__PURE__ */ jsx(
+          "aside",
+          {
+            class: "kui-workbench__rail kui-workbench__rail--right",
+            "data-workbench-rail": "right",
+            "data-collapsed": String(rightRail.collapsed ?? false),
+            "aria-label": rightRail.label || void 0,
+            style: rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : void 0,
+            children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: rightRail.content })
+          }
+        )
+      ]
+    }
+  );
+}
+
+export { Workbench };
+
+//# sourceMappingURL=workbench.js.map

package/dist/workbench.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":";;;AAgCO,SAAS,SAAA,CAAU;AAAA,EACxB,EAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,QAAA;AAAA,EACA,SAAA;AAAA,EACA,YAAA;AAAA,EACA,SAAA,GAAY;AACd,CAAA,EAAmB;AACjB,EAAA,uBACE,IAAA;AAAA,IAAC,SAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,cAAA,EAAiB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACzC,EAAA;AAAA,MACA,gBAAA,EAAe,WAAA;AAAA,MACf,YAAA,EAAY,KAAA;AAAA,MAEX,QAAA,EAAA;AAAA,QAAA,QAAA,oBACC,GAAA;AAAA,UAAC,OAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,+CAAA;AAAA,YACN,qBAAA,EAAoB,MAAA;AAAA,YACpB,gBAAA,EAAgB,MAAA,CAAO,QAAA,CAAS,SAAA,IAAa,KAAK,CAAA;AAAA,YAClD,YAAA,EAAY,SAAS,KAAA,IAAS,MAAA;AAAA,YAC9B,OACE,QAAA,CAAS,IAAA,GACL,CAAA,4BAAA,EAA+B,QAAA,CAAS,IAAI,CAAA,EAAA,CAAA,GAC5C,MAAA;AAAA,YAGN,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,mBAAS,OAAA,EAAQ;AAAA;AAAA,SAC9D;AAAA,wBAEF,IAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EACT,QAAA,EAAA;AAAA,0BAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,qBAAA,EAAsB,qBAAA,EAAmB,MACjD,QAAA,EAAA,IAAA,EACH,CAAA;AAAA,UACC,YAAA,oBACC,GAAA;AAAA,YAAC,SAAA;AAAA,YAAA;AAAA,cACC,KAAA,EAAM,uBAAA;AAAA,cACN,uBAAA,EAAqB,IAAA;AAAA,cACrB,gBAAA,EAAgB,MAAA,CAAO,YAAA,CAAa,SAAA,IAAa,KAAK,CAAA;AAAA,cACtD,YAAA,EAAY,aAAa,KAAA,IAAS,MAAA;AAAA,cAClC,OACE,YAAA,CAAa,IAAA,GACT,CAAA,+BAAA,EAAkC,YAAA,CAAa,IAAI,CAAA,EAAA,CAAA,GACnD,MAAA;AAAA,cAGN,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EACR,uBAAa,OAAA,EAChB;AAAA;AAAA;AACF,SAAA,EAEJ,CAAA;AAAA,QACC,SAAA,oBACC,GAAA;AAAA,UAAC,OAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,gDAAA;AAAA,YACN,qBAAA,EAAoB,OAAA;AAAA,YACpB,gBAAA,EAAgB,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,KAAK,CAAA;AAAA,YACnD,YAAA,EAAY,UAAU,KAAA,IAAS,MAAA;AAAA,YAC/B,OACE,SAAA,CAAU,IAAA,GACN,CAAA,4BAAA,EAA+B,SAAA,CAAU,IAAI,CAAA,EAAA,CAAA,GAC7C,MAAA;AAAA,YAGN,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,oBAAU,OAAA,EAAQ;AAAA;AAAA;AAC/D;AAAA;AAAA,GAEJ;AAEJ","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: SafeHtml;\n  /** Whether the panel is currently collapsed (the app owns this). */\n  collapsed?: boolean;\n  /** Rail width, or drawer height, in px. Overrides the CSS default. */\n  size?: number;\n  /** Accessible name for the panel region. */\n  label?: string;\n}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: SafeHtml;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  className?: string;\n}\n\n/**\n * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and\n * bottom drawer around a central work area (any absent). Collapsing snaps the\n * panel's track to zero in one reflow while its fixed-size content slides out via\n * a composited transform — the instant-width / sliding-content technique, so the\n * work area relayouts once, not per frame. The app owns each `collapsed` flag;\n * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({\n  id,\n  label,\n  main,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  className = '',\n}: WorkbenchProps) {\n  return (\n    <section\n      class={`kui-workbench ${className}`.trim()}\n      id={id}\n      data-component=\"workbench\"\n      aria-label={label}\n    >\n      {leftRail && (\n        <aside\n          class=\"kui-workbench__rail kui-workbench__rail--left\"\n          data-workbench-rail=\"left\"\n          data-collapsed={String(leftRail.collapsed ?? false)}\n          aria-label={leftRail.label || undefined}\n          style={\n            leftRail.size\n              ? `--kui-workbench-rail-width: ${leftRail.size}px`\n              : undefined\n          }\n        >\n          <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n        </aside>\n      )}\n      <div class=\"kui-workbench__center\">\n        <div class=\"kui-workbench__main\" data-workbench-main>\n          {main}\n        </div>\n        {bottomDrawer && (\n          <section\n            class=\"kui-workbench__drawer\"\n            data-workbench-drawer\n            data-collapsed={String(bottomDrawer.collapsed ?? false)}\n            aria-label={bottomDrawer.label || undefined}\n            style={\n              bottomDrawer.size\n                ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px`\n                : undefined\n            }\n          >\n            <div class=\"kui-workbench__panel-content\">\n              {bottomDrawer.content}\n            </div>\n          </section>\n        )}\n      </div>\n      {rightRail && (\n        <aside\n          class=\"kui-workbench__rail kui-workbench__rail--right\"\n          data-workbench-rail=\"right\"\n          data-collapsed={String(rightRail.collapsed ?? false)}\n          aria-label={rightRail.label || undefined}\n          style={\n            rightRail.size\n              ? `--kui-workbench-rail-width: ${rightRail.size}px`\n              : undefined\n          }\n        >\n          <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n        </aside>\n      )}\n    </section>\n  );\n}\n"]}

package/docs/accessibility.md

@@ -6,11 +6,32 @@ These are normative contracts for package components and consuming applications.
 
 - All controls have accessible names and visible `:focus-visible` treatment.
 - Decorative `LucideIcon` output is `aria-hidden`; pass `label` only when the SVG itself conveys meaning.
-- `MenuItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. It deliberately does not emit `role="menuitem"` in isolation—a true ARIA menu must own arrow, Home/End, Escape, and focus behavior as one widget.
+- `ListItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. Selected rows keep the normal foreground over their brand-tinted fill so text retains WCAG AA contrast in light and dark themes. Its leading icon visual is 18px while the row retains its 44px minimum target; multiline icons align to the first text line. Its `trailing` content is dormant and must not contain controls. Its `rootAttributes` slot accepts only application `data-*` metadata and deliberately cannot emit `role="menuitem"` in isolation—a true ARIA menu must own arrow, Home/End, Escape, and focus behavior as one widget.
+- `ListHeader` owns action naming, disabled state, and disclosure `aria-expanded`. Toggle mode supplies one decorative 18px `DisclosureArrow` when `actionIcon` is omitted; it mirrors `expanded` while the native button's accessible name stays stable. The application must update that controlled state and reveal or hide real content. A valid `count` is visually rendered in an `aria-hidden` neutral pill while the required localized `countLabel` becomes part of the owning heading or disclosure button's accessible name; zero remains a real count. Its narrow `triggerAttributes` slot may describe a native popover or controlled-content relationship with `popoverTarget`, `popoverTargetAction`, `aria-controls`, and `aria-haspopup`; the application owns the target surface and its focus/dismissal behavior.
+- Dispose `wireTabBars` and `wireTokenSearchFields` with their owning view. Disposal cancels queued controlled-render focus restoration, so a torn-down view cannot reclaim focus from its successor.
+- In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; do not reduce the target to the visible icon.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
-- `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure.
+- `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
-- `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone.
+- `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone. Its decorative option icons and value-dependent selected content remain present after controlled rerenders, so the visible choice does not silently lose its non-text cue.
+- `DisclosureArrow` is an 18px root-scaled decorative visual by default, not an interaction target. Its owning native control supplies a stable accessible name, pointer and keyboard interaction, and `aria-expanded`; multiple arrows keep independently controlled state. Consumers may override `--kui-disclosure-arrow-size` without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
+- `List` is layout-only and adds no `list` role. Children own their native or ARIA semantics. Give a scrollable List a bounded block size, avoid nested scroll owners, and keep focused children visible while scrolling.
+
+## ListActionRow
+
+`ListActionRow` renders a noninteractive visual root containing primary and
+trailing native buttons as siblings. The primary comes first in DOM and Tab
+order and alone receives `aria-current` or `aria-pressed`; the trailing button
+has its own required accessible name and disabled state. Both controls carry
+the row's item id for application delegation, while the root deliberately has
+no action or role. `label`, `icon`, and `trailingActionIcon` are dormant visual
+content and must not contain buttons, links, interactive roles, or other
+controls. A trailing click, double click, context menu, Enter, or Space
+must never activate the primary control. Selected rows keep the normal
+foreground over their brand-tinted fill so text retains WCAG AA contrast in
+light and dark themes. The application owns controlled
+selection and the lifecycle, focus, and dismissal policy of any related
+popover or context menu.
 
 ## ResizableRegion
 
@@ -22,12 +43,43 @@ The handle exposes separator role, orientation, name, minimum, maximum, and curr
 - primary-pointer drag with clamping;
 - preview callbacks while dragging and one commit callback on release.
 
-The application owns persistence and collapsed/expanded policy. Keep the last expanded size outside the component and restore it when reopening.
+The application owns persistence and collapsed/expanded policy. Keep the last expanded size outside the component and restore it when reopening. An optional `handleIcon` replaces only decorative dormant content; it must not contain controls or interactive roles because the separator remains the sole focus and interaction owner.
+
+## PanelHeader
+
+`PanelHeader` is a plain `Toolbar` heading. Its leading zone holds an optional
+icon (a normal bordered `ToolbarControlGroup`) and the title as extra-large
+`ToolbarText`, and the app's trailing controls go straight into the trailing
+zone. By default the title carries no native heading role, so for a **dialog or
+panel** the application connects `titleId` and an optional `summaryId` to the
+owning host through `aria-labelledby` and `aria-describedby`. For a **page or
+view** title, pass `headingLevel` (usually `1`): the title then exposes
+`role="heading"` with a matching `aria-level`, giving the view a heading landmark
+so screen-reader heading navigation and "main heading" semantics work — the same
+role/level pair `ToolbarText` exposes when it is given `headingLevel` directly.
+Keep the levels meaningful and non-skipping within a view. Pass the trailing
+controls as a labeled `ToolbarControlGroup` when that group needs an accessible
+name.
+
+## FloatingToolbar
+
+`FloatingToolbar` is a `role="toolbar"` region with a **required** accessible
+`label`; it floats over the content of its nearest positioned ancestor and is
+forced to a dark color scheme, but it is **not** in the top layer, so it never
+covers dialogs, popovers, or other overlays. Its children are the app's controls
+(normally `ToolbarControlGroup`s), which keep their own names, focus, and
+keyboard behavior; the application owns their actions, the toolbar's visibility,
+and — via `position` and `--kui-floating-toolbar-inset` — where it sits.
 
 ## Tabs
 
 `AppTab` renders one controlled tab. `TabBar` supplies the containing tab list,
 fixed leading/trailing regions, and a horizontally scrollable strip.
+`AppTab.rootAttributes` accepts application `data-*` metadata only; runtime
+filtering rejects roles plus case variants of component- or wiring-owned
+action, identity, selection, drag, drop, and component attributes. An optional
+`closeIcon` is decorative dormant content inside the already named close button
+and must not contain interactive descendants.
 `wireTabBars()` adds Left/Right wrapping, Home/End, Delete/Backspace close
 activation, same-bar pointer reordering, `Alt+Shift+ArrowLeft/ArrowRight`
 reordering, focus restoration, scroll-into-view, and pointer-proximity
@@ -35,6 +87,16 @@ autoscroll at either horizontal edge. Edge autoscroll is direct manipulation,
 stops on drop/drag end/disposal, and does not change keyboard behavior. It
 returns a disposer.
 
+Arrow / Home / End follow the ARIA Tabs **automatic-activation** pattern by
+default: they move roving focus and select the focused tab. If selection synchronously
+replaces the strip, focus returns to the replacement with the same bar and tab IDs. Pass
+`activation: 'manual'` (or set `data-tab-activation="manual"` on a strip via the
+`TabBar` `activation` prop, which overrides the option per bar) for
+**manual activation**: arrow keys move roving focus only and the user selects
+with Enter / Space (native on the tab button) or click. Use manual activation
+when selecting a tab is a heavy or side-effecting action — e.g. a tab that loads
+a project — so arrowing through the strip does not trigger it on every tab.
+
 The application owns the ordered tab array, selection, panels, close policy,
 routing, and persistence. On `onReorder`, synchronously render the reported
 order so the helper can restore focus to the moved tab. Pair tabs with
@@ -51,6 +113,64 @@ re-renders. Keep labels unique and meaningful even when `content` shows only an
 icon. Use tabs—not a segmented control—when choices switch page regions that
 need `tab`/`tabpanel` semantics.
 
+## TokenSearchField
+
+`TokenSearchField` exposes the editable surface as a named `searchbox`. Each
+chip is atomic (`contenteditable="false"`) and contains separately named edit
+and remove buttons; the clear action is also named. Disabled fields publish
+`aria-disabled` and stop editing without hiding the current expression. The
+application owns query parsing and must announce result-count or loading
+changes separately when that feedback is useful. Use `readTokenSearchField()`
+to ignore the chip buttons' visible text when reading browser-edited content,
+and `placeTokenSearchCaret()` to restore a text caret without landing inside a
+chip. Call `wireTokenSearchFields()` once at a stable root so Enter submits
+without inserting a contenteditable line break and keyboard chip deletion
+restores focus plus the text-relative caret after controlled rendering replaces
+the editor; the editor still wraps text visually at its inline edge. Editable text is DOM-owned between token changes; a clear handler empties
+the editor's `textContent` before updating application state. Leading and
+trailing controls share the first text line's fixed vertical center and remain
+there as the editor wraps. In `collapsible` mode, the closed state is one named
+iconic search button and the open state is the same named searchbox, whether
+the field stands alone or is composed inside `ToolbarControlGroup`.
+Applications set `expanded` while the field is focused, move focus from the
+trigger into the revealed editor, and clear `expanded` only after focus leaves
+the complete component. Text or tokens keep the field expanded even when that
+transient state is false. Width animation is disabled under reduced motion.
+
+When the field is composed with a caller-owned surface rendered outside it — a
+suggestions listbox, date picker, or help popover — mark that surface (or wrap
+it) with `data-token-search-keep-open`, or pass `collapsible.keepOpenOn(target)`,
+so focus moving into it does not collapse an empty field. `wireTokenSearchFields`
+can also, opt-in via `keyboard`, own atomic-chip editing keys: from a collapsed
+caret with no selection, Backspace removes the token before the caret and Delete
+the token after it (reported through `onRemoveToken` for the app to apply to its
+controlled state), and ArrowRight moves the caret past a trailing chip so typed
+text lands after it. An optional `onEdit({ id, editor, event })` — with the
+originating `InputEvent` so a caller can gate on `inputType`/`data` — fires on every editor
+`input`, letting a caller drop its own `input` listener; the application still
+owns query parsing and result-count/loading announcements.
+
+Managed clear captures the action before application handlers run, keeps the adopted
+expanded signal open during editor replacement, and focuses the current editor after
+rendering so typing can continue. The app still owns clearing query/tokens and emptying
+DOM-owned text. This focus step respects `manageFocus: false`, disposal, removed fields,
+and focus deliberately moved to another control; no app-level reopen callback is needed.
+
+## CollapsiblePanel / sidebar
+
+`CollapsiblePanel` is a labeled `aside` region that is `aria-hidden` while
+collapsed; its content slides via transform (disabled under reduced motion).
+`CollapsiblePanelToggle` is a named button carrying `aria-expanded` and the
+standard per-side collapse/expand glyph (`PanelLeft*` / `PanelRight*` /
+`PanelBottom*`); place a collapse toggle inside the panel and an expand toggle in
+an always-visible location so it is reachable while collapsed. `wireSidebar()`
+moves focus into the panel when it opens and restores it to the trigger when it
+closes. When a `deviceClass()` reports `compact`, an open panel becomes an overlay
+with a dismissable backdrop, Escape and backdrop-click collapse it, and Tab is
+trapped within it (the ARIA dialog pattern). The application owns each `collapsed`
+signal, the panels, their sizes, and content; the wire may persist the collapsed
+state per panel.
+
 ## Verification matrix
 
 For each changed component, inspect default, hover, focus, disabled, selected/pressed, busy/error, long-content, wide, narrow, light, dark, increased-contrast, reduced-motion, keyboard-only, and 200%-zoom states where applicable. DOM order must match reading and focus order, with no clipping or unreachable action.