@xtia/timeline 0.2.4

package/index.d.ts

@@ -0,0 +1,219 @@
+type ApplyTweenFunc = (v: number) => void;
+type EaseFunc = (v: number) => number;
+interface TweenData {
+    time: number;
+    duration: number;
+    startValue: NumberOrNumberFunction;
+    endValue: NumberOrNumberFunction;
+    apply: ApplyTweenFunc;
+    ease?: EaseFunc;
+}
+type NumberOrNumberFunction = number | (() => number);
+type EndAction = "continue" | "pause" | "loop";
+interface TimelineChain {
+    /**
+     * Add a callback to run at the end of the previous item in a chain, offset by the Timeline's current position
+     * @param time Offset, time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time.
+     * @param revert Called when a backward seek passes this event's time. Default is no action
+     */
+    then(apply: () => void, revert?: () => void): TimelineChain;
+    /**
+     * Add a callback to run at the end of the previous item in a chain, offset by the Timeline's current position
+     * @param time Offset, time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time.
+     * @param applyOnReverse Pass true to call `apply` regardless of direction of traversal, or false to specify no reversion action
+     */
+    then(apply: () => void, applyOnReverse: boolean): TimelineChain;
+    /**
+     * Add a tween to this Timeline, starting at the end of the previous item in a chain
+     * @param duration Duration of tween
+     * @param apply Function called per frame, passed a value between `from` and `to` (with possible overshoot depending on easer)
+     * @param from Initial (pre-start) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 0)
+     * @param to Final (post-end) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 1)
+     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
+     */
+    thenTween(duration: number, apply: ApplyTweenFunc, from?: NumberOrNumberFunction, to?: NumberOrNumberFunction, ease?: EaseFunc): TimelineChain;
+    /**
+     * Ensures end time extends to (at least) the specified time past the end of the previous item in a chain
+     * @param duration
+     */
+    thenWait(duration: number): TimelineChain;
+}
+export declare class Timeline {
+    private tweens;
+    private events;
+    private _position;
+    private _end;
+    private seeking;
+    private playInterval;
+    private currentSortDirection;
+    private smoothSeekTimeline?;
+    pauseAtEnd: boolean;
+    /**
+     * @property Sets a time at which to rewind back to 0. If `true`, looping will occur after the final tween or event.
+     */
+    loop: number | boolean;
+    /**
+     * @property Time delta multiplier to change speed. Affects `step()` and `play()`
+     */
+    timeScale: number;
+    /**
+     * @param autoPlay Pass true to autoplay at 60 FPS
+     * @param atEnd Choose what happens when the Timeline seeks beyond its final frame. Default is "pause"
+     */
+    constructor(autoPlay?: boolean, atEnd?: EndAction);
+    /**
+     * @param fps Pass a number, as frames per second, to autoplay at the specified frame rate.
+     * @param atEnd Choose what happens when the Timeline seeks beyond its final frame. Default is "pause"
+     */
+    constructor(fps?: number | boolean, atEnd?: EndAction);
+    get position(): number;
+    /**
+     * @property The final position at which an event or tween exists on this Timeline
+     */
+    get end(): number;
+    /**
+     * Add a tween to this Timeline
+     * @param startTime Position at which tween starts
+     * @param duration Duration of tween
+     * @param apply Function called per frame, passed a value between `from` and `to` (with possible overshoot depending on easer)
+     * @param from Initial (pre-start) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 0)
+     * @param to Final (post-end) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 1)
+     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
+     * @returns A chaining interface for the time at which the tween ends
+     */
+    tween(startTime: number, duration: number, apply: ApplyTweenFunc, from?: NumberOrNumberFunction, to?: NumberOrNumberFunction, ease?: EaseFunc): TimelineChain;
+    /**
+     * Add a tween to this Timeline
+     * @param tween Object describing the tween
+     * @returns A chaining interface for the time at which the tween ends
+     */
+    tween(tween: TweenData): TimelineChain;
+    /**
+     * Add a callback to run at a specified time
+     * @param time Time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time
+     * @param applyOnReverse Called when a backward seek passes this event's time. Default is no action
+     * @returns A chaining interface for the specified time
+     */
+    at(time: number, apply: () => void, applyOnReverse?: () => void): TimelineChain;
+    /**
+     * Add a callback to run at a specified time
+     * @param time Time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time
+     * @param applyOnReverse Pass true to call `apply` regardless of direction of traversal, or false to specify no reversion action
+     * @returns A chaining interface for the specified time
+     */
+    at(time: number, apply: () => void, applyOnReverse: boolean): TimelineChain;
+    /**
+     * Ensures end time extends to (at least) the specified time
+     * @param time
+     * @returns A chaining interface for the specified time
+     */
+    at(time: number): TimelineChain;
+    /**
+     * Add a callback to run at a specified time
+     * @param time Time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time
+     * @param applyOnReverse Called when a backward seek targets or passes this event's time
+     * @returns A chaining interface for the specified time
+     */
+    at(time: number, apply: false, applyOnReverse: () => void): TimelineChain;
+    /**
+     * Add a callback to run at a specified time, offset by the Timeline's current position
+     * @param time Offset, time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time
+     * @param revert Called when a backward seek passes this event's time. Default is no action
+     * @returns A chaining interface for the specified time
+     */
+    in(time: number, apply?: () => void, revert?: () => void): TimelineChain;
+    /**
+     * Add a callback to run at a specified time, offset by the Timeline's current position (plus, if playing, time since the last update)
+     * @param time Offset, time at which this event will be triggered
+     * @param apply Called when a forward seek targets or passes this event's time
+     * @param applyOnReverse Pass true to call `apply` regardless of direction of traversal, or false to specify no reversion action
+     * @returns A chaining interface for the specified time
+     */
+    in(time: number, apply: () => void, applyOnReverse: boolean): TimelineChain;
+    /**
+     * Set the Timeline's position, applying intersecting tweens and events
+     * Ignores the `loop` property and sets position as specified
+     * @param time The new position
+     * @param smooth Milliseconds over which to smoothly seek
+     */
+    seek(time: number, smooth: number): void;
+    /**
+     * Set the Timeline's position, applying intersecting tweens and events
+     * Ignores the `loop` property and sets position as specified
+     * @param time The new position
+     * @param smooth Pass true to smooth-seek over 400ms
+     */
+    seek(time: number, smooth?: boolean): void;
+    private _seek;
+    /**
+     * Moves the timeline forwards (or backwards given negative delta) by a specified amount, applying intersecting tweens and events
+     * Honours `loop` ending action
+     * @param delta Amount of time to move forward by. This will be affected by the `timeScale` property
+     */
+    step(delta?: number, smooth?: number | boolean): void;
+    private lastFrameTime;
+    /**
+     * Begins moving forward in time from current `position` at a rate of 1000 x `timeScale` units per second
+     * If the timeline is already playing, it will stop and resume at the specified `fps`
+     * Honours `loop` and `pause` ending actions
+     * @param fps Frames per second
+     */
+    play(fps?: number): void;
+    /**
+     * Pauses automatic progression started via `play()`
+     */
+    pause(): void;
+    get isPlaying(): boolean;
+    /**
+     * Creates a Timeline as a tween
+     * * Transposes the inner Timeline's `0` -> `innerDuration` to the parent Timeline's `startTime` -> `outerDuration`
+     * * Experimental - this functionality may change in future versions
+     * @param startTime Position on the parent Timeline at which the inner Timeline will start seeking
+     * @param outerDuration Length of time occupied on the parent Timeline by the inner Timeline
+     * @param innerDuration Duration of the inner Timeline to transpose to `startTime` -> `outerDuration`
+     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
+     * @returns
+     */
+    createInnerTimeline(startTime: number, outerDuration: number, innerDuration?: number, ease?: EaseFunc): Timeline;
+    private createChainInterface;
+    private seekTweens;
+    /**
+     * Initialises and starts a Timeline using chained calls to specify tweens and events
+     * @param looping
+     * @returns
+     */
+    static start(looping?: boolean): TimelineChain;
+}
+export declare const easers: {
+    linear: (x: number) => number;
+    easeIn: (x: number) => number;
+    easeIn4: (x: number) => number;
+    easeOut: (x: number) => number;
+    easeOut4: (x: number) => number;
+    circleIn: (x: number) => number;
+    circleIn4: (x: number) => number;
+    circleOut: (x: number) => number;
+    circleOut4: (x: number) => number;
+    easeInOut: (x: number) => number;
+    elastic: (x: number) => number;
+    overshootIn: (x: number) => number;
+    bounce: (x: number) => number;
+    noise: (x: number) => number;
+    step2: (x: number) => 0 | 1 | 0.5;
+    step3: (x: number) => 0 | 1 | 0.333 | 0.667;
+    pingpong: (x: number) => number;
+};
+export declare const dynamicEasers: {
+    average: (easers: EaseFunc[]) => (x: number) => number;
+    blend: (fromEaser: EaseFunc, toEaser: EaseFunc, amount: number) => (x: number) => number;
+    sine: (freq?: number) => (x: number) => number;
+    multiply: (easer: EaseFunc, mul: number) => (x: number) => number;
+    combine: (easers: EaseFunc[]) => (x: number) => number;
+};
+export {};

