@kerfjs/ui 5.0.0-beta.29 → 5.0.0-beta.30

package/README.md

@@ -83,6 +83,15 @@ mount(root, () => (
 
 Components return Kerf `SafeHtml`. They do not own application state or attach transient listeners. Actions are stable `data-action` hooks; the application wires them once with `delegate()` or `delegateActions()` and retains the disposer.
 
+Component content positions use one convention: `children` is the homogeneous
+primary region, while semantic positions and replacement content use explicit
+named `SafeHtml` props such as `header`, `footer`, `leading`, `trailing`,
+`icon`, and `action`. These named `SafeHtml` prop slots are ordinary typed
+function-component props—not native `<slot>` elements, wrapper slot
+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.
+
 `ListItem.rootAttributes`, `ListHeader.rootAttributes`,
 `ListActionRow.rootAttributes`, `AppTab.rootAttributes`,
 `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
@@ -108,6 +117,21 @@ Do not concatenate a count into `label` or pass a numeric `badge`; the mutually
 exclusive legacy `badge` slot remains available for non-count `SafeHtml` such
 as a `New` marker.
 
+`List.gap` accepts boolean default spacing, a direct spacing name such as
+`gap="xs"` or `gap="m"`, or a branded `CssLength`. Import `space`, `rem`, `em`,
+`px`, `pct`, `lengthVar`, `plus`, and `calc` from the CSS-free
+`@kerfjs/ui/css-values` subpath when a named step is not enough. `plus` returns
+an incomplete expression, so wrap it with `calc` before passing it to a prop.
+Raw CSS strings are deliberately rejected; the opaque brands catch authoring
+mistakes but are not sanitizers.
+
+The same property-specific boundary applies beyond spacing: use `flex()` (or a
+finite keyword) for `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
+interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
+`style` declarations; use `className`, public tokens, and component props.
+
 ## Component subpaths
 
 | Component                                                           | Browser import (includes reachable CSS) | Manual CSS export                      |
@@ -120,6 +144,7 @@ as a `New` marker.
 | `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`                  |
+| Typed CSS dimension builders                                        | `@kerfjs/ui/css-values`                 | —                                      |
 | `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`           |
@@ -288,9 +313,11 @@ are merged with catalog diagnostics before exception validation.
 Run `kerf-ui-analyze --root . src` (or import
 `@kerfjs/ui/analyzer`) to evaluate cross-file integration facts against the
 composition catalogs and application profile. It catches provable private
-selector reach-through, unknown tokens, competing geometry owners, and nested
-scroll owners; it reports forced dimensions, repeated insets, off-scale literal
-spacing, and dynamic classes separately as review findings. Text, versioned JSON,
+selector reach-through, unknown tokens, competing geometry owners, nested
+scroll owners, and cataloged CSS-value violations in JavaScript/TypeScript
+component calls and JSX. It reports forced dimensions, repeated insets,
+exceptional spacing shorthands, and dynamic classes separately as review
+findings. Text, versioned JSON,
 and SARIF outputs carry stable `KUI-L###` ids, repository-relative locations,
 evidence, and ownership chains. See the [analyzer guide](./docs/ui-analyzer.md).
 
@@ -407,6 +434,9 @@ Awesome modules the application renders.
 `webawesome.css` includes Web Awesome's native/base theme and then applies the
 Hot Sheet 2 palette, surfaces, status colors, focus treatment, form geometry,
 radii, tooltips, and shadows through Web Awesome's public `--wa-*` contract.
+On `wa-dialog`, the optional `hide-actions` class hides the exported
+`header-actions` shadow part for compositions that provide another dismissal
+affordance.
 Those tokens flow into all free component families. Every free Web Awesome 3.12
 component has an individual UX-catalog route under the collapsible ecosystem
 section, but the theme entry does not import or register component JavaScript,
@@ -427,8 +457,10 @@ classes for explicit appearance boundaries:
 ```
 
 `foundation.css` follows Hot Sheet 2's Web Awesome-compatible semantic palette.
-Brand, neutral, success, warning, and danger each expose fill, border, and
-foreground roles through `--kui-color-*`; stateful components also expose
+Brand, pop, neutral, success, warning, and danger each expose fill, border, and
+foreground roles through `--kui-color-*`. Pop is attractive, non-status emphasis
+for featured, novel, or celebratory content; it never substitutes for success,
+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.
@@ -437,8 +469,8 @@ 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.
 
-`StateBanner` has opinionated `neutral`, `info`, `success`, `warning`, and
-`danger` palettes. Override an individual banner with
+`StateBanner` has opinionated `neutral`, `info`, `pop`, `success`, `warning`,
+and `danger` palettes. Override an individual banner with
 `--kui-state-banner-background`, `--kui-state-banner-border`,
 `--kui-state-banner-foreground`, `--kui-state-banner-detail`,
 `--kui-state-banner-action-background`, and
@@ -537,7 +569,10 @@ 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
-`data-key` or `data-morph-skip` workarounds around choice icons.
+`data-key` or `data-morph-skip` workarounds around choice icons. Icon-bearing
+options retain the standard icon-to-label gap. When a compact Select is wrapped
+in a `ToolbarControlGroup`, use `focusRingOwner="group"`; the group paints the
+focus ring with its configured pill or rounded geometry.
 
 For application choices and panes, prefer Kerf's purpose-built primitives:
 `Select` over direct Web Awesome selection/dropdown composition,

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

@@ -41,6 +41,11 @@
     "KUI-L010",
     "KUI-L011",
     "KUI-L012",
+    "KUI-L013",
+    "KUI-L014",
+    "KUI-L015",
+    "KUI-L016",
+    "KUI-L017",
     "KUI-L090",
     "KUI-L101",
     "KUI-L102",

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

@@ -89,6 +89,43 @@
       ],
       "kind": "finite-vocabulary",
       "summary": "Finite public variant vocabularies, including canonical divider-edge combinations, are named exported unions rather than anonymous string sets."
+    },
+    {
+      "id": "KUI-T011",
+      "publicImport": "@kerfjs/ui",
+      "symbols": ["KerfUiContent"],
+      "kind": "recursive-semantic-content",
+      "summary": "Semantic UI content zones accept SafeHtml, runtime-empty boolean/nullish values, and readonly nested arrays while rejecting arbitrary strings, numbers, and signals."
+    },
+    {
+      "id": "KUI-T012",
+      "catalogKey": "@kerfjs/ui:list",
+      "publicImport": "@kerfjs/ui/css-values",
+      "symbols": [
+        "CssValue",
+        "CssLength",
+        "CssLengthExpression",
+        "UiSpaceName",
+        "space",
+        "plus",
+        "calc"
+      ],
+      "kind": "property-specific-css-value",
+      "summary": "List gap accepts finite spacing shorthands or branded complete length-percentage values, while raw CSS strings and non-standalone arithmetic expressions remain rejected."
+    },
+    {
+      "id": "KUI-T013",
+      "publicImport": "@kerfjs/ui/css-values",
+      "symbols": [
+        "CssFlex",
+        "CssSize",
+        "CssColor",
+        "flex",
+        "uiColor",
+        "colorVar"
+      ],
+      "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."
     }
   ]
 }

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

@@ -36,7 +36,9 @@
               "discriminated-union",
               "finite-vocabulary",
               "literal-identity",
-              "protected-attributes"
+              "property-specific-css-value",
+              "protected-attributes",
+              "recursive-semantic-content"
             ]
           },
           "summary": { "type": "string", "minLength": 1 }

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

@@ -10,18 +10,21 @@
     "zones": [
       {
         "id": "leading",
+        "jsx": { "prop": "leading" },
         "accepts": ["toolbar-text", "toolbar-control-group"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
       },
       {
         "id": "center",
+        "jsx": { "prop": "center" },
         "accepts": ["toolbar-text", "toolbar-control-group"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
       },
       {
         "id": "trailing",
+        "jsx": { "prop": "trailing" },
         "accepts": ["toolbar-text", "toolbar-control-group"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
@@ -41,6 +44,39 @@
       }
     ]
   },
+  "@kerfjs/ui:pane": {
+    "_source": "docs/layout.md#anatomy",
+    "contexts": [
+      "application-column",
+      "sidebar",
+      "main-content",
+      "inspector",
+      "dialog-column"
+    ],
+    "zones": [
+      {
+        "id": "header",
+        "jsx": { "prop": "header" },
+        "accepts": ["fixed-chrome"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "content",
+        "jsx": { "prop": "children" },
+        "accepts": ["pane-content"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "footer",
+        "jsx": { "prop": "footer" },
+        "accepts": ["fixed-chrome"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ]
+  },
   "@kerfjs/ui:toolbar-control-group": {
     "_source": "docs/component-selection.md#toolbar-composition",
     "parents": {
@@ -102,9 +138,24 @@
     "zones": [
       {
         "id": "tabs",
-        "accepts": ["app-tab"],
+        "jsx": { "prop": "children" },
+        "accepts": ["tabs"],
         "cardinality": { "min": 1, "max": "unbounded" },
         "exclusiveWith": []
+      },
+      {
+        "id": "leading",
+        "jsx": { "prop": "leading" },
+        "accepts": ["toolbar-control-group"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["toolbar-control-group"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
       }
     ],
     "state": [
@@ -133,6 +184,37 @@
       }
     ]
   },
+  "@kerfjs/ui:tabs": {
+    "_source": "docs/accessibility.md#tabs",
+    "parents": {
+      "mode": "listed",
+      "entries": ["@kerfjs/ui:tab-bar"]
+    },
+    "contexts": ["tabpanel-navigation"],
+    "zones": [
+      {
+        "id": "leading-decoration",
+        "jsx": { "prop": "leading" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing-decoration",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "close-icon",
+        "jsx": { "prop": "closeIcon" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
   "@kerfjs/ui:segmented-control": {
     "_source": "docs/accessibility.md#segmentedcontrol",
     "contexts": ["compact-exclusive-choice"],
@@ -147,6 +229,22 @@
   "@kerfjs/ui:token-search-field": {
     "_source": "docs/accessibility.md#tokensearchfield",
     "contexts": ["structured-search-editor"],
+    "zones": [
+      {
+        "id": "leading-decoration",
+        "jsx": { "prop": "leading" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing-control",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["control"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ],
     "state": [
       { "id": "tokens", "owner": "controlled", "required": true },
       { "id": "text", "owner": "component", "required": true },
@@ -169,6 +267,97 @@
       }
     ]
   },
+  "@kerfjs/ui:state-banner": {
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["persistent-status", "recoverable-error"],
+    "zones": [
+      {
+        "id": "icon",
+        "jsx": { "prop": "icon" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "action",
+        "jsx": { "prop": "action" },
+        "accepts": ["control"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:empty-state": {
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["empty-content", "busy-content"],
+    "zones": [
+      {
+        "id": "icon",
+        "jsx": { "prop": "icon" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "action",
+        "jsx": { "prop": "action" },
+        "accepts": ["control"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:split-view": {
+    "_source": "docs/split-view.md#split-view-list-detail",
+    "contexts": ["list-detail", "responsive-master-detail"],
+    "zones": [
+      {
+        "id": "list",
+        "jsx": { "prop": "list" },
+        "accepts": ["list-region"],
+        "cardinality": { "min": 1, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "detail",
+        "jsx": { "prop": "detail" },
+        "accepts": ["detail-region"],
+        "cardinality": { "min": 1, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:workbench": {
+    "_source": "docs/workbench.md#workbench",
+    "contexts": ["desktop-application-shell"],
+    "zones": [
+      {
+        "id": "main",
+        "jsx": { "prop": "main" },
+        "accepts": ["workspace-region"],
+        "cardinality": { "min": 1, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "left-rail",
+        "accepts": ["panel-region"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "right-rail",
+        "accepts": ["panel-region"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "bottom-drawer",
+        "accepts": ["panel-region"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
   "@kerfjs/ui:resize": {
     "_source": "docs/accessibility.md#resizableregion",
     "contexts": ["adjustable-pane-boundary"],
@@ -224,6 +413,14 @@
       }
     ]
   },
+  "@kerfjs/ui:wa-dialog": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "boundaries": {
+      "rootClass": null,
+      "publicClasses": ["hide-actions"],
+      "publicTokens": []
+    }
+  },
   "@kerfjs/ui:wa-radio-group": {
     "_source": "docs/webawesome-theme.md#coverage",
     "children": {

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

@@ -9,6 +9,25 @@ export type CatalogDiagnostic = {
   when: string;
   message: string;
 };
+export type CatalogCssValueProp = {
+  path: string;
+  grammar:
+    | 'length'
+    | 'size'
+    | 'flex'
+    | 'color'
+    | 'declarations'
+    | 'media-query'
+    | 'pixels';
+  helpers: string[];
+  nonStandaloneHelpers?: string[];
+  shorthands: string[];
+  canonicalShorthands: string[];
+  exceptionalShorthands: string[];
+  rawPolicy: 'forbid' | 'allow' | 'unsafe-only';
+  unsafeHelper?: string;
+  examples: string[];
+};
 export interface CatalogCompositionEntryV2 {
   key: CatalogQualifiedKey;
   package: string;
@@ -23,6 +42,8 @@ export interface CatalogCompositionEntryV2 {
   contexts: string[];
   zones: Array<{
     id: string;
+    /** Static JSX binding when this zone is supplied by a public prop. */
+    jsx?: { prop: string };
     accepts: string[];
     cardinality: CatalogCardinality;
     exclusiveWith: string[];
@@ -56,6 +77,7 @@ export interface CatalogCompositionEntryV2 {
     publicTokens: string[];
     publicParts?: string[];
   };
+  cssValueProps?: CatalogCssValueProp[];
   diagnostics: CatalogDiagnostic[];
   provenance: { selection: string; composition: string };
 }