@kerfjs/ui 5.0.0-beta.97 → 5.0.0-beta.99

package/docs/anchored-surface.md

@@ -23,10 +23,15 @@ focusable anchor on close (or the previously focused element for a nonfocusable
 anchor). Pass `initialFocus: false` for read-only
 help that leaves focus on its trigger. Escape and an outside press dismiss it;
 `dismiss`, `onDismiss`, and `outsideIgnore` can customize that behavior.
-`placement` (`bottom` or `top`), `align` (`start` or `end`), and `gap` feed the
-shared `kerfjs/overlay` positioning core: it flips vertically when the other
-side fits, clamps horizontally, and follows scroll and resize. Content taller
-than the viewport scrolls inside the surface.
+`placement` (`bottom` or `top`), `align` (`start` or `end`), `gap`, and
+`viewportMargin` feed the shared `kerfjs/overlay` positioning core: it flips
+vertically when the other side fits, keeps the surface `viewportMargin` (default
+8px) inside the viewport edges, and follows scroll and resize. The surface fits
+its height to the room beside the anchor: when neither side holds it, it opens
+on the roomier side, caps its height to that room, and scrolls its content.
+The room is exposed to the content as `--kui-anchored-surface-available-height`
+and refreshed on every reposition, so a tall help surface fits beside a field on
+a phone without application media queries or `max-height` overrides.
 
 ```tsx
 openAnchoredSurfaceAt(
@@ -52,6 +57,43 @@ 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.
 
+## Dark tone for media chrome
+
+A popup anchored to dark media chrome (a volume control in a
+`ToolbarControlGroup tone="dark"` over a video or image preview) passes
+`tone: 'dark'`:
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
+The tone is the same loud, inverse tone as a dark `ToolbarControlGroup` or
+`ToolbarText`: dark beside a light page and light beside a dark one, so the
+popup matches the group that opened it. When the surface opens it takes the
+opposite of the anchor's color scheme (an explicit `color-scheme` on the anchor
+or an ancestor wins; `light dark` follows the user's preference), and the
+surface is marked `data-tone="dark"`. Nothing else changes. Every semantic
+color token is a `light-dark()` pair, so the surface fill, border, and shadow,
+and the text, borders, and focus rings of the Kerf UI and Web Awesome
+components inside it (a `ListItem` mute row, a `wa-slider`), resolve to the
+other side by inheritance. The content needs no tone props and no overrides.
+Text and focus rings keep WCAG AA in both page schemes. A theme that replaces a
+semantic token with a single color instead of a `light-dark()` pair opts that
+token out of the flip. While the surface is open it follows a live switch: an
+OS preference change, or a theme class, attribute, or inline `color-scheme`
+changed on the anchor or one of its ancestors, flips it to the new opposite
+(the content's own color transitions run, as the page's do). A scheme changed
+only by swapping a stylesheet is not observed. `openAnchoredSurfaceAt` reads the
+scheme from its `context` (the element under the pointer), so a region with its
+own `color-scheme` is honored; without a connected `context` it reads the modal
+scope's (or the page's).
+
+## Theming
+
 Override `--kui-anchored-surface-inset` and
 `--kui-anchored-surface-radius` for a theme; content can compose any Kerf UI
 components without the surface applying action policy. Prefer `PopupMenu` for

package/docs/app-layouts.md

@@ -41,8 +41,19 @@ the layouts handle the insets for you. There is nothing to configure:
   status bar or home indicator but its first and last items can always be
   scrolled clear.
 - **Interior edges get nothing.** A `Workbench` center next to an expanded rail,
-  a `SplitView` detail beside its list, or a `NavStack` view under its chrome is
-  not inset on that edge. Collapse the rail and the center picks up the edge.
+  a `SplitView` detail beside its list, or a `NavStack` view under its docked
+  chrome is not inset on that edge. Collapse the rail and the center picks up
+  the edge. A `NavStack` with `chromePresentation="overlay"` is the exception
+  by design: its views reach under the translucent chrome, and the measured
+  chrome height (top safe area included) becomes their block-start inset, so
+  content scrolls beneath the bar yet rests clear of it (see
+  [Navigation stack › Overlay chrome](nav-stack.md#overlay-chrome)). Its
+  `bottomToolbarPresentation="overlay"` does the same at the bottom: the
+  measured toolbar height (bottom safe area included) becomes the views'
+  block-end inset, so the last item rests just above the toolbar. A
+  `TabNavigator` with `barPresentation="overlay"` does the same for its tab
+  bar: the measured bar height (bottom safe area included) becomes the
+  scenes' block-end inset.
 - **No double inset.** Whichever region applies an inset clears it for its
   descendants. A layout region whose only child is a `Pane` or another layout
   lets that child own the insets. That child fills the region — a `Workbench`
@@ -130,6 +141,16 @@ single scrolling slot; the negative margins change only its inline reach. The
 [`Pane` UX catalog example](../ux-demo/demos/pane.tsx) shows both `deepInset`
 states with the same table component.
 
+### Scrolling beneath overlaying chrome
+
+`Pane.scrollClearance` (`"block-start"`, `"block-end"`, or `"both"`) lets the
+scrolling slot pass beneath chrome laid over the pane's edge, such as a
+`DialogSurface` floating footer over a filling Pane. The slot adds the
+inherited `--kui-scroll-clearance-block-*` context that the chrome publishes to
+its block padding and `scroll-padding`, alongside the safe-area and
+`deepInset` insets, so its first and last items still rest clear of the
+chrome. See `docs/layout.md` "Scroll clearance".
+
 ## Decision matrix
 
 | Situation                                                                    | Layout                                                                                           | Device threshold                                                                                                                   |

package/docs/apple-hig.md

@@ -12,6 +12,7 @@ Native Apple applications should use native platform controls and follow the Hum
 - Use one icon family and one metaphor per action. Directional icons may mirror in RTL; checkmarks, logos, and real-world objects do not.
 - Motion is brief, causal, and optional. Honor reduced-motion and reduced-transparency preferences; repeating indicators stop moving under reduced motion.
 - Writing is concise, specific, and action-led. Labels describe the result, not implementation details.
+- Capitalize by element type, consistently: names of commands, controls, views, and fields use title style; descriptions, messages, tooltips, and option text use sentence style. See [Writing interface copy](./writing.md#capitalization).
 
 ## Interaction
 

package/docs/catalog.md

@@ -85,7 +85,7 @@ action. Filtering does not change the selected
 entry or its preview.
 
 Per-entry `resources` render as "open in new tab" links in the footer, and
-`related` renders a "Related entries" `PopupMenu` in a `single`
+`related` renders a "Related Entries" `PopupMenu` in a `single`
 `ToolbarControlGroup` (grouped by each entry's `group`), so register its elements
 with `@kerfjs/ui/popup-menu/register` when you use it.
 
@@ -132,22 +132,74 @@ entry's `tags` array.
   Pass `label` when the stack needs an accessible name: the rendered `section`
   is then exposed as a named region. An unlabeled stack remains an ordinary
   grouping rather than adding an unnecessary landmark.
+  A stack holds a 736px reading measure by default; pass `width="full"` for
+  application-width compositions (boards, app shells, drawers, split views) so
+  the stack spans the stage like a `viewport.width: "full"` row instead of
+  clipping them.
 - `CatalogExample` is one row: optional generated `ListHeader` label, optional
   generated note, then one specimen or one intentionally coupled specimen
   cluster. Use one row per variant/state; do not hand-author the helper's private
-  classes.
+  classes. A supplied `label` also names the row's `section`, so each specimen
+  is a named region that assistive technology and
+  `getByRole("region", { name })` can address.
+- Example and stack labels are headings, so they use title style ("Heading
+  Identity Stays Whole", "Icon Trigger in a Toolbar Group"); the `note` that
+  explains a specimen stays sentence style. Write a label as a name, not a
+  sentence. See [Writing interface copy](./writing.md#capitalization);
+  `kerf-ui-doctor` reports a sentence-case label as `KUI-D040`.
 - Focused demos do not import local stylesheets, use inline `style`, or invent
   styling-only `demo-*` classes. Prefer a public Kerf component, then a Web
   Awesome surface when Kerf has no equivalent, then ordinary semantic HTML.
   Use `CatalogExample.viewport` for bounded specimen width, height, frame,
   surface, overflow, responsive visibility, and public custom-property values;
   keep those constraints catalog-owned instead of recreating a demo stylesheet.
+  Widths run `sidebar` (272px, a production rail, for sidebar-pane content),
+  `compact` (440px), `medium` (640px), and `wide` (864px), each capped at the
+  stage, plus `full`; `text` and `control` size a single label or control.
   Component heights run `short` (220px) through `tall` (360px); frame an app
   shell, whole-screen layout, or other application-sized recipe with
   `height: "app"` (592px), and give its root `fill` rather than a frame `Pane`.
   An app frame stands in for the screen: it is the containing block for
   screen-fixed chrome, so a compact `CollapsiblePanel` overlay, its backdrop,
   and restore controls dock to the frame's edges rather than the page's.
+  `minHeight` (`short`, `medium`, or `app` at 592px) is a floor the frame
+  may grow past rather than a definite height.
+- A top-layer specimen (a `popover`, a modal) that production anchors to a
+  named region with CSS anchor positioning anchors to the frame instead when
+  the frame takes that name: `viewport.anchorName` is a CSS dashed-ident
+  (`"--app-shell-main"`, validated; anything else throws) that becomes the
+  frame's `anchor-name`, so the specimen's own `position-anchor` rule resolves
+  to the frame. Do not wrap the specimen in a stage element to name it. Anchor
+  names are document-wide, so give each frame on a page its own. The frame
+  only names the anchor: the specimen keeps owning its placement, and as a
+  top-layer element it is not clipped by the frame or the stage. Chromium,
+  Firefox, and WebKit with CSS anchor positioning place it against the frame;
+  an engine without anchor positioning ignores the name, and the specimen
+  falls back to whatever placement its own CSS gives it there.
+- For a centered reading column inside a wider frame, set
+  `viewport.contentWidth` (`compact` 440px, `medium` 640px, or `wide` 864px,
+  each capped at the frame) and `contentAlign: "center"` (the default is
+  `start`). Each in-flow child fills that column; `[popover]` children keep
+  their own geometry. The column applies to block, `grid`, and `flex-column`
+  frames, and `contentAlign` does nothing without `contentWidth`.
+
+```tsx
+<CatalogExample
+  label="Request Docked to the Main Column"
+  viewport={{
+    layout: "flex-column",
+    width: "full",
+    minHeight: "app",
+    anchorName: "--app-shell-main",
+    contentWidth: "medium",
+    contentAlign: "center",
+  }}
+>
+  <Transcript />
+  <PermissionRequestPopup /> {/* its CSS: position-anchor: --app-shell-main */}
+</CatalogExample>
+```
+
 - The specimen is an immediate child of `CatalogExample`. A focused component
   row should place the component root there, without a decorative card or
   spacing wrapper. A composition row may place the composition root there.
@@ -165,7 +217,7 @@ import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
   <CatalogExampleStack
-    label="Button variants"
+    label="Button Variants"
     rootAttributes={{ "data-demo": "button" }}
   >
     <CatalogExample label="Icon" note="A bare glyph." align="glyph">
@@ -174,7 +226,7 @@ const buttonPreview = (
     <CatalogExample label="Control" align="inline-control">
       <SegmentedControl id="view" label="View" value="list" choices={choices} />
     </CatalogExample>
-    <CatalogExample label="Authoring note" note="Explain the specimen below.">
+    <CatalogExample label="Authoring Note" note="Explain the specimen below.">
       <p>Use the public helper contract.</p>
     </CatalogExample>
   </CatalogExampleStack>
@@ -361,23 +413,23 @@ const sections: CatalogSection[] = [
 const renderers: Record<string, () => SafeHtml> = {
   button: () => (
     <CatalogExampleStack
-      label="Button states"
+      label="Button States"
       rootAttributes={{ "data-demo": "button" }}
     >
       <CatalogExample label="Default" align="inline-control">
         <Button label="Save" />
       </CatalogExample>
-      <CatalogExample label="Authoring note" note="Explain the specimen below.">
+      <CatalogExample label="Authoring Note" note="Explain the specimen below.">
         <p>The application owns product copy and actions.</p>
       </CatalogExample>
     </CatalogExampleStack>
   ),
   "profile-form": () => (
     <CatalogExampleStack
-      label="Profile form composition"
+      label="Profile Form Composition"
       rootAttributes={{ "data-demo": "profile-form" }}
     >
-      <CatalogExample label="Complete composition">
+      <CatalogExample label="Complete Composition">
         <ProfileForm />
       </CatalogExample>
     </CatalogExampleStack>
@@ -493,7 +545,7 @@ revealCatalogEntry(app, initial, { block: "center" });
 
 ## UX Review capture
 
-On a local Vite dev or preview server the catalog can offer a **Capture region**
+On a local Vite dev or preview server the catalog can offer a **Capture Region**
 header link that starts a UX Review region screenshot, preset with the project
 and the active entry. Static hosting has no local project, so the link never
 appears there. Three pieces wire it:

package/docs/collapsible-panel.md

@@ -147,7 +147,9 @@ top toolbar over a `Pane`:
   place groups wherever the open panel needs them;
 - a `ToolbarControlGroup` marked `relocateOnCollapse` stays available in the
   work area when the panel closes; the standard `toggle: { action, name,
-showLabel?, hideLabel? }` is always the final group.
+showLabel?, hideLabel? }` is always the final group. Give `name` as the
+  panel's title-style name ("Navigator"), which labels the toggle group and
+  completes "Show Navigator" / "Hide Navigator".
 
 Busy groups keep their inert control, spinner, and adjacent live status together
 when relocated. Clearing `busy` restores the same action in its current toolbar;
