npm - @gradial/aci - Versions diffs - 0.1.20-preview.3 → 0.1.21 - Mend

@gradial/aci 0.1.20-preview.3 → 0.1.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (227) hide show

package/templates/common/.agents/skills/authoring/references/block-registry.md ADDED Viewed

@@ -0,0 +1,151 @@
+# Component Registry Patterns
+The component registry maps contract names to runtime components. It is built
+using `createRegistry` from `@gradial/aci` with raw `[contract, component]` tuples.
+The tuple form provides **type-level validation** — the component must accept
+at least the props derived from the contract's Zod schema. If you register a
+component with the wrong prop type, TypeScript will fail at the call site.
+**Never use `Record<string, ComponentType<any>>`.** This hides prop
+mismatches and name typos until runtime.
+**Never alias** — each contract name maps to exactly one runtime component.
+No `hero` + `page_hero` pointing to the same component.
+## Registry File
+All frameworks use a single `src/cms/registry.ts` file:
+```ts
+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 { HomeHero } from '@/components/sections/HomeHero';
+import { ContainerSection } from '@/components/sections/ContainerSection';
+import { ButtonBlock } from '@/components/elements/ButtonBlock';
+export const registry = createRegistry([
+  [homeHeroContract, HomeHero],
+  [containerContract, ContainerSection],
+  [buttonContract, ButtonBlock],
+]);
+```
+When adding a new component:
+1. Create the contract in `src/cms/contracts/components/{name}.contract.ts`
+2. Export it from `src/cms/contracts/components/index.ts`
+3. Create the runtime component in `src/components/{elements|sections|chrome}/`
+4. Add a `[contract, component]` tuple in `src/cms/registry.ts`
+## Next.js Pattern
+The SDK provides `createPage(registry)` which owns param normalization, content
+loading, layout resolution, metadata generation, notFound handling, slot
+resolution (including fragment defaults), and block rendering.
+Chrome (Header/Footer) is **not** in `layout.tsx`. It is CMS-managed via
+layout fragment defaults. The `layout.tsx` file is minimal:
+```tsx
+// src/app/layout.tsx — minimal, no chrome
+import type { ReactNode } from 'react';
+import '@/design-system/styles.css';
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+```tsx
+// src/app/[[...slug]]/page.tsx — SDK owns all rendering
+import { createPage } from '@gradial/aci/next/page';
+import { registry } from '@/cms/registry';
+const page = createPage(registry);
+export const dynamic = 'force-dynamic';
+export const generateMetadata = page.generateMetadata;
+export default page.default;
+```
+`createPage` loads the page's layout, resolves all slots (filling from page
+regions or layout fragment defaults), and renders blocks via the registry.
+The `main` slot is wrapped in `<main>`; other slots render as fragments.
+## Custom Server Composition
+For route-specific server behavior such as blogs, events, and product detail
+pages, use public server-only providers:
+```ts
+import { loadRenderInput } from '@gradial/aci/content';
+import { FileContentProvider } from '@gradial/aci/providers/file';
+const provider = new FileContentProvider();
+const input = await loadRenderInput(provider, '/events');
+```
+Do not import providers from client components. Browser fetch should go through
+an app-owned HTTP endpoint backed by a server-side `ContentProvider`.
+## Astro Pattern
+Astro uses a catch-all route and renders via the shared registry:
+```astro
+---
+// src/pages/[...slug].astro
+import { createPage } from '@gradial/aci/astro/page';
+import { registry } from '@/cms/registry';
+const page = createPage(registry);
+export const getStaticPaths = page.getStaticPaths;
+export default page.default;
+---
+```
+The `createPage` helper owns param normalization, content loading, layout
+resolution, metadata generation, notFound handling, slot resolution
+(including fragment defaults), and block rendering.
+### Astro-Specific Paths
+| Concern | Path |
+|---------|------|
+| Routes | `src/pages/[...slug].astro` |
+| Layout | `src/layouts/SiteLayout.astro` |
+| Config | `astro.config.mjs` with `withAci()` |
+| Registry | `src/cms/registry.ts` (shared) |
+| Storybook | `.storybook/main.ts`, `.storybook/preview.ts` |
+## Middleware
+```ts
+// src/middleware.ts
+import { createMiddleware } from '@gradial/aci/next/middleware';
+export default createMiddleware();
+export { config } from '@gradial/aci/next/middleware';
+```
+## Asset Routes
+```ts
+// src/app/gradial/assets/[releaseId]/[...path]/route.ts
+export { GET, runtime, dynamic } from '@gradial/aci/next/asset-route';
+```
+## Anti-Patterns
+- `Record<string, any>` or `Record<string, ComponentType<any>>` — hides type errors
+- `createRegistryEntry()` wrapper — use raw `[contract, component]` tuples instead
+- Aliasing: two contract names → same component
+- Hand-rolled content loading in route files instead of `createPage`
+- `src/lib/content.ts` shim duplicating SDK behavior
+- Local Vite middleware for DAM derivative serving instead of `withAci()`
+- SvelteKit patterns (conditional rendering, `svelte:component`) — SvelteKit
+  support has been removed

package/templates/common/.agents/skills/authoring/references/contracts.md ADDED Viewed

@@ -0,0 +1,153 @@
+# Contracts Reference
+## Component Contract API
+```ts
+import { defineComponentContract, ImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+export const schema = z.object({
+  headline: z.string().min(1),
+  image: ImageSchema,
+});
+export type ContentProps = z.infer<typeof schema>;
+export const heroContract = defineComponentContract({
+  id: 'hero',
+  props: schema,
+  imageSlots: {
+    image: {
+      outputs: [{ aspectRatio: '16:9', widths: [960, 1280, 1920] }],
+      formats: ['webp'],
+      sizes: '100vw',
+    },
+  },
+});
+```
+The `defineComponentContract` function takes:
+- `id` — the contract name used in content JSON `component` fields and the
+  registry key. snake_case.
+- `props` — the Zod schema for content props.
+- `imageSlots` (optional) — image processing configuration.
+- `displayName` (optional) — human-readable name.
+- `validate` (optional) — additional validation functions.
+`renderModes` has been removed from the contract API. There is no
+`renderModes`, `canStatic`, `canSSR`, or `canClientIsland` field.
+## Contract Rules
+- Import `@gradial/aci`, `zod`, and shared schema helpers only.
+- Do not import React components, Astro components, CSS, browser
+  globals, framework runtime modules, or customer content.
+- Export a conventional `<camelName>Contract` value.
+- Export `ContentProps` from `z.infer<typeof schema>` so runtime
+  implementation can use it.
+- Use contract `id` as the content JSON `component` value and runtime
+  registry key.
+- `renderModes` has been removed. Do not include it in contracts.
+## Component Barrel
+```ts
+// src/cms/contracts/components/index.ts
+import { heroContract } from './hero.contract';
+import { buttonContract } from './button.contract';
+export default [heroContract, buttonContract];
+```
+## Layout Contract API
+```ts
+export default [
+  {
+    name: 'marketing',
+    slots: [
+      { name: 'main', required: true },
+      { name: 'footer', required: false },
+    ],
+  },
+];
+```
+Content pages reference layouts by name:
+```json
+{
+  "layout": "marketing",
+  "regions": {
+    "main": [...],
+    "footer": [...]
+  }
+}
+```
+## Multiple Runtime Mappings
+One runtime component may implement multiple contract names. Define
+separate contract files, then map each contract name to the same runtime
+component explicitly in the registry.
+## .aci.yaml Configuration
+Declares ACI contract entrypoints and framework behavior. Lives at the
+project root.
+```yaml
+version: "1"
+siteId: "site_example"
+framework: astro  # astro | next
+source:
+  root: "./"
+  outDir: "dist"       # Astro only
+  publicDir: "public"  # Astro only
+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/*"       # Next.js
+    - "/.gradial-dam/*"
+rendererProtocol: stdio-json
+```
+### Fields
+| Field | Purpose |
+|-------|---------|
+| `version` | Config schema version |
+| `siteId` | Unique site identifier |
+| `framework` | `astro` or `next` (SvelteKit removed) |
+| `source.root` | Source root directory |
+| `source.outDir` | Build output directory (Astro) |
+| `source.publicDir` | Public assets directory (Astro) |
+| `componentRegistry` | Path to component contract barrel |
+| `layoutRegistry` | Path to layout contract barrel |
+| `capabilities` | Render capabilities (static, SSR, islands, fragments) |
+| `routes.cmsManaged` | Catch-all route pattern for CMS pages |
+| `routes.frameworkOwned` | Route patterns excluded from CMS routing |
+| `rendererProtocol` | Renderer communication protocol |
+### Removed fields
+- `rendererEntry` has been removed from `.aci.yaml`. Do not include it.
+### Rules
+- `componentRegistry` and `layoutRegistry` point to contract-only modules.
+- No secrets in `.aci.yaml`, docs, fixtures, or generated files.

package/templates/common/.agents/skills/authoring/references/design-system.md ADDED Viewed

@@ -0,0 +1,171 @@
+# Design System Reference
+## Source of Truth
+Design tokens are CSS custom properties defined in `@theme` blocks under
+`src/design-system/tokens/`. Tailwind v4 reads them and auto-generates
+utility classes.
+| File | Scope |
+|------|-------|
+| `colors.css` | Brand colors, semantic tokens, surfaces, borders |
+| `typography.css` | Font families, sizes, weights, line heights |
+| `spacing.css` | Spacing scale, container padding, section spacing |
+| `radii.css` | Border radius values |
+| `shadows.css` | Card and overlay shadows |
+| `components.css` | Component-level tokens (buttons, header, footer) |
+| `index.css` | Barrel import for all token files |
+## Using Design Tokens
+### Direct Tailwind utilities (preferred)
+Tailwind v4 derives utilities from `@theme` tokens. Use these directly:
+- **Color**: `text-fg`, `text-fg-muted`, `bg-surface-default`, `bg-page-inverse`, `border-edge`
+- **Radii**: `rounded-card`, `rounded-button`
+- **Shadows**: `shadow-card-default`
+Standard spacing/sizing utilities (`px-4`, `gap-6`, `w-24`, `max-w-3xl`)
+are safe because Tailwind v4 derives its spacing scale from `--spacing`.
+Layout utilities (`items-center`, `overflow-hidden`, `aspect-video`,
+`uppercase`, `text-lg`, breakpoint prefixes like `lg:`) are all fine.
+### Bracket syntax (for tokens without direct utilities)
+For values without a direct Tailwind utility mapping — gradients,
+typography tokens, complex custom properties — use `var(--...)` bracket
+syntax:
+- **Gradients**: `bg-[image:var(--gradient-cta-dark)]`, `bg-[image:var(--gradient-hero-overlay)]`
+- **Typography**: `text-[length:var(--text-size-body)]`, `font-[var(--font-weight-semibold)]`, `[font-family:var(--font-family-heading)]`, `leading-[var(--leading-heading)]`
+- **Spacing tokens**: `py-[var(--spacing-section-y)]`, `p-[var(--spacing-card)]`
+## Forbidden Values
+**No raw hex colors**: `text-[#8b72ff]`, `bg-[#f6f6f7]`
+**No raw pixel values**: `p-[12px]`, `w-[200px]`, `gap-[24px]`
+**No raw rem values**: `text-[1.25rem]`, `p-[0.75rem]`
+**No Tailwind named colors**: `text-gray-500`, `bg-purple-400`
+Use CSS variable tokens instead. If a token doesn't exist for a value you
+need, add it to the appropriate `tokens/*.css` file.
+The ESLint rule `no-raw-tailwind-values` enforces this in component code.
+Raw values are allowed only inside `src/design-system/tokens/` and
+`src/design-system/styles.css`.
+## Component CSS Discipline
+- Use Tailwind classes for layout, spacing, responsive behavior, display,
+  flex/grid, sizing, and positioning.
+- Use CSS custom properties from the design system for colors, surfaces,
+  borders, typography, font sizes, radii, shadows, gradients, spacing
+  scales, and theme behavior.
+- Do not hard-code color, font family, or font size values in component
+  markup when a design token can express the intent.
+- Do not create component-specific text color tokens when contextual tokens
+  are enough. Prefer `--color-text-default`, `--color-text-default-muted`,
+  `--color-surface-default`, `--color-border-default`.
+- Keep button variant tokens explicit for contrast-sensitive states.
+## Theme System
+Three theme classes control semantic token resolution:
+| Class | Use Case |
+|-------|----------|
+| `theme-auto` | Normal page content following browser light/dark preference |
+| `theme-dark` | Fixed dark surfaces (header, footer, hero) |
+| `theme-accent` | CTA-style accent surfaces |
+Theme classes override semantic tokens:
+```css
+.theme-dark {
+  --color-fg: var(--color-fg-inverse);
+  --color-surface-default: var(--color-page-inverse);
+  --color-edge: var(--color-edge-inverse);
+  /* ... */
+}
+```
+Apply theme classes to wrapper elements:
+```html
+<div class="theme-dark">
+  <p class="text-fg">This text uses the dark theme fg color.</p>
+</div>
+```
+### Chrome-Specific Override Scopes
+Header, footer, and mobile nav have dedicated class scopes for
+self-contained chrome theming:
+| Scope | Purpose |
+|-------|---------|
+| `.bm-header` | Header background, text, borders, button overrides |
+| `.bm-footer` | Footer background, text, borders, button overrides |
+| `.bm-mobile-nav` | Mobile nav background, text, borders |
+These scopes set their own token values independently of the theme system.
+Use them to override chrome appearance without leaking overrides into page
+content.
+## Grid Layout
+Use a 12-column grid mental model for layout sections. Grid components
+that render a variable number of children must compute column classes
+dynamically:
+| Items | Columns | Responsive Pattern |
+|-------|---------|-------------------|
+| 1 | 12 | full width |
+| 2 | 6 each | `sm:grid-cols-2` |
+| 3 | 4 each | `sm:grid-cols-2 lg:grid-cols-3` |
+| 4 | 3 each | `sm:grid-cols-2 lg:grid-cols-4` |
+### Critical: Tailwind Purge Safety
+Tailwind purges unused CSS classes at build time. Dynamic column classes
+must appear as **complete string literals** in source code — not assembled
+via string interpolation.
+**Bad** (class is purged, no CSS generated):
+```tsx
+<div className={`grid-cols-${columns}`}>
+```
+**Good** (complete literal, survives purge):
+```tsx
+const gridClasses: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'sm:grid-cols-2',
+  3: 'sm:grid-cols-2 lg:grid-cols-3',
+  4: 'sm:grid-cols-2 lg:grid-cols-4',
+};
+<div className={gridClasses[columns]}>
+```
+This applies to all dynamic Tailwind classes, not just grid columns. Any
+class that is conditionally applied must be a complete literal visible to
+the Tailwind scanner.
+## Adding New Tokens
+When a source value doesn't map to an existing token:
+1. Add the token to the appropriate `tokens/*.css` file inside `@theme`:
+```css
+@theme {
+  --color-brand-500: #6b5ce7;
+}
+```
+2. Reference it from component code:
+```html
+<div class="text-[var(--color-brand-500)]">
+```
+3. Tailwind v4 will auto-generate a utility if the token name matches a
+   Tailwind namespace (e.g. `--color-*` generates `text-*`, `bg-*`).

package/templates/common/.agents/skills/authoring/references/image-assets.md ADDED Viewed

@@ -0,0 +1,73 @@
+# Image Slots and Assets
+## ImageSchema
+Use `ImageSchema` for DAM-managed image fields in contracts:
+```ts
+import { ImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+export const schema = z.object({
+  image: ImageSchema,
+  cards: z.array(z.object({
+    image: ImageSchema.optional(),
+  })),
+});
+```
+## Image Slots Configuration
+Declare `imageSlots` matching every `ImageSchema` field, including nested array
+paths:
+```ts
+export const contract = defineComponentContract({
+  name: 'cards',
+  schema,
+  imageSlots: {
+    image: {
+      formats: ['image/webp'],
+      sizes: '100vw',
+      outputs: [{ aspectRatio: '16:9', widths: [960, 1280] }],
+    },
+    'cards.image': {
+      formats: ['image/webp'],
+      sizes: '50vw',
+      outputs: [{ aspectRatio: '1:1', widths: [320, 640] }],
+    },
+  },
+});
+```
+## Runtime Image Rendering Rules
+- Read image values from CMS props, never hard-code.
+- Render Gradial images as `<picture>` when sources are present.
+- Use `primaryImageSource(image).src` from `@gradial/aci` to get the primary URL.
+- Preserve `width`/`height` from the primary source to prevent layout shift.
+- For CSS backgrounds, set a CSS custom property from the content asset URL.
+- Treat image URLs as opaque props — do not synthesize placeholder images
+  during code artifact builds.
+> **API note:** The schema helper is named `ImageSchema` (not
+> `GradialImageSchema`). The runtime helper is `primaryImageSource()`.
+> Use `primaryImageSource(image).src` for the primary URL.
+## Content Image References
+In content JSON, use DAM asset references:
+```json
+{
+  "image": {
+    "$type": "dam.assetRef",
+    "assetId": "ast_site_home_hero",
+    "alt": "Hero illustration"
+  }
+}
+```
+The compiler resolves these to Gradial image objects with `sources`, `alt`,
+`assetId`, and `versionId`. Each source carries `src`, `width`, `height`, and
+`type`.