@kerfjs/ui 5.0.0-beta.104 → 5.0.0-beta.106

package/docs/accessibility.md

@@ -9,20 +9,20 @@ These are normative contracts for package components and consuming applications.
 - `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.
 - `ListItemLink` shares that row content and geometry but uses native anchor Enter behavior and requires `href`. It has no `action` or `pressed` state. `external` opens a new tab with `rel="noopener noreferrer"`; the default accessible name announces the new tab for a string label, so an explicit `accessibleLabel` should do the same. Disabled and loading links omit `href`, expose `aria-disabled`, and leave the tab order. Its trailing content remains dormant.
 - `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. Optional `badge` and `status` content can appear together and should each carry meaningful text. 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.
+- Dispose `wireTabBars` and `wireSearchFields` with their owning view. Disposal cancels queued controlled-render focus restoration, so a torn-down view cannot reclaim focus from its successor.
 - `wireNavStack` moves focus into every newly active top view and remembers the last focused descendant of each mounted view for pop restoration. Mark a preferred initial heading or control with `data-nav-focus` (and `tabindex="-1"` when it is not normally tabbable); otherwise the helper uses the first enabled focusable descendant, then a programmatically focusable view-container fallback.
 - 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` inside a fitted 36px hover square; a transparent hit layer extends the pointer target to at least 44 × 44 around that square without moving layout or enlarging the painted surface. Compact headers are 36px tall like the rest of the compact List family, so their action target is 44px wide and clamped to the 36px header height instead of reaching into a neighboring row. Do not reduce the target to the visible icon, and do not force the button itself to 44px.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
 - A busy `ToolbarControlGroup` makes its controls inert and exposes `aria-busy`; its `busyLabel` is announced by an adjacent status node outside the inert group. Clear `busy` when the operation finishes so the controls rejoin the focus order.
 - A bottom `Toolbar` uses `position="footer"` for footer semantics; top toolbars keep the default `header`. Workbench's main bottom toolbar sets this automatically.
-- Interactive `ContentItem` cards are keyboard reachable. Set `selectionMode="toggle"` for a pressed button, `selectionMode="single"` for an option inside a listbox, or `selectionMode="multiple"` for a selectable row with a gridcell that can contain native controls. Place multiple-mode rows inside a labeled `List` or `Grid` with `selectionMode="multiple"`; the app owns the selection set and range gestures. Wire `wireContentItems` once so Enter and Space on the card activate its delegated action without activating it from a nested control. Disabled cards expose `aria-disabled` and leave the Tab order.
+- Interactive `ContentItem` cards are keyboard reachable. Set `selectionMode="toggle"` for a pressed button, `selectionMode="single"` for an option inside a listbox, or `selectionMode="multiple"` for a selectable row with a gridcell that can contain native controls. Place multiple-mode rows inside a labeled `List` or `Grid` with `selectionMode="multiple"`; the app owns the selection set and range gestures. Wire `wireContentItems` once so Enter and Space on the card activate its delegated action without activating it from a nested control. The activation click mirrors the key's Shift, Ctrl, and Cmd state, so Shift+Enter or Shift+Space can extend a range and Cmd/Ctrl+Enter or Cmd/Ctrl+Space can toggle one item through the same click handler a pointer uses. Disabled cards expose `aria-disabled` and leave the Tab order.
 - An unlabeled `Skeleton` (including the value slots a component's `placeholder` prop renders) is decorative loading chrome: it is `aria-hidden`, conveys no information a user needs to act on, and is deliberately exempt from the WCAG 3:1 non-text-contrast target. Inside a solid `Badge` it stays subtle (about 2.1–4.4:1 in light, 2.4–2.8:1 in dark, depending on tone); `tests/browser/tone-contrast.spec.ts` holds those values as a regression floor rather than an accessibility threshold. Announce loading through a labeled `Skeleton`, `LoadingSpinner`, or `aria-busy` on the owning region, never through the skeleton's visibility.
 - `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.
 - A removable `Chip` has a native button with a specific `removeLabel`, such as "Remove Urgent tag". The button is absent for a plain chip and disabled for a disabled chip. Its leading `icon` is decorative; the visible label names the tag. `truncate` retains the full plain-text label as a native tooltip. Tag text remains visible because tone does not convey meaning alone. A link `Chip` (`href`) is a native anchor named by its visible label, with no remove button; `external` adds `target="_blank"`, `rel="noopener noreferrer"`, and an "(opens in new tab)" name suffix for a text label, and a disabled link chip drops `href`, sets `aria-disabled`, and leaves the tab order. `tone="inherit"` paints no fill, so its label keeps the surrounding text's contrast (a brand-loud bubble's white text included), and its focus ring is drawn in the surrounding foreground so it stays visible on a brand-colored surface. An action `Chip` (`action`) is one native `<button type="button">` with no nested control: its visible label names it unless `actionLabel` supplies a fuller name, which should contain that label ("Insert filter is:mine"). Enter and Space activate it, keyboard focus draws the focus ring (in the surrounding foreground for `tone="inherit"`), and a disabled action chip is a disabled button that leaves the tab order.
 - `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 resize it with the typed `size` prop 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 by default and adds no `list` role. With `selectionMode="multiple"` and a required `ariaLabel`, it becomes a multi-select grid for `ContentItem` rows. Give a scrollable List a bounded block size, avoid nested scroll owners, and keep focused children visible while scrolling.
+- `List` is layout-only by default and adds no `list` role. With `selectionMode="multiple"` and a required `ariaLabel`, it becomes a multi-select grid for `ContentItem` rows. With `wireContentItems` the grid is one Tab stop (roving `tabindex` on the last focused row, else the first selected, else the first enabled), kept across re-renders. Content that sits between rows but is not selectable (an activity group, a "messages skipped" divider) is a `ContentItem gridRow`: a `role="row"` with a `gridcell`, no `aria-selected`, and no Tab stop of its own; arrow keys skip it and its controls stay reachable by Tab. Give a scrollable List a bounded block size, avoid nested scroll owners, and keep focused children visible while scrolling.
 - `Grid` is layout-only by default. With `selectionMode="multiple"` and a required `ariaLabel`, it becomes a multi-select grid for `ContentItem` tiles; each tile remains a row with a gridcell, including when the CSS grid wraps.
 
 In a multi-select ContentItem grid, `wireContentItems` moves focus between
@@ -32,7 +32,9 @@ tiles on the same rendered line and Up/Down moves to the nearest tile in the
 adjacent rendered line; Home/End reaches the first/last enabled tile. The
 navigation reads live geometry, so responsive column changes need no rewiring.
 The application changes selection
-on card activation and handles its own Shift/Cmd range gestures.
+on card activation; `applySelection` and `selectionGesture` from
+`@kerfjs/ui/selection` give it the platform-normalized replace,
+Cmd/Ctrl-toggle, and Shift-range model.
 With delegated click actions, use `isContentItemActivation(event, card)` in the
 card's selection handler so a nested menu trigger or other control does not
 also select the card.
@@ -110,32 +112,30 @@ even when the selected content shows its own short text.
 
 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`.
