@kerfjs/ui 4.4.1 → 5.0.0-beta.11

package/docs/design-philosophy.md

@@ -18,12 +18,65 @@ 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
+children own margin, border, background, padding, and radius, so a transparent
+surface occupies exactly the same geometry as a visible one. Major content
+groups use 24px vertical separation; the inside of an item and the gap between
+toolbar groups use 8px. Rows and actions keep 44px targets.
+
+Use the package composition so the geometry has one owner:
+
+```tsx
+<aside class="kui-pane">
+  <nav class="kui-pane__content kui-content">
+    <section>
+    <ListHeader label="Workspace" />
+    <ListItem action="open" label="Inbox" icon={inboxIcon} />
+    <ListItem action="open" label="Drafts" />
+    </section>
+    <div class="kui-content-item">Panel contents</div>
+  </nav>
+</aside>
+```
+
+Do not pad the pane and then pad every wrapper. That duplicates the geometry
+and makes transparent borders behave differently from visible ones:
+
+```tsx
+<aside class="pane padded">
+  <section class="padded">
+    <ListHeader label="Workspace" />
+    <div class="panel padded-again">Panel contents</div>
+  </section>
+</aside>
+```
+
+Change the shared item tokens at a real composition boundary when a product
+needs different geometry; do not compensate with one-off negative margins.
+
 ### Prefer directness
 
 Use the shortest understandable, recoverable interaction. Avoid modes, dialogs, confirmations, and explicit saves when direct manipulation can safely express the same result. Low ceremony still requires a discoverable affordance, visible focus, and honest feedback.
@@ -42,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/examples/command-palette-adapter.tsx

@@ -0,0 +1,70 @@
+import '@kerfjs/ui/layout.css';
+
+import { delegate, mount, signal } from 'kerfjs';
+import { delegateActions } from 'kerfjs/actions';
+
+export interface AppCommand {
+  id: string;
+  label: string;
+  keywords?: string[];
+}
+
+export interface CommandPaletteCallbacks {
+  onClose(): void;
+  onRun(command: AppCommand): void;
+}
+
+/**
+ * Application-local example, not an @kerfjs/ui export. The application owns
+ * ranking, history, shortcuts, focus policy, command availability, and copy.
+ */
+export function mountCommandPaletteAdapter(
+  root: HTMLElement,
+  commands: AppCommand[],
+  { onClose, onRun }: CommandPaletteCallbacks,
+): () => void {
+  const query = signal('');
+  const render = () => {
+    const needle = query.value.trim().toLocaleLowerCase();
+    const matches = commands.filter((command) => !needle ||
+      [command.label, ...(command.keywords ?? [])].some((value) => value.toLocaleLowerCase().includes(needle)));
+    return <section class="app-command-palette kui-content" aria-label="Command palette">
+      <div class="kui-content-item"><label for="app-command-query">Search commands</label><input id="app-command-query" type="search" value={query.value} autocomplete="off" data-command-query /></div>
+      <p class="kui-content-item" aria-live="polite">{matches.length} matching commands</p>
+      <ul class="kui-content-item" aria-label="Matching commands">{matches.map((command) => <li><button type="button" data-action="run-command" data-command-id={command.id}>{command.label}</button></li>)}</ul>
+      <footer class="kui-control-cluster kui-content-item" aria-label="Command palette actions">
+        <button type="button" data-action="clear-query">Clear search</button>
+        <button type="button" data-action="close-palette">Close</button>
+      </footer>
+    </section>;
+  };
+
+  const stopMount = mount(root, render);
+  const stopActions = delegateActions(root, 'click', {
+    'run-command': (_event, element) => {
+      const id = (element as HTMLElement).dataset.commandId;
+      const command = commands.find((candidate) => candidate.id === id);
+      if (command) onRun(command);
+    },
+    'clear-query': () => {
+      query.value = '';
+      root.querySelector<HTMLInputElement>('[data-command-query]')?.focus();
+    },
+    'close-palette': onClose,
+  });
+  const stopInput = delegate<HTMLInputElement>(root, 'input', '[data-command-query]', (_event, input) => {
+    query.value = input.value;
+  });
+  const stopEscape = delegate(root, 'keydown', '[data-command-query]', (event) => {
+    if ((event as KeyboardEvent).key === 'Escape') onClose();
+  });
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    stopEscape();
+    stopInput();
+    stopActions();
+    stopMount();
+  };
+}

