@vectoriox/iox-ui 5.84.0 → 5.85.0

package/fesm2022/vectoriox-iox-ui-scene-core.mjs

@@ -48,7 +48,25 @@ var SceneAttribute;
     SceneAttribute["Root"] = "data-iox-scene";
     SceneAttribute["Tracks"] = "data-iox-tracks";
     SceneAttribute["PhoneTracks"] = "data-iox-tracks-phone";
+    /** A root's stage that is not a Scene's `scene.stage` part: the slider a scroll plays (premium M4). */
+    SceneAttribute["Stage"] = "data-iox-scene-stage";
 })(SceneAttribute || (SceneAttribute = {}));
+/**
+ * A SLIDER THE SCROLL PLAYS (premium components M4 — M1.3's held gallery). Its progress rests on each picture and changes
+ * only over the middle share of each step, so every picture arrives and stays a moment while the page holds it: `p` is
+ * the scroll's progress through the runway (0–1), `n` the slides; the answer is Swiper's progress (0–1).
+ */
+const SLIDER_HOLD_SHARE = 0.2;
+/** Page px of scroll per picture, as a share of the screen's height (the runway the renderers reserve). */
+const SLIDER_SCROLL_STEP_SCREENS = 0.55;
+function heldProgress(p, n) {
+    if (!(n >= 2) || !Number.isFinite(p))
+        return 0;
+    const s = clamp01(p) * (n - 1);
+    const i = Math.min(n - 2, Math.floor(s));
+    const f = clamp01((s - i - SLIDER_HOLD_SHARE) / (1 - 2 * SLIDER_HOLD_SHARE));
+    return round((i + smoothstep(f)) / (n - 1));
+}
 /** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */
 const SCENE_PHONE_MAX_WIDTH = FRAMES_PHONE_MAX_WIDTH;
 const DECIMALS = 10000;
@@ -779,8 +797,26 @@ const SETTLED_PX = 0.25;
 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 STAGE_SELECTOR = `.iox-role-${SceneRole.Stage.replace(/\./g, '-')}, [${SceneAttribute.Stage}]`;
 const TRANSFORM_WILL_CHANGE = 'transform, opacity';
