animejs 4.1.4 → 4.2.0

package/dist/modules/easings/spring/index.js

@@ -0,0 +1,251 @@
+/**
+ * Anime.js - easings - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { K, minValue, noop } from '../../core/consts.js';
+import { globals } from '../../core/globals.js';
+import { isUnd, clamp, pow, PI, round, sqrt, abs, exp, cos, sin } from '../../core/helpers.js';
+import { setValue } from '../../core/values.js';
+
+/**
+ * @import {
+ *   JSAnimation,
+ * } from '../../animation/animation.js'
+ */
+
+/**
+ * @import {
+ *   EasingFunction,
+ *   SpringParams,
+ *   Callback,
+ * } from '../../types/index.js'
+*/
+
+/*
+ * Spring easing solver adapted from https://webkit.org/demos/spring/spring.js
+ * (c) 2016 Webkit - Apple Inc
+ */
+
+const maxSpringParamValue = K * 10;
+
+class Spring {
+  /**
+   * @param {SpringParams} [parameters]
+   */
+  constructor(parameters = {}) {
+    const hasBounceOrDuration = !isUnd(parameters.bounce) || !isUnd(parameters.duration);
+    this.timeStep = .02; // Interval fed to the solver to calculate duration
+    this.restThreshold = .0005; // Values below this threshold are considered resting position
+    this.restDuration = 200; // Duration in ms used to check if the spring is resting after reaching restThreshold
+    this.maxDuration = 60000; // The maximum allowed spring duration in ms (default 1 min)
+    this.maxRestSteps = this.restDuration / this.timeStep / K; // How many steps allowed after reaching restThreshold before stopping the duration calculation
+    this.maxIterations = this.maxDuration / this.timeStep / K; // Calculate the maximum iterations allowed based on maxDuration
+    this.bn = clamp(setValue(parameters.bounce, .5), -1, 1); // The bounce percentage between -1 and 1.
+    this.pd = clamp(setValue(parameters.duration, 628), 10 * globals.timeScale, maxSpringParamValue * globals.timeScale); // The perceived duration
+    this.m = clamp(setValue(parameters.mass, 1), 1, maxSpringParamValue);
+    this.s = clamp(setValue(parameters.stiffness, 100), minValue, maxSpringParamValue);
+    this.d = clamp(setValue(parameters.damping, 10), minValue, maxSpringParamValue);
+    this.v = clamp(setValue(parameters.velocity, 0), -maxSpringParamValue, maxSpringParamValue);
+    this.w0 = 0;
+    this.zeta = 0;
+    this.wd = 0;
+    this.b = 0;
+    this.completed = false;
+    this.solverDuration = 0;
+    this.settlingDuration = 0;
+    /** @type {JSAnimation} */
+    this.parent = null;
+    /** @type {Callback<JSAnimation>} */
+    this.onComplete = parameters.onComplete || noop;
+    if (hasBounceOrDuration) this.calculateSDFromBD();
+    this.compute();
+    /** @type {EasingFunction} */
+    this.ease = t => {
+      const currentTime = t * this.settlingDuration;
+      const completed = this.completed;
+      const perceivedTime = this.pd;
+      if (currentTime >= perceivedTime && !completed) {
+        this.completed = true;
+        this.onComplete(this.parent);
+      }
+      if (currentTime < perceivedTime && completed) {
+        this.completed = false;
+      }
+      return t === 0 || t === 1 ? t : this.solve(t * this.solverDuration);
+    };
+  }
+
+  /** @type {EasingFunction} */
+  solve(time) {
+    const { zeta, w0, wd, b } = this;
+    let t = time;
+    if (zeta < 1) {
+      // Underdamped
+      t = exp(-t * zeta * w0) * (1 * cos(wd * t) + b * sin(wd * t));
+    } else if (zeta === 1) {
+      // Critically damped
+      t = (1 + b * t) * exp(-t * w0);
+    } else {
+      // Overdamped
+      // Using exponential instead of cosh and sinh functions to prevent Infinity
+      // Original exp(-zeta * w0 * t) * (cosh(wd * t) + b * sinh(wd * t))
+      t = ((1 + b) * exp((-zeta * w0 + wd) * t) + (1 - b) * exp((-zeta * w0 - wd) * t)) / 2;
+    }
+    return 1 - t;
+  }
+
+  calculateSDFromBD() {
+    // Apple's SwiftUI perceived spring duration implementation https://developer.apple.com/videos/play/wwdc2023/10158/?time=1010
+    // Equations taken from Kevin Grajeda's article https://www.kvin.me/posts/effortless-ui-spring-animations
+    const pds = globals.timeScale === 1 ? this.pd / K : this.pd;
+    // Mass and velocity should be set to their default values
+    this.m = 1;
+    this.v = 0;
+    // Stiffness = (2π ÷ perceptualDuration)²
+    this.s = pow((2 * PI) / pds, 2);
+    if (this.bn >= 0) {
+      // For bounce ≥ 0 (critically damped to underdamped)
+      // damping = ((1 - bounce) × 4π) ÷ perceptualDuration
+      this.d = ((1 - this.bn) * 4 * PI) / pds;
+    } else {
+      // For bounce < 0 (overdamped)
+      // damping = 4π ÷ (perceptualDuration × (1 + bounce))
+      // Note: (1 + bounce) is positive since bounce is negative
+      this.d = (4 * PI) / (pds * (1 + this.bn));
+    }
+    this.s = round(clamp(this.s, minValue, maxSpringParamValue), 3);
+    this.d = round(clamp(this.d, minValue, 300), 3); // Clamping to 300 is needed to prevent insane values in the solver
+  }
+
+  calculateBDFromSD() {
+    // Calculate perceived duration and bounce from stiffness and damping
+    // Note: We assumes m = 1 and v = 0 for these calculations
+    const pds = (2 * PI) / sqrt(this.s);
+    this.pd = pds * (globals.timeScale === 1 ? K : 1);
+    const zeta = this.d / (2 * sqrt(this.s));
+    if (zeta <= 1) {
+      // Critically damped to underdamped
+      this.bn = 1 - (this.d * pds) / (4 * PI);
+    } else {
+      // Overdamped
+      this.bn = (4 * PI) / (this.d * pds) - 1;
+    }
+    this.bn = round(clamp(this.bn, -1, 1), 3);
+    this.pd = round(clamp(this.pd, 10 * globals.timeScale, maxSpringParamValue * globals.timeScale), 3);
+  }
+
+  compute() {
+    const { maxRestSteps, maxIterations, restThreshold, timeStep, m, d, s, v } = this;
+    const w0 = this.w0 = clamp(sqrt(s / m), minValue, K);
+    const bouncedZeta = this.zeta = d / (2 * sqrt(s * m));
+    // Calculate wd based on damping type
+    if (bouncedZeta < 1) {
+      // Underdamped
+      this.wd = w0 * sqrt(1 - bouncedZeta * bouncedZeta);
+      this.b = (bouncedZeta * w0 + -v) / this.wd;
+    } else if (bouncedZeta === 1) {
+      // Critically damped
+      this.wd = 0;
+      this.b = -v + w0;
+    } else {
+      // Overdamped
+      this.wd = w0 * sqrt(bouncedZeta * bouncedZeta - 1);
+      this.b = (bouncedZeta * w0 + -v) / this.wd;
+    }
+
+    let solverTime = 0;
+    let restSteps = 0;
+    let iterations = 0;
+    while (restSteps <= maxRestSteps && iterations <= maxIterations) {
+      if (abs(1 - this.solve(solverTime)) < restThreshold) {
+        restSteps++;
+      } else {
+        restSteps = 0;
+      }
+      this.solverDuration = solverTime;
+      solverTime += timeStep;
+      iterations++;
+    }
+    this.settlingDuration = round(this.solverDuration * K, 0) * globals.timeScale;
+  }
+
+  get bounce() {
+    return this.bn;
+  }
+
+  set bounce(v) {
+    this.bn = clamp(setValue(v, 1), -1, 1);
+    this.calculateSDFromBD();
+    this.compute();
+  }
+
+  get duration() {
+    return this.pd;
+  }
+
+  set duration(v) {
+    this.pd = clamp(setValue(v, 1), 10 * globals.timeScale, maxSpringParamValue * globals.timeScale);
+    this.calculateSDFromBD();
+    this.compute();
+  }
+
+  get stiffness() {
+    return this.s;
+  }
+
+  set stiffness(v) {
+    this.s = clamp(setValue(v, 100), minValue, maxSpringParamValue);
+    this.calculateBDFromSD();
+    this.compute();
+  }
+
+  get damping() {
+    return this.d;
+  }
+
+  set damping(v) {
+    this.d = clamp(setValue(v, 10), minValue, maxSpringParamValue);
+    this.calculateBDFromSD();
+    this.compute();
+  }
+
+  get mass() {
+    return this.m;
+  }
+
+  set mass(v) {
+    this.m = clamp(setValue(v, 1), 1, maxSpringParamValue);
+    this.compute();
+  }
+
+  get velocity() {
+    return this.v;
+  }
+
+  set velocity(v) {
+    this.v = clamp(setValue(v, 0), -maxSpringParamValue, maxSpringParamValue);
+    this.compute();
+  }
+}
+
+/**
+ * @param {SpringParams} [parameters]
+ * @returns {Spring}
+ */
+const spring = (parameters) => new Spring(parameters);
+
+/**
+ * @deprecated createSpring() is deprecated use spring() instead
+ *
+ * @param {SpringParams} [parameters]
+ * @returns {Spring}
+ */
+const createSpring = (parameters) => {
+  console.warn('createSpring() is deprecated use spring() instead');
+  return new Spring(parameters);
+};
+
+export { Spring, createSpring, spring };

