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

package/docs/layout.md

@@ -1,29 +1,42 @@
 # Pane and content layout
 
-Import `@kerfjs/ui/layout.css` for the shared geometry used by sidebars, main
-areas, inspectors, and dialogs. The vocabulary deliberately describes structure
-rather than location: the same pane can be placed anywhere.
+Import `Pane` from `@kerfjs/ui/pane`. Browser-aware bundlers receive its CSS
+automatically; other consumers can import `@kerfjs/ui/pane.css`. Import
+`@kerfjs/ui/layout.css` as well when using the related content-item and control
+layout classes. The vocabulary deliberately describes structure rather than
+location: the same pane can be placed anywhere.
 
 ## Anatomy
 
 ```tsx
-<aside class="kui-pane">
-  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
-  <div class="kui-pane__content kui-content">
+<Pane
+  element="aside"
+  label="Workspace"
+  contentElement="nav"
+  contentLabel="Workspace pages"
+  separators={["inline-end"]}
+  header={<Toolbar label="Workspace" ... />}
+  footer={<Toolbar label="Actions" ... />}
+>
     <section>...</section>
     <section>...</section>
-  </div>
-  <footer class="kui-pane__footer"><Toolbar label="Actions" ... /></footer>
-</aside>
+</Pane>
 ```
 
-`.kui-pane` has no padding. It reserves rows for an optional toolbar, one
-scrolling content area, and an optional footer. A main area or dialog often
-omits the footer; a navigation pane commonly uses all three. Fixed chrome stays
-outside `.kui-pane__content`, which is the pane's scroll owner.
+`Pane` has no padding. It reserves rows for an optional vertical header, one
+scrolling vertical content area, and an optional footer. A header may contain a
+top toolbar followed by secondary toolbar or status rows. A main area or dialog
+often omits the footer; a navigation pane commonly uses all three. Fixed chrome
+stays outside `.kui-pane__content`, which is the pane's only scroll owner.
+
+Pass any combination of logical sides to `separators`: `block-start`,
+`block-end`, `inline-start`, and `inline-end`. Every line is off by default and
+each enabled side uses `--kui-pane-separator-width` (1px) and
+`--kui-pane-separator-color` (`--kui-color-border`). Logical sides keep pane
+boundaries correct in both left-to-right and right-to-left layouts.
 
 `.kui-content` is a vertical stack with a 24px gap between major children.
-Sections may contain adjacent `MenuItem` rows without adding another major gap.
+Sections may contain adjacent `ListItem` rows without adding another major gap.
 Ordinary surface-like children use `.kui-content-item` and own their complete
 geometry:
 
@@ -37,8 +50,15 @@ Use `.kui-content-item--pill` for the 22px pill radius expressed as
 changing its geometry by setting `--kui-content-item-border` and
 `--kui-content-item-background`.
 
+Nested selection and hover highlights stay concentric and match their owning
+control's shape. Their inner radius is the outer radius minus the full inset,
+expressed by the shared `--kui-layout-highlight-inset` token (2px by default).
+For example, `SegmentedControl` and `ToolbarControlGroup` place each highlight
+behind a 1px control border and 1px control padding, so a rounded control's 12px
+outer radius produces a 10px highlight radius; a 22px pill produces 20px.
+
 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 a heading `Toolbar` 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
@@ -46,19 +66,20 @@ semantic status.
 
 ## Public roles and tokens
 
