@gradial/aci 0.1.20-preview.3 → 0.1.21

package/templates/common/eslint-rules/no-raw-tailwind-values.js

@@ -0,0 +1,127 @@
+const UNIT = '(?:px|rem|em|vh|vw|dvh|dvw|svh|svw|ch|ex|cap|ic|lh|rlh|cm|mm|in|pt|pc|%)';
+const HEX_OR_LENGTH = new RegExp(`#[0-9a-fA-F]{3,8}\\b|\\d+(?:\\.\\d+)?${UNIT}`);
+const RATIO_ONLY = /^\d+\/\d+$/;
+const VARIANT_PREFIX = /^(!)?(?:(?:hover|focus|focus-within|focus-visible|active|disabled|visited|checked|first|last|odd|even|sm|md|lg|xl|2xl|dark|light|motion-safe|motion-reduce|portrait|landscape|print|rtl|ltr|open|placeholder|before|after|first-line|first-letter|selection|marker|group-hover|group-focus|peer-hover|peer-focus|has|not|aria-\w+|data-\w+):)*/;
+
+function extractArbitrary(token) {
+  const bare = token.replace(VARIANT_PREFIX, '');
+  const open = bare.indexOf('[');
+  if (open === -1) return null;
+  const close = bare.lastIndexOf(']');
+  if (close <= open) return null;
+  return bare.slice(open + 1, close);
+}
+
+function isBadArbitrary(content) {
+  // Allow anything containing a CSS variable reference.
+  if (content.includes('var(--')) return false;
+  // Allow values with no digits (selectors, keywords like `&>div`).
+  if (!/\d/.test(content) && !content.includes('#')) return false;
+  // Strip a leading data-type hint like `length:` or `color:`.
+  const value = content.replace(/^[a-z-]+:/, '');
+  if (RATIO_ONLY.test(value)) return false;
+  if (HEX_OR_LENGTH.test(value)) return true;
+  // Unitless numeric value (e.g. z-[60], w-[300]). Flag.
+  if (/\d/.test(value)) return true;
+  return false;
+}
+
+function findBadClassTokens(classString) {
+  const tokens = classString.trim().split(/\s+/).filter(Boolean);
+  const bad = [];
+  for (const token of tokens) {
+    const arb = extractArbitrary(token);
+    if (arb !== null && isBadArbitrary(arb)) {
+      bad.push(token);
+    }
+  }
+  return bad;
+}
+
+function findBadStyleMatches(styleString) {
+  // Strip var(--...) references so legitimate token names containing digits don't match.
+  const stripped = styleString.replace(/var\([^)]*\)/g, '');
+  const matches = stripped.match(new RegExp(HEX_OR_LENGTH.source, 'g'));
+  return matches || [];
+}
+
+function reportClass(context, node, value) {
+  if (typeof value !== 'string' || !value.includes('[')) return;
+  const bad = findBadClassTokens(value);
+  if (bad.length > 0) {
+    context.report({
+      node,
+      message: `Raw arbitrary Tailwind values are not allowed: ${bad.join(', ')}. Use design system tokens (var(--...)) instead.`
+    });
+  }
+}
+
+function reportStyle(context, node, value) {
+  if (typeof value !== 'string') return;
+  const bad = findBadStyleMatches(value);
+  if (bad.length > 0) {
+    context.report({
+      node,
+      message: `Raw values are not allowed in inline style: ${bad.join(', ')}. Use design system tokens (var(--...)) instead.`
+    });
+  }
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noRawTailwindValues = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow raw hex/length values in Tailwind arbitrary values and inline style attributes; require design tokens via var(--...).'
+    },
+    schema: []
+  },
+  create(context) {
+    function handleClassNode(node, value) {
+      reportClass(context, node, value);
+    }
+
+    function handleStyleStringNode(node, value) {
+      reportStyle(context, node, value);
+    }
+
+    function visitClassLiteral(node) {
+      handleClassNode(node, node.value);
+    }
+    function visitClassTemplate(node) {
+      for (const quasi of node.quasis) handleClassNode(node, quasi.value.raw);
+    }
+
+    return {
+      // JSX/Astro class attribute
+      [`JSXAttribute[name.name=/^(class|className)$/] > Literal`]: visitClassLiteral,
+      [`JSXAttribute[name.name=/^(class|className)$/] > TemplateLiteral`]: visitClassTemplate,
+
+      // Object-form { class: '...' } (e.g. clsx args, defineProps defaults)
+      'Property[key.name="class"] > Literal'(node) {
+        handleClassNode(node, node.value);
+      },
+      'Property[key.name="class"] > TemplateLiteral'(node) {
+        for (const quasi of node.quasis) handleClassNode(node, quasi.value.raw);
+      },
+
+      // JSX/Astro style="..." (string form, common in Astro and HTML)
+      'JSXAttribute[name.name="style"] > Literal'(node) {
+        handleStyleStringNode(node, node.value);
+      },
+      'JSXAttribute[name.name="style"] > TemplateLiteral'(node) {
+        for (const quasi of node.quasis) handleStyleStringNode(node, quasi.value.raw);
+      },
+
+      // React style={{ color: '#fff', padding: '10px' }}
+      'JSXAttribute[name.name="style"] JSXExpressionContainer > ObjectExpression > Property > Literal'(node) {
+        if (typeof node.value === 'string') handleStyleStringNode(node, node.value);
+      },
+      'JSXAttribute[name.name="style"] JSXExpressionContainer > ObjectExpression > Property > TemplateLiteral'(node) {
+        for (const quasi of node.quasis) handleStyleStringNode(node, quasi.value.raw);
+      }
+    };
+  }
+};
+
+export default noRawTailwindValues;

