animejs 4.1.2 → 4.2.0-beta.0

package/dist/modules/utils/random.js

@@ -0,0 +1,72 @@
+/**
+ * Anime.js - utils - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+/**
+ * Generate a random number between optional min and max (inclusive) and decimal precision
+ *
+ * @callback RandomNumberGenerator
+ * @param    {Number} [min=0] - The minimum value (inclusive)
+ * @param    {Number} [max=1] - The maximum value (inclusive)
+ * @param    {Number} [decimalLength=0] - Number of decimal places to round to
+ * @return   {Number} A random number between min and max
+ */
+
+/**
+ * Generates a random number between min and max (inclusive) with optional decimal precision
+ *
+ * @type {RandomNumberGenerator}
+ */
+const random = (min = 0, max = 1, decimalLength = 0) => {
+  const m = 10 ** decimalLength;
+  return Math.floor((Math.random() * (max - min + (1 / m)) + min) * m) / m;
+};
+
+let _seed = 0;
+
+/**
+ * Creates a seeded pseudorandom number generator function
+ *
+ * @param  {Number} [seed] - The seed value for the random number generator
+ * @param  {Number} [seededMin=0] - The minimum default value (inclusive) of the returned function
+ * @param  {Number} [seededMax=1] - The maximum default value (inclusive) of the returned function
+ * @param  {Number} [seededDecimalLength=0] - Default number of decimal places to round to of the returned function
+ * @return {RandomNumberGenerator} A function to generate a random number between optional min and max (inclusive) and decimal precision
+ */
+const createSeededRandom = (seed, seededMin = 0, seededMax = 1, seededDecimalLength = 0) => {
+  let t = seed === undefined ? _seed++ : seed;
+  return (min = seededMin, max = seededMax, decimalLength = seededDecimalLength) => {
+    t += 0x6D2B79F5;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    const m = 10 ** decimalLength;
+    return Math.floor(((((t ^ t >>> 14) >>> 0) / 4294967296) * (max - min + (1 / m)) + min) * m) / m;
+  }
+};
+
+/**
+ * Picks a random element from an array or a string
+ *
+ * @template T
+ * @param    {String|Array<T>} items - The array or string to pick from
+ * @return   {String|T} A random element from the array or character from the string
+ */
+const randomPick = items => items[random(0, items.length - 1)];
+
+/**
+ * Shuffles an array in-place using the Fisher-Yates algorithm
+ * Adapted from https://bost.ocks.org/mike/shuffle/
+ *
+ * @param  {Array} items - The array to shuffle (will be modified in-place)
+ * @return {Array} The same array reference, now shuffled
+ */
+const shuffle = items => {
+  let m = items.length, t, i;
+  while (m) { i = random(0, --m); t = items[m]; items[m] = items[i]; items[i] = t; }
+  return items;
+};
+
+export { createSeededRandom, random, randomPick, shuffle };

package/dist/modules/utils/stagger.cjs

@@ -0,0 +1,122 @@
+/**
+ * Anime.js - utils - CJS
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+'use strict';
+
+var consts = require('../core/consts.cjs');
+var helpers = require('../core/helpers.cjs');
+var eases = require('../easings/eases.cjs');
+var position = require('../timeline/position.cjs');
+var values = require('../core/values.cjs');
+var targets = require('../core/targets.cjs');
+var random = require('./random.cjs');
+
+/**
+ * @import {
+ *   StaggerParams,
+ *   StaggerFunction,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @import {
+ *   Spring,
+ * } from '../spring/spring.js'
+*/
+
+/**
+ * @overload
+ * @param {Number} val
+ * @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
+ * @return {StaggerFunction<Number|String>}
+ */
+const stagger = (val, params = {}) => {
+  let values$1 = [];
+  let maxValue = 0;
+  const from = params.from;
+  const reversed = params.reversed;
+  const ease = params.ease;
+  const hasEasing = !helpers.isUnd(ease);
+  const hasSpring = hasEasing && !helpers.isUnd(/** @type {Spring} */(ease).ease);
+  const staggerEase = hasSpring ? /** @type {Spring} */(ease).ease : hasEasing ? eases.parseEase(ease) : null;
+  const grid = params.grid;
+  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 isRange = helpers.isArr(val);
+  const useProp = params.use;
+  const val1 = isRange ? helpers.parseNumber(val[0]) : helpers.parseNumber(val);
+  const val2 = isRange ? helpers.parseNumber(val[1]) : 0;
+  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) => {
+    const [ registeredTarget ] = targets.registerTargets(target);
+    const total = helpers.isUnd(customTotal) ? t : 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));
+        } 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);
+        }
+        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);
+    /** @type {String|Number} */
+    let output = offset + ((spacing * helpers.round(values$1[staggerIndex], 2)) || 0);
+    if (params.modifier) output = params.modifier(output);
+    if (unitMatch) output = `${output}${unitMatch[2]}`;
+    return output;
+  }
+};
+
+exports.stagger = stagger;

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

