figureone 0.15.10 → 1.0.0

package/types/js/figure/Animation/AnimationStep/ElementAnimationStep/ColorAnimationStep.d.ts

@@ -0,0 +1,203 @@
+import type { OBJ_ElementAnimationStep } from '../ElementAnimationStep';
+import type { OBJ_OpacityAnimationStep } from './OpacityAnimationStep';
+import ElementAnimationStep from '../ElementAnimationStep';
+import type { TypeColor } from '../../../../tools/types';
+import type { AnimationStartTime } from '../../AnimationManager';
+/**
+ * {@link ColorAnimationStep} options object
+ *
+ * @extends OBJ_ElementAnimationStep
+ * @property {Array<number>} [start]
+ * @property {Array<number> | 'dim' | 'undim'} [target] use `dim` to animate to
+ * element's `dimColor`, and `undim` to animate to element's `defaultColor`
+ * @property {Array<number>} [delta]
+ *
+ * @interface
+ * @group Misc Animation
+ */
+export type OBJ_ColorAnimationStep = {
+    start?: TypeColor;
+    target?: TypeColor | 'dim' | 'undim';
+    delta?: TypeColor;
+    dissolve?: 'in' | 'out' | null;
+} & OBJ_ElementAnimationStep;
+/**
+ * Color animation Step
+ *
+ * ![](./apiassets/color_animation.gif)
+ *
+ * By default, the color will start with the element's current color.
+ *
+ * Use either `delta` or `target` to define the end color
+ *
+ * In an interactive figure, it is often useful to highlight elements of the
+ * figure by coloring them and greying out, or dimming the elements not of
+ * interest. As such, a {@link FigureElement} has several color attributes:
+ * - color - current color
+ * - dimColor - color to dim to
+ * - defaultColor - color to undim to
+ *
+ * The `target` property can accept `'dim'` and `'undim'` as shortcuts to dim
+ * or undim the element.
+ *
+ * In addition, the {@link DimAnimationStep} and {@link UndimAnimationStep} can
+ * be used to do the same, which is especially useful when trying to build
+ * easy to read code in a complex animation.
+ *
+ * @extends ElementAnimationStep
+ * @param {OBJ_ColorAnimationStep} options
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Using duration
+ * p.animations.new()
+ *   .color({ target: [0, 0, 1, 1], duration: 1 })
+ *   .color({ target: [0, 0.8, 0, 1], duration: 1 })
+ *   .color({ target: [1, 0, 0, 1], duration: 1 })
+ *   .start();
+ *
+ * @example
+ * // dim and undim an element using dim and undim animation steps
+ * p.animations.new()
+ *   .dim(1)
+ *   .delay(1)
+ *   .undim(1)
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.color({
+ *   target: [0, 0, 1, 1],
+ *   duration: 2,
+ * });
+ * const step2 = new Fig.Animation.ColorAnimationStep({
+ *   element: p,
+ *   target: [0, 0.8, 0, 1],
+ *   duration: 2,
+ * });
+ *
+ * p.animations.new()
+ *   .then(step1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export declare class ColorAnimationStep extends ElementAnimationStep {
+    color: {
+        start: TypeColor;
+        delta: TypeColor;
+        target: TypeColor;
+        whenComplete: TypeColor;
+        dissolve?: 'in' | 'out' | null;
+        setDefault?: boolean;
+    };
+    /**
+     * @hideconstructor
+     */
+    constructor(...options: Array<OBJ_ColorAnimationStep>);
+    _getStateProperties(): string[];
+    _getStateName(): string;
+    start(startTime?: AnimationStartTime | null): void;
+    setFrame(deltaTime: number): void;
+    setToEnd(): void;
+    _dup(): ColorAnimationStep;
+}
+/**
+ * Dim color animation step
+ *
+ * ![](./apiassets/dim_animation.gif)
+ *
+ * Animates color of element to the `dimColor` property of {@link FigureElement}
+ *
+ * @extends ColorAnimationStep
+ * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Simple dim
+ * p.animations.new()
+ *   .dim(2)
+ *   .start();
+ *
+ * @example
+ * // Dim using options object
+ * p.animations.new()
+ *   .dim({ delay: 1, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.dim(2);
+ * const step2 = new Fig.Animation.DimAnimationStep({
+ *   element: p,
+ *   duration: 2,
+ * });
+ *
+ * p.animations.new()
+ *   .then(step1)
+ *   .undim(1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export declare class DimAnimationStep extends ColorAnimationStep {
+    /**
+     * @hideconstructor
+     */
+    constructor(timeOrOptionsIn?: number | OBJ_ElementAnimationStep, ...args: Array<OBJ_ElementAnimationStep>);
+}
+export declare function dim(timeOrOptionsIn?: number | OBJ_OpacityAnimationStep, ...args: Array<OBJ_OpacityAnimationStep>): DimAnimationStep;
+/**
+ * Undim color animation step
+ *
+ * ![](./apiassets/undim_animation.gif)
+ *
+ * Animates color of element to the `defaultColor` property of {@link FigureElement}
+ *
+ * @extends ColorAnimationStep
+ * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Simple undim
+ * p.dim();
+ * p.animations.new()
+ *   .undim(2)
+ *   .start();
+ *
+ * @example
+ * // Undim using options object
+ * p.dim();
+ * p.animations.new()
+ *   .undim({ delay: 1, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.undim(2);
+ * const step2 = new Fig.Animation.UndimAnimationStep({
+ *   element: p,
+ *   duration: 2,
+ * });
+ *
+ * p.dim();
+ * p.animations.new()
+ *   .then(step1)
+ *   .dim(1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export declare class UndimAnimationStep extends ColorAnimationStep {
+    /**
+     * @hideconstructor
+     */
+    constructor(timeOrOptionsIn?: number | OBJ_ElementAnimationStep, ...args: Array<OBJ_ElementAnimationStep>);
+}
+export declare function undim(timeOrOptionsIn?: number | OBJ_OpacityAnimationStep, ...args: Array<OBJ_OpacityAnimationStep>): UndimAnimationStep;

