@xtia/timeline 1.0.7 → 1.0.8

package/README.md

@@ -85,27 +85,41 @@ asPercent
         n => progressBar.style.width = n
     );
 
-// apply easing (creates a *new* emitter)
+// apply easing
 const eased = firstFiveSeconds.ease("easeInOut");
 eased.listen(
     v => console.log(`Eased value: ${v}`)
 );
 
-// combine them
-const frames = eased
+// chain them
+range
     .tween(0, 30)
     .map(Math.floor)
     .dedupe()
     .tap(n => console.log("Showing frame #", n))
     .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
+const filenameEmitter = range
+    .tween(0, 3)
+    .map(Math.floor)
+    .dedupe()
+    .map(n => `animation-frame-${n}.png`);
+
+// filenameEmitter will emit filenames as the Timeline passes through 'range'.
+// it can be listened directly or further transformed
+const urlEmitter = filenameEmitter
+    .map(filename => `http://www.example.com/${filename}`);
+
 ```
 
 Range objects also provide a `play()` method that instructs the Timeline to play through that particular range:
 
 ```ts
 // play through the first two seconds of the Timeline
-timeline
+await timeline
     .range(0, 2000)
     .play();
 ```
@@ -158,7 +172,41 @@ timeline
 
 ## More on tweening
 
-Tween emitters can interpolate numbers, arrays of numbers, strings, and objects with a method `blend(from: this, to: this): this`.
+Tween emitters can interpolate numbers, arrays of numbers, strings, and objects with a method `blend(from: this, to: this): this`, by the progression value emitted by their parent.
+
+```ts
+const range = timeline.range(0, 2000);
+
+// numbers
+range
+    .ease("overshootIn")
+    .tween(300, 500)
+    .listen(v => element.scrollTop = v);
+
+// number arrays
+range
+    .tween([0, 180], [360, 180])
+    .listen((angles) => pieChart.setValues(angles));
+
+// strings
+range
+    .tween("#000000", "#ff00ff")
+    .listen(v => element.style.color = v);
+
+// blendable objects
+// (T extends { blend(from: this, to: this): this })
+import { RGBA } from "@xtia/rgba";
+range
+    .tween(RGBA.parse("#c971a7"), RGBA.parse("#fff"))
+    .listen(v => element.style.background = v.hexCode);
+
+import { Angle } from "@xtia/mezr";
+range
+    .tween(Angle.degrees(45), Angle.turns(.5))
+    .map(a => `rotate(${a.asDegrees}deg)`)
+    .listen(v => element.style.transform = v);
+
+```
 
 #### String interpolation
 * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
@@ -180,7 +228,7 @@ timeline
     .listen(v => document.title = v);
 ```
 
-You can try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
+Try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
 
 ## Autoplay and Looping Strategies
 
@@ -190,13 +238,13 @@ To create a Timeline that immediately starts playing, pass `true` to its constru
 // immediately fade in an element
 new Timeline(true)
     .range(0, 1000)
-    .tween(v => element.style.opacity = v);
+    .listen(v => element.style.opacity = v);
 
 // note, an `animate(duration)` function is exported for
 // disposable, single-use animations such as this:
 import { animate } from "@xtia/timeline";
 animate(1000)
-    .tween(v => element.style.opacity = v);
+    .listen(v => element.style.opacity = v);
 ```
 
 Normally a Timeline will simply stop playing when it reaches the end. This can be changed by passing a second argument (`endAction`) to the constructor.
@@ -279,7 +327,7 @@ resourceUrls.forEach(url => {
 We can pass a second argument to `seek()` to perform a 'smooth seek' over the given duration. A third argument can provide an easing function for the smooth seek process:
 
 ```ts
