@vectoriox/iox-ui 5.69.0 → 5.70.0

package/src/scene-core/scroll-driver.ts

@@ -0,0 +1,220 @@
+import { SceneRole } from '@vectoriox/iox-ui/composite-core';
+
+import { normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, SceneTrack } from './scene';
+
+/**
+ * The ONE scroll loop (premium-sites plan §5b, SC0). Every Scene on a page reads one progress value from it, on the
+ * canvas and on the live site alike. It reads where the root is and nothing else, so it has one code path: under the
+ * canvas's zoom the same rectangle divides by the same zoom, and the answer is the same at any scale.
+ *
+ * - The value is DAMPED: the scroll stops and the page settles a moment later. This is much of the prototype's weight,
+ *   and why this is not a CSS scroll timeline, which cannot do it.
+ * - The live site pins with `position: sticky`, on the compositor. The canvas cannot (its page never scrolls itself,
+ *   its Lenis scrolls a wrapper around a zoomed frame), so `pin` holds the stage there with `translate` instead.
+ *   `translate`, not `transform`: a Stage may carry tracks of its own.
+ * - It sleeps. No frame is asked for unless something moved, so a page holding a settled Scene costs nothing.
+ * - Reads come first in a frame and writes after, and a write only ever touches compositor properties.
+ */
+
+export const SCENE_DAMPING = 9;
+const SETTLED = 0.0005;
+const MAX_FRAME_SECONDS = 0.1;
+/** The first frame after a sleep has no previous one to measure from: it counts as one frame, or a scroll would lose it. */
+const WAKING_FRAME_SECONDS = 1 / 60;
+const STAGE_SELECTOR = `.iox-role-${SceneRole.Stage.replace(/\./g, '-')}`;
+const TRANSFORM_WILL_CHANGE = 'transform, opacity';
+
+/** One frame of the damping: frame-rate independent, so 60 Hz and 120 Hz settle in the same time. */
+export function dampToward(current: number, target: number, seconds: number, rate: number = SCENE_DAMPING): number {
+    return current + (target - current) * (1 - Math.exp(-seconds * rate));
+}
+
+/** Where a root stands: scrolled `local` page px into its `travel`. `zoom` undoes the canvas's scale. */
+export function sceneScrollState(rootTop: number, originTop: number, zoom: number, travel: number): { local: number; progress: number } {
+    if (travel <= 0) return { local: 0, progress: 0 };
+    const local = Math.min(travel, Math.max(0, -(rootTop - originTop) / (zoom || 1)));
+    return { local, progress: local / travel };
+}
+
+export interface ScrollDriverOptions {
+    /** Hold the stage with `translate` (the canvas). The live site's stage is sticky and needs nothing. */
+    pin?: boolean;
+    /** The element a root scrolls under, when that is not the window (the canvas's frame, Preview's page). */
+    originOf?: (root: HTMLElement) => HTMLElement | null;
+    /** Follow what changes inside a root: tracks edited, layers added (the canvas). */
+    observe?: boolean;
+    damping?: number;
+    /** The window, for a test. */
+    host?: Window;
+}
+
+interface Layer {
+    el: HTMLElement;
+    tracks: SceneTrack[];
+    phoneTracks: SceneTrack[];
+    last: SceneFrame;
+}
+
+interface Scene {
+    root: HTMLElement;
+    stage: HTMLElement | null;
+    layers: Layer[];
+    progress: number;
+    /** Page px and the stage's own width, measured when something resizes and never per frame. */
+    height: number;
+    travel: number;
+    phone: boolean;
+    inlineSign: 1 | -1;
+    /** No frame written yet: the first one lands exactly where the scroll is, with no glide. */
+    fresh: boolean;
+    mutations: MutationObserver | null;
+}
+
+function parseTracks(raw: string | null): SceneTrack[] {
+    if (!raw) return [];
+    try { return normalizeTracks(JSON.parse(raw)); } catch { return []; }
+}
+
+export class ScrollDriver {
+    private readonly scenes = new Map<HTMLElement, Scene>();
+    private readonly host: Window;
+    private readonly resize: ResizeObserver | null;
+    private frame = 0;
+    private lastTime = 0;
+    private readonly wakeUp = (): void => this.wake();
+
+    constructor(private readonly options: ScrollDriverOptions = {}) {
+        this.host = options.host ?? window;
+        // In capture: a scroll does not bubble, and the canvas's Lenis scrolls an element, not the window.
+        this.host.addEventListener('scroll', this.wakeUp, { capture: true, passive: true });
+        this.host.addEventListener('resize', this.wakeUp, { passive: true });
+        const Observer = (this.host as Window & { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;
+        this.resize = Observer ? new Observer(() => this.remeasureAll()) : null;
+    }
+
+    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. */
+    add(root: HTMLElement): void {
+        this.remove(root);
+        const scene: Scene = { root, stage: null, layers: [], progress: 0, height: 0, travel: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
+        this.scenes.set(root, scene);
+        this.resize?.observe(root);
+        if (this.options.observe) {
+            const Observer = (this.host as Window & { MutationObserver?: typeof MutationObserver }).MutationObserver;
+            if (Observer) {
+                scene.mutations = new Observer(() => this.reread(scene));
+                scene.mutations.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: [SceneAttribute.Tracks, SceneAttribute.PhoneTracks] });
+            }
+        }
+        this.reread(scene);
+    }
+
+    remove(root: HTMLElement): void {
+        const scene = this.scenes.get(root);
+        if (!scene) return;
+        scene.mutations?.disconnect();
+        this.resize?.unobserve(root);
+        if (scene.stage) scene.stage.style.removeProperty('translate');
+        for (const layer of scene.layers) layer.el.style.removeProperty('will-change');
+        this.scenes.delete(root);
+    }
+
+    /** The damped progress a root's layers stand at. */
+    progressOf(root: HTMLElement): number | null {
+        return this.scenes.get(root)?.progress ?? null;
+    }
+
+    /** Something moved that no scroll or resize announces (the canvas's zoom). */
+    wake(): void {
+        if (this.frame) return;
+        this.frame = this.host.requestAnimationFrame(this.tick);
+    }
+
+    destroy(): void {
+        if (this.frame) this.host.cancelAnimationFrame(this.frame);
+        this.frame = 0;
+        this.host.removeEventListener('scroll', this.wakeUp, { capture: true });
+        this.host.removeEventListener('resize', this.wakeUp);
+        for (const root of [...this.scenes.keys()]) this.remove(root);
+        this.resize?.disconnect();
+    }
+
+    /** Read a root's stage and layers from its DOM: its own Scene's only, never a nested one's. */
+    private reread(scene: Scene): void {
+        scene.stage = scene.root.querySelector<HTMLElement>(STAGE_SELECTOR);
+        scene.layers = Array.from(scene.root.querySelectorAll<HTMLElement>(`[${SceneAttribute.Tracks}], [${SceneAttribute.PhoneTracks}]`))
+            .filter(el => el === scene.root || el.parentElement?.closest(`[${SceneAttribute.Root}]`) === scene.root)
+            .map(el => this.readLayer(el, scene));
+        this.measure(scene);
+        scene.fresh = true;
+        this.wake();
+    }
+
+    private readLayer(el: HTMLElement, scene: Scene): Layer {
+        const previous = scene.layers.find(layer => layer.el === el);
+        el.style.setProperty('will-change', TRANSFORM_WILL_CHANGE);
+        return { el, tracks: parseTracks(el.getAttribute(SceneAttribute.Tracks)), phoneTracks: parseTracks(el.getAttribute(SceneAttribute.PhoneTracks)), last: previous?.last ?? {} };
+    }
+
+    private remeasureAll(): void {
+        for (const scene of this.scenes.values()) this.measure(scene);
+        this.wake();
+    }
+
+    private measure(scene: Scene): void {
+        scene.height = scene.root.offsetHeight;
+        scene.travel = Math.max(0, scene.height - (scene.stage?.offsetHeight ?? scene.height));
+        scene.phone = (scene.stage?.offsetWidth ?? Infinity) <= SCENE_PHONE_MAX_WIDTH;
+        scene.inlineSign = scene.stage && this.host.getComputedStyle(scene.stage).direction === 'rtl' ? -1 : 1;
+        for (const layer of scene.layers) layer.last = {};
+    }
+
+    private readonly tick = (now: number): void => {
+        this.frame = 0;
+        const seconds = this.lastTime ? Math.min(MAX_FRAME_SECONDS, (now - this.lastTime) / 1000) : WAKING_FRAME_SECONDS;
+        this.lastTime = now;
+        const reads = [...this.scenes.values()].map(scene => this.read(scene));
+        let moving = false;
+        for (const { scene, local, target } of reads) {
+            if (this.options.pin && scene.stage) scene.stage.style.setProperty('translate', `0 ${local}px`);
+            const next = scene.fresh ? target : dampToward(scene.progress, target, seconds, this.options.damping);
+            const settled = Math.abs(next - target) < SETTLED;
+            scene.progress = settled ? target : next;
+            scene.fresh = false;
+            this.write(scene);
+            moving = moving || !settled;
+        }
+        if (moving) this.wake();
+        else this.lastTime = 0;
+    };
+
+    private read(scene: Scene): { scene: Scene; local: number; target: number } {
+        const rect = scene.root.getBoundingClientRect();
+        const origin = this.options.originOf?.(scene.root)?.getBoundingClientRect().top ?? 0;
+        const zoom = scene.height ? rect.height / scene.height : 1;
+        const { local, progress } = sceneScrollState(rect.top, origin, zoom, scene.travel);
+        return { scene, local, target: progress };
+    }
+
+    private write(scene: Scene): void {
+        for (const layer of scene.layers) {
+            const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
+            const frame = sceneFrame(tracks, scene.progress, { inlineSign: scene.inlineSign });
+            for (const key of Object.keys(frame) as (keyof SceneFrame)[]) {
+                if (frame[key] !== layer.last[key]) layer.el.style[key] = frame[key]!;
+            }
+            layer.last = frame;
+        }
+    }
+}
+
+/** A page's Scenes, driven by one driver; null when it holds none, or when the visitor asked for less motion (the
+ *  page's own CSS then lets each Scene flow). The live site's door. */
+export function attachScenes(container: HTMLElement, options: ScrollDriverOptions = {}): ScrollDriver | null {
+    const roots = container.querySelectorAll<HTMLElement>(`[${SceneAttribute.Root}]`);
+    if (!roots.length) return null;
+    const host = options.host ?? window;
+    if (host.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return null;
+    const driver = new ScrollDriver(options);
+    roots.forEach(root => driver.add(root));
+    return driver;
+}

package/styles/iox-design.css

@@ -67,6 +67,13 @@ iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
     --iox-button-ghost-ink: currentColor;
 }
 
+/* ── Scene (premium-sites plan §5b) ───────────────────────────────────────────────────────────────
+   The stage is the size container its layers' tracks measure against (`cqw` / `cqh`, scene-core), so one frame is
+   right at any width and under any canvas zoom, with no measuring. Its pin, size and clip are the node's own styles. */
+.iox-role-scene-stage {
+    container-type: size;
+}
+
 /* ── Card v2 (composite T23; complex-components board 8) ──────────────────────────────────────────
    The parts are ordinary nodes; `nodeDesignClasses` writes `iox-role-<role>` on each, so these rules are
    the same in every renderer. Zero-specificity where an author's own value must win. */