@kerfjs/ui 4.4.1 → 5.0.0-beta.10

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

@@ -0,0 +1,97 @@
+import { Signal } from 'kerfjs';
+
+interface TokenSearchSubmit {
+    id: string;
+    editor: HTMLElement;
+}
+/** 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 TokenSearchKeyboardOptions {
+    /**
+     * 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.
+     */
+    removeAdjacentToken?: boolean;
+    /**
+     * ArrowRight moves the caret past a trailing atomic token so text typed next
+     * lands after the chip. Default: true.
+     */
+    moveCaretPastToken?: boolean;
+    /** Apply the reported removal to your controlled state, then re-render. */
+    onRemoveToken?: (removal: TokenSearchTokenRemoval) => void;
+}
+/**
+ * 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 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: TokenSearchSubmit) => 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). `true` = on with defaults. */
+    keyboard?: boolean | 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 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-CVZYNJJ5.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,17 @@
+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,EAAE,EAAA,EAAI,KAAA,EAAO,IAAA,EAAM,UAAU,SAAA,EAAW,YAAA,EAAc,SAAA,GAAY,EAAA,EAAG,EAAmB;AAChH,EAAA,uBAAO,IAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAO,CAAA,cAAA,EAAiB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK,EAAG,EAAA,EAAQ,gBAAA,EAAe,WAAA,EAAY,YAAA,EAAY,KAAA,EACxG,QAAA,EAAA;AAAA,IAAA,QAAA,oBAAY,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,+CAAA,EAAgD,qBAAA,EAAoB,MAAA,EAAO,gBAAA,EAAgB,MAAA,CAAO,QAAA,CAAS,SAAA,IAAa,KAAK,CAAA,EAAG,cAAY,QAAA,CAAS,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,QAAA,CAAS,IAAA,GAAO,CAAA,4BAAA,EAA+B,QAAA,CAAS,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAC3Q,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,QAAA,CAAS,SAAQ,CAAA,EAC9D,CAAA;AAAA,oBACA,IAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EACT,QAAA,EAAA;AAAA,sBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,qBAAA,EAAsB,qBAAA,EAAmB,MAAE,QAAA,EAAA,IAAA,EAAK,CAAA;AAAA,MAC1D,YAAA,oBAAgB,GAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAM,uBAAA,EAAwB,uBAAA,EAAqB,IAAA,EAAC,gBAAA,EAAgB,MAAA,CAAO,YAAA,CAAa,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,YAAA,CAAa,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,YAAA,CAAa,IAAA,GAAO,CAAA,+BAAA,EAAkC,aAAa,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EACvQ,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,YAAA,CAAa,SAAQ,CAAA,EAClE;AAAA,KAAA,EACF,CAAA;AAAA,IACC,SAAA,oBAAa,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,gDAAA,EAAiD,qBAAA,EAAoB,OAAA,EAAQ,gBAAA,EAAgB,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,SAAA,CAAU,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,SAAA,CAAU,IAAA,GAAO,CAAA,4BAAA,EAA+B,UAAU,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAClR,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,SAAA,CAAU,SAAQ,CAAA,EAC/D;AAAA,GAAA,EACF,CAAA;AACF","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({ id, label, main, leftRail, rightRail, bottomDrawer, className = '' }: WorkbenchProps) {\n  return <section class={`kui-workbench ${className}`.trim()} id={id} data-component=\"workbench\" aria-label={label}>\n    {leftRail && <aside class=\"kui-workbench__rail kui-workbench__rail--left\" data-workbench-rail=\"left\" data-collapsed={String(leftRail.collapsed ?? false)} aria-label={leftRail.label || undefined} style={leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n    </aside>}\n    <div class=\"kui-workbench__center\">\n      <div class=\"kui-workbench__main\" data-workbench-main>{main}</div>\n      {bottomDrawer && <section class=\"kui-workbench__drawer\" data-workbench-drawer data-collapsed={String(bottomDrawer.collapsed ?? false)} aria-label={bottomDrawer.label || undefined} style={bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : undefined}>\n        <div class=\"kui-workbench__panel-content\">{bottomDrawer.content}</div>\n      </section>}\n    </div>\n    {rightRail && <aside class=\"kui-workbench__rail kui-workbench__rail--right\" data-workbench-rail=\"right\" data-collapsed={String(rightRail.collapsed ?? false)} aria-label={rightRail.label || undefined} style={rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n    </aside>}\n  </section>;\n}\n"]}

