@vectoriox/iox-ui 4.11.0 → 4.13.0

package/package.json

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

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

@@ -873,6 +873,148 @@ interface DataSourceRequest {
  */
 declare function dataSourcePlanToRequest(plan: DataSourcePlan, endpoints: DataSourceEndpoints): DataSourceRequest | null;
 
+/**
+ * Shared RELATIVE (route-context) data resolving — the SINGLE source of truth for how a detail page
+ * derives values FROM its current route item, consumed by BOTH the page builder (iox-cms-client) and
+ * the SSR client engine (iox-client-engine). Companion to `data-source-resolver.ts`.
+ *
+ * These are the pure, transport-agnostic pieces behind the Route binding scope
+ * (`$route` / `$current` / `$siblings` / `$related`). Resolution is a DEPENDENT SECOND PASS: the
+ * consumer resolves `$current` first (the existing single by-id fetch via `planDataSource`), then
+ * calls these to derive the relative values — there is NO new `DataSourcePlan` kind (`$related` still
+ * feeds a normal `collection` plan built from {@link buildRelatedFilter}). See
+ * `architecture/builder/relative-data-sources-plan.md`.
+ *
+ * There must be no second copy of this decision logic; only the transport (which HTTP layer fetches
+ * the ordered collection / related list) differs between the two consumers.
+ */
+/** Aliases in the Route scope are platform-owned and start with this prefix; a USER alias may never
+ *  start with it, which keeps the Route scope structurally collision-proof with Local/Global. Used to
+ *  validate new/renamed aliases and to render the reserved (read-only) item state in the bind picker. */
+declare const RESERVED_ALIAS_PREFIX = "$";
+/** True for a platform-owned Route-scope alias (`$route`, `$current`, `$siblings`, `$related`, …). */
+declare function isReservedAlias(alias: string | null | undefined): boolean;
+/** The `$siblings` value: the current item's neighbours within an ordered set. */
+interface SiblingsResult<T = any> {
+    /** The item before the current one (`null` at the start, unless `wrap`). */
+    prev: T | null;
+    /** The item after the current one (`null` at the end, unless `wrap`). */
+    next: T | null;
+    /** Zero-based position of the current item in the ordered set; `-1` when not found. */
+    index: number;
+    /** Total items in the set. */
+    count: number;
+    /** `true` when the current item is the first in the set. */
+    isFirst: boolean;
+    /** `true` when the current item is the last in the set. */
+    isLast: boolean;
+}
+interface ResolveSiblingsOptions {
+    /** Field identifying the current item within the list. Default `_id`. */
+    idField?: string;
+    /** Dot/bracket path to sort by BEFORE locating neighbours (e.g. `order`, `date`). Omit to use the
+     *  list's existing order. The same item neighbours differently per ordering, so this is the one
+     *  choice `$siblings` requires. */
+    sortBy?: string;
+    /** Sort direction when `sortBy` is set. Default `asc`. */
+    sortDir?: 'asc' | 'desc';
+    /** Wrap around the ends (`last.next` → first, `first.prev` → last). Only applies when `count > 1`.
+     *  Default `false`. */
+    wrap?: boolean;
+}
+/**
+ * Locate the current item within an ordered set and return its neighbours + position. Pure: the input
+ * list is never mutated (sorting works on a shallow copy). `currentId` is compared to each item's
+ * `idField` via string equality (route-param values are strings). When the current id isn't found,
+ * `index` is `-1` and `prev`/`next` are `null` (but `count` still reflects the set size).
+ */
+declare function resolveSiblings<T = any>(items: T[] | null | undefined, currentId: string | number | null | undefined, options?: ResolveSiblingsOptions): SiblingsResult<T>;
+interface BuildRelatedFilterOptions {
+    /** Field(s) on the current item whose value(s) the related items must match (e.g. `category`,
+     *  or `['category', 'brand']`). Each contributes an equality filter on that field. */
+    matchFields: string | string[];
+}
+/**
+ * Build the collection filter for `$related` from the resolved current item: an equality match on
+ * each `matchField`'s value (e.g. same `category`). Feeds a normal `collection` plan — no new plan
+ * kind. Fields whose value is not a scalar (or is empty) are omitted, matching
+ * `buildDataSourceFilter`'s "don't over-filter" rule. Exclude-self is applied to the RESULT via
+ * {@link excludeSelf} (the public query controllers are equality-only, so it can't be a `$ne` param).
+ */
+declare function buildRelatedFilter(current: any, options: BuildRelatedFilterOptions): Record<string, any>;
+/**
+ * Drop the current item from a list by `idField` (default `_id`). Used to exclude self from a
+ * `$related` result after fetch. A nullish/empty `currentId` leaves the list unchanged.
+ */
+declare function excludeSelf<T = any>(items: T[] | null | undefined, currentId: string | number | null | undefined, idField?: string): T[];
+/** The resolved Route-scope context bound values read from (`$route.projectId`, `$current.title`,
+ *  `$siblings.next`, `$related`). Assembled by each consumer during its dependent second pass. */
+interface RouteContext {
+    /** Route path params for the current URL (from `matchRouteParams`). */
+    $route: Record<string, string>;
+    /** The resolved current item (the page's single by-id source). */
+    $current: any;
+    /** Neighbours of the current item within a chosen ordered set. */
+    $siblings?: SiblingsResult;
+    /** Items related to the current one (same-attribute), excluding self. */
+    $related?: any[];
+}
+type RelativeSourceKind = 'route' | 'current' | 'siblings' | 'related';
+interface RelativeSourceSpec {
+    kind: RelativeSourceKind;
+    /** The source alias this derives from: for `current` the subject single-source; for
+     *  `siblings`/`related` the COLLECTION alias to locate within / search. Unused for `route`. */
+    from?: string;
+    /** `siblings`/`related`: the SUBJECT source alias (the current item) whose id / field values drive
+     *  the computation. Defaults to `from` when omitted. May reference `$current`. */
+    subjectFrom?: string;
+    /** Field identifying an item. Default `_id`. */
+    idField?: string;
+    /** `siblings`: sort the set before locating neighbours. */
+    sortBy?: string;
+    sortDir?: 'asc' | 'desc';
+    wrap?: boolean;
+    /** `related`: field(s) on the subject the results must match. */
+    matchFields?: string | string[];
+    /** `related`: drop the subject from its own results. Default `true`. */
+    excludeSelf?: boolean;
+}
+/** Duck-typed view of a data source carrying an optional relative descriptor (avoids a hard dep on
+ *  the full editor model / a circular type import). */
+interface RelativeCapableSource {
+    alias?: string;
+    type?: string;
+    request?: {
+        relative?: RelativeSourceSpec;
+    };
+}
+/** The already-resolved inputs a single relative source computes from. Assembled by each consumer:
+ *  the batch pass reads them from the resolved map; the builder resolves them async per alias. */
+interface RelativeInputs {
+    /** The subject item (the current resource) — for `current`/`siblings`/`related`. */
+    subject?: any;
+    /** The collection to locate within / search — for `siblings`/`related`. */
+    collection?: any;
+    /** Route path params — for `route`. */
+    routeParams?: Record<string, any>;
+}
+/**
+ * Compute ONE relative source's value from its already-resolved {@link RelativeInputs} — the SHARED
+ * kind→computation decision, so the batch pass ({@link resolveRelativeInto}) and the builder's async
+ * per-alias resolver produce identical results with no forked switch. `route` → the route params;
+ * `current` → the subject; `siblings` → {@link resolveSiblings} over the collection; `related` → the
+ * collection filtered by {@link buildRelatedFilter}'s predicate (+ {@link excludeSelf}).
+ */
+declare function computeRelative(spec: RelativeSourceSpec, inputs: RelativeInputs): any;
+/**
+ * Compute every `type:'relative'` source into `resolved` (keyed by alias), IN PLACE. Pure w.r.t. HTTP
+ * — it only reads already-resolved roots + the route params, so both consumers run it identically as
+ * a second pass. Delegates each source to {@link computeRelative}. `current`'s subject is `from`;
+ * `siblings`/`related` take `collection` = `from` and `subject` = `subjectFrom ?? from`. Mutates and
+ * returns `resolved`.
+ */
+declare function resolveRelativeInto(dataSources: RelativeCapableSource[], resolved: Record<string, any>, routeParams?: Record<string, any>): Record<string, any>;
+
 /**
  * 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
@@ -1020,5 +1162,5 @@ 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, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, SUPPRESSED_STYLE_PROPS_BY_TYPE, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, applyFeel, buildDataSourceFilter, buildTransitionTimeline, collectReferencedAliases, compileDeclarations, composeVirtualTraits, dataSourcePlanToRequest, effectiveTransitionId, feelFor, getByPath, legacyEnterToTransition, matchRouteParams, normalizeCollectionResult, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolvePageTransition, resolveRepeaterItems, resolveSingleItemId, rewriteViewportUnits, stripSuppressedProps, styleKeyToKebab };
-export type { DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, IBuilderEventEmitter, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, ResolvedPageTransition, TransitionFeel, TransitionPhase, TransitionTimelineInput };
+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, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, 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, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, RouteContext, SiblingsResult, TransitionFeel, TransitionPhase, TransitionTimelineInput };