@kerfjs/ui 5.0.0-beta.23 → 5.0.0-beta.25

package/docs/accessibility.md

@@ -6,14 +6,47 @@ These are normative contracts for package components and consuming applications.
 
 - All controls have accessible names and visible `:focus-visible` treatment.
 - Decorative `LucideIcon` output is `aria-hidden`; pass `label` only when the SVG itself conveys meaning.
-- `ListItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. Selected rows keep the normal foreground over their brand-tinted fill so text retains WCAG AA contrast in light and dark themes. Its `trailing` content is dormant and must not contain controls. Its `rootAttributes` slot accepts only application `data-*` metadata and deliberately cannot emit `role="menuitem"` in isolation—a true ARIA menu must own arrow, Home/End, Escape, and focus behavior as one widget.
+- `ListItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. Selected rows keep the normal foreground over their brand-tinted fill so text retains WCAG AA contrast in light and dark themes. Its leading icon visual is 18px while the row retains its 44px minimum target; multiline icons align to the first text line. Its `trailing` content is dormant and must not contain controls. Its `rootAttributes` slot accepts only application `data-*` metadata and deliberately cannot emit `role="menuitem"` in isolation—a true ARIA menu must own arrow, Home/End, Escape, and focus behavior as one widget.
 - `ListHeader` owns action naming, disabled state, and disclosure `aria-expanded`. Toggle mode supplies one decorative 18px `DisclosureArrow` when `actionIcon` is omitted; it mirrors `expanded` while the native button's accessible name stays stable. The application must update that controlled state and reveal or hide real content. A valid `count` is visually rendered in an `aria-hidden` neutral pill while the required localized `countLabel` becomes part of the owning heading or disclosure button's accessible name; zero remains a real count. Its narrow `triggerAttributes` slot may describe a native popover or controlled-content relationship with `popoverTarget`, `popoverTargetAction`, `aria-controls`, and `aria-haspopup`; the application owns the target surface and its focus/dismissal behavior.
+- Dispose `wireTabBars` and `wireTokenSearchFields` with their owning view. Disposal cancels queued controlled-render focus restoration, so a torn-down view cannot reclaim focus from its successor.
 - In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; do not reduce the target to the visible icon.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
