@acms-subir/core 0.3.3-next.20260929113209 → 0.3.3

package/src/theme-sdk/contract.mjs

@@ -1,36 +1,88 @@
 import { z } from 'zod';
 import { ThemeTokens } from './tokens.mjs';
+import { normalizeData, valueIssues, fieldVisible } from './fields.mjs';
+export * from './fields.mjs';
 export { ThemeTokens } from './tokens.mjs';
 export const THEME_API_VERSION = 1;
 export const Slug = z.string().regex(/^[a-z][a-z0-9-]{0,49}$/);
 const text = z.string().max(20000);
-export const Field = z.object({
-  label: z.string().min(1).max(100), type: z.enum(['text', 'textarea', 'image', 'url', 'select', 'number']),
-  default: z.union([text, z.number()]).optional(), options: z.array(z.string().max(100)).max(30).optional(),
+const FieldKey = z.string().regex(/^[a-zA-Z][a-zA-Z0-9]*$/);
+const Scalar = z.union([text, z.number().finite(), z.boolean()]);
+// link values and source configs: small flat objects
+const FlatObject = z.record(z.string().max(100), Scalar);
+const ListItem = z.record(z.string().max(100), z.union([Scalar, FlatObject]));
+export const FieldValue = z.union([Scalar, FlatObject, z.array(ListItem).max(100)]);
+/** show a field only when a sibling field matches: { field, equals | notEquals | in }; no operator = sibling is filled in */
+export const VisibleIf = z.object({ field: FieldKey, equals: Scalar.optional(), notEquals: Scalar.optional(), in: z.array(Scalar).max(30).optional() }).strict();
+const fieldBase = { label: z.string().min(1).max(100), help: z.string().max(300).optional(), visibleIf: VisibleIf.optional() };
+export const ScalarField = z.object({
+  ...fieldBase, type: z.enum(['text', 'textarea', 'richtext', 'image', 'url', 'link', 'select', 'number', 'toggle', 'date', 'time']), // = SCALAR_TYPES
+  default: z.union([Scalar, FlatObject]).optional(), options: z.array(z.string().max(100)).max(30).optional(),
+  placeholder: z.string().max(200).optional(),
+  required: z.boolean().optional(), maxLength: z.number().int().min(1).max(20000).optional(),
+  // AI help instruction for this field ("friendly, under 12 words"); locked = owners only
+  aiHint: z.string().max(300).optional(), locked: z.boolean().optional(),
+  // words vs facts: text/rich text/link labels translate by default; set false for
+  // e.g. a phone number, or true on a select whose options are words
+  translatable: z.boolean().optional(),
 }).strict();
+/** repeater: rows of scalar sub-fields (one level — a list can't hold a list) */
+export const ListField = z.object({
+  ...fieldBase, type: z.literal('list'), fields: z.record(FieldKey, ScalarField).refine(f => Object.keys(f).length > 0, 'A list needs at least one sub-field'),
+  itemLabel: FieldKey.optional(), min: z.number().int().min(0).max(100).optional(), max: z.number().int().min(1).max(100).default(50),
+  default: z.array(ListItem).max(100).optional(), locked: z.boolean().optional(),
+}).strict();
+/** linked data: the owner picks what to show; items resolve fresh on every request */
+export const SourceField = z.object({
+  ...fieldBase, type: z.literal('source'), source: z.enum(['events', 'posts', 'bookings']) /* = SOURCE_KINDS */, default: FlatObject.optional(), locked: z.boolean().optional(),
+}).strict();
+export const Field = z.union([ScalarField, ListField, SourceField]);
 export const SectionDefinition = z.object({
   name: z.string().min(1).max(100), version: z.number().int().positive().default(1),
   component: z.string().regex(/^sections\/[a-zA-Z0-9-]+\.astro$/).optional(),
   variants: z.array(Slug).min(1).max(20).default(['default']),
-  fields: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9]*$/), Field).default({}),
+  fields: z.record(FieldKey, Field).default({}),
+  description: z.string().max(300).optional(),
+  /** picker group: "Intro", "Events & times", "People", "Info", "Calls to action"… */
+  category: z.string().max(40).optional(),
+  /** sample content: picker previews and empty fields in the admin preview (never saved) */
+  example: z.record(FieldKey, FieldValue).optional(),
+  /** at most this many per page */
+  limit: z.number().int().min(1).max(20).optional(),
+  /** ready-filled picker entries ("Service times: holiday") */
+  presets: z.array(z.object({ name: z.string().min(1).max(100), description: z.string().max(200).optional(), variant: Slug.optional(), data: z.record(z.string().max(100), FieldValue).default({}) }).strict()).max(12).optional(),
 }).strict();
 const f = (label, type = 'text', value = '') => ({ label, type, default: value });
 const base = { heading: f('Heading'), text: f('Supporting text', 'textarea') };
