@pixodesk/svg-animator-web 1.0.27 → 1.0.28

package/dist/index.cjs

@@ -1316,6 +1316,12 @@ var PxScrollSchema = implementsInterface()(px.object({
   kind: px.enum(["view", "scroll"]).optional(),
   axis: px.enum(["block", "inline", "x", "y"]).optional(),
   source: px.enum(["nearest", "root"]).optional(),
+  // Free-form: the two keywords `parent`/`scroller` plus any CSS selector.
+  subject: px.string().optional(),
+  smoothing: px.number().optional(),
+  pin: px.boolean().optional(),
+  pinTop: px.number().optional(),
+  pinDistance: px.number().optional(),
   range: PxScrollRangeSchema.optional()
 }));
 var PxAnimatorConfigSchema = implementsInterface()(px.object({
@@ -6540,6 +6546,10 @@ function createNativeScrollTimeline(subject, config) {
   if (!config || !isScrollTimeline(config)) return null;
   const scroll = config.scroll || {};
   const kind = (_a = scroll.kind) != null ? _a : "view";
+  if (scroll.smoothing) {
+    console.warn('scroll timeline: `smoothing` needs the built-in driver \u2014 ignoring `driver: "native"`');
+    return null;
+  }
   const g = globalThis;
   const view = kind === "view";
   const Ctor = view ? g.ViewTimeline : g.ScrollTimeline;
@@ -6548,7 +6558,7 @@ function createNativeScrollTimeline(subject, config) {
   let timeline;
   try {
     if (view) {
-      timeline = new Ctor({ subject, axis });
+      timeline = new Ctor({ subject: resolveScrollSubject(subject, scroll.subject), axis });
     } else {
       const source = scroll.source === "root" ? documentScroller() : findNearestScroller(subject, "y") || findNearestScroller(subject, "x") || documentScroller();
       timeline = new Ctor({ source, axis });
@@ -6564,7 +6574,10 @@ function createNativeScrollTimeline(subject, config) {
   };
 }
 function findNearestScroller(el, axis) {
+  const body = document.body;
+  const root = document.documentElement;
   for (let p = el.parentElement; p; p = p.parentElement) {
+    if (p === body || p === root) return null;
     const style = getComputedStyle(p);
     const overflow = axis === "y" ? style.overflowY : style.overflowX;
     if (overflow === "auto" || overflow === "scroll" || overflow === "hidden" || overflow === "overlay") {
@@ -6576,11 +6589,42 @@ function findNearestScroller(el, axis) {
 function documentScroller() {
   return document.scrollingElement || document.documentElement;
 }
+var SUBJECT_PARENT = "parent";
+var SUBJECT_SCROLLER = "scroller";
+function resolveScrollSubject(svgRoot, subject) {
+  var _a, _b;
+  const spec = subject == null ? void 0 : subject.trim();
+  if (!spec) return svgRoot;
+  if (spec === SUBJECT_PARENT) {
+    let outermostPinned = null;
+    for (let p = svgRoot.parentElement; p && p !== document.body; p = p.parentElement) {
+      const position = getComputedStyle(p).position;
+      if (position === "sticky" || position === "fixed") outermostPinned = p;
+    }
+    return (_b = (_a = outermostPinned == null ? void 0 : outermostPinned.parentElement) != null ? _a : svgRoot.parentElement) != null ? _b : svgRoot;
+  }
+  if (spec === SUBJECT_SCROLLER) {
+    return findNearestScroller(svgRoot, "y") || findNearestScroller(svgRoot, "x") || documentScroller();
+  }
+  let found = null;
+  try {
+    found = document.querySelector(spec);
+  } catch (e) {
+    console.warn('scroll timeline: subject "' + spec + '" is not a valid selector \u2014 measuring the SVG itself');
+    return svgRoot;
+  }
+  if (!found) {
+    console.warn('scroll timeline: subject "' + spec + '" matched no element \u2014 measuring the SVG itself');
+    return svgRoot;
+  }
+  return found;
+}
 function createScrollDriver(subject, config, onProgress) {
-  var _a;
+  var _a, _b;
   if (!config || !isScrollTimeline(config)) return null;
   const scroll = config.scroll || {};
   const kind = (_a = scroll.kind) != null ? _a : "view";
+  const measured = resolveScrollSubject(subject, scroll.subject);
   const nearest = findNearestScroller(subject, "y") || findNearestScroller(subject, "x");
   const scroller = kind === "scroll" && scroll.source === "root" ? documentScroller() : nearest || documentScroller();
   const isRootScroller = scroller === documentScroller();
@@ -6591,7 +6635,7 @@ function createScrollDriver(subject, config, onProgress) {
       const maxOffset = axis === "y" ? scroller.scrollHeight - scroller.clientHeight : scroller.scrollWidth - scroller.clientWidth;
       return scrollOffsetProgress(offset, maxOffset, scroll.range);
     }
-    const subjectRect = subject.getBoundingClientRect();
+    const subjectRect = measured.getBoundingClientRect();
     let portStart, portSize;
     if (isRootScroller) {
       portStart = 0;
@@ -6605,12 +6649,43 @@ function createScrollDriver(subject, config, onProgress) {
     const subjectSize = axis === "y" ? subjectRect.height : subjectRect.width;
     return scrollViewProgress(subjectStart, subjectSize, portSize, scroll.range);
   };
-  let rafId = null;
+  const smoothingSec = Math.max(0, (_b = scroll.smoothing) != null ? _b : 0) / 1e3;
+  const SETTLE_EPSILON = 1e-3;
   let destroyed = false;
+  let smoothed = null;
+  let smoothRaf = null;
+  let lastFrameMs = 0;
+  const emit = (target) => {
+    if (!smoothingSec) {
+      onProgress(target);
+      return;
+    }
+    if (smoothed === null) {
+      smoothed = target;
+      onProgress(target);
+      return;
+    }
+    if (smoothRaf !== null) return;
+    lastFrameMs = 0;
+    const step = (nowMs) => {
+      smoothRaf = null;
+      if (destroyed) return;
+      const dtSec = lastFrameMs ? Math.min(0.1, (nowMs - lastFrameMs) / 1e3) : 1 / 60;
+      lastFrameMs = nowMs;
+      const goal = compute();
+      const k = 1 - Math.exp(-dtSec / smoothingSec);
+      smoothed = smoothed + (goal - smoothed) * k;
+      if (Math.abs(goal - smoothed) < SETTLE_EPSILON) smoothed = goal;
+      onProgress(smoothed);
+      if (smoothed !== goal) smoothRaf = requestAnimationFrame(step);
+    };
+    smoothRaf = requestAnimationFrame(step);
+  };
+  let rafId = null;
   const tick = () => {
     rafId = null;
     if (destroyed) return;
-    onProgress(compute());
+    emit(compute());
   };
   const schedule = () => {
     if (destroyed || rafId !== null) return;
@@ -6622,7 +6697,8 @@ function createScrollDriver(subject, config, onProgress) {
   let resizeObserver;
   if (typeof ResizeObserver !== "undefined") {
     resizeObserver = new ResizeObserver(schedule);
-    resizeObserver.observe(subject);
+    resizeObserver.observe(measured);
+    if (measured !== subject) resizeObserver.observe(subject);
     if (!isRootScroller) resizeObserver.observe(scroller);
   }
   const driver = {
@@ -6636,14 +6712,50 @@ function createScrollDriver(subject, config, onProgress) {
         cancelAnimationFrame(rafId);
         rafId = null;
       }
+      if (smoothRaf !== null) {
+        cancelAnimationFrame(smoothRaf);
+        smoothRaf = null;
+      }
     },
+    // `refresh` is a deliberate JUMP (attach, host relayout) — never eased.
     refresh: () => {
-      if (!destroyed) onProgress(compute());
+      if (!destroyed) {
+        smoothed = compute();
+        onProgress(smoothed);
+      }
     }
   };
   driver.refresh();
   return driver;
 }
+function applyScrollPin(svgRoot, scroll) {
+  var _a;
+  const styled = svgRoot;
+  if (!(scroll == null ? void 0 : scroll.pin) || !styled.style) return () => {
+  };
+  const style = styled.style;
+  const prevPosition = style.position;
+  const prevTop = style.top;
+  style.position = "sticky";
+  style.top = ((_a = scroll.pinTop) != null ? _a : 0) + "px";
+  let wrapper = null;
+  const parent = svgRoot.parentElement;
+  if (scroll.pinDistance && scroll.pinDistance > 0 && parent) {
+    wrapper = document.createElement("div");
+    wrapper.setAttribute("data-px-pin", "");
+    wrapper.style.height = scroll.pinDistance * 100 + "vh";
+    parent.insertBefore(wrapper, svgRoot);
+    wrapper.appendChild(svgRoot);
+  }
+  return () => {
+    style.position = prevPosition;
+    style.top = prevTop;
+    if (wrapper == null ? void 0 : wrapper.parentElement) {
+      wrapper.parentElement.insertBefore(svgRoot, wrapper);
+      wrapper.remove();
+    }
+  };
+}
 
 // src/PxAnimatorBind.ts
 function finaliseAnimator(animatorConfig, callbacks, make) {
@@ -6670,7 +6782,10 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
   if (isScrollTimeline(animatorConfig)) {
     return finaliseAnimator(animatorConfig, callbacks, (cb) => {
       var _a, _b;
+      let unpin = () => {
+      };
       if (animatorConfig.mode !== PxAnimatorMode.frames && ((_a = animatorConfig.scroll) == null ? void 0 : _a.driver) === "native" && rootElement) {
+        unpin = applyScrollPin(rootElement, animatorConfig.scroll);
         const native = createNativeScrollTimeline(rootElement, animatorConfig);
         if (native) {
           const api2 = createWebApiAnimator(
@@ -6680,12 +6795,23 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
             animatorConfig.mode === PxAnimatorMode.waapi,
             native
           );
-          if (api2) return api2;
+          if (api2) {
+            const destroyNative = api2.destroy.bind(api2);
+            api2.destroy = () => {
+              unpin();
+              destroyNative();
+            };
+            return api2;
+          }
         }
+        unpin();
+        unpin = () => {
+        };
       }
       const api = (animatorConfig.mode !== PxAnimatorMode.frames ? createWebApiAnimator(doc, cb, rootElement, animatorConfig.mode === PxAnimatorMode.waapi) : null) || createFrameLoopAnimator(doc, adapter, cb, rootElement);
       const subject = ((_b = api.getRootElement) == null ? void 0 : _b.call(api)) || rootElement;
       if (subject) {
+        unpin = applyScrollPin(subject, animatorConfig.scroll);
         const totalMs = scrollTotalDurationMs(animatorConfig);
         const driver = createScrollDriver(
           subject,
@@ -6696,6 +6822,7 @@ function bindWithEngineChoice(doc, adapter, callbacks, rootElement) {
           const destroy = api.destroy.bind(api);
           api.destroy = () => {
             driver.destroy();
+            unpin();
             destroy();
           };
         }