@407dev/cms-astro 0.1.0

package/src/fields/helpers.ts

@@ -0,0 +1,214 @@
+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, recordMissingField } from '../runtime/store';
+import type {
+  DualCallableHelper,
+  FieldComponentProps,
+  FieldHelpersMap,
+  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',
+};
+
+export function getPlaceholderForType(typeId: string, fullKey: string): unknown {
+  const isDev = typeof process !== 'undefined' && process.env?.NODE_ENV === 'development';
+  if (isDev) {
+    return `[${fullKey}]`;
+  }
+  const typeDef = getFieldType(typeId);
+  if (typeDef && typeDef.defaultValue !== undefined) {
+    return typeDef.defaultValue;
+  }
+  switch (typeId) {
+    case 'number':
+      return 0;
+    case 'toggle':
+      return false;
+    case 'image':
+    case 'video':
+      return null;
+    case 'richtext':
+      return null;
+    default:
+      return '';
+  }
+}
+
+export function createDualCallableHelper<TValue = unknown, TDefault = TValue>(
+  typeId: string,
+  publicName: string,
+  prefix = '',
+  defaultKey = '',
+): 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 rawKey = ($$props?.k ?? $$props?.key ?? defaultKey) as string;
+    const fullKey = prefix ? (rawKey ? `${prefix}.${rawKey}` : prefix) : rawKey;
+    const tag = ($$props?.as || $$props?.tag || defaultTag) as string;
+    const defaultValue = $$props?.defaultValue as TDefault | undefined;
+
+    const bundle = getActiveBundle();
+    const rawVal = fullKey ? bundle?.fields?.[fullKey] : undefined;
+
+    let displayVal: unknown = rawVal;
+    if (displayVal === undefined || displayVal === null) {
+      if (defaultValue !== undefined) {
+        displayVal = defaultValue;
+      } else {
+        if (fullKey) {
+          recordMissingField(fullKey);
+        }
+        displayVal = getPlaceholderForType(typeId, fullKey);
+      }
+    }
+
+    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 (fullKey) {
+      attrs['data-cms-field'] = fullKey;
+    }
+    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) {
+      // Synchronous read call: f.text('key', opts) or hero.heading(opts)
+      let rawKey = defaultKey;
+      let options: FieldReadOptions<TDefault> = {};
+
+      if (typeof arg0 === 'string') {
+        rawKey = arg0;
+        options = (rest[0] || {}) as FieldReadOptions<TDefault>;
+      } else if (arg0 && typeof arg0 === 'object') {
+        options = arg0 as FieldReadOptions<TDefault>;
+      }
+
+      const fullKey = prefix ? (rawKey ? `${prefix}.${rawKey}` : prefix) : rawKey;
+      const bundle = getActiveBundle();
+      const val = fullKey ? bundle?.fields?.[fullKey] : undefined;
+
+      if (val !== undefined && val !== null) {
+        return val as TValue;
+      }
+      if (options.defaultValue !== undefined) {
+        return options.defaultValue as unknown as TValue;
+      }
+      if (fullKey) {
+        recordMissingField(fullKey);
+      }
+      return getPlaceholderForType(typeId, fullKey) as TValue;
+    }
+
+    // Astro component execution: ($$result, $$props, $$slots)
+    return componentFactory(arg0, rest[0], rest[1]);
+  };
+
+  Object.assign(fn, {
+    isAstroComponentFactory: true,
+    typeId,
+    publicName,
+    prefix,
+    defaultKey,
+  });
+
+  return fn as unknown as DualCallableHelper<TValue, TDefault>;
+}
+
+export function generateAllFieldHelpers(prefix = ''): FieldHelpersMap {
+  const helpers: Record<string, DualCallableHelper<unknown, unknown>> = {};
+  const types = listFieldTypes();
+
+  for (const def of types) {
+    helpers[def.id] = createDualCallableHelper(def.id, def.id, prefix);
+    if (def.aliases) {
+      for (const alias of def.aliases) {
+        helpers[alias] = createDualCallableHelper(def.id, alias, prefix);
+      }
+    }
+  }
+
+  return helpers as unknown as FieldHelpersMap;
+}
+
+export const createFieldHelpersMap = generateAllFieldHelpers;

