animejs 4.1.2 → 4.2.0-beta.0

package/dist/modules/scope/scope.js

@@ -0,0 +1,251 @@
+/**
+ * Anime.js - scope - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { doc, win } from '../core/consts.js';
+import { globals, scope } from '../core/globals.js';
+import { mergeObjects, isFnc } from '../core/helpers.js';
+import { parseTargets } from '../core/targets.js';
+import { keepTime } from '../utils/time.js';
+
+/**
+ * @import {
+ *   Tickable,
+ *   ScopeParams,
+ *   DOMTarget,
+ *   ReactRef,
+ *   AngularRef,
+ *   DOMTargetSelector,
+ *   DefaultsParams,
+ *   ScopeConstructorCallback,
+ *   ScopeCleanupCallback,
+ *   Revertible,
+ *   ScopeMethod,
+ *   ScopedCallback,
+ * } from '../types/index.js'
+*/
+
+class Scope {
+  /** @param {ScopeParams} [parameters] */
+  constructor(parameters = {}) {
+    if (scope.current) scope.current.register(this);
+    const rootParam = parameters.root;
+    /** @type {Document|DOMTarget} */
+    let root = doc;
+    if (rootParam) {
+      root = /** @type {ReactRef} */(rootParam).current ||
+             /** @type {AngularRef} */(rootParam).nativeElement ||
+             parseTargets(/** @type {DOMTargetSelector} */(rootParam))[0] ||
+             doc;
+    }
+    const scopeDefaults = parameters.defaults;
+    const globalDefault = globals.defaults;
+    const mediaQueries = parameters.mediaQueries;
+    /** @type {DefaultsParams} */
+    this.defaults = scopeDefaults ? mergeObjects(scopeDefaults, globalDefault) : globalDefault;
+    /** @type {Document|DOMTarget} */
+    this.root = root;
+    /** @type {Array<ScopeConstructorCallback>} */
+    this.constructors = [];
+    /** @type {Array<ScopeCleanupCallback>} */
+    this.revertConstructors = [];
+    /** @type {Array<Revertible>} */
+    this.revertibles = [];
+    /** @type {Array<ScopeConstructorCallback | ((scope: this) => Tickable)>} */
+    this.constructorsOnce = [];
+    /** @type {Array<ScopeCleanupCallback>} */
+    this.revertConstructorsOnce = [];
+    /** @type {Array<Revertible>} */
+    this.revertiblesOnce = [];
+    /** @type {Boolean} */
+    this.once = false;
+    /** @type {Number} */
+    this.onceIndex = 0;
+    /** @type {Record<String, ScopeMethod>} */
+    this.methods = {};
+    /** @type {Record<String, Boolean>} */
+    this.matches = {};
+    /** @type {Record<String, MediaQueryList>} */
+    this.mediaQueryLists = {};
+    /** @type {Record<String, any>} */
+    this.data = {};
+    if (mediaQueries) {
+      for (let mq in mediaQueries) {
+        const _mq = win.matchMedia(mediaQueries[mq]);
+        this.mediaQueryLists[mq] = _mq;
+        _mq.addEventListener('change', this);
+      }
+    }
+  }
+
+  /**
+   * @param {Revertible} revertible
+   */
+  register(revertible) {
+    const store = this.once ? this.revertiblesOnce : this.revertibles;
+    store.push(revertible);
+  }
+
+  /**
+   * @template T
+   * @param {ScopedCallback<T>} cb
+   * @return {T}
+   */
+  execute(cb) {
+    let activeScope = scope.current;
+    let activeRoot = scope.root;
+    let activeDefaults = globals.defaults;
+    scope.current = this;
+    scope.root = this.root;
+    globals.defaults = this.defaults;
+    const mqs = this.mediaQueryLists;
+    for (let mq in mqs) this.matches[mq] = mqs[mq].matches;
+    const returned = cb(this);
+    scope.current = activeScope;
+    scope.root = activeRoot;
+    globals.defaults = activeDefaults;
+    return returned;
+  }
+
+  /**
+   * @return {this}
+   */
+  refresh() {
+    this.onceIndex = 0;
+    this.execute(() => {
+      let i = this.revertibles.length;
+      let y = this.revertConstructors.length;
+      while (i--) this.revertibles[i].revert();
+      while (y--) this.revertConstructors[y](this);
+      this.revertibles.length = 0;
+      this.revertConstructors.length = 0;
+      this.constructors.forEach((/** @type {ScopeConstructorCallback} */constructor) => {
+        const revertConstructor = constructor(this);
+        if (isFnc(revertConstructor)) {
+          this.revertConstructors.push(revertConstructor);
+        }
+      });
+    });
+    return this;
+  }
+
+  /**
+   * @overload
+   * @param {String} a1
+   * @param {ScopeMethod} a2
+   * @return {this}
+   *
+   * @overload
+   * @param {ScopeConstructorCallback} a1
+   * @return {this}
+   *
+   * @param {String|ScopeConstructorCallback} a1
+   * @param {ScopeMethod} [a2]
+   */
+  add(a1, a2) {
+    this.once = false;
+    if (isFnc(a1)) {
+      const constructor = /** @type {ScopeConstructorCallback} */(a1);
+      this.constructors.push(constructor);
+      this.execute(() => {
+        const revertConstructor = constructor(this);
+        if (isFnc(revertConstructor)) {
+          this.revertConstructors.push(revertConstructor);
+        }
+      });
+    } else {
+      this.methods[/** @type {String} */(a1)] = (/** @type {any} */...args) => this.execute(() => a2(...args));
+    }
+    return this;
+  }
+
+  /**
+   * @param {ScopeConstructorCallback} scopeConstructorCallback
+   * @return {this}
+   */
+  addOnce(scopeConstructorCallback) {
+    this.once = true;
+    if (isFnc(scopeConstructorCallback)) {
+      const currentIndex = this.onceIndex++;
+      const tracked = this.constructorsOnce[currentIndex];
+      if (tracked) return this;
+      const constructor = /** @type {ScopeConstructorCallback} */(scopeConstructorCallback);
+      this.constructorsOnce[currentIndex] = constructor;
+      this.execute(() => {
+        const revertConstructor = constructor(this);
+        if (isFnc(revertConstructor)) {
+          this.revertConstructorsOnce.push(revertConstructor);
+        }
+      });
+    }
+    return this;
+  }
+
+  /**
+   * @param  {(scope: this) => Tickable} cb
+   * @return {Tickable}
+   */
+  keepTime(cb) {
+    this.once = true;
+    const currentIndex = this.onceIndex++;
+    const tracked = /** @type {(scope: this) => Tickable} */(this.constructorsOnce[currentIndex]);
+    if (isFnc(tracked)) return tracked(this);
+    const constructor = /** @type {(scope: this) => Tickable} */(keepTime(cb));
+    this.constructorsOnce[currentIndex] = constructor;
+    let trackedTickable;
+    this.execute(() => {
+      trackedTickable = constructor(this);
+    });
+    return trackedTickable;
+  }
+
+  /**
+   * @param {Event} e
+   */
+  handleEvent(e) {
+    switch (e.type) {
+      case 'change':
+        this.refresh();
+        break;
+    }
+  }
+
+  revert() {
+    const revertibles = this.revertibles;
+    const revertConstructors = this.revertConstructors;
+    const revertiblesOnce = this.revertiblesOnce;
+    const revertConstructorsOnce = this.revertConstructorsOnce;
+    const mqs = this.mediaQueryLists;
+    let i = revertibles.length;
+    let j = revertConstructors.length;
+    let k = revertiblesOnce.length;
+    let l = revertConstructorsOnce.length;
+    while (i--) revertibles[i].revert();
+    while (j--) revertConstructors[j](this);
+    while (k--) revertiblesOnce[k].revert();
+    while (l--) revertConstructorsOnce[l](this);
+    for (let mq in mqs) mqs[mq].removeEventListener('change', this);
+    revertibles.length = 0;
+    revertConstructors.length = 0;
+    this.constructors.length = 0;
+    revertiblesOnce.length = 0;
+    revertConstructorsOnce.length = 0;
+    this.constructorsOnce.length = 0;
+    this.onceIndex = 0;
+    this.matches = {};
+    this.methods = {};
+    this.mediaQueryLists = {};
+    this.data = {};
+  }
+}
+
+/**
+ * @param {ScopeParams} [params]
+ * @return {Scope}
+ */
+const createScope = params => new Scope(params);
+
+export { Scope, createScope };

