figureone 0.15.10 → 1.0.0

package/types/js/figure/Animation/AnimationManager.d.ts

@@ -0,0 +1,392 @@
+import { FigureElement } from '../Element';
+import * as anim from './Animation';
+import type { Recorder } from '../Recorder/Recorder';
+import type { AnimationStep, OBJ_AnimationBuilder, OBJ_AnimationStep, OBJ_RotationAnimationStep, OBJ_ScaleAnimationStep, OBJ_TriggerAnimationStep, OBJ_PositionAnimationStep, OBJ_ColorAnimationStep, OBJ_OpacityAnimationStep, OBJ_TransformAnimationStep, OBJ_PulseTransformAnimationStep, OBJ_PulseAnimationStep, OBJ_ElementAnimationStep, OBJ_ScenarioAnimationStep, OBJ_ScenariosAnimationStep, OBJ_CustomAnimationStep } from './Animation';
+import TimeKeeper from '../TimeKeeper';
+import { NotificationManager } from '../../tools/tools';
+import { FunctionMap } from '../../tools/FunctionMap';
+import type { TypeWhen } from '../TimeKeeper';
+import type { TypeParsablePoint, TypeParsableTransform } from '../../tools/g2';
+import type { TypeColor } from '../../tools/types';
+import type { OBJ_Scenario } from '../Element';
+/**
+ * Animation start time options.
+ *
+ * {@link TypeWhen} | number | null
+ *
+ * When multiple animations need to be started, it is often
+ * desirable to synchronise their start times.
+ *
+ * `'nextFrame'` will start the animation on the
+ * next animation frame. Starting several animations with `nextFrame`
+ * will ensure they are all synchronized to that frame time.
+ *
+ * Similarly `'prevFrame'` starts the animation on the last animation
+ * frame.
+ *
+ * `'syncNow'` will start an animation at a synchronized 'now' time. The
+ * first time 'syncNow' is used, the current time will be stored and used
+ * for all subsequent calls to 'syncNow'. 'syncNow' is reset every
+ * time a new animation frame is drawn.
+ *
+ * Alternately, `'now'` can be used which will use the current time as
+ * the animation start time. As javascript is single threaded, using `'now`
+ * on multiple animations will result in them all having slightly different
+ * start times.
+ *
+ * A custom time can be used if a `number` is defined.
+ *
+ * `null` will result in `'nextFrame'` being used
+ * @typedef {TypeWhen | number | null} AnimationStartTime
+ * @group Misc Animation
+ */
+export type AnimationStartTime = TypeWhen | number | null;
+/**
+ * Start animation options object.
+ *
+ * @property {null | string} [name] name of animation to start - f null, then
+ * all animations associated with this animation manager will start (`null`)
+ * @property {AnimationStartTime} startTime when to
+ * start the animation
+ * @interface
+ * @group Misc Animation
+ */
+export type OBJ_AnimationStart = {
+    name?: string;
+    startTime: AnimationStartTime;
+};
+export type TypeAnimationManagerInputOptions = {
+    element?: FigureElement;
+    finishedCallback?: (string | (() => void)) | null;
+    recorder?: Recorder;
+    timeKeeper: TimeKeeper;
+};
+/**
+ * Animation Manager
+ *
+ * This class manages animations and creates animation steps for use in
+ * animations.
+ *
+ * Each {@link FigureElement} has its own `AnimationManager` in the
+ * `animations` property, though any
+ * animation manager can animate any other element. Therefore all parallel
+ * animations can go through the same manager, or be spread throughout
+ * different element's animation managers. Spread animations out between
+ * elements, or keeping them all in one `AnimationManager` can change how
+ * readable code is, how convenient it is to cancel running animations, and
+ * what order the animations are performed in (`AnimationManager`s tied
+ * to elements drawn earlier will perform their animation steps before those
+ * tied to elements drawn later). `AnimationManager`s will only be processed
+ * on each animation frame if the element they are tied to is not hidden.
+ *
+ * The `animations` property within `AnimationManager` is simply an array that
+ * contains a number {@link AnimationStep}s that are executed in parallel.
+ * Typically, these steps would themselves be {@link SerialAnimationStep}s or a
+ * series of animations. This means the animation manager is running a number of
+ * animation series in parallel.
+ *
+ *
+ * The `AnimationManager`s on {@link FigureElement}s should be used instead
+ * of instantiating this class separately, as those on `FigureElements` will
+ * be automatically processed every animation frame.
+ *
+ * @param
+ * @property {'animating' | 'idle' | 'waitingToStart'} state
+ * @property {Array<AnimationStep>} animations
+ * @property {NotificationManager} notifications
+ * @see {@link FigureElement}
+ * @see {@link AnimationBuilder}
+ * @example
+ * // At its heart the `AnimationManager` is just executing
+ * // an array of animation steps.
+ *
+ * // Create animation steps
+ * const position = new Fig.Animation.PositionAnimationStep({
+ *   element: p,
+ *   target: [1, 0],
+ *   duration: 2,
+ * });
+ * const rotation = new Fig.Animation.RotationAnimationStep({
+ *   element: p,
+ *   target: Math.PI,
+ *   duration: 2,
+ * });
+ *
+ * // Combine the animations into a SerialAnimationStep
+ * const series = new Fig.Animation.SerialAnimationStep([
+ *   position,
+ *   rotation,
+ * ]);
+ *
+ * // Add the animations to the animation manager and start
+ * p.animations.animations.push(series);
+ * p.animations.start();
+ *
+ * @example
+ * // Using the `new` method in `AnimationManager` creates a convenient
+ * // `AnimationBuilder` which extends a `SerialAnimationStep` by using
+ * // a fluent API pattern
+ * //
+ * // Create animation steps
+ * const position = new Fig.Animation.PositionAnimationStep({
+ *   element: p,
+ *   target: [1, 0],
+ *   duration: 2,
+ * });
+ * const rotation = new Fig.Animation.RotationAnimationStep({
+ *   element: p,
+ *   target: Math.PI,
+ *   duration: 2,
+ * });
+ *
+ * // Build and start the animation
+ * p.animations.new()
+ *   .then(position)
+ *   .then(rotation)
+ *   .start();
+ *
+ * @example
+ * // `AnimationStep`s can also be created from the `AnimationManager`
+ * // with the added convenience that the `FigureElement` that
+ * // has the `AnimationManager` will be used as the default
+ * // `element` property. This combined with the `AnimationBuilder`
+ * // makes defining most animations clean and readable code
+ *
+ * // Build and start the animation
+ * p.animations.new()
+ *   .position({ target: [1, 0], duration: 2 })
+ *   .rotation({ target: Math.PI, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Parallel animations however still need to use explicit animation steps.
+ * // Creating the steps from the `AnimationManager` means the `element` doesn't
+ * // need to be defined.
+ * //
+ * p.animations.new()
+ *   .inParallel([
+ *     p.animations.position({ target: [1, 0], duration: 2 }),
+ *     p.animations.rotation({ target: Math.PI, duration: 2 })
+ *   ])
+ *   .start();
+ * @group Animation
+ */
+export default class AnimationManager {
+    element: FigureElement | null | undefined;
+    animations: Array<anim.AnimationStep>;
+    state: 'animating' | 'idle' | 'waitingToStart';
+    fnMap: FunctionMap;
+    finishedCallback: (string | (() => void)) | null;
+    notifications: NotificationManager;
+    options: {
+        translation?: {
+            style: 'curve' | 'linear';
+            angle: number;
+            magnitude: number;
+            offset: number;
+            controlPoint: TypeParsablePoint | null;
+            direction: 'positive' | 'negative' | 'up' | 'down' | 'left' | 'right';
+        };
+    };
+    recorder: Recorder;
+    timeKeeper: TimeKeeper;
+    animationSpeed: number;
+    customSteps: Array<{
+        step: (options: Record<string, any>) => AnimationStep;
+        name: string;
+    }>;
+    /**
+     * @hideconstructor
+     */
+    constructor(elementOrOptionsIn?: FigureElement | TypeAnimationManagerInputOptions, ...optionsIn: Array<TypeAnimationManagerInputOptions>);
+    /**
+     * New animation builder attached to this animation manager
+     * @return AnimationBuilder
+     * @example
+     * p.animations.new()
+     *   .position({ target: [0.5, 0], duration: 2 })
+     *   .rotation({ target: Math.PI, duration: 2 })
+     *   .start();
+     *
+     */
+    new(name?: string | null): anim.AnimationBuilder;
+    /**
+     * Set time speed of animation relative to real time, where 1 is real time,
+     * <1 is slower than real time and >1 is faster than real time.
+     *
+     * @param {number} speed
+     */
+    setTimeSpeed(speed?: number): void;
+    /**
+     * Animation builder object
+     * @param {OBJ_AnimationBuilder} options
+     * @return {AnimationBuilder}
+     */
+    builder(...options: Array<OBJ_AnimationBuilder>): anim.AnimationBuilder;
+    /**
+     * Create a Rotation animation step that uses this element by default
+     * @param {OBJ_RotationAnimationStep} options
+     * @return {RotationAnimationStep}
+     * @example
+     * const rot = p.animations.rotation({ target: Math.PI, duration: 2 });
+     * p.animations.new()
+     *   .then(rot)
+     *   .start();
+     */
+    rotation(targetOrOptions: OBJ_RotationAnimationStep | number): any;
+    /**
+     * Create a Scale animation step tied to this element
+     * @param {TypeParsablePoint | OBJ_ScaleAnimationStep | number} targetOrOptionsOrX
+     * when a number is used, it will apply to both x and y if y is null
+     * @param {number | null} y use a number to define the y scale, or use null
+     * to use the `x` value (`null`)
+     * @return {ScaleAnimationStep}
+     */
+    scale(targetOrOptionsOrX: TypeParsablePoint | OBJ_ScaleAnimationStep | number, y?: null | number, z?: number): any;
+    /**
+     * Create a Trigger animation step
+     * @param {OBJ_TriggerAnimationStep | function(): void | string} callbackOrOptions
+     * callback can be a function or an id to a function map
+     * @return {TriggerAnimationStep}
+     */
+    trigger(callbackOrOptions: (() => void) | string | OBJ_TriggerAnimationStep): anim.TriggerAnimationStep;
+    /**
+     * Add a custom animation step that uses this element by default
+     * @param {string | ((number) => void) | OBJ_CustomAnimationStep} callbackOrOptions
+     * @return {AnimationBuilder}
+     */
+    custom(callbackOrOptions: string | ((percent: number) => void) | OBJ_CustomAnimationStep): anim.CustomAnimationStep;
+    /**
+     * Create a Delay animation step
+     * Use the `duration` value in `options` to define delay duration
+     * @param {number | OBJ_AnimationStep} delayOrOptions
+     * @return {DelayAnimationStep}
+     */
+    delay(delayOrOptions?: number | OBJ_AnimationStep): anim.DelayAnimationStep;
+    /**
+     * Create a Translation or Position animation step tied to this element
+     * @param {OBJ_PositionAnimationStep | TypeParsablePoint | number} targetOrOptionsOrX
+     * @param {number} y define if `targetOrOptionsOrX` is x (number)
+     * @return {PositionAnimationStep}
+     */
+    translation(targetOrOptionsOrX: TypeParsablePoint | OBJ_PositionAnimationStep | number, y?: number, z?: number): void;
+    /**
+     * Create a Translation or Position animation step tied to this element
+     * @param {OBJ_PositionAnimationStep | TypeParsablePoint | number} targetOrOptionsOrX
+     * @param {number} y define if `targetOrOptionsOrX` is x (number)
+     * @return {PositionAnimationStep}
+     */
+    position(targetOrOptionsOrX: TypeParsablePoint | OBJ_PositionAnimationStep | number, y?: number, z?: number): any;
+    /**
+     * Create a Color animation step tied to this element
+     * @param {OBJ_ColorAnimationStep | TypeColor} colorOrOptions
+     * @return {ColorAnimationStep}
+     */
+    color(colorOrOptions: OBJ_ColorAnimationStep | TypeColor): any;
+    /**
+     * Create a Opacity animation step tied to this element
+     * @param {OBJ_OpacityAnimationStep | number} opacityOrOptions
+     * @return {OpacityAnimationStep}
+     */
+    opacity(opacityOrOptions: OBJ_OpacityAnimationStep | number): any;
+    /**
+     * Create a Transform animation step tied to this element
+     * @param {OBJ_TransformAnimationStep | TypeParsableTransform} transformOrOptions
+     * @return {TransformAnimationStep}
+     */
+    transform(transformOrOptions: OBJ_TransformAnimationStep | TypeParsableTransform): any;
+    pulseTransform(...options: Array<OBJ_PulseTransformAnimationStep>): any;
+    /**
+     * Create a pulse animation step tied to this element
+     * @param {OBJ_PulseAnimationStep | number} scaleOrOptions pulse scale
+     * (number) or pulse animation step options
+     * @return {PulseAnimationStep}
+     */
+    pulse(scaleOrOptions: OBJ_PulseAnimationStep | number): any;
+    /**
+     * Create a Dissolve in animation step
+     * Use the `duration` value in `options` to define dissolving duration
+     * @param {number | OBJ_ElementAnimationStep} timeOrOptions
+     * @return {DissolveInAnimationStep}
+     */
+    dissolveIn(durationOrOptions?: number | OBJ_ElementAnimationStep): any;
+    /**
+     * Create a Dissolve out animation step
+     * Use the `duration` value in `options` to define dissolving duration
+     * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+     * @return {DissolveOutAnimationStep}
+     */
+    dissolveOut(durationOrOptions?: number | OBJ_ElementAnimationStep): any;
+    /**
+     * Create a Dim color animation step
+     * Use the `duration` value in `options` to define dimming duration
+     * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+     * @return {DimAnimationStep}
+     */
+    dim(durationOrOptions?: number | OBJ_ElementAnimationStep): any;
+    /**
+     * Create a Undim color animation step
+     * Use the `duration` value in `options` to define undimming duration
+     * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+     * @return {UndimAnimationStep}
+     */
+    undim(durationOrOptions?: number | OBJ_ColorAnimationStep): any;
+    getStep(options: Record<string, any>, animName: string): any;
+    /**
+     * Create a Scenario animation step tied to this element
+     * @param {OBJ_ScenarioAnimationStep | OBJ_Scenario | string} scenarioOrOptions
+     * @return {ScenarioAnimationStep}
+     */
+    scenario(scenarioOrOptions: string | OBJ_Scenario | OBJ_ScenarioAnimationStep): any;
+    /**
+     * Create a Parallel animation step that animates
+     * all child elements with the target scenario name
+     * @param {string | OBJ_ScenariosAnimationStep} scenarioNameOrOptions
+     * @return {ParallelAnimationStep}
+     */
+    scenarios(scenarioOrOptions: string | OBJ_ScenariosAnimationStep): anim.ParallelAnimationStep;
+    _state(options: Record<string, any>): Record<string, any>;
+    setTimeDelta(delta: number | null | undefined): void;
+    willStartAnimating(): boolean;
+    isAnimating(): boolean;
+    nextFrame(now: number): number | null;
+    cleanAnimations(): void;
+    /**
+     * Cancel one or all animations managed by this manager (in the `animations`
+     * array).
+     * @param {null | string} name name of animation or `null` to cancel all
+     * (`null`)
+     * @param {null | 'complete' | 'freeze'} force force the animation to complete
+     * or freeze - `null` will perform the default operation (`null`)
+     */
+    cancel(name?: string | null | undefined, force?: 'complete' | 'freeze' | null): void;
+    /**
+     * Get an animation by name.
+     @param {string} name
+     @return {AnimationStep | null}
+     */
+    get(name: string): anim.AnimationStep | null;
+    cancelAll(how?: 'complete' | 'freeze' | null, force?: boolean): void;
+    getFrameTime(frame: 'nextFrame' | 'prevFrame' | 'now' | 'syncNow'): void;
+    /**
+     * Start one or all animations managed by this manager (in the `animations`
+     * array).
+     *
+     * @param {OBJ_AnimationStart} [options]
+     */
+    start(options: OBJ_AnimationStart): void;
+    startAll(optionsIn: {
+        startTime?: AnimationStartTime;
+    }): void;
+    getTotalDuration(): number | null;
+    /**
+     * Get remaining duration of all animations
+     * @param {number} now define this if you want remaining duration from a
+     * custom time
+     */
+    getRemainingTime(animationNames?: Array<string> | string, now?: number): number;
+    getNextAnimationFinishTime(now?: number): null | number;
+    addTo(name: string): anim.AnimationStep | anim.AnimationBuilder;
+    newFromStep(nameOrStep: anim.AnimationStep): anim.AnimationStep;
+    _dup(): anim.AnimationManager;
+}

