@gradial/aci 0.1.20-preview.2 → 0.1.20

package/src/cli/compile-registry.mjs

@@ -3,7 +3,8 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
-import { GradialImageSchema } from '../types/image.ts';
+import { ImageSchema } from '../types/image.ts';
+import { getBlockRefMeta } from '../types/block-ref.ts';
 
 const DATA_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
 
@@ -47,30 +48,20 @@ async function compileRegistry(options) {
   const schemaFiles = [];
   for (const [index, component] of components.entries()) {
     validateComponent(component, index, seenComponents);
-    const schema = compileSchema(component.schema, component.name);
-    const schemaFile = `schemas/${component.name}.schema.json`;
+    const componentId = component.id;
+    const schema = compileSchema(component.props, componentId);
+    const schemaFile = `schemas/${componentId}.schema.json`;
     const schemaPath = path.join(outDir, schemaFile);
     await writeFile(schemaPath, JSON.stringify(schema, null, 2) + '\n');
     schemaFiles.push(schemaPath);
-    const renderModes = component.renderModes ?? component.render;
-    const varyDimensions = component.varyDimensions ?? component.vary;
     const imageSlots = normalizeImageSlots(component.imageSlots);
+    const slots = extractBlockSlots(component.props, componentId);
     componentEntries.push({
-      name: component.name,
-      schemaFile,
-      render: {
-        static: Boolean(renderModes.canStatic ?? renderModes.static),
-        ssr: Boolean(renderModes.canSSR ?? renderModes.ssr),
-        clientIsland: Boolean(renderModes.canClientIsland ?? renderModes.clientIsland),
-      },
-      renderModes: {
-        canStatic: Boolean(renderModes.canStatic ?? renderModes.static),
-        canSSR: Boolean(renderModes.canSSR ?? renderModes.ssr),
-        canClientIsland: Boolean(renderModes.canClientIsland ?? renderModes.clientIsland),
-      },
-      ...(component.defaultIslandMode ? { defaultIslandMode: component.defaultIslandMode } : {}),
-      ...(varyDimensions?.length ? { vary: varyDimensions, varyDimensions } : {}),
+      id: componentId,
+      name: componentId,
+      props: schemaFile,
       ...(Object.keys(imageSlots).length ? { imageSlots } : {}),
+      ...(Object.keys(slots).length ? { slots } : {}),
     });
   }
 
@@ -95,16 +86,14 @@ async function compileRegistry(options) {
     });
   }
 
-  // Post-compilation: detect nested block patterns in JSON schemas and
-  // validate that referenced component names exist in the registry.
-  const knownNames = new Set(componentEntries.map((c) => c.name));
+  const knownNames = new Set(componentEntries.map((c) => c.id));
   for (const entry of componentEntries) {
-    const schemaPath = path.join(outDir, entry.schemaFile);
-    const schemaRaw = await import('node:fs/promises').then((fs) => fs.readFile(schemaPath, 'utf-8'));
-    const schema = JSON.parse(schemaRaw);
-    const nestedBlocks = collectNestedBlockRefs(schema, knownNames, entry.name);
-    if (nestedBlocks.length > 0) {
-      entry.nestedBlocks = nestedBlocks;
+    for (const [slotName, slot] of Object.entries(entry.slots ?? {})) {
+      for (const childName of slot.allowed) {
+        if (!knownNames.has(childName)) {
+          throw new Error(`${entry.id}.slots.${slotName}.allowed references unknown component "${childName}"`);
+        }
+      }
     }
   }
 
@@ -117,6 +106,10 @@ async function compileRegistry(options) {
   };
   const registryPath = path.join(outDir, 'registry.json');
   await writeFile(registryPath, JSON.stringify(registry, null, 2) + '\n');
+
+  const pageSchemaPath = await generatePageSchema(schemaDir, componentEntries, outDir);
+  schemaFiles.push(pageSchemaPath);
+
   return { registry: registryPath, schemas: schemaFiles };
 }
 