-| Need | Class | Token / default |
-| --- | --- | --- |
-| Unpadded toolbar/content/footer structure | `.kui-pane` | — |
-| Scrolling pane content | `.kui-pane__content` | — |
-| Major vertical rhythm | `.kui-content` | `--kui-layout-content-gap: 24px` |
-| Self-contained child geometry | `.kui-content-item` | 8px margin + 1px border + 8px padding |
-| Pill child | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px` |
-| Related controls | `.kui-control-cluster` | `--kui-layout-control-gap: 8px` |
-| Inline metadata | `.kui-inline-metadata` | `--kui-layout-metadata-gap: 4px` |
-| 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`,
+| Need                                     | Class                     | Token / default                       |
+| ---------------------------------------- | ------------------------- | ------------------------------------- |
+| Unpadded header/content/footer structure | `Pane`, `.kui-pane`       | —                                     |
+| Scrolling pane content                   | `.kui-pane__content`      | —                                     |
+| Optional logical-edge separators         | `Pane.separators`         | `--kui-pane-separator-width: 1px`     |
+| Major vertical rhythm                    | `.kui-content`            | `--kui-layout-content-gap: 24px`      |
+| Self-contained child geometry            | `.kui-content-item`       | 8px margin + 1px border + 8px padding |
+| Pill child                               | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`      |
+| Related controls                         | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`       |
+| Inline metadata                          | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`      |
+| Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                      |
+
+The component layer applies the same contract to `Toolbar`, `ListHeader`,
+`ListItem`, `Toolbar`, `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 +87,122 @@ 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.
+Panel, dialog, and page headings are plain `Toolbar` compositions. The leading
+zone holds an optional icon `ToolbarControlGroup` and a direct extra-large
+`ToolbarText`; actions belong in a trailing group. Omit empty groups. Supporting
+copy is app-owned content below the toolbar and aligns with the intended content
+edge.
+
+## 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 `ListItem` 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.
+
+For `Row.gap` and `List.gap`, pass these token names directly (`gap="xs"`, `gap="m"`) or use
+`space('xs')` from `@kerfjs/ui/css-values` when composing a value in JavaScript.
+Use `rem`, `em`, `px`, `pct`, `lengthVar`, and `calc(plus(...))` only when a
+named spacing relationship does not express the requirement; do not pass raw
+CSS strings.
+
+## Text
+
+Use `Text` from `@kerfjs/ui/text` for ordinary semantic headings and
+paragraphs. Its required `variant` renders the corresponding native `h1`–`h6`
+or `p` element, and ordinary global, `data-*`, and `aria-*` attributes pass
+through. Every variant resets its native margin, owns a 1px transparent border,
+and supplies the standard 8px item padding; native typography remains available
+to the surrounding composition. Choose heading levels from the document
+outline, not for visual size. Toolbar identity and page-heading compositions
+continue to use `ToolbarText`.
+
+```tsx
+import { Text } from "@kerfjs/ui/text";
+
+<Text variant="h2" id="details-title">Details</Text>;
+<Text variant="p" aria-describedby="details-title">Supporting copy</Text>;
+```
+
+## Spacer
+
+Use `Spacer` from `@kerfjs/ui/spacer` for one intentional empty dimension that
+is not the repeated relationship owned by a parent's `gap`. Its `width` and
+`height` accept the same finite `UiSpaceName` vocabulary or a complete typed
+`CssLength`. Fixed spacers use `flex: 0 0 auto`, so flex layouts do not compress
+the requested dimension. Pass `flex` to use `1 1 auto` and consume the remaining
+space along a `Row`, `List`, or other flex parent's main axis.
+
+```tsx
+import { Row } from "@kerfjs/ui/row";
+import { Spacer } from "@kerfjs/ui/spacer";
+
+<Row gap="none">
+  <button>Back</button>
+  <Spacer flex />
+  <button>Save</button>
+</Row>;
+```
+
+Spacer is always decorative (`aria-hidden="true"`), accepts no children, and
+uses physical width and height. Prefer `Row.gap` or `List.gap` for uniform
+sibling rhythm, and never use Spacer to cancel or duplicate component-owned
+insets.
+
+## Row and List alignment
+
+Use `Row` for a horizontal flex layout and `List` for a vertical one. `Row`
+defaults to `hAlign="left"`, `vAlign="full"`, `gap="xs"`, and no wrapping;
+`List` retains its existing full-width, top-aligned defaults and zero gap.
+Both components accept the same physical-axis vocabulary:
+
+| Axis       | Values and aliases                                                                                                             | Flex behavior                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Horizontal | `left` / `l` / `flex-start`; `center` / `c` / `space-around`; `right` / `r` / `flex-end`; `full` / `f` / `space-between`       | Distributes a Row's children; aligns a List's children across its width.  |
+| Vertical   | `top` / `t` / `flex-start`; `middle` / `m` / `c` / `space-around`; `bottom` / `b` / `flex-end`; `full` / `f` / `space-between` | Aligns a Row's children across its height; distributes a List's children. |
+
+Cross-axis `space-around` and `space-between` are not valid `align-items`
+values. Kerf therefore maps `middle` to centered items and `full` to stretched
+items, while applying the requested distribution to `align-content` when a
+Row wraps. Prefer the descriptive values in application code; the short and
+CSS-shaped aliases are provided for compact or migrated call sites.
+
+`Row.flex` and `List.flex` share one typed participation contract. Omit the prop
+for the CSS initial value, pass `true` for `1 1 auto`, select the finite
+`"none"`, `"auto"`, or `"initial"` keyword, or use
+`flex(grow, shrink, basis)` from `@kerfjs/ui/css-values` for a complete branded
+shorthand. A `CssLength` is not a flex shorthand, and arbitrary strings are
+rejected by the type contract.
+
+Both components also accept `textInsets` and `controlInsets` using the shared
+physical `Sides` union. Values follow canonical top/right/bottom/left order
+(`t`, `rb`, `tbl`, `trbl`, and so on). A selected control side adds 8px of
+padding. A selected text side adds the complete content-item alignment inset —
+8px outer margin + 1px border + 8px inner padding, represented as 17px of
+container padding. When both props select the same side, the text inset wins.
+
+`ListInsetText` and `ListInsetControl` use the same `sides` vocabulary and
+default to `trbl`. The text wrapper applies its complete 8/1/8 geometry only on
+selected sides; the control wrapper applies its 8px outer margin only on
+selected sides. `ListInsetText.horizontalOnly` remains a deprecated alias for
+`sides="rl"`; an explicit `sides` value takes precedence.
+
+`--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
 
@@ -84,14 +215,14 @@ title. The icon visual is 24px inside a 34px circular background.
 4. Keep one scrolling content owner per pane. Toolbar and footer siblings stay
    fixed while the content scrolls.
 5. A split item keeps dormant and interactive regions separate. For example,
-   `MenuHeader` renders its title/count-or-badge cluster separately from its optional
+   `ListHeader` renders its title/count-or-badge cluster separately from its optional
    logical-end 44px action. The header fills the available inline width and its
    action glyph defaults to 18px; disclosure mode makes the title cluster itself
    the button and supplies the production `DisclosureArrow` unless `actionIcon`
    replaces it.
-   `MenuActionRow` uses a noninteractive row root around sibling 44px primary
-   and trailing buttons. `MenuItem.trailing` remains dormant content.
-   In multiline `MenuItem` and `MenuActionRow` rows, the leading icon stays
+   `ListActionRow` uses a noninteractive row root around sibling 44px primary
+   and trailing buttons. `ListItem.trailing` remains dormant content.
+   In multiline `ListItem` and `ListActionRow` rows, the leading icon stays
    centered on the label's first line rather than the full wrapped label.
 6. Reading width, column placement, and responsive relocation remain application
    decisions. The shared classes define local geometry, not the whole shell.

package/docs/nav-stack.md

@@ -0,0 +1,77 @@
+# 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 />,
+    bottomToolbar: <InboxStatus />,
+  },
+]);
+
+// 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 survives) but hidden. Each entry carries a
+`key` (stable identity), `content`, an optional `title`, optional per-view
+`toolbar` actions, and an optional per-view `bottomToolbar`. The component-level
+`bottomToolbar` remains a persistent fallback for views that do not provide one.
+The back control appears automatically once the stack has more than one entry;
+`wireNavStack`'s `onBack` is where the app pops its own signal.
+
+Focus follows the controlled stack automatically. On push, `wireNavStack`
+remembers the focused descendant of the departing view and moves focus into the
+new top view. On pop it restores that exact descendant when it still exists. A
+new view prefers a descendant marked `data-nav-focus`, then its first enabled
+focusable descendant, and finally the view container itself. Use
+`data-nav-focus` for a heading or primary control when DOM order is not the best
+initial reading position; it may use `tabindex="-1"` for programmatic focus.
+When a remembered control was removed during the controlled rerender, the same
+fallback order applies. Disposing the helper stops future transitions and
+cleans up any temporary fallback `tabindex` it added.
+
+## 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; and snapshots of the previous
+top and bottom chrome cross-fade into the active view's chrome. Focus moves to
+the new top view independently of animation duration. 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

@@ -14,12 +14,12 @@ the public `onCommit` callback, retains every disposer, and returns one
 idempotent disposer:
 
 ```ts
