@xtia/timeline 1.1.7 → 1.1.9

package/README.md

@@ -515,6 +515,14 @@ Listeners will be invoked with a [`PointEvent`](#pointevent-interface) when a se
 
 This point's position on the Timeline.
 
+##### `forwardOnly: Emitter<PointEvent>`
+
+Provides an emitter that forwards emissions triggered by forward-moving seeks.
+
+##### `reverseOnly: Emitter<PointEvent>`
+
+Provides an emitter that forwards emissions triggered by backward-moving seeks.
+
 #### Methods
 
 ##### `range(duration): TimelineRange`
@@ -543,14 +551,6 @@ Creates a `Promise` that will be resolved when the Timeline first seeks to/past
 
 The resolved value indicates the direction of the seek that triggered resolution.
 
-##### `forwardOnly(): Emitter<PointEvent>`
-
-Creates an emitter that forwards emissions triggered by forward-moving seeks.
-
-##### `reverseOnly(): Emitter<PointEvent>`
-
-Creates an emitter that forwards emissions triggered by backward-moving seeks.
-
 ##### `applyDirectional(apply, revert): UnsubscribeFunc`
 
 Registers an emission handler that calls one function for forward seeks to or past the point, and another for backward seeks from or past the point.

package/internal/point.d.ts

@@ -46,16 +46,16 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      */
     seek(duration: number, easer?: Easer): Promise<void>;
     /**
-     * Creates an emitter that only emits on forward-moving seeks
+     * An point emitter that only emits on forward-moving seeks
      * @returns Listenable: emits forward-seeking point events
      */
-    forwardOnly(): Emitter<PointEvent>;
+    get forwardOnly(): Emitter<PointEvent>;
     private _forwardOnly?;
     /**
-     * Creates an emitter that only emits on backward-moving seeks
+     * An point emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
-    reverseOnly(): Emitter<PointEvent>;
+    get reverseOnly(): Emitter<PointEvent>;
     private _reverseOnly?;
     filter(check: (event: PointEvent) => boolean): Emitter<PointEvent>;
     /**

package/internal/point.js

@@ -41,19 +41,19 @@ export class TimelinePoint extends Emitter {
         return this.timeline.seek(this.position, duration, easer);
     }
     /**
-     * Creates an emitter that only emits on forward-moving seeks
+     * An point emitter that only emits on forward-moving seeks
      * @returns Listenable: emits forward-seeking point events
      */
-    forwardOnly() {
+    get forwardOnly() {
         if (!this._forwardOnly)
             this._forwardOnly = this.filter(1);
         return this._forwardOnly;
     }
     /**
-     * Creates an emitter that only emits on backward-moving seeks
+     * An point emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
-    reverseOnly() {
+    get reverseOnly() {
         if (!this._reverseOnly)
             this._reverseOnly = this.filter(-1);
         return this._reverseOnly;

package/internal/timeline.d.ts

@@ -42,7 +42,7 @@ export declare class Timeline {
     get end(): TimelinePoint;
     private _currentTime;
     private _endPosition;
-    private interval;
+    private _pause;
     private points;
     private endAction;
     private ranges;
@@ -118,7 +118,8 @@ export declare class Timeline {
      */
     range(): TimelineRange;
     /**
-     * Seeks the Timeline to a specified position, triggering in order any point and range subscriptions between its current and new positions
+     * Seeks the Timeline to a specified position, triggering in order any point and range
+     * subscriptions between its current and new positions
      * @param toPosition
      */
     seek(toPosition: number | TimelinePoint): void;
@@ -133,6 +134,14 @@ export declare class Timeline {
      */
     seek(toPosition: number | TimelinePoint, durationMs: number, easer?: Easer | keyof typeof easers): Promise<void>;
     seek(toPosition: number | TimelinePoint, duration: Period, easer?: Easer | keyof typeof easers): Promise<void>;
+    /**
+     * Smooth-seeks through a range over a given duration
+     * @param range The range to seek through
+     * @param durationMs Smooth-seek duration
+     * @param easer Optional easing function
+     */
+    seek(range: TimelineRange, durationMs: number, easer?: Easer | keyof typeof easers): Promise<void>;
+    seek(range: TimelineRange, duration: Period, easer?: Easer | keyof typeof easers): Promise<void>;
     private seekDirect;
     private seekWrapped;
     private seekPoints;
@@ -147,6 +156,9 @@ export declare class Timeline {
      * Performs a smooth-seek through a range at (1000 × this.timeScale) units per second
      */
     play(range: TimelineRange, easer?: Easer): Promise<void>;
+    private playWithInterval;
+    private playWithRAF;
+    private next;
     /**
      * Stops normal progression instigated by play()
      *

package/internal/timeline.js

@@ -3,6 +3,8 @@ import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { clamp } from "./utils";
 const default_fps = 60;
+const requestAnimFrame = globalThis?.requestAnimationFrame;
+const cancelAnimFrame = globalThis?.cancelAnimationFrame;
 const EndAction = {
     pause: 0,
     continue: 1,
@@ -27,7 +29,7 @@ export class Timeline {
      * Returns true if this Timeline is currently progressing via `play()`, otherwise false
      */
     get isPlaying() {
-        return this.interval !== null;
+        return !!this._pause;
     }
     /**
      * Returns a fixed point at the current end of the Timeline
@@ -71,7 +73,7 @@ export class Timeline {
         this.timeScale = 1;
         this._currentTime = 0;
         this._endPosition = 0;
-        this.interval = null;
+        this._pause = null;
         this.points = [];
         this.ranges = [];
         this.currentSortDirection = 0;
@@ -174,6 +176,10 @@ export class Timeline {
         return range;
     }
     seek(to, duration, easer) {
+        if (to instanceof TimelineRange) {
+            this.seek(to.start);
+            return this.seek(to, duration, easer);
+        }
         const durationMs = typeof duration == "object"
             ? duration.asMilliseconds
             : duration;
@@ -193,7 +199,6 @@ export class Timeline {
             this.seekDirect(interruptPosition);
         }
         if (!durationMs) {
-            const fromTime = this._currentTime;
             this.seekDirect(toPosition);
             this._frameEvents?.emit();
             // only add Promise overhead if duration is explicitly 0
@@ -311,9 +316,8 @@ export class Timeline {
             ? sortTweens
             : sortReverse);
     }
-    play(arg = default_fps, easer) {
-        if (this.interval !== null)
-            this.pause();
+    play(arg, easer) {
+        this._pause?.();
         if (this.smoothSeeker) {
             this.smoothSeeker.pause();
             this.smoothSeeker.seek(this.smoothSeeker.end);
@@ -323,44 +327,73 @@ export class Timeline {
             this.seek(arg.start);
             return this.seek(arg.end, arg.duration / this.timeScale, easer);
         }
+        if (arg !== undefined && requestAnimFrame) {
+            this.playWithRAF();
+            return;
+        }
+        this.playWithInterval(arg ?? default_fps);
+    }
+    playWithInterval(fps) {
         let previousTime = Date.now();
-        this.interval = setInterval(() => {
+        const interval = setInterval(() => {
             const newTime = Date.now();
             const elapsed = newTime - previousTime;
             previousTime = newTime;
             let delta = elapsed * this.timeScale;
-            if (this._currentTime + delta <= this._endPosition) {
-                this.currentTime += delta;
+            this.next(delta);
+        }, 1000 / fps);
+        this._pause = () => clearInterval(interval);
+    }
+    playWithRAF() {
+        let previousTime = null;
+        let rafId;
+        const frame = (currentTime) => {
+            if (previousTime === null) {
+                previousTime = currentTime;
+            }
+            const elapsed = currentTime - previousTime;
+            previousTime = currentTime;
+            let delta = elapsed * this.timeScale;
+            this.next(delta);
+            if (this._pause)
+                rafId = requestAnimFrame(frame);
+        };
+        rafId = requestAnimFrame(frame);
+        this._pause = () => cancelAnimFrame(rafId);
+    }
+    next(delta) {
+        if (this._currentTime + delta <= this._endPosition) {
+            this.currentTime += delta;
+            return;
+        }
+        // overshot; perform restart/pause endAction			
+        if (this.endAction.type == EndAction.restart) {
+            const loopRange = this.endAction.at.to(this._endPosition);
+            const loopLen = loopRange.duration;
+            if (loopLen <= 0) {
+                const target = Math.min(this._currentTime + delta, this._endPosition);
+                this.seek(target);
                 return;
             }
-            // overshot; perform restart/pause endAction			
-            if (this.endAction.type == EndAction.restart) {
-                const loopRange = this.endAction.at.to(this._endPosition);
-                const loopLen = loopRange.duration;
-                if (loopLen <= 0) {
-                    const target = Math.min(this._currentTime + delta, this._endPosition);
-                    this.seek(target);
+            while (delta > 0) {
+                const distanceToEnd = this._endPosition - this._currentTime;
+                if (delta < distanceToEnd) {
+                    this.seek(this._currentTime + delta);
                     return;
                 }
-                while (delta > 0) {
-                    const distanceToEnd = this._endPosition - this._currentTime;
-                    if (delta < distanceToEnd) {
-                        this.seek(this._currentTime + delta);
-                        return;
-                    }
-                    this.seek(this._endPosition);
-                    delta -= distanceToEnd;
-                    this.seek(this.endAction.at);
-                }
-                return;
-            }
-            if (this.endAction.type == EndAction.pause) {
                 this.seek(this._endPosition);
-                this.pause();
-                return;
+                delta -= distanceToEnd;
+                this.seek(this.endAction.at);
             }
-            this.currentTime += delta;
-        }, 1000 / arg);
+            return;
+        }
+        if (this.endAction.type == EndAction.pause) {
+            this.seek(this._endPosition);
+            this.pause();
+            return;
+        }
+        // endaction must be "continue" or "wrap"
+        this.currentTime += delta;
     }
     /**
      * Stops normal progression instigated by play()
@@ -369,10 +402,10 @@ export class Timeline {
      *
      */
     pause() {
-        if (this.interval === null)
+        if (this._pause === null)
             return;
-        clearInterval(this.interval);
-        this.interval = null;
+        this._pause();
+        this._pause = null;
     }
     step(delta = 1) {
         this.currentTime += delta * this.timeScale;
@@ -398,12 +431,25 @@ export class Timeline {
      */
     at(position, action, reverse) {
         const point = typeof position == "number" ? this.point(position) : position;
-        if (reverse === true)
-            reverse = action;
-        if (action)
-            point.apply(reverse
-                ? (event => event.direction < 0 ? reverse() : action())
-                : action);
+        if (!action) {
+            if (reverse) {
+                if (reverse === true)
+                    throw new Error("Invalid call");
+                point.reverseOnly.apply(reverse);
+            }
+            return this.createChainingInterface(point.position);
+        }
+        if (reverse) {
+            if (reverse === true) {
+                point.apply(action);
+            }
+            else {
+                point.applyDirectional(action, reverse);
+            }
+        }
+        else {
+            point.forwardOnly.apply(action);
+        }
         return this.createChainingInterface(point.position);
     }
     createChainingInterface(position) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"