package/dist/modules/spring/index.cjs

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

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

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

package/dist/modules/spring/index.js

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

package/dist/modules/spring/spring.cjs

@@ -0,0 +1,133 @@
+/**
+ * Anime.js - spring - CJS
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+'use strict';
+
+var consts = require('../core/consts.cjs');
+var globals = require('../core/globals.cjs');
+var helpers = require('../core/helpers.cjs');
+var values = require('../core/values.cjs');
+
+/**
+ * @import {
+ *   EasingFunction,
+ *   SpringParams,
+ * } from '../types/index.js'
+*/
+
+/*
+ * Spring ease solver adapted from https://webkit.org/demos/spring/spring.js
+ * (c) 2016 Webkit - Apple Inc
+ */
+
+const maxSpringParamValue = consts.K * 10;
+
+class Spring {
+  /**
+   * @param {SpringParams} [parameters]
+   */
+  constructor(parameters = {}) {
+    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 / consts.K; // How many steps allowed after reaching restThreshold before stopping the duration calculation
+    this.maxIterations = this.maxDuration / this.timeStep / consts.K; // Calculate the maximum iterations allowed based on maxDuration
+    this.m = helpers.clamp(values.setValue(parameters.mass, 1), 0, maxSpringParamValue);
+    this.s = helpers.clamp(values.setValue(parameters.stiffness, 100), 1, maxSpringParamValue);
+    this.d = helpers.clamp(values.setValue(parameters.damping, 10), .1, maxSpringParamValue);
+    this.v = helpers.clamp(values.setValue(parameters.velocity, 0), -maxSpringParamValue, maxSpringParamValue);
+    this.w0 = 0;
+    this.zeta = 0;
+    this.wd = 0;
+    this.b = 0;
+    this.solverDuration = 0;
+    this.duration = 0;
+    this.compute();
+    /** @type {EasingFunction} */
+    this.ease = t => 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) {
+      t = helpers.exp(-t * zeta * w0) * (1 * helpers.cos(wd * t) + b * helpers.sin(wd * t));
+    } else {
+      t = (1 + b * t) * helpers.exp(-t * w0);
+    }
+    return 1 - t;
+  }
+
+  compute() {
+    const { maxRestSteps, maxIterations, restThreshold, timeStep, m, d, s, v } = this;
+    const w0 = this.w0 = helpers.clamp(helpers.sqrt(s / m), consts.minValue, consts.K);
+    const zeta = this.zeta = d / (2 * helpers.sqrt(s * m));
+    const wd = this.wd = zeta < 1 ? w0 * helpers.sqrt(1 - zeta * zeta) : 0;
+    this.b = zeta < 1 ? (zeta * w0 + -v) / wd : -v + w0;
+    let solverTime = 0;
+    let restSteps = 0;
+    let iterations = 0;
+    while (restSteps < maxRestSteps && iterations < maxIterations) {
+      if (helpers.abs(1 - this.solve(solverTime)) < restThreshold) {
+        restSteps++;
+      } else {
+        restSteps = 0;
+      }
+      this.solverDuration = solverTime;
+      solverTime += timeStep;
+      iterations++;
+    }
+    this.duration = helpers.round(this.solverDuration * consts.K, 0) * globals.globals.timeScale;
+  }
+
+  get mass() {
+    return this.m;
+  }
+
+  set mass(v) {
+    this.m = helpers.clamp(values.setValue(v, 1), 0, maxSpringParamValue);
+    this.compute();
+  }
+
+  get stiffness() {
+    return this.s;
+  }
+
+  set stiffness(v) {
+    this.s = helpers.clamp(values.setValue(v, 100), 1, maxSpringParamValue);
+    this.compute();
+  }
+
+  get damping() {
+    return this.d;
+  }
+
+  set damping(v) {
+    this.d = helpers.clamp(values.setValue(v, 10), .1, maxSpringParamValue);
+    this.compute();
+  }
+
+  get velocity() {
+    return this.v;
+  }
+
+  set velocity(v) {
+    this.v = helpers.clamp(values.setValue(v, 0), -maxSpringParamValue, maxSpringParamValue);
+    this.compute();
+  }
+}
+
+/**
+ * @param {SpringParams} [parameters]
+ * @returns {Spring}
+ */
+const createSpring = (parameters) => new Spring(parameters);
+
+exports.Spring = Spring;
+exports.createSpring = createSpring;