-import { createRecipe } from './navigation-sidebar.js';
-import { mountRecipe } from './mount-recipe.js';
+import { createRecipe } from "./navigation-sidebar.js";
+import { mountRecipe } from "./mount-recipe.js";
 
-const root = document.querySelector<HTMLElement>('#navigation')!;
+const root = document.querySelector<HTMLElement>("#navigation")!;
 const stopRecipe = mountRecipe(root, createRecipe(announce));
-window.addEventListener('pagehide', stopRecipe, { once: true });
+window.addEventListener("pagehide", stopRecipe, { once: true });
 ```
 
 The adapter is delivered as reference source, not a new package runtime export.
@@ -44,32 +44,32 @@ Adapt only public `--kui-layout-*` and component variables.
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
 One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
-`.kui-content` uses 24px major gaps; `MenuHeader`, `MenuItem`, and other
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
 `.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
 Rows and footer toolbar groups remain 44px tall. The app owns routes,
 permissions, labels, selection, valid section counts and their localized
 `countLabel` phrases, non-count badge content, disclosure state, and revealed
-content. A toggled `MenuHeader` supplies the production `DisclosureArrow` when
+content. A toggled `ListHeader` supplies the production `DisclosureArrow` when
 no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
 ## Workspace header
 
 [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,
+The page heading is a direct `Toolbar`/`ToolbarText` composition while one control cluster holds secondary,
 overflow, and primary actions. The app owns authorization and command policy;
 controls relocate without changing focus order.
 
-## Master-detail dialog
+## List-detail dialog
 
-[Open the recipe](../ux-demo/?component=recipe-master-detail-dialog) · [TSX source](../ux-demo/recipes/master-detail-dialog.tsx)
+[Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
 
 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
+`Toolbar`, `ListHeader`, `ListItem`, 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. A `ToolbarControlGroup` places the app's trailing controls in
+the 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,8 +80,11 @@ 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
-by the form. Production fields own labels, help, and native focus. The field
+A direct `ToolbarText` supplies the task title, with app-owned supporting copy
+below; their ids are referenced by the form. `ListInsetText` gives that bare
+supporting copy the same content-item text inset as the fields instead of
+duplicating its geometry in recipe CSS. 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
 apart and related controls use 8px gaps. The app owns
@@ -106,8 +109,53 @@ rows.
 
 Use `ToolbarControlGroup` for related commands, `SegmentedControl` for a few
 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.
+button for an independent command. Even that independent button sits in a
+single-control `ToolbarControlGroup`, which keeps its height, pill shape, focus,
+and hover treatment aligned with the adjacent toolbar controls. 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`.
+
+## Loading inspector
+
+[Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
+
+A record inspector whose per-record values load asynchronously. Every
+value-bearing component (`ToolbarText`, `ValueTable`/`ValueTableRow`, `Select`,
+`SegmentedControl`, `ListItem`, `StateBanner`) takes its `placeholder` from one
+loading flag, so the same real chrome renders a faithful loading state and then
+the populated record — no separate skeleton markup. The composition is the point;
+`Skeleton` is the primitive it builds on. The app owns the loading lifecycle and
+which values are still unknown.
+
+## Collapsible sidebar
+
+[Open the recipe](../ux-demo/?component=recipe-collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx)
+
+A mini app frame whose left navigation rail and bottom activity drawer are
+standalone `CollapsiblePanel`s (`@kerfjs/ui/collapsible-panel`) driven by
+`wireSidebar` (`@kerfjs/ui/wire-sidebar`). `CollapsiblePanelToggle` supplies the
+standard per-side glyph: a collapse toggle lives inside each panel and an expand
+toggle lives in the always-visible main header, so a collapsed panel is still
+reachable. `wireSidebar` owns the toggle delegation, moves focus into a panel on
+open and restores it to the trigger on close, and — when a `deviceClass()` reports
+`compact` — switches the open panel to a dismissable **overlay** (backdrop, Escape
+and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern). It
+also persists each panel's collapsed state through a supplied storage hook. The app
+owns each `collapsed` signal, the panel sizes, and the content; the wire owns the
+ephemeral interaction. For a full three-pane shell use `Workbench` instead — see
+[`app-layouts.md`](app-layouts.md). This recipe is covered end-to-end across
+Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.ts`.
 
 ## Rules shared by every recipe
 

package/docs/split-view.md

@@ -0,0 +1,55 @@
+# Split view (list-detail)
+
+`@kerfjs/ui/split-view` is a list-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.
+
+The catalog's **Interactive compact drill-down** example exercises this exact
+controlled flow: a list action sets the selected message, `detailActive` pushes
+its detail, and the wired Back action clears the selection to reveal the
+preserved list. Use the same structure in application demos so compact examples
+show the interaction rather than rendering a disconnected detail state.
+
+Compose the interactive wiring from the existing helpers — `SplitView` adds no
+wire of its own.

package/docs/sunken-panel.md

@@ -0,0 +1,53 @@
+# SunkenPanel
+
+`SunkenPanel` is a visually lowered application surface with one compact inset
+and a vertical content stack. Use it for a main work area or nested panel whose
+background should sit behind ordinary content, such as the primary stage in an
+issue tracker or component catalog.
+
+```tsx
+import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
+
+<SunkenPanel ariaLabel="Release workspace">
+  <ReleaseSummary />
+  <ReleaseChecks />
+</SunkenPanel>;
+```
+
+The default `shape="rounded"` uses the shared rounded-rectangle radius. Choose
+`shape="square"` for a flush or edge-to-edge area that needs `border-radius: 0`:
+
+```tsx
+<SunkenPanel shape="square">
+  <Workspace />
+</SunkenPanel>
+```
+
+## Ownership
+
+The root owns its lowered background, 8px padding, and 8px vertical gap.
+Children own their borders and internal geometry. The application owns child
+order, responsive placement, and scrolling; `SunkenPanel` deliberately does not
+create another scroll container.
+
+Use `ariaLabel` only when the surface is a distinct region people need to find
+by name. With a label, the root receives `role="region"`; without one it remains
+a non-landmark grouping.
+
+Do not use `SunkenPanel` merely to add padding, as a substitute for pane
+header/content/footer anatomy, or around a child that already owns the same
+outer surface.
+
+## Public styling boundary
+
+Override the public properties at the composition boundary:
+
+- `--kui-sunken-panel-background`
+- `--kui-sunken-panel-foreground`
+- `--kui-sunken-panel-padding`
+- `--kui-sunken-panel-gap`
+- `--kui-sunken-panel-radius`
+
+The public root class is `.kui-sunken-panel`. Prefer the properties above over
+styling descendants. The `square` shape deliberately overrides the radius
+property with zero; use `rounded` when customizing the radius token.

package/docs/surface-scaffold.md

@@ -0,0 +1,25 @@
+# Dialog and popup surface scaffolds
+
+`DialogSurface` and `PopupSurface` configure recurring Web Awesome surface
+geometry without application `::part()` overrides. They do not replace Web
+Awesome behavior: the application still owns open state, focus lifecycle,
+dismissal policy, ids, labels, and content.
+
+Wrap one `wa-dialog` with `DialogSurface`. Choose `size` (`small`, `medium`, or
+`large`), `presentation` (`modal`, `side-sheet`, or `fullscreen`), and independent
+`bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
+match Kerf's medium modal, 8px body, and 16px footer rhythm.
+
+Treat a dialog body as a `List` by default. When its rows or sections own their
+standard list geometry, set `bodyInset="none"` so the dialog does not add a
+second inset. Bare prose is still a list child: wrap it in `ListInsetText` so its
+text edge receives the standard 8px margin + 1px transparent border + 8px
+padding and aligns with bordered siblings. Reserve `compact` or `comfortable`
+body insets for exceptional content that does not already have list/content-item
+geometry.
+
+Wrap one `wa-dropdown` with `PopupSurface`. `inset="list-zero"` removes menu
+padding for a child that already owns row insets, `compact` uses 4px, and
+`standard` uses the shared 8px surface inset. Keep the dropdown trigger named and
+preserve `data-morph-skip-children` when its upgraded light-DOM items must retain
+identity across Kerf rerenders.

package/docs/tab-scaffold.md

@@ -0,0 +1,52 @@
+# 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. Its single-line labels preserve their full line box and
+truncate horizontally with an ellipsis when a destination name exceeds its
+share of the bar. On larger device classes, promote the tab set to a
+`Workbench` rail or a persistent sidebar instead of a bottom bar.