@caelo-cms/shared 0.10.72 → 0.11.0

package/src/lists/resolve-values.ts

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Field values as template scopes (epic #1107, `docs/lists.md` §2): how
+ * a stored value of each field type reads in a template. Shared by list
+ * entries, page properties (`{{page.props.x}}`, `{{props.x}}` on query
+ * results) and plugin source entries, so every value renders the same
+ * way wherever it comes from.
+ *
+ * Internal references stay references here (`caelo:page/<id>`,
+ * `caelo:media/<id>`): the template engine resolves every reference in
+ * the finished HTML through the page's link resolver, so a link inside a
+ * list entry follows a page move exactly like a link in module HTML.
+ */
+
+import { parseLinkRef } from "../link-refs.js";
+import type { FieldDef } from "./fields.js";
+import type { ListRenderData } from "./render-data.js";
+import type { ScopeEntry, ScopeValue } from "./scope.js";
+
+export const EMPTY_TEXT: ScopeValue = { kind: "text", text: "" };
+export const FALSE: ScopeValue = { kind: "bool", value: false };
+export const TRUE: ScopeValue = { kind: "bool", value: true };
+export const EMPTY_LIST: ScopeValue = { kind: "list", entries: [] };
+
+/** A text scope value. */
+export function text(s: string): ScopeValue {
+  return { kind: "text", text: s };
+}
+
+/** A boolean scope value. */
+export function bool(v: boolean): ScopeValue {
+  return v ? TRUE : FALSE;
+}
+
+/** A record scope value over a fixed key map. */
+export function record(
+  bare: string | null,
+  present: boolean,
+  parts: Readonly<Record<string, ScopeValue>>,
+): ScopeValue {
+  return {
+    kind: "record",
+    text: bare,
+    present,
+    get: (key) => (Object.hasOwn(parts, key) ? parts[key] : undefined),
+  };
+}
+
+/** What value scopes need from the render: data plus lazy hooks into the page context. */
+export interface ValueEnv {
+  readonly data: ListRenderData;
+  /** Format an ISO date in the site language (cached formatter). */
+  formatDate(iso: string): string;
+  /**
+   * Resolve term references to vocabulary entries. `field` names the
+   * field for markers; the vocabulary lists are recorded as deps.
+   */
+  termEntries(refs: readonly string[], field: string): ScopeValue;
+}
+
+/** The empty value of a declared field — declared-but-unset never falls through to outer scopes. */
+export function emptyValueOf(field: FieldDef): ScopeValue {
+  switch (field.type) {
+    case "boolean":
+      return FALSE;
+    case "link":
+      return linkValue({ href: "" }, null);
+    case "media":
+      return record("", false, {
+        url: EMPTY_TEXT,
+        alt: EMPTY_TEXT,
+        width: EMPTY_TEXT,
+        height: EMPTY_TEXT,
+      });
+    case "date":
+      return record("", false, { formatted: EMPTY_TEXT });
+    case "term":
+      return EMPTY_LIST;
+    default:
+      return EMPTY_TEXT;
+  }
+}
+
+/** Scope value of a link: bare = href, plus `href`, `target`, `title` (internal page title). */
+export function linkValue(
+  v: { readonly href: string; readonly target?: string },
+  data: ListRenderData | null,
+): ScopeValue {
+  const ref = v.href.length > 0 ? parseLinkRef(v.href) : null;
+  const title =
+    ref?.kind === "page" && data !== null ? (data.pages.get(ref.pageId)?.title ?? "") : "";
+  return record(v.href, v.href.length > 0, {
+    href: text(v.href),
+    target: text(v.target ?? ""),
+    title: text(title),
+  });
+}
+
+/** Scope value of a media reference: bare = url (the reference, resolved later), alt/width/height. */
+export function mediaValue(ref: string, data: ListRenderData): ScopeValue {
+  const parsed = parseLinkRef(ref);
+  const meta = parsed?.kind === "media" ? data.media.get(parsed.mediaId) : undefined;
+  return record(ref, ref.length > 0, {
+    url: text(ref),
+    alt: text(meta?.alt ?? ""),
+    width: text(meta?.width === null || meta?.width === undefined ? "" : String(meta.width)),
+    height: text(meta?.height === null || meta?.height === undefined ? "" : String(meta.height)),
+  });
+}
+
+/** Scope value of a date or timestamp: bare = the stored ISO string, `formatted` in the site language. */
+export function dateValue(iso: string, env: Pick<ValueEnv, "formatDate">): ScopeValue {
+  return record(iso, iso.length > 0, { formatted: text(env.formatDate(iso)) });
+}
+
+/**
+ * Scope value of one stored field value. `undefined` / `null` read as the
+ * field's empty value; a value of the wrong shape (data drift after a
+ * type change that skipped validation) reads as the raw string form when
+ * it has one — validation happens on write, rendering never invents data.
+ */
+export function fieldValue(field: FieldDef, raw: unknown, env: ValueEnv): ScopeValue {
+  if (raw === undefined || raw === null) return emptyValueOf(field);
+  switch (field.type) {
+    case "text":
+    case "richtext":
+    case "icon":
+    case "select":
+      return typeof raw === "string" ? text(raw) : text(String(raw));
+    case "number":
+      return typeof raw === "number" ? text(String(raw)) : text(String(raw));
+    case "boolean":
+      return bool(raw === true);
+    case "link": {
+      if (typeof raw === "object" && typeof (raw as { href?: unknown }).href === "string") {
+        return linkValue(raw as { href: string; target?: string }, env.data);
+      }
+      return typeof raw === "string" ? linkValue({ href: raw }, env.data) : emptyValueOf(field);
+    }
+    case "media":
+      return typeof raw === "string" ? mediaValue(raw, env.data) : emptyValueOf(field);
+    case "date":
+      return typeof raw === "string" ? dateValue(raw, env) : emptyValueOf(field);
+    case "module": {
+      const r = raw as { moduleId?: unknown; contentInstanceId?: unknown };
+      if (typeof r.moduleId === "string" && typeof r.contentInstanceId === "string") {
+        return {
+          kind: "module",
+          ref: { moduleId: r.moduleId, contentInstanceId: r.contentInstanceId },
+        };
+      }
+      return { kind: "failed", marker: `list-malformed:${field.name}[module]` };
+    }
+    case "term":
+      return Array.isArray(raw)
+        ? env.termEntries(
+            raw.filter((x): x is string => typeof x === "string"),
+            field.name,
+          )
+        : EMPTY_LIST;
+  }
+}
+
+/**
+ * Lookup for a `select` field's option flag: `{{#f_<option>}}` is true
+ * when `f` holds `<option>`. Returns undefined when `key` is no option
+ * flag of any select field.
+ */
+export function selectFlag(
+  fields: readonly FieldDef[],
+  values: Readonly<Record<string, unknown>>,
+  key: string,
+): ScopeValue | undefined {
+  for (const f of fields) {
+    if (f.type !== "select" || !key.startsWith(`${f.name}_`)) continue;
+    const option = key.slice(f.name.length + 1);
+    if (f.options.includes(option)) return bool(values[f.name] === option);
+  }
+  return undefined;
+}
+
+/**
+ * Generic scope of an untyped value map (plugin source entries, whose
+ * node definition the host does not hand over yet): strings and numbers
+ * as text, booleans as flags, `{ href }` objects as links.
+ */
+export function untypedValue(raw: unknown): ScopeValue | undefined {
+  if (typeof raw === "string") return text(raw);
+  if (typeof raw === "number" && Number.isFinite(raw)) return text(String(raw));
+  if (typeof raw === "boolean") return bool(raw);
+  if (
+    typeof raw === "object" &&
+    raw !== null &&
+    typeof (raw as { href?: unknown }).href === "string"
+  ) {
+    return linkValue(raw as { href: string; target?: string }, null);
+  }
+  return undefined;
+}
+
+/** Position keys every entry carries: `index` (0-based), `first`, `last`, `depth` (1-based). */
+export function positionValue(
+  key: string,
+  pos: { readonly index: number; readonly count: number; readonly depth: number },
+): ScopeValue | undefined {
+  switch (key) {
+    case "index":
+      return text(String(pos.index));
+    case "first":
+      return bool(pos.index === 0);
+    case "last":
+      return bool(pos.index === pos.count - 1);
+    case "depth":
+      return text(String(pos.depth));
+    default:
+      return undefined;
+  }
+}
+
+/** A list of entries as a scope value, with `has_`/`count_` helpers derived by the caller. */
+export function listValue(entries: readonly ScopeEntry[]): ScopeValue {
+  return { kind: "list", entries };
+}

package/src/lists/resolve.test.ts

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The list resolver (epic #1107, `docs/lists.md` §6, §9, §10): every
+ * source kind, query knobs, variant scoping, overlays (replace, hide,
+ * refused changes) and the render dependencies a page records.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { LinkPageVariant } from "../link-refs.js";
+import { fixtureData, fixtureLinkIndex, ITEM, LIST, PAGE, TERM } from "./list-fixtures.test.js";
+import type { QueryKnob } from "./list-type.js";
+import type { ListVariantOverlay } from "./render-data.js";
+import {
+  createListRenderContext,
+  type ListFieldSpec,
+  type ListPageContext,
+  type ListRenderContextOptions,
+} from "./resolve.js";
+import type { ScopeEntry } from "./scope.js";
+
+function page(
+  pageId: string | null,
+  data = fixtureData(),
+  opts: ListRenderContextOptions = {},
+): ListPageContext {
+  return createListRenderContext(data, opts).forPage(pageId, {
+    linkResolver: fixtureLinkIndex(data.pageVariants).forPage(pageId),
+  });
+}
+
+function entries(
+  ctx: ListPageContext,
+  field: ListFieldSpec,
+  value?: unknown,
+): readonly ScopeEntry[] {
+  const r = ctx.resolveField(field, value, { contentInstanceId: null });
+  if (!r.ok) throw new Error(r.marker);
+  return r.entries;
+}
+
+const textOf = (e: ScopeEntry, key: string): string => {
+  const v = e.get(key);
+  if (v?.kind === "text") return v.text;
+  if (v?.kind === "record") return v.text ?? "";
+  throw new Error(`${key} is ${v?.kind}`);
+};
+
+const query = (defaults: Record<string, unknown>, editable: QueryKnob[] = []): ListFieldSpec => ({
+  name: "q",
+  listType: "links",
+  bind: "source",
+  source: { kind: "query", editable, defaults },
+});
+
+describe("query sources", () => {
+  it("returns published pages of a type, newest first, excluding drafts", () => {
+    const got = entries(
+      page(PAGE.home),
+      query({ page_type: "news", order: "published_desc", limit: 10 }),
+    );
+    expect(got.map((e) => textOf(e, "title"))).toEqual(["Meetup", "Launch day"]);
+  });
+
+  it("excludes the rendering page by default, includes it with exclude_current: false", () => {
+    const base = { page_type: "news", order: "title_asc", limit: 10 };
+    expect(entries(page(PAGE.newsA), query(base)).map((e) => e.id)).toEqual([PAGE.newsB]);
+    expect(
+      entries(page(PAGE.newsA), query({ ...base, exclude_current: false })).map((e) => e.id),
+    ).toEqual([PAGE.newsA, PAGE.newsB]);
+  });
+
+  it("filters by terms (any / all) and parent", () => {
+    const any = query({ terms: [TERM.release, TERM.event], order: "title_asc", limit: 10 });
+    expect(entries(page(PAGE.home), any).map((e) => textOf(e, "title"))).toEqual([
+      "Launch day",
+      "Meetup",
+    ]);
+    const all = query({
+      terms: [TERM.release, TERM.event],
+      terms_mode: "all",
+      order: "title_asc",
+      limit: 10,
+    });
+    expect(entries(page(PAGE.home), all)).toEqual([]);
+    const kids = query({ parent: `caelo:page/${PAGE.about}`, order: "title_asc", limit: 10 });
+    expect(entries(page(PAGE.home), kids).map((e) => textOf(e, "title"))).toEqual(["Team"]);
+  });
+
+  it("orders by a property and applies the limit", () => {
+    const q = query({ page_type: "news", order: "prop_desc:rating", limit: 1 });
+    expect(entries(page(PAGE.home), q).map((e) => textOf(e, "title"))).toEqual(["Meetup"]);
+  });
+
+  it("applies the placement's overrides only for editable knobs", () => {
+    const q = query({ page_type: "news", order: "published_desc", limit: 3 }, ["limit"]);
+    expect(entries(page(PAGE.home), q, { limit: 1 })).toHaveLength(1);
+    const r = page(PAGE.home).resolveField(q, { page_type: "page" }, { contentInstanceId: null });
+    expect(r).toEqual({ ok: false, marker: "list-malformed:q[query.page_type]" });
+  });
+
+  it("an incomplete query (no order / limit) is malformed, never guessed", () => {
+    const r = page(PAGE.home).resolveField(query({ page_type: "news" }), undefined, {
+      contentInstanceId: null,
+    });
+    expect(r).toEqual({ ok: false, marker: "list-malformed:q[query]" });
+  });
+
+  it("returns only pages of the rendering page's variant", () => {
+    const pageVariants = new Map<string, LinkPageVariant>([
+      [PAGE.home, { variant: "en", group: null }],
+      [PAGE.newsA, { variant: "en", group: null }],
+      [PAGE.newsB, { variant: "de", group: null }],
+    ]);
+    const q = query({ page_type: "news", order: "title_asc", limit: 10 });
+    const got = entries(page(PAGE.home, fixtureData({ pageVariants })), q);
+    expect(got.map((e) => e.id)).toEqual([PAGE.newsA]);
+  });
+});
+
+describe("system sources", () => {
+  const sys = (name: "breadcrumbs" | "children" | "siblings"): ListFieldSpec => ({
+    name,
+    listType: "links",
+    bind: "source",
+    source: { kind: "system", name },
+  });
+
+  it("breadcrumbs run root → current", () => {
+    expect(entries(page(PAGE.team), sys("breadcrumbs")).map((e) => textOf(e, "title"))).toEqual([
+      "About",
+      "Team",
+    ]);
+  });
+
+  it("children are the published children in title order", () => {
+    expect(entries(page(PAGE.news), sys("children")).map((e) => textOf(e, "title"))).toEqual([
+      "Launch day",
+      "Meetup",
+    ]);
+  });
+
+  it("siblings include the current page, marked is_current", () => {
+    const got = entries(page(PAGE.newsA), sys("siblings"));
+    expect(got.map((e) => textOf(e, "title"))).toEqual(["Launch day", "Meetup"]);
+    expect(got.map((e) => e.get("is_current"))).toEqual([
+      { kind: "bool", value: true },
+      { kind: "bool", value: false },
+    ]);
+  });
+
+  it("outside any page, page-shaped system sources are empty", () => {
+    expect(entries(page(null), sys("breadcrumbs"))).toEqual([]);
+  });
+});
+
+describe("overlays (list-resolve)", () => {
+  const variants = new Map<string, LinkPageVariant>([[PAGE.home, { variant: "de", group: null }]]);
+  const HEADER: ListFieldSpec = {
+    name: "menu",
+    listType: "menu",
+    bind: "shared",
+    list: `caelo:list/${LIST.header}`,
+  };
+  const overlay = (
+    values: [string, unknown][],
+    hidden: string[] = [],
+  ): ReadonlyMap<string, ListVariantOverlay> =>
+    new Map([["de", { values: new Map(values), hidden: new Set(hidden) }]]);
+
+  it("replaces values and hides entries for the rendering page's variant", () => {
+    const data = fixtureData({
+      pageVariants: variants,
+      overlays: overlay(
+        [[`list/${LIST.header}/item/${ITEM.home}/label`, "Start"]],
+        [`list/${LIST.header}/item/${ITEM.newsEntry}`],
+      ),
+    });
+    const got = entries(page(PAGE.home, data), HEADER);
+    expect(got.map((e) => textOf(e, "label"))).toEqual(["Start", "About"]);
+    expect(got[1]?.get("last")).toEqual({ kind: "bool", value: true });
+    // Another variant's page sees the stored list.
+    expect(entries(page(PAGE.about, data), HEADER).map((e) => textOf(e, "label"))).toEqual([
+      "Home",
+      "About",
+      "News",
+    ]);
+  });
+
+  it("drops and reports unknown addresses, structural and invalid changes", () => {
+    const ctx = createListRenderContext(
+      fixtureData({
+        pageVariants: variants,
+        overlays: overlay(
+          [
+            [`list/${LIST.header}/item/${ITEM.home}/ghost`, "x"],
+            [`list/${LIST.header}/item/00000000-0000-4000-8000-999999999999/label`, "x"],
+            [`list/${LIST.header}/item/${ITEM.home}/link`, { nope: true }],
+            [
+              `list/${LIST.mega}/item/${ITEM.promo}/teaser`,
+              { moduleId: "x", contentInstanceId: "y" },
+            ],
+            ["nonsense", "x"],
+          ],
+          [`list/${LIST.header}/item/00000000-0000-4000-8000-999999999999`],
+        ),
+      }),
+    );
+    expect(ctx.overlayIssues.map((i) => i.reason)).toEqual([
+      "the entry's node declares no such field",
+      "no such list entry",
+      expect.stringContaining('"link" must be'),
+      "a module field changes structure, an overlay may only replace values",
+      "not a rendered value address",
+      "no such list entry",
+    ]);
+    const got = entries(ctx.forPage(PAGE.home), HEADER);
+    expect(got.map((e) => textOf(e, "label"))).toEqual(["Home", "About", "News"]);
+  });
+
+  it("replaces local list values by instance address and reports unknown fields", () => {
+    const ci = "00000000-0000-4000-8000-000000000999";
+    const itemId = "00000000-0000-4000-9000-000000000001";
+    const data = fixtureData({
+      pageVariants: variants,
+      overlays: overlay([
+        [`instance/${ci}/bullets/item/${itemId}/text`, "Schnell"],
+        [`instance/${ci}/bullets/item/${itemId}/ghost`, "x"],
+      ]),
+    });
+    const ctx = page(PAGE.home, data);
+    const r = ctx.resolveField(
+      { name: "bullets", listType: "texts" },
+      [{ id: itemId, node: "text", values: { text: "Fast" } }],
+      { contentInstanceId: ci },
+    );
+    if (!r.ok) throw new Error(r.marker);
+    expect(textOf(r.entries[0] as ScopeEntry, "text")).toBe("Schnell");
+    expect(ctx.overlayIssues().map((i) => i.address)).toEqual([
+      `instance/${ci}/bullets/item/${itemId}/ghost`,
+    ]);
+  });
+});
+
+describe("render dependencies", () => {
+  it("records shared lists, types, queries and page-tree reads", () => {
+    const ctx = page(PAGE.team);
+    entries(ctx, {
+      name: "menu",
+      listType: "menu",
+      bind: "shared",
+      list: `caelo:list/${LIST.header}`,
+    });
+    entries(ctx, query({ page_type: "news", terms: [TERM.event], order: "title_asc", limit: 3 }));
+    entries(ctx, {
+      name: "b",
+      listType: "links",
+      bind: "source",
+      source: { kind: "system", name: "breadcrumbs" },
+    });
+    expect(ctx.deps()).toEqual({
+      lists: [LIST.header],
+      listTypes: ["menu"],
+      queries: [{ pageType: "news", terms: [TERM.event], parent: null }],
+      pageTree: true,
+      // The breadcrumb trail's pages: their values render as entries.
+      pages: [PAGE.about, PAGE.team].sort(),
+    });
+  });
+
+  it("records only what the render reached (lazy)", () => {
+    const ctx = page(PAGE.home);
+    const mega = entries(ctx, {
+      name: "mega",
+      listType: "mega-menu",
+      bind: "shared",
+      list: `caelo:list/${LIST.mega}`,
+    });
+    expect(ctx.deps().queries).toEqual([]);
+    const columns = mega[0]?.get("columns");
+    if (columns?.kind !== "list") throw new Error("columns");
+    columns.entries[1]?.get("items");
+    expect(ctx.deps().queries).toEqual([{ pageType: "news", terms: [], parent: null }]);
+  });
+
+  it("term reads record the vocabulary list", () => {
+    const ctx = page(PAGE.newsA);
+    const scope = ctx.pageScope();
+    if (scope?.kind !== "record") throw new Error("page scope");
+    const terms = scope.get("terms");
+    if (terms?.kind !== "record") throw new Error("terms");
+    terms.get("tags");
+    expect(ctx.deps().lists).toEqual([LIST.tags]);
+  });
+});