@kerfjs/ui 5.0.0-beta.49 → 5.0.0-beta.50

package/README.md

@@ -101,6 +101,14 @@ components, or a generic `slots` object. The v2 composition catalog publishes
 sound prop bindings as `zone.jsx.prop`, allowing ESLint to validate statically
 visible content and cardinality without guessing from zone names.
 
+Stable single-root visual components also accept the explicit native
+`slot?: string` prop, so their returned root can participate directly in a web
+component's named slot and keep that assignment through Kerf rerenders. This is
+a narrow interop attribute, not general native-attribute spreading. The
+multi-root `ResizableRegion` and `CollapsiblePanel` intentionally omit it
+because neither has one unambiguous returned root; `CollapsiblePanelToggle`
+supports it as a normal single-root control.
+
 `ListItem.rootAttributes`, `ListHeader.rootAttributes`,
 `ListActionRow.rootAttributes`, `AppTab.rootAttributes`,
 `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
@@ -165,9 +173,10 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | Component                                                           | Browser import (includes reachable CSS) | Manual CSS export                      |
 | ------------------------------------------------------------------- | --------------------------------------- | -------------------------------------- |
 | `LucideIcon`                                                        | `@kerfjs/ui/lucide-icon`                | `@kerfjs/ui/lucide-icon.css`           |
+| `Badge`                                                             | `@kerfjs/ui/badge`                      | `@kerfjs/ui/badge.css`                 |
 | `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` |
+| `ToolbarControlGroup`, `ToolbarActionLink`                          | `@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`          |
@@ -258,9 +267,10 @@ without guessing from a screenshot or private CSS.
 Catalog demo authoring is deliberately separate from the entry inventory. Load
 [`catalog-authoring.json`](./ai/catalog-authoring.json) to discover the
 authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract),
-the exact API-signature context, public imports/helpers, and sanctioned metadata
-slot. Keeping this as a companion artifact prevents per-entry selection facts
-from duplicating presentation rules.
+the exact API-signature context, public imports/helpers, sanctioned metadata
+slot, three-kind taxonomy, and functional-group/importance ordering policy.
+Keeping this as a companion artifact prevents per-entry selection facts from
+duplicating presentation rules.
 
 Tools that evaluate composition may additionally load
 [`component-catalog-v2.json`](./ai/component-catalog-v2.json). It is a
@@ -398,6 +408,19 @@ roots therefore do not need a transitive stylesheet list, and removing the last
 component import also removes its reachable CSS. This is component-level CSS
 tree shaking; variants within an imported component remain together.
 
+When one public subpath groups several visual components, its source is a
+folder: one component per file and one owned stylesheet per visual component.
+The public JavaScript/TypeScript compatibility entrypoint only re-exports those
+modules, and its CSS compatibility entrypoint only imports the owner
+stylesheets. Do not accumulate multiple visual owners in either compatibility
+file.
+
+`npm run check:css-ownership` keeps that boundary honest: application CSS may
+style only application-owned structure, never package component classes or
+Web Awesome descendants. The UX catalog's `style.css` contains document-shell
+mechanics only, recipes use component-owned styles, and `catalog.css` remains a
+minimal compatibility entrypoint.
+
 The root `@kerfjs/ui` barrel stays JavaScript-only because making a side-effectful
 CSS barrel tree-shakable is not portable across bundlers. If an application uses
 that convenience import, also import `@kerfjs/ui/styles.css`, which deliberately
@@ -478,8 +501,8 @@ Tooltip and Popover surfaces omit pointer arrows by default. Override
 `--wa-tooltip-arrow-size` and `--kui-wa-popover-arrow-size`, or a single
 popover's public `--arrow-size`, when an arrow communicates useful context.
 
-Load application CSS afterward to override semantic values globally, or scope
-them to a subtree. Use Web Awesome's `.wa-light`, `.wa-dark`, and `.wa-invert`
+Configure semantic values globally at the application root, or scope variables
+to a self-owned subtree. Use Web Awesome's `.wa-light`, `.wa-dark`, and `.wa-invert`
 classes for explicit appearance boundaries:
 
 ```css
