@kerfjs/ui 5.0.0-beta.103 → 5.0.0-beta.105

package/ai/components/popup-menu.md

@@ -6,11 +6,12 @@
 
 ## When to use
 
-A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
+A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, drawn by Kerf as a native menu in the top layer.
 
 - Offer a short list of commands behind one trigger, such as a toolbar sort or More menu.
 - Group related commands under headings and dividers in one popup.
 - Nest decisions under a parent command, show checked or trailing choice state, or open a context menu at pointer coordinates.
+- Make a status Badge the trigger of a menu (a ticket status with a nested phase submenu): pass triggerContent with the Badge and label for the name, instead of wrapping the Badge in an application button.
 
 **Not when:**
 
@@ -28,7 +29,7 @@ A typed action menu with nested choices, selected state, and optional pointer-an
 - CSS: the browser build of `@kerfjs/ui/popup-menu` pulls its CSS automatically; import `@kerfjs/ui/popup-menu.css` manually only without the `browser` export condition.
 - Theme CSS: import `@kerfjs/ui/webawesome.css` once.
 - Registration: import `@kerfjs/ui/popup-menu/register` once (a side effect).
-- Declared side effects: browser-condition-css, custom-element-registration.
+- Declared side effects: browser-condition-css, document-listeners, custom-element-registration.
 
 ## Props
 
