@xtia/timeline 1.0.11 → 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

@@ -141,6 +141,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"])
+     *   .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.
      *
@@ -154,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

@@ -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/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.0.12",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"