package/src/fields/index.ts

@@ -0,0 +1,46 @@
+import { collectionPaths, defineCollection, getEntries, getEntry } from './collection';
+import { createEntryScope, entryScope } from './entryScope';
+import { defineGroup } from './group';
+import { createFieldHelpersMap } from './helpers';
+import { createScope } from './scope';
+import type { FieldHelpersMap } from './types';
+
+const baseHelpers = createFieldHelpersMap('');
+
+export type CmsF = FieldHelpersMap & {
+  scope: typeof createScope;
+  entryScope: typeof createEntryScope;
+  group: typeof defineGroup;
+  entries: typeof getEntries;
+  entry: typeof getEntry;
+  defineCollection: typeof defineCollection;
+  collectionPaths: typeof collectionPaths;
+};
+
+export const f: CmsF = {
+  ...baseHelpers,
+  scope: createScope,
+  entryScope: createEntryScope,
+  group: defineGroup,
+  entries: getEntries,
+  entry: getEntry,
+  defineCollection,
+  collectionPaths,
+};
+
+export {
+  defineCollection,
+  collectionPaths,
+  getEntries,
+  getEntry,
+  defineGroup,
+  createScope,
+  createEntryScope,
+  entryScope,
+};
+
+export { z } from '@407dev/blocks';
+
+export * from './attrs';
+export * from './entryScope';
+export * from './types';

package/src/fields/scope.ts

@@ -0,0 +1,21 @@
+import { generateAllFieldHelpers } from './helpers';
+import type { FieldScope } from './types';
+
+export function createScope(prefix = ''): FieldScope {
+  const helpers = generateAllFieldHelpers(prefix);
+
+  const scopeFn = (key: string): string => {
+    return prefix ? `${prefix}.${key}` : key;
+  };
+
+  Object.assign(scopeFn, helpers, {
+    key: (key: string): string => (prefix ? `${prefix}.${key}` : key),
+    scope: (subPrefix: string): FieldScope => {
+      const nextPrefix = prefix ? `${prefix}.${subPrefix}` : subPrefix;
+      return createScope(nextPrefix);
+    },
+    prefix,
+  });
+
+  return scopeFn as unknown as FieldScope;
+}

package/src/fields/types.ts