package/docs/accessibility.md

@@ -6,11 +6,28 @@ 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`. 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.
+- 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.
 - `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.
+
+## 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. The application owns controlled
+selection and the lifecycle, focus, and dismissal policy of any related
+popover or context menu.
 
 ## ResizableRegion
 
@@ -22,12 +39,33 @@ 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.
 
 ## 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 +73,15 @@ 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. 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 +98,57 @@ 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 })` fires on every editor
+`input`, letting a caller drop its own `input` listener; the application still
+owns query parsing and result-count/loading announcements.
+
+## 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.

package/docs/app-layouts.md

@@ -0,0 +1,61 @@
+# Choosing an app layout
+
+`@kerfjs/ui` ships four opt-in, tree-shakeable whole-screen layouts plus the
+[`device-class`](device-class.md) signal that drives their responsive behavior.
+This guide maps a **data + interaction + device** situation to the layout to
+reach for, and states the device-class threshold at which the presentation
+changes. The layouts:
+
+- [`NavStack`](nav-stack.md) — push/pop navigation (a single pane is a one-entry stack).
+- [`SplitView`](split-view.md) — list-detail (two panes, collapsing to a stack).
+- [`Workbench`](workbench.md) — the Xcode-like collapsible rails + drawer.
+- [`TabScaffold`](tab-scaffold.md) — the iOS bottom tab bar (each tab a stack).
+- [`CollapsiblePanel` + `wireSidebar`](collapsible-panel.md) — a standalone
+  collapsible rail or bottom drawer (with `CollapsiblePanelToggle`), outside a full
+  shell: the standard collapse animation, icon convention, and `wireSidebar`
+  semantics (focus, compact overlay, persistence).
+
+Derive responsiveness from `deviceClass()`: `compact` (a handset or portrait
+tablet) means "one pane at a time"; `atLeast('tablet')` / `atLeast('desktop')`
+gate the roomier presentations.
+
+## Decision matrix
+
+| Situation | Layout | Device threshold |
+| --- | --- | --- |
+| Simple app, a few flat sections | `NavStack` with one entry (single pane); add `TabScaffold` for 2–5 co-equal sections on handset | `TabScaffold` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')` |
+| Drill-down browsing (list → item → sub-item) | `NavStack`; upgrade to `SplitView` once list + detail fit together | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact` |
+| Two related panes, selecting on the left updates the right | `SplitView` | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact` |
+| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench` | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
+| Mobile app with 2–5 top-level destinations, each its own drill-down | `TabScaffold`, each tab a `NavStack` | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')` |
+
+### Worked examples
+
+- **Settings screen (simple):** one `NavStack` entry per screen; push a subpage
+  on tap. No `SplitView`/`Workbench` — it is a single flow.
+- **Mail (drill-down + two-pane):** `SplitView` with `list={<ThreadList/>}` and
+  `detail={<Message/>}`, `compact={device.value.compact}`,
+  `detailActive={selected != null}`. On desktop both panes show with a resizable
+  separator; on a phone it is a `NavStack` (threads → message, back clears the
+  selection).
+- **IDE (complex tool):** `Workbench` with a left navigator rail, a right
+  inspector rail, and a bottom console drawer, each `collapsed` bound to a
+  signal. Only offer this `atLeast('desktop')`.
+- **Social app (tabbed):** `TabScaffold` with Home / Search / Profile tabs, each
+  `content` a `NavStack`. On a tablet/desktop, render the same sections as a
+  `Workbench` left rail instead of a bottom bar.
+
+## Dialogs
+
+Pick the dialog's inner layout by the same complexity axis, then apply the device
+class to how it is presented (compose with [`overlay`](../../docs/19-native-overlay-backing.md)):
+
+- **desktop:** an inline dialog — a `SplitView` two-pane body, or a `NavStack`
+  for a wizard.
+- **portrait tablet / handset:** present a `SplitView`/complex dialog as a
+  full-screen modal (its `compact` `NavStack` form).
+- **landscape tablet:** a large partial-cover modal (does not need to go full
+  screen).
+
+A `NavStack` works as a dialog body at every size — a wizard pushes and pops its
+steps with cross-faded chrome.

