animejs 4.2.0 → 4.2.2

package/dist/bundles/anime.umd.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - UMD bundle
- * @version v4.2.0
+ * @version v4.2.2
  * @license MIT
  * @copyright 2025 - Julian Garnier
  */
@@ -385,10 +385,6 @@
  * @typedef {WAAPITweenValue|WAAPIFunctionValue|Array<String|Number|WAAPIFunctionValue>} WAAPIKeyframeValue
  */
 
-/**
- * @typedef {Callback<WAAPIAnimation>} WAAPICallback
- */
-
 /**
  * @typedef {Object} WAAPITweenOptions
  * @property {WAAPIKeyframeValue} [to]
@@ -411,11 +407,11 @@
  * @property {WAAPIEasingParam} [ease]
  * @property {CompositeOperation} [composition]
  * @property {Boolean} [persist]
- * @property {WAAPICallback} [onComplete]
+ * @property {Callback<WAAPIAnimation>} [onComplete]
  */
 
 /**
- * @typedef {Record<String, WAAPIKeyframeValue | WAAPIAnimationOptions | Boolean | ScrollObserver | WAAPICallback | WAAPIEasingParam | WAAPITweenOptions> & WAAPIAnimationOptions} WAAPIAnimationParams
+ * @typedef {Record<String, WAAPIKeyframeValue | WAAPIAnimationOptions | Boolean | ScrollObserver | Callback<WAAPIAnimation> | WAAPIEasingParam | WAAPITweenOptions> & WAAPIAnimationOptions} WAAPIAnimationParams
  */
 
 // Animatable types
@@ -558,6 +554,12 @@
  * @property {String} [onGrab]
  */
 