package/dist/modules/easings/steps/index.cjs

@@ -0,0 +1,30 @@
+/**
+ * Anime.js - easings - CJS
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+'use strict';
+
+var helpers = require('../../core/helpers.cjs');
+
+/**
+ * @import {
+ *   EasingFunction,
+ * } from '../../types/index.js'
+*/
+
+/**
+ * Steps ease implementation https://developer.mozilla.org/fr/docs/Web/CSS/transition-timing-function
+ * Only covers 'end' and 'start' jumpterms
+ * @param  {Number} steps
+ * @param  {Boolean} [fromStart]
+ * @return {EasingFunction}
+ */
+const steps = (steps = 10, fromStart) => {
+  const roundMethod = fromStart ? helpers.ceil : helpers.floor;
+  return t => roundMethod(helpers.clamp(t, 0, 1) * steps) * (1 / steps);
+};
+
+exports.steps = steps;

package/dist/modules/easings/steps/index.d.ts

@@ -0,0 +1,2 @@
+export function steps(steps?: number, fromStart?: boolean): EasingFunction;
+import type { EasingFunction } from '../../types/index.js';

package/dist/modules/easings/steps/index.js

@@ -0,0 +1,28 @@
+/**
+ * Anime.js - easings - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { ceil, floor, clamp } from '../../core/helpers.js';
+
+/**
+ * @import {
+ *   EasingFunction,
+ * } from '../../types/index.js'
+*/
+
+/**
+ * Steps ease implementation https://developer.mozilla.org/fr/docs/Web/CSS/transition-timing-function
+ * Only covers 'end' and 'start' jumpterms
+ * @param  {Number} steps
+ * @param  {Boolean} [fromStart]
+ * @return {EasingFunction}
+ */
+const steps = (steps = 10, fromStart) => {
+  const roundMethod = fromStart ? ceil : floor;
+  return t => roundMethod(clamp(t, 0, 1) * steps) * (1 / steps);
+};
+
+export { steps };

