@407dev/cms-astro 0.1.0

package/src/fields/attrs.ts

@@ -0,0 +1,24 @@
+export function cmsFieldAttr(key: string): { 'data-cms-field': string } {
+  return { 'data-cms-field': key };
+}
+
+export function cmsGroupAttr(groupName: string, prefix: string): { 'data-cms-group': string } {
+  return { 'data-cms-group': `${groupName}:${prefix}` };
+}
+
+export function cmsEntryAttr(
+  collectionKey: string,
+  slug?: string,
+): { 'data-cms-collection': string; 'data-cms-entry'?: string } {
+  if (slug) {
+    return {
+      'data-cms-collection': collectionKey,
+      'data-cms-entry': slug,
+    };
+  }
+  return { 'data-cms-collection': collectionKey };
+}
+
+export function cmsEntryFieldAttr(path: string): { 'data-cms-entry-field': string } {
+  return { 'data-cms-entry-field': path };
+}

package/src/fields/collection.ts

@@ -0,0 +1,72 @@
+import { type z, zodToJsonSchema } from '@407dev/blocks';
+import { bundleReady } from '../runtime/bundle';
+import { getActiveBundle, isDraftMode } from '../runtime/store';
+import type {
+  CollectionEntry,
+  CollectionHandle,
+  CollectionStaticPath,
+  DefineCollectionOptions,
+  InferEntryContent,
+} from './types';
+
+export function defineCollection<TSchema extends z.ZodTypeAny>(
+  options: DefineCollectionOptions<TSchema>,
+): CollectionHandle<TSchema> {
+  const jsonSchema = zodToJsonSchema(options.schema);
+
+  return {
+    key: options.key,
+    schema: options.schema,
+    route: options.route,
+    presentation: options.presentation,
+    titleField: options.titleField,
+    listColumns: options.listColumns,
+    bodyField: options.bodyField,
+    orderable: options.orderable,
+    seed: options.seed,
+    jsonSchema: jsonSchema as Record<string, unknown>,
+    schemaVersion: 1,
+  };
+}
+
+export function getEntries<T extends CollectionHandle<z.ZodTypeAny> | string>(
+  handleOrKey: T,
+): Array<CollectionEntry<InferEntryContent<T>>> {
+  const collectionKey = typeof handleOrKey === 'string' ? handleOrKey : handleOrKey.key;
+  const bundle = getActiveBundle();
+  const rawEntries = bundle?.entries?.[collectionKey] || [];
+  const draft = isDraftMode();
+
+  const filtered = draft ? rawEntries : rawEntries.filter((e) => e.status === 'published');
+
+  return filtered as unknown as Array<CollectionEntry<InferEntryContent<T>>>;
+}
+
+export function getEntry<T extends CollectionHandle<z.ZodTypeAny> | string>(
+  handleOrKey: T,
+  slug: string,
+): CollectionEntry<InferEntryContent<T>> | null {
+  const entries = getEntries(handleOrKey);
+  const found = entries.find((e) => e.slug === slug);
+  return (found || null) as CollectionEntry<InferEntryContent<T>> | null;
+}
+
+export async function collectionPaths<T extends CollectionHandle<z.ZodTypeAny> | string>(
+  handleOrKey: T,
+): Promise<Array<CollectionStaticPath<InferEntryContent<T>>>> {
+  const bundle = getActiveBundle() || (await bundleReady);
+  const collectionKey = typeof handleOrKey === 'string' ? handleOrKey : handleOrKey.key;
+  const rawEntries = bundle?.entries?.[collectionKey] || [];
+
+  // Build static paths only for published entries
+  const publishedEntries = rawEntries.filter((e) => e.status === 'published');
+
+  return publishedEntries.map((entry) => ({
+    params: {
+      slug: entry.slug,
+    },
+    props: {
+      entry: entry as CollectionEntry<InferEntryContent<T>>,
+    },
+  }));
+}

package/src/fields/collections.ts