@@ -144,33 +137,82 @@ function validateDataModel(dataModel, index, seen) {
 
 function validateComponent(component, index, seen) {
   if (!component || typeof component !== 'object') throw new Error(`components[${index}] must be an object`);
-  if (!component.name) throw new Error(`components[${index}].name is required`);
-  if (seen.has(component.name)) throw new Error(`duplicate component name ${component.name}`);
-  seen.add(component.name);
-  if (!component.schema) throw new Error(`components[${index}].schema is required`);
-  validateZodSubset(component.schema, `components[${index}].schema`);
+  if (!component.id) throw new Error(`components[${index}].id is required`);
+  if (seen.has(component.id)) throw new Error(`duplicate component id ${component.id}`);
+  seen.add(component.id);
+  if (!component.props) throw new Error(`components[${index}].props is required`);
+  validateZodSubset(component.props, `components[${index}].props`);
   validateImageSlotSchemaMatch(component, index);
-  const renderModes = component.renderModes ?? component.render;
-  if (!renderModes) throw new Error(`components[${index}].renderModes is required`);
-  const enabled = Boolean(renderModes.canStatic ?? renderModes.static)
-    || Boolean(renderModes.canSSR ?? renderModes.ssr)
-    || Boolean(renderModes.canClientIsland ?? renderModes.clientIsland);
-  if (!enabled) throw new Error(`components[${index}].renderModes must enable at least one mode`);
 }
 
 function validateImageSlotSchemaMatch(component, index) {
   const imageSlots = normalizeImageSlots(component.imageSlots);
-  const imageFields = collectGradialImageFields(component.schema);
+  const imageFields = collectImageFields(component.props);
   for (const field of imageFields) {
     if (!Object.prototype.hasOwnProperty.call(imageSlots, field)) {
-      throw new Error(`components[${index}].imageSlots.${field} is required because schema field ${field} uses GradialImageSchema`);
+      throw new Error(`components[${index}].imageSlots.${field} is required because props field ${field} uses an image schema`);
     }
   }
   for (const field of Object.keys(imageSlots)) {
     if (!imageFields.has(field)) {
-      throw new Error(`components[${index}].schema.${field} must use GradialImageSchema because imageSlots.${field} is declared`);
+      throw new Error(`components[${index}].props.${field} must use an image schema because imageSlots.${field} is declared`);
+    }
+  }
+}
+
+function extractBlockSlots(schema, componentId) {
+  const shape = getSchemaShape(schema);
+  if (!shape) return {};
+  const out = {};
+  for (const [name, fieldSchema] of Object.entries(shape)) {
+    const unwrapped = unwrapOptionalSchema(fieldSchema);
+    const meta = getBlockRefMeta(unwrapped) ?? getBlockRefMeta(unwrapArraySchema(unwrapped));
+    if (meta) {
+      out[name] = {
+        allowed: [...meta.allowed],
+        multiple: meta.multiple,
+        required: false,
+      };
+    }
+  }
+  return out;
+}
+
+function unwrapOptionalSchema(schema) {
+  let current = schema;
+  const seen = new Set();
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current);
+    const def = current._def;
+    if (!def || typeof def !== 'object') break;
+    const type = def.type;
+    const typeName = def.typeName;
+    if (type === 'optional' || type === 'nullable' || type === 'default' ||
+        typeName === 'ZodOptional' || typeName === 'ZodNullable' || typeName === 'ZodDefault') {
+      const inner = def.innerType ?? def.schema;
+      if (inner) { current = inner; continue; }
     }
+    break;
   }
+  return current;
+}
+
+function getSchemaShape(schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  const def = schema._def;
+  if (!def) return null;
+  const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+  if (shape && typeof shape === 'object') return shape;
+  return null;
+}
+
+function unwrapArraySchema(schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  const def = schema._def;
+  if (!def) return null;
+  if (def.type === 'array' && def.element) return def.element;
+  if (def.typeName === 'ZodArray' && def.type) return def.type;
+  return null;
 }
 
 function normalizeImageSlots(imageSlots) {
@@ -230,34 +272,34 @@ function normalizeSlotOutput(slotKey, output, outputIndex) {
   };
 }
 
