@xtia/timeline 1.0.8 → 1.0.9

package/README.md

@@ -5,6 +5,7 @@
 **Timeline** is a general‑purpose, environment-agnostic choreography engine that lets you orchestrate any sequence of value changes; numbers, vectors, colour tokens, custom blendable objects, or arbitrary data structures.
 
 * [API Reference](#reference)
+* [Playground](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
 
 ## Basic Use:
 
@@ -21,7 +22,7 @@ timeline
     .range(0, 1000)
     .tween("#646", "#000")
     .listen(
-        value => document.body.style.backgroundColor = value
+        value => element.style.background = value
     );
 
 // add another tween to make a slow typing effect
@@ -29,15 +30,14 @@ const message = "Hi, planet!";
 timeline
     .range(500, 2000)
     .tween(0, message.length)
+    .map(n => message.substring(0, n))
     .listen(
-        n => element.textContent = message.substring(0, n)
+        s => element.textContent = s
     );
 
 // use an easing function
 timeline
-    .end
-    .delta(500)
-    .range(3000)
+    .range(0, 3000)
     .ease("bounce")
     .tween("50%", "0%")
     .listen(
@@ -100,8 +100,8 @@ range
     .map(n => `animation-frame-${n}.png`)
     .listen(filename => img.src = filename);
 
-// each step in the chain is a 'pure', independent emitter that emits
-// a transformation of its parent's emissions
+// each step in a chain is a 'pure', independent emitter that emits a
+// transformation of its parent's emissions
 const filenameEmitter = range
     .tween(0, 3)
     .map(Math.floor)
@@ -198,7 +198,7 @@ range
 import { RGBA } from "@xtia/rgba";
 range
     .tween(RGBA.parse("#c971a7"), RGBA.parse("#fff"))
-    .listen(v => element.style.background = v.hexCode);
+    .listen(v => element.style.background = v);
 
 import { Angle } from "@xtia/mezr";
 range
@@ -414,15 +414,15 @@ Performs an interruptable 'smooth seek' to a specified position, lasting `durati
 
 Returns a Promise that will be resolved when the smooth seek is completed (or is interrupted by another seek\*).
 
-\* Resolution on interruption is not finalised in the library's design and the effect should be considered exceptional; relying on it is not recommended. Future versions might reject the promise when its seek is interrupted.
+\* If a smooth seek is interrupted by another seek, the interrupted seek will immediately complete before the new seek is applied, to ensure any resulting state reflects expectations set by the first seek.
 
 ##### `play(): void`
 
-Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating 60 times per second.
+Begins playing through the Timeline, from its current position, at (1000 × `timeScale`) units per second, updating 60 times per second.
 
 ##### `play(fps): void`
 
-Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating `fps` times per second.
+Begins playing through the Timeline, from its current position, at (1000 × `timeScale`) units per second, updating `fps` times per second.
 
 ##### `tween<T>(start, duration, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
 

package/internal/emitters.d.ts

@@ -8,6 +8,7 @@ export declare class Emitter<T> {
     protected constructor(onListen: ListenFunc<T>);
     /**
      * Used by tap() to create a clone of an Emitter with a redirected onListen
+     *
      * Should be overridden in all Emitter subclasses
      * @see {@link TimelineRange.redirect}
      * @param listen

package/internal/emitters.js

@@ -6,6 +6,7 @@ export class Emitter {
         this.onListen = onListen;
         /**
          * Used by tap() to create a clone of an Emitter with a redirected onListen
+         *
          * Should be overridden in all Emitter subclasses
          * @see {@link TimelineRange.redirect}
          * @param listen

package/internal/point.d.ts

@@ -2,7 +2,7 @@ import { Emitter, ListenFunc } from "./emitters";
 import { TimelineRange } from "./range";
 import { Timeline } from "./timeline";
 export type PointEvent = {
-    direction: -1 | 1;
+    readonly direction: -1 | 1;
 };
 export declare class TimelinePoint extends Emitter<PointEvent> {
     private timeline;

package/internal/range.d.ts

@@ -8,6 +8,10 @@ export declare class TimelineRange extends RangeProgression {
     /** The duration of this range */
     readonly duration: number;
     private endPosition;
+    /** The point on the Timeline at which this range begins */
+    readonly start: TimelinePoint;
+    /** The point on the Timeline at which this range ends */
+    readonly end: TimelinePoint;
     /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
     constructor(onListen: ListenFunc<number>, timeline: Timeline, startPosition: number, 
     /** The duration of this range */
@@ -52,9 +56,15 @@ export declare class TimelineRange extends RangeProgression {
      * @returns true if the provided point is within the range
      */
     contains(point: TimelinePoint): boolean;
+    /**
+     * Checks if a range is fully within this range
+     * @param range The range to check
+     * @returns true if the provided range is within the parent
+     */
     contains(range: TimelineRange): boolean;
-    /** The point on the Timeline at which this range begins */
-    readonly start: TimelinePoint;
-    /** The point on the Timeline at which this range ends */
-    readonly end: TimelinePoint;
+    overlaps(range: TimelineRange): boolean;
+    overlaps(range: {
+        position: number;
+        duration: number;
+    }): boolean;
 }

package/internal/range.js

@@ -11,9 +11,9 @@ export class TimelineRange extends RangeProgression {
         this.startPosition = startPosition;
         this.duration = duration;
         this.redirect = (listen) => new TimelineRange(listen, this.timeline, this.startPosition, this.duration);
-        this.start = timeline.point(startPosition);
         this.endPosition = startPosition + duration;
         this.end = timeline.point(this.endPosition);
+        this.start = timeline.point(startPosition);
     }
     /**
      * Creates two ranges by seperating one at a given point
@@ -93,4 +93,11 @@ export class TimelineRange extends RangeProgression {
             : [target.startPosition, target.startPosition + target.duration];
         return targetStart >= this.startPosition && targetEnd < this.endPosition;
     }
+    overlaps(range) {
+        const [start, end] = range instanceof TimelineRange
+            ? [range.startPosition, range.endPosition]
+            : [range.position, range.position + range.duration];
+        return Math.min(this.startPosition, this.endPosition) <= Math.max(start, end) &&
+            Math.max(this.startPosition, this.endPosition) >= Math.min(start, end);
+    }
 }

package/internal/timeline.d.ts

@@ -1,4 +1,5 @@
 import { Easer, easers } from "./easing";
+import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { Tweenable } from "./tween";
@@ -11,7 +12,7 @@ declare const EndAction: {
 };
 /**
  * Creates an autoplaying Timeline and returns a range from it
- * @param duration
+ * @param duration Animation duration, in milliseconds
  * @returns Object representing a range on a single-use, autoplaying Timeline
  */
 export declare function animate(duration: number): TimelineRange;
@@ -36,14 +37,22 @@ export declare class Timeline {
     private smoothSeeker;
     private seeking;
     readonly start: TimelinePoint;
-    private positionHandlers;
+    private progressionHandlers;
+    private _progression;
+    /**
+     * Listenable: emits a progression value (0..1) when the Timeline's internal
+     * position changes, and when the Timeline's total duration is extended
+     *
+     * **Experimental**
+     */
+    get progression(): RangeProgression;
     constructor();
     /**
-     * @param autoplay Pass `true` to begin playing at (1000 x this.timeScale) units per second immediately on creation
+     * @param autoplay Pass `true` to begin playing at (1000 × this.timeScale) units per second immediately on creation
      */
     constructor(autoplay: boolean);
     /**
-     * Creates a Timeline that begins playing immediately at (1000 x this.timeScale) units per second
+     * Creates a Timeline that begins playing immediately at (1000 × this.timeScale) units per second
      * @param autoplayFps Specifies frames per second
      */
     constructor(autoplayFps: number);
@@ -51,12 +60,12 @@ export declare class Timeline {
      * @param autoplay If this argument is `true`, the Timeline will begin playing immediately on creation. If the argument is a number, the Timeline will begin playing at the specified frames per second
      * @param endAction Specifies what should happen when the final position is passed by `play()`/`autoplay`
      *
-     * `"pause"`: **(default)** the Timeline will pause at its final position
-     * `"continue"`: The Timeline will continue progressing beyond its final position
-     * `"restart"`: The Timeline will seek back to 0 then forward to account for any overshoot and continue progressing
-     * `"wrap"`: The Timeline's position will continue to increase beyond the final position, but Points and Ranges will be activated as if looping
-     * `{restartAt: number}`: Like `"restart"` but seeking back to `restartAt` instead of 0
-     * `{wrapAt: number}`: Like `"wrap"` but as if restarting at `wrapAt` instead of 0
+     * * `"pause"`: **(default)** the Timeline will pause at its final position
+     * * `"continue"`: The Timeline will continue progressing beyond its final position
+     * * `"restart"`: The Timeline will seek back to 0 then forward to account for any overshoot and continue progressing
+     * * `"wrap"`: The Timeline's position will continue to increase beyond the final position, but Points and Ranges will be activated as if looping
+     * * `{restartAt: number}`: Like `"restart"` but seeking back to `restartAt` instead of 0
+     * * `{wrapAt: number}`: Like `"wrap"` but as if restarting at `wrapAt` instead of 0
      */
     constructor(autoplay: boolean | number, endAction: {
         wrapAt: number;
@@ -99,7 +108,7 @@ export declare class Timeline {
     /**
      * Smooth-seeks to a specified position
      *
-     * Aborts and replaces any on-going smooth-seek process on this Timeline
+     * Immediately completes and replaces any ongoing smooth-seek process on this Timeline
      * @param toPosition
      * @param duration Duration of the smooth-seek process in milliseconds
      * @param easer Optional easing function for the smooth-seek process
@@ -111,7 +120,7 @@ export declare class Timeline {
     private seekRanges;
     private sortEntries;
     /**
-     * Starts progression of the Timeline from its current position at (1000 x this.timeScale) units per second
+     * Starts progression of the Timeline from its current position at (1000 × this.timeScale) units per second
      */
     play(): void;
     play(fps: number): void;

package/internal/timeline.js

@@ -1,3 +1,4 @@
+import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { clamp } from "./utils";
@@ -10,7 +11,7 @@ const EndAction = {
 };
 /**
  * Creates an autoplaying Timeline and returns a range from it
- * @param duration
+ * @param duration Animation duration, in milliseconds
  * @returns Object representing a range on a single-use, autoplaying Timeline
  */
 export function animate(duration) {
@@ -27,6 +28,17 @@ export class Timeline {
     get end() {
         return this.point(this._endPosition);
     }
+    /**
+     * Listenable: emits a progression value (0..1) when the Timeline's internal
+     * position changes, and when the Timeline's total duration is extended
+     *
+     * **Experimental**
+     */
+    get progression() {
+        if (this._progression === null)
+            this._progression = new TimelineProgressionEmitter(this.progressionHandlers);
+        return this._progression;
+    }
     constructor(autoplay = false, endAction = "pause") {
         /**
          * Multiplies the speed at which `play()` progresses through the Timeline
@@ -43,7 +55,8 @@ export class Timeline {
         this.smoothSeeker = null;
         this.seeking = false;
         this.start = this.point(0);
-        this.positionHandlers = [];
+        this.progressionHandlers = [];
+        this._progression = null;
         if (endAction == "loop")
             endAction = "restart";
         if (autoplay !== false) {
@@ -78,8 +91,10 @@ export class Timeline {
      * Listenable: this point will emit a PointEvent whenever a `seek()` reaches or passes it
      */
     point(position) {
-        if (position > this._endPosition)
+        if (position > this._endPosition) {
             this._endPosition = position;
+            this.progressionHandlers.slice().forEach(h => h(this._currentTime / position));
+        }
         const handlers = [];
         const data = {
             handlers,
@@ -113,9 +128,9 @@ export class Timeline {
             : start;
         const startPosition = startPoint.position;
         const duration = optionalDuration ?? this._endPosition - startPosition;
-        const endPosition = startPosition + duration;
-        if (endPosition > this._endPosition)
-            this._endPosition = endPosition;
+        // const endPosition = startPosition + duration;
+        //if (endPosition > this._endPosition) this._endPosition = endPosition;
+        // ^ leave this to range's point() calls
         const handlers = [];
         const range = {
             position: startPosition,
@@ -168,7 +183,7 @@ export class Timeline {
         }
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
-            // ensure any awaits are resolved for the previous seek?
+            // ensure any awaits are resolved for the previous seek
             this.smoothSeeker.seek(this.smoothSeeker.end);
             this.smoothSeeker = null;
         }
@@ -209,7 +224,6 @@ export class Timeline {
             throw e;
         }
         this._currentTime = toPosition;
-        this.positionHandlers.slice().forEach(h => h(toPosition));
         this.seeking = false;
     }
     seekPoints(to) {
@@ -218,27 +232,25 @@ export class Timeline {
         const pointsBetween = this.points.filter(direction > 0
             ? p => p.position > from && p.position <= to
             : p => p.position <= from && p.position > to);
+        const eventData = {
+            direction
+        };
         pointsBetween.slice().forEach(p => {
             this.seekRanges(p.position);
             this._currentTime = p.position;
-            const eventData = {
-                direction
-            };
             p.handlers.slice().forEach(h => h(eventData));
         });
     }
     seekRanges(to) {
-        const fromTime = this._currentTime;
+        const seekRange = this.point(Math.min(this._currentTime, to))
+            .to(Math.max(this._currentTime, to));
         this.ranges.slice().forEach((range) => {
-            const { duration, position } = range;
-            const end = position + duration;
-            // filter ranges that overlap seeked range
-            if (Math.min(position, end) <= Math.max(to, fromTime)
-                && Math.min(to, fromTime) <= Math.max(position, end)) {
+            if (seekRange.overlaps(range)) {
                 let progress = clamp((to - range.position) / range.duration, 0, 1);
                 range.handlers.slice().forEach(h => h(progress));
             }
         });
+        this.progressionHandlers.slice().forEach(h => h(this._currentTime / this._endPosition));
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -340,6 +352,18 @@ export class Timeline {
         return this._currentTime;
     }
 }
+class TimelineProgressionEmitter extends RangeProgression {
+    constructor(handlers) {
+        super((handler) => {
+            const unique = (n) => handler(n);
+            handlers.push(unique);
+            return () => {
+                const idx = handlers.indexOf(unique);
+                handlers.splice(idx, 1);
+            };
+        });
+    }
+}
 const sortEvents = (a, b) => {
     return a.position - b.position;
 };

package/package.json

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