@saena-io/content 0.1.0

package/src/admin/index.tsx

@@ -0,0 +1,343 @@
+import { type AdminExtension, type AdminNavItem, type AdminRoute, Page } from '@saena-io/ui/admin';
+import { Button } from '@saena-io/ui/components/button';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@saena-io/ui/components/collapsible';
+import { RichTextDndProvider } from '@saena-io/ui/components/rich-text/rich-text-editor';
+import { Component, type ReactNode, memo, useEffect, useState, useSyncExternalStore } from 'react';
+import {
+  type PageDef,
+  type SectionDef,
+  allCollections,
+  allPages,
+  getPage,
+  getSection,
+} from '../define';
+import { hydratePreview } from '../field';
+import { getSectionComponent } from '../public';
+import { contentClient } from './client';
+import { CollectionManager } from './collection-manager';
+import './editors'; // registers the built-in field-type editors
+import { FieldView } from './form-engine';
+import { Chevron } from './icons';
+
+// @saena-io/content/admin — the CLIENT half (ADR-0008). One admin screen PER public page, full-bleed: the page's
+// sections stack as edge-to-edge panels separated by borders (no cards — avoids the nested-card look), beside a
+// preview pane split off by a vertical border. Page navigation lives in the main admin sidebar as a collapsible
+// "Content" group listing every page (built by buildContentAdmin from the registry — call it AFTER the
+// project's sections/pages register).
+
+/**
+ * One section, edited in a full-width, collapsible panel (no card): a bg-primary header that toggles the panel,
+ * the generated form body, and a footer with Reset + Save. `loaded` is the last server snapshot — Reset reverts
+ * to it (remounting the form via `formKey` so uncontrolled editors, e.g. rich text, re-initialise).
+ */
+function SectionPanel({
+  page,
+  section,
+  store,
+}: {
+  page: string;
+  section: string;
+  /** The live-preview store this section publishes its current value into (on load, every edit, and reset). */
+  store: PreviewStore;
+}) {
+  const def = getSection(section);
+  const [value, setValue] = useState<unknown>(undefined);
+  const [loaded, setLoaded] = useState<unknown>(undefined);
+  const [formKey, setFormKey] = useState(0);
+  const [saving, setSaving] = useState(false);
+  const [status, setStatus] = useState<string | null>(null);
+
+  useEffect(() => {
+    let live = true;
+    setValue(undefined);
+    setStatus(null);
+    contentClient
+      .getSection(page, section)
+      .then((v) => {
+        if (!live) return;
+        setValue(v);
+        setLoaded(v);
+        store.set(section, v);
+      })
+      .catch((e) => live && setStatus(String(e)));
+    return () => {
+      live = false;
+    };
+  }, [page, section, store]);
+
+  if (!def) return null;
+
+  // Every edit updates local state AND the preview store.
+  const edit = (v: unknown) => {
+    setValue(v);
+    store.set(section, v);
+  };
+
+  // Edits always create new object trees (immutable updates in the form engine), so a reference compare
+  // against the last-saved/loaded snapshot is an accurate dirty check.
+  const dirty = value !== loaded;
+
+  const save = async () => {
+    setSaving(true);
+    setStatus(null);
+    try {
+      await contentClient.saveSection({ page, section, value });
+      setLoaded(value);
+      setStatus('Saved');
+    } catch (e) {
+      setStatus(String(e));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const reset = () => {
+    setValue(loaded);
+    store.set(section, loaded);
+    setFormKey((k) => k + 1); // remount the form so uncontrolled editors re-init from `loaded`
+    setStatus(null);
+  };
+
+  return (
+    <Collapsible defaultOpen render={<section className="border-b" />}>
+      <CollapsibleTrigger className="group bg-linear-to-l from-input/30 to-input/0 flex w-full items-center justify-between gap-3 border-l-4 border-primary px-6 py-3 text-left text-secondary-foreground transition-colors hover:bg-input/30">
+        <span className="font-medium text-sm -ml-1">{def.label}</span>
+        <Chevron />
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <div className="px-6 py-4">
+          {value === undefined ? (
+            <p className="text-muted-foreground text-sm">Loading…</p>
+          ) : (
+            <FieldView
+              key={formKey}
+              field={def.schema}
+              value={value}
+              onChange={edit}
+              path={[]}
+              locale="source"
+            />
+          )}
+        </div>
+        <footer className="flex items-center justify-end gap-2 px-6 py-3 pb-6">
+          {status ? <span className="mr-auto text-muted-foreground text-xs">{status}</span> : null}
+          <Button variant="outline" size="lg" onClick={reset} disabled={saving || !dirty}>
+            Reset
+          </Button>
+          <Button size="lg" onClick={save} disabled={saving || !dirty}>
+            {saving ? 'Saving…' : 'Save'}
+          </Button>
+        </footer>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+// --- Live preview ---------------------------------------------------------------------------------------
+// Each SectionPanel pushes its current editor value into a tiny external store; the preview subscribes and
+// re-renders on change — so a keystroke re-renders ONLY the preview, not the (heavy) editor panels.
+
+interface PreviewStore {
+  set(id: string, value: unknown): void;
+  get(id: string): unknown;
+  subscribe(listener: () => void): () => void;
+  getVersion(): number;
+}
+
+function createPreviewStore(): PreviewStore {
+  const values = new Map<string, unknown>();
+  const listeners = new Set<() => void>();
+  let version = 0;
+  return {
+    set(id, value) {
+      values.set(id, value);
+      version += 1;
+      for (const l of listeners) l();
+    },
+    get: (id) => values.get(id),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getVersion: () => version,
+  };
+}
+
+/** Isolates a section's preview render: a thrown error (from rendering with mid-edit / partial data) shows a
+ *  fallback instead of crashing the admin, and the boundary self-heals when the value changes (`resetKey`). */
+class PreviewBoundary extends Component<
+  { resetKey: unknown; fallback: ReactNode; children: ReactNode },
+  { failed: boolean }
+> {
+  override state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  override componentDidUpdate(prev: { resetKey: unknown }) {
+    if (this.state.failed && prev.resetKey !== this.props.resetKey)
+      this.setState({ failed: false });
+  }
+  override render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
+
+/** Renders one section's public component from the in-editor value (client-side hydrate, no server round-trip).
+ *  Memoised so an edit to one section doesn't re-render the others' previews. */
+const SectionPreview = memo(function SectionPreview({
+  def,
+  value,
+}: {
+  def: SectionDef;
+  value: unknown;
+}) {
+  const Section = getSectionComponent(def.id);
+  if (!Section) {
+    return (
+      <p className="px-6 py-4 text-muted-foreground text-xs">
+        No preview component registered for “{def.label}”.
+      </p>
+    );
+  }
+  return <Section content={hydratePreview(def.schema, value)} />;
+});
+
+/** The right-hand pane: the page's sections rendered with their live editor values, as the public site will
+ *  show them. Non-interactive (pointer-events-none) so it can't navigate away from the editor. */
+function PreviewPane({ page, store }: { page: PageDef; store: PreviewStore }) {
+  useSyncExternalStore(store.subscribe, store.getVersion, store.getVersion);
+  const ready = page.sections.some((sid) => store.get(sid) !== undefined);
+  return (
+    <div className="flex min-h-0 flex-1 flex-col overflow-y-auto bg-background">
+      <div className="border-border border-b px-4 py-2 font-medium text-muted-foreground text-xs uppercase tracking-wide">
+        Preview
+      </div>
+      {ready ? (
+        <div className="select-none pointer-events-none">
+          {page.sections.map((sid) => {
+            const def = getSection(sid);
+            const value = store.get(sid);
+            if (!def || value === undefined) return null;
+            return (
+              <PreviewBoundary
+                key={sid}
+                resetKey={value}
+                fallback={
+                  <p className="px-6 py-4 text-destructive text-xs">
+                    Preview unavailable — finish editing this section.
+                  </p>
+                }
+              >
+                <SectionPreview def={def} value={value} />
+              </PreviewBoundary>
+            );
+          })}
+        </div>
+      ) : (
+        <p className="p-6 text-muted-foreground text-sm">Loading preview…</p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A page's admin screen. The title goes to the top bar via <Page>; the body is full-bleed and splits in two —
+ * the section panels (the editor) on the left, the live preview on the right. One DnD provider wraps the
+ * editor column; one preview store bridges the section values to the preview.
+ */
+function PageScreen({ pageId }: { pageId: string }) {
+  const page = getPage(pageId);
+  const [store] = useState(createPreviewStore);
+  if (!page) {
+    return (
+      <Page title="Content" className="p-6">
+        <p className="text-destructive text-sm">Unknown page: {pageId}</p>
+      </Page>
+    );
+  }
+  return (
+    <Page title={page.label ?? page.id} className="min-h-0">
+      {/* Full-bleed split filling the bounded content slot (the shell fixes the page height): the editor
+          column scrolls internally, the preview conforms to the height — the page itself never scrolls. */}
+      <div className="flex min-h-0 flex-1 flex-col md:flex-row">
+        <div className="flex min-h-0 flex-col overflow-y-auto md:flex-1 md:border-border md:border-r">
+          <RichTextDndProvider>
+            {page.sections.map((sid) => (
+              <SectionPanel key={sid} page={page.id} section={sid} store={store} />
+            ))}
+          </RichTextDndProvider>
+        </div>
+        <aside className="hidden min-h-0 md:flex md:flex-1 md:flex-col">
+          <PreviewPane page={page} store={store} />
+        </aside>
+      </div>
+    </Page>
+  );
+}
+
+/**
+ * Build the content admin extension from the registered pages: a collapsible "Content" nav group whose
+ * sub-items are the pages, and one route per page (`content/<id>`). Call this AFTER the project's sections +
+ * pages are registered (e.g. in the admin manifest, after importing the section barrel).
+ */
+export function buildContentAdmin(): AdminExtension {
+  const pages = allPages();
+  const collections = allCollections();
+  const firstPage = pages[0];
+  const firstCollection = collections[0];
+
+  const nav: AdminNavItem[] = [];
+  if (firstPage) {
+    nav.push({
+      id: 'content',
+      label: 'Content',
+      to: `content/${firstPage.id}`,
+      order: 10,
+      permission: 'content.manage',
+      items: pages.map((p) => ({
+        id: `content.${p.id}`,
+        label: p.label ?? p.id,
+        to: `content/${p.id}`,
+      })),
+    });
+  }
+  // Routed collections (ADR-0011) get their own collapsible nav group + one manager route each.
+  if (firstCollection) {
+    nav.push({
+      id: 'collections',
+      label: 'Collections',
+      to: `collections/${firstCollection.id}`,
+      order: 20,
+      permission: 'content.manage',
+      items: collections.map((c) => ({
+        id: `collections.${c.id}`,
+        label: c.label,
+        to: `collections/${c.id}`,
+      })),
+    });
+  }
+
+  const routes: AdminRoute[] = [
+    ...pages.map((p) => ({
+      path: `content/${p.id}`,
+      component: () => <PageScreen pageId={p.id} />,
+    })),
+    ...collections.map((c) => ({
+      path: `collections/${c.id}`,
+      component: () => <CollectionManager collectionId={c.id} />,
+    })),
+  ];
+
+  return { id: 'content', nav, routes };
+}
+
+// Re-export the editor seam so a client app can register a custom field type's admin editor by id.
+export { registerEditor, getEditor } from './field-registry';
+export type { AdminEditor, AdminEditorProps } from './field-registry';
+export { FieldView } from './form-engine';

package/src/contract.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+
+// The content plugin's API contract (ADR-0006/0008) — fn ids + zod input schemas, shared by the server
+// `Plugin.api` handlers and the admin client. Section structure (the editable tree) is read from the
+// React-free section registry (./define) directly by the admin, not over the wire; this contract is only the
+// value read/write API. The hydrated value's shape is per-section (typed via InferValue), so outputs are opaque.
+
+export const contentFns = {
+  sectionGet: 'content.section.get',
+  sectionSave: 'content.section.save',
+  // Routed collections (ADR-0011) — the admin manager's read/write API. Public reads (list / by-slug) are SSR
+  // server-direct (exported from the package), not RPC, like the section page reads.
+  collectionList: 'content.collection.list',
+  collectionGetForEdit: 'content.collection.getForEdit',
+  collectionSave: 'content.collection.save',
+  collectionDelete: 'content.collection.delete',
+  collectionReorder: 'content.collection.reorder',
+} as const;
+
+/** Identifies a section instance: which page it sits on + which section it is. */
+export const sectionRef = z.object({ page: z.string().min(1), section: z.string().min(1) });
+export type SectionRefDto = z.infer<typeof sectionRef>;
+
+/** Save payload: the section ref + the editor's value (validated server-side against the section schema). */
+export const sectionSaveInput = sectionRef.extend({ value: z.unknown() });
+export type SectionSaveInputDto = z.infer<typeof sectionSaveInput>;
+
+/** List a collection's entries (admin manager). */
+export const collectionListInput = z.object({
+  collection: z.string().min(1),
+  limit: z.number().int().positive().optional(),
+  offset: z.number().int().nonnegative().optional(),
+});
+export type CollectionListInputDto = z.infer<typeof collectionListInput>;
+
+/** Identifies one collection entry by id. */
+export const collectionItemRef = z.object({
+  collection: z.string().min(1),
+  id: z.string().min(1),
+});
+export type CollectionItemRefDto = z.infer<typeof collectionItemRef>;
+
+/** Save payload: the collection + slug + editor value; `id` omitted creates, present updates. */
+export const collectionSaveInput = z.object({
+  collection: z.string().min(1),
+  id: z.string().min(1).optional(),
+  slug: z.string(),
+  value: z.unknown(),
+});
+export type CollectionSaveInputDto = z.infer<typeof collectionSaveInput>;
+
+/** Reorder payload: the collection + the entry ids in their new order. */
+export const collectionReorderInput = z.object({
+  collection: z.string().min(1),
+  orderedIds: z.array(z.string().min(1)),
+});
+export type CollectionReorderInputDto = z.infer<typeof collectionReorderInput>;

package/src/db/schema.ts

@@ -0,0 +1,70 @@
+import {
+  index,
+  integer,
+  jsonb,
+  pgSchema,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from 'drizzle-orm/pg-core';
+
+// Content tables live in the shared `app` schema (ADR-0003). The plugin references the schema by NAME via its
+// own pgSchema('app') instance — it must not import @saena-io/core internals (§13); `app` itself is created by
+// the core migration, which runs before plugin migrations (runPluginMigrations, ADR-0006).
+const appSchema = pgSchema('app');
+
+/**
+ * A section's content VALUES for one page (ADR-0008). Structure (which pages, which sections, which fields) is
+ * CODE — this table holds only the editable content: `config` is the non-text JSON (discriminants, hrefs,
+ * scalars, list item ids + order, custom-field data), and every translatable leaf lives in the i18n store as a
+ * key (`content.<page>.<section>.…`), never here. v1 is live-edit (no draft/published columns).
+ */
+export const contentSectionValues = appSchema.table(
+  'content_section_values',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    /** Route id of the page this section instance belongs to (e.g. 'home', 'about'). */
+    page: text('page').notNull(),
+    /** Section id within the page composition. */
+    section: text('section').notNull(),
+    /** The section value projected to config (translatable leaves blanked — they live in i18n). */
+    config: jsonb('config').$type<unknown>().notNull().default({}),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [uniqueIndex('content_section_values_page_section_uq').on(t.page, t.section)],
+);
+
+export type ContentSectionRow = typeof contentSectionValues.$inferSelect;
+
+/**
+ * A routed COLLECTION entry — one row per repeatable, individually-routed item (News article, team member,
+ * event) declared via `defineCollection` (ADR-0011). Unlike a section (one row per page slot), a collection has
+ * many rows; each carries its own `slug` (the `$slug` route segment), the blanked `config` projection, and an
+ * author-controlled `sortOrder`. Every translatable leaf lives in the i18n store rooted at the row's STABLE id
+ * (`content.collection.<collection>.<id>.…`), so reorder/rename never re-keys or orphans translations. Live-edit
+ * (no draft/published columns yet — additive when draft/publish lands).
+ */
+export const contentCollectionItems = appSchema.table(
+  'content_collection_items',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    /** The `defineCollection` id this entry belongs to (e.g. 'news', 'programs'). */
+    collection: text('collection').notNull(),
+    /** URL segment for the entry's detail route; unique within a collection. */
+    slug: text('slug').notNull(),
+    /** The entry value projected to config (translatable leaves blanked — they live in i18n). */
+    config: jsonb('config').$type<unknown>().notNull().default({}),
+    /** Author-controlled order for the list/archive view. */
+    sortOrder: integer('sort_order').notNull().default(0),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('content_collection_items_collection_slug_uq').on(t.collection, t.slug),
+    index('content_collection_items_collection_order_idx').on(t.collection, t.sortOrder),
+  ],
+);
+
+export type ContentCollectionRow = typeof contentCollectionItems.$inferSelect;

package/src/define.ts

@@ -0,0 +1,92 @@
+import type { FieldDecl, InferValue } from './field';
+
+// Section + page DEFINITIONS — the React-free half of "structure is code" (ADR-0008). A section author declares
+// a section's id, label, and field schema here (the schema drives admin form + validation + i18n + the public
+// value type); the section's React component is wired separately in the ./public entry, so this registry stays
+// React-free and the server graph can read schemas without pulling React. Pages compose section ids in code.
+
+export interface SectionDef<S extends FieldDecl = FieldDecl> {
+  id: string;
+  label: string;
+  schema: S;
+}
+
+const sections = new Map<string, SectionDef>();
+
+/** Declare a content section's schema (registers it for the admin form, the server service, and key derivation). */
+export function defineSection<S extends FieldDecl>(def: SectionDef<S>): SectionDef<S> {
+  sections.set(def.id, def);
+  return def;
+}
+
+export function getSection(id: string): SectionDef | undefined {
+  return sections.get(id);
+}
+export function allSections(): SectionDef[] {
+  return [...sections.values()];
+}
+
+/** The fully-typed content a section's public component receives, derived from its schema declaration. */
+export type SectionValue<D extends SectionDef> = D extends SectionDef<infer S>
+  ? InferValue<S>
+  : never;
+
+/**
+ * A routed COLLECTION definition (ADR-0011) — a repeatable, individually-routed content type. Like a section,
+ * the `schema` drives the admin manager, validation, i18n, and the public value type; unlike a section, it has
+ * many entries (rows), each with its own `slug` + detail route the dev authors. React-free.
+ */
+export interface CollectionDef<S extends FieldDecl = FieldDecl> {
+  id: string;
+  label: string;
+  schema: S;
+  /** Optional slug auto-derivation for the admin manager (always client-overridable). `from` names a sibling
+   *  field in `schema` to slugify (mirrors the `slug({ from })` field option). */
+  slug?: { from?: string };
+}
+
+const collections = new Map<string, CollectionDef>();
+
+/** Declare a routed collection (registers it for the admin manager, the server service, and key derivation). */
+export function defineCollection<S extends FieldDecl>(def: CollectionDef<S>): CollectionDef<S> {
+  collections.set(def.id, def);
+  return def;
+}
+
+export function getCollection(id: string): CollectionDef | undefined {
+  return collections.get(id);
+}
+export function allCollections(): CollectionDef[] {
+  return [...collections.values()];
+}
+
+/** One hydrated collection entry a public route renders: its identity + slug + the typed schema value. */
+export interface CollectionItem<D extends CollectionDef> {
+  id: string;
+  slug: string;
+  value: D extends CollectionDef<infer S> ? InferValue<S> : never;
+}
+
+export interface PageDef {
+  id: string;
+  /** Public path (e.g. '/', '/about') — the dev-authored route this page composition renders at. */
+  path: string;
+  label?: string;
+  /** Ordered section ids composing the page (fixed in code; the client never reorders). */
+  sections: string[];
+}
+
+const pages = new Map<string, PageDef>();
+
+/** Declare a page as a fixed, ordered composition of sections (the admin reads this tree read-only). */
+export function definePage(def: PageDef): PageDef {
+  pages.set(def.id, def);
+  return def;
+}
+
+export function getPage(id: string): PageDef | undefined {
+  return pages.get(id);
+}
+export function allPages(): PageDef[] {
+  return [...pages.values()];
+}