@kerfjs/ui 5.0.0-beta.23 → 5.0.0-beta.25

package/ai/component-catalog.json

@@ -555,6 +555,286 @@
         "recipe": "docs/layout.md#anatomy"
       }
     },
+    {
+      "id": "nav-stack",
+      "name": "NavStack",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A controlled one-pane navigation stack that keeps prior views mounted and animates push and pop transitions.",
+      "uses": [
+        "toolbar-text"
+      ],
+      "purpose": "Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.",
+      "publicExports": [
+        "NavStackView",
+        "NavStackProps",
+        "NavStack"
+      ],
+      "useWhen": [
+        "A compact surface shows one view at a time and navigation pushes into details or pops back.",
+        "A simple single-pane screen needs the same stable app-layout contract without any nested navigation."
+      ],
+      "avoidWhen": [
+        "Do not use NavStack when a list and detail should remain visible together; use SplitView.",
+        "Do not use it for co-equal top-level destinations on compact devices; wrap one stack per destination in TabScaffold."
+      ],
+      "alternatives": [
+        {
+          "id": "split-view",
+          "relationship": "roomy-alternative",
+          "when": "Promote a list-to-detail stack to SplitView once both regions fit together."
+        },
+        {
+          "id": "tab-scaffold",
+          "relationship": "composes-with",
+          "when": "Use one NavStack as each TabScaffold tab's persistent content."
+        }
+      ],
+      "appOwns": [
+        "ordered view stack and stable keys",
+        "view content and titles",
+        "push and pop actions",
+        "focus restoration policy",
+        "optional persistent bottom toolbar"
+      ],
+      "variants": [
+        "single root view",
+        "pushed detail view",
+        "toolbar hidden",
+        "persistent bottom toolbar"
+      ],
+      "accessibility": [
+        "Give the stack region an accessible label and every back control a stable action label.",
+        "Wire pop behavior and restore focus to the control that opened the departing view after the controlled rerender."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "conditional",
+        "padding": "child",
+        "notes": [
+          "The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/nav-stack",
+        "manualCssImport": "@kerfjs/ui/nav-stack.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireNavStack",
+          "import": "@kerfjs/ui/wire-nav-stack",
+          "required": true
+        }
+      ],
+      "publicClasses": [
+        "kui-nav-stack",
+        "kui-nav-stack__chrome",
+        "kui-nav-stack__lead",
+        "kui-nav-stack__back",
+        "kui-nav-stack__back-icon",
+        "kui-nav-stack__title",
+        "kui-nav-stack__actions",
+        "kui-nav-stack__viewport",
+        "kui-nav-stack__view",
+        "kui-nav-stack__view--entering",
+        "kui-nav-stack__view--exiting",
+        "kui-nav-stack__bottom"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=nav-stack",
+        "documentation": "docs/nav-stack.md",
+        "recipe": "docs/app-layouts.md#decision-matrix"
+      }
+    },
+    {
+      "id": "split-view",
+      "name": "SplitView",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A responsive list-detail layout that shows both panes on roomy device classes and collapses to a navigation stack on compact classes.",
+      "uses": [
+        "nav-stack",
+        "resize"
+      ],
+      "purpose": "Present a selectable list and its detail together when space permits, with a one-pane drill-down replacement on compact devices.",
+      "publicExports": [
+        "SplitView",
+        "SplitViewProps",
+        "SplitViewResizable"
+      ],
+      "useWhen": [
+        "Selection in a primary list updates a related detail pane and both should remain visible on roomy device classes.",
+        "The same list-detail flow must become a navigation stack on a handset or portrait tablet."
+      ],
+      "avoidWhen": [
+        "Do not use SplitView for a single linear flow; use NavStack.",
+        "Do not use it for a complex desktop tool with multiple peripheral panels; use Workbench."
+      ],
+      "alternatives": [
+        {
+          "id": "recipe-navigation-stack",
+          "relationship": "responsive-alternative",
+          "when": "SplitView renders the one-pane navigation-stack form on compact device classes."
+        },
+        {
+          "id": "workbench",
+          "relationship": "nearest",
+          "when": "Use Workbench when a desktop-class tool needs more than the list and detail regions."
+        }
+      ],
+      "appOwns": [
+        "device-class policy",
+        "selected item and detail-active state",
+        "list and detail content",
+        "optional list width and persistence",
+        "back action"
+      ],
+      "variants": [
+        "fixed roomy split",
+        "resizable roomy split",
+        "compact list",
+        "compact detail"
+      ],
+      "accessibility": [
+        "Give the overall split and both meaningful panes accessible labels.",
+        "Wire the compact back action and optional separator keyboard behavior, and restore focus when controlled navigation replaces a view."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child",
+        "notes": [
+          "The root owns the two-column split and the list pane owns its separator; list and detail content own their internal padding and scroll behavior."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/split-view",
+        "manualCssImport": "@kerfjs/ui/split-view.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireResizableRegions",
+          "import": "@kerfjs/ui/wire-resizable-regions",
+          "required": false
+        },
+        {
+          "export": "wireNavStack",
+          "import": "@kerfjs/ui/wire-nav-stack",
+          "required": true
+        }
+      ],
+      "publicClasses": [
+        "kui-split-view",
+        "kui-split-view__list",
+        "kui-resizable-region",
+        "kui-split-view__detail",
+        "kui-split-view--compact"
+      ],
+      "publicTokens": [
+        "--kui-split-view-list-width"
+      ],
+      "links": {
+        "catalogRoute": "?component=split-view",
+        "documentation": "docs/split-view.md",
+        "recipe": "docs/app-layouts.md#decision-matrix"
+      }
+    },
+    {
+      "id": "tab-scaffold",
+      "name": "TabScaffold",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A controlled compact-device bottom tab scaffold that keeps every tab scene mounted so its navigation and scroll state survive selection changes.",
+      "uses": [],
+      "purpose": "Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.",
+      "publicExports": [
+        "TabScaffoldTab",
+        "TabScaffoldProps",
+        "TabScaffold"
+      ],
+      "useWhen": [
+        "A handset or portrait-tablet app has two to five co-equal top-level destinations.",
+        "Each destination must stay mounted so its NavStack and scroll position survive tab switches."
+      ],
+      "avoidWhen": [
+        "Do not use TabScaffold for document tabs or reorderable work items; use TabBar.",
+        "Do not retain the bottom bar on desktop when the same destinations should be promoted to a Workbench rail or sidebar."
+      ],
+      "alternatives": [
+        {
+          "id": "tabs",
+          "relationship": "semantic-alternative",
+          "when": "Use TabBar and AppTab for document-style tabpanels, overflow, closing, or reordering."
+        },
+        {
+          "id": "workbench",
+          "relationship": "roomy-alternative",
+          "when": "Promote top-level destinations to a rail or sidebar on desktop-class layouts."
+        }
+      ],
+      "appOwns": [
+        "controlled active tab id",
+        "tab labels, icons, and content",
+        "routing and persistence",
+        "responsive replacement on larger device classes"
+      ],
+      "variants": [
+        "text-only tabs",
+        "icon and text tabs",
+        "one NavStack per tab"
+      ],
+      "accessibility": [
+        "Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.",
+        "Wire selection through the controlled active id while leaving inactive scenes mounted and hidden."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self",
+        "notes": [
+          "The scaffold owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/tab-scaffold",
+        "manualCssImport": "@kerfjs/ui/tab-scaffold.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireTabScaffold",
+          "import": "@kerfjs/ui/wire-tab-scaffold",
+          "required": true
+        }
+      ],
+      "publicClasses": [
+        "kui-tab-scaffold",
+        "kui-tab-scaffold__scenes",
+        "kui-tab-scaffold__scene",
+        "kui-tab-scaffold__bar",
+        "kui-tab-scaffold__tab",
+        "kui-tab-scaffold__tab-icon",
+        "kui-tab-scaffold__tab-label"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=tab-scaffold",
+        "documentation": "docs/tab-scaffold.md",
+        "recipe": "docs/app-layouts.md#decision-matrix"
+      }
+    },
     {
       "id": "workbench",
       "name": "Workbench",
@@ -596,7 +876,12 @@
         "right rail",
         "bottom drawer",
         "all panels",
-        "independently collapsed panels"
+        "independently collapsed panels",
+        "hidden separator",
+        "slide, fade-slide, or instant content",
+        "clipped, scrolling, or popup-visible content",
+        "inline, overlay, or hidden responsive presentation",
+        "safe-area restore control"
       ],
       "accessibility": [
         "Give the Workbench and each meaningful rail or drawer an accessible label.",
@@ -623,14 +908,21 @@
         "kui-workbench__rail",
         "kui-workbench__rail--left",
         "kui-workbench__rail--right",
+        "kui-workbench__drawer",
         "kui-workbench__center",
         "kui-workbench__main",
-        "kui-workbench__drawer",
-        "kui-workbench__panel-content"
+        "kui-workbench__panel-content",
+        "kui-workbench__restore"
       ],
       "publicTokens": [
         "--kui-workbench-rail-width",
-        "--kui-workbench-drawer-height"
+        "--kui-workbench-drawer-height",
+        "--kui-workbench-popup-z",
+        "--kui-workbench-overlay-z",
+        "--kui-workbench-overlay-max-width",
+        "--kui-workbench-overlay-max-height",
+        "--kui-workbench-restore-z",
+        "--kui-workbench-restore-inset"
       ],
       "links": {
         "catalogRoute": "?component=workbench",
@@ -638,20 +930,130 @@
         "recipe": "docs/workbench.md#state-lives-in-the-app"
       }
     },
