@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

package/ai/component-catalog.schema.json

@@ -39,6 +39,8 @@
         "variants": { "type": "array", "items": { "type": "string" } },
         "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" },

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}

@@ -180,7 +180,7 @@
     ],
     "wiring": {
       "required": true,
-      "helpers": ["wireTabBars"],
+      "helpers": ["wireTabBars", "wireScrollDividers"],
       "obligations": [
         "Retain and invoke the disposer.",
         "Apply onReorder to application-owned order."
@@ -435,6 +435,7 @@
     "boundaries": {
       "rootClass": null,
       "publicClasses": ["hide-actions"],
+      "placeableClasses": ["hide-actions"],
       "publicTokens": []
     }
   },

package/ai/{component-catalog-v2.d.ts → component-composition.d.ts}

@@ -39,7 +39,7 @@ export type CatalogCssValueProp = {
   unsafeHelper?: string;
   examples: string[];
 };
-export interface CatalogCompositionEntryV2 {
+export interface CatalogCompositionEntry {
   key: CatalogQualifiedKey;
   package: string;
   id: string;
@@ -95,6 +95,10 @@ export interface CatalogCompositionEntryV2 {
   boundaries: {
     rootClass: string | null;
     publicClasses: string[];
+    /** Public classes an application may place on its own elements; absent means none. */
+    placeableClasses?: string[];
+    /** The intrinsic element the component renders at its root; a placeable class on a plain element of this tag recreates the component. */
+    rootElement?: string;
     publicTokens: string[];
     publicParts?: string[];
   };
@@ -102,10 +106,10 @@ export interface CatalogCompositionEntryV2 {
   diagnostics: CatalogDiagnostic[];
   provenance: { selection: string; composition: string };
 }
-export interface ComponentCatalogV2 {
+export interface ComponentComposition {
   $schema?: string;
-  schemaVersion: 2;
+  schemaVersion: 1;
   package: string;
-  compatibility: { v1Catalog: string; identity: 'package:id' };
-  entries: CatalogCompositionEntryV2[];
+  compatibility: { componentCatalog: string; identity: 'package:id' };
+  entries: CatalogCompositionEntry[];
 }