@xtia/timeline 1.0.3 → 1.0.5

package/README.md

@@ -163,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")

package/internal/emitters.d.ts

@@ -1,14 +1,15 @@
 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> {
     /**
@@ -149,5 +150,22 @@ export interface RangeProgression extends Emitter<number> {
      * @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

@@ -5,16 +5,15 @@ exports.createProgressEmitter = createProgressEmitter;
 const easing_1 = require("./easing");
 const tween_1 = require("./tween");
 const utils_1 = require("./utils");
-/** @internal */
-function createEmitter(onListen, api) {
-    const propertyDescriptor = Object.fromEntries(Object.entries({
-        listen: (handler) => onListen((value) => {
+function createEmitterMethodProperties(listen, extensions) {
+    return Object.fromEntries(Object.entries({
+        listen: (handler) => listen((value) => {
             handler(value);
         }),
-        map: (mapFunc) => createEmitter(handler => onListen((value) => {
+        map: (mapFunc) => createEmitter(handler => listen((value) => {
             handler(mapFunc(value));
         })),
-        filter: (filterFunc) => createEmitter(handler => onListen((value) => {
+        filter: (filterFunc) => createEmitter(handler => listen((value) => {
             if (filterFunc(value))
                 handler(value);
         })),
@@ -29,57 +28,62 @@ function createEmitter(onListen, api) {
                         previous = { value };
                     }
                 };
-                return onListen(filteredHandler);
+                return listen(filteredHandler);
             });
         },
-        tap: (cb) => createEmitter(createTapListener(cb, onListen)),
+        tap: (cb) => createTap(cb, createEmitter, listen),
+        ...extensions,
     }).map(([key, value]) => [
         key,
         { value }
     ]));
+}
+/** @internal */
+function createEmitter(listen, api) {
+    const propertyDescriptor = createEmitterMethodProperties(listen, {});
     return Object.create(api ?? {}, propertyDescriptor);
 }
 /** @internal */
-function createProgressEmitter(onListen, api = {}) {
-    const propertyDescriptor = Object.fromEntries(Object.entries({
+function createProgressEmitter(listen, api = {}) {
+    const propertyDescriptor = createEmitterMethodProperties(listen, {
         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) => createProgressEmitter(createTapListener(cb, onListen)),
-        filter: (filterFunc) => createProgressEmitter(handler => onListen((value) => {
+        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 onListen((value) => {
+                return listen((value) => {
                     if (!previous || (previous.value !== value)) {
                         handler(value);
                         previous = { value };
@@ -87,19 +91,17 @@ function createProgressEmitter(onListen, api = {}) {
                 });
             });
         },
-    }).map(([key, value]) => [
-        key,
-        { value }
-    ]));
-    return createEmitter(onListen, Object.create(api, propertyDescriptor));
+        offset: (delta) => createProgressEmitter(handler => listen(value => handler((value + delta) % 1))),
+    });
+    return Object.create(api ?? {}, propertyDescriptor);
 }
-function createTapListener(callback, parentOnListen) {
+function createTap(callback, create, parentListen) {
     const listeners = [];
     let parentUnsubscribe = null;
     const tapOnListen = (handler) => {
         listeners.push(handler);
         if (listeners.length === 1) {
-            parentUnsubscribe = parentOnListen(value => {
+            parentUnsubscribe = parentListen(value => {
                 callback(value);
                 listeners.slice().forEach(fn => fn(value));
             });
@@ -113,5 +115,5 @@ function createTapListener(callback, parentOnListen) {
             }
         };
     };
-    return tapOnListen;
+    return create(tapOnListen);
 }

package/package.json

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