figureone 0.15.10 → 1.0.0

package/types/js/figure/Equation/Equation.d.ts

@@ -0,0 +1,984 @@
+import { Point, Transform } from '../../tools/g2';
+import { FigureElementPrimitive, FigureElementCollection, FigureElement } from '../Element';
+import { FigureFont } from '../DrawingObjects/TextObject/TextObject';
+import type { ElementInterface } from './Elements/Element';
+import EquationForm from './EquationForm';
+import type { TypeHAlign, TypeVAlign } from './EquationForm';
+import EquationSymbols from './EquationSymbols';
+import { EquationFunctions } from './EquationFunctions';
+import type { TypeEquationPhrase } from './EquationFunctions';
+import type { TypeColor, OBJ_Font } from '../../tools/types';
+import type { TypeParsablePoint, TypeBorder, TypeParsableBuffer } from '../../tools/g2';
+import type { OBJ_TriggerAnimationStep } from '../Animation/Animation';
+import { AnimationManager, TriggerAnimationStep } from '../Animation/Animation';
+import type { EQN_VinculumSymbol, EQN_BoxSymbol, EQN_ArrowSymbol, EQN_SumSymbol, EQN_ProdSymbol, EQN_IntegralSymbol, EQN_StrikeSymbol, EQN_BracketSymbol, EQN_AngleBracketSymbol, EQN_BraceSymbol, EQN_BarSymbol, EQN_SquareBracketSymbol, EQN_RadicalSymbol, EQN_LineSymbol } from './EquationSymbols';
+import type { OBJ_FigureForElement } from '../Figure';
+import type { TypeText } from '../FigurePrimitives/FigurePrimitiveTypes';
+/**
+ * Object that defines new text for a selection of equation elements.
+ *
+ * Each key in the object is the name of the equation element whose text is to
+ * be updated.
+ *
+ * @property {string | FigureElement} [_elementName]
+ * @interface
+ * @group Misc Equation
+ */
+export type EQN_UpdateElementText = {
+    [elementName: string]: string | FigureElement;
+};
+/**
+ * Object where keys are property names of a {@link FigureElement} and values
+ * are the values to set the properties to.
+ *
+ * @property {any} [_propertyName]
+ * @interface
+ * @group Misc Figure Element
+ */
+export type OBJ_ElementPropertyMod = {
+    [propertyName: string]: any;
+};
+/**
+ * Object where keys are equation element names, and values are objects
+ * describing which element properties to modify after creation.
+ *
+ * @property {OBJ_ElementPropertyMod} [_elementName]
+ * @interface
+ * @group Misc Figure Element
+ */
+export type OBJ_ElementMods = {
+    [elementName: string]: OBJ_ElementPropertyMod;
+};
+/**
+ * Definition of a text or equation element.
+ *
+ * The properties 'color', 'isTouchable', 'onClick' and `touchBorder`
+ * modify the corresponding properties on the {@link FigureElementPrimitive}
+ * itself, and so could equally be set in `mods`. They are provided in the
+ * root object for convenience as they are commonly used.
+ *
+ * @property {string} [text] - Text element only
+ * @property {OBJ_Font} [font] - Text element only
+ * @property {'italic' | 'normal'} [style] - Text element only
+ * @property {object} [mods] - Properties to set on instantiated element
+ * @property {TypeColor} [color] - Color to set the element
+ * @property {boolean} [isTouchable] - make the element touchable
+ * @property {() => void | 'string' | null} [onClick] - called when touched
+ * @property {TypeBorder | 'border' | number | 'rect' | 'draw' | 'buffer'} [touchBorder]
+ * set the element's touch border
+ * @property {OBJ_ElementMods} [mods]
+ * @interface
+ * @group Equations
+ */
+export type EQN_TextElement = string | {
+    text?: string;
+    font?: OBJ_Font;
+    style?: 'italic' | 'normal' | null;
+    weight?: 'normal' | 'bold' | 'lighter' | 'bolder' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+    size?: number;
+    color?: TypeColor;
+    isTouchable?: boolean;
+    onClick?: (() => void) | 'string' | null;
+    touchBorder?: TypeBorder | 'border' | number | 'rect' | 'draw' | 'buffer';
+    mods?: OBJ_ElementMods;
+} | FigureElementPrimitive | FigureElementCollection;
+/**
+ * An equation element can be any of the below. If `string`, then a
+ * {@link EQN_TextElement} will be used where the `text` property is the
+ * `string`.
+ *
+ * - `string`
+ * - {@link FigureElementPrimitive}
+ * - {@link FigureElementCollection}
+ * - {@link EQN_TextElement}
+ * - {@link EQN_VinculumSymbol}
+ * - {@link EQN_BoxSymbol}
+ * - {@link EQN_ArrowSymbol}
+ * - {@link EQN_SumSymbol}
+ * - {@link EQN_ProdSymbol}
+ * - {@link EQN_IntegralSymbol}
+ * - {@link EQN_StrikeSymbol}
+ * - {@link EQN_BracketSymbol}
+ * - {@link EQN_AngleBracketSymbol}
+ * - {@link EQN_BraceSymbol}
+ * - {@link EQN_BarSymbol}
+ * - {@link EQN_SquareBracketSymbol}
+ * - {@link EQN_LineSymbol}
+ * - {@link EQN_RadicalSymbol}
+ * @group Equations
+ */
+export type TypeEquationElement = string | FigureElementPrimitive | FigureElementCollection | EQN_TextElement | EQN_VinculumSymbol | EQN_BoxSymbol | EQN_ArrowSymbol | EQN_SumSymbol | EQN_ProdSymbol | EQN_IntegralSymbol | EQN_StrikeSymbol | EQN_BracketSymbol | EQN_AngleBracketSymbol | EQN_BraceSymbol | EQN_BarSymbol | EQN_SquareBracketSymbol | EQN_LineSymbol | EQN_RadicalSymbol;
+/**
+ * Object where keys are element names, and values are the element definitions
+ *
+ * @see {@link Equation}
+ *
+ * @property {TypeEquationElement} [_elementName]
+ * @interface
+ * @group Equations
+ */
+export type EQN_EquationElements = {
+    [elementName: string]: TypeEquationElement;
+};
+/**
+ * Form alignment object definition.
+ *
+ * ![](./apiassets/eqn_formalignment_1.png)
+ *
+ * ![](./apiassets/eqn_formalignment_2.png)
+ *
+ * ![](./apiassets/eqn_formalignment_3.png)
+ *
+ * ![](./apiassets/eqn_formalignment_4.png)
+ *
+ * Each equation form is positioned within the {@link Equation}
+ * {@link FigureElementCollection} draw space (0, 0) point. This object
+ * defines how the form is aligned with this (0, 0) point.
+ *
+ * Using the `fixTo` property forms can either be aligned relative to the
+ * bounds of the form itself, or to an element within the form, or to a
+ * position other than the (0, 0) in in the equation's collection draw space.
+ *
+ * If `fixTo` is an element in the equation:
+ *    - the `fixTo` element is positioned at (0, 0), and all other elements
+ *      repositioned relative to that.
+ *    - The equation collection setPosition (or translation transform) can
+ *      then be used to position the equation in the figure (or relative
+ *      collection space)
+ *    - if `xAlign` is:
+ *        - `'center'`: the `fixTo` element is centered in x around (0, 0)
+ *        - `'right'`: the `fixTo` element right most point is at x = 0
+ *        - `'left'`: default - the `fixTo` element x position at 0
+ *    - if `yAlign` is:
+ *        - `'middle'`: the `fixTo` element is centered in y around (0, 0)
+ *        - `'bottom'`: the `fixTo` element bottom most point is at y = 0
+ *        - `'top'`: the `fixTo` element top most point is at y = 0
+ *        - `'baseline'`: default - the `fixTo` element y position at 0
+ *
+ * If `fixTo` is a Point, the equation is positioned at that point in the
+ * equation's draw space.
+ *  - xAlign:
+ *    - `'left'`: The equation's left most element's left most point is at
+ *              Point.x
+ *    - `'right'`: The equation's right most element's right most point is at
+ *              Point.x
+ *    - `'center'`: The equation is centered horizontally around Point.x
+ *  - `yAlign`:
+ *    - `'baseline'`: The equation's baseline is at Point.y
+ *    - `'top'`: The equation's top most element's top most point is at Point.y
+ *    - `'bottom'`: The equation's top most element's top most point is at
+ *                Point.y
+ *    - `'middle'`: The equation is centered vertically around Point.y
+ *
+ * @property {FigureElement | TypeParsablePoint | string } [fixTo] (`[0, 0]`)
+ * @property {TypeHAlign} [xAlign] (`'left'`)
+ * @property {TypeVAlign} [yAlign] (`'baseline'`)
+ *
+ * @see To test examples, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Note - the points are drawn in the figure's draw space, but as the
+ * // equation collection is at (0, 0) and it has not scaling applied, then
+ * // the equation's draw space is the same as the figure's draw space.
+ *
+ * // Draw (0, 0) point in equation collection
+ * figure.add({
+ *   make: 'polygon', options: { radius: 0.01, color: [0, 0, 1, 1], sides: 9 },
+ * });
+ * // Default alignment is left, baseline
+ * figure.add([
+ *   {
+ *     make: 'equation',
+ *     forms: { 0: ['a', '_ = ', 'bg'] },
+ *   },
+ * ]);
+ *
+ * @example
+ * // Draw (0, 0) point in equation collection
+ * figure.add({
+ *   make: 'polygon', options: { radius: 0.01, color: [0, 0, 1, 1], sides: 9 },
+ * });
+ * // Align with right, middle
+ * figure.add([
+ *   {
+ *     make: 'equation',
+ *     forms: { 0: ['a', '_ = ', 'bg'] },
+ *     formDefaults: {
+ *       alignment: {
+ *         xAlign: 'right',
+ *         yAlign: 'middle',
+ *       },
+ *     },
+ *   },
+ * ]);
+ *
+ * @example
+ * // Draw (0, 0) point in equation collection
+ * figure.add({
+ *   make: 'polygon', options: { radius: 0.01, color: [0, 0, 1, 1], sides: 9 },
+ * });
+ * // Align with center of equals sign
+ * figure.add([
+ *   {
+ *     make: 'equation',
+ *     forms: { 0: ['a', '_ = ', 'bg'] },
+ *     formDefaults: {
+ *       alignment: {
+ *         fixTo: '_ = ',
+ *         xAlign: 'center',
+ *         yAlign: 'baseline',
+ *       },
+ *     },
+ *   },
+ * ]);
+ *
+ * @example
+ * // Draw (0, 0) and (0.2, 0.1) points
+ * figure.add([
+ *   {
+ *     make: 'polygon',
+ *     options: { radius: 0.01, color: [0, 0, 1, 1], sides: 9 }
+ *   },
+ *   {
+ *     make: 'polygon',
+ *     options: {
+ *       radius: 0.01, color: [0, 0.8, 0, 1], sides: 9, position: [0.2, 0.1],
+ *     },
+ *   },
+ * ]);
+ * // Align with point (0.2, 0.1) in the equation collection
+ * figure.add([
+ *   {
+ *     make: 'equation',
+ *     forms: { 0: ['a', '_ = ', 'bg'] },
+ *     formDefaults: {
+ *       alignment: {
+ *         fixTo: [0.2, 0.1],
+ *         xAlign: 'right',
+ *         yAlign: 'baseline',
+ *       },
+ *     },
+ *   },
+ * ]);
+ * @interface
+ * @group Equations
+ */
+type EQN_FormAlignment = {
+    fixTo: FigureElement | TypeParsablePoint | string;
+    xAlign: TypeHAlign;
+    yAlign: TypeVAlign;
+};
+/**
+ * Form translation properties
+ *
+ * @property {'curved' | 'linear'} style - element should move in a straight
+ * line, or through a curve. Default: `"linear"`
+ * @property {'up' | 'down'} [direction] - curve only - element should move
+ * through an up or down curve
+ * @property {number} [mag] - the magnitude of the curve
+ * @interface
+ * @group Equations
+ */
+type EQN_TranslationStyle = {
+    style: 'curved' | 'linear';
+    direction?: 'up' | 'down';
+    mag: number;
+};
+/**
+ * Object where keys are element names and values are tranlation definition
+ * objects.
+ *
+ * `[elementName: string]: TypeEquationElement`
+ *
+ * @see {@link EQN_TranslationStyle}, {@link EQN_FormObjectDefinition}, {@link EQN_FromForm}.
+ *
+ * @property {EQN_TranslationStyle} [_elementName]
+ * @interface
+ * @group Misc Equation
+ */
+export type EQN_TranslationStyles = {
+    [elementName: string]: EQN_TranslationStyle;
+};
+/**
+ * From form options object.
+ *
+ * Any defined properties will override the corrsponding properties of the form
+ * if it being animated to from a specific form.
+ *
+ * @property {?number} [duration] duration if animating to this form, use
+ * `null` for velocity based duration
+ * @property {EQN_TranslationStyle} [translation] translation style
+ * when animating to this form
+ * @property {string | (() => void)} [onTransition] called at the start of
+ * animating to this form, or when `showForm` is used.
+ * @property {string | (() => void)} [onShow] called after animation is finished
+ * or when `showForm` is used
+ * @property {OBJ_ElementMods} [elementMods] properties to set in the equation element
+ * (@FigureElementPrimitive) when this form is shown
+ * @interface
+ * @group Equations
+ */
+export type EQN_FromForm = {
+    onTransition?: null | string | (() => void);
+    onShow?: null | string | (() => void);
+    duration?: number;
+    translation?: {
+        [elementName: string]: EQN_TranslationStyle;
+    };
+    elementMods?: OBJ_ElementMods;
+};
+/**
+ * Equation form FromForm definition.
+ *
+ * When animating from a specific form, it can be useful to customize some of
+ * the form properties specific to that transition.
+ *
+ * To do so, use this options object where each key is the specific form from
+ * which the equation is animating from, and the value is the specific
+ * properties.
+ *
+ * @property {EQN_FromForm} [_formName]
+ *
+ * @see {@link EQN_FromForm}, {@link EQN_FormObjectDefinition}
+ * @interface
+ * @group Equations
+ */
+export type EQN_FromForms = {
+    [formName: string]: EQN_FromForm;
+};
+/**
+ * In mathematics, an equation form is a specific arrangement of an equation's
+ * terms and operators. Different forms will have different
+ * arrangements, that can be achieved by performing a series of operations to
+ * both sides of the equation.
+ *
+ * For instance, the equation:
+ *
+ * a + b = c
+ *
+ * can be rearranged to a different form:
+ *
+ * a = c - b
+ *
+ * From a FigureOne figure's perspective, a form is a specific layout of
+ * equation elements.
+ *
+ * This object defines a how the elements are laid out, what properties the
+ * elements have, and some animation properties for when animating to this form.
+ *
+ * @see {@link Equation}
+ *
+ * @property {TypeEquationPhrase} content The equation phrase of the form
+ * defines how the elements are laid out
+ * @property {number} [scale] scaling factor for this form
+ * @property {EQN_FormAlignment} [alignment] how the equation's position
+ * is aligned with this form
+ * @property {string} [description] description of this form
+ * @property {{}} [modifiers] description modifiers
+ * @property {?number} [duration] duration if animating to this form, use
+ * `null` for velocity based duration
+ * @property {EQN_TranslationStyles} [translation] translation style
+ * when animating to this form
+ * @property {string | (() => void)} [onTransition] called at the start of
+ * animating to this form, or when `showForm` is used.
+ * @property {string | (() => void)} [onShow] called after animation is finished
+ * or when `showForm` is used
+ * @property {OBJ_ElementMods} [elementMods] properties to set in the equation element
+ * (@FigureElementPrimitive) when this form is shown
+ * @property {EQN_FromForms} [fromForm] override `duration`, `translation`
+ * `onTransition` and/or `onShow` with this if coming from specific forms
+ * @property {boolean} [ignoreColor] when `false`, color will be set
+ * automatically in the equation based on EQN_Color equation functions. In such
+ * cases, colors that are set external to the equation will be overridden. Use
+ * `true` to allow setting of colors externally only. (`false`)
+ *
+ * @example
+ * // Simple form definition of two different forms of the same equation and one
+ * // of the elements is colored blue in one form and red in the other
+ * figure.add({
+ *   name: 'eqn',
+ *   make: 'equation',
+ *   elements: { equals: ' = ', plus: ' + ', minus: ' \u2212 ' },
+ *   forms: {
+ *     form1: {
+ *       content: ['a', 'plus', 'b', 'equals', 'c'],
+ *       elementMods: {
+ *         a: { color: [0, 0, 1, 1] },
+ *       },
+ *     },
+ *     form2: {
+ *       content: ['a', 'equals', 'c', 'minus', 'b'],
+ *       elementMods: {
+ *         a: { color: [1, 0, 0, 1] },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * @example
+ * // Example showing all form options
+ * figure.add({
+ *   name: 'eqn',
+ *   make: 'equation',
+ *   forms: {
+ *     form1: {
+ *       content: ['a', 'b', 'c'],
+ *       subForm: 'deg',
+ *       scale: 1.2,
+ *       alignment: {
+ *         fixTo: 'b',
+ *         xAlign: 'center',
+ *         yAlign: 'bottom',
+ *       },
+ *       description: '|Form| 1 |description|',
+ *       modifiers: {
+ *         Form: { font: { color: [0, 0, 1, 0] } },
+ *       },
+ *       elementMods: {
+ *         a: {
+ *           color: [0, 0, 1, 1],
+ *           isTouchable: true,
+ *         },
+ *       },
+ *       duration: 1,
+ *       translation: {
+ *         a: {
+ *           style: 'curved',
+ *           direction: 'up',
+ *           mag: 0.95,
+ *         },
+ *         b: ['curved', 'down', 0.45],
+ *       },
+ *       fromPrev: {
+ *         duration: null,
+ *         translation: {
+ *           a: ['curved', 'down', 0.2],
+ *           b: ['curved', 'down', 0.2],
+ *         },
+ *       },
+ *       fromNext: {
+ *         duration: 2,
+ *         translation: {
+ *           a: ['curved', 'down', 0.2],
+ *           b: ['curved', 'down', 0.2],
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ * @interface
+ * @group Equations
+ */
+type EQN_FormObjectDefinition = {
+    content: TypeEquationPhrase;
+    scale?: number;
+    alignment?: EQN_FormAlignment;
+    description?: string;
+    modifiers?: {};
+    duration?: number | null;
+    translation?: EQN_TranslationStyles;
+    onShow?: string | (() => void);
+    onTransition?: string | (() => void);
+    elementMods?: OBJ_ElementMods;
+    fromForm: EQN_FromForms;
+    ignoreColor?: boolean;
+};
+/**
+ * A form definition can either be:
+ *
+ * * an equation form object {@link EQN_FormObjectDefinition}
+ * * an equation phrase {@link TypeEquationPhrase}
+ *
+ * @type {TypeEquationPhrase | EQN_FormObjectDefinition}
+ * @group Equations
+ */
+type TypeEquationForm = TypeEquationPhrase | EQN_FormObjectDefinition;
+/**
+ * An object of equation forms where each key is the form name and each value
+ * is a form defintion {@link TypeEquationForm}
+ *
+ * @property {TypeEquationForm} [_formName]
+ * @interface
+ * @group Equations
+ */
+export type EQN_Forms = {
+    [formName: string]: TypeEquationForm;
+};
+/**
+ * When an equation form series is restarted, or cycled back to the first form
+ * in the series, then two special animations can be defined with this object:
+ * * `moveFrom`: the equation will move from a location (usually another equation of the same form)
+ * * `pulse`: An element will be pulsed when the animation is finished.
+ *
+ * The default values in the pulse object are are:
+ * * `duration`: 1s
+ * * `scale`: 1.1
+ * @interface
+ * @group Equations
+ */
+type EQN_FormRestart = {
+    moveFrom?: Point | FigureElementCollection | null;
+    pulse?: {
+        duration?: number;
+        scale?: number;
+        element?: FigureElement | null;
+    };
+};
+/**
+ * {@link NextFormAnimationStep} options object.
+ *
+ * `OBJ_TriggerAnimationStep & EQN_EquationGoToForm`
+ *
+ * Duration will be automatically calculated (unless duration is set to 0).
+ * To specify it exactly, the `duration`, `dissolveOutTime`, `dissolveInTime`
+ * and `blankTime` must all be specified (or at least the ones that will be used
+ * in the form change).
+ *
+ * @extends OBJ_TriggerAnimationStep
+ * @extends EQN_EquationGoToForm
+ *
+ * @see {@link Equation}, {@link NextFormAnimationStep}
+ * @interface
+ * @group Misc Equation
+ */
+export type OBJ_NextFormAnimationStep = {} & OBJ_TriggerAnimationStep;
+/**
+ * {@link GoToFormAnimationStep} options object.
+ *
+ * `OBJ_TriggerAnimationStep & EQN_EquationGoToForm & { start?: 'string', target?: 'string'}`
+ *
+ * Duration will be automatically calculated (unless duration is set to 0).
+ * To specify it exactly, the `duration`, `dissolveOutTime`, `dissolveInTime`
+ * and `blankTime` must all be specified (or at least the ones that will be used
+ * in the form change).
+ *
+ * The `form` property of EQN_EquationGoToForm is not used. Use `target`
+ * instead.
+ *
+ * @extends OBJ_TriggerAnimationStep
+ * @extends EQN_EquationGoToForm
+ *
+ * @property {string} [start] form to start from. If undefined, then current
+ * form will be used
+ * @property {string} [target] form to go to. If undefined, then current
+ * form will be used
+ *
+ * @see {@link Equation}
+ * @interface
+ * @group Misc Equation
+ */
+export type OBJ_GoToFormAnimationStep = {
+    start?: string;
+    target?: string;
+} & OBJ_TriggerAnimationStep;
+/**
+ * Default form values applied to all forms
+ *
+ * @see {@link EQN_FormObjectDefinition}
+ * @interface
+ * @group Equations
+ */
+export type EQN_FormDefaults = {
+    alignment?: EQN_FormAlignment;
+    elementMods?: OBJ_ElementMods;
+    duration?: number;
+    translation?: EQN_TranslationStyle;
+    onShow?: null | string | (() => void);
+    onTransition?: null | string | (() => void);
+    layout?: 'lazy' | 'init' | 'always';
+    ignoreColor?: boolean;
+};
+/**
+ * Options objects to construct an {@link Equation} class.
+ *
+ * All properties are optional.
+ *
+ * @property {TypeColor} [color] default equation color
+ * @property {TypeColor} [dimColor] default equation dim color
+ * @property {OBJ_Font} [font] default {@link FigureFont} for math elements in
+ * the equation
+ * @property {OBJ_Font} [textFont] default {@link FigureFont} for text elements
+ * in the equation (defaults to `font`)
+ * @property {number} [scale] equation scale (`0.7`)
+ * @property {EQN_EquationElements} [elements] equation element definitions
+ * @property {EQN_Forms} [forms] form definitions
+ * @property {string} [initialForm] form to show when first added to a figure
+ * @property {EQN_FormDefaults} [formDefaults] default form options applied to
+ * all forms
+ * @property {Array<string> | Object.<Array<string>>} [formSeries] an object
+ * with each key being a form series name, and each value an array for form
+ * names. If defined as an array, then a form series object is created where
+ * the form series name is 'base'. Default: {}
+ * @property {string} [defaultFormSeries] If more than one form series is
+ * defined, then a default must be chosen to be the first current one. Default:
+ * first form defined
+ * @property {?EQN_FormRestart} [formRestart] behavior when form transitions
+ * from last in form series back to first
+ * @property {TypeParsablePoint} [position] position will override first
+ * translation element of transform
+ * @property {Transform} [transform]
+ * @interface
+ * @group Equations
+ */
+export type EQN_Equation = {
+    color?: TypeColor;
+    dimColor?: TypeColor;
+    font?: OBJ_Font;
+    textFont?: OBJ_Font;
+    scale?: number;
+    elements?: EQN_EquationElements;
+    formDefaults: EQN_FormDefaults;
+    forms?: EQN_Forms;
+    initialForm?: string;
+    formSeries?: Array<string> | {};
+    defaultFormSeries?: string;
+    formRestart?: EQN_FormRestart;
+    position?: TypeParsablePoint;
+    transform?: Transform;
+};
+/**
+ * Options object for {@link Equation#goToForm}.
+ *
+ * Often, `goToForm` is called to animate from a shown form to a desired form.
+ * Therefore there will be some equation elements that:
+ * * Are currently shown, but need to be hidden as they are not in the desired form
+ * * Are currently shown, are in the desired form, and need to be moved to the
+ *   correct layout position for the desired form
+ * * Are currently hidden and need to be shown in the desired form
+ *
+ * The order that elements are shown, hidden and moved is defined by the
+ * `animate` property:
+ * * `'move'`: Dissolve out elements to hide, move existing elements to new,
+ * dissolve in elements that need to be shown
+ * * `'dissolveInThenMove'`: Dissolve out the elements to hide, dissolve in the
+ * elements that need to be shown in the correct locations of the form, then
+ * move existing elements to their correct locations
+ * * `'dissolve'`: Dissolve out the entire current form, and then dissolve in the entire new form
+ * * `'moveFrom'`: Shows the desired form at the position defined in the
+ * formRestart property of {@link EQN_Equation}, then moves it to the
+ * current location
+ * * `'pulse'`: Same as `'dissolve'`, but once finished will pulse the element
+ *  defined in the pulse object in the formRestart property of {@link EQN_Equation}
+ *
+ * If a form is already animating, then the `ifAnimating` property will define
+ * the behavior of the animation:
+ * * `cancelGoTo: true`, `skipToTarget: true`: Current animation will skip to
+ *   the end, and current goTo call will be cancelled
+ * * `cancelGoTo: true`, `skipToTarget: false`: Current animation will stop in
+ *   its current state, and current goTo call will be cancelled
+ * * `cancelGoTo: false`, `skipToTarget: true`: Current animation will skip to
+ *   the end, and current goTo call will then be executed
+ * * `cancelGoTo: false`, `skipToTarget: false`: Current animation will stop in
+ *   its current state, and current goTo call will be executed
+ *
+ * @property {string} [name] - form name to goto
+ * @property {number} [index] - form index to goto (can be used instead of name)
+ * @property {'move' | 'dissolve' | 'moveFrom' | 'pulse' |
+ *  'dissolveInThenMove'} [animate] - default: `"dissolve"`
+ * @property {number} [delay] - delay before goto start. Default: `0`
+ * @property {number} [dissolveOutTime] - Default: 0.4 of duration, or 0.4s if
+ * no duration
+ * @property {number} [duration] - animation duration. Default: `null`
+ * @property {number} [blankTime] - time between dissolve out and dissolve in
+ * when animating with `dissolve` or `pulse`. Default: 0.2 of duration, or 0.2s
+ * if no duration
+ * @property {number} [dissolveInTime] - Default: 0.4 of duration, or 0.4s if
+ * no duration
+ * @property {boolean} [prioritizeFormDuration] - use duration from the form
+ * definition {@link EQN_FormObjectDefinition}. Default: `true`
+ * @property {'fromPrev' | 'fromNext'} [fromWhere] - prioritze *fromPrev* or
+ * *fromNext* duration from the form definition. {@link EQN_FormObjectDefinition}
+ * Default: `null`
+ * @property {{cancelGoTo?: boolean, skipToTarget?: boolean}} [ifAnimating] -
+ * behavior for if currently animating between forms. Default:
+ * `skipToTarget: true`, `cancelGoTo: true`
+ * @property {?() => void} [callback] - call when goto finished
+ * @interface
+ * @group Misc Equation
+ */
+type EQN_EquationGoToForm = {
+    name?: string;
+    index?: number;
+    animate?: 'move' | 'dissolve' | 'moveFrom' | 'pulse' | 'dissolveInThenMove';
+    delay?: number;
+    dissolveOutTime?: number;
+    duration?: number | null;
+    dissolveInTime?: number;
+    blankTime?: number;
+    prioritizeFormDuration?: boolean;
+    fromWhere?: string | null;
+    ifAnimating?: {
+        cancelGoTo?: boolean;
+        skipToTarget?: boolean;
+    };
+    callback?: (string | (() => void)) | null;
+};
+/**
+ * An Equation is a collection of elements that can be arranged into different
+ * forms.
+ *
+ * `Equation` should be instantiated from an *object definition*, or from
+ * the `figure.collections.equation` method.
+ *
+ * Equation includes two additional animation steps in {@link Equation.animations}:
+ * * {@link GoToFormAnimationStep}
+ * * {@link NextFormAnimationStep}
+ *
+ * @extends FigureElementCollection
+ *
+ * @see To test examples, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * @param {EQN_Equation} options
+ * @example
+ * // Create with options definition
+ * figure.add({
+ *   name: 'eqn',
+ *   make: 'equation',
+ *   elements: {
+ *     a: 'a',
+ *     b: { color: [0, 0, 1, 1] },
+ *     c: 'c',
+ *     equals: ' = ',
+ *     plus: ' + ',
+ *   },
+ *   forms: {
+ *     1: ['a', 'equals', 'b', 'plus', 'c'],
+ *   },
+ * });
+ *
+ * @example
+ * // Create with methods
+ * const eqn = figure.collections.equation();
+ * eqn.addElements({
+ *   a: 'a',
+ *   b: { color: [0, 0, 1, 1] },
+ *   c: 'c',
+ *   equals: ' = ',
+ *   plus: ' + ',
+ * });
+ * eqn.addForms({
+ *   1: ['a', 'equals', 'b', 'plus', 'c'],
+ * });
+ * figure.add('eqn', eqn);
+ * eqn.showForm('1');
+ * @group Equations
+ */
+export declare class Equation extends FigureElementCollection {
+    /**
+     * Equation parameters and functions
+     * @property {EquationFunctions} functions - equation functions
+     */
+    eqn: {
+        forms: {
+            [formName: string]: EquationForm;
+        };
+        functions: EquationFunctions;
+        symbols: EquationSymbols;
+        currentForm: string;
+        font: FigureFont;
+        textFont: FigureFont;
+        scale: number;
+        formSeries: {
+            [key: string]: Array<string>;
+        };
+        currentFormSeries: Array<string>;
+        currentFormSeriesName: string;
+        formDefaults: {
+            alignment: {
+                fixTo: (FigureElementPrimitive | FigureElementCollection | Point);
+                xAlign: TypeHAlign;
+                yAlign: TypeVAlign;
+            };
+            elementMods: OBJ_ElementMods;
+            duration?: number;
+            translation?: EQN_TranslationStyle;
+            onShow?: null | string | (() => void);
+            onTransition?: null | string | (() => void);
+            layout?: 'always' | 'lazy' | 'init';
+            ignoreColor?: boolean;
+        };
+        isAnimating: boolean;
+        descriptionElement: FigureElementPrimitive | null;
+        descriptionPosition: Point;
+        formRestart: {
+            moveFrom?: Point | FigureElementCollection;
+            pulse?: {
+                duration: number;
+                scale: number;
+                element: FigureElement;
+            };
+        } | null | undefined;
+    };
+    initialForm: string | null;
+    defaultTextType: TypeText;
+    /**
+     * {@link AnimationManager} extended to include additional animation steps
+     * specific to equations
+     * @property {NextFormAnimationStep} nextForm
+     * @property {GoToFormAnimationStep} goToForm
+     * @extends AnimationManager
+     */
+    animations: {
+        nextForm: (...opt: Array<any>) => TriggerAnimationStep;
+        goToForm: (...opt: Array<any>) => TriggerAnimationStep;
+    } & AnimationManager;
+    shapes: Record<string, any>;
+    /**
+     * @hideconstructor
+     */
+    constructor(shapes: Record<string, any>, options?: EQN_Equation);
+    stateSet(): void;
+    setFigure(figure: OBJ_FigureForElement, notify?: boolean): void;
+    fontUpdated(): void;
+    _getStateProperties(options: Record<string, any>): string[];
+    _getStatePropertiesMin(): string[];
+    /**
+      * Set the current form series to 'name'
+     */
+    setFormSeries(name: string): void;
+    /**
+      * Get the current form series name
+     */
+    getFormSeries(): string;
+    /**
+     * For equation layout. If an equation layout happens before a desired font
+     * is fully loaded, then use this method to re-layout the equation when the
+     * font is available.
+     *
+     * Either the current form only, all forms already laid out (set), or all
+     * forms of the equation can be re-laid-out.
+     *
+     * @param {'none' | 'current' | 'all' | 'set' | 'reset'} forms
+     * @param {boolean} show true will re-show current form
+     */
+    layoutForms(forms?: 'none' | 'current' | 'all' | 'set' | 'reset', show?: boolean): void;
+    contextLost(): void;
+    /**
+     * Update text of equation element or elements
+     *
+     * @param {EQN_UpdateElementText} elements elements to update
+     * @param {'all' | 'current' | 'none'} [layoutForms] which forms to re-layout
+     * with the updated text
+     *
+     */
+    updateElementText(elements: EQN_UpdateElementText, layoutForms?: 'all' | 'current' | 'none'): void;
+    makeTextElem(options: {
+        text?: string;
+        font?: FigureFont | OBJ_Font;
+        style?: 'italic' | 'normal';
+        weight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+        size?: number;
+        family?: string;
+        width?: number;
+        color?: TypeColor;
+        touchBorder?: TypeParsableBuffer | Array<Point>;
+        onClick?: (() => void) | 'string' | null;
+        isTouchable?: boolean;
+        mods?: Record<string, any>;
+    }, defaultText?: string): any;
+    getTextFromKey(key: string): string;
+    getExistingOrAddSymbol(symbol: string | Record<string, any>): any;
+    getExistingOrAddSymbolFromKey(key: string, options?: Record<string, any>): any;
+    addElementFromKey(key: string, options?: Record<string, any>): any;
+    makeSymbolElem(options: any): import("./Symbols/Bracket").default | import("./Symbols/Box").default | import("./Symbols/Sum").default | import("./Symbols/Product").default | import("./Symbols/Integral").default | import("./Symbols/Vinculum").default | import("./Symbols/Strike").default | import("./Symbols/Radical").default | import("./Symbols/Division").default | import("./Symbols/Line").default | null;
+    /**
+     * Add elements to equation.
+     */
+    addElements(elems: EQN_EquationElements): void;
+    addDescriptionElement(descriptionElement?: FigureElementPrimitive | null, descriptionPosition?: Point): void;
+    setPosition(pointOrX: TypeParsablePoint | number, y?: number): void;
+    addPhrases(phrases: {
+        [phraseName: string]: TypeEquationPhrase;
+    }): void;
+    /**
+     * Add forms to equation.
+     */
+    addForms(forms: EQN_Forms): void;
+    checkFixTo(fixTo: FigureElementCollection | FigureElementPrimitive | string | Point | null, formElements: Array<FigureElementPrimitive | FigureElementCollection>): FigureElementPrimitive | FigureElementCollection | Point;
+    createForm(elements?: any): EquationForm;
+    /**
+     * Return all the elements that are used in a form.
+     * @param {string} form
+     * @return {Array<FigureElement>}
+     */
+    getFormElements(form: string, includeHidden?: boolean): (FigureElementCollection | FigureElementPrimitive | ElementInterface)[];
+    /**
+     * Return all the elements that are used in an equation phrase.
+     * @param {TypeEquationPhrase} phrase
+     * @return {Array<FigureElement>}
+     */
+    getPhraseElements(phrase: string | Array<string>): any[];
+    getUnusedElements(): string[];
+    stopEquationAnimating(how?: 'complete' | 'cancel'): void;
+    addForm(name: string, content: Array<ElementInterface>, options?: {
+        scale?: number;
+        alignment?: EQN_FormAlignment;
+        description?: string;
+        modifiers?: Record<string, any>;
+        elementMods?: {
+            [elementName: string]: Record<string, any>;
+        };
+        onTransition?: null | string | (() => void);
+        onShow?: null | string | (() => void);
+        duration?: number;
+        translation?: {
+            [elementName: string]: EQN_TranslationStyle;
+        };
+        fromForm: {
+            [formName: string]: {
+                onTransition?: null | string | (() => void);
+                onShow?: null | string | (() => void);
+                duration?: number;
+                translation?: {
+                    [elementName: string]: EQN_TranslationStyle;
+                };
+                elementMods?: {
+                    [elementName: string]: Record<string, any>;
+                };
+            };
+        };
+    }): void;
+    /**
+     * Get the current equation form
+     */
+    getCurrentForm(): EquationForm | null;
+    render(animationStop?: boolean): void;
+    /**
+     * Set current equation form - Note, this does not show the form.
+     */
+    setCurrentForm(formOrName: EquationForm | string): void;
+    /**
+     * Show equation form
+     */
+    showForm(formOrName?: EquationForm | string, animationStop?: boolean): void;
+    showAll(): void;
+    cleanup(): void;
+    cleanupForms(): void;
+    /**
+     * Get an equation form object from a form name
+     */
+    getForm(formOrName: string | EquationForm): null | EquationForm;
+    /**
+     * Start an animation to an equation form
+     */
+    goToForm(optionsIn?: EQN_EquationGoToForm): void;
+    getFormIndex(formToGet?: null | EquationForm | string): number;
+    /**
+     * Animate to previous form in the current form series
+     */
+    prevForm(durationOrOptions?: number | null | EQN_EquationGoToForm, delay?: number): void;
+    /**
+     * Animate to next form in the current form series
+     */
+    nextForm(durationOrOptions?: number | null | EQN_EquationGoToForm, delay?: number): void;
+    /**
+     * Start from previous form and animate to current form
+     */
+    replayCurrentForm(duration: number): void;
+    animateToForm(name: string, duration?: number | null, delay?: number, callback?: null | string | (() => void)): void;
+    changeDescription(formOrName: EquationForm | string, description?: string, modifiers?: Record<string, any>): void;
+    getDescription(formOrName: EquationForm | string): string;
+}
+export {};