@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/ai/component-catalog.schema.json

@@ -29,6 +29,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,14 +42,65 @@
         "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 for a component whose placeableClasses it renders itself: a placeable class on a plain element of this tag is the component recreated, so render the component instead; another carrier element may keep the class.", "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
         "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"],
+      "properties": {
+        "margin": { "$ref": "#/$defs/geometryOwner" },
+        "border": { "$ref": "#/$defs/geometryOwner" },
+        "padding": { "$ref": "#/$defs/geometryOwner" },
+        "notes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+      },
+      "additionalProperties": false
+    },
+    "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"],
@@ -54,13 +110,34 @@
     "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": {
       "type": "object",
       "required": ["sideEffects"],
       "properties": {
+        "moduleImport": { "type": "string" },
         "browserImport": { "type": "string" },
         "manualCssImport": { "type": "string" },
         "registrationImport": { "type": "string" },

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."
+}