@vectoriox/iox-ui 5.46.0 → 5.47.0

package/harness-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-harness-core.mjs"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.46.0",
+  "version": "5.47.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -47,6 +47,10 @@
       "types": "./generation-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-generation-core.mjs"
     },
+    "./harness-core": {
+      "types": "./harness-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-harness-core.mjs"
+    },
     "./media-core": {
       "types": "./media-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-media-core.mjs"

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

@@ -17,6 +17,7 @@ export * from './site-plan.model';
 export * from './patterns';
 export * from './templates';
 export * from './serialized-node';
+export * from './shape-check';
 export * from './validate-site-plan';
 export * from './compose-site';
 export * from './nav-shape';

package/src/generation-core/shape-check.ts

@@ -0,0 +1,92 @@
+/**
+ * The ONE way a framework-free gate refuses a document "with a path, never repairs" (W1's site-plan gate, the
+ * harness's analysis gate): a documented shape table (key → type text; `key?` optional, `[name]` the object's
+ * own field names) whose key lists the gate READS — so the shape a model is told about is the shape refused —
+ * and a collector that records each refusal at its dotted path. Generic over each gate's issue-code enum.
+ */
+
+export type ShapeEntry = Readonly<Record<string, string>>;
+export type PlainObject = Record<string, unknown>;
+
+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));
+}
+
+export const isPlainObject = (v: unknown): v is PlainObject => !!v && typeof v === 'object' && !Array.isArray(v);
+export const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
+/** `path.key`, or `key` at the root. */
+export const pathAt = (path: string, key: string) => (path ? `${path}.${key}` : key);
+
+export interface PathIssue<C extends string> {
+    code: C;
+    /** Where, as a dotted path into the document (`pages[2].sections[0].binding`). */
+    path: string;
+    message: string;
+}
+
+/** The three refusals every shape gate shares, named in that gate's own code enum. */
+export interface ShapeIssueCodes<C extends string> {
+    /** A value of the wrong type, or a required value missing. */
+    shape: C;
+    /** A key the shape does not have. */
+    unknownKey: C;
+    /** A name used twice where it must be unique. */
+    duplicate: C;
+}
+
+export class PathIssueCollector<C extends string> {
+    readonly issues: PathIssue<C>[] = [];
+
+    /** `subject` names the document in a refusal ("… is not part of the plan shape"). */
+    constructor(private readonly subject: string, private readonly codes: ShapeIssueCodes<C>) {}
+
+    add(code: C, path: string, message: string): void {
+        this.issues.push({ code, path, message });
+    }
+
+    keys(obj: PlainObject, allowed: ReadonlyArray<string>, path: string): void {
+        for (const key of Object.keys(obj)) if (!allowed.includes(key)) this.add(this.codes.unknownKey, pathAt(path, key), `"${key}" is not part of the ${this.subject} shape`);
+    }
+
+    string(obj: PlainObject, key: string, path: string, required = true): string | null {
+        const v = obj[key];
+        if (v === undefined && !required) return null;
+        if (!isNonEmptyString(v)) {
+            this.add(this.codes.shape, pathAt(path, key), 'must be a non-empty string');
+            return null;
+        }
+        return v;
+    }
+
+    boolean(obj: PlainObject, key: string, path: string): void {
+        if (obj[key] !== undefined && typeof obj[key] !== 'boolean') this.add(this.codes.shape, pathAt(path, key), 'must be a boolean');
+    }
+
+    array(obj: PlainObject, key: string, path: string): unknown[] {
+        const v = obj[key];
+        if (!Array.isArray(v)) {
+            this.add(this.codes.shape, pathAt(path, key), 'must be an array');
+            return [];
+        }
+        return v;
+    }
+
+    unique(values: Array<string | null>, path: (i: number) => string, what: string): void {
+        const seen = new Set<string>();
+        values.forEach((v, i) => {
+            if (v === null) return;
+            if (seen.has(v)) this.add(this.codes.duplicate, path(i), `${what} "${v}" is used twice`);
+            seen.add(v);
+        });
+    }
+}

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

