@xtia/timeline 1.0.0 → 1.0.2

package/README.md

@@ -93,6 +93,7 @@ eased.listen(
 const frames = eased
     .tween(0, 30)
     .map(Math.floor)
+    .noRepeat()
     .map(n => `animation-frame-${n}.png`)
     .listen(filename => img.src = filename);
 ```
@@ -210,7 +211,7 @@ const wrappingTimeline = new Timeline(true, "wrap");
 const foreverTimeline = new Timeline(true, "continue");
 
 // "pause" is the default behaviour: stop at the end
-const puasingTimeline = new Timeline(true, "pause");
+const pausingTimeline = new Timeline(true, "pause");
 
 // "restart" and "wrap" strategies can designate a position
 // to loop back to
@@ -266,6 +267,12 @@ resourceUrls.forEach(url => {
 });
 ```
 
+We can pass a second argument to `seek()` to perform a 'smooth seek' over the given duration. A third argument can provide an easing function for the smooth seek process:
+
+```ts
+timeline.seek(timeline.end, 400, "overshootIn");
+```
+
 ## Backward-compatibility
 
 Despite the massive overhaul, the previous API is present and expanded  and upgrading to 1.0.0 should be frictionless in the vast majority of cases.

package/index.d.ts

@@ -1,258 +1,5 @@
-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 {
-    /**
-     * 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
-     */
-    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();
-    /**
-     * @param autoplay Pass `true` to begin playing at (1000 x this.timeScale) units per second immediately on creation
-     */
-    constructor(autoplay: boolean);
-    /**
-     * Creates a Timeline that begins playing immediately at (1000 x this.timeScale) units per second
-     * @param autoplayFps Specifies frames per second
-     */
-    constructor(autoplayFps: number);
-    /**
-     * @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
-     */
-    constructor(autoplay: boolean | number, endAction: {
-        wrapAt: number;
-    } | {
-        restartAt: number;
-    } | keyof typeof EndAction);
-    /**
-     * @deprecated "loop" endAction will be removed; use "restart" or `{restartAt: 0}` (disambiguates new looping strategies)
-     */
-    constructor(autoplay: boolean | number, endAction: "loop");
-    /**
-     * 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
-     */
-    point(position: number): TimelinePoint;
-    /**
-     * 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
-     */
-    range(start: number | TimelinePoint, duration?: number): TimelineRange;
-    /**
-     * Creates an observable range from position 0 to the Timeline's **current** final position
-     */
-    range(): TimelineRange;
-    private getWrappedPosition;
-    /**
-     * Seeks the Timeline to a specified position, triggering in order any point and range subscriptions between its current and new positions
-     * @param toPosition
-     */
-    seek(toPosition: number | TimelinePoint): void;
-    /**
-     * 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
-     */
-    seek(toPosition: number | TimelinePoint, duration: number, easer?: Easer): Promise<void>;
-    private seekDirect;
-    private seekPoints;
-    private seekRanges;
-    private sortEntries;
-    /**
-     * Starts progression of the Timeline from its current position at (1000 x this.timeScale) units per second
-     */
-    play(): void;
-    play(fps: number): void;
-    pause(): void;
-    /**
-     * Progresses the Timeline by 1 unit
-     * @param delta
-     * @deprecated Use timeline.position++
-     */
-    step(): void;
-    /**
-     * Progresses the Timeline by a given delta
-     * @param delta
-     * @deprecated Use timeline.position += n
-     */
-    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;
-    /**
-     * @deprecated use `timeline.currentTime`
-     */
-    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 {
-    /**
-     * 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
-     */
-    bisect(position?: number): [TimelineRange, TimelineRange];
-    /**
-     * Creates a series of evenly-spread points across the range, excluding the range's start and end
-     * @param count Number of Points to return
-     */
-    spread(count: number): TimelinePoint[];
-    /**
-     * Progresses the Timeline across the range
-     * @param easer
-     */
-    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> {
-    /**
-     * Creates a range on the Timeline, with a given duration, starting at this point
-     * @param duration
-     */
-    range(duration: number): TimelineRange;
-    /**
-     * Creates a range on the Timeline, with a given end point, starting at this point
-     * @param endPoint
-     */
-    to(endPoint: number | TimelinePoint): TimelineRange;
-    /**
-     * Creates a point on the Timeline at an offset position from this one
-     * @param timeOffset
-     */
-    delta(timeOffset: number): TimelinePoint;
-    /**
-     * The point's absolute position on the Timeline
-     */
-    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> {
-    /**
-     * Registers a function to receive emitted values
-     * @param handler
-     * @returns A function to deregister the handler
-     */
-    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 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
-     */
-    ease(easer?: Easer | keyof typeof easers): RangeProgression;
-    /**
-     * 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
-     */
-    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;
-    easeIn4: (x: number) => number;
-    easeOut: (x: number) => number;
-    easeOut4: (x: number) => number;
-    circleIn: (x: number) => number;
-    circleIn4: (x: number) => number;
-    circleOut: (x: number) => number;
-    circleOut4: (x: number) => number;
-    easeInOut: (x: number) => number;
-    elastic: (x: number) => number;
-    overshootIn: (x: number) => number;
-    bounce: (x: number) => number;
-    noise: (x: number) => number;
-    step2: (x: number) => 0 | 1 | 0.5;
-    step3: (x: number) => 0 | 1 | 0.333 | 0.667;
-    pingpong: (x: number) => number;
-};
-export {};
+export { Timeline, animate, ChainingInterface } from "./internal/timeline";
+export { TimelinePoint, PointEvent } from "./internal/point";
+export { RangeProgression, TimelineRange } from "./internal/range";
+export { Emitter, UnsubscribeFunc } from "./internal/emitters";
+export { easers } from "./internal/easing";