@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/ai/components/recipe-navigation-stack.md

@@ -0,0 +1,57 @@
+# Navigation Stack
+
+<!-- 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:recipe-navigation-stack` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A push/pop navigation stack drill-down with animated slides and a live device class.
+
+- A flow drills from a list into detail and back on one pane, at any device size or inside a dialog.
+
+**Not when:**
+
+- Use SplitView when a list and its detail should show together on roomy classes.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [NavStack](./nav-stack.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Row](./row.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
+
+## State and wiring
+
+**The app owns:** the stack (a signal of views); selection; routing; data.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The back control is a real button; reduced motion collapses the slide to instant.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+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: [NavStack](./nav-stack.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Row](./row.md), [Text](./text.md), [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [ContentItem](./content-item.md).
+- Docs: [`docs/recipes.md#navigation-stack`](../../docs/recipes.md#navigation-stack).
+- UX catalog route: `?component=recipe-navigation-stack`.

package/ai/components/recipe-workspace-header.md

@@ -0,0 +1,57 @@
+# Workspace Header
+
+<!-- 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:recipe-workspace-header` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Page identity with primary, secondary, and overflow actions that relocate at narrow widths.
+
+- A workspace page needs one primary heading and a small prioritized action set.
+
+**Not when:**
+
+- Use a smaller local heading when the page does not need actions or persistent identity.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [StateBanner](./state-banner.md), [Application Layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** authorization; command behavior; breadcrumbs; product copy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Heading order and action focus order remain stable when controls wrap.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+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: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [StateBanner](./state-banner.md), [Application Layout](./layout.md).
+- Docs: [`docs/recipes.md#workspace-header`](../../docs/recipes.md#workspace-header).
+- UX catalog route: `?component=recipe-workspace-header`.

package/ai/components/resize.md