@@ -0,0 +1,119 @@
+import type { CmsAsset, z } from '@407dev/blocks';
+
+export interface FieldReadOptions<T = unknown> {
+  defaultValue?: T;
+}
+
+export interface FieldComponentProps<T = unknown> {
+  k?: string;
+  key?: string;
+  defaultValue?: T;
+  as?: string;
+  tag?: string;
+  class?: string;
+  [key: string]: unknown;
+}
+
+export interface DualCallableHelper<TValue = unknown, TDefault = TValue> {
+  /** Synchronous read call: f.text('home.hero.heading', { defaultValue: '...' }) or group.field() */
+  (key?: string, options?: FieldReadOptions<TDefault>): TValue;
+  (options?: FieldReadOptions<TDefault>): TValue;
+  /** JSX / Astro template component call: <f.text k="home.hero.heading" /> */
+  (props?: FieldComponentProps<TDefault>): unknown;
+  /** Astro component factory call: ($$result, $$props, $$slots) */
+  (result: unknown, props: FieldComponentProps<TDefault>, slots?: unknown): unknown;
+  isAstroComponentFactory: true;
+  typeId: string;
+  publicName: string;
+  prefix?: string;
+  defaultKey?: string;
+}
+
+export interface FieldHelpersMap {
+  text: DualCallableHelper<string>;
+  number: DualCallableHelper<number>;
+  toggle: DualCallableHelper<boolean>;
+  select: DualCallableHelper<string>;
+  img: DualCallableHelper<CmsAsset | string>;
+  image: DualCallableHelper<CmsAsset | string>;
+  vid: DualCallableHelper<CmsAsset | string>;
+  video: DualCallableHelper<CmsAsset | string>;
+  richText: DualCallableHelper<unknown>;
+  richtext: DualCallableHelper<unknown>;
+  // biome-ignore lint/suspicious/noExplicitAny: generic index signature for arbitrary field types
+  [key: string]: any;
+}
+
+export type FieldScope = FieldHelpersMap & {
+  (key: string): string;
+  key(key: string): string;
+  scope(subPrefix: string): FieldScope;
+  readonly prefix: string;
+};
+
+export interface GroupAccessor<TShape = Record<string, unknown>> {
+  attrs(): { 'data-cms-group': string };
+  key(key: string): string;
+  (key: string): string;
+  readonly groupName: string;
+  readonly prefix: string;
+}
+
+export type BoundGroupAccessor<TShape> = GroupAccessor<TShape> & {
+  [K in keyof TShape]: TShape[K] extends DualCallableHelper<infer TVal, infer TDef>
+    ? DualCallableHelper<TVal, TDef>
+    : DualCallableHelper<unknown>;
+};
+
+export interface GroupDefinition<TShape = Record<string, unknown>> {
+  (scopeKey: string): BoundGroupAccessor<TShape>;
+  readonly groupName: string;
+  readonly shape: TShape;
+}
+
+export interface DefineCollectionOptions<TSchema extends z.ZodTypeAny> {
+  key: string;
+  schema: TSchema;
+  route?: string;
+  presentation?: 'visual' | 'form';
+  titleField?: string;
+  listColumns?: string[];
+  bodyField?: string;
+  orderable?: boolean;
+  seed?: Array<{ slug: string; content: z.input<TSchema> }>;
+}
+
+export interface CollectionHandle<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+  readonly key: string;
+  readonly schema: TSchema;
+  readonly route?: string;
+  readonly presentation?: 'visual' | 'form';
+  readonly titleField?: string;
+  readonly listColumns?: string[];
+  readonly bodyField?: string;
+  readonly orderable?: boolean;
+  readonly jsonSchema: Record<string, unknown>;
+  readonly schemaVersion: number;
+  readonly seed?: Array<{ slug: string; content: z.input<TSchema> }>;
+}
+
+export interface CollectionEntry<TContent = Record<string, unknown>> {
+  slug: string;
+  content: TContent;
+  status: 'draft' | 'published' | 'scheduled';
+  published_at?: string | null;
+  position?: string | null;
+}
+
+export type InferEntryContent<T> = T extends CollectionHandle<infer TSchema>
+  ? z.infer<TSchema>
+  : Record<string, unknown>;
+
+export interface CollectionStaticPath<TContent = Record<string, unknown>> {
+  params: {
+    slug: string;
+  };
+  props: {
+    entry: CollectionEntry<TContent>;
+  };
+}

