@vectoriox/iox-ui 5.56.1 → 5.58.0

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

@@ -1,10 +1,14 @@
 import { flavorPackById, parseHexColor, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
+import { formPresetById } from '@vectoriox/iox-ui/forms-core';
+import { SEO_DESCRIPTION_MAX, SEO_TITLE_MAX } from '@vectoriox/iox-ui/seo-core';
 
 import {
-    altSourceScopes, BindScope, patternById, patternNeedsBinding, patternOptionalParts, patternTakesBinding, patternScopes, patternSlots, PatternGlobalPosition,
+    BindScope, patternById, patternHasForm, patternLinkSlots, patternNeedsBinding, patternOptionalParts, patternRoleNeeds, patternTakesBinding, patternScopes,
+    patternSlots, PatternGlobalPosition, slotBudget,
 } from './patterns';
 import {
-    FACT_KEYS, GlobalSlot, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlanSourceKind, SITE_PLAN_VERSION,
+    FACT_KEYS, GlobalSlot, PAGE_ARCHETYPES, PlanDataSourceMode, PlanDataSourceType, RelativeOp, REQUIRED_CONTENT_ROLES, SitePlan, SitePlanSourceKind,
+    SITE_LOCALES, SITE_PLAN_VERSION,
 } from './site-plan.model';
 import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
 import {
@@ -43,9 +47,26 @@ 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',
+    /** A pattern reads a role (`@title`) the bound item's content type does not name (L0-3), or a type names no title. */
+    MissingRole = 'missing-role',
+    /** A role the contract does not know, or one played by a field the type does not have. */
+    UnknownRole = 'unknown-role',
+    /** A page type that does not exist; or (`archetypeIssues`, the plan stage's own check) sections that do not fit it. */
+    Archetype = 'archetype',
+    /** A slot's words are longer than its budget under the look's density (L0-2, M1-6c): rewrite, never cut. */
+    SlotTooLong = 'slot-too-long',
+    /** A section re-points a slot that does not link, or to a route the plan has no page for. */
+    InvalidLink = 'invalid-link',
+    /** A section's form preset is not a forms-core preset, or the pattern holds no form. */
+    InvalidForm = 'invalid-form',
+    /** A section's entrance is not a How animated level. */
+    InvalidEnter = 'invalid-enter',
+    /** The plan's language is not a site locale. */
+    InvalidLocale = 'invalid-locale',
+    /** A page's SEO words are longer than a search result shows (seo-core limits). */
+    InvalidSeo = 'invalid-seo',
+    /** A page key that is a global slot's name (`header`, `footer`): its sections' ids would be the global's. */
+    ReservedPageKey = 'reserved-page-key',
 }
 
 export type SitePlanIssue = PathIssue<SitePlanIssueCode>;
@@ -75,6 +96,9 @@ 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 ROLE_KEYS = shapeKeys(SHAPE['roles']);
+const PAGE_SEO_KEYS = shapeKeys(SHAPE['pageSeo']);
+const ARRAY_TYPE = 'array';
 const FIELD_KEYS = shapeKeys(SHAPE['field']);
 const SEED_FIXED_KEYS = shapeKeys(SHAPE['seed']);
 const CMS_SOURCE_KEYS = shapeKeys(SHAPE['cmsDataSource']);
@@ -129,6 +153,12 @@ function validateBusiness(c: Collector, business: unknown): void {
     }
 }
 
+function validateLocale(c: Collector, locale: unknown): void {
+    if (locale !== undefined && (typeof locale !== 'string' || !has(SITE_LOCALES, locale))) {
+        c.add(SitePlanIssueCode.InvalidLocale, 'locale', `must be one of ${Object.keys(SITE_LOCALES).join(', ')}`);
+    }
+}
+
 function validateDesign(c: Collector, design: unknown): void {
     if (!isObject(design)) return c.add(SitePlanIssueCode.Shape, 'design', 'must be an object');
     c.keys(design, DESIGN_KEYS, 'design');
@@ -155,7 +185,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>; previewTextField?: string; }
+interface ContentTypeInfo { fields: Set<string>; roles: Record<string, string>; }
 
 function validateContentTypes(c: Collector, list: unknown[]): Map<string, ContentTypeInfo> {
     const types = new Map<string, ContentTypeInfo>();
@@ -177,12 +207,8 @@ 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 fieldTypes = new Map(fields.filter(isObject).map(f => [f['name'], f['type']]));
+        const roles = validateRoles(c, raw['roles'], `${path}.roles`, name, fieldSet, fieldTypes);
         const seed = raw['seed'];
         if (seed !== undefined) {
             if (!isObject(seed)) c.add(SitePlanIssueCode.Shape, `${path}.seed`, 'must be an object');
@@ -195,11 +221,25 @@ 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, previewTextField: preview['previewTextField'] ?? undefined });
+        else if (name) types.set(name, { fields: fieldSet, roles });
     });
     return types;
 }
 
