@caelo-cms/shared 0.10.71 → 0.11.0

package/src/link-refs.test.ts

@@ -25,10 +25,31 @@ import {
   parseLinkRef,
   resolveLinkRefsInHtml,
 } from "./link-refs.js";
+import { DEFAULT_LIST_TYPES } from "./lists/default-types.js";
+import { createListRenderContext } from "./lists/resolve.js";
 import { renderPlacedModule } from "./nested-module-render.js";
 import { composePageWithLayout } from "./preview-compose.js";
 import { renderTemplate } from "./template-engine.js";
 
+/** A list context that knows only the shipped list types (local lists need nothing else). */
+const lists = createListRenderContext({
+  listTypes: new Map(DEFAULT_LIST_TYPES.map((t, i) => [t.slug, { id: `t${i}`, def: t }])),
+  lists: new Map(),
+  pageTypes: new Map(),
+  pages: new Map(),
+  media: new Map(),
+  siteLanguage: "en",
+}).forPage(null);
+const uid = (n: number) => `00000000-0000-4000-9000-${String(n).padStart(12, "0")}`;
+const links = (...ls: [string, string][]) =>
+  ls.map(([label, href], i) => ({
+    id: uid(i + 1),
+    node: "link",
+    values: { label, link: { href } },
+  }));
+const unstamp = (html: string) => html.replace(/ data-caelo-list-item="[^"]*"/g, "");
+const NAV_HTML = '<nav>{{#nav}}<a href="{{link}}">{{label}}</a>{{/nav}}</nav>';
+
 const PAGE = "11111111-1111-4111-8111-111111111111";
 const DRAFT = "22222222-2222-4222-8222-222222222222";
 const GONE = "33333333-3333-4333-8333-333333333333";
