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

package/docs/app-layouts.md

@@ -0,0 +1,57 @@
+# 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).
+
+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/component-contract.md

@@ -121,14 +121,14 @@ into the section label. Do not add padding to pane shells,
 double child-owned geometry with wrapper insets, or create competing scroll
 owners. The [layout contract](./layout.md) lists the public roles and tokens.
 
-`DialogHeader` composes its icon and first title line inside a borderless
-`ToolbarControlGroup` in a real top `Toolbar`. Direct `actions` children are
-automatically placed in one contained `ToolbarControlGroup`; use the optional
-localized `actionsLabel` when that group needs an accessible name. Existing
-pre-grouped action content remains layout-compatible, but new callers should
-pass the action children rather than groups. The optional summary is a separate
-row aligned below the title, so it cannot pull the 24px icon or 34px circular
-icon background out of vertical alignment with the 44px action row.
+`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading;
+it overrides no Toolbar styles. The leading zone holds an optional icon (a normal
+bordered `ToolbarControlGroup` given a brand fill with a matching border) and the
+title as extra-large `ToolbarText`, and the app's `actions` go straight into the
+trailing zone (typically as a `ToolbarControlGroup`). The icon group is omitted
+when no icon is passed. The optional summary is a separate row aligned below the
+title, so it cannot pull the icon group out of vertical alignment with the
+title and action row.
 
 `ValueTable` composes typed `ValueTableRow` entries. A row owns its `dt`/`dd`
 semantics and may receive a leading `SafeHtml` icon. Every row keeps 8px of
@@ -153,10 +153,47 @@ overrides load later in the cascade or set scoped `--kui-*` variables. JavaScrip
 modules are pure except the browser style wrappers and `@kerfjs/ui/select/register`,
 which registers exactly the Web Awesome elements used by `Select`. Eventful
 helpers such as `wireResizableRegions` and `wireTabBars` attach listeners only
-when called and return disposers. CSS, the generated wrappers that make it
+when called and return disposers. `wireTokenSearchFields` goes one step further:
+by default it also owns the collapsible field's transient expand/collapse/focus
+(activate to reveal and focus, Escape or empty blur to collapse), holding that
+state in a signal it exposes on the returned handle. An app reads that signal in
+render, hands in its own via `collapsible.signals`, drives it through
+`handle.open`/`handle.close`, or disables any individual behavior — so transient
+UI is consistent by default without every app reinventing it.
+
+`wireTokenSearchFields` is a deliberate exception, not the rule for `wire…`
+helpers. Its collapse behavior was *rich and error-prone* — reveal, focus
+transfer, Escape, empty-blur collapse, focus return — the kind of transient chrome
+apps kept reimplementing inconsistently, so the helper owns it. Everywhere else the
+app's state is **domain or persisted, not transient chrome, and stays app-owned**: a
+`NavStack`'s view stack is navigation history, a `TabBar`/`TabScaffold`'s selection
+and tab order are data, a `ResizableRegion`'s committed size and a
+`Workbench`/`SplitView` rail's `collapsed` flag are persisted layout preferences.
+Each helper already owns only the *ephemeral mechanics* around that state —
+`wireNavStack` the push/pop animation, `wireTabBars` the overflow autoscroll and
+drag preview, `wireResizableRegions` the live drag preview — and reports committed
+changes through callbacks. A `MenuHeader` `toggle` disclosure's `expanded` is
+likewise app-owned: it is a one-line boolean the app already tracks and must read to
+render the section body, so a managed helper would remove no real complexity. Reach
+for a managed default only when the transient behavior is substantial enough that
+hand-rolling it produces genuine, inconsistent variation.
+
+CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
 effects.
 
+A value-bearing component's `placeholder` prop is a first-class loading mode: the
+component renders its own real chrome (labels, icon and action affordances,
+container geometry) while replacing each **value** slot with a subtle, deliberately
+unanimated `Skeleton` block and disabling its own interactive controls
+(`aria-busy`, dropped `data-action`, disabled buttons). Sizes and shapes stay
+identical to the populated component, so a parent composes a faithful loading view —
+an inspector, a detail pane — from placeholder children without hand-rebuilding
+markup. The application still owns the loading lifecycle (when to pass `placeholder`)
+and which slots are unknown; the standalone `Skeleton` covers custom slots. It is a
+placeholder, not progress: use `LoadingSpinner` for known busy activity, and never
+animate the skeleton.
+
 Package source styles express root-scaled geometry with `remify(<px>)`; the
 build converts it against the 16px authoring baseline and exposes only ordinary
 `rem` CSS. Literal pixels remain for intentional hairlines, and `em` remains

package/docs/component-selection.md

@@ -15,6 +15,15 @@ The application adapter is usually a plain function that maps domain state to
 component props plus stable `data-action` values. It is not a fork of package
 markup or CSS.
 
+**Don't fight the components.** The package is built to look right unstyled, so
+custom CSS is the exception. Before adding `padding`, `margin`, `width`, `height`,
+`border`, `background`, a wrapper card, or a decoration, check whether the
+component, the pane, or the content-item already owns it — it almost always does,
+and adding more usually double-insets or fights it. Trust component defaults and
+fix the surrounding layout instead of overriding a control. See
+[`design-philosophy.md`](./design-philosophy.md) "Reach for the primitive, not for
+CSS".
+
 ## Production recipes
 
 Use the [complete recipe guide](./recipes.md) when several primitives form one
@@ -29,6 +38,7 @@ application boundary:
 | Composer form | [Catalog](../ux-demo/) · `?component=recipe-composer-form` |
 | List workspace states | [Catalog](../ux-demo/) · `?component=recipe-list-workspace-states` |
 | Compact toolbar choices and actions | [Catalog](../ux-demo/) · `?component=recipe-compact-toolbar` |
+| Navigation stack | [Catalog](../ux-demo/) · `?component=recipe-navigation-stack` |
 
 Recipes use public production exports and show ownership boundaries; they are
 copyable reference compositions, not new monolithic components.
@@ -50,35 +60,75 @@ an upstream component or recipe request.
 | --- | --- | --- | --- | --- | --- | --- |
 | Icon — `LucideIcon` | A decorative or explicitly labeled Lucide-compatible icon belongs in app UI. | Do not use an icon as the only name of an unfamiliar action; add visible or accessible text. Prefer it over Web Awesome `wa-icon`. | None. | Icon choice and meaningful label. | `@kerfjs/ui/lucide-icon` | [Accessibility](./accessibility.md#shared-rules) |
 | Disclosure indicator — `DisclosureArrow` | A control needs one animated 18px root-scaled visual for open and closed state, including configurable directions or a replacement icon. | Do not use it as the interactive control or accessible name; place it inside the button or control that exposes expanded state. | Pass the controlled `open` state, render it inside the owning control, author replacement icon content facing right before transforms, and override `--kui-disclosure-arrow-size` only when another visual size is required. Direction changes use the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. | Open state, interaction, accessible name, size override, replacement glyph, direction choices, and shortest-path rotation. | `@kerfjs/ui/disclosure-arrow` | [Component ownership](./component-contract.md#ownership-boundaries) |
-| Application toolbar — `Toolbar` | Leading identity, optional centered content, and trailing controls form one horizontal app bar. | Do not use it for a page title and one page action; use `PageHeader`. Do not use it as a dialog heading; use `DialogHeader`. | Compose `ToolbarText` and `ToolbarControlGroup` where their contracts fit. | Actions, command availability, responsive relocation, and state. | `@kerfjs/ui/toolbar` | [Toolbar composition](../README.md#component-subpaths) |
+| Application toolbar — `Toolbar` | Leading identity, optional centered content, and trailing controls form one horizontal app bar. | Do not use it for a page, panel, or dialog heading; use `PanelHeader`. | Compose `ToolbarText` and `ToolbarControlGroup` where their contracts fit. | Actions, command availability, responsive relocation, and state. | `@kerfjs/ui/toolbar` | [Toolbar composition](../README.md#component-subpaths) |
 | Toolbar control cluster — `ToolbarControlGroup` | Related toolbar controls need contained, borderless, pressed, or single-control treatment. | Do not use it merely to align unrelated buttons; use toolbar slots or ordinary layout. Web Awesome `wa-button-group` is only for an exceptional grouped-action contract. | Delegate child actions; use `SegmentedControl` for an exclusive choice. | Actions, pressed/expanded state, and policy. | `@kerfjs/ui/toolbar-control-group` | [Component ownership](./component-contract.md#ownership-boundaries) |
-| Toolbar identity text — `ToolbarText` | A toolbar needs large, default, or compact textual identity. | Do not substitute it for document heading semantics; use `PageHeader` or native headings. | None. | Text and responsive priority. | `@kerfjs/ui/toolbar-text` | [Toolbar composition](../README.md#component-subpaths) |
+| Toolbar identity text — `ToolbarText` | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity. | Do not substitute it for document heading semantics; use `PanelHeader` or native headings. | None. | Text and responsive priority. | `@kerfjs/ui/toolbar-text` | [Toolbar composition](../README.md#component-subpaths) |
 | Navigation row — `MenuItem` | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row. | Do not put a control in `trailing`; use `MenuActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget. | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. | Routing, selection, permissions, copy, action handling, and domain `data-*` values. | `@kerfjs/ui/menu-item` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Navigation row with trailing action — `MenuActionRow` | A full-width row needs a selectable primary action and an independently focusable trailing action. | Use `MenuItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar. | Delegate both action strings; update controlled selection and any popover/context-menu state in the app. | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior. | `@kerfjs/ui/menu-action-row` | [Accessibility](./accessibility.md#menuactionrow) |
-| Navigation section heading — `MenuHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page or dialog title; use `PageHeader` or `DialogHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/menu-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Navigation section heading — `MenuHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use `PanelHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/menu-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Application layout composition | A sidebar, main area, inspector, or dialog needs shared toolbar/content/footer and child geometry. | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane. | Use `.kui-pane` and one `.kui-pane__content`; add `.kui-content` and `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge. | Layout hierarchy, reading width, scroll ownership, responsive relocation, and pane visibility state. | `@kerfjs/ui/layout.css` | [Pane anatomy](./layout.md#anatomy) |
 | Menu composition | Navigation sections need full-size rows and the same content-item geometry as every other pane. | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `MenuItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract. | Compose `MenuHeader`, `MenuItem`, and `MenuActionRow` in `.kui-content`; use `MenuHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions. | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides. | `@kerfjs/ui/layout.css` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer` | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip. | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive. | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer. | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon. | `@kerfjs/ui/resizable-region` | [ResizableRegion contract](./accessibility.md#resizableregion) |
 | One application tab — `AppTab` | A controlled app tab needs selection, close, drag, leading/trailing anatomy, safe domain metadata, or a product-specific close glyph. | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive. | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`. | Tab identity, order, selection, close policy, content, and domain metadata values. | `@kerfjs/ui/app-tab` | [Tabs contract](./accessibility.md#tabs) |
 | Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs` | Tabs switch page regions and may overflow, close, or reorder. | Do not use it for a compact local view toggle; use `SegmentedControl`. Do not use it for a long choice list; use `Select`. Prefer it over Web Awesome `wa-tab-group`, `wa-tab`, and `wa-tab-panel` for Kerf app tabs. | Call `wireTabBars` once, retain the disposer, and apply `onReorder` synchronously; `reorderTabs` is the default array helper. | Ordered tabs, selection, panels, routing, closing, and persistence. | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars` | [Tabs contract](./accessibility.md#tabs) |
-| Page title and action — `PageHeader` | A page needs its primary heading and an optional trailing action. | Do not use it as persistent app chrome; use `Toolbar`. Do not use it inside a modal task; use `DialogHeader`. | Delegate an optional action normally. | Page title, action, and responsive placement. | `@kerfjs/ui/page-header` | [Header ownership](./component-contract.md#extracted-versus-application-specific) |
-| Dialog title and summary — `DialogHeader` | A dialog needs a toolbar-aligned title, optional summary/id and icon, and grouped actions wired to the dialog's ARIA references. | Do not use it as the page's `h1`; use `PageHeader`. It supplies header structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. | Connect title and optional summary ids to the dialog host, pass action children directly, localize `actionsLabel` when the group needs a name, and delegate actions. | Open state, focus lifecycle, dismissal, actions, labels, and copy. | `@kerfjs/ui/dialog-header` | [Header ownership](./component-contract.md#extracted-versus-application-specific) |
+| Panel, dialog, or page heading — `PanelHeader` | A panel, dialog, or page needs a heading with an extra-large title, an optional icon and subtitle, and trailing actions. | Do not use it as persistent app chrome; use `Toolbar`. It supplies header structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. | Connect the title id and any provided summary id to the dialog or panel host, pass the trailing controls (typically a `ToolbarControlGroup`), and delegate their actions. | Open state, focus lifecycle, dismissal, the trailing controls, labels, and copy. | `@kerfjs/ui/panel-header` | [Header ownership](./component-contract.md#extracted-versus-application-specific) |
 | Key/value facts — `ValueTable`, `ValueTableRow` | Read-only labels and values form a semantic definition list, optionally with a leading icon. | Do not use it for editable form fields or a row/column data grid; use native form or table semantics. | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context. | Values, formatting, icon meaning, and empty/loading policy. | `@kerfjs/ui/value-table` | [Component ownership](./component-contract.md#ownership-boundaries) |
 | Indeterminate activity — `LoadingSpinner` | A Kerf surface needs compact, labeled or decorative indeterminate progress. | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface. | None; pass a label when the spinner conveys status. | Loading lifecycle and adjacent status copy. | `@kerfjs/ui/loading-spinner` | [Accessibility](./accessibility.md#shared-rules) |
+| Loading placeholder — `Skeleton` + a component's `placeholder` prop | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent. | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free. | Set `placeholder` on a value-bearing component (`Select`, `MenuHeader`, `MenuItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `MenuActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot. | Loading lifecycle, which slots are unknown, and announcing the loading region. | `@kerfjs/ui/skeleton` | [Accessibility](./accessibility.md#shared-rules) |
 | Value selection — `Select` | A controlled form value comes from a moderate or long choice list, possibly grouped or icon-bearing. | Do not use it for commands; use a real action menu. Do not use it for a small visible choice set; use `SegmentedControl`. Prefer it over direct `wa-select`, `wa-option`, or value-like `wa-dropdown`/`wa-dropdown-item` composition. | Import `@kerfjs/ui/select/register` once; listen for standard input/change events. | Controlled value, validation, choices, and domain mapping. | `@kerfjs/ui/select` | [Web Awesome integration](../README.md#web-awesome-theme) |
 | Small exclusive choice — `SegmentedControl` | A few visible choices switch a compact view or setting, with toolbar, rounded, or pill presentation. | Do not use it for tabpanel semantics; use `TabBar`. Do not use it for many choices; use `Select`. Prefer it over `wa-button-group` when the controls select one value. | Delegate its action, read `data-segment-value`, update `value`, and rerender. | Controlled value, labels, action, and persistence. | `@kerfjs/ui/segmented-control` | [SegmentedControl contract](./accessibility.md#segmentedcontrol) |
-| Structured search editor — `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields` | Free text and ordered, editable, removable filter tokens share one searchbox; enable `collapsible` when an empty, unfocused field should reduce to one iconic action, standalone or in a toolbar group. | Do not use it for ordinary text entry; use a native input or Web Awesome `wa-input`. Do not use it when filters belong in separate form controls. | Read DOM-owned text on input, empty `textContent` on clear, and use `placeTokenSearchCaret` after explicit controlled focus changes. Call `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` once so Enter submits without adding a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. In `collapsible` mode, control `expanded`, transfer focus after activation, and clear the transient state after focus leaves. | Parsing, suggestions, tokens, query execution, results, announcements, and the transient focus/open signal. | `@kerfjs/ui/token-search-field` | [TokenSearchField contract](./accessibility.md#tokensearchfield) |
+| Structured search editor — `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields` | Free text and ordered, editable, removable filter tokens share one searchbox; enable `collapsible` when an empty, unfocused field should reduce to one iconic action, standalone or in a toolbar group. | Do not use it for ordinary text entry; use a native input or Web Awesome `wa-input`. Do not use it when filters belong in separate form controls. | Read DOM-owned text on input, empty `textContent` on clear, and use `placeTokenSearchCaret` after explicit controlled focus changes. Call `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` once so Enter submits without adding a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. In `collapsible` mode it also manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse); bind the field's `expanded` to the signal on the returned handle (`handle.expanded(id)`) or adopt your own via `collapsible.signals`, and opt out per behavior only when the app must own it. | Parsing, suggestions, tokens, query execution, results, announcements, and — only if overriding the default — the collapsible `expanded` signal. | `@kerfjs/ui/token-search-field` | [TokenSearchField contract](./accessibility.md#tokensearchfield) |
 | Persistent inline status — `StateBanner` | A neutral, info, success, warning, or danger message belongs next to the affected work. | Do not use it for a no-content screen; use `EmptyState`. Do not use it for transient confirmation; use a toast. Web Awesome `wa-callout` is the ecosystem alternative for Web Awesome-owned content. | Delegate an optional action; choose alert urgency only for attention-requiring failure. | State mapping, message lifetime, retry/action behavior, and copy. | `@kerfjs/ui/state-banner` | [Feedback accessibility](./accessibility.md#shared-rules) |
 | Empty or busy content area — `EmptyState` | A content region has no items, cannot proceed, or is loading and needs explanation plus an optional action. | Do not use it for an inline status update; use `StateBanner`. Do not use it for transient success; use `wa-toast`/`wa-toast-item` or the application's toast system. | Delegate its optional action; it composes `LoadingSpinner` when busy. | Empty/busy policy, recovery action, illustration, and copy. | `@kerfjs/ui/empty-state` | [Feedback ownership](./component-contract.md#extracted-versus-application-specific) |
 
 ## Ambiguous choices
 
-- `Toolbar` is persistent app chrome; `PageHeader` identifies a page; `DialogHeader` labels a focused modal task.
+- `Toolbar` is persistent app chrome; `PanelHeader` heads a panel, dialog, or page.
 - `TabBar` changes tabpanels and supports overflow/reorder; `SegmentedControl` chooses among a few compact views; `Select` handles a longer value list.
 - `StateBanner` persists beside affected work; `EmptyState` replaces absent content; `wa-callout` is contextual ecosystem content; `wa-toast` and `wa-toast-item` are transient and must not carry the only copy of important state.
 - `ResizableRegion` is an interactive controlled pane. CSS grid is the right answer when columns do not need a user-operable separator.
 - `TokenSearchField` is a structured editor. A native input or `wa-input` is the right answer for ordinary text.
 
+## Toolbar composition
+
+A `Toolbar` has three zones — `leading`, `center`, and `trailing`. In almost
+every case the only things that go **directly** in a zone are `ToolbarText`
+(identity/title text) and `ToolbarControlGroup` (any control or cluster of
+controls). Do not drop bare buttons, inputs, links, or arbitrary markup straight
+into a zone; wrap controls in a `ToolbarControlGroup` so they get the shared
+toolbar geometry, hover/pressed treatment, and grouping. `SegmentedControl`,
+`Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live
+**inside** a `ToolbarControlGroup`, not loose in the zone. `PanelHeader` is the
+one wrapper that composes these for you as a panel/dialog/page heading.
+
+Common toolbar patterns:
+
+| Want | Put in the zone | Notes |
+| --- | --- | --- |
+| Identity or title text | `<ToolbarText text="…" size="large" />` (or `xlarge` for a page/panel title) | Wrap in a `single` borderless group only when it must align with adjacent control pills |
+| One or more icon/text buttons | `<ToolbarControlGroup>{buttons}</ToolbarControlGroup>` | Use `buttonAppearance="push"` for toggle buttons with `aria-pressed`; `single` for a lone control |
+| An exclusive view switch | `<ToolbarControlGroup><SegmentedControl … /></ToolbarControlGroup>` | Not `TabBar`, which switches tabpanels |
+| A value list | `<ToolbarControlGroup><Select … /></ToolbarControlGroup>` | Register `@kerfjs/ui/select/register` once |
+| A collapsible search box | `<ToolbarControlGroup single><TokenSearchField collapsible … /></ToolbarControlGroup>` | The group animates the iconic ↔ expanded states; `wireTokenSearchFields` manages expand/collapse/focus by default |
+
+A **popup menu in a toolbar** is a `single` `ToolbarControlGroup` wrapping a Web
+Awesome `wa-dropdown`: its `slot="trigger"` `wa-button` is the toolbar button and
+the `wa-dropdown-item`s are the menu. Keep the dropdown's managed light-DOM
+children under `data-morph-skip-children` so kerf does not reconcile Web Awesome's
+own DOM.
+
+```tsx
+<ToolbarControlGroup single>
+  <wa-dropdown placement="bottom-start" data-morph-skip-children>
+    <wa-button slot="trigger" appearance="plain" with-caret aria-label="Sort">
+      <LucideIcon icon={ArrowDownAZ} name="arrow-down-a-z" />
+    </wa-button>
+    <wa-dropdown-item data-action="sort-recent">Recently updated</wa-dropdown-item>
+    <wa-dropdown-item data-action="sort-priority">Priority</wa-dropdown-item>
+  </wa-dropdown>
+</ToolbarControlGroup>
+```
+
 ## Correct composition and duplicated-markup trap
 
 Correct: let the pane stay unpadded while its children own the shared 8/1/8

package/docs/design-philosophy.md

@@ -18,12 +18,27 @@ A reference image defines hierarchy, relationships, and intended feel. It does n
 
 ### Continuity is correctness
 
-Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
+Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the *ephemeral mechanics* around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireTokenSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
 
 ### Hierarchy precedes decoration
 
 Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction.
 
+### Reach for the primitive, not for CSS
+
+The package is designed to look right *unstyled*. A screen built from the
+primitives, their props, and the semantic tokens should already read well, so
+custom CSS is the exception. Before adding any `padding`, `margin`, `width`,
+`height`, `border`, `background`, wrapper card, or decoration, check whether the
+component, the pane, or the content-item already owns it — it almost always does,
+and adding more usually **double-insets** or fights the component (the most common
+mistake). Trust component defaults: render a control at its natural size and color
+and fix the surrounding layout rather than overriding the control. Legitimate
+custom CSS is limited to genuinely new structure, and even then may only join a
+component's documented `publicClasses` or override documented `--kui-*` tokens at a
+real composition boundary — never size, space, or re-skin a primitive by hand, and
+never build a heading, toolbar, card, or pane geometry that a primitive provides.
+
 ### Panes share one child-owned geometry
 
 Sidebars, main areas, inspectors, and dialogs use the same unpadded pane. Their
@@ -80,6 +95,13 @@ foregrounds compatible with Hot Sheet 2 and Web Awesome. Consumers may replace
 the global palette, one semantic role, or one component instance through
 documented custom properties without rewriting component CSS.
 
+Spacing is likewise a finite, semantic scale, not a free measurement. Five
+canonical steps — 0, 4, 8, 16, and 24px, each a `--kui-space-*` token — map to a
+single relationship apiece, chosen by how connected two elements are: no
+separation, very minor air, standard within a group, between homogeneous groups,
+and major between heterogeneous groups. Off-scale values (12px, 32px) are
+deliberate exceptions. See [`layout.md`](layout.md) "Spacing scale".
+
 ### Responsive design reprioritizes
 
 Protect primary content, readable type, recognizable icons, and usable targets. Relocate secondary information before compressing it below a usable scale. Keep one clear scroll owner per region and test narrow, wide, zoomed, and intermediate layouts.

package/docs/device-class.md

@@ -0,0 +1,54 @@
+# Device class
+
+`@kerfjs/ui/device-class` reports the current viewport as a reactive **device
+class** — a size bucket × orientation × viewport-segment count — so a layout can
+pick its presentation from one signal instead of hand-wiring `matchMedia`. It is
+the foundation the app/dialog layouts build on (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+```ts
+import { deviceClass } from '@kerfjs/ui/device-class';
+
+const device = deviceClass(); // ReadonlySignal<DeviceClass>
+
+effect(() => {
+  if (device.value.compact) showStack();
+  else showSplit();
+});
+```
+
+## `DeviceClass`
+
+| Field | Meaning |
+| --- | --- |
+| `size` | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop` |
+| `orientation` | `portrait` \| `landscape` |
+| `segments` / `verticalSegments` | viewport segment counts (foldables / dual-screen); `1` on ordinary devices |
+| `handset` | `xs-mobile` or `mobile` |
+| `compact` | "one pane at a time" — a handset or a portrait tablet |
+| `atLeast(size)` | true when the current size is `size` or larger |
+
+Reading `device.value` inside an `effect`/`computed` re-runs when the viewport
+crosses a breakpoint, rotates, or changes its segment count. One shared viewport
+source backs every reader.
+
+## Breakpoints
+
+Default minimum widths (px): `mobile` 360, `tablet` 720, `desktop` 1024,
+`xl-desktop` 1440. Override per reader:
+
+```ts
+const device = deviceClass({ breakpoints: { tablet: 900 } });
+```
+
+The same numbers are mirrored as CSS custom properties in the foundation
+(`--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`)
+so CSS media queries and the JS signal read one source. `classifyViewport(width,
+orientation, segments?, verticalSegments?, breakpoints?)` is exported as the
+pure, DOM-free bucketing core.
+
+## Server rendering
+
+Without a DOM, `deviceClass()` resolves to an SSR default (1024×768, landscape,
+one segment) and hydrates to the real class on the client. Override the assumed
+viewport with `deviceClass({ ssr: { width, height } })`.

package/docs/layout.md

@@ -38,7 +38,7 @@ changing its geometry by setting `--kui-content-item-border` and
 `--kui-content-item-background`.
 
 A visible parent surface does not make every child another visible card. The
-composer recipe keeps its form as the single surface, uses `DialogHeader` for
+composer recipe keeps its form as the single surface, uses `PanelHeader` for
 its task hierarchy, and places field and action control edges on the shared 8px
 inline gutter instead of nesting them inside another padded content item. A
 conditional `StateBanner` remains visibly distinct because it communicates
@@ -58,7 +58,7 @@ semantic status.
 | Explicit scroll owner outside a pane | `.kui-scroll-owner` | `overflow: auto` |
 
 The component layer applies the same contract to `Toolbar`, `MenuHeader`,
-`MenuItem`, `PageHeader`, `DialogHeader`, `StateBanner`, `ValueTable`,
+`MenuItem`, `PanelHeader`, `StateBanner`, `ValueTable`,
 `ValueTableRow`, tabs, and form controls. A value-table row separator starts at
 the row's 8px content inset, or at 40px when the row contains its 24px leading
 icon and 8px gap, and always ends 8px from the right edge. Each value-table row
@@ -66,12 +66,37 @@ also keeps 8px of root-scaled block padding independently of its semantic inline
 inset. Most interactive rows and toolbar groups are 44px tall.
 Toolbar groups reserve a real 1px outer border around a 42px inner area, even
 when their border and background are transparent.
-`PageHeader` keeps its title on the shared inset while its action border aligns
-with the logical edge of the following `.kui-content-item` border.
-`DialogHeader` applies the same rule internally: its icon/title identity is a
-borderless group in a top toolbar, its direct action children are wrapped in a
-contained group, and its optional subtitle is a separate row aligned below the
-title. The icon visual is 24px inside a 34px circular background.
+`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading
+and overrides no Toolbar styles. The leading zone holds the optional icon (a
+normal bordered `ToolbarControlGroup` given a brand fill with a matching border,
+a 22px glyph) and the title as extra-large `ToolbarText`; the app's trailing
+controls go straight into the trailing zone, and the icon group is omitted when
+no icon is passed. The optional subtitle is a separate row below the toolbar, its
+text left-aligned with the title text.
+
+## Spacing scale
+
+Spacing is not a free choice. The official scale is five canonical steps, each
+expressing exactly one relationship — pick the step by **how connected two
+elements are**, not by eye. Every scalable value is `remify`-authored against the
+fixed 16px baseline, so it delivers as `rem`.
+
+| Value | Token | Relationship — when to use |
+| --- | --- | --- |
+| 0px | `--kui-space-none` | No separation. The elements read as a single unit (a control and its own affordance, adjacent `MenuItem` rows). |
+| 4px | `--kui-space-2xs` | Very minor. Still one connected cluster, but readability or aesthetics demand a hair of air (inline metadata, an icon beside its label). |
+| 8px | `--kui-space-xs` | Standard. Between elements **within a group** — the content-item padding/gutter, gaps between toolbar controls in a group. |
+| 16px | `--kui-space-m` | Minor. Between **homogeneous groups** — two lists, two sibling sections of the same kind. |
+| 24px | `--kui-space-l` | Major. Between **heterogeneous groups** — the `.kui-content` rhythm between major, differing regions. |
+
+The two relationships that get confused most are 8px vs 24px: 8px is *inside* a
+group, 24px is *between* major, differing regions. 16px sits between them for
+same-kind groups.
+
+`--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the
+canonical rhythm** — reach for them only as a deliberate exception, never as a
+default step. Prefer the five canonical tokens so spacing stays legible and
+consistent across every surface.
 
 ## Ownership rules
 

package/docs/nav-stack.md

@@ -0,0 +1,47 @@
+# Navigation stack
+
+`@kerfjs/ui/nav-stack` is an iOS-style push/pop navigation stack: views slide in
+and out over one another while the top chrome settles. A **single-pane layout is
+a `NavStack` with one entry**. It is one of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+Import the component and its companion stylesheet:
+
+```ts
+import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
+import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
+import '@kerfjs/ui/nav-stack.css';
+```
+
+## State lives in the app
+
+Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
+stack as a `signal<NavStackView[]>`, `NavStack({ views })` renders it, and
+`wireNavStack` animates the transitions.
+
+```tsx
+const views = signal<NavStackView[]>([{ key: 'inbox', title: 'Inbox', content: <InboxView /> }]);
+
+// render inside mount():
+<NavStack id="mail" label="Mail" views={views.value} />;
+
+// once, after first render:
+const dispose = wireNavStack(root, { onBack: () => { views.value = views.value.slice(0, -1); } });
+
+// push / pop by editing the signal:
+views.value = [...views.value, { key: id, title: 'Message', content: <MessageView id={id} /> }];
+```
+
+`NavStack` renders every entry stacked, the last one active and the rest kept
+mounted (so their DOM state and focus survive) but hidden. Each entry carries a
+`key` (stable identity), `content`, an optional `title`, and optional per-view
+`toolbar` actions. The back control appears automatically once the stack has more
+than one entry; `wireNavStack`'s `onBack` is where the app pops its own signal.
+
+## Transitions
+
+`wireNavStack(root, { onBack, duration? })` observes the rendered stack and
+animates each change: a pushed view slides in from the trailing edge; a popped
+view slides back off it over the revealed view. It returns a disposer. The
+animation honors `prefers-reduced-motion` (transitions collapse to instant) and
+`duration: 0` disables it. Applicable at every device size and inside dialogs.

package/docs/recipes.md

@@ -56,7 +56,7 @@ no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
 [Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
 
-`PageHeader` owns the page heading while one control cluster holds secondary,
+`PanelHeader` owns the page heading while one control cluster holds secondary,
 overflow, and primary actions. The app owns authorization and command policy;
 controls relocate without changing focus order.
 
@@ -66,10 +66,10 @@ controls relocate without changing focus order.
 
 The production Web Awesome dialog owns modal focus and Escape; the thin recipe
 adapter restores the invoking control consistently after the hide event.
-`DialogHeader`, `MenuHeader`, `MenuItem`, and `ValueTable` own their included
+`PanelHeader`, `MenuHeader`, `MenuItem`, and `ValueTable` own their included
 anatomy. The application owns open state, selection, dismissal policy, and
-record actions. Pass the dialog action children directly; `DialogHeader` places
-them in its top toolbar's action group and uses the localized `actionsLabel`.
+record actions. `PanelHeader` places the trailing controls the app passes
+directly into its top toolbar's trailing zone.
 The header sits on the dialog edge while retaining its internal control inset;
 the selected title receives the full content gutter, the metadata table fills
 the available detail width between the usual outer margins, and the action
@@ -80,7 +80,7 @@ Do not rebuild the dialog or reach into private shadow parts.
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
-`DialogHeader` supplies the task title and summary, with their ids referenced
+`PanelHeader` supplies the task title and summary, with their ids referenced
 by the form. Production fields own labels, help, and native focus. The field
 and footer control edges sit directly on the shared 8px inline gutter rather
 than acquiring a second content-item padding inset; major children remain 24px
@@ -109,6 +109,18 @@ visible exclusive choices, `Select` for a longer value list, and an ordinary
 button for an independent command. The app owns values, actions, persistence,
 and responsive priority.
 
+## Navigation stack
+
+[Open the recipe](../ux-demo/?component=recipe-navigation-stack) · [TSX source](../ux-demo/recipes/navigation-stack.tsx)
+
+Drill from a library list into a detail and back with `NavStack`
+(`@kerfjs/ui/nav-stack`): the app owns the stack as a signal of views and
+pushes/pops it, `NavStack` renders it, and `wireNavStack` slides the content and
+settles the chrome (reduced motion collapses the slide to instant). A live
+`deviceClass()` badge shows the current size/orientation. See the layout guide
+[`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
+`Workbench`, and `TabScaffold`.
+
 ## Rules shared by every recipe
 
 - Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one

package/docs/split-view.md

@@ -0,0 +1,49 @@
+# Split view (list-detail)
+
+`@kerfjs/ui/split-view` is a list-detail (master-detail) layout: a list and a
+detail side by side on roomy screens, collapsing to a `NavStack` (list → detail)
+on compact ones. One of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+```ts
+import { SplitView } from '@kerfjs/ui/split-view';
+import { deviceClass } from '@kerfjs/ui/device-class';
+import '@kerfjs/ui/split-view.css';
+// plus nav-stack.css when the compact path is reachable, and
+// wireResizableRegions / wireNavStack for the interactive behavior.
+```
+
+## Responsive by device class
+
+`SplitView` is declarative; the app derives `compact` from the device class and
+tracks its own selection:
+
+```tsx
+const device = deviceClass();
+const selected = signal<string | null>(null);
+
+<SplitView
+  id="mail"
+  label="Mail"
+  compact={device.value.compact}
+  detailActive={selected.value !== null}
+  list={<ThreadList />}
+  detail={<Message id={selected.value} />}
+  listTitle="Threads"
+  detailTitle="Message"
+  resizable={{ size: 320, min: 220, max: 480 }}
+/>;
+```
+
+- **Roomy** (`compact: false`): both panes show. With `resizable`, the list sits
+  in a `ResizableRegion` (wire it with `wireResizableRegions`); without it the
+  list takes a fixed `--kui-split-view-list-width` (default 320px) and the detail
+  fills the rest.
+- **Compact** (`compact: true`): the split collapses to a `NavStack`. The list is
+  the root; when `detailActive` is true the detail is pushed over it with an
+  automatic back control (wire it with `wireNavStack`, whose `onBack` clears the
+  app's selection). This is the portrait-tablet / handset presentation; as a
+  dialog the compact form is a full-screen or large partial-cover modal.
+
+Compose the interactive wiring from the existing helpers — `SplitView` adds no
+wire of its own.

package/docs/tab-scaffold.md

@@ -0,0 +1,41 @@
+# Tab scaffold
+
+`@kerfjs/ui/tab-scaffold` is a mobile-first, iOS-like bottom tab bar that switches
+between major app sections, where **each tab keeps its own content mounted** —
+usually a `NavStack`, so each tab's stack and scroll survive a switch. One of the
+opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+It is distinct from `TabBar` (document-oriented, reorderable strips).
+
+```ts
+import { TabScaffold } from '@kerfjs/ui/tab-scaffold';
+import { wireTabScaffold } from '@kerfjs/ui/wire-tab-scaffold';
+import '@kerfjs/ui/tab-scaffold.css';
+```
+
+## Controlled selection
+
+The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
+(only the active one visible) plus the bottom bar, and `wireTabScaffold` reports
+clicks.
+
+```tsx
+const active = signal('home');
+
+<TabScaffold
+  id="app"
+  label="Sections"
+  active={active.value}
+  tabs={[
+    { id: 'home', label: 'Home', icon: <HomeIcon />, content: <HomeStack /> },
+    { id: 'search', label: 'Search', icon: <SearchIcon />, content: <SearchStack /> },
+  ]}
+/>;
+
+// once, after first render:
+const dispose = wireTabScaffold(root, { onSelect: (id) => { active.value = id; } });
+```
+
+Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
+bottom bar respects the home-indicator safe area (`env(safe-area-inset-bottom)`)
+and keeps 44px targets. On larger device classes, promote the tab set to a
+`Workbench` rail or a persistent sidebar instead of a bottom bar.