@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/ai/component-catalog.schema.json

@@ -9,6 +9,20 @@
     "schemaVersion": { "const": 1 },
     "package": { "const": "@kerfjs/ui" },
     "description": { "type": "string", "minLength": 1 },
+    "wiringProviders": {
+      "description": "Public helpers whose call installs other cataloged wiring helpers.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["export", "import", "provides"],
+        "properties": {
+          "export": { "type": "string", "minLength": 1 },
+          "import": { "type": "string", "minLength": 1 },
+          "provides": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true }
+        },
+        "additionalProperties": false
+      }
+    },
     "entries": {
       "type": "array",
       "items": { "$ref": "#/$defs/entry" }
@@ -29,6 +43,11 @@
         "purpose": { "type": "string", "minLength": 1 },
         "customElement": { "type": "string" },
         "publicExports": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "publicExportImports": {
+          "description": "Subpath overrides for public exports that do not live in the component delivery import.",
+          "type": "object",
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        },
         "useWhen": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
         "avoidWhen": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
         "recommendation": { "enum": ["supported", "conditional", "exceptional", "underlying", "avoid"] },
@@ -37,15 +56,31 @@
         "wiring": { "type": "array", "items": { "$ref": "#/$defs/wiring" } },
         "appOwns": { "type": "array", "items": { "type": "string" } },
         "variants": { "type": "array", "items": { "type": "string" } },
+        "usageExamples": { "type": "array", "items": { "$ref": "#/$defs/usageExample" } },
         "accessibility": { "type": "array", "items": { "type": "string" } },
         "publicClasses": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "placeableClasses": { "description": "Public classes an application may place on its own elements (layout utilities, a document root, or item geometry on a non-div carrier). Every other public class is component anatomy: render the component instead.", "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "rootElement": { "description": "The intrinsic element the component renders at its root. Required when a component renders placeableClasses; also enables classless child-root ownership checks.", "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+        "descendantRootAttribute": { "description": "A root data attribute that anchors ownership checks for arbitrary unclassed descendant tags; requires rootElement.", "type": "string", "pattern": "^data-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+        "descendantElements": { "description": "Intrinsic element tags the component can render below its root, for composed-child selector ownership checks.", "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "uniqueItems": true },
         "publicTokens": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "cssValueProps": { "type": "array", "items": { "$ref": "#/$defs/cssValueProp" }, "uniqueItems": true },
         "geometry": { "$ref": "#/$defs/geometry" },
         "delivery": { "$ref": "#/$defs/delivery" },
         "links": { "$ref": "#/$defs/links" }
       },
       "additionalProperties": false
     },