@@ -0,0 +1,106 @@
+# ResizableRegion
+
+<!-- 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:resize` · Kerf UI · component · Controls
+
+## When to use
+
+Pointer and keyboard-operable split region with a customizable handle icon.
+
+- Provide a controlled user-resizable application pane.
+
+**Not when:**
+
+- Do not use for static columns; use CSS grid.
+
+**Alternatives:**
+
+- [Application Layout](./layout.md) (nearest)
+- [Split Panel](./wa-split-panel.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/resizable-region` — exports `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer`, `wireResizableRegions`.
+- CSS: the browser build of `@kerfjs/ui/resizable-region` pulls its CSS automatically; import `@kerfjs/ui/resizable-region.css` manually only without the `browser` export condition.
+- Wiring: `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` (required).
+- Wiring: `clampRegionSize` from `@kerfjs/ui/resizable-region` (optional).
+- Wiring: `resizeRegionFromPointer` from `@kerfjs/ui/resizable-region` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/resizable-region`](../public-api-signatures-v1.md#kerfjsuiresizable-region), [`@kerfjs/ui/wire-resizable-regions`](../public-api-signatures-v1.md#kerfjsuiwire-resizable-regions) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- horizontal
+- vertical
+- start edge
+- end edge
+- collapsed
+- custom handle icon
+- hidden separator
+- slide, fade-slide, or instant content
+- clipped, scrolling, or popup-visible content
+- inline, overlay, or hidden responsive presentation
+- safe-area restore control
+- top-corner or inline restore placement
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `restoreInset`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `restoreInset={space("xs")}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `adjustable-pane-boundary`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+- size — controlled (required)
+
+**Wiring:** `wireResizableRegions` is required.
+
+- Retain and invoke the disposer.
+- Persist committed size in the application when persistence is required.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-handle-inset` on `kui-resizable-region` (`wireResizableRegions`): Present while a clipping edge clamps the region: the handle and its focus ring sit inside the region instead of overhanging that edge.
+- `data-resizing` on `kui-resizable-region` (`wireResizableRegions`): "true" during an active pointer drag of the handle.
+
+## Geometry
+
+Margin: none · border: conditional · padding: conditional (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The region delegates visible separator geometry and hit-area padding to its orientation-specific handle.
+
+## Accessibility
+
+- Preserve separator naming, value ARIA, and keyboard behavior.
+- Keep handleIcon decorative and free of interactive descendants; the separator owns focus, naming, and pointer/keyboard interaction.
+
+## 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-resizable-region`, `kui-resizable-region__content`, `kui-resizable-region__handle`, `kui-resizable-region__handle-icon`, `kui-resizable-region__restore`.
+
+Never put `kui-resizable-region`, `kui-resizable-region__content`, `kui-resizable-region__handle`, `kui-resizable-region__handle-icon`, `kui-resizable-region__restore` on an element you write; render `ResizableRegion` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-text-link`, `--kui-focus-ring`, `--kui-radius-s`, `--kui-resizable-region-edge-extent`, `--kui-resizable-region-background`, `--kui-resizable-region-handle-active-color`, `--kui-resizable-region-handle-color`, `--kui-resizable-region-overlay-z`, `--kui-resizable-region-popup-z`, `--kui-resizable-region-restore-inset`, `--kui-resizable-region-restore-z`, `--kui-resizable-region-separator-color`, `--kui-resizable-region-size`. 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-C106` (error) when wireResizableRegions is absent: ResizableRegion requires wireResizableRegions for pointer and keyboard operation.
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [Application Layout](./layout.md), [Split Panel](./wa-split-panel.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#resizableregion`](../../docs/accessibility.md#resizableregion).
+- UX catalog route: `?component=resize`.

package/ai/components/row.md

@@ -0,0 +1,96 @@
+# Row
+
+<!-- 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:row` · Kerf UI · component · Structure
+
+A horizontal flex row with physical-axis alignment, side-selectable text/control insets, a typed xs gap by default, flex participation, and opt-in wrapping.
+
+## When to use
+
+Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full/baseline alignment instead of application-owned flex wrappers.
+
+- Arrange a group of sibling components horizontally.
+- Choose physical horizontal distribution and vertical alignment without writing one-off flex CSS.
+- Use a finite flex keyword or the flex() builder when Row participates in a flexible parent layout.
+- Allow a bounded group to wrap while retaining the same typed gap and alignment contract.
+- Apply the standard text or control inset to selected physical sides without an application wrapper.
+
+**Not when:**
+
+- Do not use Row when content belongs in a semantic list or when a named-zone component such as Toolbar owns the composition.
+- Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception.
+- Do not use alignment to replace semantic grouping or responsive relocation.
+
+**Alternatives:**
+
+- [List](./list.md) (axis-alternative) — Use List when the main layout axis is vertical.
+- [Toolbar](./toolbar.md) (semantic-alternative) — Use Toolbar when content belongs to named leading, center, and trailing application-chrome zones.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/row` — exports `Row`.
+- CSS: the browser build of `@kerfjs/ui/row` pulls its CSS automatically; import `@kerfjs/ui/row.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/row`](../public-api-signatures-v1.md#kerfjsuirow) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- left/center/right/full horizontal alignment with l/c/r/f and flex aliases
+- top/middle/bottom/full vertical alignment with t/m/c/b/f and flex aliases, plus baseline alignment
+- named none/2xs/xs/s/m/l/xl token gap
+- typed CssLength gap
+- boolean, finite-keyword, or typed CssFlex flex
+- nowrap or wrapping
+- top/right/bottom/left text and control inset combinations
+- fill: the layout root fills a definite-height parent
+- rootAttributes: safe data-\*, aria-\*, and structural role metadata on the root
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `gap`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `gap="xs"`
+- `flex`: flex grammar; raw values: forbid; shorthands `none`, `auto`, `initial`; helpers `flex` — e.g. `flex`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`, `horizontal-layout`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** child semantics and content; alignment and wrapping policy; typed gap and flex choices.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: conditional (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Row adds no margin or border. textInsets adds the full 17px content inset and controlInsets adds 8px on selected physical sides; text wins when both select a side.
+
+## Accessibility
+
+- Row adds layout only and no grouping role; children retain responsibility for native or ARIA semantics.
+- Wrapping must preserve a readable source and focus order.
+
+## 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-row`.
+
+Never put `kui-row` on an element you write; render `Row` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-layout-item-gap`, `--kui-row-gap`. 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: [List](./list.md), [Toolbar](./toolbar.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#row-and-list-alignment`](../../docs/layout.md#row-and-list-alignment).
+- UX catalog route: `?component=row`.

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/segmented-control.md

@@ -0,0 +1,83 @@
+# SegmentedControl
+
+<!-- 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:segmented-control` · Kerf UI · component · Controls
+
+## When to use
+
+Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
+
+- Expose a small controlled exclusive choice set.
+
+**Not when:**
+
+- Do not use for tabpanel semantics or many choices.
+
+**Alternatives:**
+
+- [TabBar](./tab-bar.md) (nearest)
+- [Select](./select.md) (nearest)
+- [Button Group](./wa-button-group.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/segmented-control` — exports `SegmentedControl`.
+- CSS: the browser build of `@kerfjs/ui/segmented-control` pulls its CSS automatically; import `@kerfjs/ui/segmented-control.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/segmented-control`](../public-api-signatures-v1.md#kerfjsuisegmented-control) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- filled
+- outlined
+- toolbar
+- rounded
+- pill
+- equal width
+- small
+- placeholder (loading)
+- disabled (whole control)
+
+## Composition
+
+- Parents: any.
+- Contexts: `compact-exclusive-choice`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+- value — controlled (required)
+
+No wiring helper.
+
+## 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
+
+- Every enabled choice remains in sequential tab order.
+- Every choice has a meaningful label.
+
+## 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-segmented-control`, `kui-segmented-control__item`.
+
+Never put `kui-segmented-control`, `kui-segmented-control__item` on an element you write; render `SegmentedControl` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-font-2xs`, `--kui-font-weight-semibold`, `--kui-font-xs`, `--kui-segmented-background`, `--kui-segmented-border`, `--kui-segmented-foreground`, `--kui-segmented-hover-background`, `--kui-segmented-item-radius`, `--kui-segmented-radius`, `--kui-segmented-selected-background`, `--kui-segmented-selected-border`, `--kui-segmented-selected-foreground`, `--kui-segmented-selected-shadow`, `--kui-shadow-s`, `--kui-toolbar-control-color`, `--kui-toolbar-control-hover-background`, `--kui-toolbar-control-selected-background`, `--kui-toolbar-control-selected-color`, `--kui-toolbar-control-selected-shadow`. 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: [LucideIcon](./lucide-icon.md), [TabBar](./tab-bar.md), [Select](./select.md), [Button Group](./wa-button-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#segmentedcontrol`](../../docs/accessibility.md#segmentedcontrol).
+- UX catalog route: `?component=segmented-control`.

package/ai/components/select.md

@@ -0,0 +1,118 @@
+# Select
+
+<!-- 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:select` · Kerf UI · component · Controls
+
+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
+
+Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
+
+- Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices.
+- Color an optional choice icon with a CssForegroundColor: uiColor() with a foreground token such as success-on-quiet, foregroundColorVar() for an app-owned property, or foregroundColor() for a direct custom CSS color. Fill tokens such as success are backgrounds that leave the icon nearly invisible, so they, lengths, raw color strings, and unqualified colorVar() values are rejected.
+- Use the default content-sized menu for long option labels; native popup shifting keeps it within 10px viewport gutters. fitMenu instead matches trigger width and wraps labels.
+
+**Not when:**
+
+- Do not use for commands or a small choice set that should stay visible.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Select](./wa-select.md) (prefer-over)
+- [Dropdown](./wa-dropdown.md) (prefer-over)
+- [Combobox](./combobox.md) (nearest) — Use Combobox when people may type to filter or create a new value.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/select` — exports `Select`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `uiColor`, `colorVar`, `foregroundColorVar`, `foregroundColor`.
+- CSS: the browser build of `@kerfjs/ui/select` pulls its CSS automatically; import `@kerfjs/ui/select.css` manually only without the `browser` export condition.
+- Registration: import `@kerfjs/ui/select/register` once (a side effect).
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md#kerfjsuiselect), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- placeholder
+- disabled
+- fit menu
+- grouped
+- custom selected content
+- hint text
+- placeholder (loading)
+- form, toolbar-borderless, or navigation presentation
+- default or compact size
+- label or icon-only selected presentation
+- optional caret-free round icon-only trigger
+- select- or group-owned focus ring
+- label maximum width and truncation
+- fit-content, max-content, or fill trigger width
+- custom selected content typography and ellipsis
+- multiple selection
+- 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):
+
+- `choices[].color`: color grammar; raw values: forbid; helpers `uiColor`, `foregroundColorVar`, `foregroundColor` — e.g. `color: uiColor("success-on-quiet")`
+
+## Composition
+
+- Parents: any.
+- Contexts: `controlled-value-selection`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [Badge](./badge.md).
+
+## State and wiring
+
+- value — controlled (required)
+
+**Wiring:** `@kerfjs/ui/select/register` is required.
+
+- Import the registration module once in the application.
+
+## 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
+
+- Verify the live value, standard events, focus, and rendered output.
+- 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__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__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.
+
+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-C107` (error) when the registration import is absent: Select requires @kerfjs/ui/select/register once per application.
+
+## Related
+
+- 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`.