+/**
+ * @typedef {Object} DraggableDragThresholdParams
+ * @property {Number} [mouse]
+ * @property {Number} [touch]
+ */
+
 /**
  * @typedef {Object} DraggableParams
  * @property {DOMTargetSelector} [trigger]
@@ -570,6 +572,7 @@
  * @property {Number|((draggable: Draggable) => Number)} [containerFriction]
  * @property {Number|((draggable: Draggable) => Number)} [releaseContainerFriction]
  * @property {Number|((draggable: Draggable) => Number)} [dragSpeed]
+ * @property {Number|DraggableDragThresholdParams|((draggable: Draggable) => Number|DraggableDragThresholdParams)} [dragThreshold]
  * @property {Number|((draggable: Draggable) => Number)} [scrollSpeed]
  * @property {Number|((draggable: Draggable) => Number)} [scrollThreshold]
  * @property {Number|((draggable: Draggable) => Number)} [minVelocity]
@@ -799,7 +802,7 @@
     tickThreshold: 200,
   };
 
-  const globalVersions = { version: '4.2.0', engine: null };
+  const globalVersions = { version: '4.2.2', engine: null };
 
   if (isBrowser) {
     if (!win.AnimeJS) win.AnimeJS = [];
@@ -2486,7 +2489,7 @@
     if (timer._hasChildren) {
       forEachChildren(timer, reviveTimer);
     } else {
-      forEachChildren(timer, (/** @type {Tween} tween*/tween) => {
+      forEachChildren(timer, (/** @type {Tween} tween */tween) => {
         if (tween._composition !== compositionTypes.none) {
           composeTween(tween, getTweenSiblings(tween.target, tween.property));
         }
@@ -2543,7 +2546,6 @@
                                   /** @type {Number} */(timerLoop) < 0 ? Infinity :
                                   /** @type {Number} */(timerLoop) + 1;
 
-
       let offsetPosition = 0;
 
       if (parent) {
@@ -2633,7 +2635,7 @@
     }
 
     set cancelled(cancelled) {
-      cancelled ? this.cancel() : this.reset(1).play();
+      cancelled ? this.cancel() : this.reset(true).play();
     }
 
     get currentTime() {
@@ -2698,10 +2700,10 @@
     }
 
     /**
-     * @param  {Number} internalRender
+     * @param  {Boolean} [softReset]
      * @return {this}
      */
-    reset(internalRender = 0) {
+    reset(softReset = false) {
       // If cancelled, revive the timer before rendering in order to have propertly composed tweens siblings
       reviveTimer(this);
       if (this._reversed && !this._reverse) this.reversed = false;
@@ -2710,7 +2712,7 @@
       // NOTE: This is only required for Timelines and might be better to move to the Timeline class?
       this._iterationTime = this.iterationDuration;
       // Set tickMode to tickModes.FORCE to force rendering
-      tick(this, 0, 1, internalRender, tickModes.FORCE);
+      tick(this, 0, 1, ~~softReset, tickModes.FORCE);
       // Reset timer properties after revive / render to make sure the props are not updated again
       resetTimerProperties(this);
       // Also reset children properties
@@ -2721,16 +2723,16 @@
     }
 
     /**
-     * @param  {Number} internalRender
+     * @param  {Boolean} internalRender
      * @return {this}
      */
-    init(internalRender = 0) {
+    init(internalRender = false) {
       this.fps = this._fps;
       this.speed = this._speed;
       // Manually calling .init() on timelines should render all children intial state
       // Forces all children to render once then render to 0 when reseted
       if (!internalRender && this._hasChildren) {
-        tick(this, this.duration, 1, internalRender, tickModes.FORCE);
+        tick(this, this.duration, 1, ~~internalRender, tickModes.FORCE);
       }
       this.reset(internalRender);
       // Make sure to set autoplay to false to child timers so it doesn't attempt to autoplay / link
@@ -2784,7 +2786,7 @@
 
     /** @return {this} */
     restart() {
-      return this.reset(0).resume();
+      return this.reset().resume();
     }
 
     /**
@@ -2887,8 +2889,12 @@
     }
 
     /**
-     * @param  {Callback<this>} [callback]
-     * @return {Promise}
+     * @typedef {this & {then: null}} ResolvedTimer
+     */
+
+    /**
+     * @param  {Callback<ResolvedTimer>} [callback]
+     * @return Promise<this>
      */
     then(callback = noop) {
       const then = this.then;
@@ -2896,7 +2902,7 @@
         // this.then = null prevents infinite recursion if returned by an async function
         // https://github.com/juliangarnierorg/anime-beta/issues/26
         this.then = null;
-        callback(this);
+        callback(/** @type {ResolvedTimer} */(this));
         this.then = then;
         this._resolve = noop;
       };
@@ -3845,8 +3851,12 @@
     }
 
     /**
-     * @param  {Callback<this>} [callback]
-     * @return {Promise}
+     * @typedef {this & {then: null}} ResolvedJSAnimation
+     */
+
+    /**
+     * @param  {Callback<ResolvedJSAnimation>} [callback]
+     * @return Promise<this>
      */
     then(callback) {
       return super.then(callback);
@@ -4117,7 +4127,7 @@
     const tlChild = targets ?
       new JSAnimation(targets,/** @type {AnimationParams} */(childParams), tl, adjustedPosition, false, index, length) :
       new Timer(/** @type {TimerParams} */(childParams), tl, adjustedPosition);
-    tlChild.init(1);
+    tlChild.init(true);
     // TODO: Might be better to insert at a position relative to startTime?
     addChild(tl, tlChild);
     forEachChildren(tl, (/** @type {Renderable} */child) => {
@@ -4221,7 +4231,7 @@
             parseTimelinePosition(this,a2),
           );
         }
-        return this.init(1); // 1 = internalRender
+        return this.init(true);
       }
     }
 
@@ -4330,8 +4340,12 @@
     }
 
     /**
-     * @param  {Callback<this>} [callback]
-     * @return {Promise}
+     * @typedef {this & {then: null}} ResolvedTimeline
+     */
+
+    /**
+     * @param  {Callback<ResolvedTimeline>} [callback]
+     * @return Promise<this>
      */
     then(callback) {
       return super.then(callback);
@@ -4441,7 +4455,7 @@
               tween._currentTime = 0;
             });
             if (!isUnd(duration)) animation.stretch(duration);
-            animation.reset(1).resume();
+            animation.reset(true).resume();
             return this;
           }
         };
@@ -4902,7 +4916,7 @@
   }
 
   /**
-   * @template {Array<Number>|DOMTargetSelector|String|Number|Boolean|Function|DraggableCursorParams} T
+   * @template {Array<Number>|DOMTargetSelector|String|Number|Boolean|Function|DraggableCursorParams|DraggableDragThresholdParams} T
    * @param {T | ((draggable: Draggable) => T)} value
    * @param {Draggable} draggable
    * @return {T}
@@ -4956,6 +4970,8 @@
       /** @type {Number} */
       this.dragSpeed = 0;
       /** @type {Number} */
