@vectoriox/iox-ui 4.15.0 → 4.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.15.0",
+  "version": "4.16.1",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/types/vectoriox-iox-ui.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { AfterViewInit, EventEmitter, ElementRef, SimpleChanges, OnDestroy, OnInit, Renderer2, ModuleWithProviders, InjectionToken, ChangeDetectorRef, ViewContainerRef, Type } from '@angular/core';
+import { AfterViewInit, EventEmitter, ElementRef, SimpleChanges, OnDestroy, OnInit, Renderer2, ModuleWithProviders, InjectionToken, ChangeDetectorRef, ViewContainerRef, OnChanges, Type } from '@angular/core';
 import { AnimationPlayer, AnimationBuilder } from '@angular/animations';
 import { Observable, Subject } from 'rxjs';
 import * as i3 from '@angular/platform-browser/animations';
@@ -590,9 +590,84 @@ declare class ClientListItemComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<ClientListItemComponent, "li[iox-list-item]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
 }
 
+/** One manual gallery entry. Exactly one of `url` / `binding` is the source; `binding` wins when set. */
+interface GalleryImage {
+    /** Manual URL or filebox-picked media URL. Ignored when `binding` is set. */
+    url?: string;
+    /** Per-item binding path, resolved against the render context (e.g. `product.hero.url`). */
+    binding?: string;
+    /** Optional alt text. */
+    alt?: string;
+}
+/** Bound-mode input: the resolved records + which field of each record holds the image URL. */
+interface GalleryBoundSource {
+    items: any[];
+    /** Path into each record for the URL. Empty/undefined → the record itself is treated as the URL. */
+    imageField?: string;
+}
+/**
+ * Resolve a gallery's configured images to the flat, display-ready `string[]` the loop renders.
+ * Pure. Empty/whitespace URLs are dropped so a half-filled manual list never yields blank frames.
+ *
+ * @param images  manual `GalleryImage[]` (manual mode). Ignored when `bound` is provided.
+ * @param bound   bound-mode records + image field. When present, takes precedence over `images`.
+ * @param ctx     render context for per-item bindings (item/route data). Defaults to `{}`.
+ */
+declare function resolveGalleryUrls(images: GalleryImage[] | undefined, bound: GalleryBoundSource | null | undefined, ctx?: Record<string, any>): string[];
+/**
+ * Parse a pasted block of URLs (newline- and/or comma-separated) into `GalleryImage[]`. Used by the
+ * MediaList trait editor's "paste URL list" affordance. Pure so it can be unit-tested + reused.
+ */
+declare function parseUrlList(text: string): GalleryImage[];
+
+/**
+ * `iox-gallery` — the engine/runtime twin of the Gallery builder component (the builder twin
+ * `app-builder-gallery` arrives in Phase 2). It runs the SHARED crossfade loop + effect registry from
+ * `@vectoriox/iox-ui`, so the fade behaves identically on the canvas and the live site — no forked
+ * animation logic. See iox-ai-guidance/architecture/builder/gallery-component-plan.md.
+ *
+ * Population: v1 drives the loop from the `images` input (manual mode). Data-source binding
+ * (`source`/`sourcePath`) is Phase 3 — this component already resolves through `resolveGalleryUrls`,
+ * so that only adds a bound-source input, not new render logic.
+ *
+ * SSR / no-JS: on the server the loop never starts, so the **first image renders visible** as a static
+ * frame (SEO + no-JS baseline). In the browser `ngAfterViewInit` starts the loop, which begins on the
+ * same index 0 — so the static frame and the first live frame match and there is no hydration flash.
+ */
+declare class ClientGalleryComponent implements AfterViewInit, OnChanges, OnDestroy {
+    private cdr;
+    nodeId: string;
+    /** Manual images — `GalleryImage[]` or a plain `string[]` of URLs (normalised on set). */
+    images: (GalleryImage | string)[];
+    effect: string;
+    showDuration: number;
+    fadeDuration: number;
+    autoStart: boolean;
+    /** Layout mode — only `'stack'` is rendered in v1 (`'grid'` scaffolded for later). */
+    layout: 'stack' | 'grid';
+    /** The flat, display-ready URLs the loop cycles. Recomputed when `images` changes. */
+    urls: string[];
+    private currentIndex;
+    private fadingOutIndex;
+    private started;
+    private loop;
+    private readonly isBrowser;
+    constructor(platformId: object, cdr: ChangeDetectorRef);
+    ngOnChanges(changes: SimpleChanges): void;
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /** Per-slide inline style. Before the loop activates (server + no-JS + pre-first-frame) the first
+     *  image is the visible static frame; once running, the effect owns each slide's look. */
+    slideStyle(i: number): Record<string, string>;
+    private startLoop;
+    private normalizeImages;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ClientGalleryComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ClientGalleryComponent, "iox-gallery", never, { "nodeId": { "alias": "nodeId"; "required": false; }; "images": { "alias": "images"; "required": false; }; "effect": { "alias": "effect"; "required": false; }; "showDuration": { "alias": "showDuration"; "required": false; }; "fadeDuration": { "alias": "fadeDuration"; "required": false; }; "autoStart": { "alias": "autoStart"; "required": false; }; "layout": { "alias": "layout"; "required": false; }; }, {}, never, never, false, never>;
+}
+
 declare class IoxBuilderComponentsModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<IoxBuilderComponentsModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<IoxBuilderComponentsModule, [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent], [typeof i2.CommonModule], [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<IoxBuilderComponentsModule, [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent, typeof ClientGalleryComponent], [typeof i2.CommonModule], [typeof BuilderImageComponent, typeof BuilderSpacerComponent, typeof CardComponent, typeof BuilderDividerComponent, typeof BuilderIconComponent, typeof BuilderLinkComponent, typeof BuilderButtonComponent, typeof BuilderHeadingComponent, typeof TextBlockComponent, typeof SectionComponent, typeof ContainerComponent, typeof LinkedContainerComponent, typeof ClientRepeaterComponent, typeof ButtonBlockComponent, typeof ClientSliderContainerComponent, typeof ClientSliderSlideComponent, typeof ClientListComponent, typeof ClientListItemComponent, typeof ClientGalleryComponent]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<IoxBuilderComponentsModule>;
 }
 
