animejs 4.0.2 → 4.1.1

package/types/index.js

@@ -1,6 +1,6 @@
 /**
  * anime.js - ESM
- * @version v4.0.2
+ * @version v4.1.1
  * @author Julian Garnier
  * @license MIT
  * @copyright (c) 2025 Julian Garnier
@@ -56,10 +56,13 @@ const K = 1e3;
 const maxFps = 120;
 // Strings
 const emptyString = '';
-const shortTransforms = new Map();
-shortTransforms.set('x', 'translateX');
-shortTransforms.set('y', 'translateY');
-shortTransforms.set('z', 'translateZ');
+const shortTransforms = /*#__PURE__*/ (() => {
+    const map = new Map();
+    map.set('x', 'translateX');
+    map.set('y', 'translateY');
+    map.set('z', 'translateZ');
+    return map;
+})();
 const validTransforms = [
     'translateX',
     'translateY',
@@ -79,7 +82,7 @@ const validTransforms = [
     'matrix',
     'matrix3d',
 ];
-const transformsFragmentStrings = validTransforms.reduce((a, v) => ({ ...a, [v]: v + '(' }), {});
+const transformsFragmentStrings = /*#__PURE__*/ validTransforms.reduce((a, v) => ({ ...a, [v]: v + '(' }), {});
 // Functions
 /** @return {void} */
 const noop = () => { };
@@ -123,13 +126,15 @@ const defaults = {
     onComplete: noop,
     onRender: noop,
 };
+const scope = {
+    /** @type {Scope} */
+    current: null,
+    /** @type {Document|DOMTarget} */
+    root: doc,
+};
 const globals = {
     /** @type {DefaultsParams} */
     defaults,
-    /** @type {Document|DOMTarget} */
-    root: doc,
-    /** @type {Scope} */
-    scope: null,
     /** @type {Number} */
     precision: 4,
     /** @type {Number} */
@@ -137,7 +142,7 @@ const globals = {
     /** @type {Number} */
     tickThreshold: 200,
 };
-const globalVersions = { version: '4.0.2', engine: null };
+const globalVersions = { version: '4.1.1', engine: null };
 if (isBrowser) {
     if (!win.AnimeJS)
         win.AnimeJS = [];
@@ -244,6 +249,28 @@ const snap = (v, increment) => isArr(increment) ? increment.reduce((closest, cv)
  * @return {Number}
  */
 const interpolate = (start, end, progress) => start + (end - start) * progress;
+/**
+ * @param  {Number} min
+ * @param  {Number} max
+ * @param  {Number} [decimalLength]
+ * @return {Number}
+ */
+const random = (min, max, decimalLength) => { const m = 10 ** (decimalLength || 0); return floor((Math.random() * (max - min + (1 / m)) + min) * m) / m; };
+/**
+ * Adapted from https://bost.ocks.org/mike/shuffle/
+ * @param  {Array} items
+ * @return {Array}
+ */
+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;
+};
 /**
  * @param  {Number} v
  * @return {Number}
@@ -332,6 +359,32 @@ const addChild = (parent, child, sortMethod, prevProp = '_prev', nextProp = '_ne
     child[prevProp] = prev;
     child[nextProp] = next;
 };
+/**
+ * @param  {(...args: any[]) => Tickable | ((...args: any[]) => void)} constructor
+ * @return {(...args: any[]) => Tickable | ((...args: any[]) => void)}
+ */
+const createRefreshable = constructor => {
+    /** @type {Tickable} */
+    let tracked;
+    return (...args) => {
+        let currentIteration, currentIterationProgress, reversed, alternate;
+        if (tracked) {
+            currentIteration = tracked.currentIteration;
+            currentIterationProgress = tracked.iterationProgress;
+            reversed = tracked.reversed;
+            alternate = tracked._alternate;
+            tracked.revert();
+        }
+        const cleanup = constructor(...args);
+        if (cleanup && !isFnc(cleanup) && cleanup.revert)
+            tracked = cleanup;
+        if (!isUnd(currentIterationProgress)) {
+            /** @type {Tickable} */ (tracked).currentIteration = currentIteration;
+            /** @type {Tickable} */ (tracked).iterationProgress = (alternate ? !(currentIteration % 2) ? reversed : !reversed : reversed) ? 1 - currentIterationProgress : currentIterationProgress;
+        }
+        return cleanup || noop;
+    };
+};
 
 /*
  * Base class to control framerate and playback rate.
@@ -801,8 +854,8 @@ const addAdditiveAnimation = lookups => {
     return animation;
 };
 
-const engineTickMethod = isBrowser ? requestAnimationFrame : setImmediate;
-const engineCancelMethod = isBrowser ? cancelAnimationFrame : clearImmediate;
+const engineTickMethod = /*#__PURE__*/ (() => isBrowser ? requestAnimationFrame : setImmediate)();
+const engineCancelMethod = /*#__PURE__*/ (() => isBrowser ? cancelAnimationFrame : clearImmediate)();
 class Engine extends Clock {
     /** @param {Number} [initTime] */
     constructor(initTime) {
@@ -958,7 +1011,7 @@ const parseInlineTransforms = (target, propName, animationInlineStyles) => {
  * @return {NodeList|HTMLCollection}
  */
 function getNodeList(v) {
-    const n = isStr(v) ? globals.root.querySelectorAll(v) : v;
+    const n = isStr(v) ? scope.root.querySelectorAll(v) : v;
     if (n instanceof NodeList || n instanceof HTMLCollection)
         return n;
 }
@@ -1803,8 +1856,8 @@ class Timer extends Clock {
     constructor(parameters = {}, parent = null, parentPosition = 0) {
         super(0);
         const { id, delay, duration, reversed, alternate, loop, loopDelay, autoplay, frameRate, playbackRate, onComplete, onLoop, onPause, onBegin, onBeforeUpdate, onUpdate, } = parameters;
-        if (globals.scope)
-            globals.scope.revertibles.push(this);
+        if (scope.current)
+            scope.current.register(this);
         const timerInitTime = parent ? 0 : engine._elapsedTime;
         const timerDefaults = parent ? parent.defaults : globals.defaults;
         const timerDelay = /** @type {Number} */ (isFnc(delay) || isUnd(delay) ? timerDefaults.delay : +delay);
@@ -1924,14 +1977,14 @@ class Timer extends Clock {
         this.currentTime = (this.iterationDuration * this._currentIteration) + time;
     }
     get progress() {
-        return clamp(round(this._currentTime / this.duration, 5), 0, 1);
+        return clamp(round(this._currentTime / this.duration, 10), 0, 1);
     }
     /** @param {Number} progress  */
     set progress(progress) {
         this.currentTime = this.duration * progress;
     }
     get iterationProgress() {
-        return clamp(round(this._iterationTime / this.iterationDuration, 5), 0, 1);
+        return clamp(round(this._iterationTime / this.iterationDuration, 10), 0, 1);
     }
     /** @param {Number} progress  */
     set iterationProgress(progress) {
@@ -3090,12 +3143,13 @@ class JSAnimation extends Timer {
      */
     refresh() {
         forEachChildren(this, (/** @type {Tween} */ tween) => {
-            const ogValue = getOriginalAnimatableValue(tween.target, tween.property, tween._tweenType);
-            decomposeRawValue(ogValue, decomposedOriginalValue);
-            tween._fromNumbers = cloneArray(decomposedOriginalValue.d);
-            tween._fromNumber = decomposedOriginalValue.n;
-            if (tween._func) {
-                decomposeRawValue(tween._func(), toTargetObject);
+            const tweenFunc = tween._func;
+            if (tweenFunc) {
+                const ogValue = getOriginalAnimatableValue(tween.target, tween.property, tween._tweenType);
+                decomposeRawValue(ogValue, decomposedOriginalValue);
+                decomposeRawValue(tweenFunc(), toTargetObject);
+                tween._fromNumbers = cloneArray(decomposedOriginalValue.d);
+                tween._fromNumber = decomposedOriginalValue.n;
                 tween._toNumbers = cloneArray(toTargetObject.d);
                 tween._strings = cloneArray(toTargetObject.s);
                 tween._toNumber = toTargetObject.n;
@@ -3243,31 +3297,8 @@ const commonDefaultPXProperties = [
     'borderRadius',
     ...transformsShorthands
 ];
-const validIndividualTransforms = [...transformsShorthands, ...validTransforms.filter(t => ['X', 'Y', 'Z'].some(axis => t.endsWith(axis)))];
-// Setting it to true in case CSS.registerProperty is not supported will automatically skip the registration and fallback to no animation
-let transformsPropertiesRegistered = isBrowser && (isUnd(CSS) || !Object.hasOwnProperty.call(CSS, 'registerProperty'));
-const registerTransformsProperties = () => {
-    if (transformsPropertiesRegistered)
-        return;
-    validTransforms.forEach(t => {
-        const isSkew = stringStartsWith(t, 'skew');
-        const isScale = stringStartsWith(t, 'scale');
-        const isRotate = stringStartsWith(t, 'rotate');
-        const isTranslate = stringStartsWith(t, 'translate');
-        const isAngle = isRotate || isSkew;
-        const syntax = isAngle ? '<angle>' : isScale ? "<number>" : isTranslate ? "<length-percentage>" : "*";
-        try {
-            CSS.registerProperty({
-                name: '--' + t,
-                syntax,
-                inherits: false,
-                initialValue: isTranslate ? '0px' : isAngle ? '0deg' : isScale ? '1' : '0',
-            });
-        }
-        catch { }
-    });
-    transformsPropertiesRegistered = true;
-};
+const validIndividualTransforms = /*#__PURE__*/ (() => [...transformsShorthands, ...validTransforms.filter(t => ['X', 'Y', 'Z'].some(axis => t.endsWith(axis)))])();
+let transformsPropertiesRegistered = null;
 const WAAPIAnimationsLookups = {
     _head: null,
     _tail: null,
@@ -3380,9 +3411,34 @@ class WAAPIAnimation {
      * @param {WAAPIAnimationParams} params
      */
     constructor(targets, params) {
-        if (globals.scope)
-            globals.scope.revertibles.push(this);
-        registerTransformsProperties();
+        if (scope.current)
+            scope.current.register(this);
+        // Skip the registration and fallback to no animation in case CSS.registerProperty is not supported
+        if (isNil(transformsPropertiesRegistered)) {
+            if (isBrowser && (isUnd(CSS) || !Object.hasOwnProperty.call(CSS, 'registerProperty'))) {
+                transformsPropertiesRegistered = false;
+            }
+            else {
+                validTransforms.forEach(t => {
+                    const isSkew = stringStartsWith(t, 'skew');
+                    const isScale = stringStartsWith(t, 'scale');
+                    const isRotate = stringStartsWith(t, 'rotate');
+                    const isTranslate = stringStartsWith(t, 'translate');
+                    const isAngle = isRotate || isSkew;
+                    const syntax = isAngle ? '<angle>' : isScale ? "<number>" : isTranslate ? "<length-percentage>" : "*";
+                    try {
+                        CSS.registerProperty({
+                            name: '--' + t,
+                            syntax,
+                            inherits: false,
+                            initialValue: isTranslate ? '0px' : isAngle ? '0deg' : isScale ? '1' : '0',
+                        });
+                    }
+                    catch { }
+                });
+                transformsPropertiesRegistered = true;
+            }
+        }
         const parsedTargets = registerTargets(targets);
         const targetsLength = parsedTargets.length;
         if (!targetsLength) {
@@ -3815,32 +3871,15 @@ const remove = (targets, renderable, propertyName) => {
     return targetsArray;
 };
 /**
- * @param  {Number} min
- * @param  {Number} max
- * @param  {Number} [decimalLength]
- * @return {Number}
+ * @param  {(...args: any[]) => Tickable} constructor
+ * @return {(...args: any[]) => Tickable}
  */
-const random = (min, max, decimalLength) => { const m = 10 ** (decimalLength || 0); return floor((Math.random() * (max - min + (1 / m)) + min) * m) / m; };
+const keepTime = createRefreshable;
 /**
  * @param  {String|Array} items
  * @return {any}
  */
 const randomPick = items => items[random(0, items.length - 1)];
-/**
- * Adapted from https://bost.ocks.org/mike/shuffle/
- * @param  {Array} items
- * @return {Array}
- */
-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;
-};
 /**
  * @param  {Number|String} v
  * @param  {Number} decimalLength
@@ -4021,6 +4060,7 @@ const utils = {
     shuffle,
     lerp,
     sync,
+    keepTime,
     clamp: /** @type {typeof clamp & ChainedClamp} */ (makeChainable(clamp)),
     round: /** @type {typeof round & ChainedRound} */ (makeChainable(round)),
     snap: /** @type {typeof snap & ChainedSnap} */ (makeChainable(snap)),
@@ -4340,8 +4380,8 @@ class Animatable {
      * @param {AnimatableParams} parameters
      */
     constructor(targets, parameters) {
-        if (globals.scope)
-            globals.scope.revertibles.push(this);
+        if (scope.current)
+            scope.current.register(this);
         /** @type {AnimationParams} */
         const globalParams = {};
         const properties = {};
@@ -4665,8 +4705,8 @@ class Draggable {
     constructor(target, parameters = {}) {
         if (!target)
             return;
-        if (globals.scope)
-            globals.scope.revertibles.push(this);
+        if (scope.current)
+            scope.current.register(this);
         const paramX = parameters.x;
         const paramY = parameters.y;
         const trigger = parameters.trigger;
@@ -5696,39 +5736,11 @@ class Draggable {
 const createDraggable = (target, parameters) => new Draggable(target, parameters);
 
 
-/**
- * @typedef {Object} ReactRef
- * @property {HTMLElement|SVGElement|null} [current]
- */
-/**
- * @typedef {Object} AngularRef
- * @property {HTMLElement|SVGElement} [nativeElement]
- */
-/**
- * @typedef {Object} ScopeParams
- * @property {DOMTargetSelector|ReactRef|AngularRef} [root]
- * @property {DefaultsParams} [defaults]
- * @property {Record<String, String>} [mediaQueries]
- */
-/**
- * @callback ScopeCleanup
- * @param {Scope} [scope]
- */
-/**
- * @callback ScopeConstructor
- * @param {Scope} [scope]
- * @return {ScopeCleanup|void}
- */
-/**
- * @callback ScopeMethod
- * @param {...*} args
- * @return {ScopeCleanup|void}
- */
 class Scope {
     /** @param {ScopeParams} [parameters] */
     constructor(parameters = {}) {
-        if (globals.scope)
-            globals.scope.revertibles.push(this);
+        if (scope.current)
+            scope.current.register(this);
         const rootParam = parameters.root;
         /** @type {Document|DOMTarget} */
         let root = doc;
@@ -5745,13 +5757,23 @@ class Scope {
         this.defaults = scopeDefaults ? mergeObjects(scopeDefaults, globalDefault) : globalDefault;
         /** @type {Document|DOMTarget} */
         this.root = root;
-        /** @type {Array<ScopeConstructor>} */
+        /** @type {Array<ScopeConstructorCallback>} */
         this.constructors = [];
-        /** @type {Array<Function>} */
+        /** @type {Array<ScopeCleanupCallback>} */
         this.revertConstructors = [];
         /** @type {Array<Revertible>} */
         this.revertibles = [];
-        /** @type {Record<String, Function>} */
+        /** @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 = {};
@@ -5768,26 +5790,30 @@ class Scope {
         }
     }
     /**
-     * @callback ScoppedCallback
-     * @param {this} scope
-     * @return {any}
-     *
-     * @param {ScoppedCallback} cb
-     * @return {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 = globals.scope;
-        let activeRoot = globals.root;
+        let activeScope = scope.current;
+        let activeRoot = scope.root;
         let activeDefaults = globals.defaults;
-        globals.scope = this;
-        globals.root = this.root;
+        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);
-        globals.scope = activeScope;
-        globals.root = activeRoot;
+        scope.current = activeScope;
+        scope.root = activeRoot;
         globals.defaults = activeDefaults;
         return returned;
     }
@@ -5795,6 +5821,7 @@ class Scope {
      * @return {this}
      */
     refresh() {
+        this.onceIndex = 0;
         this.execute(() => {
             let i = this.revertibles.length;
             let y = this.revertConstructors.length;
@@ -5804,9 +5831,9 @@ class Scope {
                 this.revertConstructors[y](this);
             this.revertibles.length = 0;
             this.revertConstructors.length = 0;
-            this.constructors.forEach(constructor => {
+            this.constructors.forEach((/** @type {ScopeConstructorCallback} */ constructor) => {
                 const revertConstructor = constructor(this);
-                if (revertConstructor) {
+                if (isFnc(revertConstructor)) {
                     this.revertConstructors.push(revertConstructor);
                 }
             });
@@ -5814,28 +5841,26 @@ class Scope {
         return this;
     }
     /**
-     * @callback contructorCallback
-     * @param {this} self
-     *
      * @overload
      * @param {String} a1
      * @param {ScopeMethod} a2
      * @return {this}
      *
      * @overload
-     * @param {contructorCallback} a1
+     * @param {ScopeConstructorCallback} a1
      * @return {this}
      *
-     * @param {String|contructorCallback} a1
+     * @param {String|ScopeConstructorCallback} a1
      * @param {ScopeMethod} [a2]
      */
     add(a1, a2) {
+        this.once = false;
         if (isFnc(a1)) {
-            const constructor = /** @type {contructorCallback} */ (a1);
+            const constructor = /** @type {ScopeConstructorCallback} */ (a1);
             this.constructors.push(constructor);
             this.execute(() => {
                 const revertConstructor = constructor(this);
-                if (revertConstructor) {
+                if (isFnc(revertConstructor)) {
                     this.revertConstructors.push(revertConstructor);
                 }
             });
@@ -5845,6 +5870,46 @@ class Scope {
         }
         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} */ (createRefreshable(cb));
+        this.constructorsOnce[currentIndex] = constructor;
+        let trackedTickable;
+        this.execute(() => {
+            trackedTickable = constructor(this);
+        });
+        return trackedTickable;
+    }
     /**
      * @param {Event} e
      */
@@ -5858,18 +5923,30 @@ class Scope {
     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 y = revertConstructors.length;
+        let j = revertConstructors.length;
+        let k = revertiblesOnce.length;
+        let l = revertConstructorsOnce.length;
         while (i--)
             revertibles[i].revert();
-        while (y--)
-            revertConstructors[y](this);
+        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 = {};
@@ -6186,7 +6263,7 @@ const getAnimationDomTarget = linked => {
     return $linkedTarget;
 };
 let scrollerIndex = 0;
-const debugColors = ['#FF4B4B', '#FF971B', '#FFC730', '#F9F640', '#7AFF5A', '#18FF74', '#17E09B', '#3CFFEC', '#05DBE9', '#33B3F1', '#638CF9', '#C563FE', '#FF4FCF', '#F93F8A'];
+const debugColors$1 = ['#FF4B4B', '#FF971B', '#FFC730', '#F9F640', '#7AFF5A', '#18FF74', '#17E09B', '#3CFFEC', '#05DBE9', '#33B3F1', '#638CF9', '#C563FE', '#FF4FCF', '#F93F8A'];
 /**
  * @typedef {Object} ScrollThresholdParam
  * @property {ScrollThresholdValue} [target]
@@ -6227,8 +6304,8 @@ class ScrollObserver {
      * @param {ScrollObserverParams} parameters
      */
     constructor(parameters = {}) {
-        if (globals.scope)
-            globals.scope.revertibles.push(this);
+        if (scope.current)
+            scope.current.register(this);
         const syncMode = setValue(parameters.sync, 'play pause');
         const ease = syncMode ? parseEasings(/** @type {EasingParam} */ (syncMode)) : null;
         const isLinear = syncMode && (syncMode === 'linear' || syncMode === none);
@@ -6418,7 +6495,7 @@ class ScrollObserver {
         const $debug = doc.createElement('div');
         const $thresholds = doc.createElement('div');
         const $triggers = doc.createElement('div');
-        const color = debugColors[this.index % debugColors.length];
+        const color = debugColors$1[this.index % debugColors$1.length];
         const useWin = container.useWin;
         const containerWidth = useWin ? container.winWidth : container.width;
         const containerHeight = useWin ? container.winHeight : container.height;
@@ -6771,27 +6848,475 @@ class ScrollObserver {
 const onScroll = (parameters = {}) => new ScrollObserver(parameters);
 
 
+const segmenter = !isUnd(Intl) && Intl.Segmenter;
+const valueRgx = /\{value\}/g;
+const indexRgx = /\{i\}/g;
+const whiteSpaceGroupRgx = /(\s+)/;
+const whiteSpaceRgx = /^\s+$/;
+const lineType = 'line';
+const wordType = 'word';
+const charType = 'char';
+const dataLine = `data-line`;
+/**
+ * @typedef {Object} Segment
+ * @property {String} segment
+ * @property {Boolean} [isWordLike]
+ */
+/**
+ * @typedef {Object} Segmenter
+ * @property {function(String): Iterable<Segment>} segment
+ */
+/** @type {Segmenter} */
+let wordSegmenter = null;
+/** @type {Segmenter} */
+let graphemeSegmenter = null;
+let $splitTemplate = null;
+/**
+ * @param  {Segment} seg
+ * @return {Boolean}
+ */
+const isSegmentWordLike = seg => {
+    return seg.isWordLike ||
+        seg.segment === ' ' || // Consider spaces as words first, then handle them diffrently later
+        isNum(+seg.segment); // Safari doesn't considers numbers as words
+};
 /**
- * @typedef  {Object} StaggerParameters
- * @property {Number|String} [start]
- * @property {Number|'first'|'center'|'last'} [from]
- * @property {Boolean} [reversed]
- * @property {Array.<Number>} [grid]
- * @property {('x'|'y')} [axis]
- * @property {EasingParam} [ease]
- * @property {TweenModifier} [modifier]
+ * @param {HTMLElement} $el
  */
+const setAriaHidden = $el => $el.setAttribute('aria-hidden', 'true');
 /**
- * @callback StaggerFunction
- * @param {Target} [target]
- * @param {Number} [index]
- * @param {Number} [length]
- * @param {Timeline} [tl]
- * @return {Number|String}
+ * @param {DOMTarget} $el
+ * @param {String} type
+ * @return {Array<HTMLElement>}
+ */
+const getAllTopLevelElements = ($el, type) => [... /** @type {*} */($el.querySelectorAll(`[data-${type}]:not([data-${type}] [data-${type}])`))];
+const debugColors = { line: '#00D672', word: '#FF4B4B', char: '#5A87FF' };
+/**
+ * @param {HTMLElement} $el
+ */
+const filterEmptyElements = $el => {
+    if (!$el.childElementCount && !$el.textContent.trim()) {
+        const $parent = $el.parentElement;
+        $el.remove();
+        if ($parent)
+            filterEmptyElements($parent);
+    }
+};
+/**
+ * @param {HTMLElement} $el
+ * @param {Number} lineIndex
+ * @param {Set<HTMLElement>} bin
+ * @returns {Set<HTMLElement>}
+ */
+const filterLineElements = ($el, lineIndex, bin) => {
+    const dataLineAttr = $el.getAttribute(dataLine);
+    if (dataLineAttr !== null && +dataLineAttr !== lineIndex || $el.tagName === 'BR')
+        bin.add($el);
+    let i = $el.childElementCount;
+    while (i--)
+        filterLineElements(/** @type {HTMLElement} */ ($el.children[i]), lineIndex, bin);
+    return bin;
+};
+/**
+ * @param  {'line'|'word'|'char'} type
+ * @param  {splitTemplateParams} params
+ * @return {String}
+ */
+const generateTemplate = (type, params = {}) => {
+    let template = ``;
+    const classString = isStr(params.class) ? ` class="${params.class}"` : '';
+    const cloneType = setValue(params.clone, false);
+    const wrapType = setValue(params.wrap, false);
+    const overflow = wrapType ? wrapType === true ? 'clip' : wrapType : cloneType ? 'clip' : false;
+    if (wrapType)
+        template += `<span${overflow ? ` style="overflow:${overflow};"` : ''}>`;
+    template += `<span${classString}${cloneType ? ` style="position:relative;"` : ''} data-${type}="{i}">`;
+    if (cloneType) {
+        const left = cloneType === 'left' ? '-100%' : cloneType === 'right' ? '100%' : '0';
+        const top = cloneType === 'top' ? '-100%' : cloneType === 'bottom' ? '100%' : '0';
+        template += `<span>{value}</span>`;
+        template += `<span inert style="position:absolute;top:${top};left:${left};white-space:nowrap;">{value}</span>`;
+    }
+    else {
+        template += `{value}`;
+    }
+    template += `</span>`;
+    if (wrapType)
+        template += `</span>`;
+    return template;
+};
+/**
+ * @param  {String|SplitFunctionValue} htmlTemplate
+ * @param  {Array<HTMLElement>} store
+ * @param  {Node|HTMLElement} node
+ * @param  {DocumentFragment} $parentFragment
+ * @param  {'line'|'word'|'char'} type
+ * @param  {Boolean} debug
+ * @param  {Number} lineIndex
+ * @param  {Number} [wordIndex]
+ * @param  {Number} [charIndex]
+ * @return {HTMLElement}
+ */
+const processHTMLTemplate = (htmlTemplate, store, node, $parentFragment, type, debug, lineIndex, wordIndex, charIndex) => {
+    const isLine = type === lineType;
+    const isChar = type === charType;
+    const className = `_${type}_`;
+    const template = isFnc(htmlTemplate) ? htmlTemplate(node) : htmlTemplate;
+    const displayStyle = isLine ? 'block' : 'inline-block';
+    $splitTemplate.innerHTML = template
+        .replace(valueRgx, `<i class="${className}"></i>`)
+        .replace(indexRgx, `${isChar ? charIndex : isLine ? lineIndex : wordIndex}`);
+    const $content = $splitTemplate.content;
+    const $highestParent = /** @type {HTMLElement} */ ($content.firstElementChild);
+    const $split = /** @type {HTMLElement} */ ($content.querySelector(`[data-${type}]`)) || $highestParent;
+    const $replacables = /** @type {NodeListOf<HTMLElement>} */ ($content.querySelectorAll(`i.${className}`));
+    const replacablesLength = $replacables.length;
+    if (replacablesLength) {
+        $highestParent.style.display = displayStyle;
+        $split.style.display = displayStyle;
+        $split.setAttribute(dataLine, `${lineIndex}`);
+        if (!isLine) {
+            $split.setAttribute('data-word', `${wordIndex}`);
+            if (isChar)
+                $split.setAttribute('data-char', `${charIndex}`);
+        }
+        let i = replacablesLength;
+        while (i--) {
+            const $replace = $replacables[i];
+            const $closestParent = $replace.parentElement;
+            $closestParent.style.display = displayStyle;
+            if (isLine) {
+                $closestParent.innerHTML = /** @type {HTMLElement} */ (node).innerHTML;
+            }
+            else {
+                $closestParent.replaceChild(node.cloneNode(true), $replace);
+            }
+        }
+        store.push($split);
+        $parentFragment.appendChild($content);
+    }
+    else {
+        console.warn(`The expression "{value}" is missing from the provided template.`);
+    }
+    if (debug)
+        $highestParent.style.outline = `1px dotted ${debugColors[type]}`;
+    return $highestParent;
+};
+/**
+ * A class that splits text into words and wraps them in span elements while preserving the original HTML structure.
+ * @class
+ */
+class TextSplitter {
+    /**
+     * @param  {HTMLElement|NodeList|String|Array<HTMLElement>} target
+     * @param  {TextSplitterParams} [parameters]
+     */
+    constructor(target, parameters = {}) {
+        // Only init segmenters when needed
+        if (!wordSegmenter)
+            wordSegmenter = segmenter ? new segmenter([], { granularity: wordType }) : {
+                segment: (text) => {
+                    const segments = [];
+                    const words = text.split(whiteSpaceGroupRgx);
+                    for (let i = 0, l = words.length; i < l; i++) {
+                        const segment = words[i];
+                        segments.push({
+                            segment,
+                            isWordLike: !whiteSpaceRgx.test(segment), // Consider non-whitespace as word-like
+                        });
+                    }
+                    return segments;
+                }
+            };
+        if (!graphemeSegmenter)
+            graphemeSegmenter = segmenter ? new segmenter([], { granularity: 'grapheme' }) : {
+                segment: text => [...text].map(char => ({ segment: char }))
+            };
+        if (!$splitTemplate && isBrowser)
+            $splitTemplate = doc.createElement('template');
+        if (scope.current)
+            scope.current.register(this);
+        const { words, chars, lines, accessible, includeSpaces, debug } = parameters;
+        const $target = /** @type {HTMLElement} */ ((target = isArr(target) ? target[0] : target) && /** @type {Node} */ (target).nodeType ? target : (getNodeList(target) || [])[0]);
+        const lineParams = lines === true ? {} : lines;
+        const wordParams = words === true || isUnd(words) ? {} : words;
+        const charParams = chars === true ? {} : chars;
+        this.debug = setValue(debug, false);
+        this.includeSpaces = setValue(includeSpaces, false);
+        this.accessible = setValue(accessible, true);
+        this.linesOnly = lineParams && (!wordParams && !charParams);
+        /** @type {String|false|SplitFunctionValue} */
+        this.lineTemplate = isObj(lineParams) ? generateTemplate(lineType, /** @type {splitTemplateParams} */ (lineParams)) : lineParams;
+        /** @type {String|false|SplitFunctionValue} */
+        this.wordTemplate = isObj(wordParams) || this.linesOnly ? generateTemplate(wordType, /** @type {splitTemplateParams} */ (wordParams)) : wordParams;
+        /** @type {String|false|SplitFunctionValue} */
+        this.charTemplate = isObj(charParams) ? generateTemplate(charType, /** @type {splitTemplateParams} */ (charParams)) : charParams;
+        this.$target = $target;
+        this.html = $target && $target.innerHTML;
+        this.lines = [];
+        this.words = [];
+        this.chars = [];
+        this.effects = [];
+        this.effectsCleanups = [];
+        this.cache = null;
+        this.ready = false;
+        this.width = 0;
+        this.resizeTimeout = null;
+        const handleSplit = () => this.html && (lineParams || wordParams || charParams) && this.split();
+        // Make sure this is declared before calling handleSplit() in case revert() is called inside an effect callback
+        this.resizeObserver = new ResizeObserver(() => {
+            // Use a setTimeout instead of a Timer for better tree shaking
+            clearTimeout(this.resizeTimeout);
+            this.resizeTimeout = setTimeout(() => {
+                const currentWidth = /** @type {HTMLElement} */ ($target).offsetWidth;
+                if (currentWidth === this.width)
+                    return;
+                this.width = currentWidth;
+                handleSplit();
+            }, 150);
+        });
+        // Only declare the font ready promise when splitting by lines and not alreay split
+        if (this.lineTemplate && !this.ready) {
+            doc.fonts.ready.then(handleSplit);
+        }
+        else {
+            handleSplit();
+        }
+        $target ? this.resizeObserver.observe($target) : console.warn('No Text Splitter target found.');
+    }
+    /**
+     * @param  {(...args: any[]) => Tickable | (() => void)} effect
+     * @return this
+     */
+    addEffect(effect) {
+        if (!isFnc(effect))
+            return console.warn('Effect must return a function.');
+        const refreshableEffect = createRefreshable(effect);
+        this.effects.push(refreshableEffect);
+        if (this.ready)
+            this.effectsCleanups[this.effects.length - 1] = refreshableEffect(this);
+        return this;
+    }
+    revert() {
+        clearTimeout(this.resizeTimeout);
+        this.lines.length = this.words.length = this.chars.length = 0;
+        this.resizeObserver.disconnect();
+        // Make sure to revert the effects after disconnecting the resizeObserver to avoid triggering it in the process
+        this.effectsCleanups.forEach(cleanup => isFnc(cleanup) ? cleanup(this) : cleanup.revert && cleanup.revert());
+        this.$target.innerHTML = this.html;
+        return this;
+    }
+    /**
+     * Recursively processes a node and its children
+     * @param {Node} node
+     */
+    splitNode(node) {
+        const wordTemplate = this.wordTemplate;
+        const charTemplate = this.charTemplate;
+        const includeSpaces = this.includeSpaces;
+        const debug = this.debug;
+        const nodeType = node.nodeType;
+        if (nodeType === 3) {
+            const nodeText = node.nodeValue;
+            // If the nodeText is only whitespace, leave it as is
+            if (nodeText.trim()) {
+                const tempWords = [];
+                const words = this.words;
+                const chars = this.chars;
+                const wordSegments = wordSegmenter.segment(nodeText);
+                const $wordsFragment = doc.createDocumentFragment();
+                let prevSeg = null;
+                for (const wordSegment of wordSegments) {
+                    const segment = wordSegment.segment;
+                    const isWordLike = isSegmentWordLike(wordSegment);
+                    // Determine if this segment should be a new word, first segment always becomes a new word
+                    if (!prevSeg || (isWordLike && (prevSeg && (isSegmentWordLike(prevSeg))))) {
+                        tempWords.push(segment);
+                    }
+                    else {
+                        // Only concatenate if both current and previous are non-word-like and don't contain spaces
+                        const lastWordIndex = tempWords.length - 1;
+                        const lastWord = tempWords[lastWordIndex];
+                        if (!lastWord.includes(' ') && !segment.includes(' ')) {
+                            tempWords[lastWordIndex] += segment;
+                        }
+                        else {
+                            tempWords.push(segment);
+                        }
+                    }
+                    prevSeg = wordSegment;
+                }
+                for (let i = 0, l = tempWords.length; i < l; i++) {
+                    const word = tempWords[i];
+                    if (!word.trim()) {
+                        // Preserve whitespace only if includeSpaces is false and if the current space is not the first node
+                        if (i && includeSpaces)
+                            continue;
+                        $wordsFragment.appendChild(doc.createTextNode(word));
+                    }
+                    else {
+                        const nextWord = tempWords[i + 1];
+                        const hasWordFollowingSpace = includeSpaces && nextWord && !nextWord.trim();
+                        const wordToProcess = word;
+                        const charSegments = charTemplate ? graphemeSegmenter.segment(wordToProcess) : null;
+                        const $charsFragment = charTemplate ? doc.createDocumentFragment() : doc.createTextNode(hasWordFollowingSpace ? word + '\xa0' : word);
+                        if (charTemplate) {
+                            const charSegmentsArray = [...charSegments];
+                            for (let j = 0, jl = charSegmentsArray.length; j < jl; j++) {
+                                const charSegment = charSegmentsArray[j];
+                                const isLastChar = j === jl - 1;
+                                // If this is the last character and includeSpaces is true with a following space, append the space
+                                const charText = isLastChar && hasWordFollowingSpace ? charSegment.segment + '\xa0' : charSegment.segment;
+                                const $charNode = doc.createTextNode(charText);
+                                processHTMLTemplate(charTemplate, chars, $charNode, /** @type {DocumentFragment} */ ($charsFragment), charType, debug, -1, words.length, chars.length);
+                            }
+                        }
+                        if (wordTemplate) {
+                            processHTMLTemplate(wordTemplate, words, $charsFragment, $wordsFragment, wordType, debug, -1, words.length, chars.length);
+                            // Chars elements must be re-parsed in the split() method if both words and chars are parsed
+                        }
+                        else if (charTemplate) {
+                            $wordsFragment.appendChild($charsFragment);
+                        }
+                        else {
+                            $wordsFragment.appendChild(doc.createTextNode(word));
+                        }
+                        // Skip the next iteration if we included a space
+                        if (hasWordFollowingSpace)
+                            i++;
+                    }
+                }
+                node.parentNode.replaceChild($wordsFragment, node);
+            }
+        }
+        else if (nodeType === 1) {
+            // Converting to an array is necessary to work around childNodes pottential mutation
+            const childNodes = /** @type {Array<Node>} */ ([... /** @type {*} */(node.childNodes)]);
+            for (let i = 0, l = childNodes.length; i < l; i++)
+                this.splitNode(childNodes[i]);
+        }
+    }
+    /**
+     * @param {Boolean} clearCache
+     * @return {this}
+     */
+    split(clearCache = false) {
+        const $el = this.$target;
+        const isCached = !!this.cache && !clearCache;
+        const lineTemplate = this.lineTemplate;
+        const wordTemplate = this.wordTemplate;
+        const charTemplate = this.charTemplate;
+        const fontsReady = doc.fonts.status !== 'loading';
+        const canSplitLines = lineTemplate && fontsReady;
+        this.ready = !lineTemplate || fontsReady;
+        if (canSplitLines || clearCache) {
+            // No need to revert effects animations here since it's already taken care by the refreshable
+            this.effectsCleanups.forEach(cleanup => isFnc(cleanup) && cleanup(this));
+        }
+        if (!isCached) {
+            if (clearCache) {
+                $el.innerHTML = this.html;
+                this.words.length = this.chars.length = 0;
+            }
+            this.splitNode($el);
+            this.cache = $el.innerHTML;
+        }
+        if (canSplitLines) {
+            if (isCached)
+                $el.innerHTML = this.cache;
+            this.lines.length = 0;
+            if (wordTemplate)
+                this.words = getAllTopLevelElements($el, wordType);
+        }
+        // Always reparse characters after a line reset or if both words and chars are activated
+        if (charTemplate && (canSplitLines || wordTemplate)) {
+            this.chars = getAllTopLevelElements($el, charType);
+        }
+        // Words are used when lines only and prioritized over chars
+        const elementsArray = this.words.length ? this.words : this.chars;
+        let y, linesCount = 0;
+        for (let i = 0, l = elementsArray.length; i < l; i++) {
+            const $el = elementsArray[i];
+            const { top, height } = $el.getBoundingClientRect();
+            if (y && top - y > height * .5)
+                linesCount++;
+            $el.setAttribute(dataLine, `${linesCount}`);
+            const nested = $el.querySelectorAll(`[${dataLine}]`);
+            let c = nested.length;
+            while (c--)
+                nested[c].setAttribute(dataLine, `${linesCount}`);
+            y = top;
+        }
+        if (canSplitLines) {
+            const linesFragment = doc.createDocumentFragment();
+            const parents = new Set();
+            const clones = [];
+            for (let lineIndex = 0; lineIndex < linesCount + 1; lineIndex++) {
+                const $clone = /** @type {HTMLElement} */ ($el.cloneNode(true));
+                filterLineElements($clone, lineIndex, new Set()).forEach($el => {
+                    const $parent = $el.parentElement;
+                    if ($parent)
+                        parents.add($parent);
+                    $el.remove();
+                });
+                clones.push($clone);
+            }
+            parents.forEach(filterEmptyElements);
+            for (let cloneIndex = 0, clonesLength = clones.length; cloneIndex < clonesLength; cloneIndex++) {
+                processHTMLTemplate(lineTemplate, this.lines, clones[cloneIndex], linesFragment, lineType, this.debug, cloneIndex);
+            }
+            $el.innerHTML = '';
+            $el.appendChild(linesFragment);
+            if (wordTemplate)
+                this.words = getAllTopLevelElements($el, wordType);
+            if (charTemplate)
+                this.chars = getAllTopLevelElements($el, charType);
+        }
+        // Remove the word wrappers and clear the words array if lines split only
+        if (this.linesOnly) {
+            const words = this.words;
+            let w = words.length;
+            while (w--) {
+                const $word = words[w];
+                $word.replaceWith($word.textContent);
+            }
+            words.length = 0;
+        }
+        if (this.accessible && (canSplitLines || !isCached)) {
+            const $accessible = doc.createElement('span');
+            // Make the accessible element visually-hidden (https://www.scottohara.me/blog/2017/04/14/inclusively-hidden.html)
+            $accessible.style.cssText = `position:absolute;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);width:1px;height:1px;white-space:nowrap;`;
+            // $accessible.setAttribute('tabindex', '-1');
+            $accessible.innerHTML = this.html;
+            $el.insertBefore($accessible, $el.firstChild);
+            this.lines.forEach(setAriaHidden);
+            this.words.forEach(setAriaHidden);
+            this.chars.forEach(setAriaHidden);
+        }
+        this.width = /** @type {HTMLElement} */ ($el).offsetWidth;
+        if (canSplitLines || clearCache) {
+            this.effects.forEach((effect, i) => this.effectsCleanups[i] = effect(this));
+        }
+        return this;
+    }
+    refresh() {
+        this.split(true);
+    }
+}
+/**
+ * @param  {HTMLElement|NodeList|String|Array<HTMLElement>} target
+ * @param  {TextSplitterParams} [parameters]
+ * @return {TextSplitter}
  */
+const split = (target, parameters) => new TextSplitter(target, parameters);
+const text = {
+    split,
+};
+
+
 /**
  * @param  {Number|String|[Number|String,Number|String]} val
- * @param  {StaggerParameters} params
+ * @param  {StaggerParams} params
  * @return {StaggerFunction}
  */
 const stagger = (val, params = {}) => {
@@ -6805,22 +7330,29 @@ const stagger = (val, params = {}) => {
     const staggerEase = hasSpring ? /** @type {Spring} */ (ease).ease : hasEasing ? parseEasings(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 (_, i, t, tl) => {
+    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 = (t - 1) / 2;
+            fromIndex = (total - 1) / 2;
         if (fromLast)
-            fromIndex = t - 1;
+            fromIndex = total - 1;
         if (!values.length) {
-            for (let index = 0; index < t; index++) {
+            for (let index = 0; index < total; index++) {
                 if (!grid) {
                     values.push(abs(fromIndex - index));
                 }
@@ -6844,11 +7376,13 @@ const stagger = (val, params = {}) => {
                 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[i], 2)) || 0);
+        let output = offset + ((spacing * round(values[staggerIndex], 2)) || 0);
         if (params.modifier)
             output = params.modifier(output);
         if (unitMatch)
@@ -6857,4 +7391,4 @@ const stagger = (val, params = {}) => {
     };
 };
 
-export { Animatable, Draggable, JSAnimation, Scope, ScrollObserver, Spring, Timeline, Timer, WAAPIAnimation, animate, createAnimatable, createDraggable, createScope, createSpring, createTimeline, createTimer, eases, engine, onScroll, scrollContainers, stagger, svg, utils, waapi };
+export { Animatable, Draggable, JSAnimation, Scope, ScrollObserver, Spring, TextSplitter, Timeline, Timer, WAAPIAnimation, animate, createAnimatable, createDraggable, createScope, createSpring, createTimeline, createTimer, eases, engine, onScroll, scrollContainers, stagger, svg, text, utils, waapi };