package/index.js

@@ -0,0 +1,316 @@
+"use strict";
+// PRE-PRODUCTION / ALPHA 0.2.4
+// Copyright, 2024, Aleta Lovelace
+// Licensed under CC BY-SA 4.0 <http://creativecommons.org/licenses/by-sa/4.0/>
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dynamicEasers = exports.easers = exports.Timeline = void 0;
+const blendNumbers = (from, to, progress) => from + progress * (to - from);
+const applyTween = (tween, position) => {
+    let progress = (position - tween.time) / tween.duration;
+    const startValue = Number(typeof tween.startValue == "function" ? tween.startValue() : tween.startValue);
+    const endValue = Number(typeof tween.endValue == "function" ? tween.endValue() : tween.endValue);
+    if (progress <= 0) {
+        tween.apply(startValue);
+    }
+    else if (progress >= 1) {
+        tween.apply(endValue);
+    }
+    else {
+        if (tween.ease)
+            progress = tween.ease(progress);
+        tween.apply(blendNumbers(startValue, endValue, progress));
+    }
+};
+const sortEvents = (a, b) => {
+    return a.time - b.time;
+};
+const sortTweens = (a, b) => {
+    return (a.time + a.duration) - (b.time + b.duration);
+};
+const sortReverse = (a, b) => {
+    if (a.time == b.time)
+        return 1;
+    return b.time - a.time;
+};
+const copyObject = (source, properties) => Object.fromEntries(properties.map(p => [p, source[p]]));
+class Timeline {
+    tweens = [];
+    events = [];
+    _position = 0;
+    _end = 0;
+    seeking = false;
+    playInterval;
+    currentSortDirection = 0;
+    smoothSeekTimeline;
+    pauseAtEnd;
+    /**
+     * @property Sets a time at which to rewind back to 0. If `true`, looping will occur after the final tween or event.
+     */
+    loop = false;
+    /**
+     * @property Time delta multiplier to change speed. Affects `step()` and `play()`
+     */
+    timeScale = 1;
+    constructor(autoPlay = false, atEnd = "pause") {
+        if (atEnd == "pause") {
+            this.pauseAtEnd = true;
+        }
+        else if (atEnd == "loop") {
+            this.loop = true;
+        }
+        if (autoPlay !== false)
+            this.play(autoPlay === true ? 60 : autoPlay);
+    }
+    get position() { return this._position; }
+    /**
+     * @property The final position at which an event or tween exists on this Timeline
+     */
+    get end() { return this._end; }
+    tween(startOrTween, duration, apply, from = 0, to = 1, ease) {
+        const tweenRecord = typeof startOrTween == "object" ? copyObject(startOrTween, ["apply", "duration", "ease", "endValue", "time", "startValue"]) : {
+            time: startOrTween,
+            duration,
+            startValue: from,
+            endValue: to,
+            apply,
+            ease,
+        };
+        this.tweens.push(tweenRecord);
+        const endTime = tweenRecord.time + tweenRecord.duration;
+        if (endTime > this._end)
+            this._end = endTime;
+        this.currentSortDirection = 0;
+        this.seek(this.position);
+        return this.createChainInterface(endTime);
+    }
+    at(time, apply = false, revert = false) {
+        if (time > this._end)
+            this._end = time;
+        if (apply || revert) {
+            this.events.push({ apply, revert: revert === true ? apply : revert, time });
+            this.currentSortDirection = 0;
+            if (time <= this._position && apply)
+                apply();
+        }
+        return this.createChainInterface(time);
+    }
+    in(time, apply, revert = false) {
+        // todo, subtract lastFrameTime difference if playing? [/ done?]
+        // todo, test this
+        if (this.isPlaying)
+            time -= (new Date().getTime() - this.lastFrameTime) * this.timeScale;
+        return this.at(time + this._position, apply, revert);
+    }
+    seek(time, smooth = false) {
+        if (this.seeking)
+            throw new Error("Seeking is not allowed within timeline events");
+        const interrupting = this.smoothSeekTimeline;
+        if (interrupting) {
+            interrupting.pause();
+            this.smoothSeekTimeline = undefined;
+        }
+        if (smooth === false)
+            return this._seek(time);
+        if (smooth === true)
+            smooth = 400;
+        this.smoothSeekTimeline = new Timeline(true);
+        this.smoothSeekTimeline.tween(0, smooth, v => this._seek(v), this._position, time, interrupting ? exports.easers.easeOut : exports.easers.easeInOut);
+    }
+    _seek(time) {
+        if (time === this._position)
+            return;
+        const fromPosition = this._position;
+        const reversing = time < fromPosition;
+        const requiredSortDirection = reversing ? -1 : 1;
+        if (this.currentSortDirection != requiredSortDirection) {
+            this.events.sort(reversing ? sortReverse : sortEvents);
+            this.tweens.sort(reversing ? sortReverse : sortTweens);
+            this.currentSortDirection = requiredSortDirection;
+        }
+        this.events.forEach(ev => {
+            const eventOverlaps = reversing
+                ? (ev.time <= fromPosition) && (ev.time > time)
+                : (ev.time > fromPosition) && (ev.time <= time);
+            if (!eventOverlaps)
+                return;
+            // timeline.position and tween states reflect the event's exact position during its handler
+            this.seekTweens(ev.time);
+            this._position = ev.time;
+            if (reversing) {
+                if (ev.revert)
+                    ev.revert(); // ev.revert?.() produced a 'false not callable' error :/
+            }
+            else {
+                if (ev.apply)
+                    ev.apply();
+            }
+        });
+        this.seekTweens(time);
+        this._position = time;
+        this.seeking = false;
+    }
+    /**
+     * Moves the timeline forwards (or backwards given negative delta) by a specified amount, applying intersecting tweens and events
+     * Honours `loop` ending action
+     * @param delta Amount of time to move forward by. This will be affected by the `timeScale` property
+     */
+    step(delta = 1, smooth = false) {
+        this.lastFrameTime = new Date().getTime();
+        const newPosition = this._position + delta * this.timeScale;
+        const loopAt = this.loop === true ? this._end : this.loop;
+        if (loopAt === false || newPosition < loopAt) {
+            this.seek(newPosition, smooth);
+            return;
+        }
+        const loopOvershoot = newPosition - loopAt;
+        this.seek(loopAt);
+        this.seek(0);
+        this.step(loopOvershoot);
+    }
+    lastFrameTime = new Date().getTime();
+    /**
+     * Begins moving forward in time from current `position` at a rate of 1000 x `timeScale` units per second
+     * If the timeline is already playing, it will stop and resume at the specified `fps`
+     * Honours `loop` and `pause` ending actions
+     * @param fps Frames per second
+     */
+    play(fps = 60) {
+        if (this.playInterval !== null)
+            this.pause();
+        this.lastFrameTime = new Date().getTime();
+        this.playInterval = setInterval(() => {
+            this.step(new Date().getTime() - this.lastFrameTime);
+            if (this.pauseAtEnd && this._position >= this._end) {
+                this.pause();
+                this._position = this._end;
+            }
+        }, 1000 / fps);
+    }
+    /**
+     * Pauses automatic progression started via `play()`
+     */
+    pause() {
+        if (this.playInterval !== null) {
+            clearInterval(this.playInterval);
+            this.playInterval = null;
+        }
+    }
+    get isPlaying() {
+        return this.playInterval !== null;
+    }
+    /**
+     * Creates a Timeline as a tween
+     * * Transposes the inner Timeline's `0` -> `innerDuration` to the parent Timeline's `startTime` -> `outerDuration`
+     * * Experimental - this functionality may change in future versions
+     * @param startTime Position on the parent Timeline at which the inner Timeline will start seeking
+     * @param outerDuration Length of time occupied on the parent Timeline by the inner Timeline
+     * @param innerDuration Duration of the inner Timeline to transpose to `startTime` -> `outerDuration`
+     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
+     * @returns
+     */
+    createInnerTimeline(startTime, outerDuration, innerDuration = 1, ease) {
+        const innerTimeline = new Timeline(false);
+        this.tween(startTime, outerDuration, (v) => innerTimeline.seek(v), 0, innerDuration, ease);
+        return innerTimeline;
+    }
+    createChainInterface(timeOffset) {
+        return {
+            then: (apply, revert) => {
+                return this.at(timeOffset, apply, revert);
+            },
+            thenTween: (duration, apply, from = 0, to = 0, ease) => {
+                return this.tween(timeOffset, duration, apply, from, to, ease);
+            },
+            thenWait: (duration) => {
+                return this.at(timeOffset + duration);
+            },
+        };
+    }
+    seekTweens(toTime) {
+        const fromTime = this._position;
+        this.tweens.forEach((tween) => {
+            const { duration, time: start } = tween;
+            const end = start + duration;
+            // filter tweens that overlap seeked range
+            if (Math.min(start, end) <= Math.max(toTime, fromTime)
+                && Math.min(toTime, fromTime) <= Math.max(start, end)) {
+                applyTween(tween, toTime);
+            }
+        });
+    }
+    /**
+     * Initialises and starts a Timeline using chained calls to specify tweens and events
+     * @param looping
+     * @returns
+     */
+    static start(looping = false) {
+        const tl = new Timeline(true, looping ? "loop" : "pause");
+        tl.loop = looping;
+        return tl.at(0);
+    }
+}
+exports.Timeline = Timeline;
+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,
+    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()),
+    step2: (x) => {
+        if (x < 0.333)
+            return 0;
+        if (x < 0.667)
+            return 0.5;
+        return 1;
+    },
+    step3: (x) => {
+        if (x < .25)
+            return 0;
+        if (x < .5)
+            return .333;
+        if (x < .75)
+            return .667;
+        return 1;
+    },
+    pingpong: (x) => x < .5 ? x * 2 : 1 - (x - .5) * 2,
+};
+exports.dynamicEasers = {
+    average: (easers) => (x) => {
+        return easers.reduce((n, easer) => n + easer(x), 0) / easers.length;
+    },
+    blend: (fromEaser, toEaser, amount) => (x) => {
+        return blendNumbers(fromEaser(x), toEaser(x), amount);
+    },
+    sine: (freq = 2) => (x) => Math.sin(x * freq * Math.PI * 2),
+    multiply: (easer, mul) => (x) => {
+        for (let i = 0; i < mul; i++)
+            x = easer(x);
+        return x;
+    },
+    combine: (easers) => (x) => {
+        return easers.reduce((n, easer) => easer(n), x);
+    },
+};

package/package.json

@@ -0,0 +1,14 @@
+{
+    "name": "@xtia/timeline",
+    "version": "0.2.4",
+    "description": "Temporal state coordination",
+    "main": "index.ts",
+    "keywords": [
+      "timeline",
+      "animation",
+      "tweening"
+    ],
+    "author": "Aleta Lovelace",
+    "license": "MIT"
+  }
+