@kerfjs/ui 5.0.0-beta.104 → 5.0.0-beta.105

package/docs/disclosure.md

@@ -0,0 +1,63 @@
+# Disclosure
+
+`@kerfjs/ui/disclosure` shows and hides content under a summary row. It is a
+native `<details>` with a `<summary>` that carries a `DisclosureArrow`, the
+title, and an optional quiet detail, on the shared content-item geometry.
+
+```tsx
+import { Disclosure } from "@kerfjs/ui/disclosure";
+
+<Disclosure title="Advanced Settings" detail="3 options">
+  <Text>Proxy, request timeout, and retry limits.</Text>
+</Disclosure>;
+```
+
+## Geometry
+
+The root takes the content-item geometry: an 8px inline margin, a 1px border
+(transparent unless framed), and the rounded radius. The summary row has the
+8px inset and a 42px minimum height. The content area is offset by the arrow
+column only, so Kerf block content, which brings the shared 1px + 8px inset
+(`Text`, a `List`, a `ValueTable`), lands on the title's text column. Wrap
+prose in `Text` rather than passing a bare string.
+
+- `appearance="plain"` (default) sits on the surrounding surface.
+- `appearance="framed"` draws the standard neutral border. Frame one only when
+  it marks a real distinction.
+- `appearance="sunken"` draws the border on the lowered, textured work surface,
+  for something like a log.
+
+## Open state
+
+The open state belongs to the native `<details>` once it is on the page. A
+person toggles it with a press, Enter, or Space; `open` renders it open, and a
+re-render that passes `open` opens it. A re-render never closes it, because
+kerf's morph leaves a `<details>` element's live `open` alone. To close it
+from code, set `element.open = false`. The arrow follows the live state.
+
+To react to a toggle, give it a `toggleAction` (a `data-action` on the root)
+and listen for the native `toggle` event. It does not bubble, so listen in
+the capture phase, for example with `delegateCapture`, and read
+`event.newState` (`open` or `closed`).
+
+## Accordions
+
+Disclosures that share a `name` form an exclusive group: opening one closes
+the others. This is the native `<details name>` attribute.
+
+```tsx
+{faqs.map((faq) => (
+  <Disclosure title={faq.title} name="faq" appearance="framed">
+    <Text>{faq.answer}</Text>
+  </Disclosure>
+))}
+```
+
+## Accessibility
+
+The summary is the platform's disclosure button: Enter and Space toggle it,
+and it reports its expanded state. The arrow is decorative. Keep the title a
+short, meaningful name for what it hides.
+
+Use this instead of `wa-details`, `wa-accordion`, and `wa-accordion-item`,
+which are Discouraged.

package/docs/examples/component-catalog-extension.json

@@ -8,12 +8,12 @@
       "id": "acme-filter-chip",
       "name": "FilterChip",
       "kind": "component",
-      "purpose": "A removable application filter displayed inside a token-search workflow.",
+      "purpose": "A removable application filter displayed inside a search-field workflow.",
       "useWhen": [
         "A saved application filter needs a compact visible label and remove action."
       ],
       "avoidWhen": [
-        "The value belongs to TokenSearchField's own controlled token collection."
+        "The value belongs to SearchField's own controlled token collection."
       ],
       "publicClasses": ["acme-filter-chip"],
       "publicTokens": ["--acme-filter-chip-accent"],

package/docs/layout.md

@@ -88,7 +88,7 @@ For custom chrome colors in auto mode, set `--kui-pane-chrome-background`
 on the Pane; it defaults to `--kui-color-surface`.
 
 ```tsx
-<Pane appearance="sunken" footer={<Composer />}>
+<Pane appearance="sunken" footer={<MessageComposer />}>
   <Conversation />
 </Pane>
 ```
@@ -526,7 +526,7 @@ Toolbar groups reserve a real 1px outer border around a 42px inner area, even
 when their border and background are transparent.
 A `Toolbar` lays its zones out against one 44px control band at its top: an
 ordinary `ToolbarText`, `ToolbarControlGroup`, or standalone trailing