@@ -172,25 +193,26 @@ describe("resolution", () => {
 describe("template engine — references resolve wherever they come from", () => {
   const resolver = () => index().forPage(null);
 
-  it("resolves module HTML attributes, values, defaults and link-list items", () => {
+  it("resolves module HTML attributes, values, defaults and list entries", () => {
     const r = renderTemplate({
-      html: `<a href="caelo:page/${PAGE}">Home</a><a href="{{cta_href}}">{{cta_label}}</a><img src="{{hero}}">{{#nav}}<a href="{{href}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
+      html: `<a href="caelo:page/${PAGE}">Home</a><a href="{{cta_href}}">{{cta_label}}</a><img src="{{hero}}">{{#nav}}<a href="{{link}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
       fields: [
         { name: "cta_href", kind: "url", default: `caelo:page/${PAGE}#contact` },
         { name: "cta_label", kind: "text" },
         { name: "hero", kind: "image" },
-        { name: "nav", kind: "link-list" },
+        { name: "nav", kind: "list", listType: "links" },
         { name: "body", kind: "richtext" },
       ],
       contentValues: {
         cta_label: "Talk to us",
         hero: `caelo:media/${MEDIA}`,
-        nav: [{ label: "Pricing", href: `caelo:page/${DRAFT}` }],
+        nav: links(["Pricing", `caelo:page/${DRAFT}`]),
         body: `<p>See <a href="caelo:page/${PAGE}?x=1">about</a></p>`,
       },
+      lists,
       linkResolver: resolver(),
     });
-    expect(r.html).toBe(
+    expect(unstamp(r.html)).toBe(
       '<a href="/company/about/">Home</a><a href="/company/about/#contact">Talk to us</a>' +
         '<img src="/_caelo/media/hero-shot"><a href="/pricing/">Pricing</a>' +
         '<div><p>See <a href="/company/about/?x=1">about</a></p></div>',
@@ -241,8 +263,8 @@ describe("template engine — references resolve wherever they come from", () =>
   });
 });
 
-describe("composer — nav-menu sets and pre-rendered modules", () => {
-  it("resolves nav-menu item hrefs and attributes a broken one to the nav module", () => {
+describe("composer — chrome lists and pre-rendered modules", () => {
+  it("resolves a chrome module's list entries and attributes a broken one to the module", () => {
     const out = composePageWithLayout({
       layoutHtml:
         '<html><head></head><body><caelo-slot name="header"></caelo-slot><caelo-slot name="content"></caelo-slot></body></html>',
@@ -253,11 +275,19 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
           modules: [
             {
               moduleId: "m-nav",
-              slug: "nav-menu-main",
+              slug: "main-nav",
               displayName: "Nav",
-              html: "",
+              html: NAV_HTML,
               css: "",
               js: "",
+              fields: [
+                {
+                  name: "nav",
+                  kind: "list",
+                  listType: "links",
+                  default: links(["About", `caelo:page/${PAGE}`], ["Gone", `caelo:page/${GONE}`]),
+                },
+              ],
             },
           ],
         },
@@ -279,23 +309,16 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
           ],
         },
       ],
-      structuredSets: {
-        byKindSlug: {
-          "nav-menu/main": [
-            { label: "About", href: `caelo:page/${PAGE}` },
-            { label: "Gone", href: `caelo:page/${GONE}` },
-          ],
-        },
-      },
+      lists,
       linkResolver: index().forPage(PAGE),
     });
-    expect(out.html).toContain('<a href="/company/about/">About</a>');
+    expect(unstamp(out.html)).toContain('<a href="/company/about/">About</a>');
     expect(out.html).toContain(`href="caelo:page/${GONE}"`);
     expect(out.moduleFailures).toEqual([
       {
         blockName: "header",
         moduleId: "m-nav",
-        moduleSlug: "nav-menu-main",
+        moduleSlug: "main-nav",
         field: "",
         reason: `link-target-missing:page/${GONE}`,
       },
@@ -314,7 +337,6 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
       templateHtml: '<caelo-slot name="content"></caelo-slot>',
       templateCss: "",
       blocks: [],
-      structuredSets: { byKindSlug: {} },
       linkResolver: index().forPage(PAGE),
     });
     expect(out.html).toContain('<a class="home" href="/company/about/#top">Home</a>');
@@ -631,25 +653,23 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
     });
   });
 
-  it("covers HTML href, rich text, link field and link-list in one render", () => {
+  it("covers HTML href, rich text, link field and list entries in one render", () => {
     const r = renderTemplate({
-      html: `<a href="caelo:page/${EN_HOME}">Home</a><a href="{{cta_href}}">Go</a>{{#nav}}<a href="{{href}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
+      html: `<a href="caelo:page/${EN_HOME}">Home</a><a href="{{cta_href}}">Go</a>{{#nav}}<a href="{{link}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
       fields: [
         { name: "cta_href", kind: "link" },
-        { name: "nav", kind: "link-list" },
+        { name: "nav", kind: "list", listType: "links" },
         { name: "body", kind: "richtext" },
       ],
       contentValues: {
         cta_href: `caelo:page/${EN_PRICING}#plans`,
-        nav: [
-          { label: "About", href: `caelo:page/${EN_ABOUT}` },
-          { label: "Solo", href: `caelo:page/${EN_SOLO}` },
-        ],
+        nav: links(["About", `caelo:page/${EN_ABOUT}`], ["Solo", `caelo:page/${EN_SOLO}`]),
         body: `<p><a href="caelo:page/${EN_ABOUT}?x=1">about</a></p>`,
       },
+      lists,
       linkResolver: variantIndex("preview").forPage(DE_PRICING),
     });
-    expect(r.html).toBe(
+    expect(unstamp(r.html)).toBe(
       '<a href="/de/">Home</a><a href="/de/preise/#plans">Go</a>' +
         `<a href="/de/ueber/">About</a><a href="caelo:page/${EN_SOLO}">Solo</a>` +
         '<div><p><a href="/de/ueber/?x=1">about</a></p></div>',
@@ -657,7 +677,7 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
     expect(r.missingSlots).toEqual([`link-variant-missing:page/${EN_SOLO}:de`]);
   });
 
-  it("covers nav-menu sets in the composer and attributes a missing sibling to the nav", () => {
+  it("covers chrome lists in the composer and attributes a missing sibling to the module", () => {
     const out = composePageWithLayout({
       layoutHtml:
         '<html><head></head><body><caelo-slot name="header"></caelo-slot><caelo-slot name="content"></caelo-slot></body></html>',
@@ -668,11 +688,22 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
           modules: [
             {
               moduleId: "m-nav",
-              slug: "nav-menu-main",
+              slug: "main-nav",
               displayName: "Nav",
-              html: "",
+              html: NAV_HTML,
               css: "",
               js: "",
+              fields: [
+                {
+                  name: "nav",
+                  kind: "list",
+                  listType: "links",
+                  default: links(
+                    ["About", `caelo:page/${EN_ABOUT}`],
+                    ["Solo", `caelo:page/${EN_SOLO}`],
+                  ),
+                },
+              ],
             },
           ],
         },
@@ -680,22 +711,15 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
       templateHtml: '<caelo-slot name="content"></caelo-slot>',
       templateCss: "",
       blocks: [],
-      structuredSets: {
-        byKindSlug: {
-          "nav-menu/main": [
-            { label: "About", href: `caelo:page/${EN_ABOUT}` },
-            { label: "Solo", href: `caelo:page/${EN_SOLO}` },
-          ],
-        },
-      },
+      lists,
       linkResolver: variantIndex().forPage(DE_ABOUT),
     });
-    expect(out.html).toContain('<a href="/de/ueber/">About</a>');
+    expect(unstamp(out.html)).toContain('<a href="/de/ueber/">About</a>');
     expect(out.moduleFailures).toEqual([
       {
         blockName: "header",
         moduleId: "m-nav",
-        moduleSlug: "nav-menu-main",
+        moduleSlug: "main-nav",
         field: "",
         reason: `link-variant-missing:page/${EN_SOLO}:de`,
       },
@@ -745,7 +769,7 @@ describe("link failure markers — what the build gate and the preview report",
 
   it("leaves every other marker alone, in order", () => {
     expect(isLinkFailureMarker("field-not-declared:x")).toBe(false);
-    expect(isLinkFailureMarker("link-list-malformed:nav[0]")).toBe(false);
+    expect(isLinkFailureMarker("list-malformed:nav[items[0]]")).toBe(false);
     expect(
       linkMarkersOf([
         "theme-asset-unbound:logo",

package/src/link-refs.ts

@@ -9,8 +9,8 @@
  * rendered for. Renaming or moving a page then changes no stored link.
  *
  * Grammar (one form for every place a link can live — `link` / `url`
- * fields, `link-list` items, `*_href` values, module HTML attributes,
- * rich text, structured-set items, field defaults):
+ * fields, list entry `link` values, `*_href` values, module HTML attributes,
+ * rich text, field defaults):
  *
  *   caelo:page/<pageId>[?query][#anchor]
  *   caelo:media/<mediaId>[/<variant>]
@@ -277,7 +277,7 @@ export function replaceLinkRefs(
 }
 
 /**
- * Walk a JSON value (content values, field defaults, set items) and map
+ * Walk a JSON value (content values, field defaults, list entries) and map
  * every string through {@link replaceLinkRefs}. Returns the SAME
  * reference when nothing changed, so callers can cheaply detect no-ops.
  */

package/src/lists/address.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Stable value addresses (epic #1107, `docs/lists.md` §9). Core has no
+ * locale concept; a translation plugin keys its own storage by these
+ * addresses and answers the `list-resolve` composition point with
+ * overlays keyed the same way. Entry ids never change, so an address
+ * survives moves, renames of loop names and reordering.
+ */
+
+/** One addressable stored value. */
+export type ValueAddress =
+  | {
+      readonly kind: "list";
+      readonly listId: string;
+      readonly itemId: string;
+      readonly field: string;
+    }
+  | {
+      readonly kind: "instance";
+      readonly contentInstanceId: string;
+      readonly field: string;
+      readonly itemId: string;
+      readonly itemField: string;
+    }
+  | { readonly kind: "pageProp"; readonly pageId: string; readonly field: string }
+  | {
+      readonly kind: "listTypeField";
+      readonly listTypeId: string;
+      readonly node: string;
+      readonly field: string;
+    };
+
+const SEG = "[a-z0-9_-]+";
+const ADDRESS_RE = new RegExp(
+  `^(?:list/(${SEG})/item/(${SEG})/(${SEG})` +
+    `|instance/(${SEG})/(${SEG})/item/(${SEG})/(${SEG})` +
+    `|page/(${SEG})/props/(${SEG})` +
+    `|list_type/(${SEG})/node/(${SEG})/(${SEG}))$`,
+);
+
+/** Format an address as its canonical string. */
+export function formatValueAddress(a: ValueAddress): string {
+  switch (a.kind) {
+    case "list":
+      return `list/${a.listId}/item/${a.itemId}/${a.field}`;
+    case "instance":
+      return `instance/${a.contentInstanceId}/${a.field}/item/${a.itemId}/${a.itemField}`;
+    case "pageProp":
+      return `page/${a.pageId}/props/${a.field}`;
+    case "listTypeField":
+      return `list_type/${a.listTypeId}/node/${a.node}/${a.field}`;
+  }
+}
+
+/** Parse an address string; null when it is not one. */
+export function parseValueAddress(s: string): ValueAddress | null {
+  const m = ADDRESS_RE.exec(s);
+  if (!m) return null;
+  if (m[1] && m[2] && m[3]) return { kind: "list", listId: m[1], itemId: m[2], field: m[3] };
+  if (m[4] && m[5] && m[6] && m[7]) {
+    return {
+      kind: "instance",
+      contentInstanceId: m[4],
+      field: m[5],
+      itemId: m[6],
+      itemField: m[7],
+    };
+  }
+  if (m[8] && m[9]) return { kind: "pageProp", pageId: m[8], field: m[9] };
+  if (m[10] && m[11] && m[12]) {
+    return { kind: "listTypeField", listTypeId: m[10], node: m[11], field: m[12] };
+  }
+  return null;
+}

package/src/lists/default-types.ts

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The list types every install starts with (epic #1107,
+ * `docs/lists.md` §3). They are seeded as STORED data by migration 0352
+ * and edited like any other type afterwards — these objects are the
+ * source the seed and the tests share, not a render-time fallback
+ * (CLAUDE.md §2).
+ */
+
+import type { ListTypeDef } from "./list-type.js";
+
+export const DEFAULT_LIST_TYPES: readonly ListTypeDef[] = [
+  {
+    slug: "texts",
+    name: "Texts",
+    purpose: "A flat list of short texts inside one module: feature bullets, chips, steps.",
+    role: "content",
+    root: { allow: ["text"] },
+    nodes: {
+      text: {
+        label: "Text",
+        fields: [{ name: "text", label: "Text", type: "text", required: true }],
+      },
+    },
+  },
+  {
+    slug: "links",
+    name: "Links",
+    purpose: "A flat group of links: legal links, social links, a footer column.",
+    role: "content",
+    root: { allow: ["link"] },
+    nodes: {
+      link: {
+        label: "Link",
+        fields: [
+          { name: "label", label: "Label", type: "text", required: true },
+          { name: "link", label: "Link", type: "link", required: true },
+        ],
+        current_from: "link",
+      },
+    },
+  },
+  {
+    slug: "menu",
+    name: "Menu",
+    purpose:
+      "Site navigation with up to three levels: header menu, footer menu, mobile menu. Use a custom type for mega menus with columns or teasers.",
+    role: "navigation",
+    root: { allow: ["entry"] },
+    nodes: {
+      entry: {
+        label: "Menu entry",
+        fields: [
+          { name: "label", label: "Label", type: "text", required: true },
+          { name: "link", label: "Link", type: "link" },
+        ],
+        children: { name: "children", allow: ["entry"] },
+        current_from: "link",
+      },
+    },
+    max_depth: 3,
+  },
+  {
+    slug: "categories",
+    name: "Categories",
+    purpose: "A category tree pages are assigned to: blog sections, product groups, doc areas.",
+    role: "vocabulary",
+    root: { allow: ["category"] },
+    nodes: {
+      category: {
+        label: "Category",
+        fields: [
+          { name: "name", label: "Name", type: "text", required: true },
+          { name: "slug", label: "Slug", type: "text", required: true },
+          { name: "description", label: "Description", type: "richtext" },
+          { name: "landing_page", label: "Landing page", type: "link" },
+        ],
+        children: { name: "children", allow: ["category"] },
+        current_from: "landing_page",
+      },
+    },
+    max_depth: 6,
+  },
+  {
+    slug: "tags",
+    name: "Tags",
+    purpose: "Flat keywords pages are tagged with, for filters, tag clouds and related content.",
+    role: "vocabulary",
+    root: { allow: ["tag"] },
+    nodes: {
+      tag: {
+        label: "Tag",
+        fields: [
+          { name: "name", label: "Name", type: "text", required: true },
+          { name: "slug", label: "Slug", type: "text", required: true },
+          { name: "color", label: "Color", type: "text", maxLength: 9 },
+        ],
+      },
+    },
+  },
+];