package/docs/layout.md

@@ -0,0 +1,131 @@
+# 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.
+
+## Anatomy
+
+```tsx
+<aside class="kui-pane">
+  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
+  <div class="kui-pane__content kui-content">
+    <section>...</section>
+    <section>...</section>
+  </div>
+  <footer class="kui-pane__footer"><Toolbar label="Actions" ... /></footer>
+</aside>
+```
+
+`.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.
+
+`.kui-content` is a vertical stack with a 24px gap between major children.
+Sections may contain adjacent `ListItem` rows without adding another major gap.
+Ordinary surface-like children use `.kui-content-item` and own their complete
+geometry:
+
+- 8px inline margin from the pane edge
+- 1px border, transparent by default
+- 8px internal padding and 8px internal gap
+- `calc(1px + remify(11px))`, or 12px, rounded corners
+
+Use `.kui-content-item--pill` for the 22px pill radius expressed as
+`calc(1px + remify(21px))`. Consumers can make a content item visible without
+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 `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
+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`, `ListHeader`,
+`ListItem`, `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
+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.
+`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 `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.
+
+`--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
+
+1. Do not pad a sidebar, main area, dialog, or `.kui-pane` shell. Children own
+   their own margin, border, background, padding, and radius.
+2. Use 24px gaps for major vertical separation and 8px gaps inside an item or
+   between toolbar groups. Do not confuse the two relationships.
+3. Wrap toolbar content in `ToolbarControlGroup`, including dormant text. A
+   transparent group still reserves the same 44px geometry as a visible group.
+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,
+   `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.
+   `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.
+7. A visible collapsible pane owns its collapse control in that pane's toolbar.
+   When the pane is hidden, move the restore control into the adjacent main
+   toolbar on the same logical edge: an inline-start pane restores from the
+   main toolbar's leading group, and an inline-end pane restores from its
+   trailing group. Do not leave an otherwise empty icon-only rail behind.
+
+At narrow widths or 200% zoom, relocate or stack panes before shrinking targets.
+The 8/1/8 item contract and 44px controls remain stable, so screenshots and
+focus-order tests exercise the same model at every viewport.

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

@@ -0,0 +1,167 @@
+# 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.
+
+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:
+
+```ts
+import { createRecipe } from './navigation-sidebar.js';
+import { mountRecipe } from './mount-recipe.js';
+
+const root = document.querySelector<HTMLElement>('#navigation')!;
+const stopRecipe = mountRecipe(root, createRecipe(announce));
+window.addEventListener('pagehide', stopRecipe, { once: true });
+```
+
+The adapter is delivered as reference source, not a new package runtime export.
+`delegate()` remains a valid alternative when an application needs selector-
+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.
+
+## 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; `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 `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,
+overflow, and primary actions. The app owns authorization and command policy;
+controls relocate without changing focus order.
+
+## List-detail dialog
+
+[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.
+`PanelHeader`, `ListHeader`, `ListItem`, 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.
+
+## 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
+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
+resets synchronize both those properties and the rendered value attributes;
+the Reset action also announces `Draft reset` through the catalog live region.
+
+## List workspace states
+
+[Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
+
+The same content region moves deterministically through loading, empty,
+populated, stale/background refresh, and error/retry states. The recipe owns
+feedback placement; the app owns fetching, cache age, retry policy, and domain
+rows.
+
+## Compact toolbar choices and actions
+
+[Open the recipe](../ux-demo/?component=recipe-compact-toolbar) · [TSX source](../ux-demo/recipes/compact-toolbar.tsx)
+
+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.
+
+## 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 (`PanelHeader`, `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
+
+- Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one
+  `.kui-pane__content` scroll owner for each real boundary.
+- 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.
+- 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

@@ -0,0 +1,49 @@
+# 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.
+
+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.