+const list = (label, fields, itemLabel) => ({ label, type: 'list', fields, itemLabel, max: 50 });
 /** @type {Record<string, import("zod").infer<typeof SectionDefinition>>} */
 export const BUILTIN_SECTIONS = {
-  live: { name: 'Live video', version: 1, variants: ['card','player'], fields: {} },
-  'page-content': { name: 'Existing page content', version: 1, variants: ['default'], fields: {} },
-  hero: { name: 'Hero', version: 1, variants: ['split', 'centered'], fields: { ...base, image: f('Image', 'image'), alt: f('Image description'), label: f('Button label'), href: f('Button link', 'url') } },
-  features: { name: 'Features', version: 1, variants: ['grid', 'list'], fields: { ...base, items: f('Features (one per line: title | description)', 'textarea') } },
-  testimonials: { name: 'Testimonials', version: 1, variants: ['grid', 'list'], fields: { ...base, items: f('Quotes (one per line: name | quote)', 'textarea') } },
-  faq: { name: 'FAQ', version: 1, variants: ['default'], fields: { ...base, items: f('Questions (one per line: question | answer)', 'textarea') } },
-  posts: { name: 'Posts', version: 1, variants: ['grid', 'list'], fields: { heading: f('Heading', 'text', 'Latest posts'), collection: f('Collection', 'text', 'posts'), limit: f('Number of posts', 'number', 3) } },
-  cta: { name: 'Call to action', version: 1, variants: ['default', 'panel'], fields: { ...base, label: f('Button label'), href: f('Button link', 'url') } },
+  live: { category: 'Basic', name: 'Live video', version: 1, variants: ['card','player'], fields: {} },
+  'page-content': { category: 'Basic', name: 'Existing page content', version: 1, variants: ['default'], fields: {} },
+  hero: { category: 'Basic', example: { heading: 'A place for everyone', text: 'Say what you do in one or two sentences.', label: 'Get started', href: '#' }, name: 'Hero', version: 1, variants: ['split', 'centered'], fields: { ...base, image: f('Image', 'image'), alt: f('Image description'), label: f('Button label'), href: f('Button link', 'url') } },
+  // items were "title | text" textarea lines before core 0.4; stored strings
+  // upgrade to rows through normalizeValue, so the version stays 1
+  features: { category: 'Basic', example: { heading: 'What we offer', items: [{ title: 'First thing', text: 'A short line about it.' }, { title: 'Second thing', text: 'A short line about it.' }, { title: 'Third thing', text: 'A short line about it.' }] }, name: 'Features', version: 1, variants: ['grid', 'list'], fields: { ...base, items: list('Features', { title: f('Title'), text: f('Description', 'textarea') }, 'title') } },
+  testimonials: { category: 'Basic', example: { heading: 'What people say', items: [{ title: 'Sam', text: 'A warm, specific quote.' }, { title: 'Alex', text: 'Another kind word.' }] }, name: 'Testimonials', version: 1, variants: ['grid', 'list'], fields: { ...base, items: list('Quotes', { title: f('Name'), text: f('Quote', 'textarea') }, 'title') } },
+  faq: { category: 'Basic', example: { heading: 'Questions', items: [{ title: 'A common question?', text: 'A clear answer.' }, { title: 'Another question?', text: 'Another answer.' }] }, name: 'FAQ', version: 1, variants: ['default'], fields: { ...base, items: list('Questions', { title: f('Question'), text: f('Answer', 'textarea') }, 'title') } },
+  posts: { category: 'Basic', name: 'Posts', version: 1, variants: ['grid', 'list'], fields: { heading: f('Heading', 'text', 'Latest posts'), collection: f('Collection', 'text', 'posts'), limit: f('Number of posts', 'number', 3) } },
+  cta: { category: 'Basic', example: { heading: 'Ready when you are', text: 'One clear next step.', label: 'Get in touch', href: '#' }, name: 'Call to action', version: 1, variants: ['default', 'panel'], fields: { ...base, label: f('Button label'), href: f('Button link', 'url') } },
 };
