@vectoriox/iox-ui 4.11.0 → 4.12.0

package/fesm2022/vectoriox-iox-ui.mjs

@@ -2476,6 +2476,169 @@ function dataSourcePlanToRequest(plan, endpoints) {
     }
 }
 
+/**
+ * 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. */
+const RESERVED_ALIAS_PREFIX = '$';
+/** True for a platform-owned Route-scope alias (`$route`, `$current`, `$siblings`, `$related`, …). */
+function isReservedAlias(alias) {
+    return typeof alias === 'string' && alias.startsWith(RESERVED_ALIAS_PREFIX);
+}
+const EMPTY_SIBLINGS = { prev: null, next: null, index: -1, count: 0, isFirst: false, isLast: false };
+/** Generic, deterministic comparator: numbers numerically, Dates by time, everything else by
+ *  locale-aware string compare (ISO date strings sort correctly this way). Nullish sorts first. */
+function compareValues(a, b) {
+    if (a == null && b == null)
+        return 0;
+    if (a == null)
+        return -1;
+    if (b == null)
+        return 1;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    const da = a instanceof Date ? a.getTime() : NaN;
+    const db = b instanceof Date ? b.getTime() : NaN;
+    if (!isNaN(da) && !isNaN(db))
+        return da - db;
+    return String(a).localeCompare(String(b));
+}
+/**
+ * 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).
+ */
+function resolveSiblings(items, currentId, options = {}) {
+    const list = Array.isArray(items) ? items.slice() : [];
+    const count = list.length;
+    if (count === 0)
+        return { ...EMPTY_SIBLINGS };
+    const idField = options.idField ?? '_id';
+    if (options.sortBy) {
+        const dir = options.sortDir === 'desc' ? -1 : 1;
+        list.sort((a, b) => dir * compareValues(getByPath(a, options.sortBy), getByPath(b, options.sortBy)));
+    }
+    const cid = currentId == null ? null : String(currentId);
+    const index = cid == null ? -1 : list.findIndex(it => String(getByPath(it, idField)) === cid);
+    if (index === -1)
+        return { prev: null, next: null, index: -1, count, isFirst: false, isLast: false };
+    const canWrap = !!options.wrap && count > 1;
+    const prev = index > 0 ? list[index - 1] : (canWrap ? list[count - 1] : null);
+    const next = index < count - 1 ? list[index + 1] : (canWrap ? list[0] : null);
+    return { prev, next, index, count, isFirst: index === 0, isLast: index === count - 1 };
+}
+/** A value usable as an equality filter param: a non-empty scalar. Objects/arrays/nullish are skipped
+ *  so a related query isn't built from an unresolved rel object (surfaced as a config issue in the UI
+ *  rather than silently matching everything). Multi-value match is a v2 concern. */
+function isScalarFilterValue(v) {
+    if (v == null)
+        return false;
+    if (typeof v === 'string')
+        return v !== '';
+    if (typeof v === 'number')
+        return Number.isFinite(v);
+    return typeof v === 'boolean';
+}
+/**
+ * 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).
+ */
+function buildRelatedFilter(current, options) {
+    const fields = Array.isArray(options.matchFields) ? options.matchFields : [options.matchFields];
+    const filter = {};
+    for (const field of fields) {
+        if (!field)
+            continue;
+        const value = getByPath(current, field);
+        if (isScalarFilterValue(value))
+            filter[field] = value;
+    }
+    return filter;
+}
+/**
+ * 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.
+ */
+function excludeSelf(items, currentId, idField = '_id') {
+    if (!Array.isArray(items))
+        return [];
+    if (currentId == null || currentId === '')
+        return items;
+    const cid = String(currentId);
+    return items.filter(it => String(getByPath(it, idField)) !== cid);
+}
+/** Resolve kinds in a fixed order so a `siblings`/`related` source may reference `$current` (or any
+ *  earlier relative alias) via `subjectFrom` and still see it resolved. */
+const KIND_ORDER = { route: 0, current: 1, siblings: 2, related: 3 };
+/** Does an item satisfy every field in an equality predicate map (string-compared)? */
+function matchesFilter(item, filter) {
+    return Object.keys(filter).every(k => String(getByPath(item, k)) === String(filter[k]));
+}
+/**
+ * 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. `route` → the route params; `current` → the subject source value; `siblings` →
+ * {@link resolveSiblings} over the collection; `related` → the collection filtered client-side by
+ * {@link buildRelatedFilter}'s predicate (+ {@link excludeSelf}). Mutates and returns `resolved`.
+ */
+function resolveRelativeInto(dataSources, resolved, routeParams = {}) {
+    const relatives = (dataSources ?? [])
+        .filter(d => d?.type === 'relative' && !!d.alias && !!d.request?.relative)
+        .sort((a, b) => KIND_ORDER[a.request.relative.kind] - KIND_ORDER[b.request.relative.kind]);
+    for (const d of relatives) {
+        const alias = d.alias;
+        const spec = d.request.relative;
+        const idField = spec.idField ?? '_id';
+        switch (spec.kind) {
+            case 'route':
+                resolved[alias] = routeParams;
+                break;
+            case 'current':
+                resolved[alias] = spec.from ? (resolved[spec.from] ?? null) : null;
+                break;
+            case 'siblings': {
+                const collection = resolved[spec.from ?? ''];
+                const subject = resolved[spec.subjectFrom ?? spec.from ?? ''];
+                const currentId = getByPath(subject, idField);
+                resolved[alias] = resolveSiblings(collection, currentId, {
+                    idField, sortBy: spec.sortBy, sortDir: spec.sortDir, wrap: spec.wrap,
+                });
+                break;
+            }
+            case 'related': {
+                const collection = resolved[spec.from ?? ''];
+                const subject = resolved[spec.subjectFrom ?? spec.from ?? ''];
+                const filter = buildRelatedFilter(subject, { matchFields: spec.matchFields ?? [] });
+                const pool = Array.isArray(collection) ? collection : [];
+                let items = pool.filter(it => matchesFilter(it, filter));
+                if (spec.excludeSelf !== false)
+                    items = excludeSelf(items, getByPath(subject, idField), idField);
+                resolved[alias] = items;
+                break;
+            }
+        }
+    }
+    return resolved;
+}
+
 /**
  * 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
@@ -2910,5 +3073,5 @@ function effectiveTransitionId(anim) {
  * Generated bundle index. Do not edit.
  */
 
-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 { 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, dataSourcePlanToRequest, effectiveTransitionId, excludeSelf, feelFor, getByPath, isReservedAlias, legacyEnterToTransition, matchRouteParams, normalizeCollectionResult, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolvePageTransition, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, stripSuppressedProps, styleKeyToKebab };
 //# sourceMappingURL=vectoriox-iox-ui.mjs.map