@kerfjs/ui 5.0.0-beta.94 → 5.0.0-beta.96

package/dist/toolbar-text.d.ts

@@ -46,6 +46,17 @@ type ToolbarTextProps = ToolbarTextBaseProps & (({
     headingLevel?: HeadingLevel;
     /** Render an unanimated loading skeleton instead of the text. */
     placeholder?: boolean;
+    /**
+     * Quiet, single-line supporting copy under the title ("Changes save
+     * automatically."), truncating with an ellipsis. Title and description
+     * share the toolbar's control band and the same text start, with or
+     * without a leading icon group. With a description, `id` and
+     * `headingLevel` apply to the title alone, so a dialog's
+     * `aria-labelledby` names only the title.
+     */
+    description?: string;
+    /** Id for the description, for a dialog's `aria-describedby`. */
+    descriptionId?: string;
 } & ToolbarTextWrappingProps) | {
     /** Render a native button with this delegated action; the app owns editing. */
     action: string;
@@ -53,7 +64,9 @@ type ToolbarTextProps = ToolbarTextBaseProps & (({
     placeholder?: never;
     wrap?: never;
     maxLines?: never;
+    description?: never;
+    descriptionId?: never;
 });
-declare function ToolbarText({ text, size, tone, hideBelow, showBelow, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, tone, hideBelow, showBelow, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, description, descriptionId, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize, type ToolbarTextTone };

package/dist/toolbar-text.js

@@ -1,4 +1,4 @@
-export { ToolbarText } from './chunk-3DXHNLME.js';
+export { ToolbarText } from './chunk-IGTWXPTN.js';
 
 
 

package/dist/toolbar.d.ts

@@ -4,6 +4,8 @@ import { S as Sides } from './sides-BPSWde0A.js';
 import { PaneSeparatorSide } from './pane.js';
 
 type ToolbarPosition = 'header' | 'footer';
+/** Control-band density: `default` (60px with 44px groups) or `compact`. */
+type ToolbarDensity = 'default' | 'compact';
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
@@ -11,6 +13,15 @@ interface ToolbarProps {
     label?: string;
     /** Use footer semantics for a bottom toolbar; defaults to header. */
     position?: ToolbarPosition;
+    /**
+     * `compact` sizes the toolbar to a 34px control band with 3px block
+     * insets — 40px tall — for a header embedded in a panel or card. Fill it
+     * with `ToolbarControlGroup size="compact"` groups; inline insets and the
+     * gap between zones are unchanged. Composites that render a Toolbar from a
+     * `ToolbarConfig` (Workbench, CollapsiblePanel, NavStack, SplitView) forward
+     * it and size the groups they compose to match. Defaults to `default`.
+     */
+    density?: ToolbarDensity;
     /**
      * Physical divider edges in canonical top/right/bottom/left order, drawn
      * always. Defaults to none: a toolbar pinned over or under scrolling content
@@ -59,7 +70,7 @@ interface ToolbarProps {
  * that renders a `Toolbar` for the app (a Workbench or CollapsiblePanel
  * toolbar) forwards, so the app configures that toolbar instead of styling it.
  */
-type ToolbarConfig = Pick<ToolbarProps, 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
-declare function Toolbar({ leading, center, trailing, label, position, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+type ToolbarConfig = Pick<ToolbarProps, 'density' | 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
+declare function Toolbar({ leading, center, trailing, label, position, density, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarDensity, type ToolbarPosition, type ToolbarProps };

package/dist/toolbar.js

@@ -1,3 +1,3 @@
-export { Toolbar } from './chunk-BYHGRKC3.js';
+export { Toolbar } from './chunk-CMLPFIC5.js';
 
 //# sourceMappingURL=toolbar.js.map

package/dist/value-table.d.ts

@@ -1,6 +1,7 @@
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 interface ValueTableRowProps {
     label: string | SafeHtml;
@@ -14,15 +15,32 @@ interface ValueTableRowProps {
 }
 declare function ValueTableRow({ label, value, icon, className, placeholder, slot, }: ValueTableRowProps): SafeHtml;
 
+/** `columns` keeps label and value side by side; `stacked` puts each value under its label. */
+type ValueTablePresentation = 'columns' | 'stacked';
+/** Table width below which columns stack: `compact` is 512px, `narrow` 576px. */
+type ValueTableStackBelow = 'compact' | 'narrow';
 interface ValueTableProps {
     label: string;
     /** Compact row spacing for metadata-dense surfaces. */
     density?: 'default' | 'compact';
+    /**
+     * Minimum width of the label column (for example `px(160)`); the value then
+     * takes the rest of the row. Omitted, label and value share the row by
+     * content.
+     */
+    labelWidth?: CssLength;
+    /** Side-by-side columns (default) or values stacked under their labels. */
+    presentation?: ValueTablePresentation;
+    /**
+     * Stack the rows only while the table itself is narrower than the preset,
+     * so one table reads as columns in a wide dialog and stacks on a phone.
+     */
+    stackBelow?: ValueTableStackBelow;
     className?: string;
     children: KerfUiContent;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ValueTable({ label, density, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
+declare function ValueTable({ label, density, labelWidth, presentation, stackBelow, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
 
-export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
+export { ValueTable, type ValueTablePresentation, type ValueTableProps, ValueTableRow, type ValueTableRowProps, type ValueTableStackBelow };

package/dist/value-table.js

@@ -1,4 +1,4 @@
-export { ValueTable, ValueTableRow } from './chunk-DL55BSQX.js';
+export { ValueTable, ValueTableRow } from './chunk-GZE2XVKC.js';
 
 
 

package/dist/wire-catalog.d.ts

@@ -7,6 +7,7 @@ import './pane.js';
 import './workbench.js';
 import './nav-stack-BvSKY448.js';
 import './list.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
 import './panel-toolbar-CL9tYOkh.js';

package/dist/wire-comboboxes.d.ts

@@ -0,0 +1,26 @@
+type Root = HTMLElement | Document;
+/** A committed combobox value. */
+interface ComboboxCommit {
+    id: string;
+    value: string;
+    /** True when the value matched no suggestion (the person created it). */
+    created: boolean;
+    /** The field's input; clear or keep its text after applying the commit. */
+    input: HTMLInputElement;
+}
+interface WireComboboxesOptions {
+    onCommit: (commit: ComboboxCommit) => void;
+    /** Characters that commit the typed text besides Enter. Default `[',']`. */
+    commitKeys?: readonly string[];
+}
+/**
+ * Wire every `Combobox` below root: typing filters the suggestions (and offers
+ * to create the typed text), ArrowDown/ArrowUp move the active option, Enter or
+ * a commit key (comma by default) commits the active option or the typed text,
+ * a click commits an option, and Escape or leaving the field closes the list.
+ * Typed text that matches no suggestion commits only when the field offers
+ * creation; otherwise Enter commits the first matching suggestion. Dispose with the owning application.
+ */
+declare function wireComboboxes(root: Root, { onCommit, commitKeys }: WireComboboxesOptions): () => void;
+
+export { type ComboboxCommit, type WireComboboxesOptions, wireComboboxes };

package/dist/wire-comboboxes.js

@@ -0,0 +1,3 @@
+export { wireComboboxes } from './chunk-FDZNYD4C.js';
+
+//# sourceMappingURL=wire-comboboxes.js.map

package/dist/wire-comboboxes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-comboboxes.js"}

package/dist/wire-corner-status.d.ts

@@ -0,0 +1,11 @@
+type Root = HTMLElement | Document;
+/**
+ * Open every overlay `CornerStatus` below root in the top layer, now and as
+ * renders insert them. Opening never moves focus, and a manual popover has no
+ * light dismiss or Escape, so the status stays until the application removes
+ * it. Where the Popover API is missing the host stays a fixed-position
+ * element. Dispose with the owning application.
+ */
+declare function wireCornerStatus(root: Root): () => void;
+
+export { wireCornerStatus };

package/dist/wire-corner-status.js

@@ -0,0 +1,3 @@
+export { wireCornerStatus } from './chunk-ZKKO4MHC.js';
+
+//# sourceMappingURL=wire-corner-status.js.map

package/dist/wire-corner-status.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-corner-status.js"}

package/dist/wire-file-pickers.d.ts

@@ -0,0 +1,26 @@
+type Root = HTMLElement | Document;
+/** Files a picker reported, and how they arrived. */
+interface FilePickerSelection {
+    /** The trigger or drop zone element. */
+    picker: HTMLElement;
+    /** Its `pickerId`, when set. */
+    id?: string;
+    files: File[];
+    via: 'browse' | 'drop';
+}
+interface WireFilePickersOptions {
+    onFiles: (selection: FilePickerSelection) => void;
+}
+/** Whether a file matches a native `accept` list (`.png, image/*, text/plain`). */
+declare function fileMatchesAccept(file: File, accept: string): boolean;
+/**
+ * Report files chosen through any `FilePickerTrigger` or `FileDropZone` below
+ * root, or dropped on a `FileDropZone`, and mark a zone `data-dragging` while
+ * files are dragged over it. Dropped files are filtered by the input's
+ * `accept` (and to one when it is not `multiple`); a disabled picker ignores
+ * drops. The input is reset after each report, so choosing the same file again
+ * reports again. Dispose with the owning application.
+ */
+declare function wireFilePickers(root: Root, { onFiles }: WireFilePickersOptions): () => void;
+
+export { type FilePickerSelection, type WireFilePickersOptions, fileMatchesAccept, wireFilePickers };

package/dist/wire-file-pickers.js

@@ -0,0 +1,3 @@
+export { fileMatchesAccept, wireFilePickers } from './chunk-2MSPNRWJ.js';
+
+//# sourceMappingURL=wire-file-pickers.js.map

package/dist/wire-file-pickers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-file-pickers.js"}

package/dist/wire-list-reorder.d.ts

@@ -0,0 +1,41 @@
+/** Which edge of the target row the moved rows land beside. */
+type ListDropPosition = 'before' | 'after';
+/** How the person asked for the move. */
+type ListReorderSource = 'pointer' | 'keyboard';
+/** The row the moved rows land beside, and on which side of it. */
+interface ListReorderTarget {
+    id: string;
+    position: ListDropPosition;
+}
+/** One requested reorder. The application applies it to its own ordered state. */
+interface ListReorder {
+    /** The containing list's `data-list-id`, when it has one. */
+    listId?: string;
+    /** The moved rows' `itemId`s, in their current order. */
+    sourceIds: string[];
+    target: ListReorderTarget;
+    source: ListReorderSource;
+}
+interface WireListReorderOptions {
+    /** Apply the change synchronously (for example with `reorderListItems`) and re-render. */
+    onReorder: (change: ListReorder) => void;
+}
+/**
+ * Move `sourceIds` (kept in their current relative order) to `target`'s side
+ * of the target row. Returns a new array; an unknown target, a target that is
+ * itself being moved, or no known sources leave the order unchanged.
+ */
+declare function reorderListItems<T>(items: readonly T[], getId: (item: T) => string, sourceIds: readonly string[], target: ListReorderTarget): T[];
+/**
+ * Wire native drag-and-drop and Alt+Shift+ArrowUp/ArrowDown reordering for
+ * draggable `ListItem`, `ListItemLink`, and `ListActionRow` rows below `root`.
+ * Rows reorder within their `List` (or parent element) and are identified by
+ * `itemId`. Dragging a selected or pressed row moves every selected row of
+ * its list. While a pointer drag is in progress the wiring paints the same
+ * `data-dragging` / `data-drop-position` attributes the rows' `dragging` and
+ * `dropPosition` props render. Order stays application state: `onReorder`
+ * reports the change and the application re-renders. Returns a disposer.
+ */
+declare function wireListReorder(root: HTMLElement | Document, { onReorder }: WireListReorderOptions): () => void;
+
+export { type ListDropPosition, type ListReorder, type ListReorderSource, type ListReorderTarget, type WireListReorderOptions, reorderListItems, wireListReorder };

package/dist/wire-list-reorder.js

@@ -0,0 +1,3 @@
+export { reorderListItems, wireListReorder } from './chunk-MJ5RU6XT.js';
+
+//# sourceMappingURL=wire-list-reorder.js.map

package/dist/wire-list-reorder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-list-reorder.js"}

package/dist/wire-token-search-fields.js

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-TNG3XKHB.js';
+export { wireTokenSearchFields } from './chunk-Y3LC7JQO.js';
 
 
 

package/dist/workbench.d.ts

@@ -8,6 +8,7 @@ import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement,
 import { ToolbarConfig } from './toolbar.js';
 import './toolbar-text.js';
 import './css-values.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
 import './lucide-icon.js';

package/dist/workbench.js

@@ -1,4 +1,5 @@
-export { Workbench } from './chunk-QCLLBMLA.js';
+export { Workbench } from './chunk-BU23Z5HZ.js';
+
 
 
 

package/docs/accessibility.md

@@ -256,6 +256,29 @@ light and dark themes. The application owns controlled
 selection and the lifecycle, focus, and dismissal policy of any related
 popover or context menu.
 
+With `trailingMenu`, the trailing control is a `PopupMenu` trigger instead of
+the native trailing button: an icon-only Web Awesome button named by
+`trailingMenu.label`, announced with `aria-haspopup="menu"` and
+`aria-expanded`, in the same primary-then-trailing order. Opening it moves
+focus to the first command; Escape or a choice closes the menu and returns
+focus to the trigger. An interaction-revealed trigger stays visible while its
+menu is open. A pointer opening through `openPopupMenuAt` (for example from
+the row's `contextmenu`) keeps the same keyboard and dismissal behavior.
+
+## Reorderable list rows
+
+A `draggable` `ListItem`, `ListItemLink`, or `ListActionRow` is a native HTML
+drag source (a `ListActionRow` is dragged by its noninteractive root, so its two
+buttons keep their own activation). Pointer dragging is never the only way to
+reorder: `wireListReorder()` moves the focused row (or, when it is selected or
+pressed, every selected row of its list) with Alt+Shift+ArrowUp and
+Alt+Shift+ArrowDown, and returns focus to the moved row's focusable control
+after the application re-renders. The dragged rows dim and the drop target
+draws a 2px brand insertion line (system `Highlight` in forced colors), so the
+landing position never relies on color alone. A loading placeholder is never
+draggable. The application owns order, selection, and any announcement of the
+completed move.
+
 ## ResizableRegion
 
 Set `responsiveFillAt="narrow"` or `"compact"` when a responsive composition
@@ -321,7 +344,11 @@ so screen-reader heading navigation and "main heading" semantics work — the sa
 role/level pair used throughout Kerf UI. Keep the levels meaningful and
 non-skipping within a view. Pass trailing
 controls as a labeled `ToolbarControlGroup` when that group needs an accessible
-name. Keep supporting copy as app-owned content below the toolbar.
+name. A short supporting line belongs in the title's `description`: with it,
+`id` and `headingLevel` move to the title span, so `aria-labelledby` names only
+the title, and `descriptionId` gives the description its own id for
+`aria-describedby`. Keep longer supporting copy as app-owned content below the
+toolbar.
 An editable title can use `ToolbarText action="edit-title"`; it renders a native
 button whose full text remains its accessible name even when visually truncated.
 Click, Enter, and Space activate the delegated action. The app owns the input
@@ -423,6 +450,22 @@ icon. The filled track uses the normal neutral text role for readable unselected
 labels in light and dark themes. Use tabs—not a segmented control—when choices switch page regions that
 need `tab`/`tabpanel` semantics.
 
+## ChoiceChips
+
+`ChoiceChips` renders `role="radiogroup"`, named by `label` (`aria-label`) or
+by `labelledBy` (`aria-labelledby`, typically a visible `FieldLabel`). Each
+choice is a native `<input type="radio">` inside its pill `<label>`, so the
+browser owns the interaction: the group is a single Tab stop on the checked
+radio (or the first enabled one when nothing is selected), arrow keys move and
+select, Space selects, and the checked radio submits its value under `name`.
+`required` makes an unselected group fail native form validation, and
+`disabled` (group) or a choice's `disabled` removes it from interaction. The
+radio's accessible name is the visible label; a `swatch` or `icon` is
+`aria-hidden` decoration. The focus ring is drawn on the pill around the
+focused radio, and the checked pill adds a second pixel of border so the
+selection does not rely on hue alone; forced-colors mode paints it with
+`Highlight`.
+
 ## TokenSearchField
 
 Use `presentation="form-field"` when a structured search query sits beside
@@ -491,7 +534,7 @@ controlled state), and ArrowRight moves the caret past a trailing chip so typed
 text lands after it. An optional `onEdit({ id, editor, event })` — with the
 originating `InputEvent` so a caller can gate on `inputType`/`data` — fires on every editor
 `input`, letting a caller drop its own `input` listener; the application still
-owns query parsing and result-count/loading announcements.
+owns query parsing and result-count/loading announcements. When the app's `onEdit` or `onRemoveToken` changes tokens and the controlled render replaces the focused editor, `wireTokenSearchFields` moves focus and caret to the replacement at the same mutation checkpoint (a caret at the end of the query stays at the end; any other caret keeps its place in the remaining text), so keys typed at full speed are not lost.
 
 With a `createTokenSearchModel` passed to the field and registered in
 `wireTokenSearchFields(root, { models })`, grammar parsing, chips, clear/edit/

package/docs/anchored-surface.md

@@ -36,13 +36,21 @@ openAnchoredSurfaceAt(
 );
 ```
 
-Pass `context` for a pointer opened inside a modal `<dialog>`. For app-owned
-dialogs, include `<div data-kerf-overlay-host data-morph-skip></div>` in the
-dialog markup so controls in the anchored surface stay interactive. Dialogs
-opened by `kerfjs/overlay` get that host automatically. The helper uses the
-browser top layer where available, and the shared overlay fallback elsewhere.
-Closing an anchor's modal dialog also closes the surface. The temporary pointer
-anchor is removed when the surface closes.
+Pass `context` for a pointer opened inside a modal dialog. Inside a Web
+Awesome `wa-dialog` or `wa-drawer`, the surface stays interactive with no extra
+markup: `kerfjs/overlay` finds the modal `<dialog>` in the element's shadow
+root and hosts the surface in the element's light DOM, slotted inside the
+dialog. Dialogs opened by `kerfjs/overlay` get a host automatically too. For an
+app-owned native `<dialog>`, include
+`<div data-kerf-overlay-host data-morph-skip></div>` in the dialog markup so
+controls in the anchored surface stay interactive. For any other modal context,
+pass `container`: an element inside the open modal, where the surface is
+appended instead. The helper uses the browser top layer where available, and
+the shared overlay fallback elsewhere.
+
+Closing the anchor's modal dialog also closes the surface. Escape closes only
+the surface; the dialog beneath stays open. The temporary pointer anchor is
+removed when the surface closes.
 
 Override `--kui-anchored-surface-inset` and
 `--kui-anchored-surface-radius` for a theme; content can compose any Kerf UI

package/docs/app-layouts.md

@@ -23,7 +23,8 @@ Full-height shells retain `height: 100%` so they remain embeddable. Give a
 top-level shell a definite height chain by importing `@kerfjs/ui/document.css`
 and applying `.kui-app-root` to the direct mount container; see the
 [document baseline](document-baseline.md). Do not replace an embeddable shell's
-height with `100dvh`.
+height with `100dvh`; a full-viewport app instead adds `data-viewport="locked"`
+to its `.kui-app-root`, which locks the document (not the shell) to `100dvh`.
 
 ## Safe areas
 

package/docs/catalog.md

@@ -542,6 +542,47 @@ wireCatalog(app, {
 The browser helpers behind it, `uxReviewCaptureUrl` and `loadUxReviewProject`,
 are exported from `@kerfjs/ui/catalog` for a capture link placed elsewhere.
 
+### Catalogs served without Vite
+
+A catalog served by the app's own backend (an esbuild bundle behind Hono,
+Express, or a plain Node server) mounts the same endpoint from the same
+Node-only subpath, on its development server only. The catalog requests
+`__ux-review/project.json` relative to its page, so a page at `/ux-demo` asks
+for `/__ux-review/project.json`; both helpers answer at any base path.
+
+```ts
+import {
+  resolveUxReviewProject,
+  uxReviewMiddleware,
+  uxReviewProjectResponse,
+} from "@kerfjs/ui/vite-ux-review";
+
+// Resolve once at startup: the repository holding the working directory, or
+// resolveUxReviewProject({ root, projectDirectory }) like the Vite plugin.
+const projectDirectory = resolveUxReviewProject();
+
+// Fetch API servers (Hono, Bun, Deno): null means "not this endpoint".
+if (isDev)
+  app.use("*", async (c, next) =>
+    uxReviewProjectResponse(c.req.raw, projectDirectory) ?? next(),
+  );
+
+// Node / connect servers (Express, node:http):
+if (isDev) expressApp.use(uxReviewMiddleware(projectDirectory));
+```
+
+- **`resolveUxReviewProject({ root?, projectDirectory? })`** returns the real
+  path the Vite plugin would serve: `projectDirectory` resolved against `root`,
+  or the repository holding `root` (default `process.cwd()`).
+- **`uxReviewProjectResponse(request, projectDirectory)`** answers a Fetch API
+  `Request`: the JSON for a GET, `405` for another method, or `null` for any
+  other path.
+- **`uxReviewMiddleware(projectDirectory)`** is the same endpoint as a
+  `(request, response, next)` handler; `uxReviewPlugin` mounts it on Vite.
+
+Never register the endpoint in production: it reveals a local path, and a
+deployed catalog has no local project to capture into.
+
 ## Custom action names
 
 The shell emits `data-action="catalog-select"` (sidebar items),

package/docs/component-contract.md

@@ -114,6 +114,14 @@ package root; `ui-wiring` resolves helper imports through this file, including
 relative re-export barrels. Every named export must also appear in
 `wiring.helpers`.
 
+When a component's required wiring is the application's own root-delegated
+handlers rather than a named helper, list the `data-action` values it must
+handle in `wiring.actions`. Required wiring names at least one helper or action.
+`ui-wiring` accepts an action when a reachable module that imports `delegate`,
+`delegateCapture`, or `delegateActions` (from `kerfjs` or `kerfjs/actions`)
+names it as a string, selector, or table key; a cataloged component's own
+source never counts, because it renders the attribute.
+
 The selection catalog's `wiringProviders` lists public helpers that install
 other wiring helpers. The `ui-wiring` rule accepts a provider call for each
 helper it declares; `wireCatalog` provides `wireScrollDividers`.
@@ -316,6 +324,9 @@ and disposal.
 contain controls. When a row needs an independently interactive trailing
 region, `ListActionRow` owns the noninteractive root and the two sibling native
 buttons; the application owns their delegated behavior and controlled state.
+A `ListActionRow` with `trailingMenu` composes a real `PopupMenu` as that
+sibling trailing control instead of a button; the menu styles its trigger in
+the row's context from `popup-menu.css`, and the row never styles it.
 Both row components align a leading icon with the first label line when
 `multiline` allows the label to wrap; additional lines extend below that fixed
 visual anchor.
@@ -550,9 +561,11 @@ a plain `<button>` — the group styles `> button` fully, and it keeps the group
 free of a Web Awesome dependency and shadow DOM. Use `ToolbarActionLink` when
 the action must retain native anchor navigation; the group owns its geometry,
 hover, and focus treatment. Set `overflow="scroll"` when a row of controls must
-stay inside the available toolbar width. A disabled native button keeps the
-group's geometry, dims to half opacity, uses the `not-allowed` cursor, and
-paints neither its own nor a lone group's hover surface.
+stay inside the available toolbar width. A disabled native button — `disabled`,
+or `aria-disabled="true"` when it must stay focusable — keeps the group's
+geometry, dims to half opacity, uses the `not-allowed` cursor, and paints
+neither its own nor a lone group's hover surface; a disabled raw `wa-button`
+likewise paints no hover surface.
 Set `visibility="compact-only"` for a
 group that replaces wider toolbar controls below the Toolbar's compact container
 breakpoint; do not hide the group with an application class.
@@ -560,7 +573,11 @@ Use `sizing="grow"` on an expanded search group in a wrapping zone: it grows fro
 `growBasis` (19rem by default) into available row space, then takes a whole
 row at 480px container width or less. The basis remains its intrinsic minimum
 in a wider, non-stacked Toolbar, so sibling trailing groups can share the
-row. The collapsed search stays icon-sized.
+row. The collapsed search stays icon-sized. The group owns the open and
+close motion: its flex size animates while a collapsible `TokenSearchField`
+inside fills it on every frame, laid out at least basis-wide and clipped by the
+group, so a query never wraps or leaves an empty band mid-transition. At 480px
+container width or less, and under reduced motion, it opens in one frame.
 Use `sizing="fill"` for a group, including a non-search segmented control,
 that spans its wrapping row. Set `visibility="hide-collapsed-tiny"` on a
 collapsible group to omit its closed icon at 224px or less; expanded content
@@ -649,8 +666,11 @@ owners. The [layout contract](./layout.md) lists the public roles and tokens.
 Panel, dialog, and page headings are direct `Toolbar` compositions. The leading
 zone holds an optional icon `ToolbarControlGroup` and a direct extra-large
 `ToolbarText`; app actions belong in a trailing `ToolbarControlGroup`. Omit the
-icon group when it has no content. Supporting copy is app-owned content below
-the toolbar so it cannot pull the icon or actions out of alignment.
+icon group when it has no content. A short supporting line is the title's
+`ToolbarText` `description`: it renders quiet, single-line, truncating copy
+under the title, starting at the title's text with or without an icon group,
+and the title and description share the control band so the icon and actions
+stay aligned. Longer supporting copy is app-owned content below the toolbar.
 For an editable title, `ToolbarText action="edit-title"` renders a native button
 directly in the leading zone. It keeps content width when there is room, shrinks
 and ellipsizes beside a status chip when space is tight, and emits the delegated