@vectoriox/iox-ui 5.28.0 → 5.29.0

package/src/generation-core/patterns.ts

@@ -7,12 +7,16 @@ import { SPEC_SITE_PATTERNS } from './site-spec.generated';
  * `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.
  */
 export interface PatternNode {
     readonly t: string;
@@ -28,7 +32,9 @@ export 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;
@@ -64,9 +70,10 @@ export enum PatternPlaceholder {
 export 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',
 }
 
@@ -74,7 +81,7 @@ export enum PatternDirective {
 export 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',
@@ -113,11 +120,26 @@ export function patternNeedsBinding(pattern: SitePattern): boolean {
     return patternNodes(pattern).some(n => n.src === PatternDirective.Binding);
 }
 
+const IMAGE_TYPE = 'Image';
+
+/** 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). */
+export function altSourceScopes(pattern: SitePattern): Set<string> {
+    const scopes = new Set<string>();
+    const visit = (n: PatternNode) => {
+        if (n.t === IMAGE_TYPE && n.bind && n.alt === undefined) scopes.add(n.bind.split('.')[0]);
+        for (const child of n.c ?? []) visit(child);
+    };
+    visit(pattern.node);
+    return scopes;
+}
+
 /** The bind scopes a pattern reads (`route`, `next`, …) — what its page must provide. */
 export function patternScopes(pattern: SitePattern): Set<string> {
     const scopes = new Set<string>();
     for (const n of patternNodes(pattern)) {
-        for (const path of [n.bind, n.param, n.src]) {
+        for (const path of [n.bind, n.alt, n.param, n.src]) {
             if (path && !path.startsWith('$')) scopes.add(path.split('.')[0]);
         }
     }

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

@@ -12,6 +12,7 @@
 export * from './site-spec.generated';
 export * from './node-baseline.model';
 export * from './node-baselines.generated';
+export * from './baseline-roles';
 export * from './site-plan.model';
 export * from './patterns';
 export * from './templates';

package/src/generation-core/serialized-node.ts

@@ -1,5 +1,6 @@
 import { applyElementStyle, defaultElementStyleFor, elementStyleById, NEW_NODE_STYLE_DEFAULTS, ownedTraitsOf } from '@vectoriox/iox-ui/design-core';
 
+import { releasedLayoutDefaults } from './baseline-roles';
 import { NODE_BASELINES } from './node-baselines.generated';
 import { PatternGlobalPosition } from './patterns';
 
@@ -40,13 +41,22 @@ export class ComposeError extends Error {}
 
 const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
 
+export 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.
  */
-export function createSerializedNode(id: string, type: string, props: Record<string, unknown> = {}, elementStyle?: string | null): SerializedNode {
+export function createSerializedNode(
+    id: string, type: string, props: Record<string, unknown> = {}, elementStyle?: string | null, options: CreateNodeOptions = {},
+): SerializedNode {
     const baseline = NODE_BASELINES[type];
     if (!baseline) throw new ComposeError(`"${type}" is not a registered component type`);
     const node: SerializedNode = {
@@ -57,6 +67,7 @@ export function createSerializedNode(id: string, type: string, props: Record<str
         bindings: [],
         interactions: [],
     };
+    if (options.releaseLayoutDefaults) Object.assign(node.styleProps, releasedLayoutDefaults(type));
     for (const [name, value] of Object.entries(NEW_NODE_STYLE_DEFAULTS)) if (name in node.styleProps) node.styleProps[name] = value;
     const styleId = elementStyle ?? defaultElementStyleFor(type, node.props);
     if (styleId) {

package/src/generation-core/site-plan.model.ts

@@ -3,7 +3,8 @@ import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
 import { SPEC_SITE_FACTS } from './site-spec.generated';
 
 /**
- * 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.
  */
@@ -108,9 +109,9 @@ export 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;

package/src/generation-core/site-spec.generated.ts

@@ -3,14 +3,99 @@
 // architecture/builder/design-system/build-spec.mjs: change a value THERE, then regenerate both.
 /* eslint-disable */
 export const SPEC_SITE_PLAN_SHAPE = {
-  "version": "1",
-  "source": "{ kind: 'template', templateId, templateVersion } | { kind: 'ai', runId }",
-  "business": "{ name (required), tagline?, facts: { email?, phone?, city? } }",
-  "design": "{ flavorId, seed, pairId, shape, density, motion, pillButtons, mode }  — the DesignChoices of the design system",
-  "contentTypes": "ContentTypePlan[] — { name, label, fields[], seed }",
-  "dataSources": "DataSourcePlan[] — merged by alias into the org library",
-  "pages": "PagePlan[] — { key, name, route, isHome?, template?, routeSource?, sections: { pattern, slots?, binding?, without? }[] }",
-  "globals": "{ header: patternId, footer: patternId }"
+  "plan": {
+    "version": "'1'",
+    "source": "sourceTemplate | sourceAi",
+    "business": "business",
+    "design": "design",
+    "contentTypes": "contentType[]",
+    "dataSources": "(cmsDataSource | relativeDataSource)[] — merged by alias into the org library",
+    "pages": "page[]",
+    "globals": "globals"
+  },
+  "sourceTemplate": {
+    "kind": "'template'",
+    "templateId": "string",
+    "templateVersion": "integer"
+  },
+  "sourceAi": {
+    "kind": "'ai'",
+    "runId": "string"
+  },
+  "business": {
+    "name": "string — the brand: the header, the hero, the copyright line",
+    "tagline?": "string — the hero lead and the footer line",
+    "facts?": "{ [fact]: string } — facts (email, phone, city): only the customer's own words; a blank fact is a publish-blocking placeholder, never invented"
+  },
+  "design": {
+    "flavorId": "string — a v2 flavor pack id",
+    "seed": "string — #rrggbb brand colour",
+    "pairId": "string — one of the pack's font pairings",
+    "shape": "string — axes.shapes",
+    "density": "string — axes.densities",
+    "motion": "string — axes.motions",
+    "pillButtons": "boolean",
+    "mode": "'light' | 'dark' | 'auto'",
+    "tint?": "string — axes.tints (DS9 neutral tint)",
+    "fonts?": "object — uploaded font families per role (DS5)"
+  },
+  "contentType": {
+    "name": "string — unique",
+    "label": "string",
+    "previewTextField?": "string — a field of the type: the item's name on cards and the alt text of its bound images",
+    "previewImageField?": "string — a field of the type: the item's picture",
+    "fields": "field[]",
+    "seed?": "seed"
+  },
+  "field": {
+    "name": "string — unique in the type",
+    "type": "string",
+    "controller": "string — an IOX input controller",
+    "required?": "boolean",
+    "note?": "string"
+  },
+  "seed": {
+    "count": "integer ≥ 0",
+    "sample": "boolean — items are flagged isSample",
+    "isPublished": "boolean",
+    "[field]?": "the field's value — strings are templates: {n} = the item's 1-based number, {sampleImage:n} / {sampleImage:n+k} = a bundled sample image"
+  },
+  "cmsDataSource": {
+    "alias": "string — unique; never $… (platform scopes)",
+    "type": "'cms'",
+    "mode": "'query' | 'single'",
+    "contentType": "string — a content type of the plan",
+    "limit?": "integer ≥ 1",
+    "filterByRouteParam?": "{ field, routeParam } — single only: the route param that picks the item"
+  },
+  "relativeDataSource": {
+    "alias": "string — unique",
+    "type": "'relative'",
+    "of": "string — a single cms source (the subject)",
+    "op": "'$siblings.next' | '$siblings.prev'",
+    "within": "string — a query cms source of the same type"
+  },
+  "page": {
+    "key": "string — unique",
+    "name": "string — the nav label",
+    "route": "string — /lowercase-words, :params; unique",
+    "isHome?": "boolean — exactly one page, at /",
+    "required?": "boolean — a template page the wizard's Pages step cannot leave out",
+    "inNav?": "boolean — a Link in the header and footer navigation, in plan order",
+    "template?": "string — the content type a template page renders one item of",
+    "routeSource?": "string — the single source read by the route param (route.* binds it)",
+    "sections": "section[]"
+  },
+  "section": {
+    "pattern": "string — a non-global pattern id",
+    "slots?": "{ [slot]: string } — the pattern's declared slots",
+    "binding?": "string — the list source a pattern's $binding repeater iterates (exactly when it has one)",
+    "without?": "string[] — the pattern's optional parts to leave out"
+  },
+  "globals": {
+    "header": "string — a header pattern (global: before)",
+    "footer": "string — a footer pattern (global: after)"
+  }
 } as const;
 
 export const SPEC_SITE_FACTS = {
@@ -30,6 +115,7 @@ export const SPEC_SITE_PATTERNS = {
       "tag": "nav",
       "lay": {
         "display": "flex",
+        "flexWrap": "wrap",
         "justifyContent": "space-between",
         "alignItems": "center",
         "gap": "var(--iox-space-gap)"
@@ -55,21 +141,17 @@ export const SPEC_SITE_PATTERNS = {
           "lay": {
             "display": "flex",
             "flexWrap": "wrap",
-            "gap": "28px",
-            "alignItems": "center"
+            "gap": "var(--iox-space-gap)",
+            "alignItems": "center",
+            "width": "auto"
           },
           "c": [
             {
-              "t": "Repeater",
-              "src": "$navPages",
-              "c": [
-                {
-                  "t": "Link",
-                  "es": "link",
-                  "bind": "page.name",
-                  "href": "$page.route"
-                }
-              ]
+              "t": "Link",
+              "es": "link",
+              "each": "$navPages",
+              "bind": "page.name",
+              "href": "$page.route"
             },
             {
               "t": "ButtonBlock",
@@ -147,16 +229,11 @@ export const SPEC_SITE_PATTERNS = {
                   "text": "Pages"
                 },
                 {
-                  "t": "Repeater",
-                  "src": "$navPages",
-                  "c": [
-                    {
-                      "t": "Link",
-                      "es": "link",
-                      "bind": "page.name",
-                      "href": "$page.route"
-                    }
-                  ]
+                  "t": "Link",
+                  "es": "link",
+                  "each": "$navPages",
+                  "bind": "page.name",
+                  "href": "$page.route"
                 }
               ]
             },
@@ -202,7 +279,7 @@ export const SPEC_SITE_PATTERNS = {
           "t": "Text",
           "es": "small",
           "slot": "copyright",
-          "fromBusiness": "copyright"
+          "text": "© {year} {business.name}"
         }
       ],
       "lay": {
@@ -680,6 +757,7 @@ export const SPEC_SITE_PATTERNS = {
               "t": "Image",
               "es": "media",
               "bind": "item",
+              "alt": "",
               "aspect": "4 / 3"
             }
           ]
@@ -854,32 +932,7 @@ export const SPEC_SITE_PATTERNS = {
               "c": [
                 {
                   "t": "Form",
-                  "preset": "contact",
-                  "c": [
-                    {
-                      "t": "Field",
-                      "control": "text",
-                      "label": "Name",
-                      "required": true
-                    },
-                    {
-                      "t": "Field",
-                      "control": "email",
-                      "label": "Email",
-                      "required": true
-                    },
-                    {
-                      "t": "Field",
-                      "control": "textarea",
-                      "label": "Message",
-                      "required": true
-                    },
-                    {
-                      "t": "SubmitButton",
-                      "es": "button-primary",
-                      "text": "Send"
-                    }
-                  ]
+                  "preset": "contact"
                 }
               ]
             }

package/src/generation-core/validate-site-plan.ts

@@ -1,11 +1,12 @@
 import { flavorPackById, parseHexColor, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
 
 import {
-    BindScope, patternById, patternNeedsBinding, patternOptionalParts, patternScopes, patternSlots, PatternGlobalPosition,
+    altSourceScopes, BindScope, patternById, patternNeedsBinding, patternOptionalParts, patternScopes, patternSlots, PatternGlobalPosition,
 } from './patterns';
 import {
     FACT_KEYS, GlobalSlot, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlanSourceKind, SITE_PLAN_VERSION,
 } from './site-plan.model';
+import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
 
 /**
  * The Site Plan validator — the gate in front of the composer. The wizard's plan and (later) the AI's
@@ -39,6 +40,9 @@ export enum SitePlanIssueCode {
     UnknownOptionalPart = 'unknown-optional-part',
     Binding = 'binding',
     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',
 }
 
 export interface SitePlanIssue {
@@ -59,24 +63,40 @@ export class SitePlanError extends Error {
     }
 }
 
-/** The alias of the static source the composer writes for the navigation (`$navPages`). A plan source
- *  may not take it. */
-export const NAV_PAGES_ALIAS = 'navPages';
 /** Route-scope aliases (`$route`, `$current`, …) are platform-owned. */
 const RESERVED_PREFIX = '$';
 const ID_FIELD = '_id';
 
-const PLAN_KEYS = ['version', 'source', 'business', 'design', 'contentTypes', 'dataSources', 'pages', 'globals'];
-const BUSINESS_KEYS = ['name', 'tagline', 'facts'];
-const DESIGN_REQUIRED = ['flavorId', 'seed', 'pairId', 'shape', 'density', 'motion', 'pillButtons', 'mode'];
-const DESIGN_KEYS = [...DESIGN_REQUIRED, 'tint', 'fonts'];
-const CONTENT_TYPE_KEYS = ['name', 'label', 'previewTextField', 'previewImageField', 'fields', 'seed'];
-const FIELD_KEYS = ['name', 'type', 'controller', 'required', 'note'];
-const SEED_FIXED_KEYS = ['count', 'sample', 'isPublished'];
-const CMS_SOURCE_KEYS = ['alias', 'type', 'mode', 'contentType', 'limit', 'filterByRouteParam'];
-const RELATIVE_SOURCE_KEYS = ['alias', 'type', 'of', 'op', 'within'];
-const PAGE_KEYS = ['key', 'name', 'route', 'isHome', 'required', 'inNav', 'template', 'routeSource', 'sections'];
-const SECTION_KEYS = ['pattern', 'slots', 'binding', 'without'];
+/** 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>>;
+const OPTIONAL_MARK = '?';
+const DYNAMIC_KEY = /^\[[^\]]+\]\??$/;
+const isDynamic = (key: string) => DYNAMIC_KEY.test(key);
+/** Every fixed key an object of the shape may carry. */
+export function shapeKeys(entry: ShapeEntry): string[] {
+    return Object.keys(entry).filter(k => !isDynamic(k)).map(k => (k.endsWith(OPTIONAL_MARK) ? k.slice(0, -1) : k));
+}
+/** The keys an object of the shape must carry. */
+export function requiredShapeKeys(entry: ShapeEntry): string[] {
+    return Object.keys(entry).filter(k => !isDynamic(k) && !k.endsWith(OPTIONAL_MARK));
+}
+
+const SHAPE: Readonly<Record<string, ShapeEntry>> = SPEC_SITE_PLAN_SHAPE;
+const PLAN_KEYS = shapeKeys(SHAPE['plan']);
+const TEMPLATE_SOURCE_KEYS = shapeKeys(SHAPE['sourceTemplate']);
+const AI_SOURCE_KEYS = shapeKeys(SHAPE['sourceAi']);
+const BUSINESS_KEYS = shapeKeys(SHAPE['business']);
+const DESIGN_REQUIRED = requiredShapeKeys(SHAPE['design']);
+const DESIGN_KEYS = shapeKeys(SHAPE['design']);
+const CONTENT_TYPE_KEYS = shapeKeys(SHAPE['contentType']);
+const FIELD_KEYS = shapeKeys(SHAPE['field']);
+const SEED_FIXED_KEYS = shapeKeys(SHAPE['seed']);
+const CMS_SOURCE_KEYS = shapeKeys(SHAPE['cmsDataSource']);
+const RELATIVE_SOURCE_KEYS = shapeKeys(SHAPE['relativeDataSource']);
+const PAGE_KEYS = shapeKeys(SHAPE['page']);
+const SECTION_KEYS = shapeKeys(SHAPE['section']);
 const GLOBAL_POSITION: Readonly<Record<`${GlobalSlot}`, `${PatternGlobalPosition}`>> = {
     [GlobalSlot.Header]: PatternGlobalPosition.Before,
     [GlobalSlot.Footer]: PatternGlobalPosition.After,
@@ -137,11 +157,11 @@ class Collector {
 function validateSource(c: Collector, source: unknown): void {
     if (!isObject(source)) return c.add(SitePlanIssueCode.Shape, 'source', 'must be an object');
     if (source['kind'] === SitePlanSourceKind.Template) {
-        c.keys(source, ['kind', 'templateId', 'templateVersion'], 'source');
+        c.keys(source, TEMPLATE_SOURCE_KEYS, 'source');
         c.string(source, 'templateId', 'source');
         if (!Number.isInteger(source['templateVersion'])) c.add(SitePlanIssueCode.Shape, 'source.templateVersion', 'must be an integer');
     } else if (source['kind'] === SitePlanSourceKind.Ai) {
-        c.keys(source, ['kind', 'runId'], 'source');
+        c.keys(source, AI_SOURCE_KEYS, 'source');
         c.string(source, 'runId', 'source');
     } else {
         c.add(SitePlanIssueCode.Shape, 'source.kind', `must be "${SitePlanSourceKind.Template}" or "${SitePlanSourceKind.Ai}"`);
@@ -185,7 +205,7 @@ function validateDesign(c: Collector, design: unknown): void {
     if (design['fonts'] !== undefined && !isObject(design['fonts'])) bad('fonts', 'must be an object');
 }
 
-interface ContentTypeInfo { fields: Set<string>; }
+interface ContentTypeInfo { fields: Set<string>; previewTextField?: string; }
 
 function validateContentTypes(c: Collector, list: unknown[]): Map<string, ContentTypeInfo> {
     const types = new Map<string, ContentTypeInfo>();
@@ -207,9 +227,11 @@ function validateContentTypes(c: Collector, list: unknown[]): Map<string, Conten
         });
         c.unique(names, j => `${path}.fields[${j}].name`, 'field');
         const fieldSet = new Set(names.filter((n): n is string => !!n));
+        const preview: Record<string, string | null> = {};
         for (const key of ['previewTextField', 'previewImageField']) {
             const v = c.string(raw, key, path, false);
             if (v && !fieldSet.has(v)) c.add(SitePlanIssueCode.UnknownField, `${path}.${key}`, `"${v}" is not a field of ${name}`);
+            preview[key] = v && fieldSet.has(v) ? v : null;
         }
         const seed = raw['seed'];
         if (seed !== undefined) {
@@ -223,7 +245,7 @@ function validateContentTypes(c: Collector, list: unknown[]): Map<string, Conten
             }
         }
         if (name && types.has(name)) c.add(SitePlanIssueCode.Duplicate, `${path}.name`, `content type "${name}" is used twice`);
-        else if (name) types.set(name, { fields: fieldSet });
+        else if (name) types.set(name, { fields: fieldSet, previewTextField: preview['previewTextField'] ?? undefined });
     });
     return types;
 }
@@ -236,7 +258,7 @@ function validateDataSources(c: Collector, list: unknown[], types: Map<string, C
         const path = `dataSources[${i}]`;
         if (!isObject(raw)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
         const alias = c.string(raw, 'alias', path);
-        if (alias && (alias.startsWith(RESERVED_PREFIX) || alias === NAV_PAGES_ALIAS)) {
+        if (alias && alias.startsWith(RESERVED_PREFIX)) {
             c.add(SitePlanIssueCode.ReservedAlias, `${path}.alias`, `"${alias}" is reserved for the platform`);
         }
         if (raw['type'] === PlanDataSourceType.Cms) {
@@ -363,6 +385,16 @@ function validatePages(c: Collector, list: unknown[], types: Map<string, Content
             if (scopes.has(BindScope.Next) && routeSourceOk && !nextSourceOf(sources, routeSourceAlias as string)) {
                 c.add(SitePlanIssueCode.MissingScope, `${sp}.pattern`, `"${patternId}" reads the next item — the plan needs a ${RelativeOp.SiblingsNext} source of ${routeSourceAlias}`);
             }
+
+            // A bound image's alt text is its item's previewTextField (W1.1): the item's type must name one.
+            for (const scope of altSourceScopes(pattern)) {
+                const alias = scope === BindScope.Item ? binding : routeSourceOk ? routeSourceAlias : null;
+                const typeName = alias ? sources.get(alias)?.contentType : undefined;
+                const type = typeName ? types.get(typeName) : undefined;
+                if (type && !type.previewTextField) {
+                    c.add(SitePlanIssueCode.MissingPreviewField, `${sp}.pattern`, `"${patternId}" shows ${typeName} images — ${typeName} needs a previewTextField for their alt text`);
+                }
+            }
         });
     });
     c.unique(list.map(p => (isObject(p) && isNonEmptyString(p['key']) ? p['key'] : null)), i => `pages[${i}].key`, 'page key');