@xtia/timeline 1.0.0 → 1.0.2

package/internal/emitters.d.ts

@@ -0,0 +1,52 @@
+import { RangeProgression } from "./range";
+/** @internal */
+export declare function createEmitter<T>(onListen: (handler: Handler<T>) => UnsubscribeFunc): Emitter<T>;
+/** @internal */
+export declare function createEmitter<T, API extends object>(onListen: (handler: Handler<T>) => UnsubscribeFunc, api: Omit<API, keyof Emitter<T>>): Emitter<T> & API;
+/** @internal */
+export declare function createProgressEmitter<API extends object>(onListen: (handler: Handler<number>) => UnsubscribeFunc, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
+/** @internal */
+export declare function createProgressEmitter(onListen: (handler: Handler<number>) => UnsubscribeFunc): RangeProgression;
+type Handler<T> = (value: T) => void;
+export type UnsubscribeFunc = () => void;
+export interface Emitter<T> {
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    listen(handler: Handler<T>): UnsubscribeFunc;
+    /**
+     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
+     * @param mapFunc
+     * @returns Listenable: emits transformed values
+     */
+    map<R>(mapFunc: (value: T) => R): Emitter<R>;
+    /**
+     * 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: (value: T) => boolean): Emitter<T>;
+    /**
+     * 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
+     */
+    noRepeat(compare?: (a: T, b: T) => boolean): Emitter<T>;
+    /**
+     * 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: Handler<T>): Emitter<T>;
+}
+export {};

package/internal/emitters.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmitter = createEmitter;
+exports.createProgressEmitter = createProgressEmitter;
+const easing_1 = require("./easing");
+const tween_1 = require("./tween");
+const utils_1 = require("./utils");
+/** @internal */
+function createEmitter(onListen, api) {
+    const propertyDescriptor = Object.fromEntries(Object.entries({
+        listen: (handler) => {
+            const uniqueHandler = (value) => {
+                handler(value);
+            };
+            return onListen(uniqueHandler);
+        },
+        map: (mapFunc) => {
+            return createEmitter(handler => {
+                const pipedHandler = (value) => {
+                    handler(mapFunc(value));
+                };
+                return onListen(pipedHandler);
+            });
+        },
+        filter: (filterFunc) => {
+            return createEmitter(handler => {
+                const filteredHandler = (value) => {
+                    if (filterFunc(value))
+                        handler(value);
+                };
+                return onListen(filteredHandler);
+            });
+        },
+        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 onListen(filteredHandler);
+            });
+        },
+        tap: (cb) => {
+            let listeners = [];
+            let parentUnsubscribe = null;
+            const tapOnListen = (handler) => {
+                listeners.push(handler);
+                if (listeners.length === 1) {
+                    parentUnsubscribe = onListen(value => {
+                        cb(value);
+                        listeners.slice().forEach(fn => fn(value));
+                    });
+                }
+                return () => {
+                    listeners = listeners.filter(l => l !== handler);
+                    if (listeners.length === 0 && parentUnsubscribe) {
+                        parentUnsubscribe();
+                        parentUnsubscribe = null;
+                    }
+                };
+            };
+            return createEmitter(tapOnListen);
+        },
+    }).map(([key, value]) => [
+        key,
+        { value }
+    ]));
+    return Object.create(api ?? {}, propertyDescriptor);
+}
+/** @internal */
+function createProgressEmitter(onListen, api = {}) {
+    const propertyDescriptor = Object.fromEntries(Object.entries({
+        ease: (easer) => {
+            const easerFunc = typeof easer == "string"
+                ? easing_1.easers[easer]
+                : easer;
+            return createProgressEmitter(easer ? (handler => onListen((progress) => {
+                handler(easerFunc(progress));
+            })) : onListen);
+        },
+        tween: (from, to) => createEmitter(handler => onListen(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');
+            }
+            return createProgressEmitter(handler => onListen(progress => {
+                const snapped = Math.round(progress * steps) / steps;
+                handler((0, utils_1.clamp)(snapped, 0, 1));
+            }));
+        },
+        threshold: (threshold) => createProgressEmitter(handler => onListen(progress => {
+            handler(progress >= threshold ? 1 : 0);
+        })),
+        clamp: (min = 0, max = 1) => createProgressEmitter(handler => onListen(progress => handler((0, utils_1.clamp)(progress, min, max)))),
+        repeat: (repetitions) => {
+            repetitions = Math.max(0, repetitions);
+            return createProgressEmitter(handler => onListen(progress => {
+                const out = (progress * repetitions) % 1;
+                handler(out);
+            }));
+        },
+    }).map(([key, value]) => [
+        key,
+        { value }
+    ]));
+    return createEmitter(onListen, Object.create(api, propertyDescriptor));
+}

