@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/docs/nav-stack.md

@@ -5,14 +5,19 @@ 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:
+Import the component and its wiring helper:
 
 ```ts
-import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
-import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
-import '@kerfjs/ui/nav-stack.css';
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads NavStack's stylesheet and those of the components it renders internally
+(`Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/nav-stack.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## State lives in the app
 
 Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
@@ -20,28 +25,135 @@ 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 /> }]);
+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); } });
+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} /> }];
+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.
+mounted (so their DOM state survives) but hidden. Each entry carries a
+`key` (stable identity), `content`, an optional `title`, optional per-view
+`leading`, `center`, and trailing `toolbar` groups for the top toolbar, 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.
+
+## The top toolbar
+
+The top chrome is a real `Toolbar`, so it follows the same zone,
+group, and responsive rules as every other toolbar. Its leading zone holds the
+back control (a borderless `ToolbarControlGroup`, shown once the stack has
+depth), then the active view's `leading` groups, then the view's `title` as a
+`ToolbarText`. The view's `center` fills the center zone and its `toolbar`
+fills the trailing zone. Give each zone `ToolbarControlGroup`s or `ToolbarText`,
+as in any toolbar.
+
+Configure the toolbar with `toolbarConfig` instead of styling it:
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  backText={previousTitle}
+  toolbarConfig={{
+    headingLevel: 1,
+    titleSize: "xlarge",
+    dividerSides: "b",
+    responsive: "wrap",
+  }}
+/>
+```
+
+- `toolbarConfig` forwards the `Toolbar` configuration (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and adds
+  `label` (the toolbar's accessible name), `titleSize` (the title's
+  `ToolbarText` size, default `large`), and `headingLevel` (expose the title as
+  a heading; default a plain span). The defaults keep the stack's own chrome:
+  no divider, the standard Toolbar height (a 44px control band with 8px above and below), and the top and side safe-area edges
+  claimed.
+- `backIcon` replaces the default chevron-left icon. `backText` adds visible
+  text beside it (for example, the previous view's title); visible text names
+  the control, so `backLabel` applies only to the icon-only control.
+
+The catalog's **Configured toolbar** example shows these together: a level-2
+heading title over a bottom divider, leading and center groups on the root
+view, a trailing group on the pushed view, and `backText` set to the previous
+view's title.
+
+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.
+
+## Scroll dividers
+
+The stack draws no permanent line between its chrome and the view. With
+`wireScrollDividers(appRoot)` installed (see
+[Layout › Scroll dividers](layout.md#scroll-dividers)), the top chrome shows a
+line along its bottom edge only while the active view's content is scrolled
+beneath it, and the bottom toolbar a line along its top edge only while more
+content lies below it — neither when the content fits. The line follows the
+active view across a push or pop. The chrome's line is overlaid on its bottom
+edge and the bottom toolbar's is its always-present 1px top border, colored
+only while shown, so neither ever moves the chrome or the content. When the view's only child is a `Pane`,
+the line keys on whichever actually scrolls — the view, or the Pane's content —
+and a Pane header or footer draws its own boundary instead. An explicit
+`toolbarConfig.dividerSides` still draws a permanent Toolbar edge.
+
+`chromeDividers` configures both lines, with the same values as a `Pane`'s:
+`scroll` (the default) follows the scroll state above and draws nothing until
+the wiring runs; `always` keeps both lines, with or without the wiring; `none`
+drops them even when the wiring reports scroll state. It does not change the
+top Toolbar's own `dividerSides`.
+
+```tsx
+<NavStack id="settings" label="Settings" views={views.value} chromeDividers="always" />
+```
+
+## Safe areas
+
+The stack paints through a device's unsafe areas. Its chrome pads for the top
+and side insets, its bottom toolbar for the bottom and side insets, and each
+view pads the remaining edges inside its scroller, so content scrolls under the
+unsafe area but can always be scrolled clear. A view whose only child is a
+`Pane` or layout lets that child own the insets. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
 
 ## 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.
+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

@@ -1,25 +1,25 @@
 # Production composition recipes
 
-These seven reference compositions sit between individual primitives and product
-code. Open each stable UX-catalog route to run it, then copy the linked TSX and
-CSS. The examples import public package subpaths, use semantic layout owners,
-and keep state in a per-instance application adapter. They are not new
-monolithic components.
+These ten reference compositions sit between individual primitives and product
+code. Open each stable UX-catalog route to run it, then copy the linked TSX. The
+examples import public package subpaths, compose components through their
+props and tokens, and keep state in a per-instance application adapter. They
+ship no stylesheet of their own and are not new monolithic components.
 
 Copy the recipe source together with the catalog-independent
 [`mount-recipe.ts`](../ux-demo/recipes/mount-recipe.ts) adapter. It mounts the
 controller at one stable application root, uses `delegateActions()` for recipe
-commands, forwards form and dialog lifecycle events, wires resize commits with
-the public `onCommit` callback, retains every disposer, and returns one
-idempotent disposer:
+commands, forwards form and dialog lifecycle events, runs the recipe's own
+`wire()` (for example `wireWorkbench` or `wireSidebar`), 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.
@@ -28,63 +28,86 @@ specific dispatch; either way, wire once at a stable root and retain disposal.
 
 ## Desktop application shell
 
-[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx) · [shared CSS](../ux-demo/recipes/recipes.css)
-
-Use `Toolbar`, controlled `ResizableRegion` panes, and one
-`.kui-pane__content` scroll owner per pane. The recipe owns the shell topology;
-the app owns routing, responsive pane visibility, sizes, persistence, and data.
-Keep each visible pane's collapse action in its own toolbar. Once hidden, put
-its restore action in the adjacent main toolbar on the same logical edge:
-leading for an inline-start sidebar and trailing for an inline-end inspector.
-Collapse the pane completely rather than preserving an empty icon rail.
-Adapt only public `--kui-layout-*` and component variables.
+[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx)
+
+A filling `List` (`fill`, with the recipe's `data-*` markers through
+`rootAttributes`) stacks the app-bar `Toolbar` above a `Workbench`
+(`@kerfjs/ui/workbench`): resizable navigation and inspector rails around the
+task list. Each rail composes its own panel toolbar — a default-size title and
+the standard hide toggle — and the work area's `mainToolbar` carries the xl
+view title. While a rail is hidden, `Workbench` relocates its show toggle into
+the work-area toolbar on the same logical edge (leading for the navigation
+rail, trailing for the inspector), and `wireWorkbench` hands focus between the
+two positions. Collapse a rail completely rather than preserving an empty icon
+rail. Only the three real panes own a `.kui-pane__content` scroll owner; no
+frame `Pane` wraps the layout in a scroll owner that never scrolls, and the
+app-bar `Toolbar` claims the top edge and both sides with its own
+`safeAreaEdges`.
+
+On a narrow container the rails overlay the task list one at a time instead of
+squeezing it, leaving a 44px strip on the far side that dismisses the overlay
+(`responsiveOverlayAt`, on by default; `compactOverlay: 'full'` covers the
+whole width). The app owns each rail's collapsed and size signals — which
+`wireWorkbench` keeps in sync with resizing and overlay dismissal — plus
+routing, persistence, and data. Adapt only public `--kui-layout-*` and
+component variables.
 
 ## Navigation sidebar
 
 [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-item` children own their 8px margin, 1px border, and 8px padding.
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and
+`ContentItem` 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)
 
