@vectoriox/iox-ui 5.25.0 → 5.27.0

package/src/generation-core/patterns.ts

@@ -0,0 +1,125 @@
+import { SPEC_SITE_PATTERNS } from './site-spec.generated';
+
+/**
+ * The pattern library (contract `site.patterns`): structure and element styles only — never a colour,
+ * size or font. Each node is written in the contract's short vocabulary:
+ *
+ * `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) ·
+ * `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.
+ */
+export interface PatternNode {
+    readonly t: string;
+    readonly es?: string;
+    readonly scheme?: string;
+    readonly tag?: string;
+    readonly level?: string;
+    readonly lay?: Readonly<Record<string, string>>;
+    readonly resp?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly aspect?: string;
+    readonly slot?: string;
+    readonly fromBusiness?: string;
+    readonly text?: string;
+    readonly ph?: string;
+    readonly bind?: string;
+    readonly src?: string;
+    readonly href?: string;
+    readonly param?: string;
+    readonly optional?: string;
+    readonly preset?: string;
+    readonly control?: string;
+    readonly label?: string;
+    readonly required?: boolean;
+    readonly c?: ReadonlyArray<PatternNode>;
+}
+
+export enum PatternGlobalPosition {
+    Before = 'before',
+    After = 'after',
+}
+
+export interface SitePattern {
+    readonly family: string;
+    readonly label: string;
+    /** Set on a header/footer pattern: it renders on every page, before or after the page. */
+    readonly global?: `${PatternGlobalPosition}`;
+    readonly node: PatternNode;
+}
+
+export const SITE_PATTERNS: Readonly<Record<string, SitePattern>> = SPEC_SITE_PATTERNS;
+
+/** The pattern placeholder kinds that are not FACT keys. */
+export enum PatternPlaceholder {
+    Copy = 'copy',
+    Image = 'image',
+}
+
+/** The composer directives a pattern writes where a plan supplies the value. */
+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. */
+    NavPages = '$navPages',
+    /** A Link's route: the nav item's route. */
+    PageRoute = '$page.route',
+}
+
+/** The scopes a `bind` / `param` / `src` path starts with. */
+export enum BindScope {
+    /** The nearest Repeater's row. */
+    Item = 'item',
+    /** The nearest Repeater's row, when that Repeater iterates the navigation's pages. */
+    Page = 'page',
+    /** The page's route item (`routeSource`). */
+    Route = 'route',
+    /** The route item's next sibling (the plan's `$siblings.next` source of the route item). */
+    Next = 'next',
+}
+
+export function patternById(id: string | null | undefined): SitePattern | undefined {
+    return id && Object.prototype.hasOwnProperty.call(SITE_PATTERNS, id) ? SITE_PATTERNS[id] : undefined;
+}
+
+function walk(node: PatternNode, visit: (n: PatternNode) => void): void {
+    visit(node);
+    for (const child of node.c ?? []) walk(child, visit);
+}
+
+/** Every node of a pattern, depth first. */
+export function patternNodes(pattern: SitePattern): PatternNode[] {
+    const out: PatternNode[] = [];
+    walk(pattern.node, n => out.push(n));
+    return out;
+}
+
+/** The slot names a plan section may fill. */
+export function patternSlots(pattern: SitePattern): string[] {
+    return [...new Set(patternNodes(pattern).map(n => n.slot).filter((s): s is string => !!s))];
+}
+
+/** The optional parts a plan section may leave out. */
+export function patternOptionalParts(pattern: SitePattern): string[] {
+    return [...new Set(patternNodes(pattern).map(n => n.optional).filter((s): s is string => !!s))];
+}
+
+/** True when the pattern has a Repeater iterating the section's `binding`. */
+export function patternNeedsBinding(pattern: SitePattern): boolean {
+    return patternNodes(pattern).some(n => n.src === PatternDirective.Binding);
+}
+
+/** 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]) {
+            if (path && !path.startsWith('$')) scopes.add(path.split('.')[0]);
+        }
+    }
+    return scopes;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @vectoriox/iox-ui/generation-core — the shared, FRAMEWORK-FREE site-plan core (design-system plan
+ * §6b, W1): the Site Plan shape + its validator, the pattern library and the Studio template (both
+ * generated 1:1 from iox-ai-guidance `flavor-spec.v1.json`), and `composeSite` — a plan in, the
+ * schemas, sample items, data sources, pages, routes and header/footer globals out, as serialized
+ * layout JSON. The website wizard (W2–W4) and the AI agent drive the SAME composer.
+ * Pure: no transport, no clock, no randomness. Consumed by iox-cms (the server-side site build), the
+ * builder and the engine, so nothing here may import Angular.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths —
+ * or `nest start` dies with ERR_REQUIRE_ESM while jest and build both pass.
+ */
+export * from './site-spec.generated';
+export * from './node-baseline.model';
+export * from './node-baselines.generated';
+export * from './site-plan.model';
+export * from './patterns';
+export * from './templates';
+export * from './serialized-node';
+export * from './validate-site-plan';
+export * from './compose-site';

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

