@vectoriox/iox-ui 4.14.1 → 4.16.0

package/fesm2022/vectoriox-iox-ui.mjs

@@ -1788,6 +1788,608 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImpo
                 args: ['childrenHost', { read: ViewContainerRef, static: true }]
             }] } });
 
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+function matchRouteParams(template, actual) {
+    const t = (template ?? '').replace(/^\/+/, '').split('/');
+    const a = (actual ?? '').replace(/^\/+/, '').split('/');
+    const params = {};
+    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.
+ */
+function buildDataSourceFilter(req, routeParams = {}, queryParams = {}) {
+    const params = {};
+    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.
+ */
+function resolveSingleItemId(req, routeParams = {}) {
+    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.
+ */
+function planDataSource(ds, routeParams = {}, queryParams = {}) {
+    const mode = ds?.mode === 'single' ? 'single' : 'list';
+    switch (ds?.type) {
+        case 'cms':
+        case 'shop': {
+            const domain = ds.type;
+            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 = { kind: 'collection', domain, resource, filter, mode };
+            if (req?.limit)
+                plan.limit = req.limit;
+            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' };
+        }
+        default:
+            return { kind: 'none' };
+    }
+}
+/**
+ * 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.
+ */
+function normalizeCollectionResult(mode, data) {
+    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). */
+function getByPath(obj, path) {
+    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.
+ */
+function resolveDerivedInto(dataSources, resolved) {
+    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;
+}
+function resolveRepeaterItems(resolved, sourcePath) {
+    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`. */
+function collectReferencedAliases(nodes, acc = new Set()) {
+    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). */
+function referencedDataSources(nodes, all) {
+    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. */
+function referencedDataSourcesDeep(nodes, all) {
+    const byAlias = new Map((all ?? []).map(d => [d?.alias, d]));
+    const wanted = collectReferencedAliases(nodes);
+    const queue = [...wanted];
+    const enqueue = (alias) => {
+        if (alias && !wanted.has(alias)) {
+            wanted.add(alias);
+            queue.push(alias);
+        }
+    };
+    while (queue.length) {
+        const ds = byAlias.get(queue.pop());
+        enqueue(ds?.request?.derived?.from);
+        enqueue(ds?.request?.relative?.subjectFrom);
+        enqueue(ds?.request?.relative?.from);
+    }
+    return (all ?? []).filter(d => wanted.has(d?.alias));
+}
+/**
+ * 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=`.
+ */
+function dataSourcePlanToRequest(plan, endpoints) {
+    const baseFor = (domain) => (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 = { ...plan.filter };
+            if (plan.limit)
+                params['limit'] = plan.limit;
+            return { url: `${baseFor(plan.domain)}${plan.resource}`, params };
+        }
+        case 'external':
+            return { url: plan.endpoint, params: {} };
+        default:
+            return null;
+    }
+}
+
+/**
+ * Gallery — data model + the SHARED "what are the image URLs" resolver.
+ *
+ * A Gallery is populated one of two ways (see gallery-component-plan.md):
+ *  - **Manual**: an ordered `GalleryImage[]` trait. Each item is a raw/filebox URL OR a per-item
+ *    binding path resolved against the item/route context.
+ *  - **Bound**: the whole gallery repeats over a data source (a collection, or an array property
+ *    inside one resource via `sourcePath`) — the items come from the shared `resolveRepeaterItems`,
+ *    and one field of each record (`imageField`) is the URL.
+ *
+ * `resolveGalleryUrls` is the SINGLE place both the builder canvas and the SSR/runtime engine turn a
+ * node's config into the final `string[]` the crossfade loop consumes — so both sides show the same
+ * images. It is pure and transport-agnostic; never fork it. It reuses `getByPath` (the same path
+ * reader used by data-source resolving) so binding paths behave identically everywhere.
+ */
+/**
+ * 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 `{}`.
+ */
+function resolveGalleryUrls(images, bound, ctx = {}) {
+    if (bound) {
+        const field = bound.imageField;
+        return (bound.items ?? [])
+            .map(item => (field ? getByPath(item, field) : item))
+            .map(coerceUrl)
+            .filter((u) => !!u);
+    }
+    return (images ?? [])
+        .map(img => (img?.binding ? getByPath(ctx, img.binding) : img?.url))
+        .map(coerceUrl)
+        .filter((u) => !!u);
+}
+/** A resolved value becomes a URL only if it's a non-empty string; everything else drops out. */
+function coerceUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+/**
+ * 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.
+ */
+function parseUrlList(text) {
+    if (!text)
+        return [];
+    return text
+        .split(/[\n,]+/)
+        .map(s => s.trim())
+        .filter(Boolean)
+        .map(url => ({ url }));
+}
+
+/**
+ * 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.
+ */
+/** The ken-burns zoom baked into the reference fade look (scale 1 → 1.05 over show+fade). */
+const FADE_ZOOM_EXTRA_MS = 1000;
+const fadeEffect = {
+    id: 'fade',
+    label: 'Fade',
+    defaults: { showMs: 4000, fadeMs: 1000 },
+    buildSlideStyle(state) {
+        const { active, fadingOut, firstCycleActive, durations } = state;
+        const zoomMs = durations.showMs + durations.fadeMs + FADE_ZOOM_EXTRA_MS;
+        // Before the first cycle activates, everything is flat + instant so there is no entry flash.
+        if (!firstCycleActive) {
+            return { opacity: '0', transform: 'scale(1)', transition: 'opacity 0ms, transform 0ms' };
+        }
+        const visible = active && !fadingOut;
+        const engaged = active || fadingOut; // current or outgoing slide is zoomed-in
+        return {
+            opacity: visible ? '1' : '0',
+            transform: engaged ? 'scale(1.05)' : 'scale(1)',
+            transition: `opacity ${durations.fadeMs}ms cubic-bezier(0.77, 0, 0.175, 1), ` +
+                `transform ${zoomMs}ms linear`,
+        };
+    },
+};
+/** The registry — one entry per effect. Keyed by id; unknown ids fall back to `fade`. */
+const GALLERY_EFFECTS = {
+    fade: fadeEffect,
+};
+/** Resolve an effect id to its descriptor, defaulting to `fade` (forward-compatible with new ids). */
+function resolveGalleryEffect(id) {
+    return (id && GALLERY_EFFECTS[id]) || GALLERY_EFFECTS['fade'];
+}
+const GALLERY_EFFECT_DESCRIPTORS = Object.values(GALLERY_EFFECTS).map(e => ({ id: e.id, label: e.label }));
+
+/**
+ * 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.
+ */
+/** Default scheduler over the platform's `setTimeout` / `requestAnimationFrame` (with a timer fallback). */
+const DEFAULT_GALLERY_SCHEDULER = {
+    setTimer: (fn, ms) => setTimeout(fn, ms),
+    clearTimer: h => clearTimeout(h),
+    nextFrame: fn => typeof requestAnimationFrame === 'function' ? requestAnimationFrame(fn) : setTimeout(fn, 16),
+    cancelFrame: h => {
+        if (typeof cancelAnimationFrame === 'function')
+            cancelAnimationFrame(h);
+        else
+            clearTimeout(h);
+    },
+};
+class GalleryLoop {
+    constructor(opts) {
+        this.count = 0;
+        this.currentIndex = 0;
+        this.fadingOutIndex = null;
+        this.firstCycleActive = false;
+        this.cycleTimer = null;
+        this.fadeTimer = null;
+        this.frameHandle = null;
+        /** Bumped on every (re)start so a stale timer callback from a previous run is ignored. */
+        this.runToken = 0;
+        this.running = false;
+        this.scheduler = opts.scheduler ?? DEFAULT_GALLERY_SCHEDULER;
+        this.showMs = opts.showMs;
+        this.fadeMs = opts.fadeMs;
+        this.onChange = opts.onChange;
+    }
+    get state() {
+        return {
+            currentIndex: this.currentIndex,
+            fadingOutIndex: this.fadingOutIndex,
+            firstCycleActive: this.firstCycleActive,
+        };
+    }
+    /** Start (or restart) the loop for `count` images. A count < 2 shows the single image without cycling. */
+    start(count) {
+        this.stop();
+        this.count = Math.max(0, count | 0);
+        this.currentIndex = 0;
+        this.fadingOutIndex = null;
+        this.firstCycleActive = false;
+        if (this.count === 0) {
+            this.emit();
+            return;
+        }
+        this.running = true;
+        const token = ++this.runToken;
+        // Activate on the next frame so the first paint is flat (no entry-transition flash), then
+        // begin cycling only when there is more than one image to advance through.
+        this.frameHandle = this.scheduler.nextFrame(() => {
+            if (token !== this.runToken || !this.running)
+                return;
+            this.firstCycleActive = true;
+            this.emit();
+            if (this.count > 1)
+                this.scheduleCycle(token);
+        });
+    }
+    /** Update timing live. Takes effect on the next scheduled cycle; does not restart the loop. */
+    setDurations(showMs, fadeMs) {
+        this.showMs = showMs;
+        this.fadeMs = fadeMs;
+    }
+    /** Stop and clear all timers. Idempotent. State is retained (call `start` to reset). */
+    stop() {
+        this.running = false;
+        this.runToken++;
+        if (this.cycleTimer != null) {
+            this.scheduler.clearTimer(this.cycleTimer);
+            this.cycleTimer = null;
+        }
+        if (this.fadeTimer != null) {
+            this.scheduler.clearTimer(this.fadeTimer);
+            this.fadeTimer = null;
+        }
+        if (this.frameHandle != null) {
+            this.scheduler.cancelFrame(this.frameHandle);
+            this.frameHandle = null;
+        }
+    }
+    scheduleCycle(token) {
+        if (token !== this.runToken || !this.running || this.count < 2)
+            return;
+        this.cycleTimer = this.scheduler.setTimer(() => {
+            if (token !== this.runToken || !this.running)
+                return;
+            this.fadingOutIndex = this.currentIndex;
+            this.currentIndex = (this.currentIndex + 1) % this.count;
+            this.emit();
+            this.fadeTimer = this.scheduler.setTimer(() => {
+                if (token !== this.runToken || !this.running)
+                    return;
+                this.fadingOutIndex = null;
+                this.emit();
+                this.scheduleCycle(token);
+            }, this.fadeMs);
+        }, this.showMs);
+    }
+    emit() {
+        this.onChange(this.state);
+    }
+}
+
+/**
+ * `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.
+ */
+class ClientGalleryComponent {
+    constructor(platformId, cdr) {
+        this.cdr = cdr;
+        this.nodeId = '';
+        /** Manual images — `GalleryImage[]` or a plain `string[]` of URLs (normalised on set). */
+        this.images = [];
+        this.effect = 'fade';
+        this.showDuration = 4000;
+        this.fadeDuration = 1000;
+        this.autoStart = true;
+        /** Layout mode — only `'stack'` is rendered in v1 (`'grid'` scaffolded for later). */
+        this.layout = 'stack';
+        /** The flat, display-ready URLs the loop cycles. Recomputed when `images` changes. */
+        this.urls = [];
+        this.currentIndex = 0;
+        this.fadingOutIndex = null;
+        this.started = false;
+        this.loop = null;
+        this.isBrowser = isPlatformBrowser(platformId);
+    }
+    ngOnChanges(changes) {
+        if (changes['images']) {
+            this.urls = resolveGalleryUrls(this.normalizeImages(), null);
+        }
+        if (this.loop && (changes['showDuration'] || changes['fadeDuration'])) {
+            this.loop.setDurations(this.showDuration, this.fadeDuration);
+        }
+        // If the image set changed after the loop was already running, restart it on the new count.
+        if (this.loop && changes['images'] && !changes['images'].firstChange) {
+            this.startLoop();
+        }
+    }
+    ngAfterViewInit() {
+        if (this.isBrowser && this.autoStart) {
+            this.startLoop();
+        }
+    }
+    ngOnDestroy() {
+        this.loop?.stop();
+        this.loop = null;
+    }
+    /** 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) {
+        if (!this.started) {
+            return i === 0
+                ? { opacity: '1', transform: 'scale(1)', transition: 'none' }
+                : { opacity: '0', transform: 'scale(1)', transition: 'none' };
+        }
+        return resolveGalleryEffect(this.effect).buildSlideStyle({
+            active: i === this.currentIndex,
+            fadingOut: i === this.fadingOutIndex,
+            firstCycleActive: true,
+            durations: { showMs: this.showDuration, fadeMs: this.fadeDuration },
+        });
+    }
+    startLoop() {
+        if (!this.isBrowser)
+            return;
+        this.loop?.stop();
+        this.loop = new GalleryLoop({
+            showMs: this.showDuration,
+            fadeMs: this.fadeDuration,
+            onChange: state => {
+                this.currentIndex = state.currentIndex;
+                this.fadingOutIndex = state.fadingOutIndex;
+                this.started = state.firstCycleActive;
+                this.cdr.markForCheck();
+            },
+        });
+        this.loop.start(this.urls.length);
+    }
+    normalizeImages() {
+        return (this.images ?? []).map(img => (typeof img === 'string' ? { url: img } : img));
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: ClientGalleryComponent, deps: [{ token: PLATFORM_ID }, { token: i0.ChangeDetectorRef }], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.11", type: ClientGalleryComponent, isStandalone: false, selector: "iox-gallery", inputs: { nodeId: "nodeId", images: "images", effect: "effect", showDuration: "showDuration", fadeDuration: "fadeDuration", autoStart: "autoStart", layout: "layout" }, usesOnChanges: true, ngImport: i0, template: `
+        <div class="iox-gallery" [class]="'iox-node-' + nodeId">
+            <div *ngFor="let url of urls; index as i"
+                 class="iox-gallery__img"
+                 [style.background-image]="'url(' + url + ')'"
+                 [ngStyle]="slideStyle(i)"></div>
+            <div class="iox-gallery__overlay"></div>
+        </div>
+    `, isInline: true, styles: [":host{display:block;width:100%;height:100%}.iox-gallery{position:relative;width:100%;height:100%;overflow:hidden;box-sizing:border-box}.iox-gallery__img{position:absolute;inset:0;background-size:cover;background-position:center;pointer-events:none;opacity:0;filter:brightness(1.35);-webkit-mask-image:radial-gradient(circle at 50% 50%,rgba(0,0,0,1) 80%,rgba(0,0,0,.1) 95%,rgba(0,0,0,0) 100%);mask-image:radial-gradient(circle at 50% 50%,#000 80%,#0000001a 95%,#0000)}.iox-gallery__overlay{position:absolute;inset:0;pointer-events:none;z-index:3;background:linear-gradient(to bottom,#00000080,#00000026 20% 80%,#00000080)}\n"], dependencies: [{ kind: "directive", type: i1$2.NgForOf, selector: "[ngFor][ngForOf]", inputs: ["ngForOf", "ngForTrackBy", "ngForTemplate"] }, { kind: "directive", type: i1$2.NgStyle, selector: "[ngStyle]", inputs: ["ngStyle"] }] }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: ClientGalleryComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'iox-gallery', template: `
+        <div class="iox-gallery" [class]="'iox-node-' + nodeId">
+            <div *ngFor="let url of urls; index as i"
+                 class="iox-gallery__img"
+                 [style.background-image]="'url(' + url + ')'"
+                 [ngStyle]="slideStyle(i)"></div>
+            <div class="iox-gallery__overlay"></div>
+        </div>
+    `, standalone: false, styles: [":host{display:block;width:100%;height:100%}.iox-gallery{position:relative;width:100%;height:100%;overflow:hidden;box-sizing:border-box}.iox-gallery__img{position:absolute;inset:0;background-size:cover;background-position:center;pointer-events:none;opacity:0;filter:brightness(1.35);-webkit-mask-image:radial-gradient(circle at 50% 50%,rgba(0,0,0,1) 80%,rgba(0,0,0,.1) 95%,rgba(0,0,0,0) 100%);mask-image:radial-gradient(circle at 50% 50%,#000 80%,#0000001a 95%,#0000)}.iox-gallery__overlay{position:absolute;inset:0;pointer-events:none;z-index:3;background:linear-gradient(to bottom,#00000080,#00000026 20% 80%,#00000080)}\n"] }]
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Inject,
+                    args: [PLATFORM_ID]
+                }] }, { type: i0.ChangeDetectorRef }], propDecorators: { nodeId: [{
+                type: Input
+            }], images: [{
+                type: Input
+            }], effect: [{
+                type: Input
+            }], showDuration: [{
+                type: Input
+            }], fadeDuration: [{
+                type: Input
+            }], autoStart: [{
+                type: Input
+            }], layout: [{
+                type: Input
+            }] } });
+
 const COMPONENTS = [
     BuilderImageComponent,
     BuilderSpacerComponent,
@@ -1807,6 +2409,7 @@ const COMPONENTS = [
     ClientSliderSlideComponent,
     ClientListComponent,
     ClientListItemComponent,
+    ClientGalleryComponent,
 ];
 class IoxBuilderComponentsModule {
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: IoxBuilderComponentsModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
@@ -1827,7 +2430,8 @@ class IoxBuilderComponentsModule {
             ClientSliderContainerComponent,
             ClientSliderSlideComponent,
             ClientListComponent,
-            ClientListItemComponent], imports: [CommonModule], exports: [BuilderImageComponent,
+            ClientListItemComponent,
+            ClientGalleryComponent], imports: [CommonModule], exports: [BuilderImageComponent,
             BuilderSpacerComponent,
             CardComponent,
             BuilderDividerComponent,
@@ -1844,7 +2448,8 @@ class IoxBuilderComponentsModule {
             ClientSliderContainerComponent,
             ClientSliderSlideComponent,
             ClientListComponent,
-            ClientListItemComponent] }); }
+            ClientListItemComponent,
+            ClientGalleryComponent] }); }
     static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: IoxBuilderComponentsModule, imports: [CommonModule] }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: IoxBuilderComponentsModule, decorators: [{
@@ -1891,6 +2496,7 @@ class IoxComponentRegistryService {
             ['SliderSlide', ClientSliderSlideComponent],
             ['List', ClientListComponent],
             ['ListItem', ClientListItemComponent],
+            ['Gallery', ClientGalleryComponent],
         ]);
     }
     getComponent(type) {
@@ -2105,381 +2711,128 @@ function renderDefaultDeclarations(type, styleProps, hasHoverState) {
     // parent. Phosphor forces `display:inline-flex` on its own class; generated (fantasticon) fonts
     // don't, so the engine's plain `<i class="bi-x iox-node-…">` would fall back to inline and the
     // glyph would overflow. Emit it here (guarded so a user-set display still wins) — mirrors the
-    // builder Icon component's `:host{display:inline-flex}`.
-    if (type === 'Icon' && sp['display'] === undefined) {
-        out.push('display: inline-flex', 'align-items: center', 'justify-content: center');
-    }
-    return out;
-}
-
-// Virtual trait → composed CSS property helpers.
-//
-// Several style traits are "virtual" — they don't map 1:1 to a CSS property but
-// are components of a multi-function CSS value.  composeVirtualTraits() strips
-// these virtual keys from the style map and replaces them with the correctly
-// composed CSS properties (filter, backdrop-filter, transform, transition).
-//
-// SHARED (iox-ui): consumed by BOTH the builder (render.directive + style panel)
-// and the SSR engine (LayoutRendererService). It MUST live here, not in iox-builder,
-// because the engine does not depend on iox-builder — without it the engine emitted
-// the raw virtual keys (`translate-x`, `filter-blur`, `scale-x`…) as invalid CSS.
-// Run this BEFORE compileDeclarations so the CSS output is identical on both sides.
-// ─── Filter ──────────────────────────────────────────────────────────────────
-const FILTER_FUNS = [
-    ['filterBlur', 'blur', '0px'],
-    ['filterBrightness', 'brightness', '1'],
-    ['filterContrast', 'contrast', '1'],
-    ['filterGrayscale', 'grayscale', '0'],
-    ['filterSaturate', 'saturate', '1'],
-    ['filterHueRotate', 'hue-rotate', '0deg'],
-    ['filterSepia', 'sepia', '0'],
-    ['filterInvert', 'invert', '0'],
-];
-// ─── Backdrop-filter ─────────────────────────────────────────────────────────
-const BACKDROP_FUNS = [
-    ['backdropBlur', 'blur', '0px'],
-    ['backdropBrightness', 'brightness', '1'],
-    ['backdropContrast', 'contrast', '1'],
-    ['backdropSaturate', 'saturate', '1'],
-];
-// ─── Transform ───────────────────────────────────────────────────────────────
-const TRANSFORM_FUNS = [
-    ['translateX', 'translateX', '0px'],
-    ['translateY', 'translateY', '0px'],
-    ['scaleX', 'scaleX', '1'],
-    ['scaleY', 'scaleY', '1'],
-    ['rotate', 'rotate', '0deg'],
-    ['skewX', 'skewX', '0deg'],
-    ['skewY', 'skewY', '0deg'],
-];
-// ─── ::marker pseudo-element ─────────────────────────────────────────────────
-const MARKER_FUNS = [
-    ['markerColor', 'color'],
-    ['markerFontSize', 'fontSize'],
-];
-// ─── All virtual trait names ──────────────────────────────────────────────────
-const VIRTUAL_TRAIT_KEYS = new Set([
-    ...FILTER_FUNS.map(([t]) => t),
-    ...BACKDROP_FUNS.map(([t]) => t),
-    ...TRANSFORM_FUNS.map(([t]) => t),
-    'transitionDuration', 'transitionTimingFunction', 'transitionDelay',
-    ...MARKER_FUNS.map(([t]) => t),
-]);
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-function buildFns(funs, src) {
-    return funs
-        .filter(([t, , d]) => src[t] != null && src[t] !== '' && src[t] !== d)
-        .map(([t, fn]) => `${fn}(${src[t]})`)
-        .join(' ');
-}
-// ─── Public API ───────────────────────────────────────────────────────────────
-/**
- * Strip virtual trait keys from `raw` and emit their composed CSS equivalents.
- *
- * When composing a partial state-override map (hover, active…), pass the full
- * base style map as `base` so non-overridden components (e.g. filterBrightness
- * when only filterBlur is overridden) are preserved in the composed output.
- * When operating on a complete style map, omit `base` — it defaults to `raw`.
- */
-function composeVirtualTraits(raw, base = raw) {
-    // Copy all non-virtual properties as-is
-    const result = {};
-    for (const [k, v] of Object.entries(raw)) {
-        if (!VIRTUAL_TRAIT_KEYS.has(k))
-            result[k] = v;
-    }
-    // Merge base values for any virtual key absent from the partial override map
-    const merged = (funs) => {
-        const m = {};
-        for (const [t] of funs)
-            m[t] = raw[t] ?? base[t];
-        return m;
-    };
-    // filter
-    const filterStr = buildFns(FILTER_FUNS, merged(FILTER_FUNS));
-    if (filterStr)
-        result['filter'] = filterStr;
-    // backdrop-filter
-    const backdropStr = buildFns(BACKDROP_FUNS, merged(BACKDROP_FUNS));
-    if (backdropStr)
-        result['backdropFilter'] = backdropStr;
-    // transform
-    const transformStr = buildFns(TRANSFORM_FUNS, merged(TRANSFORM_FUNS));
-    if (transformStr)
-        result['transform'] = transformStr;
-    // transition — only emit when duration is non-zero
-    const dur = raw['transitionDuration'] ?? base['transitionDuration'];
-    const ease = raw['transitionTimingFunction'] ?? base['transitionTimingFunction'];
-    const del = raw['transitionDelay'] ?? base['transitionDelay'];
-    if (dur && ease && dur !== '0ms' && dur !== '0s') {
-        const delPart = del && del !== '0ms' && del !== '0s' ? ` ${del}` : '';
-        result['transition'] = `all ${dur} ${ease}${delPart}`;
-    }
-    // ::marker pseudo-element — collected into __markerStyles so StyleRegistryService
-    // can emit a separate `.iox-node-{id}::marker { … }` rule.
-    const markerStyles = {};
-    for (const [trait, cssProp] of MARKER_FUNS) {
-        const val = raw[trait] ?? base[trait];
-        if (val != null && val !== '')
-            markerStyles[cssProp] = val;
-    }
-    if (Object.keys(markerStyles).length) {
-        result['__markerStyles'] = markerStyles;
-    }
-    return result;
-}
-
-/**
- * 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.
- */
-/**
- * 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.
- */
-function matchRouteParams(template, actual) {
-    const t = (template ?? '').replace(/^\/+/, '').split('/');
-    const a = (actual ?? '').replace(/^\/+/, '').split('/');
-    const params = {};
-    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.
- */
-function buildDataSourceFilter(req, routeParams = {}, queryParams = {}) {
-    const params = {};
-    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.
- */
-function resolveSingleItemId(req, routeParams = {}) {
-    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.
- */
-function planDataSource(ds, routeParams = {}, queryParams = {}) {
-    const mode = ds?.mode === 'single' ? 'single' : 'list';
-    switch (ds?.type) {
-        case 'cms':
-        case 'shop': {
-            const domain = ds.type;
-            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 = { kind: 'collection', domain, resource, filter, mode };
-            if (req?.limit)
-                plan.limit = req.limit;
-            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' };
-        }
-        default:
-            return { kind: 'none' };
+    // builder Icon component's `:host{display:inline-flex}`.
+    if (type === 'Icon' && sp['display'] === undefined) {
+        out.push('display: inline-flex', 'align-items: center', 'justify-content: center');
     }
+    return out;
 }
-/**
- * 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.
- */
-function normalizeCollectionResult(mode, data) {
-    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). */
-function getByPath(obj, path) {
-    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;
+
+// Virtual trait → composed CSS property helpers.
+//
+// Several style traits are "virtual" — they don't map 1:1 to a CSS property but
+// are components of a multi-function CSS value.  composeVirtualTraits() strips
+// these virtual keys from the style map and replaces them with the correctly
+// composed CSS properties (filter, backdrop-filter, transform, transition).
+//
+// SHARED (iox-ui): consumed by BOTH the builder (render.directive + style panel)
+// and the SSR engine (LayoutRendererService). It MUST live here, not in iox-builder,
+// because the engine does not depend on iox-builder — without it the engine emitted
+// the raw virtual keys (`translate-x`, `filter-blur`, `scale-x`…) as invalid CSS.
+// Run this BEFORE compileDeclarations so the CSS output is identical on both sides.
+// ─── Filter ──────────────────────────────────────────────────────────────────
+const FILTER_FUNS = [
+    ['filterBlur', 'blur', '0px'],
+    ['filterBrightness', 'brightness', '1'],
+    ['filterContrast', 'contrast', '1'],
+    ['filterGrayscale', 'grayscale', '0'],
+    ['filterSaturate', 'saturate', '1'],
+    ['filterHueRotate', 'hue-rotate', '0deg'],
+    ['filterSepia', 'sepia', '0'],
+    ['filterInvert', 'invert', '0'],
+];
+// ─── Backdrop-filter ─────────────────────────────────────────────────────────
+const BACKDROP_FUNS = [
+    ['backdropBlur', 'blur', '0px'],
+    ['backdropBrightness', 'brightness', '1'],
+    ['backdropContrast', 'contrast', '1'],
+    ['backdropSaturate', 'saturate', '1'],
+];
+// ─── Transform ───────────────────────────────────────────────────────────────
+const TRANSFORM_FUNS = [
+    ['translateX', 'translateX', '0px'],
+    ['translateY', 'translateY', '0px'],
+    ['scaleX', 'scaleX', '1'],
+    ['scaleY', 'scaleY', '1'],
+    ['rotate', 'rotate', '0deg'],
+    ['skewX', 'skewX', '0deg'],
+    ['skewY', 'skewY', '0deg'],
+];
+// ─── ::marker pseudo-element ─────────────────────────────────────────────────
+const MARKER_FUNS = [
+    ['markerColor', 'color'],
+    ['markerFontSize', 'fontSize'],
+];
+// ─── All virtual trait names ──────────────────────────────────────────────────
+const VIRTUAL_TRAIT_KEYS = new Set([
+    ...FILTER_FUNS.map(([t]) => t),
+    ...BACKDROP_FUNS.map(([t]) => t),
+    ...TRANSFORM_FUNS.map(([t]) => t),
+    'transitionDuration', 'transitionTimingFunction', 'transitionDelay',
+    ...MARKER_FUNS.map(([t]) => t),
+]);
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function buildFns(funs, src) {
+    return funs
+        .filter(([t, , d]) => src[t] != null && src[t] !== '' && src[t] !== d)
+        .map(([t, fn]) => `${fn}(${src[t]})`)
+        .join(' ');
 }
+// ─── Public API ───────────────────────────────────────────────────────────────
 /**
- * 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.
+ * Strip virtual trait keys from `raw` and emit their composed CSS equivalents.
+ *
+ * When composing a partial state-override map (hover, active…), pass the full
+ * base style map as `base` so non-overridden components (e.g. filterBrightness
+ * when only filterBlur is overridden) are preserved in the composed output.
+ * When operating on a complete style map, omit `base` — it defaults to `raw`.
  */
-function resolveDerivedInto(dataSources, resolved) {
-    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;
-}
-function resolveRepeaterItems(resolved, sourcePath) {
-    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`. */
-function collectReferencedAliases(nodes, acc = new Set()) {
-    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);
+function composeVirtualTraits(raw, base = raw) {
+    // Copy all non-virtual properties as-is
+    const result = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (!VIRTUAL_TRAIT_KEYS.has(k))
+            result[k] = v;
     }
-    return acc;
-}
-/** The subset of `all` whose `alias` is referenced by `nodes` (shallow — direct references only). */
-function referencedDataSources(nodes, all) {
-    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. */
-function referencedDataSourcesDeep(nodes, all) {
-    const byAlias = new Map((all ?? []).map(d => [d?.alias, d]));
-    const wanted = collectReferencedAliases(nodes);
-    const queue = [...wanted];
-    const enqueue = (alias) => {
-        if (alias && !wanted.has(alias)) {
-            wanted.add(alias);
-            queue.push(alias);
-        }
+    // Merge base values for any virtual key absent from the partial override map
+    const merged = (funs) => {
+        const m = {};
+        for (const [t] of funs)
+            m[t] = raw[t] ?? base[t];
+        return m;
     };
-    while (queue.length) {
-        const ds = byAlias.get(queue.pop());
-        enqueue(ds?.request?.derived?.from);
-        enqueue(ds?.request?.relative?.subjectFrom);
-        enqueue(ds?.request?.relative?.from);
+    // filter
+    const filterStr = buildFns(FILTER_FUNS, merged(FILTER_FUNS));
+    if (filterStr)
+        result['filter'] = filterStr;
+    // backdrop-filter
+    const backdropStr = buildFns(BACKDROP_FUNS, merged(BACKDROP_FUNS));
+    if (backdropStr)
+        result['backdropFilter'] = backdropStr;
+    // transform
+    const transformStr = buildFns(TRANSFORM_FUNS, merged(TRANSFORM_FUNS));
+    if (transformStr)
+        result['transform'] = transformStr;
+    // transition — only emit when duration is non-zero
+    const dur = raw['transitionDuration'] ?? base['transitionDuration'];
+    const ease = raw['transitionTimingFunction'] ?? base['transitionTimingFunction'];
+    const del = raw['transitionDelay'] ?? base['transitionDelay'];
+    if (dur && ease && dur !== '0ms' && dur !== '0s') {
+        const delPart = del && del !== '0ms' && del !== '0s' ? ` ${del}` : '';
+        result['transition'] = `all ${dur} ${ease}${delPart}`;
     }
-    return (all ?? []).filter(d => wanted.has(d?.alias));
-}
-/**
- * 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=`.
- */
-function dataSourcePlanToRequest(plan, endpoints) {
-    const baseFor = (domain) => (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 = { ...plan.filter };
-            if (plan.limit)
-                params['limit'] = plan.limit;
-            return { url: `${baseFor(plan.domain)}${plan.resource}`, params };
-        }
-        case 'external':
-            return { url: plan.endpoint, params: {} };
-        default:
-            return null;
+    // ::marker pseudo-element — collected into __markerStyles so StyleRegistryService
+    // can emit a separate `.iox-node-{id}::marker { … }` rule.
+    const markerStyles = {};
+    for (const [trait, cssProp] of MARKER_FUNS) {
+        const val = raw[trait] ?? base[trait];
+        if (val != null && val !== '')
+            markerStyles[cssProp] = val;
+    }
+    if (Object.keys(markerStyles).length) {
+        result['__markerStyles'] = markerStyles;
     }
+    return result;
 }
 
 /**
@@ -2653,6 +3006,106 @@ function resolveRelativeInto(dataSources, resolved, routeParams = {}) {
     return resolved;
 }
 
+/**
+ * Binding pipes — render-time value transforms (UI label: "Filters").
+ *
+ * A binding resolves a raw value (`resolvePath(sourceData, path)`); a pipe chain then reshapes it for
+ * display (format a timestamp, upper-case, truncate, …). This is the SINGLE shared implementation used
+ * by BOTH the builder canvas and the SSR engine — the engine renders layout JSON to a STRING and can't
+ * use Angular pipes, and `resolvePath` is already duplicated across the apply points, so the transform
+ * MUST be one pure, transport-agnostic function applied identically everywhere. Never fork it.
+ *
+ * See iox-ai-guidance/architecture/builder/binding-filters-plan.md.
+ */
+// ── Date / time (Intl locale presets — locale-aware, zero-dep, browser + Node identical) ──────────
+const DATE_PRESETS = {
+    short: { dateStyle: 'short' },
+    medium: { dateStyle: 'medium' },
+    long: { dateStyle: 'long' },
+    full: { dateStyle: 'full' },
+};
+const DATETIME_PRESETS = {
+    short: { dateStyle: 'short', timeStyle: 'short' },
+    medium: { dateStyle: 'medium', timeStyle: 'short' },
+    long: { dateStyle: 'long', timeStyle: 'medium' },
+    full: { dateStyle: 'full', timeStyle: 'long' },
+};
+/** Coerce an ISO string / epoch number / Date to a valid Date, or null (→ pipes pass the value through). */
+function toDate(value) {
+    if (value instanceof Date)
+        return isNaN(value.getTime()) ? null : value;
+    if (typeof value === 'number') {
+        const d = new Date(value);
+        return isNaN(d.getTime()) ? null : d;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const d = new Date(value);
+        return isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+function formatDate(value, args, ctx, presets) {
+    const d = toDate(value);
+    if (!d)
+        return value; // never throw — unparseable input passes through unchanged
+    const preset = args[0] || 'medium';
+    return new Intl.DateTimeFormat(ctx.locale, presets[preset] ?? presets['medium']).format(d);
+}
+/** The registry — adding a pipe here (+ a descriptor below) makes it work on both sides and appear in
+ *  the authoring UI. Keyed by name; unknown names are passed through by `applyBindingPipes`. */
+const PIPE_REGISTRY = {
+    date: (v, args, ctx) => formatDate(v, args, ctx, DATE_PRESETS),
+    datetime: (v, args, ctx) => formatDate(v, args, ctx, DATETIME_PRESETS),
+    uppercase: (v) => (v == null ? v : String(v).toUpperCase()),
+    lowercase: (v) => (v == null ? v : String(v).toLowerCase()),
+    truncate: (v, args) => {
+        if (v == null)
+            return v;
+        const s = String(v);
+        const len = Number(args[0]) || 100;
+        const suffix = args[1] != null ? String(args[1]) : '…';
+        return s.length > len ? s.slice(0, len) + suffix : s;
+    },
+    number: (v, args, ctx) => {
+        const n = typeof v === 'number' ? v : parseFloat(v);
+        if (!Number.isFinite(n))
+            return v;
+        const opts = {};
+        if (args[0] != null && args[0] !== '') {
+            opts.minimumFractionDigits = Number(args[0]);
+            opts.maximumFractionDigits = Number(args[0]);
+        }
+        return new Intl.NumberFormat(ctx.locale, opts).format(n);
+    },
+};
+/**
+ * Apply a binding's pipe chain to a resolved value, LEFT→RIGHT. Pure. An empty/undefined chain returns
+ * the value untouched; an unknown pipe name is skipped (forward-compatible with newer authored pipes).
+ * Call this at every binding-resolution point (builder canvas + engine SSR + engine hydration).
+ */
+function applyBindingPipes(value, pipes, ctx = {}) {
+    if (!pipes?.length)
+        return value;
+    return pipes.reduce((v, p) => {
+        const fn = p && PIPE_REGISTRY[p.name];
+        return fn ? fn(v, p.args ?? [], ctx) : v;
+    }, value);
+}
+const PRESET_OPTIONS = [
+    { label: 'Short', value: 'short' },
+    { label: 'Medium', value: 'medium' },
+    { label: 'Long', value: 'long' },
+    { label: 'Full', value: 'full' },
+];
+const PIPE_DESCRIPTORS = [
+    { name: 'date', label: 'Date', args: [{ key: 'preset', label: 'Format', control: 'select', options: PRESET_OPTIONS, default: 'medium' }] },
+    { name: 'datetime', label: 'Date & time', args: [{ key: 'preset', label: 'Format', control: 'select', options: PRESET_OPTIONS, default: 'medium' }] },
+    { name: 'uppercase', label: 'UPPERCASE', args: [] },
+    { name: 'lowercase', label: 'lowercase', args: [] },
+    { name: 'truncate', label: 'Truncate', args: [{ key: 'length', label: 'Max length', control: 'number', default: 100 }] },
+    { name: 'number', label: 'Number', args: [{ key: 'decimals', label: 'Decimals', control: 'number', default: null }] },
+];
+
 /**
  * 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
@@ -3087,5 +3540,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, 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 { 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 };
 //# sourceMappingURL=vectoriox-iox-ui.mjs.map