-The accessible control is that shadow combobox, not the `wa-select` wrapper;
-inspect or test the element returned by the `combobox` role. Both the `hint`
-attribute used by Kerf and Web Awesome's explicit `hint` slot produce a computed
-accessible description in Chromium, Firefox, and WebKit, so applications do not
-need an `aria-description` mirror or a shadow-DOM patch.
+The hint renders below the control and is the trigger's `aria-description`. The
+accessible control is the light-DOM trigger button (`role="combobox"`), not the
+`kui-select` root; inspect or test the element returned by the `combobox` role.
 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.
-
-The explicit `@kerfjs/ui/select/register` import also installs the canonical
-Select lifecycle adapter. The latest open/close request owns animation completion
-and deferred option focus. A stale close cannot hide a reopened popup after
-resize; stale completion events are not emitted. Preventing `wa-show` or
-`wa-hide` retains the accepted closed/open state, and removal prevents deferred
-activation. Native option selection, keyboard behavior, dismissal listeners,
-and popup anchor placement remain with Web Awesome. Raw `wa-select` elements
-without the canonical `data-component="select"` marker are unchanged.
-`tests/unit/select-lifecycle.test.ts` and `animate-select-popup.test.ts` cover
-repeated and out-of-order completions, cancellation, instance isolation, and
-removal. `tests/browser/select-lifecycle.spec.ts` repeats animation/resize/reopen
+hint wiring, and wide/narrow presentation in Chromium, Firefox, and WebKit.
+
+The explicit `@kerfjs/ui/select/register` import defines the form-associated
+`kui-select` root and wires every Select in the document. The trigger opens the
+listbox (`role="listbox"`, `aria-multiselectable` when `multiple`) as a manual
+popover in the top layer, below the trigger and flipping above when short, with
+focus on the chosen option. In the listbox the arrow keys move and wrap,
+Home/End jump, typing a label's first letters moves to it, and Enter or Space
+chooses; a single Select then closes and returns focus to the trigger, while a
+multiple Select stays open. Escape closes and returns focus to the trigger; Tab
+and an outside press close it. Options are `role="option"` elements with
+`aria-selected` and, for a disabled choice, `aria-disabled`; the template
+renders them, so a re-render keeps them. `tests/unit/select-controller.test.tsx`
+covers the keyboard, choice, and form contracts;
+`tests/browser/select-lifecycle.spec.ts` repeats open/close/resize/reopen
 sequences at wide and narrow widths in Chromium, Firefox, and WebKit.
 
 ### Help tags on icon-only triggers
