@saena-io/content 0.1.0

package/src/public/index.tsx

@@ -0,0 +1,133 @@
+import { type AssetRef, IMAGE_WIDTH_LADDER } from '@saena-io/plugin-sdk';
+import { RichTextStatic } from '@saena-io/ui/components/rich-text/static';
+import type { ComponentType } from 'react';
+import type { ImageValue } from '../field';
+
+// @saena-io/content/public — the public-site readers a section's React component uses to render field values.
+// Editor-free (RichTextStatic ships no editor), so the public bundle stays editor-free (ADR-0005/0008). v1
+// exposes the richtext reader; custom field types provide their own public reader alongside their editor. The
+// page composition + section components live in the client app and call these.
+
+/** Render a `richtext` field value (the stored serialized-Slate string) for the public site, editor-free. */
+export function ContentRichText({ value, className }: { value: string; className?: string }) {
+  return <RichTextStatic value={value} className={className} />;
+}
+
+// webp is requested for all variants (universal support, small). Widths come from the shared IMAGE_WIDTH_LADDER
+// (the serve route snaps to the same ladder, so descriptors are honest and the derivative cache stays bounded).
+const CENTRE = { x: 0.5, y: 0.5 };
+
+/** Build a derivative URL for the serve route (ADR-0009): `/api/assets/<id>?w=&fmt=webp[&ar=&fx=&fy=&q=]`. */
+function variantUrl(
+  url: string,
+  width: number,
+  ratio: number | undefined,
+  hot: { x: number; y: number },
+  quality: number | undefined,
+): string {
+  const p = new URLSearchParams({ w: String(width), fmt: 'webp' });
+  if (ratio) {
+    p.set('ar', String(ratio));
+    p.set('fx', String(hot.x));
+    p.set('fy', String(hot.y));
+  }
+  if (quality) p.set('q', String(quality));
+  return `${url}?${p.toString()}`;
+}
+
+/**
+ * Render an `image` field value for the public site (ADR-0009): an optimized, responsive `<img>` — a webp
+ * `srcset` of widths the browser picks from by DPR + the `sizes` hint, with intrinsic `width`/`height` set so
+ * there's no layout shift. Pass `ratio` (w/h) to render at a fixed aspect: variants are cropped to it, centred
+ * on the field's focal point (`hotspot`), so the subject stays in frame across breakpoints. Editor-free (just an
+ * `<img>`), so the public bundle stays editor-free. While the image loads, its dominant colour (when known) is
+ * shown as the background so the reserved box isn't blank. Renders nothing until an image is set.
+ */
+export function ContentImage({
+  value,
+  ratio,
+  sizes = '100vw',
+  quality,
+  priority = false,
+  className,
+}: {
+  value: ImageValue;
+  /** Render aspect ratio (w/h). When set, variants are cropped to it, centred on the focal point. */
+  ratio?: number;
+  /** The `sizes` attribute — how wide the image renders per breakpoint (e.g. `(min-width:768px) 50vw, 100vw`). */
+  sizes?: string;
+  /** Override the webp encoder quality (1–100) for this usage; omitted uses the pipeline's tuned default. */
+  quality?: number;
+  /** Eager-load above-the-fold images (default lazy). */
+  priority?: boolean;
+  className?: string;
+}) {
+  const ref: AssetRef | null = value.ref;
+  if (!ref) return null;
+  const loading = priority ? 'eager' : 'lazy';
+  // Dominant colour as a load placeholder (when probed); the opaque image paints over it.
+  const placeholder = ref.dominantColor ? { backgroundColor: ref.dominantColor } : undefined;
+
+  // Without intrinsic dimensions (a pre-ADR-0009 upload), or a source narrower than the smallest ladder width
+  // (a srcset would add nothing), serve the original as a plain, still-lazy `<img>`.
+  const maxW =
+    ratio && ref.width && ref.height && ratio < ref.width / ref.height
+      ? Math.round(ref.height * ratio)
+      : (ref.width ?? 0);
+  const ladder = IMAGE_WIDTH_LADDER.filter((w) => w <= maxW);
+  if (!ref.width || !ref.height || ladder.length === 0) {
+    return (
+      <img
+        src={ref.url}
+        alt={value.alt}
+        width={ref.width}
+        height={ref.height}
+        loading={loading}
+        decoding="async"
+        style={placeholder}
+        className={className}
+      />
+    );
+  }
+
+  const hot = value.hotspot ?? CENTRE;
+  // Largest deliverable width = top of the per-image ladder (non-empty here); intrinsic width/height carry the
+  // render aspect (ratio when cropping, else the source's), so the box is reserved with no layout shift.
+  const outW = ladder[ladder.length - 1] ?? maxW;
+  const outH = ratio ? Math.round(outW / ratio) : Math.round(outW / (ref.width / ref.height));
+
+  return (
+    <img
+      src={variantUrl(ref.url, outW, ratio, hot, quality)}
+      srcSet={ladder.map((w) => `${variantUrl(ref.url, w, ratio, hot, quality)} ${w}w`).join(', ')}
+      sizes={sizes}
+      alt={value.alt}
+      width={outW}
+      height={outH}
+      style={placeholder}
+      loading={loading}
+      decoding="async"
+      className={className}
+    />
+  );
+}
+
+// --- Section component registry --------------------------------------------------------------------------
+// A section's public component, keyed by its section id. Registering one lets the admin's live preview render
+// the real public component from the in-editor value (the same component the public route renders), so the
+// preview is WYSIWYG. Section composition stays code (definePage); this only makes the components addressable.
+
+/** A section's public component — receives its hydrated `content`. */
+export type SectionComponent<C = unknown> = ComponentType<{ content: C }>;
+
+const sectionComponents = new Map<string, SectionComponent>();
+
+/** Register a section's public component by id (call once at module load, alongside the component). */
+export function registerSectionComponent<C>(id: string, component: SectionComponent<C>): void {
+  sectionComponents.set(id, component as SectionComponent);
+}
+
+/** The registered public component for a section id, if any (the admin live preview reads this). */
+export function getSectionComponent(id: string): SectionComponent | undefined {
+  return sectionComponents.get(id);
+}