@@ -0,0 +1,30 @@
+/**
+ * @overload
+ * @param {Number} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<Number>}
+ */
+export function stagger(val: number, params?: StaggerParams): StaggerFunction<number>;
+/**
+ * @overload
+ * @param {String} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<String>}
+ */
+export function stagger(val: string, params?: StaggerParams): StaggerFunction<string>;
+/**
+ * @overload
+ * @param {[Number, Number]} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<Number>}
+ */
+export function stagger(val: [number, number], params?: StaggerParams): StaggerFunction<number>;
+/**
+ * @overload
+ * @param {[String, String]} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<String>}
+ */
+export function stagger(val: [string, string], params?: StaggerParams): StaggerFunction<string>;
+import type { StaggerParams } from '../types/index.js';
+import type { StaggerFunction } from '../types/index.js';

package/dist/modules/utils/stagger.js

@@ -0,0 +1,120 @@
+/**
+ * Anime.js - utils - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { unitsExecRgx, emptyString } from '../core/consts.js';
+import { isUnd, parseNumber, isFnc, abs, floor, sqrt, round, isArr, isNum, isStr, max } from '../core/helpers.js';
+import { parseEase } from '../easings/eases.js';
+import { parseTimelinePosition } from '../timeline/position.js';
+import { getOriginalAnimatableValue } from '../core/values.js';
+import { registerTargets } from '../core/targets.js';
+import { shuffle } from './random.js';
+
+/**
+ * @import {
+ *   StaggerParams,
+ *   StaggerFunction,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @import {
+ *   Spring,
+ * } from '../spring/spring.js'
+*/
+
+/**
+ * @overload
+ * @param {Number} val
+ * @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
+ * @return {StaggerFunction<Number|String>}
+ */
+const stagger = (val, params = {}) => {
+  let values = [];
+  let maxValue = 0;
+  const from = params.from;
+  const reversed = params.reversed;
+  const ease = params.ease;
+  const hasEasing = !isUnd(ease);
+  const hasSpring = hasEasing && !isUnd(/** @type {Spring} */(ease).ease);
+  const staggerEase = hasSpring ? /** @type {Spring} */(ease).ease : hasEasing ? parseEase(ease) : null;
+  const grid = params.grid;
+  const axis = params.axis;
+  const customTotal = params.total;
+  const fromFirst = isUnd(from) || from === 0 || from === 'first';
+  const fromCenter = from === 'center';
+  const fromLast = from === 'last';
+  const fromRandom = from === 'random';
+  const isRange = isArr(val);
+  const useProp = params.use;
+  const val1 = isRange ? parseNumber(val[0]) : parseNumber(val);
+  const val2 = isRange ? parseNumber(val[1]) : 0;
+  const unitMatch = unitsExecRgx.exec((isRange ? val[1] : val) + emptyString);
+  const start = params.start || 0 + (isRange ? val1 : 0);
+  let fromIndex = fromFirst ? 0 : isNum(from) ? from : 0;
+  return (target, i, t, tl) => {
+    const [ registeredTarget ] = registerTargets(target);
+    const total = isUnd(customTotal) ? t : customTotal;
+    const customIndex = !isUnd(useProp) ? isFnc(useProp) ? useProp(registeredTarget, i, total) : getOriginalAnimatableValue(registeredTarget, useProp) : false;
+    const staggerIndex = isNum(customIndex) || isStr(customIndex) && isNum(+customIndex) ? +customIndex : i;
+    if (fromCenter) fromIndex = (total - 1) / 2;
+    if (fromLast) fromIndex = total - 1;
+    if (!values.length) {
+      for (let index = 0; index < total; index++) {
+        if (!grid) {
+          values.push(abs(fromIndex - index));
+        } else {
+          const fromX = !fromCenter ? fromIndex % grid[0] : (grid[0] - 1) / 2;
+          const fromY = !fromCenter ? floor(fromIndex / grid[0]) : (grid[1] - 1) / 2;
+          const toX = index % grid[0];
+          const toY = floor(index / grid[0]);
+          const distanceX = fromX - toX;
+          const distanceY = fromY - toY;
+          let value = sqrt(distanceX * distanceX + distanceY * distanceY);
+          if (axis === 'x') value = -distanceX;
+          if (axis === 'y') value = -distanceY;
+          values.push(value);
+        }
+        maxValue = max(...values);
+      }
+      if (staggerEase) values = values.map(val => staggerEase(val / maxValue) * maxValue);
+      if (reversed) values = values.map(val => axis ? (val < 0) ? val * -1 : -val : abs(maxValue - val));
+      if (fromRandom) values = shuffle(values);
+    }
+    const spacing = isRange ? (val2 - val1) / maxValue : val1;
+    const offset = tl ? parseTimelinePosition(tl, isUnd(params.start) ? tl.iterationDuration : start) : /** @type {Number} */(start);
+    /** @type {String|Number} */
+    let output = offset + ((spacing * round(values[staggerIndex], 2)) || 0);
+    if (params.modifier) output = params.modifier(output);
+    if (unitMatch) output = `${output}${unitMatch[2]}`;
+    return output;
+  }
+};
+
+export { stagger };

