@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

package/ai/components/recipe-loading-inspector.md

@@ -0,0 +1,57 @@
+# Loading inspector
+
+<!-- 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-loading-inspector` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
+
+- A detail or inspector view must render its real chrome while its per-record values are still loading, then swap to the populated record without duplicating markup.
+
+**Not when:**
+
+- Do not hand-build a separate empty-state layout, and do not use it for known progress — use LoadingSpinner for that.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## 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: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [List](./list.md), [ValueTable](./value-table.md), [Select](./select.md), [SegmentedControl](./segmented-control.md), [ListItem](./list-item.md), [StateBanner](./state-banner.md), [Skeleton](./skeleton.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** loading lifecycle; which values are unknown; fetching, transport, and domain 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
+
+- Each component marks itself aria-busy and disables its own controls while loading; the composition keeps labels and structure stable across the transition.
+
+## 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: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [List](./list.md), [ValueTable](./value-table.md), [Select](./select.md), [SegmentedControl](./segmented-control.md), [ListItem](./list-item.md), [StateBanner](./state-banner.md), [Skeleton](./skeleton.md), [LucideIcon](./lucide-icon.md).
+- Docs: [`docs/recipes.md#loading-inspector`](../../docs/recipes.md#loading-inspector).
+- UX catalog route: `?component=recipe-loading-inspector`.

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

@@ -0,0 +1,57 @@
+# Navigation sidebar
+
+<!-- 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-sidebar` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
+
+- A workspace sidebar needs the shared toolbar/content/footer pane model, 24px major section rhythm, and 44px row and utility-action targets.
+
+**Not when:**
+
+- Use ordinary links when menu selection, section, and sidebar anatomy do not apply.
+
+## 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: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+
+## State and wiring
+
+**The app owns:** information architecture; routing; permissions; disclosure state.
+
+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
+
+- Native buttons retain names, current state, sequential focus, and disclosure state; rows and standalone footer actions remain at least 44px tall.
+
+## 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: [Pane](./pane.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [List](./list.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Docs: [`docs/recipes.md#navigation-sidebar`](../../docs/recipes.md#navigation-sidebar).
+- UX catalog route: `?component=recipe-navigation-sidebar`.

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,101 @@
+# 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
+
+## 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-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-\* 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/segmented-control.md

@@ -0,0 +1,82 @@
+# 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)
+
+## 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,107 @@
+# 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 Web Awesome select with typed single or multiple values and form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+
+## When to use
+
+Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+
+- 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, or foregroundColorVar() for an app-owned property. 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.
+
+**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)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/select` — exports `Select`, `uiColor`, `colorVar`, `foregroundColorVar`.
+- 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) 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
+- select- or group-owned focus ring
+- label maximum width and truncation
+- multiple selection
+- multiple icon-only filter trigger with a fixed triggerIcon
+
+**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` — 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), [Select](./wa-select.md), [Option](./wa-option.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.
+- 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.
+- 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.
+
+## 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__group`, `kui-select__group--separated`, `kui-select__group-title`, `kui-select__icon`.
+
+Never put `kui-select`, `kui-select--custom-selected`, `kui-select--fit-menu`, `kui-select--label-hidden`, `kui-select__custom-selected`, `kui-select__group`, `kui-select__group--separated`, `kui-select__group-title`, `kui-select__icon` 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`. 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), [Select](./wa-select.md), [Option](./wa-option.md), [SegmentedControl](./segmented-control.md), [Dropdown](./wa-dropdown.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).
+- UX catalog route: `?component=select`.