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

package/README.md

@@ -20,7 +20,7 @@ geometry inspection, and metadata ownership. AI tools can discover that
 contract and its public imports through the shipped
 [`catalog-authoring.json`](./ai/catalog-authoring.json) artifact.
 
-For connective application patterns, use the seven [production composition
+For connective application patterns, use the ten [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
@@ -101,15 +101,26 @@ 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
+`Catalog.stageRootAttributes`, `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
 application `data-*` metadata without
 teaching the package domain fields. `ListHeader.triggerAttributes` and
 `ListActionRow.trailingActionAttributes` additionally support native popover
 target and relationship attributes. Roles and component-owned action, selection,
 disclosure, naming, disabled, icon, and catalog-structure semantics remain protected props; an
 isolated `role="menuitem"` is not an extension shortcut.
+`CatalogExample.viewport` owns the finite layout constraints needed by focused
+specimens, so catalog authors do not need route-local stylesheets, inline
+styles, or styling-only demo classes.
 The slots are also filtered at runtime, so structurally widened objects and
 JavaScript callers cannot bypass those protections with case-variant names.
 `ListItem.trailing` is dormant metadata. Use `ListActionRow` when a row needs
@@ -156,7 +167,9 @@ for asymmetric or intrinsic tracks and `ResizableRegion` for adjustable ones.
 The same property-specific boundary applies beyond spacing: use `flex()` (or a
 finite keyword) for `Row.flex`, `Grid.flex`, and `List.flex`; length builders and intrinsic-size keywords for
 `Skeleton.width`/`height`; length builders for `Skeleton.radius`; and
-`uiColor()` or `colorVar()` for `SelectChoice.color`. These grammars are not
+a foreground color for `SelectChoice.color` — `uiColor()` with a foreground
+token such as `success-on-quiet`, or `foregroundColorVar()` (fill aliases such
+as `uiColor('success')` are rejected). These grammars are not
 interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 `style` declarations; use `className`, public tokens, and component props.
 
@@ -165,9 +178,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`          |
@@ -221,7 +235,17 @@ 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.
+when it adds useful context. Set `responsive="wrap"` on a heading whose title
+must stay whole: it keeps one row while everything fits and otherwise moves the
+trailing actions below the title instead of truncating it.
+
+A toolbar never clips an action. Its trailing zone wraps whole control groups
+onto another trailing-aligned row under every `responsive` policy, and a
+`responsive="stack"` toolbar wraps its stacked center and trailing groups the
+same way. Wrapping keeps every command visible at its full 44px target without
+moving focus or DOM identity. When a product wants fewer visible commands at
+narrow widths, it chooses them: render a lower-priority command inside an
+app-owned "More" popup menu (a `single` group around a `wa-dropdown`).
 
 `DisclosureArrow` defaults to an 18px root-scaled decorative visual. Override
 `--kui-disclosure-arrow-size` at the narrowest useful scope when a consumer
@@ -258,9 +282,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 +423,21 @@ 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 ship no stylesheets (`npm run check:recipes` rejects
+route stylesheets, inline styles, and styling-only classes), 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
@@ -409,6 +449,13 @@ manual delivery. Its complete supported `--kui-*` token surface is cataloged
 under the `foundation` entry. Load application overrides after package styles,
 or scope variables directly on a component instance.
 
+Applications can separately opt into `@kerfjs/ui/document.css` for border-box
+sizing, token-backed body typography/colors, zero body margin, plain-link color,
+and a definite full-height chain. Add `class="kui-app-root"` to the one direct
+mount container when a percentage-height application shell must fill the
+viewport. This global baseline is deliberately absent from `styles.css` and
+component browser imports. See [Document baseline](./docs/document-baseline.md).
+
 ## Pane and content geometry
 
 Import `@kerfjs/ui/layout.css` and use the same structural vocabulary for a
@@ -478,8 +525,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 +544,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 +626,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 +669,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

@@ -121,12 +121,29 @@
         "CssFlex",
         "CssSize",
         "CssColor",
+        "CssForegroundColor",
+        "UiForegroundColorName",
         "flex",
         "uiColor",
-        "colorVar"
+        "colorVar",
+        "foregroundColorVar"
       ],
       "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."
+      "summary": "List flex, Skeleton dimensions, and Select icon colors use separate typed CSS grammars; Select icon colors accept only foreground colors, so fill aliases such as uiColor('success') and unqualified colorVar() values are rejected. 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.d.ts

@@ -1,4 +1,15 @@
 export type CatalogQualifiedKey = `${string}:${string}`;
+/** A `data-*` attribute a wiring helper writes at runtime. The application
+ *  must not render, remove, or treat it as its own state. */
+export interface CatalogStateAttribute {
+  name: `data-${string}`;
+  /** The element that carries it: a public class, or the element passed to the helper. */
+  on: string;
+  /** The helper, one of `wiring.helpers`, that writes it. */
+  helper: string;
+  /** What its presence or value means. */
+  meaning: string;
+}
 export type CatalogCardinality = {
   min: number;
   max: number | 'unbounded';
@@ -58,7 +69,14 @@ export interface CatalogCompositionEntryV2 {
     owner: 'application' | 'controlled' | 'component';
     required: boolean;
   }>;
-  wiring: { required: boolean; helpers: string[]; obligations: string[] };
+  wiring: {
+    required: boolean;
+    helpers: string[];
+    obligations: string[];
+    /** Wiring-owned `data-*` attributes a helper writes at runtime. Optional
+     *  for extension catalogs; first-party entries always list it. */
+    stateAttributes?: CatalogStateAttribute[];
+  };
   responsive: {
     owner: 'application' | 'component' | 'shared' | 'not-applicable';
     behaviors: string[];