@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.41

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

@@ -1,11 +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;
+    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;
 }
-/** Keep TokenSearchField wrapping, submit Enter, and preserve its caret across controlled token deletion. */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit }: WireTokenSearchFieldsOptions): () => 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 TokenSearchSubmit, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
+export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };

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

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-H5AGGVU5.js';
+export { wireTokenSearchFields } from './chunk-VDUJZF5G.js';
 
 
 

package/dist/workbench.d.ts

@@ -0,0 +1,44 @@
+import { SafeHtml } from 'kerfjs';
+import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** A collapsible Workbench panel — a side rail or the bottom drawer. */
+interface WorkbenchPanel {
+    content: KerfUiContent;
+    /** 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;
+    separator?: ResizableRegionSeparator;
+    collapseMotion?: ResizableRegionCollapseMotion;
+    contentOverflow?: ResizableRegionContentOverflow;
+    presentation?: ResizableRegionPresentation;
+    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    restoreControl?: SafeHtml;
+    restorePosition?: ResizableRegionRestorePosition;
+}
+interface WorkbenchProps {
+    id: string;
+    label: string;
+    /** The central work area. */
+    main: KerfUiContent;
+    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. Bottom-drawer content stays anchored
+ * to the shell's stable bottom edge throughout that transition. 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,106 @@
+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),
+            "data-separator": leftRail.separator ?? "auto",
+            "data-collapse-motion": leftRail.collapseMotion ?? "slide",
+            "data-content-overflow": leftRail.contentOverflow ?? "clip",
+            "data-presentation": leftRail.presentation ?? "inline",
+            "aria-label": leftRail.label || void 0,
+            "aria-hidden": leftRail.presentation === "hidden" ? "true" : 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 })
+          }
+        ),
+        leftRail?.collapsed && leftRail.restoreControl && leftRail.presentation !== "hidden" && /* @__PURE__ */ jsx(
+          "div",
+          {
+            class: "kui-workbench__restore",
+            "data-panel": "left",
+            "data-position": leftRail.restorePosition ?? "bottom-start",
+            children: leftRail.restoreControl
+          }
+        ),
+        /* @__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),
+              "data-separator": bottomDrawer.separator ?? "auto",
+              "data-collapse-motion": bottomDrawer.collapseMotion ?? "slide",
+              "data-content-overflow": bottomDrawer.contentOverflow ?? "clip",
+              "data-presentation": bottomDrawer.presentation ?? "inline",
+              "aria-label": bottomDrawer.label || void 0,
+              "aria-hidden": bottomDrawer.presentation === "hidden" ? "true" : 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 })
+            }
+          ),
+          bottomDrawer?.collapsed && bottomDrawer.restoreControl && bottomDrawer.presentation !== "hidden" && /* @__PURE__ */ jsx(
+            "div",
+            {
+              class: "kui-workbench__restore",
+              "data-panel": "bottom",
+              "data-position": bottomDrawer.restorePosition ?? "bottom-end",
+              children: bottomDrawer.restoreControl
+            }
+          )
+        ] }),
+        rightRail && /* @__PURE__ */ jsx(
+          "aside",
+          {
+            class: "kui-workbench__rail kui-workbench__rail--right",
+            "data-workbench-rail": "right",
+            "data-collapsed": String(rightRail.collapsed ?? false),
+            "data-separator": rightRail.separator ?? "auto",
+            "data-collapse-motion": rightRail.collapseMotion ?? "slide",
+            "data-content-overflow": rightRail.contentOverflow ?? "clip",
+            "data-presentation": rightRail.presentation ?? "inline",
+            "aria-label": rightRail.label || void 0,
+            "aria-hidden": rightRail.presentation === "hidden" ? "true" : 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 })
+          }
+        ),
+        rightRail?.collapsed && rightRail.restoreControl && rightRail.presentation !== "hidden" && /* @__PURE__ */ jsx(
+          "div",
+          {
+            class: "kui-workbench__restore",
+            "data-panel": "right",
+            "data-position": rightRail.restorePosition ?? "bottom-end",
+            children: rightRail.restoreControl
+          }
+        )
+      ]
+    }
+  );
+}
+
+export { Workbench };
+
+//# sourceMappingURL=workbench.js.map