-timeline.seek(timeline.end, 400, "overshootIn");
+await timeline.seek(timeline.end, 400, "overshootIn");
 ```
 
 ## Backward-compatibility

package/index.js

@@ -1,15 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.easers = exports.RangeProgression = exports.Emitter = exports.TimelineRange = exports.TimelinePoint = exports.animate = exports.Timeline = void 0;
-var timeline_1 = require("./internal/timeline");
-Object.defineProperty(exports, "Timeline", { enumerable: true, get: function () { return timeline_1.Timeline; } });
-Object.defineProperty(exports, "animate", { enumerable: true, get: function () { return timeline_1.animate; } });
-var point_1 = require("./internal/point");
-Object.defineProperty(exports, "TimelinePoint", { enumerable: true, get: function () { return point_1.TimelinePoint; } });
-var range_1 = require("./internal/range");
-Object.defineProperty(exports, "TimelineRange", { enumerable: true, get: function () { return range_1.TimelineRange; } });
-var emitters_1 = require("./internal/emitters");
-Object.defineProperty(exports, "Emitter", { enumerable: true, get: function () { return emitters_1.Emitter; } });
-Object.defineProperty(exports, "RangeProgression", { enumerable: true, get: function () { return emitters_1.RangeProgression; } });
-var easing_1 = require("./internal/easing");
-Object.defineProperty(exports, "easers", { enumerable: true, get: function () { return easing_1.easers; } });
+export { Timeline, animate } from "./internal/timeline";
+export { TimelinePoint } from "./internal/point";
+export { TimelineRange } from "./internal/range";
+export { Emitter, RangeProgression } from "./internal/emitters";
+export { easers } from "./internal/easing";

package/internal/easing.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.easers = void 0;
 const overshoot = 1.70158;
-exports.easers = {
+export const easers = {
     linear: (x) => x,
     easeIn: (x) => x * x,
     easeIn4: (x) => Math.pow(x, 4),

package/internal/emitters.d.ts

@@ -1,5 +1,5 @@
 import { Easer, easers } from "./easing";
-import { Tweenable } from "./tween";
+import { BlendableWith, Tweenable } from "./tween";
 type Handler<T> = (value: T) => void;
 export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
@@ -123,6 +123,7 @@ export declare class RangeProgression extends Emitter<number> {
      * @returns Listenable: emits interpolated values
      */
     tween<T extends Tweenable>(from: T, to: T): Emitter<T>;
+    tween<T extends BlendableWith<T, R>, R>(from: T, to: R): Emitter<T>;
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
      *
@@ -182,7 +183,7 @@ export declare class RangeProgression extends Emitter<number> {
      *‎	1
      *‎	 |  /
      *‎	o| /
-     *‎	u|/      __ delta=.5
+     *‎	u|/       __ delta=.5
      *‎	t|     /
      *‎	 |    /
      *‎	 |___/__

package/internal/emitters.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RangeProgression = exports.Emitter = void 0;
-const easing_1 = require("./easing");
-const tween_1 = require("./tween");
-const utils_1 = require("./utils");
-class Emitter {
+import { easers } from "./easing";
+import { tweenValue } from "./tween";
+import { clamp } from "./utils";
+export class Emitter {
     constructor(onListen) {
         this.onListen = onListen;
         /**
@@ -124,8 +121,7 @@ class Emitter {
         return this;
     }
 }
-exports.Emitter = Emitter;
-class RangeProgression extends Emitter {
+export class RangeProgression extends Emitter {
     constructor() {
         super(...arguments);
         this.redirect = (listen) => new RangeProgression(listen);
@@ -134,14 +130,14 @@ class RangeProgression extends Emitter {
         if (!easer)
             return this;
         const easerFunc = typeof easer == "string"
-            ? easing_1.easers[easer]
+            ? easers[easer]
             : easer;
         return new RangeProgression(easer ? (handler => this.onListen((progress) => {
             handler(easerFunc(progress));
         })) : h => this.onListen(h));
     }
     tween(from, to) {
-        return new Emitter(handler => this.onListen(progress => handler((0, tween_1.tweenValue)(from, to, progress))));
+        return new Emitter(handler => this.onListen(progress => handler(tweenValue(from, to, progress))));
     }
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
@@ -156,7 +152,7 @@ class RangeProgression extends Emitter {
         }
         return new RangeProgression(handler => this.onListen(progress => {
             const snapped = Math.round(progress * steps) / steps;
-            handler((0, utils_1.clamp)(snapped, 0, 1));
+            handler(clamp(snapped, 0, 1));
         }));
     }
     /**
@@ -177,7 +173,7 @@ class RangeProgression extends Emitter {
      * @returns Listenable: emits clamped progression values
      */
     clamp(min = 0, max = 1) {
-        return new RangeProgression(handler => this.onListen(progress => handler((0, utils_1.clamp)(progress, min, max))));
+        return new RangeProgression(handler => this.onListen(progress => handler(clamp(progress, min, max))));
     }
     /**
      * Creates a chainable progress emitter that maps incoming values to a repeating linear scale
@@ -237,7 +233,7 @@ class RangeProgression extends Emitter {
      *‎	1
      *‎	 |  /
      *‎	o| /
-     *‎	u|/      __ delta=.5
+     *‎	u|/       __ delta=.5
      *‎	t|     /
      *‎	 |    /
      *‎	 |___/__
@@ -251,4 +247,3 @@ class RangeProgression extends Emitter {
         return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
     }
 }
-exports.RangeProgression = RangeProgression;

package/internal/point.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimelinePoint = void 0;
-const emitters_1 = require("./emitters");
-class TimelinePoint extends emitters_1.Emitter {
+import { Emitter } from "./emitters";
+export class TimelinePoint extends Emitter {
     /** @internal Manual construction of TimelinePoint is outside of the API contract and subject to undocumented change */
     constructor(onListen, timeline, 
     /**
@@ -42,4 +39,3 @@ class TimelinePoint extends emitters_1.Emitter {
         return this.timeline.point(this.position + timeOffset);
     }
 }
-exports.TimelinePoint = TimelinePoint;

package/internal/range.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimelineRange = void 0;
-const emitters_1 = require("./emitters");
-const point_1 = require("./point");
-const utils_1 = require("./utils");
-class TimelineRange extends emitters_1.RangeProgression {
+import { RangeProgression } from "./emitters";
+import { TimelinePoint } from "./point";
+import { clamp } from "./utils";
+export class TimelineRange extends RangeProgression {
     /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
     constructor(onListen, timeline, startPosition, 
     /** The duration of this range */
@@ -15,8 +12,8 @@ class TimelineRange extends emitters_1.RangeProgression {
         this.duration = duration;
         this.redirect = (listen) => new TimelineRange(listen, this.timeline, this.startPosition, this.duration);
         this.start = timeline.point(startPosition);
-        this.end = timeline.point(startPosition + duration);
         this.endPosition = startPosition + duration;
+        this.end = timeline.point(this.endPosition);
     }
     /**
      * Creates two ranges by seperating one at a given point
@@ -58,7 +55,7 @@ class TimelineRange extends emitters_1.RangeProgression {
      * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
     grow(delta, anchor = 0) {
-        const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
+        const clampedAnchor = clamp(anchor, 0, 1);
         const leftDelta = -delta * (1 - clampedAnchor);
         const rightDelta = delta * clampedAnchor;
         const newStart = this.startPosition + leftDelta;
@@ -79,7 +76,7 @@ class TimelineRange extends emitters_1.RangeProgression {
         if (factor <= 0) {
             throw new RangeError('scale factor must be > 0');
         }
-        const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
+        const clampedAnchor = clamp(anchor, 0, 1);
         const oldLen = this.endPosition - this.startPosition;
         const pivot = this.startPosition + oldLen * clampedAnchor;
         const newStart = pivot - (pivot - this.startPosition) * factor;
@@ -91,10 +88,9 @@ class TimelineRange extends emitters_1.RangeProgression {
         return this.timeline.range(newStart, newEnd - newStart);
     }
     contains(target) {
-        const [targetStart, targetEnd] = target instanceof point_1.TimelinePoint
+        const [targetStart, targetEnd] = target instanceof TimelinePoint
             ? [target.position, target.position]
             : [target.startPosition, target.startPosition + target.duration];
         return targetStart >= this.startPosition && targetEnd < this.endPosition;
     }
 }
-exports.TimelineRange = TimelineRange;

package/internal/timeline.js

@@ -1,10 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Timeline = void 0;
-exports.animate = animate;
-const point_1 = require("./point");
-const range_1 = require("./range");
-const utils_1 = require("./utils");
+import { TimelinePoint } from "./point";
+import { TimelineRange } from "./range";
+import { clamp } from "./utils";
 const default_fps = 60;
 const EndAction = {
     pause: 0,
@@ -17,10 +13,10 @@ const EndAction = {
  * @param duration
  * @returns Object representing a range on a single-use, autoplaying Timeline
  */
-function animate(duration) {
+export function animate(duration) {
     return new Timeline(true).range(0, duration);
 }
-class Timeline {
+export class Timeline {
     get currentTime() { return this._currentTime; }
     set currentTime(v) {
         this.seek(v);
@@ -109,7 +105,7 @@ class Timeline {
                 }
             };
         };
-        return new point_1.TimelinePoint(addHandler, this, position);
+        return new TimelinePoint(addHandler, this, position);
     }
     range(start = 0, optionalDuration) {
         const startPoint = typeof start == "number"
@@ -145,7 +141,7 @@ class Timeline {
                 }
             };
         };
-        return new range_1.TimelineRange(addHandler, this, startPosition, duration);
+        return new TimelineRange(addHandler, this, startPosition, duration);
     }
     getWrappedPosition(n) {
         if (this.endAction.type !== EndAction.wrap)
@@ -239,7 +235,7 @@ class Timeline {
             // filter ranges that overlap seeked range
             if (Math.min(position, end) <= Math.max(to, fromTime)
                 && Math.min(to, fromTime) <= Math.max(position, end)) {
-                let progress = (0, utils_1.clamp)((to - range.position) / range.duration, 0, 1);
+                let progress = clamp((to - range.position) / range.duration, 0, 1);
                 range.handlers.slice().forEach(h => h(progress));
             }
         });
@@ -344,7 +340,6 @@ class Timeline {
         return this._currentTime;
     }
 }
-exports.Timeline = Timeline;
 const sortEvents = (a, b) => {
     return a.position - b.position;
 };

package/internal/tween.d.ts

@@ -4,5 +4,8 @@ export type Tweenable = number | number[] | string | Blendable;
 export interface Blendable {
     blend(target: this, progress: number): this;
 }
+export interface BlendableWith<T, R> {
+    blend(target: R, progress: number): T;
+}
 /** @internal */
 export declare function tweenValue<T extends Tweenable>(from: T, to: T, progress: number): T;

package/internal/tween.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.tweenValue = tweenValue;
-const utils_1 = require("./utils");
+import { clamp } from "./utils";
 /** @internal */
-function tweenValue(from, to, progress) {
+export function tweenValue(from, to, progress) {
     if (Array.isArray(from)) {
         const toArr = to;
         if (from.length != toArr.length)
@@ -89,7 +86,7 @@ function parseColour(code) {
 function blendColours(from, to, bias) {
     const fromColour = parseColour(from);
     const toColour = parseColour(to);
-    const blended = fromColour.map((val, i) => (0, utils_1.clamp)(blendNumbers(val, toColour[i], bias), 0, 255));
+    const blended = fromColour.map((val, i) => clamp(blendNumbers(val, toColour[i], bias), 0, 255));
     return ("#" + blended.map(n => Math.round(n).toString(16).padStart(2, "0")).join("")).replace(/ff$/, "");
 }
 const tweenableTokenRegex = /(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/g;

package/internal/utils.js

@@ -1,6 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.clamp = void 0;
 /** @internal */
-const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
-exports.clamp = clamp;
+export const clamp = (value, min, max) => Math.min(Math.max(value, min), max);

package/package.json

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