package/internal/point.d.ts

@@ -0,0 +1,26 @@
+import { Emitter } from "./emitters";
+import { TimelineRange } from "./range";
+export type PointEvent = {
+    direction: -1 | 1;
+};
+export interface TimelinePoint extends Emitter<PointEvent> {
+    /**
+     * Creates a range on the Timeline, with a given duration, starting at this point
+     * @param duration
+     */
+    range(duration: number): TimelineRange;
+    /**
+     * Creates a range on the Timeline, with a given end point, starting at this point
+     * @param endPoint
+     */
+    to(endPoint: number | TimelinePoint): TimelineRange;
+    /**
+     * Creates a point on the Timeline at an offset position from this one
+     * @param timeOffset
+     */
+    delta(timeOffset: number): TimelinePoint;
+    /**
+     * The point's absolute position on the Timeline
+     */
+    readonly position: number;
+}

package/internal/point.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/internal/range.d.ts

@@ -0,0 +1,120 @@
+import { Easer, easers } from "./easing";
+import { Emitter } from "./emitters";
+import { TimelinePoint } from "./point";
+import { Blendable } from "./tween";
+export interface TimelineRange extends RangeProgression {
+    /**
+     * 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
+     */
+    bisect(position?: number): [TimelineRange, TimelineRange];
+    /**
+     * Creates a series of evenly-spread points across the range, excluding the range's start and end
+     * @param count Number of Points to return
+     */
+    spread(count: number): TimelinePoint[];
+    /**
+     * Progresses the Timeline across the range
+     * @param easer
+     */
+    play(easer?: Easer): Promise<void>;
+    /**
+     * 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: number, anchor?: number): TimelineRange;
+    /**
+     * 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: number, anchor?: number): TimelineRange;
+    /** 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;
+}
+export interface RangeProgression extends Emitter<number> {
+    /**
+     * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
+     *
+     * @param easer An easing function of the form `(progression: number) => number`
+     * @returns Listenable: emits eased progression values
+     */
+    ease(easer?: Easer | keyof typeof easers): RangeProgression;
+    /**
+     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
+     *
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     *
+     * @param from Value to interpolate from
+     * @param to Value to interpolate to
+     * @returns Listenable: emits interpolated values
+     */
+    tween(from: number, to: number): Emitter<number>;
+    /**
+     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
+     *
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     *
+     * #### String interpolation
+     * * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
+     * * Otherwise the `from` string is progressively replaced, left-to-right, with the `to` string
+     *
+     * eg
+     * ```ts
+     * range
+     *   .tween("0px 0px 0px #0000", "4px 4px 8px #0005")
+     *   .listen(s => element.style.textShadow = s);
+     * ```
+     *
+     * @param from Value to interpolate from
+     * @param to Value to interpolate to
+     * @returns Listenable: emits interpolated values
+     */
+    tween(from: string, to: string): Emitter<string>;
+    /**
+     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
+     *
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     *
+     * @param from Value to interpolate from
+     * @param to Value to interpolate to
+     * @returns Listenable: emits interpolated values
+     */
+    tween<T extends Blendable | number[]>(from: T, to: T): Emitter<T>;
+    /**
+     * 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: number): RangeProgression;
+    /**
+     * 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: number): RangeProgression;
+    /**
+     * 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?: number, max?: number): RangeProgression;
+    /**
+     * Creates a chainable progress emitter that maps incoming values to a repeating linear scale
+     * @param count Number of repetitions
+     */
+    repeat(count: number): RangeProgression;
+}