-function collectGradialImageFields(schema) {
+function collectImageFields(schema) {
   const out = new Set();
 
-  collectGradialImageFieldsFromSchema(schema, '', out);
+  collectImageFieldsFromSchema(schema, '', out);
 
   return out;
 }
 
-function collectGradialImageFieldsFromSchema(schema, prefix, out) {
+function collectImageFieldsFromSchema(schema, prefix, out) {
   if (!schema) {
     return;
   }
 
-  if (prefix && isGradialImageSchema(schema)) {
+  if (prefix && isImageSchema(schema)) {
     out.add(prefix);
     return;
   }
 
   const itemSchema = arrayItemSchema(schema);
   if (itemSchema) {
-    collectGradialImageFieldsFromSchema(itemSchema, prefix, out);
+    collectImageFieldsFromSchema(itemSchema, prefix, out);
     return;
   }
 
   const unionOptions = unionOptionSchemas(schema);
   if (unionOptions) {
     for (const option of unionOptions) {
-      collectGradialImageFieldsFromSchema(option, prefix, out);
+      collectImageFieldsFromSchema(option, prefix, out);
     }
     return;
   }
@@ -270,7 +312,7 @@ function collectGradialImageFieldsFromSchema(schema, prefix, out) {
 
   for (const [field, fieldSchema] of Object.entries(shape)) {
     const nextPrefix = prefix ? `${prefix}.${field}` : field;
-    collectGradialImageFieldsFromSchema(fieldSchema, nextPrefix, out);
+    collectImageFieldsFromSchema(fieldSchema, nextPrefix, out);
   }
 }
 
@@ -301,21 +343,27 @@ function arrayItemSchema(schema) {
   return null;
 }
 
-function isGradialImageSchema(schema) {
+function isImageSchema(schema) {
   const unwrapped = unwrapSchema(schema);
-  if (unwrapped === GradialImageSchema) return true;
+  if (unwrapped === ImageSchema) return true;
   try {
     const compiled = z.toJSONSchema(unwrapped, {
       target: 'draft-2020-12',
       unrepresentable: 'throw',
     });
-    const sources = compiled?.properties?.sources;
-    const sourcesIsArray = sources?.type === 'array'
-      || (Array.isArray(sources?.anyOf) && sources.anyOf.some((s) => s?.type === 'array'));
+    const properties = compiled?.properties ?? {};
+    const required = new Set(compiled?.required ?? []);
     return compiled?.type === 'object'
-      && compiled?.properties?.$type?.const === 'gradial.image'
-      && compiled?.properties?.fallback?.type === 'object'
-      && sourcesIsArray;
+      && properties.$type?.const === 'gradial.image'
+      && properties.assetId?.type === 'string'
+      && properties.versionId?.type === 'string'
+      && properties.alt?.type === 'string'
+      && properties.sources?.type === 'array'
+      && required.has('$type')
+      && required.has('assetId')
+      && required.has('versionId')
+      && required.has('alt')
+      && required.has('sources');
   } catch {
     return false;
   }
@@ -326,7 +374,7 @@ function unwrapSchema(schema) {
   const seen = new Set();
   while (current && !seen.has(current)) {
     seen.add(current);
-    if (current === GradialImageSchema) return current;
+    if (current === ImageSchema) return current;
     const def = current._def;
     const next = def?.innerType ?? def?.schema;
     if (!next) break;
@@ -349,7 +397,11 @@ function validateLayout(layout, index, seen) {
     seenSlots.add(slot.name);
     slots.push({ name: slot.name, required: Boolean(slot.required) });
   }
-  return { name: layout.name, slots };
+  const entry = { name: layout.name, slots };
+  if (layout.defaults && typeof layout.defaults === 'object') {
+    entry.defaults = layout.defaults;
+  }
+  return entry;
 }
 
 function compileSchema(schema, name) {
@@ -368,6 +420,131 @@ function compileSchema(schema, name) {
   };
 }
 
+async function generatePageSchema(schemaDir, componentEntries, outDir) {
+  const { readFile } = await import('node:fs/promises');
+  const defs = {
+    baseBlock: {
+      type: 'object',
+      required: ['id', 'component', 'props'],
+      additionalProperties: true,
+      properties: {
+        id: { type: 'string', minLength: 1 },
+        component: { type: 'string' },
+        props: { type: 'object' },
+        slots: {
+          type: 'object',
+          additionalProperties: {
+            type: 'array',
+            items: { $ref: '#/$defs/baseBlock' },
+          },
+        },
+      },
+    },
+    damAssetRef: {
+      type: 'object',
+      required: ['$type', 'assetId'],
+      additionalProperties: true,
+      properties: {
+        $type: { const: 'dam.assetRef' },
+        assetId: { type: 'string', minLength: 1 },
+        version: { type: 'string', minLength: 1 },
+        alt: { type: 'string' },
+      },
+    },
+  };
+  const oneOf = [];
+  for (const entry of componentEntries) {
+    const schemaPath = path.join(outDir, entry.props);
+    const raw = await readFile(schemaPath, 'utf-8');
+    const componentSchema = JSON.parse(raw);
+    const { $schema: _s, title: _t, ...propsSchema } = componentSchema;
+    replaceImagesWithDamAssetRef(propsSchema, defs.damAssetRef);
+    const defName = `${entry.name}Block`;
+    defs[defName] = {
+      allOf: [
+        { $ref: '#/$defs/baseBlock' },
+        {
+          properties: {
+            component: { const: entry.name },
+            props: propsSchema,
+          },
+        },
+      ],
+    };
+    oneOf.push({ $ref: `#/$defs/${defName}` });
+  }
+  const pageSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://baremetal.local/schemas/page.schema.json',
+    title: 'bare-metal Page',
+    type: 'object',
+    required: ['$type', 'id', 'status', 'layout', 'metadata', 'regions'],
+    additionalProperties: true,
+    properties: {
+      $type: { const: 'page' },
+      id: { type: 'string', minLength: 1 },
+      status: { type: 'string', minLength: 1 },
+      layout: { type: 'string', minLength: 1 },
+      metadata: {
+        type: 'object',
+        required: ['title'],
+        additionalProperties: true,
+        properties: {
+          title: { type: 'string', minLength: 1 },
+          description: { type: 'string' },
+          canonical: { type: 'string' },
+        },
+      },
+      regions: {
+        type: 'object',
+        additionalProperties: {
+          type: 'array',
+          items: { oneOf },
+        },
+      },
+    },
+    $defs: defs,
+  };
+  const pageSchemaPath = path.join(schemaDir, 'page.schema.json');
+  await writeFile(pageSchemaPath, JSON.stringify(pageSchema, null, 2) + '\n');
+  return pageSchemaPath;
+}
+
+function replaceImagesWithDamAssetRef(schema, damAssetRef) {
+  if (!schema || typeof schema !== 'object') return schema;
+  if (schema.$ref) return;
+  if (Array.isArray(schema.anyOf)) {
+    for (const s of schema.anyOf) replaceImagesWithDamAssetRef(s, damAssetRef);
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const s of schema.allOf) replaceImagesWithDamAssetRef(s, damAssetRef);
+  }
+  if (Array.isArray(schema.oneOf)) {
+    for (const s of schema.oneOf) replaceImagesWithDamAssetRef(s, damAssetRef);
+  }
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties)) {
+      if (isJsonImage(value)) {
+        schema.properties[key] = { $ref: '#/$defs/damAssetRef' };
+      } else {
+        replaceImagesWithDamAssetRef(value, damAssetRef);
+      }
+    }
+  }
+  if (schema.items) {
+    if (isJsonImage(schema.items)) {
+      schema.items = { $ref: '#/$defs/damAssetRef' };
+    } else {
+      replaceImagesWithDamAssetRef(schema.items, damAssetRef);
+    }
+  }
+}
+
+function isJsonImage(node) {
+  return node?.type === 'object'
+    && node?.properties?.$type?.const === 'gradial.image';
+}
+
 function validateZodSubset(schema, pathLabel, seen = new Set()) {
   if (seen.has(schema)) return;
   seen.add(schema);

package/src/cli/validate-content.mjs

@@ -53,20 +53,17 @@ async function validateContent(options) {
   const registry = JSON.parse(registryRaw);
 
   // Build schema map: component name → JSON Schema object
-  // Build nested blocks map: component name → array of { path, allow? }
   const schemaMap = new Map();
   const knownComponents = new Set();
-  const nestedBlocksMap = new Map();
+  const componentMap = new Map();
   for (const component of registry.components) {
     knownComponents.add(component.name);
-    if (component.schemaFile) {
-      const schemaPath = path.join(registryDir, component.schemaFile);
+    componentMap.set(component.name, component);
+    if (component.props) {
+      const schemaPath = path.join(registryDir, component.props);
       const schemaRaw = await readFile(schemaPath, 'utf-8');
       schemaMap.set(component.name, JSON.parse(schemaRaw));
     }
-    if (Array.isArray(component.nestedBlocks) && component.nestedBlocks.length > 0) {
-      nestedBlocksMap.set(component.name, component.nestedBlocks);
-    }
   }
 
   // Find all compiled route files
@@ -134,10 +131,7 @@ async function validateContent(options) {
         });
       }
 
-      // Recursively validate nested blocks (blockRef patterns)
-      const nestedIssues = validateNestedBlocks(
-        block.component, props, knownComponents, schemaMap, nestedBlocksMap,
-      );
+      const nestedIssues = validateNestedSlots(block, componentMap, schemaMap);
       for (const issue of nestedIssues) {
         collector.push({
           page: relativePath,
@@ -360,83 +354,52 @@ function resolveRef(ref, rootSchema) {
 // ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
-// Nested block validation — recursively validates blocks inside blockRef slots
+// Block ref validation — recursively validates nested blocks inside props.
 // ---------------------------------------------------------------------------
 
-function validateNestedBlocks(parentComponent, props, knownComponents, schemaMap, nestedBlocksMap) {
+function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props') {
   const issues = [];
-  // Find all block-shaped arrays in props by walking the data
-  const nestedBlocks = findNestedBlockArrays(props);
-  for (const { path: blockPath, blocks } of nestedBlocks) {
+  const parentComponent = componentMap.get(parentBlock.component);
+  if (!parentComponent) return issues;
+
+  const blockSlots = parentComponent.slots ?? {};
+  for (const [slotName, slot] of Object.entries(blockSlots)) {
+    const blocks = parentBlock.props?.[slotName];
+    if (!Array.isArray(blocks)) {
+      if (slot.required) {
+        issues.push({ path: `${path}.${slotName}`, message: `${parentBlock.component}: required block ref "${slotName}" has no children` });
+      }
+      continue;
+    }
+    if (!slot.multiple && blocks.length > 1) {
+      issues.push({ path: `${path}.${slotName}`, message: `${parentBlock.component}: block ref "${slotName}" allows at most one child` });
+    }
     for (const [index, nestedBlock] of blocks.entries()) {
-      if (!nestedBlock || typeof nestedBlock !== 'object') continue;
-      const childComponent = nestedBlock.component;
-      if (!childComponent || typeof childComponent !== 'string') continue;
-
-      const nestedPath = `${blockPath}[${index}]`;
-
-      // Check nested component exists in registry
-      if (!knownComponents.has(childComponent)) {
-        issues.push({
-          path: `${nestedPath}.component`,
-          message: `${parentComponent} → ${nestedPath}: unknown nested component "${childComponent}"`,
-        });
+      const nestedPath = `${path}.${slotName}[${index}]`;
+      if (!nestedBlock || typeof nestedBlock !== 'object' || typeof nestedBlock.component !== 'string') {
+        issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
         continue;
       }
 
-      // Validate nested block's props against its own schema
-      const childSchema = schemaMap.get(childComponent);
-      if (!childSchema) continue;
-
-      const childProps = nestedBlock.props ?? {};
-      const childIssues = validateJsonSchema(childProps, childSchema, `${nestedPath}.props`);
-      for (const issue of childIssues) {
-        issues.push({
-          nestedComponent: childComponent,
-          path: issue.path,
-          message: `${parentComponent} → ${childComponent}: ${issue.message}`,
-        });
+      if (!componentMap.has(nestedBlock.component)) {
+        issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
+        continue;
       }
-
-      // Recurse further if the nested component itself has nested blocks
-      const deeperIssues = validateNestedBlocks(
-        childComponent, childProps, knownComponents, schemaMap, nestedBlocksMap,
-      );
-      issues.push(...deeperIssues);
-    }
-  }
-  return issues;
-}
-
-/**
- * Walks a props object looking for arrays of block-shaped objects
- * (objects with `component` + `props` fields).
- */
-function findNestedBlockArrays(obj, prefix = 'props') {
-  const results = [];
-  if (!obj || typeof obj !== 'object') return results;
-
-  for (const [key, value] of Object.entries(obj)) {
-    const currentPath = `${prefix}.${key}`;
-    if (Array.isArray(value)) {
-      // Check if array contains block-shaped objects
-      const hasBlocks = value.some(
-        (item) => item && typeof item === 'object' && typeof item.component === 'string' && 'props' in item,
-      );
-      if (hasBlocks) {
-        results.push({ path: currentPath, blocks: value });
+      if (!slot.allowed.includes(nestedBlock.component)) {
+        issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: component "${nestedBlock.component}" is not allowed in block ref "${slotName}"` });
       }
-      // Also recurse into array items that are objects (for nested structures like tabs[].blocks[])
-      for (const item of value) {
-        if (item && typeof item === 'object' && !Array.isArray(item)) {
-          results.push(...findNestedBlockArrays(item, currentPath + '[]'));
+
+      const childSchema = schemaMap.get(nestedBlock.component);
+      const childProps = nestedBlock.props ?? {};
+      if (childSchema) {
+        for (const issue of validateJsonSchema(childProps, childSchema, `${nestedPath}.props`)) {
+          issues.push({ nestedComponent: nestedBlock.component, path: issue.path, message: `${parentBlock.component} → ${nestedBlock.component}: ${issue.message}` });
         }
       }
-    } else if (typeof value === 'object' && value !== null) {
-      results.push(...findNestedBlockArrays(value, currentPath));
+      issues.push(...validateNestedSlots(nestedBlock, componentMap, schemaMap, nestedPath));
     }
   }
-  return results;
+  return issues;
 }
 
 function collectBlocks(pageData) {