@@ -497,10 +520,11 @@ warning, or danger. Stateful components also expose
 component variables such as `--kui-state-banner-background`. Override the
 foundation for an application theme, a tone variable for one semantic state, or
 a component variable on one instance without replacing component selectors.
-Prefer an equivalent prop or token. When composition-specific layout still
-needs a selector, the component catalog's `publicClasses` arrays define the
-exact stable anatomy: public-class-to-public-class selectors are supported;
-descendant tag, id, attribute-only, and unlisted-class selectors are not.
+Prefer an equivalent prop or token. The component catalog's `publicClasses`
+arrays support diagnostics, tooling, browser assertions, and package-owned
+composition; they are not an application styling API. Application-owned CSS may
+style new structure rendered by its own component, but it must not select a
+nested Kerf or Web Awesome component. Add missing configuration to the owner.
 
 `StateBanner` has opinionated `neutral`, `info`, `pop`, `success`, `warning`,
 and `danger` palettes. Override an individual banner with
@@ -578,6 +602,11 @@ drag, the scroll strip automatically moves toward either edge with speed based
 on pointer proximity, exposing earlier or later drop targets. Apply the reported
 change with `reorderTabs()` or application-specific state logic. The application
 still owns selection, closing, routing, and persistence.
+For a tab-local action immediately after the final tab plus a workspace action
+at the opposite edge, set `trailingPlacement="adjacent"`, pass the local action
+through `trailing`, and pass the workspace action through `end`. TabBar owns the
+flex geometry: the tab strip shrinks and scrolls while both action regions stay
+visible. Do not recreate that split with descendant CSS overrides.
 Use `AppTab.rootAttributes` for domain `data-*` metadata and `closeIcon` for a
 decorative replacement glyph. The runtime rejects roles and case variants of
 the component- or wiring-owned action, tab identity, selection, drag, drop, and
@@ -616,7 +645,8 @@ hover/focus grip. Its optional `handleIcon` replaces only the decorative glyph;
 the component and `wireResizableRegions()` retain separator semantics and
 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;
+inline/overlay/hidden responsive presentation, `responsiveFillAt` single-track
+replacement, 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,

package/ai/catalog-authoring.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./catalog-authoring.schema.json",
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@kerfjs/ui",
   "scope": "catalog-demo-authoring",
   "authoritativeGuide": "docs/catalog.md#catalog-demo-authoring-contract",
@@ -17,6 +17,17 @@
     "wireCatalogGeometryOverlay",
     "revealCatalogEntry"
   ],
+  "taxonomy": {
+    "kinds": ["component", "composition", "recipe"],
+    "organization": {
+      "grouping": "functional-category",
+      "categoryOrder": "importance-descending",
+      "withinCategoryKindOrder": ["component", "composition"],
+      "withinKindOrder": ["importance-descending", "name-ascending"],
+      "recipes": "after-all-functional-groups"
+    },
+    "compositionTag": "Composition"
+  },
   "metadata": {
     "slot": "rootAttributes",
     "demo": "data-demo",

package/ai/catalog-authoring.schema.json

@@ -11,11 +11,12 @@
     "apiSignatures",
     "imports",
     "helpers",
+    "taxonomy",
     "metadata"
   ],
   "properties": {
     "$schema": { "type": "string" },
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "package": { "const": "@kerfjs/ui" },
     "scope": { "const": "catalog-demo-authoring" },
     "authoritativeGuide": { "type": "string", "minLength": 1 },
@@ -44,6 +45,53 @@
       "minItems": 6,
       "uniqueItems": true
     },
