@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

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,125 @@
+# 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.
+
+**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
+- multi-select grid for rich ContentItem rows
+
+**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,97 @@
+# 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)
+
+## 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.
+
+## 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/nav-stack.md

@@ -0,0 +1,120 @@
+# NavStack
+
+<!-- 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:nav-stack` · Kerf UI · component · Structure
+
+A controlled one-pane navigation stack that keeps prior views mounted, slides content on push and pop, cross-fades per-view chrome, and moves/restores focus.
+
+## When to use
+
+Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.
+
+- A compact surface shows one view at a time and navigation pushes into details or pops back.
+- A simple single-pane screen needs the same stable app-layout contract without any nested navigation.
+
+**Not when:**
+
+- Do not use NavStack when a list and detail should remain visible together; use SplitView.
+- Do not use it for co-equal top-level destinations on compact devices; wrap one stack per destination in TabNavigator.
+
+**Alternatives:**
+
+- [SplitView](./split-view.md) (roomy-alternative) — Promote a list-to-detail stack to SplitView once both regions fit together.
+- [TabNavigator](./tab-navigator.md) (composes-with) — Use one NavStack as each TabNavigator tab's persistent content.
+- [ContentSwap](./content-swap.md) (nearest) — Use ContentSwap to swap content in place inside one region without navigation chrome.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/nav-stack` — exports `NavStackView`, `NavStackToolbarConfig`, `NavStackProps`, `NavStackChromePresentation`, `NavStackBottomToolbarPresentation`, `NavStack`.
+- CSS: the browser build of `@kerfjs/ui/nav-stack` pulls its CSS automatically; import `@kerfjs/ui/nav-stack.css` manually only without the `browser` export condition.
+- Wiring: `wireNavStack` from `@kerfjs/ui/wire-nav-stack` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1.md#kerfjsuinav-stack), [`@kerfjs/ui/wire-nav-stack`](../public-api-signatures-v1.md#kerfjsuiwire-nav-stack), [`@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):**
+
+- single root view
+- pushed detail view
+- toolbar hidden
+- configured top toolbar
+- custom back icon or visible back text
+- per-view bottom toolbar
+- persistent final top-toolbar group (panelToggle) when embedded in a Workbench panel
+- persistent bottom-toolbar fallback
+- chrome and bottom-toolbar dividers only while the active view scrolls beneath them (wired by wireScrollDividers)
+- permanent or no chrome dividers (chromeDividers always or none)
+- translucent top chrome laid over the active view (chromePresentation overlay, measured by wireNavStack)
+- translucent bottom toolbar laid over the active view (bottomToolbarPresentation overlay, measured by wireNavStack)
+- app-chosen stack background color (background); overlay chrome keeps the chrome material
+- scoped tint (tint)
+- clear (transparent) bars with an optional scroll-edge material (chromePresentation / bottomToolbarPresentation: clear, scrollEdge: material)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md).
+
+## State and wiring
+
+**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; per-view leading, center, and trailing top-toolbar groups; per-view header and footer with List and Pane configuration; top-toolbar defaults, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers); whether the top chrome docks above the active view or lies over it on the translucent chrome material (chromePresentation); whether the bottom toolbar docks below the active view or lies over it on the translucent chrome material (bottomToolbarPresentation); an optional app-chosen color for the stack, its docked chrome and bottom toolbar, and every view (background, a typed CssColor); one view's own color goes in its pane: { background }; an optional scoped tint for the stack, its chrome, and views: tint: { color, scheme } re-derives surface and text tokens from an app color with text kept at AA.
+
+**Wiring:** `wireNavStack`, `wireScrollDividers` is required.
+
+- Use wireNavStack as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-nav-chrome-transition` on `kui-nav-stack` (`wireNavStack`): "true" while the chrome cross-fades between the outgoing and incoming view.
+- `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
+- `data-nav-revealed` on `kui-nav-stack__view` (`wireNavStack`): "true" on the preserved, aria-hidden previous view while an incoming view slides over it.
+- `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
+- `data-chrome-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured an overlay chrome (chromePresentation: overlay) and published its border-box height on the stack root; the chrome then lies over the active view, which clears it through the block-start edge context. Both are re-applied if a re-render drops them.
+- `data-bottom-toolbar-overlay` on `kui-nav-stack` (`wireNavStack`): measured once the helper has measured an overlay bottom toolbar (bottomToolbarPresentation: overlay) and published its border-box height on the stack root; the toolbar then lies over the active view, which clears it through the block-end edge context. Both are re-applied if a re-render drops them.
+- `data-scroll-overflow` on `the active kui-nav-stack__view, or the kui-pane__content of a sole Pane in it` (`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 `kui-nav-stack__chrome and kui-nav-stack__bottom` (`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: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content.
+- The top chrome's bottom line and the bottom toolbar's top line are scroll state (wireScrollDividers), drawn as an overlaid 1px pseudo-element on the chrome and the bottom toolbar's always-present 1px top border, so neither moves the chrome or the content.
+- chromePresentation overlay: once wireNavStack measures the live chrome (never a cross-fading copy), the chrome lies over the viewport's top edge and its border-box height, top safe area included, becomes the viewport's block-start --kui-edge-inset-\* context, so a plain view, a sole Pane, or a nested layout pads and scroll-pads by it automatically; the chrome ends where a classic scrollbar in the active view begins, so its track stays uncovered; unwired, or with hideToolbar, the chrome stays docked.
+- bottomToolbarPresentation overlay: once wireNavStack measures the live bottom toolbar (never a cross-fading copy), the toolbar lies over the viewport's bottom edge and its border-box height, bottom safe area and divider border included, becomes the viewport's block-end --kui-edge-inset-\* context, so a plain view, a sole Pane (its content, or its footer), or a nested layout pads and scroll-pads by it automatically and the last item rests just above the toolbar; it ends where a classic scrollbar in the active view begins; unwired, or while no bottom toolbar is shown, it stays docked. It is independent of chromePresentation, which governs only the top chrome.
+
+## Accessibility
+
+- Give the stack region an accessible label and every back control a stable action label; visible backText names the control itself.
+- Set toolbarConfig.headingLevel when the view title is the page's or section's heading landmark.
+- Use wireNavStack so each controlled push moves focus into the new top view and each pop restores the revealed view's remembered descendant.
+- Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target.
+- Overlay chrome (chromePresentation overlay) keeps WCAG AA over content passing beneath the translucent material: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it; keep other quiet copy in the view. The material turns opaque under reduced transparency, increased contrast, forced colors, or without backdrop-filter.
+- An overlay bottom toolbar (bottomToolbarPresentation overlay) keeps the same AA rule: an untoned ToolbarText there lifts its title and description, and a default-tone ToolbarControlGroup in either overlaid bar takes the normal text color for its controls. Its 1px top edge stays visible in forced colors.
+- A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.
+- Clear bars have no material of their own: keep their controls in glass ToolbarControlGroups; they turn opaque under reduced transparency or increased contrast and paint Canvas in forced colors.
+
+## 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-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting`.
+
+Never put `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting` on an element you write; render `NavStack` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-nav-stack-transition-duration`. 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: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [SplitView](./split-view.md), [TabNavigator](./tab-navigator.md), [ContentSwap](./content-swap.md).
+- Docs: [`docs/nav-stack.md`](../../docs/nav-stack.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
+- UX catalog route: `?component=nav-stack`.