-`wa-button` no taller than the band is centered in it by its own size, and a
+`Button` no taller than the band is centered in it by its own size, and a
 taller one (a wrapped title, a second trailing row) starts at the band's top
 and grows down, so it never moves the other controls. A wrapped `ToolbarText`
 centers its first line in the band. Other direct zone content centers against
@@ -795,10 +795,13 @@ defaults to `hAlign="left"`, `vAlign="full"`, `gap="xs"`, and no wrapping;
 Both components accept the same physical-axis vocabulary, with baseline
 alignment additionally available on the horizontal `Row` cross axis:
 
-| 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`; Row-only `baseline` | Aligns a Row's children across its height; distributes a List's children. |
+| 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`; Row-only `baseline` | Aligns a Row's children across its height; distributes a List's children. |
+
+`center` and `middle` gather the children in the middle and keep their `gap`;
+`space-around` spreads equal space around each child instead.
 
 Cross-axis `space-around` and `space-between` are not valid `align-items`
 values. Kerf therefore maps `middle` to centered items and `full` to stretched
@@ -913,6 +916,12 @@ For long reading content, such as a reader view, pass `inset="document"`: 24px
 block and 32px inline on all four sides, narrowing to 16px inline below 576px.
 It replaces any `textInsets`/`controlInsets` on that List.
 
+For a page's content column (a settings page, a setup form), pass
+`contentWidth`: `compact` (440px), `medium` (640px), or `wide` (864px) of
+content, plus the List's own insets, so it composes with `inset="document"`.
+The column is centered by default; `contentAlign="start"` keeps it at the
+leading edge. Never cap and center a page column with application CSS.
+
 A List is transparent by default. Pass `surface="base"` (the page surface) or
 `surface="raised"` to paint a solid background behind the stack and its
 insets — for example a banner strip above a sunken work area, which otherwise
@@ -961,7 +970,7 @@ instance's value.
 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. Every direct child of `ListInsetControl` grows to fill the row
-(a `Select`, a `wa-input`, or a `wa-button` spans the full inset width), and
+(a `Select`, a `TextField`, or a `Button` spans the full inset width), and
 several children share the row with an 8px gap; stack controls vertically with
 a `List` using `controlInsets` instead. Pass `sides="rl"` for tight text that
 keeps the horizontal inset without adding vertical box space.

package/docs/list-detail-dialog.md

