@xtia/timeline 1.1.0 → 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)
@@ -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))
     .apply(
         s => element.textContent = s
     );
 
-// use an easing function
+// control anything:
 timeline
-    .range(0, 3000)
-    .ease("bounce")
-    .tween("50%", "0%")
-    .apply(
-        value => element.style.marginLeft = value
-    );
+    .range(1000, 2000)
+    .tween(0, 255)
+    .listen(value => microcontroller.setPWM(value))
 
 // make it go
 timeline.play();
@@ -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(/*...*/);
 ```
 
@@ -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
@@ -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`
 
@@ -657,7 +705,6 @@ range
 
 
 
-
 ### `Emitter<T>` interface
 
 #### Methods

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/package.json

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