+/** A content type's roles (L0-3): known roles only, each played by a field of the type; `title` always; `gallery` a list. */
+function validateRoles(c: Collector, roles: unknown, path: string, typeName: string | null, fields: Set<string>, fieldTypes: Map<unknown, unknown>): Record<string, string> {
+    if (!isObject(roles)) { c.add(SitePlanIssueCode.Shape, path, 'must be an object (which field plays each role)'); return {}; }
+    const out: Record<string, string> = {};
+    for (const [role, field] of Object.entries(roles)) {
+        if (!ROLE_KEYS.includes(role)) { c.add(SitePlanIssueCode.UnknownRole, `${path}.${role}`, `"${role}" is not a role (${ROLE_KEYS.join(', ')})`); continue; }
+        if (typeof field !== 'string' || !fields.has(field)) { c.add(SitePlanIssueCode.UnknownRole, `${path}.${role}`, `"${String(field)}" is not a field of ${typeName}`); continue; }
+        if (role === 'gallery' && fieldTypes.get(field) !== ARRAY_TYPE) { c.add(SitePlanIssueCode.UnknownRole, `${path}.${role}`, `"${field}" is not a list field — a gallery is a list of pictures`); continue; }
+        out[role] = field;
+    }
+    for (const role of REQUIRED_CONTENT_ROLES) if (!out[role] && !has(roles, role)) c.add(SitePlanIssueCode.MissingRole, `${path}.${role}`, `every content type names its ${role} field`);
+    return out;
+}
+
 interface SourceInfo { type: string; mode?: string; contentType?: string; routeParam?: string; of?: string; op?: string; }
 
 function validateDataSources(c: Collector, list: unknown[], types: Map<string, ContentTypeInfo>): Map<string, SourceInfo> {
@@ -255,13 +295,17 @@ function validateDataSources(c: Collector, list: unknown[], types: Map<string, C
     return sources;
 }
 
-function validatePages(c: Collector, list: unknown[], types: Map<string, ContentTypeInfo>, sources: Map<string, SourceInfo>): void {
+function validatePages(c: Collector, list: unknown[], types: Map<string, ContentTypeInfo>, sources: Map<string, SourceInfo>, density: string | null): void {
     const homes: number[] = [];
+    const routes = new Set(list.map(p => (isObject(p) && typeof p['route'] === 'string' ? p['route'] : null)).filter((r): r is string => !!r));
     list.forEach((raw, i) => {
         const path = `pages[${i}]`;
         if (!isObject(raw)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
         c.keys(raw, PAGE_KEYS, path);
-        c.string(raw, 'key', path);
+        const key = c.string(raw, 'key', path);
+        if (key && (Object.values(GlobalSlot) as string[]).includes(key)) {
+            c.add(SitePlanIssueCode.ReservedPageKey, `${path}.key`, `"${key}" names the site's ${key} — a page's sections would share its ids`);
+        }
         c.string(raw, 'name', path);
         for (const key of ['isHome', 'required', 'inNav']) c.boolean(raw, key, path);
         const route = c.string(raw, 'route', path);
@@ -288,6 +332,10 @@ function validatePages(c: Collector, list: unknown[], types: Map<string, Content
             }
         }
 
+        const archetype = c.string(raw, 'archetype', path, false);
+        if (archetype && !has(PAGE_ARCHETYPES, archetype)) c.add(SitePlanIssueCode.Archetype, `${path}.archetype`, `"${archetype}" is not a page type (${Object.keys(PAGE_ARCHETYPES).join(', ')})`);
+        validatePageSeo(c, raw['seo'], `${path}.seo`);
+
         c.array(raw, 'sections', path).forEach((s, j) => {
             const sp = `${path}.sections[${j}]`;
             if (!isObject(s)) return c.add(SitePlanIssueCode.Shape, sp, 'must be an object');
@@ -305,9 +353,29 @@ function validatePages(c: Collector, list: unknown[], types: Map<string, Content
                     for (const [slot, value] of Object.entries(slots)) {
                         if (!declared.includes(slot)) c.add(SitePlanIssueCode.UnknownSlot, `${sp}.slots.${slot}`, `"${patternId}" has no slot "${slot}" (${declared.join(', ') || 'none'})`);
                         else if (typeof value !== 'string') c.add(SitePlanIssueCode.Shape, `${sp}.slots.${slot}`, 'must be a string');
+                        else {
+                            const budget = slotBudget(pattern, slot, density);
+                            if (budget !== null && value.length > budget) c.add(SitePlanIssueCode.SlotTooLong, `${sp}.slots.${slot}`, `${value.length} characters — the slot holds ${budget} at the ${density ?? 'regular'} density`);
+                        }
+                    }
+                }
+            }
+            const links = s['links'];
+            if (links !== undefined) {
+                if (!isObject(links)) c.add(SitePlanIssueCode.Shape, `${sp}.links`, 'must be an object');
+                else {
+                    const linkSlots = patternLinkSlots(pattern);
+                    for (const [slot, route] of Object.entries(links)) {
+                        if (!linkSlots.includes(slot)) c.add(SitePlanIssueCode.InvalidLink, `${sp}.links.${slot}`, `"${patternId}" has no linked slot "${slot}" (${linkSlots.join(', ') || 'none'})`);
+                        else if (typeof route !== 'string' || !routes.has(route) || routeParams(route).length) c.add(SitePlanIssueCode.InvalidLink, `${sp}.links.${slot}`, `"${String(route)}" is not a page route of the plan`);
                     }
                 }
             }
+            const form = c.string(s, 'form', sp, false);
+            if (form && !patternHasForm(pattern)) c.add(SitePlanIssueCode.InvalidForm, `${sp}.form`, `"${patternId}" holds no form`);
+            else if (form && !formPresetById(form)) c.add(SitePlanIssueCode.InvalidForm, `${sp}.form`, `"${form}" is not a form preset`);
+            const enter = c.string(s, 'enter', sp, false);
+            if (enter && !has(SPEC_AXES.animations, enter)) c.add(SitePlanIssueCode.InvalidEnter, `${sp}.enter`, `must be one of ${Object.keys(SPEC_AXES.animations).join(', ')}`);
             const without = s['without'];
             if (without !== undefined) {
                 const parts = patternOptionalParts(pattern);
@@ -337,13 +405,15 @@ function validatePages(c: Collector, list: unknown[], types: Map<string, Content
                 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;
+            // L0-3: the roles a pattern reads must be roles of the item's type — the section's list (`item`), the route
+            // item (`route`) or its next sibling (`next`, the same type). An optional one (`@image?`) is only left out.
+            for (const need of patternRoleNeeds(pattern)) {
+                if (need.optional) continue;
+                const alias = need.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`);
+                if (type && !type.roles[need.role]) {
+                    c.add(SitePlanIssueCode.MissingRole, `${sp}.pattern`, `"${patternId}" shows each ${typeName} item's ${need.role} — ${typeName} names no ${need.role} field (roles.${need.role})`);
                 }
             }
         });
@@ -353,6 +423,18 @@ function validatePages(c: Collector, list: unknown[], types: Map<string, Content
     if (homes.length !== 1) c.add(SitePlanIssueCode.Home, 'pages', `exactly one page is the home page (found ${homes.length})`);
 }
 
+
+function validatePageSeo(c: Collector, seo: unknown, path: string): void {
+    if (seo === undefined) return;
+    if (!isObject(seo)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
+    c.keys(seo, PAGE_SEO_KEYS, path);
+    const limits: Readonly<Record<string, number>> = { title: SEO_TITLE_MAX, description: SEO_DESCRIPTION_MAX };
+    for (const key of PAGE_SEO_KEYS) {
+        const value = c.string(seo, key, path, false);
+        if (value && value.length > limits[key]) c.add(SitePlanIssueCode.InvalidSeo, `${path}.${key}`, `${value.length} characters — a search result shows ${limits[key]}`);
+    }
+}
+
 /** The plan's `$siblings.next` source of `routeSource` — what a pattern's `next.*` reads. */
 export function nextSourceOf(sources: Map<string, { type: string; of?: string; op?: string }>, routeSource: string): string | null {
     for (const [alias, s] of sources) if (s.type === PlanDataSourceType.Relative && s.of === routeSource && s.op === RelativeOp.SiblingsNext) return alias;
@@ -381,10 +463,12 @@ export function validateSitePlan(plan: unknown): SitePlanValidation {
     if (plan['version'] !== SITE_PLAN_VERSION) c.add(SitePlanIssueCode.Version, 'version', `must be "${SITE_PLAN_VERSION}"`);
     validateSource(c, plan['source']);
     validateBusiness(c, plan['business']);
+    validateLocale(c, plan['locale']);
     validateDesign(c, plan['design']);
     const types = validateContentTypes(c, c.array(plan, 'contentTypes', ''));
     const sources = validateDataSources(c, c.array(plan, 'dataSources', ''), types);
-    validatePages(c, c.array(plan, 'pages', ''), types, sources);
+    const design = isObject(plan['design']) ? plan['design'] : {};
+    validatePages(c, c.array(plan, 'pages', ''), types, sources, typeof design['density'] === 'string' ? design['density'] : null);
     validateGlobals(c, plan['globals']);
     return { valid: c.issues.length === 0, issues: c.issues };
 }
@@ -394,3 +478,27 @@ export function assertValidSitePlan(plan: unknown): void {
     const result = validateSitePlan(plan);
     if (!result.valid) throw new SitePlanError(result.issues);
 }
+
+/**
+ * A plan's pages against their page types (L0-2): every required slot filled, every section of a family the type takes.
+ * NOT part of `validateSitePlan` — a page type is what the model READS to give a page its shape, and the plan stage
+ * holds the model's plan to it; the owner may then make any page their own (merge About into Contact, drop the
+ * closing band), which the gate must not refuse. Pure; issues carry the same paths.
+ */
+export function archetypeIssues(plan: SitePlan): SitePlanIssue[] {
+    const c = new Collector();
+    plan.pages.forEach((page, i) => {
+        const type = page.archetype ? PAGE_ARCHETYPES[page.archetype] : undefined;
+        if (!type) return;
+        const families = page.sections.map(s => patternById(s.pattern)?.family ?? '');
+        for (const slot of type.slots) {
+            if (slot.required && !families.some(f => slot.families.includes(f))) {
+                c.add(SitePlanIssueCode.Archetype, `pages[${i}].sections`, `a ${page.archetype} page needs a ${slot.label} section (${slot.families.join(' / ')})`);
+            }
+        }
+        families.forEach((family, j) => {
+            if (!type.slots.some(slot => slot.families.includes(family))) c.add(SitePlanIssueCode.Archetype, `pages[${i}].sections[${j}]`, `a ${family} section does not belong on a ${page.archetype} page`);
+        });
+    });
+    return c.issues;
+}

package/src/harness-core/harness-spec.generated.ts

@@ -138,7 +138,7 @@ export const SPEC_STRUCTURES = {
       "About",
       "Contact"
     ],
-    "shipped": false
+    "shipped": true
   },
   "place": {
     "label": "Place",
@@ -146,11 +146,11 @@ export const SPEC_STRUCTURES = {
     "pages": [
       "Home",
       "Menu",
-      "Visit (hours + map)",
+      "Visit (hours and address)",
       "About",
       "Contact"
     ],
-    "shipped": false
+    "shipped": true
   }
 } as const;
 

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

@@ -23,3 +23,4 @@ export * from './reference-colour';
 export * from './site-reading';
 export * from './generation-view';
 export * from './starting-design';
+export * from './site-audit-view';

package/src/harness-core/reference-colour.ts

@@ -1,4 +1,4 @@
-import { auditDesignContrast, designTokenRows, parseHexColor, presetChoices, stylePresetById } from '@vectoriox/iox-ui/design-core';
+import { auditDesignContrast, designTokenRows, parseHexColor, presetChoices, resolveTokenValues, stylePresetById, wcagContrastRatio } from '@vectoriox/iox-ui/design-core';
 import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
 
 import { StyleRead } from './rank';
@@ -21,6 +21,17 @@ export interface ReferenceSeed {
     used: boolean;
     /** The modes the reference colour failed in (empty when used, or when there is no reference). */
     failsIn: Array<'light' | 'dark'>;
+    /** Information only: the RAW reference colour against the style's page ground (its first mode); null without one. */
+    rawRatio: number | null;
+}
+
+/** The raw colour's ratio against the preset's own page ground, in its first mode — shown, never decisive. */
+function rawRatioOf(presetId: string, hex: string): number | null {
+    const preset = stylePresetById(presetId);
+    const choices = preset ? presetChoices(preset.id, preset.modes[0]) : null;
+    if (!preset || !choices) return null;
+    const ground = resolveTokenValues(designTokenRows(choices), preset.modes[0])['page-bg'];
+    return ground && parseHexColor(ground) ? Math.round(wcagContrastRatio(hex, ground) * 100) / 100 : null;
 }
 
 /** Every mode `presetId` offers passes the audit with `seed`. */
@@ -39,7 +50,8 @@ export function referenceSeed(read: Pick<StyleRead, 'brand'> | null | undefined,
     const preset = stylePresetById(presetId);
     if (!preset) return null;
     const reference = read?.brand && parseHexColor(read.brand) ? read.brand : null;
-    if (!reference) return { seed: preset.seed, reference: null, used: false, failsIn: [] };
+    if (!reference) return { seed: preset.seed, reference: null, used: false, failsIn: [], rawRatio: null };
     const { passes, failsIn } = seedPassesPreset(preset.id, reference);
-    return passes ? { seed: reference, reference, used: true, failsIn: [] } : { seed: preset.seed, reference, used: false, failsIn };
+    const rawRatio = rawRatioOf(preset.id, reference);
+    return passes ? { seed: reference, reference, used: true, failsIn: [], rawRatio } : { seed: preset.seed, reference, used: false, failsIn, rawRatio };
 }

package/src/harness-core/site-audit-view.ts

@@ -0,0 +1,10 @@
+import type { SiteAudit } from '@vectoriox/iox-ui/generation-core';
+
+import type { LintFinding } from './lint';
+
+/**
+ * `GET …/webbuilder/site-audit?page=` (AI plan §3e, M1-7): the eight checks (generation-core `auditSite`) and the design
+ * advice beside them (`lintDesign` — never blocks, "Keep it" dismisses). ONE definition: iox-cms answers it, the Publish
+ * dialog and Needs attention read it.
+ */
+export type SiteAuditView = SiteAudit & { advice: LintFinding[] };

package/src/harness-core/starting-design.ts

@@ -12,7 +12,11 @@ import { referenceSeed } from './reference-colour';
  * the style offers (`referenceSeed`). Pure.
  */
 
-/** A preset for this business: its choices, Motion from the business (`motionFor`), what the owner already set kept. */
+/**
+ * A preset for this business: its choices, Motion from the business (`motionFor`), the references' colour as its seed
+ * when that colour passes AA in every mode the preset offers (`referenceSeed` — judged as used), and what the owner
+ * already set kept. The ONE rule for a Look pick and for Build with these.
+ */
 export function presetDesign(
     presetId: string,
     input: MotionInput | string | null,
@@ -23,7 +27,8 @@ export function presetDesign(
     if (!base) return null;
     const motionInput: MotionInput = typeof input === 'object' && input !== null ? input : { businessType: input as string | null };
     const start = motionFor(motionInput, presetId, read);
-    return { ...base, scroll: start.scroll, animate: start.animate, between: start.between, ...kept };
+    const seed = referenceSeed(read, presetId);
+    return { ...base, ...(seed?.used ? { seed: seed.seed } : {}), scroll: start.scroll, animate: start.animate, between: start.between, ...kept };
 }
 
 export interface StartingDesign {
@@ -39,6 +44,5 @@ export function startingDesign(input: (RankInput & MotionInput) | string | null,
     const top = rankWithReferences(rankInput, read)[0];
     const design = top ? presetDesign(top.id, rankInput, {}, read) : null;
     if (!top || !design) return null;
-    const seed = referenceSeed(read, top.id);
-    return seed?.used ? { presetId: top.id, design: { ...design, seed: seed.seed }, referenceColour: true } : { presetId: top.id, design, referenceColour: false };
+    return { presetId: top.id, design, referenceColour: !!referenceSeed(read, top.id)?.used };
 }