+    "taxonomy": {
+      "type": "object",
+      "required": ["kinds", "organization", "compositionTag"],
+      "properties": {
+        "kinds": {
+          "type": "array",
+          "items": { "enum": ["component", "composition", "recipe"] },
+          "minItems": 3,
+          "maxItems": 3,
+          "uniqueItems": true
+        },
+        "organization": {
+          "type": "object",
+          "required": [
+            "grouping",
+            "categoryOrder",
+            "withinCategoryKindOrder",
+            "withinKindOrder",
+            "recipes"
+          ],
+          "properties": {
+            "grouping": { "const": "functional-category" },
+            "categoryOrder": { "const": "importance-descending" },
+            "withinCategoryKindOrder": {
+              "type": "array",
+              "items": { "enum": ["component", "composition"] },
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true
+            },
+            "withinKindOrder": {
+              "type": "array",
+              "items": {
+                "enum": ["importance-descending", "name-ascending"]
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true
+            },
+            "recipes": { "const": "after-all-functional-groups" }
+          },
+          "additionalProperties": false
+        },
+        "compositionTag": { "const": "Composition" }
+      },
+      "additionalProperties": false
+    },
     "metadata": {
       "type": "object",
       "required": ["slot", "demo", "geometryOverlaySkip"],

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

@@ -127,6 +127,20 @@
       ],
       "kind": "property-specific-css-value",
       "summary": "List flex, Skeleton dimensions, and Select icon colors use separate typed CSS grammars; row declaration-string props are absent rather than sharing a generic CSS escape hatch."
+    },
+    {
+      "id": "KUI-T014",
+      "publicImport": "@kerfjs/ui",
+      "symbols": [
+        "BadgeProps",
+        "CatalogProps",
+        "CollapsiblePanelToggleProps",
+        "SelectProps",
+        "SkeletonProps",
+        "TextProps"
+      ],
+      "kind": "explicit-native-attribute",
+      "summary": "Stable single-root visual components accept an explicit native slot attribute; multi-root components and arbitrary native attribute spreading remain excluded."
     }
   ]
 }

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

@@ -35,6 +35,7 @@
               "controlled-callback",
               "discriminated-union",
               "finite-vocabulary",
+              "explicit-native-attribute",
               "literal-identity",
               "property-specific-css-value",
               "protected-attributes",

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

@@ -166,6 +166,13 @@
         "accepts": ["toolbar-control-group"],
         "cardinality": { "min": 0, "max": 1 },
         "exclusiveWith": []
