create-kerf-component 5.0.0-beta.51 → 5.0.0-beta.53

package/README.md

@@ -54,6 +54,11 @@ A ready-to-publish component package that encodes the rules from the kerf docs
   not render, remove, or treat those attributes as their own state. The field
   is optional; names must be unique per component, and the checker rejects a
   helper that is not listed in `wiring.helpers`.
+  A wrapper that renders a cataloged component declares it under
+  `composition.rendersAs` (for example
+  `["@kerfjs/ui:toolbar-control-group"]`), so the `ui-composition` lint treats
+  it as that root. Every key must resolve to an entry generated in the same run
+  or to an installed package's catalog.
 
 ## Layout produced
 

package/catalog.js

@@ -186,8 +186,21 @@ function valueAt(value, path) {
   return path.split('.').reduce((current, part) => current?.[part], value);
 }
 
+// Paths where an explicit `null` is itself the author's decision: a component
+// whose root element belongs to another catalog (a `rendersAs` wrapper) or that
+// exposes no public root class.
+const NULLABLE_DECISIONS = new Set(['boundaries.rootClass']);
+
 function requireDecision(component, path, at, diagnostics) {
   const value = valueAt(component, path);
+  const explicitNull =
+    value === null &&
+    NULLABLE_DECISIONS.has(path) &&
+    Object.hasOwn(
+      valueAt(component, path.slice(0, path.lastIndexOf('.'))) ?? {},
+      path.slice(path.lastIndexOf('.') + 1),
+    );
+  if (explicitNull) return;
   if (value === undefined || value === null || value === '') {
     diagnostics.push(
       `${at}.${path}: author decision required; the generator does not infer semantics or geometry from rendered appearance`,
@@ -621,6 +634,9 @@ function toEntry(packageName, component) {
     publicExports: component.publicExports,
     sourceLinks: component.sourceLinks,
     source: component.source,
+    ...(component.composition.rendersAs
+      ? { rendersAs: component.composition.rendersAs }
+      : {}),
     parents: component.composition.parents,
     contexts: component.composition.contexts,
     zones: component.composition.zones,
@@ -636,6 +652,75 @@ function toEntry(packageName, component) {
   };
 }
 
+// The catalog keys a package's `rendersAs` may name: entries generated in this
+// run, or those of an installed dependency's shipped catalog (its
+// package.json#kerfComponentCatalog.output, or @kerfjs/ui's ai/ catalog).
+function dependencyCatalogKeys(packageRoot, packageName, cache) {
+  const cacheKey = `${packageRoot}\0${packageName}`;
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
+  let keys;
+  for (let dir = packageRoot; ; dir = dirname(dir)) {
+    const manifestPath = join(dir, 'node_modules', packageName, 'package.json');
+    if (existsSync(manifestPath)) {
+      const dependencyRoot = dirname(manifestPath);
+      let catalogPath;
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (manifest[CONFIG_KEY]?.output)
+          catalogPath = resolve(dependencyRoot, manifest[CONFIG_KEY].output);
+      } catch {
+        // An unreadable manifest leaves the package unresolved below.
+      }
+      catalogPath ??= join(dependencyRoot, 'ai', 'component-catalog-v2.json');
+      try {
+        const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
+        keys = new Set(
+          (catalog.entries ?? []).map(
+            (entry) => entry.key ?? `${catalog.package}:${entry.id}`,
+          ),
+        );
+      } catch {
+        // No readable catalog: the package stays unresolved.
+      }
+      break;
+    }
+    if (dirname(dir) === dir) break;
+  }
+  cache.set(cacheKey, keys);
+  return keys;
+}
+
+function validateRendersAs(results, diagnostics) {
+  const generated = new Map(
+    results.map(({ catalog }) => [
+      catalog.package,
+      new Set(catalog.entries.map((entry) => entry.key)),
+    ]),
+  );
+  const cache = new Map();
+  for (const { packageRoot, metadataPath, catalog } of results)
+    for (const entry of catalog.entries)
+      for (const root of entry.rendersAs ?? []) {
+        const at = `${metadataPath}: components.${entry.id}.composition.rendersAs`;
+        const rootPackage = root.slice(0, root.lastIndexOf(':'));
+        if (root === entry.key) {
+          diagnostics.push(`${at}: ${root} names the component itself`);
+          continue;
+        }
+        const keys =
+          generated.get(rootPackage) ??
+          dependencyCatalogKeys(packageRoot, rootPackage, cache);
+        if (!keys)
+          diagnostics.push(
+            `${at}: cannot resolve a component catalog for package ${rootPackage}; install it or generate its catalog`,
+          );
+        else if (!keys.has(root))
+          diagnostics.push(
+            `${at}: ${root} is not an entry in ${rootPackage}'s catalog`,
+          );
+      }
+}
+
 export function generateCatalogs(root = process.cwd()) {
   const diagnostics = [];
   const packages = configuredPackages(resolve(root), diagnostics);
@@ -707,10 +792,12 @@ export function generateCatalogs(root = process.cwd()) {
     );
     results.push({
       packageRoot,
+      metadataPath,
       outputPath: resolve(packageRoot, config.output),
       catalog,
     });
   }
+  validateRendersAs(results, diagnostics);
   if (diagnostics.length) throw new CatalogError(diagnostics.sort());
   return results;
 }

package/component-catalog-v2.schema.json

@@ -151,6 +151,13 @@
         },
         "sourceLinks": { "$ref": "#/$defs/stringList" },
         "source": { "type": "string", "minLength": 1 },
+        "rendersAs": {
+          "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys), any one of them or nothing. Composition checks treat an element of this entry as each declared root: a zone accepts it only if it accepts every root, and each root's parent contract applies to where it is placed.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
+          "uniqueItems": true
+        },
         "parents": {
           "type": "object",
           "required": ["mode", "entries"],

package/component-metadata.schema.json

@@ -159,6 +159,13 @@
         "layout"
       ],
       "properties": {
+        "rendersAs": {
+          "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys such as @kerfjs/ui:toolbar-control-group), any one of them or nothing. UI composition checks treat the wrapper as each declared root.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
+          "uniqueItems": true
+        },
         "parents": {
           "type": "object",
           "required": ["mode", "entries"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kerf-component",
-  "version": "5.0.0-beta.51",
+  "version": "5.0.0-beta.53",
   "description": "Scaffold a publishable kerf component package that already follows kerf's hard packaging rules.",
   "type": "module",
   "license": "MIT",

package/template/package.json

@@ -36,7 +36,7 @@
     "kerfjs": "^5.0.0-0"
   },
   "devDependencies": {
-    "kerfjs": "^5.0.0-beta.51",
+    "kerfjs": "^5.0.0-beta.53",
     "tsup": "^8",
     "typescript": "^5 || ^6"
   }