@vectoriox/iox-ui 5.28.0 → 5.29.1

package/forms-core/index.d.ts

@@ -379,5 +379,45 @@ declare function withAntiSpamFields(values: Record<string, any>, renderedAt: num
  */
 declare function interpretSubmitResponse(body: any): SubmitResponse;
 
-export { ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, HONEYPOT_FIELD, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RENDERED_AT_FIELD, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, fieldOptionsOf, firstInvalidField, interpretSubmitResponse, onFieldBlur, onFieldChange, onSubmitAttempt, parseFieldOptions, resetFormState, rulesFor, shouldShowError, submitEndpointPath, uniqueFieldName, validateField, validateForm, withAntiSpamFields };
-export type { FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, FormTransport, RuleDescriptor, SubmitAction, SubmitRequest, SubmitResponse, ValidationRule };
+/**
+ * FORM PRESETS — a complete, working form as one insert: its fields, its submit label and the words of
+ * its Success and Error blocks. ONE definition (W1.1): the builder's Forms tray builds a preset from
+ * here (`buildFormPreset`, iox-builder), and the site composer (`generation-core`) stamps the SAME preset
+ * into a composed page, so a generated contact form is the real one — never a second, drifting copy.
+ * Data only: framework-free, like the rest of forms-core.
+ */
+declare enum FormPresetId {
+    Contact = "contact",
+    Newsletter = "newsletter",
+    Application = "application",
+    Booking = "booking"
+}
+interface FormPresetField {
+    label: string;
+    control: string;
+    required?: boolean;
+    help?: string;
+    placeholder?: string;
+    /** Choices for select/radio, `value|Label` per line — the Field's `optionsText` trait. */
+    optionsText?: string;
+    rows?: number;
+}
+interface FormPresetDef {
+    id: `${FormPresetId}`;
+    name: string;
+    icon: string;
+    /** One line in the panel: what it collects and where it goes. */
+    description: string;
+    /** The form's author-facing name, which the submissions inbox groups by. */
+    formName: string;
+    fields: FormPresetField[];
+    submitLabel: string;
+    successText: string;
+    errorText: string;
+}
+declare const FORM_PRESETS: readonly FormPresetDef[];
+/** The preset with this id, or undefined. */
+declare function formPresetById(id: string | null | undefined): FormPresetDef | undefined;
+
+export { ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FORM_PRESETS, FeedbackTiming, FormPresetId, HONEYPOT_FIELD, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RENDERED_AT_FIELD, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, fieldOptionsOf, firstInvalidField, formPresetById, interpretSubmitResponse, onFieldBlur, onFieldChange, onSubmitAttempt, parseFieldOptions, resetFormState, rulesFor, shouldShowError, submitEndpointPath, uniqueFieldName, validateField, validateForm, withAntiSpamFields };
+export type { FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormPresetDef, FormPresetField, FormResult, FormRuntimeState, FormSpec, FormTransport, RuleDescriptor, SubmitAction, SubmitRequest, SubmitResponse, ValidationRule };

package/generation-core/index.d.ts

@@ -1,14 +1,99 @@
 import { DesignChoices } from '@vectoriox/iox-ui/design-core';
 
 declare const SPEC_SITE_PLAN_SHAPE: {
-    readonly version: "1";
-    readonly source: "{ kind: 'template', templateId, templateVersion } | { kind: 'ai', runId }";
-    readonly business: "{ name (required), tagline?, facts: { email?, phone?, city? } }";
-    readonly design: "{ flavorId, seed, pairId, shape, density, motion, pillButtons, mode }  — the DesignChoices of the design system";
-    readonly contentTypes: "ContentTypePlan[] — { name, label, fields[], seed }";
-    readonly dataSources: "DataSourcePlan[] — merged by alias into the org library";
-    readonly pages: "PagePlan[] — { key, name, route, isHome?, template?, routeSource?, sections: { pattern, slots?, binding?, without? }[] }";
-    readonly globals: "{ header: patternId, footer: patternId }";
+    readonly plan: {
+        readonly version: "'1'";
+        readonly source: "sourceTemplate | sourceAi";
+        readonly business: "business";
+        readonly design: "design";
+        readonly contentTypes: "contentType[]";
+        readonly dataSources: "(cmsDataSource | relativeDataSource)[] — merged by alias into the org library";
+        readonly pages: "page[]";
+        readonly globals: "globals";
+    };
+    readonly sourceTemplate: {
+        readonly kind: "'template'";
+        readonly templateId: "string";
+        readonly templateVersion: "integer";
+    };
+    readonly sourceAi: {
+        readonly kind: "'ai'";
+        readonly runId: "string";
+    };
+    readonly business: {
+        readonly name: "string — the brand: the header, the hero, the copyright line";
+        readonly "tagline?": "string — the hero lead and the footer line";
+        readonly "facts?": "{ [fact]: string } — facts (email, phone, city): only the customer's own words; a blank fact is a publish-blocking placeholder, never invented";
+    };
+    readonly design: {
+        readonly flavorId: "string — a v2 flavor pack id";
+        readonly seed: "string — #rrggbb brand colour";
+        readonly pairId: "string — one of the pack's font pairings";
+        readonly shape: "string — axes.shapes";
+        readonly density: "string — axes.densities";
+        readonly motion: "string — axes.motions";
+        readonly pillButtons: "boolean";
+        readonly mode: "'light' | 'dark' | 'auto'";
+        readonly "tint?": "string — axes.tints (DS9 neutral tint)";
+        readonly "fonts?": "object — uploaded font families per role (DS5)";
+    };
+    readonly contentType: {
+        readonly name: "string — unique";
+        readonly label: "string";
+        readonly "previewTextField?": "string — a field of the type: the item's name on cards and the alt text of its bound images";
+        readonly "previewImageField?": "string — a field of the type: the item's picture";
+        readonly fields: "field[]";
+        readonly "seed?": "seed";
+    };
+    readonly field: {
+        readonly name: "string — unique in the type";
+        readonly type: "string";
+        readonly controller: "string — an IOX input controller";
+        readonly "required?": "boolean";
+        readonly "note?": "string";
+    };
+    readonly seed: {
+        readonly count: "integer ≥ 0";
+        readonly sample: "boolean — items are flagged isSample";
+        readonly isPublished: "boolean";
+        readonly "[field]?": "the field's value — strings are templates: {n} = the item's 1-based number, {sampleImage:n} / {sampleImage:n+k} = a bundled sample image";
+    };
+    readonly cmsDataSource: {
+        readonly alias: "string — unique; never $… (platform scopes)";
+        readonly type: "'cms'";
+        readonly mode: "'query' | 'single'";
+        readonly contentType: "string — a content type of the plan";
+        readonly "limit?": "integer ≥ 1";
+        readonly "filterByRouteParam?": "{ field, routeParam } — single only: the route param that picks the item";
+    };
+    readonly relativeDataSource: {
+        readonly alias: "string — unique";
+        readonly type: "'relative'";
+        readonly of: "string — a single cms source (the subject)";
+        readonly op: "'$siblings.next' | '$siblings.prev'";
+        readonly within: "string — a query cms source of the same type";
+    };
+    readonly page: {
+        readonly key: "string — unique";
+        readonly name: "string — the nav label";
+        readonly route: "string — /lowercase-words, :params; unique";
+        readonly "isHome?": "boolean — exactly one page, at /";
+        readonly "required?": "boolean — a template page the wizard's Pages step cannot leave out";
+        readonly "inNav?": "boolean — a Link in the header and footer navigation, in plan order";
+        readonly "template?": "string — the content type a template page renders one item of";
+        readonly "routeSource?": "string — the single source read by the route param (route.* binds it)";
+        readonly sections: "section[]";
+    };
+    readonly section: {
+        readonly pattern: "string — a non-global pattern id";
+        readonly "slots?": "{ [slot]: string } — the pattern's declared slots";
+        readonly "binding?": "string — the list source a pattern's $binding repeater iterates (exactly when it has one)";
+        readonly "without?": "string[] — the pattern's optional parts to leave out";
+    };
+    readonly globals: {
+        readonly header: "string — a header pattern (global: before)";
+        readonly footer: "string — a footer pattern (global: after)";
+    };
 };
 declare const SPEC_SITE_FACTS: {
     readonly email: "Email address";
@@ -26,6 +111,7 @@ declare const SPEC_SITE_PATTERNS: {
             readonly tag: "nav";
             readonly lay: {
                 readonly display: "flex";
+                readonly flexWrap: "wrap";
                 readonly justifyContent: "space-between";
                 readonly alignItems: "center";
                 readonly gap: "var(--iox-space-gap)";
@@ -47,18 +133,16 @@ declare const SPEC_SITE_PATTERNS: {
                 readonly lay: {
                     readonly display: "flex";
                     readonly flexWrap: "wrap";
-                    readonly gap: "28px";
+                    readonly gap: "var(--iox-space-gap)";
                     readonly alignItems: "center";
+                    readonly width: "auto";
                 };
                 readonly c: readonly [{
-                    readonly t: "Repeater";
-                    readonly src: "$navPages";
-                    readonly c: readonly [{
-                        readonly t: "Link";
-                        readonly es: "link";
-                        readonly bind: "page.name";
-                        readonly href: "$page.route";
-                    }];
+                    readonly t: "Link";
+                    readonly es: "link";
+                    readonly each: "$navPages";
+                    readonly bind: "page.name";
+                    readonly href: "$page.route";
                 }, {
                     readonly t: "ButtonBlock";
                     readonly es: "button-primary";
@@ -125,14 +209,11 @@ declare const SPEC_SITE_PATTERNS: {
                         readonly level: "h4";
                         readonly text: "Pages";
                     }, {
-                        readonly t: "Repeater";
-                        readonly src: "$navPages";
-                        readonly c: readonly [{
-                            readonly t: "Link";
-                            readonly es: "link";
-                            readonly bind: "page.name";
-                            readonly href: "$page.route";
-                        }];
+                        readonly t: "Link";
+                        readonly es: "link";
+                        readonly each: "$navPages";
+                        readonly bind: "page.name";
+                        readonly href: "$page.route";
                     }];
                 }, {
                     readonly t: "Container";
@@ -168,7 +249,7 @@ declare const SPEC_SITE_PATTERNS: {
                 readonly t: "Text";
                 readonly es: "small";
                 readonly slot: "copyright";
-                readonly fromBusiness: "copyright";
+                readonly text: "© {year} {business.name}";
             }];
             readonly lay: {
                 readonly display: "flex";
@@ -580,6 +661,7 @@ declare const SPEC_SITE_PATTERNS: {
                     readonly t: "Image";
                     readonly es: "media";
                     readonly bind: "item";
+                    readonly alt: "";
                     readonly aspect: "4 / 3";
                 }];
             }];
@@ -729,26 +811,6 @@ declare const SPEC_SITE_PATTERNS: {
                     readonly c: readonly [{
                         readonly t: "Form";
                         readonly preset: "contact";
-                        readonly c: readonly [{
-                            readonly t: "Field";
-                            readonly control: "text";
-                            readonly label: "Name";
-                            readonly required: true;
-                        }, {
-                            readonly t: "Field";
-                            readonly control: "email";
-                            readonly label: "Email";
-                            readonly required: true;
-                        }, {
-                            readonly t: "Field";
-                            readonly control: "textarea";
-                            readonly label: "Message";
-                            readonly required: true;
-                        }, {
-                            readonly t: "SubmitButton";
-                            readonly es: "button-primary";
-                            readonly text: "Send";
-                        }];
                     }];
                 }];
             }];