-- `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure.
+- `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
 - `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone. Its decorative option icons and value-dependent selected content remain present after controlled rerenders, so the visible choice does not silently lose its non-text cue.
 - `DisclosureArrow` is an 18px root-scaled decorative visual by default, not an interaction target. Its owning native control supplies a stable accessible name, pointer and keyboard interaction, and `aria-expanded`; multiple arrows keep independently controlled state. Consumers may override `--kui-disclosure-arrow-size` without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
+- `List` is layout-only and adds no `list` role. Children own their native or ARIA semantics. Give a scrollable List a bounded block size, avoid nested scroll owners, and keep focused children visible while scrolling.
+
+## Select
+
+Supply a visible `label`, or `ariaLabel` when the surrounding interface already
+provides visual context. A nonempty `label` takes precedence when both are
+supplied. Kerf forwards that name through Web Awesome's internal label contract;
+an `aria-label` on the custom-element host alone cannot name its shadow
+combobox. With `ariaLabel` alone, Kerf visually hides the internal label without
+adding height or spacing. This also applies to `renderSelected`: selected content
+stays separate from the control's stable accessible name. Applications do not
+need shadow-DOM patches or extra label styling.
+
+Use `presentation="toolbar-borderless"` with `size="compact"` inside a
+`ToolbarControlGroup`; set `focusRingOwner="group"` when that parent paints the
+composed focus ring. `selectedPresentation="icon-only"` hides only the visible
+selected label—the required `label` or `ariaLabel` still names the combobox.
+Navigation selects can use intrinsic `presentation="navigation"` plus
+`labelMaxWidth` for component-owned ellipsis. These props own the control's
+appearance; its parent continues to own outer placement.
+
+Use `hint` for persistent supporting text below the control; use
+`placeholderText` only for the empty value shown inside the closed control.
+Kerf passes hint text through Web Awesome's form-control contract, which renders
+the hint part and connects the shadow combobox to it with `aria-describedby`.
+Loading placeholders keep the same visible hint while replacing the interactive
+control with inert chrome.
+
+`tests/unit/components.test.tsx` covers name projection and visible/hidden label
+variants. `tests/browser/select-accessibility.spec.ts` verifies actual accessible
+names, unchanged unlabeled geometry, keyboard selection, controlled rerenders,
+native hint wiring, and wide/narrow presentation in Chromium, Firefox, and WebKit.
 
 ## ListActionRow
 
@@ -43,21 +76,21 @@ The handle exposes separator role, orientation, name, minimum, maximum, and curr
 
 The application owns persistence and collapsed/expanded policy. Keep the last expanded size outside the component and restore it when reopening. An optional `handleIcon` replaces only decorative dormant content; it must not contain controls or interactive roles because the separator remains the sole focus and interaction owner.
 
-## PanelHeader
+## Toolbar headings
 
-`PanelHeader` is a plain `Toolbar` heading. Its leading zone holds an optional
-icon (a normal bordered `ToolbarControlGroup`) and the title as extra-large
-`ToolbarText`, and the app's trailing controls go straight into the trailing
-zone. By default the title carries no native heading role, so for a **dialog or
-panel** the application connects `titleId` and an optional `summaryId` to the
-owning host through `aria-labelledby` and `aria-describedby`. For a **page or
-view** title, pass `headingLevel` (usually `1`): the title then exposes
+Compose panel, dialog, and page headings as a plain `Toolbar`. Its leading zone
+holds an optional icon `ToolbarControlGroup` and a direct extra-large
+`ToolbarText`; controls belong in a trailing `ToolbarControlGroup`. By default
+the title carries no native heading role, so for a **dialog or panel** the
+application connects the title id and optional supporting-copy id to the owning
+host through `aria-labelledby` and `aria-describedby`. For a **page or view**
+title, pass `headingLevel` (usually `1`) to `ToolbarText`: it then exposes
 `role="heading"` with a matching `aria-level`, giving the view a heading landmark
 so screen-reader heading navigation and "main heading" semantics work — the same
-role/level pair `ToolbarText` exposes when it is given `headingLevel` directly.
-Keep the levels meaningful and non-skipping within a view. Pass the trailing
+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.
+name. Keep supporting copy as app-owned content below the toolbar.
 
 ## FloatingToolbar
 
@@ -73,6 +106,13 @@ and — via `position` and `--kui-floating-toolbar-inset` — where it sits.
 
 `AppTab` renders one controlled tab. `TabBar` supplies the containing tab list,
 fixed leading/trailing regions, and a horizontally scrollable strip.
+Use `TabBar.presentation` for rail, segmented, or inspector chrome,
+`allocation="fill"` when peers should divide the strip, and
+`trailingPlacement="adjacent"` when an action belongs beside the final tab.
+`AppTab` provides compact 32px, segmented, truncating-label, and icon-only
+presentations. Icon-only tabs keep the required `name` as the tab button's
+accessible name while visually hiding the duplicate label. These props own
+component appearance only; the application still owns the bar's outer placement.
 `AppTab.rootAttributes` accepts application `data-*` metadata only; runtime
 filtering rejects roles plus case variants of component- or wiring-owned
 action, identity, selection, drag, drop, and component attributes. An optional
@@ -86,7 +126,8 @@ stops on drop/drag end/disposal, and does not change keyboard behavior. It
 returns a disposer.
 
 Arrow / Home / End follow the ARIA Tabs **automatic-activation** pattern by
-default: they move roving focus and select the focused tab. Pass
+default: they move roving focus and select the focused tab. If selection synchronously
+replaces the strip, focus returns to the replacement with the same bar and tab IDs. Pass
 `activation: 'manual'` (or set `data-tab-activation="manual"` on a strip via the
 `TabBar` `activation` prop, which overrides the option per bar) for
 **manual activation**: arrow keys move roving focus only and the user selects
@@ -123,7 +164,12 @@ and `placeTokenSearchCaret()` to restore a text caret without landing inside a
 chip. Call `wireTokenSearchFields()` once at a stable root so Enter submits
 without inserting a contenteditable line break and keyboard chip deletion
 restores focus plus the text-relative caret after controlled rendering replaces
-the editor; the editor still wraps text visually at its inline edge. Editable text is DOM-owned between token changes; a clear handler empties
+the editor. Restoration finishes after synchronous input listeners and before
+another keystroke; it does not wait for an animation frame that could overwrite
+a later selection. Select All + Backspace/Delete shares that replacement path
+and keeps the adopted expanded signal open while managed focus is enabled.
+Real outside focus, empty Escape, disposal, and removed fields retain their usual
+behavior. The editor still wraps text visually at its inline edge. Editable text is DOM-owned between token changes; a clear handler empties
 the editor's `textContent` before updating application state. Leading and
 trailing controls share the first text line's fixed vertical center and remain
 there as the editor wraps. In `collapsible` mode, the closed state is one named
@@ -147,6 +193,12 @@ originating `InputEvent` so a caller can gate on `inputType`/`data` — fires on
 `input`, letting a caller drop its own `input` listener; the application still
 owns query parsing and result-count/loading announcements.
 
+Managed clear captures the action before application handlers run, keeps the adopted
+expanded signal open during editor replacement, and focuses the current editor after
+rendering so typing can continue. The app still owns clearing query/tokens and emptying
+DOM-owned text. This focus step respects `manageFocus: false`, disposal, removed fields,
+and focus deliberately moved to another control; no app-level reopen callback is needed.
+
 ## CollapsiblePanel / sidebar
 
 `CollapsiblePanel` is a labeled `aside` region that is `aria-hidden` while

package/docs/catalog.md

@@ -109,9 +109,10 @@ const buttonPreview = (
 );
 ```
 