+      },
+      {
+        "id": "end",
+        "jsx": { "prop": "end" },
+        "accepts": ["toolbar-control-group"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
       }
     ],
     "state": [

package/ai/component-catalog-v2.json

@@ -7,6 +7,54 @@
     "identity": "package:id"
   },
   "entries": [
+    {
+      "key": "@kerfjs/ui:badge",
+      "package": "@kerfjs/ui",
+      "id": "badge",
+      "name": "Badge",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "metadata text", "owner": "application", "required": false },
+        {
+          "id": "semantic tone mapping",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "accessible label for abbreviated content",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["foundation"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component.",
+          "Keep meaningful text visible because tone is supplementary."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-badge",
+        "publicClasses": ["kui-badge"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:lucide-icon",
       "package": "@kerfjs/ui",
@@ -596,7 +644,6 @@
         "publicClasses": [
           "kui-split-view",
           "kui-split-view__list",
-          "kui-resizable-region",
           "kui-split-view__detail",
           "kui-split-view--compact"
         ],
@@ -1062,6 +1109,11 @@
       },
       "state": [
         { "id": "actions", "owner": "application", "required": false },
+        {
+          "id": "link destination and copy",
+          "owner": "application",
+          "required": false
+        },
         { "id": "pressed state", "owner": "application", "required": false },
         { "id": "expanded state", "owner": "application", "required": false },
         { "id": "avatar image URL", "owner": "application", "required": false }
@@ -1079,8 +1131,11 @@
       },
       "cssValueProps": [],
       "boundaries": {
-        "rootClass": "kui-toolbar-control-group",
-        "publicClasses": ["kui-toolbar-control-group"],
+        "rootClass": "kui-toolbar-action-link",
+        "publicClasses": [
+          "kui-toolbar-action-link",
+          "kui-toolbar-control-group"
+        ],
         "publicTokens": [
           "--kui-color-brand-on-quiet",
           "--kui-color-pop-border-normal",
@@ -1317,7 +1372,7 @@
       "key": "@kerfjs/ui:headers",
       "package": "@kerfjs/ui",
       "id": "headers",
-      "name": "Header composition",
+      "name": "Headers",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -1786,16 +1841,12 @@
           "kui-list-header",
           "kui-list-header__action",
           "kui-list-header__action-layer",
-          "kui-list-header__badge",
-          "kui-list-header__count",
           "kui-list-header__label",
           "kui-list-header__title",
           "kui-list-header__toggle"
         ],
         "publicTokens": [
           "--kui-color-neutral-border-quiet",
-          "--kui-color-neutral-fill-quiet",
-          "--kui-color-neutral-on-quiet",
           "--kui-focus-ring",
           "--kui-font-xs",
           "--kui-list-header-action-icon-size",
@@ -1803,15 +1854,8 @@
           "--kui-layout-inline-margin",
           "--kui-layout-item-gap",
           "--kui-layout-item-padding",
-          "--kui-layout-pill-radius",
-          "--kui-list-header-count-font-size",
           "--kui-list-header-hover-background",
-          "--kui-list-group-divider-color",
-          "--kui-color-brand-on-normal",
-          "--kui-color-pop-fill-normal",
-          "--kui-color-pop-on-normal",
-          "--kui-color-danger-fill-normal",
-          "--kui-color-danger-on-normal"
+          "--kui-list-group-divider-color"
         ]
       },
       "diagnostics": [
@@ -2087,7 +2131,7 @@
       "key": "@kerfjs/ui:application-tabs",
       "package": "@kerfjs/ui",
       "id": "application-tabs",
-      "name": "Application tabs composition",
+      "name": "Application tabs",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -2258,6 +2302,13 @@
           "accepts": ["toolbar-control-group"],
           "cardinality": { "min": 0, "max": 1 },
           "exclusiveWith": []
+        },
+        {
+          "id": "end",
+          "jsx": { "prop": "end" },
+          "accepts": ["toolbar-control-group"],
+          "cardinality": { "min": 0, "max": 1 },
+          "exclusiveWith": []
         }
       ],
       "children": {
@@ -2279,7 +2330,14 @@
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
         "roles": ["navigation"],
-        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+        "geometry": {
+          "margin": "none",
+          "border": "self",
+          "padding": "self",
+          "notes": [
+            "TabBar owns inline flex allocation: tabs shrink and scroll, an adjacent trailing action follows the tab strip, and the end action stays pinned at the far edge; leading, trailing, and end actions do not shrink."
+          ]
+        }
       },
       "accessibility": {
         "obligations": [
@@ -2294,7 +2352,8 @@
           "kui-tab-bar",
           "kui-tab-bar__leading",
           "kui-tab-bar__tabs",
-          "kui-tab-bar__trailing"
+          "kui-tab-bar__trailing",
+          "kui-tab-bar__end"
         ],
         "publicTokens": ["--kui-tab-bar-background", "--kui-tab-bar-border"]
       },
@@ -2638,7 +2697,7 @@
       "key": "@kerfjs/ui:feedback",
       "package": "@kerfjs/ui",
       "id": "feedback",
-      "name": "Feedback composition",
+      "name": "Feedback",
       "kind": "composition",
       "source": "kerf",
       "parents": { "mode": "any", "entries": [] },
@@ -2724,7 +2783,6 @@
         "publicClasses": [
           "kui-state-banner",
           "kui-state-banner__action",
-          "kui-state-banner__badge",
           "kui-state-banner__copy",
           "kui-state-banner__detail",
           "kui-state-banner__icon"
@@ -2756,8 +2814,6 @@
           "--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",