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

package/ai/components/nav-stack.md

@@ -0,0 +1,103 @@
+# 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 TabScaffold.
+
+**Alternatives:**
+
+- [SplitView](./split-view.md) (roomy-alternative) — Promote a list-to-detail stack to SplitView once both regions fit together.
+- [TabScaffold](./tab-scaffold.md) (composes-with) — Use one NavStack as each TabScaffold tab's persistent content.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/nav-stack` — exports `NavStackView`, `NavStackToolbarConfig`, `NavStackProps`, `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 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)
+
+## 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 titles; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar content or a persistent fallback; per-view leading, center, and trailing top-toolbar groups; top-toolbar configuration, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
+
+**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-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
+- `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.
+
+## 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.
+
+## 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.
+
+## 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), [TabScaffold](./tab-scaffold.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`.

package/ai/components/pane.md

@@ -0,0 +1,100 @@
+# Pane
+
+<!-- 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:pane` · Kerf UI · component · Structure
+
+An unpadded application column with optional vertical header/footer slots, one scrolling vertical content stack, and independent logical-edge separators.
+
+## When to use
+
+Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.
+
+- An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.
+- A pane boundary needs an opt-in separator on any combination of logical sides.
+- Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers).
+
+**Not when:**
+
+- Do not use Pane as a padded card or add a competing scroll owner around its content slot.
+- Do not enable separators merely as decoration; use them only where the pane owns a real boundary.
+
+**Alternatives:**
+
+- [Application layout](./layout.md) (composes-with) — Use the layout content-item and control classes inside Pane when children need shared geometry.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/pane` — exports `Pane`, `wireScrollDividers`.
+- CSS: the browser build of `@kerfjs/ui/pane` pulls its CSS automatically; import `@kerfjs/ui/pane.css` manually only without the `browser` export condition.
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/pane`](../public-api-signatures-v1.md#kerfjsuipane), [`@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):**
+
+- content only
+- header + content
+- header + content + footer
+- block-start separator
+- block-end separator
+- inline-start separator
+- inline-end separator
+- chrome dividers only while scrolled (default, wired by wireScrollDividers)
+- always or no chrome dividers
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-column`, `sidebar`, `main-content`, `inspector`, `dialog-column`.
+- Children: unrestricted.
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `header` — JSX prop `header`; accepts `fixed-chrome`; any number.
+- `content` — JSX prop `children`; accepts `pane-content`; any number.
+- `footer` — JSX prop `footer`; accepts `fixed-chrome`; any number.
+
+## State and wiring
+
+**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers).
+
+**Wiring:** `wireScrollDividers` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `kui-pane__content` (`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-pane__header and kui-pane__footer` (`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.
+
+## Geometry
+
+Margin: child · 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 pane is unpadded; separators are independently opt-in on logical edges and default off.
+- Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-\*); content block insets are scroll padding.
+
+## Accessibility
+
+- Choose semantic root and content elements that match the region and provide labels for landmark elements.
+- Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent.
+
+## 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-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar`.
+
+Never put `kui-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar` on an element you write; render `Pane` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Application layout](./layout.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/layout.md#anatomy`](../../docs/layout.md#anatomy).
+- UX catalog route: `?component=pane`.

package/ai/components/popup-menu.md

@@ -0,0 +1,82 @@
+# PopupMenu
+
+<!-- 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:popup-menu` · Kerf UI · component · Controls
+
+## When to use
+
+A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.
+
+- Offer a short list of commands behind one trigger, such as a toolbar sort or More menu.
+- Group related commands under headings and dividers in one popup.
+
+**Not when:**
+
+- Do not use it to choose a persistent value (use Select) or for navigation rows (use ListItem).
+- Do not hand-write wa-dropdown / wa-dropdown-item markup for an action menu; use PopupMenu.
+
+**Alternatives:**
+
+- [Select](./select.md) (nearest)
+- [Dropdown](./wa-dropdown.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/popup-menu` — exports `PopupMenu`.
+- CSS: the browser build of `@kerfjs/ui/popup-menu` pulls its CSS automatically; import `@kerfjs/ui/popup-menu.css` manually only without the `browser` export condition.
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@kerfjs/ui/popup-menu/register` once (a side effect).
+- Declared side effects: browser-condition-css, custom-element-registration.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/popup-menu`](../public-api-signatures-v1.md#kerfjsuipopup-menu) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- icon trigger
+- text trigger
+- icon and text trigger
+- headings and dividers
+- item icons
+- disabled items
+- placement
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md), [Button](./wa-button.md), [Divider](./wa-divider.md).
+
+## State and wiring
+
+**The app owns:** commands and their delegated actions; which items are enabled; reactions to the menu opening or closing.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape.
+- Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-popup-menu`, `kui-popup-menu__label`.
+
+Never put `kui-popup-menu`, `kui-popup-menu__label` on an element you write; render `PopupMenu` 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: [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md), [Button](./wa-button.md), [Divider](./wa-divider.md), [Select](./select.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- UX catalog route: `?component=popup-menu`.

package/ai/components/recipe-app-shell.md

@@ -0,0 +1,57 @@
+# Desktop application shell
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:recipe-app-shell` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
+
+- A desktop workspace needs persistent chrome and user-adjustable navigation or inspector panes.
+
+**Not when:**
+
+- Use ordinary CSS grid when panes are static or the product does not need a user-operable separator.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** routing; pane visibility; pane sizes and persistence; workspace data.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each pane has one scroll owner and each resize handle keeps its separator keyboard contract.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Workbench](./workbench.md), [List](./list.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md).
+- Docs: [`docs/recipes.md#desktop-application-shell`](../../docs/recipes.md#desktop-application-shell).
+- UX catalog route: `?component=recipe-app-shell`.

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

@@ -0,0 +1,57 @@
+# Collapsible sidebar
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:recipe-collapsible-sidebar` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.
+
+- A rail or drawer must collapse and expand outside a full Workbench shell, keeping the app's collapsed signals, sizes, and content while the wire owns toggle, focus, the compact overlay, and persistence.
+
+**Not when:**
+
+- Use the Workbench layout when the whole screen is a three-pane shell; use an ordinary always-visible sidebar when it never collapses.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+
+## State and wiring
+
+**The app owns:** each panel's collapsed signal; panel sizes; routing and selection; content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each panel is a labeled aside that is aria-hidden while collapsed; toggles carry aria-expanded and the standard per-side glyph; while compact an open panel is an overlay with a backdrop, Escape and backdrop-click dismiss, and a trapped Tab ring.
+
+## 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: [CollapsiblePanel](./collapsible-panel.md), [Pane](./pane.md), [Row](./row.md), [List](./list.md), [Grid](./grid.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [Text](./text.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Application layout](./layout.md), [ContentItem](./content-item.md).
+- Docs: [`docs/recipes.md#collapsible-sidebar`](../../docs/recipes.md#collapsible-sidebar).
+- UX catalog route: `?component=recipe-collapsible-sidebar`.

package/ai/components/recipe-compact-toolbar.md

@@ -0,0 +1,57 @@
+# Compact toolbar choices and actions
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:recipe-compact-toolbar` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.
+
+- A dense workspace toolbar mixes a few distinct control semantics.
+
+**Not when:**
+
+- Do not group unrelated actions or use buttons to imitate selection controls.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [LucideIcon](./lucide-icon.md), [Grid](./grid.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md).
+
+## State and wiring
+
+**The app owns:** controlled values; actions; persistence; responsive priority.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Each control retains its own native name, pressed/value state, and keyboard contract.
+
+## 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), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [LucideIcon](./lucide-icon.md), [Grid](./grid.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md).
+- Docs: [`docs/recipes.md#compact-toolbar-choices-and-actions`](../../docs/recipes.md#compact-toolbar-choices-and-actions).
+- UX catalog route: `?component=recipe-compact-toolbar`.

package/ai/components/recipe-composer-form.md

@@ -0,0 +1,57 @@
+# Composer form
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:recipe-composer-form` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.
+
+- A short form needs one coherent surface, consistent field/action rhythm, and persistent validation feedback.
+
+**Not when:**
+
+- Do not turn each form section into another visible card or use the recipe as a generic form engine or transport abstraction.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** validation rules; draft persistence; permissions; transport.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The form references its ToolbarText title and supporting-summary ids; production fields own labels and help; invalid submission creates an assertive persistent StateBanner while successful submission creates a polite persistent banner.
+
+## 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), [ToolbarText](./toolbar-text.md), [List](./list.md), [ListInsetText](./list-inset-text.md), [Text](./text.md), [Row](./row.md), [Select](./select.md), [StateBanner](./state-banner.md), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Button](./wa-button.md), [Application layout](./layout.md).
+- Docs: [`docs/recipes.md#composer-form`](../../docs/recipes.md#composer-form).
+- UX catalog route: `?component=recipe-composer-form`.

package/ai/components/recipe-list-detail-dialog.md

@@ -0,0 +1,57 @@
+# List-detail dialog
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:recipe-list-detail-dialog` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Production modal laid out as a workbench: a full-height SplitView list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
+
+- A focused task compares several records without leaving the current workspace.
+
+**Not when:**
+
+- Use a page when the task needs a durable route or substantially more working space.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css, individual-custom-element-registration.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Surface scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
+
+## State and wiring
+
+**The app owns:** open state; selected record; pushed compact detail; dismiss policy; record actions.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Web Awesome owns modal focus, Escape, and the labeled header with its close control; the application adapter restores the invoking control after hide, and the compact NavStack back control returns to the list.
+
+## 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: [Surface scaffolds](./surface-scaffold.md), [SplitView](./split-view.md), [NavStack](./nav-stack.md), [Row](./row.md), [List](./list.md), [ListHeader](./list-header.md), [ListItem](./list-item.md), [ValueTable](./value-table.md), [LucideIcon](./lucide-icon.md), [Dialog](./wa-dialog.md), [Button](./wa-button.md).
+- Docs: [`docs/recipes.md#list-detail-dialog`](../../docs/recipes.md#list-detail-dialog).
+- UX catalog route: `?component=recipe-list-detail-dialog`.

package/ai/components/recipe-list-workspace-states.md

@@ -0,0 +1,57 @@
+# List workspace states
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:recipe-list-workspace-states` · Kerf UI · production recipe · Recipes
+
+## When to use
+
+Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
+
+- A list surface must communicate initial load, absence, background refresh, failure, and recovery.
+
+**Not when:**
+
+- Do not replace domain rows with a generic component or use transient toasts as the only error record.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: lazy-recipe-css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+## Composition
+
+- Parents: used at the root of a screen or reference, not nested.
+- Contexts: `application-reference`.
+- Children: unrestricted.
+- Built from: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application layout](./layout.md).
+
+## State and wiring
+
+**The app owns:** fetching; cache age; retry policy; domain rows.
+
+No wiring helper.
+
+## Geometry
+
+Margin: composed · border: composed · padding: composed (layout role: reference-composition). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Busy, polite, and assertive states use the appropriate production feedback semantics.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [ListItem](./list-item.md), [Row](./row.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md), [LoadingSpinner](./loading-spinner.md), [Application layout](./layout.md).
+- Docs: [`docs/recipes.md#list-workspace-states`](../../docs/recipes.md#list-workspace-states).
+- UX catalog route: `?component=recipe-list-workspace-states`.