package/internal/range.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/internal/timeline.d.ts

@@ -0,0 +1,147 @@
+import { Easer, easers } from "./easing";
+import { TimelinePoint } from "./point";
+import { TimelineRange } from "./range";
+import { Tweenable } from "./tween";
+import { Widen } from "./utils";
+declare const EndAction: {
+    readonly pause: 0;
+    readonly continue: 1;
+    readonly wrap: 2;
+    readonly restart: 3;
+};
+/**
+ * Creates an autoplaying Timeline and returns a range from it
+ * @param duration
+ * @returns Object representing a range on a single-use, autoplaying Timeline
+ */
+export declare function animate(duration: number): TimelineRange;
+export declare class Timeline {
+    /**
+     * Multiplies the speed at which `play()` progresses through the Timeline
+     *
+     * A value of 2 would double progression speed while .25 would slow it to a quarter
+     */
+    timeScale: number;
+    get currentTime(): number;
+    set currentTime(v: number);
+    get isPlaying(): boolean;
+    get end(): TimelinePoint;
+    private _currentTime;
+    private _endPosition;
+    private interval;
+    private points;
+    private endAction;
+    private ranges;
+    private currentSortDirection;
+    private smoothSeeker;
+    private seeking;
+    readonly start: TimelinePoint;
+    private positionHandlers;
+    constructor();
+    /**
+     * @param autoplay Pass `true` to begin playing at (1000 x 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
+     * @param autoplayFps Specifies frames per second
+     */
+    constructor(autoplayFps: number);
+    /**
+     * @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
+     */
+    constructor(autoplay: boolean | number, endAction: {
+        wrapAt: number;
+    } | {
+        restartAt: number;
+    } | keyof typeof EndAction);
+    /**
+     * @deprecated "loop" endAction will be removed; use "restart" or `{restartAt: 0}` (disambiguates new looping strategies)
+     */
+    constructor(autoplay: boolean | number, endAction: "loop");
+    /**
+     * Defines a single point on the Timeline
+     *
+     * @param position
+     * @returns A point on the Timeline as specified
+     *
+     * Listenable: this point will emit a PointEvent whenever a `seek()` reaches or passes it
+     */
+    point(position: number): TimelinePoint;
+    /**
+     * 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
+     * @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;
+    /**
+     * Creates an observable range from position 0 to the Timeline's **current** final position
+     */
+    range(): TimelineRange;
+    private getWrappedPosition;
+    /**
+     * Seeks the Timeline to a specified position, triggering in order any point and range subscriptions between its current and new positions
+     * @param toPosition
+     */
+    seek(toPosition: number | TimelinePoint): void;
+    /**
+     * Smooth-seeks to a specified position
+     *
+     * Aborts and replaces any on-going 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
+     * @returns A promise, resolved when the smooth-seek process finishes
+     */
+    seek(toPosition: number | TimelinePoint, duration: number, easer?: Easer | keyof typeof easers): Promise<void>;
+    private seekDirect;
+    private seekPoints;
+    private seekRanges;
+    private sortEntries;
+    /**
+     * Starts progression of the Timeline from its current position at (1000 x this.timeScale) units per second
+     */
+    play(): void;
+    play(fps: number): void;
+    pause(): void;
+    /**
+     * Progresses the Timeline by 1 unit
+     * @param delta
+     * @deprecated Use timeline.position++
+     */
+    step(): void;
+    /**
+     * Progresses the Timeline by a given delta
+     * @param delta
+     * @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, end: TimelinePoint, // ease migration for tl.tween(0, tl.end, ...)
+    apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
+    private createChainingInterface;
+    /**
+     * @deprecated use `timeline.currentTime`
+     */
+    get position(): number;
+}
+export interface ChainingInterface {
+    thenTween(duration: number, apply: (v: number) => void, from?: number, to?: number, easer?: Easer): ChainingInterface;
+    then(action: () => void): ChainingInterface;
+    thenWait(duration: number): ChainingInterface;
+    readonly end: TimelinePoint;
+}
+export {};