@@ -1218,5 +1293,121 @@ declare function effectiveTransitionId(anim: {
     enter?: string | null;
 } | null | undefined): string;
 
-export { AOSService, AnalyticsService, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CardComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, ENVIRONMENT, IOX_BUILDER_EVENTS, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxPageComponent, IoxPageModule, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, applyBindingPipes, applyFeel, buildDataSourceFilter, buildRelatedFilter, buildTransitionTimeline, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, dataSourcePlanToRequest, effectiveTransitionId, excludeSelf, feelFor, getByPath, isReservedAlias, legacyEnterToTransition, matchRouteParams, normalizeCollectionResult, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolvePageTransition, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, stripSuppressedProps, styleKeyToKebab };
-export type { BuildRelatedFilterOptions, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, IBuilderEventEmitter, IoxPipe, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, RouteContext, SiblingsResult, TransitionFeel, TransitionPhase, TransitionTimelineInput };
+/**
+ * Gallery effect registry — the SHARED, effect-agnostic description of how each gallery slide looks
+ * and animates in a given crossfade state. Modeled on `binding-pipes.ts` / `PAGE_TRANSITION_PRESETS`:
+ * a descriptor map + a resolve fn, all pure, consumed by BOTH the builder twin and the engine twin so
+ * the fade looks identical on the canvas and the live site.
+ *
+ * v1 ships only `fade` (the look ported from `sites/interior-design` fade-gallery). Adding `slide`,
+ * `zoom`, `kenburns`, … later is a new entry here + its CSS — NO component refactor, because the
+ * component only ever asks `resolveGalleryEffect(id).buildSlideStyle(state)` for per-slide inline CSS.
+ *
+ * See iox-ai-guidance/architecture/builder/gallery-component-plan.md.
+ */
+/** Timing knobs for one running gallery. Overridable per-node via traits; defaults live per effect. */
+interface GalleryDurations {
+    /** ms an image is held fully visible before the next crossfade begins. */
+    showMs: number;
+    /** ms the opacity crossfade takes. */
+    fadeMs: number;
+}
+/** The state of a single slide at render time, from which an effect derives its inline CSS. */
+interface GallerySlideState {
+    /** This slide is the current (incoming/visible) one. */
+    active: boolean;
+    /** This slide is the outgoing one, mid-crossfade. */
+    fadingOut: boolean;
+    /** The loop has completed its first activation RAF (used to suppress the initial transition flash). */
+    firstCycleActive: boolean;
+    durations: GalleryDurations;
+}
+interface GalleryEffect {
+    id: string;
+    /** Default English label; consumers may map `id` to their own i18n key. */
+    label: string;
+    /** Default timing for this effect; a node's traits may override either value. */
+    defaults: GalleryDurations;
+    /** Inline style map for one slide in the given state. Pure — no DOM, no side effects. */
+    buildSlideStyle(state: GallerySlideState): Record<string, string>;
+}
+/** The registry — one entry per effect. Keyed by id; unknown ids fall back to `fade`. */
+declare const GALLERY_EFFECTS: Record<string, GalleryEffect>;
+/** Resolve an effect id to its descriptor, defaulting to `fade` (forward-compatible with new ids). */
+declare function resolveGalleryEffect(id: string | undefined | null): GalleryEffect;
+/** Metadata that DATA-DRIVES the authoring UI's effect dropdown (no per-effect if-chains). */
+interface GalleryEffectDescriptor {
+    id: string;
+    label: string;
+}
+declare const GALLERY_EFFECT_DESCRIPTORS: GalleryEffectDescriptor[];
+
+/**
+ * Gallery crossfade loop — the SHARED, framework-free state machine that drives which image is
+ * visible over time. Ported from the reference fade-gallery's `scheduleCycle` / `tryStartLoop` /
+ * first-cycle-activation logic, with Angular specifics removed so BOTH the builder twin and the
+ * engine/runtime twin (`iox-gallery`) run ONE implementation — never a forked copy that drifts.
+ *
+ * The loop owns only *timing + index* state and emits it through `onChange`; the component maps that
+ * state to CSS via the effect registry (`gallery-effects.ts`). Timers are injected so the loop is
+ * deterministic under fake timers in tests and platform-guardable in the engine.
+ *
+ * See iox-ai-guidance/architecture/builder/gallery-component-plan.md.
+ */
+/** The observable state of a running loop. */
+interface GalleryLoopState {
+    /** Index of the current (incoming/visible) image. */
+    currentIndex: number;
+    /** Index of the outgoing image mid-crossfade, or null when settled. */
+    fadingOutIndex: number | null;
+    /**
+     * True once the loop has completed its initial activation tick. Slides render flat + instant until
+     * this flips, so the first paint doesn't flash a transition (matches the reference gallery).
+     */
+    firstCycleActive: boolean;
+}
+/** Injectable timer surface — real timers in production, fake in tests, no-op RAF on the server. */
+interface GalleryLoopScheduler {
+    setTimer(fn: () => void, ms: number): any;
+    clearTimer(handle: any): void;
+    /** Schedule a callback for "next frame". The engine/tests may implement this as a microtask/timeout. */
+    nextFrame(fn: () => void): any;
+    cancelFrame(handle: any): void;
+}
+/** Default scheduler over the platform's `setTimeout` / `requestAnimationFrame` (with a timer fallback). */
+declare const DEFAULT_GALLERY_SCHEDULER: GalleryLoopScheduler;
+interface GalleryLoopOptions {
+    showMs: number;
+    fadeMs: number;
+    onChange: (state: GalleryLoopState) => void;
+    scheduler?: GalleryLoopScheduler;
+}
+declare class GalleryLoop {
+    private readonly scheduler;
+    private showMs;
+    private fadeMs;
+    private readonly onChange;
+    private count;
+    private currentIndex;
+    private fadingOutIndex;
+    private firstCycleActive;
+    private cycleTimer;
+    private fadeTimer;
+    private frameHandle;
+    /** Bumped on every (re)start so a stale timer callback from a previous run is ignored. */
+    private runToken;
+    private running;
+    constructor(opts: GalleryLoopOptions);
+    get state(): GalleryLoopState;
+    /** Start (or restart) the loop for `count` images. A count < 2 shows the single image without cycling. */
+    start(count: number): void;
+    /** Update timing live. Takes effect on the next scheduled cycle; does not restart the loop. */
+    setDurations(showMs: number, fadeMs: number): void;
+    /** Stop and clear all timers. Idempotent. State is retained (call `start` to reset). */
+    stop(): void;
+    private scheduleCycle;
+    private emit;
+}
+
+export { AOSService, AnalyticsService, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, ENVIRONMENT, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxPageComponent, IoxPageModule, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, applyBindingPipes, applyFeel, buildDataSourceFilter, buildRelatedFilter, buildTransitionTimeline, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, dataSourcePlanToRequest, effectiveTransitionId, excludeSelf, feelFor, getByPath, isReservedAlias, legacyEnterToTransition, matchRouteParams, normalizeCollectionResult, parseUrlList, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolvePageTransition, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, stripSuppressedProps, styleKeyToKebab };
+export type { BuildRelatedFilterOptions, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, IoxPipe, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, RouteContext, SiblingsResult, TransitionFeel, TransitionPhase, TransitionTimelineInput };