@gradial/aci 0.1.1 → 0.1.3

package/src/cli/compile-registry.mjs

@@ -5,6 +5,16 @@ import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { GradialImageSchema } from '../types/image.ts';
 
+// Shim React global so JSX-containing component files can be loaded.
+// The compile-registry only extracts contract metadata (schemas, imageSlots)
+// and never renders components, but importing .tsx files requires the JSX
+// runtime to be resolvable. Next.js uses jsx: "preserve" which leaves React
+// references in the transpiled output.
+try {
+  const React = await import('react');
+  if (!globalThis.React) globalThis.React = React;
+} catch { /* react not available — component files without JSX will still work */ }
+
 const args = parseArgs(process.argv.slice(2));
 
 try {
@@ -62,6 +72,19 @@ async function compileRegistry(options) {
   const seenLayouts = new Set();
   const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
 
+  // 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));
+  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;
+    }
+  }
+
   const registry = {
     manifestVersion: '1',
     generatedAt: new Date().toISOString(),
@@ -192,6 +215,14 @@ function collectGradialImageFieldsFromSchema(schema, prefix, out) {
     return;
   }
 
+  const unionOptions = unionOptionSchemas(schema);
+  if (unionOptions) {
+    for (const option of unionOptions) {
+      collectGradialImageFieldsFromSchema(option, prefix, out);
+    }
+    return;
+  }
+
   const def = unwrapSchema(schema)?._def;
   const shape = typeof def?.shape === 'function' ? def.shape() : def?.shape;
   if (!shape || typeof shape !== 'object') {
@@ -204,6 +235,14 @@ function collectGradialImageFieldsFromSchema(schema, prefix, out) {
   }
 }
 
+function unionOptionSchemas(schema) {
+  const def = unwrapSchema(schema)?._def;
+  if (!def) return null;
+  if (Array.isArray(def.options)) return def.options;
+  if (def.options instanceof Map) return Array.from(def.options.values());
+  return null;
+}
+
 function arrayItemSchema(schema) {
   let current = schema;
   const seen = new Set();
@@ -231,10 +270,13 @@ function isGradialImageSchema(schema) {
       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'));
     return compiled?.type === 'object'
       && compiled?.properties?.$type?.const === 'gradial.image'
       && compiled?.properties?.fallback?.type === 'object'
-      && compiled?.properties?.sources?.type === 'array';
+      && sourcesIsArray;
   } catch {
     return false;
   }
@@ -344,6 +386,105 @@ function childSchemas(def) {
   return children;
 }
 
+// ---------------------------------------------------------------------------
+// Nested block detection — walks generated JSON schemas to find blockRef
+// patterns (objects with `component` enum + `props`) and validates that
+// referenced component names exist in the registry.
+// ---------------------------------------------------------------------------
+
+function collectNestedBlockRefs(schema, knownNames, componentName) {
+  const results = [];
+  _walkSchemaForBlockRefs(schema, schema, '', results, knownNames, componentName);
+  return results;
+}
+
+function _walkSchemaForBlockRefs(node, rootSchema, currentPath, results, knownNames, componentName) {
+  if (!node || typeof node !== 'object') return;
+
+  // Resolve $ref
+  if (node.$ref) {
+    const resolved = resolveJsonSchemaRef(node.$ref, rootSchema);
+    if (resolved) _walkSchemaForBlockRefs(resolved, rootSchema, currentPath, results, knownNames, componentName);
+    return;
+  }
+
+  // Check if this object matches the blockRef signature:
+  // { type: "object", properties: { id, component, props } }
+  if (isBlockRefSchema(node)) {
+    const allow = extractBlockRefAllow(node, rootSchema);
+    // Validate allowed names exist
+    for (const name of allow) {
+      if (!knownNames.has(name)) {
+        throw new Error(
+          `${componentName}: nested block allowlist references unknown component "${name}" at ${currentPath || '(root)'}`,
+        );
+      }
+    }
+    results.push({
+      path: currentPath || '(root)',
+      ...(allow.length > 0 ? { allow } : {}),
+    });
+    return; // Don't recurse into the block schema itself
+  }
+
+  // Recurse into object properties
+  if (node.properties) {
+    for (const [key, propSchema] of Object.entries(node.properties)) {
+      const nextPath = currentPath ? `${currentPath}.${key}` : key;
+      _walkSchemaForBlockRefs(propSchema, rootSchema, nextPath, results, knownNames, componentName);
+    }
+  }
+
+  // Recurse into array items
+  if (node.items) {
+    _walkSchemaForBlockRefs(node.items, rootSchema, `${currentPath}[]`, results, knownNames, componentName);
+  }
+
+  // Recurse into anyOf / allOf / oneOf
+  for (const keyword of ['anyOf', 'allOf', 'oneOf']) {
+    if (Array.isArray(node[keyword])) {
+      for (const sub of node[keyword]) {
+        _walkSchemaForBlockRefs(sub, rootSchema, currentPath, results, knownNames, componentName);
+      }
+    }
+  }
+}
+
+function isBlockRefSchema(node) {
+  if (node.type !== 'object' || !node.properties) return false;
+  const props = node.properties;
+  // Must have component and props fields
+  if (!props.component || !props.props) return false;
+  // component must be a string or enum
+  const comp = props.component;
+  if (comp.type !== 'string' && !Array.isArray(comp.enum)) return false;
+  // props must be an object (record)
+  if (props.props.type !== 'object') return false;
+  return true;
+}
+
+function extractBlockRefAllow(node, rootSchema) {
+  let comp = node.properties.component;
+  // Resolve $ref on the component field
+  if (comp.$ref) {
+    comp = resolveJsonSchemaRef(comp.$ref, rootSchema) ?? comp;
+  }
+  if (Array.isArray(comp.enum)) {
+    return comp.enum.filter((v) => typeof v === 'string');
+  }
+  return [];
+}
+
+function resolveJsonSchemaRef(ref, rootSchema) {
+  if (!ref || !ref.startsWith('#/')) return null;
+  const parts = ref.slice(2).split('/');
+  let current = rootSchema;
+  for (const part of parts) {
+    current = current?.[part];
+  }
+  return current ?? null;
+}
+
 function parseArgs(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i++) {

package/src/cli/validate-content.mjs

@@ -53,8 +53,10 @@ 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();
   for (const component of registry.components) {
     knownComponents.add(component.name);
     if (component.schemaFile) {
@@ -62,6 +64,9 @@ async function validateContent(options) {
       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
@@ -128,6 +133,19 @@ async function validateContent(options) {
           message: issue.message,
         });
       }
+
+      // Recursively validate nested blocks (blockRef patterns)
+      const nestedIssues = validateNestedBlocks(
+        block.component, props, knownComponents, schemaMap, nestedBlocksMap,
+      );
+      for (const issue of nestedIssues) {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          component: block.component,
+          ...issue,
+        });
+      }
     }
   }
 
