@xtia/timeline 1.0.2 → 1.0.4

package/README.md

@@ -94,6 +94,7 @@ const frames = eased
     .tween(0, 30)
     .map(Math.floor)
     .noRepeat()
+    .tap(n => console.log("Showing frame #", n))
     .map(n => `animation-frame-${n}.png`)
     .listen(filename => img.src = filename);
 ```
@@ -162,7 +163,8 @@ Tween emitters can interpolate numbers, arrays of numbers, strings, and objects
 * Otherwise the `from` string is progressively replaced, left-to-right, with the `to` string
 
 ```ts
-// note: this looks really cool
+// tween four values in a CSS string
+// see this live: https://codepen.io/xtaltia/pen/PwZYbKY
 timeline
     .range(0, 2000)
     .ease("elastic")
@@ -231,9 +233,10 @@ timeline.currentTime += 500;
 Seeking lets us control a Timeline with anything:
 
 ```ts
-// syncronise with a video, to show subtitles or related
+// synchronise with a video, to show subtitles or related
 // activities:
 videoElement.addEventListener(
+    "timeupdate",
     () => timeline.seek(videoElement.currentTime)
 );
 

package/index.d.ts

@@ -1,5 +1,5 @@
 export { Timeline, animate, ChainingInterface } from "./internal/timeline";
 export { TimelinePoint, PointEvent } from "./internal/point";
-export { RangeProgression, TimelineRange } from "./internal/range";
-export { Emitter, UnsubscribeFunc } from "./internal/emitters";
+export { TimelineRange } from "./internal/range";
+export { Emitter, RangeProgression, UnsubscribeFunc } from "./internal/emitters";
 export { easers } from "./internal/easing";

package/internal/emitters.d.ts

@@ -1,13 +1,15 @@
-import { RangeProgression } from "./range";
+import { Easer, easers } from "./easing";
+import { Blendable } from "./tween";
 /** @internal */
-export declare function createEmitter<T>(onListen: (handler: Handler<T>) => UnsubscribeFunc): Emitter<T>;
+export declare function createEmitter<T>(listen: ListenFunc<T>): Emitter<T>;
 /** @internal */
-export declare function createEmitter<T, API extends object>(onListen: (handler: Handler<T>) => UnsubscribeFunc, api: Omit<API, keyof Emitter<T>>): Emitter<T> & API;
+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: (handler: Handler<number>) => UnsubscribeFunc, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
+export declare function createProgressEmitter<API extends object>(onListen: ListenFunc<number>, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
 /** @internal */
-export declare function createProgressEmitter(onListen: (handler: Handler<number>) => UnsubscribeFunc): RangeProgression;
+export declare function createProgressEmitter(onListen: ListenFunc<number>): RangeProgression;
 type Handler<T> = (value: T) => void;
+type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
 export interface Emitter<T> {
     /**
@@ -49,4 +51,121 @@ export interface Emitter<T> {
      */
     tap(cb: Handler<T>): Emitter<T>;
 }
+export interface RangeProgression extends Emitter<number> {
+    /**
+     * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
+     *
+     * @param easer An easing function of the form `(progression: number) => number`
+     * @returns Listenable: emits eased progression values
+     */
+    ease(easer?: Easer | keyof typeof easers): RangeProgression;
+    /**
+     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
+     *
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     *
+     * @param from Value to interpolate from
+     * @param to Value to interpolate to
+     * @returns Listenable: emits interpolated values
+     */
+    tween(from: number, to: number): Emitter<number>;
+    /**
+     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
+     *
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     *
+     * #### String interpolation
+     * * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
+     * * Otherwise the `from` string is progressively replaced, left-to-right, with the `to` string
+     *
+     * eg
+     * ```ts
+     * range
+     *   .tween("0px 0px 0px #0000", "4px 4px 8px #0005")
+     *   .listen(s => element.style.textShadow = s);
+     * ```
+     *
+     * @param from Value to interpolate from
+     * @param to Value to interpolate to
+     * @returns Listenable: emits interpolated values
+     */
+    tween(from: string, to: string): Emitter<string>;
+    /**
+     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
+     *
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     *
+     * @param from Value to interpolate from
+     * @param to Value to interpolate to
+     * @returns Listenable: emits interpolated values
+     */
+    tween<T extends Blendable | number[]>(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.
+     *
+     * @param steps – positive integer (e.g. 10 → 0, .1, .2 … 1)
+     * @throws RangeError if steps is not a positive integer
+     * @returns Listenable: emits quantised progression values
+     */
+    snap(steps: number): RangeProgression;
+    /**
+     * Creates a chainable progress emitter that emits `1` when the incoming progress value is greater‑than‑or‑equal to the supplied `threshold`, otherwise emits `0`
+     *
+     * @param threshold the cut‑off value
+     * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
+     */
+    threshold(threshold: number): RangeProgression;
+    /**
+     * Creates a chainable progress emitter that clamps incoming values
+     * @param min default 0
+     * @param max default 1
+     * @returns Listenable: emits clamped progression values
+     */
+    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
+     *
+     * @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: (value: number) => void): 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
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check: (value: number) => boolean): RangeProgression;
+    /**
+     * 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;
+    /**
+     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping between 0 and 1
+     *
+     * ```plain
+     *‎	1
+     *‎	 |  /
+     *‎	o| /
+     *‎	u|/      __ delta=.5
+     *‎	t|     /
+     *‎	 |    /
+     *‎	 |___/__
+     *‎	0  in   1
+     * ```
+     *
+     * @param delta
+     */
+    offset(delta: number): RangeProgression;
+}
 export {};

package/internal/emitters.js

@@ -6,31 +6,18 @@ const easing_1 = require("./easing");
 const tween_1 = require("./tween");
 const utils_1 = require("./utils");
 /** @internal */
-function createEmitter(onListen, api) {
+function createEmitter(listen, api) {
     const propertyDescriptor = Object.fromEntries(Object.entries({
-        listen: (handler) => {
-            const uniqueHandler = (value) => {
+        listen: (handler) => listen((value) => {
+            handler(value);
+        }),
+        map: (mapFunc) => createEmitter(handler => listen((value) => {
+            handler(mapFunc(value));
+        })),
+        filter: (filterFunc) => createEmitter(handler => listen((value) => {
+            if (filterFunc(value))
                 handler(value);
-            };
-            return onListen(uniqueHandler);
-        },
-        map: (mapFunc) => {
-            return createEmitter(handler => {
-                const pipedHandler = (value) => {
-                    handler(mapFunc(value));
-                };
-                return onListen(pipedHandler);
-            });
-        },
-        filter: (filterFunc) => {
-            return createEmitter(handler => {
-                const filteredHandler = (value) => {
-                    if (filterFunc(value))
-                        handler(value);
-                };
-                return onListen(filteredHandler);
-            });
-        },
+        })),
         noRepeat: (compare) => {
             let previous = null;
             return createEmitter(handler => {
@@ -42,30 +29,10 @@ function createEmitter(onListen, api) {
                         previous = { value };
                     }
                 };
-                return onListen(filteredHandler);
+                return listen(filteredHandler);
             });
         },
-        tap: (cb) => {
-            let listeners = [];
-            let parentUnsubscribe = null;
-            const tapOnListen = (handler) => {
-                listeners.push(handler);
-                if (listeners.length === 1) {
-                    parentUnsubscribe = onListen(value => {
-                        cb(value);
-                        listeners.slice().forEach(fn => fn(value));
-                    });
-                }
-                return () => {
-                    listeners = listeners.filter(l => l !== handler);
-                    if (listeners.length === 0 && parentUnsubscribe) {
-                        parentUnsubscribe();
-                        parentUnsubscribe = null;
-                    }
-                };
-            };
-            return createEmitter(tapOnListen);
-        },
+        tap: (cb) => createTap(cb, createEmitter, listen),
     }).map(([key, value]) => [
         key,
         { value }
@@ -73,40 +40,79 @@ function createEmitter(onListen, api) {
     return Object.create(api ?? {}, propertyDescriptor);
 }
 /** @internal */
-function createProgressEmitter(onListen, api = {}) {
+function createProgressEmitter(listen, api = {}) {
     const propertyDescriptor = Object.fromEntries(Object.entries({
         ease: (easer) => {
             const easerFunc = typeof easer == "string"
                 ? easing_1.easers[easer]
                 : easer;
-            return createProgressEmitter(easer ? (handler => onListen((progress) => {
+            return createProgressEmitter(easer ? (handler => listen((progress) => {
                 handler(easerFunc(progress));
-            })) : onListen);
+            })) : listen);
         },
-        tween: (from, to) => createEmitter(handler => onListen(progress => handler((0, tween_1.tweenValue)(from, to, progress)))),
+        tween: (from, to) => createEmitter(handler => listen(progress => handler((0, tween_1.tweenValue)(from, to, progress)))),
         snap: (steps) => {
             if (!Number.isInteger(steps) || steps <= 0) {
                 throw new RangeError('snap(steps) requires a positive integer');
             }
-            return createProgressEmitter(handler => onListen(progress => {
+            return createProgressEmitter(handler => listen(progress => {
                 const snapped = Math.round(progress * steps) / steps;
                 handler((0, utils_1.clamp)(snapped, 0, 1));
             }));
         },
-        threshold: (threshold) => createProgressEmitter(handler => onListen(progress => {
+        threshold: (threshold) => createProgressEmitter(handler => listen(progress => {
             handler(progress >= threshold ? 1 : 0);
         })),
-        clamp: (min = 0, max = 1) => createProgressEmitter(handler => onListen(progress => handler((0, utils_1.clamp)(progress, min, max)))),
+        clamp: (min = 0, max = 1) => createProgressEmitter(handler => listen(progress => handler((0, utils_1.clamp)(progress, min, max)))),
         repeat: (repetitions) => {
             repetitions = Math.max(0, repetitions);
-            return createProgressEmitter(handler => onListen(progress => {
+            return createProgressEmitter(handler => listen(progress => {
                 const out = (progress * repetitions) % 1;
                 handler(out);
             }));
         },
+        tap: (cb) => createTap(cb, createProgressEmitter, listen),
+        filter: (filterFunc) => createProgressEmitter(handler => listen((value) => {
+            if (filterFunc(value))
+                handler(value);
+        })),
+        noRepeat: () => {
+            let previous = null;
+            return createProgressEmitter(handler => {
+                return listen((value) => {
+                    if (!previous || (previous.value !== value)) {
+                        handler(value);
+                        previous = { value };
+                    }
+                });
+            });
+        },
+        offset: (delta) => createProgressEmitter(handler => listen(value => handler((value + delta) % 1))),
     }).map(([key, value]) => [
         key,
         { value }
     ]));
-    return createEmitter(onListen, Object.create(api, propertyDescriptor));
+    return Object.create(api ?? {}, propertyDescriptor);
+}
+function createTap(callback, create, parentListen) {
+    const listeners = [];
+    let parentUnsubscribe = null;
+    const tapOnListen = (handler) => {
+        listeners.push(handler);
+        if (listeners.length === 1) {
+            parentUnsubscribe = parentListen(value => {
+                callback(value);
+                listeners.slice().forEach(fn => fn(value));
+            });
+        }
+        return () => {
+            const idx = listeners.indexOf(handler);
+            listeners.splice(idx, 1);
+            if (listeners.length === 0 && parentUnsubscribe) {
+                parentUnsubscribe();
+                parentUnsubscribe = null;
+            }
+        };
+    };
+    return create(tapOnListen);
 }

package/internal/point.d.ts

@@ -7,16 +7,19 @@ export interface TimelinePoint extends Emitter<PointEvent> {
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
      * @param duration
+     * @returns Listenable: emits normalised (0..1) range progression
      */
     range(duration: number): TimelineRange;
     /**
      * Creates a range on the Timeline, with a given end point, starting at this point
      * @param endPoint
+     * @returns Listenable: emits normalised (0..1) range progression
      */
     to(endPoint: number | TimelinePoint): TimelineRange;
     /**
      * Creates a point on the Timeline at an offset position from this one
      * @param timeOffset
+     * @returns Listenable: emits a PointEvent when the point is reached or passed by a Timeline seek
      */
     delta(timeOffset: number): TimelinePoint;
     /**

package/internal/range.d.ts

@@ -1,25 +1,26 @@
 import { Easer, easers } from "./easing";
-import { Emitter } from "./emitters";
+import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
-import { Blendable } from "./tween";
 export interface TimelineRange extends RangeProgression {
     /**
      * Creates two ranges by seperating one at a given point
      * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
      *
      * Must be greater than 0 and less than the range's duration
+     * @returns Tuple of two ranges
      */
     bisect(position?: number): [TimelineRange, TimelineRange];
     /**
      * Creates a series of evenly-spread points across the range, excluding the range's start and end
      * @param count Number of Points to return
+     * @returns Array(count) of points
      */
     spread(count: number): TimelinePoint[];
     /**
      * Progresses the Timeline across the range
      * @param easer
      */
-    play(easer?: Easer): Promise<void>;
+    play(easer?: Easer | keyof typeof easers): Promise<void>;
     /**
      * Creates a new range representing a direct expansion of this one
      * @param delta Amount to grow by (in time units)
@@ -34,6 +35,12 @@ export interface TimelineRange extends RangeProgression {
      * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
     scale(factor: number, anchor?: number): TimelineRange;
+    /**
+     * Checks if a point is within this range
+     * @param point The point to check
+     * @returns true if the provided point is within the range
+     */
+    contains(point: TimelinePoint): boolean;
     /** The point on the Timeline at which this range begins */
     readonly start: TimelinePoint;
     /** The point on the Timeline at which this range ends */
@@ -41,80 +48,3 @@ export interface TimelineRange extends RangeProgression {
     /** The duration of this range */
     readonly duration: number;
 }
-export interface RangeProgression extends Emitter<number> {
-    /**
-     * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
-     *
-     * @param easer An easing function of the form `(progression: number) => number`
-     * @returns Listenable: emits eased progression values
-     */
-    ease(easer?: Easer | keyof typeof easers): RangeProgression;
-    /**
-     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
-     *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
-     *
-     * @param from Value to interpolate from
-     * @param to Value to interpolate to
-     * @returns Listenable: emits interpolated values
-     */
-    tween(from: number, to: number): Emitter<number>;
-    /**
-     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
-     *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
-     *
-     * #### String interpolation
-     * * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
-     * * Otherwise the `from` string is progressively replaced, left-to-right, with the `to` string
-     *
-     * eg
-     * ```ts
-     * range
-     *   .tween("0px 0px 0px #0000", "4px 4px 8px #0005")
-     *   .listen(s => element.style.textShadow = s);
-     * ```
-     *
-     * @param from Value to interpolate from
-     * @param to Value to interpolate to
-     * @returns Listenable: emits interpolated values
-     */
-    tween(from: string, to: string): Emitter<string>;
-    /**
-     * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
-     *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
-     *
-     * @param from Value to interpolate from
-     * @param to Value to interpolate to
-     * @returns Listenable: emits interpolated values
-     */
-    tween<T extends Blendable | number[]>(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.
-     *
-     * @param steps – positive integer (e.g. 10 → 0, .1, .2 … 1)
-     * @throws RangeError if steps is not a positive integer
-     * @returns Listenable: emits quantised progression values
-     */
-    snap(steps: number): RangeProgression;
-    /**
-     * Creates a chainable progress emitter that emits `1` when the incoming progress value is greater‑than‑or‑equal to the supplied `threshold`, otherwise emits `0`
-     *
-     * @param threshold the cut‑off value
-     * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
-     */
-    threshold(threshold: number): RangeProgression;
-    /**
-     * Creates a chainable progress emitter that clamps incoming values
-     * @param min default 0
-     * @param max default 1
-     * @returns Listenable: emits clamped progression values
-     */
-    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;
-}

package/internal/timeline.js

@@ -201,6 +201,9 @@ class Timeline {
                 }
                 return this.range(newStart, newEnd - newStart);
             },
+            contains: point => {
+                return point.position >= startPosition && point.position < endPosition;
+            }
         });
     }
     getWrappedPosition(n) {

package/internal/tween.js

@@ -93,27 +93,27 @@ function blendColours(from, to, bias) {
     return ("#" + blended.map(n => Math.round(n).toString(16).padStart(2, "0")).join("")).replace(/ff$/, "");
 }
 const tweenableTokenRegex = /(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/g;
+const tokenise = (s) => {
+    const chunks = [];
+    let lastIdx = 0;
+    let m;
+    while ((m = tweenableTokenRegex.exec(s))) {
+        const token = m[0];
+        const prefix = s.slice(lastIdx, m.index); // literal before token
+        chunks.push({ prefix, token });
+        lastIdx = m.index + token.length;
+    }
+    // trailing literal after the last token – stored as a final chunk
+    // with an empty token (so the consumer can easily append it)
+    const tail = s.slice(lastIdx);
+    if (tail.length) {
+        chunks.push({ prefix: tail, token: "" });
+    }
+    return chunks;
+};
 function blendStrings(from, to, progress) {
     if (from === to || progress === 0)
         return from;
-    const tokenise = (s) => {
-        const chunks = [];
-        let lastIdx = 0;
-        let m;
-        while ((m = tweenableTokenRegex.exec(s))) {
-            const token = m[0];
-            const prefix = s.slice(lastIdx, m.index); // literal before token
-            chunks.push({ prefix, token });
-            lastIdx = m.index + token.length;
-        }
-        // trailing literal after the last token – stored as a final chunk
-        // with an empty token (so the consumer can easily append it)
-        const tail = s.slice(lastIdx);
-        if (tail.length) {
-            chunks.push({ prefix: tail, token: "" });
-        }
-        return chunks;
-    };
     const fromChunks = tokenise(from);
     const toChunks = tokenise(to);
     const tokenCount = fromChunks.filter(c => c.token).length;

package/package.json

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