package/dist/workbench.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":"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","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type {\n  ResizableRegionCollapseMotion,\n  ResizableRegionContentOverflow,\n  ResizableRegionPresentation,\n  ResizableRegionRestorePosition,\n  ResizableRegionSeparator,\n} from './resizable-region.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: KerfUiContent;\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  separator?: ResizableRegionSeparator;\n  collapseMotion?: ResizableRegionCollapseMotion;\n  contentOverflow?: ResizableRegionContentOverflow;\n  presentation?: ResizableRegionPresentation;\n  /** Control shown in a safe-area-aware viewport corner while collapsed. */\n  restoreControl?: SafeHtml;\n  restorePosition?: ResizableRegionRestorePosition;\n}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: KerfUiContent;\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. Bottom-drawer content stays anchored\n * to the shell's stable bottom edge throughout that transition. The app owns\n * each `collapsed` flag; the collapse is pure CSS (no wire). See\n * `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          data-separator={leftRail.separator ?? 'auto'}\n          data-collapse-motion={leftRail.collapseMotion ?? 'slide'}\n          data-content-overflow={leftRail.contentOverflow ?? 'clip'}\n          data-presentation={leftRail.presentation ?? 'inline'}\n          aria-label={leftRail.label || undefined}\n          aria-hidden={leftRail.presentation === 'hidden' ? 'true' : 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      {leftRail?.collapsed &&\n        leftRail.restoreControl &&\n        leftRail.presentation !== 'hidden' && (\n          <div\n            class=\"kui-workbench__restore\"\n            data-panel=\"left\"\n            data-position={leftRail.restorePosition ?? 'bottom-start'}\n          >\n            {leftRail.restoreControl}\n          </div>\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            data-separator={bottomDrawer.separator ?? 'auto'}\n            data-collapse-motion={bottomDrawer.collapseMotion ?? 'slide'}\n            data-content-overflow={bottomDrawer.contentOverflow ?? 'clip'}\n            data-presentation={bottomDrawer.presentation ?? 'inline'}\n            aria-label={bottomDrawer.label || undefined}\n            aria-hidden={\n              bottomDrawer.presentation === 'hidden' ? 'true' : undefined\n            }\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        {bottomDrawer?.collapsed &&\n          bottomDrawer.restoreControl &&\n          bottomDrawer.presentation !== 'hidden' && (\n            <div\n              class=\"kui-workbench__restore\"\n              data-panel=\"bottom\"\n              data-position={bottomDrawer.restorePosition ?? 'bottom-end'}\n            >\n              {bottomDrawer.restoreControl}\n            </div>\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          data-separator={rightRail.separator ?? 'auto'}\n          data-collapse-motion={rightRail.collapseMotion ?? 'slide'}\n          data-content-overflow={rightRail.contentOverflow ?? 'clip'}\n          data-presentation={rightRail.presentation ?? 'inline'}\n          aria-label={rightRail.label || undefined}\n          aria-hidden={rightRail.presentation === 'hidden' ? 'true' : 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      {rightRail?.collapsed &&\n        rightRail.restoreControl &&\n        rightRail.presentation !== 'hidden' && (\n          <div\n            class=\"kui-workbench__restore\"\n            data-panel=\"right\"\n            data-position={rightRail.restorePosition ?? 'bottom-end'}\n          >\n            {rightRail.restoreControl}\n          </div>\n        )}\n    </section>\n  );\n}\n"]}

package/docs/accessibility.md

@@ -6,18 +6,70 @@ 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`. 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.
-- `MenuHeader` 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, `MenuHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `MenuHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-menu-header-action-icon-size`; do not reduce the target to the visible icon.
+- `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.
+- `wireNavStack` moves focus into every newly active top view and remembers the last focused descendant of each mounted view for pop restoration. Mark a preferred initial heading or control with `data-nav-focus` (and `tabindex="-1"` when it is not normally tabbable); otherwise the helper uses the first enabled focusable descendant, then a programmatically focusable view-container fallback.
+- 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. 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.
-
-## MenuActionRow
-
-`MenuActionRow` renders a noninteractive visual root containing primary and
+- `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.
+
+## Select
+
+Supply a visible `label`, or `ariaLabel` when the surrounding interface already
+provides visual context. A nonempty `label` takes precedence when both are
+supplied. Kerf forwards that name through Web Awesome's internal label contract;
+an `aria-label` on the custom-element host alone cannot name its shadow
+combobox. With `ariaLabel` alone, Kerf visually hides the internal label without
+adding height or spacing. This also applies to `renderSelected`: selected content
+stays separate from the control's stable accessible name. Applications do not
+need shadow-DOM patches or extra label styling.
+
+Use `presentation="toolbar-borderless"` with `size="compact"` inside a
+`ToolbarControlGroup`; set `focusRingOwner="group"` when that parent paints the
+composed focus ring. `selectedPresentation="icon-only"` hides only the visible
+selected label—the required `label` or `ariaLabel` still names the combobox.
+Navigation selects can use intrinsic `presentation="navigation"` plus
+`labelMaxWidth` for component-owned ellipsis. These props own the control's
+appearance; its parent continues to own outer placement.
+
+Use `hint` for persistent supporting text below the control; use
+`placeholderText` only for the empty value shown inside the closed control.
+Kerf passes hint text through Web Awesome's form-control contract, which renders
+the hint part and connects the shadow combobox to it with `aria-describedby`.
+The accessible control is that shadow combobox, not the `wa-select` wrapper;
+inspect or test the element returned by the `combobox` role. Both the `hint`
+attribute used by Kerf and Web Awesome's explicit `hint` slot produce a computed
+accessible description in Chromium, Firefox, and WebKit, so applications do not
+need an `aria-description` mirror or a shadow-DOM patch.
+Loading placeholders keep the same visible hint while replacing the interactive
+control with inert chrome.
+
+`tests/unit/components.test.tsx` covers name projection and visible/hidden label
+variants. `tests/browser/select-accessibility.spec.ts` verifies actual accessible
+names, unchanged unlabeled geometry, keyboard selection, controlled rerenders,
+native hint wiring, and wide/narrow presentation in Chromium, Firefox, and WebKit.
+
+The explicit `@kerfjs/ui/select/register` import also installs the canonical
+Select lifecycle adapter. The latest open/close request owns animation completion
+and deferred option focus. A stale close cannot hide a reopened popup after
+resize; stale completion events are not emitted. Preventing `wa-show` or
+`wa-hide` retains the accepted closed/open state, and removal prevents deferred
+activation. Native option selection, keyboard behavior, dismissal listeners,
+and popup anchor placement remain with Web Awesome. Raw `wa-select` elements
+without the canonical `data-component="select"` marker are unchanged.
+`tests/unit/select-lifecycle.test.ts` and `animate-select-popup.test.ts` cover
+repeated and out-of-order completions, cancellation, instance isolation, and
+removal. `tests/browser/select-lifecycle.spec.ts` repeats animation/resize/reopen
+sequences at wide and narrow widths in Chromium, Firefox, and WebKit.
+
+## 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
@@ -25,7 +77,9 @@ 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
+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.
 
@@ -41,21 +95,48 @@ The handle exposes separator role, orientation, name, minimum, maximum, and curr
 
 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.
 
-## DialogHeader
-
-`DialogHeader` keeps its icon and `h2` together in the leading borderless
-`ToolbarControlGroup`, with optional actions in a separate trailing group. Pass
-localized `actionsLabel` text when the action group needs an accessible name;
-the component does not synthesize an English label. The application connects
-`titleId` and an optional `summaryId` to the owning dialog through
-`aria-labelledby` and `aria-describedby`. Pass action children directly so the
-component can group them; existing pre-grouped actions remain compatible, but
-their inner groups retain their own labels and semantics.
+## Toolbar headings
+
+For headings and paragraphs outside toolbar identity/title zones, use `Text`.
+It renders the selected native `h1`–`h6` or `p` element, so heading navigation
+follows the variant directly; choose a level that preserves the document
+outline. Native global, `data-*`, and `aria-*` attributes pass through.
+
+Compose panel, dialog, and page headings as a plain `Toolbar`. Its leading zone
+holds an optional icon `ToolbarControlGroup` and a direct extra-large
+`ToolbarText`; controls belong in a trailing `ToolbarControlGroup`. By default
+the title carries no native heading role, so for a **dialog or panel** the
+application connects the title id and optional supporting-copy id to the owning
+host through `aria-labelledby` and `aria-describedby`. For a **page or view**
+title, pass `headingLevel` (usually `1`) to `ToolbarText`: it 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 used throughout Kerf UI. Keep the levels meaningful and
+non-skipping within a view. Pass trailing
+controls as a labeled `ToolbarControlGroup` when that group needs an accessible
+name. Keep supporting copy as app-owned content below the toolbar.
+
+## 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.
+Use `TabBar.presentation` for rail, segmented, or inspector chrome,
+`allocation="fill"` when peers should divide the strip, and
+`trailingPlacement="adjacent"` when an action belongs beside the final tab.
+`AppTab` provides compact 32px, segmented, truncating-label, and icon-only
+presentations. Icon-only tabs keep the required `name` as the tab button's
+accessible name while visually hiding the duplicate label. These props own
+component appearance only; the application still owns the bar's outer placement.
 `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
@@ -68,6 +149,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
@@ -97,7 +188,12 @@ 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. Restoration finishes after synchronous input listeners and before
+another keystroke; it does not wait for an animation frame that could overwrite
+a later selection. Select All + Backspace/Delete shares that replacement path
+and keeps the adopted expanded signal open while managed focus is enabled.
+Real outside focus, empty Escape, disposal, and removed fields retain their usual
+behavior. 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
@@ -108,6 +204,45 @@ 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 or pointer activation moving into it does not collapse an empty field.
+The helper preserves the pointer target when a browser omits
+`focusout.relatedTarget`, preventing the field or target from disappearing
+between pointerdown and click. `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 restores focus at the actual
+mutation checkpoint before the next input task. It also returns keyboard activation
+from the clear button to a surviving editor immediately. No animation frame owns
+clear focus, so fast typing cannot escape to page shortcuts or lose its first letter. 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.

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.