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

package/docs/slider.md

@@ -0,0 +1,64 @@
+# Slider
+
+`@kerfjs/ui/slider` picks a value on a range. It is a native
+`<input type="range">` drawn as a track, a brand fill up to the value, and a
+round thumb, identically in Chromium, Firefox, and WebKit.
+
+```tsx
+import { Slider } from "@kerfjs/ui/slider";
+import { wireSliders } from "@kerfjs/ui/wire-sliders";
+
+<Slider
+  id="volume"
+  label="Volume"
+  value={volume.value}
+  showValue
+  unit="%"
+  hint="Applies to every output device."
+  action="set-volume"
+/>;
+
+const stop = wireSliders(root);
+```
+
+## Props
+
+- `id` (required) identifies the input and derives the readout, hint, and
+  tick ids.
+- `min` (default 0), `max` (default 100), `step` (default 1), and `value`
+  (default the midpoint, snapped to `step`; clamped to the range).
+- `label` names it in a row above the track; `ariaLabel` names one without a
+  visible label.
+- `showValue` adds the current value at the end of the label row, followed by
+  `unit` (such as `%`). With a `unit`, the spoken value includes it too.
+- `ticks` labels stops under the track (`{ value, label? }`). The labels are
+  visual; the input still reports its value.
+- `hint` is supporting text below it and its accessible description.
+- `size="compact"` is a 3px track, a 16px thumb, and 14px text; `disabled`
+  dims it.
+- `orientation="vertical"` stands it up, minimum at the bottom, `length`
+  tall (default 160px), with the label row above and the fill running upward.
+  A vertical Slider takes no `ticks`. Arrow keys still step it.
+- `action` puts a `data-action` on the input. Listen for `input` (live) or
+  `change` (committed) and store the value the app re-renders with.
+
+## Live readout
+
+The fill and the readout come from the rendered value. Call
+`wireSliders(root)` once above your Sliders: one delegated `input` listener
+keeps the fill, the readout, and the spoken value text in step with a drag
+before the app re-renders. `syncSlider(input)` recomputes one by hand.
+
+## Geometry and accessibility
+
+A horizontal Slider fills the available width (a vertical one is as wide as
+its label row) with the shared block-content inset (a
+transparent 1px border and 8px padding), so its label sits on the same text
+column as `Text`. Keyboard and screen-reader behavior are the platform's:
+arrow keys, Page Up and Down, Home, and End step it. The readout is hidden
+from assistive technology because the input already reports its value.
+Forced colors draw a `Highlight` fill on a `GrayText` track.
+
+Use a numeric `TextField` when the exact number matters, a `Switch` for on or
+off, and a `SegmentedControl` for a few named options. Use this instead of
+`wa-slider`, which is Discouraged.

package/docs/surface-scaffold.md

@@ -1,23 +1,78 @@
 # 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, dismissal policy, ids,
