@kerfjs/ui 5.0.0-beta.56 → 5.0.0-beta.58

package/ai/{component-catalog-v2.json → component-composition.json}

@@ -1,9 +1,9 @@
 {
-  "$schema": "./component-catalog-v2.schema.json",
-  "schemaVersion": 2,
+  "$schema": "./component-composition.schema.json",
+  "schemaVersion": 1,
   "package": "@kerfjs/ui",
   "compatibility": {
-    "v1Catalog": "./component-catalog.json",
+    "componentCatalog": "./component-catalog.json",
     "identity": "package:id"
   },
   "entries": [
@@ -379,6 +379,7 @@
       "boundaries": {
         "rootClass": "kui-app-root",
         "publicClasses": ["kui-app-root"],
+        "placeableClasses": ["kui-app-root"],
         "publicTokens": []
       },
       "diagnostics": [],
@@ -438,6 +439,12 @@
           "kui-inline-metadata",
           "kui-scroll-owner"
         ],
+        "placeableClasses": [
+          "kui-content",
+          "kui-control-cluster",
+          "kui-inline-metadata",
+          "kui-scroll-owner"
+        ],
         "publicTokens": [
           "--kui-layout-control-gap",
           "--kui-layout-content-gap",
@@ -524,13 +531,31 @@
           "id": "responsive placement and visibility",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "whether the chrome dividers follow the scroll, always show, or never show (chromeDividers)",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireScrollDividers"],
         "obligations": [],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-scroll-overflow",
+            "on": "kui-pane__content",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "kui-pane__header and kui-pane__footer",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -622,11 +647,16 @@
           "id": "top-toolbar configuration, title size, and heading level",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers)",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
         "required": true,
-        "helpers": ["wireNavStack"],
+        "helpers": ["wireNavStack", "wireScrollDividers"],
         "obligations": ["Use wireNavStack as documented."],
         "stateAttributes": [
           {
@@ -646,6 +676,18 @@
             "on": "kui-nav-stack__view",
             "helper": "wireNavStack",
             "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
+          },
+          {
+            "name": "data-scroll-overflow",
+            "on": "the active kui-nav-stack__view, or the kui-pane__content of a sole Pane in it",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "kui-nav-stack__chrome and kui-nav-stack__bottom",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -657,7 +699,8 @@
           "border": "conditional",
           "padding": "child",
           "notes": [
-            "The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content."
+            "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."
           ]
         }
       },
@@ -680,8 +723,6 @@
           "kui-nav-stack__chrome-copy",
           "kui-nav-stack__chrome-copy--bottom",
           "kui-nav-stack__chrome-copy--exiting",
-          "kui-nav-stack__toolbar",
-          "kui-nav-stack__title",
           "kui-nav-stack__viewport",
           "kui-nav-stack__view",
           "kui-nav-stack__view--entering",
@@ -748,7 +789,7 @@
           "required": false
         },
         {
-          "id": "compact list and detail toolbar groups and toolbar configuration",
+          "id": "compact list and detail toolbar groups, toolbar configuration, and chrome dividers",
           "owner": "application",
           "required": false
         },
@@ -862,23 +903,42 @@
           "id": "responsive replacement on larger device classes",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "whether the bar divider follows the scroll, always shows, or never shows (chromeDividers)",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
         "required": true,
-        "helpers": ["wireTabScaffold"],
+        "helpers": ["wireTabScaffold", "wireScrollDividers"],
         "obligations": ["Use wireTabScaffold as documented."],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-scroll-overflow",
+            "on": "the active kui-tab-scaffold__scene, or what scrolls inside it (a sole NavStack's active view or a sole Pane's content)",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "kui-tab-scaffold__bar",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
         "roles": ["structure"],
         "geometry": {
           "margin": "none",
-          "border": "self",
+          "border": "conditional",
           "padding": "self",
           "notes": [
-            "The scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry."
+            "The scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
+            "The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border."
           ]
         }
       },
