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

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

package/ai/components/pane.md

@@ -0,0 +1,127 @@
+# 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).
+- Wiring: `wirePaneChrome` from `@kerfjs/ui/wire-pane-chrome` (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)
+- compactChrome { header, footer }: fixed, scroll, or overlay (opened by compactChromeOpen), applied by a NavStack view, TabNavigator scene, full-screen dialog, or compact Workbench
+
+## 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`, `wirePaneChrome` 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,174 @@
+# 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, drawn by Kerf as a native menu in the top layer.
+
+- 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.
+- Make a status Badge the trigger of a menu (a ticket status with a nested phase submenu): pass triggerContent with the Badge and label for the name, instead of wrapping the Badge in an application button.
+
+**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, document-listeners, 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
+- triggerContent: app content such as a Badge as the whole trigger, a bare button named by label with a pill focus ring
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [Tooltip](./wa-tooltip.md).
+
+## State and wiring
+
+**The app owns:** commands and their delegated actions; which items are enabled; the checked state of checkbox choices, which the menu reports as requested in its kui-menu-select event; 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
+
+- The trigger is a native button with aria-haspopup="menu" and aria-expanded; an icon-only trigger requires label, rendered as visually hidden text inside the button, and a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. The open menu (role="menu") takes the trigger's name, each submenu takes its parent item's label, and a heading names the role="group" that holds its items, so a screen reader announces named menus and getByRole('menu', { name }) finds them. Items are menuitem or menuitemcheckbox buttons with aria-checked and aria-disabled.
+- Keyboard: Enter, Space, or ArrowDown on the trigger opens on the first item (ArrowUp on the last); ArrowUp/ArrowDown move and wrap past disabled items, Home/End jump, and typing a label's first letters moves to it; Enter or Space chooses; ArrowRight opens a submenu on its first item and ArrowLeft returns to the parent item (mirrored right to left); Escape closes the current level and returns focus to its opener; Tab closes the menu and continues from the trigger.
+- Once registered, an icon-only trigger shows its label as an aria-hidden 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__trigger`, `kui-popup-menu__label`, `kui-popup-menu__menu`, `kui-popup-menu__item`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor`.
+
+Never put `kui-popup-menu`, `kui-popup-menu__trigger`, `kui-popup-menu__label`, `kui-popup-menu__menu`, `kui-popup-menu__item`, `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: [LucideIcon](./lucide-icon.md), [Tooltip](./wa-tooltip.md), [Select](./select.md), [Dropdown](./wa-dropdown.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/progress-bar.md

@@ -0,0 +1,82 @@
+# ProgressBar
+
+<!-- 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:progress-bar` · Kerf UI · component · Feedback
+
+A linear progress indicator on the native progress element: determinate value of max or an indeterminate sweep, a visible label or ariaLabel, an optional value or valueText readout, brand or status tones, and a default or compact track.
+
+## When to use
+
+Show how far a measurable task has gone (an upload, a migration, a quota) or that work of unknown size is under way.
+
+- A task reports measurable progress (files uploaded, steps completed, quota used): pass value and max, a label, and showValue or valueText for the readout.
+- Work of unknown length is under way and a full-width indicator fits: omit value for the indeterminate sweep.
+
+**Not when:**
+
+- Do not use it for a small inline busy state; use LoadingSpinner or an indeterminate ProgressRing.
+- Do not use it for a scale reading that is not progress (a rating, a level); use a native meter.
+- Do not use wa-progress-bar.
+
+**Alternatives:**
+
+- [ProgressRing](./progress-ring.md) (nearest) — Use a ProgressRing where a bar does not fit, inline in a row or toolbar.
+- [LoadingSpinner](./loading-spinner.md) (nearest) — Use a LoadingSpinner for a brief busy state with no measurable progress.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/progress-bar` — exports `ProgressBar`, `ProgressBarProps`, `ProgressBarSize`, `ProgressBarRootAttributes`, `ProgressTone`.
+- CSS: the browser build of `@kerfjs/ui/progress-bar` pulls its CSS automatically; import `@kerfjs/ui/progress-bar.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/progress-bar`](../public-api-signatures-v1.md#kerfjsuiprogress-bar) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- determinate with a label and value readout
+- indeterminate sweep
+- brand, success, warning, or danger tone
+- default 6px or compact 4px track
+- ariaLabel without a visible label
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the value, max, and valueText; the label or ariaLabel; the tone and size.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- It fills the available width with the shared block-content inset (a transparent 1px border and 8px padding); the label row sits 4px above the track.
+
+## Accessibility
+
+- The native progress element is the progressbar: a visible label names it through aria-labelledby (or ariaLabel without one), and valueText replaces the spoken percentage.
+- The indeterminate sweep holds still under prefers-reduced-motion or the static-effects switch; forced colors draw a CanvasText-bordered track with a Highlight fill.
+
+## 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-progress-bar`, `kui-progress-bar__header`, `kui-progress-bar__label`, `kui-progress-bar__value`, `kui-progress-bar__track`.
+
+Never put `kui-progress-bar`, `kui-progress-bar__header`, `kui-progress-bar__label`, `kui-progress-bar__value`, `kui-progress-bar__track` on an element you write; render `ProgressBar` 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: [ProgressRing](./progress-ring.md), [LoadingSpinner](./loading-spinner.md).
+- Docs: [`docs/progress.md`](../../docs/progress.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=progress-bar`.

package/ai/components/progress-ring.md

@@ -0,0 +1,80 @@
+# ProgressRing
+
+<!-- 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:progress-ring` · Kerf UI · component · Feedback
+
+A circular progress indicator: an SVG track and arc, determinate (filling clockwise from the top) or an indeterminate spinning arc, in small, medium, and large sizes to sit inline in text, a row, or a toolbar, as a named progressbar.
+
+## When to use
+
+Show compact progress (a claim's time remaining, a per-row upload) where a bar does not fit.
+
+- Progress belongs beside an item in a row, a toolbar, or a line of text: pass value and max, a label, and valueText for speech.
+- A compact indicator of work of unknown length: omit value for the spinning arc.
+
+**Not when:**
+
+- Do not use it where a full-width readout fits and the amount matters; use ProgressBar.
+- Do not use wa-progress-ring.
+
+**Alternatives:**
+
+- [ProgressBar](./progress-bar.md) (nearest) — Use a ProgressBar where a full-width bar with a label row fits.
+- [LoadingSpinner](./loading-spinner.md) (nearest) — Use a LoadingSpinner for a brief busy glyph inside a control.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/progress-ring` — exports `ProgressRing`, `ProgressRingProps`, `ProgressRingSize`, `ProgressRingRootAttributes`, `ProgressTone`.
+- CSS: the browser build of `@kerfjs/ui/progress-ring` pulls its CSS automatically; import `@kerfjs/ui/progress-ring.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/progress-ring`](../public-api-signatures-v1.md#kerfjsuiprogress-ring) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- determinate arc
+- indeterminate spinning arc
+- small (16px), medium (24px), or large (40px)
+- brand, success, warning, or danger tone
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the value, max, and valueText; the label; the tone and size.
+
+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.
+
+- Its box is exactly its diameter, so it aligns with icons of the same size.
+
+## Accessibility
+
+- It is role progressbar named by label, with aria-valuenow as a percentage (or valueText); the SVG is decorative.
+- The spin holds still under prefers-reduced-motion or the static-effects switch; forced colors draw a GrayText track and a Highlight arc.
+
+## 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-progress-ring`, `kui-progress-ring__track`, `kui-progress-ring__arc`.
+
+Never put `kui-progress-ring`, `kui-progress-ring__track`, `kui-progress-ring__arc` on an element you write; render `ProgressRing` 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: [ProgressBar](./progress-bar.md), [LoadingSpinner](./loading-spinner.md).
+- Docs: [`docs/progress.md`](../../docs/progress.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=progress-ring`.