@xtia/timeline 1.0.11 → 1.1.0

package/README.md

@@ -21,7 +21,7 @@ const timeline = new Timeline();
 timeline
     .range(0, 1000)
     .tween("#646", "#000")
-    .listen(
+    .apply(
         value => element.style.background = value
     );
 
@@ -31,7 +31,7 @@ timeline
     .range(500, 2000)
     .tween(0, message.length)
     .map(n => message.substring(0, n))
-    .listen(
+    .apply(
         s => element.textContent = s
     );
 
@@ -40,7 +40,7 @@ timeline
     .range(0, 3000)
     .ease("bounce")
     .tween("50%", "0%")
-    .listen(
+    .apply(
         value => element.style.marginLeft = value
     );
 
@@ -56,11 +56,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 +74,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 +98,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
@@ -146,7 +146,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 +181,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 +218,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 +238,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 +302,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 +435,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.
@@ -483,6 +483,13 @@ Creates a [`TimelineRange`](#timelinerange-interface) on the Timeline to which t
 
 Creates a `TimelinePoint` at an offset from the this point.
 
+##### `seek(): void`
+
+Seeks the parent Timeline to this point.
+
+##### `seek(duration: number, easer?: Easer): Promise<void>`
+
+Smooth-seeks the parent Timeline to this point over a specified duration and resolves the returned Promise on completion.
 
 
 
@@ -501,7 +508,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
@@ -593,6 +600,10 @@ blend(from: this, to: this, progress: number): this
 
 Creates an emitter that quantises progression emitted by the parent to the nearest of `steps` discrete values.
 
+##### `sample<T>(values: ArrayLike<T>): `[`Emitter<T>`](#emittert-interface)
+
+Creates an emitter that emits values from an array according to progression.
+
 ##### `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`.
@@ -639,9 +650,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);
 ```
 
 
@@ -651,7 +662,7 @@ range
 
 #### 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.
 
@@ -685,9 +696,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
@@ -125,6 +131,20 @@ export declare class RangeProgression extends Emitter<number> {
      */
     tween<T extends Tweenable>(from: T, to: T): Emitter<T>;
     tween<T extends BlendableWith<T, R>, R>(from: T, to: R): Emitter<T>;
+    /**
+     * Creates a chainable emitter that takes a value from an array according to progression
+     *
+     * @example
+     * ```ts
+     * range
+     *   .sample(["a", "b", "c"])
+     *   .apply(v => console.log(v));
+     * // logs 'b' when a seek lands halfway through range
+     * ```
+     * @param source array to sample
+     * @returns Listenable: emits the sampled values
+     */
+    sample<T>(source: ArrayLike<T>): Emitter<T>;
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
      *

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
      */
@@ -141,6 +151,26 @@ export class RangeProgression extends Emitter {
         const tween = createTween(from, to);
         return new Emitter(handler => this.onListen(progress => handler(tween(progress))));
     }
+    /**
+     * Creates a chainable emitter that takes a value from an array according to progression
+     *
+     * @example
+     * ```ts
+     * range
+     *   .sample(["a", "b", "c"])
+     *   .apply(v => console.log(v));
+     * // logs 'b' when a seek lands halfway through range
+     * ```
+     * @param source array to sample
+     * @returns Listenable: emits the sampled values
+     */
+    sample(source) {
+        return new Emitter(handler => this.onListen(progress => {
+            const clampedProgress = clamp(progress);
+            const index = Math.floor(clampedProgress * (source.length - 1));
+            handler(source[index]);
+        }));
+    }
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
      *
@@ -154,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, 0, 1));
+            handler(snapped);
         }));
     }
     /**

package/internal/point.d.ts

@@ -36,6 +36,9 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * @returns Listenable: emits a PointEvent when the point is reached or passed by a Timeline seek
      */
     delta(timeOffset: number): TimelinePoint;
+    /**
+     * Seeks the parent Timeline to this point
+     */
     seek(): void;
-    seek(duration?: number, easer?: Easer): void;
+    seek(duration: number, easer?: Easer): Promise<void>;
 }

package/internal/point.js

@@ -39,6 +39,6 @@ export class TimelinePoint extends Emitter {
         return this.timeline.point(this.position + timeOffset);
     }
     seek(duration = 0, easer) {
-        this.timeline.seek(this.position, duration, easer);
+        return this.timeline.seek(this.position, duration, easer);
     }
 }

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/internal/tween.d.ts

@@ -7,5 +7,7 @@ export interface Blendable {
 export interface BlendableWith<T, R> {
     blend(target: R, progress: number): T;
 }
-export declare function createTween<T extends Tweenable>(from: T, to: T): ((progress: number) => T);
-export declare function createTween<T extends BlendableWith<T, R>, R>(from: T, to: R): ((progress: number) => T);
+type TweenFunc<T> = (progress: number) => T;
+export declare function createTween<T extends Tweenable>(from: T, to: T): TweenFunc<T>;
+export declare function createTween<T extends BlendableWith<T, R>, R>(from: T, to: R): TweenFunc<T>;
+export {};

package/internal/tween.js

@@ -1,4 +1,9 @@
 import { clamp } from "./utils";
+const tokenTypes = {
+    none: 0,
+    number: 1,
+    colour: 2,
+};
 export function createTween(from, to) {
     if (from === to)
         return () => from;
@@ -24,8 +29,9 @@ function createStringTween(from, to) {
     if (tokenCount !== toChunks.filter(c => c.token).length) {
         return createStringMerge(from, to);
     }
-    // where token prefix mismatch, use merging
-    if (fromChunks.some((chunk, i) => toChunks[i].prefix !== chunk.prefix)) {
+    // where token prefix/type mismatch, use merging
+    if (fromChunks.some((chunk, i) => toChunks[i].prefix !== chunk.prefix ||
+        toChunks[i].type !== chunk.type)) {
         return createStringMerge(from, to);
     }
     // convert token chunks to individual string tween funcs
@@ -33,9 +39,9 @@ function createStringTween(from, to) {
         const fromToken = chunk.token;
         const toToken = toChunks[i].token;
         const prefix = chunk.prefix;
-        if (!fromToken)
+        if (chunk.type === tokenTypes.none)
             return () => prefix;
-        if (fromToken.startsWith("#")) {
+        if (chunk.type === tokenTypes.colour) {
             const fromColour = parseColour(fromToken);
             const toColour = parseColour(toToken);
             return progress => prefix + blendColours(fromColour, toColour, progress);
@@ -65,7 +71,7 @@ function createStringMerge(from, to) {
     if (!to)
         return () => from;
     const split = (s) => {
-        // prefer Intl.Segmenter if available (Node ≥ 14, modern browsers)
+        // prefer Intl.Segmenter if available (Node 14, modern browsers)
         if (typeof Intl !== "undefined" && Intl.Segmenter) {
             const seg = new Intl.Segmenter(undefined, { granularity: "grapheme" });
             return Array.from(seg.segment(s), (seg) => seg.segment);
@@ -86,7 +92,7 @@ function createStringMerge(from, to) {
     const fromP = pad(a);
     const toP = pad(b);
     return (progress) => {
-        const clampedProgress = clamp(progress, 0, 1);
+        const clampedProgress = clamp(progress);
         const replaceCount = Math.floor(clampedProgress * maxLen);
         const result = new Array(maxLen);
         for (let i = 0; i < maxLen; ++i) {
@@ -122,20 +128,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) => {
+function 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 });
+        const type = getTokenType(token);
+        chunks.push({ prefix, token, type });
         lastIdx = m.index + token.length;
     }
     // trailing literal after the last token – stored as a final chunk
     const tail = s.slice(lastIdx);
     if (tail.length) {
-        chunks.push({ prefix: tail, token: "" });
+        chunks.push({ prefix: tail, token: "", type: tokenTypes.none });
     }
     return chunks;
-};
+}
+;
+function getTokenType(token) {
+    if (token.startsWith("#"))
+        return tokenTypes.colour;
+    return tokenTypes.number;
+}

package/internal/utils.d.ts

@@ -1,4 +1,4 @@
 /** @internal */
-export declare const clamp: (value: number, min: number, max: number) => number;
+export declare const clamp: (value: number, min?: number, max?: number) => number;
 /** @internal */
 export type Widen<T> = T extends number ? number : T extends string ? string : T;

package/internal/utils.js

@@ -1,2 +1,2 @@
 /** @internal */
-export const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+export const clamp = (value, min = 0, max = 1) => Math.min(Math.max(value, min), max);

package/package.json

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