-labels, and content. With `@kerfjs/ui/popup-menu/register` imported, a dropdown
-inside `PopupSurface` also keeps keyboard item navigation made during its show
-animation when Web Awesome completes its initial focus handoff.
-
-Wrap one `wa-dialog` with `DialogSurface`. Choose `size` (`small`, `medium`, or
-`large`), `presentation` (`modal`, `side-sheet`, `fullscreen`, or
-`bottom-sheet`; see [Bottom sheets](#bottom-sheets)), and independent
-`bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
-match Kerf's medium modal, 8px body, and 16px footer rhythm.
+`DialogSurface` is Kerf's modal dialog: a native `<dialog>` with a header
+(title, header actions, close button), a body, and an optional footer, sized
+and presented by its props. `PopoverDialogSurface` is its non-modal sibling,
+and `PopupSurface` insets a raw Web Awesome dropdown. The application owns
+open state, dismissal policy, ids, names, and content.
+
+`DialogSurface` is the single-pane dialog type. For a modal that picks a
+record from a list and shows its detail beside it, use
+[`ListDetailDialog`](./list-detail-dialog.md) instead of wrapping a
+`SplitView` in a `DialogSurface`: it draws no surface header, so the title and
+close control sit in the detail column and the divider runs the full height.
+For an editing task with side panels, use
+[`WorkbenchDialog`](./workbench-dialog.md), a header-less dialog around a
+`Workbench` whose rails become overlays on compact devices.
+
+```tsx
+import { DialogSurface, openDialog } from '@kerfjs/ui/surface-scaffold';
+
+<Button action="edit-workspace">Edit Workspace</Button>
+<DialogSurface
+  id="edit-workspace"
+  label="Edit Workspace"
+  bodyInset="none"
+  footer={
+    <>
+      <Button rootAttributes={{ 'data-dialog-close': '' }}>Cancel</Button>
+      <Button tone="brand" action="save-workspace">Save</Button>
+    </>
+  }
+>
+  <List>
+    <ListInsetText>Changes apply to every project in this workspace.</ListInsetText>
+  </List>
+</DialogSurface>;
+
+openDialog(document.getElementById('edit-workspace') as HTMLDialogElement);
+```
+
+- **Name.** `label` names the dialog and is its title text. With `heading`
+  (title content such as an xl `ToolbarText` with a description), pass
+  `labelledBy`, the id of the element that names it, or keep `label`.
+- **Header.** The title, then `headerActions` and a close button (`closeLabel`,
+  default `Close`). `withoutHeader` renders none, for content that owns its
+  heading and close control.
+- **Body and footer.** `children` is the body; `footer` sits below it (or
+  floats over it, see [Chat dialogs](#chat-dialogs-a-floating-footer-over-a-filling-transcript)).
+- **Opening and closing.** Render the dialog closed and open it with
+  `openDialog(dialog)`: it opens modally in the top layer, the rest of the
+  page is inert, and focus moves to an `autofocus` element or else the panel.
+  `closeDialog(dialog)` closes it after its exit motion; the browser returns
+  focus to the element that opened it. Do not toggle its `open` attribute,
+  which opens a dialog without modality.
+- **Close requests.** The close button, any element inside with
+  `data-dialog-close` (a Cancel button), Escape, and, with `lightDismiss`, a
+  press on the backdrop ask to close: the dialog dispatches a cancelable
+  `kui-request-close` whose `detail.source` is `close-button`, `escape`, or
+  `backdrop`. Call `preventDefault()` to keep it open (unsaved changes); the
+  panel then pulses, as it does for a backdrop press without `lightDismiss`.
+  The native `close` event fires once it has closed. Your own
+  `closeDialog()` is never refused.
+
+Choose `size` (`small`, `medium`, or `large`), `presentation` (`modal`,
+`side-sheet`, `fullscreen`, or `bottom-sheet`; see
+[Bottom sheets](#bottom-sheets)), and independent `bodyInset` / `footerInset`
+(`none`, `compact`, or `comfortable`). The defaults match Kerf's medium modal,
+8px body, and 16px footer rhythm. The dialog scales and fades in and out
+(150ms), unless motion is reduced or the document's static effects mode is on.
 
 The panel corner is concentric with a pill `ToolbarControlGroup` (22px) resting
 at the body inset: 30px for `compact` (and `none`) and 38px for `comfortable`,
 so header and body controls nest into the curve. A side sheet uses the same
-radius on its leading corners, and a bare `wa-dialog` or `PopoverDialogSurface`
-takes the 30px default.
+radius on its leading corners, and a `PopoverDialogSurface` takes the 30px
+default.
 
 The modal size presets have preferred widths of 400px, 560px, and 800px,
 respectively, before the viewport width cap. Set `preferredWidth` to a branded
@@ -31,14 +86,12 @@ resource tracks or preview aspect sizing.
 Every `DialogSurface` root has the same structure, so two sibling dialogs that
 are rendered conditionally are matched by position when the page re-renders:
 one open dialog's element (with its accessible name and open state) can be
-reused for another, and Web Awesome events such as `wa-after-hide` fire on the
-wrong dialog or not at all. Give each sibling a stable key on its root with
-`rootAttributes`, instead of wrapping it in an app `div`:
+reused for another, and its `close` event fires on the wrong dialog. Give each
+sibling a stable key on its root with `rootAttributes` (or an `id`), instead
+of wrapping it in an app `div`:
 
 ```tsx
-<DialogSurface rootAttributes={{ "data-key": "project-setup" }}>
-  <wa-dialog label="Set up project">…</wa-dialog>
-</DialogSurface>
+<DialogSurface label="Set up project" rootAttributes={{ "data-key": "project-setup" }}>…</DialogSurface>
 ```
 
 `rootAttributes` takes `data-*` identity only; the surface's own configuration
@@ -51,26 +104,25 @@ It sets the minimum horizontal clearance; `preferredWidth` overrides the `size`
 preset when supplied. `maxHeight` accepts a branded length or `"viewport"`; explicit caps are
 clamped to the dynamic viewport height minus twice the gutter (16px per edge
 when the gutter is omitted). Negative gutters/caps clamp to zero. Omitting
-both options preserves Web Awesome's existing width and phone height caps.
+both options keeps the default caps: 20px clear of each viewport edge, and
+80% of the viewport height at 420px wide or narrower.
 These options apply only to `presentation="modal"`; side sheets and fullscreen
 surfaces keep their own geometry, and a bottom sheet reads `height` and
 `maxHeight` as described in [Bottom sheets](#bottom-sheets).
 
 ```tsx
-import '@kerfjs/ui/surface-scaffold/register';
 import { remify } from '@kerfjs/ui/css-values';
 import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
 
-<DialogSurface preferredWidth={remify(832)} viewportGutter={remify(8)} maxHeight="viewport" bodyInset="none">
-  <wa-dialog label="Close Workspace">{/* Application-owned content and footer */}</wa-dialog>
+<DialogSurface id="close-workspace" label="Close Workspace" preferredWidth={remify(832)} viewportGutter={remify(8)} maxHeight="viewport" bodyInset="none" footer={actions}>
+  {/* Application-owned content */}
 </DialogSurface>;
 ```
 
 This gives a desktop modal an 832px preferred width and a phone modal an 8px edge gutter with a `calc(100dvh - 16px)` height
-cap without application selectors on Kerf roots or Web Awesome parts. A cap
-is not a fixed height: short content stays naturally sized, and taller content
-scrolls in Web Awesome's body while its header/footer remain outside that
-scroll owner. Choosing a larger cap cannot guarantee that arbitrary content
+cap without application selectors on Kerf roots. A cap is not a fixed
+height: short content stays naturally sized, and taller content scrolls in the
+dialog body while its header/footer remain outside that scroll owner. Choosing a larger cap cannot guarantee that arbitrary content
 fits without scrolling; preview tracks, canvas aspect ratios and content sizing
 remain application-owned.
 
@@ -95,7 +147,7 @@ edit sheet. The default `modal` presentation is unchanged.
 - **Safe area and keyboard.** The panel runs to the edge, behind the home
   indicator and any virtual keyboard, while a block-end padding keeps its
   content above them. The padding is the largest of
-  `--kui-safe-area-block-end`, the keyboard overlap the register measures from
+  `--kui-safe-area-block-end`, the keyboard overlap `openDialog` measures from
   `visualViewport` (layout height minus the visual viewport's height and top
   offset, ignored while pinch-zoomed), and the VirtualKeyboard API's
   `env(keyboard-inset-height)`. A page whose viewport meta sets
@@ -113,31 +165,27 @@ edit sheet. The default `modal` presentation is unchanged.
   horizontal `separator` named "Resize sheet" with `aria-valuemin`,
   `aria-valuenow`, and `aria-valuemax` in visible px. Drag it, or use the
   arrow keys (16px), Page Up/Down (64px), Home (`minHeight`, default 160px),
-  and End (the cap). The register injects the grabber into the dialog's
-  shadow panel, so it never disturbs `bodyLayout` children or a Kerf morph.
-  Each opening starts again at `height`.
+  and End (the cap). The grabber sits at the panel's top edge, outside the
+  body, so it never disturbs `bodyLayout` children, and the resized height
+  survives a re-render while the sheet is open. Each opening starts again at
+  `height`.
 - **Motion.** The sheet slides up from the bottom edge when it opens and back
   down when it is dismissed. `enterMotion="standard"` or
-  `exitMotion="standard"` keeps Web Awesome's scale-and-fade for that
-  transition. The slide falls back to Web Awesome's motion under
-  `prefers-reduced-motion: reduce` and the document's static effects mode
-  (`:root[data-kui-effects="static"]`). A prevented close still pulses.
+  `exitMotion="standard"` keeps the dialog's scale-and-fade for that
+  transition. There is no motion under `prefers-reduced-motion: reduce` or
+  the document's static effects mode (`:root[data-kui-effects="static"]`). A
+  refused close still pulses.
 
 ```tsx
-import '@kerfjs/ui/surface-scaffold/register';
 import { remify } from '@kerfjs/ui/css-values';
 import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
 
-<DialogSurface presentation="bottom-sheet" height={remify(360)} minHeight={remify(200)} resizable bodyInset="none">
-  <wa-dialog label="New Message" light-dismiss>
-    {/* Application-owned fields */}
-  </wa-dialog>
+<DialogSurface id="new-message" label="New Message" lightDismiss presentation="bottom-sheet" height={remify(360)} minHeight={remify(200)} resizable bodyInset="none">
+  {/* Application-owned fields */}
 </DialogSurface>;
 ```
 
-The resize grabber, keyboard clearance, and slide need the `/register`
-entry. Without it the sheet keeps its bottom-edge geometry and safe-area
-padding, shows no grabber, and opens with Web Awesome's own animation.
+`openDialog` wires the resize grabber, keyboard clearance, and slide.
 `preferredWidth`, `bodyLayout`, the floating header and footer, and the
 insets compose with a bottom sheet as they do with a modal.
 
@@ -231,10 +279,8 @@ body's whole height to its one child, which owns its own scrolling; the body
 itself stops scrolling. Combine it with `bodyInset="none"`.
 
 ```tsx
-<DialogSurface size="large" height={remify(640)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill">
-  <wa-dialog label="Repository Status">
-    <SplitView id="repo-split" label="Changes" listWidth={{ size: 432, maxFraction: 0.5 }} list={list} detail={detail} />
-  </wa-dialog>
+<DialogSurface label="Repository Status" size="large" height={remify(640)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill">
+  <SplitView id="repo-split" label="Changes" listWidth={{ size: 432, maxFraction: 0.5 }} list={list} detail={detail} />
 </DialogSurface>;
 ```
 
@@ -253,8 +299,8 @@ and floats its composer over the body's block end. Two props compose it:
   The modal panel is its positioning context. The default `docked` footer
   sits below the body as before.
 
-The register measures the footer (it follows a composer that grows, wraps, or
-hides) and the body reserves that height plus the offset after its own inset,
+An open dialog measures its footer (it follows a composer that grows, wraps,
+or hides) and the body reserves that height plus the offset after its own inset,
 with a matching `scroll-padding`. Flowing body content scrolls beneath the
 floating footer and its end stays reachable above it; with `fill` or
 `fill-last` the filling child's scrollport ends at the footer's top. Content
@@ -278,24 +324,31 @@ Choose the offset like any other responsive value: the scaffold adds no
 breakpoint. An 8px offset lines a composer up with the transcript's
 content-item edges when the body has `bodyInset="none"` and list geometry;
 `viewportGutter` and `footerOffset` can follow `deviceClass()` when a phone
-needs tighter edges. Put a [`Composer`](./composer.md) in the floating footer
+needs tighter edges. Put a [`MessageComposer`](./message-composer.md) in the floating footer
 with `footerInset="none"`: its raised frame and shadow lift it over the
 transcript, and its field grows the measured footer. With `submitOnEnter` and
-`wireComposers(root)`, Enter sends through the same action as the Send button.
+`wireMessageComposers(root)`, Enter sends through the same action as the Send button.
 
 ```tsx
-<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill-last" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
-  <wa-dialog label="Assistant">
-    <StateBanner title="Answers use the latest nightly build." tone="neutral" />
-    <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">
-      {messages.map((message) => (
-        <ContentItem bubble={message.mine ? 'end' : 'start'} appearance={message.mine ? 'brand-loud' : 'neutral'}>
-          <Text variant="span">{message.text}</Text>
-        </ContentItem>
-      ))}
-    </List>
-    <Composer submitOnEnter slot="footer" id="assistant-message" name="message" label="Message" placeholder="Ask about this build" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
-  </wa-dialog>
+<DialogSurface
+  label="Assistant"
+  height={remify(560)}
+  viewportGutter={remify(8)}
+  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={<Button tone="brand" action="send-message">Send</Button>} />}
+>
+  <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+  <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">
+    {messages.map((message) => (
+      <ContentItem bubble={message.mine ? 'end' : 'start'} appearance={message.mine ? 'brand-loud' : 'neutral'}>
+        <Text variant="span">{message.text}</Text>
+      </ContentItem>
+    ))}
+  </List>
 </DialogSurface>;
 ```
 
@@ -308,11 +361,11 @@ behind `--kui-chrome-material-filter` (a blur and saturation backdrop filter).
 Content passing beneath the title bar reads as softened color, not as
 competing text. The default `docked` header sits above the body as before.
 
-The register measures the header the same way it measures the footer (it
-follows a title that wraps, text that grows, or a `without-header` toggle).
+An open dialog measures its header the same way it measures the footer (it
+follows a title that wraps, text that grows, or a `withoutHeader` toggle).
 The body reserves the measured height before its own inset, with a matching
 `scroll-padding`, so flowing content starts below the title bar and scrolls
-beneath it. A dialog without the register has no measurement, so its header
+beneath it. Unmeasured (a dialog opened without `openDialog`), the header
 stays docked rather than covering content.
 
 To let a filling transcript scroll visibly beneath the title bar, make it the
@@ -325,21 +378,29 @@ reservation: they never sit beneath the title bar. Combined with a floating
 composer and `scrollClearance="both"`, the transcript scrolls beneath both:
 
 ```tsx
-<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill" headerPresentation="floating" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
-  <wa-dialog label="Release Thread">
-    <ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />
-    <List gap="xs" controlInsets="tb" scrollable scrollClearance="both">
-      {bubbles}
-    </List>
-    <Composer submitOnEnter slot="footer" id="thread-message" name="message" label="Message" placeholder="Reply to the thread" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
-  </wa-dialog>
+<DialogSurface
+  label="Release Thread"
+  heading={<ToolbarText text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />}
+  height={remify(560)}
+  viewportGutter={remify(8)}
+  bodyInset="none"
+  bodyLayout="fill"
+  headerPresentation="floating"
+  footerPresentation="floating"
+  footerOffset={remify(8)}
+  footerInset="none"
+  footer={<MessageComposer submitOnEnter id="thread-message" name="message" label="Message" placeholder="Reply to the thread" trailing={<Button tone="brand" action="send-message">Send</Button>} />}
+>
+  <List gap="xs" controlInsets="tb" scrollable scrollClearance="both">
+    {bubbles}
+  </List>
 </DialogSurface>;
 ```
 
 Like a `Pane`'s overlay header, the title bar draws its divider as scroll
 state: a 1px line along its bottom edge only while the body, or a filling
 child that reaches beneath it, is scrolled away from its top, and none at
-rest. The register follows those scrollers (a nested scroller that starts
+rest. The open dialog follows those scrollers (a nested scroller that starts
 below the title bar never counts), and the line is an inset shadow, so it
 never moves the header or the content.
 
@@ -347,8 +408,8 @@ The material turns opaque under `prefers-reduced-transparency: reduce` or
 `prefers-contrast: more`, and where the browser lacks `backdrop-filter`; in
 forced colors the header paints `Canvas` with a `CanvasText` bottom edge.
 
-For a title with a short supporting line, slot a `ToolbarText` as the label
-(`<ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />`).
+For a title with a short supporting line, pass a `ToolbarText` as the
+`heading` (`heading={<ToolbarText text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />}`).
 On the floating title bar an untoned `ToolbarText` keeps AA by itself: its
 title takes the normal text color and its description lifts halfway toward
 it. Any other quiet copy you place there can fall below AA over the content
@@ -365,7 +426,7 @@ geometry.
 
 ## Non-modal dialogs: `PopoverDialogSurface`
 
-`wa-dialog` is modal: it makes the page inert until it closes. When a dialog
+`DialogSurface` is modal: it makes the page inert until it closes. When a dialog
 should leave the page interactive and close on Escape or a press outside (a
 status panel, a quick inspector), render `PopoverDialogSurface` instead of a
 hand-built popover with application chrome CSS. It is a native
@@ -386,8 +447,8 @@ pass `describedBy`, the id of the element that holds the summary. It renders as
 </PopoverDialogSurface>;
 ```
 
-`DialogSurface` has no `describedBy`. It wraps a `wa-dialog` that the app
-authors, so the app names and describes that dialog on its own markup.
+`DialogSurface` has no `describedBy`: name it with `label` or `labelledBy`,
+and keep any description in the body or its `heading`'s description.
 
 Open it with a control's `popoverTarget` (or `showPopover()`); the browser
 places it centered in the top layer, light-dismisses it, and restores nothing
@@ -404,13 +465,19 @@ preview.
 </PopoverDialogSurface>;
 ```
 
-Use `DialogSurface` with `wa-dialog` whenever the task must block the page.
+Use `DialogSurface` whenever the task must block the page.
 
 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. Import `@kerfjs/ui/popup-menu/register` once for
-the focus handoff fix when wrapping a raw `wa-dropdown`.
-
-Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog`, measures each surface's footer for a floating footer's body clearance, draws a floating header's divider while content is scrolled beneath it, wires a bottom sheet's resize grabber, keyboard clearance, and slide, and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+`standard` uses the shared 8px surface inset. Keep the menu trigger named. A raw
+`wa-dropdown` should keep `data-morph-skip-children` when its upgraded light-DOM
+items must retain identity across Kerf rerenders; a `PopupMenu` already
+protects its own open state from the morph.
+
+`openDialog` installs the document listeners every `DialogSurface` needs
+(close requests, motion, and, while each dialog is open, chrome measurement,
+the floating header's divider, the bottom sheet's keyboard clearance and
+grabber, and restoring that measured state after an application re-render).
+Import `@kerfjs/ui/surface-scaffold/register` once when a dialog may be opened
+without `openDialog` and should still take close requests. Rendering a
+`DialogSurface` has no side effects and registers no custom element.

package/docs/tag-field.md

@@ -0,0 +1,66 @@
+# TagField
+
+`@kerfjs/ui/tag-field` collects short values as removable tags, each
+submitted as its own form value. It is SearchField's token editor in its
+`form-field` presentation, so tags look and edit like SearchField chips, plus
+a hidden input per tag.
+
+```tsx
+import { TagField } from "@kerfjs/ui/tag-field";
+import { wireTagFields } from "@kerfjs/ui/wire-tag-fields";
+
+const labels = signal(["bug", "docs"]);
+
+<TagField
+  id="labels"
+  label="Labels"
+  name="labels"
+  tags={labels.value}
+  hint="Press Enter or a comma to add a label."
+/>;
+
+const stop = wireTagFields(root, {
+  onChange: ({ tags }) => (labels.value = tags),
+});
+```
+
+## Props
+
+- `id` and `label` (required): the editor's identity and its visible name.
+- `tags` (required): the list, in order. The app owns it.
+- `name` and `form`: each tag submits as a hidden `<input name>` (none while
+  `disabled`).
+- `hint`, or `error`, which replaces the hint, marks the field invalid, and
+  turns its frame and message the danger color.
+- `max`: the most tags `wireTagFields` accepts.
+- `placeholder` (default `Add tag…`) and `morePlaceholder` after the last tag
+  (default `Add another…`), `required`, `disabled`, `icon` (default a tag
+  glyph), and `clearLabel` (default `Clear Tags`).
+
+## Editing
+
+`wireTagFields(root, options)` wires every TagField under `root`, including
+the SearchField editor mechanics it is built on:
+
+- **Adding.** Enter or a delimiter (default `,`) adds the typed text; text
+  pasted with delimiters becomes several tags; Tab, or focus leaving the
+  editor, adds what is typed (`commitOnBlur: false` turns that off).
+- **Refusing.** A duplicate (unless `allowDuplicates`), a value past `max`, or
+  a value `normalize` refuses is reported to `onReject({ id, value, reason })`
+  with `reason` `duplicate`, `max`, or `invalid`; show it as the `error`.
+  `normalize` defaults to trimming and refusing empty text.
+- **Removing and editing.** Backspace at the start removes the last tag; a
+  chip's × removes it; its label moves it back into the editor to edit; the
+  clear button empties the list.
+- **Moving.** ArrowLeft at the start reaches the chips; ArrowLeft and
+  ArrowRight move between them and back to the editor; Backspace or Delete
+  removes the focused chip.
+
+Every change goes to `onChange({ id, tags })`; apply it and re-render. The
+caret returns to the editor after a change made while typing. A
+`wireSearchFields` on the same root leaves a TagField's keys to
+`wireTagFields`, so both can wire one page.
+
+Use `SearchField` instead when the tokens are search filters, and
+`ChoiceChips` to pick several values from a short known set. Use this instead
+of `wa-tag-input`, which is Discouraged.

package/docs/type-contracts.md

@@ -17,12 +17,12 @@ public-signature artifact.
 | `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `SearchField({ collapsible: true })`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `KUI-T006` | `SearchFieldEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `KUI-T008` | A literal `TabNavigator.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all TabBarItem, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `KUI-T012` | `List.gap` accepts finite `UiSpaceName` shorthands or a complete branded `CssLength`; raw strings and non-standalone `CssLengthExpression` arithmetic are rejected. `calc(plus(...))` promotes a typed expression to a complete value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `KUI-T013` | CSS-valued props preserve property grammar: `List.flex` uses `CssFlex`, `Skeleton` dimensions use `CssSize`/`CssLength`, and choice icons and `LucideIcon.color` use `CssForegroundColor` (foreground tokens via `uiColor()`, `foregroundColorVar()`, or custom values via `foregroundColor()`; fill tokens such as `uiColor('success-fill-quiet')` are rejected); a row `iconTile` is a finite tone or a `CssColor` fill (custom values via `fillColor()`) with an optional `CssForegroundColor` glyph, and a `ChoiceChips` swatch is a `CssColor` fill (`fillColor()`, `uiColor()`, `colorVar()`) or `'transparent'`; a `fillColor()` value is a plain `CssColor` and is rejected where a `CssForegroundColor` is required; row declaration strings are absent. |
@@ -62,9 +62,9 @@ dataset. Do not cast a known literal typo merely to bypass the relationship.
 The following existing contracts were already exact and remain covered by the
 ordinary source/type gates:
 
-- required identity or accessible-name inputs on `AppTab`, `FloatingToolbar`,
+- required identity or accessible-name inputs on `TabBarItem`, `FloatingToolbar`,
   `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
-  `SegmentedControl`, `TokenSearchField`, and `ValueTable`;
+  `SegmentedControl`, `SearchField`, and `ValueTable`;
 - finite variants exported or represented as literal props on `DisclosureArrow`,
   `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
   `SunkenPanel`, `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
@@ -73,7 +73,7 @@ ordinary source/type gates:
   `wireWorkbench`;
 - a `ListHeader` count requires `countLabel` and excludes badge/status, while
   badge and status can appear together or be explicitly `undefined`; and
-- protected application metadata boundaries on `AppTab`, `ListItem`,
+- protected application metadata boundaries on `TabBarItem`, `ListItem`,
   `ListActionRow`, `ListHeader`, `Pane`, `CatalogExample`, and
   `CatalogExampleStack`.
 
@@ -88,7 +88,7 @@ unnamed non-landmark surfaces are intentional variants, not missing contracts.
 
 Types do not claim to validate:
 
-- the contents of `SafeHtml` slots (for example, “only AppTab children” or “no
+- the contents of `SafeHtml` slots (for example, “only TabBarItem children” or “no
   interactive descendants”);
 - nonempty arrays, unique ids, numeric min/max ordering, or a controlled value
   loaded from dynamic data;
@@ -109,7 +109,7 @@ move errors into casts without making the integration safer.
 - Give every `Select` either `label` or `ariaLabel`. Use an explicit `<string>`
   generic only for genuinely dynamic choice data.
 - Put `expanded`/expand-action props behind `collapsible: true`.
-- Replace `wireTokenSearchFields({ keyboard: true })` with either
+- Replace `wireSearchFields({ keyboard: true })` with either
   `{ keyboard: { onRemoveToken } }` or
   `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
   wanted.

package/docs/ui-analyzer.md

@@ -138,7 +138,7 @@ rejecting every stylesheet attached to a `kind: composition` catalog entry.
   `.kui-list-item__label`, `.acme-meter`), its `[data-component="…"]` root, or
   a Web Awesome tag the package themes (`wa-button`, `wa-select`), and the rule
   sets at least one ordinary property. It also catches a raw descendant of
-  cataloged component anatomy, such as `.kui-app-tab__select > svg`, even when
+  cataloged component anatomy, such as `.kui-tab-bar-item__select > svg`, even when
   the component class is not the final compound. A component root used only as
   context (`.kui-toolbar > .my-widget`) and app-named descendants remain
   available for app-owned content. In component mode, classless element subjects