package/types/js/figure/Animation/AnimationStep/ElementAnimationStep/OpacityAnimationStep.d.ts

@@ -0,0 +1,220 @@
+import type { OBJ_ElementAnimationStep } from '../ElementAnimationStep';
+import ElementAnimationStep from '../ElementAnimationStep';
+import type { AnimationStartTime } from '../../AnimationManager';
+/**
+ * {@link OpacityAnimationStep} options object
+ *
+ * @extends OBJ_ElementAnimationStep
+ *
+ * @property {number} [start]
+ * @property {number} [target]
+ * @property {number} [delta]
+ * @property {null | 'in' | 'out'} dissolve will override target opacity if not
+ * `null` (`null`)
+ * @property {boolean} dissolveFromCurrent (`false`)
+ * @interface
+ * @group Misc Animation
+ */
+export type OBJ_OpacityAnimationStep = {
+    start?: number;
+    target?: number;
+    delta?: number;
+    dissolve?: 'in' | 'out' | null;
+    dissolveFromCurrent?: boolean;
+} & OBJ_ElementAnimationStep;
+/**
+ * Opacity Animation Step
+ *
+ * ![](./apiassets/opacity_animation.gif)
+ *
+ * A {@link FigureElement} has `color` and `opacity` properties. The `color`
+ * property has an alpha channel that defines opacity, but it should be used
+ * as a base color definition, and not used to dissolve an element in and out.
+ *
+ * Therefore, to animate an element's opacity or temporarily dissolve in or out
+ * an element, use an opacity animation step.
+ *
+ * The `opacity` is multiplied by the
+ * `color` alpha channel to get the final opacity of the element.
+ *
+ * By default, the opacity will start with the {@link FigureElement}'s current
+ * opacity unless dissolving. If dissolving, the opacity will start at `0` if
+ * dissolving in, or `1` if dissolving out unless `dissolveFromCurrent` is
+ * `true` in which case the opacity will start from the current opacity.
+ *
+ * The {@link DissolveInAnimationStep} and {@link DissolveOutAnimationStep}
+ * extend the `OpacityAnimationStep` to make it even more convenient to
+ * dissolve.
+ *
+ * @extends ElementAnimationStep
+ * @param {OBJ_OpacityAnimationStep} options
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Using numerical values for opacity
+ * p.animations.new()
+ *   .opacity({ target: 0.4, duration: 2 })
+ *   .opacity({ target: 1, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Dissolve out then in
+ * p.animations.new()
+ *   .opacity({ dissolve: 'out', duration: 2 })
+ *   .opacity({ dissolve: 'in', duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Using the dissolve animation step
+ * p.animations.new()
+ *   .dissolveOut(2)
+ *   .dissolveIn({ delay: 1, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.opacity({
+ *   target: 0,
+ *   duration: 2,
+ * });
+ * const step2 = new Fig.Animation.OpacityAnimationStep({
+ *   element: p,
+ *   target: 1,
+ *   duration: 2,
+ * });
+ * const step3 = p.animations.dissolveOut({
+ *   duration: 2,
+ * });
+ * const step4 = new Fig.Animation.DissolveInAnimationStep({
+ *   element: p,
+ *   duration: 2,
+ * });
+ *
+ * p.animations.new()
+ *   .then(step1)
+ *   .then(step2)
+ *   .then(step3)
+ *   .then(step4)
+ *   .start();
+ * @group Animation
+ */
+export declare class OpacityAnimationStep extends ElementAnimationStep {
+    opacity: {
+        start: number;
+        delta: number;
+        target: number;
+        whenComplete: number;
+        dissolve?: 'in' | 'out' | null;
+        dissolveFromCurrent: boolean;
+    };
+    /**
+     * @hideconstructor
+     */
+    constructor(...optionsIn: Array<OBJ_OpacityAnimationStep>);
+    _getStateProperties(): string[];
+    _getStateName(): string;
+    start(startTime?: AnimationStartTime | null): void;
+    cancelledWithNoComplete(): void;
+    setFrame(deltaTime: number): void;
+    setToEnd(): void;
+    _dup(): OpacityAnimationStep;
+}
+/**
+ * Dissolve in animation step
+ *
+ * ![](./apiassets/dissolvein_animation.gif)
+ *
+ * Animates opacity of element to dissolve in.
+ *
+ * @extends OpacityAnimationStep
+ * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Simple dissolve in
+ * p.setOpacity(0)
+ * p.animations.new()
+ *   .dissolveIn(2)
+ *   .start();
+ *
+ * @example
+ * // Dissolve in using options object
+ * p.setOpacity(0);
+ * p.animations.new()
+ *   .dissolveIn({ delay: 1, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.dissolveIn(2);
+ * const step2 = new Fig.Animation.DissolveInAnimationStep({
+ *   element: p,
+ *   duration: 2,
+ * });
+ *
+ * p.setOpacity(0);
+ * p.animations.new()
+ *   .then(step1)
+ *   .dissolveOut(1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export declare class DissolveInAnimationStep extends OpacityAnimationStep {
+    /**
+     * @hideconstructor
+     */
+    constructor(timeOrOptionsIn?: number | OBJ_ElementAnimationStep, ...args: Array<OBJ_ElementAnimationStep>);
+}
+export declare function dissolveIn(timeOrOptionsIn?: number | OBJ_OpacityAnimationStep, ...args: Array<OBJ_OpacityAnimationStep>): DissolveInAnimationStep;
+/**
+ * Dissolve out animation step
+ *
+ * ![](./apiassets/dissolveout_animation.gif)
+ *
+ * Animates opacity of element to dissolve out.
+ *
+ * @extends OpacityAnimationStep
+ * @param {number | OBJ_ElementAnimationStep} durationOrOptions
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Simple dissolve out
+ * p.animations.new()
+ *   .dissolveOut(2)
+ *   .start();
+ *
+ * @example
+ * // Dissolve out using options object
+ * p.animations.new()
+ *   .dissolveOut({ delay: 1, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.dissolveOut(2);
+ * const step2 = new Fig.Animation.DissolveOutAnimationStep({
+ *   element: p,
+ *   duration: 2,
+ * });
+ *
+ * p.animations.new()
+ *   .then(step1)
+ *   .dissolveIn(1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export declare class DissolveOutAnimationStep extends OpacityAnimationStep {
+    /**
+     * @hideconstructor
+     */
+    constructor(timeOrOptionsIn?: number | OBJ_ElementAnimationStep, ...args: Array<OBJ_ElementAnimationStep>);
+}
+export declare function dissolveOut(timeOrOptionsIn?: number | OBJ_OpacityAnimationStep, ...args: Array<OBJ_OpacityAnimationStep>): DissolveOutAnimationStep;

