@vectoriox/iox-ui 5.28.0 → 5.29.0

package/src/generation-core/compose-site.ts

@@ -1,21 +1,24 @@
-import { DesignChoices, resolveDesignChoices } from '@vectoriox/iox-ui/design-core';
+import { DesignChoices, LinkType, resolveDesignChoices } from '@vectoriox/iox-ui/design-core';
+import { FormPresetDef, FormPresetField, formPresetById } from '@vectoriox/iox-ui/forms-core';
 
 import { NODE_BASELINES } from './node-baselines.generated';
 import { BindScope, PatternDirective, PatternNode, PatternPlaceholder, SitePattern, patternById } from './patterns';
-import { assertStyleSlots, createSerializedNode, SerializedBinding, SerializedNode, setStyleProps, ComposeError, walkSerialized } from './serialized-node';
+import { assertStyleSlots, ComposeError, createSerializedNode, SerializedBinding, SerializedNode, setStyleProps } from './serialized-node';
 import {
     ContentTypePlan, DataSourcePlan, FactKey, FACT_KEYS, GlobalSlot, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType,
     RelativeOp, SitePlan, SitePlanSource, SITE_FACT_LABELS, SiteBusiness,
 } from './site-plan.model';
-import { assertValidSitePlan, NAV_PAGES_ALIAS, nextSourceOf, routeParams } from './validate-site-plan';
+import { assertValidSitePlan, nextSourceOf, routeParams } from './validate-site-plan';
 
 /**
  * THE composer — a Site Plan in, ordinary IOX data out (design-system plan §6b, W1). Deterministic and
  * pure: the same plan composes to byte-identical output, with no clock, no randomness and no transport.
- * The wizard and the AI agent both end here; W2's site-build service writes what it returns.
+ * The wizard and the AI agent both end here; W2's site-build service writes what it returns. The one
+ * thing that changes with time — the copyright year — comes in through `ComposeContext`.
  *
  * Every node is created the way the builder creates one (`createSerializedNode`): the type's full
- * constructor defaults, then ONE element style, then the pattern's layout. So a composed page is what
+ * constructor defaults — its empty-drop sizes released, so the pattern owns its box (`BASELINE_ROLES`) —
+ * then ONE element style, then the pattern's layout. So a composed page is what
  * an author would have built by hand from the palette — the builder reloads it and saves it unchanged,
  * and the engine renders it with nothing to resolve. Never a colour, size or font a pattern did not
  * name; never a fact the customer did not give (blank → a placeholder carrying the fact's label).
@@ -45,15 +48,34 @@ export enum ComposeIssueCode {
     /** A slot the plan and the business left empty and the pattern gives no words for — the node keeps
      *  its type's default text. */
     UnfilledSlot = 'unfilled-slot',
-    /** A pattern links to a route the plan has no page for (an optional page was left out). */
-    DanglingLink = 'dangling-link',
+    /** A link to a page the plan leaves out now opens an email to the business (`mailto:`). */
+    LinkToEmail = 'link-to-email',
+    /** A link or button to a page the plan leaves out, with no business email to send to: removed. */
+    LinkRemoved = 'link-removed',
+    /** A linked box to a page the plan leaves out, with no business email: it keeps its contents as a
+     *  plain Container and loses only the link. */
+    LinkUnlinked = 'link-unlinked',
 }
 
