create-kerf-component 5.0.0-beta.52 → 5.0.0-beta.54

package/README.md

@@ -54,6 +54,22 @@ 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.
+  Each `publicExports` item names a `package.json#exports` subpath that maps to
+  the `src/` file exporting it. A private, bundled application
+  (`package.json#private: true`) has no per-file `dist/` entries and is never
+  imported by package name, so its items may omit `subpath`
+  (`{ "name": "DemandSegmentsControl" }`); the checker then verifies the name
+  against the component's `source` file, which is how the UI lint resolves the
+  wrapper. A subpath it does declare is still checked against `exports`.
+  `private: true` is the only opt-in: a `.kerf-ui-profile.json` `scope` does
+  not change this. An application that is published to npm (an app shell), or
+  whose manifest omits `private`, either declares a real `subpath` for each
+  item or sets `"private": true`.
 
 ## 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`,
@@ -519,6 +532,11 @@ function validateComponent(
     diagnostics.push(`${at}.source: file does not exist: ${component.source}`);
 
   const exports = packageJson.exports ?? {};
+  // A private application (package.json#private) is bundled, never imported
+  // by package name, and has no per-file dist entries. Its exports may omit
+  // `subpath`; each name is then verified against the component's own
+  // `source` file, which is how the Kerf UI rules resolve its wrappers.
+  const privateApplication = packageJson.private === true;
   if (
     !Array.isArray(component.publicExports) ||
     !component.publicExports.length
@@ -528,13 +546,34 @@ function validateComponent(
     const seen = new Set();
     for (const item of component.publicExports) {
       const exportAt = `${at}.publicExports`;
-      if (!item?.name || typeof item?.subpath !== 'string') {
-        diagnostics.push(`${exportAt}: every export requires name and subpath`);
+      const sourceOnly =
+        privateApplication &&
+        Boolean(item?.name) &&
+        !Object.hasOwn(item, 'subpath');
+      if (!item?.name || (!sourceOnly && typeof item?.subpath !== 'string')) {
+        diagnostics.push(
+          `${exportAt}: every export requires name and subpath (only a private application, package.json#private, may omit subpath)`,
+        );
         continue;
       }
-      const key = `${item.subpath}:${item.name}`;
-      if (seen.has(key)) diagnostics.push(`${exportAt}: duplicate ${key}`);
+      const key = sourceOnly
+        ? `source:${item.name}`
+        : `${item.subpath}:${item.name}`;
+      if (seen.has(key))
+        diagnostics.push(
+          `${exportAt}: duplicate ${sourceOnly ? item.name : key}`,
+        );
       seen.add(key);
+      if (sourceOnly) {
+        if (
+          existsSync(sourcePath) &&
+          !exportedNamesFromFile(sourcePath).has(item.name)
+        )
+          diagnostics.push(
+            `${exportAt}: ${item.name} is not exported by ${component.source}`,
+          );
+        continue;
+      }
       if (!(item.subpath in exports))
         diagnostics.push(
           `${exportAt}: package.json does not export subpath ${item.subpath}`,
@@ -621,6 +660,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 +678,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 +818,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

@@ -137,10 +137,11 @@
         "kind": { "enum": ["component", "composition", "recipe"] },
         "purpose": { "type": "string", "minLength": 1 },
         "publicExports": {
+          "description": "Each export's name and the package.json#exports subpath that serves it. An entry from a private application omits subpath: the application is bundled, never imported by package name, so the name resolves through the entry's source file.",
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["name", "subpath"],
+            "required": ["name"],
             "properties": {
               "name": { "type": "string", "minLength": 1 },
               "subpath": { "type": "string", "pattern": "^\\." }
@@ -151,6 +152,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

@@ -97,9 +97,10 @@
         "publicExports": {
           "type": "array",
           "minItems": 1,
+          "description": "Each export's name and package.json#exports subpath. A private application (package.json#private) may omit subpath; the name is then verified against the component's source file.",
           "items": {
             "type": "object",
-            "required": ["name", "subpath"],
+            "required": ["name"],
             "properties": {
               "name": { "type": "string", "minLength": 1 },
               "subpath": { "type": "string", "pattern": "^\\." }
@@ -159,6 +160,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.52",
+  "version": "5.0.0-beta.54",
   "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.52",
+    "kerfjs": "^5.0.0-beta.54",
     "tsup": "^8",
     "typescript": "^5 || ^6"
   }