+    "usageExample": {
+      "type": "object",
+      "required": ["title", "code"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "code": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
     "geometry": {
       "type": "object",
       "required": ["margin", "border", "padding"],
@@ -60,6 +95,28 @@
     "geometryOwner": {
       "enum": ["self", "parent", "child", "none", "conditional"]
     },
+    "cssValueProp": {
+      "type": "object",
+      "required": ["path", "grammar", "helpers", "shorthands", "canonicalShorthands", "exceptionalShorthands", "rawPolicy", "examples"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^(?:[A-Za-z][A-Za-z0-9]*(?:\\[\\])?\\.)*[A-Za-z][A-Za-z0-9]*$" },
+        "grammar": { "enum": ["length", "size", "flex", "color", "declarations", "media-query", "pixels"] },
+        "helpers": { "$ref": "#/$defs/stringList" },
+        "nonStandaloneHelpers": { "$ref": "#/$defs/stringList" },
+        "shorthands": { "$ref": "#/$defs/stringList" },
+        "canonicalShorthands": { "$ref": "#/$defs/stringList" },
+        "exceptionalShorthands": { "$ref": "#/$defs/stringList" },
+        "rawPolicy": { "enum": ["forbid", "allow", "unsafe-only"] },
+        "unsafeHelper": { "type": "string", "minLength": 1 },
+        "examples": { "$ref": "#/$defs/stringList" }
+      },
+      "additionalProperties": false
+    },
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
     "alternative": {
       "type": "object",
       "required": ["id", "relationship"],
@@ -69,7 +126,27 @@
     "wiring": {
       "type": "object",
       "required": ["export", "import", "required"],
-      "properties": { "export": { "type": "string" }, "import": { "type": "string" }, "required": { "type": "boolean" }, "reason": { "type": "string" } },
+      "properties": {
+        "export": { "type": "string" },
+        "import": { "type": "string" },
+        "required": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "stateAttributes": {
+          "description": "Wiring-owned state attributes: data-* attributes this helper writes at runtime on the entry's elements. The application must not render, remove, or treat them as its own state.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/stateAttribute" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "stateAttribute": {
+      "type": "object",
+      "required": ["name", "on", "meaning"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "pattern": "^data-[a-z0-9]+(-[a-z0-9]+)*$" },
+        "on": { "type": "string", "minLength": 1, "description": "The element that carries it: a public class, or the element passed to the helper." },
+        "meaning": { "type": "string", "minLength": 1, "description": "What its presence or value means." }
+      },
       "additionalProperties": false
     },
     "delivery": {

package/ai/component-class-owners.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+// The one rule for which component export renders a cataloged public class —
+// the KUI-L103 "render X instead" answer. `eslint-plugin-kerfjs`'s
+// `ui-public-boundaries` rule loads this file from the installed
+// `@kerfjs/ui/ai/` directory (beside `application-ui-profile-sync.cjs`), and
+// `@kerfjs/ui`'s generated `ai/components/*.md` pages import it, so the lint
+// message and the component reference cannot name different components. It
+// applies to any composition catalog, `@kerfjs/ui`'s or a declared component
+// package's (`acme-meter`), so it assumes no class prefix. CommonJS so the
+// ESLint rule can load it synchronously.
+
+// The component render exports among an entry's public exports: PascalCase
+// names (JSX treats a lowercase tag as an intrinsic element) other than prop
+// types, deduplicated in catalog order. Helpers such as `uiColor` or `px` are
+// never a class's renderer.
+function componentExportNames(exports) {
+  return [
+    ...new Set(
+      (exports ?? []).filter(
+        (name) =>
+          typeof name === 'string' &&
+          /^[A-Z]/.test(name) &&
+          !name.endsWith('Props'),
+      ),
+    ),
+  ];
+}
+
+// The export that renders `className`: the export named after the class's
+// block, tried from the whole block down to its last word
+// (`kui-toolbar-action-link` is ToolbarActionLink, `kui-pane__content` is
+// Pane, `acme-meter__bar` is Meter), else the entry's own export, else every
+// component export the entry lists.
+function classRenderers(className, entryName, exports) {
+  const components = componentExportNames(exports);
+  const words = className.replace(/(?:__|--).*$/, '').split('-');
+  for (let start = 0; start < words.length; start += 1) {
+    const candidate = words
+      .slice(start)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join('');
+    if (components.includes(candidate)) return [candidate];
+  }
+  if (components.includes(entryName)) return [entryName];
+  return components;
+}
+
+// The public classes of one catalog entry that are its component's rendered
+// anatomy, each with the exports that render it. A class the entry lists in
+// `placeableClasses` is the application's to place and is absent — unless the
+// entry names the `rootElement` its component renders around those classes:
+// then the class is listed with that `element`, because a plain
+// `<div class="kui-content-item">` is exactly what ContentItem renders while
+// a `<ul>` carrying the geometry stays the application's. An entry with no
+// component export owns no classes.
+function componentClassOwnership({
+  name,
+  exports,
+  publicClasses,
+  placeableClasses,
+  rootElement,
+}) {
+  const components = componentExportNames(exports);
+  if (components.length === 0) return [];
+  const placeable = new Set(placeableClasses ?? []);
+  const owned = [];
+  for (const className of publicClasses ?? []) {
+    if (placeable.has(className) && !rootElement) continue;
+    owned.push({
+      className,
+      render: classRenderers(className, name, components),
+      ...(placeable.has(className) ? { element: rootElement } : {}),
+    });
+  }
+  return owned;
+}
+
+module.exports = {
+  classRenderers,
+  componentClassOwnership,
+  componentExportNames,
+};

package/ai/component-composition-extension.d.ts

@@ -0,0 +1,7 @@
+import type {
+  CatalogCompositionEntry,
+  ComponentComposition,
+} from './component-composition.js';
+
+export type ConsumerCompositionEntry = CatalogCompositionEntry;
+export type ConsumerComponentComposition = ComponentComposition;

package/ai/component-composition-extension.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition-extension.schema.json",
+  "title": "Kerf UI consumer composition catalog extension",
+  "allOf": [{ "$ref": "./component-composition.schema.json" }],
+  "description": "Consumer composition catalogs use the composition entry contract with their own non-empty package identity; keys are always package:id."
+}

package/ai/{component-catalog-v2-overrides.json → component-composition-rules.json}

@@ -1,46 +1,91 @@
 {
   "@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",
-        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "jsx": { "prop": "leading" },
+        "accepts": ["KerfUiContent"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
       },
       {
         "id": "center",
-        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "jsx": { "prop": "center" },
+        "accepts": ["KerfUiContent"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
       },
       {
         "id": "trailing",
-        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "jsx": { "prop": "trailing" },
+        "accepts": ["KerfUiContent"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
       }
     ],
     "children": {
-      "mode": "listed",
-      "concepts": ["toolbar-text", "toolbar-control-group"],
+      "mode": "any",
+      "concepts": [],
       "requiredConcepts": []
-    },
-    "diagnostics": [
+    }
+  },
+  "@kerfjs/ui:pane": {
+    "_source": "docs/layout.md#anatomy",
+    "contexts": [
+      "application-column",
+      "sidebar",
+      "main-content",
+      "inspector",
+      "dialog-column"
+    ],
+    "zones": [
       {
-        "id": "KUI-C101",
-        "severity": "error",
-        "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup",
-        "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup are direct zone children."
+        "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",
+    "jsxExports": {
+      "ToolbarActionLink": {
+        "parents": {
+          "mode": "listed",
+          "entries": ["@kerfjs/ui:toolbar-control-group"]
+        }
+      }
+    },
     "parents": {
       "mode": "listed",
-      "entries": ["@kerfjs/ui:toolbar", "@kerfjs/ui:panel-header"]
+      "entries": [
+        "@kerfjs/ui:toolbar",
+        "@kerfjs/ui:floating-toolbar",
+        "@kerfjs/ui:tab-bar"
+      ]
     },
     "contexts": ["toolbar-zone"],
     "zones": [
@@ -57,40 +102,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:row": {
+    "_source": "docs/layout.md#row-and-list-alignment",
+    "contexts": ["application-ui", "horizontal-layout"],
+    "children": {
+      "mode": "any",
+      "concepts": [],
+      "requiredConcepts": []
+    },
+    "zones": []
   },
   "@kerfjs/ui:list": {
     "_source": "docs/component-selection.md#problem-to-component-matrix",
@@ -132,9 +152,31 @@
     "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", "wa-button"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "end",
+        "jsx": { "prop": "end" },
+        "accepts": ["toolbar-control-group", "wa-button"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
       }
     ],
     "state": [
@@ -142,7 +184,7 @@
     ],
     "wiring": {
       "required": true,
-      "helpers": ["wireTabBars"],
+      "helpers": ["wireTabBars", "wireScrollDividers"],
       "obligations": [
         "Retain and invoke the disposer.",
         "Apply onReorder to application-owned order."
@@ -163,6 +205,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"],
@@ -174,9 +247,56 @@
       ]
     }
   },
+  "@kerfjs/ui:choice-chips": {
+    "_source": "docs/accessibility.md#choicechips",
+    "contexts": ["wrapping-exclusive-choice", "wrapping-multiple-choice"],
+    "state": [{ "id": "value", "owner": "controlled", "required": false }],
+    "accessibility": {
+      "obligations": [
+        "Name the radio group (or, with multiple, the checkbox group) with label or with labelledBy pointing at a visible heading.",
+        "Every choice keeps a visible text label; a swatch or icon is decorative."
+      ]
+    }
+  },
+  "@kerfjs/ui:composer": {
+    "_source": "docs/accessibility.md#composer",
+    "contexts": ["chat-composer", "dialog-floating-footer"],
+    "zones": [
+      {
+        "id": "actions",
+        "jsx": { "prop": "actions" },
+        "accepts": ["KerfUiContent"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ],
+    "state": [{ "id": "value", "owner": "controlled", "required": false }],
+    "accessibility": {
+      "obligations": [
+        "Name the message field with label in title style; give it an id so a hint becomes its accessible description.",
+        "Give every trailing action a visible or accessible name, such as a Send button."
+      ]
+    }
+  },
   "@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 },
@@ -199,6 +319,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"],
@@ -254,6 +465,27 @@
       }
     ]
   },
+  "@kerfjs/ui:wa-dialog": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "boundaries": {
+      "rootClass": null,
+      "publicClasses": ["hide-actions"],
+      "placeableClasses": ["hide-actions"],
+      "publicTokens": []
+    }
+  },
+  "@kerfjs/ui:wa-badge": {
+    "_source": "docs/webawesome-theme.md#badge-and-tag-guidance",
+    "boundaries": {
+      "rootClass": null,
+      "publicClasses": [],
+      "publicTokens": [
+        "--kui-wa-badge-accent-foreground",
+        "--kui-wa-badge-filled-background",
+        "--kui-wa-badge-filled-foreground"
+      ]
+    }
+  },
   "@kerfjs/ui:wa-radio-group": {
     "_source": "docs/webawesome-theme.md#coverage",
     "children": {