package/dist/modules/utils/target.cjs

@@ -0,0 +1,130 @@
+/**
+ * Anime.js - utils - CJS
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+'use strict';
+
+var globals = require('../core/globals.cjs');
+var consts = require('../core/consts.cjs');
+var helpers = require('../core/helpers.cjs');
+var targets = require('../core/targets.cjs');
+var styles = require('../core/styles.cjs');
+var values = require('../core/values.cjs');
+var units = require('../core/units.cjs');
+var composition = require('../waapi/composition.cjs');
+var composition$1 = require('../animation/composition.cjs');
+var animation = require('../animation/animation.cjs');
+
+/**
+ * @import {
+ *   Renderable,
+ *   DOMTargetSelector,
+ *   JSTargetsParam,
+ *   DOMTargetsParam,
+ *   TargetsParam,
+ *   DOMTarget,
+ *   AnimationParams,
+ *   TargetsArray,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @import {
+ *   WAAPIAnimation
+ * } from '../waapi/waapi.js'
+*/
+
+/**
+ * @overload
+ * @param  {DOMTargetSelector} targetSelector
+ * @param  {String} propName
+ * @return {String}
+ *
+ * @overload
+ * @param  {JSTargetsParam} targetSelector
+ * @param  {String} propName
+ * @return {Number|String}
+ *
+ * @overload
+ * @param  {DOMTargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String} unit
+ * @return {String}
+ *
+ * @overload
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {Boolean} unit
+ * @return {Number}
+ *
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String|Boolean} [unit]
+ */
+function get(targetSelector, propName, unit) {
+  const targets$1 = targets.registerTargets(targetSelector);
+  if (!targets$1.length) return;
+  const [ target ] = targets$1;
+  const tweenType = values.getTweenType(target, propName);
+  const normalizePropName = styles.sanitizePropertyName(propName, target, tweenType);
+  let originalValue = values.getOriginalAnimatableValue(target, normalizePropName);
+  if (helpers.isUnd(unit)) {
+    return originalValue;
+  } else {
+    values.decomposeRawValue(originalValue, values.decomposedOriginalValue);
+    if (values.decomposedOriginalValue.t === consts.valueTypes.NUMBER || values.decomposedOriginalValue.t === consts.valueTypes.UNIT) {
+      if (unit === false) {
+        return values.decomposedOriginalValue.n;
+      } else {
+        const convertedValue = units.convertValueUnit(/** @type {DOMTarget} */(target), values.decomposedOriginalValue, /** @type {String} */(unit), false);
+        return `${helpers.round(convertedValue.n, globals.globals.precision)}${convertedValue.u}`;
+      }
+    }
+  }
+}
+
+/**
+ * @param  {TargetsParam} targets
+ * @param  {AnimationParams} parameters
+ * @return {JSAnimation}
+ */
+const set = (targets, parameters) => {
+  if (helpers.isUnd(parameters)) return;
+  parameters.duration = consts.minValue;
+  // Do not overrides currently active tweens by default
+  parameters.composition = values.setValue(parameters.composition, consts.compositionTypes.none);
+  // Skip init() and force rendering by playing the animation
+  return new animation.JSAnimation(targets, parameters, null, 0, true).resume();
+};
+
+/**
+ * @param  {TargetsParam} targets
+ * @param  {Renderable|WAAPIAnimation} [renderable]
+ * @param  {String} [propertyName]
+ * @return {TargetsArray}
+ */
+const remove = (targets$1, renderable, propertyName) => {
+  const targetsArray = targets.parseTargets(targets$1);
+  for (let i = 0, l = targetsArray.length; i < l; i++) {
+    composition.removeWAAPIAnimation(
+      /** @type {DOMTarget}  */(targetsArray[i]),
+      propertyName,
+      renderable && /** @type {WAAPIAnimation} */(renderable).controlAnimation && /** @type {WAAPIAnimation} */(renderable),
+    );
+  }
+  composition$1.removeTargetsFromRenderable(
+    targetsArray,
+    /** @type {Renderable} */(renderable),
+    propertyName
+  );
+  return targetsArray;
+};
+
+exports.$ = targets.registerTargets;
+exports.cleanInlineStyles = styles.cleanInlineStyles;
+exports.get = get;
+exports.remove = remove;
+exports.set = set;

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

