@caelo-cms/shared 0.10.72 → 0.11.0

package/dist/lists/resolve-values.d.ts

@@ -0,0 +1,63 @@
+import type { FieldDef } from "./fields.js";
+import type { ListRenderData } from "./render-data.js";
+import type { ScopeEntry, ScopeValue } from "./scope.js";
+export declare const EMPTY_TEXT: ScopeValue;
+export declare const FALSE: ScopeValue;
+export declare const TRUE: ScopeValue;
+export declare const EMPTY_LIST: ScopeValue;
+/** A text scope value. */
+export declare function text(s: string): ScopeValue;
+/** A boolean scope value. */
+export declare function bool(v: boolean): ScopeValue;
+/** A record scope value over a fixed key map. */
+export declare function record(bare: string | null, present: boolean, parts: Readonly<Record<string, ScopeValue>>): ScopeValue;
+/** 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 declare function emptyValueOf(field: FieldDef): ScopeValue;
+/** Scope value of a link: bare = href, plus `href`, `target`, `title` (internal page title). */
+export declare function linkValue(v: {
+    readonly href: string;
+    readonly target?: string;
+}, data: ListRenderData | null): ScopeValue;
+/** Scope value of a media reference: bare = url (the reference, resolved later), alt/width/height. */
+export declare function mediaValue(ref: string, data: ListRenderData): ScopeValue;
+/** Scope value of a date or timestamp: bare = the stored ISO string, `formatted` in the site language. */
+export declare function dateValue(iso: string, env: Pick<ValueEnv, "formatDate">): ScopeValue;
+/**
+ * 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 declare function fieldValue(field: FieldDef, raw: unknown, env: ValueEnv): ScopeValue;
+/**
+ * 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 declare function selectFlag(fields: readonly FieldDef[], values: Readonly<Record<string, unknown>>, key: string): ScopeValue | 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 declare function untypedValue(raw: unknown): ScopeValue | undefined;
+/** Position keys every entry carries: `index` (0-based), `first`, `last`, `depth` (1-based). */
+export declare function positionValue(key: string, pos: {
+    readonly index: number;
+    readonly count: number;
+    readonly depth: number;
+}): ScopeValue | undefined;
+/** A list of entries as a scope value, with `has_`/`count_` helpers derived by the caller. */
+export declare function listValue(entries: readonly ScopeEntry[]): ScopeValue;
+//# sourceMappingURL=resolve-values.d.ts.map

package/dist/lists/resolve-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-values.d.ts","sourceRoot":"","sources":["../../src/lists/resolve-values.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,eAAO,MAAM,UAAU,EAAE,UAAuC,CAAC;AACjE,eAAO,MAAM,KAAK,EAAE,UAA2C,CAAC;AAChE,eAAO,MAAM,IAAI,EAAE,UAA0C,CAAC;AAC9D,eAAO,MAAM,UAAU,EAAE,UAA0C,CAAC;AAEpE,0BAA0B;AAC1B,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAE1C;AAED,6BAA6B;AAC7B,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,CAE3C;AAED,iDAAiD;AACjD,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAC1C,UAAU,CAOZ;AAED,0FAA0F;AAC1F,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,kEAAkE;IAClE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;CACjE;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAoBxD;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CACvB,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,UAAU,CASZ;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,UAAU,CASxE;AAED,0GAA0G;AAC1G,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,UAAU,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,UAAU,CAwCnF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,GAAG,EAAE,MAAM,GACV,UAAU,GAAG,SAAS,CAOxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAYjE;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9E,UAAU,GAAG,SAAS,CAaxB;AAED,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAEpE"}

package/dist/lists/resolve-values.js

@@ -0,0 +1,181 @@
+// 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";
+export const EMPTY_TEXT = { kind: "text", text: "" };
+export const FALSE = { kind: "bool", value: false };
+export const TRUE = { kind: "bool", value: true };
+export const EMPTY_LIST = { kind: "list", entries: [] };
+/** A text scope value. */
+export function text(s) {
+    return { kind: "text", text: s };
+}
+/** A boolean scope value. */
+export function bool(v) {
+    return v ? TRUE : FALSE;
+}
+/** A record scope value over a fixed key map. */
+export function record(bare, present, parts) {
+    return {
+        kind: "record",
+        text: bare,
+        present,
+        get: (key) => (Object.hasOwn(parts, key) ? parts[key] : undefined),
+    };
+}
+/** The empty value of a declared field — declared-but-unset never falls through to outer scopes. */
+export function emptyValueOf(field) {
+    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, data) {
+    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, data) {
+    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, env) {
+    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, raw, env) {
+    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.href === "string") {
+                return linkValue(raw, 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;
+            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) => 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, values, key) {
+    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) {
+    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.href === "string") {
+        return linkValue(raw, null);
+    }
+    return undefined;
+}
+/** Position keys every entry carries: `index` (0-based), `first`, `last`, `depth` (1-based). */
+export function positionValue(key, pos) {
+    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) {
+    return { kind: "list", entries };
+}
+//# sourceMappingURL=resolve-values.js.map

package/dist/lists/resolve-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-values.js","sourceRoot":"","sources":["../../src/lists/resolve-values.ts"],"names":[],"mappings":"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"}

