@vectoriox/iox-ui 4.4.4 → 4.5.0

package/package.json

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

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

@@ -812,5 +812,107 @@ interface DataSourceRequest {
  */
 declare function dataSourcePlanToRequest(plan: DataSourcePlan, endpoints: DataSourceEndpoints): DataSourceRequest | null;
 
-export { AOSService, AnalyticsService, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CardComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, DEFAULT_WIDTH_BY_TYPE, ENVIRONMENT, IOX_BUILDER_EVENTS, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxPageComponent, IoxPageModule, IoxUiModule, LinkedContainerComponent, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, SectionComponent, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, buildDataSourceFilter, compileDeclarations, composeVirtualTraits, dataSourcePlanToRequest, matchRouteParams, normalizeCollectionResult, planDataSource, renderDefaultDeclarations, resolveSingleItemId, rewriteViewportUnits, styleKeyToKebab };
-export type { DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, IBuilderEventEmitter };
+/**
+ * Cinematic page-transition presets — the SINGLE SOURCE OF TRUTH shared by the page builder
+ * (preview) and the SSR client engine (production). Pure, transport-agnostic: this module only
+ * describes WAAPI keyframe pairs + timing/ordering. It never touches the DOM.
+ *
+ * A page transition plays TWO synchronized WAAPI animations at once — an `out` animation on a
+ * snapshot of the outgoing page and an `in` animation on the incoming page — inside a shared
+ * `perspective` container, gated on BOTH finishing (the "cinematic" feel, à la Codrops
+ * PageTransitions). The consumer supplies the DOM (snapshot layer + live page) and calls
+ * `element.animate(frames, options)`; it does NOT redefine the frames.
+ *
+ * @see architecture/builder/page-transitions.md
+ */
+/** Perspective (px) applied to the transition container unless a preset overrides it. */
+declare const DEFAULT_PAGE_TRANSITION_PERSPECTIVE = 1200;
+/** Default transition duration (ms) when the page does not specify one. */
+declare const DEFAULT_PAGE_TRANSITION_DURATION = 600;
+type PageTransitionCategory = 'move' | 'fade' | 'scale' | 'rotate';
+interface PageTransitionPreset {
+    category: PageTransitionCategory;
+    label: string;
+    /** Keyframes for the OUTGOING page (played on a fixed snapshot). */
+    outKeyframes: Keyframe[];
+    /** Keyframes for the INCOMING page. */
+    inKeyframes: Keyframe[];
+    /** Which layer is stacked on top during the transition. Default: 'in'. */
+    ontop?: 'in' | 'out';
+    /** `transform-origin` for the outgoing layer (3D hinge effects). */
+    outTransformOrigin?: string;
+    /** `transform-origin` for the incoming layer. */
+    inTransformOrigin?: string;
+    /** Override the container perspective (px) for this preset. */
+    perspective?: number;
+    /** Delay before the OUT animation starts, as a fraction (0..1) of the duration. */
+    outDelayRatio?: number;
+    /** Delay before the IN animation starts, as a fraction (0..1) of the duration. */
+    inDelayRatio?: number;
+}
+declare const PAGE_TRANSITION_PRESETS: Record<string, PageTransitionPreset>;
+interface PageTransitionCategoryMeta {
+    value: PageTransitionCategory;
+    label: string;
+    presets: {
+        value: string;
+        label: string;
+    }[];
+}
+/** Built from PAGE_TRANSITION_PRESETS so the two lists can never drift apart. */
+declare const PAGE_TRANSITION_CATEGORIES: PageTransitionCategoryMeta[];
+interface PageTransitionOptions {
+    /** Total transition duration (ms). */
+    duration?: number;
+    easing?: string;
+    /** Container perspective (px); a preset-specific perspective still wins. */
+    perspective?: number;
+}
+interface ResolvedPageTransition {
+    outFrames: Keyframe[];
+    inFrames: Keyframe[];
+    outOptions: KeyframeAnimationOptions;
+    inOptions: KeyframeAnimationOptions;
+    ontop: 'in' | 'out';
+    perspective: number;
+    outTransformOrigin?: string;
+    inTransformOrigin?: string;
+}
+/**
+ * Resolve a persisted preset id + timing into the two WAAPI animations the consumer runs.
+ * Returns `null` for unknown / 'none' presets (caller should skip the transition).
+ */
+declare function resolvePageTransition(name: string | null | undefined, opts?: PageTransitionOptions): ResolvedPageTransition | null;
+type TransitionPhase = 'leave' | 'transition' | 'enter';
+interface TransitionTimelineInput {
+    /** At least one element on the outgoing page has a `pageLeave` interaction. */
+    hasLeave: boolean;
+    /** A page transition preset is configured (and not 'none'). */
+    hasTransition: boolean;
+    /** At least one element on the incoming page has a `pageEnter` interaction. */
+    hasEnter: boolean;
+}
+/**
+ * The ordered phases a navigation runs, given what is present. The order is INVARIANT:
+ * every element `leave` animation finishes before the page `transition` starts, and the page
+ * `transition` finishes before any element `enter` animation begins. Phases with nothing to
+ * play are omitted. The engine iterates this list and `await`s each phase's completion.
+ */
+declare function buildTransitionTimeline(input: TransitionTimelineInput): TransitionPhase[];
+/**
+ * Map a legacy `enter` preset (none/fade/slideUp/slideDown/zoomIn/zoomOut/blurIn/flip) to the
+ * nearest cinematic paired `transition` id, so pages saved before this system keep animating.
+ * Returns 'fade' for anything unmapped, and 'none' for 'none'.
+ */
+declare function legacyEnterToTransition(enter: string | null | undefined): string;
+/**
+ * Resolve the effective transition id for a page's route-animation settings: the explicit
+ * `transition` when present, otherwise migrated from the legacy `enter` preset.
+ */
+declare function effectiveTransitionId(anim: {
+    transition?: string | null;
+    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_DURATION, 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, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, SectionComponent, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, buildDataSourceFilter, buildTransitionTimeline, compileDeclarations, composeVirtualTraits, dataSourcePlanToRequest, effectiveTransitionId, legacyEnterToTransition, matchRouteParams, normalizeCollectionResult, planDataSource, renderDefaultDeclarations, resolvePageTransition, resolveSingleItemId, rewriteViewportUnits, styleKeyToKebab };
+export type { DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, IBuilderEventEmitter, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, ResolvedPageTransition, TransitionPhase, TransitionTimelineInput };