+      this.dragThreshold = 3;
+      /** @type {Number} */
       this.maxVelocity = 0;
       /** @type {Number} */
       this.minVelocity = 0;
@@ -5373,6 +5389,16 @@
         if (onHover) cursorStyles.onHover = onHover;
         if (onGrab) cursorStyles.onGrab = onGrab;
       }
+      const parsedDragThreshold = parseDraggableFunctionParameter(params.dragThreshold, this);
+      const dragThreshold = { mouse: 3, touch: 7 };
+      if (isNum(parsedDragThreshold)) {
+        dragThreshold.mouse = parsedDragThreshold;
+        dragThreshold.touch = parsedDragThreshold;
+      } else if (parsedDragThreshold) {
+        const { mouse, touch } = parsedDragThreshold;
+        if (!isUnd(mouse)) dragThreshold.mouse = mouse;
+        if (!isUnd(touch)) dragThreshold.touch = touch;
+      }
       this.containerArray = isArr(container) ? container : null;
       this.$container = /** @type {HTMLElement} */(container && !this.containerArray ? parseTargets(/** @type {DOMTarget} */(container))[0] : doc.body);
       this.useWin = this.$container === doc.body;
@@ -5387,6 +5413,7 @@
       this.scrollSpeed = setValue(parseDraggableFunctionParameter(params.scrollSpeed, this), 1.5);
       this.scrollThreshold = setValue(parseDraggableFunctionParameter(params.scrollThreshold, this), 20);
       this.dragSpeed = setValue(parseDraggableFunctionParameter(params.dragSpeed, this), 1);
+      this.dragThreshold = this.isFinePointer ? dragThreshold.mouse : dragThreshold.touch;
       this.minVelocity = setValue(parseDraggableFunctionParameter(params.minVelocity, this), 0);
       this.maxVelocity = setValue(parseDraggableFunctionParameter(params.maxVelocity, this), 50);
       this.velocityMultiplier = setValue(parseDraggableFunctionParameter(params.velocityMultiplier, this), 1);
@@ -5688,8 +5715,7 @@
         this.$trigger.addEventListener('touchend', preventDefault);
 
         // Don't check for a miminim distance move if already dragging
-        if (this.dragged || (!this.disabled[0] && abs(movedX) > 3) || (!this.disabled[1] && abs(movedY) > 3)) {
-
+        if (this.dragged || (!this.disabled[0] && abs(movedX) > this.dragThreshold) || (!this.disabled[1] && abs(movedY) > this.dragThreshold)) {
           this.updateTicker.resume();
           this.pointer[2] = this.pointer[0];
           this.pointer[3] = this.pointer[1];
@@ -6278,6 +6304,8 @@
       /** @type {Number} */
       this.top = 0;
       /** @type {Number} */
+      this.scale = 1;
+      /** @type {Number} */
       this.zIndex = 0;
       /** @type {Number} */
       this.scrollX = 0;
@@ -6389,6 +6417,7 @@
         height = $el.clientHeight;
         this.top = elRect.top;
         this.left = elRect.left;
+        this.scale = elRect.width ? width / elRect.width : (elRect.height ? height / elRect.height : 1);
       }
       this.width = width;
       this.height = height;
@@ -6914,8 +6943,9 @@
         }
       }
       const rect = $target.getBoundingClientRect();
-      const offset = isHori ? rect.left + container.scrollX - container.left : rect.top + container.scrollY - container.top;
-      const targetSize = isHori ? rect.width : rect.height;
+      const scale = container.scale;
+      const offset = (isHori ? rect.left + container.scrollX - container.left : rect.top + container.scrollY - container.top) * scale;
+      const targetSize = (isHori ? rect.width : rect.height) * scale;
       const containerSize = isHori ? container.width : container.height;
       const scrollSize = isHori ? container.scrollWidth : container.scrollHeight;
       const maxScroll = scrollSize - containerSize;
@@ -7629,36 +7659,46 @@
 
   /**
    * @param {SVGGeometryElement} $path
+   * @param {Number} totalLength
    * @param {Number} progress
-   * @param {Number}lookup
+   * @param {Number} lookup
+   * @param {Boolean} shouldClamp
    * @return {DOMPoint}
    */
