@vectoriox/iox-ui 5.46.0 → 5.48.0

package/generation-core/index.d.ts

@@ -1,4 +1,4 @@
-import { DesignChoices } from '@vectoriox/iox-ui/design-core';
+import { DesignChoices, AnimateId } from '@vectoriox/iox-ui/design-core';
 
 declare const SPEC_SITE_PLAN_SHAPE: {
     readonly plan: {
@@ -23,7 +23,7 @@ declare const SPEC_SITE_PLAN_SHAPE: {
     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 "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";
     };
     readonly design: {
         readonly flavorId: "string — a v2 flavor pack id";
@@ -102,6 +102,8 @@ declare const SPEC_SITE_FACTS: {
     readonly email: "Email address";
     readonly phone: "Phone number";
     readonly city: "City or area";
+    readonly address: "Street address";
+    readonly hours: "Opening hours";
 };
 declare const SPEC_SITE_PATTERNS: {
     readonly "nav.inline-cta": {
@@ -1759,6 +1761,100 @@ declare const SPEC_SITE_TEMPLATES: {
         };
     };
 };
+declare const SPEC_SITE_LIBRARY: readonly [{
+    readonly id: "nav.inline-cta";
+    readonly family: "nav";
+}, {
+    readonly id: "nav.centered-logo";
+    readonly family: "nav";
+}, {
+    readonly id: "nav.overlay-menu";
+    readonly family: "nav";
+}, {
+    readonly id: "hero.split";
+    readonly family: "hero";
+}, {
+    readonly id: "hero.centered";
+    readonly family: "hero";
+}, {
+    readonly id: "hero.full-bleed-media";
+    readonly family: "hero";
+}, {
+    readonly id: "hero.stacked-editorial";
+    readonly family: "hero";
+}, {
+    readonly id: "proof.logo-strip";
+    readonly family: "proof";
+}, {
+    readonly id: "proof.stat-row";
+    readonly family: "proof";
+}, {
+    readonly id: "proof.testimonial-single";
+    readonly family: "proof";
+}, {
+    readonly id: "proof.testimonial-carousel";
+    readonly family: "proof";
+}, {
+    readonly id: "feature.triad";
+    readonly family: "feature";
+}, {
+    readonly id: "feature.alternating-rows";
+    readonly family: "feature";
+}, {
+    readonly id: "feature.icon-list";
+    readonly family: "feature";
+}, {
+    readonly id: "feature.tabbed";
+    readonly family: "feature";
+}, {
+    readonly id: "collection.card-grid";
+    readonly family: "collection";
+}, {
+    readonly id: "collection.masonry-gallery";
+    readonly family: "collection";
+}, {
+    readonly id: "collection.slider";
+    readonly family: "collection";
+}, {
+    readonly id: "collection.list-detail";
+    readonly family: "collection";
+}, {
+    readonly id: "story.long-form";
+    readonly family: "story";
+}, {
+    readonly id: "story.timeline";
+    readonly family: "story";
+}, {
+    readonly id: "story.quote-break";
+    readonly family: "story";
+}, {
+    readonly id: "cta.banner";
+    readonly family: "cta";
+}, {
+    readonly id: "cta.split-form";
+    readonly family: "cta";
+}, {
+    readonly id: "contact.split-map";
+    readonly family: "contact";
+}, {
+    readonly id: "contact.simple";
+    readonly family: "contact";
+}, {
+    readonly id: "faq.accordion";
+    readonly family: "faq";
+}, {
+    readonly id: "pricing.tiers";
+    readonly family: "pricing";
+}, {
+    readonly id: "footer.three-column";
+    readonly family: "footer";
+}, {
+    readonly id: "footer.mega";
+    readonly family: "footer";
+}, {
+    readonly id: "footer.minimal";
+    readonly family: "footer";
+}];
 
 /** What an untouched node of one registered type saves as (`NODE_BASELINES`, generated from the live
  *  iox-builder configs) — the builder serializer's flat `props` / `styleProps`, the trait names it has a
@@ -2190,6 +2286,51 @@ declare function setStyleProps(node: SerializedNode, values: Readonly<Record<str
 /** Every node of a tree, depth first. */
 declare function walkSerialized(nodes: ReadonlyArray<SerializedNode>, visit: (node: SerializedNode, ancestors: SerializedNode[]) => void, ancestors?: SerializedNode[]): void;
 
+/**
+ * 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.
+ */
+type ShapeEntry = Readonly<Record<string, string>>;
+type PlainObject = Record<string, unknown>;
+/** 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[];
+declare const isPlainObject: (v: unknown) => v is PlainObject;
+declare const isNonEmptyString: (v: unknown) => v is string;
+/** `path.key`, or `key` at the root. */
+declare const pathAt: (path: string, key: string) => string;
+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. */
+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;
+}
+declare class PathIssueCollector<C extends string> {
+    private readonly subject;
+    private readonly codes;
+    readonly issues: PathIssue<C>[];
+    /** `subject` names the document in a refusal ("… is not part of the plan shape"). */
+    constructor(subject: string, codes: ShapeIssueCodes<C>);
+    add(code: C, path: string, message: string): void;
+    keys(obj: PlainObject, allowed: ReadonlyArray<string>, path: string): void;
+    string(obj: PlainObject, key: string, path: string, required?: boolean): string | null;
+    boolean(obj: PlainObject, key: string, path: string): void;
+    array(obj: PlainObject, key: string, path: string): unknown[];
+    unique(values: Array<string | null>, path: (i: number) => string, what: string): void;
+}
+
 /**
  * The Site Plan validator — the gate in front of the composer. The wizard's plan and (later) the AI's
  * plan go through the SAME checks: an unknown pattern, a slot the pattern does not declare, a source
@@ -2225,12 +2366,7 @@ declare enum SitePlanIssueCode {
      *  its alt text. */
     MissingPreviewField = "missing-preview-field"
 }
-interface SitePlanIssue {
-    code: SitePlanIssueCode;
-    /** Where, as a dotted path into the plan (`pages[2].sections[0].binding`). */
-    path: string;
-    message: string;
-}
+type SitePlanIssue = PathIssue<SitePlanIssueCode>;
 interface SitePlanValidation {
     valid: boolean;
     issues: SitePlanIssue[];
@@ -2239,14 +2375,6 @@ declare class SitePlanError extends Error {
     readonly issues: ReadonlyArray<SitePlanIssue>;
     constructor(issues: ReadonlyArray<SitePlanIssue>);
 }
-/** 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. */
@@ -2581,5 +2709,111 @@ declare function removeBarItem(globals: ReadonlyArray<SerializedNode>, itemId: s
 /** The bar's Items list drag-to-reorder (board 2): item `from` moves to `to`. Input not mutated. */
 declare function moveBarItem(globals: ReadonlyArray<SerializedNode>, from: number, to: number): BarItemsEditResult;
 
-export { BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BaselineRole, BindScope, CardBindTarget, ComposeError, ComposeIssueCode, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, FACT_KEYS, GlobalSlot, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NavPagesSource, NavRole, NavShape, NavShapeError, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, 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, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, composeNavHeader, composeSection, composeSite, createSerializedNode, findNavRoot, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, setStyleProps, shapeKeys, siteNavPages, validateSitePlan, walkSerialized };
-export type { AddBarItemResult, BarItemsEditResult, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, DataSourcePlan, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PagePlan, PageSectionPlan, PatternNode, RelativeDataSourcePlan, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };
+/**
+ * How animated (AI plan rev 3.1 §3p) — the ONE reading of the contract's `axes.animations` (what each level
+ * moves, how) and `axes.animationFamilies` (which parts a section family lets move). The pieces every stamper
+ * shares: the Design step's business specimen (H4-4) today, `planEntrances` in the composer (M1-6b) next. Pure.
+ *
+ * A level with `content` moves a section's content together, once; otherwise it names parts (heading, items,
+ * media…) and each part enters on its own, items one after another. Navigation, footers and globals are a family
+ * with no parts, so nothing there ever moves.
+ */
+declare enum EntrancePart {
+    Content = "content",
+    Heading = "heading",
+    Items = "items",
+    Media = "media",
+    RowMedia = "rowMedia",
+    HeroText = "heroText"
+}
+/** What an entrance stamp is marked with — a later restamp touches only what the look made (H4-5). */
+declare const ENTRANCE_ORIGIN_LOOK = "look";
+/** The trigger every entrance plays on. */
+declare const ENTRANCE_TRIGGER = "viewportEnter";
+/** The easing every entrance plays with (only `opacity` and `transform` move). */
+declare const ENTRANCE_EASING = "ease-out";
+/** One entrance as the contract states it. */
+interface EntranceSpec {
+    readonly type: string;
+    readonly duration: number;
+    readonly distance?: number;
+    /** Items: ms added per item, up to `cap` items. */
+    readonly stagger?: number;
+    readonly cap?: number;
+    /** The type a right-to-left page plays instead (a side-by-side row slides in from ITS side). */
+    readonly mirror?: string;
+}
+/** What one section family moves at one level. `content` set = the whole content together, and no parts. */
+interface SectionEntrances {
+    readonly content: EntranceSpec | null;
+    readonly parts: Readonly<Partial<Record<EntrancePart, EntranceSpec>>>;
+}
+/** The interaction action a stamp carries — the shape both interaction runtimes play. */
+interface EntranceAction {
+    type: string;
+    target: 'self';
+    duration: number;
+    delay: number;
+    easing: typeof ENTRANCE_EASING;
+    once: true;
+    params?: {
+        distance: number;
+    };
+}
+interface EntranceInteraction {
+    id: string;
+    trigger: typeof ENTRANCE_TRIGGER;
+    actions: [EntranceAction];
+    origin: typeof ENTRANCE_ORIGIN_LOOK;
+}
+/** What a section of `family` moves at `level` — nothing for an unknown level or family. */
+declare function sectionEntrances(level: AnimateId | string | null | undefined, family: string): SectionEntrances;
+/** The literal delay of the `index`-th item: `stagger` ms each, the last `cap` waiting no longer than the one before. */
+declare function staggerDelay(spec: EntranceSpec, index?: number): number;
+/** The action a node plays: the spec's type (mirrored on a right-to-left page), its distance and its delay. */
+declare function entranceAction(spec: EntranceSpec, opts?: {
+    index?: number;
+    rtl?: boolean;
+}): EntranceAction;
+/** The stamp on a node: `viewportEnter`, once, on itself (a duplicated node needs no remap), from the look. */
+declare function entranceInteraction(nodeId: string, action: EntranceAction): EntranceInteraction;
+
+/**
+ * What each page of a plan shows and where its data comes from (AI plan rev 3 §3d, `describePlanData`) — the
+ * Plan step's data lines, in the vocabulary the builder already uses. Pure and STRUCTURED: the screen words
+ * each kind in its own language ("Lists every Project", "One Project, found by its address /work/:slug").
+ */
+declare enum PageDataKind {
+    /** A section repeats every item of a content type. */
+    List = "list",
+    /** A section repeats the newest `count` items. */
+    Latest = "latest",
+    /** A template page: one item, found by its address — one page per item. */
+    One = "one",
+    /** The next (or previous) item beside the page's own. */
+    Siblings = "siblings",
+    /** A form: what it sends, to the studio's inbox (+ an email when Email is connected). */
+    Form = "form",
+    /** Words and pictures, no data. */
+    Static = "static"
+}
+interface PageDataLine {
+    kind: PageDataKind;
+    /** The content type's label ("Projects"), for every kind that reads one. */
+    contentType?: string;
+    /** Latest: how many. */
+    count?: number;
+    /** One: the page's own address, with its parameter. */
+    route?: string;
+    /** Form: the form preset (`contact`). */
+    form?: string;
+}
+interface PageData {
+    pageKey: string;
+    lines: PageDataLine[];
+}
+/** One entry per page of the plan, in plan order. */
+declare function describePlanData(plan: SitePlan): PageData[];
+
+export { BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BaselineRole, BindScope, CardBindTarget, ComposeError, ComposeIssueCode, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, GlobalSlot, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NavPagesSource, NavRole, NavShape, NavShapeError, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, composeNavHeader, composeSection, composeSite, createSerializedNode, describePlanData, entranceAction, entranceInteraction, findNavRoot, isNonEmptyString, isPlainObject, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, pathAt, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, sectionEntrances, setStyleProps, shapeKeys, siteNavPages, staggerDelay, validateSitePlan, walkSerialized };
+export type { AddBarItemResult, BarItemsEditResult, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, DataSourcePlan, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };