@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

package/docs/sunken-panel.md

@@ -0,0 +1,93 @@
+# SunkenPanel
+
+`SunkenPanel` is a visually lowered application surface with one compact inset
+and a vertical content stack. Use it for a main work area or nested panel whose
+background should sit behind ordinary content, such as the primary stage in an
+issue tracker or component catalog.
+
+```tsx
+import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
+
+<SunkenPanel ariaLabel="Release workspace">
+  <ReleaseSummary />
+  <ReleaseChecks />
+</SunkenPanel>;
+```
+
+The default `shape="rounded"` uses the shared rounded-rectangle radius. Choose
+`shape="square"` for a flush or edge-to-edge area that needs `border-radius: 0`:
+
+```tsx
+<SunkenPanel shape="square">
+  <Workspace />
+</SunkenPanel>
+```
+
+## Filling a work area
+
+Set `fill` when the panel is the direct layout root of a parent with a definite
+height. Inside a flex column, use `flex` so it takes the remaining space and
+can shrink with its parent. Like `Grid`, `flex` accepts `true` (equivalent to
+`1 1 auto`), a CSS flex keyword, or a typed `CssFlex` value. The panel keeps
+`min-height: 0`, allowing its parent to own scrolling.
+
+```tsx
+<List fill>
+  <Toolbar label="Work area" />
+  <SunkenPanel flex>
+    <WorkArea />
+  </SunkenPanel>
+</List>
+```
+
+Inside a `Pane`, the Pane's content remains the scroll owner. Place a
+`SunkenPanel fill` in a definite-height Pane content region when the surface
+itself needs to cover empty space, or use `flex` when a flex parent allocates
+the remaining space. The panel does not add another scroller.
+
+## Ownership
+
+The root owns its lowered background, 8px padding, and 8px vertical gap.
+Children own their borders and internal geometry. The application owns child
+order, responsive placement, and scrolling; `SunkenPanel` deliberately does not
+create another scroll container.
+
+Use `ariaLabel` only when the surface is a distinct region people need to find
+by name. With a label, the root receives `role="region"`; without one it remains
+a non-landmark grouping.
+
+Set `tabIndex={0}` to include the whole panel in the Tab order, or
+`tabIndex={-1}` for a programmatic focus target. Keyboard focus draws the
+standard focus ring. `outlined` keeps the same ring visible independently of
+focus, for example while the panel is a drop target. Give a focusable work area
+an `ariaLabel` when it is a distinct named region.
+
+Do not use `SunkenPanel` merely to add padding, as a substitute for pane
+header/content/footer anatomy, or around a child that already owns the same
+outer surface.
+
+For a lowered scrolling work area with Pane chrome, use
+[`Pane appearance="sunken"`](layout.md#lowered-work-surfaces). It paints the
+scroll viewport and empty space without adding a second scroller.
+
+## Public styling boundary
+
+Override the public properties at the composition boundary:
+
+- `--kui-sunken-panel-background`
+- `--kui-sunken-panel-foreground`
+- `--kui-sunken-panel-padding`
+- `--kui-sunken-panel-gap`
+- `--kui-sunken-panel-radius`
+
+The default background uses the shared translucent lowered-surface token.
+Nested panels composite naturally at every depth: darker in light mode and
+lighter in dark mode, without wrappers, depth classes, or per-instance token
+assignments. Pane and Web Awesome sunken surfaces use the same palette.
+See [Contextual transparency](./webawesome-theme.md#contextual-transparency).
+Keep ordinary composition on these defaults; public properties are theming
+escape hatches, not a reason to restyle each demo or nesting level.
+
+The public root class is `.kui-sunken-panel`. Prefer the properties above over
+styling descendants. The `square` shape deliberately overrides the radius
+property with zero; use `rounded` when customizing the radius token.

package/docs/surface-scaffold.md

@@ -0,0 +1,74 @@
+# 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`, or `fullscreen`), and independent
+`bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
+match Kerf's medium modal, 8px body, and 16px footer rhythm.
+
+The modal size presets have preferred widths of 400px, 560px, and 800px,
+respectively, before the viewport width cap. Set `preferredWidth` to a branded
+`CssLength` when the desktop shell needs another width. It takes precedence over
+`size`, while the viewport cap still applies. For example, 832px and 480px
+desktop preferences can share the same responsive dialog without changing its
+resource tracks or preview aspect sizing.
+
+### Modal viewport bounds
+
+`viewportGutter` accepts a branded `CssLength` from `@kerfjs/ui/css-values`.
+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.
+These options apply only to `presentation="modal"`; side sheets and fullscreen
+surfaces keep their own geometry.
+
+```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>;
+```
+
+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
+fits without scrolling; preview tracks, canvas aspect ratios and content sizing
+remain application-owned.
+
+Responsive policy is explicit application state: read `deviceClass()` during
+the render to choose the gutter, cap or presentation. For example use
+`viewportGutter={remify(device.value.handset ? 8 : 16)}` with `maxHeight="viewport"`.
+The scaffold introduces no hidden breakpoint or automatic fullscreen switch.
+An application can configure device-class breakpoints when its phone policy
+differs from the default. Prefer a typed cap such as `maxHeight={remify(640)}`
+when the modal should stop growing before the viewport bound.
+
+Treat a dialog body as a `List` by default. When its rows or sections own their
+standard list geometry, set `bodyInset="none"` so the dialog does not add a
+second inset. Bare prose is still a list child: wrap it in `ListInsetText` so its
+text edge receives the standard 8px margin + 1px transparent border + 8px
+padding and aligns with bordered siblings. Reserve `compact` or `comfortable`
+body insets for exceptional content that does not already have list/content-item
+geometry.
+
+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` 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. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.

package/docs/tab-navigator.md

@@ -0,0 +1,210 @@
+# 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).
+
+## Scroll divider
+
+The bar has no permanent top border. 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 it, 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.
+
+## 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/type-contracts.md

@@ -0,0 +1,135 @@
+# 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 `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                                                                                 |
+| `KUI-T006` | `TokenSearchEditorAttributes` 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-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); 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 `AppTab`, `FloatingToolbar`,
+  `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
+  `SegmentedControl`, `TokenSearchField`, 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 `AppTab`, `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 AppTab 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 `wireTokenSearchFields({ 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(...))`.
+- 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.