@@ -0,0 +1,35 @@
+import { z } from '@407dev/blocks';
+import { defineCollection } from './collection';
+
+export function defineEmailCampaignCollection() {
+  return defineCollection({
+    key: 'email.campaign',
+    presentation: 'form',
+    titleField: 'subject',
+    listColumns: ['preheader'],
+    bodyField: 'body',
+    schema: z.object({
+      subject: z.string(),
+      preheader: z.string().optional(),
+      body: z.any(),
+      cta: z
+        .object({
+          text: z.string(),
+          url: z.string(),
+        })
+        .optional(),
+    }),
+  });
+}
+
+export function defineSmsCampaignCollection() {
+  return defineCollection({
+    key: 'sms.campaign',
+    presentation: 'form',
+    titleField: 'name',
+    schema: z.object({
+      name: z.string(),
+      body: z.string(),
+    }),
+  });
+}

package/src/fields/entryScope.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { runWithDraftBundle } from '../runtime/store';
+import type { ContentBundle } from '../types';
+import { cmsEntryAttr, cmsEntryFieldAttr } from './attrs';
+import { createEntryScope } from './entryScope';
+
+const mockBundle: ContentBundle = {
+  bundleVersion: 1,
+  site_id: 'test-site',
+  fields: {},
+  collections: {
+    blog: {
+      presentation: 'visual',
+      orderable: false,
+      schema_version: 1,
+    },
+  },
+  entries: {
+    blog: [
+      {
+        slug: 'first-post',
+        content: {
+          title: 'First Post Title',
+          description: 'A blog post description',
+          meta: {
+            seo_title: 'SEO Title for Post',
+          },
+        },
+        status: 'published',
+      },
+    ],
+  },
+  routes: [],
+  settings: { robots: {}, default_seo: {}, sitemap: {} },
+  redirects: [],
+};
+
+describe('entryScope', () => {
+  it('returns proper attrs for entry container', () => {
+    const scope = createEntryScope('blog', 'first-post');
+    expect(scope.attrs()).toEqual({
+      'data-cms-collection': 'blog',
+      'data-cms-entry': 'first-post',
+    });
+  });
+
+  it('provides cmsEntryFieldAttr helper', () => {
+    expect(cmsEntryFieldAttr('title')).toEqual({
+      'data-cms-entry-field': 'title',
+    });
+  });
+
+  it('reads fields synchronously from draft bundle', async () => {
+    await runWithDraftBundle(mockBundle, async () => {
+      const scope = createEntryScope('blog', 'first-post');
+      expect(scope.text('title')).toBe('First Post Title');
+      expect(scope.text('description')).toBe('A blog post description');
+      expect(scope.text('meta.seo_title')).toBe('SEO Title for Post');
+      expect(scope.text('nonexistent', { defaultValue: 'Fallback' })).toBe('Fallback');
+    });
+  });
+});

package/src/fields/entryScope.ts

