@xtia/timeline 1.1.0 → 1.1.2

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, seekable, 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)
@@ -17,7 +17,7 @@ import { Timeline } from "@xtia/timeline";
 // create a Timeline
 const timeline = new Timeline();
 
-// over the first second, fade the body's background colour
+// over the first second, fade an element's background colour
 timeline
     .range(0, 1000)
     .tween("#646", "#000")
@@ -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/internal/timeline.d.ts

@@ -151,6 +151,7 @@ export interface ChainingInterface {
     thenTween<T extends Tweenable>(duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer: Easer): ChainingInterface;
     then(action: () => void): ChainingInterface;
     thenWait(duration: number): ChainingInterface;
+    fork(fn: (chain: ChainingInterface) => void): ChainingInterface;
     readonly end: TimelinePoint;
 }
 export {};

package/internal/timeline.js

@@ -330,12 +330,12 @@ export class Timeline {
             reverse = action;
         if (action)
             point.apply(reverse
-                ? (event => event.direction < 0 ? reverse() : action)
+                ? (event => event.direction < 0 ? reverse() : action())
                 : action);
         return this.createChainingInterface(point.position);
     }
     createChainingInterface(position) {
-        return {
+        const chain = {
             thenTween: (duration, apply, from, to, easer) => {
                 return this.tween(position, duration, apply, from, to, easer);
             },
@@ -344,8 +344,13 @@ export class Timeline {
                 this.point(position + delay);
                 return this.createChainingInterface(position + delay);
             },
+            fork: fn => {
+                fn(chain);
+                return chain;
+            },
             end: this.point(position),
         };
+        return chain;
     }
     /**
      * @deprecated use `timeline.currentTime`

package/internal/tween.js

@@ -1,9 +1,11 @@
 import { clamp } from "./utils";
-const tokenTypes = {
-    none: 0,
-    number: 1,
-    colour: 2,
-};
+var TokenTypes;
+(function (TokenTypes) {
+    TokenTypes[TokenTypes["none"] = 0] = "none";
+    TokenTypes[TokenTypes["number"] = 1] = "number";
+    TokenTypes[TokenTypes["colour"] = 2] = "colour";
+})(TokenTypes || (TokenTypes = {}));
+;
 export function createTween(from, to) {
     if (from === to)
         return () => from;
@@ -39,9 +41,9 @@ function createStringTween(from, to) {
         const fromToken = chunk.token;
         const toToken = toChunks[i].token;
         const prefix = chunk.prefix;
-        if (chunk.type === tokenTypes.none)
+        if (chunk.type === TokenTypes.none)
             return () => prefix;
-        if (chunk.type === tokenTypes.colour) {
+        if (chunk.type === TokenTypes.colour) {
             const fromColour = parseColour(fromToken);
             const toColour = parseColour(toToken);
             return progress => prefix + blendColours(fromColour, toColour, progress);
@@ -142,13 +144,13 @@ function tokenise(s) {
     // trailing literal after the last token – stored as a final chunk
     const tail = s.slice(lastIdx);
     if (tail.length) {
-        chunks.push({ prefix: tail, token: "", type: tokenTypes.none });
+        chunks.push({ prefix: tail, token: "", type: TokenTypes.none });
     }
     return chunks;
 }
 ;
 function getTokenType(token) {
     if (token.startsWith("#"))
-        return tokenTypes.colour;
-    return tokenTypes.number;
+        return TokenTypes.colour;
+    return TokenTypes.number;
 }

package/package.json

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