+/** one language's words for a section: values by path + review state per path */
+export const SectionTranslation = z.object({
+  data: z.record(z.string().max(200), z.union([text, z.number().finite(), z.boolean()])).default({}),
+  meta: z.record(z.string().max(200), z.object({ state: z.enum(['ai', 'reviewed']), src: z.string().max(20) }).strict()).default({}),
+}).strict();
 export const SectionInstance = z.object({
   id: z.string().min(1).max(100), type: Slug, version: z.number().int().positive().default(1),
   variant: Slug.default('default'), hidden: z.boolean().default(false),
-  data: z.record(z.string().max(100), z.union([text, z.number().finite()])).default({}),
+  // shown only inside this window (site timezone): YYYY-MM-DD or YYYY-MM-DDTHH:MM
+  showFrom: z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})?$/).optional(), showUntil: z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})?$/).optional(),
+  // owner-locked: editors can't change or remove it
+  locked: z.boolean().optional(),
+  // per extra language: translated words only (facts stay in `data`)
+  translations: z.record(z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})?$/), SectionTranslation).optional(),
+  data: z.record(z.string().max(100), FieldValue).default({}),
 }).strict();
 export const SectionLayout = z.object({ mode: z.enum(['content', 'sections']).default('sections'), sections: z.array(SectionInstance).max(50) }).strict()
   .refine(v => new Set(v.sections.map(s => s.id)).size === v.sections.length, 'Section IDs must be unique');
@@ -48,6 +100,11 @@ export const PostOptions = z.object({
   toc: z.boolean().default(true),
 });
 
