@mosetta/content 0.0.0-stage → 0.0.10

package/src/units.ts

@@ -0,0 +1,396 @@
+// A LIVE PREFAB is a tree embedded in a page by reference and always taken at its CURRENT
+// published form. The reference names its AUTHOR, like a module's does, and no version:
+//
+//   _ns_<namespace>_t_prefab_n_<name>_v_live
+//
+// A prefab of the project itself (its namespace — a header, a styled button, the blog's frame)
+// comes from the project's content; a prefab of a library in the project's code distribution (the
+// editor's workbench — `mosetta-editor`) comes from the distribution. Which is which is the
+// caller's business (it knows the project's namespace); this module only expands.
+//
+// Expansion happens on the server before a render (the live route and the draft preview alike):
+// the node is replaced by the prefab's blocks, and the node's own children — an article — land
+// inside the prefab's OUTLET block (a frame is a prefab with an outlet). Ids of the prefab's blocks
+// are prefixed with the node's id (`<node>/<inner>`), which is how the editor tells a prefab's
+// blocks from the page's own; a setting that names a sibling block by id names it as authored (see
+// localIdOf). The prefab's structure and styles are its own; an instance may set only the OPEN
+// FIELDS the prefab declares — a button's text and address — kept in the node's `fields`. One
+// level only: a prefab inside a prefab is left as it is. Pure data in, pure data out.
+import type { IBlueprintNodeDoc, IPageDoc, IPrefabDoc, IPrefabField } from './model';
+
+export type { IBlueprintNodeDoc, IPageDoc, IPrefabDoc, IPrefabField } from './model';
+
+export const PREFAB_REFERENCE_RE = /^_ns_([a-z0-9][a-z0-9-]*)_t_prefab_n_([a-z][A-Za-z0-9]*)_v_live$/;
+/** kept for the callers that say "unit": a live prefab is the only kind */
+export const UNIT_REFERENCE_RE = PREFAB_REFERENCE_RE;
+
+export interface IUnitRef {
+  /** the author: the project's namespace, or a library's */
+  readonly namespace: string;
+  readonly name: string;
+}
+
+/** the reference a page tree uses to embed a prefab live */
+export const prefabReference = (namespace: string, name: string): string => `_ns_${namespace}_t_prefab_n_${name}_v_live`;
+export const unitReference = prefabReference;
+
+export const unitOf = (reference: string): IUnitRef | null => {
+  const match = PREFAB_REFERENCE_RE.exec(reference);
+  return match ? { namespace: match[1], name: match[2] } : null;
+};
+
+/** the prefab's name — null for a module reference */
+export const unitNameOf = (reference: string): string | null => unitOf(reference)?.name ?? null;
+
+/** where a distribution keeps a library's prefab in its public code store (what the build writes) */
+export const prefabPath = (namespace: string, name: string): string => `prefabs/${namespace}/${name}.json`;
+
+/** the outlet block: whatever module is named `outlet` (the ui-kit ships one) — its children are the page */
+export const isOutletReference = (reference: string): boolean => /_t_component_n_outlet_v_/.test(reference);
+
+/** the separator between a prefab node's id and the ids of the blocks it expands into */
+export const UNIT_ID_SEPARATOR = '/';
+
+/** the prefab node an expanded block belongs to, or null for a page's own block */
+export const unitOwnerOf = (id: string): string | null => {
+  const at = id.indexOf(UNIT_ID_SEPARATOR);
+  return at > 0 ? id.slice(0, at) : null;
+};
+
+/**
+ * A block's id as its document authored it — the expansion prefix dropped. A setting that names a
+ * sibling block (a dock's panel naming its child) was written against these ids, so a block
+ * resolving such a setting compares local ids: it works the same in a page and inside a prefab.
+ */
+export const localIdOf = (id: string): string => id.slice(id.lastIndexOf(UNIT_ID_SEPARATOR) + 1);
+
+/** an instance's values of the open fields: block id → setting → value */
+export type TFieldValues = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+
+/** the settings key an instance keeps its open fields' values under */
+export const FIELDS_SETTING = 'fields';
+
+export interface IExpandedUnit extends IUnitRef {
+  readonly rev: number;
+}
+
+export interface IUnitSource {
+  readonly root: IBlueprintNodeDoc;
+  /** the prefab's revision (a content prefab) or content digest (a distribution's) — keys the render cache */
+  readonly rev: number;
+  readonly fields?: readonly IPrefabField[];
+}
+
+export type TUnitLoader = (unit: IUnitRef) => Promise<IUnitSource | null>;
+
+const fieldValuesOf = (node: IBlueprintNodeDoc): TFieldValues => {
+  const raw: unknown = node.settings?.[FIELDS_SETTING];
+  return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as TFieldValues : {};
+};
+
+/** the prefab's blocks, ids prefixed, the instance's values in the open fields — no other setting */
+function instantiate(node: IBlueprintNodeDoc, prefix: string, open: ReadonlyMap<string, readonly string[]>, values: TFieldValues): IBlueprintNodeDoc {
+  const settable = open.get(node.id) ?? [];
+  const own = values[node.id] ?? {};
+  const given = settable.filter((s) => own[s] !== undefined);
+  const settings = given.length ? { ...(node.settings ?? {}), ...Object.fromEntries(given.map((s) => [s, own[s]])) } : node.settings;
+  return {
+    ...node,
+    ...(settings ? { settings } : {}),
+    id: `${prefix}${UNIT_ID_SEPARATOR}${node.id}`,
+    children: (node.children ?? []).map((c) => instantiate(c, prefix, open, values)),
+  };
+}
+
+const openFields = (fields: readonly IPrefabField[] | undefined): Map<string, string[]> => {
+  const open = new Map<string, string[]>();
+  for (const f of fields ?? []) open.set(f.node, [...(open.get(f.node) ?? []), f.setting]);
+  return open;
+};
+
+/** the outlet's children become the page's blocks; the first outlet in document order wins */
+export function fillOutlet(nodes: IBlueprintNodeDoc[], body: IBlueprintNodeDoc[]): { nodes: IBlueprintNodeDoc[]; filled: boolean } {
+  let filled = false;
+  const walk = (node: IBlueprintNodeDoc): IBlueprintNodeDoc => {
+    if (filled) return node;
+    if (isOutletReference(node.reference)) {
+      filled = true;
+      return { ...node, children: body };
+    }
+    return { ...node, children: (node.children ?? []).map(walk) };
+  };
+  return { nodes: nodes.map(walk), filled };
+}
+
+/** the node's slot travels to what replaces it: a frame in a `footer` slot stays in the footer */
+function withSlot(nodes: IBlueprintNodeDoc[], slot: string | undefined): IBlueprintNodeDoc[] {
+  return nodes.map((node) => {
+    const { slot: own, ...rest } = node;
+    void own;
+    return slot === undefined ? rest : { ...rest, slot };
+  });
+}
+
+/** blocks as rendered hold the PREVIOUS body inside their outlet — emptied before refilling */
+function stripBody(node: IBlueprintNodeDoc): IBlueprintNodeDoc {
+  if (isOutletReference(node.reference)) return { ...node, children: [] };
+  return { ...node, children: (node.children ?? []).map(stripBody) };
+}
+
+/** the instance's current field values put onto blocks already expanded (ids carry the prefix) */
+function refill(node: IBlueprintNodeDoc, values: TFieldValues): IBlueprintNodeDoc {
+  const own = values[localIdOf(node.id)];
+  const settings = own ? { ...(node.settings ?? {}), ...own } : node.settings;
+  return { ...node, ...(settings ? { settings } : {}), children: (node.children ?? []).map((c) => refill(c, values)) };
+}
+
+/**
+ * A prefab node expanded from blocks ALREADY RENDERED: the editor's live tree updates carry the
+ * raw document, and the preview realm re-expands it from what it shows right now — no server
+ * round trip while the author types (an instance's field included). Unknown blocks (a prefab
+ * inserted a moment ago) stay a raw node until the next server render.
+ */
+export function expandUnitsFrom(current: IBlueprintNodeDoc, next: IBlueprintNodeDoc): IBlueprintNodeDoc {
+  const chrome = new Map<string, IBlueprintNodeDoc[]>();
+  // a prefab's top blocks are kept under its node's id; the descent goes on below them — another
+  // prefab's blocks may sit in its outlet (a page's frame inside the site's theme)
+  const collect = (nodes: readonly IBlueprintNodeDoc[], within: string | null) => {
+    for (const node of nodes) {
+      const owner = unitOwnerOf(node.id);
+      if (owner !== null && owner !== within) {
+        chrome.set(owner, [...(chrome.get(owner) ?? []), node]);
+        collect(node.children ?? [], owner);
+        continue;
+      }
+      collect(node.children ?? [], within);
+    }
+  };
+  collect(current.children ?? [], null);
+  const expand = (nodes: readonly IBlueprintNodeDoc[]): IBlueprintNodeDoc[] => nodes.flatMap((node) => {
+    const body = expand(node.children ?? []);
+    if (unitOf(node.reference) === null) return [{ ...node, children: body }];
+    const known = chrome.get(node.id);
+    if (!known) return [{ ...node, children: body }];
+    // the outlet is refilled with the body as it is now; the fields with the instance's values
+    const values = fieldValuesOf(node);
+    const { nodes: filled, filled: ok } = fillOutlet(known.map((n) => refill(stripBody(n), values)), body);
+    return withSlot(ok ? filled : [...filled, ...body], node.slot);
+  });
+  return { ...next, children: expand(next.children ?? []) };
+}
+
+const cacheName = (u: IUnitRef): string => `${u.namespace}.${u.name}`;
+
+/**
+ * Every prefab node in the page replaced by its prefab's blocks, the node's children inside the
+ * outlet, the instance's open fields filled. A prefab that cannot be loaded (unpublished,
+ * deleted) leaves the node's children in place — the article still renders, only the frame is
+ * missing. Returns the expanded document and the prefabs it used with their revisions: they
+ * belong in the render's cache key.
+ */
+export async function expandUnits(doc: IBlueprintNodeDoc, load: TUnitLoader): Promise<{ doc: IBlueprintNodeDoc; units: IExpandedUnit[] }> {
+  const units: IExpandedUnit[] = [];
+  const loaded = new Map<string, Promise<IUnitSource | null>>();
+  const source = (unit: IUnitRef) => {
+    const key = `${unit.namespace}:${unit.name}`;
+    let pending = loaded.get(key);
+    if (!pending) {
+      pending = load(unit);
+      loaded.set(key, pending);
+    }
+    return pending;
+  };
+  // every prefab the tree places is asked for at once — a prefab inside another one's place would
+  // otherwise wait for the outer one's read
+  const prefetch = (node: IBlueprintNodeDoc) => {
+    const ref = unitOf(node.reference);
+    if (ref) void source(ref).catch(() => null);
+    for (const child of node.children ?? []) prefetch(child);
+  };
+  prefetch(doc);
+  const expandChildren = async (children: readonly IBlueprintNodeDoc[]): Promise<IBlueprintNodeDoc[]> => {
+    const out: IBlueprintNodeDoc[] = [];
+    for (const child of children) {
+      const ref = unitOf(child.reference);
+      if (ref === null) {
+        out.push({ ...child, children: await expandChildren(child.children ?? []) });
+        continue;
+      }
+      const body = await expandChildren(child.children ?? []);
+      const unit = await source(ref);
+      if (!unit) {
+        out.push(...withSlot(body, child.slot));
+        continue;
+      }
+      if (!units.some((u) => u.namespace === ref.namespace && u.name === ref.name)) units.push({ ...ref, rev: unit.rev });
+      const open = openFields(unit.fields);
+      const values = fieldValuesOf(child);
+      const chrome = (unit.root.children ?? []).map((n) => instantiate(n, child.id, open, values));
+      const { nodes, filled } = fillOutlet(chrome, body);
+      out.push(...withSlot(filled ? nodes : [...nodes, ...body], child.slot));
+    }
+    return out;
+  };
+  return { doc: { ...doc, children: await expandChildren(doc.children ?? []) }, units: units.sort((a, b) => cacheName(a).localeCompare(cacheName(b))) };
+}
+
+/** the cache-key suffix naming the prefabs a render depends on: `+acme.header@3+mosetta-editor.workbench@2711` */
+export const unitsCacheSuffix = (units: readonly IExpandedUnit[]): string => units.map((u) => `+${cacheName(u)}@${u.rev}`).join('');
+
+/** a small, stable number for a text — a distribution's prefab has no revision counter, its digest is its revision */
+export function textDigest(text: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * The loader of a distribution's prefabs: `<publicBase>prefabs/<namespace>/<name>.json`,
+ * revalidated by ETag on every call (the deploy uploads prefabs uncached, with the catalog), its
+ * revision the digest of what was read. Unreachable or absent → null, and the node renders
+ * without it.
+ */
+export function prefabLoader(publicBase: string | ((namespace: string) => string), fetchImpl: typeof fetch = fetch): (unit: IUnitRef) => Promise<IUnitSource | null> {
+  // a library's prefabs lie with its code: one base, or a base per namespace (its code source)
+  const baseOf = typeof publicBase === 'function' ? publicBase : () => publicBase;
+  const known = new Map<string, { etag: string | null; unit: IUnitSource }>();
+  return async (ref) => {
+    const url = `${baseOf(ref.namespace)}${prefabPath(ref.namespace, ref.name)}`;
+    const cached = known.get(url);
+    let res: Response;
+    try {
+      res = await fetchImpl(url, { headers: cached?.etag ? { 'If-None-Match': cached.etag } : {} });
+    } catch {
+      return cached?.unit ?? null;
+    }
+    if (cached && res.status === 304) return cached.unit;
+    if (!res.ok) return null;
+    const text = await res.text();
+    let parsed: { root?: unknown; fields?: unknown };
+    try {
+      parsed = JSON.parse(text) as { root?: unknown; fields?: unknown };
+    } catch {
+      return null;
+    }
+    if (!parsed.root || typeof parsed.root !== 'object') return null;
+    const unit: IUnitSource = {
+      root: parsed.root as IBlueprintNodeDoc,
+      rev: textDigest(text),
+      ...(Array.isArray(parsed.fields) ? { fields: parsed.fields as IPrefabField[] } : {}),
+    };
+    known.set(url, { etag: res.headers.get('ETag'), unit });
+    return unit;
+  };
+}
+
+/** the project's own namespace, as its content config names it (`config.json`: `namespace`) — or null */
+export function projectNamespaceOf(config: unknown): string | null {
+  const ns = (config as { namespace?: unknown } | null)?.namespace;
+  return typeof ns === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(ns) ? ns : null;
+}
+
+/**
+ * The loader of the project's own prefabs, over a content store's read: the prefab's live
+ * revision (`prefabs/<name>/prefab.json` → `versions/<live>.json`). A prefab document is a tree like
+ * a page's — its root's children are what an instance expands into — with its open fields beside.
+ */
+export function contentPrefabLoader(get: (key: string) => Promise<Response>): (name: string) => Promise<IUnitSource | null> {
+  return async (name) => {
+    const metaRes = await get(`prefabs/${name}/prefab.json`);
+    if (!metaRes.ok) return null;
+    const meta = (await metaRes.json()) as { live?: unknown };
+    if (typeof meta.live !== 'number') return null;
+    const docRes = await get(`prefabs/${name}/versions/${meta.live}.json`);
+    if (!docRes.ok) return null;
+    const doc = (await docRes.json()) as IBlueprintNodeDoc & { root?: IBlueprintNodeDoc; fields?: unknown };
+    return {
+      root: doc.root ?? doc,
+      rev: meta.live,
+      ...(Array.isArray(doc.fields) ? { fields: doc.fields as IPrefabField[] } : {}),
+    };
+  };
+}
+
+// ---- a prefab in the editor ----
+//
+// The editor edits every tree in a PAGE's shape — one session, one canvas, one tree panel for
+// both. A prefab opens as a page whose root is the prefab's root, its open fields and its draft's
+// working fields along; the pattern is the site's root, where the canvas previews it. What is
+// stored stays a prefab: the shape is converted back on every write.
+
+/** the path the canvas previews a prefab under */
+export const PREFAB_CANVAS_PATTERN = '/';
+
+/** a prefab (a draft or a revision) as the editor edits it */
+export function prefabAsPage(prefab: IPrefabDoc): IPageDoc {
+  const { root, fields, devOnly, history, redo, seq, createdAt, baseRev, title } = prefab;
+  return {
+    ...root,
+    pattern: PREFAB_CANVAS_PATTERN,
+    ...(fields ? { fields } : {}),
+    ...(devOnly ? { devOnly } : {}),
+    ...(seq !== undefined ? { seq } : {}),
+    ...(createdAt !== undefined ? { createdAt } : {}),
+    ...(baseRev !== undefined ? { baseRev } : {}),
+    ...(title !== undefined ? { title } : {}),
+    ...(history ? { history } : {}),
+    ...(redo ? { redo } : {}),
+  };
+}
+
+/** what the editor wrote, stored as the prefab it is: the page's own things (route, meta) dropped */
+export function pageAsPrefab(page: IPageDoc): IPrefabDoc {
+  const { id, reference, children, slot, settings, ssr, fields, devOnly, history, redo, seq, createdAt, baseRev, title } = page;
+  const root: IBlueprintNodeDoc = {
+    id,
+    reference,
+    children,
+    ...(slot !== undefined ? { slot } : {}),
+    ...(settings !== undefined ? { settings } : {}),
+    ...(ssr !== undefined ? { ssr } : {}),
+  };
+  return {
+    root,
+    ...(fields ? { fields } : {}),
+    ...(devOnly ? { devOnly } : {}),
+    ...(seq !== undefined ? { seq } : {}),
+    ...(createdAt !== undefined ? { createdAt } : {}),
+    ...(baseRev !== undefined ? { baseRev } : {}),
+    ...(title !== undefined ? { title } : {}),
+    ...(history ? { history } : {}),
+    ...(redo ? { redo } : {}),
+  };
+}
+
+/** the namespace a module or prefab reference is authored under (`_ns_<namespace>_t_…`), or null */
+export const namespaceOfReference = (reference: string): string | null => /^_ns_(.+?)_t_/.exec(reference)?.[1] ?? null;
+
+/**
+ * A document without the blocks of DISCONNECTED distributions (ADR-0059): every node whose module
+ * (or prefab) is authored under one of `namespaces` leaves, with what it holds. The site renders
+ * what is left, on the server and in the browser alike — the browser gets this very document, so
+ * it never asks for a disconnected block. Untouched branches keep their identity.
+ *
+ * With `standIn`, such a node is not dropped but REPLACED by what it returns — the editor's preview
+ * shows a placeholder where the block stood, so the author sees it and can take it out.
+ */
+export function withoutDistributions<T extends IBlueprintNodeDoc>(
+  doc: T,
+  namespaces: readonly string[],
+  standIn?: (node: IBlueprintNodeDoc) => IBlueprintNodeDoc,
+): T {
+  if (!namespaces.length) return doc;
+  const off = new Set(namespaces);
+  const isOff = (node: IBlueprintNodeDoc) => off.has(namespaceOfReference(node.reference) ?? '');
+  const prune = <N extends IBlueprintNodeDoc>(node: N): N => {
+    const children = node.children ?? [];
+    const kept = standIn
+      ? children.map((child) => (isOff(child) ? standIn(child) : prune(child)))
+      : children.filter((child) => !isOff(child)).map(prune);
+    return kept.length === children.length && kept.every((child, i) => child === children[i]) ? node : { ...node, children: kept };
+  };
+  return prune(doc);
+}

package/src/versions.ts

@@ -0,0 +1,40 @@
+// VERSIONS of distributions (ADR-0061). A module's full id carries its distribution's version in
+// the encoded form (`…_v_1_2_0`), the catalog names it dotted (`1.2.0`); a deployed version never
+// changes, and versions compare as the numbers they are — `0.0.10` is after `0.0.9`.
+
+/** the version a reference names, dotted (`1.2.0`), or null for one that names none (`_v_live`) */
+export function versionOfReference(reference: string): string | null {
+  const encoded = /_v_(\d+(?:_\d+)*)$/.exec(reference)?.[1];
+  return encoded ? encoded.replace(/_/g, '.') : null;
+}
+
+/** a version as a full id spells it */
+export const encodeVersion = (version: string): string => version.trim().replace(/[^a-zA-Z0-9]/g, '_');
+
+/** the same module at another version */
+export function withVersion(reference: string, version: string): string {
+  return reference.replace(/_v_[A-Za-z0-9_]+$/, `_v_${encodeVersion(version)}`);
+}
+
+/** the numbers of a version, in either spelling (`1.2.0`, `1_2_0`) */
+const partsOf = (version: string): number[] => version.split(/[._]/).map((part) => Number.parseInt(part, 10) || 0);
+
+/** < 0 when `a` comes before `b`, > 0 after, 0 for the same version — in either spelling */
+export function compareVersions(a: string, b: string): number {
+  const left = partsOf(a);
+  const right = partsOf(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const delta = (left[i] ?? 0) - (right[i] ?? 0);
+    if (delta) return delta;
+  }
+  return 0;
+}
+
+/** the latest of some versions, or undefined for none */
+export function latestVersion(versions: Iterable<string>): string | undefined {
+  let latest: string | undefined;
+  for (const version of versions) {
+    if (latest === undefined || compareVersions(version, latest) > 0) latest = version;
+  }
+  return latest;
+}