package/dist/lists/resolve.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The list resolver (epic #1107, `docs/lists.md` §6, §7, §10). Turns a
+ * module's `list` field — local entries, a shared list, a page query, a
+ * system source or a plugin source — into the entry scopes the template
+ * engine iterates, for ONE rendering page.
+ *
+ * Built once per preview / per build from batch-loaded
+ * {@link ListRenderData} and cut per page with `forPage`, the same split
+ * as `SiteLinkIndex`: everything after loading is pure and synchronous,
+ * and the editor preview and the static generator get byte-identical
+ * output from the same input.
+ *
+ * Per page it also records what the render read ({@link ListRenderDeps}),
+ * which the generator writes to `render-deps.json` so an incremental
+ * build can rebuild exactly the pages a change reaches.
+ *
+ * Loud, never silently empty (CLAUDE.md §2): an unbound shared field, a
+ * deleted list, an unknown type, a plugin source whose plugin is off and
+ * a malformed entry all resolve to a failure marker the engine renders
+ * raw.
+ */
+import type { LinkResolver } from "../link-refs.js";
+import { type SourceDef } from "./list-type.js";
+import type { ListRenderData, ListRenderDeps, PluginSourceEntry } from "./render-data.js";
+import type { ScopeEntry, ScopeValue } from "./scope.js";
+/** True for a list failure marker — the editor's missing-content surface shows these. */
+export declare function isListFailureMarker(marker: string): boolean;
+/** What the resolver needs from a module `list` field (`docs/lists.md` §7). */
+export interface ListFieldSpec {
+    readonly name: string;
+    readonly listType: string;
+    readonly bind?: "local" | "shared" | "source";
+    readonly list?: string;
+    readonly source?: SourceDef;
+    readonly default?: unknown;
+}
+/** Result of resolving one list field for one page. */
+export type ListFieldResolution = {
+    readonly ok: true;
+    readonly entries: readonly ScopeEntry[];
+} | {
+    readonly ok: false;
+    readonly marker: string;
+};
+/**
+ * Where a local list is stored: the content instance holding the module
+ * field's value. Null for module field defaults (site chrome renders
+ * from defaults) — then entries cannot be addressed by a plugin overlay
+ * and carry `local/<field>/<itemId>` as their item attribute.
+ */
+export interface ListHolder {
+    readonly contentInstanceId: string | null;
+}
+/** An overlay entry the resolver refused (unknown address, structural or invalid value). */
+export interface ListOverlayIssue {
+    readonly variant: string;
+    readonly address: string;
+    readonly reason: string;
+}
+/** Per-page options of {@link ListRenderContext.forPage}. */
+export interface ListPageOptions {
+    /** The page's link resolver; drives `is_current` URL comparison. */
+    readonly linkResolver?: LinkResolver;
+    /** Entries of every ACTIVE plugin list source for this page, keyed by source name. */
+    readonly pluginSources?: Readonly<Record<string, readonly PluginSourceEntry[]>>;
+}
+/** The list view of ONE rendering page, handed to the template engine. */
+export interface ListPageContext {
+    /** The rendering page, or null for a render outside any page. */
+    readonly pageId: string | null;
+    /** Resolve a module list field with its placement value. */
+    resolveField(field: ListFieldSpec, value: unknown, holder: ListHolder): ListFieldResolution;
+    /** `{{page.*}}`: the rendering page as a record scope; null outside a page. */
+    pageScope(): ScopeValue | null;
+    /**
+     * A section name no module field declares, read as a plugin list
+     * source (`{{#language_links}}` written before the field kind existed).
+     * Null when no installed plugin declares the name.
+     */
+    pluginSource(name: string): ListFieldResolution | null;
+    /** What this page's render read so far. */
+    deps(): ListRenderDeps;
+    /** Overlay values this page's render refused (also the render-wide ones). */
+    overlayIssues(): readonly ListOverlayIssue[];
+}
+/** Render-wide options of {@link createListRenderContext}. */
+export interface ListRenderContextOptions {
+    /** Source names declared by installed-but-inactive plugins → plugin slug. */
+    readonly dormantPluginSources?: Readonly<Record<string, string>>;
+}
+/** The render-wide list context; cut per page with {@link ListRenderContext.forPage}. */
+export interface ListRenderContext {
+    forPage(pageId: string | null, opts?: ListPageOptions): ListPageContext;
+    /** Overlay entries refused while preparing the render (shared lists, page props). */
+    readonly overlayIssues: readonly ListOverlayIssue[];
+}
+/** Resolve one list field for a page (thin wrapper, `docs/lists.md` §10). */
+export declare function resolveListField(field: ListFieldSpec, value: unknown, page: ListPageContext, holder?: ListHolder): ListFieldResolution;
+/** Build the render-wide list context from loaded data. */
+export declare function createListRenderContext(data: ListRenderData, opts?: ListRenderContextOptions): ListRenderContext;
+/** Every embedded module a set of shared lists references (`module` fields), for batch loading. */
+export declare function collectListModuleRefs(data: Pick<ListRenderData, "lists" | "listTypes">): {
+    moduleId: string;
+    contentInstanceId: string;
+}[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/lists/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/lists/resolve.ts"],"names":[],"mappings":"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"}