@caltho/site-kit 0.2.10 → 0.3.0

package/dist/content/index.js

@@ -10,10 +10,17 @@
 // them with no further work.
 import { z } from "zod";
 import { checkStructure, describePath } from "../schema.js";
-import { lookProblems, lookSchema } from "./look.js";
-export { contrast, lookCss, lookProblems, lookVars } from "./look.js";
-export { checkStructure, describePath } from "../schema.js";
+import { presets } from "../sections/presets.js";
+import { built, component, treeProblems } from "../tree/index.js";
+import { CONTENT_FORMAT } from "../content-migrate.js";
+import { consent } from "../consent.js";
+import { FIELD_KINDS, itemPath } from "./lists.js";
+import { buttonStyleName, COLOUR_ROLES, colourOf, isDark, lookProblems, lookSchema, swatchSlug } from "./look.js";
+export { COLOUR_ROLES, colourOf, contrast, HEADER_LAYOUTS, HEADER_STYLES, headerOf, isDark, KIT_FONTS, KIT_TYPE, lookCss, lookProblems, lookVars, swatchSlug, TYPE_ROLES, uploadedFontCss, buttonStyleClass, BUTTON_SIZES, MAX_BUTTON_STYLES, THEME_BUTTONS, } from "./look.js";
+export { fontFaceCss, fontFiles, googleFamily, googleFont, googleFonts, isFontName, servedAt } from "../fonts-google.js";
+export { blockLabel, checkStructure, describePath } from "../schema.js";
 export { z };
+export { allPages, FIELD_KINDS, fromList, itemOf, itemPages, itemPath, PAGE_LINK, THIS_ITEM, withListItems } from "./lists.js";
 // Fields carry an "x-ui" hint in the JSON Schema, so CalOS draws the right control: a text area, a
 // Markdown box, a picture picker.
 export const text = z.string().trim().min(1);
