animejs 4.0.0 → 4.0.2

package/lib/anime.esm.js

@@ -1,6 +1,6 @@
 /**
  * anime.js - ESM
- * @version v4.0.0
+ * @version v4.0.2
  * @author Julian Garnier
  * @license MIT
  * @copyright (c) 2025 Julian Garnier
@@ -9,18 +9,18 @@
 
 /**
  * @typedef {Object} DefaultsParams
- * @property {number|string} [id]
+ * @property {Number|String} [id]
  * @property {PercentageKeyframes|DurationKeyframes} [keyframes]
  * @property {EasingParam} [playbackEase]
- * @property {number} [playbackRate]
- * @property {number} [frameRate]
- * @property {number|boolean} [loop]
- * @property {boolean} [reversed]
- * @property {boolean} [alternate]
- * @property {boolean|ScrollObserver} [autoplay]
- * @property {number|FunctionValue} [duration]
- * @property {number|FunctionValue} [delay]
- * @property {number} [loopDelay]
+ * @property {Number} [playbackRate]
+ * @property {Number} [frameRate]
+ * @property {Number|Boolean} [loop]
+ * @property {Boolean} [reversed]
+ * @property {Boolean} [alternate]
+ * @property {Boolean|ScrollObserver} [autoplay]
+ * @property {Number|FunctionValue} [duration]
+ * @property {Number|FunctionValue} [delay]
+ * @property {Number} [loopDelay]
  * @property {EasingParam} [ease]
  * @property {'none'|'replace'|'blend'|compositionTypes} [composition]
  * @property {(v: any) => any} [modifier]
@@ -38,6 +38,60 @@
 /** @typedef {Timer&JSAnimation&Timeline} CallbackArgument */
 /** @typedef {Animatable|Tickable|Draggable|ScrollObserver|Scope} Revertible */
 
+/**
+ * @typedef {Object} DraggableAxisParam
+ * @property {String} [mapTo]
+ * @property {TweenModifier} [modifier]
+ * @property {TweenComposition} [composition]
+ * @property {Number|Array<Number>|((draggable: Draggable) => Number|Array<Number>)} [snap]
+ */
+
+/**
+ * @typedef {Object} DraggableCursorParams
+ * @property {String} [onHover]
+ * @property {String} [onGrab]
+ */
+
+/**
+ * @typedef {Object} DraggableParams
+ * @property {DOMTargetSelector} [trigger]
+ * @property {DOMTargetSelector|Array<Number>|((draggable: Draggable) => DOMTargetSelector|Array<Number>)} [container]
+ * @property {Boolean|DraggableAxisParam} [x]
+ * @property {Boolean|DraggableAxisParam} [y]
+ * @property {TweenModifier} [modifier]
+ * @property {Number|Array<Number>|((draggable: Draggable) => Number|Array<Number>)} [snap]
+ * @property {Number|Array<Number>|((draggable: Draggable) => Number|Array<Number>)} [containerPadding]
+ * @property {Number|((draggable: Draggable) => Number)} [containerFriction]
+ * @property {Number|((draggable: Draggable) => Number)} [releaseContainerFriction]
+ * @property {Number|((draggable: Draggable) => Number)} [dragSpeed]
+ * @property {Number|((draggable: Draggable) => Number)} [scrollSpeed]
+ * @property {Number|((draggable: Draggable) => Number)} [scrollThreshold]
+ * @property {Number|((draggable: Draggable) => Number)} [minVelocity]
+ * @property {Number|((draggable: Draggable) => Number)} [maxVelocity]
+ * @property {Number|((draggable: Draggable) => Number)} [velocityMultiplier]
+ * @property {Number} [releaseMass]
+ * @property {Number} [releaseStiffness]
+ * @property {Number} [releaseDamping]
+ * @property {Boolean} [releaseDamping]
+ * @property {EasingParam} [releaseEase]
+ * @property {Boolean|DraggableCursorParams|((draggable: Draggable) => Boolean|DraggableCursorParams)} [cursor]
+ * @property {Callback<Draggable>} [onGrab]
+ * @property {Callback<Draggable>} [onDrag]
+ * @property {Callback<Draggable>} [onRelease]
+ * @property {Callback<Draggable>} [onUpdate]
+ * @property {Callback<Draggable>} [onSettle]
+ * @property {Callback<Draggable>} [onSnap]
+ * @property {Callback<Draggable>} [onResize]
+ * @property {Callback<Draggable>} [onAfterResize]
+ */
+
+/**
+ * @typedef {SVGGeometryElement & {
+ *   setAttribute(name: 'draw', value: `${number} ${number}`): void;
+ *   draw: `${number} ${number}`;
+ * }} DrawableSVGGeometry
+ */
+
 /**
  * @callback EasingFunction
  * @param {Number} time
@@ -450,7 +504,7 @@ const globals = {
   tickThreshold: 200,
 };
 
-const globalVersions = { version: '4.0.0', engine: null };
+const globalVersions = { version: '4.0.2', engine: null };
 
 if (isBrowser) {
   if (!win.AnimeJS) win.AnimeJS = [];
@@ -531,7 +585,6 @@ const atan2 = Math.atan2;
 const PI = Math.PI;
 const _round = Math.round;
 
-
 /**
  * @param  {Number} v
  * @param  {Number} min
@@ -580,7 +633,7 @@ const clampInfinity = v => v === Infinity ? maxValue : v === -Infinity ? -1e12 :
  * @param  {Number} v
  * @return {Number}
  */