package/src/service.ts

@@ -0,0 +1,375 @@
+import { randomUUID } from 'node:crypto';
+import type { RequestContext, TranslatableInput } from '@saena-io/plugin-sdk';
+import { and, asc, eq, sql } from 'drizzle-orm';
+import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { contentCollectionItems, contentSectionValues } from './db/schema';
+import { type CollectionDef, getCollection, getPage, getSection } from './define';
+import {
+  fieldEmpty,
+  fieldToConfig,
+  fieldValidate,
+  fillSection,
+  hydrateSection,
+  sectionLeaves,
+  slugify,
+} from './field';
+
+// The content service (ADR-0008). Sections + pages are CODE (the registry in ./define); this persists only
+// the editable VALUES: structure/config in content_section_values, and every translatable leaf as an i18n key
+// via the field core's leaf walk. Live-edit (no draft/publish in v1). Plugins query their own tables through
+// ctx.db, which the SDK keeps opaque (Database = unknown) — cast to the drizzle handle the core provides.
+function db(ctx: RequestContext): PostgresJsDatabase {
+  return ctx.db as PostgresJsDatabase;
+}
+
+/** The i18n key prefix for a section instance: `content.<page>.<section>`. */
+function sectionPrefix(page: string, section: string): string {
+  return `content.${page}.${section}`;
+}
+
+export interface SaveSectionInput {
+  page: string;
+  section: string;
+  /** The section's value as produced by the admin editor (validated against the section schema here). */
+  value: unknown;
+}
+
+/**
+ * Persist a section's content: validate against its schema, prune the i18n keys of any removed list items /
+ * abandoned union variants, store the config projection (text blanked), then sync every text leaf to i18n.
+ */
+export async function saveSection(ctx: RequestContext, input: SaveSectionInput): Promise<void> {
+  ctx.requirePermission('content.manage');
+  const def = getSection(input.section);
+  if (!def) throw new Error(`unknown content section: ${input.section}`);
+  const prefix = sectionPrefix(input.page, input.section);
+  const storage = fieldValidate(def.schema, input.value);
+
+  const [existing] = await db(ctx)
+    .select({ config: contentSectionValues.config })
+    .from(contentSectionValues)
+    .where(
+      and(
+        eq(contentSectionValues.page, input.page),
+        eq(contentSectionValues.section, input.section),
+      ),
+    )
+    .limit(1);
+
+  const leaves = sectionLeaves(def.schema, storage, prefix);
+  const newKeys = new Set(leaves.map((l) => l.key));
+  const config = fieldToConfig(def.schema, storage);
+  const fields: TranslatableInput[] = leaves.map((l) => ({
+    key: l.key,
+    sourceText: l.sourceText,
+    format: l.format,
+  }));
+  // One transaction: prune removed i18n keys, write the config projection, and sync the text leaves together —
+  // so a mid-save failure can never leave the config and its translations out of sync. The i18n seam runs on
+  // the same `tx` (ADR-0005/0008).
+  await db(ctx).transaction(async (tx) => {
+    if (existing) {
+      // Keys that existed but no longer do (a removed item, a switched union variant) → prune from i18n.
+      const oldKeys = sectionLeaves(def.schema, existing.config, prefix).map((l) => l.key);
+      for (const key of oldKeys) {
+        if (!newKeys.has(key)) await ctx.i18n.deleteKeysByPrefix(key, { tx });
+      }
+    }
+    await tx
+      .insert(contentSectionValues)
+      .values({ page: input.page, section: input.section, config })
+      .onConflictDoUpdate({
+        target: [contentSectionValues.page, contentSectionValues.section],
+        set: { config, updatedAt: new Date() },
+      });
+    await ctx.i18n.syncTranslatable(fields, { tx });
+  });
+}
+
+/** `localizeMany` echoes unknown keys back as their own value (a public "missing string" marker). A content
+ *  field with no translation yet — e.g. one newly added to an already-saved section — should read as empty in
+ *  both the editor and the public render, so drop the echoes (value === key) before hydrate/fill. */
+function dropMissing(localized: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(localized)) if (v !== k) out[k] = v;
+  return out;
+}
+
+/** Load a section's content, hydrated + localized for `ctx.locale`. Unsaved sections hydrate to empty values. */
+export async function getSectionContent(
+  ctx: RequestContext,
+  page: string,
+  section: string,
+): Promise<unknown> {
+  const def = getSection(section);
+  if (!def) throw new Error(`unknown content section: ${section}`);
+  const prefix = sectionPrefix(page, section);
+  const [row] = await db(ctx)
+    .select({ config: contentSectionValues.config })
+    .from(contentSectionValues)
+    .where(and(eq(contentSectionValues.page, page), eq(contentSectionValues.section, section)))
+    .limit(1);
+
+  if (!row) {
+    // Never saved: hydrate the empty config with no localized text (text leaves → '').
+    const empty = fieldToConfig(def.schema, fieldEmpty(def.schema));
+    return hydrateSection(def.schema, empty, {}, prefix);
+  }
+  const keys = sectionLeaves(def.schema, row.config, prefix).map((l) => l.key);
+  const localized = dropMissing(await ctx.i18n.localizeMany(keys, ctx.locale));
+  return hydrateSection(def.schema, row.config, localized, prefix);
+}
+
+/**
+ * Load a section's content for the ADMIN editor: the storage shape (list item ids preserved) with translatable
+ * leaves filled from the editing locale's source — so the editor mutates a complete payload that saves back
+ * with stable ids + i18n keys. Distinct from getSectionContent, which gives the public a clean value shape.
+ */
+export async function getSectionForEdit(
+  ctx: RequestContext,
+  page: string,
+  section: string,
+): Promise<unknown> {
+  const def = getSection(section);
+  if (!def) throw new Error(`unknown content section: ${section}`);
+  const prefix = sectionPrefix(page, section);
+  const [row] = await db(ctx)
+    .select({ config: contentSectionValues.config })
+    .from(contentSectionValues)
+    .where(and(eq(contentSectionValues.page, page), eq(contentSectionValues.section, section)))
+    .limit(1);
+
+  const config = row?.config ?? fieldToConfig(def.schema, fieldEmpty(def.schema));
+  if (!row) return fillSection(def.schema, config, {}, prefix);
+  const keys = sectionLeaves(def.schema, config, prefix).map((l) => l.key);
+  const localized = dropMissing(await ctx.i18n.localizeMany(keys, ctx.locale));
+  return fillSection(def.schema, config, localized, prefix);
+}
+
+/** Load every section of a page, keyed by section id — the public route's hydration payload. */
+export async function getPageContent(
+  ctx: RequestContext,
+  page: string,
+): Promise<Record<string, unknown> | null> {
+  const def = getPage(page);
+  if (!def) return null;
+  const out: Record<string, unknown> = {};
+  for (const section of def.sections) out[section] = await getSectionContent(ctx, page, section);
+  return out;
+}
+
+// --- Routed collections (ADR-0011) -----------------------------------------------------------------------
+// One row per entry in content_collection_items; the per-entry field pipeline is the SAME field core sections
+// use. Each entry's translatable leaves are rooted at its STABLE row id — `content.collection.<c>.<id>.…` — so
+// reorder/rename never re-keys or orphans translations. Saves are transactional (config + i18n together).
+
+/** The i18n key prefix for a collection entry — rooted at the entry's stable row id (ADR-0011). */
+function collectionItemPrefix(collection: string, id: string): string {
+  return `content.collection.${collection}.${id}`;
+}
+
+function requireCollection(id: string): CollectionDef {
+  const def = getCollection(id);
+  if (!def) throw new Error(`unknown content collection: ${id}`);
+  return def;
+}
+
+/** A collection entry as the service returns it: identity + slug + the (opaque) hydrated value. Callers cast
+ *  `value` to their schema's `InferValue` via `CollectionItem<typeof def>`. */
+export interface CollectionItemRecord {
+  id: string;
+  slug: string;
+  value: unknown;
+}
+
+export interface SaveCollectionItemInput {
+  collection: string;
+  /** Omit to create a new entry; provide to update an existing one. */
+  id?: string;
+  slug: string;
+  /** The entry value from the admin editor (validated server-side against the collection schema). */
+  value: unknown;
+}
+
+/** Create or update a collection entry. In ONE transaction: upsert the row, prune removed i18n keys, and sync
+ *  the text leaves (rooted at the entry's stable id). Returns the entry id. */
+export async function saveItem(
+  ctx: RequestContext,
+  input: SaveCollectionItemInput,
+): Promise<{ id: string }> {
+  ctx.requirePermission('content.manage');
+  const def = requireCollection(input.collection);
+  const id = input.id ?? randomUUID();
+  const slug = slugify(input.slug) || id;
+  const prefix = collectionItemPrefix(input.collection, id);
+  const storage = fieldValidate(def.schema, input.value);
+  const leaves = sectionLeaves(def.schema, storage, prefix);
+  const newKeys = new Set(leaves.map((l) => l.key));
+  const config = fieldToConfig(def.schema, storage);
+  const fields: TranslatableInput[] = leaves.map((l) => ({
+    key: l.key,
+    sourceText: l.sourceText,
+    format: l.format,
+  }));
+
+  await db(ctx).transaction(async (tx) => {
+    const [existing] = await tx
+      .select({ config: contentCollectionItems.config })
+      .from(contentCollectionItems)
+      .where(eq(contentCollectionItems.id, id))
+      .limit(1);
+    if (existing) {
+      // Prune keys that existed but no longer do (a removed list item / switched union variant).
+      const oldKeys = sectionLeaves(def.schema, existing.config, prefix).map((l) => l.key);
+      for (const key of oldKeys) {
+        if (!newKeys.has(key)) await ctx.i18n.deleteKeysByPrefix(key, { tx });
+      }
+    }
+    // New entries append at the end of the collection's order.
+    let sortOrder = 0;
+    if (!existing) {
+      const [m] = await tx
+        .select({ max: sql<number>`coalesce(max(${contentCollectionItems.sortOrder}), -1)` })
+        .from(contentCollectionItems)
+        .where(eq(contentCollectionItems.collection, input.collection));
+      sortOrder = (m?.max ?? -1) + 1;
+    }
+    await tx
+      .insert(contentCollectionItems)
+      .values({ id, collection: input.collection, slug, config, sortOrder })
+      .onConflictDoUpdate({
+        target: contentCollectionItems.id,
+        set: { slug, config, updatedAt: new Date() },
+      });
+    await ctx.i18n.syncTranslatable(fields, { tx });
+  });
+  return { id };
+}
+
+/** Delete a collection entry + its i18n keys, atomically. */
+export async function deleteItem(
+  ctx: RequestContext,
+  input: { collection: string; id: string },
+): Promise<void> {
+  ctx.requirePermission('content.manage');
+  const prefix = collectionItemPrefix(input.collection, input.id);
+  await db(ctx).transaction(async (tx) => {
+    await tx
+      .delete(contentCollectionItems)
+      .where(
+        and(
+          eq(contentCollectionItems.collection, input.collection),
+          eq(contentCollectionItems.id, input.id),
+        ),
+      );
+    await ctx.i18n.deleteKeysByPrefix(prefix, { tx });
+  });
+}
+
+/** Set the collection's order from an explicit id sequence (the admin manager's drag-to-reorder). */
+export async function reorderItems(
+  ctx: RequestContext,
+  collection: string,
+  orderedIds: string[],
+): Promise<void> {
+  ctx.requirePermission('content.manage');
+  await db(ctx).transaction(async (tx) => {
+    for (const [i, id] of orderedIds.entries()) {
+      await tx
+        .update(contentCollectionItems)
+        .set({ sortOrder: i, updatedAt: new Date() })
+        .where(
+          and(eq(contentCollectionItems.collection, collection), eq(contentCollectionItems.id, id)),
+        );
+    }
+  });
+}
+
+/** Hydrate rows into public records, batching the i18n lookup across all rows (no N+1). */
+async function hydrateRows(
+  ctx: RequestContext,
+  def: CollectionDef,
+  collection: string,
+  rows: { id: string; slug: string; config: unknown }[],
+): Promise<CollectionItemRecord[]> {
+  const withPrefix = rows.map((row) => ({ row, prefix: collectionItemPrefix(collection, row.id) }));
+  const allKeys = withPrefix.flatMap(({ row, prefix }) =>
+    sectionLeaves(def.schema, row.config, prefix).map((l) => l.key),
+  );
+  const localized = allKeys.length
+    ? dropMissing(await ctx.i18n.localizeMany(allKeys, ctx.locale))
+    : {};
+  return withPrefix.map(({ row, prefix }) => ({
+    id: row.id,
+    slug: row.slug,
+    value: hydrateSection(def.schema, row.config, localized, prefix),
+  }));
+}
+
+export interface ListItemsOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/** List a collection's entries (ordered, hydrated + localized) — the list/archive route's payload. */
+export async function listItems(
+  ctx: RequestContext,
+  collection: string,
+  opts?: ListItemsOptions,
+): Promise<CollectionItemRecord[]> {
+  const def = requireCollection(collection);
+  let q = db(ctx)
+    .select()
+    .from(contentCollectionItems)
+    .where(eq(contentCollectionItems.collection, collection))
+    .orderBy(asc(contentCollectionItems.sortOrder))
+    .$dynamic();
+  if (opts?.limit != null) q = q.limit(opts.limit);
+  if (opts?.offset != null) q = q.offset(opts.offset);
+  return hydrateRows(ctx, def, collection, await q);
+}
+
+/** Load one entry by its `$slug` route segment (hydrated + localized), or null — the detail route's payload. */
+export async function getItemBySlug(
+  ctx: RequestContext,
+  collection: string,
+  slug: string,
+): Promise<CollectionItemRecord | null> {
+  const def = requireCollection(collection);
+  const [row] = await db(ctx)
+    .select()
+    .from(contentCollectionItems)
+    .where(
+      and(eq(contentCollectionItems.collection, collection), eq(contentCollectionItems.slug, slug)),
+    )
+    .limit(1);
+  if (!row) return null;
+  const [item] = await hydrateRows(ctx, def, collection, [row]);
+  return item ?? null;
+}
+
+/** Load one entry by id for the ADMIN editor: the storage shape (list item ids preserved) with text filled
+ *  from the editing locale — symmetric with getSectionForEdit. */
+export async function getItemForEdit(
+  ctx: RequestContext,
+  collection: string,
+  id: string,
+): Promise<CollectionItemRecord | null> {
+  const def = requireCollection(collection);
+  const [row] = await db(ctx)
+    .select()
+    .from(contentCollectionItems)
+    .where(
+      and(eq(contentCollectionItems.collection, collection), eq(contentCollectionItems.id, id)),
+    )
+    .limit(1);
+  if (!row) return null;
+  const prefix = collectionItemPrefix(collection, id);
+  const keys = sectionLeaves(def.schema, row.config, prefix).map((l) => l.key);
+  const localized = dropMissing(await ctx.i18n.localizeMany(keys, ctx.locale));
+  return {
+    id: row.id,
+    slug: row.slug,
+    value: fillSection(def.schema, row.config, localized, prefix),
+  };
+}