@caelo-cms/shared 0.10.71 → 0.11.0

package/src/lists/page-type.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Page types (epic #1107, `docs/lists.md` §5). A page type says what a
+ * page IS — News, Product, Doc — while the template stays its layout.
+ * It declares the page's properties (same field system as list entries),
+ * the templates a page of this type may use, and the vocabularies whose
+ * terms apply. Page queries filter on it; the AI reads "this module sits
+ * on three News pages" from it (CLAUDE.md §1A). Replaces `templates.kind`.
+ */
+
+import { z } from "zod";
+import { checkFieldDef, fieldDefSchema, type ListIssue } from "./fields.js";
+
+export const pageTypeDefSchema = z
+  .object({
+    slug: z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/),
+    name: z.string().min(1).max(200),
+    purpose: z.string().min(1).max(1000),
+    /** Template ids a page of this type may bind to. */
+    templates: z.array(z.string().uuid()).min(1).max(64),
+    defaultTemplate: z.string().uuid(),
+    properties: z.array(fieldDefSchema).max(32).default([]),
+    vocabularies: z
+      .array(
+        z
+          .object({
+            /** Vocabulary list id. */
+            list: z.string().uuid(),
+            cardinality: z.enum(["one", "many"]),
+            required: z.boolean().optional(),
+          })
+          .strict(),
+      )
+      .max(16)
+      .default([]),
+  })
+  .strict();
+export type PageTypeDef = z.infer<typeof pageTypeDefSchema>;
+
+/** Static checks beyond the Zod shape. */
+export function checkPageTypeDef(def: PageTypeDef): ListIssue[] {
+  const issues: ListIssue[] = [];
+  if (!def.templates.includes(def.defaultTemplate)) {
+    issues.push({
+      path: "defaultTemplate",
+      message: "defaultTemplate must be one of templates.",
+    });
+  }
+  const seen = new Set<string>();
+  def.properties.forEach((f, i) => {
+    const at = `properties[${i}]`;
+    if (seen.has(f.name)) issues.push({ path: at, message: `duplicate property "${f.name}".` });
+    seen.add(f.name);
+    if (f.type === "module") {
+      issues.push({
+        path: at,
+        message: "page properties cannot embed modules — place the module on the page instead.",
+      });
+    }
+    issues.push(...checkFieldDef(f, at));
+  });
+  const lists = new Set<string>();
+  def.vocabularies.forEach((v, i) => {
+    if (lists.has(v.list)) {
+      issues.push({ path: `vocabularies[${i}]`, message: "vocabulary listed twice." });
+    }
+    lists.add(v.list);
+  });
+  return issues;
+}

