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

package/README.md

@@ -15,7 +15,7 @@ For connective application patterns, use the seven [production composition
 recipes](./docs/recipes.md). Each has a stable catalog route, runnable state,
 public-subpath source, semantic layout ownership, and explicit application
 customization boundaries. The composer recipe demonstrates one coherent form
-surface with `PanelHeader` hierarchy and field/action controls aligned to the
+surface with a `Toolbar`/`ToolbarText` heading and field/action controls aligned to the
 shared 8px gutter; only persistent feedback adds a nested semantic
 `StateBanner` surface.
 
@@ -41,11 +41,7 @@ mount(root, () => (
   <>
     <Toolbar
       label="Document"
-      leading={
-        <ToolbarControlGroup appearance="borderless" single>
-          <ToolbarText text="Notes" />
-        </ToolbarControlGroup>
-      }
+      leading={<ToolbarText text="Notes" />}
     />
     <section>
       <ListHeader
@@ -120,14 +116,24 @@ as a `New` marker.
 | `DisclosureArrow`                                                   | `@kerfjs/ui/disclosure-arrow`           | `@kerfjs/ui/disclosure-arrow.css`      |
 | `Toolbar`                                                           | `@kerfjs/ui/toolbar`                    | `@kerfjs/ui/toolbar.css`               |
 | `ToolbarControlGroup`                                               | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css` |
+| `DialogSurface`, `PopupSurface`                                     | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`      |
 | `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`      |
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
+| `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |
 | `ListActionRow`                                                     | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`       |
 | `ListItem`                                                          | `@kerfjs/ui/list-item`                  | `@kerfjs/ui/list-item.css`             |
 | `ListHeader`                                                        | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`           |
 | `ListInsetControl`                                                  | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`    |
 | `ListInsetText`                                                     | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`       |
 | `Pane`                                                              | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                  |
+| `NavStack`                                                          | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`             |
+| `wireNavStack`                                                      | `@kerfjs/ui/wire-nav-stack`             | —                                      |
+| `SplitView`                                                         | `@kerfjs/ui/split-view`                 | `@kerfjs/ui/split-view.css`            |
+| `TabScaffold`                                                       | `@kerfjs/ui/tab-scaffold`               | `@kerfjs/ui/tab-scaffold.css`          |
+| `wireTabScaffold`                                                   | `@kerfjs/ui/wire-tab-scaffold`          | —                                      |
+| `Workbench`                                                         | `@kerfjs/ui/workbench`                  | `@kerfjs/ui/workbench.css`             |
+| `CollapsiblePanel`, `CollapsiblePanelToggle`                        | `@kerfjs/ui/collapsible-panel`          | `@kerfjs/ui/collapsible-panel.css`     |
+| `wireSidebar`                                                       | `@kerfjs/ui/wire-sidebar`               | —                                      |
 | Content and navigation composition                                  | —                                       | `@kerfjs/ui/layout.css`                |
 | `ResizableRegion`                                                   | `@kerfjs/ui/resizable-region`           | `@kerfjs/ui/resizable-region.css`      |
 | `wireResizableRegions`                                              | `@kerfjs/ui/wire-resizable-regions`     | —                                      |
@@ -143,22 +149,22 @@ as a `New` marker.
 | `wireTokenSearchFields`                                             | `@kerfjs/ui/wire-token-search-fields`   | —                                      |
 | `StateBanner`                                                       | `@kerfjs/ui/state-banner`               | `@kerfjs/ui/state-banner.css`          |
 | `EmptyState`                                                        | `@kerfjs/ui/empty-state`                | `@kerfjs/ui/empty-state.css`           |
-| `PanelHeader`                                                       | `@kerfjs/ui/panel-header`               | `@kerfjs/ui/panel-header.css`          |
 | `ValueTable`, `ValueTableRow`                                       | `@kerfjs/ui/value-table`                | `@kerfjs/ui/value-table.css`           |
 
-Opt-in application layouts keep JavaScript and CSS explicit. For the
-desktop-class multi-panel shell, import `Workbench` from
-`@kerfjs/ui/workbench` and load `@kerfjs/ui/workbench.css`; its supported
-classes and size tokens are cataloged under the `workbench` entry. See
-[`docs/workbench.md`](./docs/workbench.md) for panel ownership and responsive
-replacement guidance.
-
-`PanelHeader` is a plain `Toolbar` used as a panel, dialog, or page heading: an
-optional icon control group (given a brand fill with a matching border), the
-title as extra-large `ToolbarText`, the app's trailing action controls, and an
-optional subtitle on a separate row below the title. It overrides no toolbar
-styles — the app passes its own trailing controls (typically a
-`ToolbarControlGroup`).
+Opt-in application layouts keep JavaScript and CSS explicit. Import each
+layout from its component subpath, load the matching manual CSS export, and
+add its wire subpath when the layout has interactive behavior. The catalog
+entries for `nav-stack`, `split-view`, `tab-scaffold`, `workbench`, and
+`collapsible-panel` document their selection rules, ownership boundaries,
+public classes, tokens, and focused demos. See
+[`docs/app-layouts.md`](./docs/app-layouts.md) for the layout decision matrix.
+
+Compose panel, dialog, and page headings directly with `Toolbar`: put an optional
+icon in a `ToolbarControlGroup`, use a direct extra-large `ToolbarText` for the
+title, and put actions in the trailing zone inside their own control group. Set
+`headingLevel` for page or section headings. Supporting copy is app-owned content
+below the toolbar and should be connected to its host with `aria-describedby`
+when it adds useful context.
 
 `DisclosureArrow` defaults to an 18px root-scaled decorative visual. Override
 `--kui-disclosure-arrow-size` at the narrowest useful scope when a consumer
@@ -302,7 +308,7 @@ retention policy, and a separate unscored human-visual rubric. See the
 
 ### Unified repair-loop doctor
 
-Use `kerf-ui-doctor` for the supported application repair loop across profile/catalog validation, TypeScript, the Kerf UI ESLint preset, static layout analysis, and an optional explicitly authorized browser evaluation. It emits one portable versioned JSON report with deterministic exit codes, exact suppressions, monorepo package selection, changed/full modes, caching, and local-path redaction. See the [UI doctor guide](./docs/ui-doctor.md).
+Use `kerf-ui-doctor` for the supported application repair loop across profile/catalog validation, TypeScript, the Kerf UI ESLint preset, static layout analysis, and an optional explicitly authorized browser evaluation. Its isolated Kerf lint pass preserves each file's applicable core-rule and suppression settings without executing consumer plugin rules. It emits one portable versioned JSON report with deterministic exit codes, exact suppressions, monorepo package selection, changed/full modes, caching, and local-path redaction. See the [UI doctor guide](./docs/ui-doctor.md).
 
 For code generation, pair catalog selection guidance with the checked-in
 [`public-api-signatures-v1.md`](./ai/public-api-signatures-v1.md) declaration
@@ -478,7 +484,12 @@ Call `wireTokenSearchFields()` once at a stable root to make Enter submit throug
 `onSubmit` without inserting a contenteditable line break and to preserve focus
 plus the text-relative caret when keyboard deletion of a chip causes controlled
 rendering to replace the editor. A select-all deletion is normalized to a truly
-empty editor even when the browser leaves an atomic chip or line break behind.
+empty editor even when the browser leaves an atomic chip or line break behind;
+replacement typing consumes that intent so a later Backspace/Delete remains an
+ordinary character edit.
+Managed deletion keeps a collapsible replacement editor open and focused before
+the next keystroke; applications must persist both query and tokens from the DOM
+read. Genuine outside focus and Escape still collapse an empty field.
 Text still wraps visually when it reaches the field edge.
 Clear actions should empty the editor's `textContent` before clearing app state.
 The leading icon, first text line, clear action, and trailing slot share one
@@ -516,6 +527,13 @@ import "@kerfjs/ui/select/register";
 ```
 
 That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it.
+Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
+nonempty visible label takes precedence when both are supplied. Kerf names the
+actual shadow combobox without adding visible label spacing; this also works
+with `renderSelected`, and needs no application shadow-DOM patch. Use `hint`
+for persistent supporting text below the control and `placeholderText` for the
+empty value inside the closed control. Loading placeholders preserve the hint.
+
 `Select` also owns the Kerf/Web Awesome reconciliation boundary: option icons
 keep stable slotted elements across rerenders, and `renderSelected` content is
 replaced when the controlled value changes. Consumers do not need to add
@@ -528,7 +546,11 @@ Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over
 Split Panel. `ResizableRegion` includes Hot Sheet 2's 1px separator and
 hover/focus grip. Its optional `handleIcon` replaces only the decorative glyph;
 the component and `wireResizableRegions()` retain separator semantics and
-pointer/keyboard behavior. Consider Web Awesome Popup when its anchored-positioning
+pointer/keyboard behavior. Typed policies cover separator visibility,
+instant-track/composited-content collapse, popup-safe overflow,
+inline/overlay/hidden responsive presentation, and safe-area restore controls;
+the same policies are available on `Workbench` and `CollapsiblePanel`. Consider
+Web Awesome Popup when its anchored-positioning
 engine removes custom placement code; treat Tree, Animated Image, Comparison,
 Zoomable Frame, and the displaced alternatives above as exceptional rather
 than default patterns. The detailed rationale lives in the theme contract.

package/ai/application-ui-diagnostic-ids-v1.json

@@ -38,6 +38,9 @@
     "KUI-L007",
     "KUI-L008",
     "KUI-L009",
+    "KUI-L010",
+    "KUI-L011",
+    "KUI-L012",
     "KUI-L090",
     "KUI-L101",
     "KUI-L102",

package/ai/application-ui-profile.defaults.json

@@ -19,7 +19,7 @@
       "avoid": ["@kerfjs/ui:wa-button-group"]
     },
     "navigation-row": { "preferred": "@kerfjs/ui:list-item" },
-    "panel-heading": { "preferred": "@kerfjs/ui:panel-header" },
+    "panel-heading": { "preferred": "@kerfjs/ui:toolbar" },
     "structured-search": { "preferred": "@kerfjs/ui:token-search-field" }
   },
   "theme": {

package/ai/compile-time-contracts-v1.json

@@ -54,14 +54,6 @@
     },
     {
       "id": "KUI-T007",
-      "catalogKey": "@kerfjs/ui:panel-header",
-      "publicImport": "@kerfjs/ui/panel-header",
-      "symbols": ["PanelHeaderProps"],
-      "kind": "conditional-property",
-      "summary": "PanelHeader summaryId cannot be supplied without rendered summary content."
-    },
-    {
-      "id": "KUI-T008",
       "catalogKey": "@kerfjs/ui:toolbar-text",
       "publicImport": "@kerfjs/ui/toolbar-text",
       "symbols": ["ToolbarTextProps"],
@@ -69,14 +61,14 @@
       "summary": "ToolbarText maxLines is accepted only when wrapping is enabled."
     },
     {
-      "id": "KUI-T009",
+      "id": "KUI-T008",
       "publicImport": "@kerfjs/ui/tab-scaffold",
       "symbols": ["TabScaffoldTab", "TabScaffoldProps"],
       "kind": "literal-identity",
       "summary": "Literal TabScaffold active ids are constrained to the declared tab ids; dynamic integrations may widen the generic to string."
     },
     {
-      "id": "KUI-T010",
+      "id": "KUI-T009",
       "catalogKey": "@kerfjs/ui:token-search-field",
       "publicImport": "@kerfjs/ui/wire-token-search-fields",
       "symbols": ["TokenSearchKeyboardOptions", "WireTokenSearchFieldsOptions"],
@@ -84,9 +76,10 @@
       "summary": "Adjacent-token removal requires the callback that commits removal to application-owned state."
     },
     {
-      "id": "KUI-T011",
+      "id": "KUI-T010",
       "publicImport": "@kerfjs/ui",
       "symbols": [
+        "DividerSides",
         "StateBannerUrgency",
         "TabActivation",
         "ToolbarControlGroupAppearance",
@@ -95,7 +88,7 @@
         "ToolbarControlGroupTone"
       ],
       "kind": "finite-vocabulary",
-      "summary": "Finite public variant vocabularies are named exported unions rather than anonymous string sets."
+      "summary": "Finite public variant vocabularies, including canonical divider-edge combinations, are named exported unions rather than anonymous string sets."
     }
   ]
 }

package/ai/component-catalog-v2-overrides.json

@@ -1,7 +1,12 @@
 {
   "@kerfjs/ui:toolbar": {
     "_source": "docs/component-selection.md#toolbar-composition",
-    "contexts": ["application-chrome", "panel-header"],
+    "contexts": [
+      "application-chrome",
+      "page-header",
+      "panel-header",
+      "dialog-header"
+    ],
     "zones": [
       {
         "id": "leading",
@@ -40,7 +45,7 @@
     "_source": "docs/component-selection.md#toolbar-composition",
     "parents": {
       "mode": "listed",
-      "entries": ["@kerfjs/ui:toolbar", "@kerfjs/ui:panel-header"]
+      "entries": ["@kerfjs/ui:toolbar"]
     },
     "contexts": ["toolbar-zone"],
     "zones": [
@@ -57,57 +62,15 @@
       "requiredConcepts": ["control"]
     }
   },
-  "@kerfjs/ui:panel-header": {
-    "_source": "docs/component-selection.md#problem-to-component-matrix",
-    "contexts": ["page-header", "panel-header", "dialog-header"],
-    "zones": [
-      {
-        "id": "title",
-        "accepts": ["text"],
-        "cardinality": { "min": 1, "max": 1 },
-        "exclusiveWith": []
-      },
-      {
-        "id": "subtitle",
-        "accepts": ["text"],
-        "cardinality": { "min": 0, "max": 1 },
-        "exclusiveWith": []
-      },
-      {
-        "id": "controls",
-        "accepts": ["control"],
-        "cardinality": { "min": 0, "max": "unbounded" },
-        "exclusiveWith": []
-      }
-    ],
-    "state": [
-      { "id": "placeholder", "owner": "controlled", "required": false }
-    ],
-    "diagnostics": [
-      {
-        "id": "KUI-C102",
-        "severity": "error",
-        "when": "the title is absent",
-        "message": "PanelHeader requires a title that names its page, panel, or dialog."
-      }
-    ]
-  },
   "@kerfjs/ui:list": {
-    "_source": "docs/component-selection.md#correct-composition-and-duplicated-markup-trap",
-    "contexts": ["navigation-list"],
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["application-ui", "navigation-list", "vertical-layout"],
     "children": {
-      "mode": "listed",
-      "concepts": ["list-header", "list-item", "list-action-row"],
+      "mode": "any",
+      "concepts": [],
       "requiredConcepts": []
     },
-    "zones": [
-      {
-        "id": "rows",
-        "accepts": ["list-header", "list-item", "list-action-row"],
-        "cardinality": { "min": 1, "max": "unbounded" },
-        "exclusiveWith": []
-      }
-    ]
+    "zones": []
   },
   "@kerfjs/ui:list-header": {
     "_source": "docs/accessibility.md#shared-rules",

package/ai/component-catalog-v2.d.ts

@@ -54,6 +54,7 @@ export interface CatalogCompositionEntryV2 {
     rootClass: string | null;
     publicClasses: string[];
     publicTokens: string[];
+    publicParts?: string[];
   };
   diagnostics: CatalogDiagnostic[];
   provenance: { selection: string; composition: string };