package/types/js/figure/Animation/AnimationStep/ElementAnimationStep/PositionAnimationStep.d.ts

@@ -0,0 +1,124 @@
+import { Point } from '../../../../tools/g2';
+import type { OBJ_TranslationPath } from '../../../../tools/g2';
+import type { OBJ_ElementAnimationStep } from '../ElementAnimationStep';
+import ElementAnimationStep from '../ElementAnimationStep';
+import type { AnimationStartTime } from '../../AnimationManager';
+/**
+ * {@link PositionAnimationStep} options object
+ *
+ * @extends OBJ_ElementAnimationStep
+ *
+ * @property {TypeParsablePoint} [start] start position - if undefined then
+ * current position is used
+ * @property {TypeParsablePoint} [target] target position - if undefined then
+ * `delta` is used
+ * @property {TypeParsablePoint} [delta] target delta - only used if `target`
+ * is undefined
+ * @property {null | TypeParsablePoint | number} [velocity] velocity of
+ * position overrides `duration` - `null` to use `duration` (`null`)
+ * @property {number} [null | maxDuration] maximum duration to cap to -
+ * `null` for no cap (`null`)
+ * @property {OBJ_TranslationPath} [path] (`{ style: 'linear' }`)
+ * @property {number | null} [maxDuration] maximum duration to clip animation
+ * to where `null` is unlimited (`null`)
+ *
+ * @see {@link PositionAnimationStep} for description and examples
+ * @interface
+ * @group Misc Animation
+ */
+export type OBJ_PositionAnimationStep = {
+    start?: Point;
+    target?: Point;
+    delta?: Point;
+    path?: OBJ_TranslationPath;
+    velocity?: Point;
+    maxDuration?: number;
+} & OBJ_ElementAnimationStep;
+/**
+ * Position animation step
+ *
+ * ![](./apiassets/position_animation.gif)
+ *
+ * The position animation step animates the first {@link Translation} transform
+ * in the {@link FigureElement}'s {@link Transform}.
+ *
+ * By default, the position will start with the element's current position.
+ *
+ * Use either `delta` or `target` to define it's end point.
+ *
+ * The path of travel between `start` and `target` can either be a straight
+ * line (`'linear'`) or a quadratic bezier curve (`'curve'`)
+ *
+ * For custom paths, the {@link CustomAnimationStep} can be used.
+ *
+ *
+ * @extends ElementAnimationStep
+ *
+ * @param {OBJ_PositionAnimationStep} options
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Using duration
+ * p.animations.new()
+ *   .position({ target: [1, 0], duration: 2 })
+ *   .start()
+ *
+ * @example
+ * // Using velocity
+ * p.animations.new()
+ *   .position({ target: [1, 0], velocity: 0.5 })
+ *   .start()
+ *
+ * @example
+ * // Linear and curved path
+ * p.animations.new()
+ *   .delay(1)
+ *   .position({ target: [1, 0], duration: 2 })
+ *   .position({
+ *     target: [0, 0],
+ *     duration: 2,
+ *     path: {
+ *       style: 'curve',
+ *       magnitude: 0.8,
+ *       direction: 'up',
+ *     },
+ *   })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.position({ target: [1, 0], duration: 2 });
+ * const step2 = new Fig.Animation.PositionAnimationStep({
+ *   element: p,
+ *   target: [0, 0],
+ *   duration: 2,
+ * });
+ *
+ * p.animations.new()
+ *   .then(step1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export default class PositionAnimationStep extends ElementAnimationStep {
+    position: {
+        start: Point | null | undefined;
+        delta: Point | null | undefined;
+        target: Point | null | undefined;
+        path: OBJ_TranslationPath;
+        velocity: Point | null | undefined;
+        maxDuration: number | null | undefined;
+    };
+    /**
+     * @hideconstructor
+     */
+    constructor(...optionsIn: Array<OBJ_PositionAnimationStep>);
+    _getStateProperties(): string[];
+    _getStateName(): string;
+    start(startTime?: AnimationStartTime | null): void;
+    setFrame(deltaTime: number): void;
+    setToEnd(): void;
+    _dup(): PositionAnimationStep;
+}

