@kerfjs/ui 5.0.0-beta.50 → 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
@@ -111,13 +111,16 @@ 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
@@ -164,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.
 
@@ -230,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
@@ -418,7 +433,9 @@ 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
+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
@@ -432,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

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

@@ -121,12 +121,15 @@
         "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",

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[];