@xtia/timeline 1.0.0 → 1.0.2

package/internal/timeline.js

@@ -0,0 +1,414 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Timeline = void 0;
+exports.animate = animate;
+const emitters_1 = require("./emitters");
+const utils_1 = require("./utils");
+const default_fps = 60;
+const EndAction = {
+    pause: 0,
+    continue: 1,
+    wrap: 2,
+    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
+ */
+function animate(duration) {
+    return new Timeline(true).range(0, duration);
+}
+class Timeline {
+    get currentTime() { return this._currentTime; }
+    set currentTime(v) {
+        this.seek(v);
+    }
+    get isPlaying() {
+        return this.interval !== null;
+    }
+    get end() {
+        return this.point(this._endPosition);
+    }
+    constructor(autoplay = false, endAction = "pause") {
+        /**
+         * 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
+         */
+        this.timeScale = 1;
+        this._currentTime = 0;
+        this._endPosition = 0;
+        this.interval = null;
+        this.points = [];
+        this.ranges = [];
+        this.currentSortDirection = 0;
+        this.smoothSeeker = null;
+        this.seeking = false;
+        this.start = this.point(0);
+        this.positionHandlers = [];
+        if (endAction == "loop")
+            endAction = "restart";
+        if (autoplay !== false) {
+            this.play(typeof autoplay == "number" ? autoplay : default_fps);
+        }
+        if (typeof endAction == "object"
+            && "restartAt" in endAction) {
+            this.endAction = {
+                type: EndAction.restart,
+                at: this.point(endAction.restartAt),
+            };
+        }
+        else if (typeof endAction == "object"
+            && "wrapAt" in endAction) {
+            this.endAction = {
+                type: EndAction.wrap,
+                at: this.point(endAction.wrapAt),
+            };
+        }
+        else
+            this.endAction = {
+                type: EndAction[endAction],
+                at: this.point(0),
+            };
+    }
+    /**
+     * 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) {
+        if (position > this._endPosition)
+            this._endPosition = position;
+        const handlers = [];
+        const data = {
+            handlers,
+            position,
+        };
+        return (0, emitters_1.createEmitter)(handler => {
+            if (this.seeking)
+                throw new Error("Can't add a listener while seeking");
+            // we're adding and removing points and ranges to the internal registry according to whether any subscriptions are active, to allow obsolete points and ranges to be garbage-collected
+            if (handlers.length == 0) {
+                this.points.push(data);
+                this.currentSortDirection = 0;
+            }
+            handlers.push(handler);
+            return () => {
+                const idx = handlers.indexOf(handler);
+                if (idx === -1)
+                    throw new Error("Internal error: attempting to remove a non-present handler");
+                handlers.splice(idx, 1);
+                if (handlers.length == 0) {
+                    const idx = this.points.indexOf(data);
+                    this.points.splice(idx, 1);
+                }
+            };
+        }, {
+            delta: t => this.point(position + t),
+            range: duration => this.range(position, duration),
+            to: target => {
+                const targetPosition = typeof target == "number"
+                    ? target
+                    : target.position;
+                return this.range(position, targetPosition - position);
+            },
+            position,
+        });
+    }
+    range(start = 0, optionalDuration) {
+        const startPoint = typeof start == "number"
+            ? this.point(start)
+            : start;
+        const startPosition = startPoint.position;
+        const duration = optionalDuration ?? this._endPosition - startPosition;
+        const endPosition = startPosition + duration;
+        if (endPosition > this._endPosition)
+            this._endPosition = endPosition;
+        const handlers = [];
+        const range = {
+            position: startPosition,
+            duration,
+            handlers,
+        };
+        const addHandler = (handler) => {
+            if (this.seeking)
+                throw new Error("Can't add a listener while seeking");
+            if (handlers.length == 0) {
+                this.ranges.push(range);
+                this.currentSortDirection = 0;
+            }
+            handlers.push(handler);
+            return () => {
+                const idx = handlers.indexOf(handler);
+                if (idx === -1)
+                    throw new Error("Internal error: attempting to remove a non-present handler");
+                handlers.splice(idx, 1);
+                if (handlers.length == 0) {
+                    const idx = this.ranges.indexOf(range);
+                    this.ranges.splice(idx, 1);
+                }
+            };
+        };
+        return (0, emitters_1.createProgressEmitter)(addHandler, {
+            duration,
+            start: this.point(startPosition),
+            end: this.point(startPosition + duration),
+            bisect: (position = duration / 2) => {
+                return [
+                    this.range(startPosition, position),
+                    this.range(startPosition + position, duration - position),
+                ];
+            },
+            spread: (count) => {
+                const delta = duration / (count + 1);
+                return [
+                    ...Array(count).fill(0).map((_, idx) => this.point(idx * delta + startPosition + delta))
+                ];
+            },
+            play: (easer) => {
+                this.pause();
+                this.currentTime = startPosition;
+                return this.seek(startPosition + duration, duration, easer);
+            },
+            grow: (delta, anchor = 0) => {
+                const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
+                const leftDelta = -delta * (1 - clampedAnchor);
+                const rightDelta = delta * clampedAnchor;
+                const newStart = startPosition + leftDelta;
+                const newEnd = endPosition + rightDelta;
+                if (newEnd < newStart) {
+                    const mid = (newStart + newEnd) / 2;
+                    return this.range(mid, 0);
+                }
+                return this.range(newStart, newEnd - newStart);
+            },
+            scale: (factor, anchor = 0.5) => {
+                if (factor <= 0) {
+                    throw new RangeError('scale factor must be > 0');
+                }
+                const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
+                const oldLen = endPosition - startPosition;
+                const pivot = startPosition + oldLen * clampedAnchor;
+                const newStart = pivot - (pivot - startPosition) * factor;
+                const newEnd = pivot + (endPosition - pivot) * factor;
+                if (newEnd < newStart) {
+                    const mid = (newStart + newEnd) / 2;
+                    return this.range(mid, 0);
+                }
+                return this.range(newStart, newEnd - newStart);
+            },
+        });
+    }
+    getWrappedPosition(n) {
+        if (this.endAction.type !== EndAction.wrap)
+            return n;
+        const wrapAt = this.endAction.at?.position ?? 0;
+        if (wrapAt == 0)
+            return n % this._endPosition;
+        if (n <= this._endPosition)
+            return n;
+        const loopStart = wrapAt;
+        const segment = this._endPosition - loopStart;
+        if (segment <= 0)
+            return Math.min(n, this._endPosition);
+        const overflow = n - this._endPosition;
+        const remainder = overflow % segment;
+        return loopStart + remainder;
+    }
+    seek(to, duration = 0, easer) {
+        const toPosition = typeof to == "number"
+            ? to
+            : to.position;
+        if (this.seeking) {
+            throw new Error("Can't seek while seeking");
+        }
+        if (this.smoothSeeker !== null) {
+            this.smoothSeeker.pause();
+            // ensure any awaits are resolved for the previous seek?
+            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker = null;
+        }
+        if (duration === 0) {
+            this.seekDirect(toPosition);
+            return;
+        }
+        const seeker = new Timeline(true);
+        this.smoothSeeker = seeker;
+        seeker.range(0, duration).ease(easer).tween(this.currentTime, toPosition).listen(v => this.seekDirect(v));
+        return new Promise(r => seeker.end.listen(() => r()));
+    }
+    seekDirect(toPosition) {
+        const fromPosition = this._currentTime;
+        if (toPosition === fromPosition)
+            return;
+        const loopingTo = this.getWrappedPosition(toPosition);
+        const loopingFrom = this.getWrappedPosition(fromPosition);
+        let virtualFrom = loopingFrom;
+        let virtualTo = loopingTo;
+        const direction = toPosition > fromPosition ? 1 : -1;
+        if (direction !== this.currentSortDirection)
+            this.sortEntries(direction);
+        if (direction === 1 && loopingTo < loopingFrom) {
+            virtualFrom = loopingFrom - this._endPosition;
+        }
+        else if (direction === -1 && loopingTo > loopingFrom) {
+            virtualFrom = loopingFrom + this._endPosition;
+        }
+        this.seeking = true;
+        this._currentTime = virtualFrom;
+        try {
+            this.seekPoints(virtualTo);
+            this.seekRanges(virtualTo);
+        }
+        catch (e) {
+            this.pause();
+            throw e;
+        }
+        this._currentTime = toPosition;
+        this.positionHandlers.slice().forEach(h => h(toPosition));
+        this.seeking = false;
+    }
+    seekPoints(to) {
+        const from = this._currentTime;
+        const direction = to > from ? 1 : -1;
+        const pointsBetween = this.points.filter(direction > 0
+            ? p => p.position > from && p.position <= to
+            : p => p.position <= from && p.position > to);
+        pointsBetween.slice().forEach(p => {
+            this.seekRanges(p.position);
+            this._currentTime = p.position;
+            const eventData = {
+                direction
+            };
+            p.handlers.slice().forEach(h => h(eventData));
+        });
+    }
+    seekRanges(to) {
+        const fromTime = this._currentTime;
+        this.ranges.slice().forEach((range) => {
+            const { duration, position } = range;
+            const end = position + duration;
+            // filter ranges that overlap seeked range
+            if (Math.min(position, end) <= Math.max(to, fromTime)
+                && Math.min(to, fromTime) <= Math.max(position, end)) {
+                let progress = (0, utils_1.clamp)((to - range.position) / range.duration, 0, 1);
+                range.handlers.slice().forEach(h => h(progress));
+            }
+        });
+    }
+    sortEntries(direction) {
+        this.currentSortDirection = direction;
+        this.points.sort(direction == 1
+            ? sortEvents
+            : sortReverse);
+        this.ranges.sort(direction == 1
+            ? sortTweens
+            : sortReverse);
+    }
+    play(fps = default_fps) {
+        if (this.interval !== null)
+            this.pause();
+        let previousTime = Date.now();
+        this.interval = setInterval(() => {
+            const newTime = Date.now();
+            const elapsed = newTime - previousTime;
+            previousTime = newTime;
+            let delta = elapsed * this.timeScale;
+            if (this._currentTime + delta <= this._endPosition) {
+                this.currentTime += delta;
+                return;
+            }
+            // overshot; perform endAction			
+            if (this.endAction.type == EndAction.restart) {
+                const loopRange = this.endAction.at.to(this._endPosition);
+                const loopLen = loopRange.duration;
+                if (loopLen <= 0) {
+                    const target = Math.min(this._currentTime + delta, this._endPosition);
+                    this.seek(target);
+                    return;
+                }
+                while (delta > 0) {
+                    const distanceToEnd = this._endPosition - this._currentTime;
+                    if (delta < distanceToEnd) {
+                        this.seek(this._currentTime + delta);
+                        return;
+                    }
+                    this.seek(this._endPosition);
+                    delta -= distanceToEnd;
+                    this.seek(this.endAction.at);
+                }
+                return;
+            }
+            if (this.endAction.type == EndAction.pause) {
+                this.seek(this._endPosition);
+                this.pause();
+                return;
+            }
+            this.currentTime += delta;
+        }, 1000 / fps);
+    }
+    pause() {
+        if (this.interval === null)
+            return;
+        clearInterval(this.interval);
+        this.interval = null;
+    }
+    step(delta = 1) {
+        this.currentTime += delta * this.timeScale;
+    }
+    tween(start, durationOrToPoint, apply, from, to, easer) {
+        const startPosition = typeof start == "number"
+            ? start
+            : start.position;
+        const duration = typeof durationOrToPoint == "number"
+            ? durationOrToPoint
+            : (durationOrToPoint.position - startPosition);
+        this.range(startPosition, duration).ease(easer).tween(from, to).listen(apply);
+        return this.createChainingInterface(startPosition + duration);
+    }
+    at(position, action, reverse) {
+        const point = typeof position == "number" ? this.point(position) : position;
+        if (reverse === true)
+            reverse = action;
+        if (action)
+            point.listen(reverse
+                ? (event => event.direction < 0 ? reverse() : action)
+                : action);
+        return this.createChainingInterface(point.position);
+    }
+    createChainingInterface(position) {
+        return {
+            thenTween: (duration, apply, from = 0, to = 1, easer) => {
+                return this.tween(position, duration, apply, from, to, easer);
+            },
+            then: (action) => this.at(position, action),
+            thenWait: (delay) => {
+                this.point(position + delay);
+                return this.createChainingInterface(position + delay);
+            },
+            end: this.point(position),
+        };
+    }
+    /**
+     * @deprecated use `timeline.currentTime`
+     */
+    get position() {
+        return this._currentTime;
+    }
+}
+exports.Timeline = Timeline;
+const sortEvents = (a, b) => {
+    return a.position - b.position;
+};
+const sortTweens = (a, b) => {
+    return (a.position + a.duration) - (b.position + b.duration);
+};
+const sortReverse = (a, b) => {
+    if (a.position == b.position)
+        return 1;
+    return b.position - a.position;
+};

package/internal/tween.d.ts

@@ -0,0 +1,8 @@
+/** @internal */
+export type Tweenable = number | number[] | string | Blendable;
+/** @internal */
+export interface Blendable {
+    blend(target: this, progress: number): this;
+}
+/** @internal */
+export declare function tweenValue<T extends Tweenable>(from: T, to: T, progress: number): T;

package/internal/tween.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tweenValue = tweenValue;
+const utils_1 = require("./utils");
+/** @internal */
+function tweenValue(from, to, progress) {
+    if (Array.isArray(from)) {
+        const toArr = to;
+        if (from.length != toArr.length)
+            throw new Error("Array size mismatch");
+        return from.map((v, i) => tweenValue(v, toArr[i], progress));
+    }
+    if (typeof from == "string") {
+        return blendStrings(from, to, progress);
+    }
+    if (typeof from == "number") {
+        return blendNumbers(from, to, progress);
+    }
+    if (from && typeof from == "object") {
+        if ("blend" in from) {
+            const blendableSource = from;
+            return blendableSource.blend(to, progress);
+        }
+    }
+    throw new Error("Value not recognised as Tweenable");
+}
+function blendNumbers(from, to, progress) {
+    return from + progress * (to - from);
+}
+function mergeStrings(from, to, progress) {
+    const p = Math.min(Math.max(progress, 0), 1);
+    // Fast‑path: identical strings or one is empty
+    if (from === to)
+        return from;
+    if (!from)
+        return to;
+    if (!to)
+        return from;
+    const split = (s) => {
+        // Prefer Intl.Segmenter if available (Node ≥ 14, modern browsers)
+        if (typeof Intl !== "undefined" && Intl.Segmenter) {
+            const seg = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+            return Array.from(seg.segment(s), (seg) => seg.segment);
+        }
+        // Fallback regex (covers surrogate pairs & combining marks)
+        const graphemeRegex = /(\P{Mark}\p{Mark}*|[\uD800-\uDBFF][\uDC00-\uDFFF])/gu;
+        return s.match(graphemeRegex) ?? Array.from(s);
+    };
+    const a = split(from);
+    const b = split(to);
+    const maxLen = Math.max(a.length, b.length);
+    const pad = (arr) => {
+        const diff = maxLen - arr.length;
+        if (diff <= 0)
+            return arr;
+        return arr.concat(Array(diff).fill(" "));
+    };
+    const fromP = pad(a);
+    const toP = pad(b);
+    const replaceCount = Math.floor(p * maxLen);
+    const result = new Array(maxLen);
+    for (let i = 0; i < maxLen; ++i) {
+        result[i] = i < replaceCount ? toP[i] : fromP[i];
+    }
+    while (result.length && result[result.length - 1] === " ") {
+        result.pop();
+    }
+    return result.join("");
+}
+function parseColour(code) {
+    if (code.length < 2 || !code.startsWith("#"))
+        throw new Error("Invalid colour");
+    let rawHex = code.substring(1);
+    if (rawHex.length == 1)
+        rawHex = rawHex + rawHex + rawHex;
+    if (rawHex.length == 2) {
+        const white = rawHex[0];
+        const alpha = rawHex[1];
+        rawHex = white + white + white + alpha;
+    }
+    if (rawHex.length == 3)
+        rawHex += "f";
+    if (rawHex.length == 4)
+        rawHex = rawHex.replace(/./g, c => c + c);
+    if (rawHex.length == 6)
+        rawHex += "ff";
+    return [...rawHex.matchAll(/../g)].map(hex => parseInt(hex[0], 16));
+}
+function blendColours(from, to, bias) {
+    const fromColour = parseColour(from);
+    const toColour = parseColour(to);
+    const blended = fromColour.map((val, i) => (0, utils_1.clamp)(blendNumbers(val, toColour[i], bias), 0, 255));
+    return ("#" + blended.map(n => Math.round(n).toString(16).padStart(2, "0")).join("")).replace(/ff$/, "");
+}
+const tweenableTokenRegex = /(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/g;
+function blendStrings(from, to, progress) {
+    if (from === to || progress === 0)
+        return from;
+    const tokenise = (s) => {
+        const chunks = [];
+        let lastIdx = 0;
+        let m;
+        while ((m = tweenableTokenRegex.exec(s))) {
+            const token = m[0];
+            const prefix = s.slice(lastIdx, m.index); // literal before token
+            chunks.push({ prefix, token });
+            lastIdx = m.index + token.length;
+        }
+        // trailing literal after the last token – stored as a final chunk
+        // with an empty token (so the consumer can easily append it)
+        const tail = s.slice(lastIdx);
+        if (tail.length) {
+            chunks.push({ prefix: tail, token: "" });
+        }
+        return chunks;
+    };
+    const fromChunks = tokenise(from);
+    const toChunks = tokenise(to);
+    const tokenCount = fromChunks.filter(c => c.token).length;
+    if (tokenCount !== toChunks.filter(c => c.token).length) {
+        return mergeStrings(from, to, progress);
+    }
+    let result = "";
+    for (let i = 0, j = 0; i < fromChunks.length && j < toChunks.length;) {
+        const f = fromChunks[i];
+        const t = toChunks[j];
+        // The *prefix* (the text before the token) must be the same.
+        if (f.prefix !== t.prefix) {
+            return mergeStrings(from, to, progress);
+        }
+        // Append the unchanged prefix.
+        result += f.prefix;
+        // If we are at the *trailing* chunk (no token), just break.
+        if (!f.token && !t.token) {
+            break;
+        }
+        // Blend the token according to its kind.
+        let blended;
+        if (f.token.startsWith("#")) {
+            blended = blendColours(f.token, t.token, progress);
+        }
+        else {
+            const fNum = parseFloat(f.token);
+            const tNum = parseFloat(t.token);
+            const blendedNum = blendNumbers(fNum, tNum, progress);
+            blended = blendedNum.toString();
+        }
+        result += blended;
+        // Advance both pointers.
+        i++;
+        j++;
+    }
+    return result;
+}

package/internal/utils.d.ts

@@ -0,0 +1,4 @@
+/** @internal */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/** @internal */
+export type Widen<T> = T extends number ? number : T extends string ? string : T;

package/internal/utils.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clamp = void 0;
+/** @internal */
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+exports.clamp = clamp;

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"
   },
-  "description": "A general‑purpose, environment-agnostic choreography engine",
-  "main": "index.js",
+  "description": "A general-purpose, environment-agnostic choreography engine",
+  "sideEffects": false,
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./internal/*": null
+  },
   "scripts": {
     "prepublishOnly": "cp ../README.md .",
     "postpublish": "rm README.md"