@@ -936,9 +998,40 @@ interface NodeBaseline {
 }
 
 declare const NODE_BASELINES: Readonly<Record<string, NodeBaseline>>;
+/** What every style trait saves as when no constructor sets it (buildFullStyleTraits' defaults). */
+declare const NEUTRAL_STYLE_PROPS: Readonly<Record<string, unknown>>;
+
+/**
+ * Why each type's constructor sets the style values it sets (W1.1, Q1). Every value a type's config
+ * gives that differs from what the trait saves when nobody sets it (`NEUTRAL_STYLE_PROPS`) is exactly
+ * one of:
+ *
+ * - **Layout** — a size or spacing that exists only so an EMPTY node dropped from the palette is visible
+ *   and grabbable (a Container's 200px, a Text's 10px padding). A composed node is never empty and its
+ *   pattern owns its box, so the composer RELEASES these to the neutral value unless the pattern
+ *   declares one: the nav bar was 200px tall and every lead line indented 10px (W1's screenshot).
+ * - **Behaviour** — what makes the type work: a button's inline-flex centring, a form's column, the 44px
+ *   touch target, a slide's width, a spacer's height, a list's marker room. Kept.
+ * - **Look** — the type's pre-design-system paint, which its element style replaces. Kept (the style
+ *   writes over it; a type with no style keeps its pre-DS2 look, D5).
+ *
+ * Saved pages are untouched: this is the composer's rule, never the builder's (a palette drop still
+ * gets its 200px). `baseline-roles.spec.ts` fails the moment a config gains a default this table does
+ * not classify — so a new default is a decision, not an accident.
+ */
+declare enum BaselineRole {
+    Layout = "layout",
+    Behaviour = "behaviour",
+    Look = "look"
+}
+declare const BASELINE_ROLES: Readonly<Record<string, Readonly<Record<string, BaselineRole>>>>;
+/** The style values a type's constructor sets for an empty palette drop, each mapped to the value the
+ *  trait saves when nobody sets it — what a composed node of that type starts from. */
+declare function releasedLayoutDefaults(type: string): Record<string, unknown>;
 
 /**
- * The Site Plan (contract `site.planShape`) — the ONE document the website wizard writes
+ * The Site Plan (contract `site.planShape`, `SPEC_SITE_PLAN_SHAPE`: every key typed and explained, and the
+ * validator reads its key lists from it) — the ONE document the website wizard writes
  * (`source.kind: template`) and the AI agent will write (`source.kind: ai`). One validator, one
  * composer: everything the wizard proves is proven for the agent.
  */
