@gradial/aci 0.1.20-preview.2 → 0.1.20

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,27 @@
+version: "1"
+siteId: "site_astro"
+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>

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

@@ -0,0 +1,94 @@
+---
+import Button from '../elements/Button.astro';
+import Container from '../elements/Container.astro';
+import Icon from '../elements/Icon.astro';
+import Logo from '../elements/Logo.astro';
+
+interface NavItem {
+  id: string;
+  label: string;
+  href: string;
+}
+
+interface UtilityItem extends NavItem {
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+}
+
+interface Props {
+  brandHref: string;
+  brandLabel?: string;
+  brandLogo?: { src: string; alt?: string } | null;
+  navigation?: NavItem[];
+  utilities?: UtilityItem[];
+}
+
+const {
+  brandHref,
+  brandLabel = 'Gradial',
+  brandLogo = null,
+  navigation = [],
+  utilities = []
+} = Astro.props;
+---
+
+<header class="bm-header sticky top-0 z-[var(--z-header)] [font-family:var(--font-family-base)] text-fg">
+  <a
+    href="#content-main"
+    class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-10 focus:rounded-button focus:bg-white focus:px-4 focus:py-2 focus:text-black"
+  >
+    Skip to main content
+  </a>
+  <Container className="flex min-h-[var(--height-header)] items-center justify-between gap-4">
+    <a href={brandHref} class="shrink-0">
+      <Logo label={brandLabel} src={brandLogo?.src || ''} alt={brandLogo?.alt || brandLabel} />
+    </a>
+    <nav class="hidden items-center gap-9 text-[length:var(--text-size-body-small)] font-[var(--font-weight-semibold)] text-fg-muted lg:flex" aria-label="Primary">
+      {navigation.map((item) => (
+        <a class="transition hover:text-link-hover" href={item.href}>{item.label}</a>
+      ))}
+    </nav>
+    <div class="flex shrink-0 items-center gap-3">
+      <div class="hidden items-center gap-3 sm:flex">
+        {utilities.map((item) => (
+          <Button href={item.href} variant={item.variant || 'outline'}>{item.label}</Button>
+        ))}
+      </div>
+      <div class="lg:hidden">
+        <input id="site-mobile-nav" class="peer sr-only" type="checkbox" />
+        <label
+          for="site-mobile-nav"
+          class="inline-grid size-11 cursor-pointer place-items-center rounded-button border border-edge text-fg transition hover:text-link-hover"
+          aria-label="Open main navigation"
+        >
+          <Icon name="menu" className="size-6" />
+        </label>
+        <div class="bm-mobile-nav pointer-events-none fixed inset-0 z-[var(--z-overlay)] flex translate-x-full flex-col px-[var(--spacing-container)] py-5 text-fg opacity-0 transition duration-300 ease-out peer-checked:pointer-events-auto peer-checked:translate-x-0 peer-checked:opacity-100">
+          <div class="flex min-h-[var(--height-header)] items-center justify-between gap-4">
+            <a href={brandHref} class="shrink-0">
+              <Logo label={brandLabel} src={brandLogo?.src || ''} alt={brandLogo?.alt || brandLabel} />
+            </a>
+            <label
+              for="site-mobile-nav"
+              class="inline-grid size-11 cursor-pointer place-items-center rounded-button border border-edge text-fg transition hover:text-link-hover"
+              aria-label="Close main navigation"
+            >
+              <Icon name="close" className="size-6" />
+            </label>
+          </div>
+          <nav class="grid flex-1 content-center gap-4 py-10 font-[var(--font-weight-bold)] text-[length:var(--mobile-nav-link-size)] leading-[var(--mobile-nav-link-line-height)] text-fg" aria-label="Mobile main navigation">
+            {navigation.map((item) => (
+              <a class="transition hover:text-link-hover" href={item.href}>{item.label}</a>
+            ))}
+          </nav>
+          {utilities.length ? (
+            <div class="grid gap-3 border-t border-edge pt-5 sm:hidden">
+              {utilities.map((item) => (
+                <Button href={item.href} variant={item.variant || 'outline'} className="w-full">{item.label}</Button>
+              ))}
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  </Container>
+</header>

package/templates/astro/template/src/components/elements/AtomicBlock.astro

@@ -0,0 +1,15 @@
+---
+import type { KernelAtomicBlock } from '@gradial/aci/content';
+import ButtonBlock from './ButtonBlock.astro';
+
+interface Props {
+  block: KernelAtomicBlock;
+}
+
+const { block } = Astro.props;
+const props = (block.props || {}) as any;
+---
+
+{block.component === 'button' ? (
+  <ButtonBlock {...props} />
+) : null}