@@ -0,0 +1,96 @@
+# List-detail dialog
+
+`@kerfjs/ui/list-detail-dialog` is the modal form of a list-detail layout: a
+list column beside the selected item's detail, each running the dialog's full
+height. It is one of three dialog types:
+
+| Type                                                           | Use it for                                               |
+| -------------------------------------------------------------- | -------------------------------------------------------- |
+| `DialogSurface` ([surface-scaffold.md](surface-scaffold.md))   | One pane: a title, a body, and footer buttons.           |
+| `ListDetailDialog` (this page)                                 | Pick a record from a list and show its detail beside it. |
+| `WorkbenchDialog` ([workbench-dialog.md](workbench-dialog.md)) | An editing task with side panels.                        |
+
+```ts
+import {
+  ListDetailDialog,
+  openDialog,
+} from "@kerfjs/ui/list-detail-dialog";
+import { deviceClass } from "@kerfjs/ui/device-class";
+```
+
+In a browser bundler that honors the `browser` export condition, the import
+also loads the stylesheets of every component it renders (DialogSurface,
+SplitView, NavStack, Pane, and the toolbar components). Without that
+condition, import `@kerfjs/ui/list-detail-dialog.css`, which pulls in the same
+stylesheets, or `@kerfjs/ui/styles.css`.
+
+## Where things go
+
+- **The detail column owns the dialog's identity.** Its header toolbar carries
+  the primary title (an xl level-2 heading, with an optional `description`
+  line), the `actions` you pass, and the close control, last. Record actions go
+  in the detail `footer`, pinned below the scrolling detail.
+- **The list column is secondary.** Its header carries `list.title` at the
+  default toolbar size, so it reads as pane identity beside the primary title,
+  followed by your `list.toolbar` controls. An add control or count can go in
+  `list.footer`.
+- **The surface draws no header.** Both columns start at the dialog's top
+  edge, so the divider between them runs the dialog's full height.
+
+Each column is a `Pane`: its header and footer stay pinned and its content
+scrolls on its own. Pass content that owns its geometry, usually a `List`.
+
+## Responsive by device class
+
+The component is declarative. The app derives `compact` from the device class
+and tracks its own selection and, on compact devices, whether the detail is
+pushed:
+
+```tsx
+const device = deviceClass();
+const selected = signal("atlas");
+const detailOpen = signal(false);
+
+<ListDetailDialog
+  id="projects"
+  label="Project Details"
+  compact={device.value.compact}
+  detailActive={detailOpen.value}
+  backLabel="Back to Projects"
+  list={{
+    title: "Recent Projects",
+    content: <List>{rows}</List>,
+  }}
+  detail={{
+    title: project.name,
+    content: <List>{details}</List>,
+    footer: actions,
+  }}
+/>;
+```
+
+- **Roomy** (`compact: false`): a modal of `size` `large` with a definite
+  height (default 560px, bounded by the viewport; pass `maxHeight` instead to
+  size it to its content). The list column is 280px, at most 40% of the
+  dialog, by default; set `list.width` like SplitView's `listWidth`.
+- **Compact** (`compact: true`): the dialog fills the screen and becomes a
+  `NavStack`. The list is the root view (titled `list.title`, with its toolbar
+  controls); `detailActive` pushes the detail (titled `detail.title`, with its
+  `actions`). Every view keeps the close control, and each view's `footer` is
+  pinned below it. The stack's back control dispatches `nav-back`; set
+  `detailActive` back to `false` in response. Wire `wireNavStack` above it for
+  the push and pop motion.
+
+Render one `ListDetailDialog` for both presentations, so crossing the compact
+breakpoint while it is open morphs it in place and it stays open.
+
+## Opening and closing
+
+It is a `DialogSurface` underneath: open it with `openDialog(element)` and close
+it with `closeDialog(element)`, the close control, Escape, an element with
+`data-dialog-close`, or (with `lightDismiss`) a press on the backdrop. Both
+functions are re-exported from this subpath. Give sibling dialogs distinct
+`rootAttributes['data-key']` values so a re-render morphs each into itself.
+
+See the [list-detail dialog recipe](recipes.md#list-detail-dialog) for a
+complete, production-backed example.

package/docs/manual-test-plan.md

@@ -21,7 +21,7 @@ an iPhone (Safari) and an Android phone (Chrome).
    between its minimum height and the screen less the top safe area.
 
 Playwright cannot raise a virtual keyboard; the overlap formula is unit-tested
-(`tests/unit/dialog-bottom-sheet.test.ts`) and a simulated keyboard is covered
+(`tests/unit/dialog-surface-controller.test.tsx`) and a simulated keyboard is covered
 in `tests/browser/dialog-bottom-sheet.spec.ts`.
 
 ## Automated coverage summary

package/docs/{composer.md → message-composer.md}

@@ -1,6 +1,6 @@
-# Composer
+# MessageComposer
 
-`Composer` (`@kerfjs/ui/composer`, CSS `@kerfjs/ui/composer.css`) is the chat
+`MessageComposer` (`@kerfjs/ui/message-composer`, CSS `@kerfjs/ui/message-composer.css`) is the chat
 or prompt composer: the place a person writes a message, assistant prompt, or
 reply and sends it with a trailing action. It replaces app-owned composer
 chrome, such as a `wa-textarea` and a button wrapped in application CSS that
@@ -9,7 +9,7 @@ draws a frame, a focus border, and a shadow.
 ## Contract
 
 ```tsx
-<Composer
+<MessageComposer
   id="assistant-message"
   name="message"
   label="Message"
@@ -17,10 +17,10 @@ draws a frame, a focus border, and a shadow.
   hint="Answers use the latest nightly build."
   minRows={1}
   maxRows={8}
-  actions={
-    <wa-button variant="brand" data-action="send-message">
+  trailing={
+    <Button tone="brand" action="send-message">
       Send
-    </wa-button>
+    </Button>
   }
 />
 ```
@@ -34,18 +34,24 @@ draws a frame, a focus border, and a shadow.
 - **Field.** A native, borderless `<textarea>` named by `label`. It sizes to
   its content with `field-sizing: content`, between `minRows` (default 1) and
   `maxRows` (default 8) lines, and scrolls past the maximum. Both bounds are
-  positive integers, and `maxRows` is at least `minRows`; otherwise `Composer`
+  positive integers, and `maxRows` is at least `minRows`; otherwise `MessageComposer`
   throws a `RangeError`. In an engine without `field-sizing`, the field keeps
   a fixed height of three lines, clamped to the bounds, and scrolls.
-- **Action row.** Below the field: an optional quiet `hint` at the text start
-  and the trailing `actions`, normally one brand Send button. With an `id`,
-  the hint is the field's accessible description (`<id>-hint`).
+- **Action row.** Below the field, a compact `Toolbar` (footer semantics,
+  named "<label> Actions") that the composer insets for you. Its leading zone
+  holds optional `leading` controls, such as an attach button or a model
+  `Select` in a `ToolbarControlGroup`, then the optional quiet `hint`; its
+  trailing zone holds `trailing`, normally one brand Send `Button`. Every
+  toolbar convention applies, from control groups to responsive relocation.
+  With an `id`, the hint is the field's accessible description
+  (`<id>-hint`).
 - **Value.** `value` seeds the field (a restored draft, or `''`). The app
   reads the textarea in its send action, clears it, and re-renders.
 - **Disabled.** `disabled` disables the field; the app disables or marks busy
   its own actions.
-- **Placement.** `slot` assigns it to a web component slot, such as a
-  `wa-dialog`'s `footer`. `rootAttributes` takes safe `data-*` identity.
+- **Placement.** Pass it as a `DialogSurface`'s `footer`, or use `slot` to
+  assign it to a web component slot. `rootAttributes` takes safe `data-*`
+  identity.
 - **Enter to send.** `submitOnEnter` opts in to the keyboard contract below;
   it marks the root `data-submit-on-enter="true"` (protected from
   `rootAttributes`) and gives the field `aria-keyshortcuts="Enter"`.
@@ -55,13 +61,13 @@ like, and where the composer sits.
 
 ## Enter to send
 
-Set `submitOnEnter` and call `wireComposers` once over an ancestor of every
+Set `submitOnEnter` and call `wireMessageComposers` once over an ancestor of every
 such composer; it returns a disposer:
 
 ```ts
-import { wireComposers } from '@kerfjs/ui/wire-composers';
+import { wireMessageComposers } from '@kerfjs/ui/wire-message-composers';
 
-const stopComposers = wireComposers(app);
+const stopMessageComposers = wireMessageComposers(app);
 ```
 
 In an opted-in composer's field:
@@ -74,14 +80,14 @@ In an opted-in composer's field:
 | Enter on an empty or whitespace-only message | Nothing: no send and no newline.                                                                          |
 | Auto-repeating Enter (key held down)         | Nothing.                                                                                                  |
 
-The first trailing action is the first `wa-button`, `button`, or
+The first trailing action is the first `button` (a `Button`), `wa-button`, or
 `[data-action]` element inside `actions`. Clicking it means the keyboard send
 runs the same delegated `data-action` handler as a pointer send, so the app
 writes one send handler that reads the field, clears it, and re-renders. The
 click does not move focus, so the person keeps typing. Nothing is sent while
 the field is `disabled`, or while that action has a `disabled` attribute or
-property, a `loading` attribute (a busy `wa-button`), or
-`aria-disabled="true"`; the Enter is still suppressed, so a message waiting on
+property, `aria-busy="true"` (a busy `Button`), a `loading` attribute (a busy
+`wa-button`), or `aria-disabled="true"`; the Enter is still suppressed, so a message waiting on
 a busy Send does not gain a newline.
 
 Leave `submitOnEnter` off for a long-form prompt where Enter should be a
@@ -98,12 +104,19 @@ with `bodyLayout="fill-last"` and `footerPresentation="floating"` (and
 composer into the footer:
 
 ```tsx
-<DialogSurface height={remify(560)} bodyInset="none" bodyLayout="fill-last" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
-  <wa-dialog id="assistant" label="Assistant">
-    <StateBanner title="Answers use the latest nightly build." tone="neutral" />
-    <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">{messages}</List>
-    <Composer submitOnEnter slot="footer" id="assistant-message" name="message" label="Message" placeholder="Ask about this build" actions={send} />
-  </wa-dialog>
+<DialogSurface
+  id="assistant"
+  label="Assistant"
+  height={remify(560)}
+  bodyInset="none"
+  bodyLayout="fill-last"
+  footerPresentation="floating"
+  footerOffset={remify(8)}
+  footerInset="none"
+  footer={<MessageComposer submitOnEnter id="assistant-message" name="message" label="Message" placeholder="Ask about this build" trailing={send} />}
+>
+  <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+  <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">{messages}</List>
 </DialogSurface>;
 ```
 
@@ -121,14 +134,14 @@ instead.
 - Style its field, frame, or action row from application CSS. A variation it
   does not offer is a component gap.
 - Use it for an ordinary form field submitted with the rest of a form; use
-  `wa-textarea` with a `FieldLabel`.
+  a `multiline` `TextField`.
 
 ## Verification
 
-`tests/unit/composer.test.tsx` covers serialization, the hint description,
-row bounds, and protected attributes; `tests/unit/wire-composers.test.tsx`
+`tests/unit/message-composer.test.tsx` covers serialization, the hint description,
+row bounds, and protected attributes; `tests/unit/wire-message-composers.test.tsx`
 covers the Enter-to-send matrix (modifiers, IME, empty, repeat, disabled
-field and actions, first action only, disposal). `tests/browser/composer.spec.ts` covers
+field and actions, first action only, disposal). `tests/browser/message-composer.spec.ts` covers
 the focus-within border, growth up to `maxRows` and then scrolling, the action
 row geometry, and the send flow at wide and phone widths, and, in Chromium,
 Firefox, and WebKit, Enter, Shift+Enter, Cmd/Ctrl+Enter, empty messages, and

package/docs/overlay-toast.md

@@ -0,0 +1,62 @@
+# Toasts
+
+`kerfjs/overlay`'s `toast()` shows a brief, auto-dismissing notification in
+one body-level live region. The core ships no CSS. Import
+`@kerfjs/ui/overlay-toast.css` once and every toast takes Kerf's look:
+
+```ts
+import "@kerfjs/ui/overlay-toast.css";
+import { toast } from "kerfjs/overlay";
+
+const exit = { exitClass: "kui-toast-exit", exitDuration: 200 };
+
+toast("Draft saved.", exit);
+toast("Project published.", { ...exit, variant: "success" });
+```
+
+## What the stylesheet does
+
+- **Placement.** The region (`.kerf-toasts`) sits above the bottom edge,
+  centered, 16px from the viewport edge plus the bottom safe area, at most
+  480px wide. It never blocks the page; only the toasts take presses.
+- **Stacking.** Toasts stack newest last with an 8px gap.
+- **Surface.** Each toast (`.kerf-toast`) is the raised surface with a neutral
+  border, the rounded radius, and the large shadow.
+- **Tones.** `variant: 'info' | 'success' | 'warning'` lays the brand,
+  success, or warning quiet fill over the opaque surface, with the matching
+  border and text.
+- **StateBanner content.** A toast whose only content is a `StateBanner` takes
+  the banner's tone, border, and inset, and keeps its own elevation:
+
+  ```tsx
+  toast(
+    () => <StateBanner title="Export Finished" detail="report.csv is ready." tone="success" />,
+    { ...exit, duration: 6000 },
+  );
+  ```
+
+- **Motion.** A new toast rises and fades in on its own (no `enterClass`
+  needed). Pass `exitClass: 'kui-toast-exit'` with `exitDuration: 200` and it
+  sinks and fades out before removal. Under `prefers-reduced-motion` or
+  `:root[data-kui-effects="static"]` it only fades, or not at all.
+- **Forced colors.** Toasts draw a `CanvasText` border on `Canvas`.
+
+## Choices the app owns
+
+- What to say and when: a toast confirms a completed action (saved, copied,
+  published) or reports a status. An error the person must act on, or a
+  decision, belongs in a `StateBanner` in the affected surface or a
+  `DialogSurface`, not a toast that disappears.
+- `duration` (default 4000ms; `0` keeps it until you call `dismiss()`), and
+  `mode: 'replace'` to collapse a rapid sequence to the latest message.
+- Top-edge stacking: pass your own region as `container` with
+  `data-placement="top"` (and the `kerf-toasts` class); it stacks from the top
+  safe area down.
+- Stacking order above other layers: set `--kui-overlay-toast-z-index`
+  (default 1100).
+
+The region is `aria-live="polite"` and each toast is `role="status"`, so a
+screen reader announces it without moving focus. Never make a toast the only
+path to an action.
+
+Use this instead of `wa-toast` and `wa-toast-item`, which are Discouraged.

package/docs/overlay-tooltip.md

@@ -0,0 +1,53 @@
+# Tooltips
+
+`kerfjs/overlay`'s `tooltip(anchor, content, options?)` shows a hover and
+keyboard-focus tooltip beside any element and positions it there. The core
+ships no CSS. Import `@kerfjs/ui/overlay-tooltip.css` once and every tooltip
+takes the help tag's look:
+
+```ts
+import "@kerfjs/ui/overlay-tooltip.css";
+import { tooltip } from "kerfjs/overlay";
+
+const stop = tooltip(
+  deployButton,
+  "Builds the current branch and deploys it to staging.",
+  { exitClass: "kui-tooltip-exit", exitDuration: 100 },
+);
+// Later: stop() removes the listeners and any shown tooltip.
+```
+
+## What the stylesheet does
+
+- **Look.** The `.kerf-tooltip` wrapper takes the loud neutral fill with
+  on-loud text at 14px and a 3px radius: the same look as the help tags that
+  icon-only Kerf controls show.
+- **Width.** It sizes to its text and wraps at 40 characters, staying 8px
+  inside a narrow viewport.
+- **Pointer.** It never takes the pointer, so it cannot block the control
+  beneath it.
+- **Motion.** It fades in on its own (no `enterClass` needed). Pass
+  `exitClass: 'kui-tooltip-exit'` with `exitDuration: 100` and it fades out as
+  it hides. Under `prefers-reduced-motion` or
+  `:root[data-kui-effects="static"]` it appears and leaves at once.
+- **Forced colors.** It draws `CanvasText` on `Canvas`.
+- **Stacking.** Set `--kui-overlay-tooltip-z-index` (default 1200) to change
+  its stacking order. With `native: true` it is in the top layer instead.
+
+Structured content from a render function inherits the tooltip's colors, so
+use plain inline markup (`<strong>`, a line break) rather than components that
+set their own text color.
+
+## When to use it
+
+- A control or value needs a short explanation on hover and focus: a longer
+  description of an action, a chart point, or a truncated label.
+- Not for icon-only Kerf controls: `@kerfjs/ui/help-tags-register` already
+  shows their help tag.
+- Not for interactive content or the only copy of important information. Use an
+  `AnchoredSurface` the person opens, or visible text.
+
+Keep the anchor's accessible name complete without the tooltip; the wrapper is
+`role="tooltip"` and appears on keyboard focus as well as hover.
+
+Use this instead of `wa-tooltip`, which is Discouraged.

package/docs/progress.md

@@ -0,0 +1,62 @@
+# Progress
+
+Two components show progress: `ProgressBar` (`@kerfjs/ui/progress-bar`), a
+linear bar on the native `<progress>` element, and `ProgressRing`
+(`@kerfjs/ui/progress-ring`), a compact circle for a line of text, a row, or a
+toolbar. Both are determinate (`value` of `max`, default `max` 1) or, without a
+`value`, indeterminate.
+
+```tsx
+import { ProgressBar } from "@kerfjs/ui/progress-bar";
+import { ProgressRing } from "@kerfjs/ui/progress-ring";
+
+<ProgressBar
+  id="upload"
+  label="Uploading Files"
+  value={3}
+  max={12}
+  valueText="3 of 12 files"
+  showValue
+/>;
+<ProgressRing label="Claim Time Remaining" value={0.75} valueText="45 minutes left" />;
+```
+
+## ProgressBar
+
+- **Name.** `label` is a visible line above the bar that also names it (with
+  an `id`, through `aria-labelledby`); `ariaLabel` names a bar without one.
+- **Readout.** `showValue` puts the percentage, or `valueText`, at the end of
+  the label row. `valueText` also replaces the spoken percentage.
+- **Indeterminate.** Omit `value` and a band sweeps across the track. It holds
+  still under `prefers-reduced-motion` or the static-effects switch.
+- **Tone and size.** `tone` is `brand` (default), `success`, `warning`, or
+  `danger`; `size="compact"` is a 4px track for a row or table cell (default
+  6px).
+
+The bar takes the full available width and the shared block-content inset (a
+transparent 1px border and 8px padding), so its label sits on the same text
+column as `Text`.
+
+## ProgressRing
+
+- **Name.** `label` is required: the ring is `role="progressbar"` with
+  `aria-valuenow` as a percentage, or `valueText`.
+- **Size.** `small` (16px) for a line of text, `medium` (24px, the default)
+  beside an icon in a row or toolbar, `large` (40px) on its own. Its box is
+  exactly its diameter, so it aligns with icons of the same size.
+- **Indeterminate.** Omit `value` and it spins a quarter arc, which holds still
+  under reduced motion.
+- **Tone.** The same tones as the bar.
+
+## Choosing
+
+- A measurable task with room for a label row: `ProgressBar`.
+- Compact progress beside an item: `ProgressRing`.
+- A brief busy glyph inside a control: `LoadingSpinner`.
+- App-wide progress with no home beside the work: `CornerStatus` or
+  `EdgeActivityIndicator`.
+- A reading on a scale that is not progress (a rating, a level): a native
+  `<meter>`.
+
+Forced colors draw the fills in `Highlight`. Use these instead of
+`wa-progress-bar` and `wa-progress-ring`, which are Discouraged.

package/docs/recipes.md

@@ -77,27 +77,21 @@ controls relocate without changing focus order.
 
 [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. Its explicit 16px `viewportGutter` and `maxHeight="viewport"`
-bound the roomy modal to the dynamic viewport; the compact fullscreen
-presentation retains its existing geometry. Application render state chooses
-the presentation and can likewise choose gutter/cap values for a compact modal.
-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.
+The recipe renders `ListDetailDialog` (`@kerfjs/ui/list-detail-dialog`). On
+roomy devices the list and the detail are full-height columns, each a `Pane`
+with its own top `Toolbar`, so the divider runs the dialog's full height. The
+list column's toolbar carries its quiet default-size title; the detail
+column's toolbar carries the dialog's primary extra-large title and the close
+control, and its pinned footer carries the record actions. The surface draws
+no header of its own, and its label still names the modal. Its explicit 16px
+`viewportGutter` bounds the roomy modal to the dynamic viewport. On compact
+devices the same component fills the screen and becomes a `NavStack`
+drill-down whose back control the application pops; every view keeps the
+close control and the detail keeps its pinned actions. The application owns
+open state, selection, the pushed detail, dismissal policy, and record
+actions. Do not compose `DialogSurface` around a `SplitView` by hand for this
+layout: the surface header would span both columns and stop the divider below
+it. See [ListDetailDialog](./list-detail-dialog.md).
 
 ## Composer Form