@@ -0,0 +1,91 @@
+import { applyElementStyle, defaultElementStyleFor, elementStyleById, NEW_NODE_STYLE_DEFAULTS, ownedTraitsOf } from '@vectoriox/iox-ui/design-core';
+
+import { NODE_BASELINES } from './node-baselines.generated';
+import { PatternGlobalPosition } from './patterns';
+
+/**
+ * A node exactly as a saved page layout stores it (the builder serializer's shape): flat `props` and
+ * a FULL `styleProps` (self-describing — render-parity.md, task 10), the element style's pseudo-states,
+ * sparse per-breakpoint overrides and the bindings. What the composer emits; what the builder reloads
+ * and the engine renders, unchanged.
+ */
+export interface SerializedBinding {
+    prop: string;
+    source: string;
+    path: string;
+}
+
+export type SerializedResponsive = Partial<Record<string, { styleProps?: Record<string, unknown> }>>;
+
+export interface SerializedNode {
+    id: string;
+    type: string;
+    label?: string;
+    props: Record<string, unknown>;
+    styleProps: Record<string, unknown>;
+    stateStyles?: Partial<Record<string, Record<string, unknown>>>;
+    responsive?: SerializedResponsive;
+    elementStyle?: string;
+    bindings: SerializedBinding[];
+    interactions: unknown[];
+    isGlobal?: boolean;
+    globalPosition?: `${PatternGlobalPosition}`;
+    children?: SerializedNode[];
+}
+
+/** A pattern the composer cannot stamp as the builder would (an unregistered type, a trait the type has
+ *  no slot for, a style that does not apply). The plan is validated first, so this means the CONTRACT is
+ *  wrong — never something to work around. */
+export class ComposeError extends Error {}
+
+const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+
+/**
+ * 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.
+ */
+export function createSerializedNode(id: string, type: string, props: Record<string, unknown> = {}, elementStyle?: string | null): SerializedNode {
+    const baseline = NODE_BASELINES[type];
+    if (!baseline) throw new ComposeError(`"${type}" is not a registered component type`);
+    const node: SerializedNode = {
+        id,
+        type,
+        props: { ...clone(baseline.props), ...props },
+        styleProps: clone(baseline.styleProps) as Record<string, unknown>,
+        bindings: [],
+        interactions: [],
+    };
+    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) {
+        const style = elementStyleById(styleId);
+        if (!style?.appliesTo.includes(type)) throw new ComposeError(`element style "${styleId}" does not apply to ${type}`);
+        const missing = ownedTraitsOf(style).filter(o => !o.state && !baseline.styleTraits.includes(o.trait));
+        if (missing.length) throw new ComposeError(`${type} has no slot for ${styleId}'s ${missing.map(o => o.trait).join(', ')}`);
+        applyElementStyle(node, styleId);
+    }
+    if (baseline.container) node.children = [];
+    return node;
+}
+
+/** Refuse a style trait the type has no slot for — the builder would silently drop it. */
+export function assertStyleSlots(type: string, names: ReadonlyArray<string>): void {
+    const slots = NODE_BASELINES[type]?.styleTraits ?? [];
+    for (const name of names) if (!slots.includes(name)) throw new ComposeError(`${type} has no style trait "${name}"`);
+}
+
+/** Write style traits onto a node (each one a slot the type has). */
+export function setStyleProps(node: SerializedNode, values: Readonly<Record<string, unknown>>): void {
+    assertStyleSlots(node.type, Object.keys(values));
+    for (const [name, value] of Object.entries(values)) node.styleProps[name] = value;
+}
+
+/** Every node of a tree, depth first. */
+export function walkSerialized(nodes: ReadonlyArray<SerializedNode>, visit: (node: SerializedNode, ancestors: SerializedNode[]) => void, ancestors: SerializedNode[] = []): void {
+    for (const node of nodes) {
+        visit(node, ancestors);
+        if (node.children?.length) walkSerialized(node.children, visit, [...ancestors, node]);
+    }
+}

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

