@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/ai/components/headers.md

@@ -0,0 +1,63 @@
+# Headers
+
+<!-- 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:headers` · Kerf UI · CSS composition · Structure
+
+## When to use
+
+Page, dialog, and definition-list hierarchy.
+
+- Compose page, dialog, and definition-list hierarchy from their distinct primitives.
+
+**Not when:**
+
+- Do not reuse one header primitive only because its typography looks similar.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- page
+- dialog
+- key/value
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md).
+
+## State and wiring
+
+**The app owns:** scope hierarchy; copy; actions.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · 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
+
+- Preserve heading and description relationships for the containing surface.
+
+## 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), [ValueTable](./value-table.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
+- UX catalog route: `?component=headers`.

package/ai/components/icon-button.md

@@ -0,0 +1,82 @@
+# IconButton
+
+<!-- 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:icon-button` · Kerf UI · component · Controls
+
+Square, icon-only Web Awesome button with a LucideIcon and a required accessible name.
+
+## When to use
+
+Render an icon-only action as a square one form-control height on each side, so it matches an adjacent wa-input or Select, without ::part overrides.
+
+- An icon-only action stands alone or beside a form field, such as a Browse button next to a path input.
+
+**Not when:**
+
+- Do not use inside a ToolbarControlGroup; the group owns its controls' geometry, so compose a native button with a LucideIcon there.
+- Do not use when the action needs a visible text label; use wa-button with text.
+- Do not override wa-button::part(base) width, min-height, or padding to square an icon button; use IconButton.
+
+**Alternatives:**
+
+- [Button](./wa-button.md) (prefer-over) — Web Awesome squares a button only for a lone wa-icon; with a LucideIcon use IconButton.
+- [ListInsetControl](./list-inset-control.md) (composes-with) — Beside a field in a ListInsetControl the square keeps its size and aligns with the field below its label.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/icon-button` — exports `IconButton`.
+- CSS: the browser build of `@kerfjs/ui/icon-button` pulls its CSS automatically; import `@kerfjs/ui/icon-button.css` manually only without the `browser` export condition.
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/button/button.js` once (a side effect).
+- Declared side effects: browser-condition-css, custom-element-registration.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/icon-button`](../public-api-signatures-v1.md#kerfjsuiicon-button) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- default appearance
+- plain
+- outlined
+- danger variant
+- disabled
+- xs, s, m, l, or xl size
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Button](./wa-button.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the delegated action; the accessible name; appearance, variant, and size choice.
+
+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
+
+- label is required and names the button through its LucideIcon (role img), since the button shows no text.
+
+## 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-icon-button`.
+
+Never put `kui-icon-button` on an element you write; render `IconButton` 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: [Button](./wa-button.md), [LucideIcon](./lucide-icon.md), [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=icon-button`.

package/ai/components/icon-toggle-button.md

@@ -0,0 +1,80 @@
+# IconToggleButton
+
+<!-- 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:icon-toggle-button` · Kerf UI · component · Controls
+
+A standalone icon-only toggle with a single contained toolbar group's geometry and pressed chrome.
+
+## When to use
+
+Render an icon-only aria-pressed toggle in content or a pane footer, where a Toolbar does not belong, with the 44px contained geometry and raised pressed face of a single ToolbarControlGroup.
+
+- An icon-only on/off control (show a panel, a conversation) sits in content or a pane footer outside any Toolbar.
+
+**Not when:**
+
+- Do not use inside a Toolbar; compose a ToolbarControlGroup there.
+- Do not use for a momentary action; use IconButton.
+- Do not use for one-of-several choices; use SegmentedControl.
+
+**Alternatives:**
+
+- [ToolbarControlGroup](./toolbar-control-group.md) (nearest) — Inside a Toolbar, a single ToolbarControlGroup with a pressed button is the same control.
+- [IconButton](./icon-button.md) (nearest) — Use IconButton for a momentary icon-only action.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/icon-toggle-button` — exports `IconToggleButton`.
+- CSS: the browser build of `@kerfjs/ui/icon-toggle-button` pulls its CSS automatically; import `@kerfjs/ui/icon-toggle-button.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/icon-toggle-button`](../public-api-signatures-v1.md#kerfjsuiicon-toggle-button) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- pressed
+- unpressed
+- pill or rounded shape
+- disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the pressed state and its delegated action; the accessible name.
+
+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
+
+- Native button with aria-pressed and a required aria-label; with help tags registered it shows that label on hover and keyboard focus.
+
+## 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-icon-toggle-button`, `kui-icon-toggle-button__face`.
+
+Never put `kui-icon-toggle-button`, `kui-icon-toggle-button__face` on an element you write; render `IconToggleButton` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-color-brand-on-quiet`, `--kui-shadow-s`, `--kui-focus-ring`, `--kui-layout-pill-radius`, `--kui-layout-rounded-radius`, `--kui-layout-highlight-inset`. 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), [ToolbarControlGroup](./toolbar-control-group.md), [IconButton](./icon-button.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=icon-toggle-button`.

package/ai/components/layout.md

@@ -0,0 +1,75 @@
+# Application Layout
+
+<!-- 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:layout` · Kerf UI · CSS composition · Foundation
+
+Unpadded panes, 24px content stacks, and self-contained 8/1/8 content items for application layout boundaries.
+
+## When to use
+
+Provide one reusable pane, toolbar, content stack, and content-item geometry across sidebars, main areas, and dialogs.
+
+- Build sidebars, main areas, inspectors, or dialogs from an unpadded pane with optional toolbar/footer and one content stack.
+- Relocate a hidden pane's restore control into the adjacent main toolbar on the same logical edge.
+
+**Not when:**
+
+- Do not pad the pane itself or add wrapper insets around children that already own content-item geometry.
+- Do not leave an empty icon-only rail after collapsing a pane.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/layout.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- toolbar + content
+- toolbar + content + footer
+- hidden inline-start pane restored from main-toolbar leading
+- hidden inline-end pane restored from main-toolbar trailing
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [ContentItem](./content-item.md).
+
+## State and wiring
+
+**The app owns:** layout hierarchy; reading width; responsive relocation; pane visibility and matching collapse/restore controls.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Keep reading and focus order coherent when controls wrap or panes relocate, and preserve one scroll owner per pane.
+- When collapse replaces one control with its counterpart in another toolbar, move focus to the newly rendered restore or collapse control.
+
+## 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-content`, `kui-control-cluster`, `kui-inline-metadata`, `kui-scroll-owner`.
+
+Classes an application may place on its own elements: `kui-content`, `kui-control-cluster`, `kui-inline-metadata`, `kui-scroll-owner`.
+
+Public tokens it reads: `--kui-layout-control-gap`, `--kui-layout-content-gap`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-metadata-gap`, `--kui-layout-pill-radius`, `--kui-layout-rounded-radius`. 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: [ContentItem](./content-item.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/layout.md#public-roles-and-tokens`](../../docs/layout.md#public-roles-and-tokens).
+- UX catalog route: `?component=layout`.

package/ai/components/list-action-row.md

@@ -0,0 +1,108 @@
+# ListActionRow
+
+<!-- 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-action-row` · Kerf UI · component · Navigation
+
+Configurable navigation rows with structured labels, status/busy metadata, density, group dividers, and a primary native-button action beside a sibling trailing native button or trailing overflow PopupMenu.
+
+## When to use
+
+Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.
+
+- A navigation or item row needs both a primary selectable action and an independently focusable trailing action.
+- A command row needs a trailing "…" overflow menu (trailingMenu), optionally also opened at the pointer from the row's contextmenu with openPopupMenuAt.
+- A settings or command row identifies each entry by a colored icon tile (iconTile) instead of a bare glyph.
+
+**Not when:**
+
+- Use ListItem when trailing content is dormant metadata; use AppTab only for tablist semantics and ToolbarControlGroup only for toolbar controls.
+- Do not inject declaration strings; use className, public tokens, and cataloged component props for application styling.
+
+**Alternatives:**
+
+- [ListItem](./list-item.md) (nearest) — Trailing content is noninteractive.
+- [AppTab](./tabs.md) (semantic alternative) — The primary control selects a tabpanel inside TabBar.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-action-row` — exports `ListActionRow`.
+- CSS: the browser build of `@kerfjs/ui/list-action-row` pulls its CSS automatically; import `@kerfjs/ui/list-action-row.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-action-row`](../public-api-signatures-v1.md#kerfjsuilist-action-row), [`@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):**
+
+- selected
+- pressed
+- disabled primary
+- disabled trailing action
+- multiline
+- placeholder (loading)
+- compact density
+- description and status
+- busy while retaining content
+- interaction-revealed trailing action
+- trailing overflow menu
+- 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
+- draggable row with dragging and drop-before / drop-after insertion states
+- 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), [PopupMenu](./popup-menu.md).
+
+## State and wiring
+
+**The app owns:** routing; selection; action handling; domain data attributes; popover or context-menu policy; row order.
+
+**Wiring:** `wireListReorder`, `reorderListItems` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-dragging` on `ListActionRow 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 `ListActionRow 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.
+
+## Accessibility
+
+- The noninteractive root contains two sibling native buttons in primary-then-trailing focus order; each button has its own action, item identity, accessible name, and disabled state.
+- A trailingMenu replaces the trailing button with a PopupMenu trigger in the same position: an icon-only button named by trailingMenu.label that exposes aria-haspopup="menu" and aria-expanded, moves focus into the menu, and returns focus to the trigger on Escape or a choice.
+- Selection semantics are exposed only by the primary button; label, icon, and trailingActionIcon are dormant SafeHtml and must not contain interactive descendants; never place an interactive descendant in ListItem.trailing.
+- A draggable row is dragged by its noninteractive root; with wireListReorder, Alt+Shift+ArrowUp/ArrowDown on its primary button moves it, and focus returns to that button after the application re-renders.
+
+## 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-action-row`, `kui-list-action-row__icon`, `kui-list-action-row__label`, `kui-list-action-row__primary-label`, `kui-list-action-row__description`, `kui-list-action-row__status`, `kui-list-action-row__primary`, `kui-list-action-row__trailing-action`.
+
+Never put `kui-list-action-row`, `kui-list-action-row__icon`, `kui-list-action-row__label`, `kui-list-action-row__primary-label`, `kui-list-action-row__description`, `kui-list-action-row__status`, `kui-list-action-row__primary`, `kui-list-action-row__trailing-action` on an element you write; render `ListActionRow` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-border-loud`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-focus-ring`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-radius-pill`, `--kui-list-action-row-background`, `--kui-list-action-row-border`, `--kui-list-action-row-color`, `--kui-list-action-row-dragging-opacity`, `--kui-list-action-row-drop-indicator`, `--kui-list-action-row-drop-indicator-width`, `--kui-list-action-row-hover-background`, `--kui-list-action-row-hover-border`, `--kui-list-action-row-selected-background`, `--kui-list-action-row-selected-border`, `--kui-list-action-row-selected-color`, `--kui-list-action-row-trailing-hover-background`, `--kui-list-group-divider-color`, `--kui-list-row-padding-inline`, `--kui-list-row-icon-size`, `--kui-font-xs`, `--kui-radius-m`, `--kui-color-brand-fill-quiet`, `--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), [PopupMenu](./popup-menu.md), [ListItem](./list-item.md), [AppTab](./tabs.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-action-row`.

package/ai/components/list-header.md

@@ -0,0 +1,91 @@
+# ListHeader
+
+<!-- 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-header` · Kerf UI · component · Navigation
+
+Configurable section headings with five independent label sizes, full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.
+
+## When to use
+
+Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and optional count or combined badge/status indicators from a logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.
+
+- Label a navigation section with an optional semantic count or simultaneous badge and status indicators, plus an action or disclosure state; toggle mode supplies an 18px DisclosureArrow unless actionIcon replaces it.
+
+**Not when:**
+
+- Do not concatenate a section count into label or pass a bare number through badge; use count with its required localized countLabel for a sole section quantity.
+- Do not use as a page or dialog title.
+
+**Alternatives:**
+
+- [Toolbar](./toolbar.md) (nearest)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-header` — exports `ListHeader`.
+- CSS: the browser build of `@kerfjs/ui/list-header` pulls its CSS automatically; import `@kerfjs/ui/list-header.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list-header`](../public-api-signatures-v1.md#kerfjsuilist-header) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- heading
+- label sizes xs, sm (default), m, l, xl
+- count
+- badge
+- badge and status together
+- action
+- toggle
+- placeholder (loading)
+- inline shrink-wrapped presentation
+- compact density
+- neutral, accent, pop, or danger indicator tone
+- before, after, or paired group divider
+
+## Composition
+
+- Parents: any.
+- Contexts: `navigation-list`.
+- Children: unrestricted.
+- Built from: [Badge](./badge.md), [LucideIcon](./lucide-icon.md), [DisclosureArrow](./disclosure-arrow.md), [Text](./text.md).
+
+## State and wiring
+
+- expanded — controlled
+
+No wiring helper.
+
+## 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.
+
+## Accessibility
+
+- When toggle mode is used, the application reveals matching content and keeps expanded state synchronized.
+- The owning control retains a stable accessible 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-header`, `kui-list-header__action`, `kui-list-header__action-layer`, `kui-list-header__title`, `kui-list-header__toggle`.
+
+Never put `kui-list-header`, `kui-list-header__action`, `kui-list-header__action-layer`, `kui-list-header__title`, `kui-list-header__toggle` on an element you write; render `ListHeader` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-quiet`, `--kui-focus-ring`, `--kui-list-header-action-icon-size`, `--kui-list-header-border-width`, `--kui-list-header-color`, `--kui-list-header-min-height`, `--kui-list-header-title-min-height`, `--kui-list-header-title-padding-block`, `--kui-list-header-title-padding-inline`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-list-header-hover-background`, `--kui-list-group-divider-color`. 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-C103` (error) when toggle mode does not reveal matching controlled content: ListHeader expanded state must match real revealed content.
+
+## Related
+
+- Components: [Badge](./badge.md), [LucideIcon](./lucide-icon.md), [DisclosureArrow](./disclosure-arrow.md), [Text](./text.md), [Toolbar](./toolbar.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-header`.

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`.