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

package/ai/components/pane.md

@@ -0,0 +1,125 @@
+# 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).
+- A lowered background must cover the scrolling work viewport and blank space after short content without a second scroll container (appearance: sunken).
+- A child table or other component needs edge-to-edge decoration with text aligned to other pane content.
+- An opaque edge-to-edge child needs a reserved vertical scrollbar gutter.
+- Scrolling content must pass beneath chrome laid over the pane edge (a DialogSurface floating footer) while its first and last items still rest clear of it (scrollClearance).
+- The header should float over the scrolling content on a translucent material so content scrolls visibly beneath it, with the first item still resting below the header (headerPresentation: overlay, measured by wireScrollDividers).
+- A pane needs an app-chosen surface color, such as a media detail page painted in its artwork's color (background, a typed CssColor; also in PaneConfig).
+- A region should take on an app color (a media page in its artwork's color) with its text, quiet text, links, fills, and chrome material re-derived to keep AA (tint: { color, scheme }; also in PaneConfig).
+- The header lies over imagery and must be fully transparent, with glass control groups for legibility and the material fading back in once content scrolls beneath (headerPresentation: clear, scrollEdge: material).
+
+**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.
+- A ToolbarText description in an overlay header is fine: an untoned ToolbarText there takes the normal text color for its title and lifts its description halfway toward it, keeping AA over the content passing beneath. Do not put other quiet secondary text in an overlay header; keep it in the content.
+
+**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
+- scrollClearance block-start, block-end, or both on the scrolling content
+- overlay header on the translucent chrome material (headerPresentation: overlay)
+- app-chosen background color (background), replacing the default or sunken fill
+- scoped tint re-deriving surface and text tokens from an app color (tint)
+- clear (transparent) overlay header, optionally with the scroll-edge material (headerPresentation: clear, scrollEdge: material)
+
+## 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); default or sunken scrolling work surface (appearance); whether to reserve a vertical scrollbar gutter for opaque edge-to-edge content (--kui-pane-scrollbar-gutter); optional keyboard or programmatic focus (tabIndex) and persistent focus outline (outlined); whether the scrolling content clears overlaying chrome on its block edges (scrollClearance, also in PaneConfig, so a Workbench mainPane or panel pane, a CollapsiblePanel pane, or a NavStack view pane forwards it); whether the header is docked in its own row or laid over the scrolling content on the translucent chrome material (headerPresentation, also in PaneConfig); an optional app-chosen surface color that replaces the appearance's fill (background, a typed CssColor from @kerfjs/ui/css-values, also in PaneConfig, so a Workbench panel or mainPane, a CollapsiblePanel pane, or a NavStack view pane forwards it); an optional scoped tint (tint: { color, scheme }, also in PaneConfig): the color and the declared light or dark scheme it belongs to; Kerf does no color detection; an optional tint accent (tint.accent) that re-derives the brand ramp, links, and focus ring inside the tinted scope at AA.
+
+**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.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured an overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root (and a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered); the header then lies over the content, which clears it. Both are re-applied if a re-render drops them.
+
+## 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.
+- The scrolling content exposes its resolved logical inline padding to descendants as --kui-pane-content-inset-inline-start/end, including safe areas and deepInset.
+- deepInset adds --kui-space-xs to every side of the scrolling content and its block scroll padding; header/footer chrome still owns safe-area padding at its edge.
+- For opaque edge-to-edge children, --kui-pane-scrollbar-gutter: stable reserves a vertical scrollbar gutter outside the published content insets; the default is auto.
+- scrollClearance adds the inherited --kui-scroll-clearance-block-start/end context, published by overlaying chrome, to the scrolling content block padding and scroll padding alongside safe areas and deepInset.
+- headerPresentation overlay: once wireScrollDividers measures the header, the header shares the content cell above the scroller, its border-box height is published as --kui-scroll-clearance-block-start on the Pane root, and the content clears it automatically; unwired or with chromePlacement auto, the header stays docked.
+- The scrolling content also publishes its resolved block-start padding (safe area, deepInset, and overlay or clear header clearance) as --kui-pane-content-inset-block-start, so a first child such as an underChrome BackdropImage can run up beneath it.
+
+## 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.
+- An overlay header's text uses the normal text color, which keeps WCAG AA over the 80% chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
+- 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.
+- A tint clamps the re-derived surface and text lightness so normal, quiet, link, and neutral-on-quiet text keep 4.5:1 over the tinted surface, raised surface, and quiet fills for any color; under prefers-contrast: more or without relative color syntax the scope keeps the plain palette in its declared scheme.
+- A clear header has no material of its own: keep its controls in glass ToolbarControlGroups and a title over imagery on a scrim; it turns opaque under reduced transparency or increased contrast and paints 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-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`, `--kui-pane-chrome-background`, `--kui-pane-content-inset-inline-start`, `--kui-pane-content-inset-inline-end`, `--kui-pane-scrollbar-gutter`, `--kui-sunken-panel-background`, `--kui-chrome-material`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`. 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,171 @@
+# 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 typed action menu with nested choices, selected state, and optional pointer-anchored context opening, 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.
+- Nest decisions under a parent command, show checked or trailing choice state, or open a context menu at pointer coordinates.
+
+**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`, `openPopupMenu`, `openPopupMenuAt`, `closePopupMenu`.
+- 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
+- nested actions
+- checked choices and trailing details
+- danger tone and disabled reasons
+- context trigger with a rendered anchor point and a zero-footprint anchor host
+- 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; contextmenu event handling and identification of the menu root when using a pointer-anchored context menu.
+
+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. The context anchor stays out of the accessibility tree. The open menu takes the trigger's name (the context or icon-only label, or the visible text), and each submenu takes its parent item's label, so a screen reader announces a named menu and getByRole('menu', { name }) finds it. Web Awesome provides menu roles, nested 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.
+
+## Usage examples
+
+### Nested decisions
+
+The app owns the current decision, batch disabled state, and delegated actions. Each child keeps its own record metadata.
+
+```tsx
+<PopupMenu
+  label="Line actions"
+  items={[
+    {
+      label: 'Decide',
+      submenu: [
+        {
+          label: 'Approve',
+          action: 'decide',
+          checked: current === 'approve',
+          attributes: { 'data-line-id': lineId, 'data-decision': 'approve' },
+        },
+        {
+          label: 'Reject',
+          action: 'decide',
+          tone: 'danger',
+          disabled: needsPrice,
+          disabledReason: needsPrice ? 'Add a price first' : undefined,
+          attributes: { 'data-line-id': lineId, 'data-decision': 'reject' },
+        },
+      ],
+    },
+    { kind: 'divider' },
+    { label: 'Remove', action: 'remove', tone: 'danger' },
+  ]}
+/>
+```
+
+### Flat selected choices
+
+Headings separate sort dimensions; trailing safe content marks the active command without changing its accessible label.
+
+```tsx
+<PopupMenu
+  label="Sort chat"
+  items={[
+    { kind: 'heading', label: 'Sort By' },
+    {
+      label: 'Updated',
+      action: 'sort-updated',
+      details: sort === 'updated' ? tick : undefined,
+    },
+    {
+      label: 'Priority',
+      action: 'sort-priority',
+      details: sort === 'priority' ? tick : undefined,
+    },
+    { kind: 'heading', label: 'Order' },
+    {
+      label: 'Newest First',
+      action: 'order-newest',
+      details: order === 'newest' ? tick : undefined,
+    },
+  ]}
+/>
+```
+
+### Pointer anchored context menu
+
+Keep the row's visible disabled action separate from the context menu anchor. Find the menu root with a stable data attribute.
+
+```tsx
+<PopupMenu
+  context
+  label="Demand Actions"
+  rootAttributes={{ 'data-demand-menu': '' }}
+  items={[{ label: 'Open', action: 'open-demand' }]}
+/>;
+// In the app's row wiring:
+row.addEventListener('contextmenu', (event) => {
+  event.preventDefault();
+  const menu = row.querySelector('[data-demand-menu]') as PopupMenuElement;
+  openPopupMenuAt(menu, event.clientX, event.clientY);
+});
+// Call closePopupMenu(menu) when the app needs to dismiss it.
+```
+
+## 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`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor`.
+
+Never put `kui-popup-menu`, `kui-popup-menu__label`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor` 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#popup-menu-migration`](../../docs/component-selection.md#popup-menu-migration).
+- 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`.