@xtia/timeline 1.2.3 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Aleta Lovelace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -342,7 +342,7 @@ await timeline.seek(timeline.end, 400, "overshootIn");
 
 ## Backward-compatibility
 
-Despite the massive overhaul, the previous API is present and expanded and upgrading to 1.0.0 should be frictionless in the vast majority of cases.
+The previous API is present and expanded, but deprecated.
 
 #### Breaking changes
 
@@ -363,6 +363,7 @@ Despite the massive overhaul, the previous API is present and expanded and upgra
 * `timeline.position` will be replaced with `timeline.currentTime` to be consistent with other seekable concepts.
 * `"loop"` endAction is now `"restart"` to disambiguate from new looping strategies.
 * `timeline.step()` is redundant now that `currentTime` is writable; use `timeline.currentTime += delta` instead.
+* The legacy API (`tl.tween()`, `tl.at()`, `tl.position`) will be removed in 2.*
 
 
 

package/{internal → lib}/animate.js

@@ -4,7 +4,7 @@ export function animate(duration, looping = false) {
     const durationMs = typeof duration == "number"
         ? duration
         : duration.asMilliseconds;
-    if (durationMs === Infinity || durationMs < 0)
+    if (durationMs === Infinity || durationMs <= 0)
         throw new RangeError("animate() duration must be positive and finite");
     let t = 0;
     if (looping) {

package/{internal → lib}/driver.js

@@ -19,7 +19,7 @@ const createIntervalDriver = (tick) => {
     };
 };
 export const masterDriver = (() => {
-    const timelines = new Map();
+    const subscriptions = new Map();
     let previousTime = null;
     let pause = null;
     const stepAll = (currentTime) => {
@@ -29,7 +29,7 @@ export const masterDriver = (() => {
         }
         const delta = currentTime - previousTime;
         previousTime = currentTime;
-        timelines.forEach((step, tl) => {
+        subscriptions.forEach((step, tl) => {
             step(delta);
         });
     };
@@ -38,14 +38,14 @@ export const masterDriver = (() => {
         : createIntervalDriver(stepAll);
     return (stepFn) => {
         const key = Symbol();
-        timelines.set(key, stepFn);
-        if (timelines.size === 1) {
+        subscriptions.set(key, stepFn);
+        if (subscriptions.size === 1) {
             previousTime = null;
             pause = start();
         }
         return () => {
-            timelines.delete(key);
-            if (timelines.size === 0) {
+            subscriptions.delete(key);
+            if (subscriptions.size === 0) {
                 pause();
             }
         };

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { Timeline, ChainingInterface } from "./timeline.js";
+export { animate } from "./animate.js";
+export { TimelinePoint, PointEvent } from "./point.js";
+export { TimelineRange } from "./range.js";
+export { type Emitter, type RangeProgression, UnsubscribeFunc } from "./emitters.js";
+export { easers } from "./easing.js";

package/lib/index.js

@@ -0,0 +1,5 @@
+export { Timeline } from "./timeline.js";
+export { animate } from "./animate.js";
+export { TimelinePoint } from "./point.js";
+export { TimelineRange } from "./range.js";
+export { easers } from "./easing.js";

package/{internal → lib}/path.d.ts

@@ -18,7 +18,16 @@ type CurveSegment = {
     speed?: number;
     ease?: Easer | keyof typeof easers;
 };
-type StaticSegment = LineSegment | CurveSegment;
+type ArcSegment = {
+    type: "arc";
+    from?: XY;
+    to: XY;
+    radius?: number;
+    direction: "clockwise" | "anticlockwise";
+    speed?: number;
+    ease?: Easer | keyof typeof easers;
+};
+type StaticSegment = LineSegment | CurveSegment | ArcSegment;
 type Segment = StaticSegment | CustomSegment;
 type CustomSegment = {
     get: SegmentEvaluator;

package/lib/path.js

@@ -0,0 +1,150 @@
+import { createListenable } from "./emitters.js";
+import { Timeline } from "./timeline.js";
+export function createPathEmitter(input) {
+    const { listen, emit } = createListenable();
+    const tl = new Timeline();
+    const firstItem = input[0];
+    let getCurrentPosition;
+    let items;
+    if (Array.isArray(firstItem)) {
+        // first is XY - use it as starting position and exclude it from iteration
+        items = input.slice(1);
+        getCurrentPosition = () => firstItem;
+    }
+    else {
+        items = input;
+        getCurrentPosition = () => [0, 0];
+    }
+    items.forEach(item => {
+        const speed = typeof item === 'object' && !Array.isArray(item) && "speed" in item ? item.speed ?? 1 : 1;
+        if (typeof item == "function") {
+            const length = estimateLength(item);
+            tl.end.range(length / speed)
+                .apply(v => emit(item(v)));
+            getCurrentPosition = () => item(1);
+        }
+        else if (Array.isArray(item)) { // XY
+            const start = getCurrentPosition();
+            const length = distance(start, item);
+            tl.end.range(length / speed)
+                .tween(start, item)
+                .apply(emit);
+            getCurrentPosition = () => item;
+        }
+        else if ("get" in item) { // custom segment
+            const length = item.length ?? estimateLength(item.get);
+            tl.end.range(length / speed)
+                .ease(item.ease)
+                .apply(v => emit(item.get(v)));
+            getCurrentPosition = () => item.get(1);
+        }
+        else
+            switch (item.type) { // static segment
+                case "line": {
+                    const start = item.from ?? getCurrentPosition();
+                    const length = distance(start, item.to);
+                    tl.end.range(length / speed)
+                        .ease(item.ease)
+                        .tween(start, item.to)
+                        .apply(emit);
+                    getCurrentPosition = () => item.to;
+                    break;
+                }
+                case "curve": {
+                    const start = item.from ?? getCurrentPosition();
+                    const curve = createCurve(start, item.to, item.control1, item.control2);
+                    const length = estimateLength(curve);
+                    tl.end.range(length / speed)
+                        .ease(item.ease)
+                        .apply(v => emit(curve(v)));
+                    getCurrentPosition = () => item.to;
+                    break;
+                }
+                case "arc": {
+                    const start = getCurrentPosition();
+                    const arc = createArc(start, item.to, item.radius, item.direction);
+                    const length = estimateLength(arc);
+                    tl.end.range(length / (item.speed ?? 1))
+                        .ease(item.ease)
+                        .apply(v => emit(arc(v)));
+                    getCurrentPosition = () => item.to;
+                    break;
+                }
+            }
+    });
+    return { listen, seek: t => {
+            tl.seek(t * tl.end.position);
+        } };
+}
+function createCurve([startX, startY], [endX, endY], [control1x, control1y], [control2x, control2y]) {
+    return (t) => {
+        const ti = 1 - t;
+        const x = ti ** 3 * startX +
+            3 * ti ** 2 * t * control1x +
+            3 * ti * t ** 2 * control2x +
+            t ** 3 * endX;
+        const y = ti ** 3 * startY +
+            3 * ti ** 2 * t * control1y +
+            3 * ti * t ** 2 * control2y +
+            t ** 3 * endY;
+        return [x, y];
+    };
+}
+function estimateLength(curve, samples = 100) {
+    let length = 0;
+    let prev = curve(0);
+    for (let i = 1; i <= samples; i++) {
+        const t = i / samples;
+        const current = curve(t);
+        length += Math.sqrt((current[0] - prev[0]) ** 2 + (current[1] - prev[1]) ** 2);
+        prev = current;
+    }
+    return length;
+}
+const distance = (a, b) => Math.sqrt((b[0] - a[0]) ** 2 + (b[1] - a[1]) ** 2);
+function createArc([startX, startY], [endX, endY], radius, direction = "clockwise") {
+    const dx = endX - startX;
+    const dy = endY - startY;
+    const chordLength = Math.sqrt(dx * dx + dy * dy);
+    if (chordLength < 0.0001) {
+        return _ => [startX, startY];
+    }
+    const r = radius ?? chordLength / 2;
+    const minRadius = chordLength / 2;
+    let effectiveRadius = Math.max(r, minRadius);
+    const halfChord = chordLength / 2;
+    let centreOffset = Math.sqrt(effectiveRadius * effectiveRadius - halfChord * halfChord);
+    if (isNaN(centreOffset)) {
+        effectiveRadius = minRadius;
+        centreOffset = 0;
+    }
+    const chordMidX = (startX + endX) / 2;
+    const chordMidY = (startY + endY) / 2;
+    const perpX = -dy / chordLength;
+    const perpY = dx / chordLength;
+    const sign = direction === "clockwise" ? 1 : -1;
+    const centerX = chordMidX + perpX * sign * centreOffset;
+    const centerY = chordMidY + perpY * sign * centreOffset;
+    const startAngle = Math.atan2(startY - centerY, startX - centerX);
+    const endAngle = Math.atan2(endY - centerY, endX - centerX);
+    let angleDiff = endAngle - startAngle;
+    if (direction === "clockwise") {
+        if (angleDiff > 0)
+            angleDiff -= Math.PI * 2;
+        if (angleDiff > -Math.PI)
+            angleDiff -= Math.PI * 2;
+    }
+    else {
+        if (angleDiff < 0)
+            angleDiff += Math.PI * 2;
+        if (angleDiff < Math.PI)
+            angleDiff += Math.PI * 2;
+    }
+    return (t) => {
+        const clampedT = Math.max(0, Math.min(1, t));
+        const angle = startAngle + angleDiff * clampedT;
+        const x = centerX + effectiveRadius * Math.cos(angle);
+        const y = centerY + effectiveRadius * Math.sin(angle);
+        return [x, y];
+    };
+}

package/{internal → lib}/point.d.ts

@@ -46,13 +46,13 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      */
     seek(duration: number, easer?: Easer): Promise<void>;
     /**
-     * An point emitter that only emits on forward-moving seeks
+     * A point emitter that only emits on forward-moving seeks
      * @returns Listenable: emits forward-seeking point events
      */
     get forwardOnly(): Emitter<PointEvent>;
     private _forwardOnly?;
     /**
-     * An point emitter that only emits on backward-moving seeks
+     * A point emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
     get reverseOnly(): Emitter<PointEvent>;

package/{internal → lib}/point.js

@@ -41,7 +41,7 @@ export class TimelinePoint extends Emitter {
         return this.timeline.seek(this.position, duration, easer);
     }
     /**
-     * An point emitter that only emits on forward-moving seeks
+     * A point emitter that only emits on forward-moving seeks
      * @returns Listenable: emits forward-seeking point events
      */
     get forwardOnly() {
@@ -50,7 +50,7 @@ export class TimelinePoint extends Emitter {
         return this._forwardOnly;
     }
     /**
-     * An point emitter that only emits on backward-moving seeks
+     * A point emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
     get reverseOnly() {

package/{internal → lib}/timeline.d.ts

@@ -196,7 +196,7 @@ export declare class Timeline {
      * @deprecated Legacy API may be absent in a future major version
      */
     at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
-    private createChainingInterface;
+    private chain;
     /**
      * @deprecated use `timeline.currentTime`
      */

package/{internal → lib}/timeline.js

@@ -394,7 +394,7 @@ export class Timeline {
             ? durationOrToPoint
             : (durationOrToPoint.position - startPosition);
         this.range(startPosition, duration).ease(easer).tween(from, to).apply(apply);
-        return this.createChainingInterface(startPosition + duration);
+        return this.chain(startPosition + duration);
     }
     /**
      * Adds an event at a specific position
@@ -414,7 +414,7 @@ export class Timeline {
                     throw new Error("Invalid call");
                 point.reverseOnly.apply(reverse);
             }
-            return this.createChainingInterface(point.position);
+            return this.chain(point.position);
         }
         if (reverse) {
             if (reverse === true) {
@@ -427,9 +427,9 @@ export class Timeline {
         else {
             point.forwardOnly.apply(action);
         }
-        return this.createChainingInterface(point.position);
+        return this.chain(point.position);
     }
-    createChainingInterface(position) {
+    chain(position) {
         const chain = {
             thenTween: (duration, apply, from, to, easer) => {
                 return this.tween(position, duration, apply, from, to, easer);
@@ -437,7 +437,7 @@ export class Timeline {
             then: (action) => this.at(position, action),
             thenWait: (delay) => {
                 this.point(position + delay);
-                return this.createChainingInterface(position + delay);
+                return this.chain(position + delay);
             },
             fork: fn => {
                 fn(chain);

package/{internal → lib}/tween.js

@@ -50,6 +50,10 @@ function createStringTween(from, to) {
         const prefix = chunk.prefix;
         if (chunk.type === TokenTypes.none)
             return () => prefix;
+        if (fromToken === toToken) {
+            const full = prefix + fromToken;
+            return () => full;
+        }
         if (chunk.type === TokenTypes.colour) {
             const fromColour = parseColour(fromToken);
             const toColour = parseColour(toToken);

package/package.json

@@ -1,30 +1,41 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.2.3",
+  "version": "1.3.0",
+  "description": "A general-purpose, environment-agnostic choreography engine",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"
   },
-  "description": "A general-purpose, environment-agnostic choreography engine",
   "sideEffects": false,
-  "types": "./index.d.ts",
-  "main": "./index.js",
+  "files": [
+    "lib/"
+  ],
+  "types": "./lib/index.d.ts",
+  "main": "./lib/index.js",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
     },
-    "./internal/*": null
+    "./lib/*": null
   },
   "scripts": {
-    "prepublishOnly": "cp ../README.md .",
-    "postpublish": "rm README.md"
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "tsc"
   },
+  "author": "Aleta Lovelace",
   "keywords": [
     "animation",
     "timeline",
     "choreography"
   ],
-  "author": "Aleta Lovelace",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@xtia/mezr": "^0.1.2",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3"
+  }
 }

package/index.d.ts

@@ -1,6 +0,0 @@
-export { Timeline, ChainingInterface } from "./internal/timeline.js";
-export { animate } from "./internal/animate.js";
-export { TimelinePoint, PointEvent } from "./internal/point.js";
-export { TimelineRange } from "./internal/range.js";
-export { type Emitter, type RangeProgression, UnsubscribeFunc } from "./internal/emitters.js";
-export { easers } from "./internal/easing.js";

package/index.js

@@ -1,5 +0,0 @@
-export { Timeline } from "./internal/timeline.js";
-export { animate } from "./internal/animate.js";
-export { TimelinePoint } from "./internal/point.js";
-export { TimelineRange } from "./internal/range.js";
-export { easers } from "./internal/easing.js";

package/internal/path.js

@@ -1,85 +0,0 @@
-import { createListenable } from "./emitters.js";
-import { Timeline } from "./timeline.js";
-export function createPathEmitter(input) {
-    const { listen, emit } = createListenable();
-    const tl = new Timeline();
-    let lastXY = [0, 0];
-    const firstItem = input[0];
-    let getCurrentPosition;
-    let items;
-    if (Array.isArray(firstItem)) {
-        // first is XY - use it as starting position and exclude it from iteration
-        items = input.slice(1);
-        getCurrentPosition = () => firstItem;
-    }
-    else {
-        items = input;
-        getCurrentPosition = () => [0, 0];
-    }
-    items.forEach(item => {
-        const speed = typeof item === 'object' && !Array.isArray(item) && "speed" in item ? item.speed ?? 1 : 1;
-        if (typeof item == "function") {
-            const length = estimateLength(item);
-            tl.end.range(length / speed).apply(v => lastXY = item(v));
-            getCurrentPosition = () => item(1);
-        }
-        else if (Array.isArray(item)) { // XY
-            const start = getCurrentPosition();
-            const length = distance(start, item);
-            tl.end.range(length / speed).tween(start, item).apply(v => lastXY = v);
-            getCurrentPosition = () => item;
-        }
-        else if ("get" in item) { // custom segment
-            const length = item.length ?? estimateLength(item.get);
-            tl.end.range(length / speed).ease(item.ease).apply(v => lastXY = item.get(v));
-            getCurrentPosition = () => item.get(1);
-        }
-        else
-            switch (item.type) { // static segment
-                case "line": {
-                    const start = item.from ?? getCurrentPosition();
-                    const length = distance(start, item.to);
-                    tl.end.range(length / speed).ease(item.ease).tween(start, item.to).apply(v => lastXY = v);
-                    getCurrentPosition = () => item.to;
-                    break;
-                }
-                case "curve": {
-                    const start = item.from ?? getCurrentPosition();
-                    const curve = createCurve(start, item.to, item.control1, item.control2);
-                    const length = estimateLength(curve);
-                    tl.end.range(length / speed).ease(item.ease).map(curve).apply(v => lastXY = v);
-                    getCurrentPosition = () => item.to;
-                }
-            }
-    });
-    return { listen, seek: t => {
-            tl.seek(t * tl.end.position);
-            emit(lastXY);
-        } };
-}
-function createCurve([startX, startY], [endX, endY], [control1x, control1y], [control2x, control2y]) {
-    return (t) => {
-        const ti = 1 - t;
-        const x = ti ** 3 * startX +
-            3 * ti ** 2 * t * control1x +
-            3 * ti * t ** 2 * control2x +
-            t ** 3 * endX;
-        const y = ti ** 3 * startY +
-            3 * ti ** 2 * t * control1y +
-            3 * ti * t ** 2 * control2y +
-            t ** 3 * endY;
-        return [x, y];
-    };
-}
-function estimateLength(curve, samples = 100) {
-    let length = 0;
-    let prev = curve(0);
-    for (let i = 1; i <= samples; i++) {
-        const t = i / samples;
-        const current = curve(t);
-        length += Math.sqrt((current[0] - prev[0]) ** 2 + (current[1] - prev[1]) ** 2);
-        prev = current;
-    }
-    return length;
-}
-const distance = (a, b) => Math.sqrt((b[0] - a[0]) ** 2 + (b[1] - a[1]) ** 2);