@@ -968,7 +1028,7 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": ["wireWorkbench"],
+        "helpers": ["wireWorkbench", "wireScrollDividers"],
         "obligations": [],
         "stateAttributes": [
           {
@@ -982,6 +1042,18 @@
             "on": "kui-workbench__rail",
             "helper": "wireWorkbench",
             "meaning": "Present on a resizable rail or the drawer while a pointer drag resizes it."
+          },
+          {
+            "name": "data-scroll-overflow",
+            "on": "kui-pane__content of each panel and work-area Pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "kui-pane__header and kui-pane__footer of each panel and work-area Pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -1076,7 +1148,7 @@
       ],
       "wiring": {
         "required": true,
-        "helpers": ["wireSidebar"],
+        "helpers": ["wireSidebar", "wireScrollDividers"],
         "obligations": ["Use wireSidebar as documented."],
         "stateAttributes": [
           {
@@ -1096,6 +1168,18 @@
             "on": "kui-collapsible-panel__backdrop",
             "helper": "wireSidebar",
             "meaning": "Keeps the injected compact-overlay backdrop through the application's re-render; the helper creates and removes the backdrop itself."
+          },
+          {
+            "name": "data-scroll-overflow",
+            "on": "kui-pane__content of each panel and work-area Pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "kui-pane__header and kui-pane__footer of each panel and work-area Pane",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
           }
         ]
       },
@@ -1274,9 +1358,22 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireScrollDividers"],
         "obligations": [],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-scroll-overflow",
+            "on": "the targets scroller",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "a Toolbar named as targets chrome",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -2054,9 +2151,22 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireScrollDividers"],
         "obligations": [],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-scroll-overflow",
+            "on": "the targets scroller",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "a List named as targets chrome",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -2155,14 +2265,12 @@
           "kui-list-header",
           "kui-list-header__action",
           "kui-list-header__action-layer",
-          "kui-list-header__label",
           "kui-list-header__title",
           "kui-list-header__toggle"
         ],
         "publicTokens": [
           "--kui-color-neutral-border-quiet",
           "--kui-focus-ring",
-          "--kui-font-xs",
           "--kui-list-header-action-icon-size",
           "--kui-list-header-color",
           "--kui-layout-inline-margin",
@@ -2521,6 +2629,12 @@
           "kui-content-item--pill",
           "kui-content-item--framed"
         ],
+        "placeableClasses": [
+          "kui-content-item",
+          "kui-content-item--pill",
+          "kui-content-item--framed"
+        ],
+        "rootElement": "div",
         "publicTokens": [
           "--kui-content-item-border",
           "--kui-content-item-radius",
@@ -2737,7 +2851,7 @@
       ],
       "wiring": {
         "required": true,
-        "helpers": ["wireTabBars"],
+        "helpers": ["wireTabBars", "wireScrollDividers"],
         "obligations": [
           "Retain and invoke the disposer.",
           "Apply onReorder to application-owned order."
@@ -2760,6 +2874,18 @@
             "on": "kui-tab-bar__tabs",
             "helper": "wireTabBars",
             "meaning": "\"start\" or \"end\" while a drag near that edge auto-scrolls the strip."
+          },
+          {
+            "name": "data-scroll-overflow",
+            "on": "kui-tab-bar__tabs",
+            "helper": "wireScrollDividers",
+            "meaning": "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."
+          },
+          {
+            "name": "data-scroll-divider",
+            "on": "chrome named in wireScrollDividers targets (a TabBar strip has none)",
+            "helper": "wireScrollDividers",
+            "meaning": "The sides, in t/r/b/l order, on which that chrome currently draws its scroll divider. Re-applied if a re-render drops it."
           }
         ]
       },
@@ -2791,7 +2917,11 @@
           "kui-tab-bar__trailing",
           "kui-tab-bar__end"
         ],
-        "publicTokens": ["--kui-tab-bar-background", "--kui-tab-bar-border"]
+        "publicTokens": [
+          "--kui-tab-bar-background",
+          "--kui-tab-bar-border",
+          "--kui-tab-bar-divider-color"
+        ]
       },
       "diagnostics": [
         {
@@ -4586,6 +4716,7 @@
       "boundaries": {
         "rootClass": null,
         "publicClasses": ["hide-actions"],
+        "placeableClasses": ["hide-actions"],
         "publicTokens": []
       },
       "diagnostics": [],

package/ai/{component-catalog-v2.schema.json → component-composition.schema.json}

@@ -1,18 +1,25 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-v2.schema.json",
-  "title": "Kerf UI composition catalog v2",
+  "$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": 2 },
+    "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": ["v1Catalog", "identity"],
+      "required": ["componentCatalog", "identity"],
       "properties": {
-        "v1Catalog": { "type": "string", "minLength": 1 },
+        "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
@@ -274,6 +281,15 @@
               ]
             },
             "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" }
           },

package/ai/components/README.md

@@ -0,0 +1,170 @@
+# @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.
+- [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) — Large, default, and compact 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 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 without repeating application-owned grid-template-columns CSS.
+- [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 navigation rows.
+- [Application tabs](./application-tabs.md) — Show AppTab and TabBar in a complete controlled composition.
+- [AppTab](./tabs.md) — Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.
+- [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) — Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+- [PopupMenu](./popup-menu.md) — A trigger button that opens a typed list of commands, 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`.