@@ -47,17 +48,18 @@ Exact prop names and types: [`@kerfjs/ui/popup-menu`](../public-api-signatures-v
 - danger tone and disabled reasons
 - context trigger with a rendered anchor point and a zero-footprint anchor host
 - placement
+- triggerContent: app content such as a Badge as the whole trigger, a bare button named by label with a pill focus ring
 
 ## Composition
 
 - Parents: any.
 - Contexts: `application-ui`.
 - Children: unrestricted.
-- Built from: [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md), [Button](./wa-button.md), [Divider](./wa-divider.md).
+- Built from: [LucideIcon](./lucide-icon.md), [Tooltip](./wa-tooltip.md).
 
 ## State and wiring
 
-**The app owns:** commands and their delegated actions; which items are enabled; reactions to the menu opening or closing; contextmenu event handling and identification of the menu root when using a pointer-anchored context menu.
+**The app owns:** commands and their delegated actions; which items are enabled; the checked state of checkbox choices, which the menu reports as requested in its kui-menu-select event; reactions to the menu opening or closing; contextmenu event handling and identification of the menu root when using a pointer-anchored context menu.
 
 No wiring helper.
 
@@ -67,8 +69,9 @@ Margin: none · border: child · padding: child (layout role: controls). `self`
 
 ## Accessibility
 
-- An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. The open menu takes the trigger's name (the context or icon-only label, or the visible text), and each submenu takes its parent item's label, so a screen reader announces a named menu and getByRole('menu', { name }) finds it. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.
-- Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
+- The trigger is a native button with aria-haspopup="menu" and aria-expanded; an icon-only trigger requires label, rendered as visually hidden text inside the button, and a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. The open menu (role="menu") takes the trigger's name, each submenu takes its parent item's label, and a heading names the role="group" that holds its items, so a screen reader announces named menus and getByRole('menu', { name }) finds them. Items are menuitem or menuitemcheckbox buttons with aria-checked and aria-disabled.
+- Keyboard: Enter, Space, or ArrowDown on the trigger opens on the first item (ArrowUp on the last); ArrowUp/ArrowDown move and wrap past disabled items, Home/End jump, and typing a label's first letters moves to it; Enter or Space chooses; ArrowRight opens a submenu on its first item and ArrowLeft returns to the parent item (mirrored right to left); Escape closes the current level and returns focus to its opener; Tab closes the menu and continues from the trigger.
+- Once registered, an icon-only trigger shows its label as an aria-hidden help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
 
 ## Usage examples
 
@@ -158,14 +161,14 @@ row.addEventListener('contextmenu', (event) => {
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-popup-menu`, `kui-popup-menu__label`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-popup-menu`, `kui-popup-menu__trigger`, `kui-popup-menu__label`, `kui-popup-menu__menu`, `kui-popup-menu__item`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor`.
 
-Never put `kui-popup-menu`, `kui-popup-menu__label`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor` on an element you write; render `PopupMenu` instead (`KUI-L103`).
+Never put `kui-popup-menu`, `kui-popup-menu__trigger`, `kui-popup-menu__label`, `kui-popup-menu__menu`, `kui-popup-menu__item`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor` on an element you write; render `PopupMenu` instead (`KUI-L103`).
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 
 ## Related
 
-- Components: [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md), [Button](./wa-button.md), [Divider](./wa-divider.md), [Select](./select.md).
+- Components: [LucideIcon](./lucide-icon.md), [Tooltip](./wa-tooltip.md), [Select](./select.md), [Dropdown](./wa-dropdown.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#popup-menu-migration`](../../docs/component-selection.md#popup-menu-migration).
 - UX catalog route: `?component=popup-menu`.

package/ai/components/progress-bar.md

@@ -0,0 +1,82 @@
+# ProgressBar
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:progress-bar` · Kerf UI · component · Feedback
+
+A linear progress indicator on the native progress element: determinate value of max or an indeterminate sweep, a visible label or ariaLabel, an optional value or valueText readout, brand or status tones, and a default or compact track.
+
+## When to use
+
+Show how far a measurable task has gone (an upload, a migration, a quota) or that work of unknown size is under way.
+
+- A task reports measurable progress (files uploaded, steps completed, quota used): pass value and max, a label, and showValue or valueText for the readout.
+- Work of unknown length is under way and a full-width indicator fits: omit value for the indeterminate sweep.
+
+**Not when:**
+
+- Do not use it for a small inline busy state; use LoadingSpinner or an indeterminate ProgressRing.
+- Do not use it for a scale reading that is not progress (a rating, a level); use a native meter.
+- Do not use wa-progress-bar.
+
+**Alternatives:**
+
+- [ProgressRing](./progress-ring.md) (nearest) — Use a ProgressRing where a bar does not fit, inline in a row or toolbar.
+- [LoadingSpinner](./loading-spinner.md) (nearest) — Use a LoadingSpinner for a brief busy state with no measurable progress.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/progress-bar` — exports `ProgressBar`, `ProgressBarProps`, `ProgressBarSize`, `ProgressBarRootAttributes`, `ProgressTone`.
+- CSS: the browser build of `@kerfjs/ui/progress-bar` pulls its CSS automatically; import `@kerfjs/ui/progress-bar.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/progress-bar`](../public-api-signatures-v1.md#kerfjsuiprogress-bar) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- determinate with a label and value readout
+- indeterminate sweep
+- brand, success, warning, or danger tone
+- default 6px or compact 4px track
+- ariaLabel without a visible label
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the value, max, and valueText; the label or ariaLabel; the tone and size.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- It fills the available width with the shared block-content inset (a transparent 1px border and 8px padding); the label row sits 4px above the track.
+
+## Accessibility
+
+- The native progress element is the progressbar: a visible label names it through aria-labelledby (or ariaLabel without one), and valueText replaces the spoken percentage.
+- The indeterminate sweep holds still under prefers-reduced-motion or the static-effects switch; forced colors draw a CanvasText-bordered track with a Highlight fill.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-progress-bar`, `kui-progress-bar__header`, `kui-progress-bar__label`, `kui-progress-bar__value`, `kui-progress-bar__track`.
+
+Never put `kui-progress-bar`, `kui-progress-bar__header`, `kui-progress-bar__label`, `kui-progress-bar__value`, `kui-progress-bar__track` on an element you write; render `ProgressBar` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ProgressRing](./progress-ring.md), [LoadingSpinner](./loading-spinner.md).
+- Docs: [`docs/progress.md`](../../docs/progress.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=progress-bar`.

package/ai/components/progress-ring.md

@@ -0,0 +1,80 @@
+# ProgressRing
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:progress-ring` · Kerf UI · component · Feedback
+
+A circular progress indicator: an SVG track and arc, determinate (filling clockwise from the top) or an indeterminate spinning arc, in small, medium, and large sizes to sit inline in text, a row, or a toolbar, as a named progressbar.
+
+## When to use
+
+Show compact progress (a claim's time remaining, a per-row upload) where a bar does not fit.
+
+- Progress belongs beside an item in a row, a toolbar, or a line of text: pass value and max, a label, and valueText for speech.
+- A compact indicator of work of unknown length: omit value for the spinning arc.
+
+**Not when:**
+
+- Do not use it where a full-width readout fits and the amount matters; use ProgressBar.
+- Do not use wa-progress-ring.
+
+**Alternatives:**
+
+- [ProgressBar](./progress-bar.md) (nearest) — Use a ProgressBar where a full-width bar with a label row fits.
+- [LoadingSpinner](./loading-spinner.md) (nearest) — Use a LoadingSpinner for a brief busy glyph inside a control.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/progress-ring` — exports `ProgressRing`, `ProgressRingProps`, `ProgressRingSize`, `ProgressRingRootAttributes`, `ProgressTone`.
+- CSS: the browser build of `@kerfjs/ui/progress-ring` pulls its CSS automatically; import `@kerfjs/ui/progress-ring.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/progress-ring`](../public-api-signatures-v1.md#kerfjsuiprogress-ring) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- determinate arc
+- indeterminate spinning arc
+- small (16px), medium (24px), or large (40px)
+- brand, success, warning, or danger tone
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the value, max, and valueText; the label; the tone and size.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Its box is exactly its diameter, so it aligns with icons of the same size.
+
+## Accessibility
+
+- It is role progressbar named by label, with aria-valuenow as a percentage (or valueText); the SVG is decorative.
+- The spin holds still under prefers-reduced-motion or the static-effects switch; forced colors draw a GrayText track and a Highlight arc.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-progress-ring`, `kui-progress-ring__track`, `kui-progress-ring__arc`.
+
+Never put `kui-progress-ring`, `kui-progress-ring__track`, `kui-progress-ring__arc` on an element you write; render `ProgressRing` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ProgressBar](./progress-bar.md), [LoadingSpinner](./loading-spinner.md).
+- Docs: [`docs/progress.md`](../../docs/progress.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=progress-ring`.

package/ai/components/radio-group.md

@@ -0,0 +1,88 @@
+# RadioGroup
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:radio-group` · Kerf UI · component · Controls
+
+A native fieldset of radios, each drawn as a Kerf circle beside its label, with the group label above, per-choice hints, and hint and error text below, stacked or wrapping.
+
+## When to use
+
+Choose exactly one of a few options that should stay visible with room for a label and hint each, with native keyboard behavior and form participation.
+
+- A form asks for one of two to about six options that people should compare at a glance, each with a readable label and an optional hint.
+
+**Not when:**
+
+- Do not use for many options or a compact toolbar value; use Select.
+- Do not use to switch a view; use SegmentedControl.
+- Do not use for chip-styled or color choices; use ChoiceChips.
+
+**Alternatives:**
+
+- [Radio Group](./wa-radio-group.md) (prefer-over)
+- [Radio](./wa-radio.md) (prefer-over)
+- [Select](./select.md) (nearest) — Use Select for a long list.
+- [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips for wrapping pill choices.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/radio-group` — exports `RadioGroup`.
+- CSS: the browser build of `@kerfjs/ui/radio-group` pulls its CSS automatically; import `@kerfjs/ui/radio-group.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/radio-group`](../public-api-signatures-v1.md#kerfjsuiradio-group) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- vertical or horizontal
+- per-choice hint
+- disabled choice
+- whole group disabled
+- hint
+- error
+- required
+- default or compact size
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** value; choices and their copy; validation and error copy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The label and hint sit on the text column (1px + 8px); the choices sit on the 8px control column, 12px apart.
+
+## Accessibility
+
+- A native \<fieldset role="radiogroup"> named by its legend (label) or ariaLabel; each choice is a native radio inside its \<label>, invisibly over the drawn circle. The browser owns the interaction: one Tab stop, arrow keys move and select, and the checked radio submits its value under name.
+- The group's hint and error form its aria-description; an error sets aria-invalid on the group and the danger border on each circle. required sets each radio's native required and aria-required on the group. A choice's hint is that radio's aria-description.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-radio-group`, `kui-radio-group__label`, `kui-radio-group__choices`, `kui-radio-group__choice`, `kui-radio-group__row`, `kui-radio-group__control`, `kui-radio-group__input`, `kui-radio-group__circle`, `kui-radio-group__choice-label`, `kui-radio-group__choice-hint`, `kui-radio-group__hint`, `kui-radio-group__error`.
+
+Never put `kui-radio-group`, `kui-radio-group__label`, `kui-radio-group__choices`, `kui-radio-group__choice`, `kui-radio-group__row`, `kui-radio-group__control`, `kui-radio-group__input`, `kui-radio-group__circle`, `kui-radio-group__choice-label`, `kui-radio-group__choice-hint`, `kui-radio-group__hint`, `kui-radio-group__error` on an element you write; render `RadioGroup` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-quiet`, `--kui-layout-item-padding`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Radio Group](./wa-radio-group.md), [Radio](./wa-radio.md), [Select](./select.md), [ChoiceChips](./choice-chips.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=radio-group`.

package/ai/components/recipe-list-detail-dialog.md

@@ -6,7 +6,7 @@
 
 ## When to use
 
-Production modal laid out as a workbench: a full-height SplitView list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
+Production ListDetailDialog: a full-height list column with its own title beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
 
 - A focused task compares several records without leaving the current workspace.
 
@@ -17,7 +17,7 @@ Production modal laid out as a workbench: a full-height SplitView list sidebar w
 ## Imports
 
 - Nothing to import: this is a reference composition.
-- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+- Declared side effects: lazy-recipe-css.
 
 ## Props
 
@@ -28,7 +28,7 @@ No props: this entry has no JavaScript API.
 - Parents: used at the root of a screen or reference, not nested.
 - Contexts: `application-reference`.
 - Children: unrestricted.
-- Built from: [Surface Scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
+- Built from: [ListDetailDialog](./list-detail-dialog.md), [Row](./row.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Button](./button.md).
 
 ## State and wiring
 
@@ -42,7 +42,7 @@ Margin: composed · border: composed · padding: composed (layout role: referenc
 
 ## Accessibility
 
-- Web Awesome owns modal focus, Escape, and the labeled header with its close control; the application adapter restores the invoking control after hide, and the compact NavStack back control returns to the list.
+- ListDetailDialog's native modal dialog owns focus, Escape, and inertness, and returns focus to the opener on close; the close control sits in the detail column (or each compact view), and the compact NavStack back control returns to the list.
 
 ## Styling boundary
 
@@ -52,6 +52,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [Surface Scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
+- Components: [ListDetailDialog](./list-detail-dialog.md), [Row](./row.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Button](./button.md).
 - Docs: [`docs/recipes.md#list-detail-dialog`](../../docs/recipes.md#list-detail-dialog).
 - UX catalog route: `?component=recipe-list-detail-dialog`.

package/ai/components/search-field.md

@@ -0,0 +1,108 @@
+# SearchField
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:search-field` · Kerf UI · component · Controls
+
+## When to use
+
+Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+
+- Combine DOM-owned free text with ordered editable/removable filter tokens in one searchbox.
+- Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group.
+- Use presentation="form-field" for a structured search query beside Web Awesome form controls, with a visible label, optional hint, and required marker.
+
+**Not when:**
+
+- Do not use for ordinary text input or separately labeled filter controls.
+
+**Alternatives:**
+
+- [Input](./wa-input.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/search-field` — exports `SearchField`, `readSearchField`, `placeSearchFieldCaret`.
+- JavaScript: `@kerfjs/ui/wire-search-fields` — exports `wireSearchFields`.
+- JavaScript: `@kerfjs/ui/search-field-model` — exports `createSearchFieldModel`.
+- CSS: the browser build of `@kerfjs/ui/search-field` pulls its CSS automatically; import `@kerfjs/ui/search-field.css` manually only without the `browser` export condition.
+- Wiring: `readSearchField` from `@kerfjs/ui/search-field` (required).
+- Wiring: `placeSearchFieldCaret` from `@kerfjs/ui/search-field` (optional).
+- Wiring: `wireSearchFields` from `@kerfjs/ui/wire-search-fields` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/search-field`](../public-api-signatures-v1.md#kerfjsuisearch-field), [`@kerfjs/ui/wire-search-fields`](../public-api-signatures-v1.md#kerfjsuiwire-search-fields), [`@kerfjs/ui/search-field-model`](../public-api-signatures-v1.md#kerfjsuisearch-field-model) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- tokens
+- free text
+- disabled
+- collapsible standalone or toolbar composition
+- visible form-field label, hint, and required marker
+
+## Composition
+
+- Parents: any.
+- Contexts: `structured-search-editor`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading-decoration` — JSX prop `leading`; accepts `dormant-decoration`; 0–1.
+- `trailing-control` — JSX prop `trailing`; accepts `control`; 0–1.
+
+## State and wiring
+
+- tokens — controlled (required)
+- text — component (required)
+- expanded — controlled
+
+**Wiring:** `wireSearchFields` is required.
+
+- Retain and invoke the disposer.
+- Use readSearchField for DOM-owned text.
+- With a managed model, read model.state.peek() (never model.state.value) in the host render and bind model.result as a signal hole; the field itself re-renders only when model.structure changes, not per keystroke.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-search-field-text` on `the text span inside kui-search-field__editor` (`wireSearchFields`): Marks the plain-text span the helper inserts when the editor is emptied.
+- `data-empty` on `the text span inside kui-search-field__editor` (`wireSearchFields`): "true" on that span while it holds no text.
+- `data-placeholder-visible` on `the kui-search-field root` (`wireSearchFields`): Tracks whether the DOM-owned editor is empty so its placeholder stays outside the editable area.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Announce result changes when useful and keep tokens atomic during editing.
+- Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.
+- Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.
+- In collapsible mode, wireSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out.
+- The form-field presentation associates its visible label and optional hint with the searchbox, exposes aria-required when required, and lets wireSearchFields focus the editor from a label click. The app validates required input.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-search-field`, `kui-search-field__clear`, `kui-search-field__editor`, `kui-search-field__expand`, `kui-search-field__leading`, `kui-search-field__token`, `kui-search-field__token-edit`, `kui-search-field__token-remove`, `kui-search-field__suggestions`, `kui-search-field__suggestion`, `kui-search-field__trailing`.
+
+Never put `kui-search-field`, `kui-search-field__clear`, `kui-search-field__editor`, `kui-search-field__expand`, `kui-search-field__leading`, `kui-search-field__token`, `kui-search-field__token-edit`, `kui-search-field__token-remove`, `kui-search-field__suggestions`, `kui-search-field__suggestion`, `kui-search-field__trailing` on an element you write; render `SearchField` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text-link`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-focus-ring`, `--kui-font-s`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-search-field-background`, `--kui-search-field-border`, `--kui-search-field-editor-min-width`, `--kui-search-field-line-size`, `--kui-search-field-token-background`, `--kui-search-field-token-foreground`, `--kui-search-field-expanded-width`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Diagnostics
+
+- `KUI-C105` (error) when wireSearchFields is absent: SearchField requires its public wiring helper for keyboard and collapsible behavior.
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [Input](./wa-input.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#searchfield`](../../docs/accessibility.md#searchfield).
+- UX catalog route: `?component=search-field`.

package/ai/components/select.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:select` · Kerf UI · component · Controls
 
-Controlled Web Awesome select with typed single or multiple values, disabled choices, optional bulk actions, and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+Controlled Kerf select with typed single or multiple values, disabled choices, optional bulk actions, and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations; a native trigger and a top-layer listbox wired by select/register.
 
 ## When to use
 
@@ -58,6 +58,7 @@ Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md
 - disabled choice with an optional reason
 - opt-in select-all and clear actions for multiple selection
 - multiple icon-only filter trigger with a fixed triggerIcon
+- maxTriggerWidth / minTriggerWidth bounds on the closed trigger under any presentation, ellipsizing custom selected content
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
@@ -68,7 +69,7 @@ Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md
 - Parents: any.
 - Contexts: `controlled-value-selection`.
 - Children: unrestricted.
-- Built from: [LucideIcon](./lucide-icon.md), [Badge](./badge.md), [Select](./wa-select.md), [Option](./wa-option.md).
+- Built from: [LucideIcon](./lucide-icon.md), [Badge](./badge.md).
 
 ## State and wiring
 
@@ -85,21 +86,22 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 ## Accessibility
 
 - Verify the live value, standard events, focus, and rendered output.
-- A nonempty label names the internal combobox; otherwise ariaLabel supplies a visually hidden label without adding control height, including custom selected content.
-- Hint text is visible below the control through Web Awesome's native hint relationship; placeholderText remains the empty value inside the closed control.
-- Import select/register once; its scoped lifecycle adapter keeps the latest open/close request authoritative across animation reversals, canceled transitions, and removal. Do not add consumer popup timing or position repairs.
-- With multiple, the popup stays open while choices toggle (pointer, Enter, or Space) and closes on an outside press, Escape, or focus leaving; each chosen option shows a check, and the closed control summarizes the chosen labels in choice order.
-- Disabled choices stay visible but cannot be selected; disabledReason exposes a tooltip. A multiple Select can opt in to localized select-all and clear buttons, which skip disabled choices and publish ordinary input/change events for changed values.
-- A multiple icon-only trigger shows its fixed triggerIcon and, while any choice is chosen, an aria-hidden count Badge; the combobox's accessible name ends with the chosen labels in choice order, and its hidden value stays empty.
-- Once registered, an icon-only trigger (single or multiple) shows an aria-hidden Web Awesome help tag repeating its accessible name (a single Select adds its current choice) after a 500ms hover and at once on keyboard focus; it hides while the popup is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
+- The trigger is a native button with role="combobox", aria-haspopup="listbox", and aria-expanded. A nonempty label names it (the visible label is aria-hidden text beside it); otherwise ariaLabel names it without adding control height, including custom selected content.
+- Hint text is visible below the control and is the trigger's aria-description; placeholderText remains the empty value inside the closed control.
+- Import select/register once: it defines the form-associated kui-select root (value, name, form submission, and form reset) and wires every Select in the document. The listbox opens below the trigger in the top layer, flipping above when short and capped at the viewport edges. Do not add consumer popup timing or position repairs.
+- Keyboard: Enter, Space, ArrowDown, or ArrowUp on the trigger opens on the chosen option (Home/End on the first/last), and typing opens on a matching label; in the listbox the arrows move and wrap, Home/End jump, typing a label's first letters moves to it, Enter or Space chooses, Escape closes and returns focus to the trigger, and Tab closes and continues from the trigger.
+- With multiple, the listbox (aria-multiselectable) stays open while choices toggle (pointer, Enter, or Space) and closes on an outside press, Escape, or Tab; each chosen option shows a check, and the closed control summarizes the chosen labels in choice order.
+- Disabled choices stay visible with aria-disabled but cannot be chosen; disabledReason is their title. A multiple Select can opt in to localized select-all and clear buttons below the listbox, which skip disabled choices and publish ordinary change events for changed values.
+- A multiple icon-only trigger shows its fixed triggerIcon and, while any choice is chosen, an aria-hidden count Badge; the trigger's accessible name ends with the chosen labels in choice order, and its value text stays empty.
+- Once registered, an icon-only trigger (single or multiple) shows an aria-hidden help tag repeating its accessible name (a single Select adds its current choice) after a 500ms hover and at once on keyboard focus; it hides while the listbox is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
 
 ## Styling boundary
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-select`, `kui-select--custom-selected`, `kui-select--fit-menu`, `kui-select--label-hidden`, `kui-select__custom-selected`, `kui-select__custom-selected-content`, `kui-select__group`, `kui-select__group--separated`, `kui-select__group-title`, `kui-select__icon`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-select`, `kui-select--custom-selected`, `kui-select--fit-menu`, `kui-select__custom-selected`, `kui-select__custom-selected-content`, `kui-select__group`, `kui-select__group--separated`, `kui-select__group-title`, `kui-select__icon`, `kui-select__listbox`, `kui-select__option`, `kui-select__popup`, `kui-select__trigger`, `kui-select__value`.
 
-Never put `kui-select`, `kui-select--custom-selected`, `kui-select--fit-menu`, `kui-select--label-hidden`, `kui-select__custom-selected`, `kui-select__custom-selected-content`, `kui-select__group`, `kui-select__group--separated`, `kui-select__group-title`, `kui-select__icon` on an element you write; render `Select` instead (`KUI-L103`).
+Never put `kui-select`, `kui-select--custom-selected`, `kui-select--fit-menu`, `kui-select__custom-selected`, `kui-select__custom-selected-content`, `kui-select__group`, `kui-select__group--separated`, `kui-select__group-title`, `kui-select__icon`, `kui-select__listbox`, `kui-select__option`, `kui-select__popup`, `kui-select__trigger`, `kui-select__value` on an element you write; render `Select` instead (`KUI-L103`).
 
 Public tokens it reads: `--kui-color-neutral-border-quiet`, `--kui-color-neutral-on-quiet`, `--kui-disclosure-icon-scale`, `--kui-font-2xs`, `--kui-select-selected-color`, `--kui-select-selected-font-size`, `--kui-select-selected-font-weight`, `--kui-select-trigger-max-width`. Set a token only where its public contract allows; prefer a prop.
 
@@ -111,6 +113,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [LucideIcon](./lucide-icon.md), [Badge](./badge.md), [Select](./wa-select.md), [Option](./wa-option.md), [SegmentedControl](./segmented-control.md), [Dropdown](./wa-dropdown.md), [Combobox](./combobox.md).
-- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- Components: [LucideIcon](./lucide-icon.md), [Badge](./badge.md), [SegmentedControl](./segmented-control.md), [Select](./wa-select.md), [Dropdown](./wa-dropdown.md), [Combobox](./combobox.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
 - UX catalog route: `?component=select`.