-`PanelHeader` 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
-
-[Open the recipe](../ux-demo/?component=recipe-master-detail-dialog) · [TSX source](../ux-demo/recipes/master-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.
-`PanelHeader`, `MenuHeader`, `MenuItem`, and `ValueTable` own their included
-anatomy. The application owns open state, selection, dismissal policy, and
-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
-cluster uses one outer gutter without a second content-item inset.
-Do not rebuild the dialog or reach into private shadow parts.
+## List-detail dialog
+
+[Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
+
+A list-detail dialog is laid out like a `Workbench` with a left sidebar: on
+roomy devices the list is a full-height sidebar and the detail is a full-height
+main column, each a `Pane` with its own top `Toolbar`. The sidebar's toolbar
+carries its quiet default-size title (and it may add a bottom toolbar for
+sidebar-only actions); the main column's toolbar carries the dialog's primary
+extra-large title and the close control, and its footer carries the record
+actions. The Web Awesome dialog therefore renders `without-header` there —
+its label still names the modal — and the close button uses
+`data-dialog="close"`. Web Awesome keeps modal focus and Escape, and the thin
+recipe adapter restores the invoking control after the hide event.
+`DialogSurface` chooses the large modal with no body inset, because the panes
+own their geometry. On compact devices the dialog becomes a full-screen sheet
+with its own labeled header and footer actions, and `SplitView` becomes a
+`NavStack` drill-down whose back control the application pops. The
+application owns open state, selection, the pushed detail, dismissal policy,
+and record actions. Do not put the primary title in a header spanning both
+columns, rebuild the dialog, or reach into private shadow parts.
 
 ## Composer form
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
-`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
-apart and related controls use 8px gaps. The app owns
+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. The title and
+supporting line share a nested heading `List` with `gap="none"`, so the heading
+unit stays together instead of taking the form's 24px section gap. Production
+fields own labels, help, and native focus. One `List` owns the 24px major
+rhythm; the field `List` and the action `Row` use `controlInsets` to sit on the
+shared 8px inline gutter with 8px gaps between related controls, rather than
+acquiring a second content-item padding inset. The app owns
 validation, drafts, permissions, and transport. Persistent error or success
 feedback is the only nested semantic surface and uses `StateBanner`, not a toast.
 Because upgraded Web Awesome fields retain live value properties, controlled
@@ -106,8 +129,12 @@ 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. At compact
+widths the toolbar stacks its zones and wraps whole trailing groups onto another
+row, so the last action is never clipped. The app owns values, actions,
+persistence, and responsive priority.
 
 ## Navigation stack
 
@@ -116,11 +143,59 @@ and responsive priority.
 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
+settles the chrome (reduced motion collapses the slide to instant). 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. Its heading `Toolbar` uses
+`responsive="wrap"`, so on a narrow inspector the toggle moves below a whole
+record title instead of truncating it. 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`). Each panel takes a `toolbar` — a
+title plus the standard per-side toggle — so the hide control lives in the
+panel's own header, and `CollapsiblePanelRelocated` renders the matching show
+control only while the panel is collapsed, so exactly one control owns each
+action and a collapsed panel is still reachable. The rail's relocated toggle
+leads the always-visible main header; the drawer's sits in a
+`FloatingToolbar` passed as the drawer's own `restoreControl`, which the panel
+floats in its column's safe-area-aware bottom-end corner, next to where the
+drawer opens — do not hand-roll a conditional floating control beside the
+panel. `wireSidebar` owns the toggle delegation, moves focus into a
+panel on open, restores it on close (to the trigger, or to the panel's expand toggle when
+the trigger sits inside the collapsed panel), and — when a `deviceClass()` reports
+`compact` — presents the panels as a dismissable **overlay** (backdrop, Escape
+and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern).
+The overlay starts closed and opens only from a toggle; the rail's signal is
+seeded from the device class with `inlineCollapsed: false`, so the first compact
+render has no overlay and a wide crossing restores the open inline rail. It
+also persists each panel's inline collapsed state through a supplied storage hook. A
+filling `Row` (`fill` plus `rootAttributes`) is the root: it takes the frame's
+definite height and places the rail beside a `List` column, and a one-column
+`Grid` grows the main pane above the drawer. Because the panels sit at the real
+frame edges, each grows through its edge's safe area and hands that edge back to
+its siblings when it collapses; the drawer's activity log is a `ValueTable`. 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
 
 - Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one
@@ -128,9 +203,17 @@ settles the chrome (reduced motion collapses the slide to instant). A live
 - For direct `wa-*` JSX, import types from `@kerfjs/ui/webawesome`. Import only
   individual Web Awesome registration modules and theme them with
   `@kerfjs/ui/webawesome.css`.
-- Prefer public props and variables at the composition boundary. When a recipe
-  needs responsive topology, join only classes listed in the catalog's
-  `publicClasses`; do not copy component markup or select descendants by tag,
-  id, attribute alone, or an unlisted implementation class.
+- Compose, don't style. A recipe ships no stylesheet, sets no inline style, and
+  names no class outside the published layout vocabulary (`.kui-content`,
+  `.kui-control-cluster`, …) and themed Web Awesome classes — a content item is
+  a `ContentItem`, not a hand-written `.kui-content-item`; it configures
+  components through props, `rootAttributes`, and tokens. When a recipe needs a
+  capability no component offers, record it as a component gap rather than
+  papering over it with CSS. `npm run check:recipes` enforces these rules on
+  every file in `ux-demo/recipes/`.
+- Each recipe also exports a catalog-only `presentation`: the `CatalogExample`
+  viewport that frames it in the UX catalog and its ownership note. An
+  application that copies the recipe ignores that export and mounts the
+  controller into its own container.
 - Start from the copyable mount adapter, or reproduce its complete boundary:
   wire stable `data-action` hooks once and retain every disposer.

package/docs/split-view.md

@@ -1,18 +1,31 @@
 # Split view (list-detail)
 
-`@kerfjs/ui/split-view` is a list-detail (master-detail) layout: a list and a
+`@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.
+import { SplitView } from "@kerfjs/ui/split-view";
+import { deviceClass } from "@kerfjs/ui/device-class";
+// plus wireResizableRegions / wireNavStack for the interactive behavior.
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads SplitView's stylesheet and those of the components it renders internally
+(its compact `NavStack`, `ResizableRegion`, and the toolbar
+components). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/split-view.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
+## Safe areas
+
+The list pane grows by the inline-start unsafe inset and pads for the edges it
+touches; the detail pads for its own outer edges. Neither is inset on the
+shared interior edge. A pane whose only child is a `Pane` lets that child own
+the insets, and the compact form hands them to its `NavStack`. See
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 ## Responsive by device class
 
 `SplitView` is declarative; the app derives `compact` from the device class and
@@ -45,5 +58,55 @@ const selected = signal<string | null>(null);
   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.
 
+## Configuring the list region and the compact stack
+
+`resizable` forwards the list's `ResizableRegion` configuration alongside
+`size`, `min`, and `max`: `separator` (`"hidden"` keeps the resize hit target
+but paints no line), `handleIcon`, `contentOverflow`, and collapse —
+`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, and
+`restorePosition`. A collapsed list snaps to zero width, renders `inert` and
+`aria-hidden`, and the detail fills the split; the app owns the `collapsed`
+flag and renders the restore control (usually a `FloatingToolbar`). Omitted
+options keep the region's defaults.
+
+```tsx
+resizable={{
+  size: listWidth.value,
+  min: 220,
+  max: 480,
+  collapsed: listCollapsed.value,
+  restoreControl: <ShowThreadsToolbar />,
+}}
+```
+
+`compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
+`backText`, `hideToolbar`, the persistent `bottomToolbar`, and `chromeDividers`
+forward to the stack, and `list` / `detail` give each view its own top-toolbar groups
+(`leading`, `center`, trailing `toolbar`) and `bottomToolbar`:
+
+```tsx
+compactStack={{
+  backText: "Threads",
+  toolbarConfig: { headingLevel: 1 },
+  list: { toolbar: <ComposeGroup /> },
+  detail: { toolbar: <ReplyGroup />, bottomToolbar: <MessageActions /> },
+}}
+```
+
+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. It also forwards `compactStack`: a level-2 heading title over
+a bottom divider, a Compose group on the list view, and a Reply group plus a
+bottom toolbar on the detail. Use the same structure in application demos so
+compact examples show the interaction rather than rendering a disconnected
+detail state.
+
+The catalog's **Resizable, collapsible list** example forwards `resizable`: a
+hidden separator that still resizes the list (its committed width comes back
+through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
+control in the list's own toolbar, and a `FloatingToolbar` restore control in
+the split's bottom-start corner.
+
 Compose the interactive wiring from the existing helpers — `SplitView` adds no
 wire of its own.

package/docs/sunken-panel.md

@@ -0,0 +1,58 @@
+# 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`
+
+`--kui-sunken-panel-background` can be overridden for a known backdrop. Keep
+the default lowered surface opaque; a translucent override compounds when
+sunken panels nest. See [Contextual transparency](./webawesome-theme.md#contextual-transparency)
+for the color and contrast evaluation.
+
+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 `PopupMenu` (or another single `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.