package/types/js/figure/Animation/AnimationStep/ElementAnimationStep/PulseAnimationStep.d.ts

@@ -0,0 +1,137 @@
+import type { TypeParsablePoint } from '../../../../tools/g2';
+import type { OBJ_ElementAnimationStep } from '../ElementAnimationStep';
+import ElementAnimationStep from '../ElementAnimationStep';
+import type { TypeWhen } from '../../../TimeKeeper';
+import type { FigureElement } from '../../../Element';
+/**
+ * {@link PulseAnimationStep} options object
+ *
+ * @extends OBJ_ElementAnimationStep
+ * @property {number} [frequency] pulse frequency in Hz - a frequency of zero
+ * will set the frequency so just one cycle will be performed in the duration
+ * (`0`)
+ * @property {number} [scale] maximum scale value to pulse to (`1.5`)
+ * @property {number} [rotation] maximum rotation value to pulse to
+ * @property {number} [translation] maximum translation displacment value to
+ * pulse to (`1.5`)
+ * @property {number} [angle] translation angle (`0`)
+ * @property {number} [min] minimum value to pulse to
+ * @property {null | FigureElement | TypeParsablePoint} [centerOn] center
+ * of scale or rotation pulse. By default, the element calling the pulse
+ * will be the default `centerOn`.
+ * @property {'left' | 'center' | 'right' | 'location' | number} [xAlign]
+ * if `centerOn` is a {@link FigureElement} then this property can be used to
+ * horizontally align the pulse center with the element. `'location'` is the
+ * (0, 0) draw space coordinate of the element. `number` defines the percent
+ * width from the left of the element (`'center'`)
+ * @property {'bottom' | 'middle' | 'top' | 'location' | number} [yAlign]
+ * if `centerOn` is a {@link FigureElement} then this property can be used to
+ * vertically align the pulse center with the element. `'location'` is the
+ * (0, 0) draw space coordinate of the element. `number` defines the percent
+ * width from the left of the element (`'center'`)
+ * @property {'figure' | 'gl' | 'local' | 'draw' | 'pixel'} [space]
+ * if `centerOn` is a point, use this to define the space the point is in
+ * (`'figure'`)
+ * @property {number} [num] the number of draw copies of the pulse to make (`1`)
+ * @property {null | string | function(): void} [done] callback when pulse is
+ * finished. If `string` then the element's {@link FunctionMap} `fnMap` will be
+ * used (`null`)
+ * @property {TypeWhen} [when] when to start the pulse (`'syncNow'`)
+ *
+ * @interface
+ * @group Misc Animation
+ */
+export type OBJ_PulseAnimationStep = {
+    stopAfterDuration?: boolean | null | undefined;
+    frequency?: number;
+    scale?: number;
+    rotation?: number;
+    translation?: number;
+    angle?: number;
+    min?: number;
+    centerOn?: null | FigureElement | TypeParsablePoint;
+    xAlign?: 'left' | 'center' | 'right' | 'origin' | number;
+    yAlign?: 'bottom' | 'middle' | 'top' | 'origin' | number;
+    space?: 'figure' | 'gl' | 'local' | 'draw';
+    done?: ((arg: any) => void) | null | undefined;
+    num?: number;
+    when?: TypeWhen;
+} & OBJ_ElementAnimationStep;
+/**
+ * Pulse animation step
+ *
+ * ![](./apiassets/pulse_animation.gif)
+ *
+ * The pulse animation step animates a pulse.
+ *
+ * The options are the same as those in the * <a href="#figureelementpulse">pulse</a> method.
+ *
+ * @extends ElementAnimationStep
+ * @param {OBJ_PulseAnimationStep} options
+ *
+ *
+ * @see To test examples, append them to the
+ * <a href="#animation-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Scale pulse, rotation pulse and translation pulse
+ * p.animations.new()
+ *   .pulse({
+ *     scale: 1.5,
+ *     duration: 1,
+ *   })
+ *   .pulse({
+ *     duration: 1,
+ *     rotation: 0.15,
+ *     frequency: 4,
+ *   })
+ *   .pulse({
+ *     duration: 1,
+ *     translation: 0.02,
+ *     min: -0.02,
+ *     frequency: 4,
+ *   })
+ *   .start();
+ *
+ * @example
+ * // Different ways to create a stand-alone step
+ * const step1 = p.animations.pulse({
+ *   scale: 1.5,
+ *   duration: 1,
+ * });
+ * const step2 = new Fig.Animation.PulseAnimationStep({
+ *   element: p,
+ *   rotation: 0.15,
+ *   frequency: 4,
+ * });
+ * p.animations.new()
+ *   .then(step1)
+ *   .then(step2)
+ *   .start();
+ * @group Animation
+ */
+export default class PulseAnimationStep extends ElementAnimationStep {
+    pulse: {
+        frequency: number;
+        scale: number;
+        rotation?: number;
+        translation?: number;
+        angle: number;
+        min: number;
+        centerOn: null | FigureElement | TypeParsablePoint;
+        xAlign: 'left' | 'center' | 'right' | 'origin' | number;
+        yAlign: 'bottom' | 'middle' | 'top' | 'origin' | number;
+        space: 'figure' | 'gl' | 'local' | 'draw';
+        done: ((arg: any) => void) | null | undefined;
+        num: number;
+        when: TypeWhen;
+        stopAfterDuration: boolean;
+    };
+    toStart: boolean;
+    constructor(...optionsIn: Array<OBJ_PulseAnimationStep>);
+    _getStateProperties(): string[];
+    _getStateName(): string;
+    setFrame(): void;
+    setToEnd(): void;
+    _dup(): PulseAnimationStep;
+}