package/src/head.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { type HeadRouteInput, buildHeadTags } from './head';
+import type { CmsSiteConfig } from './types';
+
+describe('buildHeadTags', () => {
+  const mockSiteConfig: CmsSiteConfig = {
+    site_id: 'site-1',
+    redirects: [],
+    robots: {},
+    default_seo: {
+      title: 'Default Site Title',
+      description: 'Default site description',
+      canonical: 'https://example.com/fallback',
+      og_image: 'https://example.com/default-og.jpg',
+      twitter_card: 'summary',
+    },
+    sitemap: {},
+  };
+
+  const mockRoute: HeadRouteInput = {
+    path: '/about',
+    title: 'About Route',
+    seo: {
+      title: 'About Us | Custom Title',
+      description: 'Custom route description',
+      noindex: true,
+      og_image: {
+        id: 'asset-1',
+        url: 'https://example.com/custom-og.jpg',
+        alt: 'Custom OG',
+        focal_x: 0.5,
+        focal_y: 0.5,
+        mime_type: 'image/jpeg',
+        filename: 'custom.jpg',
+      },
+    },
+  };
+
+  it('merges default SEO under route SEO overrides', () => {
+    const tags = buildHeadTags(mockRoute, mockSiteConfig, { siteUrl: 'https://example.com' });
+
+    const titleTag = tags.find((t) => t.tag === 'title');
+    expect(titleTag?.content).toBe('About Us | Custom Title');
+
+    const descTag = tags.find((t) => t.attrs?.name === 'description');
+    expect(descTag?.attrs?.content).toBe('Custom route description');
+
+    const canonicalTag = tags.find((t) => t.tag === 'link' && t.attrs?.rel === 'canonical');
+    expect(canonicalTag?.attrs?.href).toBe('https://example.com/fallback');
+
+    const robotsTag = tags.find((t) => t.attrs?.name === 'robots');
+    expect(robotsTag?.attrs?.content).toBe('noindex, nofollow');
+
+    const ogImageTag = tags.find((t) => t.attrs?.property === 'og:image');
+    expect(ogImageTag?.attrs?.content).toBe('https://example.com/custom-og.jpg');
+
+    const twitterTag = tags.find((t) => t.attrs?.name === 'twitter:card');
+    expect(twitterTag?.attrs?.content).toBe('summary');
+  });
+
+  it('falls back to site defaults and generates canonical url from route path', () => {
+    const minimalRoute: HeadRouteInput = {
+      path: '/pricing',
+    };
+
+    const tags = buildHeadTags(minimalRoute, mockSiteConfig, { siteUrl: 'https://example.com' });
+
+    const titleTag = tags.find((t) => t.tag === 'title');
+    expect(titleTag?.content).toBe('Default Site Title');
+
+    const canonicalTag = tags.find((t) => t.tag === 'link' && t.attrs?.rel === 'canonical');
+    expect(canonicalTag?.attrs?.href).toBe('https://example.com/fallback');
+  });
+});

package/src/head.ts

@@ -0,0 +1,123 @@
+import type { CmsAsset } from '@407dev/blocks';
+import type { CmsSiteConfig, RouteSeo } from './types';
+
+export interface HeadTag {
+  tag: 'title' | 'meta' | 'link';
+  attrs?: Record<string, string>;
+  content?: string;
+}
+
+export interface BuildHeadTagsOptions {
+  siteUrl?: string;
+}
+
+export interface HeadRouteInput {
+  path?: string;
+  pattern?: string;
+  title?: string;
+  seo?: RouteSeo;
+  [key: string]: unknown;
+}
+
+/**
+ * Pure function building an array of head tag descriptors from route and site config.
+ * Merges site_settings.default_seo underneath routes.seo overrides.
+ */
+export function buildHeadTags(
+  route?: HeadRouteInput | null,
+  siteConfig?: CmsSiteConfig | null,
+  options?: BuildHeadTagsOptions,
+): HeadTag[] {
+  const tags: HeadTag[] = [];
+  const defaultSeo: RouteSeo = siteConfig?.default_seo || {};
+  const routeSeo: RouteSeo = (route?.seo || {}) as RouteSeo;
+
+  // Title
+  const title = routeSeo.title || defaultSeo.title || route?.title || '';
+  if (title) {
+    tags.push({ tag: 'title', content: title });
+  }
+
+  // Description
+  const description = routeSeo.description || defaultSeo.description;
+  if (description) {
+    tags.push({
+      tag: 'meta',
+      attrs: { name: 'description', content: description },
+    });
+  }
+
+  // Canonical URL
+  const siteUrl = options?.siteUrl ? options.siteUrl.replace(/\/+$/, '') : '';
+  let canonical = routeSeo.canonical || defaultSeo.canonical;
+  if (!canonical && siteUrl && route?.path) {
+    const normPath =
+      route.path === '/' ? '' : route.path.startsWith('/') ? route.path : `/${route.path}`;
+    canonical = `${siteUrl}${normPath}`;
+  }
+  if (canonical) {
+    tags.push({
+      tag: 'link',
+      attrs: { rel: 'canonical', href: canonical },
+    });
+  }
+
+  // Robots Noindex
+  if (routeSeo.noindex || defaultSeo.noindex) {
+    tags.push({
+      tag: 'meta',
+      attrs: { name: 'robots', content: 'noindex, nofollow' },
+    });
+  }
+
+  // Open Graph
+  const ogTitle =
+    routeSeo.og_title || routeSeo.title || defaultSeo.og_title || defaultSeo.title || route?.title;
+  if (ogTitle) {
+    tags.push({
+      tag: 'meta',
+      attrs: { property: 'og:title', content: ogTitle },
+    });
+  }
+
+  const ogDescription =
+    routeSeo.og_description ||
+    routeSeo.description ||
+    defaultSeo.og_description ||
+    defaultSeo.description;
+  if (ogDescription) {
+    tags.push({
+      tag: 'meta',
+      attrs: { property: 'og:description', content: ogDescription },
+    });
+  }
+
+  const rawOgImage = routeSeo.og_image || defaultSeo.og_image;
+  const ogImageUrl =
+    typeof rawOgImage === 'object' && rawOgImage !== null && 'url' in rawOgImage
+      ? (rawOgImage as CmsAsset).url
+      : (rawOgImage as string | undefined);
+
+  if (ogImageUrl) {
+    tags.push({
+      tag: 'meta',
+      attrs: { property: 'og:image', content: ogImageUrl },
+    });
+  }
+
+  if (canonical) {
+    tags.push({
+      tag: 'meta',
+      attrs: { property: 'og:url', content: canonical },
+    });
+  }
+
+  // Twitter
+  const twitterCard = routeSeo.twitter_card || defaultSeo.twitter_card || 'summary_large_image';
+  tags.push({
+    tag: 'meta',
+    attrs: { name: 'twitter:card', content: twitterCard },
+  });
+
+  return tags;
+}

