@xtia/timeline 0.2.5 → 1.0.0

package/index.d.ts

@@ -1,195 +1,241 @@
-type ApplyTweenFunc = (v: number) => void;
-type EaseFunc = (v: number) => number;
-interface TweenData {
-    time: number;
-    duration: number;
-    startValue: NumberOrNumberFunction;
-    endValue: NumberOrNumberFunction;
-    apply: ApplyTweenFunc;
-    ease?: EaseFunc;
-}
-type NumberOrNumberFunction = number | (() => number);
-type EndAction = "continue" | "pause" | "loop";
-interface TimelineChain {
+type PointEvent = {
+    direction: -1 | 1;
+};
+declare const EndAction: {
+    readonly pause: 0;
+    readonly continue: 1;
+    readonly wrap: 2;
+    readonly restart: 3;
+};
+/**
+ * Creates an autoplaying Timeline and returns a range from it
+ * @param duration
+ * @returns Object representing a range on a single-use, autoplaying Timeline
+ */
+export declare function animate(duration: number): TimelineRange;
+export declare class Timeline {
     /**
-     * Add a callback to run at the end of the previous item in a chain, offset by the Timeline's current position
-     * @param time Offset, time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time.
-     * @param revert Called when a backward seek passes this event's time. Default is no action
+     * Multiplies the speed at which `play()` progresses through the Timeline
+     *
+     * A value of 2 would double progression speed while .25 would slow it to a quarter
      */
-    then(apply: () => void, revert?: () => void): TimelineChain;
+    timeScale: number;
+    get currentTime(): number;
+    set currentTime(v: number);
+    get isPlaying(): boolean;
+    get end(): TimelinePoint;
+    private _currentTime;
+    private _endPosition;
+    private interval;
+    private points;
+    private endAction;
+    private ranges;
+    private currentSortDirection;
+    private smoothSeeker;
+    private seeking;
+    readonly start: TimelinePoint;
+    private positionHandlers;
+    constructor();
     /**
-     * Add a callback to run at the end of the previous item in a chain, offset by the Timeline's current position
-     * @param time Offset, time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time.
-     * @param applyOnReverse Pass true to call `apply` regardless of direction of traversal, or false to specify no reversion action
+     * @param autoplay Pass `true` to begin playing at (1000 x this.timeScale) units per second immediately on creation
      */
-    then(apply: () => void, applyOnReverse: boolean): TimelineChain;
+    constructor(autoplay: boolean);
     /**
-     * Add a tween to this Timeline, starting at the end of the previous item in a chain
-     * @param duration Duration of tween
-     * @param apply Function called per frame, passed a value between `from` and `to` (with possible overshoot depending on easer)
-     * @param from Initial (pre-start) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 0)
-     * @param to Final (post-end) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 1)
-     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
+     * Creates a Timeline that begins playing immediately at (1000 x this.timeScale) units per second
+     * @param autoplayFps Specifies frames per second
      */
-    thenTween(duration: number, apply: ApplyTweenFunc, from?: NumberOrNumberFunction, to?: NumberOrNumberFunction, ease?: EaseFunc): TimelineChain;
+    constructor(autoplayFps: number);
     /**
-     * Ensures end time extends to (at least) the specified time past the end of the previous item in a chain
-     * @param duration
+     * @param autoplay If this argument is `true`, the Timeline will begin playing immediately on creation. If the argument is a number, the Timeline will begin playing at the specified frames per second
+     * @param endAction Specifies what should happen when the final position is passed by `play()`/`autoplay`
+     *
+     * `"pause"`: **(default)** the Timeline will pause at its final position
+     * `"continue"`: The Timeline will continue progressing beyond its final position
+     * `"restart"`: The Timeline will seek back to 0 then forward to account for any overshoot and continue progressing
+     * `"wrap"`: The Timeline's position will continue to increase beyond the final position, but Points and Ranges will be activated as if looping
+     * `{restartAt: number}`: Like `"restart"` but seeking back to `restartAt` instead of 0
+     * `{wrapAt: number}`: Like `"wrap"` but as if restarting at `wrapAt` instead of 0
      */
-    thenWait(duration: number): TimelineChain;
-}
-export declare class Timeline {
-    private tweens;
-    private events;
-    private _position;
-    private _end;
-    private seeking;
-    private playInterval;
-    private currentSortDirection;
-    private smoothSeekTimeline?;
-    pauseAtEnd: boolean;
+    constructor(autoplay: boolean | number, endAction: {
+        wrapAt: number;
+    } | {
+        restartAt: number;
+    } | keyof typeof EndAction);
     /**
-     * @property Sets a time at which to rewind back to 0. If `true`, looping will occur after the final tween or event.
+     * @deprecated "loop" endAction will be removed; use "restart" or `{restartAt: 0}` (disambiguates new looping strategies)
      */
-    loop: number | boolean;
+    constructor(autoplay: boolean | number, endAction: "loop");
     /**
-     * @property Time delta multiplier to change speed. Affects `step()` and `play()`
+     * Defines a single point on the Timeline
+     *
+     * @param position
+     * @returns A point on the Timeline as specified
+     *
+     * Listenable: this point will emit a PointEvent whenever a `seek()` reaches or passes it
      */
-    timeScale: number;
+    point(position: number): TimelinePoint;
     /**
-     * @param autoPlay Pass true to autoplay at 60 FPS
-     * @param atEnd Choose what happens when the Timeline seeks beyond its final frame. Default is "pause"
+     * Defines a range on this Timeline
+     *
+     * @param start The position on this Timeline at which the range starts
+     * @param duration Length of the resulting range - if omitted, the range will end at the Timeline's **current** final position
+     * @returns A range on the Timeline
+     *
+     * Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
-    constructor(autoPlay?: boolean, atEnd?: EndAction);
+    range(start: number | TimelinePoint, duration?: number): TimelineRange;
     /**
-     * @param fps Pass a number, as frames per second, to autoplay at the specified frame rate.
-     * @param atEnd Choose what happens when the Timeline seeks beyond its final frame. Default is "pause"
+     * Creates an observable range from position 0 to the Timeline's **current** final position
      */
-    constructor(fps?: number | boolean, atEnd?: EndAction);
-    get position(): number;
+    range(): TimelineRange;
+    private getWrappedPosition;
     /**
-     * @property The final position at which an event or tween exists on this Timeline
+     * Seeks the Timeline to a specified position, triggering in order any point and range subscriptions between its current and new positions
+     * @param toPosition
      */
-    get end(): number;
+    seek(toPosition: number | TimelinePoint): void;
     /**
-     * Add a tween to this Timeline
-     * @param startTime Position at which tween starts
-     * @param duration Duration of tween
-     * @param apply Function called per frame, passed a value between `from` and `to` (with possible overshoot depending on easer)
-     * @param from Initial (pre-start) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 0)
-     * @param to Final (post-end) value to pass to `apply()`. If passed a function it will be called for each frame calculation. (default 1)
-     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
-     * @returns A chaining interface for the time at which the tween ends
+     * Smooth-seeks to a specified position
+     *
+     * Aborts and replaces any on-going smooth-seek process on this Timeline
+     * @param toPosition
+     * @param duration Duration of the smooth-seek process in milliseconds
+     * @param easer Optional easing function for the smooth-seek process
+     * @returns A promise, resolved when the smooth-seek process finishes
      */
-    tween(startTime: number, duration: number, apply: ApplyTweenFunc, from?: NumberOrNumberFunction, to?: NumberOrNumberFunction, ease?: EaseFunc): TimelineChain;
+    seek(toPosition: number | TimelinePoint, duration: number, easer?: Easer): Promise<void>;
+    private seekDirect;
+    private seekPoints;
+    private seekRanges;
+    private sortEntries;
     /**
-     * Add a tween to this Timeline
-     * @param tween Object describing the tween
-     * @returns A chaining interface for the time at which the tween ends
+     * Starts progression of the Timeline from its current position at (1000 x this.timeScale) units per second
      */
-    tween(tween: TweenData): TimelineChain;
+    play(): void;
+    play(fps: number): void;
+    pause(): void;
     /**
-     * Add a callback to run at a specified time
-     * @param time Time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time
-     * @param applyOnReverse Called when a backward seek passes this event's time. Default is no action
-     * @returns A chaining interface for the specified time
+     * Progresses the Timeline by 1 unit
+     * @param delta
+     * @deprecated Use timeline.position++
      */
-    at(time: number, apply: () => void, applyOnReverse?: () => void): TimelineChain;
+    step(): void;
     /**
-     * Add a callback to run at a specified time
-     * @param time Time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time
-     * @param applyOnReverse Pass true to call `apply` regardless of direction of traversal, or false to specify no reversion action
-     * @returns A chaining interface for the specified time
+     * Progresses the Timeline by a given delta
+     * @param delta
+     * @deprecated Use timeline.position += n
      */
-    at(time: number, apply: () => void, applyOnReverse: boolean): TimelineChain;
+    step(delta: number): void;
+    tween<T extends Tweenable>(start: number | TimelinePoint, duration: number, apply: (v: T) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    tween<T extends Tweenable>(start: number | TimelinePoint, end: TimelinePoint, // ease migration for tl.tween(0, tl.end, ...)
+    apply: (v: T) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
+    private createChainingInterface;
     /**
-     * Ensures end time extends to (at least) the specified time
-     * @param time
-     * @returns A chaining interface for the specified time
+     * @deprecated use `timeline.currentTime`
      */
-    at(time: number): TimelineChain;
+    get position(): number;
+}
+interface ChainingInterface {
+    thenTween(duration: number, apply: (v: number) => void, from?: number, to?: number, easer?: Easer): ChainingInterface;
+    then(action: () => void): ChainingInterface;
+    thenWait(duration: number): ChainingInterface;
+    readonly end: TimelinePoint;
+}
+export interface TimelineRange extends RangeProgression {
     /**
-     * Add a callback to run at a specified time
-     * @param time Time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time
-     * @param applyOnReverse Called when a backward seek targets or passes this event's time
-     * @returns A chaining interface for the specified time
+     * 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
      */
-    at(time: number, apply: false, applyOnReverse: () => void): TimelineChain;
+    bisect(position?: number): [TimelineRange, TimelineRange];
     /**
-     * Add a callback to run at a specified time, offset by the Timeline's current position
-     * @param time Offset, time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time
-     * @param revert Called when a backward seek passes this event's time. Default is no action
-     * @returns A chaining interface for the specified time
+     * Creates a series of evenly-spread points across the range, excluding the range's start and end
+     * @param count Number of Points to return
      */
-    in(time: number, apply?: () => void, revert?: () => void): TimelineChain;
+    spread(count: number): TimelinePoint[];
     /**
-     * Add a callback to run at a specified time, offset by the Timeline's current position (plus, if playing, time since the last update)
-     * @param time Offset, time at which this event will be triggered
-     * @param apply Called when a forward seek targets or passes this event's time
-     * @param applyOnReverse Pass true to call `apply` regardless of direction of traversal, or false to specify no reversion action
-     * @returns A chaining interface for the specified time
+     * Progresses the Timeline across the range
+     * @param easer
      */
-    in(time: number, apply: () => void, applyOnReverse: boolean): TimelineChain;
+    play(easer?: Easer): Promise<void>;
+    /** The point on the Timeline at which this range begins */
+    readonly start: TimelinePoint;
+    /** The point on the Timeline at which this range ends */
+    readonly end: TimelinePoint;
+    /** The duration of this range */
+    readonly duration: number;
+}
+export interface TimelinePoint extends Emitter<PointEvent> {
     /**
-     * Set the Timeline's position, applying intersecting tweens and events
-     * Ignores the `loop` property and sets position as specified
-     * @param time The new position
-     * @param smooth Milliseconds over which to smoothly seek
+     * Creates a range on the Timeline, with a given duration, starting at this point
+     * @param duration
      */
-    seek(time: number, smooth: number): void;
+    range(duration: number): TimelineRange;
     /**
-     * Set the Timeline's position, applying intersecting tweens and events
-     * Ignores the `loop` property and sets position as specified
-     * @param time The new position
-     * @param smooth Pass true to smooth-seek over 400ms
+     * Creates a range on the Timeline, with a given end point, starting at this point
+     * @param endPoint
      */
-    seek(time: number, smooth?: boolean): void;
-    private _seek;
+    to(endPoint: number | TimelinePoint): TimelineRange;
     /**
-     * Moves the timeline forwards (or backwards given negative delta) by a specified amount, applying intersecting tweens and events
-     * Honours `loop` ending action
-     * @param delta Amount of time to move forward by. This will be affected by the `timeScale` property
+     * Creates a point on the Timeline at an offset position from this one
+     * @param timeOffset
      */
-    step(delta?: number, smooth?: number | boolean): void;
-    private lastFrameTime;
+    delta(timeOffset: number): TimelinePoint;
     /**
-     * Begins moving forward in time from current `position` at a rate of 1000 x `timeScale` units per second
-     * If the timeline is already playing, it will stop and resume at the specified `fps`
-     * Honours `loop` and `pause` ending actions
-     * @param fps Frames per second
+     * The point's absolute position on the Timeline
      */
-    play(fps?: number): void;
+    readonly position: number;
+}
+type Tweenable = number | number[] | string | Blendable;
+interface Blendable {
+    blend(target: this, progress: number): this;
+}
+type Handler<T> = (value: T) => void;
+type Disposer = () => void;
+interface Emitter<T> {
     /**
-     * Pauses automatic progression started via `play()`
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
      */
-    pause(): void;
-    get isPlaying(): boolean;
+    listen(handler: Handler<T>): Disposer;
+    map<R>(mapFunc: (value: T) => R): Emitter<R>;
+}
+export interface TweenEmitter<T extends Tweenable> extends Emitter<T> {
+}
+export interface RangeProgression extends Emitter<number> {
     /**
-     * Creates a Timeline as a tween
-     * * Transposes the inner Timeline's `0` -> `innerDuration` to the parent Timeline's `startTime` -> `outerDuration`
-     * * Experimental - this functionality may change in future versions
-     * @param startTime Position on the parent Timeline at which the inner Timeline will start seeking
-     * @param outerDuration Length of time occupied on the parent Timeline by the inner Timeline
-     * @param innerDuration Duration of the inner Timeline to transpose to `startTime` -> `outerDuration`
-     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
-     * @returns
+     * 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 an eased value
      */
-    createInnerTimeline(startTime: number, outerDuration: number, innerDuration?: number, ease?: EaseFunc): Timeline;
-    private createChainInterface;
-    private seekTweens;
+    ease(easer?: Easer | keyof typeof easers): RangeProgression;
     /**
-     * Initialises and starts a Timeline using chained calls to specify tweens and events
-     * @param looping
-     * @returns
+     * Creates an 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 an interpolated value
      */
-    static start(looping?: boolean): TimelineChain;
+    tween<T extends Tweenable>(from: T, to: T): TweenEmitter<T>;
 }
+type Easer = (n: number) => number;
 export declare const easers: {
     linear: (x: number) => number;
     easeIn: (x: number) => number;
@@ -209,11 +255,4 @@ export declare const easers: {
     step3: (x: number) => 0 | 1 | 0.333 | 0.667;
     pingpong: (x: number) => number;
 };
-export declare const dynamicEasers: {
-    average: (easers: EaseFunc[]) => (x: number) => number;
-    blend: (fromEaser: EaseFunc, toEaser: EaseFunc, amount: number) => (x: number) => number;
-    sine: (freq?: number) => (x: number) => number;
-    multiply: (easer: EaseFunc, mul: number) => (x: number) => number;
-    combine: (easers: EaseFunc[]) => (x: number) => number;
-};
 export {};