@@ -0,0 +1,136 @@
+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
+ * (`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.
+ */
+
+export const SITE_PLAN_VERSION = '1';
+
+export enum SitePlanSourceKind {
+    Template = 'template',
+    Ai = 'ai',
+}
+
+export type SitePlanSource =
+    | { kind: `${SitePlanSourceKind.Template}`; templateId: string; templateVersion: number }
+    | { kind: `${SitePlanSourceKind.Ai}`; runId: string };
+
+/** A fact a customer could be held to. Only ever the customer's own words; blank → a placeholder. */
+export type FactKey = keyof typeof SPEC_SITE_FACTS;
+export const FACT_KEYS = Object.keys(SPEC_SITE_FACTS) as ReadonlyArray<FactKey>;
+/** The label a missing fact shows, verbatim from the contract. */
+export const SITE_FACT_LABELS: Readonly<Record<FactKey, string>> = SPEC_SITE_FACTS;
+
+export interface SiteBusiness {
+    readonly name: string;
+    readonly tagline?: string;
+    readonly facts?: Readonly<Partial<Record<FactKey, string>>>;
+}
+
+export interface ContentFieldPlan {
+    readonly name: string;
+    readonly type: string;
+    readonly controller: string;
+    readonly required?: boolean;
+    readonly note?: string;
+}
+
+/** How the content type's sample items are seeded. String values are templates: `{n}` is the item's
+ *  1-based number, `{sampleImage:n}` / `{sampleImage:n+k}` a bundled sample image (resolved by the build). */
+export interface ContentSeedPlan {
+    readonly count: number;
+    readonly sample: boolean;
+    readonly isPublished: boolean;
+    readonly [field: string]: unknown;
+}
+
+export interface ContentTypePlan {
+    readonly name: string;
+    readonly label: string;
+    readonly previewTextField?: string;
+    readonly previewImageField?: string;
+    readonly fields: ReadonlyArray<ContentFieldPlan>;
+    readonly seed?: ContentSeedPlan;
+}
+
+export enum PlanDataSourceType {
+    Cms = 'cms',
+    Relative = 'relative',
+}
+
+export enum PlanDataSourceMode {
+    Query = 'query',
+    Single = 'single',
+}
+
+/** The relative operations a plan may name, and the shipped `RelativeSourceSpec` each one is. */
+export enum RelativeOp {
+    SiblingsNext = '$siblings.next',
+    SiblingsPrev = '$siblings.prev',
+}
+
+export interface CmsDataSourcePlan {
+    readonly alias: string;
+    readonly type: `${PlanDataSourceType.Cms}`;
+    readonly mode: `${PlanDataSourceMode}`;
+    readonly contentType: string;
+    readonly limit?: number;
+    readonly filterByRouteParam?: { readonly field: string; readonly routeParam: string };
+}
+
+export interface RelativeDataSourcePlan {
+    readonly alias: string;
+    readonly type: `${PlanDataSourceType.Relative}`;
+    /** The subject: the alias of the current item. */
+    readonly of: string;
+    readonly op: `${RelativeOp}`;
+    /** The collection the subject is located within. */
+    readonly within: string;
+}
+
+export type DataSourcePlan = CmsDataSourcePlan | RelativeDataSourcePlan;
+
+export interface PageSectionPlan {
+    readonly pattern: string;
+    readonly slots?: Readonly<Record<string, string>>;
+    /** The list source alias a pattern's `$binding` repeater iterates. */
+    readonly binding?: string;
+    /** Optional pattern parts (`optional: <id>`) to leave out. */
+    readonly without?: ReadonlyArray<string>;
+}
+
+export interface PagePlan {
+    readonly key: string;
+    readonly name: string;
+    readonly route: string;
+    readonly isHome?: boolean;
+    /** Carried by templates (the wizard's Pages step); not part of the documented plan shape. */
+    readonly required?: boolean;
+    /** In the navigation (`$navPages`). Carried by templates; not part of the documented plan shape. */
+    readonly inNav?: boolean;
+    /** A template page: the content type it renders one item of. */
+    readonly template?: string;
+    /** The single source bound to the route item (`route.*`). */
+    readonly routeSource?: string;
+    readonly sections: ReadonlyArray<PageSectionPlan>;
+}
+
+export enum GlobalSlot {
+    Header = 'header',
+    Footer = 'footer',
+}
+
+export interface SitePlan {
+    readonly version: typeof SITE_PLAN_VERSION;
+    readonly source: SitePlanSource;
+    readonly business: SiteBusiness;
+    readonly design: Readonly<DesignChoices>;
+    readonly contentTypes: ReadonlyArray<ContentTypePlan>;
+    readonly dataSources: ReadonlyArray<DataSourcePlan>;
+    readonly pages: ReadonlyArray<PagePlan>;
+    readonly globals: Readonly<Record<`${GlobalSlot}`, string>>;
+}