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

package/ai/components/list-inset-control.md

@@ -0,0 +1,74 @@
+# ListInsetControl
+
+<!-- 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:list-inset-control` · Kerf UI · component · Structure
+
+Insets selected physical sides of a self-bordered control in a pane/list content region.
+
+## When to use
+
+Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
+
+- Place a control that carries its own border and padding (an input, a wa-\* control) in a pane/list content region so its edges align with .kui-content items.
+
+**Not when:**
+
+- Do not wrap a component that already owns its content-item margin (ListItem, StateBanner, …) — that double-insets it. Use ListInsetText for bare text.
+
+**Alternatives:**
+
+- [ListInsetText](./list-inset-text.md) (nearest)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-inset-control` — exports `ListInsetControl`.
+- CSS: the browser build of `@kerfjs/ui/list-inset-control` pulls its CSS automatically; import `@kerfjs/ui/list-inset-control.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list-inset-control`](../public-api-signatures-v1.md#kerfjsuilist-inset-control) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- all-side inset by default
+- top/right/bottom/left inset combinations
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the wrapped control and its behavior.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: child · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- A layout wrapper only; it adds no role or name — the wrapped control keeps its own.
+
+## 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-list-inset-control`.
+
+Never put `kui-list-inset-control` on an element you write; render `ListInsetControl` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-layout-inline-margin`. 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: [ListInsetText](./list-inset-text.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=list-inset-control`.

package/ai/components/list-inset-text.md

@@ -0,0 +1,72 @@
+# ListInsetText
+
+<!-- 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:list-inset-text` · Kerf UI · component · Structure
+
+Gives selected physical sides of bare text the content-item geometry so it lines up with bordered items.
+
+## When to use
+
+Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
+
+- Line a plain text element up with bordered .kui-content items — it adds the 8px margin, 1px transparent border, and 8px padding the text lacks.
+
+**Not when:**
+
+- Do not use it to wrap an interactive control (use ListInsetControl), or a component that already owns its content-item geometry.
+
+**Alternatives:**
+
+- [ListInsetControl](./list-inset-control.md) (nearest)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-inset-text` — exports `ListInsetText`.
+- CSS: the browser build of `@kerfjs/ui/list-inset-text` pulls its CSS automatically; import `@kerfjs/ui/list-inset-text.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list-inset-text`](../public-api-signatures-v1.md#kerfjsuilist-inset-text) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- all-side inset by default
+- top/right/bottom/left inset combinations
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the text content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- A layout wrapper only; it adds no role or name.
+
+## 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-list-inset-text`.
+
+Never put `kui-list-inset-text` on an element you write; render `ListInsetText` 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: [ListInsetControl](./list-inset-control.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=list-inset-text`.

package/ai/components/list-item.md

@@ -0,0 +1,108 @@
+# ListItem
+
+<!-- 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:list-item` · Kerf UI · component · Navigation
+
+Configurable native-button action rows and native-anchor navigation rows with structured labels, status/busy metadata, density, group dividers, protected domain metadata hooks, and rounded-boundary overflow clipping.
+
+## When to use
+
+Selectable, disabled, trailing, and multiline action or link rows.
+
+- Render a selectable, disabled, trailing, or multiline sidebar action row whose descendants must remain clipped to the rounded row boundary; use ListItemLink when the destination has an href and needs native link activation.
+- A settings or command row identifies each entry by a colored icon tile (iconTile) instead of a bare glyph.
+
+**Not when:**
+
+- Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use ListActionRow for sibling row actions.
+- Do not inject declaration strings; use className, public tokens, and cataloged component props for application styling.
+
+**Alternatives:**
+
+- [ListActionRow](./list-action-row.md) (nearest) — The trailing region must be independently interactive.
+- [SummaryRow](./summary-row.md) (nearest) — Use SummaryRow for dense selectable item summaries with metadata.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-item` — exports `ListItem`, `ListItemLink`, `wireListReorder`, `reorderListItems`.
+- CSS: the browser build of `@kerfjs/ui/list-item` pulls its CSS automatically; import `@kerfjs/ui/list-item.css` manually only without the `browser` export condition.
+- Wiring: `wireListReorder` from `@kerfjs/ui/wire-list-reorder` (optional).
+- Wiring: `reorderListItems` from `@kerfjs/ui/wire-list-reorder` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list-item`](../public-api-signatures-v1.md#kerfjsuilist-item), [`@kerfjs/ui/wire-list-reorder`](../public-api-signatures-v1.md#kerfjsuiwire-list-reorder) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- native link and external link
+- selected
+- pressed
+- disabled
+- trailing
+- multiline
+- placeholder (loading)
+- compact density
+- spacious density
+- centered icon beside a multiline label
+- drag-target state
+- draggable row with dragging and drop-before / drop-after insertion states
+- description and status
+- busy while retaining content
+- before, after, or paired group divider
+- position-aware divided-list corners: flat wherever a divider line (this row's or a neighbor's) meets the edge
+- filled leading icon tile (iconTile): a quiet tone preset (neutral, brand, success, warning, danger) or an application fill with an optional foreground; a 32px rounded tile holding an 18px glyph
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `style`: declarations grammar; raw values: forbid — e.g. `className="app-row"`
+- `iconTile.color`: color grammar; raw values: forbid; helpers `fillColor`, `uiColor`, `colorVar` — e.g. `iconTile={{ color: fillColor("#e5484d") }}`
+- `iconTile.foreground`: color grammar; raw values: forbid; helpers `uiColor`, `foregroundColorVar`, `foregroundColor` — e.g. `iconTile={{ color: fillColor("#e5484d"), foreground: foregroundColor("white") }}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** routing; link destinations; selection; permissions; action handling; domain data attributes; row order.
+
+**Wiring:** `wireListReorder`, `reorderListItems` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-dragging` on `ListItem / ListItemLink rows being dragged` (`wireListReorder`): "true" on every row a pointer drag is moving (the dragged row, or every selected row of its list when the dragged row is selected). Same attribute the `dragging` prop renders.
+- `data-drop-position` on `ListItem / ListItemLink row under the pointer` (`wireListReorder`): "before" or "after": the edge of this row the dragged rows would land beside. Same attribute the `dropPosition` prop renders.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Public resting, hover, and selected text, fill, and border tokens can be scoped to a row or its containing list without changing the default tones.
+
+## Accessibility
+
+- ListItem uses native button activation and pressed maps to aria-pressed; ListItemLink uses native anchor activation and external opens a new tab with safe rel and an announced default label. Both map selected to aria-current; disabled or loading links omit href and leave the tab order. rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls. A draggable row reorders by pointer drag or, with wireListReorder, Alt+Shift+ArrowUp/ArrowDown; a placeholder is never draggable.
+
+## 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-list-item`, `kui-list-item__icon`, `kui-list-item__label`, `kui-list-item__primary-label`, `kui-list-item__description`, `kui-list-item__status`, `kui-list-item__trailing`.
+
+Never put `kui-list-item`, `kui-list-item__icon`, `kui-list-item__label`, `kui-list-item__primary-label`, `kui-list-item__description`, `kui-list-item__status`, `kui-list-item__trailing` on an element you write; render `ListItem` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-border-loud`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-radius-pill`, `--kui-focus-ring`, `--kui-list-item-color`, `--kui-list-item-background`, `--kui-list-item-align-items`, `--kui-list-item-border-width`, `--kui-list-item-border`, `--kui-list-item-columns`, `--kui-list-item-drag-target-background`, `--kui-list-item-drag-target-outline`, `--kui-list-item-drag-target-outline-offset`, `--kui-list-item-dragging-opacity`, `--kui-list-item-drop-indicator`, `--kui-list-item-drop-indicator-width`, `--kui-list-item-gap`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-icon-color`, `--kui-list-item-icon-size`, `--kui-list-item-label-max-width`, `--kui-list-item-label-weight`, `--kui-list-item-min-height`, `--kui-list-item-padding-block`, `--kui-list-item-padding-inline`, `--kui-list-item-radius`, `--kui-list-item-selected-background`, `--kui-list-item-selected-border`, `--kui-list-item-selected-color`, `--kui-list-item-trailing-color`, `--kui-list-group-divider-color`, `--kui-list-row-padding-inline`, `--kui-list-row-icon-size`, `--kui-font-xs`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-radius-m`, `--kui-color-brand-on-quiet`, `--kui-color-success-fill-quiet`, `--kui-color-success-border-quiet`, `--kui-color-success-on-quiet`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-border-quiet`, `--kui-color-warning-on-quiet`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-border-quiet`, `--kui-color-danger-on-quiet`. 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), [LoadingSpinner](./loading-spinner.md), [ListActionRow](./list-action-row.md), [SummaryRow](./summary-row.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=list-item`.

package/ai/components/list.md

@@ -0,0 +1,127 @@
+# List
+
+<!-- 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:list` · Kerf UI · component · Navigation
+
+A vertical stack with physical-axis alignment, side-selectable text/control insets, optional typed token/length gap, flex growth, vertical scrolling, and independently selectable divider edges.
+
+## When to use
+
+Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.
+
+- Arrange component rows or sections in a vertical stretch-aligned stack.
+- Let one bounded list own vertical scrolling, flex growth, or one or more physical-edge dividers.
+- Choose a finite gap shorthand such as xs or m, or compose a typed length with @kerfjs/ui/css-values when the spacing scale is insufficient.
+- Use a finite flex keyword or the flex() builder when List participates in flexible layout.
+- Apply the standard text or control inset to selected physical sides without an application wrapper.
+- Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row.
+- Use selectionMode="multiple" and ariaLabel to group selectable rich ContentItem rows in a multi-select grid.
+- Use scrollClearance on the scrollable List that reaches an edge overlaid by chrome (a DialogSurface floating footer) so rows scroll visibly beneath it while the first and last rows still rest clear of it.
+- Render a bounded, framed result picker of ListItem rows (search results, duplicate candidates) with scrollable, frame, and typed maxHeight/minHeight instead of an app-owned bordered scroller.
+- Call wireListFocusScroll(root) once when keyboard users move focus through a scrollable List's rows, so Firefox and Safari bring a partly hidden focused row and its ring fully into view as Chromium does.
+- Cap and center a page-level content column (a settings page or setup form) with contentWidth and, for long prose, inset="document", instead of an application max-width wrapper.
+
+**Not when:**
+
+- Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.
+- Do not create nested scroll owners or use divider sides as a substitute for meaningful grouping.
+- Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use the off-rhythm s/xl spacing steps without a deliberate exception.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list` — exports `List`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `plus`, `calc`, `flex`.
+- JavaScript: `@kerfjs/ui/wire-list-focus-scroll` — exports `wireListFocusScroll`.
+- CSS: the browser build of `@kerfjs/ui/list` pulls its CSS automatically; import `@kerfjs/ui/list.css` manually only without the `browser` export condition.
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Wiring: `wireListFocusScroll` from `@kerfjs/ui/wire-list-focus-scroll` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#kerfjsuilist), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values), [`@kerfjs/ui/wire-list-focus-scroll`](../public-api-signatures-v1.md#kerfjsuiwire-list-focus-scroll), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- no gap
+- standard boolean gap
+- named none/2xs/xs/s/m/l/xl token gap
+- typed CssLength gap
+- boolean, finite-keyword, or typed CssFlex flex
+- scrollable
+- scrollClearance block-start, block-end, or both: clears overlaying chrome inside the scroll area
+- frame: 1px neutral border, control radius, and a 4px focus-ring-safe inset
+- typed CssLength maxHeight and minHeight bounds
+- base or raised solid surface
+- document reading inset
+- left/center/right/full horizontal alignment
+- top/middle/bottom/full vertical alignment
+- top/right/bottom/left divider combinations
+- 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 on the root
+- scroll dividers when named as wireScrollDividers targets chrome or scroller (by its id)
+- multi-select grid for rich ContentItem rows
+- contentWidth (compact 440px, medium 640px, wide 864px) and contentAlign for a readable, centered page column
+
+**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="none"`
+- `maxHeight`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight={rem(14)}`
+- `minHeight`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `minHeight={rem(4.25)}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`, `navigation-list`, `vertical-layout`.
+- Children: unrestricted.
+- Built from: [ListHeader](./list-header.md), [ListActionRow](./list-action-row.md), [ListItem](./list-item.md).
+
+## State and wiring
+
+**The app owns:** child semantics and content; the bounded height needed for scrolling; typed gap, flex, alignment, and divider choices; the accessible label and selection state of a multi-select grid; which one scroller opts into scroll clearance (the one reaching the covered edge); the result picker bounds (maxHeight/minHeight) and its rows.
+
+**Wiring:** `wireScrollDividers`, `wireListFocusScroll` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `the targets scroller` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `a List named as targets chrome` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: conditional · padding: conditional (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap.
+- scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the List block padding and scroll-padding on the opted-in edges; without it the context is ignored.
+- frame draws a 1px --kui-color-neutral-border-normal border with --kui-radius-m and a 4px --kui-space-2xs inset on every side (replacing inset/textInsets/controlInsets), exactly the focus-ring reach, so the first and last rows' rings stay inside the clip at the scroll extremes; maxHeight/minHeight bound the List directly.
+- Every scrollable List's block scroll padding is the focus-ring reach plus 2px of slack (6px, no change at rest), so any row focused or scrolled into view stops with its ring inside the clip; an unframed List's first and last rows still meet the clip at the scroll extremes, so use frame when they must show a whole ring.
+- As a direct child of a Pane's scrolling content, a List that does not scroll itself never shrinks below its rows (flex-shrink 0), so the content's block-end padding (a bottom safe area, an overlay NavStack bottom toolbar's clearance) follows its last row.
+
+## Accessibility
+
+- List adds layout only and no list role by default; selectionMode="multiple" makes it an aria-multiselectable grid with a required ariaLabel for selectable ContentItem rows.
+- Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll.
+- A focused scrollable List (a keyboard-focusable scroller) draws the theme focus ring inset and rounded inside its own box, so a rounded or clipping parent never cuts it off; do not restyle its focus.
+- With wireListFocusScroll, a keyboard-focused (:focus-visible) element in a scrollable List whose focus ring crosses the clip is scrolled into view (block and inline nearest, honoring the ring-room scroll padding) in every engine; pointer focus never scrolls, so a click cannot move its row from under the pointer.
+
+## 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-list`.
+
+Never put `kui-list` on an element you write; render `List` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-layout-item-gap`, `--kui-list-divider-color`, `--kui-list-gap`, `--kui-space-l`, `--kui-space-m`, `--kui-space-xl`. 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: [ListHeader](./list-header.md), [ListActionRow](./list-action-row.md), [ListItem](./list-item.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#correct-composition-and-duplicated-markup-trap`](../../docs/component-selection.md#correct-composition-and-duplicated-markup-trap).
+- UX catalog route: `?component=list`.

package/ai/components/loading-spinner.md

@@ -0,0 +1,73 @@
+# LoadingSpinner
+
+<!-- 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:loading-spinner` · Kerf UI · component · Feedback
+
+## When to use
+
+Meaningfully labeled or decorative progress.
+
+- Show compact labeled or decorative indeterminate activity in Kerf UI.
+
+**Not when:**
+
+- Do not use for known progress.
+
+**Alternatives:**
+
+- [Spinner](./wa-spinner.md) (prefer-over)
+- [Progress Bar](./wa-progress-bar.md) (prefer-over)
+- [Progress Ring](./wa-progress-ring.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/loading-spinner` — exports `LoadingSpinner`.
+- CSS: the browser build of `@kerfjs/ui/loading-spinner` pulls its CSS automatically; import `@kerfjs/ui/loading-spinner.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/loading-spinner`](../public-api-signatures-v1.md#kerfjsuiloading-spinner) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- labeled
+- decorative
+- sized
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** loading lifecycle; adjacent status copy.
+
+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.
+
+## Accessibility
+
+- Labeled spinners use role img; decorative spinners are hidden and stop for reduced motion.
+
+## 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-loading-spinner`.
+
+Never put `kui-loading-spinner` on an element you write; render `LoadingSpinner` 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: [Spinner](./wa-spinner.md), [Progress Bar](./wa-progress-bar.md), [Progress Ring](./wa-progress-ring.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=loading-spinner`.

package/ai/components/lucide-icon.md

@@ -0,0 +1,99 @@
+# LucideIcon
+
+<!-- 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:lucide-icon` · Kerf UI · component · Foundation
+
+## When to use
+
+Decorative and meaningfully labeled Lucide-compatible icons.
+
+- Render a decorative or explicitly labeled Lucide-compatible icon in Kerf application UI.
+
+**Not when:**
+
+- Do not use an icon as the only name of an unfamiliar action.
+
+**Alternatives:**
+
+- [Icon](./wa-icon.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/lucide-icon` — exports `LucideIcon`.
+- CSS: the browser build of `@kerfjs/ui/lucide-icon` pulls its CSS automatically; import `@kerfjs/ui/lucide-icon.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/lucide-icon`](../public-api-signatures-v1.md#kerfjsuilucide-icon) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- decorative
+- labeled
+- inline text flow
+- outline (default appearance)
+- solid (appearance=solid)
+- hover title for a status icon
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** icon choice; meaningful label; optional foreground color.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Decorative icons are aria-hidden; meaningful icons require a label.
+- title adds an SVG \<title> as hover text over the whole icon box (a transparent hit box fills the 24-unit view box); with label, the label stays the name, and alone the title names the icon.
+
+## Usage examples
+
+### Solid selected glyph
+
+The solid appearance fills a compatible Lucide glyph with currentColor while retaining its stroke and accessible name policy.
+
+```tsx
+<LucideIcon icon={Star} name="star" appearance="solid" />
+```
+
+### Semantic icon color
+
+Set an icon foreground with a semantic color token; omit color to inherit from surrounding text. Use foregroundColor() for a custom CSS color or foregroundColorVar() for an app variable.
+
+```tsx
+<LucideIcon icon={Bell} name="alert" color={uiColor('warning-on-quiet')} />
+```
+
+### Inline with text
+
+Let a decorative icon flow inside Text or other prose while preserving its inherited 1em size.
+
+```tsx
+<Text>
+  Ready <LucideIcon icon={Bell} name="notification" inline /> now.
+</Text>
+```
+
+## 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: [Icon](./wa-icon.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=lucide-icon`.

package/ai/components/message-composer.md

@@ -0,0 +1,85 @@
+# MessageComposer
+
+<!-- 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:message-composer` · Kerf UI · component · Controls
+
+A raised chat or prompt composer: a framed message field that grows with its content above a compact Toolbar action row with leading controls, a hint, and a send button.
+
+## When to use
+
+Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
+
+- Write a chat message, assistant prompt, or comment reply that is sent with a trailing action, especially in a DialogSurface floating footer over a transcript.
+
+**Not when:**
+
+- Use wa-textarea with a FieldLabel for an ordinary form field that is submitted with the rest of a form.
+- Do not wrap it in another framed ContentItem or card; it owns its frame, padding, and shadow.
+
+**Alternatives:**
+
+- [Textarea](./wa-textarea.md) (prefer-over) — Use MessageComposer instead of a wa-textarea and a button in app-styled chrome for a chat or prompt composer; it owns the raised frame, focus-within border, auto-grow, and action row.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/message-composer` — exports `MessageComposer`, `wireMessageComposers`.
+- CSS: the browser build of `@kerfjs/ui/message-composer` pulls its CSS automatically; import `@kerfjs/ui/message-composer.css` manually only without the `browser` export condition.
+- Wiring: `wireMessageComposers` from `@kerfjs/ui/wire-message-composers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/message-composer`](../public-api-signatures-v1.md#kerfjsuimessage-composer), [`@kerfjs/ui/wire-message-composers`](../public-api-signatures-v1.md#kerfjsuiwire-message-composers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- minRows and maxRows bounds for the growing field
+- optional hint, described by the field when an id is given
+- optional leading controls (attach, model Select) in the Toolbar action row's leading zone
+- disabled field
+- submitOnEnter: Enter or Cmd/Ctrl+Enter activates the first trailing action, Shift+Enter inserts a newline (with wireMessageComposers)
+- slotted into a DialogSurface floating footer
+
+## Composition
+
+- Parents: any.
+- Contexts: `chat-composer`, `dialog-floating-footer`.
+- Children: unrestricted.
+- Built from: [Text](./text.md), [Toolbar](./toolbar.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading` — JSX prop `leading`; accepts `KerfUiContent`; any number.
+- `trailing` — JSX prop `trailing`; accepts `KerfUiContent`; at least 1.
+
+## State and wiring
+
+- value — controlled
+
+**Wiring:** `wireMessageComposers` is optional.
+
+## 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
+
+- Name the message field with label in title style; give it an id so a hint becomes its accessible description.
+- Give every trailing action a visible or accessible name, such as a Send button.
+
+## 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-message-composer`.
+
+Never put `kui-message-composer` on an element you write; render `MessageComposer` 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: [Text](./text.md), [Toolbar](./toolbar.md), [Textarea](./wa-textarea.md).
+- Docs: [`docs/message-composer.md`](../../docs/message-composer.md), [`docs/accessibility.md#messagecomposer`](../../docs/accessibility.md#messagecomposer).
+- UX catalog route: `?component=message-composer`.