-const clampZero = v => v < minValue ? minValue : v;
+const normalizeTime = v => v <= minValue ? minValue : clampInfinity(round(v, 11));
 
 // Arrays
 
@@ -1504,43 +1557,61 @@ const morphTo = (path2, precision = .33) => ($path1) => {
 };
 
 /**
- * @param {SVGGeometryElement} $el
- * @param {Number} start
- * @param {Number} end
- * @return {Proxy}
+ * @param {SVGGeometryElement} [$el]
+ * @return {Number}
  */
-function createDrawableProxy($el, start, end) {
-  const strokeLineCap = getComputedStyle($el).strokeLinecap;
+const getScaleFactor = $el => {
+  let scaleFactor = 1;
+  if ($el && $el.getCTM) {
+    const ctm = $el.getCTM();
+    if (ctm) {
+      const scaleX = sqrt(ctm.a * ctm.a + ctm.b * ctm.b);
+      const scaleY = sqrt(ctm.c * ctm.c + ctm.d * ctm.d);
+      scaleFactor = (scaleX + scaleY) / 2;
+    }
+  }
+  return scaleFactor;
+};
+
+/**
+ * Creates a proxy that wraps an SVGGeometryElement and adds drawing functionality.
+ * @param {SVGGeometryElement} $el - The SVG element to transform into a drawable
+ * @param {number} start - Starting position (0-1)
+ * @param {number} end - Ending position (0-1)
+ * @return {DrawableSVGGeometry} - Returns a proxy that preserves the original element's type with additional 'draw' attribute functionality
+ */
+const createDrawableProxy = ($el, start, end) => {
   const pathLength = K;
+  const computedStyles = getComputedStyle($el);
+  const strokeLineCap = computedStyles.strokeLinecap;
+  // @ts-ignore
+  const $scalled = computedStyles.vectorEffect === 'non-scaling-stroke' ? $el : null;
   let currentCap = strokeLineCap;
+
   const proxy = new Proxy($el, {
     get(target, property) {
       const value = target[property];
       if (property === proxyTargetSymbol) return target;
       if (property === 'setAttribute') {
-        /** @param {any[]} args */
         return (...args) => {
           if (args[0] === 'draw') {
             const value = args[1];
             const values = value.split(' ');
             const v1 = +values[0];
             const v2 = +values[1];
-
             // TOTO: Benchmark if performing two slices is more performant than one split
-
             // const spaceIndex = value.indexOf(' ');
             // const v1 = round(+value.slice(0, spaceIndex), precision);
             // const v2 = round(+value.slice(spaceIndex + 1), precision);
-
-            const os = v1 * -1e3;
-            const d1 = (v2 * pathLength) + os;
-            // Prevents linecap to smear by offsetting the dasharray length by 0.01% when v2 is not at max
-            const d2 = (pathLength + ((v1 === 0 && v2 === 1) || (v1 === 1 && v2 === 0) ? 0 : 10) - d1);
-            // Handle cases where the cap is still visible when the line is completly hidden
+            const scaleFactor = getScaleFactor($scalled);
+            const os = v1 * -1e3 * scaleFactor;
+            const d1 = (v2 * pathLength * scaleFactor) + os;
+            const d2 = (pathLength * scaleFactor +
+                      ((v1 === 0 && v2 === 1) || (v1 === 1 && v2 === 0) ? 0 : 10 * scaleFactor) - d1);
             if (strokeLineCap !== 'butt') {
               const newCap = v1 === v2 ? 'butt' : strokeLineCap;
               if (currentCap !== newCap) {
-                target.setAttribute('stroke-linecap', `${newCap}`);
+                target.style.strokeLinecap = `${newCap}`;
                 currentCap = newCap;
               }
             }
@@ -1550,31 +1621,37 @@ function createDrawableProxy($el, start, end) {
           return Reflect.apply(value, target, args);
         };
       }
+
       if (isFnc(value)) {
-        /** @param {any[]} args */
         return (...args) => Reflect.apply(value, target, args);
       } else {
         return value;
       }
     }
   });
+
   if ($el.getAttribute('pathLength') !== `${pathLength}`) {
     $el.setAttribute('pathLength', `${pathLength}`);
     proxy.setAttribute('draw', `${start} ${end}`);
   }
-  return /** @type {typeof Proxy} */(/** @type {unknown} */(proxy));
-}
+
+  return /** @type {DrawableSVGGeometry} */(proxy);
+};
 
 /**
- * @param {TargetsParam} selector
- * @param {Number} [start=0]
- * @param {Number} [end=0]
- * @return {Array.<Proxy>}
+ * Creates drawable proxies for multiple SVG elements.
+ * @param {TargetsParam} selector - CSS selector, SVG element, or array of elements and selectors
+ * @param {number} [start=0] - Starting position (0-1)
+ * @param {number} [end=0] - Ending position (0-1)
+ * @return {Array<DrawableSVGGeometry>} - Array of proxied elements with drawing functionality
  */
 const createDrawable = (selector, start = 0, end = 0) => {
-  const els = /** @type {Array.<Proxy>} */((/** @type {unknown} */(parseTargets(selector))));
-  els.forEach(($el, i) => els[i] = createDrawableProxy(/** @type {SVGGeometryElement} */(/** @type {unknown} */($el)), start, end));
-  return els;
+  const els = parseTargets(selector);
+  return els.map($el => createDrawableProxy(
+    /** @type {SVGGeometryElement} */($el),
+    start,
+    end
+  ));
 };
 
 // Motion path animation
@@ -2589,11 +2666,12 @@ class Timer extends Clock {
    */
   stretch(newDuration) {
     const currentDuration = this.duration;
-    if (currentDuration === clampZero(newDuration)) return this;
+    const normlizedDuration = normalizeTime(newDuration);
+    if (currentDuration === normlizedDuration) return this;
     const timeScale = newDuration / currentDuration;
     const isSetter = newDuration <= minValue;
-    this.duration = isSetter ? minValue : clampZero(clampInfinity(round(currentDuration * timeScale, 12)));
-    this.iterationDuration = isSetter ? minValue : clampZero(clampInfinity(round(this.iterationDuration * timeScale, 12)));
+    this.duration = isSetter ? minValue : normlizedDuration;
+    this.iterationDuration = isSetter ? minValue : normalizeTime(this.iterationDuration * timeScale);
     this._offset *= timeScale;
     this._delay *= timeScale;
     this._loopDelay *= timeScale;
@@ -3637,13 +3715,13 @@ class JSAnimation extends Timer {
    */
   stretch(newDuration) {
     const currentDuration = this.duration;
-    if (currentDuration === clampZero(newDuration)) return this;
+    if (currentDuration === normalizeTime(newDuration)) return this;
     const timeScale = newDuration / currentDuration;
     // NOTE: Find a better way to handle the stretch of an animation after stretch = 0
     forEachChildren(this, (/** @type {Tween} */tween) => {
       // Rounding is necessary here to minimize floating point errors
-      tween._updateDuration = clampZero(round(tween._updateDuration * timeScale, 12));
-      tween._changeDuration = clampZero(round(tween._changeDuration * timeScale, 12));
+      tween._updateDuration = normalizeTime(tween._updateDuration * timeScale);
+      tween._changeDuration = normalizeTime(tween._changeDuration * timeScale);
       tween._currentTime *= timeScale;
       tween._startTime *= timeScale;
       tween._absoluteStartTime *= timeScale;
@@ -3745,13 +3823,14 @@ const parseWAAPIEasing = (ease) => {
       const parsed = parseEaseString(ease, WAAPIeases, WAAPIEasesLookups);
       if (isFnc(parsed)) parsedEase = parsed === none ? 'linear' : easingToLinear(parsed);
     }
+    WAAPIEasesLookups[ease] = parsedEase;
   } else if (isFnc(ease)) {
     const easing = easingToLinear(ease);
     if (easing) parsedEase = easing;
   } else if (/** @type {Spring} */(ease).ease) {
     parsedEase = easingToLinear(/** @type {Spring} */(ease).ease);
   }
-  return WAAPIEasesLookups[ease] = parsedEase;
+  return parsedEase;
 };
 
 /**
@@ -3825,6 +3904,7 @@ const validIndividualTransforms = [...transformsShorthands, ...validTransforms.f
 let transformsPropertiesRegistered = isBrowser && (isUnd(CSS) || !Object.hasOwnProperty.call(CSS, 'registerProperty'));
 
 const registerTransformsProperties = () => {
+  if (transformsPropertiesRegistered) return;
   validTransforms.forEach(t => {
     const isSkew = stringStartsWith(t, 'skew');
     const isScale = stringStartsWith(t, 'scale');
@@ -3832,13 +3912,14 @@ const registerTransformsProperties = () => {
     const isTranslate = stringStartsWith(t, 'translate');
     const isAngle = isRotate || isSkew;
     const syntax = isAngle ? '<angle>' : isScale ? "<number>" : isTranslate ? "<length-percentage>" : "*";
-    CSS.registerProperty({
-      name: '--' + t,
-      syntax,
-      inherits: false,
-      initialValue: isTranslate ? '0px' : isAngle ? '0deg' : isScale ? '1' : '0',
-    });
-  });
+    try {
+      CSS.registerProperty({
+        name: '--' + t,
+        syntax,
+        inherits: false,
+        initialValue: isTranslate ? '0px' : isAngle ? '0deg' : isScale ? '1' : '0',
+      });
+    } catch {}  });
   transformsPropertiesRegistered = true;
 };
 
@@ -3953,7 +4034,7 @@ class WAAPIAnimation {
 
     if (globals.scope) globals.scope.revertibles.push(this);
 
-    if (!transformsPropertiesRegistered) registerTransformsProperties();
+    registerTransformsProperties();
 
     const parsedTargets = registerTargets(targets);
     const targetsLength = parsedTargets.length;
@@ -4120,7 +4201,13 @@ class WAAPIAnimation {
   /** @param {Number} time */
   set currentTime(time) {
     const t = time * (globals.timeScale === 1 ? 1 : K);
-    this.forEach(anim => anim.currentTime = t);
+    this.forEach(anim => {
+      // Make sure the animation playState is not 'paused' in order to properly trigger an onfinish callback.
+      // The "paused" play state supersedes the "finished" play state; if the animation is both paused and finished, the "paused" state is the one that will be reported.
+      // https://developer.mozilla.org/en-US/docs/Web/API/Animation/finish_event
+      if (t >= this.duration) anim.play();
+      anim.currentTime = t;
+    });
   }
 
   get progress() {
@@ -4907,15 +4994,11 @@ class Timeline extends Timer {
    */
   stretch(newDuration) {
     const currentDuration = this.duration;
-    if (currentDuration === clampZero(newDuration)) return this;
+    if (currentDuration === normalizeTime(newDuration)) return this;
     const timeScale = newDuration / currentDuration;
     const labels = this.labels;
-    forEachChildren(this, (/** @type {JSAnimation} */child) => {
-      child.stretch(child.duration * timeScale);
-    });
-    for (let labelName in labels) {
-      labels[labelName] *= timeScale;
-    }
+    forEachChildren(this, (/** @type {JSAnimation} */child) => child.stretch(child.duration * timeScale));
+    for (let labelName in labels) labels[labelName] *= timeScale;
     return super.stretch(newDuration);
   }
 
@@ -5281,12 +5364,6 @@ class Transforms {
   }
 }
 
-/**
- * @typedef {Object} DraggableCursorParams
- * @property {String} [onHover]
- * @property {String} [onGrab]
- */
-
 /**
  * @template {Array<Number>|DOMTargetSelector|String|Number|Boolean|Function|DraggableCursorParams} T
  * @param {T | ((draggable: Draggable) => T)} value
@@ -5297,47 +5374,6 @@ const parseDraggableFunctionParameter = (value, draggable) => value && isFnc(val
 
 let zIndex = 0;
 
-/**
- * @typedef {Object} DraggableAxisParam
- * @property {String} [mapTo]
- * @property {TweenModifier} [modifier]
- * @property {TweenComposition} [composition]
- * @property {Number|Array<Number>|((draggable: Draggable) => Number|Array<Number>)} [snap]
- */
-
-/**
- * @typedef {Object} DraggableParams
- * @property {DOMTargetSelector} [trigger]
- * @property {DOMTargetSelector|Array<Number>|((draggable: Draggable) => DOMTargetSelector|Array<Number>)} [container]
- * @property {Boolean|DraggableAxisParam} [x]
- * @property {Boolean|DraggableAxisParam} [y]
- * @property {TweenModifier} [modifier]
- * @property {Number|Array<Number>|((draggable: Draggable) => Number|Array<Number>)} [snap]
- * @property {Number|Array<Number>|((draggable: Draggable) => Number|Array<Number>)} [containerPadding]
- * @property {Number|((draggable: Draggable) => Number)} [containerFriction]
- * @property {Number|((draggable: Draggable) => Number)} [releaseContainerFriction]
- * @property {Number|((draggable: Draggable) => Number)} [dragSpeed]
- * @property {Number|((draggable: Draggable) => Number)} [scrollSpeed]
- * @property {Number|((draggable: Draggable) => Number)} [scrollThreshold]
- * @property {Number|((draggable: Draggable) => Number)} [minVelocity]
- * @property {Number|((draggable: Draggable) => Number)} [maxVelocity]
- * @property {Number|((draggable: Draggable) => Number)} [velocityMultiplier]
- * @property {Number} [releaseMass]
- * @property {Number} [releaseStiffness]
- * @property {Number} [releaseDamping]
- * @property {Boolean} [releaseDamping]
- * @property {EasingParam} [releaseEase]
- * @property {Boolean|DraggableCursorParams|((draggable: Draggable) => Boolean|DraggableCursorParams)} [cursor]
- * @property {Callback<Draggable>} [onGrab]
- * @property {Callback<Draggable>} [onDrag]
- * @property {Callback<Draggable>} [onRelease]
- * @property {Callback<Draggable>} [onUpdate]
- * @property {Callback<Draggable>} [onSettle]
- * @property {Callback<Draggable>} [onSnap]
- * @property {Callback<Draggable>} [onResize]
- * @property {Callback<Draggable>} [onAfterResize]
- */
-
 class Draggable {
   /**
    * @param {TargetsParam} target
@@ -5536,7 +5572,7 @@ class Draggable {
     this.canScroll = false;
     this.enabled = false;
     this.initialized = false;
-    this.activeProp = this.disabled[0] ? yProp : xProp;
+    this.activeProp = this.disabled[1] ? xProp : yProp;
     this.animate.animations[this.activeProp].onRender = () => {
       const hasUpdated = this.updated;
       const hasMoved = this.grabbed && hasUpdated;
@@ -6356,6 +6392,7 @@ class Draggable {
     this.overshootXTicker.revert();
     this.overshootYTicker.revert();
     this.resizeTicker.revert();
+    this.animate.revert();
     return this;
   }
 
@@ -6407,7 +6444,7 @@ const createDraggable = (target, parameters) => new Draggable(target, parameters
 
 /**
  * @typedef {Object} ReactRef
- * @property {HTMLElement|SVGElement} [current]
+ * @property {HTMLElement|SVGElement|null} [current]
  */
 
 /**