@@ -25,7 +25,7 @@ export const SPEC_SITE_PLAN_SHAPE = {
   "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"
+    "facts?": "{ [fact]: string } — facts (email, phone, city, address, hours): only the customer's own words; a blank fact is a publish-blocking placeholder, never invented"
   },
   "design": {
     "flavorId": "string — a v2 flavor pack id",
@@ -104,7 +104,9 @@ export const SPEC_SITE_PLAN_SHAPE = {
 export const SPEC_SITE_FACTS = {
   "email": "Email address",
   "phone": "Phone number",
-  "city": "City or area"
+  "city": "City or area",
+  "address": "Street address",
+  "hours": "Opening hours"
 } as const;
 
 export const SPEC_SITE_PATTERNS = {
@@ -2052,3 +2054,130 @@ export const SPEC_SITE_TEMPLATES = {
     }
   }
 } as const;
+
+export const SPEC_SITE_LIBRARY = [
+  {
+    "id": "nav.inline-cta",
+    "family": "nav"
+  },
+  {
+    "id": "nav.centered-logo",
+    "family": "nav"
+  },
+  {
+    "id": "nav.overlay-menu",
+    "family": "nav"
+  },
+  {
+    "id": "hero.split",
+    "family": "hero"
+  },
+  {
+    "id": "hero.centered",
+    "family": "hero"
+  },
+  {
+    "id": "hero.full-bleed-media",
+    "family": "hero"
+  },
+  {
+    "id": "hero.stacked-editorial",
+    "family": "hero"
+  },
+  {
+    "id": "proof.logo-strip",
+    "family": "proof"
+  },
+  {
+    "id": "proof.stat-row",
+    "family": "proof"
+  },
+  {
+    "id": "proof.testimonial-single",
+    "family": "proof"
+  },
+  {
+    "id": "proof.testimonial-carousel",
+    "family": "proof"
+  },
+  {
+    "id": "feature.triad",
+    "family": "feature"
+  },
+  {
+    "id": "feature.alternating-rows",
+    "family": "feature"
+  },
+  {
+    "id": "feature.icon-list",
+    "family": "feature"
+  },
+  {
+    "id": "feature.tabbed",
+    "family": "feature"
+  },
+  {
+    "id": "collection.card-grid",
+    "family": "collection"
+  },
+  {
+    "id": "collection.masonry-gallery",
+    "family": "collection"
+  },
+  {
+    "id": "collection.slider",
+    "family": "collection"
+  },
+  {
+    "id": "collection.list-detail",
+    "family": "collection"
+  },
+  {
+    "id": "story.long-form",
+    "family": "story"
+  },
+  {
+    "id": "story.timeline",
+    "family": "story"
+  },
+  {
+    "id": "story.quote-break",
+    "family": "story"
+  },
+  {
+    "id": "cta.banner",
+    "family": "cta"
+  },
+  {
+    "id": "cta.split-form",
+    "family": "cta"
+  },
+  {
+    "id": "contact.split-map",
+    "family": "contact"
+  },
+  {
+    "id": "contact.simple",
+    "family": "contact"
+  },
+  {
+    "id": "faq.accordion",
+    "family": "faq"
+  },
+  {
+    "id": "pricing.tiers",
+    "family": "pricing"
+  },
+  {
+    "id": "footer.three-column",
+    "family": "footer"
+  },
+  {
+    "id": "footer.mega",
+    "family": "footer"
+  },
+  {
+    "id": "footer.minimal",
+    "family": "footer"
+  }
+] as const;

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

@@ -7,6 +7,9 @@ import {
     FACT_KEYS, GlobalSlot, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlanSourceKind, SITE_PLAN_VERSION,
 } from './site-plan.model';
 import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
+import {
+    isNonEmptyString, isPlainObject as isObject, PathIssue, PathIssueCollector, pathAt as at, PlainObject as Obj, requiredShapeKeys, ShapeEntry, shapeKeys,
+} from './shape-check';
 
 /**
  * The Site Plan validator — the gate in front of the composer. The wizard's plan and (later) the AI's
@@ -45,12 +48,7 @@ export enum SitePlanIssueCode {
     MissingPreviewField = 'missing-preview-field',
 }
 
-export interface SitePlanIssue {
-    code: SitePlanIssueCode;
-    /** Where, as a dotted path into the plan (`pages[2].sections[0].binding`). */
-    path: string;
-    message: string;
-}
+export type SitePlanIssue = PathIssue<SitePlanIssueCode>;
 
 export interface SitePlanValidation {
     valid: boolean;
@@ -67,22 +65,8 @@ export class SitePlanError extends Error {
 const RESERVED_PREFIX = '$';
 const ID_FIELD = '_id';
 
-/** 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));
-}
-
+/** The documented plan shape (contract `site.planShape`): its key lists are READ (`shape-check`), so a key
+ *  the plan documents is a key the gate validates — and an undocumented one is refused. */
 const SHAPE: Readonly<Record<string, ShapeEntry>> = SPEC_SITE_PLAN_SHAPE;
 const PLAN_KEYS = shapeKeys(SHAPE['plan']);
 const TEMPLATE_SOURCE_KEYS = shapeKeys(SHAPE['sourceTemplate']);
@@ -104,53 +88,16 @@ const GLOBAL_POSITION: Readonly<Record<`${GlobalSlot}`, `${PatternGlobalPosition
 const ROUTE = /^\/(?:(?:[a-z0-9]+(?:-[a-z0-9]+)*|:[a-zA-Z_][a-zA-Z0-9_]*)(?:\/(?:[a-z0-9]+(?:-[a-z0-9]+)*|:[a-zA-Z_][a-zA-Z0-9_]*))*)?$/;
 const ROUTE_PARAM = /:([a-zA-Z_][a-zA-Z0-9_]*)/g;
 
-type Obj = Record<string, unknown>;
-
-const isObject = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
-const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
 const has = (table: object, key: string) => Object.prototype.hasOwnProperty.call(table, key);
-const at = (path: string, key: string) => (path ? `${path}.${key}` : key);
 
 /** The `:param` names of a route, in order. */
 export function routeParams(route: string): string[] {
     return [...route.matchAll(ROUTE_PARAM)].map(m => m[1]);
 }
 
-class Collector {
-    readonly issues: SitePlanIssue[] = [];
-    add(code: SitePlanIssueCode, path: string, message: string): void {
-        this.issues.push({ code, path, message });
-    }
-    keys(obj: Obj, allowed: ReadonlyArray<string>, path: string): void {
-        for (const key of Object.keys(obj)) if (!allowed.includes(key)) this.add(SitePlanIssueCode.UnknownKey, at(path, key), `"${key}" is not part of the plan shape`);
-    }
-    string(obj: Obj, key: string, path: string, required = true): string | null {
-        const v = obj[key];
-        if (v === undefined && !required) return null;
-        if (!isNonEmptyString(v)) {
-            this.add(SitePlanIssueCode.Shape, at(path, key), 'must be a non-empty string');
-            return null;
-        }
-        return v;
-    }
-    boolean(obj: Obj, key: string, path: string): void {
-        if (obj[key] !== undefined && typeof obj[key] !== 'boolean') this.add(SitePlanIssueCode.Shape, at(path, key), 'must be a boolean');
-    }
-    array(obj: Obj, key: string, path: string): unknown[] {
-        const v = obj[key];
-        if (!Array.isArray(v)) {
-            this.add(SitePlanIssueCode.Shape, at(path, key), 'must be an array');
-            return [];
-        }
-        return v;
-    }
-    unique(values: Array<string | null>, path: (i: number) => string, what: string): void {
-        const seen = new Set<string>();
-        values.forEach((v, i) => {
-            if (v === null) return;
-            if (seen.has(v)) this.add(SitePlanIssueCode.Duplicate, path(i), `${what} "${v}" is used twice`);
-            seen.add(v);
-        });
+class Collector extends PathIssueCollector<SitePlanIssueCode> {
+    constructor() {
+        super('plan', { shape: SitePlanIssueCode.Shape, unknownKey: SitePlanIssueCode.UnknownKey, duplicate: SitePlanIssueCode.Duplicate });
     }
 }
 

package/src/harness-core/business-types.ts

@@ -0,0 +1,141 @@
+import type { DensityId, DesignMotion, MoodId, MotionId, TintId } from '@vectoriox/iox-ui/design-core';
+import type { FactKey } from '@vectoriox/iox-ui/generation-core';
+
+import {
+    SPEC_BUSINESS_TYPES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS,
+} from './harness-spec.generated';
+
+/**
+ * The design harness's knowledge (AI plan rev 3 §3f, H2): the 30 kinds of business IOX serves, each with the
+ * styles that suit it (best first, with the reason), its look rules and content rules (one closed grammar,
+ * read by the ranker and the lint), its voice, its motion, the pages it needs and its home sections.
+ * Generated 1:1 from the contract (`harness`, gated in build-spec.mjs). Seeded from UI UX Pro Max — the
+ * attribution travels with the data (`HARNESS_SOURCE.notice`).
+ */
+export const HARNESS_SOURCE = SPEC_HARNESS_SOURCE;
+
+/** What a site may need — the closed list an analysis returns; each maps to the archetype a plan writes. */
+export type NeedId = keyof typeof SPEC_NEEDS;
+export const NEED_IDS = Object.keys(SPEC_NEEDS) as ReadonlyArray<NeedId>;
+export interface NeedDef {
+    readonly label: string;
+    readonly archetype: string;
+}
+export const NEEDS: Readonly<Record<NeedId, NeedDef>> = SPEC_NEEDS;
+
+/** What an owner may ask to avoid ("no dark backgrounds") — each one look rule. */
+export type UserAvoidId = keyof typeof SPEC_USER_AVOIDS;
+export const USER_AVOID_IDS = Object.keys(SPEC_USER_AVOIDS) as ReadonlyArray<UserAvoidId>;
+
+/** The structures a site is built from (Studio · Practice · Place). */
+export type StructureId = keyof typeof SPEC_STRUCTURES;
+export const STRUCTURES = SPEC_STRUCTURES;
+
+/** How much a kind of business needs "book a slot" — the next product bet (off this road). */
+export enum BookingNeed {
+    Must = 'must',
+    Tables = 'tables',
+    Sometimes = 'sometimes',
+    None = 'none',
+}
+
+/** The content checks of the avoid grammar (a look rule is the other kind). */
+export enum AvoidCheck {
+    NeedsFamily = 'needs-family',
+    NeedsFact = 'needs-fact',
+    ImageHero = 'image-hero',
+    NoPattern = 'no-pattern',
+    BrandHue = 'brand-hue',
+    CopyLength = 'copy-length',
+}
+
+/** How much text a site carries, shortest first. */
+export enum CopyLength {
+    Short = 'short',
+    Standard = 'standard',
+    Rich = 'rich',
+}
+export const COPY_LENGTH_ORDER: ReadonlyArray<`${CopyLength}`> = [CopyLength.Short, CopyLength.Standard, CopyLength.Rich];
+
+/** A look a business should not wear: each named axis lists the values that match (all named axes must). */
+export interface LookCondition {
+    readonly flavor?: ReadonlyArray<string>;
+    readonly mode?: ReadonlyArray<string>;
+    readonly motion?: ReadonlyArray<MotionId>;
+    readonly moods?: ReadonlyArray<MoodId>;
+    readonly tint?: ReadonlyArray<TintId>;
+    readonly density?: ReadonlyArray<DensityId>;
+    readonly scroll?: ReadonlyArray<string>;
+    readonly animate?: ReadonlyArray<string>;
+    readonly between?: ReadonlyArray<string>;
+}
+
+export interface LookRule {
+    readonly when: LookCondition;
+    readonly say: string;
+}
+
+export type CheckRule =
+    | { readonly check: `${AvoidCheck.NeedsFamily}`; readonly family: string; readonly say: string }
+    | { readonly check: `${AvoidCheck.NeedsFact}`; readonly fact: FactKey; readonly say: string }
+    | { readonly check: `${AvoidCheck.ImageHero}`; readonly say: string }
+    | { readonly check: `${AvoidCheck.NoPattern}`; readonly pattern: string; readonly say: string }
+    | { readonly check: `${AvoidCheck.BrandHue}`; readonly from: number; readonly to: number; readonly minChroma: number; readonly say: string }
+    | { readonly check: `${AvoidCheck.CopyLength}`; readonly max: `${CopyLength}`; readonly say: string };
+
+export type AvoidRule = LookRule | CheckRule;
+
+export const isLookRule = (rule: AvoidRule): rule is LookRule => 'when' in rule;
+
+export interface GoodFit {
+    readonly preset: string;
+    readonly reason: string;
+}
+
+export interface BusinessType {
+    readonly id: string;
+    readonly label: string;
+    readonly he: string;
+    readonly group: string;
+    readonly uupm: string;
+    /** Keywords (English + Hebrew): the eval's expected answer and the no-model fallback. */
+    readonly match: ReadonlyArray<string>;
+    /** The styles that suit it, best first, each with why. */
+    readonly good: ReadonlyArray<GoodFit>;
+    readonly colour: { readonly mood: string; readonly swatches: ReadonlyArray<string> };
+    readonly fonts: string;
+    readonly tone: string;
+    /** The motion TIMING it suits (the design axis — hover lift, durations). */
+    readonly motion: MotionId;
+    /** How its site usually scrolls, how animated it is and what plays between pages (rev 3.1). */
+    readonly moves: Readonly<DesignMotion>;
+    readonly imagery: string;
+    readonly pages: ReadonlyArray<string>;
+    /** The needs its page set implies, in page order (derived from `pages` at contract build). */
+    readonly needs: ReadonlyArray<NeedId>;
+    /** The home page's sections, library ids. */
+    readonly home: ReadonlyArray<string>;
+    readonly avoid: ReadonlyArray<AvoidRule>;
+    /** Words its copy must not use. */
+    readonly words: ReadonlyArray<string>;
+    readonly structure: StructureId;
+    /** In the M1-alpha slice. */
+    readonly slice: boolean;
+    /** Stock photos may fill its pictures (never the work itself). */
+    readonly stock: boolean;
+    readonly booking: `${BookingNeed}`;
+}
+
+/** The 30, in the board's order. Assignment here proves the generated data fits the type. */
+export const BUSINESS_TYPES: ReadonlyArray<BusinessType> = SPEC_BUSINESS_TYPES;
+
+export function businessTypeById(id: string | null | undefined): BusinessType | undefined {
+    return id ? BUSINESS_TYPES.find(t => t.id === id) : undefined;
+}
+
+export const BUSINESS_TYPE_IDS: ReadonlyArray<string> = BUSINESS_TYPES.map(t => t.id);
+
+/** The user-avoid rule for an id, or undefined. */
+export function userAvoidRule(id: string): LookRule | undefined {
+    return (SPEC_USER_AVOIDS as Readonly<Record<string, LookRule>>)[id];
+}