-The overlay selects every immediate child of a `CatalogExample` except the
-helper-generated label and note. It does not recursively promote a nested child
-to be the specimen. Outside an example row, it selects only top-level
+The overlay selects every immediate child of a `CatalogExample`; the helper
+marks its generated label and note so they are excluded automatically. It does
+not recursively promote a nested child to be the specimen. Outside an example
+row, it selects only top-level
 `[data-component]` roots in the canvas and ignores nested component descendants.
 These rules keep a row's label/group scaffolding out of the measurement and make
 the authored nesting determine exactly what is inspected.
@@ -138,15 +139,19 @@ Pass the conditional `geometryOverlay` boolean to `Catalog`, then call
 `wireCatalogGeometryOverlay(root)` once after the first render and retain its
 disposer alongside `wireCatalog`'s.
 
-| Overlay mark            | Meaning                                                                                              | It is not                                                                              |
-| ----------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| Orange translucent band | A positive computed margin on the selected specimen, after subtracting the helper's alignment inset. | Padding, gap, or empty content. Zero and negative margins are not drawn.               |
-| Quiet dashed outline    | The border-box outer bound of a selected specimen whose computed background is transparent.          | A real CSS border, focus ring, padding edge, or proof that the specimen owns its size. |
-
-The overlay does not visualize padding, borders, gaps, negative/zero margins,
-scroll overflow, hit targets, nested descendants, or geometry ownership. Inspect
-computed styles and the machine-readable `geometry` metadata for those facts.
-Opaque specimens do not receive the transparent-bound outline.
+| Overlay mark            | Meaning                                                                                              | It is not                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Orange translucent band | A positive computed margin on the selected specimen, after subtracting the helper's alignment inset. | Padding, gap, or empty content. Zero and negative margins are not drawn. |
+| Accent solid edge       | The selected specimen's computed border widths and radius, except `none`/`hidden` styles.            | A focus ring, outline, child border, or metadata ownership claim.        |
+| Quiet dashed outline    | The border-box bound of a transparent selected specimen with no visible border.                      | A real CSS border, padding edge, or proof that the specimen owns size.   |
+
+The overlay recomputes from live rendered styles when specimens resize, preview
+markup changes, theme/root attributes change, or loaded/inline stylesheets
+change. Component CSS is therefore the source of truth; do not duplicate margin
+or border values in demo data. The overlay does not visualize padding, gaps,
+negative/zero margins, scroll overflow, hit targets, or nested descendants.
+Inspect computed styles and the machine-readable `geometry` metadata for those
+facts. Opaque borderless specimens do not receive the dashed bound.
 
 ```tsx
 <Catalog

package/docs/collapsible-panel.md

@@ -20,6 +20,9 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
   the fixed-size content slides out via `transform` (composited, clipped) — never
   a per-frame width/height animation. The app owns the `collapsed` signal; `size`
   overrides the CSS default width/height.
+  Reusable shell policies are typed props: `separator`, `collapseMotion`,
+  `contentOverflow`, and `presentation`. A collapsed panel may also receive a
+  `restoreControl`, which Kerf places at the safe-area-aware `restorePosition`.
 - **`CollapsiblePanelToggle({ side, collapsed, action, panelId?, label? })`** and
   **`collapsiblePanelToggleIcon(side, collapsed)`** — the standard toggle
   affordance and its icon convention, so every sidebar reads the same: `PanelLeft*`
@@ -38,6 +41,10 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
     `deviceClass()` signal): the open panel floats over the content with a
     dismissable backdrop, Escape and backdrop-click collapse it, and Tab is trapped
     within the panel (the ARIA dialog pattern);
+  - accepts `compactPresentation: "hidden"` when a compact application replaces
+    the panel with different navigation instead of overlaying it;
+  - keeps compact overlays exclusive by default, collapsing another open panel
+    when a new one opens (`exclusiveCompact: false` opts out);
   - **persists** the collapsed state to `storage` (default `localStorage`) under
     `storageKey`, seeding the signal on wire-up.
 

package/docs/component-contract.md

@@ -193,6 +193,10 @@ an unlisted implementation class. Selectors such as `.kui-state-banner span`,
 private structure. If no prop, token, or cataloged class expresses a recurring
 need, request a supported hook instead of inferring one from rendered markup.
 
+`ListItem` renders its leading icon and nested SVG at a root-scaled 18px by
+default while retaining the row's 44px minimum interactive target. Multiline
+rows align that 18px visual with the first inherited text line.
+
 `DisclosureArrow` uses an 18px root-scaled visual by default. Override
 `--kui-disclosure-arrow-size` on the component or its containing scope when a
 consumer needs another size. Kerf `Select` uses a separate Web Awesome expand
@@ -210,7 +214,9 @@ glyph defaults to 18px through `--kui-list-header-action-icon-size`.
 
 `StateBanner` exposes instance-level `--kui-state-banner-background`,
 `--kui-state-banner-border`, `--kui-state-banner-foreground`,
-`--kui-state-banner-detail`, and action background variables. Its five built-in
+`--kui-state-banner-detail`, `--kui-state-banner-badge-background`,
+`--kui-state-banner-badge-foreground`, and action background variables. Its optional
+badge is a compact pill beside the title and follows the banner tone by default. Its five built-in
 tones can be rethemed globally with
 `--kui-state-banner-{tone}-{background|border|foreground}`. Toolbar control,
 segmented-control, app-tab, and tab-bar colors likewise use their public
@@ -231,6 +237,13 @@ header, one scrolling vertical `.kui-pane__content`, and an optional footer.
 Logical-edge separator lines are independently opt-in and default off.
 `@kerfjs/ui/layout.css` retains the pane roles and supplies the related content
 geometry classes.
+`List` is the corresponding layout-only vertical stack: its children stretch by
+default, while `gap`, `flex`, and `scrollable` opt into standard/custom spacing,
+flex growth, and vertical scroll ownership. `dividerSides` accepts canonical
+physical top/right/bottom/left combinations such as `tr` and `trbl`; the stack
+adds no list semantics, margin, or padding of its own. String props receive
+browser CSS, so use `gap="var(--kui-space-2xs)"` for the root-scaled 4px token or
+`gap="0.25rem"`; source-only `remify(4px)` is not valid at runtime.
 `.kui-content` gives major children 24px vertical separation.
 `.kui-content-item` gives one child 8px inline margin, a real 1px border,
 8px padding, and 12px corners; border and background may be transparent without
@@ -250,14 +263,11 @@ into the section label. Do not add padding to pane shells,
 double child-owned geometry with wrapper insets, or create competing scroll
 owners. The [layout contract](./layout.md) lists the public roles and tokens.
 
-`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading;
-it overrides no Toolbar styles. The leading zone holds an optional icon (a normal
-bordered `ToolbarControlGroup` given a brand fill with a matching border) and the
-title as extra-large `ToolbarText`, and the app's `actions` go straight into the
-trailing zone (typically as a `ToolbarControlGroup`). The icon group is omitted
-when no icon is passed. The optional summary is a separate row aligned below the
-title, so it cannot pull the icon group out of vertical alignment with the
-title and action row.
+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.
 
 `ValueTable` composes typed `ValueTableRow` entries. A row owns its `dt`/`dd`
 semantics and may receive a leading `SafeHtml` icon. Every row keeps 8px of