@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/ai/component-composition.schema.json

@@ -0,0 +1,375 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition.schema.json",
+  "title": "Kerf UI composition catalog",
+  "type": "object",
+  "required": ["schemaVersion", "package", "compatibility", "entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Version of the composition catalog format itself, independent of component-catalog.json's own schemaVersion."
+    },
+    "package": { "type": "string", "minLength": 1 },
+    "compatibility": {
+      "type": "object",
+      "required": ["componentCatalog", "identity"],
+      "properties": {
+        "componentCatalog": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path to the component (selection) catalog this composition layer describes, or \"not-applicable\" when the package publishes none."
+        },
+        "identity": { "const": "package:id" }
+      },
+      "additionalProperties": false
+    },
+    "entries": { "type": "array", "items": { "$ref": "#/$defs/entry" } }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stateAttribute": {
+      "type": "object",
+      "required": ["name", "on", "helper", "meaning"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^data-[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "on": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The element that carries it: a public class, or the element passed to the helper."
+        },
+        "helper": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The helper, one of wiring.helpers, that writes it."
+        },
+        "meaning": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What its presence or value means."
+        }
+      },
+      "additionalProperties": false
+    },
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "cardinality": {
+      "type": "object",
+      "required": ["min", "max"],
+      "properties": {
+        "min": { "type": "integer", "minimum": 0 },
+        "max": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1 },
+            { "const": "unbounded" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "zone": {
+      "type": "object",
+      "required": ["id", "accepts", "cardinality", "exclusiveWith"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "jsx": {
+          "type": "object",
+          "required": ["prop"],
+          "properties": {
+            "prop": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        },
+        "accepts": { "$ref": "#/$defs/stringList" },
+        "cardinality": { "$ref": "#/$defs/cardinality" },
+        "exclusiveWith": { "$ref": "#/$defs/stringList" }
+      },
+      "additionalProperties": false
+    },
+    "state": {
+      "type": "object",
+      "required": ["id", "owner", "required"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "owner": { "enum": ["application", "controlled", "component"] },
+        "required": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["id", "severity", "when", "message"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^KUI-C[0-9]{3}$" },
+        "severity": { "enum": ["error", "warning"] },
+        "when": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "entry": {
+      "type": "object",
+      "required": [
+        "key",
+        "package",
+        "id",
+        "name",
+        "kind",
+        "source",
+        "parents",
+        "contexts",
+        "zones",
+        "children",
+        "state",
+        "wiring",
+        "responsive",
+        "layout",
+        "accessibility",
+        "boundaries",
+        "diagnostics",
+        "provenance"
+      ],
+      "properties": {
+        "key": { "type": "string", "minLength": 3 },
+        "package": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["component", "composition", "recipe"] },
+        "purpose": { "type": "string", "minLength": 1 },
+        "publicExports": {
+          "description": "Each export's name and the package.json#exports subpath that serves it. An entry from a private application omits subpath: the application is bundled, never imported by package name, so the name resolves through the entry's source file.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "subpath": { "type": "string", "pattern": "^\\." }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "sourceLinks": { "$ref": "#/$defs/stringList" },
+        "source": { "type": "string", "minLength": 1 },
+        "rendersAs": {
+          "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys), any one of them or nothing. Composition checks treat an element of this entry as each declared root: a zone accepts it only if it accepts every root, and each root's parent contract applies to where it is placed.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
+          "uniqueItems": true
+        },
+        "jsxExports": {
+          "description": "Placement contracts for additional JSX exports from one selection entry. These exports do not stand for the entry's root or its zones.",
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Z][A-Za-z0-9]*$" },
+          "additionalProperties": {
+            "type": "object",
+            "required": ["parents"],
+            "properties": {
+              "parents": {
+                "type": "object",
+                "required": ["mode", "entries"],
+                "properties": {
+                  "mode": { "enum": ["any", "root", "listed"] },
+                  "entries": { "$ref": "#/$defs/stringList" }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "parents": {
+          "type": "object",
+          "required": ["mode", "entries"],
+          "properties": {
+            "mode": { "enum": ["any", "root", "listed"] },
+            "entries": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "contexts": { "$ref": "#/$defs/stringList" },
+        "zones": { "type": "array", "items": { "$ref": "#/$defs/zone" } },
+        "children": {
+          "type": "object",
+          "required": ["mode", "concepts", "requiredConcepts"],
+          "properties": {
+            "mode": { "enum": ["any", "none", "listed"] },
+            "concepts": { "$ref": "#/$defs/stringList" },
+            "requiredConcepts": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "state": { "type": "array", "items": { "$ref": "#/$defs/state" } },
+        "wiring": {
+          "type": "object",
+          "required": ["required", "helpers", "obligations"],
+          "properties": {
+            "required": { "type": "boolean" },
+            "helpers": { "$ref": "#/$defs/stringList" },
+            "obligations": { "$ref": "#/$defs/stringList" },
+            "stateAttributes": {
+              "description": "Wiring-owned state attributes: data-* attributes a wiring helper writes at runtime, which the application must not render, remove, or treat as its own state. Optional for extension catalogs; first-party entries always list it, empty when their helpers write none.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/stateAttribute" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "responsive": {
+          "type": "object",
+          "required": ["owner", "behaviors"],
+          "properties": {
+            "owner": {
+              "enum": ["application", "component", "shared", "not-applicable"]
+            },
+            "behaviors": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "layout": {
+          "type": "object",
+          "required": ["roles", "geometry"],
+          "properties": {
+            "roles": { "$ref": "#/$defs/stringList" },
+            "geometry": {
+              "type": "object",
+              "required": ["margin", "border", "padding"],
+              "properties": {
+                "margin": {
+                  "enum": [
+                    "self",
+                    "parent",
+                    "child",
+                    "none",
+                    "conditional",
+                    "composed"
+                  ]
+                },
+                "border": {
+                  "enum": [
+                    "self",
+                    "parent",
+                    "child",
+                    "none",
+                    "conditional",
+                    "composed"
+                  ]
+                },
+                "padding": {
+                  "enum": [
+                    "self",
+                    "parent",
+                    "child",
+                    "none",
+                    "conditional",
+                    "composed"
+                  ]
+                },
+                "notes": { "$ref": "#/$defs/stringList" }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "accessibility": {
+          "type": "object",
+          "required": ["obligations"],
+          "properties": { "obligations": { "$ref": "#/$defs/stringList" } },
+          "additionalProperties": false
+        },
+        "cssValueProps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/cssValueProp" }
+        },
+        "boundaries": {
+          "type": "object",
+          "required": ["rootClass", "publicClasses", "publicTokens"],
+          "properties": {
+            "rootClass": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "null" }
+              ]
+            },
+            "publicClasses": { "$ref": "#/$defs/stringList" },
+            "placeableClasses": {
+              "$ref": "#/$defs/stringList",
+              "description": "The subset of publicClasses an application may place on its own elements. Absent means none: every public class is the component's rendered anatomy, reached by rendering the component."
+            },
+            "rootElement": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "The intrinsic element the component renders at its root. A placeableClasses class on a plain element of this tag recreates the component; the class stays placeable on any other carrier element."
+            },
+            "publicTokens": { "$ref": "#/$defs/stringList" },
+            "publicParts": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/diagnostic" }
+        },
+        "provenance": {
+          "type": "object",
+          "required": ["selection", "composition"],
+          "properties": {
+            "selection": { "type": "string", "minLength": 1 },
+            "composition": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "cssValueProp": {
+      "type": "object",
+      "required": [
+        "path",
+        "grammar",
+        "helpers",
+        "shorthands",
+        "canonicalShorthands",
+        "exceptionalShorthands",
+        "rawPolicy",
+        "examples"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9]*(?:\\[\\]\\.[A-Za-z][A-Za-z0-9]*)?$"
+        },
+        "grammar": {
+          "enum": [
+            "length",
+            "size",
+            "flex",
+            "color",
+            "declarations",
+            "media-query",
+            "pixels"
+          ]
+        },
+        "helpers": { "$ref": "#/$defs/stringList" },
+        "nonStandaloneHelpers": { "$ref": "#/$defs/stringList" },
+        "shorthands": { "$ref": "#/$defs/stringList" },
+        "canonicalShorthands": { "$ref": "#/$defs/stringList" },
+        "exceptionalShorthands": { "$ref": "#/$defs/stringList" },
+        "rawPolicy": { "enum": ["forbid", "allow", "unsafe-only"] },
+        "unsafeHelper": { "type": "string", "minLength": 1 },
+        "examples": { "$ref": "#/$defs/stringList" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/ai/components/README.md

@@ -0,0 +1,171 @@
+# @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 without application rules on Web Awesome internals.
+- [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.
+- [TabScaffold](./tab-scaffold.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.
+- [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.
+- [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.
+- [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.
+- [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, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+
+## 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 mutually exclusive semantic count or badge from an optional 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 AppTab and TabBar in a complete controlled composition.
+- [AppTab](./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.
+- [TokenSearchField](./token-search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+- [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.
+- [PopupMenu](./popup-menu.md) — A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
+
+## Kerf UI — Feedback
+
+- [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.
+- [EmptyState](./empty-state.md) — Actionable empty and busy content states.
+- [LoadingSpinner](./loading-spinner.md) — Meaningfully labeled or decorative progress.
+- [Skeleton](./skeleton.md) — A subtle, unanimated loading placeholder block for a not-yet-known value slot.
+
+## Web Awesome — Actions
+
+- [Button](./wa-button.md) — Action control with semantic variants, appearances, loading, and icon support.
+- [Button Group](./wa-button-group.md) (conditional) — Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
+- [Copy Button](./wa-copy-button.md) — Copies a supplied value and announces success or failure.
+- [Dropdown](./wa-dropdown.md) (conditional) — Action-menu primitive; prefer Kerf Select when choosing a value.
+- [Dropdown Item](./wa-dropdown-item.md) (conditional) — Action-menu row; prefer Kerf Select options for value selection.
+
+## Web Awesome — Forms
+
+- [Checkbox](./wa-checkbox.md) — Binary form control with checked, indeterminate, and disabled states.
+- [Checkbox Group](./wa-checkbox-group.md) — Labels and validates a related set of checkboxes.
+- [Color Picker](./wa-color-picker.md) — Color input with swatches, formats, opacity, and eyedropper support.
+- [Input](./wa-input.md) — Text input with labels, hints, clear controls, and semantic appearances.
+- [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) (underlying) — Underlying ecosystem option; prefer choices passed to Kerf Select.
+- [OTP Input](./wa-otp-input.md) — Experimental segmented one-time-password input.
+- [Radio](./wa-radio.md) — Single-choice control used inside a radio group.
+- [Radio Group](./wa-radio-group.md) — Labels and manages a mutually exclusive set of radios.
+- [Rating](./wa-rating.md) — Interactive rating control with accessible labeling.
+- [Select](./wa-select.md) (underlying) — Underlying ecosystem field; prefer Kerf Select for app UI.
+- [Slider](./wa-slider.md) — Range input with markers and value tooltip support.
+- [Switch](./wa-switch.md) — Immediate on/off setting control.
+- [Textarea](./wa-textarea.md) — Multiline text field with labels, hints, and resize behavior.
+- [Time Input](./wa-time-input.md) — Experimental segmented time field with an optional picker.
+
+## Web Awesome — Layout
+
+- [Accordion](./wa-accordion.md) — Coordinates one or more collapsible content sections.
+- [Accordion Item](./wa-accordion-item.md) — Experimental labeled disclosure section used by an accordion.
+- [Card](./wa-card.md) — Groups related content and optional header, media, and footer slots.
+- [Details](./wa-details.md) — Single disclosure panel for secondary information.
+- [Dialog](./wa-dialog.md) — Modal surface for focused tasks and confirmations.
+- [Divider](./wa-divider.md) — Visual separator for related groups of content.
+- [Drawer](./wa-drawer.md) — Edge-anchored modal surface for navigation or secondary tasks.
+- [Page](./wa-page.md) — Responsive application shell with navigation, banner, and main slots.
+- [Scroller](./wa-scroller.md) — Overflow container with accessible scrolling affordances.
+- [Split Panel](./wa-split-panel.md) (conditional) — Alternative split API; prefer 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.
+- [Tab](./wa-tab.md) (conditional) — Ecosystem tab label; prefer Kerf TabBar or SegmentedControl.
+- [Tab Group](./wa-tab-group.md) (conditional) — Ecosystem tabs; prefer Kerf TabBar or SegmentedControl.
+- [Tab Panel](./wa-tab-panel.md) (conditional) — Ecosystem tab panel; prefer app-owned panels with Kerf navigation.
+- [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) — Compact status or count label with semantic variants.
+- [Callout](./wa-callout.md) — Prominent contextual message with semantic variants.
+- [Progress Bar](./wa-progress-bar.md) — Linear indicator for determinate or indeterminate progress.
+- [Progress Ring](./wa-progress-ring.md) — Circular indicator for determinate or indeterminate progress.
+- [Skeleton](./wa-skeleton.md) — Placeholder shape for content that is still loading.
+- [Spinner](./wa-spinner.md) — Compact indeterminate activity indicator.
+- [Tag](./wa-tag.md) — Compact categorization label with optional removal action.
+- [Toast](./wa-toast.md) — Placement-aware stack of transient notifications.
+- [Toast Item](./wa-toast-item.md) — One dismissible notification inside a toast stack.
+- [Tooltip](./wa-tooltip.md) — Brief contextual label anchored to a control.
+
+## 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) — Loads and injects an external HTML fragment.
+- [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) — Anchored non-modal surface built on popup positioning.
+- [Popup](./wa-popup.md) (conditional) — Preferred low-level anchored positioning when Tooltip or Popover do not fit.
+- [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 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.
+- [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.

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 AppTab and TabBar in a complete controlled composition.
+
+- Compose application state, panels, actions, overflow, and reordering around TabBar and AppTab.
+
+**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: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.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: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+- Docs: [`docs/accessibility.md`](../../docs/accessibility.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=application-tabs`.