package/types/js/figure/Animation/AnimationStep/CustomStep.d.ts

@@ -0,0 +1,99 @@
+import type { OBJ_AnimationStep } from '../AnimationStep';
+import AnimationStep from '../AnimationStep';
+import type { AnimationStartTime } from '../AnimationManager';
+/**
+ * {@link CustomAnimationStep} options object
+ *
+ * @extends OBJ_AnimationStep
+ *
+ * @property {string | function(int): void} callback function to run each
+ * animation frame
+ * @property {number} [startPercent] percent to start animation at (`0`)
+ * @property {'linear' | 'easeinout' | 'easein' | 'easeout' | AnimationProgression} [progression]
+ * @interface
+ * @group Misc Animation
+ */
+export type OBJ_CustomAnimationStep = {
+    callback?: string | ((percent: number) => void);
+    startPercent?: number;
+    progression?: 'linear' | 'easeinout' | 'easein' | 'easeout' | ((percent: number) => number);
+    duration?: number | null;
+} & OBJ_AnimationStep;
+/**
+ * Custom animation step
+ *
+ * ![](./apiassets/custom_animation.gif)
+ *
+ * Custom animation steps are useful for orchestrating complex animations, or
+ * performing non-linear animations.
+ *
+ * This step will execute a custom callback function on each animation frame.
+ * Custom animations can either have finite `duration` or infinite
+ * (`duration` = `null`). If finite, the callback function will be passed
+ * percentage progress through the duration. If infinite, the callback function
+ * will be passed the delta time from the start of the animation.
+ *
+ * The animation can be stopped at any time by returning `true` from the
+ * callback funciton/
+ *
+ * For finite durations, the percentage progress can either be linear with
+ * time, or non-linear.
+ *  Built-in non-linear progressions are `'easeinout'`, `'easein`' and
+ * `'easeout'` which will slow progress at the start and/or end of the
+ * animation. A function to create a custom non-linear progressor can also be
+ * used.
+ *
+ * @extends AnimationStep
+ *
+ * @param {OBJ_CustomAnimationStep} options
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Move an object through a sine wave of wavelength 1 from
+ * // x = -1 to x = 1
+ * function sine(percentComplete) {
+ *   const x = -1 + percentComplete * 2;
+ *   const y = 0.5 * Math.sin(Math.PI * 2 * x);
+ *   p.setPosition(x, y);
+ * }
+ *
+ * p.animations.new()
+ *   .custom({ callback: sine, duration: 5 })
+ *   .start();
+ *
+ * @example
+ * // Animate a object in a circle indefinitely at a frequency of 0.1Hz
+ * p.animations.new()
+ *   .custom({
+ *     callback: (t) => {
+ *       const x = 0.5 * Math.cos(2 * Math.PI * 0.1 * t);
+ *       const y = 0.5 * Math.sin(2 * Math.PI * 0.1 * t);
+ *       p.setPosition(x, y);
+ *     },
+ *     duration: null,
+ *   })
+ *   .start();
+ * @group Animation
+ */
+export declare class CustomAnimationStep extends AnimationStep {
+    callback: ((percent: number) => void) | null;
+    startPercent: number | null | undefined;
+    progression: string | ((percent: number, invert?: boolean) => number);
+    customProperties: Record<string, any>;
+    isInfinite: boolean;
+    /**
+     * @hideconstructor
+     */
+    constructor(...optionsIn: Array<OBJ_CustomAnimationStep>);
+    fnExec(idOrFn: string | Function | null, ...args: any): any;
+    start(startTime?: AnimationStartTime | null): void;
+    _getStateProperties(): string[];
+    _getStateName(): string;
+    setFrame(deltaTime: number): void;
+    getPercentComplete(percentTime: number, invert?: boolean): any;
+    setToEnd(): void;
+    _dup(): CustomAnimationStep;
+}
+export declare function custom(...optionsIn: Array<OBJ_CustomAnimationStep>): CustomAnimationStep;

package/types/js/figure/Animation/AnimationStep/DelayStep.d.ts

@@ -0,0 +1,24 @@
+import type { OBJ_AnimationStep } from '../AnimationStep';
+import AnimationStep from '../AnimationStep';
+import type { AnimationStartTime } from '../AnimationManager';
+/**
+ * Delay animation step
+ *
+ * While all animations steps accept a delay property,
+ * having this step sometimes makes the animation seem
+ * more readable.
+ *
+ * @param {number | OBJ_AnimationStep} delayOrOptions
+ * @extends AnimationStep
+ * @group Animation
+ */
+export declare class DelayAnimationStep extends AnimationStep {
+    /**
+     * @hideconstructor
+     */
+    constructor(numOrOptions?: number | OBJ_AnimationStep, ...args: Array<OBJ_AnimationStep>);
+    _dup(): DelayAnimationStep;
+    start(startTime?: AnimationStartTime | null): void;
+    _getStateName(): string;
+}
+export declare function delay(numOrOptionsIn?: number | OBJ_AnimationStep, ...args: Array<OBJ_AnimationStep>): DelayAnimationStep;