@xtia/timeline 1.0.1 → 1.0.3

package/internal/easing.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.easers = void 0;
+const overshoot = 1.70158;
+exports.easers = {
+    linear: (x) => x,
+    easeIn: (x) => x * x,
+    easeIn4: (x) => Math.pow(x, 4),
+    easeOut: (x) => 1 - Math.pow((1 - x), 2),
+    easeOut4: (x) => 1 - Math.pow((1 - x), 4),
+    circleIn: (x) => 1 - Math.sqrt(1 - Math.pow(x, 2)),
+    circleIn4: (x) => 1 - Math.sqrt(1 - Math.pow(x, 4)),
+    circleOut: (x) => Math.sqrt(1 - Math.pow((1 - x), 2)),
+    circleOut4: (x) => Math.sqrt(1 - Math.pow((1 - x), 4)),
+    easeInOut: (x) => -Math.cos(x * Math.PI) / 2 + .5,
+    elastic: (x) => 1 - Math.cos(4 * Math.PI * x) * (1 - x),
+    overshootIn: (x) => --x * x * ((overshoot + 1) * x + overshoot) + 1,
+    sine: (x) => (Math.sin(2 * Math.PI * x) + 1) / 2,
+    invert: (x) => 1 - x,
+    bounce: (x) => {
+        if (x < 4 / 11.0) {
+            return (121 * x * x) / 16.0;
+        }
+        else if (x < 8 / 11.0) {
+            return (363 / 40.0 * x * x) - (99 / 10.0 * x) + 17 / 5.0;
+        }
+        else if (x < 9 / 10.0) {
+            return (4356 / 361.0 * x * x) - (35442 / 1805.0 * x) + 16061 / 1805.0;
+        }
+        else {
+            return (54 / 5.0 * x * x) - (513 / 25.0 * x) + 268 / 25.0;
+        }
+    },
+    noise: (x) => x == 0 ? 0 : (x >= 1 ? 1 : Math.random()),
+    pingpong: (x) => x < .5 ? x * 2 : 1 - (x - .5) * 2,
+};

package/internal/emitters.d.ts

@@ -0,0 +1,153 @@
+import { Easer, easers } from "./easing";
+import { Blendable } from "./tween";
+/** @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 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;
+    /**
+     * Creates a chainable progress 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: (value: number) => void): RangeProgression;
+    /**
+     * 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: (value: number) => boolean): RangeProgression;
+    /**
+     * 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
+     */
+    noRepeat(): RangeProgression;
+}
+export {};

package/internal/emitters.js

@@ -0,0 +1,117 @@
+"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) => onListen((value) => {
+            handler(value);
+        }),
+        map: (mapFunc) => createEmitter(handler => onListen((value) => {
+            handler(mapFunc(value));
+        })),
+        filter: (filterFunc) => createEmitter(handler => onListen((value) => {
+            if (filterFunc(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 onListen(filteredHandler);
+            });
+        },
+        tap: (cb) => createEmitter(createTapListener(cb, onListen)),
+    }).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);
+            }));
+        },
+        tap: (cb) => createProgressEmitter(createTapListener(cb, onListen)),
+        filter: (filterFunc) => createProgressEmitter(handler => onListen((value) => {
+            if (filterFunc(value))
+                handler(value);
+        })),
+        noRepeat: () => {
+            let previous = null;
+            return createProgressEmitter(handler => {
+                return onListen((value) => {
+                    if (!previous || (previous.value !== value)) {
+                        handler(value);
+                        previous = { value };
+                    }
+                });
+            });
+        },
+    }).map(([key, value]) => [
+        key,
+        { value }
+    ]));
+    return createEmitter(onListen, Object.create(api, propertyDescriptor));
+}
+function createTapListener(callback, parentOnListen) {
+    const listeners = [];
+    let parentUnsubscribe = null;
+    const tapOnListen = (handler) => {
+        listeners.push(handler);
+        if (listeners.length === 1) {
+            parentUnsubscribe = parentOnListen(value => {
+                callback(value);
+                listeners.slice().forEach(fn => fn(value));
+            });
+        }
+        return () => {
+            const idx = listeners.indexOf(handler);
+            listeners.splice(idx, 1);
+            if (listeners.length === 0 && parentUnsubscribe) {
+                parentUnsubscribe();
+                parentUnsubscribe = null;
+            }
+        };
+    };
+    return tapOnListen;
+}

package/internal/point.d.ts

@@ -0,0 +1,29 @@
+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
+     * @returns Listenable: emits normalised (0..1) range progression
+     */
+    range(duration: number): TimelineRange;
+    /**
+     * 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: number | TimelinePoint): TimelineRange;
+    /**
+     * 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: 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,50 @@
+import { Easer, easers } from "./easing";
+import { RangeProgression } from "./emitters";
+import { TimelinePoint } from "./point";
+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
+     * @returns Tuple of two ranges
+     */
+    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
+     * @returns Array(count) of points
+     */
+    spread(count: number): TimelinePoint[];
+    /**
+     * Progresses the Timeline across the range
+     * @param easer
+     */
+    play(easer?: Easer | keyof typeof easers): 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;
+    /**
+     * Checks if a point is within this range
+     * @param point The point to check
+     * @returns true if the provided point is within the range
+     */
+    contains(point: TimelinePoint): 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

@@ -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 {};