+    {
+      "id": "collapsible-panel",
+      "name": "CollapsiblePanel",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A standalone controlled left or right rail or bottom drawer with standard collapse icons and optional compact-overlay behavior through wireSidebar.",
+      "uses": [
+        "lucide-icon"
+      ],
+      "purpose": "Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.",
+      "publicExports": [
+        "CollapsiblePanelSide",
+        "collapsiblePanelToggleIcon",
+        "CollapsiblePanelToggleProps",
+        "CollapsiblePanelToggle",
+        "CollapsiblePanelProps",
+        "CollapsiblePanel"
+      ],
+      "useWhen": [
+        "An application needs one collapsible side rail or bottom drawer outside a full Workbench.",
+        "The panel should become a dismissable, focus-managed overlay on compact devices."
+      ],
+      "avoidWhen": [
+        "Do not use CollapsiblePanel for a complete editor shell with multiple coordinated rails and a drawer; use Workbench.",
+        "Do not preserve an empty icon-only rail when collapsed; move the restore control into adjacent visible chrome."
+      ],
+      "alternatives": [
+        {
+          "id": "workbench",
+          "relationship": "larger-composition",
+          "when": "Use Workbench when the central work area coordinates multiple peripheral panels."
+        },
+        {
+          "id": "recipe-collapsible-sidebar",
+          "relationship": "recipe",
+          "when": "Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership."
+        }
+      ],
+      "appOwns": [
+        "controlled collapsed state",
+        "panel content and size",
+        "toggle placement",
+        "persistence policy",
+        "compact-device policy"
+      ],
+      "variants": [
+        "left rail",
+        "right rail",
+        "bottom drawer",
+        "collapsed",
+        "compact overlay",
+        "compact responsive replacement",
+        "hidden separator",
+        "slide, fade-slide, or instant content",
+        "clipped, scrolling, or popup-visible content",
+        "safe-area restore control"
+      ],
+      "accessibility": [
+        "Give the panel region and every collapse or restore control an accessible label.",
+        "Keep the restore control outside the disappearing panel and use wireSidebar for focus transfer, Escape, backdrop dismissal, and compact focus trapping."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child",
+        "notes": [
+          "The panel owns its dock-edge separator and size track; its child content owns internal padding and scrolling."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/collapsible-panel",
+        "manualCssImport": "@kerfjs/ui/collapsible-panel.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [
+        {
+          "export": "wireSidebar",
+          "import": "@kerfjs/ui/wire-sidebar",
+          "required": true
+        }
+      ],
+      "publicClasses": [
+        "kui-collapsible-panel",
+        "kui-collapsible-panel--left",
+        "kui-collapsible-panel--right",
+        "kui-collapsible-panel--bottom",
+        "kui-collapsible-panel__content",
+        "kui-collapsible-panel__restore",
+        "kui-collapsible-panel__backdrop",
+        "kui-collapsible-panel__toggle"
+      ],
+      "publicTokens": [
+        "--kui-collapsible-panel-width",
+        "--kui-collapsible-panel-height",
+        "--kui-collapsible-panel-popup-z",
+        "--kui-collapsible-panel-overlay-z",
+        "--kui-collapsible-panel-restore-z",
+        "--kui-collapsible-panel-restore-inset",
+        "--kui-collapsible-panel-backdrop-z"
+      ],
+      "links": {
+        "catalogRoute": "?component=collapsible-panel",
+        "documentation": "docs/collapsible-panel.md",
+        "recipe": "docs/collapsible-panel.md#recipe-and-coverage"
+      }
+    },
     {
       "id": "sunken-panel",
       "name": "SunkenPanel",
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A lowered application surface with one compact inset and a vertical content stack.",
+      "description": "A rounded or square-corner lowered application surface with one compact inset and a vertical content stack.",
       "uses": [],
-      "purpose": "Group a vertical list of application content on a visually lowered surface with one owned 8px inset.",
+      "purpose": "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.",
       "publicExports": [
         "SunkenPanel"
       ],
       "useWhen": [
-        "A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack."
+        "A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack.",
+        "Use the default rounded shape for an inset surface; choose square for a flush or edge-to-edge application area."
       ],
       "avoidWhen": [
         "Do not use it merely to add padding, as a substitute for Pane anatomy, or around children that already own the same outer surface."
@@ -665,10 +1067,13 @@
       ],
       "appOwns": [
         "region semantics and accessible name",
+        "corner shape",
         "scroll ownership",
         "child ordering and content"
       ],
       "variants": [
+        "rounded surface",
+        "square-corner surface",
         "unnamed surface",
         "named region"
       ],
@@ -723,25 +1128,21 @@
         "Toolbar"
       ],
       "useWhen": [
-        "Compose persistent application chrome with leading, center, and trailing regions."
+        "Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions."
       ],
       "avoidWhen": [
-        "Do not use for a page title or dialog heading."
-      ],
-      "alternatives": [
-        {
-          "id": "panel-header",
-          "relationship": "nearest"
-        }
+        "Do not use it as a generic wrapper when no toolbar or heading relationship exists."
       ],
+      "alternatives": [],
       "appOwns": [
         "actions",
         "command availability",
         "responsive relocation"
       ],
       "variants": [
-        "divider",
-        "no divider",
+        "bottom divider (default)",
+        "no dividers",
+        "top/right/bottom/left divider combinations",
         "centered content"
       ],
       "accessibility": [
@@ -752,7 +1153,7 @@
         "border": "conditional",
         "padding": "self",
         "notes": [
-          "Padding belongs to the toolbar; the optional divider variant also owns its border."
+          "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges."
         ]
       },
       "delivery": {
@@ -771,7 +1172,8 @@
       ],
       "publicTokens": [
         "--kui-color-border",
-        "--kui-font-sans"
+        "--kui-font-sans",
+        "--kui-toolbar-divider-color"
       ],
       "links": {
         "catalogRoute": "?component=toolbar",
@@ -785,12 +1187,12 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Contained, borderless, pressed, and single-control toolbar groups.",
+      "description": "Typed toolbar groups for compact, mixed, selected, dropdown, and avatar controls.",
       "uses": [
         "lucide-icon",
         "segmented-control"
       ],
-      "purpose": "Contained, borderless, pressed, and single-control toolbar groups.",
+      "purpose": "Typed toolbar groups for compact, mixed, selected, dropdown, and avatar controls.",
       "publicExports": [
         "ToolbarControlGroup"
       ],
@@ -821,7 +1223,14 @@
         "contained",
         "borderless",
         "pressed",
-        "single"
+        "single",
+        "default or compact size",
+        "comfortable or tight density",
+        "icon, text, mixed, or avatar content",
+        "raised, filled, or outline selected chrome",
+        "brand or neutral selected tone",
+        "nested dropdown trigger",
+        "avatar scrim"
       ],
       "accessibility": [
         "Name the group when its relationship is not evident from context."
@@ -871,6 +1280,75 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "surface-scaffold",
+      "name": "Surface scaffolds",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Typed Web Awesome dialog and popup surface sizing, presentation, and inset composition.",
+      "uses": [
+        "wa-dialog",
+        "wa-dropdown",
+        "wa-dropdown-item"
+      ],
+      "purpose": "Configure recurring dialog and popup geometry without consumer ::part() overrides.",
+      "publicExports": [
+        "DialogSurface",
+        "PopupSurface"
+      ],
+      "useWhen": [
+        "A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset."
+      ],
+      "avoidWhen": [
+        "Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "open state",
+        "focus lifecycle",
+        "dismissal policy",
+        "content",
+        "outer placement"
+      ],
+      "variants": [
+        "small, medium, or large dialog",
+        "modal, side-sheet, or fullscreen dialog",
+        "none, compact, or comfortable body and footer inset",
+        "standard, compact, or zero-inset popup menu"
+      ],
+      "accessibility": [
+        "Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.",
+        "Use popup surfaces only for real dropdown menus with named triggers."
+      ],
+      "geometry": {
+        "margin": "parent",
+        "border": "child",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/surface-scaffold",
+        "manualCssImport": "@kerfjs/ui/surface-scaffold.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-dialog-surface",
+        "kui-popup-surface"
+      ],
+      "publicTokens": [
+        "--kui-radius-l",
+        "--kui-wa-container-inset",
+        "--kui-wa-surface-inset"
+      ],
+      "links": {
+        "catalogRoute": "?component=surface-scaffold",
+        "documentation": "docs/surface-scaffold.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "floating-toolbar",
       "name": "FloatingToolbar",
@@ -951,17 +1429,12 @@
         "ToolbarText"
       ],
       "useWhen": [
-        "Render toolbar identity text at a supported hierarchy size."
+        "Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics."
       ],
       "avoidWhen": [
-        "Do not substitute it for document heading semantics."
-      ],
-      "alternatives": [
-        {
-          "id": "panel-header",
-          "relationship": "nearest"
-        }
+        "Do not omit headingLevel when the text is the page or section heading."
       ],
+      "alternatives": [],
       "appOwns": [
         "text",
         "responsive priority"
@@ -1012,7 +1485,9 @@
       "source": "kerf",
       "description": "Page, dialog, and definition-list hierarchy.",
       "uses": [
-        "panel-header",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
         "value-table"
       ],
       "purpose": "Page, dialog, and definition-list hierarchy.",
@@ -1023,16 +1498,7 @@
       "avoidWhen": [
         "Do not reuse one header primitive only because its typography looks similar."
       ],
-      "alternatives": [
-        {
-          "id": "toolbar",
-          "relationship": "nearest"
-        },
-        {
-          "id": "panel-header",
-          "relationship": "nearest"
-        }
-      ],
+      "alternatives": [],
       "appOwns": [
         "scope hierarchy",
         "copy",
@@ -1065,91 +1531,6 @@
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
     },
-    {
-      "id": "panel-header",
-      "name": "PanelHeader",
-      "category": "Structure",
-      "kind": "component",
-      "source": "kerf",
-      "description": "A plain Toolbar as a panel, dialog, or page heading: optional icon group, an extra-large title, trailing actions, and an optional subtitle row.",
-      "uses": [
-        "lucide-icon",
-        "toolbar",
-        "toolbar-control-group",
-        "toolbar-text"
-      ],
-      "purpose": "A plain Toolbar as a panel, dialog, or page heading: optional icon group, an extra-large title, trailing actions, and an optional subtitle row.",
-      "publicExports": [
-        "PanelHeader"
-      ],
-      "useWhen": [
-        "Give a panel, dialog, or page a heading with an extra-large title, optional icon and subtitle, and trailing actions."
-      ],
-      "avoidWhen": [
-        "Do not use it as persistent application chrome; use Toolbar. It supplies header structure, not modal behavior."
-      ],
-      "alternatives": [
-        {
-          "id": "toolbar",
-          "relationship": "nearest"
-        },
-        {
-          "id": "wa-dialog",
-          "relationship": "prefer-over"
-        }
-      ],
-      "appOwns": [
-        "open state",
-        "focus lifecycle",
-        "dismissal",
-        "copy",
-        "the trailing action controls"
-      ],
-      "variants": [
-        "title",
-        "optional summary",
-        "icon",
-        "actions",
-        "placeholder (loading)",
-        "page heading (headingLevel)"
-      ],
-      "accessibility": [
-        "Connect the title id and any provided summary id to the dialog or panel host.",
-        "Pass the trailing actions as a labeled ToolbarControlGroup when the group needs an accessible name.",
-        "For a page/view title pass headingLevel (usually 1) so the title exposes role=heading + aria-level as a heading landmark; omit it for a dialog title, which is referenced via aria-labelledby to titleId."
-      ],
-      "geometry": {
-        "margin": "none",
-        "border": "child",
-        "padding": "child"
-      },
-      "delivery": {
-        "browserImport": "@kerfjs/ui/panel-header",
-        "manualCssImport": "@kerfjs/ui/panel-header.css",
-        "sideEffects": [
-          "browser-condition-css"
-        ]
-      },
-      "wiring": [],
-      "publicClasses": [
-        "kui-panel-header",
-        "kui-panel-header__icon",
-        "kui-panel-header__summary"
-      ],
-      "publicTokens": [
-        "--kui-color-brand-fill-quiet",
-        "--kui-color-brand-on-quiet",
-        "--kui-color-text-quiet",
-        "--kui-panel-header-icon-background",
-        "--kui-panel-header-icon-border",
-        "--kui-panel-header-icon-foreground"
-      ],
-      "links": {
-        "catalogRoute": "?component=panel-header",
-        "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#ambiguous-choices"
-      }
-    },
     {
       "id": "value-table",
       "name": "ValueTable",
@@ -1226,63 +1607,69 @@
     },
     {
       "id": "list",
-      "name": "List composition",
+      "name": "List",
       "category": "Navigation",
-      "kind": "composition",
+      "kind": "component",
       "source": "kerf",
-      "description": "Navigation rows and section headers composed as ordinary content items inside a pane.",
+      "description": "A stretch-aligned vertical stack with optional gap, flex growth, vertical scrolling, and independently selectable divider edges.",
       "uses": [
         "list-header",
         "list-action-row",
         "list-item"
       ],
-      "purpose": "Compose navigation with the same pane, content stack, item, and toolbar geometry used throughout the application, including a controlled ListHeader disclosure only when it reveals real content.",
-      "publicExports": [],
+      "purpose": "Standardize vertical component layout and its scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.",
+      "publicExports": [
+        "List"
+      ],
       "useWhen": [
-        "Compose navigation sections in a .kui-content stack, using ListHeader, ListItem, and ListActionRow children plus optional .kui-content-item surfaces."
+        "Arrange component rows or sections in a vertical stretch-aligned stack.",
+        "Let one bounded list own vertical scrolling, flex growth, or one or more physical-edge dividers."
       ],
       "avoidWhen": [
-        "Do not add sidebar-specific wrapper padding or use the pattern for unrelated inline controls.",
-        "Do not place a disclosure chevron on navigation that does not expand content."
+        "Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.",
+        "Do not create nested scroll owners or use divider sides as a substitute for meaningful grouping."
       ],
       "alternatives": [],
       "appOwns": [
-        "information architecture",
-        "routing",
-        "responsive shell behavior"
+        "child semantics and content",
+        "the bounded height needed for scrolling",
+        "gap, flex, and divider choices"
       ],
       "variants": [
-        "section",
-        "icon rows",
-        "iconless rows",
-        "content item",
-        "pane toolbar or footer"
+        "no gap",
+        "standard or custom gap",
+        "boolean or custom flex",
+        "scrollable",
+        "top/right/bottom/left divider combinations"
       ],
       "accessibility": [
-        "Use native links for link navigation, retain ListItem button semantics for actions, and keep standalone header and toolbar actions at least 44px square.",
-        "A ListHeader disclosure controls real content, keeps a stable accessible name and aria-expanded state, and uses the production DisclosureArrow visual."
+        "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
+        "Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll."
       ],
       "geometry": {
-        "margin": "child",
-        "border": "child",
-        "padding": "child"
+        "margin": "none",
+        "border": "conditional",
+        "padding": "none",
+        "notes": [
+          "List adds no margin or padding; dividerSides draws only the selected physical edges without changing box geometry."
+        ]
       },
       "delivery": {
-        "manualCssImport": "@kerfjs/ui/layout.css",
+        "browserImport": "@kerfjs/ui/list",
+        "manualCssImport": "@kerfjs/ui/list.css",
         "sideEffects": [
-          "css"
+          "browser-condition-css"
         ]
       },
       "wiring": [],
       "publicClasses": [
-        "kui-content",
-        "kui-content-item"
+        "kui-list"
       ],
       "publicTokens": [
-        "--kui-layout-content-gap",
-        "--kui-layout-inline-margin",
-        "--kui-layout-item-padding",
-        "--kui-layout-rounded-radius"
+        "--kui-color-border",
+        "--kui-layout-item-gap",
+        "--kui-list-divider-color",
+        "--kui-list-gap"
       ],
       "links": {
         "catalogRoute": "?component=list",
@@ -1296,7 +1683,7 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Full-width section headings with a semantic neutral count pill or non-count badge, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
+      "description": "Configurable section headings with semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
       "uses": [
         "lucide-icon",
         "disclosure-arrow"
@@ -1314,7 +1701,7 @@
       ],
       "alternatives": [
         {
-          "id": "panel-header",
+          "id": "toolbar",
           "relationship": "nearest"
         }
       ],
@@ -1333,7 +1720,10 @@
         "badge",
         "action",
         "toggle",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "compact density",
+        "neutral, accent, or danger indicator tone",
+        "before, after, or paired group divider"
       ],
       "accessibility": [
         "A valid count is hidden as duplicate visual text and its required localized countLabel joins the owned heading or disclosure-button accessible name; zero remains visible.",
@@ -1375,7 +1765,11 @@
         "--kui-layout-item-padding",
         "--kui-layout-pill-radius",
         "--kui-list-header-count-font-size",
-        "--kui-list-header-hover-background"
+        "--kui-list-header-hover-background",
+        "--kui-list-group-divider-color",
+        "--kui-color-brand-on-normal",
+        "--kui-color-danger-fill-normal",
+        "--kui-color-danger-on-normal"
       ],
       "links": {
         "catalogRoute": "?component=list-header",
@@ -1389,9 +1783,10 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Full-width navigation rows with sibling primary and trailing native-button actions.",
+      "description": "Configurable navigation rows with structured labels, status/busy metadata, density, group dividers, and sibling primary/trailing native-button actions.",
       "uses": [
-        "lucide-icon"
+        "lucide-icon",
+        "loading-spinner"
       ],
       "purpose": "Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.",
       "publicExports": [
@@ -1428,7 +1823,12 @@
         "disabled primary",
         "disabled trailing action",
         "multiline",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "compact density",
+        "description and status",
+        "busy while retaining content",
+        "interaction-revealed trailing action",
+        "before, after, or paired group divider"
       ],
       "accessibility": [
         "The noninteractive root contains two sibling native buttons in primary-then-trailing focus order; each button has its own action, item identity, accessible name, and disabled state.",
@@ -1451,6 +1851,9 @@
         "kui-list-action-row",
         "kui-list-action-row__icon",
         "kui-list-action-row__label",
+        "kui-list-action-row__primary-label",
+        "kui-list-action-row__description",
+        "kui-list-action-row__status",
         "kui-list-action-row__primary",
         "kui-list-action-row__trailing-action"
       ],
@@ -1461,6 +1864,8 @@
         "--kui-color-neutral-fill-normal",
         "--kui-color-neutral-fill-quiet",
         "--kui-color-neutral-on-normal",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-neutral-border-quiet",
         "--kui-focus-ring",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
@@ -1475,7 +1880,9 @@
         "--kui-list-action-row-selected-background",
         "--kui-list-action-row-selected-border",
         "--kui-list-action-row-selected-color",
-        "--kui-list-action-row-trailing-hover-background"
+        "--kui-list-action-row-trailing-hover-background",
+        "--kui-list-group-divider-color",
+        "--kui-font-xs"
       ],
       "links": {
         "catalogRoute": "?component=list-action-row",
@@ -1489,9 +1896,10 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Selectable, disabled, trailing, and multiline native-button navigation rows with protected domain metadata hooks.",
+      "description": "Configurable native-button navigation rows with structured labels, status/busy metadata, density, group dividers, and protected domain metadata hooks.",
       "uses": [
-        "lucide-icon"
+        "lucide-icon",
+        "loading-spinner"
       ],
       "purpose": "Selectable, disabled, trailing, and multiline navigation rows.",
       "publicExports": [
@@ -1523,7 +1931,11 @@
         "disabled",
         "trailing",
         "multiline",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "compact density",
+        "description and status",
+        "busy while retaining content",
+        "before, after, or paired group divider"
       ],
       "accessibility": [
         "Uses native button activation; selected maps to aria-current and pressed to aria-pressed; rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls."
@@ -1545,6 +1957,9 @@
         "kui-list-item",
         "kui-list-item__icon",
         "kui-list-item__label",
+        "kui-list-item__primary-label",
+        "kui-list-item__description",
+        "kui-list-item__status",
         "kui-list-item__trailing"
       ],
       "publicTokens": [
@@ -1552,11 +1967,14 @@
         "--kui-color-neutral-fill-quiet",
         "--kui-color-neutral-on-normal",
         "--kui-color-neutral-on-quiet",
+        "--kui-color-neutral-border-quiet",
         "--kui-focus-ring",
         "--kui-list-item-color",
         "--kui-list-item-hover-background",
         "--kui-list-item-selected-background",
         "--kui-list-item-selected-color",
+        "--kui-list-group-divider-color",
+        "--kui-font-xs",
         "--kui-layout-inline-margin",
         "--kui-layout-item-gap",
         "--kui-layout-item-padding",
@@ -1683,11 +2101,11 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Roving-tabindex-ready tabs with protected application metadata and customizable close affordances.",
+      "description": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.",
       "uses": [
         "lucide-icon"
       ],
-      "purpose": "Roving-tabindex-ready tabs with protected application metadata and customizable close affordances.",
+      "purpose": "Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.",
       "publicExports": [
         "AppTab"
       ],
@@ -1708,7 +2126,8 @@
         "selection",
         "close policy",
         "content",
-        "application data attribute values"
+        "application data attribute values",
+        "outer placement"
       ],
       "variants": [
         "selected",
@@ -1717,7 +2136,11 @@
         "leading",
         "trailing",
         "custom close icon",
-        "root metadata"
+        "root metadata",
+        "compact size",
+        "segmented presentation",
+        "icon-only accessible presentation",
+        "label maximum width and truncation"
       ],
       "accessibility": [
         "Compose in a tablist and pair with an application-owned tabpanel.",
@@ -1777,12 +2200,12 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled, reorderable tab strips with horizontal overflow.",
+      "description": "Controlled tab strips with typed rail, segmented, and inspector presentation plus intrinsic or fill allocation.",
       "uses": [
         "tabs",
         "toolbar-control-group"
       ],
-      "purpose": "Controlled, reorderable tab strips with horizontal overflow.",
+      "purpose": "Controlled tab strips with typed rail, segmented, and inspector presentation plus intrinsic or fill allocation.",
       "publicExports": [
         "TabBar",
         "wireTabBars",
@@ -1813,13 +2236,17 @@
         "selection",
         "panels",
         "routing",
-        "persistence"
+        "persistence",
+        "outer placement"
       ],
       "variants": [
         "leading",
         "trailing",
         "overflow",
-        "reorderable"
+        "reorderable",
+        "rail, segmented, and inspector presentation",
+        "intrinsic or fill allocation",
+        "separate or adjacent trailing action"
       ],
       "accessibility": [
         "Keep exactly one selected tab at tabindex 0 and preserve the wiring keyboard model."
@@ -2014,7 +2441,7 @@
       "accessibility": [
         "Announce result changes when useful and keep tokens atomic during editing.",
         "Keep leading and trailing controls aligned to the first text line while content wraps.",
-        "Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion; visual wrapping remains available.",
+        "Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.",
         "In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out."
       ],
       "geometry": {
@@ -2127,7 +2554,12 @@
         "start edge",
         "end edge",
         "collapsed",
-        "custom handle icon"
+        "custom handle icon",
+        "hidden separator",
+        "slide, fade-slide, or instant content",
+        "clipped, scrolling, or popup-visible content",
+        "inline, overlay, or hidden responsive presentation",
+        "safe-area restore control"
       ],
       "accessibility": [
         "Preserve separator naming, value ARIA, and keyboard behavior.",
@@ -2169,7 +2601,8 @@
         "kui-resizable-region",
         "kui-resizable-region__content",
         "kui-resizable-region__handle",
-        "kui-resizable-region__handle-icon"
+        "kui-resizable-region__handle-icon",
+        "kui-resizable-region__restore"
       ],
       "publicTokens": [
         "--kui-color-border",
@@ -2179,6 +2612,10 @@
         "--kui-radius-s",
         "--kui-resizable-region-handle-active-color",
         "--kui-resizable-region-handle-color",
+        "--kui-resizable-region-overlay-z",
+        "--kui-resizable-region-popup-z",
+        "--kui-resizable-region-restore-inset",
+        "--kui-resizable-region-restore-z",
         "--kui-resizable-region-separator-color",
         "--kui-resizable-region-size"
       ],
@@ -2194,13 +2631,13 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "Controlled Web Awesome select with grouped choices and rerender-stable icon slots.",
+      "description": "Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
       "uses": [
         "lucide-icon",
         "wa-select",
         "wa-option"
       ],
-      "purpose": "Controlled Web Awesome select with grouped choices and rerender-stable icon slots.",
+      "purpose": "Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.",
       "publicExports": [
         "Select"
       ],
@@ -2228,7 +2665,9 @@
         "value",
         "validation",
         "choices",
-        "domain mapping"
+        "hint copy",
+        "domain mapping",
+        "outer placement"
       ],
       "variants": [
         "placeholder",
@@ -2236,10 +2675,18 @@
         "fit menu",
         "grouped",
         "custom selected content",
-        "placeholder (loading)"
+        "hint text",
+        "placeholder (loading)",
+        "form, toolbar-borderless, or navigation presentation",
+        "default or compact size",
+        "label or icon-only selected presentation",
+        "select- or group-owned focus ring",
+        "label maximum width and truncation"
       ],
       "accessibility": [
-        "Verify the live value, standard events, focus, and rendered output."
+        "Verify the live value, standard events, focus, and rendered output.",
+        "A nonempty label names the internal combobox; otherwise ariaLabel supplies a visually hidden label without adding control height, including custom selected content.",
+        "Hint text is visible below the control through Web Awesome's native hint relationship; placeholderText remains the empty value inside the closed control."
       ],
       "geometry": {
         "margin": "none",
@@ -2259,6 +2706,7 @@
         "kui-select",
         "kui-select--custom-selected",
         "kui-select--fit-menu",
+        "kui-select--label-hidden",
         "kui-select__custom-selected",
         "kui-select__group",
         "kui-select__group--separated",
@@ -2385,6 +2833,7 @@
         }
       ],
       "appOwns": [
+        "badge content",
         "state mapping",
         "message lifetime",
         "retry behavior",
@@ -2398,10 +2847,12 @@
         "danger",
         "status",
         "alert",
+        "badge",
         "placeholder (loading)"
       ],
       "accessibility": [
-        "Use alert urgency only for an attention-requiring failure."
+        "Use alert urgency only for an attention-requiring failure.",
+        "Keep optional badge content terse and do not rely on its tone alone for meaning."
       ],
       "geometry": {
         "margin": "self",
@@ -2419,7 +2870,9 @@
       "publicClasses": [
         "kui-state-banner",
         "kui-state-banner__action",
+        "kui-state-banner__badge",
         "kui-state-banner__copy",
+        "kui-state-banner__detail",
         "kui-state-banner__icon"
       ],
       "publicTokens": [
@@ -2446,6 +2899,8 @@
         "--kui-state-banner-action-background",
         "--kui-state-banner-action-hover-background",
         "--kui-state-banner-background",
+        "--kui-state-banner-badge-background",
+        "--kui-state-banner-badge-foreground",
         "--kui-state-banner-border",
         "--kui-state-banner-danger-background",
         "--kui-state-banner-danger-border",
@@ -5405,7 +5860,6 @@
         "toolbar-control-group",
         "list-header",
         "list-item",
-        "panel-header",
         "resize",
         "value-table",
         "layout"
@@ -5483,7 +5937,9 @@
       "source": "kerf",
       "purpose": "Page identity with primary, secondary, and overflow actions that relocate at narrow widths.",
       "uses": [
-        "panel-header",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
         "state-banner",
         "layout"
       ],
@@ -5491,7 +5947,7 @@
         "A workspace page needs one primary heading and a small prioritized action set."
       ],
       "avoidWhen": [
-        "Use Toolbar for persistent application chrome or PanelHeader for a focused modal task."
+        "Use a smaller local heading when the page does not need actions or persistent identity."
       ],
       "appOwns": [
         "authorization",
@@ -5519,9 +5975,11 @@
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "Production modal containing a PanelHeader, navigable record master list, and ValueTable detail.",
+      "purpose": "Production modal containing a Toolbar heading, navigable record master list, and ValueTable detail.",
       "uses": [
-        "panel-header",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
         "list-header",
         "list-item",
         "value-table",
@@ -5541,7 +5999,7 @@
         "record actions"
       ],
       "accessibility": [
-        "Web Awesome owns modal focus and Escape; the application adapter restores the invoking control after hide, and PanelHeader supplies the visible hierarchy."
+        "Web Awesome owns modal focus and Escape; the application adapter restores the invoking control after hide, and Toolbar plus ToolbarText supply the visible hierarchy."
       ],
       "delivery": {
         "sideEffects": [
@@ -5561,9 +6019,11 @@
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "One visible publishing-form surface with PanelHeader hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.",
+      "purpose": "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.",
       "uses": [
-        "panel-header",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
         "select",
         "state-banner",
         "wa-input",
@@ -5584,7 +6044,7 @@
         "transport"
       ],
       "accessibility": [
-        "The form references PanelHeader's title and summary ids; production fields own labels and help; invalid submission creates an assertive persistent StateBanner while successful submission creates a polite persistent banner."
+        "The form references its ToolbarText title and supporting-summary ids; production fields own labels and help; invalid submission creates an assertive persistent StateBanner while successful submission creates a polite persistent banner."
       ],
       "delivery": {
         "sideEffects": [
@@ -5606,7 +6066,9 @@
       "source": "kerf",
       "purpose": "Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.",
       "uses": [
-        "panel-header",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
         "state-banner",
         "empty-state",
         "loading-spinner",
@@ -5727,7 +6189,9 @@
       "source": "kerf",
       "purpose": "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.",
       "uses": [
-        "panel-header",
+        "toolbar",
+        "toolbar-control-group",
+        "toolbar-text",
         "value-table",
         "select",
         "segmented-control",
@@ -5770,7 +6234,6 @@
       "source": "kerf",
       "purpose": "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.",
       "uses": [
-        "panel-header",
         "list-header",
         "list-item",
         "toolbar",