package/dist/modules/spring/spring.d.ts

@@ -0,0 +1,37 @@
+export class Spring {
+    /**
+     * @param {SpringParams} [parameters]
+     */
+    constructor(parameters?: SpringParams);
+    timeStep: number;
+    restThreshold: number;
+    restDuration: number;
+    maxDuration: number;
+    maxRestSteps: number;
+    maxIterations: number;
+    m: number;
+    s: number;
+    d: number;
+    v: number;
+    w0: number;
+    zeta: number;
+    wd: number;
+    b: number;
+    solverDuration: number;
+    duration: number;
+    /** @type {EasingFunction} */
+    ease: EasingFunction;
+    solve(time: number): number;
+    compute(): void;
+    set mass(v: number);
+    get mass(): number;
+    set stiffness(v: number);
+    get stiffness(): number;
+    set damping(v: number);
+    get damping(): number;
+    set velocity(v: number);
+    get velocity(): number;
+}
+export function createSpring(parameters?: SpringParams): Spring;
+import type { EasingFunction } from '../types/index.js';
+import type { SpringParams } from '../types/index.js';

package/dist/modules/spring/spring.js

@@ -0,0 +1,130 @@
+/**
+ * Anime.js - spring - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { K, minValue } from '../core/consts.js';
+import { globals } from '../core/globals.js';
+import { clamp, sqrt, abs, round, exp, cos, sin } from '../core/helpers.js';
+import { setValue } from '../core/values.js';
+
+/**
+ * @import {
+ *   EasingFunction,
+ *   SpringParams,
+ * } from '../types/index.js'
+*/
+
+/*
+ * Spring ease 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 = {}) {
+    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.m = clamp(setValue(parameters.mass, 1), 0, maxSpringParamValue);
+    this.s = clamp(setValue(parameters.stiffness, 100), 1, maxSpringParamValue);
+    this.d = clamp(setValue(parameters.damping, 10), .1, maxSpringParamValue);
+    this.v = clamp(setValue(parameters.velocity, 0), -maxSpringParamValue, maxSpringParamValue);
+    this.w0 = 0;
+    this.zeta = 0;
+    this.wd = 0;
+    this.b = 0;
+    this.solverDuration = 0;
+    this.duration = 0;
+    this.compute();
+    /** @type {EasingFunction} */
+    this.ease = t => 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) {
+      t = exp(-t * zeta * w0) * (1 * cos(wd * t) + b * sin(wd * t));
+    } else {
+      t = (1 + b * t) * exp(-t * w0);
+    }
+    return 1 - t;
+  }
+
+  compute() {
+    const { maxRestSteps, maxIterations, restThreshold, timeStep, m, d, s, v } = this;
+    const w0 = this.w0 = clamp(sqrt(s / m), minValue, K);
+    const zeta = this.zeta = d / (2 * sqrt(s * m));
+    const wd = this.wd = zeta < 1 ? w0 * sqrt(1 - zeta * zeta) : 0;
+    this.b = zeta < 1 ? (zeta * w0 + -v) / wd : -v + w0;
+    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.duration = round(this.solverDuration * K, 0) * globals.timeScale;
+  }
+
+  get mass() {
+    return this.m;
+  }
+
+  set mass(v) {
+    this.m = clamp(setValue(v, 1), 0, maxSpringParamValue);
+    this.compute();
+  }
+
+  get stiffness() {
+    return this.s;
+  }
+
+  set stiffness(v) {
+    this.s = clamp(setValue(v, 100), 1, maxSpringParamValue);
+    this.compute();
+  }
+
+  get damping() {
+    return this.d;
+  }
+
+  set damping(v) {
+    this.d = clamp(setValue(v, 10), .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 createSpring = (parameters) => new Spring(parameters);
+
+export { Spring, createSpring };

package/dist/modules/svg/drawable.cjs

@@ -0,0 +1,119 @@
+/**
+ * Anime.js - svg - 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 targets = require('../core/targets.cjs');
+
+/**
+ * @import {
+ *   TargetsParam,
+ *   DrawableSVGGeometry,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @param {SVGGeometryElement} [$el]
+ * @return {Number}
+ */
+const getScaleFactor = $el => {
+  let scaleFactor = 1;
+  if ($el && $el.getCTM) {
+    const ctm = $el.getCTM();
+    if (ctm) {
+      const scaleX = helpers.sqrt(ctm.a * ctm.a + ctm.b * ctm.b);
+      const scaleY = helpers.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 = consts.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 === consts.proxyTargetSymbol) return target;
+      if (property === 'setAttribute') {
+        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 scaleFactor = getScaleFactor($scalled);
+            const os = v1 * -pathLength * 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.style.strokeLinecap = `${newCap}`;
+                currentCap = newCap;
+              }
+            }
+            target.setAttribute('stroke-dashoffset', `${os}`);
+            target.setAttribute('stroke-dasharray', `${d1} ${d2}`);
+          }
+          return Reflect.apply(value, target, args);
+        };
+      }
+
+      if (helpers.isFnc(value)) {
+        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 {DrawableSVGGeometry} */(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 = targets.parseTargets(selector);
+  return els.map($el => createDrawableProxy(
+    /** @type {SVGGeometryElement} */($el),
+    start,
+    end
+  ));
+};
+
+exports.createDrawable = createDrawable;

package/dist/modules/svg/drawable.d.ts

@@ -0,0 +1,3 @@
+export function createDrawable(selector: TargetsParam, start?: number, end?: number): Array<DrawableSVGGeometry>;
+import type { TargetsParam } from '../types/index.js';
+import type { DrawableSVGGeometry } from '../types/index.js';