@xtia/timeline 1.1.17 → 1.1.19

package/README.md

@@ -7,6 +7,8 @@ Timeline is a type-safe, seekable, deterministic choreography system that can co
 * [API Reference](#reference)
 * [Playground](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
 * [Intro by HL](https://codepen.io/H-L-the-lessful/full/vELdyvB)
+* [Sprite sheet demo](https://codepen.io/xtaltia/pen/jEWrXOg)
+* [Web animation benchmark](https://codepen.io/xtaltia/pen/qENNzRw)
 
 ## Basic Use:
 
@@ -137,7 +139,7 @@ Points represent specific times in the Timeline.
 ```ts
 const twoSecondsIn = timeline.point(2000);
 const fiveSecondsIn = firstFiveSeconds.end;
-const sixSecondsIn = fiveSecondsdIn.delta(1000);
+const sixSecondsIn = fiveSecondsIn.delta(1000);
 ```
 
 Points emit `PointEvent` objects when their position is reached or passed.
@@ -156,8 +158,8 @@ Directionality can also be leveraged with `point.applyDirectional()`:
 
 ```ts
 twoSecondsIn.applyDirectional(
-    parent.append(element), // do
-    element.remove() // undo
+    () => parent.append(element), // do
+    () => element.remove() // undo
 );
 ```
 
@@ -178,7 +180,7 @@ timeline
 
 ## More on tweening
 
-Tween emitters can interpolate numbers, arrays of numbers, strings, and objects with a method `blend(from: this, to: this): this`, by the progression value emitted by their parent.
+Tween emitters can interpolate numbers, arrays of numbers, strings, and objects with a method `blend(to: this, progression: number): this`, by the progression value emitted by their parent.
 
 ```ts
 const range = timeline.range(0, 2000);
@@ -200,7 +202,7 @@ range
     .apply(v => element.style.color = v);
 
 // blendable objects
-// (T extends { blend(from: this, to: this): this })
+// (T extends { blend(to: this, progression: number): this })
 import { RGBA } from "@xtia/rgba";
 range
     .tween(RGBA.parse("#c971a7"), RGBA.parse("#fff"))
@@ -643,10 +645,6 @@ Returns a Promise that will be resolved when the range playthrough completes.
 
 ##### `grow(delta, anchor?): TimelineRange`
 
-Creates a new range on the parent Timeline. The location and duration of the new range are copied from this range and grown from an anchor point, specified as a normalised (0..1) progression of the parent range.
-
-##### `grow(delta, anchor?): TimelineRange`
-
 Creates a new range on the parent Timeline. The location and duration of the new range are copied from this range and scaled multiplicatively from an anchor point, specified as a normalised (0..1) progression of the parent range.
 
 ##### `subdivide(n): TimelineRange[]`
@@ -665,6 +663,62 @@ Returns true if the given [`TimelinePoint`](#timelinepoint-class) sits within th
 
 Returns true if the given range overlaps with this range.
 
+##### `path(steps: Path): Emitter<[number, number]>
+
+Creates an emitter that follows a given path, emitting `[x, y]` (`XY`) as its parent range is progressed.
+
+Path segments can be expressed as a mix of `[x, y]`, resolver functions (`progress => XY`) and Segment descriptor objects.
+
+```ts
+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 CustomSegment = {
+    get: SegmentEvaluator;
+    length?: number;
+    ease?: Easer | keyof typeof easers;
+}
+```
+
+* If the first element is `[x, y]`, it defines the path's starting position.
+* If the first element is a non-custom descriptor object it must include a `from` property.
+* Duration of segments defined as resolver functions, and custom segments without a `length` property, will be estimated by point sampling
+
+```ts
+// simple path with coordinates
+const eg1 = range.path([[0, 0], [100, 50], [200, 0]])
+
+// mixed path with curve segments
+const eg2 = range.path([
+  [0, 0], // start position
+  {
+    type: 'curve',
+    to: [100, 100],
+    control1: [25, 0],
+    control2: [75, 100],
+    ease: easers.easeOut
+  },
+  [50, 50] // straight line to final position
+]);
+
+eg2.map(([x, y]) => [x + "%", y + "%"])
+    .apply(([left, top]) => element.style({ left, top }));
+```
 
 
 

package/internal/emitters.d.ts

@@ -69,7 +69,7 @@ export declare class Emitter<T> {
      * ```
      * @param cb
      */
-    fork(cb: (branch: this) => void): this;
+    fork(...cb: ((branch: this) => void)[]): this;
 }
 export declare class RangeProgression extends Emitter<number> {
     /**

package/internal/emitters.js

@@ -105,8 +105,8 @@ export class Emitter {
      * ```
      * @param cb
      */
-    fork(cb) {
-        cb(this);
+    fork(...cb) {
+        cb.forEach(cb => cb(this));
         return this;
     }
 }

package/internal/path.d.ts

@@ -23,7 +23,8 @@ type Segment = StaticSegment | CustomSegment;
 type CustomSegment = {
     get: SegmentEvaluator;
     length?: number;
-};
+    ease?: Easer | keyof typeof easers;
+} | SegmentEvaluator;
 type FirstSegment = CustomSegment | (StaticSegment & {
     from: XY;
 });

package/internal/path.js

@@ -3,6 +3,7 @@ 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;
@@ -17,15 +18,20 @@ export function createPathEmitter(input) {
     }
     items.forEach(item => {
         const speed = typeof item === 'object' && !Array.isArray(item) && "speed" in item ? item.speed ?? 1 : 1;
-        if (Array.isArray(item)) { // XY
+        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(emit);
+            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).map(v => item.get(v)).apply(emit);
+            tl.end.range(length / speed).ease(item.ease).apply(v => lastXY = item.get(v));
             getCurrentPosition = () => item.get(1);
         }
         else
@@ -33,7 +39,7 @@ export function createPathEmitter(input) {
                 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);
+                    tl.end.range(length / speed).ease(item.ease).tween(start, item.to).apply(v => lastXY = v);
                     getCurrentPosition = () => item.to;
                     break;
                 }
@@ -41,23 +47,27 @@ export function createPathEmitter(input) {
                     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);
+                    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) };
+    return { listen, seek: t => {
+            tl.seek(t * tl.end.position);
+            emit(lastXY);
+        } };
 }
-function createCurve(start, end, control1, control2) {
+function createCurve([startX, startY], [endX, endY], [control1x, control1y], [control2x, control2y]) {
     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];
+        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];
     };
 }