package/dist/modules/engine/engine.cjs

@@ -0,0 +1,168 @@
+/**
+ * Anime.js - engine - 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 clock = require('../core/clock.cjs');
+var render = require('../core/render.cjs');
+var additive = require('../animation/additive.cjs');
+
+/**
+ * @import {
+ *   DefaultsParams,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @import {
+ *   Tickable,
+ * } from '../types/index.js'
+*/
+
+const engineTickMethod = /*#__PURE__*/ (() => consts.isBrowser ? requestAnimationFrame : setImmediate)();
+const engineCancelMethod = /*#__PURE__*/ (() => consts.isBrowser ? cancelAnimationFrame : clearImmediate)();
+
+class Engine extends clock.Clock {
+
+  /** @param {Number} [initTime] */
+  constructor(initTime) {
+    super(initTime);
+    this.useDefaultMainLoop = true;
+    this.pauseOnDocumentHidden = true;
+    /** @type {DefaultsParams} */
+    this.defaults = globals.defaults;
+    // this.paused = isBrowser && doc.hidden ? true  : false;
+    this.paused = true;
+    /** @type {Number|NodeJS.Immediate} */
+    this.reqId = 0;
+  }
+
+  update() {
+    const time = this._currentTime = helpers.now();
+    if (this.requestTick(time)) {
+      this.computeDeltaTime(time);
+      const engineSpeed = this._speed;
+      const engineFps = this._fps;
+      let activeTickable = /** @type {Tickable} */(this._head);
+      while (activeTickable) {
+        const nextTickable = activeTickable._next;
+        if (!activeTickable.paused) {
+          render.tick(
+            activeTickable,
+            (time - activeTickable._startTime) * activeTickable._speed * engineSpeed,
+            0, // !muteCallbacks
+            0, // !internalRender
+            activeTickable._fps < engineFps ? activeTickable.requestTick(time) : consts.tickModes.AUTO
+          );
+        } else {
+          helpers.removeChild(this, activeTickable);
+          this._hasChildren = !!this._tail;
+          activeTickable._running = false;
+          if (activeTickable.completed && !activeTickable._cancelled) {
+            activeTickable.cancel();
+          }
+        }
+        activeTickable = nextTickable;
+      }
+      additive.additive.update();
+    }
+  }
+
+  wake() {
+    if (this.useDefaultMainLoop && !this.reqId) {
+      // Imediatly request a tick to update engine._elapsedTime and get accurate offsetPosition calculation in timer.js
+      this.requestTick(helpers.now());
+      this.reqId = engineTickMethod(tickEngine);
+    }
+    return this;
+  }
+
+  pause() {
+    if (!this.reqId) return;
+    this.paused = true;
+    return killEngine();
+  }
+
+  resume() {
+    if (!this.paused) return;
+    this.paused = false;
+    helpers.forEachChildren(this, (/** @type {Tickable} */child) => child.resetTime());
+    return this.wake();
+  }
+
+  // Getter and setter for speed
+  get speed() {
+    return this._speed * (globals.globals.timeScale === 1 ? 1 : consts.K);
+  }
+
+  set speed(playbackRate) {
+    this._speed = playbackRate * globals.globals.timeScale;
+    helpers.forEachChildren(this, (/** @type {Tickable} */child) => child.speed = child._speed);
+  }
+
+  // Getter and setter for timeUnit
+  get timeUnit() {
+    return globals.globals.timeScale === 1 ? 'ms' : 's';
+  }
+
+  set timeUnit(unit) {
+    const secondsScale = 0.001;
+    const isSecond = unit === 's';
+    const newScale = isSecond ? secondsScale : 1;
+    if (globals.globals.timeScale !== newScale) {
+      globals.globals.timeScale = newScale;
+      globals.globals.tickThreshold = 200 * newScale;
+      const scaleFactor = isSecond ? secondsScale : consts.K;
+      /** @type {Number} */
+      (this.defaults.duration) *= scaleFactor;
+      this._speed *= scaleFactor;
+    }
+  }
+
+  // Getter and setter for precision
+  get precision() {
+    return globals.globals.precision;
+  }
+
+  set precision(precision) {
+    globals.globals.precision = precision;
+  }
+
+}
+
+const engine = /*#__PURE__*/(() => {
+  const engine = new Engine(helpers.now());
+  if (consts.isBrowser) {
+    globals.globalVersions.engine = engine;
+    consts.doc.addEventListener('visibilitychange', () => {
+      if (!engine.pauseOnDocumentHidden) return;
+      consts.doc.hidden ? engine.pause() : engine.resume();
+    });
+  }
+  return engine;
+})();
+
+
+const tickEngine = () => {
+  if (engine._head) {
+    engine.reqId = engineTickMethod(tickEngine);
+    engine.update();
+  } else {
+    engine.reqId = 0;
+  }
+};
+
+const killEngine = () => {
+  engineCancelMethod(/** @type {NodeJS.Immediate & Number} */(engine.reqId));
+  engine.reqId = 0;
+  return engine;
+};
+
+exports.engine = engine;