+/** The issues that are a dangling link (a route the plan has no page for) and what was done about it. */
+export const DANGLING_LINK_CODES: ReadonlySet<ComposeIssueCode> = new Set([
+    ComposeIssueCode.LinkToEmail, ComposeIssueCode.LinkRemoved, ComposeIssueCode.LinkUnlinked,
+]);
+
 export interface ComposeIssue {
     code: ComposeIssueCode;
     nodeId: string;
     owner: string;
+    /** In plain words, for the wizard to show. */
     detail: string;
+    /** A dangling link's route. */
+    route?: string;
+}
+
+/** What the composer may not decide for itself — today the clock. */
+export interface ComposeContext {
+    /** The calendar year the copyright line reads (`{year}`), from the caller's clock. */
+    year: number;
 }
 
 export interface ComposedPage {
@@ -131,19 +153,40 @@ const BIND_PROP: Readonly<Record<string, string>> = {
     Link: 'label',
     Image: 'src',
 };
-/** Types whose `href` is a website page (`linkType: page` + `pageRoute`). */
-const PAGE_LINK_TYPES: ReadonlySet<string> = new Set(['Link', 'LinkedContainer']);
+/** Where each linking type writes a page link and an external URL (a ButtonBlock links only as an `<a>`). */
+interface LinkSlots { url: string; fixed?: Readonly<Record<string, string>>; }
+const LINK_SLOTS: Readonly<Record<string, LinkSlots>> = {
+    Link: { url: 'url' },
+    LinkedContainer: { url: 'url' },
+    ButtonBlock: { url: 'href', fixed: { tag: 'a' } },
+};
+/** What a linked box becomes when its link has nowhere to go: the same box, unlinked. */
+const UNLINKED_TYPE: Readonly<Record<string, string>> = { LinkedContainer: 'Container' };
 const BUTTON_BLOCK = 'ButtonBlock';
 const FORM = 'Form';
-const FORM_STATE_BLOCKS = ['FormSuccess', 'FormError'];
-const LINK_TYPE_PAGE = 'page';
-const ANCHOR_TAG = 'a';
+const FIELD = 'Field';
+const IMAGE = 'Image';
+const SUBMIT_BUTTON = 'SubmitButton';
+const FORM_SUCCESS = 'FormSuccess';
+const FORM_ERROR = 'FormError';
+const FORM_STATE_BLOCKS = [FORM_SUCCESS, FORM_ERROR];
+/** The Field traits a preset field fills, 1:1 (`FormPresetField`). */
+const PRESET_FIELD_PROPS: ReadonlyArray<keyof FormPresetField> = ['label', 'control', 'required', 'help', 'placeholder', 'optionsText', 'rows'];
 const LABEL_TAG = 'span';
 const TEXT = 'Text';
-/** A button's label reads the button's type and ink (the consent preset's labels, `consent-preset.ts`). */
-const BUTTON_LABEL_INHERITS = { fontSize: 'inherit', fontWeight: 'inherit', color: 'inherit' };
+/** A button's label reads the button's own type and ink (contract element style, W1.1 Q6). */
+const BUTTON_LABEL_STYLE = 'button-label';
 const ITEM_VALUE_PATH = '$';
 const STATUS_DRAFT = 'draft';
+const MAILTO = 'mailto:';
+/** A pattern's `alt: ''` — the image is decorative and its alt is written empty. */
+const DECORATIVE_ALT = '';
+/** What the composer writes for every node: the pattern owns the box (W1.1, Q1). */
+const COMPOSED = { releaseLayoutDefaults: true };
+/** The words a pattern may leave for compose time: the year (`ComposeContext`) and the business name. */
+const TEXT_VARIABLE = /\{(year|business\.name)\}/g;
+/** What `page.*` may read on a node stamped for a navigation page. */
+const STAMPED_PAGE_FIELDS: ReadonlySet<string> = new Set(['name', 'route']);
 
 const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
 
@@ -157,12 +200,8 @@ function stableHash(text: string): string {
     return h.toString(36).padStart(7, '0').slice(-6);
 }
 
-/** A page route as a base-relative href — the engine's `resolvePageHref` form (`/contact` → `contact`,
- *  `/` → `./`), so a link stays inside the org's `<base href>`. */
-export function baseRelativeHref(route: string): string {
-    const path = route.replace(/\/{2,}/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
-    return path || './';
-}
+const create = (id: string, type: string, props: Record<string, unknown> = {}, elementStyle?: string | null) =>
+    createSerializedNode(id, type, props, elementStyle, COMPOSED);
 
 interface RepeaterScope {
     /** The alias a row's children bind (`repeaterItemAlias`: the iterate-path's last segment, else the source). */
@@ -174,6 +213,11 @@ interface Ctx {
     page: PagePlan | null;
     section: PageSectionPlan | null;
     plan: SitePlan;
+    year: number;
+    /** The business email a dangling link is pointed at, when the customer gave one. */
+    email: string | null;
+    /** The navigation page an `each: $navPages` node is being stamped for. */
+    navPage: PagePlan | null;
     /** `next.*` → this alias. */
     nextAlias: string | null;
     placeholders: ComposedPlaceholder[];
@@ -185,6 +229,11 @@ function nonEmpty(v: unknown): v is string {
     return typeof v === 'string' && v.trim() !== '';
 }
 
+/** A pattern's own words with the compose-time variables filled: `{year}`, `{business.name}`. */
+function fillVariables(text: string, ctx: Ctx): string {
+    return text.replace(TEXT_VARIABLE, (_m, name: string) => (name === 'year' ? String(ctx.year) : ctx.plan.business.name));
+}
+
 interface TextChoice {
     value?: string;
     placeholder?: { kind: PlaceholderKind; fact?: FactKey };
@@ -204,17 +253,17 @@ function chooseText(pn: PatternNode, ctx: Ctx): TextChoice {
         const given = ctx.plan.business.facts?.[fact];
         return nonEmpty(given) ? { value: given } : { value: SITE_FACT_LABELS[fact], placeholder: { kind: PlaceholderKind.Fact, fact } };
     }
-    if (pn.ph === PatternPlaceholder.Copy) return { value: pn.text, placeholder: { kind: PlaceholderKind.Copy } };
-    return { value: pn.text };
+    const own = pn.text === undefined ? undefined : fillVariables(pn.text, ctx);
+    if (pn.ph === PatternPlaceholder.Copy) return { value: own, placeholder: { kind: PlaceholderKind.Copy } };
+    return { value: own };
 }
 
-/** A `bind` / `param` / `src` path → the binding source + path, in this node's scope. */
+/** A `bind` / `alt` / `param` / `src` path → the binding source + path, in this node's scope. */
 function resolveScoped(path: string, repeater: RepeaterScope | null, ctx: Ctx, nodeId: string): { source: string; path: string } {
     const [scope, ...rest] = path.split('.');
     const sub = rest.join('.');
     switch (scope) {
         case BindScope.Item:
-        case BindScope.Page:
             if (!repeater) throw new ComposeError(`${nodeId}: "${path}" outside a Repeater`);
             return { source: repeater.itemAlias, path: sub || ITEM_VALUE_PATH };
         case BindScope.Route:
@@ -228,6 +277,24 @@ function resolveScoped(path: string, repeater: RepeaterScope | null, ctx: Ctx, n
     }
 }
 
+/** `page.<field>` on a node stamped for a navigation page: that page's own words, written in. */
+function stampedPageValue(path: string, ctx: Ctx, nodeId: string): string {
+    const field = path.split('.').slice(1).join('.');
+    if (!ctx.navPage) throw new ComposeError(`${nodeId}: "${path}" on a node that is not stamped per page (each)`);
+    if (!STAMPED_PAGE_FIELDS.has(field)) throw new ComposeError(`${nodeId}: a page has no "${field}" (${[...STAMPED_PAGE_FIELDS].join(', ')})`);
+    return (ctx.navPage as unknown as Record<string, string>)[field];
+}
+
+const isPageScope = (path: string | undefined) => !!path && path.split('.')[0] === BindScope.Page;
+
+/** The content type behind a data source alias (a relative source reads its `within` list's type). */
+function contentTypeOfSource(alias: string, plan: SitePlan): ContentTypePlan | undefined {
+    const ds = plan.dataSources.find(d => d.alias === alias);
+    if (!ds) return undefined;
+    if (ds.type === PlanDataSourceType.Relative) return contentTypeOfSource(ds.within, plan);
+    return plan.contentTypes.find(t => t.name === ds.contentType);
+}
+
 function addBinding(node: SerializedNode, binding: SerializedBinding): void {
     const declared = NODE_BASELINES[node.type]?.traits ?? [];
     if (!declared.includes(binding.prop) && !binding.prop.startsWith('routeParam:')) {
@@ -246,10 +313,135 @@ function setProp(node: SerializedNode, name: string, value: unknown): void {
     node.props[name] = value;
 }
 
-/** One pattern node → one serialized node (and its subtree). `null` when the section leaves it out. */
+function linkSlots(node: SerializedNode): LinkSlots {
+    const slots = LINK_SLOTS[node.type];
+    if (!slots) throw new ComposeError(`${node.id}: ${node.type} cannot link`);
+    return slots;
+}
+
+/** A link to one of the site's pages, by route — the builder shows the route, the engine resolves it. */
+function writePageLink(node: SerializedNode, route: string): void {
+    const slots = linkSlots(node);
+    for (const [k, v] of Object.entries(slots.fixed ?? {})) setProp(node, k, v);
+    setProp(node, 'linkType', LinkType.Page);
+    setProp(node, 'pageRoute', route);
+}
+
+function writeExternalLink(node: SerializedNode, url: string): void {
+    const slots = linkSlots(node);
+    for (const [k, v] of Object.entries(slots.fixed ?? {})) setProp(node, k, v);
+    setProp(node, 'linkType', LinkType.External);
+    setProp(node, slots.url, url);
+}
+
+/** What happens to a node linking to a route the plan has no page for (W1.1, Q11) — the same rule for
+ *  every pattern and every page: an email to the business when one is given; else a link or button is
+ *  removed and a linked box keeps its contents, unlinked. */
+enum DanglingFate {
+    Email = 'email',
+    Remove = 'remove',
+    Unlink = 'unlink',
+}
+
+function danglingFate(pn: PatternNode, ctx: Ctx): DanglingFate | null {
+    if (!pn.href || pn.href === PatternDirective.PageRoute || ctx.routes.has(pn.href)) return null;
+    if (ctx.email) return DanglingFate.Email;
+    return UNLINKED_TYPE[pn.t] ? DanglingFate.Unlink : DanglingFate.Remove;
+}
+
+const DANGLING_ISSUE: Readonly<Record<DanglingFate, ComposeIssueCode>> = {
+    [DanglingFate.Email]: ComposeIssueCode.LinkToEmail,
+    [DanglingFate.Remove]: ComposeIssueCode.LinkRemoved,
+    [DanglingFate.Unlink]: ComposeIssueCode.LinkUnlinked,
+};
+
+function reportDangling(fate: DanglingFate, pn: PatternNode, id: string, words: string | undefined, ctx: Ctx): void {
+    const what = words ? `"${words}"` : `A ${pn.t === BUTTON_BLOCK ? 'button' : 'link'}`;
+    const outcome = {
+        [DanglingFate.Email]: `it now opens an email to ${ctx.email}`,
+        [DanglingFate.Remove]: 'with no email address to send to instead, it was removed',
+        [DanglingFate.Unlink]: 'with no email address to send to instead, the box keeps its contents without the link',
+    }[fate];
+    ctx.issues.push({
+        code: DANGLING_ISSUE[fate], nodeId: id, owner: ctx.owner, route: pn.href,
+        detail: `${what} linked to ${pn.href}, which this site has no page for — ${outcome}.`,
+    });
+}
+
+/** The alt binding of a bound Image: the pattern's `alt`, else the bound item's preview text field. */
+function altBinding(pn: PatternNode, repeater: RepeaterScope | null, ctx: Ctx, id: string): { source: string; path: string } {
+    if (pn.alt) return resolveScoped(pn.alt, repeater, ctx, id);
+    const bound = resolveScoped(pn.bind as string, repeater, ctx, id);
+    const field = contentTypeOfSource(bound.source, ctx.plan)?.previewTextField;
+    if (!field) throw new ComposeError(`${id}: a bound image needs an alt — the pattern names none and "${bound.source}" has no previewTextField`);
+    return { source: bound.source, path: field };
+}
+
+/** A preset Form's children — the forms-core preset's fields, submit and the WORDS of both state blocks. */
+function presetChildren(preset: FormPresetDef, id: string): SerializedNode[] {
+    const fields = preset.fields.map((f, i) => {
+        const props = Object.fromEntries(PRESET_FIELD_PROPS.filter(k => f[k] !== undefined).map(k => [k, f[k]]));
+        assertTraits(FIELD, Object.keys(props));
+        return create(`${id}-${i}`, FIELD, props);
+    });
+    const n = fields.length;
+    const submit = create(`${id}-${n}`, SUBMIT_BUTTON, { label: preset.submitLabel });
+    const blocks = [[FORM_SUCCESS, preset.successText], [FORM_ERROR, preset.errorText]].map(([type, words], i) => {
+        const block = create(`${id}-${n + 1 + i}`, type);
+        block.children = [create(`${id}-${n + 1 + i}-0`, TEXT, { content: words })];
+        return block;
+    });
+    return [...fields, submit, ...blocks];
+}
+
+/** A Form: its stable id, its preset's name and children (or the pattern's own children), and both state
+ *  blocks — never optional (forms plan D7). */
+function composeForm(node: SerializedNode, pn: PatternNode, id: string, ctx: Ctx): void {
+    if (!pn.preset) {
+        node.children = [...(node.children ?? []), ...FORM_STATE_BLOCKS.map((type, i) => create(`${id}-${(pn.c?.length ?? 0) + i}`, type))];
+        return;
+    }
+    const preset = formPresetById(pn.preset);
+    if (!preset) throw new ComposeError(`${id}: no form preset "${pn.preset}" in forms-core`);
+    if (pn.c?.length) throw new ComposeError(`${id}: a preset Form takes its fields from the preset, not the pattern`);
+    setProp(node, 'name', preset.formName);
+    setProp(node, 'formId', `${preset.id}-${stableHash(`${ctx.owner}/${id}`)}`);
+    node.children = presetChildren(preset, id);
+}
+
+/** A pattern node's children; an `each` child is stamped once per navigation page, its id carrying the
+ *  page key so it survives a page being left out or reordered. */
+function composeChildren(pn: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode[] {
+    const out: SerializedNode[] = [];
+    (pn.c ?? []).forEach((child, i) => {
+        const childId = `${id}-${i}`;
+        if (!child.each) {
+            const node = composeNode(child, childId, repeater, ctx);
+            if (node) out.push(node);
+            return;
+        }
+        if (child.each !== PatternDirective.NavPages) throw new ComposeError(`${childId}: "each" stamps "${PatternDirective.NavPages}" only`);
+        for (const page of ctx.plan.pages.filter(p => p.inNav)) {
+            const node = composeNode(child, `${childId}-${page.key}`, repeater, { ...ctx, navPage: page });
+            if (node) out.push(node);
+        }
+    });
+    return out;
+}
+
+/** One pattern node → one serialized node (and its subtree). `null` when the section leaves it out or a
+ *  dangling link is removed. */
 function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode | null {
     if (pn.optional && ctx.section?.without?.includes(pn.optional)) return null;
 
+    const words = chooseText(pn, ctx);
+    const fate = danglingFate(pn, ctx);
+    if (fate === DanglingFate.Remove) {
+        reportDangling(fate, pn, id, words.value, ctx);
+        return null;
+    }
+    const type = fate === DanglingFate.Unlink ? UNLINKED_TYPE[pn.t] : pn.t;
+
     const props: Record<string, unknown> = {};
     if (pn.level) props['level'] = pn.level;
     if (pn.tag) props['htmlTag'] = pn.tag;
@@ -257,31 +449,28 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
     if (pn.control) props['control'] = pn.control;
     if (pn.label) props['label'] = pn.label;
     if (pn.required !== undefined) props['required'] = pn.required;
-    assertTraits(pn.t, Object.keys(props));
+    assertTraits(type, Object.keys(props));
     // Props first: a Heading with no `es` wears its LEVEL's default style.
-    const node = createSerializedNode(id, pn.t, props, pn.es ?? null);
+    const node = create(id, type, props, pn.es ?? null);
 
     // Words.
-    const words = chooseText(pn, ctx);
     if (words.placeholder) {
-        const shown = words.value ?? String(NODE_BASELINES[pn.t]?.props[TEXT_PROP[pn.t]] ?? '');
+        const shown = words.value ?? String(NODE_BASELINES[type]?.props[TEXT_PROP[type]] ?? '');
         ctx.placeholders.push({ nodeId: id, owner: ctx.owner, kind: words.placeholder.kind, ...(words.placeholder.fact ? { fact: words.placeholder.fact } : {}), ...(pn.slot ? { slot: pn.slot } : {}), text: shown });
     } else if (words.value === undefined && (pn.slot || pn.fromBusiness)) {
-        ctx.issues.push({ code: ComposeIssueCode.UnfilledSlot, nodeId: id, owner: ctx.owner, detail: `no value for ${pn.slot ? `slot "${pn.slot}"` : `business "${pn.fromBusiness}"`} — keeps the ${pn.t} default` });
+        ctx.issues.push({ code: ComposeIssueCode.UnfilledSlot, nodeId: id, owner: ctx.owner, detail: `no value for ${pn.slot ? `slot "${pn.slot}"` : `business "${pn.fromBusiness}"`} — keeps the ${type} default` });
     }
     if (words.value !== undefined) {
-        if (pn.t === BUTTON_BLOCK) {
-            const label = createSerializedNode(`${id}-label`, TEXT, { content: words.value, tag: LABEL_TAG });
-            setStyleProps(label, BUTTON_LABEL_INHERITS);
-            node.children = [label];
+        if (type === BUTTON_BLOCK) {
+            node.children = [create(`${id}-label`, TEXT, { content: words.value, tag: LABEL_TAG }, BUTTON_LABEL_STYLE)];
         } else {
-            const prop = TEXT_PROP[pn.t];
-            if (!prop) throw new ComposeError(`${id}: ${pn.t} cannot hold text`);
+            const prop = TEXT_PROP[type];
+            if (!prop) throw new ComposeError(`${id}: ${type} cannot hold text`);
             setProp(node, prop, words.value);
         }
     }
 
-    // Images.
+    // Images: an empty slot, or a bound one — both fall back to the DS3 empty image, never a stock URL.
     if (pn.ph === PatternPlaceholder.Image) {
         setProp(node, 'src', '');
         ctx.placeholders.push({ nodeId: id, owner: ctx.owner, kind: PlaceholderKind.Image, text: '' });
@@ -289,32 +478,31 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
     if (pn.aspect) setStyleProps(node, { aspectRatio: pn.aspect });
 
     // Links.
-    if (pn.href) {
-        if (pn.href === PatternDirective.PageRoute) {
-            setProp(node, 'linkType', LINK_TYPE_PAGE);
-            addBinding(node, { prop: 'pageRoute', ...resolveScoped(`${BindScope.Page}.route`, repeater, ctx, id) });
-        } else {
-            if (!ctx.routes.has(pn.href)) ctx.issues.push({ code: ComposeIssueCode.DanglingLink, nodeId: id, owner: ctx.owner, detail: `links to ${pn.href}, which the plan has no page for` });
-            if (PAGE_LINK_TYPES.has(pn.t)) {
-                setProp(node, 'linkType', LINK_TYPE_PAGE);
-                setProp(node, 'pageRoute', pn.href);
-            } else if (pn.t === BUTTON_BLOCK) {
-                setProp(node, 'tag', ANCHOR_TAG);
-                setProp(node, 'href', baseRelativeHref(pn.href));
-            } else {
-                throw new ComposeError(`${id}: ${pn.t} cannot link`);
-            }
-        }
+    if (pn.href === PatternDirective.PageRoute) {
+        writePageLink(node, stampedPageValue(`${BindScope.Page}.route`, ctx, id));
+    } else if (pn.href && !fate) {
+        writePageLink(node, pn.href);
+    } else if (fate) {
+        if (fate === DanglingFate.Email) writeExternalLink(node, `${MAILTO}${ctx.email}`);
+        reportDangling(fate, pn, id, words.value, ctx);
     }
-    if (pn.param) {
+    if (pn.param && !fate) {
         const names = pn.href ? routeParams(pn.href) : [];
         if (names.length !== 1) throw new ComposeError(`${id}: "param" needs an href with one :param`);
         addBinding(node, { prop: `routeParam:${names[0]}`, ...resolveScoped(pn.param, repeater, ctx, id) });
     }
     if (pn.bind) {
-        const prop = BIND_PROP[pn.t];
-        if (!prop) throw new ComposeError(`${id}: ${pn.t} has no bindable value`);
-        addBinding(node, { prop, ...resolveScoped(pn.bind, repeater, ctx, id) });
+        const prop = BIND_PROP[type];
+        if (!prop) throw new ComposeError(`${id}: ${type} has no bindable value`);
+        if (isPageScope(pn.bind)) setProp(node, prop, stampedPageValue(pn.bind, ctx, id));
+        else addBinding(node, { prop, ...resolveScoped(pn.bind, repeater, ctx, id) });
+    }
+    if (type === IMAGE && pn.bind && !isPageScope(pn.bind)) {
+        setProp(node, 'src', '');
+        if (pn.alt === DECORATIVE_ALT) setProp(node, 'alt', DECORATIVE_ALT);
+        else addBinding(node, { prop: 'alt', ...altBinding(pn, repeater, ctx, id) });
+    } else if (pn.alt !== undefined) {
+        throw new ComposeError(`${id}: "alt" belongs on a bound Image`);
     }
 
     // Layout.
@@ -331,8 +519,6 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
         if (pn.src === PatternDirective.Binding) {
             if (!ctx.section?.binding) throw new ComposeError(`${id}: "$binding" with no section binding`);
             binding = { prop: 'source', source: ctx.section.binding, path: '' };
-        } else if (pn.src === PatternDirective.NavPages) {
-            binding = { prop: 'source', source: NAV_PAGES_ALIAS, path: '' };
         } else {
             const scoped = resolveScoped(pn.src, repeater, ctx, id);
             binding = { prop: 'source', source: scoped.source, path: scoped.path === ITEM_VALUE_PATH ? '' : scoped.path };
@@ -343,28 +529,18 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
     }
 
     // Children.
-    const children = (pn.c ?? [])
-        .map((child, i) => composeNode(child, `${id}-${i}`, rowScope, ctx))
-        .filter((c): c is SerializedNode => !!c);
     if (pn.c?.length) {
-        if (!node.children) throw new ComposeError(`${id}: ${pn.t} holds no children`);
-        node.children = [...node.children, ...children];
-    }
-
-    // A Form: its stable id, and both state blocks — never optional (forms plan D7).
-    if (pn.t === FORM) {
-        if (pn.preset) setProp(node, 'formId', `${pn.preset}-${stableHash(`${ctx.owner}/${id}`)}`);
-        node.children = [
-            ...(node.children ?? []),
-            ...FORM_STATE_BLOCKS.map((type, i) => createSerializedNode(`${id}-${(pn.c?.length ?? 0) + i}`, type)),
-        ];
+        if (!node.children) throw new ComposeError(`${id}: ${type} holds no children`);
+        node.children = [...node.children, ...composeChildren(pn, id, rowScope, ctx)];
     }
+    if (type === FORM) composeForm(node, pn, id, ctx);
     return node;
 }
 
 function composePattern(pattern: SitePattern, id: string, ctx: Ctx): SerializedNode {
+    if (pattern.node.each) throw new ComposeError(`${id}: a pattern's root cannot be stamped per page`);
     const node = composeNode(pattern.node, id, null, ctx);
-    if (!node) throw new ComposeError(`${id}: a pattern's root cannot be optional`);
+    if (!node) throw new ComposeError(`${id}: a pattern's root cannot be optional or a link`);
     node.label = pattern.label;
     return node;
 }
@@ -384,13 +560,6 @@ function composeDataSource(ds: DataSourcePlan): ComposedDataSource {
     };
 }
 
-function navPagesSource(plan: SitePlan): ComposedDataSource {
-    return {
-        id: `ds-${NAV_PAGES_ALIAS}`, alias: NAV_PAGES_ALIAS, type: 'static', mode: PlanDataSourceMode.Query,
-        request: { data: plan.pages.filter(p => p.inNav).map(p => ({ name: p.name, route: p.route })) },
-    };
-}
-
 function expandSeedValue(value: unknown, n: number): unknown {
     if (Array.isArray(value)) return value.map(v => expandSeedValue(v, n));
     if (typeof value !== 'string') return value;
@@ -411,24 +580,19 @@ function composeItems(type: ContentTypePlan): ComposedItem[] {
     return items;
 }
 
-/** True when a composed tree iterates the navigation's pages. */
-function bindsAlias(trees: ReadonlyArray<ReadonlyArray<SerializedNode>>, alias: string): boolean {
-    let found = false;
-    for (const tree of trees) walkSerialized(tree, node => { if (node.bindings.some(b => b.source === alias)) found = true; });
-    return found;
-}
-
 /**
  * Compose a Site Plan. Throws `SitePlanError` (every issue) when the plan does not validate — the
- * composer never repairs a plan.
+ * composer never repairs a plan. `context` carries what the composer may not read for itself (the year).
  */
-export function composeSite(plan: SitePlan): ComposedSite {
+export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSite {
     assertValidSitePlan(plan);
+    if (!Number.isInteger(context?.year)) throw new ComposeError('composeSite needs the year (ComposeContext.year) — the composer reads no clock');
     const placeholders: ComposedPlaceholder[] = [];
     const issues: ComposeIssue[] = [];
     const routes = new Set(plan.pages.map(p => p.route));
     const relatives = new Map(plan.dataSources.map(d => [d.alias, d.type === PlanDataSourceType.Relative ? { type: d.type, of: d.of, op: d.op } : { type: d.type }]));
-    const base = { plan, placeholders, issues, routes };
+    const email = nonEmpty(plan.business.facts?.email) ? plan.business.facts!.email!.trim() : null;
+    const base = { plan, placeholders, issues, routes, year: context.year, email, navPage: null };
 
     const pages: ComposedPage[] = plan.pages.map(page => {
         const nextAlias = page.routeSource ? nextSourceOf(relatives, page.routeSource) : null;
@@ -455,16 +619,13 @@ export function composeSite(plan: SitePlan): ComposedSite {
         return node;
     });
 
-    const dataSources = plan.dataSources.map(composeDataSource);
-    if (bindsAlias([...pages.map(p => p.layout), globals], NAV_PAGES_ALIAS)) dataSources.push(navPagesSource(plan));
-
     return {
         source: clone(plan.source),
         business: clone(plan.business),
         design: resolveDesignChoices(clone(plan.design)),
         schemas: clone(plan.contentTypes) as ContentTypePlan[],
         items: Object.fromEntries(plan.contentTypes.map(t => [t.name, composeItems(t)])),
-        dataSources,
+        dataSources: plan.dataSources.map(composeDataSource),
         pages,
         globals,
         routes: plan.pages.map(p => ({ key: p.key, path: p.route, isHome: p.isHome === true })),

package/src/generation-core/node-baselines.generated.ts

@@ -196,7 +196,9 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
   "ButtonBlock": {
     "props": {
       "tag": "button",
+      "linkType": "external",
       "href": "",
+      "pageRoute": "",
       "target": "_self",
       "type": "button"
     },
@@ -286,7 +288,9 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
     },
     "traits": [
       "tag",
+      "linkType",
       "href",
+      "pageRoute",
       "target",
       "type"
     ],
@@ -4839,3 +4843,89 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
     "container": true
   }
 };
+
+/** What every style trait saves as when no constructor sets it (buildFullStyleTraits' defaults). */
+export const NEUTRAL_STYLE_PROPS: Readonly<Record<string, unknown>> = {
+  "position": "static",
+  "top": "auto",
+  "right": "auto",
+  "bottom": "auto",
+  "left": "auto",
+  "zIndex": "0",
+  "display": "block",
+  "flexDirection": "row",
+  "flexWrap": "nowrap",
+  "justifyContent": "flex-start",
+  "alignItems": "stretch",
+  "gap": "0px",
+  "gridTemplateColumns": "1fr",
+  "gridTemplateRows": "auto",
+  "justifyItems": "stretch",
+  "alignContent": "stretch",
+  "direction": "ltr",
+  "alignSelf": "auto",
+  "order": "0",
+  "flexGrow": "0",
+  "flexShrink": "1",
+  "flexBasis": "auto",
+  "justifySelf": "auto",
+  "gridColumn": "auto",
+  "gridRow": "auto",
+  "width": "auto",
+  "height": "auto",
+  "minWidth": "auto",
+  "minHeight": "auto",
+  "maxWidth": "auto",
+  "maxHeight": "auto",
+  "aspectRatio": "auto",
+  "objectFit": "cover",
+  "overflow": "visible",
+  "fontFamily": "Poppins, sans-serif",
+  "fontSize": "16px",
+  "fontWeight": "400",
+  "color": "#000000",
+  "lineHeight": "1.5",
+  "letterSpacing": "0px",
+  "textTransform": "none",
+  "textAlign": "left",
+  "fontStyle": "normal",
+  "textDecoration": "none",
+  "WebkitTextStrokeWidth": "0px",
+  "WebkitTextStrokeColor": "transparent",
+  "margin": "0px 0px 0px 0px",
+  "padding": "0px 0px 0px 0px",
+  "borderWidth": "0px",
+  "borderStyle": "solid",
+  "borderColor": "#CCCCCC",
+  "borderRadius": "0px",
+  "backgroundColor": "transparent",
+  "opacity": "1",
+  "mixBlendMode": "normal",
+  "cursor": "auto",
+  "boxShadow": "",
+  "textShadow": "",
+  "translateX": "0px",
+  "translateY": "0px",
+  "scaleX": "1",
+  "scaleY": "1",
+  "rotate": "0deg",
+  "skewX": "0deg",
+  "skewY": "0deg",
+  "filterBlur": "0px",
+  "filterHueRotate": "0deg",
+  "filterBrightness": "1",
+  "filterContrast": "1",
+  "filterSaturate": "1",
+  "filterGrayscale": "0",
+  "filterSepia": "0",
+  "filterInvert": "0",
+  "backdropFilter": "none",
+  "backdropBlur": "0px",
+  "backdropBrightness": "1",
+  "backdropContrast": "1",
+  "backdropSaturate": "1",
+  "clipPath": "none",
+  "transitionDuration": "0ms",
+  "transitionDelay": "0ms",
+  "transitionTimingFunction": "ease"
+};