@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/docs/tab-navigator.md

@@ -0,0 +1,291 @@
+# Tab navigator
+
+`@kerfjs/ui/tab-navigator` is a mobile-first, iOS-like bottom tab bar that switches
+between major app sections, where **each tab keeps its own content mounted** —
+usually a `NavStack`, so each tab's stack and scroll survive a switch. One of the
+opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+It is distinct from `TabBar` (document-oriented, reorderable strips).
+
+## Migration from TabScaffold
+
+The deprecated `TabScaffold` API was removed during the 5.0 beta series. Replace names and import
+paths when updating an app:
+
+| Previous                                                                           | Current                                                                                |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `TabScaffold`, `TabScaffoldTab`, `TabScaffoldProps` from `@kerfjs/ui/tab-scaffold` | `TabNavigator`, `TabNavigatorTab`, `TabNavigatorProps` from `@kerfjs/ui/tab-navigator` |
+| `wireTabScaffold`, `WireTabScaffoldOptions` from `@kerfjs/ui/wire-tab-scaffold`    | `wireTabNavigator`, `WireTabNavigatorOptions` from `@kerfjs/ui/wire-tab-navigator`     |
+| `@kerfjs/ui/tab-scaffold.css`                                                      | `@kerfjs/ui/tab-navigator.css`                                                         |
+
+Props, rendered DOM classes, data attributes, and wiring behavior are unchanged.
+The old JS and CSS subpaths are no longer exported. Import the new CSS path
+when your build does not use the package's `browser` condition.
+
+```ts
+import { TabNavigator } from "@kerfjs/ui/tab-navigator";
+import { wireTabNavigator } from "@kerfjs/ui/wire-tab-navigator";
+```
+
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads TabNavigator's stylesheet and those of the components it renders internally
+(the tab `Badge`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/tab-navigator.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
+## Controlled selection
+
+The app owns the active tab (a signal); `TabNavigator` renders every tab's scene
+(only the active one visible) plus the bottom bar, and `wireTabNavigator` reports
+clicks.
+
+```tsx
+const active = signal("home");
+
+<TabNavigator
+  id="app"
+  label="Sections"
+  active={active.value}
+  tabs={[
+    { id: "home", label: "Home", icon: <HomeIcon />, content: <HomeStack /> },
+    {
+      id: "search",
+      label: "Search",
+      icon: <SearchIcon />,
+      content: <SearchStack />,
+    },
+  ]}
+/>;
+
+// once, after first render:
+const dispose = wireTabNavigator(root, {
+  onSelect: (id) => {
+    active.value = id;
+  },
+});
+```
+
+Each `TabNavigatorTab` has an `id`, `label`, optional `icon`, optional `badge`
+and `badgeLabel` (see [Tab badges](#tab-badges)), and `content`. The
+bottom bar paints through the home-indicator safe area and pads for it and for
+the side insets, while each scene pads for the top and side insets (a scene
+whose only child is a `NavStack` or `Pane` lets that child own them; see
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas)). The bar keeps 44px targets. Its single-line labels preserve their full line box and
+truncate horizontally with an ellipsis when a destination name exceeds its
+share of the bar. On larger device classes, promote the tab set to a
+`Workbench` rail or a persistent sidebar instead of a bottom bar.
+
+Set `deepInset: true` on a plain tab scene to add 8px of padding on every side
+of its scrolling content, giving ordinary content items a 16px inline edge inset.
+The default is `false`. A scene whose only child is a `Pane` or layout lets
+that child own its content gutter: for a nested `NavStack`, set
+`pane: { deepInset: true }` on its views instead. The navigator bar and a
+stack's top toolbar remain full width.
+
+A plain scene can opt into `tabIndex: 0` to become a Tab stop or `tabIndex: -1`
+to accept programmatic focus. `outlined: true` keeps the standard focus ring
+visible independently of focus, for example for a drop target. Keyboard focus
+also draws that ring. Only the active scene receives the requested tab index or
+outline; inactive scenes stay out of the Tab order and hide the outline. A
+scene containing a `Pane` or another layout should put these options on its
+inner focus owner instead. A focusable scene is a tabpanel named by its tab label.
+
+## A NavStack with a top toolbar and Pane
+
+Put the `NavStack` directly in a tab's `content`. Give each view a structured
+`toolbar` and `pane` configuration. Leave `bottomToolbar` off both the views
+and the stack: the navigator's tab bar is the only bottom chrome. The view's
+Pane owns scrolling, while the stack keeps its toolbar above it and the
+navigator keeps the tab bar below it.
+
+```tsx
+import { List } from "@kerfjs/ui/list";
+import { ListItem } from "@kerfjs/ui/list-item";
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+
+const projectViews: NavStackView[] = [
+  {
+    key: "projects",
+    toolbar: { title: "Projects" },
+    pane: { appearance: "sunken" },
+    content: <List><ListItem label="Project Atlas" /></List>,
+  },
+];
+
+<TabNavigator
+  id="app"
+  label="Sections"
+  active={active.value}
+  tabs={[
+    {
+      id: "projects",
+      label: "Projects",
+      content: (
+        <NavStack
+          id="projects-stack"
+          label="Projects navigation"
+          views={projectViews}
+        />
+      ),
+    },
+    { id: "search", label: "Search", content: <SearchScene /> },
+  ]}
+/>;
+```
+
+The app owns each stack's view array and the navigator's active tab. Call
+`wireTabNavigator` for tab selection and `wireNavStack` for back navigation
+and transitions, each on its own component root. Push a detail by appending
+a view with its own `toolbar` and `pane`; switching tabs keeps that view
+mounted. The catalog's **NavStack Inside a Tab** example demonstrates the
+push, tab switch, and return flow.
+
+Set a tab's `appearance: "sunken"` when its scene owns scrolling and should
+paint the lowered surface behind short or long content. For a scene whose
+only child is a `Pane` or `NavStack`, set appearance on that child's scroll
+owner. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+
+## Bar separator and scroll divider
+
+`separator="auto"` (the default) draws the bar's top edge when the active scene
+has `appearance: "sunken"`. It also follows the sunken appearance of a sole
+`Pane`, or the active `Pane` view of a sole `NavStack`, inside that scene. The
+edge stays visible when the content fits and as the active tab or nested view
+changes. `separator="hidden"` suppresses the top line, including any scroll
+divider or `chromeDividers="always"` line.
+
+For a flat active scene, the bar has no permanent top line. With `wireScrollDividers(appRoot)`
+installed (see [Layout › Scroll dividers](layout.md#scroll-dividers)), it shows
+a line along its top edge only while the active scene's content continues below
+it — not at the scroll end and not when the content fits. The line keys on
+whatever actually scrolls in the scene: the scene itself or, through a sole
+child, a `NavStack`'s active view or a `Pane`'s content. A `NavStack` with its
+own bottom toolbar sits between them, so that toolbar's line applies instead.
+The line is the bar's always-present 1px top border, colored only while shown,
+so it never moves the bar or a tab.
+
+`chromeDividers` configures the scroll divider, with the same values as a `Pane`'s: `scroll`
+(the default) follows the scroll state and draws nothing until the wiring runs;
+`always` keeps the line, with or without the wiring; `none` drops it even when
+the wiring reports content below. It does not suppress the sunken-surface
+separator; use `separator="hidden"` for that.
+
+## Background colors
+
+`background` paints the navigator and its docked bar in an app-chosen color
+from `@kerfjs/ui/css-values` (`uiColor(...)`, `fillColor(...)`, or
+`colorVar(...)`) instead of the surface. A tab's own `background` paints its
+scene and replaces that scene's `appearance`. The overlay bar keeps the
+chrome material over either. Keep the bar's labels and the scene's text at AA
+over the colors you choose; forced colors paint `Canvas`. See
+[Background colors](layout.md#background-colors).
+
+```tsx
+<TabNavigator
+  id="library"
+  label="Library"
+  active={active.value}
+  background={uiColor("surface-raised")}
+  tabs={[{ id: "now", label: "Now Playing", content: <NowPlaying />, background: fillColor("#2b1d3a") }]}
+/>
+```
+
+`tint={{ color, scheme }}` on the navigator, or on one tab for its scene,
+re-derives the surface and text tokens from an app color, keeping text at AA.
+See [Tinted surfaces](layout.md#tinted-surfaces).
+
+## Translucent bar
+
+`barPresentation="overlay"` lays the tab bar over the active scene's bottom
+edge on the translucent chrome material (`--kui-chrome-material` behind
+`--kui-chrome-material-filter`), so the scene's content scrolls visibly beneath
+it, as under an iOS tab bar. The default, `docked`, gives the bar its own band.
+
+```tsx
+<TabNavigator
+  id="mail"
+  label="Mail Sections"
+  barPresentation="overlay"
+  active={active.value}
+  tabs={tabs}
+/>;
+```
+
+`wireTabNavigator` measures the live bar's border box (bottom safe area and its
+1px top edge included), publishes it on the root, and marks the root
+`data-bar-overlay="measured"`. The scenes then hand that height to their
+content as the block-end `--kui-edge-inset-*` context: a plain scene pads and
+scroll-pads by it, and a sole `Pane` or `NavStack` clears it itself, so the
+last item, and anything focused or scrolled into view, rests just above the
+bar. A `NavStack` with its own bottom toolbar pads that toolbar for the bar as
+it would for a bottom safe area: the toolbar's controls sit just above the tab
+bar while its material runs on beneath it. Until the wiring runs, the bar stays
+docked.
+
+Over the material, unselected labels lift halfway toward the normal text color
+and the selected label mixes 40% of it into the brand color, so both keep AA
+over any content beneath. The material turns opaque under reduced
+transparency, increased contrast, or without `backdrop-filter`, and paints
+`Canvas` with a `CanvasText` top edge in forced colors. The scroll divider still
+shows only while more content lies below. Like the NavStack overlay bars, the
+tab bar ends where a classic (space-taking) scrollbar's track begins, so the
+active scene's thumb and buttons stay visible and usable.
+
+### Clear bar
+
+`barPresentation="clear"` lays the bar over the active scene like `overlay`
+but fully transparent, for a bar over imagery. It stays
+clear while content scrolls beneath it; with `scrollEdge="material"` (or
+`"surface"`) a backing fades in (opacity only) while the scene continues
+beneath the bar and fades out over the last `scrollEdgeDistance` pixels
+(default 60) before its end. A clear bar draws
+no scroll divider, turns opaque under reduced transparency or increased
+contrast, and paints `Canvas` in forced colors. See
+[Clear header](layout.md#clear-header).
+
+## Tab badges
+
+Give a tab a `badge` (a count or short string such as `3`, `"99+"`, or
+`"New"`) to show the iOS tab-bar badge: a compact, solid `danger` `Badge` at the
+top-trailing corner of the tab's icon, growing outward as the text lengthens
+(without an icon it sits above the label). The badge is decorative
+(`aria-hidden`); its meaning reaches assistive technology through `badgeLabel`,
+which the tab folds into its accessible name as `"<label>, <badgeLabel>"`:
+
+```tsx
+{
+  id: "inbox",
+  label: "Inbox",
+  icon: <LucideIcon icon={Inbox} name="inbox" />,
+  badge: unread.value,
+  badgeLabel: `${unread.value} unread`,
+  content: <InboxStack />,
+}
+```
+
+`badgeLabel` defaults to the badge text itself, so supply a localized phrase
+whenever the bare text would be ambiguous. Omitting `badge` (or passing an
+empty string or a non-finite number) renders no badge and leaves the tab's name
+as its label; `0` renders, so pass `undefined` when a count should disappear.
+Keep the text short — clamp large counts (`"99+"`) in the app. The tone follows
+the platform convention and is fixed; do not restyle the badge.
+
+### Dot badges
+
+For new content without a count, pass `badge: true`. The tab shows the iOS
+tab-bar dot — an 8px solid `danger` `Badge` (`size="dot"`) centered on the
+icon's top-trailing corner (above the label without an icon). A dot has no
+text to fall back on, so `badgeLabel` is required by the types:
+
+```tsx
+{
+  id: "feed",
+  label: "Feed",
+  icon: <LucideIcon icon={Rss} name="rss" />,
+  badge: hasNewPosts.value ? true : undefined,
+  badgeLabel: "New activity",
+  content: <FeedStack />,
+}
+```
+
+The tab's accessible name becomes `"Feed, New activity"`. Pass `undefined` to
+clear the dot; `false` is not a badge value.

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

@@ -0,0 +1,137 @@
+# Compile-time contracts
+
+Kerf UI rejects invalid integrations at compile time only when TypeScript can
+prove the relationship from one call. The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact names those guarantees with stable `KUI-T###` ids. Its source fixture
+is compiled twice: against `src/` and against declarations extracted from the
+actual `npm pack` tarball. `npm run check:catalog` also verifies that every
+contract still points to a real catalog entry/import and a symbol in the emitted
+public-signature artifact.
+
+## Strengthened contracts
+
+| ID         | Compile-time guarantee                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `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 `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 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. |
+| `KUI-T014` | Stable single-root visual components accept the explicit native `slot` attribute. Multi-root `ResizableRegion` and `CollapsiblePanel` remain excluded because no single returned element can own the assignment, and other arbitrary native attributes remain rejected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+
+`KerfUiContent` lets conditionals and mapped component collections be direct
+siblings without an otherwise-unnecessary `Fragment`:
+
+```tsx
+<List>
+  {intro ? <ListInsetText>{intro}</ListInsetText> : null}
+  {rows.map((row) => (
+    <ListItem label={row.label} />
+  ))}
+</List>
+```
+
+The type is intentionally narrower than core JSX children. Wrap prose in a
+semantic text component, and read signals into components or structural
+conditionals rather than passing signal objects as content.
+
+Literal identity inference is intentionally additive for dynamic applications.
+When choices or ids arrive at runtime and the state signal is correctly typed as
+`string`, widen the component explicitly:
+
+```tsx
+<Select<string> value={loadedValue.value} choices={loadedChoices.value} ... />
+<SegmentedControl<string> value={mode.value} choices={loadedModes.value} ... />
+<TabNavigator<string> active={active.value} tabs={loadedTabs.value} ... />
+```
+
+The widening is an honest statement that TypeScript cannot know the runtime
+dataset. Do not cast a known literal typo merely to bypass the relationship.
+
+## Complete public-surface audit
+
+The following existing contracts were already exact and remain covered by the
+ordinary source/type gates:
+
+- required identity or accessible-name inputs on `TabBarItem`, `FloatingToolbar`,
+  `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
+  `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;
+- required controlled-state callbacks on `wireResizableRegions`, `wireTabBars`,
+  and `wireTabNavigator`, and the required app-owned size signals on
+  `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 `TabBarItem`, `ListItem`,
+  `ListActionRow`, `ListHeader`, `Pane`, `CatalogExample`, and
+  `CatalogExampleStack`.
+
+The remaining components (`LucideIcon`, `DisclosureArrow`, `Toolbar`,
+`ToolbarControlGroup`, `ListInsetControl`, `ListInsetText`, `LoadingSpinner`,
+`Skeleton`, `EmptyState`, `StateBanner`, `ValueTableRow`, and the
+pure helpers) have independent props with no further conditional invalid state
+that TypeScript can truthfully remove. Optional labels on decorative icons and
+unnamed non-landmark surfaces are intentional variants, not missing contracts.
+
+## Boundaries TypeScript cannot prove
+
+Types do not claim to validate:
+
+- 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;
+- equality between ids rendered in separate calls, elements discovered later in
+  the DOM, or an ARIA relationship's live target;
+- that a caller retained and invoked a wiring disposer; or
+- CSS class/token use inside arbitrary strings.
+
+Those remain catalog `KUI-C###` diagnostics, runtime filtering/guards, lint or
+browser assertions. Encoding them as permissive-looking TypeScript brands would
+move errors into casts without making the integration safer.
+
+## Migration from the earlier declarations
+
+- Add `actionLabel` and `actionIcon` to a non-toggle `ListHeader` action. For a
+  disclosure, set literal `toggle: true`, provide `action` and controlled
+  `expanded`, and remove trailing-action-only props.
+- 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 `wireSearchFields({ keyboard: true })` with either
+  `{ keyboard: { onRemoveToken } }` or
+  `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
+  wanted.
+- Add `wrap: true` anywhere `ToolbarText.maxLines` is used.
+- Replace `Toolbar({ divider: false })` with `dividerSides: ''`, which is now
+  the default (a toolbar pinned over scrolling content gets its divider from
+  `wireScrollDividers` through its `Pane`); canonical combinations such as `b`,
+  `tr`, and `trbl` select permanent physical edges.
+- Replace raw `List.gap` strings with a direct spacing shorthand (`"xs"`,
+  `"m"`) or a complete value from `@kerfjs/ui/css-values`. Replace
+  `gap="0.25rem"` with `gap={rem(0.25)}` and wrap sums with `calc(plus(...))`.
+  `Row`, `Grid`, and `List` also accept `gap={{ column: 'none', row: 'm' }}`;
+  each axis uses the same typed value contract.
+- Replace raw `List.flex` shorthands with `flex(grow, shrink, basis)` or a finite
+  keyword; replace raw Skeleton dimensions with `px`/`rem`/`em`/`pct` builders;
+  and replace raw choice colors with a foreground token such as
+  `uiColor('success-on-quiet')`, an app-owned `foregroundColorVar()`, or `foregroundColor('rebeccapurple')` for an application-chosen CSS color.
+  `SelectChoice.color` rejects fill tokens (`uiColor('success-fill-quiet')`) and
+  unqualified `colorVar()` values because a fill paints a nearly invisible
+  icon.
+- Remove `style` from `ListItem` and `ListActionRow`; use `className`, public
+  tokens, and cataloged props. These breaking cleanups land before 5.0 stable.
+
+JavaScript runtime behavior remains defensive for previously emitted calls, but
+new TypeScript builds report these invalid or ignored combinations.