package/src/image.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { buildCdnImageUrl, buildSrcSet, isCdnTransformableUrl } from './image';
+
+describe('image helpers', () => {
+  it('identifies transformable URLs vs local/r2 URLs', () => {
+    expect(isCdnTransformableUrl('https://assets.mybrand.com/photo.jpg')).toBe(true);
+    expect(isCdnTransformableUrl('http://mybrand.com/img.png')).toBe(true);
+    expect(isCdnTransformableUrl('http://localhost:8787/assets/files/img.png')).toBe(false);
+    expect(isCdnTransformableUrl('https://pub-123.r2.dev/img.png')).toBe(false);
+    expect(isCdnTransformableUrl('data:image/png;base64,123')).toBe(false);
+    expect(isCdnTransformableUrl('')).toBe(false);
+  });
+
+  it('builds CDN image URL with formatting options', () => {
+    const url = 'https://assets.mybrand.com/photo.jpg';
+    const cdnUrl = buildCdnImageUrl(url, { width: 800, fit: 'cover', quality: 85 });
+    expect(cdnUrl).toBe(
+      '/cdn-cgi/image/width=800,format=auto,fit=cover,quality=85/https://assets.mybrand.com/photo.jpg',
+    );
+  });
+
+  it('degrades to raw URL for local / non-zone hostnames', () => {
+    const localUrl = 'http://localhost:8787/assets/files/test.png';
+    expect(buildCdnImageUrl(localUrl, { width: 600 })).toBe(localUrl);
+
+    const r2DevUrl = 'https://pub-123.r2.dev/test.png';
+    expect(buildCdnImageUrl(r2DevUrl, { width: 600 })).toBe(r2DevUrl);
+  });
+
+  it('builds responsive srcset strings', () => {
+    const url = 'https://assets.mybrand.com/photo.jpg';
+    const srcset = buildSrcSet(url, [400, 800]);
+    expect(srcset).toBe(
+      '/cdn-cgi/image/width=400,format=auto/https://assets.mybrand.com/photo.jpg 400w, /cdn-cgi/image/width=800,format=auto/https://assets.mybrand.com/photo.jpg 800w',
+    );
+  });
+
+  it('returns empty srcset for non-transformable URLs', () => {
+    const localUrl = 'http://localhost:8787/photo.jpg';
+    expect(buildSrcSet(localUrl)).toBe('');
+  });
+});