package/internal/timeline.js

@@ -2,9 +2,43 @@ import { createListenable, RangeProgression } from "./emitters.js";
 import { TimelinePoint } from "./point.js";
 import { TimelineRange } from "./range.js";
 import { clamp } from "./utils.js";
-const default_fps = 60;
+const default_interval_fps = 60;
 const requestAnimFrame = globalThis?.requestAnimationFrame;
 const cancelAnimFrame = globalThis?.cancelAnimationFrame;
+const rafController = (() => {
+    const timelines = new Map();
+    let rafId = null;
+    const start = () => {
+        let previousTime = null;
+        const frame = (currentTime) => {
+            if (previousTime === null) {
+                previousTime = currentTime;
+            }
+            const elapsed = currentTime - previousTime;
+            previousTime = currentTime;
+            timelines.forEach((step, tl) => {
+                const delta = elapsed * tl.timeScale;
+                step(delta);
+            });
+            rafId = requestAnimFrame(frame);
+        };
+        rafId = requestAnimFrame(frame);
+    };
+    return {
+        add: (timeline, stepFn) => {
+            timelines.set(timeline, stepFn);
+            if (rafId === null)
+                start();
+        },
+        remove: (timeline) => {
+            timelines.delete(timeline);
+            if (timelines.size === 0) {
+                cancelAnimFrame(rafId);
+                rafId = null;
+            }
+        }
+    };
+})();
 const EndAction = {
     pause: 0,
     continue: 1,
@@ -350,7 +384,7 @@ export class Timeline {
             this.playWithRAF();
             return;
         }
-        this.playWithInterval(arg ?? default_fps);
+        this.playWithInterval(arg ?? default_interval_fps);
     }
     playWithInterval(fps) {
         let previousTime = performance.now();
@@ -364,21 +398,8 @@ export class Timeline {
         this._pause = () => clearInterval(interval);
     }
     playWithRAF() {
-        let previousTime = null;
-        let rafId;
-        const frame = (currentTime) => {
-            if (previousTime === null) {
-                previousTime = currentTime;
-            }
-            const elapsed = currentTime - previousTime;
-            previousTime = currentTime;
-            let delta = elapsed * this.timeScale;
-            this.next(delta);
-            if (this._pause)
-                rafId = requestAnimFrame(frame);
-        };
-        rafId = requestAnimFrame(frame);
-        this._pause = () => cancelAnimFrame(rafId);
+        rafController.add(this, n => this.next(n));
+        this._pause = () => rafController.remove(this);
     }
     next(delta) {
         if (this._currentTime + delta <= this._endPosition) {

package/package.json

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