-  const getPathPoint = ($path, progress, lookup = 0) => {
-    return $path.getPointAtLength(progress + lookup >= 1 ? progress + lookup : 0);
+  const getPathPoint = ($path, totalLength, progress, lookup, shouldClamp) => {
+    const point = progress + lookup;
+    const pointOnPath = shouldClamp
+      ? Math.max(0, Math.min(point, totalLength)) // Clamp between 0 and totalLength
+      : (point % totalLength + totalLength) % totalLength; // Wrap around
+    return $path.getPointAtLength(pointOnPath);
   };
 
   /**
    * @param {SVGGeometryElement} $path
    * @param {String} pathProperty
+   * @param {Number} [offset=0]
    * @return {FunctionValue}
    */
-  const getPathProgess = ($path, pathProperty) => {
+  const getPathProgess = ($path, pathProperty, offset = 0) => {
     return $el => {
       const totalLength = +($path.getTotalLength());
       const inSvg = $el[isSvgSymbol];
       const ctm = $path.getCTM();
+      const shouldClamp = offset === 0;
       /** @type {TweenObjectValue} */
       return {
         from: 0,
         to: totalLength,
         /** @type {TweenModifier} */
         modifier: progress => {
+          const offsetLength = offset * totalLength;
+          const newProgress = progress + offsetLength;
           if (pathProperty === 'a') {
-            const p0 = getPathPoint($path, progress, -1);
-            const p1 = getPathPoint($path, progress, 1);
+            const p0 = getPathPoint($path, totalLength, newProgress, -1, shouldClamp);
+            const p1 = getPathPoint($path, totalLength, newProgress, 1, shouldClamp);
             return atan2(p1.y - p0.y, p1.x - p0.x) * 180 / PI;
           } else {
-            const p = getPathPoint($path, progress, 0);
+            const p = getPathPoint($path, totalLength, newProgress, 0, shouldClamp);
             return pathProperty === 'x' ?
               inSvg || !ctm ? p.x : p.x * ctm.a + p.y * ctm.c + ctm.e :
               inSvg || !ctm ? p.y : p.x * ctm.b + p.y * ctm.d + ctm.f
@@ -7670,14 +7710,15 @@
 
   /**
    * @param {TargetsParam} path
+   * @param {Number} [offset=0]
    */
-  const createMotionPath = path => {
+  const createMotionPath = (path, offset = 0) => {
     const $path = getPath(path);
     if (!$path) return;
     return {
-      translateX: getPathProgess($path, 'x'),
-      translateY: getPathProgess($path, 'y'),
-      rotate: getPathProgess($path, 'a'),
+      translateX: getPathProgess($path, 'x', offset),
+      translateY: getPathProgess($path, 'y', offset),
+      rotate: getPathProgess($path, 'a', offset),
     }
   };
 
@@ -7789,8 +7830,18 @@
    * @return {FunctionValue}
    */
   const morphTo = (path2, precision = .33) => ($path1) => {
+    const tagName1 = ($path1.tagName || '').toLowerCase();
+    if (!tagName1.match(/^(path|polygon|polyline)$/)) {
+      throw new Error(`Can't morph a <${$path1.tagName}> SVG element. Use <path>, <polygon> or <polyline>.`);
+    }
     const $path2 = /** @type {SVGGeometryElement} */(getPath(path2));
-    if (!$path2) return;
+    if (!$path2) {
+      throw new Error("Can't morph to an invalid target. 'path2' must resolve to an existing <path>, <polygon> or <polyline> SVG element.");
+    }
+    const tagName2 = ($path2.tagName || '').toLowerCase();
+    if (!tagName2.match(/^(path|polygon|polyline)$/)) {
+      throw new Error(`Can't morph a <${$path2.tagName}> SVG element. Use <path>, <polygon> or <polyline>.`);
+    }
     const isPath = $path1.tagName === 'path';
     const separator = isPath ? ' ' : ',';
     const previousPoints = $path1[morphPointsSymbol];
@@ -8716,14 +8767,18 @@
     }
 
     /**
-     * @param  {WAAPICallback} [callback]
-     * @return {Promise}
+     * @typedef {this & {then: null}} ResolvedWAAPIAnimation
+     */
+
+    /**
+     * @param  {Callback<ResolvedWAAPIAnimation>} [callback]
+     * @return Promise<this>
      */
     then(callback = noop) {
       const then = this.then;
       const onResolve = () => {
         this.then = null;
-        callback(this);
+        callback(/** @type {ResolvedWAAPIAnimation} */(this));
         this.then = then;
         this._resolve = noop;
       };