@xtia/timeline 1.0.12 → 1.1.1

package/README.md

@@ -1,8 +1,8 @@
 # Timeline
 
-### A Type‑Safe Choreography Engine for Deterministic Timelines
+### Not Just Another Animation Library
 
-**Timeline** is a general‑purpose, environment-agnostic choreography engine that lets you orchestrate any sequence of value changes; numbers, vectors, colour tokens, custom blendable objects, or arbitrary data structures.
+Timeline is a type-safe, deterministic choreography system that can control state transitions in any environment, whether that's a simple or complex CSS animation, managing a microcontroller's output, or synchronising complex hardware sequences.
 
 * [API Reference](#reference)
 * [Playground](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
@@ -21,7 +21,7 @@ const timeline = new Timeline();
 timeline
     .range(0, 1000)
     .tween("#646", "#000")
-    .listen(
+    .apply(
         value => element.style.background = value
     );
 
@@ -29,20 +29,18 @@ timeline
 const message = "Hi, planet!";
 timeline
     .range(500, 2000)
+    .ease("easeOut")
     .tween(0, message.length)
     .map(n => message.substring(0, n))
-    .listen(
+    .apply(
         s => element.textContent = s
     );
 
-// use an easing function
+// control anything:
 timeline
-    .range(0, 3000)
-    .ease("bounce")
-    .tween("50%", "0%")
-    .listen(
-        value => element.style.marginLeft = value
-    );
+    .range(1000, 2000)
+    .tween(0, 255)
+    .listen(value => microcontroller.setPWM(value))
 
 // make it go
 timeline.play();
@@ -56,11 +54,11 @@ timeline.play();
 const firstFiveSeconds = timeline.range(0, 5000);
 ```
 
-The range object is *listenable* and emits a progression value (between 0 and 1) when the Timeline's internal position passes through or over that period.
+The range object is *applyable* and emits a progression value (between 0 and 1) when the Timeline's internal position passes through or over that period.
 
 ```ts
 firstFiveSeconds
-    .listen(
+    .apply(
         value => console.log(`${value} is between 0 and 1`)
     );
 ```
@@ -74,20 +72,20 @@ const asPercent = firstFiveSeconds.map(n => n * 100);
 // use the result in a log message
 asPercent
     .map(n => n.toFixed(2))
-    .listen(
+    .apply(
         n => console.log(`We are ${n}% through the first five seconds`)
     );
 
 // and in a css property
 asPercent
     .map(n => `${n}%`)
-    .listen(
+    .apply(
         n => progressBar.style.width = n
     );
 
 // apply easing
 const eased = firstFiveSeconds.ease("easeInOut");
-eased.listen(
+eased.apply(
     v => console.log(`Eased value: ${v}`)
 );
 
@@ -98,7 +96,7 @@ range
     .dedupe()
     .tap(n => console.log("Showing frame #", n))
     .map(n => `animation-frame-${n}.png`)
-    .listen(filename => img.src = filename);
+    .apply(filename => img.src = filename);
 
 // each step in a chain is a 'pure', independent emitter that emits a
 // transformation of its parent's emissions
@@ -129,7 +127,7 @@ Custom easers can be passed to `ease()` as `(progress: number) => number`:
 ```ts
 timeline
     .range(0, 1000)
-    .ease(n => Math.sqrt(n))
+    .ease(n => n * n)
     .tween(/*...*/);
 ```
 
@@ -146,7 +144,7 @@ const sixSecondsIn = fiveSecondsdIn.delta(1000);
 Points emit `PointEvent` objects when their position is reached or passed.
 
 ```ts
-twoSecondsIn.listen(event => {
+twoSecondsIn.apply(event => {
     // event.direction (-1 | 1) tells us the direction of the seek that
     // triggered the point. This allows for reversible point events
     document.body.classList.toggle("someClass", event.direction > 0);
@@ -181,30 +179,30 @@ const range = timeline.range(0, 2000);
 range
     .ease("overshootIn")
     .tween(300, 500)
-    .listen(v => element.scrollTop = v);
+    .apply(v => element.scrollTop = v);
 
 // number arrays
 range
     .tween([0, 180], [360, 180])
-    .listen((angles) => pieChart.setValues(angles));
+    .apply((angles) => pieChart.setValues(angles));
 
 // strings
 range
     .tween("#000000", "#ff00ff")
-    .listen(v => element.style.color = v);
+    .apply(v => element.style.color = v);
 
 // blendable objects
 // (T extends { blend(from: this, to: this): this })
 import { RGBA } from "@xtia/rgba";
 range
     .tween(RGBA.parse("#c971a7"), RGBA.parse("#fff"))
-    .listen(v => element.style.background = v);
+    .apply(v => element.style.background = v);
 
 import { Angle } from "@xtia/mezr";
 range
     .tween(Angle.degrees(45), Angle.turns(.5))
     .map(a => `rotate(${a.asDegrees}deg)`)
-    .listen(v => element.style.transform = v);
+    .apply(v => element.style.transform = v);
 
 ```
 
@@ -218,14 +216,14 @@ timeline
     .range(0, 2000)
     .ease("elastic")
     .tween("0px 0px 0px #0000", "15px 15px 20px #0005")
-    .listen(s => element.style.textShadow = s);
+    .apply(s => element.style.textShadow = s);
 
 // text progress bar
 timeline
     .range(0, 2000)
     .tween("--------", "########")
     .dedupe()
-    .listen(v => document.title = v);
+    .apply(v => document.title = v);
 ```
 
 Try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
@@ -238,13 +236,13 @@ To create a Timeline that immediately starts playing, pass `true` to its constru
 // immediately fade in an element
 new Timeline(true)
     .range(0, 1000)
-    .listen(v => element.style.opacity = v);
+    .apply(v => element.style.opacity = v);
 
 // note, an `animate(duration)` function is exported for
 // disposable, single-use animations such as this:
 import { animate } from "@xtia/timeline";
 animate(1000)
-    .listen(v => element.style.opacity = v);
+    .apply(v => element.style.opacity = v);
 ```
 
 Normally a Timeline will simply stop playing when it reaches the end. This can be changed by passing a second argument (`endAction`) to the constructor.
@@ -302,19 +300,19 @@ window.addEventListener(
 setInterval(() => timeline.seek(Date.now()), 1000);
 timeline
     .point(new Date("2026-10-31").getTime())
-    .listen(() => console.log("Happy anniversary 🏳️‍⚧️💗"));
+    .apply(() => console.log("Happy anniversary 🏳️‍⚧️💗"));
 
 // show a progress bar for loaded resources
 const loadingTimeline = new Timeline();
 loadingTimeline
     .range(0, resourceUrls.length)
     .tween("0%", "100%");
-    .listen(v => progressBar.style.width = v);
+    .apply(v => progressBar.style.width = v);
 
 // and do something when they're loaded
 loadingTimeline
     .end
-    .listen(startGame);
+    .apply(startGame);
 
 // to drive it, just seek forward by 1 for each loaded resource
 resourceUrls.forEach(url => {
@@ -435,7 +433,7 @@ timeline
     .range(start, duration)
     .ease(easer)
     .tween(from, to)
-    .listen(apply);
+    .apply(apply);
 ```
 
 Returns a [`ChainingInterface`](#chaininginterface-interface) representing the point at which the tween ends.
@@ -491,6 +489,33 @@ Seeks the parent Timeline to this point.
 
 Smooth-seeks the parent Timeline to this point over a specified duration and resolves the returned Promise on completion.
 
+##### `promise(): Promise<-1 | 1>`
+
+Creates a `Promise` that will be resolved when the Timeline first seeks to/past this point.
+
+The resolved value indicates the direction of the seek that triggered resolution.
+
+##### `forwardOnly(): Emitter<PointEvent>`
+
+Creates an emitter that forwards emissions triggered by forward-moving seeks.
+
+##### `reverseOnly(): Emitter<PointEvent>`
+
+Creates an emitter that forwards emissions triggered by backward-moving seeks.
+
+##### `applyDirectional(apply, revert): UnsubscribeFunc`
+
+Registers an emission handler that calls one function for forward seeks to or past the point, and another for backward seeks from or past the point.
+
+```ts
+point
+    .applyDirectional(
+        element.classList.add("faded"),
+        element.classList.remove("faded"),
+    );
+```
+
+
 
 
 ### `PointEvent` interface
@@ -508,7 +533,7 @@ Allows point listeners to undo effects when the Timeline is reversed.
 ```ts
 timeline
     .point(4000)
-    .listen(
+    .apply(
         event => element.classList.toggle(
             "visible",
             event.direction > 0
@@ -565,10 +590,22 @@ Creates a new range on the parent Timeline. The location and duration of the new
 
 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.
 
-##### `contains(point)`
+##### `subdivide(n): TimelineRange[]`
+
+Creates the specified number of ranges, each of `(parent.duration / count)` duration, spread evenly over this range.
+
+##### `shift(delta): TimelineRange`
+
+Creates a new range by offsetting the parent by a given time delta.
+
+##### `contains(point): boolean`
 
 Returns true if the given [`TimelinePoint`](#timelinepoint-interface) sits within this range.
 
+##### `overlaps(range): boolean`
+
+Returns true if the given range overlaps with this range.
+
 
 
 
@@ -634,9 +671,20 @@ If `check(value)` returns true, the value will be emitted.
 
 Creates an emitter that discards emitted values that are the same as the last value emitted by the new emitter
 
+##### `sample<T>(items): T`
+
+Creates a chainable emitter that takes a value from an array according to progression.
+
+```ts
+range
+  .sample(["a", "b", "c"])
+  .apply(v => console.log(v));
+// logs 'b' when a seek lands halfway through range
+```
+
 ##### `offset(delta): RangeProgression`
 
-Creates an emitter that offsets its parent's values by the given delta, wrapping at 1
+Creates an emitter that offsets its parent's values by the given delta, wrapping at 1.
 
 ##### `fork(cb: (branch) => void): RangeProgression`
 
@@ -650,19 +698,18 @@ range
   .fork(branch => {
     branch
       .map(s => `Loading: ${s}`)
-      .listen(s => document.title = s)
+      .apply(s => document.title = s)
   })
-  .listen(v => progressBar.style.width = v);
+  .apply(v => progressBar.style.width = v);
 ```
 
 
 
-
 ### `Emitter<T>` interface
 
 #### Methods
 
-##### `listen(handler: Handler<T>): UnsubscribeFunc`
+##### `apply(handler: Handler<T>): UnsubscribeFunc`
 
 Attaches a handler to the emitter and returns a function that will unsubscribe the handler.
 
@@ -696,9 +743,9 @@ range
   .fork(branch => {
     branch
       .map(s => `Loading: ${s}`)
-      .listen(s => document.title = s)
+      .apply(s => document.title = s)
   })
-  .listen(v => progressBar.style.width = v);
+  .apply(v => progressBar.style.width = v);
 ```
 
 

package/internal/emitters.d.ts

@@ -16,11 +16,17 @@ export declare class Emitter<T> {
      */
     protected redirect: (listen: ListenFunc<T>) => Emitter<T>;
     /**
-     * Registers a function to receive emitted values
+     * Compatibility alias for `apply()` - registers a function to receive emitted values
      * @param handler
      * @returns A function to deregister the handler
      */
     listen(handler: Handler<T>): UnsubscribeFunc;
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    apply(handler: Handler<T>): UnsubscribeFunc;
     /**
      * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
      * @param mapFunc
@@ -65,9 +71,9 @@ export declare class Emitter<T> {
      *   .fork(branch => {
      *     branch
      *       .map(s => `Loading: ${s}`)
-     *       .listen(s => document.title = s)
+     *       .apply(s => document.title = s)
      *   })
-     *   .listen(v => progressBar.style.width = v);
+     *   .apply(v => progressBar.style.width = v);
      * ```
      * @param cb
      */
@@ -106,7 +112,7 @@ export declare class RangeProgression extends Emitter<number> {
      * ```ts
      * range
      *   .tween("0px 0px 0px #0000", "4px 4px 8px #0005")
-     *   .listen(s => element.style.textShadow = s);
+     *   .apply(s => element.style.textShadow = s);
      * ```
      *
      * @param from Value to interpolate from
@@ -132,7 +138,7 @@ export declare class RangeProgression extends Emitter<number> {
      * ```ts
      * range
      *   .sample(["a", "b", "c"])
-     *   .listen(v => console.log(v));
+     *   .apply(v => console.log(v));
      * // logs 'b' when a seek lands halfway through range
      * ```
      * @param source array to sample

package/internal/emitters.js

@@ -15,7 +15,7 @@ export class Emitter {
         this.redirect = (listen) => new Emitter(listen);
     }
     /**
-     * Registers a function to receive emitted values
+     * Compatibility alias for `apply()` - registers a function to receive emitted values
      * @param handler
      * @returns A function to deregister the handler
      */
@@ -24,6 +24,16 @@ export class Emitter {
             handler(value);
         });
     }
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    apply(handler) {
+        return this.onListen((value) => {
+            handler(value);
+        });
+    }
     /**
      * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
      * @param mapFunc
@@ -111,9 +121,9 @@ export class Emitter {
      *   .fork(branch => {
      *     branch
      *       .map(s => `Loading: ${s}`)
-     *       .listen(s => document.title = s)
+     *       .apply(s => document.title = s)
      *   })
-     *   .listen(v => progressBar.style.width = v);
+     *   .apply(v => progressBar.style.width = v);
      * ```
      * @param cb
      */
@@ -148,7 +158,7 @@ export class RangeProgression extends Emitter {
      * ```ts
      * range
      *   .sample(["a", "b", "c"])
-     *   .listen(v => console.log(v));
+     *   .apply(v => console.log(v));
      * // logs 'b' when a seek lands halfway through range
      * ```
      * @param source array to sample
@@ -174,7 +184,7 @@ export class RangeProgression extends Emitter {
         }
         return new RangeProgression(handler => this.onListen(progress => {
             const snapped = Math.round(progress * steps) / steps;
-            handler(clamp(snapped));
+            handler(snapped);
         }));
     }
     /**

package/internal/point.d.ts

@@ -1,5 +1,5 @@
 import { Easer } from "./easing";
-import { Emitter, ListenFunc } from "./emitters";
+import { Emitter, ListenFunc, UnsubscribeFunc } from "./emitters";
 import { TimelineRange } from "./range";
 import { Timeline } from "./timeline";
 export type PointEvent = {
@@ -41,4 +41,42 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      */
     seek(): void;
     seek(duration: number, easer?: Easer): Promise<void>;
+    /**
+     * Creates an emitter that only emits on forward-moving seeks
+     * @returns
+     */
+    forwardOnly(): Emitter<PointEvent>;
+    /**
+     * Creates an emitter that only emits on backward-moving seeks
+     * @returns
+     */
+    reverseOnly(): Emitter<PointEvent>;
+    /**
+     * Creates a Promise that will be resolved when the Timeline first seeks to/past this point
+     *
+     * The resolved value indicates the direction of the seek that triggered resolution
+     *
+     * @returns A Promise, resolved when the point is triggered by a seek
+     */
+    promise(): Promise<1 | -1>;
+    /**
+     * Registers a pair of functions to handle seeks that reach or pass this point, depending on seek direction
+     *
+     * @example
+     * ```
+     * point
+     * 	.applyDirectional(
+     *     element.classList.add("faded"),
+     *     element.classList.remove("faded"),
+     *   );
+     * ```
+     *
+     * Note, for deterministic consistency, a forward-seek triggers points when it
+     * *passes or reaches* them, while a backward-seek triggers points when it
+     * *passes or departs from* them.
+     * @param apply Handler for forward-moving seeks that pass or reach this point
+     * @param revert Handler for backward-moving seeks that pass this point
+     * @returns A function to deregister both handlers
+     */
+    applyDirectional(apply: () => void, revert: () => void): UnsubscribeFunc;
 }

package/internal/point.js

@@ -41,4 +41,67 @@ export class TimelinePoint extends Emitter {
     seek(duration = 0, easer) {
         return this.timeline.seek(this.position, duration, easer);
     }
+    /**
+     * Creates an emitter that only emits on forward-moving seeks
+     * @returns
+     */
+    forwardOnly() {
+        return new Emitter(handler => {
+            return this.onListen((ev) => {
+                if (ev.direction > 0)
+                    handler(ev);
+            });
+        });
+    }
+    /**
+     * Creates an emitter that only emits on backward-moving seeks
+     * @returns
+     */
+    reverseOnly() {
+        return new Emitter(handler => {
+            return this.onListen((ev) => {
+                if (ev.direction < 0)
+                    handler(ev);
+            });
+        });
+    }
+    /**
+     * Creates a Promise that will be resolved when the Timeline first seeks to/past this point
+     *
+     * The resolved value indicates the direction of the seek that triggered resolution
+     *
+     * @returns A Promise, resolved when the point is triggered by a seek
+     */
+    promise() {
+        return new Promise(resolve => {
+            let remove = this.apply((ev) => {
+                remove();
+                resolve(ev.direction);
+            });
+        });
+    }
+    /**
+     * Registers a pair of functions to handle seeks that reach or pass this point, depending on seek direction
+     *
+     * @example
+     * ```
+     * point
+     * 	.applyDirectional(
+     *     element.classList.add("faded"),
+     *     element.classList.remove("faded"),
+     *   );
+     * ```
+     *
+     * Note, for deterministic consistency, a forward-seek triggers points when it
+     * *passes or reaches* them, while a backward-seek triggers points when it
+     * *passes or departs from* them.
+     * @param apply Handler for forward-moving seeks that pass or reach this point
+     * @param revert Handler for backward-moving seeks that pass this point
+     * @returns A function to deregister both handlers
+     */
+    applyDirectional(apply, revert) {
+        return this.onListen(eventData => eventData.direction > 0
+            ? apply()
+            : revert());
+    }
 }

package/internal/range.d.ts

@@ -32,8 +32,22 @@ export declare class TimelineRange extends RangeProgression {
      */
     spread(count: number): TimelinePoint[];
     /**
-     * Progresses the Timeline across the range
-     * @param easer
+     * Creates the specified number of ranges, each of `(parent.duration / count)` duration, spread
+     * evenly over this range
+     * @param count Number of sub-ranges to create
+     * @returns Array of sub-ranges
+     */
+    subdivide(count: number): TimelineRange[];
+    /**
+     * Creates a new range by offsetting the parent by a given time delta
+     * @param delta
+     * @returns Offset range
+     */
+    shift(delta: number): TimelineRange;
+    /**
+     * Progresses the Timeline across the range at 1000 units per second
+     * @param easer Optional easing function
+     * @returns Promise, resolved when the end is reached
      */
     play(easer?: Easer | keyof typeof easers): Promise<void>;
     /**

package/internal/range.js

@@ -44,8 +44,27 @@ export class TimelineRange extends RangeProgression {
         ];
     }
     /**
-     * Progresses the Timeline across the range
-     * @param easer
+     * Creates the specified number of ranges, each of `(parent.duration / count)` duration, spread
+     * evenly over this range
+     * @param count Number of sub-ranges to create
+     * @returns Array of sub-ranges
+     */
+    subdivide(count) {
+        const duration = this.duration / count;
+        return Array.from({ length: count }, (_, i) => this.timeline.range(this.startPosition + i * duration, duration));
+    }
+    /**
+     * Creates a new range by offsetting the parent by a given time delta
+     * @param delta
+     * @returns Offset range
+     */
+    shift(delta) {
+        return this.timeline.range(this.startPosition + delta, this.duration);
+    }
+    /**
+     * Progresses the Timeline across the range at 1000 units per second
+     * @param easer Optional easing function
+     * @returns Promise, resolved when the end is reached
      */
     play(easer) {
         this.timeline.pause();
@@ -78,7 +97,7 @@ export class TimelineRange extends RangeProgression {
      */
     scale(factor, anchor = 0) {
         if (factor <= 0) {
-            throw new RangeError('scale factor must be > 0');
+            throw new RangeError('Scale factor must be > 0');
         }
         const clampedAnchor = clamp(anchor, 0, 1);
         const oldLen = this.endPosition - this.startPosition;

package/internal/timeline.js

@@ -184,7 +184,7 @@ export class Timeline {
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
             // ensure any awaits are resolved for the previous seek
-            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker.end.seek();
             this.smoothSeeker = null;
         }
         if (duration === 0) {
@@ -193,8 +193,8 @@ export class Timeline {
         }
         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()));
+        seeker.range(0, duration).ease(easer).tween(this.currentTime, toPosition).apply(v => this.seekDirect(v));
+        return new Promise(r => seeker.end.apply(() => r()));
     }
     seekDirect(toPosition) {
         const fromPosition = this._currentTime;
@@ -321,7 +321,7 @@ export class Timeline {
         const duration = typeof durationOrToPoint == "number"
             ? durationOrToPoint
             : (durationOrToPoint.position - startPosition);
-        this.range(startPosition, duration).ease(easer).tween(from, to).listen(apply);
+        this.range(startPosition, duration).ease(easer).tween(from, to).apply(apply);
         return this.createChainingInterface(startPosition + duration);
     }
     at(position, action, reverse) {
@@ -329,7 +329,7 @@ export class Timeline {
         if (reverse === true)
             reverse = action;
         if (action)
-            point.listen(reverse
+            point.apply(reverse
                 ? (event => event.direction < 0 ? reverse() : action)
                 : action);
         return this.createChainingInterface(point.position);

package/package.json

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