package/templates/common/public/assets/meridian-logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 40" fill="#0f172a">
+  <g aria-label="Meridian">
+    <circle cx="16" cy="20" r="6" fill="#0f172a"/>
+    <path d="M16 6v6M16 28v6M6 20h6M20 20h6" stroke="#0f172a" stroke-width="3" stroke-linecap="round"/>
+    <ellipse cx="16" cy="20" rx="14" ry="5" fill="none" stroke="#0f172a" stroke-width="2" transform="rotate(-30 16 20)"/>
+  </g>
+  <text x="42" y="26" font-family="Space Grotesk, Inter, sans-serif" font-size="22" font-weight="700" letter-spacing="-0.02em" fill="#0f172a">Meridian</text>
+</svg>

package/templates/nextjs/template/.aci.yaml

@@ -0,0 +1,26 @@
+version: "1"
+siteId: "site_nextjs"
+domain: "meridian.local"
+framework: next
+
+source:
+  root: "./"
+
+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/*"
+    - "/_next/*"
+    - "/.gradial-dam/*"
+
+rendererProtocol: stdio-json

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

@@ -0,0 +1,13 @@
+import type { StorybookConfig } from '@storybook/nextjs';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx|mdx)'],
+  addons: ['@storybook/addon-docs'],
+  framework: {
+    name: '@storybook/nextjs',
+    options: {}
+  },
+  staticDirs: ['../public'],
+};
+
+export default config;

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

@@ -0,0 +1,34 @@
+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: [
+    // Storybook decorator types are verbose; keep the starter example focused.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (Story: any, context: any) => {
+      const theme = context.globals.theme || 'light';
+      document.body.className = `theme-${theme} min-h-screen bg-[var(--color-surface-default)]`;
+      return Story();
+    }
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    options: {
+      storySort: {
+        order: ['Core Atomic Blocks', 'Composition', '*']
+      }
+    }
+  }
+};
+
+export default preview;

package/templates/nextjs/template/eslint.config.mjs

@@ -0,0 +1,36 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { includeIgnoreFile } from '@eslint/compat';
+import { FlatCompat } from '@eslint/eslintrc';
+import eslintPlugin from 'eslint-plugin-import';
+import noRawTailwind from './eslint-rules/no-raw-tailwind-values.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const compat = new FlatCompat({ baseDirectory: __dirname });
+const gitignorePath = resolve(__dirname, '.gitignore');
+
+const eslintConfig = [
+  includeIgnoreFile(gitignorePath),
+  { ignores: ['next-env.d.ts'] },
+  ...compat.extends('next/core-web-vitals', 'next/typescript'),
+  {
+    plugins: {
+      import: eslintPlugin,
+    },
+  },
+  {
+    plugins: {
+      'aci-rules': {
+        rules: {
+          'no-raw-tailwind-values': noRawTailwind,
+        },
+      },
+    },
+    rules: {
+      'aci-rules/no-raw-tailwind-values': 'warn',
+    },
+  },
+];
+
+export default eslintConfig;

package/templates/nextjs/template/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/nextjs/template/next.config.ts

@@ -0,0 +1,8 @@
+import { withAci } from '@gradial/aci/next/config';
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default withAci(nextConfig);

package/templates/nextjs/template/package.json.tmpl

@@ -0,0 +1,46 @@
+{
+  "name": "{{siteName}}",
+  "version": "{{version}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "ACI_CONTENT_PROVIDER=file next dev -H 0.0.0.0",
+    "build": "next build",
+    "preview": "next start -H 0.0.0.0",
+    "typecheck": "tsc --noEmit",
+    "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",
+    "lint": "eslint .",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build"
+  },
+  "dependencies": {
+    "@gradial/aci": "0.2.0-rc.0",
+    "js-yaml": "^4.1.1",
+    "next": "^15.1.6",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@eslint/compat": "^1.2.0",
+    "@eslint/eslintrc": "^3.2.0",
+    "eslint": "^9.18.0",
+    "eslint-config-next": "^15.1.6",
+    "eslint-plugin-import": "^2.29.1",
+    "tailwindcss": "^4.2.4",
+    "@tailwindcss/postcss": "^4.2.4",
+    "tsx": "^4.20.0",
+    "typescript": "5.9.3",
+    "storybook": "^9.0.0",
+    "@storybook/nextjs": "^9.0.0",
+    "@storybook/addon-docs": "^9.0.0"
+  }
+}

package/templates/nextjs/template/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/templates/nextjs/template/src/app/[[...slug]]/page.tsx

@@ -0,0 +1,8 @@
+import { createPage } from '@gradial/aci/next';
+import { registry } from '@/cms/registry';
+
+const page = createPage(registry);
+
+export const dynamic = 'force-dynamic';
+export const generateMetadata = page.generateMetadata;
+export default page.default;

package/templates/nextjs/template/src/app/gradial/assets/[releaseId]/[...path]/route.ts

@@ -0,0 +1,31 @@
+import { getReleaseAssetResponse } from '@gradial/aci/content';
+import { FileContentProvider } from '@gradial/aci/providers/file';
+
+const LOCAL_RELEASE_ID = 'local';
+
+type AssetRouteContext = {
+  params: Promise<{
+    releaseId?: string;
+    path?: string[];
+  }>;
+};
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+export async function GET(_request: Request, { params }: AssetRouteContext): Promise<Response> {
+  const resolvedParams = await params;
+  const releaseId = resolvedParams.releaseId || '';
+  const assetPath = '/' + (resolvedParams.path || []).join('/');
+  if (!releaseId || assetPath === '/') {
+    return new Response('asset not found', { status: 404 });
+  }
+  if (releaseId === LOCAL_RELEASE_ID) {
+    return new FileContentProvider().fetchRaw(assetPath);
+  }
+  try {
+    return await getReleaseAssetResponse({ releaseId, assetPath });
+  } catch {
+    return new Response('asset not found', { status: 404 });
+  }
+}

package/templates/nextjs/template/src/app/layout.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import { Inter, Space_Grotesk } from 'next/font/google';
+import { DevRefresh } from '@gradial/aci/next';
+import '@/design-system/styles.css';
+
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+  display: 'swap',
+  weight: ['400', '500', '600', '700'],
+});
+
+const spaceGrotesk = Space_Grotesk({
+  subsets: ['latin'],
+  variable: '--font-space-grotesk',
+  display: 'swap',
+  weight: ['400', '500', '600', '700'],
+});
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${spaceGrotesk.variable}`}>
+      <body>
+        {children}
+        <DevRefresh />
+      </body>
+    </html>
+  );
+}

package/templates/nextjs/template/src/cms/contracts/components/button.contract.ts

@@ -0,0 +1,19 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  label: z.string().min(1),
+  href: z.string().min(1),
+  variant: z.enum(['primary', 'secondary', 'tertiary', 'outline', 'ghost']).optional(),
+  newWindow: z.boolean().optional(),
+  icon: z.string().optional(),
+  iconPosition: z.enum(['before', 'after']).optional(),
+  className: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const buttonContract = defineComponentContract({
+  id: 'button',
+  props: schema,
+});

package/templates/nextjs/template/src/cms/contracts/components/container.contract.ts

@@ -0,0 +1,20 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  theme: z.enum(['auto', 'light', 'dark']).optional(),
+  className: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const containerContract = defineComponentContract({
+  id: 'container',
+  props: schema,
+  slots: {
+    content: {
+      allowed: ['button'],
+      multiple: true,
+    },
+  },
+});

package/templates/nextjs/template/src/cms/contracts/components/homeHero.contract.ts

@@ -0,0 +1,36 @@
+import { defineComponentContract, ImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  eyebrow: z.string().optional(),
+  headline: z.string().min(1),
+  description: z.string().optional(),
+  ctaLabel: z.string().min(1),
+  ctaHref: z.string().min(1),
+  image: ImageSchema,
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const homeHeroContract = defineComponentContract({
+  id: 'home_hero',
+  props: schema,
+  imageSlots: {
+    image: {
+      formats: ['image/avif', 'image/webp', 'image/jpeg'],
+      sizes: '100vw',
+      outputs: [
+        {
+          aspectRatio: '16:9',
+          widths: [768, 1280, 1920],
+          media: '(min-width: 768px)',
+        },
+        {
+          aspectRatio: '3:4',
+          widths: [480, 720, 960],
+          media: '(max-width: 767px)',
+        },
+      ],
+    },
+  },
+});

package/templates/nextjs/template/src/cms/contracts/components/index.ts

@@ -0,0 +1,15 @@
+import { buttonContract } from './button.contract';
+import { containerContract } from './container.contract';
+import { homeHeroContract } from './homeHero.contract';
+import { siteNavigationContract } from './siteNavigation.contract';
+import { siteFooterContract } from './siteFooter.contract';
+
+const componentContracts = [
+  homeHeroContract,
+  containerContract,
+  buttonContract,
+  siteNavigationContract,
+  siteFooterContract,
+];
+
+export default componentContracts;

package/templates/nextjs/template/src/cms/contracts/components/siteFooter.contract.ts

@@ -0,0 +1,45 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+const linkSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  href: z.string().min(1),
+});
+
+const groupSchema = z.object({
+  id: z.string().min(1),
+  title: z.string(),
+  links: z.array(linkSchema),
+});
+
+const columnSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().optional(),
+  links: z.array(linkSchema).optional(),
+  groups: z.array(groupSchema).optional(),
+});
+
+const socialSchema = linkSchema.extend({
+  icon: z.string().optional(),
+});
+
+export const schema = z.object({
+  brandHref: z.string().min(1),
+  brandLabel: z.string().min(1),
+  brandLogo: z.object({
+    src: z.string(),
+    alt: z.string(),
+  }).nullable().optional(),
+  columns: z.array(columnSchema),
+  social: z.array(socialSchema).optional(),
+  legalLinks: z.array(linkSchema).optional(),
+  copyright: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const siteFooterContract = defineComponentContract({
+  id: 'site-footer',
+  props: schema,
+});

package/templates/nextjs/template/src/cms/contracts/components/siteNavigation.contract.ts

@@ -0,0 +1,30 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+const linkSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  href: z.string().min(1),
+});
+
+const utilitySchema = linkSchema.extend({
+  variant: z.enum(['primary', 'secondary', 'tertiary', 'outline', 'ghost']).optional(),
+});
+
+export const schema = z.object({
+  brandHref: z.string().min(1),
+  brandLabel: z.string().min(1),
+  brandLogo: z.object({
+    src: z.string(),
+    alt: z.string(),
+  }).nullable().optional(),
+  navigation: z.array(linkSchema),
+  utilities: z.array(utilitySchema).optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const siteNavigationContract = defineComponentContract({
+  id: 'site-navigation',
+  props: schema,
+});

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

@@ -0,0 +1,16 @@
+const layoutContracts = [
+  {
+    name: 'default',
+    slots: [
+      { name: 'header', required: false },
+      { name: 'main', required: true },
+      { name: 'footer', required: false },
+    ],
+    defaults: {
+      header: [{ kind: 'fragment-ref', fragmentId: 'navbar', inline: true }],
+      footer: [{ kind: 'fragment-ref', fragmentId: 'site-footer', inline: true }],
+    },
+  },
+];
+
+export default layoutContracts;

package/templates/nextjs/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';
+import { ContainerSection } from '@/components/sections/ContainerSection';
+import { ButtonBlock } from '@/components/elements/ButtonBlock';
+import { Header } from '@/components/chrome/Header';
+import { Footer } from '@/components/chrome/Footer';
+import { FeatureGrid } from '@/components/sections/FeatureGrid';
+import { FeatureCard } from '@/components/sections/FeatureCard';
+import { StatsBar } from '@/components/sections/StatsBar';
+
+export const registry = createRegistry([
+  [homeHeroContract, HomeHero],
+  [containerContract, ContainerSection],
+  [buttonContract, ButtonBlock],
+  [siteNavigationContract, Header],
+  [siteFooterContract, Footer],
+  [featureGridContract, FeatureGrid],
+  [featureCardContract, FeatureCard],
+  [statsBarContract, StatsBar],
+]);