@xtia/timeline 1.1.12 → 1.1.14

package/README.md

@@ -107,8 +107,8 @@ const filenameEmitter = range
     .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
+// 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}`);
 
@@ -145,12 +145,21 @@ Points emit `PointEvent` objects when their position is reached or passed.
 ```ts
 twoSecondsIn.apply(event => {
     // event.direction (-1 | 1) tells us the direction of the seek that
-    // triggered the point. This allows for reversible point events
-    document.body.classList.toggle("someClass", event.direction > 0);
+    // triggered the point. This allows for reversible effects:
+    element.classList.toggle("someClass", event.direction > 0);
 });
 ```
 
-*Note*, point events will be triggered in order, depending on the direction of the seek that passes over them.
+*Note*, point events will be triggered in order, depending on the direction of the seek that passes over them. To ensure consistent reversible behaviour, a point is triggered with `direction = 1` when a forward seek *passes or lands on* it, and with `direction = -1` when a backward seek *passes or departs from* it.
+
+Directionality can also be leveraged with `point.applyDirectional()`:
+
+```ts
+twoSecondsIn.applyDirectional(
+    parent.append(element), // do
+    element.remove() // undo
+);
+```
 
 We can also create ranges from points:
 
@@ -165,7 +174,7 @@ timeline
     .tween(/*...*/);
 ```
 
-*Note*, points and ranges without active listeners are not stored, so will be garbage-collected if unreferenced.
+*Note*, points and ranges are transient interfaces for adding behaviour to their Timelines; they can be garbage-collected if unreferenced even while their listeners persist.
 
 ## More on tweening
 

package/internal/emitters.d.ts

@@ -6,7 +6,7 @@ export type UnsubscribeFunc = () => void;
 export declare class Emitter<T> {
     protected onListen: ListenFunc<T>;
     protected constructor(onListen: ListenFunc<T>);
-    protected createTransformListen<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
+    protected transform<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
      * @param handler

package/internal/emitters.js

@@ -5,7 +5,7 @@ export class Emitter {
     constructor(onListen) {
         this.onListen = onListen;
     }
-    createTransformListen(handler) {
+    transform(handler) {
         let parentUnsubscribe = null;
         const parentListen = this.onListen;
         const { emit, listen } = createListenable(() => parentUnsubscribe = parentListen(value => {
@@ -38,7 +38,7 @@ export class Emitter {
      * @returns Listenable: emits transformed values
      */
     map(mapFunc) {
-        const listen = this.createTransformListen((value, emit) => emit(mapFunc(value)));
+        const listen = this.transform((value, emit) => emit(mapFunc(value)));
         return new Emitter(listen);
     }
     /**
@@ -47,7 +47,7 @@ export class Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        const listen = this.createTransformListen((value, emit) => check(value) && emit(value));
+        const listen = this.transform((value, emit) => check(value) && emit(value));
         return new Emitter(listen);
     }
     /**
@@ -59,7 +59,7 @@ export class Emitter {
      */
     dedupe(compare) {
         let previous = null;
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             if (!previous || (compare
                 ? !compare(previous.value, value)
                 : (previous.value !== value))) {
@@ -81,7 +81,7 @@ export class Emitter {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb) {
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             cb(value);
             emit(value);
         });
@@ -115,13 +115,13 @@ export class RangeProgression extends Emitter {
             ? easers[easer]
             : easer;
         const listen = easerFunc
-            ? this.createTransformListen((value, emit) => emit(easerFunc(value)))
+            ? this.transform((value, emit) => emit(easerFunc(value)))
             : this.onListen;
         return new RangeProgression(listen);
     }
     tween(from, to) {
         const tween = createTween(from, to);
-        const listen = this.createTransformListen((progress, emit) => emit(tween(progress)));
+        const listen = this.transform((progress, emit) => emit(tween(progress)));
         return new Emitter(listen);
     }
     /**
@@ -138,7 +138,7 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits the sampled values
      */
     sample(source) {
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             const clampedProgress = clamp(value);
             const index = Math.floor(clampedProgress * (source.length - 1));
             emit(source[index]);
@@ -168,7 +168,7 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
      */
     threshold(threshold) {
-        const listen = this.createTransformListen((value, emit) => emit(value >= threshold ? 1 : 0));
+        const listen = this.transform((value, emit) => emit(value >= threshold ? 1 : 0));
         return new RangeProgression(listen);
     }
     /**
@@ -201,7 +201,7 @@ export class RangeProgression extends Emitter {
     repeat(count) {
         if (count <= 0)
             throw new RangeError("Repeat count must be greater than 0");
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             const out = (value * count) % 1;
             emit(out);
         });
@@ -213,7 +213,7 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             if (check(value))
                 emit(value);
         });
@@ -226,7 +226,7 @@ export class RangeProgression extends Emitter {
     dedupe() {
         if (!this._dedupe) {
             let previous = null;
-            const listen = this.createTransformListen((value, emit) => {
+            const listen = this.transform((value, emit) => {
                 if (previous !== value) {
                     emit(value);
                     previous = value;
@@ -268,7 +268,7 @@ export class RangeProgression extends Emitter {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb) {
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             cb(value);
             emit(value);
         });

package/internal/point.js

@@ -59,7 +59,7 @@ export class TimelinePoint extends Emitter {
         return this._reverseOnly;
     }
     filter(arg) {
-        const listen = this.createTransformListen(typeof arg == "number"
+        const listen = this.transform(typeof arg == "number"
             ? (value, emit) => {
                 if (value.direction === arg)
                     emit(value);
@@ -79,7 +79,7 @@ export class TimelinePoint extends Emitter {
      */
     promise() {
         return new Promise(resolve => {
-            let remove = this.apply((ev) => {
+            let remove = this.onListen((ev) => {
                 remove();
                 resolve(ev.direction);
             });
@@ -116,7 +116,7 @@ export class TimelinePoint extends Emitter {
     dedupe() {
         if (!this._dedupe) {
             let previous = 0;
-            const listen = this.createTransformListen((value, emit) => {
+            const listen = this.transform((value, emit) => {
                 if (value.direction !== previous) {
                     previous = value.direction;
                     emit(value);

package/internal/range.js

@@ -23,8 +23,8 @@ export class TimelineRange extends RangeProgression {
      * @returns Tuple of two ranges
      */
     bisect(position = this.duration / 2) {
-        if (position >= this.endPosition) {
-            throw new RangeError("Bisection position is beyond end of range");
+        if (position >= this.duration) {
+            throw new RangeError("Bisection position is at or beyond end of range");
         }
         return [
             this.timeline.range(this.startPosition, position),

package/internal/timeline.d.ts

@@ -20,6 +20,20 @@ type Period = {
  */
 export declare function animate(durationMs: number): TimelineRange;
 export declare function animate(period: Period): TimelineRange;
+type TimelineOptions = {
+    atEnd?: {
+        wrapAt: number;
+    } | {
+        restartAt: number;
+    } | keyof typeof EndAction;
+    timeScale?: number;
+} & ({
+    autoplay: true;
+    fps?: number;
+} | ({
+    autoplay?: false;
+    fps?: never;
+}));
 export declare class Timeline {
     /**
      * Multiplies the speed at which `play()` progresses through the Timeline
@@ -90,6 +104,7 @@ export declare class Timeline {
     } | {
         restartAt: number;
     } | keyof typeof EndAction);
+    constructor(options: TimelineOptions);
     /**
      * @deprecated "loop" endAction will be removed; use "restart" or `{restartAt: 0}` (disambiguates new looping strategies)
      */

package/internal/timeline.js

@@ -64,7 +64,7 @@ export class Timeline {
         }
         return this._progression.emitter;
     }
-    constructor(autoplay = false, endAction = "pause") {
+    constructor(optionsOrAutoplay = false, endAction = "pause") {
         /**
          * Multiplies the speed at which `play()` progresses through the Timeline
          *
@@ -85,13 +85,26 @@ export class Timeline {
         this.start = this.point(0);
         this._frameEvents = null;
         this._progression = null;
+        // "loop" is temporary alias for "restart":
         if (endAction == "loop")
             endAction = "restart";
-        if (autoplay === true) {
+        if (typeof optionsOrAutoplay == "object") {
+            endAction = optionsOrAutoplay.atEnd ?? "pause";
+            this.timeScale = optionsOrAutoplay.timeScale ?? 1;
+            if ("autoplay" in optionsOrAutoplay && optionsOrAutoplay.autoplay) {
+                if ("fps" in optionsOrAutoplay && optionsOrAutoplay.fps) {
+                    this.play(optionsOrAutoplay.fps);
+                }
+                else {
+                    this.play();
+                }
+            }
+        }
+        else if (optionsOrAutoplay === true) {
             this.play();
         }
-        else if (typeof autoplay == "number") {
-            this.play(autoplay);
+        else if (typeof optionsOrAutoplay == "number") {
+            this.play(optionsOrAutoplay);
         }
         if (typeof endAction == "object"
             && "restartAt" in endAction) {

package/internal/tween.js

@@ -134,7 +134,19 @@ function parseColour(code) {
 }
 function blendColours(from, to, bias) {
     const blended = from.map((val, i) => clamp(blendNumbers(val, to[i], bias), 0, 255));
-    return ("#" + blended.map(n => Math.round(n).toString(16).padStart(2, "0")).join("")).replace(/ff$/, "");
+    if (blended[3] === 255) {
+        return "#" +
+            Math.round(blended[0]).toString(16).padStart(2, "0") +
+            Math.round(blended[1]).toString(16).padStart(2, "0") +
+            Math.round(blended[2]).toString(16).padStart(2, "0");
+    }
+    else {
+        return "#" +
+            Math.round(blended[0]).toString(16).padStart(2, "0") +
+            Math.round(blended[1]).toString(16).padStart(2, "0") +
+            Math.round(blended[2]).toString(16).padStart(2, "0") +
+            Math.round(blended[3]).toString(16).padStart(2, "0");
+    }
 }
 const tweenableTokenRegex = /(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/g;
 function tokenise(s) {

package/package.json

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