@@ -166,7 +168,8 @@ divider of its own unless `dividerSides` says so. The `Pane` under it draws
 the line under the toolbar only while its content is scrolled (see
 [Scroll dividers](./layout.md#scroll-dividers)), and takes the panel's `pane`
 (`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
-`safeAreaEdges`, `chromeDividers`) — for example `{ contentElement: "nav",
+`safeAreaEdges`, `chromeDividers`, `appearance`, `deepInset`,
+`scrollClearance`, `headerPresentation`, `tabIndex`, `outlined`) — for example `{ contentElement: "nav",
 contentLabel: "Sections" }` for a navigation rail. An omitted or `undefined`
 field keeps the `Pane` default; without a `toolbar` there is no `Pane`, so
 `pane` is ignored.
@@ -187,8 +190,8 @@ inert; avoid duplicate `id` attributes on marked groups.
 const toolbar: CollapsiblePanelToolbar = {
   label: "Navigator",
   leading: <NewFileGroup />,
-  trailing: <ToolbarControlGroup relocateOnCollapse label="Search files"><SearchButton /></ToolbarControlGroup>,
-  toggle: { action: "toggle-nav", name: "navigator" },
+  trailing: <ToolbarControlGroup relocateOnCollapse label="Search Files"><SearchButton /></ToolbarControlGroup>,
+  toggle: { action: "toggle-nav", name: "Navigator" },
 };
 
 <Row fill gap="none">
@@ -307,7 +310,7 @@ mount(app, () => (
           side="left"
           collapsed
           action="toggle-nav"
-          label="Show navigator"
+          label="Show Navigator"
         />
       )}
       {/* content */}
@@ -362,7 +365,7 @@ sizes, content, and any per-project persistence — exactly as with the other la
 
 ## Recipe and coverage
 
-The catalog ships a runnable **Collapsible sidebar** recipe — a left rail and a
+The catalog ships a runnable **Collapsible Sidebar** recipe — a left rail and a
 bottom drawer with the standard toggles, the compact overlay, and per-panel
 persistence: [open it](../ux-demo/?component=recipe-collapsible-sidebar) or read
 [`recipes.md`](recipes.md#collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx).

package/docs/component-contract.md

@@ -89,8 +89,12 @@ only cataloged `descendantElements` and composed JSX evidence.
 An entry's optional `cssValueProps` makes CSS-adjacent prop grammar equally
 machine-evaluable. Each path records the property grammar, finite shorthands,
 canonical versus exceptional spacing choices, standalone and expression-only
-helpers, raw/unsafe policy, and serialization examples. Nested paths use the
-bounded `items[].property` form. Consumer catalogs can publish the same facts;
+helpers, raw/unsafe policy, and serialization examples. Nested paths are
+dot-separated object members, each optionally suffixed with `[]` to visit
+every array element: `items[].property` for a value inside each array item,
+`iconTile.color` for a member of an object-valued prop. A member that is not a
+literal object or array (a tone string such as `iconTile="brand"`, a variable)
+is skipped rather than guessed. Consumer catalogs can publish the same facts;
 ESLint, `kerf-ui-analyze`, and `kerf-ui-doctor` then issue the same stable
 `KUI-L013`–`KUI-L017` feedback for application and third-party components.
 
@@ -246,10 +250,10 @@ product that genuinely needs one of these elements records a narrow `KUI-L301`
 profile exception for the file that renders it.
 
 Catalog detail footers use one standard resource vocabulary and order. Build
-them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo source`
-first, optional `Component source` and `Design template`, then `Guidance`.
+them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo Source`
+first, optional `Component Source` and `Design Template`, then `Guidance`.
 Third-party entries use the typed `integrationGuidance` kind, which renders
-`Integration guidance`, and omit `Component source` when the implementation is
+`Integration Guidance`, and omit `Component Source` when the implementation is
 not owned by the catalog's project. Prefer these semantic kinds over local labels
 such as “View source” or “Read UI guidance”; the helper makes that convention a
 compile-time choice while still returning ordinary `CatalogResource[]` values.
@@ -333,6 +337,8 @@ visual anchor.
 
 `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
 
+`ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
+
 ### Public CSS anatomy
 
 The `publicClasses` array on each entry in
@@ -396,7 +402,12 @@ The documented exceptions live with their reasons in
 check, so the list only shrinks. The layout regions' inherited edge-inset
 context (`--kui-edge-inset-*` handed to a sole Pane or layout child and cleared
 for any other content, and a Toolbar clearing it for its zones) is the one
-design exception; the others name the open fix ticket.
+design exception; the others name the open fix ticket. The scroll-clearance
+context (`--kui-scroll-clearance-block-*`) needs no exception: overlaying
+chrome publishes it on its own element (a `DialogSurface` on its dialog body,
+a `Pane` overlay header, through `wireScrollDividers`, on its own Pane root).
+A scroll owner reads it only through its own `scrollClearance` prop, or, for an
+overlay-header Pane's content, through its own `headerPresentation`.
 
 Applications and component packages built on the package follow the same
 rules, and the downstream tools enforce them against the composition catalog
@@ -623,11 +634,19 @@ own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
 `PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
 `PopupMenu` and a `Select` draw one popup: the same caret that turns to face the
 open popup, fade-in surface, surface inset, row height and padding, current-row
-fill, and group titles, all read from one private popup-choice contract in
-`foundation.css`. Checkbox items reserve a check column; plain commands start
-at the checkmark's leading edge, beside the group title rather than the
-farther-in Select option label. Checked submenu items keep their checkmark and
-label inside the submenu surface. Compact mixed controls retain the standard
+fill, group titles, and scroll cue, all read from one private popup-choice
+contract in `foundation.css`. A capped popup that scrolls (a long listbox, a
+menu, or a phone submenu) shows a soft shadow along each edge with more
+choices beyond it, so overlay scrollbars never leave it looking complete; the
+cue is CSS-only, appears only toward hidden rows, and a popup whose choices
+all fit draws none. Checkbox items reserve a check column, and so does every
+plain command in a level (the top menu or one submenu) that holds a checkbox
+item, through an `aria-hidden` icon-slot spacer, so check, icon, and label
+columns align across the level. A level without a checkbox item keeps the
+compact start: plain commands begin at the checkmark's leading edge, beside the
+group title rather than the farther-in Select option label. Checked submenu
+items keep their checkmark inside the submenu surface with the same check-column
+advance as the top level. Compact mixed controls retain the standard
 item padding, omit an internal separator, and let the raised selected item paint
 over the outer border instead of shrinking to an inset highlight. The Web
 Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
@@ -739,7 +758,12 @@ propagating before the window, or a press without a click, collapses in the
 next task instead.
 `TokenSearchField.trailingAction` supplies an icon, accessible `label`, delegated
 `action`, and optional `id`; the field renders a 24px wide button that fills its
-34px line slot, including the hit target, disabled state, hover, and focus ring.
+34px line slot (32px in `toolbar-group`), including the hit target, disabled
+state, hover, focus ring, and the clear button's radius in each presentation.
+`expanded` renders `aria-expanded` and `pressed` renders `aria-pressed` (one or
+the other, never both); either `true` state keeps the hover fill at full text
+strength. `controls` and `haspopup` render `aria-controls` and `aria-haspopup`,
+and `attributes` carries domain `data-*` metadata but never `data-action`.
 Use `trailing` for passive content. The two props are mutually exclusive.
 For a collapsible search in a stretched Toolbar center, `fill` lets the expanded
 field and its enclosing search `ToolbarControlGroup` consume the available width;
@@ -782,7 +806,16 @@ When a leading AppTab is pinned, the leading scroll divider appears at that
 tab's trailing edge while peer tabs scroll beneath it, including in RTL.
 With `snapTabs`, `wireTabBars` measures the pinned tab and settles peers at
 whole-tab starts after scroll and selection changes, reserving end room so the
-last peer can align there. The application still owns selection and tab order.
+last peer can align there. That room is scrollable content after the last tab,
+inside the strip, so it lengthens the scroll range without widening the strip:
+the strip still shrinks to its allocation, and `trailing` and `end` stay inside
+the bar. The room is still in-flow content, so it counts toward the strip's
+content-based flex basis: when another zone also shrinks (a trailing zone
+given `--kui-tab-bar-trailing-flex: 0 1 auto` with shrinkable content), the
+strip keeps a proportionally larger share. The share converges within a few
+frames and never pushes `trailing` or `end` out of the bar; keep the trailing
+zone non-shrinking with `snapTabs` to avoid it. The application still owns
+selection and tab order.
 ResizeObserver notifications coalesce snap measurements into the next animation
 frame, so inset writes cannot resize the observed strip during observer delivery.
 `wireTabBars` watches the whole root it is given, but a mutation re-measures only