@vectoriox/iox-ui 5.42.0 → 5.44.0

package/src/data-core/data-source-resolver.ts

@@ -0,0 +1,378 @@
+/**
+ * Shared data-source resolving pattern — the SINGLE source of truth for how an IoxDataSource
+ * becomes a backend fetch, consumed by BOTH the page builder (iox-cms-client bindings panel) and
+ * the SSR client engine (iox-client-engine DataSourceResolverService). There must be no second
+ * copy of this decision logic; only the transport differs between the two:
+ *
+ *   builder → authenticated org-scoped controllers (admin session):
+ *              single by id → GET admin.../resources/:type/:id   (ContentService.getContentById)
+ *              collection    → GET admin.../resources/:type        (ContentService.getContent)
+ *   engine  → @Public() controllers (no auth, isPublished filter applied server-side):
+ *              single by id → GET api/:type/:id                    (UserResourcesController)
+ *              collection    → GET api/:type?filters                (UserResourcesController)
+ *
+ * The DECISION (by-id vs collection, which id, which filters, how to pick the single result) is
+ * identical for both — that's what this module owns. Each app maps the returned {@link DataSourcePlan}
+ * onto its own transport. A single item is ALWAYS fetched by its id as a path segment — never a
+ * `?_id=` query — to match the builder's getContentById.
+ */
+
+export type DataSourceMode = 'single' | 'list';
+export type DataSourceDomain = 'cms' | 'shop';
+
+export interface DataSourceRouteFilter {
+    field?: string;
+    routeParam?: string;
+    defaultId?: string;
+}
+
+export interface DataSourceQueryFilter {
+    field?: string;
+    /** URL query param the value is read from. OMIT for a CONSTANT filter — then `defaultValue`
+     *  alone is the value, so `isReviewShow=true` filters identically in preview and on the site. */
+    queryParam?: string;
+    /** Value used when the query param is absent — i.e. always, for a constant filter, and in the
+     *  builder preview, where there are no live query params. NOT preview-only: it is the runtime
+     *  fallback too. An empty default with no query-param value means the filter is DROPPED. */
+    defaultValue?: string;
+}
+
+/** The order a query source returns its rows in (CC2, board 4 "Sort" — the data source popover). */
+export enum DataSourceSortDir {
+    Asc = 'asc',
+    Desc = 'desc',
+}
+
+export interface DataSourceSort {
+    /** A field of the content type (a dot path into a nested object is allowed). */
+    field?: string;
+    dir?: DataSourceSortDir | `${DataSourceSortDir}`;
+}
+
+/** The query parameter carrying the order: `sort=order` ascending, `sort=-order` descending. A CONTROL like
+ *  `limit`, not a field filter — the public controllers split it out (iox-cms `query-controls.ts`). */
+export const SORT_PARAM = 'sort';
+const SORT_FIELD = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+/** `sort`'s wire value, or null when the source sets no (valid) order. */
+export function sortParamValue(sort: DataSourceSort | null | undefined): string | null {
+    const field = sort?.field?.trim();
+    if (!field || !SORT_FIELD.test(field)) return null;
+    return sort?.dir === DataSourceSortDir.Desc ? `-${field}` : field;
+}
+
+export interface DataSourceRequestSpec {
+    contentType?: string;
+    limit?: number;
+    /** A query source's order (CC2). Absent = the backend's natural order, as before. */
+    sort?: DataSourceSort;
+    filterByRouteParam?: DataSourceRouteFilter;
+    filterByQueryParams?: DataSourceQueryFilter[];
+}
+
+/** Structural (duck-typed) view of an IoxDataSource — kept free of the editor model so both libs
+ *  can depend on it without pulling in iox-builder. */
+export interface DataSourceSpec {
+    alias?: string;
+    type?: string; // 'cms' | 'shop' | 'external-api' | 'static'
+    mode?: DataSourceMode;
+    request?: {
+        cms?: DataSourceRequestSpec;
+        shop?: DataSourceRequestSpec;
+        endpoint?: string;
+        data?: any;
+        /** `derived` alias: a VIEW into another variable — resolve `from` then getByPath(value, path)
+         *  (e.g. galleryImages = product.gallery). See repeater-binding-ux-plan.md. */
+        derived?: { from: string; path: string };
+    };
+}
+
+export type DataSourcePlan =
+    | { kind: 'by-id'; domain: DataSourceDomain; resource: string; id: string; mode: DataSourceMode }
+    | { kind: 'collection'; domain: DataSourceDomain; resource: string; filter: Record<string, any>; limit?: number; sort?: string; mode: DataSourceMode }
+    | { kind: 'external'; endpoint: string; mode: DataSourceMode }
+    | { kind: 'static'; data: any; mode: DataSourceMode }
+    | { kind: 'derived'; from: string; path: string; mode: DataSourceMode }
+    | { kind: 'none' };
+
+/**
+ * Match a page route template against an actual path and extract named params.
+ *   matchRouteParams('/project/:projectId', 'project/68abc') → { projectId: '68abc' }
+ * Both sides are normalised (leading slash stripped) and split on '/'; values are URL-decoded.
+ */
+export function matchRouteParams(template: string | undefined, actual: string | undefined): Record<string, string> {
+    const t = (template ?? '').replace(/^\/+/, '').split('/');
+    const a = (actual ?? '').replace(/^\/+/, '').split('/');
+    const params: Record<string, string> = {};
+    for (let i = 0; i < t.length; i++) {
+        const seg = t[i];
+        if (seg && seg.startsWith(':')) params[seg.slice(1)] = decodeURIComponent(a[i] ?? '');
+    }
+    return params;
+}
+
+/**
+ * Build the query filter for a data-source request from its filterByRouteParam / filterByQueryParams
+ * config. `field` is filtered by the route-param value (falling back to `defaultId`); query filters
+ * map each `field` to a query-param value (falling back to `defaultValue`), and a filter with NO
+ * `queryParam` is a constant on `defaultValue`. Empty values are omitted so the source isn't
+ * accidentally filtered to nothing.
+ */
+export function buildDataSourceFilter(
+    req: DataSourceRequestSpec | undefined,
+    routeParams: Record<string, any> = {},
+    queryParams: Record<string, any> = {},
+): Record<string, any> {
+    const params: Record<string, any> = {};
+    const byRoute = req?.filterByRouteParam;
+    if (byRoute?.field && byRoute?.routeParam) {
+        const value = routeParams[byRoute.routeParam] ?? byRoute.defaultId;
+        if (value !== undefined && value !== null && value !== '') params[byRoute.field] = value;
+    }
+    for (const q of req?.filterByQueryParams ?? []) {
+        if (!q?.field) continue;
+        // No queryParam → a CONSTANT filter: defaultValue is the value, in the builder preview and
+        // on the live site alike. With a queryParam the URL wins and defaultValue is the fallback.
+        const value = q.queryParam ? (queryParams[q.queryParam] ?? q.defaultValue) : q.defaultValue;
+        if (value !== undefined && value !== null && value !== '') params[q.field] = value;
+    }
+    return params;
+}
+
+/**
+ * Mirrors the builder's getContentById decision. When a SINGLE source is filtered by the item id
+ * (`_id`) via a route param, the item is fetched by PATH (`.../:type/:id`), not a `?_id=` query.
+ * Returns that id (route-param value, else `defaultId`), or `null` when the source isn't a
+ * single-by-id fetch — in which case the caller uses the collection endpoint + filters. The
+ * path-based form only applies to the id field; a single source filtered by any other field still
+ * goes through the collection endpoint.
+ */
+export function resolveSingleItemId(req: DataSourceRequestSpec | undefined, routeParams: Record<string, any> = {}): string | null {
+    const byRoute = req?.filterByRouteParam;
+    if (!byRoute?.routeParam) return null;
+    if (byRoute.field && byRoute.field !== '_id') return null;
+    const value = routeParams[byRoute.routeParam] ?? byRoute.defaultId;
+    return value !== undefined && value !== null && value !== '' ? String(value) : null;
+}
+
+/**
+ * Resolve an IoxDataSource into a transport-agnostic {@link DataSourcePlan}. This is the shared
+ * decision both the builder and the SSR engine run; each then executes the plan with its own
+ * HTTP layer. Single sources with a route-param id resolve to a `by-id` (path) fetch — exactly like
+ * the builder's getContentById.
+ */
+export function planDataSource(
+    ds: DataSourceSpec | undefined,
+    routeParams: Record<string, any> = {},
+    queryParams: Record<string, any> = {},
+): DataSourcePlan {
+    const mode: DataSourceMode = ds?.mode === 'single' ? 'single' : 'list';
+    switch (ds?.type) {
+        case 'cms':
+        case 'shop': {
+            const domain = ds.type as DataSourceDomain;
+            const req = domain === 'cms' ? ds.request?.cms : ds.request?.shop;
+            const resource = req?.contentType;
+            if (!resource) return { kind: 'none' };
+            const id = mode === 'single' ? resolveSingleItemId(req, routeParams) : null;
+            if (id) return { kind: 'by-id', domain, resource, id, mode };
+            const filter = buildDataSourceFilter(req, routeParams, queryParams);
+            const plan: DataSourcePlan = { kind: 'collection', domain, resource, filter, mode };
+            if (req?.limit) (plan as any).limit = req.limit;
+            const sort = sortParamValue(req?.sort);
+            if (sort) (plan as any).sort = sort;
+            return plan;
+        }
+        case 'external-api': {
+            const endpoint = ds.request?.endpoint;
+            return endpoint ? { kind: 'external', endpoint, mode } : { kind: 'none' };
+        }
+        case 'static':
+            return { kind: 'static', data: ds.request?.data ?? null, mode };
+        case 'derived': {
+            const d = ds.request?.derived;
+            return d?.from ? { kind: 'derived', from: d.from, path: d.path ?? '', mode } : { kind: 'none' };
+        }
+        case 'variable':
+            // A VARIABLE is a page-local resource whose value is WRITTEN at runtime by an interaction
+            // (setContext), never fetched. It resolves to nothing here on purpose: the page renders
+            // its empty state until something writes it. `request.variable.itemsFrom` only names the
+            // source whose items it holds, so the bind picker can suggest fields.
+            return { kind: 'none' };
+        default:
+            return { kind: 'none' };
+    }
+}
+
+/**
+ * The aliases on a page that are VARIABLES — runtime-written resources, not fetched data.
+ *
+ * Shared so the builder and the SSR engine agree on which aliases start empty and are filled by
+ * interactions. See element-context-state-plan.md.
+ */
+export function variableAliases(dataSources: readonly { alias?: string; type?: string }[] | undefined): Set<string> {
+    const out = new Set<string>();
+    for (const ds of dataSources ?? []) {
+        if (ds?.type === 'variable' && ds.alias) out.add(ds.alias);
+    }
+    return out;
+}
+
+/** The source alias whose items a variable holds, if it declares one (for field suggestions). */
+export function variableItemsFrom(
+    dataSources: readonly { alias?: string; type?: string; request?: any }[] | undefined,
+    alias: string,
+): string | undefined {
+    for (const ds of dataSources ?? []) {
+        if (ds?.type === 'variable' && ds.alias === alias) return ds.request?.variable?.itemsFrom || undefined;
+    }
+    return undefined;
+}
+
+/**
+ * Normalise a collection response into the shape a source expects: unwraps `{items}`/`{data}`
+ * envelopes, then returns the first item for a `single` source or the whole array for a `list`.
+ * A `by-id` response is already the item, so callers pass it through unchanged.
+ */
+export function normalizeCollectionResult(mode: DataSourceMode, data: any): any {
+    const items = Array.isArray(data) ? data : (data?.items ?? data?.data ?? []);
+    return mode === 'single' ? (items[0] ?? null) : items;
+}
+
+/** Navigate a dot/bracket path into an object, e.g. `gallery`, `details.images`, `variants[0].skus`.
+ *  Returns undefined if any segment is missing. Kept minimal + self-contained so it is shareable by
+ *  both the builder and the SSR engine (the two have divergent local `resolvePath` copies). */
+export function getByPath(obj: any, path: string): any {
+    if (obj == null || !path) return obj;
+    // Turn `a[0].b` into ['a','0','b'].
+    const segments = path.replace(/\[(\w+)\]/g, '.$1').split('.').filter(Boolean);
+    let cur = obj;
+    for (const seg of segments) {
+        if (cur == null) return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+
+/**
+ * The array a Repeater (or a repeating Slider) iterates over — the SHARED decision so the builder
+ * canvas and the SSR engine agree (see data-source-resolving.md).
+ * - No `sourcePath`: the resolved source IS the list. An array passes through; a lone object degrades
+ *   to a single-row list (back-compat with the old `fetchItems`); null/undefined → `[]`.
+ * - With `sourcePath`: the source resolved to a SINGLE resource (e.g. a product); dive into the
+ *   nested array property (e.g. `gallery`). Non-array / missing → `[]`.
+ */
+/**
+ * Fill in `derived` aliases in an already-resolved map. Given the data sources and a map of resolved
+ * NON-derived values (by alias), compute each `type:'derived'` alias as `getByPath(parent, path)` in
+ * dependency order (chains resolved by iterating until stable). Mutates + returns the map. Used by the
+ * SSR engine after it resolves the root sources; the builder resolves derived lazily per alias.
+ */
+export function resolveDerivedInto(dataSources: DataSourceSpec[], resolved: Record<string, any>): Record<string, any> {
+    const derived = (dataSources ?? []).filter(d => d?.type === 'derived' && !!d.alias);
+    let changed = true, guard = 0;
+    while (changed && guard++ < 25) {
+        changed = false;
+        for (const d of derived) {
+            if (d.alias! in resolved) continue;
+            const from = d.request?.derived?.from;
+            if (from && from in resolved) {
+                resolved[d.alias!] = getByPath(resolved[from], d.request!.derived!.path ?? '');
+                changed = true;
+            }
+        }
+    }
+    return resolved;
+}
+
+export function resolveRepeaterItems(resolved: any, sourcePath?: string | null): any[] {
+    if (sourcePath) {
+        const nested = getByPath(resolved, sourcePath);
+        return Array.isArray(nested) ? nested : [];
+    }
+    if (Array.isArray(resolved)) return resolved;
+    return resolved == null ? [] : [resolved];
+}
+
+// ── Referenced data sources (shared: builder-save + SSR resolve) ─────────────────────────────────
+// Which data-source aliases a node tree uses, so a consumer resolves ONLY what a page/global needs
+// (not the whole org library). Used by cms-client (persist globals' sources) and the SSR engine
+// (resolve the referenced subset per page). See org-data-sources-plan.md.
+
+/** Aliases referenced anywhere in a node tree: a repeater/slider `source` (a `bindings` entry with
+ *  `prop === 'source'`, or `props.source` for the slider) plus every binding's `source`. */
+export function collectReferencedAliases(nodes: any[], acc: Set<string> = new Set<string>()): Set<string> {
+    for (const n of nodes ?? []) {
+        for (const b of n?.bindings ?? []) { if (b?.source) acc.add(b.source); }
+        if (n?.props?.source) acc.add(n.props.source);
+        if (n?.children?.length) collectReferencedAliases(n.children, acc);
+    }
+    return acc;
+}
+
+/** The subset of `all` whose `alias` is referenced by `nodes` (shallow — direct references only). */
+export function referencedDataSources(nodes: any[], all: any[]): any[] {
+    const aliases = collectReferencedAliases(nodes);
+    return (all ?? []).filter(ds => aliases.has(ds?.alias));
+}
+
+/** Like `referencedDataSources`, but also pulls in a referenced source's DEPENDENCIES (transitively),
+ *  none of which the layout names directly:
+ *   - a `derived` alias needs its `request.derived.from` parent;
+ *   - a `relative` (route-context) alias needs its `request.relative.subjectFrom` (the current item)
+ *     and `request.relative.from` (the collection it navigates).
+ *  Use this when RESOLVING (the engine) so derived views and siblings/related don't resolve to nothing. */
+export function referencedDataSourcesDeep(nodes: any[], all: any[]): any[] {
+    const byAlias = new Map((all ?? []).map(d => [d?.alias, d]));
+    const wanted = collectReferencedAliases(nodes);
+    const queue = [...wanted];
+    const enqueue = (alias?: string) => {
+        if (alias && !wanted.has(alias)) { wanted.add(alias); queue.push(alias); }
+    };
+    while (queue.length) {
+        const ds: any = byAlias.get(queue.pop() as string);
+        enqueue(ds?.request?.derived?.from);
+        enqueue(ds?.request?.relative?.subjectFrom);
+        enqueue(ds?.request?.relative?.from);
+    }
+    return (all ?? []).filter(d => wanted.has(d?.alias));
+}
+
+/** Base URLs for the PUBLIC content controllers. Both must end with `/`. The builder and the SSR
+ *  engine pass their own host (they proxy `/api` differently) but MUST target the public
+ *  (`@Public()`) controllers, never the authed admin ones — data resolving is storefront data. */
+export interface DataSourceEndpoints {
+    /** cms resources, e.g. `${HOST}` (engine, HOST ends `/api/`) or `${HOST}api/` (builder). */
+    cmsBase: string;
+    /** shop resources, e.g. `${HOST}shop/` (engine) or `${HOST}api/shop/` (builder). */
+    shopBase: string;
+}
+
+export interface DataSourceRequest {
+    url: string;
+    params: Record<string, any>;
+}
+
+/**
+ * Turn a resolved {@link DataSourcePlan} into the concrete public HTTP request (url + params) — the
+ * SINGLE place that decides the URL shape, shared by the builder binding preview and the SSR engine
+ * so both hit the SAME public endpoints (no admin, no duplication). Returns `null` for `static` /
+ * `none` plans (no HTTP call). A single item is a PATH segment (`/:resource/:id`), never `?_id=`.
+ */
+export function dataSourcePlanToRequest(plan: DataSourcePlan, endpoints: DataSourceEndpoints): DataSourceRequest | null {
+    const baseFor = (domain: DataSourceDomain) => (domain === 'shop' ? endpoints.shopBase : endpoints.cmsBase);
+    switch (plan.kind) {
+        case 'by-id':
+            return { url: `${baseFor(plan.domain)}${plan.resource}/${encodeURIComponent(plan.id)}`, params: {} };
+        case 'collection': {
+            const params: Record<string, any> = { ...plan.filter };
+            if (plan.limit) params['limit'] = plan.limit;
+            if (plan.sort) params[SORT_PARAM] = plan.sort;
+            return { url: `${baseFor(plan.domain)}${plan.resource}`, params };
+        }
+        case 'external':
+            return { url: plan.endpoint, params: {} };
+        default:
+            return null;
+    }
+}

package/src/data-core/public-api.ts

@@ -0,0 +1,12 @@
+/**
+ * @vectoriox/iox-ui/data-core — the shared, FRAMEWORK-FREE data-source core (data-source-resolving.md): the ONE
+ * decision of how a data source becomes a fetch (`planDataSource`), the route-param matcher, the derived /
+ * relative (`$siblings`, `$related`) resolvers, the repeater item reader, and which sources a node tree
+ * references (`referencedDataSourcesDeep`). The builder and the SSR engine resolve with it; iox-cms reads it
+ * under plain Node (W2's Undo: is a data source still in use). Pure: no transport, no Angular. The main
+ * entry re-exports it by package path, so `@vectoriox/iox-ui` keeps working.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths —
+ * or `nest start` dies with ERR_REQUIRE_ESM while jest and build both pass.
+ */
+export * from './data-source-resolver';
+export * from './relative-sources';

package/src/data-core/relative-sources.ts

@@ -0,0 +1,282 @@
+/**
+ * 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.
+ */
+
+import { getByPath } from './data-source-resolver';
+
+/** 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. */
+export const RESERVED_ALIAS_PREFIX = '$';
+
+/** True for a platform-owned Route-scope alias (`$route`, `$current`, `$siblings`, `$related`, …). */
+export function isReservedAlias(alias: string | null | undefined): boolean {
+    return typeof alias === 'string' && alias.startsWith(RESERVED_ALIAS_PREFIX);
+}
+
+/** The `$siblings` value: the current item's neighbours within an ordered set. */
+export 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;
+}
+
+export 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;
+}
+
+const EMPTY_SIBLINGS: SiblingsResult = { 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: any, b: any): number {
+    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).
+ */
+export function resolveSiblings<T = any>(
+    items: T[] | null | undefined,
+    currentId: string | number | null | undefined,
+    options: ResolveSiblingsOptions = {},
+): SiblingsResult<T> {
+    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 };
+}
+
+export 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[];
+}
+
+/** 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: any): boolean {
+    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).
+ */
+export function buildRelatedFilter(current: any, options: BuildRelatedFilterOptions): Record<string, any> {
+    const fields = Array.isArray(options.matchFields) ? options.matchFields : [options.matchFields];
+    const filter: Record<string, any> = {};
+    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.
+ */
+export function excludeSelf<T = any>(items: T[] | null | undefined, currentId: string | number | null | undefined, idField = '_id'): T[] {
+    if (!Array.isArray(items)) return [];
+    if (currentId == null || currentId === '') return items;
+    const cid = String(currentId);
+    return items.filter(it => String(getByPath(it, idField)) !== cid);
+}
+
+/** 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. */
+export 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[];
+}
+
+// ── Relative source declaration + the shared second-pass resolver ────────────────────────────────
+// A relative source is declared like a `derived` one (`type:'relative'`), and resolved AFTER the
+// root/derived sources by a PURE pass over the resolved map — mirroring `resolveDerivedInto`, so the
+// SSR engine and the builder canvas agree with no forked logic. `planDataSource` returns `none` for
+// it (not fetched); each consumer excludes `relative` from its fetched roots and runs this pass.
+
+export type RelativeSourceKind = 'route' | 'current' | 'siblings' | 'related';
+
+export 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;
+    /** `siblings`: resolve to a SINGLE neighbour ITEM (`next`/`prev`) instead of the whole
+     *  `{prev,next,index,count,…}` object — so a source can be named e.g. `nextProject` and bound
+     *  directly (`nextProject.route`). Omit for the whole-object shape. */
+    pick?: 'next' | 'prev';
+    /** `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. */
+export 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>;
+}
+
+/** 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: Record<RelativeSourceKind, number> = { route: 0, current: 1, siblings: 2, related: 3 };
+
+/** Does an item satisfy every field in an equality predicate map (string-compared)? */
+function matchesFilter(item: any, filter: Record<string, any>): boolean {
+    return Object.keys(filter).every(k => String(getByPath(item, k)) === String(filter[k]));
+}
+
+/**
+ * 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}).
+ */
+export function computeRelative(spec: RelativeSourceSpec, inputs: RelativeInputs): any {
+    const idField = spec.idField ?? '_id';
+    switch (spec.kind) {
+        case 'route':
+            return inputs.routeParams ?? {};
+        case 'current':
+            return inputs.subject ?? null;
+        case 'siblings': {
+            const siblings = resolveSiblings(inputs.collection, getByPath(inputs.subject, idField), {
+                idField, sortBy: spec.sortBy, sortDir: spec.sortDir, wrap: spec.wrap,
+            });
+            // `pick` resolves the source directly to that neighbour item (named-source shape,
+            // e.g. `nextProject`); without it the caller binds a sub-path of the whole object.
+            return spec.pick ? siblings[spec.pick] : siblings;
+        }
+        case 'related': {
+            const filter = buildRelatedFilter(inputs.subject, { matchFields: spec.matchFields ?? [] });
+            const pool = Array.isArray(inputs.collection) ? inputs.collection : [];
+            const items = pool.filter(it => matchesFilter(it, filter));
+            return spec.excludeSelf !== false ? excludeSelf(items, getByPath(inputs.subject, idField), idField) : items;
+        }
+        default:
+            return null;
+    }
+}
+
+/**
+ * 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`.
+ */
+export function resolveRelativeInto(
+    dataSources: RelativeCapableSource[],
+    resolved: Record<string, any>,
+    routeParams: Record<string, any> = {},
+): Record<string, any> {
+    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 spec = d.request!.relative!;
+        const subjectAlias = spec.kind === 'current' ? spec.from : (spec.subjectFrom ?? spec.from);
+        resolved[d.alias!] = computeRelative(spec, {
+            subject: subjectAlias ? resolved[subjectAlias] : undefined,
+            collection: spec.from ? resolved[spec.from] : undefined,
+            routeParams,
+        });
+    }
+    return resolved;
+}