+/** starting layouts a theme offers ("Start from Church home"); the owner's copy is theirs to edit */
+export const PagePreset = z.object({
+  name: z.string().min(1).max(100), description: z.string().max(300).optional(),
+  sections: z.array(z.object({ type: Slug, variant: Slug.optional(), hidden: z.boolean().optional(), data: z.record(z.string().max(100), FieldValue).default({}) }).strict()).min(1).max(50),
+}).strict();
 export const ThemeManifest = z.object({
   name: z.string().min(1).max(120), description: z.string().max(2000).default(''), slug: Slug.optional(),
   version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/).default('1.0.0'),
@@ -57,6 +114,7 @@ export const ThemeManifest = z.object({
   templates: z.array(z.string().regex(/^(home|event|post-[a-z0-9-]+|page-[a-z0-9-]+)\.astro$/)).default([]),
   sections: z.record(Slug, SectionDefinition).default({}),
   assets: z.array(z.string().regex(/^assets\/(?!.*\.\.)[a-zA-Z0-9_./-]+$/)).default([]),
+  presets: z.record(Slug, PagePreset).default({}),
 }).strict();
 /** @param {Partial<import("zod").infer<typeof ThemeManifest>>} [manifest] */
 export function sectionDefinitions(manifest = {}) {
@@ -65,17 +123,16 @@ export function sectionDefinitions(manifest = {}) {
 /** @param {import("zod").infer<typeof SectionLayout>} layout
  * @param {Record<string, import("zod").infer<typeof SectionDefinition>>} definitions */
 export function sectionIssues(layout, definitions) {
+  const counts = {};
   return layout.sections.flatMap(s => {
     const d = definitions[s.type];
     if (!d) return [{ id: s.id, message: `Unavailable section: ${s.type}. Its data is preserved.` }];
     if (s.version !== d.version) return [{ id: s.id, message: `Section ${s.type} needs a migration from v${s.version} to v${d.version}.` }];
     if (!d.variants.includes(s.variant)) return [{ id: s.id, message: `Unsupported variant: ${s.variant}` }];
-    return Object.entries(d.fields).flatMap(([key, field]) => {
-      const value = s.data[key] ?? field.default ?? (field.type === 'number' ? 0 : '');
-      const valid = field.type === 'number' ? typeof value === 'number' && Number.isFinite(value)
-        : typeof value === 'string' && (field.type !== 'select' || field.options?.includes(value));
-      const safeLink = !['url','image'].includes(field.type) || value === '' || (typeof value === 'string' && /^(https?:\/\/|mailto:|tel:|\/(?!\/)|#)/i.test(value.trim()));
-      return valid && safeLink ? [] : [{ id: s.id, message: `Invalid ${field.label}` }];
-    });
+    counts[s.type] = (counts[s.type] ?? 0) + 1;
+    const over = d.limit && counts[s.type] > d.limit ? [{ id: s.id, message: `${d.name} can appear at most ${d.limit} ${d.limit === 1 ? 'time' : 'times'} per page.` }] : [];
+    const data = normalizeData(d, s.data);
+    return [...over, ...Object.entries(d.fields).flatMap(([key, field]) =>
+      fieldVisible(field, data) ? valueIssues(field, data[key]).map(message => ({ id: s.id, message })) : [])];
   });
 }

package/src/theme-sdk/fields.d.mts

@@ -0,0 +1,88 @@
+/** empty value for a field when neither data nor a default exists */
+export function emptyValue(field: any): false | 0 | "" | never[] | {
+    label: string;
+    href: string;
+    limit?: undefined;
+} | {
+    limit: number;
+    label?: undefined;
+    href?: undefined;
+};
+/** the field's declared default (deep-copied), or its empty value */
+export function defaultValue(field: any): any;
+/**
+ * Coerce a stored value into the field's current shape. Tolerant by design:
+ * a value saved by an older schema (e.g. the v1 built-ins' "title | text"
+ * textarea lines, now a list) upgrades instead of disappearing.
+ */
+export function normalizeValue(field: any, value: any): any;
+/** one list row: every declared sub-field present; unknown keys kept (orphans) */
+export function normalizeItem(listField: any, row: any): any;
+/** full data object for a section: declared fields normalized, unknown keys kept */
+export function normalizeData(definition: any, data?: {}): {};
+/** data for a brand-new section instance */
+export function initialData(definition: any): {};
+/** "30% 20%" (x y), clamped; anything else → centered */
+export function safeFocus(value: any): string;
+/** saved keys the current schema no longer declares (kept, never deleted silently) */
+export function orphanKeys(definition: any, data?: {}): string[];
+/** short human label for a list row, for collapsed rows in the editor */
+export function itemTitle(listField: any, row: any, index: any): string;
+/** a field's visibleIf against its siblings (section data, or a list row) */
+export function fieldVisible(field: any, siblings?: {}): any;
+/** "2026-12-01" / "2026-12-01T09:30" window check against a wall-clock "now" in the site timezone */
+export function scheduledVisible(section: any, nowWall: any): boolean;
+/** "19:00" → "7:00 PM" in the site's locale (times of day carry no zone) */
+export function formatTime(value: any, locale?: string): string;
+/** "2026-10-04" → "Oct 4, 2026" (date-only values are calendar dates, not instants) */
+export function formatDay(value: any, locale?: string, opts?: {
+    month: string;
+    day: string;
+    year: string;
+}): any;
+/**
+ * Issues for one field value (after normalization). `path` prefixes messages
+ * so list rows read "Services › Youth Night: Invalid Time".
+ */
+export function valueIssues(field: any, value: any, path?: any): string[];
+/** words, not facts: text-like fields and link labels; selects only when marked */
+export function isTranslatable(field: any): boolean;
+/** short, stable fingerprint of a source text (detects "the English changed") */
+export function textHash(value: any): string;
+/**
+ * Every translatable piece of a section's data, in order:
+ * { path, key, rowId?, sub?, field, label, kind, source, hash }
+ */
+export function translationUnits(definition: any, data?: {}): {
+    path: string;
+    key: string;
+    field: any;
+    label: any;
+    kind: any;
+    source: string;
+    hash: string;
+}[];
+/** 'missing' | 'ai' | 'reviewed' | 'outdated' for one unit */
+export function unitStatus(unit: any, translation: any): "ai" | "reviewed" | "missing" | "outdated";
+/** counts of each status for a section in one language */
+export function translationSummary(definition: any, data: any, translation: any): {
+    total: number;
+    missing: number;
+    ai: number;
+    reviewed: number;
+    outdated: number;
+};
+/** section data as seen in a language: translated words over the shared facts (field-by-field fallback) */
+export function localizeData(definition: any, data: {} | undefined, translation: any): {};
+export const SCALAR_TYPES: readonly ["text", "textarea", "richtext", "image", "url", "link", "select", "number", "toggle", "date", "time"];
+export const SOURCE_KINDS: readonly ["events", "posts", "bookings"];
+export const SOURCE_LIMIT_MAX: 24;
+export const SAFE_URL: RegExp;
+export function safeUrl(value: any): string;
+/** an image's focal point lives beside it: data["photo__focus"] = "30% 20%" */
+export const FOCUS_SUFFIX: "__focus";
+export function focusKey(key: any): string;
+export function isEmptyValue(v: any): boolean;
+export function hasSource(definition: any): boolean;
+export function newRowId(): string;
+export function rowKey(row: any, i: any): any;

package/src/theme-sdk/fields.mjs

@@ -0,0 +1,326 @@
+// Section field helpers shared by the server renderer, the validator and the
+// admin editor. Deliberately zod-free so the Design screen can import it
+// without pulling the schema library into the client bundle.
+//
+// Value shapes by field type:
+//   text | textarea | richtext | image | url | select | date | time → string
+//   number → number        toggle → boolean
+//   link   → { label, href, ref? }   (ref = 'page:<id>' | 'post:<id>' | 'event:<id>' | 'booking:<id>')
+//   list   → Array<Record<subKey, scalar | link>>
+//   source → { calendar?, collection?, tag?, resource?, limit? }  (resolved to items at render time)
+
+export const SCALAR_TYPES = /** @type {const} */ (['text', 'textarea', 'richtext', 'image', 'url', 'link', 'select', 'number', 'toggle', 'date', 'time']);
+export const SOURCE_KINDS = /** @type {const} */ (['events', 'posts', 'bookings']);
+export const SOURCE_LIMIT_MAX = 24;
+
+export const SAFE_URL = /^(https?:\/\/|mailto:|tel:|\/(?!\/)|#)/i;
+export const safeUrl = (value) => {
+  const s = String(value ?? '').trim();
+  return SAFE_URL.test(s) ? s : '';
+};
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** empty value for a field when neither data nor a default exists */
+export function emptyValue(field) {
+  switch (field.type) {
+    case 'number': return 0;
+    case 'toggle': return false;
+    case 'link': return { label: '', href: '' };
+    case 'list': return [];
+    case 'source': return { limit: 3 };
+    default: return '';
+  }
+}
+
+/** the field's declared default (deep-copied), or its empty value */
+export function defaultValue(field) {
+  if (field.default === undefined) return emptyValue(field);
+  return typeof field.default === 'object' ? structuredClone(field.default) : field.default;
+}
+
+/**
+ * Coerce a stored value into the field's current shape. Tolerant by design:
+ * a value saved by an older schema (e.g. the v1 built-ins' "title | text"
+ * textarea lines, now a list) upgrades instead of disappearing.
+ */
+export function normalizeValue(field, value) {
+  if (value === undefined || value === null) return defaultValue(field);
+  switch (field.type) {
+    case 'number': {
+      const n = typeof value === 'number' ? value : Number(value);
+      return Number.isFinite(n) ? n : defaultValue(field);
+    }
+    case 'toggle':
+      return typeof value === 'boolean' ? value : value === 'true' || value === 1 || value === '1';
+    case 'link':
+      if (isObject(value)) return { label: String(value.label ?? ''), href: String(value.href ?? ''), ...(value.ref ? { ref: String(value.ref) } : {}) };
+      return { label: '', href: String(value) };
+    case 'list': {
+      const keys = Object.keys(field.fields ?? {});
+      let rows = value;
+      if (typeof value === 'string') {
+        // legacy "a | b" lines → one item per line, cells mapped to sub-fields in order
+        rows = value.split('\n').map((l) => l.trim()).filter(Boolean).map((line) => {
+          const cells = line.split('|');
+          const item = {};
+          keys.forEach((k, i) => {
+            const cell = i === keys.length - 1 ? cells.slice(i).join('|') : cells[i];
+            if (cell !== undefined) item[k] = cell.trim();
+          });
+          return item;
+        });
+      }
+      if (!Array.isArray(rows)) return defaultValue(field);
+      return rows.filter(isObject).map((row) => normalizeItem(field, row));
+    }
+    case 'source':
+      return isObject(value) ? { ...value } : defaultValue(field);
+    default:
+      return typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' ? String(value) : defaultValue(field);
+  }
+}
+
+/** one list row: every declared sub-field present; unknown keys kept (orphans) */
+export function normalizeItem(listField, row) {
+  const out = { ...row };
+  for (const [key, sub] of Object.entries(listField.fields ?? {})) out[key] = normalizeValue(sub, row[key]);
+  return out;
+}
+
+/** full data object for a section: declared fields normalized, unknown keys kept */
+export function normalizeData(definition, data = {}) {
+  const out = { ...data };
+  for (const [key, field] of Object.entries(definition?.fields ?? {})) out[key] = normalizeValue(field, data[key]);
+  return out;
+}
+
+/** data for a brand-new section instance */
+export function initialData(definition) {
+  const out = {};
+  for (const [key, field] of Object.entries(definition?.fields ?? {})) {
+    if (field.default !== undefined || ['list', 'source', 'toggle', 'link'].includes(field.type)) out[key] = defaultValue(field);
+  }
+  return out;
+}
+
+/** an image's focal point lives beside it: data["photo__focus"] = "30% 20%" */
+export const FOCUS_SUFFIX = '__focus';
+export const focusKey = (key) => `${key}${FOCUS_SUFFIX}`;
+/** "30% 20%" (x y), clamped; anything else → centered */
+export function safeFocus(value) {
+  const m = /^(\d{1,3}(?:\.\d+)?)% (\d{1,3}(?:\.\d+)?)%$/.exec(String(value ?? '').trim());
+  if (!m) return '50% 50%';
+  const c = (n) => Math.max(0, Math.min(100, Math.round(Number(n))));
+  return `${c(m[1])}% ${c(m[2])}%`;
+}
+
+/** saved keys the current schema no longer declares (kept, never deleted silently) */
+export function orphanKeys(definition, data = {}) {
+  const declared = definition?.fields ?? {};
+  return Object.keys(data).filter((k) => !(k in declared) && !(k.endsWith(FOCUS_SUFFIX) && declared[k.slice(0, -FOCUS_SUFFIX.length)]?.type === 'image'));
+}
+
+/** short human label for a list row, for collapsed rows in the editor */
+export function itemTitle(listField, row, index) {
+  const keys = Object.keys(listField.fields ?? {});
+  const key = listField.itemLabel && keys.includes(listField.itemLabel) ? listField.itemLabel : keys.find((k) => ['text', 'select'].includes(listField.fields[k].type)) ?? keys[0];
+  const v = key ? row?.[key] : '';
+  const text = isObject(v) ? v.label : v;
+  return String(text ?? '').trim() || `Item ${index + 1}`;
+}
+
+/** a field's visibleIf against its siblings (section data, or a list row) */
+export function fieldVisible(field, siblings = {}) {
+  const c = field?.visibleIf;
+  if (!c) return true;
+  const raw = siblings?.[c.field];
+  const v = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw.href ?? raw.label ?? '' : raw;
+  if (c.equals !== undefined) return v === c.equals;
+  if (c.notEquals !== undefined) return v !== c.notEquals;
+  if (c.in) return c.in.includes(v);
+  return Array.isArray(v) ? v.length > 0 : v !== undefined && v !== '' && v !== false && v !== null;
+}
+
+/** is a (normalized) value empty? */
+export const isEmptyValue = (v) => v === '' || v === undefined || v === null || (Array.isArray(v) && v.length === 0) ||
+  (typeof v === 'object' && !Array.isArray(v) && 'href' in v && !String(v.href ?? '').trim() && !String(v.label ?? '').trim());
+
+/** "2026-12-01" / "2026-12-01T09:30" window check against a wall-clock "now" in the site timezone */
+export function scheduledVisible(section, nowWall) {
+  const day = nowWall.slice(0, 10);
+  if (section.showFrom && (section.showFrom.length === 10 ? day < section.showFrom : nowWall < section.showFrom)) return false;
+  if (section.showUntil && (section.showUntil.length === 10 ? day > section.showUntil : nowWall >= section.showUntil)) return false;
+  return true;
+}
+
+/** true when a section uses linked data (a source field) */
+export const hasSource = (definition) => Object.values(definition?.fields ?? {}).some((f) => f.type === 'source');
+
+/** "19:00" → "7:00 PM" in the site's locale (times of day carry no zone) */
+export function formatTime(value, locale = 'en-US') {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(value ?? '').trim());
+  if (!m) return String(value ?? '');
+  const d = new Date(Date.UTC(2000, 0, 1, Number(m[1]), Number(m[2])));
+  try { return new Intl.DateTimeFormat(locale, { hour: 'numeric', minute: '2-digit', timeZone: 'UTC' }).format(d); }
+  catch { return `${m[1]}:${m[2]}`; }
+}
+
+/** "2026-10-04" → "Oct 4, 2026" (date-only values are calendar dates, not instants) */
+export function formatDay(value, locale = 'en-US', opts = { month: 'short', day: 'numeric', year: 'numeric' }) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value ?? '').trim());
+  if (!m) return String(value ?? '');
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+  try { return new Intl.DateTimeFormat(locale, { ...opts, timeZone: 'UTC' }).format(d); }
+  catch { return value; }
+}
+
+/**
+ * Issues for one field value (after normalization). `path` prefixes messages
+ * so list rows read "Services › Youth Night: Invalid Time".
+ */
+export function valueIssues(field, value, path = field.label) {
+  const bad = (what = `Invalid ${field.label}`) => [path === field.label ? what : `${path}: ${what}`];
+  if (field.required && isEmptyValue(value)) return bad(`${field.label} is required`);
+  if (field.maxLength && typeof value === 'string' && (field.type === 'richtext' ? value.replace(/<[^>]+>/g, '') : value).length > field.maxLength) return bad(`${field.label} is over ${field.maxLength} characters`);
+  switch (field.type) {
+    case 'number': return typeof value === 'number' && Number.isFinite(value) ? [] : bad();
+    case 'toggle': return typeof value === 'boolean' ? [] : bad();
+    case 'select': return typeof value === 'string' && (value === '' || field.options?.includes(value)) ? [] : bad();
+    case 'url': case 'image': return typeof value === 'string' && (value === '' || SAFE_URL.test(value.trim())) ? [] : bad(`${field.label} must be an http(s) or site-relative link`);
+    case 'date': return typeof value === 'string' && (value === '' || /^\d{4}-\d{2}-\d{2}$/.test(value)) ? [] : bad(`${field.label} must be a date (YYYY-MM-DD)`);
+    case 'time': return typeof value === 'string' && (value === '' || /^([01]?\d|2[0-3]):[0-5]\d$/.test(value)) ? [] : bad(`${field.label} must be a time (HH:MM)`);
+    case 'link': {
+      if (!isObject(value)) return bad();
+      const href = String(value.href ?? '').trim();
+      if (href && !SAFE_URL.test(href)) return bad(`${field.label} must be an http(s) or site-relative link`);
+      if (value.ref !== undefined && !/^(page|post|event|booking):[A-Za-z0-9_-]{1,100}$/.test(String(value.ref))) return bad();
+      return [];
+    }
+    case 'list': {
+      if (!Array.isArray(value)) return bad();
+      const out = [];
+      if (field.min && value.length < field.min) out.push(...bad(`${field.label} needs at least ${field.min}`));
+      if (value.length > (field.max ?? 50)) out.push(...bad(`${field.label} allows at most ${field.max ?? 50}`));
+      value.forEach((row, i) => {
+        for (const [key, sub] of Object.entries(field.fields ?? {})) {
+          if (!fieldVisible(sub, row)) continue;
+          out.push(...valueIssues(sub, normalizeValue(sub, row?.[key]), `${field.label} › ${itemTitle(field, row, i)}`));
+        }
+      });
+      return out;
+    }
+    case 'source': {
+      if (!isObject(value)) return bad();
+      const limit = value.limit ?? 3;
+      if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > SOURCE_LIMIT_MAX) return bad(`${field.label}: show between 1 and ${SOURCE_LIMIT_MAX}`);
+      for (const k of ['calendar', 'collection', 'tag', 'resource']) {
+        if (value[k] !== undefined && (typeof value[k] !== 'string' || !/^[a-z0-9-]{0,100}$/i.test(value[k]))) return bad();
+      }
+      return [];
+    }
+    default: return typeof value === 'string' ? [] : bad();
+  }
+}
+
+// ---- translations ---------------------------------------------------------
+// A section keeps one set of data (facts shared by every language) plus, per
+// extra language, only the translated words:
+//   translations: { es: { data: { heading: '…', 'services.r4k2.note': '…', cta: 'Planea tu visita' },
+//                          meta: { heading: { state: 'ai' | 'reviewed', src: '<hash of the English>' } } } }
+// Paths: top-level keys; list rows as `<list>.<rowId>.<sub>` (rowId = row._id,
+// or `#<index>` for rows saved before ids existed); link fields translate
+// their label only.
+
+/** words, not facts: text-like fields and link labels; selects only when marked */
+export function isTranslatable(field) {
+  if (!field || field.translatable === false) return false;
+  if (['text', 'textarea', 'richtext', 'link'].includes(field.type)) return true;
+  return field.type === 'select' && field.translatable === true;
+}
+
+/** short, stable fingerprint of a source text (detects "the English changed") */
+export function textHash(value) {
+  let h = 5381;
+  const s = String(value ?? '');
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+/** a new list-row id */
+export const newRowId = () => Math.random().toString(36).slice(2, 8);
+export const rowKey = (row, i) => (row && typeof row._id === 'string' && row._id ? row._id : `#${i}`);
+
+const sourceText = (field, value) => (field.type === 'link' ? String(value?.label ?? '') : String(value ?? ''));
+
+/**
+ * Every translatable piece of a section's data, in order:
+ * { path, key, rowId?, sub?, field, label, kind, source, hash }
+ */
+export function translationUnits(definition, data = {}) {
+  const out = [];
+  const d = normalizeData(definition, data);
+  for (const [key, field] of Object.entries(definition?.fields ?? {})) {
+    if (!fieldVisible(field, d)) continue;
+    if (field.type === 'list') {
+      (d[key] ?? []).forEach((row, i) => {
+        const rid = rowKey(row, i);
+        for (const [sub, sf] of Object.entries(field.fields ?? {})) {
+          if (!isTranslatable(sf) || !fieldVisible(sf, row)) continue;
+          const source = sourceText(sf, row[sub]);
+          if (!source.trim()) continue;
+          out.push({ path: `${key}.${rid}.${sub}`, key, rowId: rid, sub, field: sf, label: `${field.label} › ${itemTitle(field, row, i)} › ${sf.label}`, kind: sf.type, source, hash: textHash(source) });
+        }
+      });
+      continue;
+    }
+    if (!isTranslatable(field)) continue;
+    const source = sourceText(field, d[key]);
+    if (!source.trim()) continue;
+    out.push({ path: key, key, field, label: field.label, kind: field.type, source, hash: textHash(source) });
+  }
+  return out;
+}
+
+/** 'missing' | 'ai' | 'reviewed' | 'outdated' for one unit */
+export function unitStatus(unit, translation) {
+  const value = translation?.data?.[unit.path];
+  if (value === undefined || String(value).trim() === '') return 'missing';
+  const meta = translation?.meta?.[unit.path];
+  if (meta && meta.src !== unit.hash) return 'outdated';
+  return meta?.state === 'reviewed' ? 'reviewed' : 'ai';
+}
+
+/** counts of each status for a section in one language */
+export function translationSummary(definition, data, translation) {
+  const counts = { total: 0, missing: 0, ai: 0, reviewed: 0, outdated: 0 };
+  for (const u of translationUnits(definition, data)) { counts.total++; counts[unitStatus(u, translation)]++; }
+  return counts;
+}
+
+/** section data as seen in a language: translated words over the shared facts (field-by-field fallback) */
+export function localizeData(definition, data = {}, translation) {
+  if (!translation?.data || !Object.keys(translation.data).length) return data;
+  const out = structuredClone(data);
+  for (const [key, field] of Object.entries(definition?.fields ?? {})) {
+    if (field.type === 'list') {
+      if (!Array.isArray(out[key])) continue;
+      out[key] = out[key].map((row, i) => {
+        if (!row || typeof row !== 'object') return row;
+        const rid = rowKey(row, i);
+        const next = { ...row };
+        for (const [sub, sf] of Object.entries(field.fields ?? {})) {
+          const t = translation.data[`${key}.${rid}.${sub}`];
+          if (!isTranslatable(sf) || t === undefined || String(t).trim() === '') continue;
+          next[sub] = sf.type === 'link' ? { ...normalizeValue(sf, row[sub]), label: String(t) } : t;
+        }
+        return next;
+      });
+      continue;
+    }
+    const t = translation.data[key];
+    if (!isTranslatable(field) || t === undefined || String(t).trim() === '') continue;
+    out[key] = field.type === 'link' ? { ...normalizeValue(field, out[key]), label: String(t) } : t;
+  }
+  return out;
+}

package/src/theme-sdk/index.ts

@@ -1,4 +1,5 @@
-export { ThemeTokens, ThemeManifest, PostOptions, SectionDefinition, SectionInstance, SectionLayout, SectionPages, BUILTIN_SECTIONS, sectionDefinitions, sectionIssues, THEME_API_VERSION } from './contract.mjs';
+export { ThemeTokens, ThemeManifest, PostOptions, SectionDefinition, SectionInstance, SectionLayout, SectionPages, PagePreset, BUILTIN_SECTIONS, sectionDefinitions, sectionIssues, THEME_API_VERSION } from './contract.mjs';
+export { formatTime, formatDay } from './fields.mjs';
 export { CONTENT, postsIndexUrl, postUrl, tagUrl, collectionUrl } from '../lib/content';
 export { formatDate } from '../lib/dates';
 export type { Page, Post, Settings, Tag, CalEvent, Calendar, User } from '../lib/schema';
@@ -8,7 +9,14 @@ export interface PageProps { settings: Settings; page: Page; html: string }
 export interface PostProps { settings: Settings; post: Post; html: string; authors: User[]; related: Post[] }
 import type { Occurrence } from '../lib/calendar/events';
 export interface EventProps { settings: Settings; event: CalEvent; html: string; calendars: Calendar[]; origin: string; occurrence: Occurrence; upcoming: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>[]; preview?: boolean; rsvp?: {going:number;left:number|null;maxSeats:number;error:string;open:boolean}|null }
-export interface SectionProps { data: Record<string, string | number>; variant: string; settings: Settings; page: Page }
+/**
+ * Props for a coded section. `data` holds resolved values: link fields arrive
+ * as LinkValue, lists as row arrays, source fields as fresh item arrays
+ * (EventItem / PostItem / BookingItem), richtext as sanitized HTML.
+ * `acms theme types <slug>` writes a typed Data interface per section.
+ */
+export interface SectionProps<D = Record<string, unknown>> { data: D; variant: string; settings: Settings; page: Page }
+export type { LinkValue, EventItem, PostItem, BookingItem } from '../lib/sections';
 
 export { slugify, authorSlug } from '../lib/schema';