Animation

Animation

/**
 * Type of data of animation event.
 */
interface AnimationEventData {
    /**
     * Current value. (In range [from, to].)
     */
    currentValue: number;
    /**
     * Current raw progress. (Linear; in range [0, 1].)
     */
    rawProgress: number;
    /**
     * Current progress. (`timing(rawProgress)`)
     */
    progress: number;
}

/**
 * Emits when animation starts. (stoppable&cancelable)
 */
type AnimationStartEvent = Event<'start', AnimationEventData>;

/**
 * Emits when animation stops(pauses). (stoppable&cancelable)
 */
type AnimationStopEvent = Event<'stop', AnimationEventData>;

/**
 * Emits when animation resumes. (stoppable&cancelable)
 */
type AnimationResumeEvent = Event<'resume', AnimationEventData>;

/**
 * Emits when animation updates. (cancelable)
 */
type AnimationUpdateEvent = Event<'update', AnimationEventData>;

/**
 * Emits when animation finishes. (stoppable&cancelable)
 */
type AnimationFinishEvent = Event<'finish', AnimationEventData>;

/**
 * Type map of animation events.
 */
type AnimationEvents = {
    start: AnimationStartEvent;
    stop: AnimationStopEvent;
    resume: AnimationResumeEvent;
    update: AnimationUpdateEvent;
    finish: AnimationFinishEvent;
};

/**
 * Type of options of {@link Animation}.
 */
type AnimationOptions<Events extends AnimationEvents> = Partial<{
    /**
     * Start value.
     * @default 0
     */
    from: number;
    /**
     * End value.
     * @default 1
     */
    to: number;
    /**
     * Duration of animation. (ms)
     * @default 1000
     */
    duration: number;
    /**
     * The timing function to use.
     * @default Timing.linear
     */
    timing: TimingFunction;
    /**
     * The callback that is automatically
     * attached to `update` event.
     */
    callback: EventListener<Events['update']>;
    /**
     * Whether to emit `update` events when animation starts.
     * @default true
     */
    updateOnStart: boolean;
}>;

/**
 * Class of animations.
 */
class Animation<Events extends AnimationEvents = AnimationEvents> extends EventEmitter<Events> {

    /**
     * Constructor of {@link Animation}.
     */
    constructor(options?: AnimationOptions<Events>);

    /**
     * Start value.
     * @default 0
     */
    from: number;

    /**
     * End value.
     * @default 1
     */
    to: number;

    /**
     * Duration of animation. (ms)
     * @default 1000
     */
    duration: number;

    /**
     * The timing function to use.
     * @default Timing.linear
     */
    timing: TimingFunction;

    /**
     * Whether to emit `update` events when animation starts.
     * @default true
     */
    updateOnStart: boolean;

    /**
     * Whether the animation is active.
     */
    get active(): boolean;

    /**
     * Current value. (In range [from, to].)
     */
    get currentValue(): number;

    /**
     * Current raw progress. (Linear; in range [0, 1].)
     */
    get rawProgress(): number;

    /**
     * Current progress. (`timing(rawProgress)`)
     */
    get progress(): number;

    /**
     * Start the animation.
     * (Executes `Schedule.animate(this)` automatically.)
     */
    start(timeStamp: number): void;

    /**
     * Stop the animation.
     * (Executes `Schedule.cancelAnimation(this)` automatically.)
     */
    stop(timeStamp: number): void;

    /**
     * Resume the animation.
     * (Executes `Schedule.animate(this)` automatically.)
     */
    resume(timeStamp: number): void;

    /**
     * Finish the animation.
     * (Executes `Schedule.cancelAnimation(this)` automatically.)
     */
    finish(timeStamp: number): void;

    /**
     * Update the animation.
     */
    update(timeStamp: number): void;
}