@xtia/timeline 1.0.10 → 1.0.12

package/README.md

@@ -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.
 
 
 
@@ -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`.

package/internal/emitters.d.ts

@@ -125,6 +125,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"])
+     *   .listen(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

@@ -1,5 +1,5 @@
 import { easers } from "./easing";
-import { tweenValue } from "./tween";
+import { createTween } from "./tween";
 import { clamp } from "./utils";
 export class Emitter {
     constructor(onListen) {
@@ -138,7 +138,28 @@ export class RangeProgression extends Emitter {
         })) : h => this.onListen(h));
     }
     tween(from, to) {
-        return new Emitter(handler => this.onListen(progress => handler(tweenValue(from, to, progress))));
+        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"])
+     *   .listen(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.
@@ -153,7 +174,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(clamp(snapped));
         }));
     }
     /**

package/internal/point.d.ts

@@ -1,3 +1,4 @@
+import { Easer } from "./easing";
 import { Emitter, ListenFunc } from "./emitters";
 import { TimelineRange } from "./range";
 import { Timeline } from "./timeline";
@@ -35,4 +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): Promise<void>;
 }

package/internal/point.js

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

package/internal/range.js

@@ -6,7 +6,11 @@ export class TimelineRange extends RangeProgression {
     constructor(onListen, timeline, startPosition, 
     /** The duration of this range */
     duration) {
-        super(onListen);
+        super(duration == 0
+            ? () => {
+                throw new Error("Zero-duration ranges may not be listened");
+            }
+            : onListen);
         this.timeline = timeline;
         this.startPosition = startPosition;
         this.duration = duration;

package/internal/timeline.js

@@ -189,7 +189,7 @@ export class Timeline {
         }
         if (duration === 0) {
             this.seekDirect(toPosition);
-            return;
+            return Promise.resolve();
         }
         const seeker = new Timeline(true);
         this.smoothSeeker = seeker;

package/internal/tween.d.ts

@@ -1,5 +1,5 @@
 /** @internal */
-export type Tweenable = number | number[] | string | Blendable;
+export type Tweenable = number | number[] | string | string[] | Blendable | Blendable[];
 /** @internal */
 export interface Blendable {
     blend(target: this, progress: number): this;
@@ -7,5 +7,7 @@ export interface Blendable {
 export interface BlendableWith<T, R> {
     blend(target: R, progress: number): T;
 }
-/** @internal */
-export declare function tweenValue<T extends Tweenable>(from: T, to: T, 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,45 +1,82 @@
 import { clamp } from "./utils";
-/** @internal */
-export function tweenValue(from, to, progress) {
+const tokenTypes = {
+    none: 0,
+    number: 1,
+    colour: 2,
+};
+export function createTween(from, to) {
+    if (from === to)
+        return () => from;
     if (Array.isArray(from)) {
-        const toArr = to;
-        if (from.length != toArr.length)
+        if (from.length != to.length) {
             throw new Error("Array size mismatch");
-        return from.map((v, i) => tweenValue(v, toArr[i], progress));
+        }
+        const tweens = from.map((f, i) => createTween(f, to[i]));
+        return progress => tweens.map(t => t(progress));
     }
-    if (typeof from == "string") {
-        return blendStrings(from, to, progress);
+    switch (typeof from) {
+        case "number": return progress => blendNumbers(from, to, progress);
+        case "object": return progress => from.blend(to, progress);
+        case "string": return createStringTween(from, to);
+        default: throw new Error("Invalid tweening type");
     }
-    if (typeof from == "number") {
-        return blendNumbers(from, to, progress);
+}
+function createStringTween(from, to) {
+    const fromChunks = tokenise(from);
+    const toChunks = tokenise(to);
+    const tokenCount = fromChunks.filter(c => c.token).length;
+    // where length mismatch, use merging
+    if (tokenCount !== toChunks.filter(c => c.token).length) {
+        return createStringMerge(from, to);
     }
-    if (from && typeof from == "object") {
-        if ("blend" in from) {
-            const blendableSource = from;
-            return blendableSource.blend(to, progress);
-        }
+    // 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);
     }
-    throw new Error("Value not recognised as Tweenable");
+    // convert token chunks to individual string tween funcs
+    const tweenChunks = fromChunks.map((chunk, i) => {
+        const fromToken = chunk.token;
+        const toToken = toChunks[i].token;
+        const prefix = chunk.prefix;
+        if (chunk.type === tokenTypes.none)
+            return () => prefix;
+        if (chunk.type === tokenTypes.colour) {
+            const fromColour = parseColour(fromToken);
+            const toColour = parseColour(toToken);
+            return progress => prefix + blendColours(fromColour, toColour, progress);
+        }
+        else {
+            const fromNum = parseFloat(fromToken);
+            const toNum = parseFloat(toToken);
+            return progress => {
+                const blendedNum = blendNumbers(fromNum, toNum, progress);
+                return prefix + blendedNum.toString();
+            };
+        }
+    });
+    if (tweenChunks.length == 1)
+        return tweenChunks[0];
+    return progress => tweenChunks.map(t => t(progress)).join("");
 }
 function blendNumbers(from, to, progress) {
     return from + progress * (to - from);
 }
-function mergeStrings(from, to, progress) {
-    const p = Math.min(Math.max(progress, 0), 1);
-    // Fast‑path: identical strings or one is empty
+function createStringMerge(from, to) {
+    // fast‑path: identical strings or one is empty
     if (from === to)
-        return from;
+        return () => from;
     if (!from)
-        return to;
+        return () => to;
     if (!to)
-        return from;
+        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);
         }
-        // Fallback regex (covers surrogate pairs & combining marks)
+        // fallback regex (covers surrogate pairs & combining marks)
         const graphemeRegex = /(\P{Mark}\p{Mark}*|[\uD800-\uDBFF][\uDC00-\uDFFF])/gu;
         return s.match(graphemeRegex) ?? Array.from(s);
     };
@@ -54,15 +91,18 @@ function mergeStrings(from, to, progress) {
     };
     const fromP = pad(a);
     const toP = pad(b);
-    const replaceCount = Math.floor(p * maxLen);
-    const result = new Array(maxLen);
-    for (let i = 0; i < maxLen; ++i) {
-        result[i] = i < replaceCount ? toP[i] : fromP[i];
-    }
-    while (result.length && result[result.length - 1] === " ") {
-        result.pop();
-    }
-    return result.join("");
+    return (progress) => {
+        const clampedProgress = clamp(progress);
+        const replaceCount = Math.floor(clampedProgress * maxLen);
+        const result = new Array(maxLen);
+        for (let i = 0; i < maxLen; ++i) {
+            result[i] = i < replaceCount ? toP[i] : fromP[i];
+        }
+        while (result.length && result[result.length - 1] === " ") {
+            result.pop();
+        }
+        return result.join("");
+    };
 }
 function parseColour(code) {
     if (code.length < 2 || !code.startsWith("#"))
@@ -84,68 +124,31 @@ function parseColour(code) {
     return [...rawHex.matchAll(/../g)].map(hex => parseInt(hex[0], 16));
 }
 function blendColours(from, to, bias) {
-    const fromColour = parseColour(from);
-    const toColour = parseColour(to);
-    const blended = fromColour.map((val, i) => clamp(blendNumbers(val, toColour[i], bias), 0, 255));
+    const blended = from.map((val, i) => clamp(blendNumbers(val, to[i], bias), 0, 255));
     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
-    // with an empty token (so the consumer can easily append it)
     const tail = s.slice(lastIdx);
     if (tail.length) {
-        chunks.push({ prefix: tail, token: "" });
+        chunks.push({ prefix: tail, token: "", type: tokenTypes.none });
     }
     return chunks;
-};
-function blendStrings(from, to, progress) {
-    if (from === to || progress === 0)
-        return from;
-    const fromChunks = tokenise(from);
-    const toChunks = tokenise(to);
-    const tokenCount = fromChunks.filter(c => c.token).length;
-    if (tokenCount !== toChunks.filter(c => c.token).length) {
-        return mergeStrings(from, to, progress);
-    }
-    let result = "";
-    for (let i = 0, j = 0; i < fromChunks.length && j < toChunks.length;) {
-        const f = fromChunks[i];
-        const t = toChunks[j];
-        // The *prefix* (the text before the token) must be the same.
-        if (f.prefix !== t.prefix) {
-            return mergeStrings(from, to, progress);
-        }
-        // Append the unchanged prefix.
-        result += f.prefix;
-        // If we are at the *trailing* chunk (no token), just break.
-        if (!f.token && !t.token) {
-            break;
-        }
-        // Blend the token according to its kind.
-        let blended;
-        if (f.token.startsWith("#")) {
-            blended = blendColours(f.token, t.token, progress);
-        }
-        else {
-            const fNum = parseFloat(f.token);
-            const tNum = parseFloat(t.token);
-            const blendedNum = blendNumbers(fNum, tNum, progress);
-            blended = blendedNum.toString();
-        }
-        result += blended;
-        // Advance both pointers.
-        i++;
-        j++;
-    }
-    return result;
+}
+;
+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.10",
+  "version": "1.0.12",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"