+/**
+ * Dispatched (bubbling) by something the driver plays that arrived after the driver last looked — a Swiper booted on a
+ * slider's stage. Never a DOM `scroll`: nothing that follows the driver may dispatch one (SC2).
+ */
+const SCENE_WAKE_EVENT = 'iox-scene-wake';
+/**
+ * ONE driver per root (premium M4 — §0 "To verify first"). The live site attaches a driver per runtime instance (the
+ * page's and the globals'); an instance that scanned a container holding the other's Scenes would drive them a second
+ * time, two damped values fighting over one layer. A root is held by the first driver that adds it until that driver
+ * lets it go.
+ */
+const HELD = new WeakMap();
+function sliderOf(stage) {
+    // The stage is the runway's child: the `.swiper` itself (both engine paths), or the canvas's shell around it.
+    const holder = (stage?.classList.contains('swiper') ? stage : stage?.querySelector('.swiper'));
+    const swiper = holder?.swiper;
+    return swiper && typeof swiper.setProgress === 'function' && !swiper.destroyed ? swiper : null;
+}
 /** One frame of the damping: frame-rate independent, so 60 Hz and 120 Hz settle in the same time. */
 function dampToward(current, target, seconds, rate = SCENE_DAMPING) {
     return current + (target - current) * (1 - Math.exp(-seconds * rate));
@@ -809,6 +845,13 @@ class ScrollDriver {
         this.frame = 0;
         this.lastTime = 0;
         this.wakeUp = () => this.wake();
+        this.onWakeEvent = (e) => {
+            const scene = [...this.scenes.values()].find(s => s.root.contains(e.target));
+            if (scene) {
+                scene.fresh = true;
+                this.wake();
+            }
+        };
         this.tick = (now) => {
             this.frame = 0;
             const seconds = this.lastTime ? Math.min(MAX_FRAME_SECONDS, (now - this.lastTime) / 1000) : WAKING_FRAME_SECONDS;
@@ -837,13 +880,18 @@ class ScrollDriver {
         // 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 });
+        this.host.addEventListener(SCENE_WAKE_EVENT, this.onWakeEvent, { capture: true });
         const Observer = this.host.ResizeObserver;
         this.resize = Observer ? new Observer(() => this.remeasureAll()) : null;
     }
-    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. */
+    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. False when another driver holds it. */
     add(root) {
+        const holder = HELD.get(root);
+        if (holder && holder !== this)
+            return false;
         this.remove(root);
-        const scene = { root, stage: null, layers: [], progress: 0, target: 0, height: 0, travel: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
+        HELD.set(root, this);
+        const scene = { root, stage: null, layers: [], progress: 0, target: 0, height: 0, travel: 0, stick: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
         this.scenes.set(root, scene);
         this.resize?.observe(root);
         if (this.options.observe) {
@@ -854,11 +902,18 @@ class ScrollDriver {
             }
         }
         this.readScene(scene);
+        return true;
+    }
+    /** True when this driver holds `root`. */
+    holds(root) {
+        return this.scenes.has(root);
     }
     remove(root) {
         const scene = this.scenes.get(root);
         if (!scene)
             return;
+        if (HELD.get(root) === this)
+            HELD.delete(root);
         scene.mutations?.disconnect();
         this.resize?.unobserve(root);
         if (scene.stage)
@@ -922,6 +977,7 @@ class ScrollDriver {
         this.frame = 0;
         this.host.removeEventListener('scroll', this.wakeUp, { capture: true });
         this.host.removeEventListener('resize', this.wakeUp);
+        this.host.removeEventListener(SCENE_WAKE_EVENT, this.onWakeEvent, { capture: true });
         for (const root of [...this.scenes.keys()])
             this.remove(root);
         this.resize?.disconnect();
@@ -971,6 +1027,9 @@ class ScrollDriver {
     measure(scene) {
         scene.height = scene.root.offsetHeight;
         scene.travel = Math.max(0, scene.height - (scene.stage?.offsetHeight ?? scene.height));
+        // Where the stage holds: its sticky top (a played slider holds mid-screen; a Scene's stage at 0). Read when
+        // something resizes, never per frame.
+        scene.stick = scene.stage ? (parseFloat(this.host.getComputedStyle(scene.stage).top) || 0) : 0;
         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)
@@ -980,10 +1039,14 @@ class ScrollDriver {
         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);
+        const { local, progress } = sceneScrollState(rect.top, origin + scene.stick * zoom, zoom, scene.travel);
         return { scene, local, target: progress };
     }
     write(scene) {
+        // A slider the scroll plays (M4): the damped moment, held on each picture.
+        const slider = sliderOf(scene.stage);
+        if (slider)
+            slider.setProgress(heldProgress(scene.progress, slider.slides?.length ?? 0), 0);
         for (const layer of scene.layers) {
             const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
             this.writeWords(layer, sceneWordsLit(tracks, scene.progress));
@@ -1062,6 +1125,39 @@ function attachScenes(container, options = {}) {
     roots.forEach(root => driver.add(root));
     return driver;
 }
+/**
+ * The Scene roots that belong to `elements` (each, and what it holds) — what one runtime instance owns: the page's nodes,
+ * or the globals'. Never a whole container that also holds another instance's Scenes (premium M4: the globals' instance
+ * scanned the app root and drove the page's Scenes a second time).
+ */
+function sceneRootsIn(elements) {
+    const out = new Set();
+    for (const el of elements) {
+        if (el.hasAttribute?.(SceneAttribute.Root))
+            out.add(el);
+        // A wrapper the node renders around itself (a played slider's runway around its `.swiper`) is the node's own.
+        const parent = el.parentElement;
+        if (parent?.hasAttribute(SceneAttribute.Root) && parent.children.length === 1)
+            out.add(parent);
+        el.querySelectorAll?.(`[${SceneAttribute.Root}]`).forEach(root => out.add(root));
+    }
+    return [...out];
+}
+/** The live site's door for a runtime that owns some nodes: their Scenes on one driver (null when none, or under reduced
+ *  motion — the page's own CSS then lets each Scene flow). A root another driver holds stays with it. */
+function attachSceneRoots(roots, options = {}) {
+    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);
+    const held = roots.filter(root => driver.add(root));
+    if (held.length)
+        return driver;
+    driver.destroy();
+    return null;
+}
 
 /**
  * @vectoriox/iox-ui/scene-core — a Scene: a stage that holds still while the page scrolls past it, its layers moving on
@@ -1074,5 +1170,5 @@ function attachScenes(container, options = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FILM_SMOOTH, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WORDS, SCENE_WORD_DIM, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFilmDensity, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, scenePlayed, sceneRevealFromOf, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withScenePlayback, withSceneRevealFrom, withoutSceneKey, withoutScenePlayback };
+export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FILM_SMOOTH, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WAKE_EVENT, SCENE_WORDS, SCENE_WORD_DIM, SLIDER_HOLD_SHARE, SLIDER_SCROLL_STEP_SCREENS, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachSceneRoots, attachScenes, buildSceneRecipe, colourAt, dampToward, heldProgress, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFilmDensity, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, scenePlayed, sceneRevealFromOf, sceneRootOnPath, sceneRootsIn, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withScenePlayback, withSceneRevealFrom, withoutSceneKey, withoutScenePlayback };
 //# sourceMappingURL=vectoriox-iox-ui-scene-core.mjs.map