@@ -1035,9 +1128,9 @@ interface PagePlan {
     readonly name: string;
     readonly route: string;
     readonly isHome?: boolean;
-    /** Carried by templates (the wizard's Pages step); not part of the documented plan shape. */
+    /** A template page the wizard's Pages step cannot leave out (`planFromTemplate`). */
     readonly required?: boolean;
-    /** In the navigation (`$navPages`). Carried by templates; not part of the documented plan shape. */
+    /** A Link in the header and footer navigation (`each: $navPages`), in plan order. */
     readonly inNav?: boolean;
     /** A template page: the content type it renders one item of. */
     readonly template?: string;
@@ -1067,12 +1160,16 @@ interface SitePlan {
  * `t` component type · `es` element style · `scheme` section colour scheme · `tag` a Container's html
  * tag · `level` a Heading's level · `lay` layout-only styleProps · `resp` per-breakpoint styleProps ·
  * `aspect` an Image's aspect ratio · `slot` author-editable text, filled from the plan's section slots ·
- * `fromBusiness` text from the plan's business · `text` the pattern's own words · `ph` a publish-blocking
- * placeholder (a FACT key, `copy` or `image`) · `bind` a binding path on the repeater item (`item.*`,
- * `page.*`), the route item (`route.*`) or its next sibling (`next.*`) · `src` what a Repeater iterates
- * (`$binding`, `$navPages`, `route.<array>`) · `href` a page route (`$page.route` = the nav item's) ·
+ * `fromBusiness` text from the plan's business · `text` the pattern's own words (`{year}` and
+ * `{business.name}` are filled at compose time) · `ph` a publish-blocking placeholder (a FACT key,
+ * `copy` or `image`) · `bind` a binding path on the repeater item (`item.*`), the route item
+ * (`route.*`) or its next sibling (`next.*`) — or, on an `each` node, the page it is stamped for
+ * (`page.*`, written as plain words) · `alt` an Image's alt binding (default: the bound item's preview
+ * text field; `''` = decorative, written empty) · `src` what a Repeater iterates (`$binding`, `route.<array>`) · `each` stamp the node once
+ * per page in the navigation (`$navPages`) · `href` a page route (`$page.route` = the stamped page's) ·
  * `param` the value of the route's `:param` · `optional` a part a page may leave out (`without`) ·
- * `preset` a Form preset · `control` / `label` / `required` a Field's · `c` children.
+ * `preset` a forms-core form preset (its fields, submit and Success/Error words) · `control` / `label` /
+ * `required` a Field's · `c` children.
  */
 interface PatternNode {
     readonly t: string;
@@ -1088,7 +1185,9 @@ interface PatternNode {
     readonly text?: string;
     readonly ph?: string;
     readonly bind?: string;
+    readonly alt?: string;
     readonly src?: string;
+    readonly each?: string;
     readonly href?: string;
     readonly param?: string;
     readonly optional?: string;
@@ -1119,16 +1218,17 @@ declare enum PatternPlaceholder {
 declare enum PatternDirective {
     /** A Repeater's source: the section's `binding`. */
     Binding = "$binding",
-    /** A Repeater's source: the plan's pages that are in the navigation. */
+    /** `each`: one plain node per page of the plan that is in the navigation (`inNav`), in plan order —
+     *  words and routes written in, editable on the canvas (W1.1). */
     NavPages = "$navPages",
-    /** A Link's route: the nav item's route. */
+    /** A Link's route: the route of the page an `each` node is stamped for. */
     PageRoute = "$page.route"
 }
 /** The scopes a `bind` / `param` / `src` path starts with. */
 declare enum BindScope {
     /** The nearest Repeater's row. */
     Item = "item",
-    /** The nearest Repeater's row, when that Repeater iterates the navigation's pages. */
+    /** The page an `each: $navPages` node is stamped for — resolved to plain words, never a binding. */
     Page = "page",
     /** The page's route item (`routeSource`). */
     Route = "route",
@@ -1144,6 +1244,10 @@ declare function patternSlots(pattern: SitePattern): string[];
 declare function patternOptionalParts(pattern: SitePattern): string[];
 /** True when the pattern has a Repeater iterating the section's `binding`. */
 declare function patternNeedsBinding(pattern: SitePattern): boolean;
+/** The scopes whose ITEM a pattern's bound Images take their alt text from (an Image that names no `alt`
+ *  of its own): `item` (the row of a `$binding` Repeater — the section's list), `route` or `next`. Each
+ *  needs a content type with a `previewTextField` (W1.1, Q7). */
+declare function altSourceScopes(pattern: SitePattern): Set<string>;
 /** The bind scopes a pattern reads (`route`, `next`, …) — what its page must provide. */
 declare function patternScopes(pattern: SitePattern): Set<string>;
 
@@ -1213,13 +1317,19 @@ interface SerializedNode {
  *  wrong — never something to work around. */
 declare class ComposeError extends Error {
 }
+interface CreateNodeOptions {
+    /** The composer's rule (W1.1): the type's empty-drop sizes (`BaselineRole.Layout`) start neutral, so
+     *  the PATTERN owns the box. The builder never does this — a palette drop keeps its 200px. */
+    releaseLayoutDefaults?: boolean;
+}
 /**
  * A NEW node of `type`, as the builder creates one (ComponentRegistryService.createConfig, serialized):
  * the type's constructor defaults, its text colour released to `inherit` (NEW_NODE_STYLE_DEFAULTS), then
  * ONE element style — `elementStyle` when given, else the type's default for its props (a Heading
- * follows its level). `props` are applied before the style is chosen.
+ * follows its level). `props` are applied before the style is chosen. With `releaseLayoutDefaults` the
+ * constructor's layout sizes are released first, so an element style that owns one still writes it.
  */
-declare function createSerializedNode(id: string, type: string, props?: Record<string, unknown>, elementStyle?: string | null): SerializedNode;
+declare function createSerializedNode(id: string, type: string, props?: Record<string, unknown>, elementStyle?: string | null, options?: CreateNodeOptions): SerializedNode;
 /** Refuse a style trait the type has no slot for — the builder would silently drop it. */
 declare function assertStyleSlots(type: string, names: ReadonlyArray<string>): void;
 /** Write style traits onto a node (each one a slot the type has). */
@@ -1257,7 +1367,10 @@ declare enum SitePlanIssueCode {
     UnknownSlot = "unknown-slot",
     UnknownOptionalPart = "unknown-optional-part",
     Binding = "binding",
-    MissingScope = "missing-scope"
+    MissingScope = "missing-scope",
+    /** A pattern binds an item's image, and the item's content type names no `previewTextField` to be
+     *  its alt text. */
+    MissingPreviewField = "missing-preview-field"
 }
 interface SitePlanIssue {
     code: SitePlanIssueCode;
@@ -1273,9 +1386,14 @@ declare class SitePlanError extends Error {
     readonly issues: ReadonlyArray<SitePlanIssue>;
     constructor(issues: ReadonlyArray<SitePlanIssue>);
 }
-/** The alias of the static source the composer writes for the navigation (`$navPages`). A plan source
- *  may not take it. */
-declare const NAV_PAGES_ALIAS = "navPages";
+/** The documented plan shape (contract `site.planShape`): key → type; a key ending in `?` is optional and
+ *  a `[name]` key stands for the object's own field names. The key lists below are READ from it, so a
+ *  key the plan documents is a key the gate validates — and an undocumented one is refused. */
+type ShapeEntry = Readonly<Record<string, string>>;
+/** Every fixed key an object of the shape may carry. */
+declare function shapeKeys(entry: ShapeEntry): string[];
+/** The keys an object of the shape must carry. */
+declare function requiredShapeKeys(entry: ShapeEntry): string[];
 /** The `:param` names of a route, in order. */
 declare function routeParams(route: string): string[];
 /** The plan's `$siblings.next` source of `routeSource` — what a pattern's `next.*` reads. */
@@ -1292,10 +1410,12 @@ declare function assertValidSitePlan(plan: unknown): void;
 /**
  * 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).
@@ -1322,14 +1442,29 @@ declare 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. */
+declare const DANGLING_LINK_CODES: ReadonlySet<ComposeIssueCode>;
 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. */
+interface ComposeContext {
+    /** The calendar year the copyright line reads (`{year}`), from the caller's clock. */
+    year: number;
 }
 interface ComposedPage {
     key: string;
@@ -1384,14 +1519,11 @@ declare const SAMPLE_IMAGE_REF: RegExp;
 declare function sampleImageRef(index: number): string;
 /** The 1-based index a `{sampleImage:k}` value names, or null. */
 declare function parseSampleImageRef(value: unknown): number | null;
-/** 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>`. */
-declare function baseRelativeHref(route: string): string;
 /**
  * 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).
  */
-declare function composeSite(plan: SitePlan): ComposedSite;
+declare function composeSite(plan: SitePlan, context: ComposeContext): ComposedSite;
 
-export { BindScope, ComposeError, ComposeIssueCode, FACT_KEYS, GlobalSlot, NAV_PAGES_ALIAS, NODE_BASELINES, PatternDirective, PatternGlobalPosition, PatternPlaceholder, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, assertStyleSlots, assertValidSitePlan, baseRelativeHref, composeSite, createSerializedNode, nextSourceOf, parseSampleImageRef, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, planFromTemplate, routeParams, sampleImageRef, setStyleProps, validateSitePlan, walkSerialized };
-export type { CmsDataSourcePlan, ComposeIssue, ComposedDataSource, ComposedItem, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, DataSourcePlan, FactKey, NodeBaseline, PagePlan, PageSectionPlan, PatternNode, RelativeDataSourcePlan, SerializedBinding, SerializedNode, SerializedResponsive, SiteBusiness, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };
+export { BASELINE_ROLES, BaselineRole, BindScope, ComposeError, ComposeIssueCode, DANGLING_LINK_CODES, FACT_KEYS, GlobalSlot, NEUTRAL_STYLE_PROPS, NODE_BASELINES, PatternDirective, PatternGlobalPosition, PatternPlaceholder, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, altSourceScopes, assertStyleSlots, assertValidSitePlan, composeSite, createSerializedNode, nextSourceOf, parseSampleImageRef, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, planFromTemplate, releasedLayoutDefaults, requiredShapeKeys, routeParams, sampleImageRef, setStyleProps, shapeKeys, validateSitePlan, walkSerialized };
+export type { CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, DataSourcePlan, FactKey, NodeBaseline, PagePlan, PageSectionPlan, PatternNode, RelativeDataSourcePlan, SerializedBinding, SerializedNode, SerializedResponsive, SiteBusiness, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };

package/index.d.ts

@@ -446,6 +446,17 @@ declare class ClientRepeaterComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<ClientRepeaterComponent, "iox-repeater", never, { "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
 }
 
+/**
+ * Where a node links (W1.1). Link and LinkedContainer always had two link types — an external URL or a
+ * website PAGE by its route — and ButtonBlock now has the same pair, so a composed "Get in touch" button
+ * is a page link the builder shows as `/contact`, not a hand-built URL. Framework-free: the composer
+ * (generation-core) writes it, the builder canvas and both engine render paths read it.
+ */
+declare enum LinkType {
+    External = "external",
+    Page = "page"
+}
+
 /**
  * Directive-host ButtonBlock: the real `<a>`/`<button>` IS the host — no `app-button-block`
  * wrapper, no inner/outer split. The tag is chosen by whoever CREATES the component (engine
@@ -453,16 +464,21 @@ declare class ClientRepeaterComponent {
  * The `iox-btn-block` class (UA resets: inline-flex, color/font inherit, no border) matches the
  * string renderer and lives in the engine's global styles.scss — kept OFF `:host` so styleProps
  * (`.iox-node-{id}`) can override it. Children render into the host via `childrenHost`.
+ * A page link (`linkType: page`) arrives with its `pageRoute` already resolved by the engine (params
+ * substituted, base-relative — the Link's resolver); `buttonBlockHref` decides the href for every renderer.
  */
 declare class ButtonBlockComponent {
     tag: 'button' | 'a';
+    linkType: LinkType;
     href: string;
+    pageRoute: string;
     target: '_self' | '_blank';
     type: 'button' | 'submit' | 'reset';
     nodeId: string;
     childrenHost: ViewContainerRef;
+    get resolvedHref(): string | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<ButtonBlockComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ButtonBlockComponent, "a[iox-button-block],button[iox-button-block]", never, { "tag": { "alias": "tag"; "required": false; }; "href": { "alias": "href"; "required": false; }; "target": { "alias": "target"; "required": false; }; "type": { "alias": "type"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ButtonBlockComponent, "a[iox-button-block],button[iox-button-block]", never, { "tag": { "alias": "tag"; "required": false; }; "linkType": { "alias": "linkType"; "required": false; }; "href": { "alias": "href"; "required": false; }; "pageRoute": { "alias": "pageRoute"; "required": false; }; "target": { "alias": "target"; "required": false; }; "type": { "alias": "type"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
 }
 
 /** The five fixed breakpoints (plan decision D2). Desktop-first: each narrower one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.28.0",
+  "version": "5.29.1",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/contrast-audit.ts

@@ -16,7 +16,8 @@ import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token
  * - `inherit` → the container's ink, a transparent fill → what is under it, translucent fills composited,
  *   a gradient ground (Glass's mesh, Midnight's glow) checked at its worst stop;
  * - base and hover; a button's icon read through the contract's `inkScopes` (it takes the button's ink),
- *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`).
+ *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`); the form's
+ *   Success / Error notices, in every scheme and container.
  *
  * WCAG 2: 4.5:1 for text, 3:1 for glyphs, UI boundaries and focus indicators (1.4.11), judged on 8-bit
  * colours. The same audit gates the contract (`colour.mjs auditContrast`, every flavor × tint × a seed
@@ -162,11 +163,11 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
                     check(FIELD, `${part.part} thumb`, parseCssColour(resolveIn(values, part.thumb), boxInk), bgs.map(b => compositeOver(paint, b)), part.min);
                 }
             }
-            if (box === null && schemeId === DEFAULT_SCHEME) {
-                for (const n of notices) {
-                    const fill = paintColours(resolveIn(values, ownStyle(n)['backgroundColor']), boxInk);
-                    check(n.id, 'text', parseCssColour(resolveIn(values, ownStyle(n)['color']), boxInk), overAll(fill, bgs), WCAG_AA_TEXT);
-                }
+            // A form's Success / Error notice sits wherever its form does — on the section in every scheme
+            // AND inside every container (the Studio's contact form lives in a Card): W1.1.
+            for (const n of notices) {
+                const fill = paintColours(resolveIn(values, ownStyle(n)['backgroundColor']), boxInk);
+                check(n.id, 'text', parseCssColour(resolveIn(values, ownStyle(n)['color']), boxInk), overAll(fill, bgs), WCAG_AA_TEXT);
             }
         }
     }

package/src/design-core/flavor-spec.generated.ts

@@ -1522,6 +1522,23 @@ export const SPEC_ELEMENT_STYLES = [
       "color": "var(--iox-link-hover-color)"
     }
   },
+  {
+    "id": "button-label",
+    "label": "Button label",
+    "group": "Text",
+    "appliesTo": [
+      "Text"
+    ],
+    "base": {
+      "fontFamily": "inherit",
+      "fontSize": "inherit",
+      "fontWeight": "inherit",
+      "lineHeight": "inherit",
+      "letterSpacing": "inherit",
+      "textTransform": "inherit",
+      "color": "inherit"
+    }
+  },
   {
     "id": "section",
     "label": "Section",

package/src/design-core/node-links.ts

@@ -0,0 +1,32 @@
+/**
+ * Where a node links (W1.1). Link and LinkedContainer always had two link types — an external URL or a
+ * website PAGE by its route — and ButtonBlock now has the same pair, so a composed "Get in touch" button
+ * is a page link the builder shows as `/contact`, not a hand-built URL. Framework-free: the composer
+ * (generation-core) writes it, the builder canvas and both engine render paths read it.
+ */
+
+export enum LinkType {
+    External = 'external',
+    Page = 'page',
+}
+
+export interface ButtonBlockLinkProps {
+    tag?: unknown;
+    linkType?: unknown;
+    href?: unknown;
+    pageRoute?: unknown;
+}
+
+const ANCHOR_TAG = 'a';
+
+/**
+ * The href a ButtonBlock renders, or `null` for none (it is a `<button>`, or a link with no target).
+ * Only an `<a>` links. A page link's route goes through `pageHref` — the engine's `resolvePageHref`
+ * (`:params` substituted, base-relative); the builder canvas passes none and shows the route as authored,
+ * as its Link does.
+ */
+export function buttonBlockHref(props: ButtonBlockLinkProps, pageHref: (route: string) => string = route => route): string | null {
+    if (props.tag !== ANCHOR_TAG) return null;
+    const href = props.linkType === LinkType.Page ? pageHref(String(props.pageRoute ?? '')) : String(props.href ?? '');
+    return href || null;
+}

package/src/design-core/public-api.ts

@@ -17,6 +17,7 @@ export * from './element-styles';
 export * from './adopt';
 export * from './node-classes';
 export * from './empty-image';
+export * from './node-links';
 export * from './brand';
 export * from './colour-eval';
 export * from './brand-neutrals';