@saena-io/content 0.1.0

package/src/field/builtins.ts

@@ -0,0 +1,524 @@
+import type { AssetRef } from '@saena-io/plugin-sdk';
+import { z } from 'zod';
+import type { InferValue } from './infer';
+import { fieldType, registerFieldType } from './registry';
+import type { FieldDecl, FieldType, TypedDecl } from './types';
+
+// The built-in field types + the authoring helpers that produce typed declarations. Each built-in is ONE
+// mechanism with custom types: the form engine renders `getEditor(id)` for every field, built-ins ship that
+// editor, custom types register their own. This module owns the React-free behaviour (empty/validate/leaves/
+// hydrate); the React editors live in ../admin. Importing this module registers the built-ins.
+//
+// Storage vs config: text/richtext leaves are TRANSLATABLE — their source text is synced to i18n and stripped
+// from the persisted config by the service; on read, `hydrate` resolves them via `ctx.text(path)`, never from
+// storage. Everything else (numbers, hrefs, discriminants, refs) is CONFIG — persisted in the JSON blob.
+
+/** A lighter slugify for live typing — keeps repeated/trailing hyphens so word boundaries stay typeable. */
+export function softSlugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+}
+/** Normalise to a URL slug: lowercase, separators → hyphens, strip the rest, collapse + trim hyphens. */
+export function slugify(input: string): string {
+  return softSlugify(input)
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// Leaf types
+// ---------------------------------------------------------------------------------------------------------
+
+const textType: FieldType<string, string> = {
+  id: 'text',
+  kind: 'leaf',
+  empty: () => '',
+  validate: (_d, raw) => (raw == null ? '' : z.string().parse(raw)),
+  leaves: (_d, s, path) => [{ path, sourceText: s ?? '', format: 'plain' }],
+  hydrate: (_d, _s, ctx, path) => ctx.text(path),
+  toConfig: () => '',
+  fill: (_d, _s, ctx, path) => ctx.text(path),
+};
+
+// Rich text storage is the serialized Slate-JSON string (the @saena-io/ui codec's shape); the field core keeps it
+// opaque so it stays @saena-io/ui-free (the server graph ships no editor). '' is the empty doc.
+const richtextType: FieldType<string, string> = {
+  id: 'richtext',
+  kind: 'leaf',
+  empty: () => '',
+  validate: (_d, raw) => (raw == null ? '' : z.string().parse(raw)),
+  leaves: (_d, s, path) => [{ path, sourceText: s ?? '', format: 'rich' }],
+  hydrate: (_d, _s, ctx, path) => ctx.text(path),
+  toConfig: () => '',
+  fill: (_d, _s, ctx, path) => ctx.text(path),
+};
+
+const numberType: FieldType<number, number> = {
+  id: 'number',
+  kind: 'leaf',
+  empty: () => 0,
+  validate: (_d, raw) => (raw == null ? 0 : z.number().parse(raw)),
+  leaves: () => [],
+  hydrate: (_d, s) => s ?? 0,
+  toConfig: (_d, s) => s ?? 0,
+  fill: (_d, s) => s ?? 0,
+};
+
+const booleanType: FieldType<boolean, boolean> = {
+  id: 'boolean',
+  kind: 'leaf',
+  empty: () => false,
+  validate: (_d, raw) => (raw == null ? false : z.boolean().parse(raw)),
+  leaves: () => [],
+  hydrate: (_d, s) => s ?? false,
+  toConfig: (_d, s) => s ?? false,
+  fill: (_d, s) => s ?? false,
+};
+
+// An ISO date string (YYYY-MM-DD or full ISO); kept as a string so it's trivially serializable.
+const dateType: FieldType<string, string> = {
+  id: 'date',
+  kind: 'leaf',
+  empty: () => '',
+  validate: (_d, raw) => (raw == null ? '' : z.string().parse(raw)),
+  leaves: () => [],
+  hydrate: (_d, s) => s ?? '',
+  toConfig: (_d, s) => s ?? '',
+  fill: (_d, s) => s ?? '',
+};
+
+export interface SelectCfg {
+  options: string[];
+}
+const selectType: FieldType<string, string> = {
+  id: 'select',
+  kind: 'leaf',
+  empty: (d) => (d.cfg as SelectCfg | undefined)?.options?.[0] ?? '',
+  validate: (d, raw) => {
+    const options = (d.cfg as SelectCfg | undefined)?.options ?? [];
+    const v = raw == null ? '' : z.string().parse(raw);
+    return options.length === 0 || options.includes(v) ? v : (options[0] ?? '');
+  },
+  leaves: () => [],
+  hydrate: (_d, s) => s ?? '',
+  toConfig: (_d, s) => s ?? '',
+  fill: (_d, s) => s ?? '',
+};
+
+// A URL slug — config (locale-neutral). Normalised on save; the editor slugifies input + can auto-derive from
+// a sibling field (see SlugCfg.from).
+export interface SlugCfg {
+  /** A sibling field key to auto-derive the slug from (until the user edits it). */
+  from?: string;
+}
+const slugType: FieldType<string, string> = {
+  id: 'slug',
+  kind: 'leaf',
+  empty: () => '',
+  validate: (_d, raw) => slugify(raw == null ? '' : String(raw)),
+  leaves: () => [],
+  hydrate: (_d, s) => s ?? '',
+  toConfig: (_d, s) => s ?? '',
+  fill: (_d, s) => s ?? '',
+};
+
+// A link/CTA: href is config; label is a translatable text leaf nested at [...path, 'label'].
+interface LinkValue {
+  href: string;
+  label: string;
+}
+const linkType: FieldType<LinkValue, LinkValue> = {
+  id: 'link',
+  kind: 'leaf',
+  empty: () => ({ href: '', label: '' }),
+  validate: (_d, raw) => {
+    const o = (raw ?? {}) as Partial<LinkValue>;
+    return { href: z.string().parse(o.href ?? ''), label: z.string().parse(o.label ?? '') };
+  },
+  leaves: (_d, s, path) => [
+    { path: [...path, 'label'], sourceText: s?.label ?? '', format: 'plain' },
+  ],
+  hydrate: (_d, s, ctx, path) => ({ href: s?.href ?? '', label: ctx.text([...path, 'label']) }),
+  toConfig: (_d, s) => ({ href: s?.href ?? '', label: '' }),
+  fill: (_d, s, ctx, path) => ({ href: s?.href ?? '', label: ctx.text([...path, 'label']) }),
+};
+
+// An image: `ref` is the uploaded AssetRef (config — a denormalized snapshot carrying the render URL, ADR-0002);
+// `alt` is a translatable leaf; `hotspot` is the optional focal point (config — the "keep in frame" point used
+// when the public component crops to a render ratio, ADR-0009). The registry (core) is the system-of-record.
+/** A focal point on the original, each axis 0–1. Unset ⇒ centre (0.5, 0.5). */
+interface Hotspot {
+  x: number;
+  y: number;
+}
+interface ImageValue {
+  ref: AssetRef | null;
+  alt: string;
+  hotspot?: Hotspot;
+}
+/** Loosely validate a stored AssetRef (own uploads are well-formed; this guards hand-edited config) → null on junk. */
+const assetRefSchema = z
+  .object({
+    id: z.string(),
+    url: z.string(),
+    mime: z.string(),
+    size: z.number(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    dominantColor: z.string().optional(),
+    public: z.boolean(),
+  })
+  .nullable()
+  .catch(null);
+const clamp01 = (n: number): number => (Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0.5);
+/** Clamp a hand-edited/stored hotspot into range; junk (or absent) ⇒ undefined (centre default). */
+const hotspotSchema = z
+  .object({ x: z.number(), y: z.number() })
+  .transform((h) => ({ x: clamp01(h.x), y: clamp01(h.y) }))
+  .optional()
+  .catch(undefined);
+const imageType: FieldType<ImageValue, ImageValue> = {
+  id: 'image',
+  kind: 'leaf',
+  empty: () => ({ ref: null, alt: '' }),
+  validate: (_d, raw) => {
+    const o = (raw ?? {}) as Partial<ImageValue>;
+    return {
+      ref: assetRefSchema.parse(o.ref ?? null),
+      alt: z.string().parse(o.alt ?? ''),
+      hotspot: hotspotSchema.parse(o.hotspot),
+    };
+  },
+  leaves: (_d, s, path) => [{ path: [...path, 'alt'], sourceText: s?.alt ?? '', format: 'plain' }],
+  hydrate: (_d, s, ctx, path) => ({
+    ref: s?.ref ?? null,
+    alt: ctx.text([...path, 'alt']),
+    hotspot: s?.hotspot,
+  }),
+  toConfig: (_d, s) => ({ ref: s?.ref ?? null, alt: '', hotspot: s?.hotspot }),
+  fill: (_d, s, ctx, path) => ({
+    ref: s?.ref ?? null,
+    alt: ctx.text([...path, 'alt']),
+    hotspot: s?.hotspot,
+  }),
+};
+
+// ---------------------------------------------------------------------------------------------------------
+// Composite types — recurse into children via the registry
+// ---------------------------------------------------------------------------------------------------------
+
+interface ObjectCfg {
+  children: Record<string, FieldDecl>;
+}
+type ObjStorage = Record<string, unknown>;
+const objectType: FieldType<ObjStorage, ObjStorage> = {
+  id: 'object',
+  kind: 'object',
+  empty: (d) => {
+    const { children } = d.cfg as ObjectCfg;
+    const out: ObjStorage = {};
+    for (const [k, child] of Object.entries(children)) out[k] = fieldType(child.type).empty(child);
+    return out;
+  },
+  validate: (d, raw) => {
+    const { children } = d.cfg as ObjectCfg;
+    const src = (raw ?? {}) as ObjStorage;
+    const out: ObjStorage = {};
+    for (const [k, child] of Object.entries(children))
+      out[k] = fieldType(child.type).validate(child, src[k]);
+    return out;
+  },
+  leaves: (d, s, path) => {
+    const { children } = d.cfg as ObjectCfg;
+    const src = (s ?? {}) as ObjStorage;
+    return Object.entries(children).flatMap(([k, child]) =>
+      fieldType(child.type).leaves(child, src[k], [...path, k]),
+    );
+  },
+  hydrate: (d, s, ctx, path) => {
+    const { children } = d.cfg as ObjectCfg;
+    const src = (s ?? {}) as ObjStorage;
+    const out: ObjStorage = {};
+    for (const [k, child] of Object.entries(children))
+      out[k] = fieldType(child.type).hydrate(child, src[k], ctx, [...path, k]);
+    return out;
+  },
+  toConfig: (d, s) => {
+    const { children } = d.cfg as ObjectCfg;
+    const src = (s ?? {}) as ObjStorage;
+    const out: ObjStorage = {};
+    for (const [k, child] of Object.entries(children))
+      out[k] = fieldType(child.type).toConfig(child, src[k]);
+    return out;
+  },
+  fill: (d, s, ctx, path) => {
+    const { children } = d.cfg as ObjectCfg;
+    const src = (s ?? {}) as ObjStorage;
+    const out: ObjStorage = {};
+    for (const [k, child] of Object.entries(children))
+      out[k] = fieldType(child.type).fill(child, src[k], ctx, [...path, k]);
+    return out;
+  },
+};
+
+interface ListCfg {
+  item: FieldDecl;
+  /** Derives the label shown on a collapsed item card in the admin (e.g. a program's title). Admin-only and
+   *  ignored by the React-free core; if omitted the admin falls back to a title/name/label heuristic. NOTE: it
+   *  receives the item's EDITOR (storage) value — for shallow text/object/union fields this matches the public
+   *  shape, but a field reached THROUGH a nested list appears as `{ items: [...] }`, not a flat array. */
+  itemTitle?: (value: unknown) => string;
+}
+interface ListItem {
+  _id: string;
+  value: unknown;
+}
+interface ListStorage {
+  items: ListItem[];
+}
+const listType: FieldType<ListStorage, unknown[]> = {
+  id: 'list',
+  kind: 'list',
+  empty: () => ({ items: [] }),
+  validate: (d, raw) => {
+    const { item } = d.cfg as ListCfg;
+    const items = Array.isArray((raw as ListStorage | undefined)?.items)
+      ? (raw as ListStorage).items
+      : [];
+    return {
+      items: items.map((it) => ({
+        _id: String(it?._id ?? ''),
+        value: fieldType(item.type).validate(item, it?.value),
+      })),
+    };
+  },
+  leaves: (d, s, path) => {
+    const { item } = d.cfg as ListCfg;
+    return (s?.items ?? []).flatMap((it) =>
+      fieldType(item.type).leaves(item, it.value, [...path, it._id]),
+    );
+  },
+  hydrate: (d, s, ctx, path) => {
+    const { item } = d.cfg as ListCfg;
+    return (s?.items ?? []).map((it) =>
+      fieldType(item.type).hydrate(item, it.value, ctx, [...path, it._id]),
+    );
+  },
+  toConfig: (d, s) => {
+    const { item } = d.cfg as ListCfg;
+    return {
+      items: (s?.items ?? []).map((it) => ({
+        _id: it._id,
+        value: fieldType(item.type).toConfig(item, it.value),
+      })),
+    };
+  },
+  fill: (d, s, ctx, path) => {
+    const { item } = d.cfg as ListCfg;
+    return {
+      items: (s?.items ?? []).map((it) => ({
+        _id: it._id,
+        value: fieldType(item.type).fill(item, it.value, ctx, [...path, it._id]),
+      })),
+    };
+  },
+};
+
+interface UnionCfg {
+  discriminant: string;
+  variants: Record<string, FieldDecl>;
+}
+type UnionStorage = Record<string, unknown>;
+// A discriminated union: storage is the discriminant flat-merged with the active variant's (object) storage.
+// Variants MUST be object declarations, so the merge + the recursive walk are uniform (the variant's object
+// type reads only its own child keys; the extra discriminant key is ignored). Switching variants reuses the
+// same path, so abandoned keys are pruned by prefix on save.
+const unionType: FieldType<UnionStorage, UnionStorage> = {
+  id: 'union',
+  kind: 'union',
+  empty: (d) => {
+    const { discriminant, variants } = d.cfg as UnionCfg;
+    const first = Object.keys(variants)[0];
+    if (!first) return {};
+    const variant = variants[first] as FieldDecl;
+    return { [discriminant]: first, ...(fieldType(variant.type).empty(variant) as ObjStorage) };
+  },
+  validate: (d, raw) => {
+    const { discriminant, variants } = d.cfg as UnionCfg;
+    const keys = Object.keys(variants);
+    const given = (raw as UnionStorage | undefined)?.[discriminant];
+    const vid = typeof given === 'string' && variants[given] ? given : (keys[0] ?? '');
+    const variant = variants[vid];
+    if (!variant) return {};
+    return {
+      [discriminant]: vid,
+      ...(fieldType(variant.type).validate(variant, raw) as ObjStorage),
+    };
+  },
+  leaves: (d, s, path) => {
+    const { discriminant, variants } = d.cfg as UnionCfg;
+    const vid = s?.[discriminant];
+    const variant = typeof vid === 'string' ? variants[vid] : undefined;
+    return variant ? fieldType(variant.type).leaves(variant, s, path) : [];
+  },
+  hydrate: (d, s, ctx, path) => {
+    const { discriminant, variants } = d.cfg as UnionCfg;
+    const vid = s?.[discriminant];
+    const variant = typeof vid === 'string' ? variants[vid] : undefined;
+    if (!variant) return { [discriminant]: vid };
+    return {
+      [discriminant]: vid,
+      ...(fieldType(variant.type).hydrate(variant, s, ctx, path) as ObjStorage),
+    };
+  },
+  toConfig: (d, s) => {
+    const { discriminant, variants } = d.cfg as UnionCfg;
+    const vid = s?.[discriminant];
+    const variant = typeof vid === 'string' ? variants[vid] : undefined;
+    if (!variant) return { [discriminant]: vid };
+    return { [discriminant]: vid, ...(fieldType(variant.type).toConfig(variant, s) as ObjStorage) };
+  },
+  fill: (d, s, ctx, path) => {
+    const { discriminant, variants } = d.cfg as UnionCfg;
+    const vid = s?.[discriminant];
+    const variant = typeof vid === 'string' ? variants[vid] : undefined;
+    if (!variant) return { [discriminant]: vid };
+    return {
+      [discriminant]: vid,
+      ...(fieldType(variant.type).fill(variant, s, ctx, path) as ObjStorage),
+    };
+  },
+};
+
+// Register all built-ins on import.
+for (const t of [
+  textType,
+  richtextType,
+  numberType,
+  booleanType,
+  dateType,
+  selectType,
+  slugType,
+  linkType,
+  imageType,
+  objectType,
+  listType,
+  unionType,
+]) {
+  registerFieldType(t);
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// Authoring helpers — produce typed declarations so InferValue recovers the public value type
+// ---------------------------------------------------------------------------------------------------------
+
+type Visible = (siblings: Record<string, unknown>) => boolean;
+interface LeafOpts {
+  label?: string;
+  visible?: Visible;
+}
+
+export function text(opts?: LeafOpts): TypedDecl<string> {
+  return { type: 'text', label: opts?.label, visible: opts?.visible };
+}
+export function richtext(opts?: LeafOpts): TypedDecl<string> {
+  return { type: 'richtext', label: opts?.label, visible: opts?.visible };
+}
+export function number(opts?: LeafOpts): TypedDecl<number> {
+  return { type: 'number', label: opts?.label, visible: opts?.visible };
+}
+export function boolean(opts?: LeafOpts): TypedDecl<boolean> {
+  return { type: 'boolean', label: opts?.label, visible: opts?.visible };
+}
+export function date(opts?: LeafOpts): TypedDecl<string> {
+  return { type: 'date', label: opts?.label, visible: opts?.visible };
+}
+export function select<const O extends string>(
+  options: readonly O[],
+  opts?: LeafOpts,
+): TypedDecl<O, SelectCfg> {
+  return {
+    type: 'select',
+    label: opts?.label,
+    visible: opts?.visible,
+    cfg: { options: [...options] },
+  };
+}
+export function slug(opts?: LeafOpts & { from?: string }): TypedDecl<string, SlugCfg> {
+  return { type: 'slug', label: opts?.label, visible: opts?.visible, cfg: { from: opts?.from } };
+}
+export function link(opts?: LeafOpts): TypedDecl<LinkValue> {
+  return { type: 'link', label: opts?.label, visible: opts?.visible };
+}
+/** `ratio` (w/h) is an editor-only crop **guide** shown in the focal-point picker; the public component still
+ *  owns the real render ratio(s) (ADR-0009). The cfg type is inline (anonymous) so the inferred schema type
+ *  stays portable across the package boundary. */
+export function image(
+  opts?: LeafOpts & { ratio?: number },
+): TypedDecl<ImageValue, { ratio?: number }> {
+  return {
+    type: 'image',
+    label: opts?.label,
+    visible: opts?.visible,
+    cfg: { ratio: opts?.ratio },
+  };
+}
+
+export function object<C extends Record<string, TypedDecl<unknown>>>(
+  children: C,
+  opts?: LeafOpts,
+): TypedDecl<{ [K in keyof C]: InferValue<C[K]> }, { children: C }> {
+  return { type: 'object', label: opts?.label, visible: opts?.visible, cfg: { children } };
+}
+
+/** Like `object`, but rendered as a visual group (a muted, rounded box) to show related fields belong
+ *  together. Same data shape as `object` — the fields nest under this key. */
+export function group<C extends Record<string, TypedDecl<unknown>>>(
+  children: C,
+  opts?: LeafOpts,
+): TypedDecl<{ [K in keyof C]: InferValue<C[K]> }, { children: C; group: true }> {
+  return {
+    type: 'object',
+    label: opts?.label,
+    visible: opts?.visible,
+    cfg: { children, group: true },
+  };
+}
+
+// `itemTitle` is typed against the item's value `V` for ergonomics (the common case — a shallow text/object/
+// union title — matches the editor shape it's actually called with). The exception is a title reached through a
+// NESTED list, which appears as `{ items: [...] }` at runtime; see ListCfg.itemTitle.
+export function list<V>(
+  item: TypedDecl<V>,
+  opts?: LeafOpts & { itemTitle?: (value: V) => string },
+): TypedDecl<V[], { item: TypedDecl<V>; itemTitle?: (value: V) => string }> {
+  return {
+    type: 'list',
+    label: opts?.label,
+    visible: opts?.visible,
+    cfg: { item, itemTitle: opts?.itemTitle },
+  };
+}
+
+export function union<
+  D extends string,
+  V extends Record<string, TypedDecl<Record<string, unknown>>>,
+>(
+  discriminant: D,
+  variants: V,
+  opts?: LeafOpts,
+): TypedDecl<
+  { [K in keyof V]: { [P in D]: K } & InferValue<V[K]> }[keyof V],
+  { discriminant: D; variants: V }
+> {
+  return {
+    type: 'union',
+    label: opts?.label,
+    visible: opts?.visible,
+    cfg: { discriminant, variants },
+  };
+}
+
+export type { LinkValue, ImageValue };