@@ -341,6 +359,86 @@ function resolveRef(ref, rootSchema) {
 // Content helpers
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Nested block validation — recursively validates blocks inside blockRef slots
+// ---------------------------------------------------------------------------
+
+function validateNestedBlocks(parentComponent, props, knownComponents, schemaMap, nestedBlocksMap) {
+  const issues = [];
+  // Find all block-shaped arrays in props by walking the data
+  const nestedBlocks = findNestedBlockArrays(props);
+  for (const { path: blockPath, blocks } of nestedBlocks) {
+    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}"`,
+        });
+        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}`,
+        });
+      }
+
+      // 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 });
+      }
+      // 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 + '[]'));
+        }
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      results.push(...findNestedBlockArrays(value, currentPath));
+    }
+  }
+  return results;
+}
+
 function collectBlocks(pageData) {
   const blocks = [];
   if (pageData.regions && typeof pageData.regions === 'object') {

package/src/types/component.ts

@@ -0,0 +1,59 @@
+import type { IslandMode, VaryDimension } from './render-mode.js';
+import type { ImageSlotContract } from './image.js';
+import type { z } from 'zod';
+
+export interface ComponentRenderModes {
+  canStatic: boolean;
+  canSSR: boolean;
+  canClientIsland: boolean;
+}
+
+/**
+ * A CMS-registered component — sync or async (server components).
+ * Accepts content props derived from the Zod schema.
+ */
+type CmsComponentFn<TProps = any> =
+  | ((props: TProps) => import('react').ReactElement | null)
+  | ((props: TProps) => Promise<import('react').ReactElement | null>);
+
+/**
+ * Infers the props type from a schema.
+ * If TSchema is a Zod type, returns z.infer<TSchema>.
+ * Otherwise returns Record<string, unknown>.
+ */
+type InferContentProps<TSchema> = TSchema extends z.ZodType<infer T> ? T : Record<string, unknown>;
+
+export interface ComponentDefinition<TSchema = unknown> {
+  name: string;
+  /**
+   * The React component that renders this CMS block.
+   * Accepts at least the schema-derived props, but may accept additional
+   * composition params (className, etc.) passed by parent sections.
+   */
+  component?: CmsComponentFn<any>;
+  schema: TSchema;
+  renderModes?: ComponentRenderModes;
+  render?: ComponentRenderModes;
+  defaultIslandMode?: IslandMode;
+  varyDimensions?: VaryDimension[];
+  vary?: VaryDimension[];
+  imageSlots?: Record<string, ImageSlotContract>;
+}
+
+export interface ComponentContract<TSchema = unknown> {
+  name: string;
+  component?: CmsComponentFn<any>;
+  schema: TSchema;
+  renderModes: ComponentRenderModes;
+  render: ComponentRenderModes;
+  defaultIslandMode?: IslandMode;
+  varyDimensions?: VaryDimension[];
+  vary?: VaryDimension[];
+  imageSlots?: Record<string, ImageSlotContract>;
+}
+
+export type InferComponentProps<TContract> = TContract extends ComponentContract<infer TSchema>
+  ? InferContentProps<TSchema>
+  : Record<string, unknown>;
+
+export type { CmsComponentFn, InferContentProps };

package/src/types/config.ts

@@ -0,0 +1,36 @@
+import type { RenderCapabilities } from './renderer.js';
+
+export interface BareMetalConfig {
+  version: '1';
+  siteId: string;
+  framework: 'astro' | 'next' | 'sveltekit' | 'custom';
+  source: {
+    root: string;
+    outDir?: string;
+  };
+  componentRegistry: string;
+  layoutRegistry: string;
+  rendererEntry: string;
+  capabilities: RenderCapabilities;
+  routes: RouteConfig;
+  dam?: DAMConfig;
+  externalDependencies?: ExternalDependency[];
+  rendererProtocol: 'http' | 'stdio-json';
+}
+
+export interface RouteConfig {
+  cmsManaged: string;
+  frameworkOwned?: string[];
+}
+
+export interface ExternalDependency {
+  name: string;
+  host: string;
+  kind?: 'api' | 'client-script';
+  description?: string;
+  cacheTTL?: number;
+}
+
+export interface DAMConfig {
+  autoApproveUploads?: boolean;
+}

package/src/types/image.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+
+export interface ImageSource {
+  src: string;
+  width: number;
+  height: number;
+  type: string;
+}
+
+export interface PictureSource {
+  media?: string;
+  type: string;
+  srcset: string;
+  sizes?: string;
+}
+
+export interface GradialImage {
+  $type: 'gradial.image';
+  assetId: string;
+  versionId: string;
+  alt: string;
+  fallback: ImageSource;
+  sources: PictureSource[];
+}
+
+export interface ImageSlotContract {
+  outputs: SlotOutput[];
+  formats: string[];
+  sizes: string;
+}
+
+export interface SlotOutput {
+  aspectRatio: string;
+  widths: number[];
+  media?: string;
+}
+
+export const GradialImageSchema = z.object({
+  $type: z.literal('gradial.image'),
+  assetId: z.string().min(1),
+  versionId: z.string().min(1),
+  alt: z.string(),
+  fallback: z.object({
+    src: z.string().min(1),
+    width: z.number().int().nonnegative(),
+    height: z.number().int().nonnegative(),
+    type: z.string().min(1),
+  }),
+  sources: z.array(z.object({
+    media: z.string().optional(),
+    type: z.string().min(1),
+    srcset: z.string().min(1),
+    sizes: z.string().optional(),
+  })).nullable().default([]),
+});
+
+export type ImageHTMLAttributes = Record<string, string | number | boolean | undefined | null>;
+
+export function renderImageHTML(image: GradialImage, attrs: ImageHTMLAttributes = {}): string {
+  const imgAttrs = renderAttrs({
+    ...attrs,
+    src: image.fallback.src,
+    alt: image.alt,
+    width: image.fallback.width > 0 ? image.fallback.width : undefined,
+    height: image.fallback.height > 0 ? image.fallback.height : undefined,
+  });
+  const img = `<img${imgAttrs}>`;
+  if (!image.sources.length) {
+    return img;
+  }
+  const sources = image.sources.map((source) => `<source${renderAttrs({
+    media: source.media,
+    type: source.type,
+    srcset: source.srcset,
+    sizes: source.sizes,
+  })}>`).join('');
+  return `<picture>${sources}${img}</picture>`;
+}
+
+function renderAttrs(attrs: ImageHTMLAttributes): string {
+  const rendered = Object.entries(attrs)
+    .filter(([, value]) => value !== undefined && value !== null && value !== false)
+    .map(([name, value]) => value === true ? escapeName(name) : `${escapeName(name)}="${escapeAttr(String(value))}"`);
+  if (!rendered.length) {
+    return '';
+  }
+  return ' ' + rendered.join(' ');
+}
+
+function escapeName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_:-]/g, '');
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from './config.js';
+export * from './component.js';
+export * from './layout.js';
+export * from './page.js';
+export * from './renderer.js';
+export * from './render-mode.js';
+export * from './image.js';
+export * from './video.js';
+export * from './media.js';

package/src/types/layout.ts

@@ -0,0 +1,29 @@
+import type { FragmentRefNode } from './page.js';
+
+export interface LayoutSlot {
+  name: string;
+  required: boolean;
+}
+
+/** Default content for non-required layout slots, keyed by slot name. */
+export type LayoutDefaults = Record<string, FragmentRefNode[]>;
+
+export interface LayoutDefinition {
+  name: string;
+  slots: LayoutSlot[];
+  /** Default fragment references for slots not provided by the page. */
+  defaults?: LayoutDefaults;
+}
+
+export interface LayoutContract {
+  name: string;
+  slots: LayoutSlot[];
+  defaults?: LayoutDefaults;
+}
+
+/** A compiled layout file as stored on disk. */
+export interface CompiledLayout {
+  name: string;
+  slots: LayoutSlot[];
+  defaults: LayoutDefaults;
+}

package/src/types/media.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { GradialImageSchema, renderImageHTML, type GradialImage } from './image.js';
+import { GradialVideoSchema, type GradialVideo } from './video.js';
+
+// ---------------------------------------------------------------------------
+// GradialAsset — union of all DAM-backed asset types
+//
+// Content authors write: { "$type": "dam.assetRef", "assetId": "..." }
+// The compiler resolves this to a GradialImage or GradialVideo based on
+// the asset's media type in the DAM.
+// ---------------------------------------------------------------------------
+
+/** Discriminated union of all compiler-resolved asset types. */
+export type GradialAsset = GradialImage | GradialVideo;
+
+// ---------------------------------------------------------------------------
+// Zod schema — discriminated on $type
+// ---------------------------------------------------------------------------
+
+export const GradialAssetSchema = z.discriminatedUnion('$type', [
+  GradialImageSchema,
+  GradialVideoSchema,
+]);
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isGradialImage(value: unknown): value is GradialImage {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as Record<string, unknown>).$type === 'gradial.image'
+  );
+}
+
+export function isGradialVideo(value: unknown): value is GradialVideo {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as Record<string, unknown>).$type === 'gradial.video'
+  );
+}
+
+export function isGradialAsset(value: unknown): value is GradialAsset {
+  return isGradialImage(value) || isGradialVideo(value);
+}
+
+// ---------------------------------------------------------------------------
+// HTML string renderers (framework-agnostic)
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders a GradialVideo to an HTML string.
+ * Uses poster.fallback.src for the poster attribute.
+ * Includes <source> elements for format variants.
+ */
+export function renderVideoHTML(
+  video: GradialVideo,
+  attrs: Record<string, string | number | boolean | undefined | null> = {},
+): string {
+  const posterSrc = video.poster?.fallback.src;
+  const attrPairs: Array<[string, string | number | boolean | undefined | null]> = [
+    ...Object.entries(attrs),
+    ['src', video.sources?.length ? undefined : video.src],
+    ['poster', posterSrc],
+    ['width', video.width > 0 ? video.width : undefined],
+    ['height', video.height > 0 ? video.height : undefined],
+  ];
+  const attrString = renderAttrs(attrPairs);
+
+  const sources = (video.sources ?? [])
+    .map((s) => `<source${renderAttrs([['src', s.src], ['type', s.type]])}>`)
+    .join('');
+
+  // If no format variants, src is on the <video> element itself
+  if (!sources) {
+    return `<video${attrString}></video>`;
+  }
+  return `<video${attrString}>${sources}</video>`;
+}
+
+/**
+ * Renders any GradialAsset to an HTML string.
+ * Delegates to renderImageHTML or renderVideoHTML based on $type.
+ */
+export function renderAssetHTML(
+  asset: GradialAsset,
+  attrs: Record<string, string | number | boolean | undefined | null> = {},
+): string {
+  if (asset.$type === 'gradial.image') {
+    return renderImageHTML(asset, attrs);
+  }
+  return renderVideoHTML(asset, attrs);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function renderAttrs(
+  pairs: Array<[string, string | number | boolean | undefined | null]>,
+): string {
+  const rendered = pairs
+    .filter(([, value]) => value !== undefined && value !== null && value !== false)
+    .map(([name, value]) =>
+      value === true
+        ? escapeName(name)
+        : `${escapeName(name)}="${escapeAttr(String(value))}"`,
+    );
+  if (!rendered.length) return '';
+  return ' ' + rendered.join(' ');
+}
+
+function escapeName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_:-]/g, '');
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}