@needle-tools/engine 4.10.2 → 4.10.3

package/src/engine-components/web/ScrollFollow.ts

@@ -53,6 +53,12 @@ type ScrollFollowEvent = {
  * 2. Add a ScrollFollow component to the same GameObject or another GameObject in the scene.
  * 3. Assign the PlayableDirector component to the ScrollFollow's target property.
  * 4. The timeline will now scrub based on the scroll position of the page.
+ * 5. (Optional) Add ScrollMarker markers to your HTML to define specific points in the timeline that correspond to elements on the page. For example:
+ *   ```html
+ *   <div data-timeline-marker="0.0">Start of Timeline</div>
+ *   <div data-timeline-marker="0.5">Middle of Timeline</div>
+ *   <div data-timeline-marker="1.0">End of Timeline</div>
+ * ```
  * 
  * @category Web
  * @group Components
@@ -291,67 +297,75 @@ export class ScrollFollow extends Behaviour {
     private handleTimelineTarget(director: PlayableDirector, value: number) {
 
         const duration = director.duration;
-
-
-        let scrollRegionStart = Infinity;
-        let scrollRegionEnd = 0;
-        markersArray.length = 0;
-
-        // querySelectorResults.length = 0;
-        let markerIndex = 0;
-
-        // https://scroll-driven-animations.style/tools/view-timeline/ranges
-        for (const marker of director.foreachMarker<ScrollMarkerModel & { element?: HTMLElement | null, needsUpdate?: boolean, timeline?: ViewTimeline }>("ScrollMarker")) {
-
-            const index = markerIndex++;
-
-            // Get marker elements from DOM
-            if ((marker.element === undefined || marker.needsUpdate === true || /** element is not in DOM anymore? */ (marker.element && !marker.element?.parentNode))) {
-                marker.needsUpdate = false;
-                try {
-                    // TODO: with this it's currently not possible to remap markers from HTML. For example if I have two sections and I want to now use the marker["center"] multiple times to stay at that marker for a longer time
-                    marker.element = tryGetElementsForSelector(index, marker.name) as HTMLElement | null;
-                    if (debug) console.debug(`ScrollMarker #${index} "${marker.name}" (${marker.time.toFixed(2)}) found`, marker.element);
-                    if (!marker.element) {
-                        marker.timeline = undefined;
-                        if (debug || isDevEnvironment()) console.warn(`No HTML element found for ScrollMarker: ${marker.name} (index ${index})`);
-                        continue;
+        let markersArray = timelineMarkerArrays.get(director);
+
+        // Create markers array
+        if (!markersArray) {
+            markersArray = [];
+            timelineMarkerArrays.set(director, markersArray);
+
+            let markerIndex = 0;
+
+            for (const marker of director.foreachMarker<ScrollMarkerModel & { element?: HTMLElement | null, needsUpdate?: boolean, timeline?: ViewTimeline }>("ScrollMarker")) {
+
+                const index = markerIndex++;
+
+                // Get marker elements from DOM
+                if ((marker.element === undefined || marker.needsUpdate === true || /** element is not in DOM anymore? */ (marker.element && !marker.element?.parentNode))) {
+                    marker.needsUpdate = false;
+                    try {
+                        // TODO: with this it's currently not possible to remap markers from HTML. For example if I have two sections and I want to now use the marker["center"] multiple times to stay at that marker for a longer time
+                        marker.element = tryGetElementsForSelector(index) as HTMLElement | null;
+                        if (debug) console.debug(`ScrollMarker #${index} (${marker.time.toFixed(2)}) found`, marker.element);
+                        if (!marker.element) {
+                            if (debug || isDevEnvironment()) console.warn(`No HTML element found for ScrollMarker: ${marker.name} (index ${index})`);
+                            continue;
+                        }
                     }
-                    else {
-                        /** @ts-ignore */
-                        marker.timeline = new ViewTimeline({
-                            subject: marker.element,
-                            axis: 'block', // https://drafts.csswg.org/scroll-animations/#scroll-notation
-                        });
+                    catch (error) {
+                        marker.element = null;
+                        console.error("ScrollMarker selector is not valid: " + marker.name + "\n", error);
                     }
                 }
-                catch (error) {
-                    marker.element = null;
-                    console.error("ScrollMarker selector is not valid: " + marker.name + "\n", error);
-                }
-            }
 
-            // skip markers without element (e.g. if the selector didn't return any element)
-            if (!marker.element) continue;
+                // skip markers without element (e.g. if the selector didn't return any element)
+                if (!marker.element) continue;
 
-            markersArray.push(marker);
+                markersArray.push(marker);
+            }
 
-            const top = marker.element.offsetTop;
-            const height = marker.element.offsetHeight;
-            const bottom = top + height;
-            if (top < scrollRegionStart) {
-                scrollRegionStart = top;
+            // If the timeline has no markers defined we can use timeline-marker elements in the DOM. These must define times then
+            if (markersArray.length <= 0) {
+                const markers = document.querySelectorAll(`[data-timeline-marker]`);
+                markers.forEach((element) => {
+                    const value = element.getAttribute("data-timeline-marker");
+                    const time = parseFloat(value || ("NaN"));
+                    if (!isNaN(time)) {
+                        markersArray!.push({
+                            time,
+                            element: element as HTMLElement,
+                        });
+                    }
+                    else if (isDevEnvironment() || debug) {
+                        console.warn("[ScrollFollow] data-timeline-marker attribute is not a valid number. Supported are numbers only (e.g. <div data-timeline-marker=\"0.5\">)");
+                    }
+                });
             }
-            if (bottom > scrollRegionEnd) {
-                scrollRegionEnd = bottom;
+
+            // Init ViewTimeline for markers
+            for (const marker of markersArray) {
+                if (marker.element) {
+                    // https://scroll-driven-animations.style/tools/view-timeline/ranges
+                    /** @ts-ignore */
+                    marker.timeline = new ViewTimeline({
+                        subject: marker.element,
+                        axis: 'block', // https://drafts.csswg.org/scroll-animations/#scroll-notation
+                    });
+                }
             }
         }
 
 
-
-        const currentTop = this._scrollValue;
-        const currentBottom = currentTop + this._scrollContainerHeight;
-
         weightsArray.length = 0;
         let sum = 0;
         const oneFrameTime = 1 / 60;
@@ -374,7 +388,7 @@ export class ScrollFollow extends Behaviour {
                 const time01 = calculateTimelinePositionNormalized(timeline);
                 // remap 0-1 to 0 - 1 - 0 (full weight at center)
                 const weight = 1 - Math.abs(time01 - 0.5) * 2;
-                const name = marker.name || `marker${i}`;
+                const name = `marker${i}`;
                 if (time01 > 0 && time01 <= 1) {
                     const lerpTime = marker.time + (nextTime - marker.time) * time01;
                     weightsArray.push({ name, time: lerpTime, weight: weight });
@@ -391,38 +405,6 @@ export class ScrollFollow extends Behaviour {
                     sum += 1;
                 }
             }
-            continue;
-            // if(this.context.time.frame % 10 === 0) console.log(marker.element?.className, timeline, calculateTimelinePositionNormalized(timeline!));
-
-            // const top = marker.element.offsetTop - this._scrollContainerHeight;
-            // const height = marker.element.offsetHeight + this._scrollContainerHeight;
-            // const bottom = top + height;
-            // let overlap = 0;
-
-            // // TODO: if we have two marker sections where no HTML overlaps (vor example because some large section is between them) we probably want to still virtually interpolate between them slowly in that region
-
-            // if (bottom < currentTop) {
-            //     // marker is above scroll region
-            //     overlap = 0;
-            // }
-            // else if (top > currentBottom) {
-            //     // marker is below scroll region
-            //     overlap = 0;
-            // }
-            // else {
-            //     // calculate overlap in pixels
-            //     const overlapTop = Math.max(top, currentTop);
-            //     const overlapBottom = Math.min(bottom, currentBottom);
-            //     const height = Math.max(1, currentBottom - currentTop);
-            //     overlap = Math.max(0, overlapBottom - overlapTop);
-            // }
-
-            // // if(this.context.time.frame % 20 === 0) console.log(overlap)
-
-            // if (overlap > 0) {
-            //     weightsArray.push({ time: marker.time, weight: overlap });
-            //     sum += overlap;
-            // }
         }
 
         if (weightsArray.length <= 0 && markerCount <= 0) {
@@ -456,12 +438,14 @@ export class ScrollFollow extends Behaviour {
 }
 
 
+const timelineMarkerArrays: WeakMap<PlayableDirector,
+    Array<{
+        time: number,
+        element?: HTMLElement | null | undefined,
+        timeline?: ViewTimeline,
+    }>
+> = new WeakMap();
 
-const weightsArray: OverlapInfo[] = [];
-const markersArray: Array<ScrollMarkerModel & {
-    element?: HTMLElement | null,
-    timeline?: ViewTimeline,
-}> = [];
 
 type OverlapInfo = {
     name: string,
@@ -471,6 +455,8 @@ type OverlapInfo = {
     weight: number,
 }
 
+const weightsArray: OverlapInfo[] = [];
+
 
 // type SelectorCache = {
 //     /** The selector used to query the *elements */
@@ -480,41 +466,23 @@ type OverlapInfo = {
 // }
 // const querySelectorResults: Array<SelectorCache> = [];
 
-const needleScrollMarkerIndexCache = new Map<number, Element | null>();
-const needleScrollMarkerNameCache = new Map<string, Element | null>();
+const needleScrollMarkerCache = new Array<Element>();
 let needsScrollMarkerRefresh = true;
 
-function tryGetElementsForSelector(index: number, name: string, _cycle: number = 0): Element | null {
+function tryGetElementsForSelector(index: number): Element | null {
 
     if (!needsScrollMarkerRefresh) {
-        if (name?.length) {
-            const element = needleScrollMarkerNameCache.get(name) || null;
-            if (element) return element;
-            // const isNumber = !isNaN(Number(name));
-            // if (!isNumber) {
-            // }
-        }
-        const element = needleScrollMarkerIndexCache.get(index) || null;
-        const value = element?.getAttribute("data-timeline-marker");
-        // if (value?.length) {
-        //     if (cycle === 0) {
-        //         // if the HTML marker we found by index does define a different marker name we try to find the correct HTML element by name
-        //         return tryGetElementsForSelector(index, value, 1);
-        //     }
-        //     if (isDevEnvironment()) console.warn(`ScrollMarker name mismatch: expected "${name}", got "${value}"`);
-        // }
-        return element;
+        const element = needleScrollMarkerCache[index] || null;
+        if (element) return element;
     }
     needsScrollMarkerRefresh = false;
-    needleScrollMarkerIndexCache.clear();
+    needleScrollMarkerCache.length = 0;
     const markers = document.querySelectorAll(`[data-timeline-marker]`);
     markers.forEach((m, i) => {
-        needleScrollMarkerIndexCache.set(i, m);
-        const name = m.getAttribute("data-timeline-marker");
-        if (name?.length) needleScrollMarkerNameCache.set(name, m);
+        needleScrollMarkerCache[i] = m;
     });
     needsScrollMarkerRefresh = false;
-    return tryGetElementsForSelector(index, name);
+    return tryGetElementsForSelector(index);
 }