package/docs/catalog.md

@@ -0,0 +1,155 @@
+# Catalog — a reusable component-gallery shell
+
+`@kerfjs/ui/catalog` is an opt-in, whole-screen shell for building a **component
+catalog** — the collapsible category sidebar + titled preview stage + resources
+footer that the kerf UI catalog itself uses. Point it at your own components and
+you get the same shell without rebuilding it. Like the app layouts, it is a
+subpath-only, tree-shakeable module that adds nothing to the main barrel.
+
+```bash
+npm install @kerfjs/ui   # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
+```
+
+- `Catalog(props)` returns the shell as `SafeHtml` (a `<main class="kui-catalog">`).
+  It is **controlled and stateless**: your app owns the `active`, `collapsed`, and
+  `theme` signals and computes the preview `content` from `active` in its own
+  `mount()` render.
+- `wireCatalog(root, options)` wires the interactions (sidebar selection, the
+  related-entry popup menu, and the collapse/theme toggles) with one delegated
+  listener set and returns a disposer; it can also mirror the active id into the
+  URL.
+
+## What you supply
+
+- **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
+  description?, resources?, related? }] }`. Each entry becomes a sidebar `ListItem`
+  under a `ListHeader` for its category.
+- **`content`** — the rendered preview for the active entry. Keep a map of `id →
+  () => SafeHtml` in your app and call `renderers[active]()` in your render.
+- **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
+- **`secondarySections`** — an optional secondary "ecosystem" group shown below the
+  primary sections with a quieter treatment: `{ label, sections, collapsible?,
+  expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
+  `expanded` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
+- Optional slots: `headerActions` (extra header controls), `sidebarFooter` (extra
+  sidebar content), and `status` (a footer status line).
+
+Per-entry `resources` render as "open in new tab" links in the footer, and
+`related` renders a "Related entries" popup menu — a `single` `ToolbarControlGroup`
+around a `wa-dropdown` (grouped by each entry's `group`), so register its elements
+with `@kerfjs/ui/select/register` when you use it.
+
+## Preview examples
+
+Compose each entry's `content` from `CatalogExample` (and `CatalogExampleStack`)
+instead of hand-rolled example markup, so labels, notes, and left-edge alignment
+stay consistent:
+
+```tsx
+import { CatalogExample, CatalogExampleStack } from '@kerfjs/ui/catalog';
+
+const buttonPreview = (
+  <CatalogExampleStack label="Button variants">
+    <CatalogExample label="Icon" note="A bare glyph." align="glyph">
+      <LucideIcon icon={Plus} name="plus" />
+    </CatalogExample>
+    <CatalogExample label="Control" align="inline-control">
+      <SegmentedControl id="view" label="View" value="list" choices={choices} />
+    </CatalogExample>
+    <CatalogExample label="In composition">
+      <ValueTable label="Metadata">{rows}</ValueTable>
+    </CatalogExample>
+  </CatalogExampleStack>
+);
+```
+
+`label` is optional — omit it for a bare specimen with no `ListHeader`. `align`
+lines a specimen's visible left edge up with its label text: `'glyph'`
+(16px) for a bare glyph/text specimen, `'inline-control'` (8px) for a control that
+already carries ~8px of its own inline padding, and `'none'` (the default) for a
+content-item/composition that already owns its geometry. The inset is published as
+the `--kui-catalog-example-align` custom property so a debug overlay can exclude it
+from a specimen's measured margin.
+
+## Complete example
+
+```tsx
+import { mount, signal } from 'kerfjs';
+import { Catalog, type CatalogSection } from '@kerfjs/ui/catalog';
+import { wireCatalog } from '@kerfjs/ui/wire-catalog';
+import '@kerfjs/ui/styles.css'; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+
+// 1. Describe your components once.
+const sections: CatalogSection[] = [
+  {
+    category: 'Controls',
+    entries: [
+      { id: 'button', name: 'Button', description: 'A pressable control.',
+        resources: [{ label: 'Source', href: '/src/button.tsx', detail: 'src/button.tsx' }] },
+      { id: 'field', name: 'Field', description: 'A labeled input.',
+        related: [{ id: 'button', name: 'Button', group: 'Used with' }] },
+    ],
+  },
+  { category: 'Feedback', entries: [{ id: 'toast', name: 'Toast', description: 'A transient message.' }] },
+];
+
+// 2. One preview render per entry id.
+const renderers: Record<string, () => ReturnType<typeof Button>> = {
+  button: () => <Button label="Save" />,
+  field: () => <Field label="Name" />,
+  toast: () => <Toast>Saved</Toast>,
+};
+
+// 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
+const initial = new URLSearchParams(location.search).get('c') ?? sections[0].entries[0].id;
+const active = signal(initial);
+const collapsed = signal(false);
+const theme = signal<'light' | 'dark'>('light');
+
+const app = document.getElementById('app')!;
+mount(app, () => (
+  <Catalog
+    brand={{ title: 'Acme UI', subtitle: 'Design system' }}
+    sections={sections}
+    active={active.value}
+    content={renderers[active.value]?.() ?? <></>}
+    collapsed={collapsed.value}
+    theme={theme.value}
+  />
+));
+
+wireCatalog(app, {
+  onSelect: (id) => { active.value = id; },
+  onToggleSidebar: () => { collapsed.value = !collapsed.value; },
+  onToggleTheme: () => {
+    theme.value = theme.value === 'dark' ? 'light' : 'dark';
+    document.documentElement.dataset.theme = theme.value; // apply your theme however you like
+  },
+  urlParam: 'c', // mirror the active id into ?c=<id>
+});
+```
+
+## Ownership boundary
+
+`Catalog` renders the shell; the app owns everything stateful:
+
+- **`active`** is domain state (which entry is shown) — the app's signal, updated in
+  `onSelect`, read to compute `content`.
+- **`collapsed`** is transient UI — the app's signal, flipped in `onToggleSidebar`.
+- **`theme`** is a global preference — the app's signal; `wireCatalog` only reports
+  the toggle, the app applies the theme (the shell reads `theme` to show the toggle's
+  opposite-state label). Omit `theme` to hide the toggle entirely.
+
+## Custom action names
+
+The shell emits `data-action="catalog-select"` (sidebar items),
+`catalog-toggle-sidebar`, and `catalog-toggle-theme`. Override them with
+`selectAction` / `toggleSidebarAction` / `toggleThemeAction` on `Catalog` (and the
+matching options on `wireCatalog`) if they collide with your own action table.
+
+## CSS
+
+`Catalog` composes public primitives (`Toolbar`, `ListHeader`, `ListItem`, `Select`,
+…). Import `@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css`
+plus each composed primitive's CSS. The shell is theme-aware and responsive: it
+stacks the sidebar above the detail below ~832px and hides it when collapsed.

package/docs/collapsible-panel.md

@@ -0,0 +1,102 @@
+# CollapsiblePanel + wireSidebar — reusable sidebar / drawer support
+
+`@kerfjs/ui/collapsible-panel` and `@kerfjs/ui/wire-sidebar` are the standalone,
+reusable pieces for an app's own **side rails** and **bottom drawers** — the same
+collapse semantics the `Workbench` shell and the catalog sidebar use, but outside
+a full shell so you can dock one panel wherever your layout needs it. They are
+subpath-only, tree-shakeable modules that add nothing to the main barrel.
+
+```bash
+npm install @kerfjs/ui   # kerfjs is a peer
+```
+
+Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.css`.
+
+## The pieces
+
+- **`CollapsiblePanel({ id, side, collapsed?, size?, label?, children })`** — the
+  docked panel: a `'left'` / `'right'` rail or a `'bottom'` drawer. It owns only
+  presentation. Collapsing snaps the panel's own size to zero in one reflow while
+  the fixed-size content slides out via `transform` (composited, clipped) — never
+  a per-frame width/height animation. The app owns the `collapsed` signal; `size`
+  overrides the CSS default width/height.
+- **`CollapsiblePanelToggle({ side, collapsed, action, panelId?, label? })`** and
+  **`collapsiblePanelToggleIcon(side, collapsed)`** — the standard toggle
+  affordance and its icon convention, so every sidebar reads the same: `PanelLeft*`
+  for a left rail, `PanelRight*` for a right rail, `PanelBottom*` for a bottom
+  drawer — the `Close` glyph while open, the `Open` glyph while collapsed. Placement
+  is the app's: put a collapse toggle in the panel's own header and an expand toggle
+  somewhere always-visible (a toolbar) so it is reachable while collapsed.
+- **`wireSidebar(root, { panels, deviceClass?, storage? })`** — the interaction
+  semantics. Each `panels` entry is `{ id, collapsed, toggleAction, storageKey? }`.
+  It:
+  - **toggles** the panel's `collapsed` signal when any `[data-action=toggleAction]`
+    button is clicked, and remembers the trigger;
+  - **manages focus** — moves focus into the panel when it opens, and restores it
+    to the trigger when it closes;
+  - **presents a compact overlay** when `deviceClass.compact` is true (pass a
+    `deviceClass()` signal): the open panel floats over the content with a
+    dismissable backdrop, Escape and backdrop-click collapse it, and Tab is trapped
+    within the panel (the ARIA dialog pattern);
+  - **persists** the collapsed state to `storage` (default `localStorage`) under
+    `storageKey`, seeding the signal on wire-up.
+
+  Returns a disposer. Retain it and call it on teardown.
+
+## Example
+
+```tsx
+import { signal, mount } from 'kerfjs';
+import { deviceClass } from '@kerfjs/ui/device-class';
+import { CollapsiblePanel, CollapsiblePanelToggle } from '@kerfjs/ui/collapsible-panel';
+import { wireSidebar } from '@kerfjs/ui/wire-sidebar';
+import '@kerfjs/ui/collapsible-panel.css';
+
+const navCollapsed = signal(false);
+const device = deviceClass();
+
+const app = document.querySelector('#app')!;
+mount(app, () => (
+  <div class="layout">
+    <CollapsiblePanel id="nav" side="left" collapsed={navCollapsed.value} label="Navigator">
+      <header>
+        <CollapsiblePanelToggle side="left" collapsed={navCollapsed.value} action="toggle-nav" panelId="nav" />
+      </header>
+      {/* nav items */}
+    </CollapsiblePanel>
+    <main>
+      {navCollapsed.value && <CollapsiblePanelToggle side="left" collapsed action="toggle-nav" label="Show navigator" />}
+      {/* content */}
+    </main>
+  </div>
+));
+
+const stop = wireSidebar(app, {
+  panels: [{ id: 'nav', collapsed: navCollapsed, toggleAction: 'toggle-nav', storageKey: 'app.nav-collapsed' }],
+  deviceClass: device,
+});
+```
+
+## When to use which
+
+- One or two independent rails / a drawer you place yourself → **`CollapsiblePanel` +
+  `wireSidebar`**.
+- A whole Xcode-like workspace (left rail + right rail + bottom drawer + work area
+  in one shell) → **[`Workbench`](workbench.md)**, which owns the layout and the same
+  collapse animation.
+- Drag-to-resize a panel → compose **[`ResizableRegion`](../src/resizable-region.tsx)**
+  / `wireResizableRegions`; the app owns the size signal.
+
+The app still owns everything domain-specific — which panels exist, their order,
+sizes, content, and any per-project persistence — exactly as with the other layouts.
+
+## Recipe and coverage
+
+The catalog ships a runnable **Collapsible sidebar** recipe — a left rail and a
+bottom drawer with the standard toggles, the compact overlay, and per-panel
+persistence: [open it](../ux-demo/?component=recipe-collapsible-sidebar) or read
+[`recipes.md`](recipes.md#collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx).
+It is covered end-to-end across Chromium, Firefox, and WebKit by
+`tests/browser/collapsible-sidebar-recipe.spec.ts` (collapse/expand, focus
+move/restore, the compact overlay + Escape/backdrop dismiss, and the Tab trap),
+alongside the component/wire unit tests.