@xtia/timeline 1.0.5 → 1.0.7

package/README.md

@@ -4,6 +4,7 @@
 
 **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.
 
+* [API Reference](#reference)
 
 ## Basic Use:
 
@@ -33,8 +34,9 @@ timeline
     );
 
 // use an easing function
-typingRange
+timeline
     .end
+    .delta(500)
     .range(3000)
     .ease("bounce")
     .tween("50%", "0%")
@@ -93,7 +95,7 @@ eased.listen(
 const frames = eased
     .tween(0, 30)
     .map(Math.floor)
-    .noRepeat()
+    .dedupe()
     .tap(n => console.log("Showing frame #", n))
     .map(n => `animation-frame-${n}.png`)
     .listen(filename => img.src = filename);
@@ -164,7 +166,6 @@ Tween emitters can interpolate numbers, arrays of numbers, strings, and objects
 
 ```ts
 // tween four values in a CSS string
-// see this live: https://codepen.io/xtaltia/pen/PwZYbKY
 timeline
     .range(0, 2000)
     .ease("elastic")
@@ -175,9 +176,12 @@ timeline
 timeline
     .range(0, 2000)
     .tween("--------", "########")
+    .dedupe()
     .listen(v => document.title = v);
 ```
 
+You can try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
+
 ## Autoplay and Looping Strategies
 
 To create a Timeline that immediately starts playing, pass `true` to its constructor:
@@ -259,10 +263,12 @@ loadingTimeline
     .tween("0%", "100%");
     .listen(v => progressBar.style.width = v);
 
+// and do something when they're loaded
 loadingTimeline
     .end
     .listen(startGame);
 
+// to drive it, just seek forward by 1 for each loaded resource
 resourceUrls.forEach(url => {
     preload(url).then(
         () => loadingTimeline.currentTime++
@@ -278,7 +284,7 @@ timeline.seek(timeline.end, 400, "overshootIn");
 
 ## Backward-compatibility
 
-Despite the massive overhaul, the previous API is present and expanded  and upgrading to 1.0.0 should be frictionless in the vast majority of cases.
+Despite the massive overhaul, the previous API is present and expanded and upgrading to 1.0.0 should be frictionless in the vast majority of cases.
 
 #### Breaking changes
 
@@ -287,7 +293,7 @@ Despite the massive overhaul, the previous API is present and expanded  and upgr
 #### Mitigation
 
 * `timeline.tween()` now accepts TimelinePoint as a starting position, and provides an overload that replaces the `duration: number` parameter with `end: TimelinePoint`.
-* Should you encounter a case where this change still causes issue, eg `tl.tween(0, tl.end / 2, ...)`, `tl.end.position` is equivalent to the old API's `tl.end`.
+* Should you encounter a case where this change still causes issue, eg `timeline.tween(0, timeline.end / 2, ...)`, `timeline.end.position` is equivalent to the old API's `timeline.end`.
 
 #### Enhancements (non-breaking)
 
@@ -298,4 +304,402 @@ Despite the massive overhaul, the previous API is present and expanded  and upgr
 
 * `timeline.position` will be replaced with `timeline.currentTime` to be consistent with other seekable concepts.
 * `"loop"` endAction is now `"restart"` to disambiguate from new looping strategies.
-* `timeline.step()` is redundant now that `currentTime` is writable; use `timeline.currentTime += delta` instead.
+* `timeline.step()` is redundant now that `currentTime` is writable; use `timeline.currentTime += delta` instead.
+
+
+
+## Reference
+
+### `Timeline` class
+
+A self-contained collection of points and ranges that trigger events as the Timeline seeks to and through them.
+
+#### Properties
+
+##### `currentTime: number`
+
+Reads or sets the Timeline's current time position. Setting this property will perform a `seek()`, triggering any listener that is passed or landed on.
+
+##### `timeScale: number`
+
+Controls the speed at which a Timeline will progress when driven by the `play()` method (including by autoplay).
+
+##### `isPlaying: boolean`
+
+Returns true if the Timeline is actively being driven by the `play()` method (including by autoplay).
+
+##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+
+Returns the **current** final point in the Timeline.
+
+##### `start: `[`TimelinePoint`](#timelinepoint-interface)
+
+Returns a point representing position 0.
+
+#### Methods
+
+##### `point(position): `[`TimelinePoint`](#timelinepoint-interface)
+
+Returns a point that represents a specific position on the Timeline.
+
+If `position` is greater than that Timeline's end-position, the end-position will be extended to `position`.
+
+*Note*, for deterministic consistency, points will be triggered if a forward-moving seek lands exactly on the point's position (or passes it entirely), while a backward-moving seek will trigger points that are passed or moved from.
+
+##### `range(start, duration): `[`TimelineRange`](#timelinerange-interface)
+
+Returns a range that represents a section of the Timeline.
+
+If the end of the range is beyond the Timeline's end-position, the end-position will be extended to the end of the range.
+
+If `duration` is omitted, the range will extend from `start` to the **current** end-position of the Timeline.
+
+If `start` is omitted, the range will start at 0 and represent the full **current** range of the Timeline.
+
+##### `seek(toPosition): void`
+
+Sets the Timeline's internal position (`currentTime`), triggering in chronological order listeners attached to any [`TimelinePoint`](#timelinepoint-interface) or [`TimelineRange`](#timelinerange-interface) that are passed or landed on.
+
+##### `seek(toPosition, duration, easer?): Promise<void>`
+
+Performs an interruptable 'smooth seek' to a specified position, lasting `duration` milliseconds, with optional easing.
+
+Returns a Promise that will be resolved when the smooth seek is completed (or is interrupted by another seek\*).
+
+\* Resolution on interruption is not finalised in the library's design and the effect should be considered exceptional; relying on it is not recommended. Future versions might reject the promise when its seek is interrupted.
+
+##### `play(): void`
+
+Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating 60 times per second.
+
+##### `play(fps): void`
+
+Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating `fps` times per second.
+
+##### `tween<T>(start, duration, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
+
+Creates a [`TimelineRange`](#timelinerange-interface) and attaches a tweening listener.
+
+Equivalent to
+
+```ts
+timeline
+    .range(start, duration)
+    .ease(easer)
+    .tween(from, to)
+    .listen(apply);
+```
+
+Returns a [`ChainingInterface`](#chaininginterface-interface) representing the point at which the tween ends.
+
+##### `tween<T>(start, end, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
+
+As above, but if the second argument is a [`TimelinePoint`](#timelinepoint-interface), it will specify when on the Timeline the tween will *end*.
+
+##### `at(position, apply, reverse?): `[`ChainingInterface`](#chaininginterface-interface)
+
+Creates a [`TimelinePoint`](#timelinepoint-interface) and attaches a listener that will trigger when the Timeline seeks past or to that point.
+
+If `reverse` is a function, that will be called instead of `apply` when the seek that triggered the event was moving backwards. If `reverse` is `true`, `apply` will be called regardless of which direction the seek moved. If `reverse` is false or omitted, this listener will ignore backward-moving seeks.
+
+
+
+
+### `TimelinePoint` interface
+
+Represents a single point on a [`Timeline`](#timeline-class).
+
+##### Inherits [`Emitter<PointEvent>`](#emittert-interface)
+
+Listeners will be invoked with a [`PointEvent`](#pointevent-interface) when a seek passes or lands on the point.
+
+*Note*, during a point event, the parent Timeline's `currentTime` property will return that point's position, even if the Timeline is configured with a [*wrap* end action](#autoplay-and-looping-strategies) and its true position is beyond its end. For deterministic consistency, ranges will emit values for the point's position before the point emits.
+
+#### Properties
+
+##### `position: number`
+
+This point's position on the Timeline.
+
+#### Methods
+
+##### `range(duration): TimelineRange`
+
+Creates a [`TimelineRange`](#timelinerange-interface) on the Timeline to which the point belongs, of the specified duration.
+
+##### `to(endPoint): TimelineRange`
+
+Creates a [`TimelineRange`](#timelinerange-interface) on the Timeline to which the point belongs, ending at the specified point.
+
+##### `delta(timeOffset): TimelinePoint`
+
+Creates a `TimelinePoint` at an offset from the this point.
+
+
+
+
+### `PointEvent` interface
+
+Provides information relevant to [`TimelinePoint`](#timelinepoint-interface) events.
+
+#### Properties
+
+##### `direction: -1 | 1`
+
+Provides the direction of the seek that triggered a point event. `direction === 1` indicates that the seek moved forward and `direction === -1` indicates that the seek was moving backwards.
+
+Allows point listeners to undo effects when the Timeline is reversed.
+
+```ts
+timeline
+    .point(4000)
+    .listen(
+        event => element.classList.toggle(
+            "visible",
+            event.direction > 0
+        )
+    );
+```
+
+
+
+
+### `TimelineRange` interface
+
+Represents a fixed-length, fixed position section of a [`Timeline`](#timeline-class).
+
+##### Inherits [`RangeProgression`](#rangeprogression-interface)
+
+Emits a normalised progression (0..1) of the range when the parent Timeline seeks over or into it.
+
+#### Properties
+
+##### `start: `[`TimelinePoint`](#timelinepoint-interface)
+
+The point on the Timeline at which this range starts.
+
+##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+
+The point on the Timeline at which this range ends.
+
+##### `duration: number`
+
+The length of the range.
+
+#### Methods
+
+##### `bisect(position?): [TimelineRange, TimelineRange]`
+
+Creates two ranges representing two distinct sections of the parent. `position` is relative to the parent's start.
+
+##### `spread(count): `[`TimelinePoint`](#timelinepoint-interface)[]
+
+Creates and returns `count` points spread evenly over the range.
+
+##### `play(easer?): Promise<void>`
+
+Instructs the Timeline to which this range belongs to play through the represented range. This playthrough counts as a smooth seek for seek interruption purposes.
+
+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.
+
+##### `contains(point)`
+
+Returns true if the given [`TimelinePoint`](#timelinepoint-interface) sits within this range.
+
+
+
+
+### `RangeProgression` interface
+
+Represents a step in an immutable [`TimelineRange`](#timelinerange-interface) event transformation pipeline.
+
+##### Inherits [`Emitter<number>`](#emittert-interface)
+
+Listeners will be invoked when a seek passes or lands within a range.
+
+#### Methods
+
+##### `ease(easer?): RangeProgression`
+
+Creates an emitter that applies an easing function to parent emissions.
+
+##### `tween<T>(from, to): `[`Emitter<T>`](#emittert-interface)
+
+Creates an emitter blends two values, biased by progression emitted by the parent.
+
+`T` may be `string`, `number`, `number[]` or an object type that includes
+
+```ts
+blend(from: this, to: this, progress: number): this
+```
+
+##### `snap(steps): RangeProgression`
+
+Creates an emitter that quantises progression emitted by the parent to the nearest of `steps` discrete values.
+
+##### `threshold(threshold): RangeProgression`
+
+Creates an emitter that emits 0 when the parent emits a value below `threshold` and 1 when a parent emission is equal to or greater than `threshold`.
+
+```ts
+emittedValue = parentEmission < threshold ? 0 : 1
+```
+
+##### `clamp(min?, max?): RangeProgression`
+
+Creates an emitter that clamps progression between `min` and `max`.
+
+##### `repeat(count): RangeProgression`
+
+Creates an emitter that multiplies progression and wraps at 1, thereby mapping to a repeating scale.
+
+##### `tap(cb): RangeProgression`
+
+Creates an emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+
+##### `filter(check: (value) => boolean): RangeProgression`
+
+Creates an emitter that selectively discards parent emissions.
+
+If `check(value)` returns true, the value will be emitted.
+
+##### `dedupe(): RangeProgression`
+
+Creates an emitter that discards emitted values that are the same as the last value emitted by the new emitter
+
+##### `offset(delta): RangeProgression`
+
+Creates an emitter that offsets its parent's values by the given delta, wrapping at 1
+
+##### `fork(cb: (branch) => void): RangeProgression`
+
+Immediately invokes `cb` with this emitter and returns this emitter for further chaining.
+
+Allows branching without breaking a composition chain, eg:
+
+```ts
+range
+  .tween("0%", "100%")
+  .fork(branch => {
+    branch
+      .map(s => `Loading: ${s}`)
+      .listen(s => document.title = s)
+  })
+  .listen(v => progressBar.style.width = v);
+```
+
+
+
+
+### `Emitter<T>` interface
+
+#### Methods
+
+##### `listen(handler: Handler<T>): UnsubscribeFunc`
+
+Attaches a handler to the emitter and returns a function that will unsubscribe the handler.
+
+##### `map<R>(mapFunc: (value: T) => R): Emitter<R>`
+
+Creates an emitter that performs an arbitrary transformation.
+
+##### `filter(check: (value: T) => boolean): Emitter<T>`
+
+Creates an emitter that selectively discards parent emissions.
+
+If `check(value)` returns true, the value will be emitted.
+
+##### `dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>`
+
+Creates an emitter that discards emitted values that are the same as the last value emitted by the new emitter
+
+##### `tap(cb: Handler<T>): Emitter<T>`
+
+Creates an emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+
+##### `fork(cb: (branch: Emitter<T>) => void): Emitter<T>`
+
+Immediately invokes `cb` with this emitter and returns this emitter for further chaining.
+
+Allows branching without breaking a composition chain, eg:
+
+```ts
+range
+  .tween("0%", "100%")
+  .fork(branch => {
+    branch
+      .map(s => `Loading: ${s}`)
+      .listen(s => document.title = s)
+  })
+  .listen(v => progressBar.style.width = v);
+```
+
+
+
+
+### `animate(duration)` function
+
+Creates and returns a [`TimelineRange`](#timelinerange-interface) that will automatically play over `duration` milliseconds.
+
+### `ChainingInterface` interface
+
+Conveys composable sequential tweens and events with the simplified API. Each instance represents a specific point on the parent Timeline.
+
+```ts
+timeline
+    .tween(0, 1000, doThing, 0, 100)
+    .thenWait(500)
+    .then(doOtherThing)
+    .thenWait(250)
+    .thenTween(2000, dothing, 100, 0);
+```
+
+#### Properties
+
+##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+
+The point on the Timeline at which the effect of the previous chained call ends.
+
+#### Methods
+
+##### `thenTween(duration, apply, from, to, easer): ChainingInterface`
+
+Adds a tween, beginning at the point the interface represents. Returns a new `ChainingInterface` representing the end of the new tween.
+
+##### `then(action: () => void): ChainingInterface`
+
+Adds a point event at the point the interface represents.
+
+##### `thenWait(duration): ChainingInterface`
+
+Creates a new `ChainingInterface` by offsetting the parent by `duration`.
+
+
+
+### `easers` const
+
+The following easers are provided:
+
+`linear`, `easeIn`, `easeIn4`, `easeOut`, `easeOut4`, `circleIn`, `circleIn4`, `circleOut`, `circleOut4`, `easeInOut`, `elastic`, `overshootIn`, `sine`, `invert`, `bounce`, `noise`, `pingpong`
+
+Methods that accept an easing function accept both `(progress: number) => number` and any of the names above.
+
+```ts
+timeline
+    .tween(s, e, a, f, t, v => Math.sqrt(v))
+    .thenTween(s, e, a, f, t, c, "elastic");
+
+timeline
+    .range(0, 1000)
+    .ease("circleOut")
+    .ease(easers.easeIn)
+    // ...
+```

package/index.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.easers = exports.animate = exports.Timeline = void 0;
+exports.easers = exports.RangeProgression = exports.Emitter = exports.TimelineRange = exports.TimelinePoint = exports.animate = exports.Timeline = void 0;
 var timeline_1 = require("./internal/timeline");
 Object.defineProperty(exports, "Timeline", { enumerable: true, get: function () { return timeline_1.Timeline; } });
 Object.defineProperty(exports, "animate", { enumerable: true, get: function () { return timeline_1.animate; } });
+var point_1 = require("./internal/point");
+Object.defineProperty(exports, "TimelinePoint", { enumerable: true, get: function () { return point_1.TimelinePoint; } });
+var range_1 = require("./internal/range");
+Object.defineProperty(exports, "TimelineRange", { enumerable: true, get: function () { return range_1.TimelineRange; } });
+var emitters_1 = require("./internal/emitters");
+Object.defineProperty(exports, "Emitter", { enumerable: true, get: function () { return emitters_1.Emitter; } });
+Object.defineProperty(exports, "RangeProgression", { enumerable: true, get: function () { return emitters_1.RangeProgression; } });
 var easing_1 = require("./internal/easing");
 Object.defineProperty(exports, "easers", { enumerable: true, get: function () { return easing_1.easers; } });

package/internal/emitters.d.ts

@@ -1,17 +1,19 @@
 import { Easer, easers } from "./easing";
-import { Blendable } from "./tween";
-/** @internal */
-export declare function createEmitter<T>(listen: ListenFunc<T>): Emitter<T>;
-/** @internal */
-export declare function createEmitter<T, API extends object>(onListen: ListenFunc<T>, api: Omit<API, keyof Emitter<T>>): Emitter<T> & API;
-/** @internal */
-export declare function createProgressEmitter<API extends object>(onListen: ListenFunc<number>, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
-/** @internal */
-export declare function createProgressEmitter(onListen: ListenFunc<number>): RangeProgression;
+import { Tweenable } from "./tween";
 type Handler<T> = (value: T) => void;
-type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
+export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
-export interface Emitter<T> {
+export declare class Emitter<T> {
+    protected onListen: ListenFunc<T>;
+    protected constructor(onListen: ListenFunc<T>);
+    /**
+     * Used by tap() to create a clone of an Emitter with a redirected onListen
+     * Should be overridden in all Emitter subclasses
+     * @see {@link TimelineRange.redirect}
+     * @param listen
+     * @returns {this}
+     */
+    protected redirect: (listen: ListenFunc<T>) => Emitter<T>;
     /**
      * Registers a function to receive emitted values
      * @param handler
@@ -37,7 +39,7 @@ export interface Emitter<T> {
      * If no `compare` function is provided, values will be compared via `===`
      * @returns Listenable: emits non-repeating values
      */
-    noRepeat(compare?: (a: T, b: T) => boolean): Emitter<T>;
+    dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>;
     /**
      * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
      *
@@ -49,9 +51,29 @@ export interface Emitter<T> {
      * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
-    tap(cb: Handler<T>): Emitter<T>;
+    tap(cb: Handler<T>): this;
+    /**
+     * Immediately passes this emitter to a callback and returns this emitter
+     *
+     * Allows branching without breaking a composition chain
+     *
+     * @example
+     * ```ts
+     * range
+     *   .tween("0%", "100%")
+     *   .fork(branch => {
+     *     branch
+     *       .map(s => `Loading: ${s}`)
+     *       .listen(s => document.title = s)
+     *   })
+     *   .listen(v => progressBar.style.width = v);
+     * ```
+     * @param cb
+     */
+    fork(cb: (branch: this) => void): this;
 }
-export interface RangeProgression extends Emitter<number> {
+export declare class RangeProgression extends Emitter<number> {
+    protected redirect: (listen: ListenFunc<number>) => RangeProgression;
     /**
      * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
      *
@@ -59,6 +81,7 @@ export interface RangeProgression extends Emitter<number> {
      * @returns Listenable: emits eased progression values
      */
     ease(easer?: Easer | keyof typeof easers): RangeProgression;
+    ease(easer?: undefined): RangeProgression;
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
@@ -99,7 +122,7 @@ export interface RangeProgression extends Emitter<number> {
      * @param to Value to interpolate to
      * @returns Listenable: emits interpolated values
      */
-    tween<T extends Blendable | number[]>(from: T, to: T): Emitter<T>;
+    tween<T extends Tweenable>(from: T, to: T): Emitter<T>;
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
      *
@@ -124,21 +147,23 @@ export interface RangeProgression extends Emitter<number> {
     clamp(min?: number, max?: number): RangeProgression;
     /**
      * Creates a chainable progress emitter that maps incoming values to a repeating linear scale
-     * @param count Number of repetitions
-     */
-    repeat(count: number): RangeProgression;
-    /**
-     * Creates a chainable progress emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
-     *
-     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
-     * All listeners attached to the returned emitter receive the same values as the parent emitter.
      *
-     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     * ```plain
+     * 	count=2
+     *‎	1
+     *‎	 |     /     /
+     *‎	o|    /     /
+     *‎	u|   /     /
+     *‎	t|  /     /
+     *‎	 | /     /
+     *‎	 |/_____/_____
+     *‎	0     in      1
+     * ```
      *
-     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
-     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     * @param count Number of repetitions
+     * @returns Listenable: emits scaled and repeating values
      */
-    tap(cb: (value: number) => void): RangeProgression;
+    repeat(count: number): RangeProgression;
     /**
      * Creates a chainable progress emitter that selectively forwards emissions along the chain
      * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
@@ -149,9 +174,9 @@ export interface RangeProgression extends Emitter<number> {
      * Creates a chainable progress emitter that discards emitted values that are the same as the last value emitted by the new emitter
      * @returns Listenable: emits non-repeating values
      */
-    noRepeat(): RangeProgression;
+    dedupe(): RangeProgression;
     /**
-     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping between 0 and 1
+     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
      *
      * ```plain
      *‎	1
@@ -165,6 +190,7 @@ export interface RangeProgression extends Emitter<number> {
      * ```
      *
      * @param delta
+     * @returns Listenable: emits offset values
      */
     offset(delta: number): RangeProgression;
 }