package/src/lists/refs.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * `caelo:list/<id>` — the reference a module `list` field with
+ * `bind: "shared"` stores (epic #1107, `docs/lists.md` §7). Its own file
+ * because the module field schema (`content.ts`) and the resolver both
+ * need it, and the resolver imports far more than the schema should.
+ */
+
+/** `caelo:list/<id>` */
+export const LIST_REF_RE = /^caelo:list\/([0-9a-f-]{36})$/;
+
+/** Parse `caelo:list/<id>`; null when the string is not one. */
+export function parseListRef(s: string): string | null {
+  return LIST_REF_RE.exec(s)?.[1] ?? null;
+}
+
+/** Format a shared-list reference. */
+export function formatListRef(listId: string): string {
+  return `caelo:list/${listId}`;
+}

package/src/lists/render-data.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * What a render needs to resolve lists, loaded in one batch per preview
+ * or per build (epic #1107, `docs/lists.md` §10). The admin side builds it
+ * (`admin-core/src/lists/load.ts`: draft overlay in previews, published
+ * state in builds); the shared resolver (`resolve.ts`) consumes it. After
+ * loading, everything is pure and synchronous — the same split as
+ * `SiteLinkIndex` for links.
+ */
+
+import type { LinkPageVariant } from "../link-refs.js";
+import type { ListItem } from "./items.js";
+import type { ListTypeDef } from "./list-type.js";
+import type { PageTypeDef } from "./page-type.js";
+
+/** A list type as loaded (draft view in previews). */
+export interface LoadedListType {
+  readonly id: string;
+  readonly def: ListTypeDef;
+}
+
+/** A shared list as loaded. */
+export interface LoadedList {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly typeSlug: string;
+  readonly items: readonly ListItem[];
+}
+
+/** A page type as loaded. */
+export interface LoadedPageType {
+  readonly id: string;
+  readonly def: PageTypeDef;
+}
+
+/**
+ * One page as queries, system sources and `{{page.*}}` see it. Every
+ * live page of the render's scope is listed; `inBuild` says whether a
+ * query may return it (published in this build; in previews: status
+ * published in the draft view).
+ */
+export interface ListPageRecord {
+  readonly id: string;
+  readonly title: string;
+  readonly parentId: string | null;
+  readonly pageTypeSlug: string;
+  readonly properties: Readonly<Record<string, unknown>>;
+  /** `caelo:term/<listId>/<itemId>` */
+  readonly terms: readonly string[];
+  /** ISO timestamp, null until the first Publish live. */
+  readonly firstPublishedAt: string | null;
+  readonly updatedAt: string;
+  /** SEO meta description, or null. */
+  readonly summary: string | null;
+  /** `caelo:media/<id>` social image, or null. */
+  readonly image: string | null;
+  readonly inBuild: boolean;
+}
+
+/** Media metadata for `{{f.alt}}`, `{{f.width}}`, `{{f.height}}`. URLs come from the link resolver. */
+export interface ListMediaRecord {
+  readonly id: string;
+  readonly alt: string | null;
+  readonly width: number | null;
+  readonly height: number | null;
+}
+
+/**
+ * A plugin's `list-resolve` answer for one output variant. Keys are
+ * value addresses (`address.ts`). An overlay may replace values and hide
+ * entries; it can never add, remove or reorder entries.
+ */
+export interface ListVariantOverlay {
+  readonly values: ReadonlyMap<string, unknown>;
+  /** Addresses of hidden entries: `list/<listId>/item/<itemId>` or `instance/<id>/<field>/item/<itemId>`. */
+  readonly hidden: ReadonlySet<string>;
+}
+
+/** An entry a plugin list source produced for one page. Values follow the source's node definition. */
+export interface PluginSourceEntry {
+  readonly id: string;
+  readonly values: Readonly<Record<string, unknown>>;
+}
+
+export interface ListRenderData {
+  /** Keyed by list type slug. */
+  readonly listTypes: ReadonlyMap<string, LoadedListType>;
+  /** Keyed by list id. */
+  readonly lists: ReadonlyMap<string, LoadedList>;
+  /** Keyed by page type slug. */
+  readonly pageTypes: ReadonlyMap<string, LoadedPageType>;
+  /** Keyed by page id. */
+  readonly pages: ReadonlyMap<string, ListPageRecord>;
+  /** Keyed by media id. */
+  readonly media: ReadonlyMap<string, ListMediaRecord>;
+  /** The `link-resolve` page partition (same map the link index uses). */
+  readonly pageVariants?: ReadonlyMap<string, LinkPageVariant>;
+  /** `list-resolve` overlays keyed by variant. */
+  readonly overlays?: ReadonlyMap<string, ListVariantOverlay>;
+  /** `site_settings.site_language`, for `{{date.formatted}}`. */
+  readonly siteLanguage: string;
+}
+
+/** Render dependencies one page collected (build manifest `render-deps.json`). */
+export interface ListRenderDeps {
+  readonly lists: readonly string[];
+  readonly listTypes: readonly string[];
+  /** Normalised query filters (page type, terms, parent) the page rendered. */
+  readonly queries: readonly {
+    readonly pageType: string | null;
+    readonly terms: readonly string[];
+    readonly parent: string | null;
+  }[];
+  /** System sources that depend on the page tree (breadcrumbs, children, siblings, term_pages). */
+  readonly pageTree: boolean;
+  /**
+   * Pages a system source (breadcrumbs, children, siblings) rendered as
+   * entries. Those entries expose the page's values (`props`, `terms`,
+   * `updated_at`), so editing any of them must rebuild this page too —
+   * `pageTree` alone only covers title / parent / build membership.
+   */
+  readonly pages: readonly string[];
+}

package/src/lists/render-deps.test.ts

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Incremental build selection over `render-deps.json` (epic #1107,
+ * `docs/lists.md` §10): exactly the pages a change reaches.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { PAGE, PAGES, TERM } from "./list-fixtures.test.js";
+import type { ListRenderDeps } from "./render-data.js";
+import {
+  mergeRenderDeps,
+  parseRenderDeps,
+  type RenderDepsPageAttrs,
+  renderDepsAttrs,
+  selectDependentPages,
+} from "./render-deps.js";
+
+const NONE: ListRenderDeps = { lists: [], listTypes: [], queries: [], pageTree: false, pages: [] };
+const LIST_A = "00000000-0000-4000-8000-00000000aaaa";
+
+const deps = mergeRenderDeps(
+  null,
+  new Map<string, ListRenderDeps>([
+    // The home page shows the header menu and "latest news".
+    [
+      PAGE.home,
+      {
+        ...NONE,
+        lists: [LIST_A],
+        listTypes: ["menu"],
+        queries: [{ pageType: "news", terms: [], parent: null }],
+      },
+    ],
+    // About shows breadcrumbs.
+    [PAGE.about, { ...NONE, pageTree: true }],
+    // Team shows "related: events".
+    [PAGE.team, { ...NONE, queries: [{ pageType: null, terms: [TERM.event], parent: null }] }],
+    [PAGE.news, NONE],
+  ]),
+  PAGES,
+);
+const current = (patch: Partial<Record<string, Partial<RenderDepsPageAttrs>>> = {}) =>
+  new Map(PAGES.map((p) => [p.id, { ...renderDepsAttrs(p), ...(patch[p.id] ?? {}) }] as const));
+
+describe("selectDependentPages", () => {
+  it("a changed list rebuilds the pages that read it", () => {
+    const got = selectDependentPages(
+      deps,
+      { pageIds: [], listIds: [LIST_A], listTypeSlugs: [] },
+      current(),
+    );
+    expect([...got]).toEqual([PAGE.home]);
+  });
+
+  it("a changed list type rebuilds the pages that read lists of it", () => {
+    const got = selectDependentPages(
+      deps,
+      { pageIds: [], listIds: [], listTypeSlugs: ["menu"] },
+      current(),
+    );
+    expect([...got]).toEqual([PAGE.home]);
+  });
+
+  it("publishing a News page rebuilds exactly the pages whose query matches it", () => {
+    // The draft enters the build: it now matches "latest news" (home);
+    // its title / build membership change hits the page-tree reader (about).
+    const got = selectDependentPages(
+      deps,
+      { pageIds: [PAGE.newsDraft], listIds: [], listTypeSlugs: [] },
+      current({ [PAGE.newsDraft]: { inBuild: true } }),
+    );
+    expect([...got].sort()).toEqual([PAGE.home, PAGE.about].sort());
+  });
+
+  it("a page that LEFT a filter reaches the pages that rendered it", () => {
+    // Meetup loses the "event" term: Team's related query showed it before.
+    const got = selectDependentPages(
+      deps,
+      { pageIds: [PAGE.newsB], listIds: [], listTypeSlugs: [] },
+      current({ [PAGE.newsB]: { terms: [] } }),
+    );
+    expect(got.has(PAGE.team)).toBe(true);
+    expect(got.has(PAGE.home)).toBe(true);
+    expect(got.has(PAGE.about)).toBe(false);
+  });
+
+  it("a content edit that changes no filter attribute reaches no page-tree reader", () => {
+    const got = selectDependentPages(
+      deps,
+      { pageIds: [PAGE.home], listIds: [], listTypeSlugs: [] },
+      current(),
+    );
+    expect(got.size).toBe(0);
+  });
+});
+
+describe("render-deps.json", () => {
+  it("a property-only edit of a page a system source rendered rebuilds that reader (#1121 review)", () => {
+    // Team lists its children; News is one of them. Editing News' props
+    // changes no tree attribute, but Team shows News' values.
+    const withChildren = mergeRenderDeps(
+      deps,
+      new Map([[PAGE.team, { ...NONE, pageTree: true, pages: [PAGE.news] }]]),
+      PAGES,
+    );
+    const got = selectDependentPages(
+      withChildren,
+      { pageIds: [PAGE.news], listIds: [], listTypeSlugs: [] },
+      current(),
+    );
+    expect(got.has(PAGE.team)).toBe(true);
+    expect(got.has(PAGE.about)).toBe(false);
+  });
+
+  it("round-trips and merges an incremental build into the previous file", () => {
+    const parsed = parseRenderDeps(JSON.stringify(deps));
+    expect(parsed).toEqual(deps);
+    const merged = mergeRenderDeps(
+      parsed,
+      new Map([[PAGE.news, { ...NONE, pageTree: true }]]),
+      PAGES,
+    );
+    expect(merged.pages[PAGE.news]?.pageTree).toBe(true);
+    expect(merged.pages[PAGE.home]).toEqual(deps.pages[PAGE.home] as ListRenderDeps);
+  });
+
+  it("an unknown version reads as no deps (a full build follows)", () => {
+    expect(parseRenderDeps(JSON.stringify({ version: 0, pages: {}, index: {} }))).toBeNull();
+    expect(parseRenderDeps(null)).toBeNull();
+  });
+});

package/src/lists/render-deps.ts

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Render dependencies of a build (epic #1107, `docs/lists.md` §10): which
+ * lists, list types, page queries and page-tree sources every page read,
+ * written by the static generator as `render-deps.json`, and the
+ * selection an incremental build runs on it — every page whose deps
+ * intersect the change.
+ *
+ * A query matches by its filter (page type, terms, parent), so a page
+ * that ENTERED, LEFT or CHANGED inside a filter reaches every page that
+ * rendered that query. That is why the file keeps each page's filter
+ * attributes as of the build: "left the filter" can only be seen against
+ * what the page was before.
+ *
+ * Cost: one pass over the recorded deps per change set — O(changes ×
+ * deps), never a re-render of the site to find out.
+ */
+
+import type { ListPageRecord, ListRenderDeps } from "./render-data.js";
+
+export const RENDER_DEPS_FILE = "render-deps.json";
+export const RENDER_DEPS_VERSION = 2;
+
+/** A page's filter-relevant attributes as of a build. */
+export interface RenderDepsPageAttrs {
+  readonly pageType: string;
+  readonly terms: readonly string[];
+  readonly parent: string | null;
+  readonly title: string;
+  readonly inBuild: boolean;
+}
+
+/** `render-deps.json`. */
+export interface RenderDepsFile {
+  readonly version: typeof RENDER_DEPS_VERSION;
+  /** Per rendered page: what its render read. */
+  readonly pages: Readonly<Record<string, ListRenderDeps>>;
+  /** Per known page: its filter attributes when the build ran. */
+  readonly index: Readonly<Record<string, RenderDepsPageAttrs>>;
+}
+
+/** The attributes {@link RenderDepsFile.index} keeps for a page. */
+export function renderDepsAttrs(p: ListPageRecord): RenderDepsPageAttrs {
+  return {
+    pageType: p.pageTypeSlug,
+    terms: [...p.terms].sort(),
+    parent: p.parentId,
+    title: p.title,
+    inBuild: p.inBuild,
+  };
+}
+
+/**
+ * Merge the deps of a (possibly incremental) build into the previous
+ * file: rebuilt pages replace their entry, the index is the current one.
+ */
+export function mergeRenderDeps(
+  previous: RenderDepsFile | null,
+  rebuilt: ReadonlyMap<string, ListRenderDeps>,
+  pages: Iterable<ListPageRecord>,
+): RenderDepsFile {
+  const out: Record<string, ListRenderDeps> = { ...(previous?.pages ?? {}) };
+  for (const [id, deps] of rebuilt) out[id] = deps;
+  const index: Record<string, RenderDepsPageAttrs> = {};
+  for (const p of pages) index[p.id] = renderDepsAttrs(p);
+  for (const id of Object.keys(out)) if (!index[id]) delete out[id];
+  return { version: RENDER_DEPS_VERSION, pages: out, index };
+}
+
+/** Parse a stored deps file; null when it is absent or of another version. */
+export function parseRenderDeps(raw: string | null): RenderDepsFile | null {
+  if (raw === null) return null;
+  const v = JSON.parse(raw) as Partial<RenderDepsFile>;
+  if (v.version !== RENDER_DEPS_VERSION || !v.pages || !v.index) return null;
+  return v as RenderDepsFile;
+}
+
+/** What changed since the build the deps file describes. */
+export interface RenderChange {
+  readonly pageIds: readonly string[];
+  readonly listIds: readonly string[];
+  readonly listTypeSlugs: readonly string[];
+}
+
+/**
+ * The pages an incremental build must rebuild beyond the changed pages
+ * themselves:
+ *
+ * - every page that read a changed list or list type;
+ * - for every changed page: every page whose query filter matches the
+ *   page's attributes before OR after the change (entered, left or
+ *   changed inside the filter);
+ * - every page with page-tree deps (breadcrumbs, children, siblings,
+ *   term pages) when a changed page's title, parent or build membership
+ *   changed;
+ * - every page whose system source rendered a changed page as an entry
+ *   (its `props`, `terms`, `updated_at` show there).
+ *
+ * `current` is the page index as the new build sees it.
+ */
+export function selectDependentPages(
+  deps: RenderDepsFile,
+  change: RenderChange,
+  current: ReadonlyMap<string, RenderDepsPageAttrs>,
+): Set<string> {
+  const out = new Set<string>();
+  const lists = new Set(change.listIds);
+  const types = new Set(change.listTypeSlugs);
+  const changedPages = new Set(change.pageIds);
+  const states: RenderDepsPageAttrs[] = [];
+  let treeChanged = false;
+  for (const id of change.pageIds) {
+    const before = deps.index[id];
+    const after = current.get(id);
+    if (before) states.push(before);
+    if (after) states.push(after);
+    if (
+      !before ||
+      !after ||
+      before.title !== after.title ||
+      before.parent !== after.parent ||
+      before.inBuild !== after.inBuild
+    ) {
+      treeChanged = true;
+    }
+  }
+  const matches = (q: ListRenderDeps["queries"][number], p: RenderDepsPageAttrs): boolean =>
+    (q.pageType === null || q.pageType === p.pageType) &&
+    (q.parent === null || q.parent === p.parent) &&
+    (q.terms.length === 0 || q.terms.some((t) => p.terms.includes(t)));
+  for (const [pageId, d] of Object.entries(deps.pages)) {
+    if (
+      d.lists.some((l) => lists.has(l)) ||
+      d.listTypes.some((t) => types.has(t)) ||
+      (treeChanged && d.pageTree) ||
+      d.pages.some((id) => changedPages.has(id)) ||
+      (states.length > 0 && d.queries.some((q) => states.some((s) => matches(q, s))))
+    ) {
+      out.add(pageId);
+    }
+  }
+  return out;
+}