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

package/ai/components/README.md

@@ -0,0 +1,206 @@
+# @kerfjs/ui component reference
+
+<!-- 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`. -->
+
+One short page per catalog entry. Pick a component by the interface need from the one-line purposes below, then open only the pages you use. Each page lists when to use and avoid it, imports and CSS/registration side effects, where its exact props live, legal parents, zones with their JSX props and child counts, which state the app owns and which a wiring helper owns, geometry ownership, accessibility obligations, the styling boundary (configure through props; never override internals), and its `KUI-C` diagnostics.
+
+Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-api-signatures-v1.md) (Web Awesome JSX in [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md)). Tools and linters read the canonical machine sources instead: [`component-catalog.json`](../component-catalog.json) (selection and delivery) and [`component-composition.json`](../component-composition.json) (composition), joined by `package:id`. Prefer a Kerf UI component over a Web Awesome element whenever both fit.
+
+## Kerf UI — Foundation
+
+- [Badge](./badge.md) — Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+- [Chip](./chip.md) — Render removable tags, file or link chips, and activatable action chips without application rules on Web Awesome internals or anchor and button chrome.
+- [LucideIcon](./lucide-icon.md) — Decorative and meaningfully labeled Lucide-compatible icons.
+- [DisclosureArrow](./disclosure-arrow.md) — Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
+- [Foundation Tokens](./foundation.md) — Provide the shared semantic token foundation for application themes and every styled Kerf UI component.
+- [Document Baseline](./document-baseline.md) — Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
+- [Application Layout](./layout.md) — Provide one reusable pane, toolbar, content stack, and content-item geometry across sidebars, main areas, and dialogs.
+
+## Kerf UI — Structure
+
+- [Pane](./pane.md) — Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.
+- [NavStack](./nav-stack.md) — Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.
+- [SplitView](./split-view.md) — Present a selectable list and its detail together when space permits, with a one-pane drill-down replacement on compact devices.
+- [TabNavigator](./tab-navigator.md) — Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.
+- [Workbench](./workbench.md) — Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.
+- [CollapsiblePanel](./collapsible-panel.md) — Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
+- [SunkenPanel](./sunken-panel.md) — Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.
+- [BackdropImage](./backdrop-image.md) — Open a scrolling Pane or NavStack view with a hero or tiled backdrop image (an artist, album, or place page) that lags the scroll and progressively blurs on a compositor-only scroll timeline, dissolves through a mask into an app-chosen color, and continues that color under the following content, with Kerf-owned static fallbacks.
+- [Toolbar](./toolbar.md) — Leading, centered, and trailing toolbar composition.
+- [ToolbarControlGroup](./toolbar-control-group.md) — Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
+- [Surface Scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
+- [ListDetailDialog](./list-detail-dialog.md) — Present a selectable list beside the selected item's detail inside a modal, with the dialog's title and close control in the detail column and a one-pane drill-down on compact devices.
+- [WorkbenchDialog](./workbench-dialog.md) — Present an editing task with side panels (layers, an inspector) inside a modal, with the dialog's title and close control in the work area and rails that overlay the work area on compact devices instead of narrowing it.
+- [FloatingToolbar](./floating-toolbar.md) — A transparent, forced-dark toolbar that floats over its container's content.
+- [ToolbarText](./toolbar-text.md) — Extra-large through extra-small toolbar identity text.
+- [Text](./text.md) — Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact through extra-large size, or monospace font.
+- [Headers](./headers.md) — Page, dialog, and definition-list hierarchy.
+- [ValueTable](./value-table.md) — Key/value rows with optional icons and aligned separators.
+- [FramedList](./framed-list.md) — Group settings-style rows of arbitrary content (copy, keycaps, controls) in one framed surface with between-row dividers and an optional highlighted row, without app list CSS.
+- [SummaryRow](./summary-row.md) — Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.
+- [Row](./row.md) — Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full/baseline alignment instead of application-owned flex wrappers.
+- [Grid](./grid.md) — Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.
+- [ColumnTrack](./column-track.md) — Lay out a board of columns (kanban) as one horizontal scroll owner: equal columns that never shrink below a minimum, or a paged phone layout with a peeking next column and start snapping, without app track CSS.
+- [ContentSwap](./content-swap.md) — Swap arbitrary content in place (a dialog body that steps to a second page, a label or footer whose actions change) with Kerf-owned push or crossfade motion, reduced-motion handling, and an inert, hidden inactive side.
+- [Spacer](./spacer.md) — Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.
+- [ListInsetControl](./list-inset-control.md) — Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
+- [ListInsetText](./list-inset-text.md) — Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
+- [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
+- [Disclosure](./disclosure.md) — Keep secondary or optional content one press away under a summary, or let a person open one of several sections at a time.
+
+## Kerf UI — Navigation
+
+- [List](./list.md) — Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.
+- [ListHeader](./list-header.md) — Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and optional count or combined badge/status indicators from a logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.
+- [ListActionRow](./list-action-row.md) — Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.
+- [ListItem](./list-item.md) — Selectable, disabled, trailing, and multiline action or link rows.
+- [Application Tabs](./application-tabs.md) — Show TabBarItem and TabBar in a complete controlled composition.
+- [TabBarItem](./tabs.md) — Render a controlled application tab with compact or icon-only presentation, a visible drop target, optional full-name display, and an optional pinned leading position.
+- [TabBar](./tab-bar.md) — Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
+
+## Kerf UI — Controls
+
+- [SegmentedControl](./segmented-control.md) — Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
+- [ChoiceChips](./choice-chips.md) — Choose one value, or with multiple any number of values, from a visible set too large for a segmented track, such as a color palette with labeled swatches or a set of annotation intents.
+- [ColorSwatches](./color-swatches.md) — Let a person choose one color from a small fixed palette (a label, tag, or command color), or no color.
+- [ColorPicker](./color-picker.md) — Let a person choose any color precisely, by dragging, typing channel or hex values, sampling the screen, or picking a preset or saved sample.
+- [ColorField](./color-field.md) — Put a color choice in a form or inspector without keeping a full picker open.
+- [MessageComposer](./message-composer.md) — Write a chat message or prompt in a raised frame whose border turns brand while focus is within, with a field that grows between row bounds and a trailing send action.
+- [SearchField](./search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+- [TagField](./tag-field.md) — Collect a list of short values (labels, recipients, keywords) as removable tags, each submitted as its own form value.
+- [ResizableRegion](./resize.md) — Pointer and keyboard-operable split region with a customizable handle icon.
+- [Select](./select.md) — Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
+- [Combobox](./combobox.md) — Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.
+- [TextField](./text-field.md) — Collect free text (names, addresses, notes, comments) with Kerf's field chrome, a visible or accessible label, supporting and validation text, and native input semantics.
+- [Checkbox](./checkbox.md) — Turn one independent option on or off in a form or settings list, including a parent whose children are partly checked, without Web Awesome.
+- [CheckboxGroup](./checkbox-group.md) — Choose any number of a few related options that should stay visible under one group label, with native keyboard behavior and form participation.
+- [RadioGroup](./radio-group.md) — Choose exactly one of a few options that should stay visible with room for a label and hint each, with native keyboard behavior and form participation.
+- [Switch](./switch.md) — Turn a setting on or off the moment it changes, such as live updates or a preference, without Web Awesome.
+- [Slider](./slider.md) — Let a person pick a value from a range where the relative position matters more than an exact number (volume, zoom, opacity, a threshold).
+- [PopupMenu](./popup-menu.md) — 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.
+- [Button](./button.md) — Trigger an action from a dialog footer, a form, or content outside any Toolbar, with Kerf's button chrome and native button semantics.
+- [SplitButton](./split-button.md) — Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a rounded or pill shape, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
+- [FilePicker](./file-picker.md) — Let people choose or drop files (attachments, evidence, imports) without app CSS: a link-toned browse trigger and a dashed drop target that highlights while dragging, both around visually hidden native file inputs.
+
+## Kerf UI — Feedback
+
+- [AnchoredSurface](./anchored-surface.md) — Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
+- [Feedback](./feedback.md) — Banners, empty states, and labeled progress.
+- [StateBanner](./state-banner.md) — Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
+- [Toast](./toast.md) — Show a brief, non-blocking confirmation or status message that dismisses itself, without hand-written toast CSS.
+- [Tooltip](./tooltip.md) — Explain a control or value on hover and keyboard focus with a styled tooltip, without hand-written tooltip CSS.
+- [CornerStatus](./corner-status.md) — Show ongoing app-level progress such as "Loading…" or "Updating Tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+- [EdgeActivityIndicator](./edge-activity-indicator.md) — Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.
+- [EmptyState](./empty-state.md) — Actionable empty and busy content states.
+- [LoadingSpinner](./loading-spinner.md) — Meaningfully labeled or decorative progress.
+- [ProgressBar](./progress-bar.md) — Show how far a measurable task has gone (an upload, a migration, a quota) or that work of unknown size is under way.
+- [ProgressRing](./progress-ring.md) — Show compact progress (a claim's time remaining, a per-row upload) where a bar does not fit.
+- [Skeleton](./skeleton.md) — A subtle, unanimated loading placeholder block for a not-yet-known value slot.
+
+## Web Awesome — Actions
+
+- [Button](./wa-button.md) (avoid) — Ecosystem action button; use Kerf Button.
+- [Button Group](./wa-button-group.md) (avoid) — Ecosystem button group; use Kerf ToolbarControlGroup, SplitButton, or SegmentedControl.
+- [Copy Button](./wa-copy-button.md) — Copies a supplied value and announces success or failure.
+- [Dropdown](./wa-dropdown.md) (avoid) — Ecosystem action menu; use Kerf PopupMenu, or Select when choosing a value.
+- [Dropdown Item](./wa-dropdown-item.md) (avoid) — Ecosystem action-menu row; use Kerf PopupMenu items or Select choices.
+
+## Web Awesome — Forms
+
+- [Checkbox](./wa-checkbox.md) (avoid) — Ecosystem checkbox; use Kerf Checkbox.
+- [Checkbox Group](./wa-checkbox-group.md) (avoid) — Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.
+- [Color Picker](./wa-color-picker.md) (avoid) — Ecosystem color picker; use the Kerf ColorField or ColorPicker.
+- [Input](./wa-input.md) (avoid) — Ecosystem text input; use Kerf TextField.
+- [Known Date](./wa-known-date.md) — Experimental segmented field for partially or fully known dates.
+- [Number Input](./wa-number-input.md) — Numeric input with keyboard and stepper controls.
+- [Option](./wa-option.md) (avoid) — Ecosystem select option; use Kerf Select choices.
+- [OTP Input](./wa-otp-input.md) — Experimental segmented one-time-password input.
+- [Radio](./wa-radio.md) (avoid) — Ecosystem radio; use Kerf RadioGroup choices.
+- [Radio Group](./wa-radio-group.md) (avoid) — Ecosystem radio group; use Kerf RadioGroup, ChoiceChips, or SegmentedControl.
+- [Rating](./wa-rating.md) — Interactive rating control with accessible labeling.
+- [Select](./wa-select.md) (avoid) — Ecosystem select field; use Kerf Select.
+- [Slider](./wa-slider.md) (avoid) — Ecosystem range slider; use the Kerf Slider.
+- [Switch](./wa-switch.md) (avoid) — Ecosystem switch; use Kerf Switch.
+- [Textarea](./wa-textarea.md) (avoid) — Ecosystem multi-line input; use Kerf TextField with multiline.
+- [Time Input](./wa-time-input.md) — Experimental segmented time field with an optional picker.
+- [Tag Input](./wa-tag-input.md) (avoid) — Ecosystem tag input; use the Kerf TagField.
+
+## Web Awesome — Layout
+
+- [Accordion](./wa-accordion.md) (avoid) — Ecosystem accordion; use Kerf Disclosures sharing a name.
+- [Accordion Item](./wa-accordion-item.md) (avoid) — Ecosystem accordion item; use a Kerf Disclosure in a named group.
+- [Card](./wa-card.md) (avoid) — Ecosystem card; use Kerf ContentItem or SunkenPanel.
+- [Details](./wa-details.md) (avoid) — Ecosystem disclosure; use the Kerf Disclosure.
+- [Dialog](./wa-dialog.md) (avoid) — Ecosystem dialog; use Kerf DialogSurface with openDialog and closeDialog.
+- [Divider](./wa-divider.md) — Visual separator for related groups of content.
+- [Drawer](./wa-drawer.md) (avoid) — Ecosystem drawer; use Kerf DialogSurface sheets or CollapsiblePanel.
+- [Page](./wa-page.md) (avoid) — Ecosystem page shell; use the Kerf app layouts.
+- [Scroller](./wa-scroller.md) (avoid) — Ecosystem scroll container; use Kerf Pane scroll edges or ColumnTrack.
+- [Split Panel](./wa-split-panel.md) (avoid) — Alternative split API; use Kerf ResizableRegion for application panes.
+
+## Web Awesome — Navigation
+
+- [Breadcrumb](./wa-breadcrumb.md) — Ordered navigation trail for the current location.
+- [Breadcrumb Item](./wa-breadcrumb-item.md) — One link or current-location item in a breadcrumb.
+- [Pagination](./wa-pagination.md) — Experimental page navigation for a bounded result set.
+- [Stepper](./wa-stepper.md) — Ordered indicator for a multi-step process, such as checkout or setup, with optional step-by-step navigation.
+- [Step](./wa-step.md) — Marker and label for one stage of a wa-stepper process, with completed, loading, disabled, and semantic-color states.
+- [Tab](./wa-tab.md) (avoid) — Ecosystem tab label; use Kerf TabBar or SegmentedControl.
+- [Tab Group](./wa-tab-group.md) (avoid) — Ecosystem tabs; use Kerf TabBar or SegmentedControl.
+- [Tab Panel](./wa-tab-panel.md) (avoid) — Ecosystem tab panel; use Kerf TabBar with application-owned panels.
+- [Tree](./wa-tree.md) (exceptional) — Specialized hierarchy; use only when the product requires tree behavior.
+- [Tree Item](./wa-tree-item.md) (exceptional) — Specialized tree row; use only as part of a required tree.
+
+## Web Awesome — Feedback
+
+- [Badge](./wa-badge.md) (avoid) — Ecosystem badge; use Kerf Badge.
+- [Callout](./wa-callout.md) (avoid) — Ecosystem callout; use Kerf StateBanner.
+- [Progress Bar](./wa-progress-bar.md) (avoid) — Ecosystem progress bar; use the Kerf ProgressBar.
+- [Progress Ring](./wa-progress-ring.md) (avoid) — Ecosystem progress ring; use the Kerf ProgressRing.
+- [Skeleton](./wa-skeleton.md) (avoid) — Ecosystem placeholder; use Kerf Skeleton.
+- [Spinner](./wa-spinner.md) (avoid) — Ecosystem spinner; use Kerf LoadingSpinner.
+- [Tag](./wa-tag.md) (avoid) — Ecosystem tag; use Kerf Chip.
+- [Toast](./wa-toast.md) (avoid) — Ecosystem toast stack; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+- [Toast Item](./wa-toast-item.md) (avoid) — Ecosystem toast item; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+- [Tooltip](./wa-tooltip.md) (avoid) — Ecosystem tooltip; use kerfjs/overlay tooltip() with @kerfjs/ui/overlay-tooltip.css.
+
+## Web Awesome — Media
+
+- [Animated Image](./wa-animated-image.md) (exceptional) — Specialized animated media; use only for a concrete product requirement.
+- [Avatar](./wa-avatar.md) — Person or entity image with initials fallback.
+- [Carousel](./wa-carousel.md) — Navigable horizontal or vertical collection of slides.
+- [Carousel Item](./wa-carousel-item.md) — One content slide inside a carousel.
+- [Comparison](./wa-comparison.md) (exceptional) — Specialized before-and-after media; use only when specifically required.
+- [Icon](./wa-icon.md) (avoid) — Ecosystem icon renderer; use Kerf LucideIcon in application UI.
+- [Markdown](./wa-markdown.md) — Experimental renderer for trusted Markdown content.
+- [QR Code](./wa-qr-code.md) — Scannable QR representation of a supplied value.
+- [Zoomable Frame](./wa-zoomable-frame.md) (avoid) — Avoid for application UI; keep embedded-media behavior application-owned.
+
+## Web Awesome — Helpers
+
+- [Animation](./wa-animation.md) — Declarative Web Animations API wrapper with preset effects.
+- [Format Bytes](./wa-format-bytes.md) — Locale-aware byte and bit value formatter.
+- [Format Date](./wa-format-date.md) — Locale-aware date and time formatter.
+- [Format Number](./wa-format-number.md) — Locale-aware number, currency, unit, and percentage formatter.
+- [Include](./wa-include.md) (avoid) — Ecosystem remote HTML include; fetch with kerfjs/async and render Kerf content.
+- [Intersection Observer](./wa-intersection-observer.md) — Declaratively emits visibility changes for slotted content.
+- [Mutation Observer](./wa-mutation-observer.md) — Declaratively emits DOM mutation records for slotted content.
+- [Popover](./wa-popover.md) (avoid) — Ecosystem popover; use Kerf AnchoredSurface.
+- [Popup](./wa-popup.md) (avoid) — Ecosystem positioning primitive; use Kerf AnchoredSurface or kerfjs/overlay positioning.
+- [Random Content](./wa-random-content.md) — Experimental helper that selects one slotted item at random.
+- [Relative Time](./wa-relative-time.md) — Locale-aware human description of a date relative to now.
+- [Resize Observer](./wa-resize-observer.md) — Declaratively emits size changes for slotted content.
+
+## Kerf UI — Recipes
+
+- [Desktop Application Shell](./recipe-app-shell.md) — App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
+- [Navigation Sidebar](./recipe-navigation-sidebar.md) — Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
+- [Workspace Header](./recipe-workspace-header.md) — Page identity with primary, secondary, and overflow actions that relocate at narrow widths.
+- [List-detail dialog](./recipe-list-detail-dialog.md) — Production ListDetailDialog: a full-height list column with its own title beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
+- [Composer Form](./recipe-composer-form.md) — 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.
+- [List Workspace States](./recipe-list-workspace-states.md) — Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
+- [Compact Toolbar Choices and Actions](./recipe-compact-toolbar.md) — A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.
+- [Navigation Stack](./recipe-navigation-stack.md) — A push/pop navigation stack drill-down with animated slides and a live device class.
+- [Loading Inspector](./recipe-loading-inspector.md) — A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
+- [Collapsible Sidebar](./recipe-collapsible-sidebar.md) — 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.
+- [Media Detail](./recipe-media-detail.md) — An Apple-Music-style album page: clear NavStack chrome with the scroll-edge material, a scoped tint from the artwork's color, an underChrome BackdropImage with parallax and progressive blur, and glass control groups.

package/ai/components/anchored-surface.md

@@ -0,0 +1,99 @@
+# AnchoredSurface
+
+<!-- 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:anchored-surface` · Kerf UI · component · Feedback
+
+A styled non-modal surface for app-owned interactive help or popup content, anchored to an element or pointer.
+
+## When to use
+
+Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
+
+- Show interactive help or other arbitrary content near a control or pointer, including inside a modal dialog.
+
+**Not when:**
+
+- Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page.
+
+**Alternatives:**
+
+- [PopupMenu](./popup-menu.md) (nearest)
+- [Popup](./wa-popup.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/anchored-surface` — exports `openAnchoredSurface`, `openAnchoredSurfaceAt`.
+- CSS: the browser build of `@kerfjs/ui/anchored-surface` pulls its CSS automatically; import `@kerfjs/ui/anchored-surface.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/anchored-surface`](../public-api-signatures-v1.md#kerfjsuianchored-surface) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- element anchor
+- pointer anchor
+- top or bottom placement
+- modal-dialog host
+- tone: 'dark' (the inverse tone of a dark ToolbarControlGroup, for popups anchored to media chrome)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** content and action policy; opening trigger and programmatic close after an action; accessible name.
+
+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.
+
+## Accessibility
+
+- The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default.
+
+## Usage examples
+
+### Interactive help
+
+The trigger owns when to open; the returned handle closes when an action completes.
+
+```tsx
+const handle = openAnchoredSurface(button, () => <HelpPanel />, {
+  label: 'Field help',
+});
+// Close from the app's action handler: handle.close();
+```
+
+### Popup anchored to dark media chrome
+
+tone: 'dark' matches a ToolbarControlGroup tone="dark": the surface takes the opposite of the anchor's color scheme (openAnchoredSurfaceAt reads it from point.context) and follows a live OS-preference or ancestor theme switch while open, so its content inherits the inverse text, border, and focus colors without overrides.
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public tokens it reads: `--kui-anchored-surface-inset`, `--kui-anchored-surface-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [PopupMenu](./popup-menu.md), [Popup](./wa-popup.md).
+- Docs: [`docs/anchored-surface.md`](../../docs/anchored-surface.md).
+- UX catalog route: `?component=anchored-surface`.

package/ai/components/application-tabs.md

@@ -0,0 +1,65 @@
+# Application Tabs
+
+<!-- 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:application-tabs` · Kerf UI · CSS composition · Navigation
+
+Controlled document tabs with application-owned state and panels.
+
+## When to use
+
+Show TabBarItem and TabBar in a complete controlled composition.
+
+- Compose application state, panels, actions, overflow, and reordering around TabBar and TabBarItem.
+
+**Not when:**
+
+- Use SegmentedControl instead for a compact local choice.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- overflow
+- keyboard and pointer reordering
+- adding and closing documents
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [TabBarItem](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Pane](./pane.md).
+
+## State and wiring
+
+**The app owns:** ordered tabs; selected tab; tabpanels; add and close policy; routing and persistence.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Keep one selected tab synchronized with one named tabpanel and retain the wireTabBars disposer.
+
+## 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: [TabBarItem](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Pane](./pane.md).
+- Docs: [`docs/accessibility.md`](../../docs/accessibility.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=application-tabs`.

package/ai/components/backdrop-image.md

@@ -0,0 +1,84 @@
+# BackdropImage
+
+<!-- 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:backdrop-image` · Kerf UI · component · Structure
+
+An image block at the top of a scrolling view that can lag the scroll, fade into an app color, and keep painting that color under the content below.
+
+## When to use
+
+Open a scrolling Pane or NavStack view with a hero or tiled backdrop image (an artist, album, or place page) that lags the scroll and progressively blurs on a compositor-only scroll timeline, dissolves through a mask into an app-chosen color, and continues that color under the following content, with Kerf-owned static fallbacks.
+
+- A scrolling view opens with a large mood or identity image (an artist, album, place, or collection header) whose page should read as one surface with it.
+- The image should lag the scroll (parallax), blur progressively as it scrolls away, or dissolve into a color without app scroll listeners, animated filters, or background-attachment: fixed.
+
+**Not when:**
+
+- Do not use for inline content images, thumbnails, avatars, or media a person inspects; render an img or the matching media component.
+- Do not hand-roll scroll listeners, background-attachment: fixed, animated blur filters, or mask gradients around an image in app CSS.
+- Do not put it in a region that does not scroll vertically; parallax needs a scroll container ancestor.
+
+**Alternatives:**
+
+- [Pane](./pane.md) (composes-with) — Place BackdropImage first in a Pane's scrolling content (or a NavStack view) so its scroller drives the parallax.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered work surface without imagery.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/backdrop-image` — exports `BackdropImage`.
+- CSS: the browser build of `@kerfjs/ui/backdrop-image` pulls its CSS automatically; import `@kerfjs/ui/backdrop-image.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/backdrop-image`](../public-api-signatures-v1.md#kerfjsuibackdrop-image) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- fitted image (cover, contain, fill) with a focal position
+- tiled background (repeat, repeat-x, repeat-y)
+- parallax none, subtle, or a 0 to 1 lag factor
+- progressive blur from a once-filtered copy or an app-supplied blurred asset, with an optional dim
+- fade into a color that also paints below
+- bottom or full scrim under overlay content
+- image running beneath clear or overlay chrome (underChrome)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the image, its alt text (empty for a decorative image), and responsive candidates; the fade color, whether the image lags the scroll, and whether it blurs (and any pre-blurred asset); overlay content and its contrast against the image and scrim; the content below the image; whether the image runs up beneath overlay or clear chrome and the top safe area (underChrome); it must then be the first child of the Pane's content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The root bleeds to the Pane's resolved inline insets (the safe area) and hands them back to its overlay and content, so their items keep the ordinary text axis.
+- The image block is height tall (default 320px) and grows with taller overlay content.
+
+## Accessibility
+
+- alt describes a meaningful image; pass an empty alt for a decorative one. A tiled image with alt text is exposed as role="img". Parallax and the progressive blur run only with prefers-reduced-motion: no-preference and scroll-driven animation support, and are off under data-kui-effects="static" and on slow-update displays, leaving a static, sharp image; the blurred copy is decorative and aria-hidden. Reduced transparency or increased contrast replaces the fade with a hard edge on solid fadeTo and puts overlay content on a solid fadeTo band. Overlay text needs a scrim or fade color that keeps it at AA.
+
+## 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-backdrop-image`.
+
+Never put `kui-backdrop-image` on an element you write; render `BackdropImage` 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: [Pane](./pane.md), [SunkenPanel](./sunken-panel.md).
+- Docs: [`docs/backdrop-image.md`](../../docs/backdrop-image.md), [`docs/backdrop-image.md#fallbacks`](../../docs/backdrop-image.md#fallbacks).
+- UX catalog route: `?component=backdrop-image`.

package/ai/components/badge.md

@@ -0,0 +1,77 @@
+# Badge
+
+<!-- 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:badge` · Kerf UI · component · Foundation
+
+Self-styled, non-interactive status, count, and category metadata configured through semantic tone, appearance, shape, and size props.
+
+## When to use
+
+Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+
+- Show a short status, count, category, or metadata label whose presentation should be configured rather than restyled.
+
+**Not when:**
+
+- Do not use Badge as a button, link, or removable chip; choose an interactive control with the correct native semantics.
+- Do not rely on tone alone to communicate meaning.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/badge` — exports `Badge`.
+- CSS: the browser build of `@kerfjs/ui/badge` pulls its CSS automatically; import `@kerfjs/ui/badge.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#kerfjsuibadge) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, info, pop, success, warning, or danger tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size, or a text-free dot (size: 'dot')
+- labeled or decorative duplicate
+- leading icon
+- title tooltip and data-\* rootAttributes
+- maxWidth caps the badge and truncates long text with an ellipsis, defaulting the title to string or number content
+- placement="corner": a count or dot straddling the top-trailing corner of an icon-only Button or a ToolbarControlGroup button
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** metadata text; semantic tone mapping; accessible label for abbreviated content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component. A text-free dot must take either label (exposed as an image) or ariaHidden, which the types enforce.
+- Keep meaningful text visible because tone is supplementary.
+- A label replaces abbreviated or symbolic visible text; the badge is then a labeled image (role img).
+
+## 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-badge`, `kui-badge__icon`, `kui-badge__label`.
+
+Never put `kui-badge`, `kui-badge__icon`, `kui-badge__label` on an element you write; render `Badge` 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
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=badge`.

package/ai/components/button.md

@@ -0,0 +1,94 @@
+# Button
+
+<!-- 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:button` · Kerf UI · component · Controls
+
+A standalone action button: a native button (or a link with href) in a neutral, brand, success, or danger tone and a primary, secondary, or plain emphasis, at the 44px control height or compact.
+
+## When to use
+
+Trigger an action from a dialog footer, a form, or content outside any Toolbar, with Kerf's button chrome and native button semantics.
+
+- A dialog footer, a form, or content needs an action button: tone="brand" for the main action, tone="success" for a positive action such as a pricing check, tone="danger" for a destructive one, and emphasis="secondary" or "plain" for the quieter actions beside it.
+- A form submits or resets: type="submit" or "reset" (the default type never submits), with name, value, and form when needed.
+- An action navigates: href renders a link with the same chrome.
+- A single primary action spans its form, sheet, or narrow column: fill makes it span the parent's available inline width, label centered, as SplitButton's fill does.
+
+**Not when:**
+
+- Do not use inside a ToolbarControlGroup; give the group plain \<button> controls, which it styles.
+- Do not use for an icon-only action; use an icon-only Button (with pressed for an on/off toggle).
+- Do not use for a menu trigger; use PopupMenu.
+
+**Alternatives:**
+
+- [Button](./wa-button.md) (prefer-over)
+- [ToolbarControlGroup](./toolbar-control-group.md) (nearest) — Inside a Toolbar, compose plain buttons in a ToolbarControlGroup.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/button` — exports `Button`.
+- CSS: the browser build of `@kerfjs/ui/button` pulls its CSS automatically; import `@kerfjs/ui/button.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md#kerfjsuibutton) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, brand, success, or danger tone
+- primary, secondary, or plain emphasis
+- default or compact size
+- rounded (default) or pill shape
+- content width (default) or fill: spans the parent's available inline width, label centered and ellipsized when it no longer fits
+- leading icon
+- icon-only square (icon and ariaLabel, no label)
+- pressed toggle (aria-pressed) on any tone and emphasis
+- loading
+- disabled
+- link (href)
+- badge (a count, short text, or true for a dot) over the corner, named through badgeLabel, with badgeTone
+- focusRingInset: the focus ring drawn inside the box for an ancestor that clips overflow
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** the label and its delegated action; what a press does while loading; form ownership.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- A native \<button> (type="button" unless set) or, with href, an \<a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.
+- Loading shows a spinner in place of the label, which still names the button, and sets aria-busy="true". A disabled link drops its href and reports aria-disabled="true". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.
+- With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag.
+
+## 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-button`, `kui-button__icon`, `kui-button__label`, `kui-button__spinner`.
+
+Never put `kui-button`, `kui-button__icon`, `kui-button__label`, `kui-button__spinner` on an element you write; render `Button` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-on-quiet`, `--kui-color-brand-border-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-on-fill`, `--kui-color-success-border-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-on-quiet`, `--kui-color-danger-border-loud`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-layout-rounded-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LoadingSpinner](./loading-spinner.md), [Button](./wa-button.md), [ToolbarControlGroup](./toolbar-control-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=button`.