animejs 4.1.4 → 4.2.0

package/dist/modules/timer/timer.js

@@ -0,0 +1,488 @@
+/**
+ * Anime.js - timer - ESM
+ * @version v4.2.0
+ * @license MIT
+ * @copyright 2025 - Julian Garnier
+ */
+
+import { minValue, noop, maxValue, compositionTypes, tickModes } from '../core/consts.js';
+import { isFnc, isUnd, now, clampInfinity, clamp, round, forEachChildren, addChild, normalizeTime, floor } from '../core/helpers.js';
+import { globals, scope } from '../core/globals.js';
+import { setValue } from '../core/values.js';
+import { tick } from '../core/render.js';
+import { removeTweenSliblings, composeTween, getTweenSiblings } from '../animation/composition.js';
+import { Clock } from '../core/clock.js';
+import { engine } from '../engine/engine.js';
+
+/**
+ * @import {
+ *   Callback,
+ *   TimerParams,
+ *   Renderable,
+ *   Tween,
+ * } from '../types/index.js'
+*/
+
+/**
+ * @import {
+ *   ScrollObserver,
+ * } from '../events/scroll.js'
+*/
+
+/**
+ * @import {
+ *   Timeline,
+ * } from '../timeline/timeline.js'
+*/
+
+/**
+ * @param  {Timer} timer
+ * @return {Timer}
+ */
+const resetTimerProperties = timer => {
+  timer.paused = true;
+  timer.began = false;
+  timer.completed = false;
+  return timer;
+};
+
+/**
+ * @param  {Timer} timer
+ * @return {Timer}
+ */
+const reviveTimer = timer => {
+  if (!timer._cancelled) return timer;
+  if (timer._hasChildren) {
+    forEachChildren(timer, reviveTimer);
+  } else {
+    forEachChildren(timer, (/** @type {Tween} tween*/tween) => {
+      if (tween._composition !== compositionTypes.none) {
+        composeTween(tween, getTweenSiblings(tween.target, tween.property));
+      }
+    });
+  }
+  timer._cancelled = 0;
+  return timer;
+};
+
+let timerId = 0;
+
+/**
+ * Base class used to create Timers, Animations and Timelines
+ */
+class Timer extends Clock {
+  /**
+   * @param {TimerParams} [parameters]
+   * @param {Timeline} [parent]
+   * @param {Number} [parentPosition]
+   */
+  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 (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);
+    const timerDuration = isFnc(duration) || isUnd(duration) ? Infinity : +duration;
+    const timerLoop = setValue(loop, timerDefaults.loop);
+    const timerLoopDelay = setValue(loopDelay, timerDefaults.loopDelay);
+    const timerIterationCount = timerLoop === true ||
+                                timerLoop === Infinity ||
+                                /** @type {Number} */(timerLoop) < 0 ? Infinity :
+                                /** @type {Number} */(timerLoop) + 1;
+
+
+    let offsetPosition = 0;
+
+    if (parent) {
+      offsetPosition = parentPosition;
+    } else {
+      // Make sure to tick the engine once if not currently running to get up to date engine._elapsedTime
+      // to avoid big gaps with the following offsetPosition calculation
+      if (!engine.reqId) engine.requestTick(now());
+      // Make sure to scale the offset position with globals.timeScale to properly handle seconds unit
+      offsetPosition = (engine._elapsedTime - engine._startTime) * globals.timeScale;
+    }
+
+    // Timer's parameters
+    this.id = !isUnd(id) ? id : ++timerId;
+    /** @type {Timeline} */
+    this.parent = parent;
+    // Total duration of the timer
+    this.duration = clampInfinity(((timerDuration + timerLoopDelay) * timerIterationCount) - timerLoopDelay) || minValue;
+    /** @type {Boolean} */
+    this.backwards = false;
+    /** @type {Boolean} */
+    this.paused = true;
+    /** @type {Boolean} */
+    this.began = false;
+    /** @type {Boolean} */
+    this.completed = false;
+    /** @type {Callback<this>} */
+    this.onBegin = onBegin || timerDefaults.onBegin;
+    /** @type {Callback<this>} */
+    this.onBeforeUpdate = onBeforeUpdate || timerDefaults.onBeforeUpdate;
+    /** @type {Callback<this>} */
+    this.onUpdate = onUpdate || timerDefaults.onUpdate;
+    /** @type {Callback<this>} */
+    this.onLoop = onLoop || timerDefaults.onLoop;
+    /** @type {Callback<this>} */
+    this.onPause = onPause || timerDefaults.onPause;
+    /** @type {Callback<this>} */
+    this.onComplete = onComplete || timerDefaults.onComplete;
+    /** @type {Number} */
+    this.iterationDuration = timerDuration; // Duration of one loop
+    /** @type {Number} */
+    this.iterationCount = timerIterationCount; // Number of loops
+    /** @type {Boolean|ScrollObserver} */
+    this._autoplay = parent ? false : setValue(autoplay, timerDefaults.autoplay);
+    /** @type {Number} */
+    this._offset = offsetPosition;
+    /** @type {Number} */
+    this._delay = timerDelay;
+    /** @type {Number} */
+    this._loopDelay = timerLoopDelay;
+    /** @type {Number} */
+    this._iterationTime = 0;
+    /** @type {Number} */
+    this._currentIteration = 0; // Current loop index
+    /** @type {Function} */
+    this._resolve = noop; // Used by .then()
+    /** @type {Boolean} */
+    this._running = false;
+    /** @type {Number} */
+    this._reversed = +setValue(reversed, timerDefaults.reversed);
+    /** @type {Number} */
+    this._reverse = this._reversed;
+    /** @type {Number} */
+    this._cancelled = 0;
+    /** @type {Boolean} */
+    this._alternate = setValue(alternate, timerDefaults.alternate);
+    /** @type {Renderable} */
+    this._prev = null;
+    /** @type {Renderable} */
+    this._next = null;
+
+    // Clock's parameters
+    /** @type {Number} */
+    this._elapsedTime = timerInitTime;
+    /** @type {Number} */
+    this._startTime = timerInitTime;
+    /** @type {Number} */
+    this._lastTime = timerInitTime;
+    /** @type {Number} */
+    this._fps = setValue(frameRate, timerDefaults.frameRate);
+    /** @type {Number} */
+    this._speed = setValue(playbackRate, timerDefaults.playbackRate);
+  }
+
+  get cancelled() {
+    return !!this._cancelled;
+  }
+
+  set cancelled(cancelled) {
+    cancelled ? this.cancel() : this.reset(1).play();
+  }
+
+  get currentTime() {
+    return clamp(round(this._currentTime, globals.precision), -this._delay, this.duration);
+  }
+
+  set currentTime(time) {
+    const paused = this.paused;
+    // Pausing the timer is necessary to avoid time jumps on a running instance
+    this.pause().seek(+time);
+    if (!paused) this.resume();
+  }
+
+  get iterationCurrentTime() {
+    return round(this._iterationTime, globals.precision);
+  }
+
+  set iterationCurrentTime(time) {
+    this.currentTime = (this.iterationDuration * this._currentIteration) + time;
+  }
+
+  get progress() {
+    return clamp(round(this._currentTime / this.duration, 10), 0, 1);
+  }
+
+  set progress(progress) {
+    this.currentTime = this.duration * progress;
+  }
+
+  get iterationProgress() {
+    return clamp(round(this._iterationTime / this.iterationDuration, 10), 0, 1);
+  }
+
+  set iterationProgress(progress) {
+    const iterationDuration = this.iterationDuration;
+    this.currentTime = (iterationDuration * this._currentIteration) + (iterationDuration * progress);
+  }
+
+  get currentIteration() {
+    return this._currentIteration;
+  }
+
+  set currentIteration(iterationCount) {
+    this.currentTime = (this.iterationDuration * clamp(+iterationCount, 0, this.iterationCount - 1));
+  }
+
+  get reversed() {
+    return !!this._reversed;
+  }
+
+  set reversed(reverse) {
+    reverse ? this.reverse() : this.play();
+  }
+
+  get speed() {
+    return super.speed;
+  }
+
+  set speed(playbackRate) {
+    super.speed = playbackRate;
+    this.resetTime();
+  }
+
+  /**
+   * @param  {Number} internalRender
+   * @return {this}
+   */
+  reset(internalRender = 0) {
+    // If cancelled, revive the timer before rendering in order to have propertly composed tweens siblings
+    reviveTimer(this);
+    if (this._reversed && !this._reverse) this.reversed = false;
+    // Rendering before updating the completed flag to prevent skips and to make sure the properties are not overridden
+    // Setting the iterationTime at the end to force the rendering to happend backwards, otherwise calling .reset() on Timelines might not render children in the right order
+    // NOTE: This is only required for Timelines and might be better to move to the Timeline class?
+    this._iterationTime = this.iterationDuration;
+    // Set tickMode to tickModes.FORCE to force rendering
+    tick(this, 0, 1, internalRender, tickModes.FORCE);
+    // Reset timer properties after revive / render to make sure the props are not updated again
+    resetTimerProperties(this);
+    // Also reset children properties
+    if (this._hasChildren) {
+      forEachChildren(this, resetTimerProperties);
+    }
+    return this;
+  }
+
+  /**
+   * @param  {Number} internalRender
+   * @return {this}
+   */
+  init(internalRender = 0) {
+    this.fps = this._fps;
+    this.speed = this._speed;
+    // Manually calling .init() on timelines should render all children intial state
+    // Forces all children to render once then render to 0 when reseted
+    if (!internalRender && this._hasChildren) {
+      tick(this, this.duration, 1, internalRender, tickModes.FORCE);
+    }
+    this.reset(internalRender);
+    // Make sure to set autoplay to false to child timers so it doesn't attempt to autoplay / link
+    const autoplay = this._autoplay;
+    if (autoplay === true) {
+      this.resume();
+    } else if (autoplay && !isUnd(/** @type {ScrollObserver} */(autoplay).linked)) {
+      /** @type {ScrollObserver} */(autoplay).link(this);
+    }
+    return this;
+  }
+
+  /** @return {this} */
+  resetTime() {
+    const timeScale = 1 / (this._speed * engine._speed);
+    // TODO: See if we can safely use engine._elapsedTime here
+    // if (!engine.reqId) engine.requestTick(now())
+    // this._startTime = engine._elapsedTime - (this._currentTime + this._delay) * timeScale;
+    this._startTime = now() - (this._currentTime + this._delay) * timeScale;
+    return this;
+  }
+
+  /** @return {this} */
+  pause() {
+    if (this.paused) return this;
+    this.paused = true;
+    this.onPause(this);
+    return this;
+  }
+
+  /** @return {this} */
+  resume() {
+    if (!this.paused) return this;
+    this.paused = false;
+    // We can safely imediatly render a timer that has no duration and no children
+    if (this.duration <= minValue && !this._hasChildren) {
+      tick(this, minValue, 0, 0, tickModes.FORCE);
+    } else {
+      if (!this._running) {
+        addChild(engine, this);
+        engine._hasChildren = true;
+        this._running = true;
+      }
+      this.resetTime();
+      // Forces the timer to advance by at least one frame when the next tick occurs
+      this._startTime -= 12;
+      engine.wake();
+    }
+    return this;
+  }
+
+  /** @return {this} */
+  restart() {
+    return this.reset(0).resume();
+  }
+
+  /**
+   * @param  {Number} time
+   * @param  {Boolean|Number} [muteCallbacks]
+   * @param  {Boolean|Number} [internalRender]
+   * @return {this}
+   */
+  seek(time, muteCallbacks = 0, internalRender = 0) {
+    // Recompose the tween siblings in case the timer has been cancelled
+    reviveTimer(this);
+    // If you seek a completed animation, otherwise the next play will starts at 0
+    this.completed = false;
+    const isPaused = this.paused;
+    this.paused = true;
+    // timer, time, muteCallbacks, internalRender, tickMode
+    tick(this, time + this._delay, ~~muteCallbacks, ~~internalRender, tickModes.AUTO);
+    return isPaused ? this : this.resume();
+  }
+
+  /** @return {this} */
+  alternate() {
+    const reversed = this._reversed;
+    const count = this.iterationCount;
+    const duration = this.iterationDuration;
+    // Calculate the maximum iterations possible given the iteration duration
+    const iterations = count === Infinity ? floor(maxValue / duration) : count;
+    this._reversed = +(this._alternate && !(iterations % 2) ? reversed : !reversed);
+    if (count === Infinity) {
+      // Handle infinite loops to loop on themself
+      this.iterationProgress = this._reversed ? 1 - this.iterationProgress : this.iterationProgress;
+    } else {
+      this.seek((duration * iterations) - this._currentTime);
+    }
+    this.resetTime();
+    return this;
+  }
+
+  /** @return {this} */
+  play() {
+    if (this._reversed) this.alternate();
+    return this.resume();
+  }
+
+  /** @return {this} */
+  reverse() {
+    if (!this._reversed) this.alternate();
+    return this.resume();
+  }
+
+  // TODO: Move all the animation / tweens / children related code to Animation / Timeline
+
+  /** @return {this} */
+  cancel() {
+    if (this._hasChildren) {
+      forEachChildren(this, (/** @type {Renderable} */child) => child.cancel(), true);
+    } else {
+      forEachChildren(this, removeTweenSliblings);
+    }
+    this._cancelled = 1;
+    // Pausing the timer removes it from the engine
+    return this.pause();
+  }
+
+  /**
+   * @param  {Number} newDuration
+   * @return {this}
+   */
+  stretch(newDuration) {
+    const currentDuration = this.duration;
+    const normlizedDuration = normalizeTime(newDuration);
+    if (currentDuration === normlizedDuration) return this;
+    const timeScale = newDuration / currentDuration;
+    const isSetter = newDuration <= minValue;
+    this.duration = isSetter ? minValue : normlizedDuration;
+    this.iterationDuration = isSetter ? minValue : normalizeTime(this.iterationDuration * timeScale);
+    this._offset *= timeScale;
+    this._delay *= timeScale;
+    this._loopDelay *= timeScale;
+    return this;
+  }
+
+ /**
+   * Cancels the timer by seeking it back to 0 and reverting the attached scroller if necessary
+   * @return {this}
+   */
+  revert() {
+    tick(this, 0, 1, 0, tickModes.AUTO);
+    const ap = /** @type {ScrollObserver} */(this._autoplay);
+    if (ap && ap.linked && ap.linked === this) ap.revert();
+    return this.cancel();
+  }
+
+ /**
+   * Imediatly completes the timer, cancels it and triggers the onComplete callback
+   * @return {this}
+   */
+  complete() {
+    return this.seek(this.duration).cancel();
+  }
+
+  /**
+   * @param  {Callback<this>} [callback]
+   * @return {Promise}
+   */
+  then(callback = noop) {
+    const then = this.then;
+    const onResolve = () => {
+      // this.then = null prevents infinite recursion if returned by an async function
+      // https://github.com/juliangarnierorg/anime-beta/issues/26
+      this.then = null;
+      callback(this);
+      this.then = then;
+      this._resolve = noop;
+    };
+    return new Promise(r => {
+      this._resolve = () => r(onResolve());
+      // Make sure to resolve imediatly if the timer has already completed
+      if (this.completed) this._resolve();
+      return this;
+    });
+  }
+
+}
+
+/**
+ * @param {TimerParams} [parameters]
+ * @return {Timer}
+ */
+const createTimer = parameters => new Timer(parameters, null, 0).init();
+
+export { Timer, createTimer };