@xtia/timeline 1.1.1 → 1.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 ### Not Just Another Animation Library
 
-Timeline is a type-safe, deterministic choreography system that can control state transitions in any environment, whether that's a simple or complex CSS animation, managing a microcontroller's output, or synchronising complex hardware sequences.
+Timeline is a type-safe, seekable, deterministic choreography system that can control state transitions in any environment, whether that's a simple or complex CSS animation, managing a microcontroller's output, or synchronising complex hardware sequences.
 
 * [API Reference](#reference)
 * [Playground](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
@@ -17,7 +17,7 @@ import { Timeline } from "@xtia/timeline";
 // create a Timeline
 const timeline = new Timeline();
 
-// over the first second, fade the body's background colour
+// over the first second, fade an element's background colour
 timeline
     .range(0, 1000)
     .tween("#646", "#000")
@@ -40,7 +40,7 @@ timeline
 timeline
     .range(1000, 2000)
     .tween(0, 255)
-    .listen(value => microcontroller.setPWM(value))
+    .apply(value => microcontroller.setPWM(value))
 
 // make it go
 timeline.play();
@@ -510,8 +510,8 @@ Registers an emission handler that calls one function for forward seeks to or pa
 ```ts
 point
     .applyDirectional(
-        element.classList.add("faded"),
-        element.classList.remove("faded"),
+        () => element.classList.add("faded"),
+        () => element.classList.remove("faded"),
     );
 ```
 

package/internal/point.d.ts

@@ -38,19 +38,31 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
     delta(timeOffset: number): TimelinePoint;
     /**
      * Seeks the parent Timeline to this point
+     * @deprecated Use timeline.seek(point)
      */
     seek(): void;
+    /**
+     * Smooth-seeks the parent Timeline to this point
+     * @deprecated Use timeline.seek(point)
+     */
     seek(duration: number, easer?: Easer): Promise<void>;
     /**
      * Creates an emitter that only emits on forward-moving seeks
-     * @returns
+     * @returns Listenable: emits forward-seeking point events
      */
     forwardOnly(): Emitter<PointEvent>;
     /**
      * Creates an emitter that only emits on backward-moving seeks
-     * @returns
+     * @returns Listenable: emits backward-seeking point events
      */
     reverseOnly(): Emitter<PointEvent>;
+    filter(check: (event: PointEvent) => boolean): Emitter<PointEvent>;
+    /**
+     * Creates an emitter that forwards events emitted by seeks of a specific direction
+     * @param allow Direction to allow
+     * @returns Listenable: emits point events that match the given direction
+     */
+    filter(allow: -1 | 1): Emitter<PointEvent>;
     /**
      * Creates a Promise that will be resolved when the Timeline first seeks to/past this point
      *
@@ -66,8 +78,8 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * ```
      * point
      * 	.applyDirectional(
-     *     element.classList.add("faded"),
-     *     element.classList.remove("faded"),
+     *     () => element.classList.add("faded"),
+     *     () => element.classList.remove("faded"),
      *   );
      * ```
      *
@@ -79,4 +91,9 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * @returns A function to deregister both handlers
      */
     applyDirectional(apply: () => void, revert: () => void): UnsubscribeFunc;
+    /**
+     * Creates an emitter that forwards point events whose direction differs from the previous emission
+     * @returns Listenable: emits non-repeating point events
+     */
+    dedupe(): Emitter<PointEvent>;
 }

package/internal/point.js

@@ -43,24 +43,30 @@ export class TimelinePoint extends Emitter {
     }
     /**
      * Creates an emitter that only emits on forward-moving seeks
-     * @returns
+     * @returns Listenable: emits forward-seeking point events
      */
     forwardOnly() {
-        return new Emitter(handler => {
-            return this.onListen((ev) => {
-                if (ev.direction > 0)
-                    handler(ev);
-            });
-        });
+        return this.filter(1);
     }
     /**
      * Creates an emitter that only emits on backward-moving seeks
-     * @returns
+     * @returns Listenable: emits backward-seeking point events
      */
     reverseOnly() {
+        return this.filter(-1);
+    }
+    filter(arg) {
+        if (typeof arg == "number") {
+            return new Emitter(handler => {
+                return this.onListen((ev) => {
+                    if (ev.direction === arg)
+                        handler(ev);
+                });
+            });
+        }
         return new Emitter(handler => {
             return this.onListen((ev) => {
-                if (ev.direction < 0)
+                if (arg(ev))
                     handler(ev);
             });
         });
@@ -87,8 +93,8 @@ export class TimelinePoint extends Emitter {
      * ```
      * point
      * 	.applyDirectional(
-     *     element.classList.add("faded"),
-     *     element.classList.remove("faded"),
+     *     () => element.classList.add("faded"),
+     *     () => element.classList.remove("faded"),
      *   );
      * ```
      *
@@ -104,4 +110,17 @@ export class TimelinePoint extends Emitter {
             ? apply()
             : revert());
     }
+    /**
+     * Creates an emitter that forwards point events whose direction differs from the previous emission
+     * @returns Listenable: emits non-repeating point events
+     */
+    dedupe() {
+        let previous = 0;
+        return new Emitter(handler => this.onListen(event => {
+            if (event.direction !== previous) {
+                handler(event);
+                previous = event.direction;
+            }
+        }));
+    }
 }

package/internal/range.d.ts

@@ -48,6 +48,7 @@ export declare class TimelineRange extends RangeProgression {
      * Progresses the Timeline across the range at 1000 units per second
      * @param easer Optional easing function
      * @returns Promise, resolved when the end is reached
+     * @deprecated Use timeline.play(range, easer?)
      */
     play(easer?: Easer | keyof typeof easers): Promise<void>;
     /**

package/internal/range.js

@@ -1,6 +1,5 @@
 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, 
@@ -28,8 +27,8 @@ export class TimelineRange extends RangeProgression {
      */
     bisect(position = this.duration / 2) {
         return [
-            this.timeline.range(position, this.startPosition),
-            this.timeline.range(position + this.startPosition, this.duration - this.startPosition),
+            this.timeline.range(this.startPosition, position),
+            this.timeline.range(position + this.startPosition, this.duration - position),
         ];
     }
     /**
@@ -65,11 +64,12 @@ export class TimelineRange extends RangeProgression {
      * Progresses the Timeline across the range at 1000 units per second
      * @param easer Optional easing function
      * @returns Promise, resolved when the end is reached
+     * @deprecated Use timeline.play(range, easer?)
      */
     play(easer) {
         this.timeline.pause();
         this.timeline.currentTime = this.startPosition;
-        return this.timeline.seek(this.startPosition + this.duration, this.duration, easer);
+        return this.timeline.seek(this.end, this.duration, easer);
     }
     /**
      * Creates a new range representing a direct expansion of this one
@@ -78,16 +78,7 @@ export class TimelineRange extends 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 = clamp(anchor, 0, 1);
-        const leftDelta = -delta * (1 - clampedAnchor);
-        const rightDelta = delta * clampedAnchor;
-        const newStart = this.startPosition + leftDelta;
-        const newEnd = this.startPosition + this.duration + rightDelta;
-        if (newEnd < newStart) {
-            const mid = (newStart + newEnd) / 2;
-            return this.timeline.range(mid, 0);
-        }
-        return this.timeline.range(newStart, newEnd - newStart);
+        return this.timeline.range(this.startPosition - (delta * anchor), this.duration + delta);
     }
     /**
      * Creates a new range representing a multiplicative expansion of this one
@@ -99,16 +90,7 @@ export class TimelineRange extends RangeProgression {
         if (factor <= 0) {
             throw new RangeError('Scale factor must be > 0');
         }
-        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;
-        const newEnd = pivot + (this.endPosition - pivot) * factor;
-        if (newEnd < newStart) {
-            const mid = (newStart + newEnd) / 2;
-            return this.timeline.range(mid, 0);
-        }
-        return this.timeline.range(newStart, newEnd - newStart);
+        return this.grow((factor - 1) * this.duration, anchor);
     }
     contains(target) {
         const [targetStart, targetEnd] = target instanceof TimelinePoint

package/internal/timeline.d.ts

@@ -89,12 +89,12 @@ export declare class Timeline {
      * Defines a range on this Timeline
      *
      * @param start The position on this Timeline at which the range starts
-     * @param duration Length of the resulting range - if omitted, the range will end at the Timeline's **current** final position
+     * @param duration Length of the resulting range
      * @returns A range on the Timeline
      *
      * Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
-    range(start: number | TimelinePoint, duration?: number): TimelineRange;
+    range(start: number | TimelinePoint, duration: number): TimelineRange;
     /**
      * Creates an observable range from position 0 to the Timeline's **current** final position
      */
@@ -124,6 +124,16 @@ export declare class Timeline {
      */
     play(): void;
     play(fps: number): void;
+    /**
+     * Performs a smooth-seek through a range at (1000 × this.timeScale) units per second
+     */
+    play(range: TimelineRange, easer?: Easer): Promise<void>;
+    /**
+     * Stops normal progression instigated by play()
+     *
+     * Does not affect ongoing smooth-seek operations or play(range)
+     *
+     */
     pause(): void;
     /**
      * Progresses the Timeline by 1 unit
@@ -148,9 +158,10 @@ export declare class Timeline {
     get position(): number;
 }
 export interface ChainingInterface {
-    thenTween<T extends Tweenable>(duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer: Easer): ChainingInterface;
+    thenTween<T extends Tweenable>(duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
     then(action: () => void): ChainingInterface;
     thenWait(duration: number): ChainingInterface;
+    fork(fn: (chain: ChainingInterface) => void): ChainingInterface;
     readonly end: TimelinePoint;
 }
 export {};

package/internal/timeline.js

@@ -179,12 +179,12 @@ export class Timeline {
             ? to
             : to.position;
         if (this.seeking) {
-            throw new Error("Can't seek while seeking");
+            throw new Error("Can't seek while a seek event is processed");
         }
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
             // ensure any awaits are resolved for the previous seek
-            this.smoothSeeker.end.seek();
+            this.smoothSeeker.seek(this.smoothSeeker.end);
             this.smoothSeeker = null;
         }
         if (duration === 0) {
@@ -193,8 +193,12 @@ export class Timeline {
         }
         const seeker = new Timeline(true);
         this.smoothSeeker = seeker;
-        seeker.range(0, duration).ease(easer).tween(this.currentTime, toPosition).apply(v => this.seekDirect(v));
-        return new Promise(r => seeker.end.apply(() => r()));
+        seeker
+            .range(0, duration)
+            .ease(easer)
+            .tween(this.currentTime, toPosition)
+            .apply(v => this.seekDirect(v));
+        return seeker.end.promise();
     }
     seekDirect(toPosition) {
         const fromPosition = this._currentTime;
@@ -252,7 +256,7 @@ export class Timeline {
                 range.handlers.slice().forEach(h => h(progress));
             }
         });
-        this.progressionHandlers.slice().forEach(h => h(fromTime / this._endPosition));
+        this.progressionHandlers.slice().forEach(h => h(toTime / this._endPosition));
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -263,9 +267,18 @@ export class Timeline {
             ? sortTweens
             : sortReverse);
     }
-    play(fps = default_fps) {
+    play(arg = default_fps, easer) {
         if (this.interval !== null)
             this.pause();
+        if (this.smoothSeeker) {
+            this.smoothSeeker.pause();
+            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker = null;
+        }
+        if (arg instanceof TimelineRange) {
+            this.seek(arg.start);
+            return this.seek(arg.end, arg.duration / this.timeScale, easer);
+        }
         let previousTime = Date.now();
         this.interval = setInterval(() => {
             const newTime = Date.now();
@@ -303,8 +316,14 @@ export class Timeline {
                 return;
             }
             this.currentTime += delta;
-        }, 1000 / fps);
+        }, 1000 / arg);
     }
+    /**
+     * Stops normal progression instigated by play()
+     *
+     * Does not affect ongoing smooth-seek operations or play(range)
+     *
+     */
     pause() {
         if (this.interval === null)
             return;
@@ -330,12 +349,12 @@ export class Timeline {
             reverse = action;
         if (action)
             point.apply(reverse
-                ? (event => event.direction < 0 ? reverse() : action)
+                ? (event => event.direction < 0 ? reverse() : action())
                 : action);
         return this.createChainingInterface(point.position);
     }
     createChainingInterface(position) {
-        return {
+        const chain = {
             thenTween: (duration, apply, from, to, easer) => {
                 return this.tween(position, duration, apply, from, to, easer);
             },
@@ -344,8 +363,13 @@ export class Timeline {
                 this.point(position + delay);
                 return this.createChainingInterface(position + delay);
             },
+            fork: fn => {
+                fn(chain);
+                return chain;
+            },
             end: this.point(position),
         };
+        return chain;
     }
     /**
      * @deprecated use `timeline.currentTime`

package/internal/tween.js

@@ -1,9 +1,11 @@
 import { clamp } from "./utils";
-const tokenTypes = {
-    none: 0,
-    number: 1,
-    colour: 2,
-};
+var TokenTypes;
+(function (TokenTypes) {
+    TokenTypes[TokenTypes["none"] = 0] = "none";
+    TokenTypes[TokenTypes["number"] = 1] = "number";
+    TokenTypes[TokenTypes["colour"] = 2] = "colour";
+})(TokenTypes || (TokenTypes = {}));
+;
 export function createTween(from, to) {
     if (from === to)
         return () => from;
@@ -39,9 +41,9 @@ function createStringTween(from, to) {
         const fromToken = chunk.token;
         const toToken = toChunks[i].token;
         const prefix = chunk.prefix;
-        if (chunk.type === tokenTypes.none)
+        if (chunk.type === TokenTypes.none)
             return () => prefix;
-        if (chunk.type === tokenTypes.colour) {
+        if (chunk.type === TokenTypes.colour) {
             const fromColour = parseColour(fromToken);
             const toColour = parseColour(toToken);
             return progress => prefix + blendColours(fromColour, toColour, progress);
@@ -142,13 +144,13 @@ function tokenise(s) {
     // trailing literal after the last token – stored as a final chunk
     const tail = s.slice(lastIdx);
     if (tail.length) {
-        chunks.push({ prefix: tail, token: "", type: tokenTypes.none });
+        chunks.push({ prefix: tail, token: "", type: TokenTypes.none });
     }
     return chunks;
 }
 ;
 function getTokenType(token) {
     if (token.startsWith("#"))
-        return tokenTypes.colour;
-    return tokenTypes.number;
+        return TokenTypes.colour;
+    return TokenTypes.number;
 }

package/package.json

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