@@ -33,16 +40,26 @@ export const href = z
     .string()
     .regex(/^(\/[\w\-./#?=&%]*|#[\w-]+|https?:\/\/\S+|tel:\+?[\d\s()-]+|mailto:\S+@\S+)$/, { error: HREF_HELP })
     .meta({ "x-error": HREF_HELP });
-export const link = z.object({ label: text, href, style: z.enum(["primary", "secondary"]).optional() });
+export const link = z.object({
+    label: text,
+    href,
+    // Main (the brand colour), quiet (an outline), or the accent colour: a button that stands out on a photo or a dark band.
+    style: z.enum(["primary", "secondary", "accent"]).optional().meta({ title: "Style", "x-labels": { primary: "Main", secondary: "Quiet", accent: "Accent colour" } }),
+});
 export const time = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, { error: "A time like 08:00 or 17:30" }).meta({ "x-error": "A time like 08:00 or 17:30" });
 export const DAYS = ["Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"];
 /** What every block has: a place on the page, for links like /#contact. */
 const blockBase = { id: z.string().regex(/^[a-z][\w-]*$/).optional() };
 /**
- * How a section sits on the page, for a site that offers it (defineSite's `placement`): its alignment,
- * width, spacing and the screens it shows on. The site's design says what each means at every width,
- * so a choice here stays sensible on a phone. CalOS shows it as the section's Layout. (A block's own
- * `layout`, a site's choice of how it's drawn, is a different thing and keeps its name.)
+ * How a section sits on the page, offered on every section (defineSite's `placement`, on unless a site
+ * turns it off): its alignment, width, spacing, the screens it shows on, and what's behind it. The
+ * site's design says what each means at every width, so a choice here stays sensible on a phone.
+ * CalOS shows it as the section's Layout. (A block's own `layout`, a site's choice of how it's drawn,
+ * is a different thing and keeps its name.)
+ *
+ * Its background is drawn by KitBlocks (../next/blocks.tsx) as a frame around the section: a colour
+ * (one of the page's, by its role, or one of the site's own, by its slug) and a photo, shaded so the
+ * words over it read.
  */
 export const placement = z
     .object({
@@ -50,9 +67,24 @@ export const placement = z
     width: z.enum(["narrow", "normal", "wide"]).default("normal").meta({ title: "Width" }),
     spacing: z.enum(["compact", "normal", "roomy"]).default("normal").meta({ title: "Spacing" }),
     show: z.enum(["all", "desktop", "phone"]).default("all").meta({ title: "Show on" }),
+    // A line across the page's full width above it, below it or both (a strip between two rules), quiet (the Look's line colour) or strong (its text colour).
+    lines: z.enum(["none", "top", "bottom", "both"]).optional().meta({ title: "Lines", "x-labels": { none: "None", top: "Above", bottom: "Below", both: "Above and below" } }),
+    lineColour: z.enum(["quiet", "strong"]).optional().meta({ title: "Line colour", "x-labels": { quiet: "Quiet", strong: "Strong" } }),
+    background: z
+        .object({
+        color: z
+            .string()
+            .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, { error: "One of the site's colours" })
+            .optional()
+            .meta({ title: "Colour", "x-ui": "swatch", "x-error": "One of the site's colours" }),
+        photo: image.optional().meta({ title: "Photo" }),
+        overlay: z.enum(["none", "light", "dark"]).default("dark").meta({ title: "Shade over the photo" }),
+    })
+        .optional()
+        .meta({ title: "Background" }),
 })
     .meta({ title: "Layout" });
-/** A section's placement as class names, only what differs from the usual: "place-align-center place-width-narrow", or "". */
+/** A section's placement as class names, only what differs from the usual: "place-align-center place-width-narrow", or "". Its background is the frame's (frameClass). */
 export function placementClass(block) {
     const l = block.placement ?? {};
     const usual = { align: "left", width: "normal", spacing: "normal", show: "all" };
@@ -61,6 +93,63 @@ export function placementClass(block) {
         .map((k) => `place-${k}-${l[k]}`)
         .join(" ");
 }
+/** The classes of the lines across a section's full width (KitBlocks wraps it in them), or "" for none. */
+export function linesClass(block) {
+    const l = block.placement?.lines;
+    if (!l || l === "none")
+        return "";
+    return ["kit-lines", `kit-lines-${l}`, block.placement?.lineColour === "strong" ? "kit-lines-strong" : ""].filter(Boolean).join(" ");
+}
+/** Whether a section has something behind it (a colour or a photo), and so a frame. */
+export function hasBackground(block) {
+    const b = block.placement?.background;
+    return Boolean(b && (b.color || b.photo?.src));
+}
+/** What a page's colours are when a site has no Look: a light page, its other colours dark. */
+const NO_LOOK = { "--look-page": "#ffffff", "--look-soft": "#f3f3f3", "--look-brand": "#111111", "--look-accent": "#111111", "--look-ink": "#111111" };
+/**
+ * Whether a section's background is dark, so its words go light: under a photo, by its shade (dark
+ * or none: light words; light: dark words); else by its colour's value in the Look (`vars`, from
+ * lookVars, at build and in the preview alike). A colour it can't find counts as light.
+ */
+export function backgroundIsDark(block, vars = {}) {
+    const b = block.placement?.background;
+    if (!b)
+        return false;
+    if (b.photo?.src)
+        return (b.overlay ?? "dark") !== "light";
+    if (!b.color)
+        return false;
+    const value = colourOf(b.color, { ...NO_LOOK, ...vars });
+    return value ? isDark(value) : false;
+}
+/**
+ * The classes of the frame KitBlocks draws around a section with a background, or "" for one
+ * without: `kit-frame`, its colour (`kit-bg-soft`, or `kit-bg-swatch-2` for the site's second own
+ * colour, found in `vars`), `kit-frame-photo kit-overlay-dark` under a photo, and `kit-frame-dark`
+ * when its words go light (backgroundIsDark). sections.css draws them from the Look's variables.
+ */
+export function frameClass(block, vars = {}) {
+    if (!hasBackground(block))
+        return "";
+    const b = block.placement.background;
+    const out = ["kit-frame"];
+    if (b.color) {
+        if (COLOUR_ROLES.includes(b.color))
+            out.push(`kit-bg-${b.color}`);
+        else {
+            const value = vars[`--look-swatch-${b.color}`];
+            const n = value ? Array.from({ length: 12 }, (_, i) => i + 1).find((i) => vars[`--look-swatch-${i}`] === value) : undefined;
+            if (n)
+                out.push(`kit-bg-swatch-${n}`);
+        }
+    }
+    if (b.photo?.src)
+        out.push("kit-frame-photo", `kit-overlay-${b.overlay ?? "dark"}`);
+    if (backgroundIsDark(block, vars))
+        out.push("kit-frame-dark");
+    return out.join(" ");
+}
 const address = z.object({
     street: text,
     locality: text,
@@ -111,7 +200,7 @@ const pageBase = (trailingSlash) => ({
 });
 /**
  * The site's menu, as its header draws it: the one edited in CalOS (its links in order, one picked out,
- * and the header's button), else the pages that have a menu label, in page order (and no button: the
+ * each with the links under it if it has any, and the header's button), else the pages that have a menu label, in page order (and no button: the
  * site's own default).
  */
 export function menuOf(site) {
@@ -129,14 +218,85 @@ export function footerOf(site) {
  * A site's content shape from its blocks: each a name and the fields it has. The site's own block
  * type is `z.output<typeof content.schema>["pages"][number]["blocks"][number]`.
  */
+/** A list's key and a field's: what Shows and Repeats for name them by (`lists.products.items`, `this.price`). */
+const listKey = z.string().regex(/^[a-z][a-zA-Z0-9]{0,39}$/, { error: "Letters and numbers, starting with a lowercase letter, like products or teamMembers" });
+const fieldKey = z
+    .string()
+    .regex(/^[a-z][a-zA-Z0-9]{0,39}$/, { error: "Letters and numbers, starting with a lowercase letter, like name or price" })
+    .refine((k) => k !== "id" && k !== "slug", { error: "id and slug are an item's own" });
+/** An item: its id, its address part, and its values (each checked against its field's kind: listProblems). */
+const listItem = z
+    .object({
+    id: z.string().regex(/^[\w-]{1,64}$/),
+    slug: z.string().max(80).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, { error: "Lowercase letters, numbers and dashes, like walnut-desk" }),
+})
+    .catchall(z.unknown());
+/** Each kind of a list's field, as a value is checked. */
+const VALUE = {
+    text: z.string().trim().max(300),
+    longText: z.string().max(5000),
+    image,
+    link: href,
+    number: z.number().finite(),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, { error: "A date like 2026-11-09" }),
+};
+/**
+ * What a list's shape can't say alone: fields named once, each item's values of their field's kind
+ * and no others, ids and addresses used once, a page titled and described by a field of words, and no
+ * item at the address of one of the site's pages.
+ */
+function listProblems(site) {
+    const out = [];
+    const lists = (site.lists ?? {});
+    const pagePaths = new Set(site.pages.map((p) => p.path));
+    for (const [key, list] of Object.entries(lists)) {
+        const at = ["lists", key];
+        const fields = new Map();
+        list.fields.forEach((f, i) => {
+            if (fields.has(f.key))
+                out.push({ path: [...at, "fields", i, "key"], message: `Two fields are called ${f.key}` });
+            fields.set(f.key, f.kind);
+        });
+        const ids = new Set();
+        const slugs = new Set();
+        list.items.forEach((item, i) => {
+            if (ids.has(item.id))
+                out.push({ path: [...at, "items", i, "id"], message: `Two items have the id ${item.id}` });
+            ids.add(item.id);
+            if (slugs.has(item.slug))
+                out.push({ path: [...at, "items", i, "slug"], message: `Two items have the address ${item.slug}` });
+            slugs.add(item.slug);
+            for (const [k, v] of Object.entries(item)) {
+                if (k === "id" || k === "slug" || v === undefined || v === null || v === "")
+                    continue;
+                const kind = fields.get(k);
+                if (!kind)
+                    out.push({ path: [...at, "items", i, k], message: `${k} isn't one of ${list.name}'s fields` });
+                else if (!VALUE[kind].safeParse(v).success)
+                    out.push({ path: [...at, "items", i, k], message: `Not a ${kind === "longText" ? "text" : kind} value` });
+            }
+            if (list.page && pagePaths.has(itemPath(list.page, item.slug, site.trailingSlash !== false)))
+                out.push({ path: [...at, "items", i, "slug"], message: `There's a page at ${itemPath(list.page, item.slug, site.trailingSlash !== false)} already` });
+        });
+        if (list.page) {
+            const words = (k) => !k || fields.get(k) === "text" || fields.get(k) === "longText";
+            if (!fields.has(list.page.title) || fields.get(list.page.title) !== "text")
+                out.push({ path: [...at, "page", "title"], message: "The title is one of the list's fields of words" });
+            if (list.page.description && (!fields.has(list.page.description) || !words(list.page.description)))
+                out.push({ path: [...at, "page", "description"], message: "The description is one of the list's fields of words" });
+        }
+    }
+    return out;
+}
 export function defineSite(blocks, o = {}) {
     const names = Object.keys(blocks);
     if (!names.length)
         throw new Error("A site needs at least one kind of block");
+    const placed = o.placement ?? true;
     const union = z.discriminatedUnion("type", 
     // Each kind keeps what the site said of it (its title, for CalOS to call it by).
     names.map((type) => {
-        const kind = z.object({ type: z.literal(type), ...blockBase, ...(o.placement ? { placement: placement.optional() } : {}) }).extend(blocks[type].shape);
+        const kind = z.object({ type: z.literal(type), ...blockBase, ...(placed ? { placement: placement.optional() } : {}) }).extend(blocks[type].shape);
         const meta = blocks[type].meta();
         return meta ? kind.meta(meta) : kind;
     }));
@@ -144,6 +304,14 @@ export function defineSite(blocks, o = {}) {
     const page = z.object({ ...pageBase(trailingSlash), ...o.pageExtend, blocks: z.array(union).min(1) });
     const schema = z
         .object({
+        /** Which format of the kit's the content is in (../content-migrate.ts): none for the first; set by the migrations, never edited. */
+        format: z
+            .number()
+            .int()
+            .min(0)
+            .max(CONTENT_FORMAT, { error: `A newer format than this kit's (${CONTENT_FORMAT}): the site needs a newer @caltho/site-kit` })
+            .optional()
+            .meta({ title: "Content format", readOnly: true, "x-ui": "hidden" }),
         /** The address it's served at once live (its main domain). */
         url: z.url({ protocol: /^https$/, error: "The site's address, starting https://" }).meta({ title: "Web address" }),
         lang: z.string().default("en-US").meta({ title: "Language" }),
@@ -153,8 +321,23 @@ export function defineSite(blocks, o = {}) {
         /** The header's links in order, and its button: edited as one list in CalOS. Left out, the pages' menu labels are used. */
         menu: z
             .object({
-            links: z.array(z.object({ label: text, href, emphasis: z.boolean().default(false).meta({ title: "Emphasize" }) })).max(10),
-            button: z.object({ label: text, href }).optional().meta({ title: "Button" }),
+            links: z
+                .array(z.object({
+                label: text,
+                href,
+                emphasis: z.boolean().default(false).meta({ title: "Emphasize" }),
+                children: z.array(z.object({ label: text, href })).max(8).optional().meta({ title: "Links under it" }),
+            }))
+                .max(10),
+            button: z
+                .object({
+                label: text,
+                href,
+                // Drawn in the theme's Main (the usual), Accent or Quiet, or one of the business's own button styles.
+                style: buttonStyleName.optional().meta({ title: "Style", "x-ui": "button-style" }),
+            })
+                .optional()
+                .meta({ title: "Button" }),
         })
             .optional()
             .meta({ title: "Menu" }),
@@ -167,11 +350,48 @@ export function defineSite(blocks, o = {}) {
         })
             .optional()
             .meta({ title: "Footer" }),
+        /**
+         * A header or footer of the business's own, built as a tree like a built section (../tree), in
+         * place of the kit's: its links, logo and button are elements, a phone menu an accordion. Left
+         * out, the kit's header and footer (from the menu, footer and Look above).
+         */
+        ownHeader: built.optional().meta({ title: "Your own header", "x-ui": "hidden" }),
+        ownFooter: built.optional().meta({ title: "Your own footer", "x-ui": "hidden" }),
+        /** A cookie banner, and visits counted only once a visitor accepts: off unless turned on (../consent.ts). */
+        consent: consent.optional(),
         /** Old addresses kept answering, when CalOS doesn't supply them at build. */
         redirects: z.array(z.object({ from: z.string().startsWith("/"), to: href, status: z.union([z.literal(301), z.literal(302)]).default(301) })).default([]),
         ...(o.look ? { look: lookSchema(o.look) } : {}),
         ...o.extend,
         pages: z.array(page).min(1),
+        /**
+         * The site's lists (./lists.ts): items of one kind kept once, repeated by built sections and,
+         * where a list has a page, each at its own address from one design.
+         */
+        lists: z
+            .record(listKey, z.object({
+            name: text.meta({ title: "Name" }),
+            fields: z.array(z.object({ key: fieldKey, label: text, kind: z.enum(FIELD_KINDS) })).max(30),
+            items: z.array(listItem).max(2000).default([]),
+            page: z
+                .object({
+                path: pageBase(trailingSlash).path,
+                title: fieldKey.meta({ title: "The field each page is titled by" }),
+                description: fieldKey.optional().meta({ title: "The field each page is described by" }),
+                blocks: z.array(union).min(1),
+            })
+                .optional()
+                .meta({ title: "A page for each item" }),
+            /** Where its items come from, when CalOS fills it from one of the business's tables: kept by CalOS, never drawn. */
+            source: z
+                .object({ table: z.string().max(60), fields: z.record(z.string(), z.string().max(60)), publish: z.enum(["draft", "auto"]).default("draft") })
+                .optional()
+                .meta({ "x-ui": "hidden" }),
+        }))
+            .default({})
+            .meta({ title: "Lists", "x-ui": "hidden" }),
+        /** Trees kept once and used by name (`use` blocks), changed in one place for every use: on a site that takes built sections. */
+        ...(names.includes("built") || names.includes("use") ? { components: z.array(component).max(50).default([]).meta({ title: "Components" }) } : {}),
         /** Sections the business put together and named, to add again anywhere ("Package card"): CalOS offers them beside the site's own kinds. */
         saved: z
             .array(z.object({ name: text.meta({ title: "Name" }), block: union }))
@@ -186,6 +406,13 @@ export function defineSite(blocks, o = {}) {
         if (o.look)
             for (const i of lookProblems(s.look, o.look))
                 ctx.addIssue({ code: "custom", path: i.path, message: i.message });
+        if (placed)
+            for (const i of backgroundProblems(s, o.look))
+                ctx.addIssue({ code: "custom", path: i.path, message: i.message });
+        for (const i of builtProblems(s))
+            ctx.addIssue({ code: "custom", path: i.path, message: i.message });
+        for (const i of listProblems(s))
+            ctx.addIssue({ code: "custom", path: i.path, message: i.message });
         o.refine?.(s, ctx);
     });
     return {
@@ -201,9 +428,64 @@ export function defineSite(blocks, o = {}) {
         csp: o.csp ?? {},
         share: o.share,
         look: o.look,
-        /** The declaration CalOS draws its editing forms from. */
-        jsonSchema: () => z.toJSONSchema(schema, { io: "input", unrepresentable: "any" }),
+        /**
+         * The declaration CalOS draws its editing forms from. A site with sections of the business's own
+         * (`own`) carries the ready-made ones it can start from, each one this site's schema takes, as
+         * `x-presets`: [{ key, name, description, block }].
+         */
+        jsonSchema: () => {
+            const json = z.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+            if (names.includes("own"))
+                json["x-presets"] = presets.filter((p) => union.safeParse(p.block).success);
+            return json;
+        },
+    };
+}
+/** A section's background naming a colour the site hasn't: one of the page's roles, or one of the Look's own colours by its slug. */
+function backgroundProblems(site, look) {
+    const palette = site.look?.palette ?? look?.palette ?? [];
+    const known = new Set([...COLOUR_ROLES, ...palette.map((s) => swatchSlug(s.name))]);
+    const out = [];
+    const check = (b, at) => {
+        const color = b.placement?.background?.color;
+        if (color && !known.has(color))
+            out.push({ path: [...at, "placement", "background", "color"], message: `"${color}" isn't one of the site's colours: choose another` });
+    };
+    site.pages.forEach((p, i) => p.blocks.forEach((b, j) => check(b, ["pages", i, "blocks", j])));
+    const saved = site.saved ?? [];
+    saved.forEach((s, i) => s?.block && check(s.block, ["saved", i, "block"]));
+    return out;
+}
+/**
+ * What a built section's tree can't say alone (../tree: depth, size, an id used twice), for every
+ * tree the content keeps, and that each component a `use` block names is one the site has.
+ */
+function builtProblems(site) {
+    const out = [];
+    const components = Array.isArray(site.components) ? site.components : [];
+    const keys = new Set();
+    components.forEach((c, i) => {
+        if (c?.key && keys.has(c.key))
+            out.push({ path: ["components", i, "key"], message: `Two components are called ${c.key}` });
+        if (c?.key)
+            keys.add(c.key);
+        if (c?.root)
+            for (const m of treeProblems(c.root))
+                out.push({ path: ["components", i, "root"], message: m });
+    });
+    const design = site.consent?.design;
+    if (design && !keys.has(design))
+        out.push({ path: ["consent", "design"], message: `The site has no component called ${design}` });
+    const check = (b, at) => {
+        if (b.type === "built" && b.root && typeof b.root === "object")
+            for (const m of treeProblems(b.root))
+                out.push({ path: [...at, "root"], message: m });
+        if (b.type === "use" && typeof b.component === "string" && !keys.has(b.component))
+            out.push({ path: [...at, "component"], message: `The site has no component called ${b.component}` });
     };
+    site.pages.forEach((p, i) => p.blocks.forEach((b, j) => check(b, ["pages", i, "blocks", j])));
+    (site.saved ?? []).forEach((s, i) => s?.block && check(s.block, ["saved", i, "block"]));
+    return out;
 }
 /** Search results cut a title at about 60 characters and a description at about 160: said, not refused, since the page still works. */
 function lengthWarnings(site) {

package/dist/content/lists.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import type { Block, Page } from "./index.ts";
+/** The kinds a list's field may be. */
+export declare const FIELD_KINDS: readonly ["text", "longText", "image", "link", "number", "date"];
+export type FieldKind = (typeof FIELD_KINDS)[number];
+export type ListField = {
+    key: string;
+    label: string;
+    kind: FieldKind;
+};
+/** An item: its id (stable, from CalOS), its address part, and a value per field. */
+export type ListItem = {
+    id: string;
+    slug: string;
+    [field: string]: unknown;
+};
+/** A list's page: where its items live, the fields that title and describe each, and its design. */
+export type ListPage = {
+    path: string;
+    title: string;
+    description?: string;
+    blocks: Block[];
+};
+export type List = {
+    name: string;
+    fields: ListField[];
+    items: ListItem[];
+    page?: ListPage;
+};
+/** An item page's blocks carry the item they're drawn with (read by built sections as `this.`). */
+export declare const THIS_ITEM = "thisItem";
+type WithLists = {
+    pages: Page[];
+    lists?: Record<string, List>;
+    trailingSlash?: boolean;
+};
+/** An item page's address: under its list's page, by its address part. */
+export declare const itemPath: (page: ListPage, slug: string, trailingSlash?: boolean) => string;
+/** Every item page of every list that has a page, as pages: its design's blocks, each carrying the item. */
+export declare function itemPages(site: WithLists): Page[];
+/**
+ * A section's items taken from one of the site's lists, as CalOS sets it when the business picks a
+ * list for a section that repeats things (Services, Team, Reviews): which list, the section's array
+ * it fills (`into`, fixed by the section), and each of an item's fields from which of the list's
+ * (PAGE_LINK: the item's own page). The section's typed items stay, unused, until the list is unpicked.
+ */
+export type FromList = {
+    list: string;
+    into: string;
+    fields: Record<string, string>;
+};
+/** In a FromList's fields: the item's own page, where its list has pages. */
+export declare const PAGE_LINK = "@page";
+/**
+ * The field a section that repeats things adds to say its items can come from a list: `into` names
+ * its array (`items`, `people`). CalOS offers the site's lists for it and matches the fields.
+ */
+export declare const fromList: (into: string) => z.ZodOptional<z.ZodObject<{
+    list: z.ZodString;
+    into: z.ZodDefault<z.ZodLiteral<string>>;
+    fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>>;
+/** A block with its items from a list, where it takes them from one (and the list is there): each item's fields as matched. */
+export declare function withListItems(block: Block, site: Pick<WithLists, "lists" | "trailingSlash">): Block;
+/** The site's pages and its lists' item pages: every address the site answers at, each section's items from its list where it takes them from one. */
+export declare const allPages: (site: WithLists) => Page[];
+/** Whether a page is an item page (its blocks carry an item). */
+export declare const itemOf: (page: Page) => ListItem | null;
+export {};

package/dist/content/lists.js

@@ -0,0 +1,77 @@
+// A site's lists (cal-os docs/design/site-lists.md): items of one kind (products, team members,
+// testimonials) kept once in the content, repeated by built sections (Repeats for
+// `lists.<key>.items`), and, where a list has a page, each item at its own address, drawn from one
+// design: `/products/walnut-desk/` is the products page's blocks with that item, read as `this.<field>`.
+// Pure: the build, the preview and CalOS find the same pages.
+import { z } from "zod";
+/** The kinds a list's field may be. */
+export const FIELD_KINDS = ["text", "longText", "image", "link", "number", "date"];
+/** An item page's blocks carry the item they're drawn with (read by built sections as `this.`). */
+export const THIS_ITEM = "thisItem";
+const listsOf = (site) => Object.entries(site.lists ?? {}).filter(([, l]) => l && typeof l === "object");
+/** An item page's address: under its list's page, by its address part. */
+export const itemPath = (page, slug, trailingSlash = true) => `${page.path.replace(/\/$/, "")}/${slug}${trailingSlash ? "/" : ""}`;
+/** Words for a value used as a page's title or description. */
+const words = (v) => (typeof v === "string" ? v : typeof v === "number" ? String(v) : "");
+/** Every item page of every list that has a page, as pages: its design's blocks, each carrying the item. */
+export function itemPages(site) {
+    const out = [];
+    for (const [, list] of listsOf(site)) {
+        const page = list.page;
+        if (!page || !Array.isArray(page.blocks) || !Array.isArray(list.items))
+            continue;
+        // The item's first picture is what it's shared with (no card made for each item).
+        const picture = list.fields.find((f) => f.kind === "image")?.key;
+        for (const item of list.items) {
+            if (!item?.slug)
+                continue;
+            const share = picture ? item[picture] : undefined;
+            out.push({
+                path: itemPath(page, item.slug, site.trailingSlash !== false),
+                title: words(item[page.title]) || item.slug,
+                description: page.description ? words(item[page.description]) : "",
+                noindex: false,
+                ...(share && typeof share === "object" && share.src ? { share } : {}),
+                blocks: page.blocks.map((b) => ({ ...b, [THIS_ITEM]: item })),
+            });
+        }
+    }
+    return out;
+}
+/** In a FromList's fields: the item's own page, where its list has pages. */
+export const PAGE_LINK = "@page";
+/**
+ * The field a section that repeats things adds to say its items can come from a list: `into` names
+ * its array (`items`, `people`). CalOS offers the site's lists for it and matches the fields.
+ */
+export const fromList = (into) => z
+    .object({
+    list: z.string().regex(/^[\w-]{1,60}$/),
+    into: z.literal(into).default(into),
+    fields: z.record(z.string().regex(/^[\w-]{1,60}$/), z.string().regex(/^(@page|[\w-]{1,60})$/)).default({}),
+})
+    .optional()
+    .meta({ title: "Items from a list", "x-ui": "list-source", "x-into": into });
+/** A block with its items from a list, where it takes them from one (and the list is there): each item's fields as matched. */
+export function withListItems(block, site) {
+    const from = block.from;
+    if (!from?.list || !from.into)
+        return block;
+    const list = site.lists?.[from.list];
+    if (!list || !Array.isArray(list.items))
+        return block;
+    const kinds = new Map(list.fields.map((f) => [f.key, f.kind]));
+    const items = list.items.map((item) => Object.fromEntries(Object.entries(from.fields ?? {}).flatMap(([to, src]) => {
+        const v = src === PAGE_LINK ? (list.page && item.slug ? itemPath(list.page, item.slug, site.trailingSlash !== false) : undefined) : item[src];
+        if (v !== undefined && v !== null && v !== "")
+            return [[to, v]];
+        // Words left empty are empty words, so a section drawing them as text has something to draw.
+        const kind = src === PAGE_LINK ? undefined : kinds.get(src);
+        return kind === "text" || kind === "longText" ? [[to, ""]] : [];
+    })));
+    return { ...block, [from.into]: items };
+}
+/** The site's pages and its lists' item pages: every address the site answers at, each section's items from its list where it takes them from one. */
+export const allPages = (site) => [...site.pages, ...itemPages(site)].map((p) => (p.blocks.some((b) => b.from?.list) ? { ...p, blocks: p.blocks.map((b) => withListItems(b, site)) } : p));
+/** Whether a page is an item page (its blocks carry an item). */
+export const itemOf = (page) => page.blocks[0]?.[THIS_ITEM] ?? null;

package/dist/content/lists.test.d.ts

@@ -0,0 +1 @@
+export {};