@@ -158,9 +158,13 @@ all three kinds, and any of `@kerfjs/ui/select/register`,
 `@kerfjs/ui/popup-menu/register`, or `@kerfjs/ui/help-tags/register` installs
 it (once per document, however many are imported). An application whose
 toolbars have icon-only buttons but no registered `Select` or `PopupMenu`
-imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip
-element. Pure `SafeHtml` rendering stays zero-JS: without an installer, nothing
-shows a tag.
+imports `@kerfjs/ui/help-tags/register`, which installs only the help tags.
+The tag is Kerf's own element (no Web Awesome): one `aria-hidden`,
+`popover="manual"` element in the top layer, placed 8px below its trigger
+(flipping above when short, kept 8px clear of the viewport edge), styled by a
+zero-specificity stylesheet the installer adopts so a theme can restyle it.
+Pure `SafeHtml` rendering stays zero-JS: without an installer, nothing shows a
+tag.
 
 - **Text.** The tag says what the accessible name says: a filter's name and
   chosen labels ("Filter by label: Bug, Docs", or "Filter by label" when none
@@ -200,7 +204,7 @@ visible text get no tag: their visible text already names them. A button that
 carries a native `title`, or that the application has already given a
 `wa-tooltip` `for` its `id`, keeps that and gets no second tag, so nothing is
 shown twice. Zero-JS components that name an icon control with a native `title`
-(the `ListHeader` action, the `AppTab` close button, the `TokenSearchField`
+(the `ListHeader` action, the `TabBarItem` close button, the `SearchField`
 reveal and clear buttons, and `SegmentedControl` choice titles) keep the
 browser's own tooltip, which needs no script; the installer deliberately skips
 them rather than stacking a second tag on the first. Icon-only buttons outside
@@ -213,43 +217,55 @@ Chromium.
 
 ## PopupMenu
 
-`PopupMenu` renders a Web Awesome dropdown, so the menu roles, arrow-key and
-typeahead navigation, Escape, and focus return to the trigger come from
-`wa-dropdown`. Kerf's part is the trigger's name. A Web Awesome button takes its
-name from its content and ignores an `aria-label` on the host, so an icon-only
-trigger requires `label`, which renders as visually hidden text inside the
-button; a trigger with visible `text` is named by that text. An icon-only
-trigger also shows its `label` as an `aria-hidden` help tag on hover and
-keyboard focus (see [Help tags on icon-only triggers](#help-tags-on-icon-only-triggers)).
-The open menu carries that same name. Web Awesome renders the `role="menu"`
-panel inside the dropdown's shadow root, where no ID reference can reach the
-trigger (the context anchor is `aria-hidden` light DOM, and a button trigger's
-real `<button>` sits in `wa-button`'s own shadow root). So `PopupMenu` renders
-the name it already knows (a context or icon-only `label`, or the visible
-`text`) as `data-menu-label` on the dropdown, and the register copies it to the
-panel as `aria-label` on first render and on every open. A submenu panel shares
-a shadow root with its parent item's label and is `aria-labelledby` it, so it
-is announced as, for example, "More Actions, menu".
-`tests/browser/popup-menu-accessible-name.spec.ts` finds each panel with
-`getByRole('menu', { name })` in Chromium, Firefox, and WebKit. Group headings
-render as the same uppercase group titles a grouped `Select` shows, and dividers
-are presentational. A keyboard-focused item is the menu's current row, painted
-with the Select's current-option fill rather than a second focus ring inside the
-open popup. A disabled item stays in the menu but cannot be
-chosen; disable the whole trigger only when every command is unavailable.
-Clicking outside dismisses a context `PopupMenu`, including one reopened while
-its previous hide animation is still finishing.
-Nested items use Web Awesome's submenu pointer and Left/Right arrow routing;
-headings and dividers can separate nested groups without becoming keyboard
-choices. A rapid ArrowDown or ArrowUp after opening a submenu keeps the chosen
-item focused when its show animation finishes. If a submenu is reopened during
-its close animation, it remains visible; pointer and ArrowRight actions also
-recover a submenu left hidden with an open state. Set `checked` to `true` or `false` for checkbox menu semantics; omit it
-for a plain command. `details` supplies optional
-trailing visual content without changing a command's accessible label. A
-`context` menu's invisible anchor is outside the accessibility tree and normal
-Tab order; opening the menu moves focus into its commands and Escape dismisses
-it. Keep a separate visible row action named even when it is disabled.
+`PopupMenu` is Kerf's own menu: a native trigger `<button>` and a `role="menu"`
+panel that opens as a manual popover in the top layer, wired by
+`@kerfjs/ui/popup-menu/register`. The trigger carries `aria-haspopup="menu"`
+and an `aria-expanded` that follows the menu. An icon-only trigger requires
+`label`, which renders as visually hidden text inside the button; a trigger
+with visible `text` is named by that text. An icon-only trigger also shows its
+`label` as an `aria-hidden` help tag on hover and keyboard focus (see
+[Help tags on icon-only triggers](#help-tags-on-icon-only-triggers)).
+The open menu carries that same name as its `aria-label` (a context or
+icon-only `label`, or the visible `text`), and each submenu panel is named by
+its parent item's label, so it is announced as, for example, "More Actions,
+menu". `tests/browser/popup-menu-accessible-name.spec.ts` finds each panel with
+`getByRole('menu', { name })` in Chromium, Firefox, and WebKit.
+
+Items are `menuitem` (or `menuitemcheckbox`, with `aria-checked`) buttons;
+a disabled item keeps `aria-disabled="true"`, stays in the menu, is skipped by
+the arrow keys, and cannot be chosen (its click never reaches the
+application's `data-action`). Disable the whole trigger only when every command
+is unavailable. A heading names the `role="group"` that holds the items under
+it and is itself hidden from assistive technology, so its words are announced
+once; dividers are `role="separator"`. A keyboard-focused item is the menu's
+current row, painted with the Select's current-option fill rather than a second
+focus ring inside the open popup.
+
+The keyboard follows the menu-button pattern. Enter, Space, or ArrowDown on the
+trigger opens the menu on its first item, and ArrowUp on its last. ArrowUp and
+ArrowDown move and wrap, Home and End jump, and typing the first letters of a
+label moves to it. Enter or Space chooses the current item; a choice closes the
+menu and returns focus to the trigger. ArrowRight opens a submenu on its first
+item and ArrowLeft returns to the parent item (mirrored right to left); a key
+pressed while a submenu is still fading in lands on the item it names. Escape
+closes the current level and returns focus to its opener, so an enclosing
+dialog stays open; Tab closes the menu and continues from the trigger. A press
+anywhere outside an open menu closes it, including a context menu opened by
+that same press.
+
+Hovering an item that has a submenu opens it. While a pointer-opened submenu
+is showing, a "safe triangle" from the pointer to the submenu's near edge keeps
+a diagonal move toward the submenu from closing it as the pointer crosses the
+parent's other rows; moving onto another item of the parent closes it after a
+short grace period. Set `checked` to `true` or `false` for checkbox menu
+semantics; omit it for a plain command. The application owns that state: a
+choice reports the state it asks for in the root's `kui-menu-select` event, and the
+menu shows the new state once the application renders it. `details` supplies
+optional trailing visual content without changing a command's accessible
+label. A `context` menu's invisible anchor is outside the accessibility tree
+and normal Tab order; opening the menu moves focus into its commands and Escape
+dismisses it. Keep a separate visible row action named even when it is
+disabled.
 
 ## ListActionRow
 
@@ -386,7 +402,7 @@ overlay's own floating toolbars stay.
 
 ## Tabs
 
-`AppTab` renders one controlled tab. `TabBar` supplies the containing tab list,
+`TabBarItem` renders one controlled tab. `TabBar` supplies the containing tab list,
 fixed leading/trailing/end regions, and a horizontally scrollable strip.
 Use `TabBar.presentation` for rail, segmented, or inspector chrome,
 `allocation="fill"` when peers should divide the strip, and
@@ -397,9 +413,8 @@ the shrinkable/scrolling tabs and pins `end` at the far edge. Leading,
 trailing, and end actions remain visible and do not shrink. The component owns
 that geometry; applications must not override its anatomy to create the split.
 `trailing` and `end` each accept one `ToolbarControlGroup` for grouped controls
-or one standalone `wa-button` when a primary action needs its own Web Awesome
-chrome. Do not add a wrapper or flex margins to position the action.
-`AppTab` provides compact 32px, segmented, truncating-label, and icon-only
+or one standalone `Button` when a primary action needs its own chrome. Do not add a wrapper or flex margins to position the action.
+`TabBarItem` 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. The default name
 overflow is an ellipsis; `nameOverflow="visible"` lets an inline loading
@@ -413,12 +428,12 @@ show placeholder content in its panel until loading completes; its close
 button is disabled and hidden and it is not draggable. A `placeholder` tab
 (unknown) is instead disabled, out of the tab order, and not draggable. These props own
 component appearance only; the application still owns the bar's outer placement.
-`AppTab.rootAttributes` accepts application `data-*` metadata only; runtime
+`TabBarItem.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
 `closeIcon` is decorative dormant content inside the already named close button
 and must not contain interactive descendants.
-The first `AppTab` can set `pinned` to stay at the inline start while its peers
+The first `TabBarItem` can set `pinned` to stay at the inline start while its peers
 scroll. It remains a normal tab within the same tablist and roving-focus order;
 focus and controlled selection reveal peers beyond the pinned tab. Pin only the
 leading tab of a strip.
@@ -477,20 +492,89 @@ focused radio, and the checked pill adds a second pixel of border so the
 selection does not rely on hue alone; forced-colors mode paints it with
 `Highlight`.
 
-With `multiple`, the group renders `role="group"` with the same naming, and
-each choice is a native `<input type="checkbox">` inside its pill. Every pill
-is its own Tab stop, Space toggles it, assistive technology reads its native
-checked state, and every checked box submits its value under `name`
-(`FormData.getAll(name)`). Native `required` on a checkbox demands that one
-box, so a multiple group takes no `required`; validate an "at least one" rule
-in the application. Every chip color is a theme token resolved through
+With `multiple: 'toggle'`, the group renders `role="group"` with the same
+naming, and each choice is a native `<input type="checkbox">` inside its pill.
+Every pill is its own Tab stop, Space toggles it, assistive technology reads
+its native checked state, and every checked box submits its value under
+`name` (`FormData.getAll(name)`). Native `required` on a checkbox demands that
+one box, so a multiple group takes no `required`; validate an "at least one"
+rule in the application.
+
+With `multiple: true`, the group is a named `role="listbox"` with
+`aria-multiselectable="true"` and `aria-orientation="horizontal"`, and each
+pill is a `role="option"` whose `aria-selected` reports its state and whose
+visible label is its name; a disabled chip is `aria-disabled`. The listbox is
+one Tab stop (roving `tabindex` on the first selected enabled chip). With
+`wireChoiceChips`: Left/Right (mirrored in right-to-left text), Up/Down,
+Home, and End move focus and select only that chip; Shift with them extends
+the range from the anchor; Cmd on Apple platforms or Ctrl elsewhere with them
+moves focus without changing the selection; Space toggles the focused chip
+and Shift+Space extends to it; Cmd/Ctrl+A selects every enabled chip. A
+click selects one chip, Cmd/Ctrl-click toggles one, and Shift-click extends.
+Hidden inputs submit each selected value under `name`. The focus ring follows
+`:focus-visible` on the option. Every chip color is a theme token resolved through
 `light-dark()`, so inside a dark appearance scope (`.wa-dark`, `.wa-invert`,
 or any `color-scheme: dark` ancestor) the pills, labels, checked tint, and
 focus ring read on inverse chrome without overrides.
 
-## Composer
+## TextField
+
+`TextField` renders a native `<input>` (or, with `multiline`, a `<textarea>`)
+inside one `<label>`, so a click anywhere on the field focuses it. The input is
+named explicitly — `aria-label` from `label`, whose visible text is
+`aria-hidden`, or from `ariaLabel` — so the clear button and the character
+count inside the label never join its name. `hint` and `error` are visible
+below the field and together form its `aria-description`; `error` also sets
+`aria-invalid="true"`, draws the box border in the danger color, and shows the
+message in the danger text color, so validity never relies on hue alone.
+`required`, `disabled`, `readOnly`, `maxLength`, `type`, and `autocomplete`
+are native attributes. A required field shows an `aria-hidden` asterisk after
+its label; the input itself reports `required`. The focus ring is drawn on the
+box around the input (`:focus-within`), 3px with a 1px offset like every Kerf
+control.
 
-`Composer`'s message field is a native `<textarea>` named by `label`
+`clearable` adds a native `<button>` named by `clearLabel` (default "Clear")
+after the input. It is hidden while the field is empty, is a normal Tab stop,
+and with `wireTextFields(root)` empties the field, dispatches bubbling `input`
+and `change` events as typing would, and returns focus to the field. A
+disabled or read-only field's clear button is disabled. `showCount` (with
+`maxLength`) shows a live `count / maxLength` beside the hint that
+`wireTextFields` keeps current. Compact text grows to 16px on coarse-pointer
+touch screens so focusing a field never zooms the page in iOS.
+
+## Checkbox, RadioGroup, and Switch
+
+Each control is a native input inside its `<label>`, positioned invisibly over
+an `aria-hidden` drawn box, circle, or track. The label names it, and pointer,
+keyboard, touch exploration, and form submission all reach the real input.
+Keyboard focus draws the 3px focus ring with a 1px offset on the drawn shape;
+forced-colors mode paints checked state with `Highlight`.
+
+- `Checkbox` is an `<input type="checkbox">`; Space toggles it. `hint` and
+  `error` form its `aria-description`, and `error` sets `aria-invalid="true"`
+  and a danger border. `indeterminate` renders a `data-indeterminate` marker
+  that `wireCheckboxes(root)` turns into the native `indeterminate` property
+  (the only way to set it), so assistive technology reports a mixed state; a
+  click clears it natively and the app's next render decides it again.
+- `RadioGroup` is a `<fieldset role="radiogroup">` named by its `<legend>`
+  (`label`) or `ariaLabel`. The browser owns the interaction: one Tab stop,
+  arrow keys move and select (skipping disabled choices), and the checked
+  radio submits its value under `name`. The group's `hint` and `error` form
+  its `aria-description`; `error` sets `aria-invalid` on the group, `required`
+  sets native `required` on each radio plus `aria-required` on the group, and a
+  choice's `hint` is that radio's `aria-description`.
+- `Switch` is an `<input type="checkbox" role="switch">`, so assistive
+  technology announces on and off; Space toggles it. Its `hint` is its
+  `aria-description`. The thumb's slide is skipped when reduced motion is
+  preferred. Use it only for a setting that applies immediately.
+
+Hints sit on the label's text column, not under the drawn shape. Safari's
+default Tab order skips checkboxes and radios as it does buttons; the
+controls keep that platform setting.
+
+## MessageComposer
+
+`MessageComposer`'s message field is a native `<textarea>` named by `label`
 (`aria-label`, title style). With an `id`, the `hint` renders with the id
 `<id>-hint` and becomes the field's `aria-describedby`; without an `id`, the
 hint is visible only. The field draws no border or outline of its own: the
@@ -500,7 +584,7 @@ outline). Each trailing action keeps its own name and focus ring. `disabled`
 disables the field only; the app disables its actions. Sending and
 announcing a sent message stay with the app.
 
-With `submitOnEnter` and `wireComposers`, the field carries
+With `submitOnEnter` and `wireMessageComposers`, the field carries
 `aria-keyshortcuts="Enter"`, so assistive technology announces the shortcut.
 Enter and Cmd/Ctrl+Enter activate the first trailing action, the same control
 a pointer or Tab-and-Space user reaches; Shift+Enter inserts a newline. An
@@ -512,20 +596,20 @@ disabled field, or a disabled, loading, or `aria-disabled` action sends
 nothing. A visible hint may also state the shortcut when the audience may not
 expect it.
 
-## TokenSearchField
+## SearchField
 
 Use `presentation="form-field"` when a structured search query sits beside
 Web Awesome form controls. It renders the visible `label` with the same inset
 and typography, an optional `hint`, and an optional `required` marker. The
 searchbox references the label and hint with `aria-labelledby` and
 `aria-describedby`, and `required` sets `aria-required`; the application
-validates the value before submission. `wireTokenSearchFields()` also moves
+validates the value before submission. `wireSearchFields()` also moves
 focus to the editor when the visible label is clicked. The field stands outside
-a Toolbar and fills the same inline space as a neighboring `wa-input`.
-Its control radius and required-marker color and offset follow Web Awesome's
-form-control tokens, so the two controls read as one form.
+a Toolbar and fills the same inline space as a neighboring `TextField`.
+Its control radius follows the shared `--kui-layout-rounded-radius`, so the two
+controls read as one form.
 
-`TokenSearchField` exposes the editable surface as a named `searchbox`. Each
+`SearchField` exposes the editable surface as a named `searchbox`. Each
 chip is atomic (`contenteditable="false"`) and contains separately named edit
 and remove buttons; the clear action is also named. A `trailingAction` is a
 named button whose `label` is also its tooltip; a help toggle sets `expanded`
@@ -533,10 +617,10 @@ named button whose `label` is also its tooltip; a help toggle sets `expanded`
 an on/off toggle sets `pressed` (`aria-pressed`). Disabled fields publish
 `aria-disabled` and stop editing without hiding the current expression. The
 application owns query parsing and must announce result-count or loading
-changes separately when that feedback is useful. Use `readTokenSearchField()`
+changes separately when that feedback is useful. Use `readSearchField()`
 to ignore the chip buttons' visible text when reading browser-edited content,
-and `placeTokenSearchCaret()` to restore a text caret without landing inside a
-chip. Call `wireTokenSearchFields()` once at a stable root so Enter submits
+and `placeSearchFieldCaret()` to restore a text caret without landing inside a
+chip. Call `wireSearchFields()` 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. Restoration finishes after synchronous input listeners and before
@@ -566,12 +650,12 @@ the complete component. Text or tokens keep the field expanded even when that
 transient state is false. Width animation is disabled under reduced motion.
 Clearing with ✕ follows where focus was when it was pressed: from inside the
 field (the editor, or ✕ reached by keyboard) the caret returns to the emptied
-editor; with focus elsewhere, `wireTokenSearchFields` leaves focus where it is
+editor; with focus elsewhere, `wireSearchFields` leaves focus where it is
 and collapses the emptied field, as it would on blur.
 
 When the field is composed with a caller-owned surface rendered outside it — a
 suggestions listbox, date picker, or help popover — mark that surface (or wrap
-it) with `data-token-search-keep-open`, or pass `collapsible.keepOpenOn(target)`,
+it) with `data-search-field-keep-open`, or pass `collapsible.keepOpenOn(target)`,
 so focus or pointer activation moving into it does not collapse an empty field.
 The helper preserves the pointer target when a browser omits
 `focusout.relatedTarget`, preventing the field or target from disappearing
@@ -579,7 +663,7 @@ between pointerdown and click. For an empty field losing focus during a pointer
 press, managed collapse waits until that press's click has dispatched (or the
 press ends without a click), then rechecks focus and content before closing.
 This keeps a shifting search row from moving the pressed control mid-click.
-`wireTokenSearchFields`
+`wireSearchFields`
 can also, opt-in via `keyboard`, own atomic-chip editing keys: from a collapsed
 caret with no selection, Backspace removes the token before the caret and Delete
 the token after it (reported through `onRemoveToken` for the app to apply to its
@@ -587,10 +671,10 @@ controlled state), and ArrowRight moves the caret past a trailing chip so typed
 text lands after it. An optional `onEdit({ id, editor, event })` — with the
 originating `InputEvent` so a caller can gate on `inputType`/`data` — fires on every editor
 `input`, letting a caller drop its own `input` listener; the application still
-owns query parsing and result-count/loading announcements. When the app's `onEdit` or `onRemoveToken` changes tokens and the controlled render replaces the focused editor, `wireTokenSearchFields` moves focus and caret to the replacement at the same mutation checkpoint (a caret at the end of the query stays at the end; any other caret keeps its place in the remaining text), so keys typed at full speed are not lost.
+owns query parsing and result-count/loading announcements. When the app's `onEdit` or `onRemoveToken` changes tokens and the controlled render replaces the focused editor, `wireSearchFields` moves focus and caret to the replacement at the same mutation checkpoint (a caret at the end of the query stays at the end; any other caret keeps its place in the remaining text), so keys typed at full speed are not lost.
 
-With a `createTokenSearchModel` passed to the field and registered in
-`wireTokenSearchFields(root, { models })`, grammar parsing, chips, clear/edit/
+With a `createSearchFieldModel` passed to the field and registered in
+`wireSearchFields(root, { models })`, grammar parsing, chips, clear/edit/
 remove actions, and suggestions are managed. Arrow Down moves from the editor
 to suggestions, arrow keys move between suggestions, Enter selects one, and
 Escape returns focus to the editor. The application still announces results
@@ -708,7 +792,7 @@ panel behind it. The same rule and fallbacks apply.
   controls take `--kui-color-text` there. An overlay `TabNavigator` bar's
   unselected labels lift halfway toward `--kui-color-text`, and its selected
   label mixes 40% of it into the brand color: the plain brand color measured
-  about 3.2:1 (light) over the worst case. `wa-dialog`'s own close button is an
+  about 3.2:1 (light) over the worst case. A `DialogSurface`'s close button is an
   icon, held to the 3:1 non-text bar, and measures about 3.8:1 (light) and
   4.1:1 (dark) over the raised material. Any other quiet copy you place in
   overlay chrome yourself has no such lift; keep it in the content.

package/docs/anchored-surface.md

@@ -41,12 +41,13 @@ openAnchoredSurfaceAt(
 );
 ```
 
-Pass `context` for a pointer opened inside a modal dialog. Inside a Web
-Awesome `wa-dialog` or `wa-drawer`, the surface stays interactive with no extra
-markup: `kerfjs/overlay` finds the modal `<dialog>` in the element's shadow
-root and hosts the surface in the element's light DOM, slotted inside the
-dialog. Dialogs opened by `kerfjs/overlay` get a host automatically too. For an
-app-owned native `<dialog>`, include
+Pass `context` for a pointer opened inside a modal dialog. Inside a
+`DialogSurface`, the surface stays interactive with no extra markup: the
+dialog renders the host `kerfjs/overlay` uses. Inside a Web Awesome
+`wa-dialog` or `wa-drawer`, `kerfjs/overlay` finds the modal `<dialog>` in the
+element's shadow root and hosts the surface in the element's light DOM,
+slotted inside the dialog. Dialogs opened by `kerfjs/overlay` get a host
+automatically too. For another app-owned native `<dialog>`, include
 `<div data-kerf-overlay-host data-morph-skip></div>` in the dialog markup so
 controls in the anchored surface stay interactive. For any other modal context,
 pass `container`: an element inside the open modal, where the surface is
@@ -79,7 +80,7 @@ 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
+components inside it (a `ListItem` mute row, a `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

package/docs/app-layouts.md

@@ -158,6 +158,34 @@ 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".
 
+### Compact chrome
+
+A `Pane` declares what its header and footer do when its container presents
+compactly, with `compactChrome: { header?, footer? }`:
+
+- `fixed` (default) keeps the chrome docked; it shrinks the content area.
+- `scroll` puts the chrome inline with the content: the pane scrolls as one
+  column, and a footer settles at the bottom of short content and scrolls
+  past long content. Chrome left `fixed` stays stuck to its edge.
+- `overlay` lays the chrome over the content's edge on the chrome material,
+  hidden until the app opens it with `compactChromeOpen` from a control the
+  person can reach (a toolbar button in the view).
+
+The Pane only declares the policy. Its container applies it in its compact
+presentation — a `NavStack` view (so a compact `SplitView` and
+`ListDetailDialog` too), a `TabNavigator` scene, a full-screen
+`DialogSurface` (so a compact `WorkbenchDialog`), or a `Workbench` at its
+compact width (448px or less) — and ignores it when roomy. Pass it through a
+view's or panel's `pane` configuration (`pane: { compactChrome: { footer:
+'scroll' } }`).
+
+Make open `overlay` chrome transient with `wirePaneChrome(root, { header,
+footer })` from `@kerfjs/ui/wire-pane-chrome`, passing the signals the Pane
+renders as `compactChromeOpen`: Escape, or a press that starts and ends outside
+the open chrome, sets its signal to false, and focus left inside the chrome
+returns to the control that opened it. The app's own toggle keeps working,
+because the dismissal is decided at the click.
+
 ## Decision matrix
 
 | Situation                                                                    | Layout                                                                                           | Device threshold                                                                                                                   |

package/docs/catalog.md

@@ -62,6 +62,15 @@ description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
   primary sections with a quieter treatment: `{ label, sections, collapsible?,
 expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
   `expanded` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
+  An optional `tagFilter: { tag, label, show }` adds a compact `Switch` at the
+  top of the open group that leaves out every entry carrying `tag` (and any
+  section it empties) until `show` is true. The active entry is always listed,
+  so a direct route still shows where it is. The app owns `show`; wire it with
+  `wireCatalog`'s `onToggleSecondaryFilter(show)` (action
+  `catalog-toggle-secondary-filter`, configurable through
+  `toggleSecondaryFilterAction`). Hidden entries are not rendered, so the
+  sidebar filter does not search them. The UX catalog uses it to hide
+  `Discouraged` Web Awesome entries by default.
 - Optional slots: `headerActions` (extra header controls), `sidebarFooter` (extra
   sidebar content), and `status` (a footer status line).
 - **`settings`** — the active entry's settings (variant and state controls for
@@ -73,7 +82,7 @@ expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
   `ListInsetControl` + `Select` (or other form components) so they share the
   pane's text column; the Catalog owns the pane, its title, and its toggle.
 
-The sidebar includes a `TokenSearchField` in its fixed header for every Catalog
+The sidebar includes a `SearchField` in its fixed header for every Catalog
 consumer, so the filter remains visible while the entries scroll. `wireCatalog`
 filters entry names and section headings as text is typed,
 ignoring case. A heading match shows all its entries; a matching secondary
@@ -206,9 +215,9 @@ entry's `tags` array.
 
 Use `align="glyph"` for a bare glyph/text specimen, `align="inline-control"`
 for a control whose own inline padding contributes about 8px, and
-`align="text-trigger"` for a Web Awesome dropdown's text trigger whose visible
-label needs an 8px inset (such as a plain `PopupMenu` trigger). The dropdown host
-has no layout box, so this inset applies to its button child. Use
+`align="text-trigger"` for a text menu trigger whose visible label needs an
+8px inset (such as a plain `PopupMenu` trigger), so its text lines up with the
+example label past the trigger's own padding and border. Use
 `align="none"` (the default) for a content item or composition that owns its
 geometry.
 
@@ -324,7 +333,7 @@ facts that source can prove without guessing at rendered intent:
 - every `@kerfjs/ui` import is a published package export and relative imports
   do not reach into `ui/src`;
 - focused demos have no relative stylesheet imports, inline style attributes,
-  or styling-only `demo-*`, `wa-demo-*`, and token-search class names;
+  or styling-only `demo-*`, `wa-demo-*`, and search-field class names;
 - demo JSX does not copy private `kui-catalog-*` structural classes;
 - recipe sources (checked by `npm run check:recipes` with the same shared
   analyzer) import no stylesheet other than public `@kerfjs/ui` CSS, set no