@vectoriox/iox-ui 5.26.0 → 5.28.0

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

@@ -0,0 +1,474 @@
+import { DesignChoices, resolveDesignChoices } from '@vectoriox/iox-ui/design-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 {
+    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';
+
+/**
+ * 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.
+ *
+ * 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
+ * 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).
+ */
+
+export enum PlaceholderKind {
+    /** A FACT the customer did not give (email, phone, city): publish-blocking. */
+    Fact = 'fact',
+    /** The pattern's own words, for the author to rewrite. */
+    Copy = 'copy',
+    /** An image slot with no image: the empty-image placeholder (DS3). */
+    Image = 'image',
+}
+
+export interface ComposedPlaceholder {
+    nodeId: string;
+    /** The page key, or the global slot (`header` / `footer`), the node lives in. */
+    owner: string;
+    kind: PlaceholderKind;
+    fact?: FactKey;
+    slot?: string;
+    /** What the node shows meanwhile: the fact's label, the pattern's copy, or '' for an image. */
+    text: string;
+}
+
+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',
+}
+
+export interface ComposeIssue {
+    code: ComposeIssueCode;
+    nodeId: string;
+    owner: string;
+    detail: string;
+}
+
+export interface ComposedPage {
+    key: string;
+    name: string;
+    route: { path: string };
+    isHome: boolean;
+    status: 'draft';
+    /** DS3: every page the wizard creates follows the look (page-bg / text / font-body). */
+    pageSettings: { designSystem: true };
+    layout: SerializedNode[];
+}
+
+export interface ComposedDataSource {
+    id: string;
+    alias: string;
+    type: string;
+    mode: string;
+    request: Record<string, unknown>;
+}
+
+export type ComposedItem = Record<string, unknown> & { isPublished: boolean; isSample: boolean };
+
+export interface ComposedRoute {
+    key: string;
+    path: string;
+    isHome: boolean;
+}
+
+export interface ComposedSite {
+    source: SitePlanSource;
+    business: SiteBusiness;
+    /** The look, completed against its pack (`resolveDesignChoices`) — what the build applies. */
+    design: DesignChoices;
+    /** The content types to create, as the plan states them. */
+    schemas: ContentTypePlan[];
+    /** Sample items per content type. `{sampleImage:k}` values name a bundled sample image the build resolves. */
+    items: Record<string, ComposedItem[]>;
+    /** Merged by alias into the org data-source library. */
+    dataSources: ComposedDataSource[];
+    pages: ComposedPage[];
+    /** Header + footer: root nodes carry `isGlobal` and `globalPosition`. */
+    globals: SerializedNode[];
+    routes: ComposedRoute[];
+    placeholders: ComposedPlaceholder[];
+    issues: ComposeIssue[];
+}
+
+/** `{sampleImage:k}` — a bundled abstract sample image, never a stock photo (plan §6b). */
+export const SAMPLE_IMAGE_REF = /^\{sampleImage:(\d+)\}$/;
+const SAMPLE_IMAGE_TEMPLATE = /\{sampleImage:n(?:\+(\d+))?\}/g;
+const ITEM_NUMBER = /\{n\}/g;
+
+export function sampleImageRef(index: number): string {
+    return `{sampleImage:${index}}`;
+}
+
+/** The 1-based index a `{sampleImage:k}` value names, or null. */
+export function parseSampleImageRef(value: unknown): number | null {
+    const m = typeof value === 'string' ? SAMPLE_IMAGE_REF.exec(value) : null;
+    return m ? Number(m[1]) : null;
+}
+
+/** The prop a pattern's `text` / slot / fact fills, per type. */
+const TEXT_PROP: Readonly<Record<string, string>> = {
+    Heading: 'content',
+    Text: 'content',
+    Link: 'label',
+    SubmitButton: 'label',
+};
+/** The prop a pattern's `bind` binds, per type. */
+const BIND_PROP: Readonly<Record<string, string>> = {
+    Heading: 'content',
+    Text: 'content',
+    Link: 'label',
+    Image: 'src',
+};
+/** Types whose `href` is a website page (`linkType: page` + `pageRoute`). */
+const PAGE_LINK_TYPES: ReadonlySet<string> = new Set(['Link', 'LinkedContainer']);
+const BUTTON_BLOCK = 'ButtonBlock';
+const FORM = 'Form';
+const FORM_STATE_BLOCKS = ['FormSuccess', 'FormError'];
+const LINK_TYPE_PAGE = 'page';
+const ANCHOR_TAG = 'a';
+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' };
+const ITEM_VALUE_PATH = '$';
+const STATUS_DRAFT = 'draft';
+
+const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+
+/** 32-bit FNV-1a, base 36 — a short stable id fragment. */
+function stableHash(text: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    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 || './';
+}
+
+interface RepeaterScope {
+    /** The alias a row's children bind (`repeaterItemAlias`: the iterate-path's last segment, else the source). */
+    itemAlias: string;
+}
+
+interface Ctx {
+    owner: string;
+    page: PagePlan | null;
+    section: PageSectionPlan | null;
+    plan: SitePlan;
+    /** `next.*` → this alias. */
+    nextAlias: string | null;
+    placeholders: ComposedPlaceholder[];
+    issues: ComposeIssue[];
+    routes: ReadonlySet<string>;
+}
+
+function nonEmpty(v: unknown): v is string {
+    return typeof v === 'string' && v.trim() !== '';
+}
+
+interface TextChoice {
+    value?: string;
+    placeholder?: { kind: PlaceholderKind; fact?: FactKey };
+}
+
+/** Where a node's words come from: the plan's slot → the business → the customer's fact → the pattern's
+ *  own text. A missing fact shows its label and is a placeholder; nothing is ever made up. */
+function chooseText(pn: PatternNode, ctx: Ctx): TextChoice {
+    const fact = pn.ph && (FACT_KEYS as ReadonlyArray<string>).includes(pn.ph) ? pn.ph as FactKey : null;
+    const slotValue = pn.slot ? ctx.section?.slots?.[pn.slot] : undefined;
+    if (nonEmpty(slotValue)) return { value: slotValue };
+    if (pn.fromBusiness) {
+        const v = (ctx.plan.business as unknown as Record<string, unknown>)[pn.fromBusiness];
+        if (nonEmpty(v)) return { value: v };
+    }
+    if (fact) {
+        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 };
+}
+
+/** A `bind` / `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:
+            if (!ctx.page?.routeSource) throw new ComposeError(`${nodeId}: "${path}" on a page with no routeSource`);
+            return { source: ctx.page.routeSource, path: sub || ITEM_VALUE_PATH };
+        case BindScope.Next:
+            if (!ctx.nextAlias) throw new ComposeError(`${nodeId}: "${path}" with no next-sibling source`);
+            return { source: ctx.nextAlias, path: sub || ITEM_VALUE_PATH };
+        default:
+            throw new ComposeError(`${nodeId}: unknown binding scope "${scope}"`);
+    }
+}
+
+function addBinding(node: SerializedNode, binding: SerializedBinding): void {
+    const declared = NODE_BASELINES[node.type]?.traits ?? [];
+    if (!declared.includes(binding.prop) && !binding.prop.startsWith('routeParam:')) {
+        throw new ComposeError(`${node.type} has no trait "${binding.prop}" to bind`);
+    }
+    node.bindings.push(binding);
+}
+
+function assertTraits(type: string, names: ReadonlyArray<string>): void {
+    const declared = NODE_BASELINES[type]?.traits ?? [];
+    for (const name of names) if (!declared.includes(name)) throw new ComposeError(`${type} has no trait "${name}"`);
+}
+
+function setProp(node: SerializedNode, name: string, value: unknown): void {
+    assertTraits(node.type, [name]);
+    node.props[name] = value;
+}
+
+/** One pattern node → one serialized node (and its subtree). `null` when the section leaves it out. */
+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 props: Record<string, unknown> = {};
+    if (pn.level) props['level'] = pn.level;
+    if (pn.tag) props['htmlTag'] = pn.tag;
+    if (pn.scheme) props['colorScheme'] = pn.scheme;
+    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));
+    // Props first: a Heading with no `es` wears its LEVEL's default style.
+    const node = createSerializedNode(id, pn.t, 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]] ?? '');
+        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` });
+    }
+    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];
+        } else {
+            const prop = TEXT_PROP[pn.t];
+            if (!prop) throw new ComposeError(`${id}: ${pn.t} cannot hold text`);
+            setProp(node, prop, words.value);
+        }
+    }
+
+    // Images.
+    if (pn.ph === PatternPlaceholder.Image) {
+        setProp(node, 'src', '');
+        ctx.placeholders.push({ nodeId: id, owner: ctx.owner, kind: PlaceholderKind.Image, text: '' });
+    }
+    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.param) {
+        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) });
+    }
+
+    // Layout.
+    if (pn.lay) setStyleProps(node, pn.lay);
+    if (pn.resp) {
+        for (const layer of Object.values(pn.resp)) assertStyleSlots(node.type, Object.keys(layer));
+        node.responsive = Object.fromEntries(Object.entries(pn.resp).map(([bp, styleProps]) => [bp, { styleProps: { ...styleProps } }]));
+    }
+
+    // A Repeater's rows.
+    let rowScope = repeater;
+    if (pn.src) {
+        let binding: SerializedBinding;
+        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 };
+        }
+        addBinding(node, binding);
+        const lastSegment = binding.path.split('.').filter(Boolean).pop();
+        rowScope = { itemAlias: lastSegment || binding.source };
+    }
+
+    // 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)),
+        ];
+    }
+    return node;
+}
+
+function composePattern(pattern: SitePattern, id: string, ctx: Ctx): SerializedNode {
+    const node = composeNode(pattern.node, id, null, ctx);
+    if (!node) throw new ComposeError(`${id}: a pattern's root cannot be optional`);
+    node.label = pattern.label;
+    return node;
+}
+
+function composeDataSource(ds: DataSourcePlan): ComposedDataSource {
+    const id = `ds-${ds.alias}`;
+    if (ds.type === PlanDataSourceType.Cms) {
+        const cms: Record<string, unknown> = { contentType: ds.contentType };
+        if (ds.limit !== undefined) cms['limit'] = ds.limit;
+        if (ds.filterByRouteParam) cms['filterByRouteParam'] = { ...ds.filterByRouteParam };
+        return { id, alias: ds.alias, type: PlanDataSourceType.Cms, mode: ds.mode, request: { cms } };
+    }
+    const pick = ds.op === RelativeOp.SiblingsNext ? 'next' : 'prev';
+    return {
+        id, alias: ds.alias, type: PlanDataSourceType.Relative, mode: PlanDataSourceMode.Single,
+        request: { relative: { kind: 'siblings', from: ds.within, subjectFrom: ds.of, pick } },
+    };
+}
+
+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;
+    return value
+        .replace(ITEM_NUMBER, String(n))
+        .replace(SAMPLE_IMAGE_TEMPLATE, (_m, plus?: string) => sampleImageRef(n + (plus ? Number(plus) : 0)));
+}
+
+function composeItems(type: ContentTypePlan): ComposedItem[] {
+    const seed = type.seed;
+    if (!seed) return [];
+    const items: ComposedItem[] = [];
+    for (let n = 1; n <= seed.count; n++) {
+        const item: Record<string, unknown> = {};
+        for (const field of type.fields) if (field.name in seed) item[field.name] = expandSeedValue(seed[field.name], n);
+        items.push({ ...item, isPublished: seed.isPublished, isSample: seed.sample });
+    }
+    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.
+ */
+export function composeSite(plan: SitePlan): ComposedSite {
+    assertValidSitePlan(plan);
+    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 pages: ComposedPage[] = plan.pages.map(page => {
+        const nextAlias = page.routeSource ? nextSourceOf(relatives, page.routeSource) : null;
+        const layout = page.sections.map((section, i) => {
+            const pattern = patternById(section.pattern) as SitePattern;
+            return composePattern(pattern, `${page.key}-${i}`, { ...base, owner: page.key, page, section, nextAlias });
+        });
+        return {
+            key: page.key,
+            name: page.name,
+            route: { path: page.route },
+            isHome: page.isHome === true,
+            status: STATUS_DRAFT,
+            pageSettings: { designSystem: true },
+            layout,
+        };
+    });
+
+    const globals = Object.values(GlobalSlot).map(slot => {
+        const pattern = patternById(plan.globals[slot]) as SitePattern;
+        const node = composePattern(pattern, slot, { ...base, owner: slot, page: null, section: null, nextAlias: null });
+        node.isGlobal = true;
+        node.globalPosition = pattern.global;
+        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,
+        pages,
+        globals,
+        routes: plan.pages.map(p => ({ key: p.key, path: p.route, isHome: p.isHome === true })),
+        placeholders,
+        issues,
+    };
+}

package/src/generation-core/node-baseline.model.ts

@@ -0,0 +1,10 @@
+/** What an untouched node of one registered type saves as (`NODE_BASELINES`, generated from the live
+ *  iox-builder configs) — the builder serializer's flat `props` / `styleProps`, the trait names it has a
+ *  slot for, and whether it holds children. */
+export interface NodeBaseline {
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly styleProps: Readonly<Record<string, unknown>>;
+    readonly traits: ReadonlyArray<string>;
+    readonly styleTraits: ReadonlyArray<string>;
+    readonly container: boolean;
+}