@@ -0,0 +1,126 @@
+/**
+ * @overload
+ * @param  {DOMTargetSelector} targetSelector
+ * @param  {String} propName
+ * @return {String}
+ *
+ * @overload
+ * @param  {JSTargetsParam} targetSelector
+ * @param  {String} propName
+ * @return {Number|String}
+ *
+ * @overload
+ * @param  {DOMTargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String} unit
+ * @return {String}
+ *
+ * @overload
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {Boolean} unit
+ * @return {Number}
+ *
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String|Boolean} [unit]
+ */
+export function get(targetSelector: DOMTargetSelector, propName: string): string;
+/**
+ * @overload
+ * @param  {DOMTargetSelector} targetSelector
+ * @param  {String} propName
+ * @return {String}
+ *
+ * @overload
+ * @param  {JSTargetsParam} targetSelector
+ * @param  {String} propName
+ * @return {Number|String}
+ *
+ * @overload
+ * @param  {DOMTargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String} unit
+ * @return {String}
+ *
+ * @overload
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {Boolean} unit
+ * @return {Number}
+ *
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String|Boolean} [unit]
+ */
+export function get(targetSelector: JSTargetsParam, propName: string): number | string;
+/**
+ * @overload
+ * @param  {DOMTargetSelector} targetSelector
+ * @param  {String} propName
+ * @return {String}
+ *
+ * @overload
+ * @param  {JSTargetsParam} targetSelector
+ * @param  {String} propName
+ * @return {Number|String}
+ *
+ * @overload
+ * @param  {DOMTargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String} unit
+ * @return {String}
+ *
+ * @overload
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {Boolean} unit
+ * @return {Number}
+ *
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String|Boolean} [unit]
+ */
+export function get(targetSelector: DOMTargetsParam, propName: string, unit: string): string;
+/**
+ * @overload
+ * @param  {DOMTargetSelector} targetSelector
+ * @param  {String} propName
+ * @return {String}
+ *
+ * @overload
+ * @param  {JSTargetsParam} targetSelector
+ * @param  {String} propName
+ * @return {Number|String}
+ *
+ * @overload
+ * @param  {DOMTargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String} unit
+ * @return {String}
+ *
+ * @overload
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {Boolean} unit
+ * @return {Number}
+ *
+ * @param  {TargetsParam} targetSelector
+ * @param  {String} propName
+ * @param  {String|Boolean} [unit]
+ */
+export function get(targetSelector: TargetsParam, propName: string, unit: boolean): number;
+export { registerTargets as $ };
+export function set(targets: TargetsParam, parameters: AnimationParams): JSAnimation;
+export function remove(targets: TargetsParam, renderable?: Renderable | WAAPIAnimation, propertyName?: string): TargetsArray;
+export { cleanInlineStyles } from "../core/styles.js";
+import type { DOMTargetSelector } from '../types/index.js';
+import type { JSTargetsParam } from '../types/index.js';
+import type { DOMTargetsParam } from '../types/index.js';
+import type { TargetsParam } from '../types/index.js';
+import { registerTargets } from '../core/targets.js';
+import type { AnimationParams } from '../types/index.js';
+import { JSAnimation } from '../animation/animation.js';
+import type { Renderable } from '../types/index.js';
+import type { WAAPIAnimation } from '../waapi/waapi.js';
+import type { TargetsArray } from '../types/index.js';