animejs 4.3.5 → 4.4.0

package/dist/modules/types/index.d.ts

@@ -27,12 +27,12 @@ export type Renderable = JSAnimation | Timeline;
 export type Tickable = Timer | Renderable;
 export type CallbackArgument = Timer & JSAnimation & Timeline;
 export type Revertible = Animatable | Tickable | WAAPIAnimation | Draggable | ScrollObserver | TextSplitter | Scope | AutoLayout;
-export type StaggerFunction<T> = (target?: Target, index?: number, length?: number, tl?: Timeline) => T;
+export type StaggerFunction<T> = (target?: Target, index?: number, targets?: TargetsArray, prevTween?: Tween | null, tl?: Timeline) => T;
 export type StaggerParams = {
     start?: number | string;
-    from?: number | "first" | "center" | "last" | "random";
+    from?: number | "first" | "center" | "last" | "random" | Array<number>;
     reversed?: boolean;
-    grid?: Array<number>;
+    grid?: Array<number> | boolean;
     axis?: ("x" | "y");
     use?: string | ((target: Target, i: number, length: number) => number);
     total?: number;
@@ -57,8 +57,8 @@ export type PowerEasing = (power?: number | string) => EasingFunction;
 export type BackEasing = (overshoot?: number | string) => EasingFunction;
 export type ElasticEasing = (amplitude?: number | string, period?: number | string) => EasingFunction;
 export type EasingFunctionWithParams = PowerEasing | BackEasing | ElasticEasing;
-export type EasingParam = (string & {}) | EaseStringParamNames | EasingFunction | Spring;
-export type WAAPIEasingParam = (string & {}) | EaseStringParamNames | WAAPIEaseStringParamNames | EasingFunction | Spring;
+export type EasingParam = (string & {}) | EaseStringParamNames | EasingFunction | Spring | TweakRegister;
+export type WAAPIEasingParam = (string & {}) | EaseStringParamNames | WAAPIEaseStringParamNames | EasingFunction | Spring | TweakRegister;
 export type SpringParams = {
     /**
      * - Mass, default 1
@@ -112,9 +112,10 @@ export type TimerOptions = {
     autoplay?: boolean | ScrollObserver;
     frameRate?: number;
     playbackRate?: number;
+    priority?: number;
 };
 export type TimerParams = TimerOptions & TickableCallbacks<Timer>;
-export type FunctionValue = (target: Target, index: number, length: number) => number | string | TweenObjectValue | EasingParam | Array<number | string | TweenObjectValue>;
+export type FunctionValue = (target?: Target, index?: number, targets?: TargetsArray, prevTween?: Tween | null) => number | string | TweenObjectValue | EasingParam | Array<number | string | TweenObjectValue>;
 export type TweenModifier = (value: number) => number | string;
 export type ColorArray = [number, number, number, number];
 export type Tween = {
@@ -246,7 +247,7 @@ export type TimelinePosition = number | `+=${number}` | `-=${number}` | `*=${num
  * - `'label'` - Label: Position animation at a named label position (e.g., `'My Label'`)<br>
  * - `stagger(String|Nummber)` - Stagger multi-elements animation positions (e.g., 10, 20, 30...)
  */
-export type TimelineAnimationPosition = TimelinePosition | StaggerFunction<number | string>;
+export type TimelineAnimationPosition = TimelinePosition | StaggerFunction<number | string> | TweakRegister;
 export type TimelineOptions = {
     defaults?: DefaultsParams;
     playbackEase?: EasingParam;
@@ -254,7 +255,7 @@ export type TimelineOptions = {
 };
 export type TimelineParams = TimerOptions & TimelineOptions & TickableCallbacks<Timeline> & RenderableCallbacks<Timeline>;
 export type WAAPITweenValue = string | number | Array<string> | Array<number>;
-export type WAAPIFunctionValue = (target: DOMTarget, index: number, length: number) => WAAPITweenValue | WAAPIEasingParam;
+export type WAAPIFunctionValue = (target: DOMTarget, index: number, targets: DOMTargetsArray) => WAAPITweenValue | WAAPIEasingParam;
 export type WAAPIKeyframeValue = WAAPITweenValue | WAAPIFunctionValue | Array<string | number | WAAPIFunctionValue>;
 export type WAAPITweenOptions = {
     to?: WAAPIKeyframeValue;
@@ -392,6 +393,72 @@ export type TextSplitterParams = {
     includeSpaces?: boolean;
     debug?: boolean;
 };
+export type ScrambleTextParams = {
+    /**
+     * - the text to transition to, otherwise uses the original text
+     */
+    text?: string | ((arg0: Target, arg1: number, arg2: TargetsArray) => string);
+    /**
+     * - the characters used for scramble; named sets: 'lowercase', 'uppercase', 'numbers', 'symbols', 'braille', 'blocks', 'shades'; range syntax: 'A-Z', 'a-z0-9'; defaults to 'a-zA-Z0-9!%#_'
+     */
+    chars?: string | ((arg0: Target, arg1: number, arg2: TargetsArray) => string);
+    /**
+     * - the easing applied to the scramble animation
+     */
+    ease?: EasingParam;
+    /**
+     * - where the reveal wave starts from, 'auto' (default) uses 'left' when text grows and 'right' when it shrinks
+     */
+    from?: number | "left" | "center" | "right" | "random" | "auto";
+    /**
+     * - reverses the reveal order, so 'center' reveals from edges inward instead of center outward
+     */
+    reversed?: boolean;
+    /**
+     * - characters displayed at the leading edge of the reveal wave; true uses '_', a number is a char code, a string is used directly
+     */
+    cursor?: boolean | number | string;
+    /**
+     * - adds random timing offsets to each character's start and end, creating a more organic reveal
+     */
+    perturbation?: number;
+    /**
+     * - a seed for the random number generator to produce reproducible scramble sequences
+     */
+    seed?: number;
+    /**
+     * - controls the starting appearance: false shows original text, true scrambles it (default), '' starts from blank, ' ' replaces characters with spaces, a custom string (supports range syntax like 'A-Z') uses its characters as scramble set
+     */
+    override?: boolean | string;
+    /**
+     * - characters per second entering the active zone; higher values make the reveal wave move faster (default: 60)
+     */
+    revealRate?: number;
+    /**
+     * - time in ms each character spends scrambling before settling into its final glyph (default: 300)
+     */
+    settleDuration?: number;
+    /**
+     * - how many times per second scramble characters cycle in the active zone (default: 30)
+     */
+    settleRate?: number;
+    /**
+     * - if set to a value greater than 0, overrides the computed duration from interval and settle; if unset or 0, duration is calculated automatically from text length and timing parameters
+     */
+    duration?: number | ((arg0: Target, arg1: number, arg2: TargetsArray) => number);
+    /**
+     * - delay in ms before the reveal wave starts within the scramble animation
+     */
+    revealDelay?: number | ((arg0: Target, arg1: number, arg2: TargetsArray) => number);
+    /**
+     * - delay in ms before the entire scramble animation starts
+     */
+    delay?: number | ((arg0: Target, arg1: number, arg2: TargetsArray) => number);
+    /**
+     * - callback fired each time a character changes during scramble; receives the current scrambled text and the eased progress (0-1)
+     */
+    onChange?: (arg0: string, arg1: number) => void;
+};
 export type DrawableSVGGeometry = SVGGeometryElement & {
     setAttribute(name: "draw", value: `${number} ${number}`): void;
     draw: `${number} ${number}`;
@@ -408,5 +475,6 @@ import type { TextSplitter } from '../text/split.js';
 import type { Scope } from '../scope/scope.js';
 import type { AutoLayout } from '../layout/layout.js';
 import type { Spring } from '../easings/spring/index.js';
+import type { TweakRegister } from 'tweaks';
 import type { tweenTypes } from '../core/consts.js';
 import type { valueTypes } from '../core/consts.js';

package/dist/modules/utils/chainable.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -36,10 +36,13 @@ const chain = fn => {
     const result = fn(...args);
     return new Proxy(consts.noop, {
       apply: (_, __, [v]) => result(v),
-      get: (_, prop) => chain(/**@param {...Number|String} nextArgs */(...nextArgs) => {
-        const nextResult = chainables[prop](...nextArgs);
-        return (/**@type {Number|String} */v) => nextResult(result(v));
-      })
+      get: (_, prop) => {
+        if (!chainables[prop]) return undefined;
+        return chain(/**@param {...Number|String} nextArgs */(...nextArgs) => {
+          const nextResult = chainables[prop](...nextArgs);
+          return (/**@type {Number|String} */v) => nextResult(result(v));
+        })
+      }
     });
   }
 };

package/dist/modules/utils/chainable.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -34,10 +34,13 @@ const chain = fn => {
     const result = fn(...args);
     return new Proxy(noop, {
       apply: (_, __, [v]) => result(v),
-      get: (_, prop) => chain(/**@param {...Number|String} nextArgs */(...nextArgs) => {
-        const nextResult = chainables[prop](...nextArgs);
-        return (/**@type {Number|String} */v) => nextResult(result(v));
-      })
+      get: (_, prop) => {
+        if (!chainables[prop]) return undefined;
+        return chain(/**@param {...Number|String} nextArgs */(...nextArgs) => {
+          const nextResult = chainables[prop](...nextArgs);
+          return (/**@type {Number|String} */v) => nextResult(result(v));
+        })
+      }
     });
   }
 };

package/dist/modules/utils/index.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -12,6 +12,7 @@ var random = require('./random.cjs');
 var time = require('./time.cjs');
 var target = require('./target.cjs');
 var stagger = require('./stagger.cjs');
+var helpers = require('../core/helpers.cjs');
 var styles = require('../core/styles.cjs');
 var targets = require('../core/targets.cjs');
 
@@ -39,5 +40,8 @@ exports.get = target.get;
 exports.remove = target.remove;
 exports.set = target.set;
 exports.stagger = stagger.stagger;
+exports.addChild = helpers.addChild;
+exports.forEachChildren = helpers.forEachChildren;
+exports.removeChild = helpers.removeChild;
 exports.cleanInlineStyles = styles.cleanInlineStyles;
 exports.$ = targets.registerTargets;

package/dist/modules/utils/index.d.ts

@@ -3,3 +3,4 @@ export * from "./random.js";
 export * from "./time.js";
 export * from "./target.js";
 export * from "./stagger.js";
+export { forEachChildren, addChild, removeChild } from "../core/helpers.js";

package/dist/modules/utils/index.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -10,5 +10,6 @@ export { createSeededRandom, random, randomPick, shuffle } from './random.js';
 export { keepTime, sync } from './time.js';
 export { get, remove, set } from './target.js';
 export { stagger } from './stagger.js';
+export { addChild, forEachChildren, removeChild } from '../core/helpers.js';
 export { cleanInlineStyles } from '../core/styles.js';
 export { registerTargets as $ } from '../core/targets.js';

package/dist/modules/utils/number.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/utils/number.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/utils/random.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/utils/random.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/utils/stagger.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.3.5
+ * @version v4.4.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -19,6 +19,7 @@ var random = require('./random.cjs');
  * @import {
  *   StaggerParams,
  *   StaggerFunction,
+ *   JSTarget,
  * } from '../types/index.js'
 */
 
@@ -34,24 +35,28 @@ var random = require('./random.cjs');
  * @param {StaggerParams} [params]
  * @return {StaggerFunction<Number>}
  */
+
 /**
  * @overload
  * @param {String} val
  * @param {StaggerParams} [params]
  * @return {StaggerFunction<String>}
  */
+
 /**
  * @overload
  * @param {[Number, Number]} val
  * @param {StaggerParams} [params]
  * @return {StaggerFunction<Number>}
  */
+
 /**
  * @overload
  * @param {[String, String]} val
  * @param {StaggerParams} [params]
  * @return {StaggerFunction<String>}
  */
+
 /**
  * @param {Number|String|[Number, Number]|[String, String]} val The staggered value or range
  * @param {StaggerParams} [params] The stagger parameters
@@ -60,6 +65,7 @@ var random = require('./random.cjs');
 const stagger = (val, params = {}) => {
   let values$1 = [];
   let maxValue = 0;
+  let cachedOffset;
   const from = params.from;
   const reversed = params.reversed;
   const ease = params.ease;
@@ -67,12 +73,14 @@ const stagger = (val, params = {}) => {
   const hasSpring = hasEasing && !helpers.isUnd(/** @type {Spring} */(ease).ease);
   const staggerEase = hasSpring ? /** @type {Spring} */(ease).ease : hasEasing ? parser.parseEase(ease) : null;
   const grid = params.grid;
+  const autoGrid = grid === true;
   const axis = params.axis;
   const customTotal = params.total;
   const fromFirst = helpers.isUnd(from) || from === 0 || from === 'first';
   const fromCenter = from === 'center';
   const fromLast = from === 'last';
   const fromRandom = from === 'random';
+  const fromArr = helpers.isArr(from);
   const isRange = helpers.isArr(val);
   const useProp = params.use;
   const val1 = isRange ? helpers.parseNumber(val[0]) : helpers.parseNumber(val);
@@ -80,40 +88,129 @@ const stagger = (val, params = {}) => {
   const unitMatch = consts.unitsExecRgx.exec((isRange ? val[1] : val) + consts.emptyString);
   const start = params.start || 0 + (isRange ? val1 : 0);
   let fromIndex = fromFirst ? 0 : helpers.isNum(from) ? from : 0;
-  return (target, i, t, tl) => {
+  return (target, i, t, _, tl) => {
     const [ registeredTarget ] = targets.registerTargets(target);
-    const total = helpers.isUnd(customTotal) ? t : customTotal;
+    const total = helpers.isUnd(customTotal) ? t.length : customTotal;
     const customIndex = !helpers.isUnd(useProp) ? helpers.isFnc(useProp) ? useProp(registeredTarget, i, total) : values.getOriginalAnimatableValue(registeredTarget, useProp) : false;
     const staggerIndex = helpers.isNum(customIndex) || helpers.isStr(customIndex) && helpers.isNum(+customIndex) ? +customIndex : i;
     if (fromCenter) fromIndex = (total - 1) / 2;
     if (fromLast) fromIndex = total - 1;
     if (!values$1.length) {
-      for (let index = 0; index < total; index++) {
-        if (!grid) {
-          values$1.push(helpers.abs(fromIndex - index));
+      if (autoGrid) {
+        let hasPositions = true;
+        let minPosX = Infinity;
+        let minPosY = Infinity;
+        let maxPosX = -Infinity;
+        let maxPosY = -Infinity;
+        const pxArr = [];
+        const pyArr = [];
+        for (let index = 0; index < total; index++) {
+          const el = t[index];
+          let px = 0;
+          let py = 0;
+          let found = false;
+          if (el && helpers.isFnc(el.getBoundingClientRect)) {
+            const rect = el.getBoundingClientRect();
+            px = rect.left + rect.width / 2;
+            py = rect.top + rect.height / 2;
+            found = true;
+          } else {
+            const obj = /** @type {JSTarget} */(el);
+            if (obj && helpers.isNum(obj.x) && helpers.isNum(obj.y)) {
+              px = obj.x;
+              py = obj.y;
+              found = true;
+            }
+          }
+          if (!found) {
+            hasPositions = false;
+            break;
+          }
+          pxArr.push(px);
+          pyArr.push(py);
+          if (px < minPosX) minPosX = px;
+          if (py < minPosY) minPosY = py;
+          if (px > maxPosX) maxPosX = px;
+          if (py > maxPosY) maxPosY = py;
+        }
+        if (hasPositions) {
+          let fX = pxArr[0];
+          let fY = pyArr[0];
+          if (fromArr) {
+            fX = minPosX + from[0] * (maxPosX - minPosX);
+            fY = minPosY + from[1] * (maxPosY - minPosY);
+          } else if (fromCenter) {
+            fX = (minPosX + maxPosX) / 2;
+            fY = (minPosY + maxPosY) / 2;
+          } else if (fromLast) {
+            fX = pxArr[total - 1];
+            fY = pyArr[total - 1];
+          } else if (helpers.isNum(from)) {
+            fX = pxArr[from];
+            fY = pyArr[from];
+          }
+          for (let index = 0; index < total; index++) {
+            const distanceX = fX - pxArr[index];
+            const distanceY = fY - pyArr[index];
+            let value = helpers.sqrt(distanceX * distanceX + distanceY * distanceY);
+            if (axis === 'x') value = -distanceX;
+            if (axis === 'y') value = -distanceY;
+            values$1.push(value);
+          }
+          let minDist = Infinity;
+          for (let index = 0, l = values$1.length; index < l; index++) {
+            const absVal = helpers.abs(values$1[index]);
+            if (absVal > 0 && absVal < minDist) minDist = absVal;
+          }
+          if (minDist > 0 && minDist < Infinity) {
+            for (let index = 0, l = values$1.length; index < l; index++) {
+              values$1[index] = values$1[index] / minDist;
+            }
+          }
         } else {
-          const fromX = !fromCenter ? fromIndex % grid[0] : (grid[0] - 1) / 2;
-          const fromY = !fromCenter ? helpers.floor(fromIndex / grid[0]) : (grid[1] - 1) / 2;
-          const toX = index % grid[0];
-          const toY = helpers.floor(index / grid[0]);
-          const distanceX = fromX - toX;
-          const distanceY = fromY - toY;
-          let value = helpers.sqrt(distanceX * distanceX + distanceY * distanceY);
-          if (axis === 'x') value = -distanceX;
-          if (axis === 'y') value = -distanceY;
-          values$1.push(value);
+          for (let index = 0; index < total; index++) {
+            values$1.push(helpers.abs(fromIndex - index));
+          }
+        }
+      } else {
+        for (let index = 0; index < total; index++) {
+          if (!grid) {
+            values$1.push(helpers.abs(fromIndex - index));
+          } else {
+            let fromX, fromY;
+            if (fromArr) {
+              fromX = from[0] * (grid[0] - 1);
+              fromY = from[1] * (grid[1] - 1);
+            } else if (fromCenter) {
+              fromX = (grid[0] - 1) / 2;
+              fromY = (grid[1] - 1) / 2;
+            } else {
+              fromX = fromIndex % grid[0];
+              fromY = helpers.floor(fromIndex / grid[0]);
+            }
+            const toX = index % grid[0];
+            const toY = helpers.floor(index / grid[0]);
+            const distanceX = fromX - toX;
+            const distanceY = fromY - toY;
+            let value = helpers.sqrt(distanceX * distanceX + distanceY * distanceY);
+            if (axis === 'x') value = -distanceX;
+            if (axis === 'y') value = -distanceY;
+            values$1.push(value);
+          }
         }
-        maxValue = helpers.max(...values$1);
       }
+      maxValue = helpers.max(...values$1);
       if (staggerEase) values$1 = values$1.map(val => staggerEase(val / maxValue) * maxValue);
       if (reversed) values$1 = values$1.map(val => axis ? (val < 0) ? val * -1 : -val : helpers.abs(maxValue - val));
       if (fromRandom) values$1 = random.shuffle(values$1);
     }
     const spacing = isRange ? (val2 - val1) / maxValue : val1;
-    const offset = tl ? position.parseTimelinePosition(tl, helpers.isUnd(params.start) ? tl.iterationDuration : start) : /** @type {Number} */(start);
+    if (helpers.isUnd(cachedOffset)) {
+      cachedOffset = tl ? position.parseTimelinePosition(tl, helpers.isUnd(params.start) ? tl.iterationDuration : start) : /** @type {Number} */(start);
+    }
     /** @type {String|Number} */
-    let output = offset + ((spacing * helpers.round(values$1[staggerIndex], 2)) || 0);
-    if (params.modifier) output = params.modifier(output);
+    let output = cachedOffset + ((spacing * helpers.round(values$1[staggerIndex], 2)) || 0);
+    if (params.modifier) output = params.modifier(/** @type {Number} */(output));
     if (unitMatch) output = `${output}${unitMatch[2]}`;
     return output;
   }