@gradial/aci 0.1.20-preview.3 → 0.1.21

package/src/types/block-ref.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { ComponentContract } from './component.js';
+
+const BLOCK_REF_KEY = '_gradialBlockRef';
+
+export interface BlockRefMeta {
+  allowed: readonly string[];
+  multiple: boolean;
+}
+
+const blockRefBase = z.object({
+  id: z.string().min(1),
+  component: z.string().min(1),
+  props: z.record(z.string(), z.unknown()),
+});
+
+type InferContractProps<T> = T extends ComponentContract<string, infer Schema>
+  ? Schema extends z.ZodType<infer P> ? P : Record<string, unknown>
+  : Record<string, unknown>;
+
+type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
+
+export type BlockRefEntry<T extends ComponentContract> = {
+  id: string;
+  component: InferContractId<T>;
+  props: InferContractProps<T>;
+};
+
+export type BlockRefUnion<T extends readonly ComponentContract[]> = {
+  [K in keyof T]: BlockRefEntry<T[K]>;
+}[number];
+
+function attachMeta<T extends z.ZodTypeAny>(
+  schema: T,
+  allowed: readonly string[],
+  multiple: boolean,
+): T {
+  Object.defineProperty(schema, BLOCK_REF_KEY, {
+    value: { allowed, multiple } satisfies BlockRefMeta,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+  return schema;
+}
+
+export function blockRefArray<const T extends readonly ComponentContract[]>(
+  contracts: T,
+): z.ZodArray<z.ZodType<BlockRefUnion<T>>> {
+  return attachMeta(
+    z.array(blockRefBase) as unknown as z.ZodArray<z.ZodType<BlockRefUnion<T>>>,
+    contracts.map((c) => c.id),
+    true,
+  );
+}
+
+export function blockRef<const T extends readonly ComponentContract[]>(
+  contracts: T,
+): z.ZodType<BlockRefUnion<T>> {
+  return attachMeta(
+    blockRefBase as unknown as z.ZodType<BlockRefUnion<T>>,
+    contracts.map((c) => c.id),
+    false,
+  );
+}
+
+export function getBlockRefMeta(schema: unknown): BlockRefMeta | null {
+  if (schema && typeof schema === 'object' && BLOCK_REF_KEY in schema) {
+    return (schema as Record<string, unknown>)[BLOCK_REF_KEY] as BlockRefMeta;
+  }
+  return null;
+}
+
+export type BlockRef = z.infer<typeof blockRefBase>;

package/src/types/image.ts

@@ -1,28 +1,47 @@
 import { z } from 'zod';
 
+// ---------------------------------------------------------------------------
+// Image source variant (responsive derivative)
+//
+// Each entry is one concrete derivative produced by the compiler for the asset
+// slot. Renderers pick the primary variant and build a srcset from the list.
+// ---------------------------------------------------------------------------
+
 export interface ImageSource {
+  /** Derivative URL. */
   src: string;
+  /** Intrinsic width in pixels. */
   width: number;
+  /** Intrinsic height in pixels. */
   height: number;
+  /** MIME type hint, e.g. image/webp. */
   type: string;
 }
 
-export interface PictureSource {
-  media?: string;
-  type: string;
-  srcset: string;
-  sizes?: string;
-}
+// ---------------------------------------------------------------------------
+// Image — DAM-backed image asset with compiler-resolved derivatives
+//
+// Content authors write an asset reference: { "$type": "dam.assetRef", ... }
+// The compiler resolves it to this Image value based on the asset's media type.
+// ---------------------------------------------------------------------------
 
-export interface GradialImage {
+export interface Image {
+  /** Discriminator — always 'gradial.image'. */
   $type: 'gradial.image';
+  /** DAM asset identifier. */
   assetId: string;
+  /** DAM version identifier. */
   versionId: string;
+  /** Accessible description of the image content. */
   alt: string;
-  fallback: ImageSource;
-  sources: PictureSource[] | null;
+  /** Responsive derivative variants produced for the asset slot. */
+  sources: ImageSource[];
 }
 
+// ---------------------------------------------------------------------------
+// Image slot contract (declared by components that accept image props)
+// ---------------------------------------------------------------------------
+
 export interface ImageSlotContract {
   outputs: SlotOutput[];
   formats: string[];
@@ -35,66 +54,66 @@ export interface SlotOutput {
   media?: string;
 }
 
-export const GradialImageSchema = z.object({
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+
+export const ImageSourceSchema = z.object({
+  src: z.string().min(1),
+  width: z.number().int().nonnegative(),
+  height: z.number().int().nonnegative(),
+  type: z.string().min(1),
+});
+
+export const ImageSchema = 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([]),
+  sources: z.array(ImageSourceSchema).min(1),
 });
 
-export type ImageHTMLAttributes = Record<string, string | number | boolean | undefined | null>;
+// ---------------------------------------------------------------------------
+// Shared attrs helper — consumed by React, Astro, and Svelte components
+// ---------------------------------------------------------------------------
 
-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>`;
-}
+export type ImageAttrs = Record<string, unknown>;
 
-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(' ');
+/**
+ * Picks the primary variant from an image's sources.
+ * Uses the largest width; ties fall back to the first entry.
+ */
+export function primaryImageSource(image: Image): ImageSource {
+  return image.sources.reduce((largest, source) =>
+    source.width > largest.width ? source : largest,
+    image.sources[0],
+  );
 }
 
-function escapeName(name: string): string {
-  return name.replace(/[^A-Za-z0-9_:-]/g, '');
-}
+/**
+ * Computes the full set of <img> attributes for an Image.
+ *
+ * Framework components (React <Picture>, Astro <img>, Svelte <img>) call this
+ * and spread the result into their native element.  No HTML string serialization.
+ */
+export function imageAttrs(image: Image, overrides: ImageAttrs = {}): ImageAttrs {
+  const primary = primaryImageSource(image);
+  const srcset = image.sources
+    .map((s) => `${s.src} ${s.width}w`)
+    .join(', ');
+  const sizes = image.sources
+    .map((s) => `(max-width: ${s.width}px) ${s.width}px`)
+    .join(', ');
 
-function escapeAttr(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  return {
+    src: primary.src,
+    alt: image.alt,
+    width: primary.width > 0 ? primary.width : undefined,
+    height: primary.height > 0 ? primary.height : undefined,
+    srcSet: srcset || undefined,
+    sizes: sizes || undefined,
+    loading: 'lazy',
+    decoding: 'async',
+    ...overrides,
+  };
 }

package/templates/astro/template/.aci.yaml

@@ -0,0 +1,28 @@
+version: "1"
+siteId: "site_astro"
+domain: "meridian.local"
+framework: astro
+
+source:
+  root: "./"
+  outDir: "dist"
+  publicDir: "public"
+
+componentRegistry: ./src/cms/contracts/components/index.ts
+layoutRegistry: ./src/cms/contracts/layouts/index.ts
+
+capabilities:
+  staticRender: true
+  ssr: true
+  ssrIslands: true
+  clientIslands: true
+  fragmentRender: true
+
+routes:
+  cmsManaged: "/[...slug]"
+  frameworkOwned:
+    - "/api/*"
+    - "/_astro/*"
+    - "/storybook/*"
+
+rendererProtocol: stdio-json

package/templates/astro/template/.storybook/main.ts

@@ -0,0 +1,79 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import tailwindcss from '@tailwindcss/postcss';
+
+const sharedRoot = fileURLToPath(new URL('../src', import.meta.url));
+
+function withSharedAlias(alias: any) {
+  if (Array.isArray(alias)) {
+    return [...alias, { find: '@shared', replacement: sharedRoot }];
+  }
+
+  return {
+    ...alias,
+    '@shared': sharedRoot
+  };
+}
+
+const config = {
+  stories: ['../src/**/*.stories.@(ts|mdx)'],
+  addons: ['@storybook/addon-docs'],
+  framework: {
+    name: '@storybook-astro/framework',
+    options: {}
+  },
+  core: {
+    builder: '@storybook/builder-vite'
+  },
+  staticDirs: ['../public'],
+  viteFinal: async (config: any) => {
+    const astroComponentPaths = new Set<string>();
+    const buildServerPlugin = config.plugins?.flat().find(
+      (p: any) => p?.name === 'storybook-astro:build-server'
+    );
+
+    if (buildServerPlugin) {
+      const origWriteBundle = buildServerPlugin.writeBundle;
+      buildServerPlugin.writeBundle = async function(this: any, ...args: any[]) {
+        for (const componentPath of astroComponentPaths) {
+          buildServerPlugin.resolveId?.call(
+            this,
+            componentPath,
+            componentPath
+          );
+        }
+        return origWriteBundle?.apply(this, args);
+      };
+    }
+
+    config.plugins = [
+      {
+        name: 'storybook-astro:resolve-compat',
+        enforce: 'pre' as const,
+        resolveId(id: string, importer: string | undefined) {
+          if (id?.endsWith('.astro') && importer) {
+            astroComponentPaths.add(resolve(dirname(importer), id));
+          }
+          return undefined;
+        }
+      },
+      ...config.plugins
+    ];
+
+    return {
+      ...config,
+      resolve: {
+        ...config.resolve,
+        alias: withSharedAlias(config.resolve?.alias)
+      },
+      css: {
+        ...config.css,
+        postcss: {
+          plugins: [tailwindcss()]
+        }
+      }
+    };
+  }
+};
+
+export default config;

package/templates/astro/template/.storybook/manager.ts

@@ -0,0 +1,6 @@
+import { addons } from 'storybook/manager-api';
+import { themes } from 'storybook/theming';
+
+addons.setConfig({
+  theme: themes.dark
+});

package/templates/astro/template/.storybook/preview.ts

@@ -0,0 +1,33 @@
+import '../src/design-system/styles.css';
+
+const preview = {
+  globalTypes: {
+    theme: {
+      description: 'Theme for components',
+      toolbar: {
+        title: 'Theme',
+        icon: 'sun',
+        items: ['light', 'dark'],
+        dynamicTitle: true
+      }
+    }
+  },
+  decorators: [
+    (storyFn: any, context: any) => {
+      const theme = context.globals.theme || 'light';
+      document.body.setAttribute('data-visual-root', '');
+      document.body.className = `theme-${theme} min-h-screen bg-[var(--color-surface-default)]`;
+      return storyFn();
+    }
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    options: {
+      storySort: {
+        order: ['Core Atomic Blocks', 'Composition', '*']
+      }
+    }
+  }
+};
+
+export default preview;

package/templates/astro/template/astro.config.mjs

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+import tailwindcss from '@tailwindcss/postcss';
+import { withAci } from '@gradial/aci/astro';
+
+const pageRuntimeBuild = process.env.ACI_CODE_ARTIFACT_BUILD === '1';
+const rawBasePath = String(process.env.ACI_SITE_BASE_PATH || '').trim().replace(/\/+$/g, '');
+const base = rawBasePath
+  ? rawBasePath.startsWith('/') ? rawBasePath : `/${rawBasePath}`
+  : '/';
+const rawOutDir = String(process.env.ACI_ASTRO_OUT_DIR || '').trim();
+const rawCacheDir = String(process.env.ACI_ASTRO_CACHE_DIR || '').trim();
+const outDir = rawOutDir
+  ? (path.isAbsolute(rawOutDir) ? rawOutDir : `./${rawOutDir}`)
+  : 'dist';
+
+export default defineConfig({
+  adapter: pageRuntimeBuild ? node({ mode: 'middleware' }) : undefined,
+  integrations: [withAci()],
+  srcDir: './src',
+  outDir,
+  cacheDir: rawCacheDir
+    ? (path.isAbsolute(rawCacheDir) ? rawCacheDir : `./${rawCacheDir}`)
+    : undefined,
+  output: pageRuntimeBuild ? 'server' : 'static',
+  trailingSlash: 'always',
+  base,
+  devToolbar: { enabled: false },
+  vite: {
+    css: {
+      postcss: {
+        plugins: [tailwindcss()],
+      },
+    },
+  },
+});

package/templates/astro/template/package.json.tmpl

@@ -0,0 +1,41 @@
+{
+  "name": "{{siteName}}",
+  "version": "{{version}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev --host 0.0.0.0",
+    "build": "astro build",
+    "preview": "ACI_CONTENT_ROOT=./.aci/compiled astro preview --host 0.0.0.0",
+    "typecheck": "ACI_CONTENT_ROOT=./.aci/compiled astro check --tsconfig ./tsconfig.json",
+    "aci:compile": "node ./node_modules/@gradial/aci/bin/aci.js build --compile-only",
+    "content:compile": "node ./node_modules/@gradial/aci/bin/aci.js build --skip-code --content ./.content --out ./.aci/compiled",
+    "aci:build": "node ./node_modules/@gradial/aci/bin/aci.js build --content ./.content",
+    "aci:doctor": "node ./node_modules/@gradial/aci/bin/aci.js doctor",
+    "aci:validate": "node ./node_modules/@gradial/aci/bin/aci.js build --validate-only",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build"
+  },
+  "dependencies": {
+    "@gradial/aci": "^0.1.20",
+    "js-yaml": "^4.1.0",
+    "marked": "^18.0.3",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.8",
+    "@astrojs/node": "^10.1.4",
+    "@tailwindcss/postcss": "^4.2.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.8.0",
+    "astro": "^6.1.9",
+    "tailwindcss": "^4.2.4",
+    "tsx": "^4.20.0",
+    "typescript": "5.9.3",
+    "vite": "^7.2.7",
+    "storybook": "^10.0.0",
+    "@storybook-astro/framework": "^1.6.0",
+    "@storybook/addon-docs": "^10.0.0",
+    "@storybook/builder-vite": "^10.0.0"
+  }
+}

package/templates/astro/template/src/cms/contracts/layouts/index.ts

@@ -0,0 +1,18 @@
+import { defineLayoutContract, slot, fragmentDefault } from '@gradial/aci';
+
+const layoutContracts = [
+  defineLayoutContract({
+    name: 'default',
+    slots: [
+      slot('header', false),
+      slot('main', true),
+      slot('footer', false),
+    ],
+    defaults: {
+      header: [fragmentDefault('navbar')],
+      footer: [fragmentDefault('site-footer')],
+    },
+  }),
+];
+
+export default layoutContracts;

package/templates/astro/template/src/cms/registry.ts

@@ -0,0 +1,28 @@
+import { createRegistry } from '@gradial/aci';
+import { homeHeroContract } from './contracts/components/homeHero.contract';
+import { containerContract } from './contracts/components/container.contract';
+import { buttonContract } from './contracts/components/button.contract';
+import { siteNavigationContract } from './contracts/components/siteNavigation.contract';
+import { siteFooterContract } from './contracts/components/siteFooter.contract';
+import { featureGridContract } from './contracts/components/featureGrid.contract';
+import { featureCardContract } from './contracts/components/featureCard.contract';
+import { statsBarContract } from './contracts/components/statsBar.contract';
+import HomeHero from '../components/sections/HomeHero.astro';
+import ContainerSection from '../components/sections/ContainerSection.astro';
+import ButtonBlock from '../components/elements/ButtonBlock.astro';
+import Header from '../components/chrome/Header.astro';
+import Footer from '../components/chrome/Footer.astro';
+import FeatureGrid from '../components/sections/FeatureGrid.astro';
+import FeatureCard from '../components/sections/FeatureCard.astro';
+import StatsBar from '../components/sections/StatsBar.astro';
+
+export const registry = createRegistry([
+  [homeHeroContract, HomeHero],
+  [containerContract, ContainerSection],
+  [buttonContract, ButtonBlock],
+  [siteNavigationContract, Header],
+  [siteFooterContract, Footer],
+  [featureGridContract, FeatureGrid],
+  [featureCardContract, FeatureCard],
+  [statsBarContract, StatsBar],
+]);

package/templates/astro/template/src/components/chrome/Footer.astro

@@ -0,0 +1,107 @@
+---
+import Container from '../elements/Container.astro';
+import Logo from '../elements/Logo.astro';
+
+interface FooterLink {
+  id: string;
+  label: string;
+  href: string;
+}
+
+interface FooterGroup {
+  id: string;
+  title: string;
+  links: FooterLink[];
+}
+
+interface FooterColumn {
+  id: string;
+  title?: string;
+  groups?: FooterGroup[];
+  links?: FooterLink[];
+}
+
+interface Props {
+  brandHref: string;
+  brandLabel?: string;
+  brandLogo?: { src: string; alt?: string } | null;
+  social?: Array<FooterLink & { icon?: string }>;
+  columns?: FooterColumn[];
+  legalLinks?: FooterLink[];
+  copyright?: string;
+}
+
+const {
+  brandHref,
+  brandLabel = 'Gradial',
+  brandLogo = null,
+  social = [],
+  columns = [],
+  legalLinks = [],
+  copyright = ''
+} = Astro.props;
+
+function columnGroups(column: FooterColumn): FooterGroup[] {
+  if (column.groups?.length) {
+    return column.groups;
+  }
+
+  return [{
+    id: column.id,
+    title: column.title || '',
+    links: column.links || []
+  }];
+}
+---
+
+<footer class="bm-footer [font-family:var(--font-family-base)] text-fg" id="footer">
+  <Container className="py-[var(--spacing-footer-y)]">
+    <div class="grid gap-12 pb-24 md:grid-cols-[var(--footer-grid-columns)] lg:gap-24">
+      <a href={brandHref} class="self-start">
+        <Logo
+          label={brandLabel}
+          src={brandLogo?.src || ''}
+          alt={brandLogo?.alt || brandLabel}
+          className="w-[var(--width-logo-footer-mobile)] md:w-[var(--width-logo-footer)]"
+        />
+      </a>
+      <div class="grid gap-10 sm:grid-cols-2 lg:grid-cols-4">
+        {columns.map((column) => (
+          <div class="space-y-10">
+            {columnGroups(column).map((group) => (
+              <section class="space-y-5" aria-label={group.title}>
+                <h2 class="text-[length:var(--text-size-body-small)] font-[var(--font-weight-semibold)] text-fg-muted">{group.title}</h2>
+                <ul class="space-y-4 text-[length:var(--text-size-body-small)] font-[var(--font-weight-semibold)] leading-body text-fg">
+                  {group.links.map((link) => (
+                    <li><a class="transition hover:text-link-hover" href={link.href}>{link.label}</a></li>
+                  ))}
+                </ul>
+              </section>
+            ))}
+          </div>
+        ))}
+        <section class="space-y-5" aria-label="Social">
+          <h2 class="text-[length:var(--text-size-body-small)] font-[var(--font-weight-semibold)] text-fg-muted">Social</h2>
+          <ul class="space-y-4 text-[length:var(--text-size-body-small)] font-[var(--font-weight-semibold)] text-fg">
+            {social.map((item) => (
+              <li>
+                <a class="inline-flex items-center gap-2 transition hover:text-link-hover" href={item.href}>
+                  <span class="min-w-5 text-[length:var(--text-size-caption)] text-fg-muted">{item.icon || item.label.slice(0, 1)}</span>
+                  <span>{item.label}</span>
+                </a>
+              </li>
+            ))}
+          </ul>
+        </section>
+      </div>
+    </div>
+    <div class="flex flex-col gap-6 border-t border-edge pt-8 text-[length:var(--text-size-caption)] font-[var(--font-weight-semibold)] text-fg-muted md:flex-row md:items-center md:justify-between">
+      <ul class="flex flex-wrap gap-x-9 gap-y-3 text-fg">
+        {legalLinks.map((link) => (
+          <li><a class="transition hover:text-link-hover" href={link.href}>{link.label}</a></li>
+        ))}
+      </ul>
+      <p>{copyright}</p>
+    </div>
+  </Container>
+</footer>