package/dist/modules/engine/engine.d.ts

@@ -0,0 +1,21 @@
+export const engine: Engine;
+declare class Engine extends Clock {
+    useDefaultMainLoop: boolean;
+    pauseOnDocumentHidden: boolean;
+    /** @type {DefaultsParams} */
+    defaults: DefaultsParams;
+    paused: boolean;
+    /** @type {Number|NodeJS.Immediate} */
+    reqId: number | NodeJS.Immediate;
+    update(): void;
+    wake(): this;
+    pause(): Engine;
+    resume(): this;
+    set timeUnit(unit: "ms" | "s");
+    get timeUnit(): "ms" | "s";
+    set precision(precision: number);
+    get precision(): number;
+}
+import { Clock } from '../core/clock.js';
+import type { DefaultsParams } from '../types/index.js';
+export {};

package/dist/modules/engine/engine.js

@@ -0,0 +1,166 @@
+/**
+ * Anime.js - engine - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { globalVersions, defaults, globals } from '../core/globals.js';
+import { isBrowser, doc, tickModes, K } from '../core/consts.js';
+import { now, removeChild, forEachChildren } from '../core/helpers.js';
+import { Clock } from '../core/clock.js';
+import { tick } from '../core/render.js';
+import { additive } from '../animation/additive.js';
+
+/**
+ * @import {
+ *   DefaultsParams,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @import {
+ *   Tickable,
+ * } from '../types/index.js'
+*/
+
+const engineTickMethod = /*#__PURE__*/ (() => isBrowser ? requestAnimationFrame : setImmediate)();
+const engineCancelMethod = /*#__PURE__*/ (() => isBrowser ? cancelAnimationFrame : clearImmediate)();
+
+class Engine extends Clock {
+
+  /** @param {Number} [initTime] */
+  constructor(initTime) {
+    super(initTime);
+    this.useDefaultMainLoop = true;
+    this.pauseOnDocumentHidden = true;
+    /** @type {DefaultsParams} */
+    this.defaults = defaults;
+    // this.paused = isBrowser && doc.hidden ? true  : false;
+    this.paused = true;
+    /** @type {Number|NodeJS.Immediate} */
+    this.reqId = 0;
+  }
+
+  update() {
+    const time = this._currentTime = now();
+    if (this.requestTick(time)) {
+      this.computeDeltaTime(time);
+      const engineSpeed = this._speed;
+      const engineFps = this._fps;
+      let activeTickable = /** @type {Tickable} */(this._head);
+      while (activeTickable) {
+        const nextTickable = activeTickable._next;
+        if (!activeTickable.paused) {
+          tick(
+            activeTickable,
+            (time - activeTickable._startTime) * activeTickable._speed * engineSpeed,
+            0, // !muteCallbacks
+            0, // !internalRender
+            activeTickable._fps < engineFps ? activeTickable.requestTick(time) : tickModes.AUTO
+          );
+        } else {
+          removeChild(this, activeTickable);
+          this._hasChildren = !!this._tail;
+          activeTickable._running = false;
+          if (activeTickable.completed && !activeTickable._cancelled) {
+            activeTickable.cancel();
+          }
+        }
+        activeTickable = nextTickable;
+      }
+      additive.update();
+    }
+  }
+
+  wake() {
+    if (this.useDefaultMainLoop && !this.reqId) {
+      // Imediatly request a tick to update engine._elapsedTime and get accurate offsetPosition calculation in timer.js
+      this.requestTick(now());
+      this.reqId = engineTickMethod(tickEngine);
+    }
+    return this;
+  }
+
+  pause() {
+    if (!this.reqId) return;
+    this.paused = true;
+    return killEngine();
+  }
+
+  resume() {
+    if (!this.paused) return;
+    this.paused = false;
+    forEachChildren(this, (/** @type {Tickable} */child) => child.resetTime());
+    return this.wake();
+  }
+
+  // Getter and setter for speed
+  get speed() {
+    return this._speed * (globals.timeScale === 1 ? 1 : K);
+  }
+
+  set speed(playbackRate) {
+    this._speed = playbackRate * globals.timeScale;
+    forEachChildren(this, (/** @type {Tickable} */child) => child.speed = child._speed);
+  }
+
+  // Getter and setter for timeUnit
+  get timeUnit() {
+    return globals.timeScale === 1 ? 'ms' : 's';
+  }
+
+  set timeUnit(unit) {
+    const secondsScale = 0.001;
+    const isSecond = unit === 's';
+    const newScale = isSecond ? secondsScale : 1;
+    if (globals.timeScale !== newScale) {
+      globals.timeScale = newScale;
+      globals.tickThreshold = 200 * newScale;
+      const scaleFactor = isSecond ? secondsScale : K;
+      /** @type {Number} */
+      (this.defaults.duration) *= scaleFactor;
+      this._speed *= scaleFactor;
+    }
+  }
+
+  // Getter and setter for precision
+  get precision() {
+    return globals.precision;
+  }
+
+  set precision(precision) {
+    globals.precision = precision;
+  }
+
+}
+
+const engine = /*#__PURE__*/(() => {
+  const engine = new Engine(now());
+  if (isBrowser) {
+    globalVersions.engine = engine;
+    doc.addEventListener('visibilitychange', () => {
+      if (!engine.pauseOnDocumentHidden) return;
+      doc.hidden ? engine.pause() : engine.resume();
+    });
+  }
+  return engine;
+})();
+
+
+const tickEngine = () => {
+  if (engine._head) {
+    engine.reqId = engineTickMethod(tickEngine);
+    engine.update();
+  } else {
+    engine.reqId = 0;
+  }
+};
+
+const killEngine = () => {
+  engineCancelMethod(/** @type {NodeJS.Immediate & Number} */(engine.reqId));
+  engine.reqId = 0;
+  return engine;
+};
+
+export { engine };

package/dist/modules/engine/index.cjs

@@ -0,0 +1,14 @@
+/**
+ * Anime.js - engine - CJS
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+'use strict';
+
+var engine = require('./engine.cjs');
+
+
+
+exports.engine = engine.engine;

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

@@ -0,0 +1 @@
+export * from "./engine.js";

package/dist/modules/engine/index.js

@@ -0,0 +1,8 @@
+/**
+ * Anime.js - engine - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+export { engine } from './engine.js';