@xtia/timeline 1.1.14 → 1.1.16

package/internal/emitters.d.ts

@@ -1,4 +1,5 @@
 import { Easer, easers } from "./easing";
+import { Path, XY } from "./path";
 import { BlendableWith, Tweenable } from "./tween";
 type Handler<T> = (value: T) => void;
 export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
@@ -187,6 +188,7 @@ export declare class RangeProgression extends Emitter<number> {
      * @returns Listenable: emits non-repeating values
      */
     dedupe(): RangeProgression;
+    path(segments: Path): Emitter<XY>;
     private _dedupe?;
     /**
      * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1

package/internal/emitters.js

@@ -1,4 +1,5 @@
 import { easers } from "./easing";
+import { createPathEmitter } from "./path";
 import { createTween } from "./tween";
 import { clamp } from "./utils";
 export class Emitter {
@@ -138,10 +139,14 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits the sampled values
      */
     sample(source) {
+        if (source.length === 0) {
+            throw new Error("Sample source is empty");
+        }
+        const sourceArray = Array.from(source);
         const listen = this.transform((value, emit) => {
             const clampedProgress = clamp(value);
-            const index = Math.floor(clampedProgress * (source.length - 1));
-            emit(source[index]);
+            const index = Math.floor(clampedProgress * (sourceArray.length - 1));
+            emit(sourceArray[index]);
         });
         return new Emitter(listen);
     }
@@ -236,6 +241,29 @@ export class RangeProgression extends Emitter {
         }
         return this._dedupe;
     }
+    path(segments) {
+        const pathEvaluator = createPathEmitter(segments);
+        let parentUnsubscribe = null;
+        let pathUnsubscribe = null;
+        const { listen, emit } = createListenable(() => {
+            // onAddFirst - when first listener subscribes
+            pathUnsubscribe = pathEvaluator.listen(emit);
+            parentUnsubscribe = this.listen((timeValue) => {
+                pathEvaluator.seek(timeValue);
+            });
+        }, () => {
+            // onRemoveLast - when last listener unsubscribes  
+            if (pathUnsubscribe) {
+                pathUnsubscribe();
+                pathUnsubscribe = null;
+            }
+            if (parentUnsubscribe) {
+                parentUnsubscribe();
+                parentUnsubscribe = null;
+            }
+        });
+        return new Emitter(listen);
+    }
     /**
      * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
      *

package/internal/path.d.ts

@@ -0,0 +1,36 @@
+import { Easer, easers } from "./easing";
+import { ListenFunc } from "./emitters";
+export type XY = [number, number];
+type SegmentEvaluator = (t: number) => XY;
+type LineSegment = {
+    type: "line";
+    from?: XY;
+    to: XY;
+    speed?: number;
+    ease?: Easer | keyof typeof easers;
+};
+type CurveSegment = {
+    type: "curve";
+    from?: XY;
+    to: XY;
+    control1: XY;
+    control2: XY;
+    speed?: number;
+    ease?: Easer | keyof typeof easers;
+};
+type StaticSegment = LineSegment | CurveSegment;
+type Segment = StaticSegment | CustomSegment;
+type CustomSegment = {
+    get: SegmentEvaluator;
+    length?: number;
+};
+type FirstSegment = CustomSegment | (StaticSegment & {
+    from: XY;
+});
+export type Path = [FirstSegment | XY, ...(Segment | XY)[]] | XY[];
+type PathEvaluator = {
+    listen: ListenFunc<XY>;
+    seek: (n: number) => void;
+};
+export declare function createPathEmitter(input: Path): PathEvaluator;
+export {};

package/internal/path.js

@@ -0,0 +1,75 @@
+import { createListenable } from "./emitters";
+import { Timeline } from "./timeline";
+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 (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).map(v => item.get(v)).apply(emit);
+            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).map(curve).apply(emit);
+                    getCurrentPosition = () => item.to;
+                }
+            }
+    });
+    return { listen, seek: t => tl.seek(t * tl.end.position) };
+}
+function createCurve(start, end, control1, control2) {
+    return (t) => {
+        const x = (1 - t) ** 3 * start[0] +
+            3 * (1 - t) ** 2 * t * control1[0] +
+            3 * (1 - t) * t ** 2 * control2[0] +
+            t ** 3 * end[0];
+        const y = (1 - t) ** 3 * start[1] +
+            3 * (1 - t) ** 2 * t * control1[1] +
+            3 * (1 - t) * t ** 2 * control2[1] +
+            t ** 3 * end[1];
+        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);

package/internal/tween.js

@@ -132,21 +132,18 @@ function parseColour(code) {
         rawHex += "ff";
     return [...rawHex.matchAll(/../g)].map(hex => parseInt(hex[0], 16));
 }
-function blendColours(from, to, bias) {
-    const blended = from.map((val, i) => clamp(blendNumbers(val, to[i], bias), 0, 255));
-    if (blended[3] === 255) {
-        return "#" +
-            Math.round(blended[0]).toString(16).padStart(2, "0") +
-            Math.round(blended[1]).toString(16).padStart(2, "0") +
-            Math.round(blended[2]).toString(16).padStart(2, "0");
-    }
-    else {
-        return "#" +
-            Math.round(blended[0]).toString(16).padStart(2, "0") +
-            Math.round(blended[1]).toString(16).padStart(2, "0") +
-            Math.round(blended[2]).toString(16).padStart(2, "0") +
-            Math.round(blended[3]).toString(16).padStart(2, "0");
-    }
+const hexLookup = new Array(256);
+for (let i = 0; i < 256; i++) {
+    hexLookup[i] = i.toString(16).padStart(2, "0");
+}
+function blendColours([fromR, fromG, fromB, fromA], [toR, toG, toB, toA], bias) {
+    const r = Math.max(0, Math.min(255, Math.round(fromR + bias * (toR - fromR))));
+    const g = Math.max(0, Math.min(255, Math.round(fromG + bias * (toG - fromG))));
+    const b = Math.max(0, Math.min(255, Math.round(fromB + bias * (toB - fromB))));
+    const a = Math.max(0, Math.min(255, Math.round(fromA + bias * (toA - fromA))));
+    return a === 255
+        ? "#" + hexLookup[r] + hexLookup[g] + hexLookup[b]
+        : "#" + hexLookup[r] + hexLookup[g] + hexLookup[b] + hexLookup[a];
 }
 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 tokenise(s) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"