@xtia/timeline 1.0.5 → 1.0.7

package/internal/emitters.js

@@ -1,119 +1,254 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createEmitter = createEmitter;
-exports.createProgressEmitter = createProgressEmitter;
+exports.RangeProgression = exports.Emitter = void 0;
 const easing_1 = require("./easing");
 const tween_1 = require("./tween");
 const utils_1 = require("./utils");
-function createEmitterMethodProperties(listen, extensions) {
-    return Object.fromEntries(Object.entries({
-        listen: (handler) => listen((value) => {
+class Emitter {
+    constructor(onListen) {
+        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
+         * @returns {this}
+         */
+        this.redirect = (listen) => new Emitter(listen);
+    }
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    listen(handler) {
+        return this.onListen((value) => {
             handler(value);
-        }),
-        map: (mapFunc) => createEmitter(handler => listen((value) => {
+        });
+    }
+    /**
+     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
+     * @param mapFunc
+     * @returns Listenable: emits transformed values
+     */
+    map(mapFunc) {
+        return new Emitter(handler => this.onListen((value) => {
             handler(mapFunc(value));
-        })),
-        filter: (filterFunc) => createEmitter(handler => listen((value) => {
-            if (filterFunc(value))
+        }));
+    }
+    /**
+     * Creates a chainable emitter that selectively forwards emissions along the chain
+     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check) {
+        return new Emitter(handler => this.onListen((value) => {
+            if (check(value))
                 handler(value);
-        })),
-        noRepeat: (compare) => {
-            let previous = null;
-            return createEmitter(handler => {
-                const filteredHandler = (value) => {
-                    if (!previous || (compare
-                        ? !compare(previous.value, value)
-                        : (previous.value !== value))) {
-                        handler(value);
-                        previous = { value };
-                    }
-                };
-                return listen(filteredHandler);
-            });
-        },
-        tap: (cb) => createTap(cb, createEmitter, listen),
-        ...extensions,
-    }).map(([key, value]) => [
-        key,
-        { value }
-    ]));
-}
-/** @internal */
-function createEmitter(listen, api) {
-    const propertyDescriptor = createEmitterMethodProperties(listen, {});
-    return Object.create(api ?? {}, propertyDescriptor);
-}
-/** @internal */
-function createProgressEmitter(listen, api = {}) {
-    const propertyDescriptor = createEmitterMethodProperties(listen, {
-        ease: (easer) => {
-            const easerFunc = typeof easer == "string"
-                ? easing_1.easers[easer]
-                : easer;
-            return createProgressEmitter(easer ? (handler => listen((progress) => {
-                handler(easerFunc(progress));
-            })) : listen);
-        },
-        tween: (from, to) => createEmitter(handler => listen(progress => handler((0, tween_1.tweenValue)(from, to, progress)))),
-        snap: (steps) => {
-            if (!Number.isInteger(steps) || steps <= 0) {
-                throw new RangeError('snap(steps) requires a positive integer');
+        }));
+    }
+    /**
+     * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
+     * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
+     *
+     * If no `compare` function is provided, values will be compared via `===`
+     * @returns Listenable: emits non-repeating values
+     */
+    dedupe(compare) {
+        let previous = null;
+        return new Emitter(handler => {
+            const filteredHandler = (value) => {
+                if (!previous || (compare
+                    ? !compare(previous.value, value)
+                    : (previous.value !== value))) {
+                    handler(value);
+                    previous = { value };
+                }
+            };
+            return this.onListen(filteredHandler);
+        });
+    }
+    /**
+     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     *
+     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
+     * All listeners attached to the returned emitter receive the same values as the parent emitter.
+     *
+     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     *
+     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
+     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     */
+    tap(cb) {
+        const listeners = [];
+        let parentUnsubscribe = null;
+        const tappedListen = (handler) => {
+            listeners.push(handler);
+            if (listeners.length === 1) {
+                parentUnsubscribe = this.onListen(value => {
+                    cb(value);
+                    listeners.slice().forEach(fn => fn(value));
+                });
             }
-            return createProgressEmitter(handler => listen(progress => {
-                const snapped = Math.round(progress * steps) / steps;
-                handler((0, utils_1.clamp)(snapped, 0, 1));
-            }));
-        },
-        threshold: (threshold) => createProgressEmitter(handler => listen(progress => {
+            return () => {
+                const idx = listeners.indexOf(handler);
+                listeners.splice(idx, 1);
+                if (listeners.length === 0 && parentUnsubscribe) {
+                    parentUnsubscribe();
+                    parentUnsubscribe = null;
+                }
+            };
+        };
+        return this.redirect(tappedListen);
+    }
+    /**
+     * Immediately passes this emitter to a callback and returns this emitter
+     *
+     * Allows branching without breaking a composition chain
+     *
+     * @example
+     * ```ts
+     * range
+     *   .tween("0%", "100%")
+     *   .fork(branch => {
+     *     branch
+     *       .map(s => `Loading: ${s}`)
+     *       .listen(s => document.title = s)
+     *   })
+     *   .listen(v => progressBar.style.width = v);
+     * ```
+     * @param cb
+     */
+    fork(cb) {
+        cb(this);
+        return this;
+    }
+}
+exports.Emitter = Emitter;
+class RangeProgression extends Emitter {
+    constructor() {
+        super(...arguments);
+        this.redirect = (listen) => new RangeProgression(listen);
+    }
+    ease(easer) {
+        if (!easer)
+            return this;
+        const easerFunc = typeof easer == "string"
+            ? easing_1.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))));
+    }
+    /**
+     * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
+     *
+     * @param steps – positive integer (e.g. 10 → 0, .1, .2 … 1)
+     * @throws RangeError if steps is not a positive integer
+     * @returns Listenable: emits quantised progression values
+     */
+    snap(steps) {
+        if (!Number.isInteger(steps) || steps <= 0) {
+            throw new RangeError('snap(steps) requires a positive integer');
+        }
+        return new RangeProgression(handler => this.onListen(progress => {
+            const snapped = Math.round(progress * steps) / steps;
+            handler((0, utils_1.clamp)(snapped, 0, 1));
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that emits `1` when the incoming progress value is greater‑than‑or‑equal to the supplied `threshold`, otherwise emits `0`
+     *
+     * @param threshold the cut‑off value
+     * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
+     */
+    threshold(threshold) {
+        return new RangeProgression(handler => this.onListen(progress => {
             handler(progress >= threshold ? 1 : 0);
-        })),
-        clamp: (min = 0, max = 1) => createProgressEmitter(handler => listen(progress => handler((0, utils_1.clamp)(progress, min, max)))),
-        repeat: (repetitions) => {
-            repetitions = Math.max(0, repetitions);
-            return createProgressEmitter(handler => listen(progress => {
-                const out = (progress * repetitions) % 1;
-                handler(out);
-            }));
-        },
-        tap: (cb) => createTap(cb, createProgressEmitter, listen),
-        filter: (filterFunc) => createProgressEmitter(handler => listen((value) => {
-            if (filterFunc(value))
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that clamps incoming values
+     * @param min default 0
+     * @param max default 1
+     * @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))));
+    }
+    /**
+     * Creates a chainable progress emitter that maps incoming values to a repeating linear scale
+     *
+     * ```plain
+     * 	count=2
+     *‎	1
+     *‎	 |     /     /
+     *‎	o|    /     /
+     *‎	u|   /     /
+     *‎	t|  /     /
+     *‎	 | /     /
+     *‎	 |/_____/_____
+     *‎	0     in      1
+     * ```
+     *
+     * @param count Number of repetitions
+     * @returns Listenable: emits scaled and repeating values
+     */
+    repeat(count) {
+        count = Math.max(0, count);
+        return new RangeProgression(handler => this.onListen(progress => {
+            const out = (progress * count) % 1;
+            handler(out);
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that selectively forwards emissions along the chain
+     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check) {
+        return new RangeProgression(handler => this.onListen((value) => {
+            if (check(value))
                 handler(value);
-        })),
-        noRepeat: () => {
-            let previous = null;
-            return createProgressEmitter(handler => {
-                return listen((value) => {
-                    if (!previous || (previous.value !== value)) {
-                        handler(value);
-                        previous = { value };
-                    }
-                });
-            });
-        },
-        offset: (delta) => createProgressEmitter(handler => listen(value => handler((value + delta) % 1))),
-    });
-    return Object.create(api ?? {}, propertyDescriptor);
-}
-function createTap(callback, create, parentListen) {
-    const listeners = [];
-    let parentUnsubscribe = null;
-    const tapOnListen = (handler) => {
-        listeners.push(handler);
-        if (listeners.length === 1) {
-            parentUnsubscribe = parentListen(value => {
-                callback(value);
-                listeners.slice().forEach(fn => fn(value));
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that discards emitted values that are the same as the last value emitted by the new emitter
+     * @returns Listenable: emits non-repeating values
+     */
+    dedupe() {
+        let previous = null;
+        return new RangeProgression(handler => {
+            return this.onListen((value) => {
+                if (!previous === null || previous !== value) {
+                    handler(value);
+                    previous = value;
+                }
             });
-        }
-        return () => {
-            const idx = listeners.indexOf(handler);
-            listeners.splice(idx, 1);
-            if (listeners.length === 0 && parentUnsubscribe) {
-                parentUnsubscribe();
-                parentUnsubscribe = null;
-            }
-        };
-    };
-    return create(tapOnListen);
+        });
+    }
+    /**
+     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
+     *
+     * ```plain
+     *‎	1
+     *‎	 |  /
+     *‎	o| /
+     *‎	u|/      __ delta=.5
+     *‎	t|     /
+     *‎	 |    /
+     *‎	 |___/__
+     *‎	0  in   1
+     * ```
+     *
+     * @param delta
+     * @returns Listenable: emits offset values
+     */
+    offset(delta) {
+        return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
+    }
 }
+exports.RangeProgression = RangeProgression;

package/internal/point.d.ts

@@ -1,9 +1,22 @@
-import { Emitter } from "./emitters";
+import { Emitter, ListenFunc } from "./emitters";
 import { TimelineRange } from "./range";
+import { Timeline } from "./timeline";
 export type PointEvent = {
     direction: -1 | 1;
 };
-export interface TimelinePoint extends Emitter<PointEvent> {
+export declare class TimelinePoint extends Emitter<PointEvent> {
+    private timeline;
+    /**
+     * The point's absolute position on the Timeline
+     */
+    readonly position: number;
+    /** @internal Manual construction of TimelinePoint is outside of the API contract and subject to undocumented change */
+    constructor(onListen: ListenFunc<PointEvent>, timeline: Timeline, 
+    /**
+     * The point's absolute position on the Timeline
+     */
+    position: number);
+    protected redirect: (listen: ListenFunc<PointEvent>) => TimelinePoint;
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
      * @param duration
@@ -22,8 +35,4 @@ export interface TimelinePoint extends Emitter<PointEvent> {
      * @returns Listenable: emits a PointEvent when the point is reached or passed by a Timeline seek
      */
     delta(timeOffset: number): TimelinePoint;
-    /**
-     * The point's absolute position on the Timeline
-     */
-    readonly position: number;
 }

package/internal/point.js

@@ -1,2 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimelinePoint = void 0;
+const emitters_1 = require("./emitters");
+class TimelinePoint extends emitters_1.Emitter {
+    /** @internal Manual construction of TimelinePoint is outside of the API contract and subject to undocumented change */
+    constructor(onListen, timeline, 
+    /**
+     * The point's absolute position on the Timeline
+     */
+    position) {
+        super(onListen);
+        this.timeline = timeline;
+        this.position = position;
+        this.redirect = (listen) => new TimelinePoint(listen, this.timeline, this.position);
+    }
+    /**
+     * Creates a range on the Timeline, with a given duration, starting at this point
+     * @param duration
+     * @returns Listenable: emits normalised (0..1) range progression
+     */
+    range(duration) {
+        return this.timeline.range(this.position, duration);
+    }
+    /**
+     * Creates a range on the Timeline, with a given end point, starting at this point
+     * @param endPoint
+     * @returns Listenable: emits normalised (0..1) range progression
+     */
+    to(endPoint) {
+        const endPosition = typeof endPoint == "number"
+            ? endPoint
+            : endPoint.position;
+        return this.timeline.range(this.position, endPosition - this.position);
+    }
+    /**
+     * Creates a point on the Timeline at an offset position from this one
+     * @param timeOffset
+     * @returns Listenable: emits a PointEvent when the point is reached or passed by a Timeline seek
+     */
+    delta(timeOffset) {
+        return this.timeline.point(this.position + timeOffset);
+    }
+}
+exports.TimelinePoint = TimelinePoint;

package/internal/range.d.ts

@@ -1,7 +1,18 @@
 import { Easer, easers } from "./easing";
-import { RangeProgression } from "./emitters";
+import { ListenFunc, RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
-export interface TimelineRange extends RangeProgression {
+import { Timeline } from "./timeline";
+export declare class TimelineRange extends RangeProgression {
+    private timeline;
+    private startPosition;
+    /** The duration of this range */
+    readonly duration: number;
+    private endPosition;
+    /** @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 */
+    duration: number);
+    protected redirect: (listen: ListenFunc<number>) => TimelineRange;
     /**
      * Creates two ranges by seperating one at a given point
      * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
@@ -41,10 +52,9 @@ export interface TimelineRange extends RangeProgression {
      * @returns true if the provided point is within the range
      */
     contains(point: TimelinePoint): boolean;
+    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;
-    /** The duration of this range */
-    readonly duration: number;
 }

package/internal/range.js

@@ -1,2 +1,100 @@
 "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 {
+    /** @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 */
+    duration) {
+        super(onListen);
+        this.timeline = timeline;
+        this.startPosition = startPosition;
+        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;
+    }
+    /**
+     * Creates two ranges by seperating one at a given point
+     * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
+     *
+     * Must be greater than 0 and less than the range's duration
+     * @returns Tuple of two ranges
+     */
+    bisect(position = this.duration / 2) {
+        return [
+            this.timeline.range(position, this.startPosition),
+            this.timeline.range(position + this.startPosition, this.duration - this.startPosition),
+        ];
+    }
+    /**
+     * Creates a series of evenly-spread points across the range, excluding the range's start and end
+     * @param count Number of Points to return
+     * @returns Array(count) of points
+     */
+    spread(count) {
+        const delta = this.duration / (count + 1);
+        return [
+            ...Array(count).fill(0).map((_, idx) => this.timeline.point(idx * delta + this.startPosition + delta))
+        ];
+    }
+    /**
+     * Progresses the Timeline across the range
+     * @param easer
+     */
+    play(easer) {
+        this.timeline.pause();
+        this.timeline.currentTime = this.startPosition;
+        return this.timeline.seek(this.startPosition + this.duration, this.duration, easer);
+    }
+    /**
+     * Creates a new range representing a direct expansion of this one
+     * @param delta Amount to grow by (in time units)
+     * @param anchor Normalised position at which to expand (0 being the start, expanding right, 1 being the end, expanding left, 0.5 expanding evenly)
+     * @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 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);
+    }
+    /**
+     * Creates a new range representing a multiplicative expansion of this one
+     * @param factor Size multiplier
+     * @param anchor Normalised position at which to expand (0 being the start, expanding right, 1 being the end, expanding left, 0.5 expanding evenly)
+     * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
+     */
+    scale(factor, anchor = 0) {
+        if (factor <= 0) {
+            throw new RangeError('scale factor must be > 0');
+        }
+        const clampedAnchor = (0, utils_1.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);
+    }
+    contains(target) {
+        const [targetStart, targetEnd] = target instanceof point_1.TimelinePoint
+            ? [target.position, target.position]
+            : [target.startPosition, target.startPosition + target.duration];
+        return targetStart >= this.startPosition && targetEnd < this.endPosition;
+    }
+}
+exports.TimelineRange = TimelineRange;

package/internal/timeline.d.ts

@@ -128,9 +128,9 @@ export declare class Timeline {
      * @deprecated Use timeline.position += n
      */
     step(delta: number): void;
-    tween<T extends Tweenable>(start: number | TimelinePoint, duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    tween<T extends Tweenable>(start: number | TimelinePoint, duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer | keyof typeof easers): ChainingInterface;
     tween<T extends Tweenable>(start: number | TimelinePoint, end: TimelinePoint, // ease migration for tl.tween(0, tl.end, ...)
-    apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer | keyof typeof easers): ChainingInterface;
     at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
     private createChainingInterface;
     /**
@@ -139,7 +139,7 @@ export declare class Timeline {
     get position(): number;
 }
 export interface ChainingInterface {
-    thenTween(duration: number, apply: (v: number) => void, from?: number, to?: number, 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;
     readonly end: TimelinePoint;