@@ -0,0 +1,240 @@
+import type { z } from '@407dev/blocks';
+import { getFieldType, listFieldTypes } from '@407dev/field-types';
+import {
+  createComponent,
+  markHTMLString,
+  renderTemplate,
+  spreadAttributes,
+} from 'astro/runtime/server/index.js';
+import { renderRichTextHtml } from '../richtext/render';
+import { getActiveBundle } from '../runtime/store';
+import { cmsEntryAttr } from './attrs';
+import { getPlaceholderForType } from './helpers';
+import type {
+  CollectionHandle,
+  DualCallableHelper,
+  FieldComponentProps,
+  FieldReadOptions,
+} from './types';
+
+const DEFAULT_TAGS: Record<string, string> = {
+  text: 'span',
+  number: 'span',
+  toggle: 'span',
+  select: 'span',
+  image: 'img',
+  img: 'img',
+  video: 'video',
+  vid: 'video',
+  richtext: 'div',
+  richText: 'div',
+};
+
+function getNestedValue(obj: unknown, path: string): unknown {
+  if (!obj || typeof obj !== 'object' || !path) return undefined;
+  if (path in (obj as Record<string, unknown>)) {
+    return (obj as Record<string, unknown>)[path];
+  }
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+export function createEntryDualCallableHelper<TValue = unknown, TDefault = TValue>(
+  typeId: string,
+  publicName: string,
+  collectionKey: string,
+  slug: string,
+  defaultPath = '',
+): DualCallableHelper<TValue, TDefault> {
+  const typeDef = getFieldType(typeId) || getFieldType(publicName);
+  const defaultTag =
+    DEFAULT_TAGS[typeId] || DEFAULT_TAGS[publicName] || typeDef?.renderHint?.tag || 'span';
+
+  // biome-ignore lint/suspicious/noExplicitAny: Astro runtime internal component factory
+  const componentFactory = createComponent(async ($$result: any, $$props: any, _slots: any) => {
+    const rawPath = ($$props?.k ?? $$props?.key ?? defaultPath) as string;
+    const tag = ($$props?.as || $$props?.tag || defaultTag) as string;
+    const defaultValue = $$props?.defaultValue as TDefault | undefined;
+
+    const bundle = getActiveBundle();
+    const entries = bundle?.entries?.[collectionKey] || [];
+    const entry = entries.find((e) => e.slug === slug);
+    const rawVal = entry?.content ? getNestedValue(entry.content, rawPath) : undefined;
+
+    let displayVal: unknown = rawVal;
+    if (displayVal === undefined || displayVal === null) {
+      if (defaultValue !== undefined) {
+        displayVal = defaultValue;
+      } else {
+        displayVal = getPlaceholderForType(typeId, rawPath);
+      }
+    }
+
+    const {
+      k: _k,
+      key: _key,
+      defaultValue: _def,
+      as: _as,
+      tag: _tag,
+      components: _comp,
+      ...htmlProps
+    } = ($$props || {}) as FieldComponentProps<TDefault>;
+
+    const attrs: Record<string, unknown> = {
+      ...htmlProps,
+    };
+    if (rawPath) {
+      attrs['data-cms-entry-field'] = rawPath;
+    }
+    if (!attrs['data-cms-kind']) {
+      attrs['data-cms-kind'] = typeId;
+    }
+
+    if (typeId === 'image' || publicName === 'img') {
+      if (displayVal && typeof displayVal === 'object') {
+        const asset = displayVal as {
+          url?: string;
+          alt?: string;
+          width?: number;
+          height?: number;
+        };
+        if (asset.url && !attrs.src) attrs.src = asset.url;
+        if (asset.alt && !attrs.alt) attrs.alt = asset.alt;
+        if (asset.width && !attrs.width) attrs.width = asset.width;
+        if (asset.height && !attrs.height) attrs.height = asset.height;
+      } else if (typeof displayVal === 'string' && displayVal) {
+        if (!attrs.src) attrs.src = displayVal;
+      }
+
+      return renderTemplate`<img${spreadAttributes(attrs)}>`;
+    }
+
+    if (typeId === 'video' || publicName === 'vid') {
+      if (displayVal && typeof displayVal === 'object') {
+        const asset = displayVal as {
+          url?: string;
+          poster?: string;
+          width?: number;
+          height?: number;
+        };
+        if (asset.url && !attrs.src) attrs.src = asset.url;
+        if (asset.poster && !attrs.poster) attrs.poster = asset.poster;
+        if (asset.width && !attrs.width) attrs.width = asset.width;
+        if (asset.height && !attrs.height) attrs.height = asset.height;
+      } else if (typeof displayVal === 'string' && displayVal) {
+        if (!attrs.src) attrs.src = displayVal;
+      }
+      if (attrs.controls === undefined) attrs.controls = true;
+
+      return renderTemplate`<video${spreadAttributes(attrs)}></video>`;
+    }
+
+    if (typeId === 'richtext' || publicName === 'richText') {
+      const html = renderRichTextHtml(displayVal, { components: $$props?.components });
+      return renderTemplate`<${tag}${spreadAttributes(attrs)}>${markHTMLString(html)}</${tag}>`;
+    }
+
+    return renderTemplate`<${tag}${spreadAttributes(attrs)}>${
+      displayVal !== null && displayVal !== undefined ? String(displayVal) : ''
+    }</${tag}>`;
+  });
+
+  const fn = (arg0?: unknown, ...rest: unknown[]): unknown => {
+    const isComponentCall =
+      arg0 &&
+      typeof arg0 === 'object' &&
+      'styles' in (arg0 as Record<string, unknown>) &&
+      'scripts' in (arg0 as Record<string, unknown>);
+
+    if (!isComponentCall) {
+      let rawPath = defaultPath;
+      let options: FieldReadOptions<TDefault> = {};
+
+      if (typeof arg0 === 'string') {
+        rawPath = arg0;
+        options = (rest[0] || {}) as FieldReadOptions<TDefault>;
+      } else if (arg0 && typeof arg0 === 'object') {
+        options = arg0 as FieldReadOptions<TDefault>;
+      }
+
+      const bundle = getActiveBundle();
+      const entries = bundle?.entries?.[collectionKey] || [];
+      const entry = entries.find((e) => e.slug === slug);
+      const val = entry?.content ? getNestedValue(entry.content, rawPath) : undefined;
+
+      if (val !== undefined && val !== null) {
+        return val as TValue;
+      }
+      if (options.defaultValue !== undefined) {
+        return options.defaultValue as unknown as TValue;
+      }
+      return getPlaceholderForType(typeId, rawPath) as TValue;
+    }
+
+    return componentFactory(arg0, rest[0], rest[1]);
+  };
+
+  Object.assign(fn, {
+    isAstroComponentFactory: true,
+    typeId,
+    publicName,
+    collectionKey,
+    slug,
+    defaultPath,
+  });
+
+  return fn as unknown as DualCallableHelper<TValue, TDefault>;
+}
+
+export type EntryScopeAccessor = {
+  attrs(): { 'data-cms-collection': string; 'data-cms-entry'?: string };
+  collectionKey: string;
+  slug: string;
+  text: DualCallableHelper<string>;
+  number: DualCallableHelper<number>;
+  toggle: DualCallableHelper<boolean>;
+  select: DualCallableHelper<string>;
+  img: DualCallableHelper<unknown>;
+  image: DualCallableHelper<unknown>;
+  richText: DualCallableHelper<unknown>;
+  richtext: DualCallableHelper<unknown>;
+  // biome-ignore lint/suspicious/noExplicitAny: generic index signature for arbitrary entry helpers
+  [key: string]: any;
+};
+
+export function createEntryScope(
+  handleOrKey: CollectionHandle<z.ZodTypeAny> | string,
+  slug: string,
+): EntryScopeAccessor {
+  const collectionKey = typeof handleOrKey === 'string' ? handleOrKey : handleOrKey.key;
+
+  const boundHelpers: Record<string, DualCallableHelper<unknown, unknown>> = {};
+  const types = listFieldTypes();
+
+  for (const def of types) {
+    boundHelpers[def.id] = createEntryDualCallableHelper(def.id, def.id, collectionKey, slug);
+    if (def.aliases) {
+      for (const alias of def.aliases) {
+        boundHelpers[alias] = createEntryDualCallableHelper(def.id, alias, collectionKey, slug);
+      }
+    }
+  }
+
+  const accessor = {
+    ...boundHelpers,
+    attrs: () => cmsEntryAttr(collectionKey, slug),
+    collectionKey,
+    slug,
+  };
+
+  return accessor as EntryScopeAccessor;
+}
+
+export const entryScope = createEntryScope;

package/src/fields/group.ts

@@ -0,0 +1,51 @@
+import { cmsGroupAttr } from './attrs';
+import { createDualCallableHelper } from './helpers';
+import type { BoundGroupAccessor, DualCallableHelper, GroupDefinition } from './types';
+
+export function defineGroup<TShape extends Record<string, unknown>>(
+  nameOrShape: string | TShape,
+  shapeOrUndefined?: TShape,
+): GroupDefinition<TShape> {
+  const groupName = typeof nameOrShape === 'string' ? nameOrShape : 'Group';
+  const shape = (typeof nameOrShape === 'string' ? shapeOrUndefined || {} : nameOrShape) as TShape;
+
+  const groupDef = (scopeKey: string): BoundGroupAccessor<TShape> => {
+    const accessorFn = (key: string): string => {
+      return scopeKey ? `${scopeKey}.${key}` : key;
+    };
+
+    const boundHelpers: Record<string, DualCallableHelper<unknown, unknown>> = {};
+
+    for (const [key, helperDef] of Object.entries(shape)) {
+      const helperObj = helperDef as Record<string, unknown> | undefined;
+      const typeId = (helperObj?.typeId as string) || (helperObj?.publicName as string);
+
+      if (!typeId) {
+        throw new Error(
+          `f.group('${groupName}', ...) field '${key}' must reference a field helper (e.g. f.text, f.img), got ${typeof helperDef}`,
+        );
+      }
+
+      const publicName = (helperObj?.publicName as string) || typeId;
+      boundHelpers[key] = createDualCallableHelper(typeId, publicName, scopeKey, key);
+    }
+
+    Object.assign(accessorFn, boundHelpers, {
+      attrs: (): { 'data-cms-group': string } => cmsGroupAttr(groupName, scopeKey),
+      key: (key: string): string => (scopeKey ? `${scopeKey}.${key}` : key),
+      groupName,
+      prefix: scopeKey,
+    });
+
+    return accessorFn as BoundGroupAccessor<TShape>;
+  };
+
+  Object.assign(groupDef, {
+    groupName,
+    shape,
+  });
+
+  return groupDef as unknown as GroupDefinition<TShape>;
+}
+
+export const group = defineGroup;

package/src/fields/helpers.test.ts

@@ -0,0 +1,51 @@
+import { registerFieldType } from '@407dev/field-types';
+import { describe, expect, it } from 'vitest';
+import { generateAllFieldHelpers, getPlaceholderForType } from './helpers';
+
+describe('packages/astro field helpers and recipe gate', () => {
+  it('generates all registered base types and aliases', () => {
+    const helpers = generateAllFieldHelpers();
+    expect(helpers.text).toBeDefined();
+    expect(helpers.text.typeId).toBe('text');
+    expect(helpers.img).toBeDefined();
+    expect(helpers.img.typeId).toBe('image');
+    expect(helpers.image).toBeDefined();
+    expect(helpers.image.typeId).toBe('image');
+    expect(helpers.richText).toBeDefined();
+    expect(helpers.richText.typeId).toBe('richtext');
+    expect(helpers.vid).toBeDefined();
+    expect(helpers.vid.typeId).toBe('video');
+    expect(helpers.video).toBeDefined();
+    expect(helpers.video.typeId).toBe('video');
+    expect(helpers.videoList).toBeDefined();
+    expect(helpers.videoList.typeId).toBe('media.videoList');
+    expect(helpers.streamVideo).toBeDefined();
+    expect(helpers.streamVideo.typeId).toBe('media.streamVideo');
+    expect(helpers.geoArea).toBeDefined();
+    expect(helpers.geoArea.typeId).toBe('geo.area');
+    expect(helpers.addressList).toBeDefined();
+    expect(helpers.addressList.typeId).toBe('address.list');
+  });
+
+  describe('Recipe gate: test.color automatic SDK exposure', () => {
+    it('generateAllFieldHelpers exposes testColor with typeId test.color without SDK edits', () => {
+      registerFieldType({
+        id: 'test.color',
+        aliases: ['testColor'],
+        defaultValue: '#112233',
+        constraintsSchema: {},
+        validate: () => ({ valid: true }),
+      });
+
+      const helpers = generateAllFieldHelpers();
+      expect(helpers['test.color']).toBeDefined();
+      expect(helpers['test.color'].typeId).toBe('test.color');
+
+      expect(helpers.testColor).toBeDefined();
+      expect(helpers.testColor.typeId).toBe('test.color');
+      expect(helpers.testColor.publicName).toBe('testColor');
+
+      expect(getPlaceholderForType('test.color', 'theme.color')).toBe('#112233');
+    });
+  });
+});