figureone 1.4.1 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.4.1",
+  "version": "1.7.0",
   "description": "Draw, animate and interact with shapes, text, plots and equations in Javascript. Create interactive slide shows, and interactive videos.",
   "main": "index.js",
   "types": "types/index.d.ts",

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

@@ -503,6 +503,7 @@ declare class FigureElement {
     drawNumber: number;
     moveSetTransform: boolean;
     allowSetColor: string;
+    ignoreSetColor: string | Array<string>;
     /**
      * @hideconstructor
      */
@@ -588,12 +589,20 @@ declare class FigureElement {
     clear(_canvasIndex?: number): void;
     cleanup(deleteTexture?: boolean): void;
     willStartAnimating(): boolean;
+    /**
+     * Returns `true` if a `setColor` command tagged with source `from` should be
+     * ignored by this element (per `ignoreSetColor`). Untagged commands
+     * (`from == null`) are never ignored.
+     */
+    isSetColorIgnored(from?: string | null): boolean;
     /**
      Set element color.
      @param {[number, number, number, number]} color RGBA color from 0 to 1
      @param {boolean} [setDefault] also set the default color to this color
+     @param {string | null} [from] source label of this color command; if it
+     matches `ignoreSetColor` the command is ignored
      */
-    setColor(color: TypeColor, setDefault?: boolean): void;
+    setColor(color: TypeColor, setDefault?: boolean, from?: string | null): void;
     /**
      * Set element color to `dimColor`
      */
@@ -879,7 +888,7 @@ declare class FigureElementPrimitive extends FigureElement {
     _dup(transform?: Transform | null): FigureElementPrimitive;
     clear(canvasIndex?: number): void;
     resize(figureHTMLElement?: HTMLElement | null | undefined): void;
-    setColor(color: TypeColor, setDefault?: boolean): void;
+    setColor(color: TypeColor, setDefault?: boolean, from?: string | null): void;
     setOpacity(opacity: number): void;
     show(): void;
     hide(): void;
@@ -1138,7 +1147,7 @@ declare class FigureElementCollection extends FigureElement {
     getSelectionFromBorders(glLocation: Point): FigureElement | null;
     stop(how?: 'freeze' | 'cancel' | 'complete' | 'animateToComplete' | 'dissolveToComplete', elementOnly?: boolean): void;
     setFont(fontSize: number): void;
-    setColor(color?: TypeColor, setDefault?: boolean): void;
+    setColor(color?: TypeColor, setDefault?: boolean, from?: string | null): void;
     setDimColor(color?: TypeColor): void;
     undim(children?: TypeElementPath | null | undefined): void;
     dim(children?: TypeElementPath | null | undefined): void;

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

@@ -89,6 +89,7 @@ export default class BaseAnnotationFunction implements ElementInterface {
     scale: number;
     showContent: boolean;
     color: TypeColor | null;
+    opacity: number | null;
     fullSize: {
         leftOffset: number;
         width: number;
@@ -107,7 +108,9 @@ export default class BaseAnnotationFunction implements ElementInterface {
     cleanup(): void;
     getAllElements(includeHidden?: boolean): any[];
     setPositions(): void;
-    setColor(colorIn?: TypeColor | null): void;
+    setColor(colorIn?: TypeColor | null, from?: string | null): void;
+    setOpacity(opacityIn?: number | null): void;
+    collectDrawOrder(ops: Array<any>): void;
     offsetLocation(offset?: Point): void;
     calcSize(location: Point, scale: number): void;
     setEncompassGlyph(scale: number, contentBoundsIn: Bounds): [Bounds, Bounds];

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

@@ -15,7 +15,8 @@ export default class BaseEquationFunction extends Elements {
     _dup(namedCollection?: Record<string, any>): any;
     getAllElements(includeHidden?: boolean): any[];
     setPositions(): void;
-    setColor(colorIn?: TypeColor | null): void;
+    setColor(colorIn?: TypeColor | null, from?: string | null): void;
+    setOpacity(opacityIn?: number | null): void;
     offsetLocation(offset?: Point): void;
     calcSize(location: Point, scale: number): void;
 }

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

@@ -0,0 +1,6 @@
+import { Point } from '../../../tools/g2';
+import BaseEquationFunction from './BaseEquationFunction';
+export default class DrawOrder extends BaseEquationFunction {
+    calcSize(location: Point, scale: number): void;
+    collectDrawOrder(ops: Array<any>): void;
+}

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

@@ -25,7 +25,9 @@ export interface ElementInterface {
     offsetLocation(offset: Point): void;
     getBounds(useFullSize?: boolean): Bounds;
     cleanup(): void;
-    setColor(colorIn: TypeColor | null): void;
+    setColor(colorIn: TypeColor | null, from?: string | null): void;
+    setOpacity(opacityIn: number | null): void;
+    collectDrawOrder(ops: Array<any>): void;
 }
 declare class BlankElement {
     ascent: number;
@@ -48,6 +50,7 @@ declare class Element implements ElementInterface {
     showContent: boolean;
     color: TypeColor | null;
     defaultColor: TypeColor;
+    opacity: number | null;
     fullSize: {
         leftOffset: number;
         width: number;
@@ -61,7 +64,9 @@ declare class Element implements ElementInterface {
     _dup(namedCollection?: Record<string, any>): Element;
     getAllElements(includeHidden?: boolean): (FigureElementCollection | FigureElementPrimitive)[];
     setPositions(): void;
-    setColor(colorIn?: TypeColor | null): void;
+    setColor(colorIn?: TypeColor | null, from?: string | null): void;
+    setOpacity(opacityIn?: number | null): void;
+    collectDrawOrder(ops: Array<any>): void;
     offsetLocation(offset?: Point): void;
     getBounds(useFullSize?: boolean): Bounds;
 }
@@ -75,6 +80,7 @@ declare class Elements implements ElementInterface {
     fnMap: FunctionMap;
     showContent: boolean;
     color: TypeColor | null;
+    opacity: number | null;
     fullSize: {
         leftOffset: number;
         width: number;
@@ -88,7 +94,9 @@ declare class Elements implements ElementInterface {
     calcSize(location: Point, scale: number): void;
     getAllElements(includeHidden?: boolean): (FigureElementCollection | FigureElementPrimitive | ElementInterface)[];
     setPositions(): void;
-    setColor(colorIn?: TypeColor | null): void;
+    setColor(colorIn?: TypeColor | null, from?: string | null): void;
+    setOpacity(opacityIn?: number | null): void;
+    collectDrawOrder(ops: Array<any>): void;
     offsetLocation(offset?: Point): void;
     getBounds(useFullSize?: boolean): Bounds;
 }

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

@@ -0,0 +1,6 @@
+import { Point } from '../../../tools/g2';
+import BaseEquationFunction from './BaseEquationFunction';
+export default class Opacity extends BaseEquationFunction {
+    opacity: number | null;
+    calcSize(location: Point, scale: number): void;
+}

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

@@ -31,6 +31,16 @@ export type EQN_UpdateElementText = {
  * Object where keys are property names of a {@link FigureElement} and values
  * are the values to set the properties to.
  *
+ * Two keys are treated specially as draw-order operations rather than element
+ * properties: `back` and `front`. Each takes an options object (`{}` for the
+ * full extreme, `{ num }` to move a set number of places, or `{ before }` /
+ * `{ after }` to position relative to an anchor element) and reorders the
+ * element in the equation's draw stack - paralleling the {@link EQN_Back} and
+ * {@link EQN_Front} equation functions. When several elements declare `back` or
+ * `front` mods, they are applied in definition order, so
+ * `{ a: { back: {} }, b: { back: {} } }` sends `a` to the back and then `b` to
+ * the back.
+ *
  * @property {any} [_propertyName]
  * @interface
  * @group Misc Figure Element
@@ -392,6 +402,11 @@ export type EQN_FromForms = {
  * 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`)
+ * @property {boolean} [ignoreOpacity] when `false`, opacity will be set
+ * automatically in the equation based on EQN_Opacity equation functions
+ * (multiplicative cascade). Element opacities set externally will be
+ * overridden. Use `true` to allow setting of opacities externally only.
+ * (`false`)
  *
  * @example
  * // Simple form definition of two different forms of the same equation and one
@@ -483,6 +498,7 @@ type EQN_FormObjectDefinition = {
     elementMods?: OBJ_ElementMods;
     fromForm: EQN_FromForms;
     ignoreColor?: boolean;
+    ignoreOpacity?: boolean;
 };
 /**
  * A form definition can either be:
@@ -588,6 +604,7 @@ export type EQN_FormDefaults = {
     onTransition?: null | string | (() => void);
     layout?: 'lazy' | 'init' | 'always';
     ignoreColor?: boolean;
+    ignoreOpacity?: boolean;
 };
 /**
  * Options objects to construct an {@link Equation} class.
@@ -726,6 +743,32 @@ type EQN_EquationGoToForm = {
  * * {@link GoToFormAnimationStep}
  * * {@link NextFormAnimationStep}
  *
+ * In addition to the notifications published by {@link FigureElement}, an
+ * Equation publishes a `formChanged` notification whenever the displayed form
+ * may have changed. The payload is an object
+ * `{ phase, form, fromForm?, progress? }` where `phase` is one of:
+ * - `'showForm'`: a form was set via `showForm`. Callers can suppress this
+ *   event by passing `notify: false` to `showForm`; internal `showForm`
+ *   calls made by `goToForm` do this so the `goToForm*` event stream is
+ *   not interleaved with stray `showForm` events.
+ * - `'goToFormStart'`: a `goToForm` call has just begun
+ * - `'goToFormStep'`: published on every animation frame during a `goToForm`
+ *   animation; `progress` is the percentage (0-1) through the animation. A
+ *   final `goToFormStep` with `progress: 1` is always published immediately
+ *   before `goToFormEnd`
+ * - `'goToFormEnd'`: a `goToForm` call has finished
+ *
+ *  * `fromForm` is only included on the `goToForm*` phases (it carries the
+ * `fromWhere` option from `goToForm`); it is absent on `showForm`. `progress`
+ * is only included on `goToFormStep`. The event order for a `goToForm` call
+ * is always: `goToFormStart` → zero-or-more `goToFormStep` → `goToFormStep`
+ * with `progress: 1` → `goToFormEnd`.
+ *
+ * A user-initiated `showForm` made while a `goToForm` animation is running
+ * will publish its `showForm` event interleaved with the ongoing
+ * `goToFormStep` stream — listeners that drive UI from "the current
+ * transition" should account for this. Pass `notify: false` to suppress.
+ *
  * @extends FigureElementCollection
  *
  * @see To test examples, append them to the
@@ -799,6 +842,7 @@ export declare class Equation extends FigureElementCollection {
             onTransition?: null | string | (() => void);
             layout?: 'always' | 'lazy' | 'init';
             ignoreColor?: boolean;
+            ignoreOpacity?: boolean;
         };
         isAnimating: boolean;
         descriptionElement: FigureElementPrimitive | null;
@@ -979,7 +1023,20 @@ export declare class Equation extends FigureElementCollection {
     /**
      * Show equation form
      */
-    showForm(formOrName?: EquationForm | string, animationStop?: boolean): void;
+    /**
+     * Show equation form.
+     *
+     * @param formOrName the form, or its name, to show
+     * @param animationStop if `true`, stops any in-progress element animations
+     * before rendering the form (default `true`)
+     * @param notify if `true`, publish a `formChanged` notification with
+     * `phase: 'showForm'` (default `true`). Pass `false` to suppress the
+     * event — useful for bulk updates or when this `showForm` is part of a
+     * larger transition the caller is broadcasting separately. The internal
+     * `showForm` calls made by `goToForm` use `false` so the `goToForm*`
+     * event stream is not interleaved with stray `showForm` events.
+     */
+    showForm(formOrName?: EquationForm | string, animationStop?: boolean, notify?: boolean): void;
     showAll(): void;
     cleanup(): void;
     cleanupForms(): void;

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

@@ -103,6 +103,7 @@ export default class EquationForm extends Elements {
     positionsSet: boolean;
     layout: 'always' | 'lazy' | 'init';
     ignoreColor: boolean;
+    ignoreOpacity: boolean;
     fromForm: {
         [key: string]: {
             onTransition?: string | (() => void);
@@ -122,6 +123,9 @@ export default class EquationForm extends Elements {
     getNamedElements(): Record<string, any>;
     rearrange(): void;
     setPositions(noArrange?: boolean): void;
+    collectElementModDrawOrder(ops: Array<any>): void;
+    setDrawOrder(): void;
+    applyDrawOrderOp(collection: any, op: any): void;
     _dup(elements?: TypeElements, collectionMethods?: TypeCollectionMethods): EquationForm;
     arrange(scale?: number, xAlign?: TypeHAlign | null, yAlign?: TypeVAlign | null, fixTo?: FigureElementPrimitive | FigureElementCollection | Point): void;
     lazyArrange(scale?: number, xAlign?: TypeHAlign | null, yAlign?: TypeVAlign | null, fixTo?: FigureElementPrimitive | FigureElementCollection | Point): void;
@@ -133,7 +137,7 @@ export default class EquationForm extends Elements {
     render(): void;
     showHide(showTime?: number, hideTime?: number, callback?: ((arg?: any) => void) | null, animationStop?: boolean): void;
     hideShow(showTime?: number, hideTime?: number, callback?: ((arg?: any) => void) | null, animationStop?: boolean): void;
-    allHideShow(delay?: number, hideTime?: number, blankTime?: number, showTime?: number, callback?: ((cancelled: boolean) => void) | null): void;
+    allHideShow(delay?: number, hideTime?: number, blankTime?: number, showTime?: number, callback?: ((cancelled: boolean) => void) | null): number;
     applyElementMods(fromWhere?: null | string): void;
     animatePositionsTo(delay: number, dissolveOutTime: number, moveTime: number | null, dissolveInTime: number, callback?: (string | ((arg?: any) => void)) | null, fromWhere?: string | null | undefined, dissolveInBeforeMove?: boolean): number;
 }

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

@@ -11,6 +11,8 @@ import Container from './Elements/Container';
 import BaseAnnotationFunction from './Elements/BaseAnnotationFunction';
 import Offset from './Elements/Offset';
 import Color from './Elements/Color';
+import Opacity from './Elements/Opacity';
+import DrawOrder from './Elements/DrawOrder';
 import type { TypeColor } from '../../tools/types';
 export declare function getFigureElement(elementsObject: {
     [key: string]: FigureElementPrimitive | FigureElementCollection;
@@ -46,6 +48,10 @@ export declare function getFigureElement(elementsObject: {
  *  - `{ prodOf: `{@link EQN_ProdOf} `}`
  *  - `{ topStrike: `{@link EQN_StrikeComment} `}`
  *  - `{ bottomStrike: `{@link EQN_StrikeComment} `}`
+ *  - `{ color: `{@link EQN_Color} `}`
+ *  - `{ opacity: `{@link EQN_Opacity} `}`
+ *  - `{ back: `{@link EQN_Back} `}`
+ *  - `{ front: `{@link EQN_Front} `}`
  *  - `{ make: string, name?: string, ... }` (inline element — creates any
  *    element type directly in a form using the same `make` values as
  *    {@link Figure.add}. If `name` is omitted, one is auto-generated.)
@@ -142,6 +148,14 @@ export type TypeEquationPhrase = string | number | {
     topStrike: EQN_StrikeComment;
 } | {
     bottomStrike: EQN_StrikeComment;
+} | {
+    color: EQN_Color;
+} | {
+    opacity: EQN_Opacity;
+} | {
+    back: EQN_Back;
+} | {
+    front: EQN_Front;
 } | {
     make: string;
     name?: string;
@@ -564,6 +578,25 @@ export type EQN_Scale = {
  *   },
  *   touch: { onClick: e => e.nextForm() },
  * });
+ * @example
+ * // The `color` function recolours a phrase explicitly. Separately, an element
+ * // can opt out of the equation's default ('form') colour cascade with
+ * // `ignoreSetColor`, while still accepting explicit colour commands. Here both
+ * // squares start blue; recolouring the whole equation to grey greys the left
+ * // (free) square, but the right (locked) square keeps its colour.
+ * const blue = [0, 0, 1, 1];
+ * const locked = figure.primitives.rectangle({ width: 0.5, height: 0.5, color: blue });
+ * locked.ignoreSetColor = 'form'; // ignore the default cascade, keep blue
+ * const eqn = figure.add({
+ *   make: 'equation',
+ *   color: [1, 0, 0, 1],
+ *   elements: {
+ *     free: figure.primitives.rectangle({ width: 0.5, height: 0.5, color: blue }),
+ *     locked,
+ *   },
+ *   forms: { 0: ['free', '  ', 'locked'] },
+ * });
+ * eqn.setColor([0.5, 0.5, 0.5, 1], true, 'form'); // free -> grey, locked stays blue
  * @interface
  * @group Equation Layout
  */
@@ -577,6 +610,255 @@ export type EQN_Color = {
     TypeColor,
     (boolean | null | undefined)
 ];
+/**
+ * Equation opacity function
+ *
+ * Set an opacity multiplier on an equation phrase. The opacity cascades
+ * multiplicatively, so nested `opacity` functions multiply together (e.g. an
+ * outer `0.5` around an inner `0.5` yields `0.25` on the inner content).
+ *
+ * Opacity values are expected to be in the range `[0, 1]`. Whenever the form
+ * is shown, the cascaded opacity is assigned to each wrapped element, overriding
+ * any externally-set element `opacity`. Set `ignoreOpacity: true` on the form
+ * to suppress this and preserve externally-set opacities.
+ *
+ * Options can be an object, or an array in the property order below
+ *
+ * @property {TypeEquationPhrase} content
+ * @property {number} opacity opacity multiplier in the range `[0, 1]`
+ * @property {boolean} [fullContentBounds] Use full bounds with content (`false`)
+ *
+ * @see To test examples, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Simple Array Definition
+ * figure.add({
+ *   make: 'equation',
+ *   forms: {
+ *     0: ['a', { opacity: ['b', 0.3] }, 'c'],
+ *   },
+ * });
+ *
+ * @example
+ * // Simple Object Definition
+ * figure.add({
+ *   make: 'equation',
+ *   forms: {
+ *     0: [
+ *       'a',
+ *       {
+ *         opacity: {
+ *           content: 'b',
+ *           opacity: 0.3,
+ *         },
+ *       },
+ *       'c',
+ *     ],
+ *   },
+ * });
+ *
+ * @interface
+ * @group Equation Layout
+ */
+export type EQN_Opacity = {
+    content: TypeEquationPhrase;
+    opacity: number;
+    fullContentBounds?: boolean;
+    name?: string;
+} | [
+    TypeEquationPhrase,
+    number,
+    (boolean | null | undefined)
+];
+/**
+ * Equation back function
+ *
+ * Send an equation phrase's elements back in the equation's draw stack. All
+ * elements within `content` are moved together as a group, keeping their
+ * current relative draw order. Nested `front`/`back` functions are applied
+ * inner-most first, so an inner `front`/`back` reorders the elements and this
+ * (outer) function then moves the reordered group as a unit.
+ *
+ * The group's position is determined by, in order of precedence:
+ * - `before` - position the group just before (behind) the most-back of the
+ *   named anchor element(s). `num` shifts it further back (default `0`).
+ * - `after` - position the group just after (in front of) the most-front of
+ *   the named anchor element(s). `num` shifts it further forward (default `0`).
+ * - `num` - a positive value moves the group that many places back; a negative
+ *   value positions it `|num|` places ahead of the very back.
+ * - otherwise the group is sent completely to the back.
+ *
+ * The reorder is applied whenever the form is shown, relative to the equation's
+ * natural (definition) draw order, so each form deterministically defines its
+ * own stacking.
+ *
+ * Options can be an object, or an array in the property order below
+ *
+ * @property {TypeEquationPhrase} content
+ * @property {number} [num] places to send the group back (positive), or an
+ * absolute position `|num|` places ahead of the full back (negative). When
+ * `before`/`after` is set, `num` is the offset from the anchor (default `0`).
+ * If undefined (and no anchor), the group is sent completely to the back
+ * @property {string | Array<string>} [before] anchor element name(s) - position
+ * the group just before the most-back anchor
+ * @property {string | Array<string>} [after] anchor element name(s) - position
+ * the group just after the most-front anchor
+ * @property {boolean} [fullContentBounds] Use full bounds with content (`false`)
+ *
+ * @see To test examples, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Three overlapping squares, offset so the stacking order is visible. Blue
+ * // is defined last so it sits on top by default; `back` sends it behind the
+ * // red and green squares (so green ends up on top).
+ * const sq = color => figure.primitives.rectangle({ width: 0.6, height: 0.6, color });
+ * figure.add({
+ *   make: 'equation',
+ *   elements: {
+ *     r: sq([1, 0, 0, 1]),
+ *     g: sq([0, 0.8, 0, 1]),
+ *     b: sq([0, 0, 1, 1]),
+ *   },
+ *   forms: {
+ *     0: [
+ *       { offset: ['r', [0, 0]] },
+ *       { offset: ['g', [0.3, -0.25]] },
+ *       { offset: [{ back: ['b'] }, [0.6, -0.5]] },
+ *     ],
+ *   },
+ * });
+ *
+ * @example
+ * // Object Definition with an anchor - position the blue square just before
+ * // (behind) the red square, so red and green sit on top of it.
+ * const sq = color => figure.primitives.rectangle({ width: 0.6, height: 0.6, color });
+ * figure.add({
+ *   make: 'equation',
+ *   elements: {
+ *     r: sq([1, 0, 0, 1]),
+ *     g: sq([0, 0.8, 0, 1]),
+ *     b: sq([0, 0, 1, 1]),
+ *   },
+ *   forms: {
+ *     0: [
+ *       { offset: ['r', [0, 0]] },
+ *       { offset: ['g', [0.3, -0.25]] },
+ *       { offset: [{ back: { content: 'b', before: 'r' } }, [0.6, -0.5]] },
+ *     ],
+ *   },
+ * });
+ *
+ * @interface
+ * @group Equation Layout
+ */
+export type EQN_Back = {
+    content: TypeEquationPhrase;
+    num?: number;
+    before?: string | Array<string>;
+    after?: string | Array<string>;
+    fullContentBounds?: boolean;
+    name?: string;
+} | [
+    TypeEquationPhrase,
+    (number | null | undefined),
+    (boolean | null | undefined)
+];
+/**
+ * Equation front function
+ *
+ * Bring an equation phrase's elements forward in the equation's draw stack. All
+ * elements within `content` are moved together as a group, keeping their
+ * current relative draw order. Nested `front`/`back` functions are applied
+ * inner-most first, so an inner `front`/`back` reorders the elements and this
+ * (outer) function then moves the reordered group as a unit.
+ *
+ * The group's position is determined by, in order of precedence:
+ * - `before` - position the group just before (behind) the most-back of the
+ *   named anchor element(s). `num` shifts it further back (default `0`).
+ * - `after` - position the group just after (in front of) the most-front of
+ *   the named anchor element(s). `num` shifts it further forward (default `0`).
+ * - `num` - a positive value moves the group that many places forward; a
+ *   negative value positions it `|num|` places behind the very front.
+ * - otherwise the group is brought completely to the front.
+ *
+ * The reorder is applied whenever the form is shown, relative to the equation's
+ * natural (definition) draw order, so each form deterministically defines its
+ * own stacking.
+ *
+ * Options can be an object, or an array in the property order below
+ *
+ * @property {TypeEquationPhrase} content
+ * @property {number} [num] places to bring the group forward (positive), or an
+ * absolute position `|num|` places behind the full front (negative). When
+ * `before`/`after` is set, `num` is the offset from the anchor (default `0`).
+ * If undefined (and no anchor), the group is brought completely to the front
+ * @property {string | Array<string>} [before] anchor element name(s) - position
+ * the group just before the most-back anchor
+ * @property {string | Array<string>} [after] anchor element name(s) - position
+ * the group just after the most-front anchor
+ * @property {boolean} [fullContentBounds] Use full bounds with content (`false`)
+ *
+ * @see To test examples, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Three overlapping squares, offset so the stacking order is visible. Red is
+ * // defined first so it sits at the back by default; `front` brings it on top
+ * // of the green and blue squares.
+ * const sq = color => figure.primitives.rectangle({ width: 0.6, height: 0.6, color });
+ * figure.add({
+ *   make: 'equation',
+ *   elements: {
+ *     r: sq([1, 0, 0, 1]),
+ *     g: sq([0, 0.8, 0, 1]),
+ *     b: sq([0, 0, 1, 1]),
+ *   },
+ *   forms: {
+ *     0: [
+ *       { offset: [{ front: ['r'] }, [0, 0]] },
+ *       { offset: ['g', [0.3, -0.25]] },
+ *       { offset: ['b', [0.6, -0.5]] },
+ *     ],
+ *   },
+ * });
+ *
+ * @example
+ * // Object Definition with an anchor - position the red square just after (in
+ * // front of) the green square, so it covers green but stays behind blue.
+ * const sq = color => figure.primitives.rectangle({ width: 0.6, height: 0.6, color });
+ * figure.add({
+ *   make: 'equation',
+ *   elements: {
+ *     r: sq([1, 0, 0, 1]),
+ *     g: sq([0, 0.8, 0, 1]),
+ *     b: sq([0, 0, 1, 1]),
+ *   },
+ *   forms: {
+ *     0: [
+ *       { offset: [{ front: { content: 'r', after: 'g' } }, [0, 0]] },
+ *       { offset: ['g', [0.3, -0.25]] },
+ *       { offset: ['b', [0.6, -0.5]] },
+ *     ],
+ *   },
+ * });
+ *
+ * @interface
+ * @group Equation Layout
+ */
+export type EQN_Front = {
+    content: TypeEquationPhrase;
+    num?: number;
+    before?: string | Array<string>;
+    after?: string | Array<string>;
+    fullContentBounds?: boolean;
+    name?: string;
+} | [
+    TypeEquationPhrase,
+    (number | null | undefined),
+    (boolean | null | undefined)
+];
 /**
  * Equation bracket
  *
@@ -3272,8 +3554,8 @@ export declare class EquationFunctions {
     stringToElement(content: string): any;
     parseContent(content: TypeEquationPhrase | null | undefined): any;
     contentToElement(content: TypeEquationPhrase | Elements | FigureElementPrimitive | FigureElementCollection): Elements;
-    eqnMethod(name: string, params: any): BaseAnnotationFunction | Fraction | Matrix | Lines | Scale | Container | Offset | Color | null;
-    dispatchEqnMethod(name: string, params: any): BaseAnnotationFunction | Fraction | Matrix | Lines | Scale | Container | Offset | Color | null;
+    eqnMethod(name: string, params: any): BaseAnnotationFunction | Fraction | Matrix | Lines | Scale | Container | Offset | Color | Opacity | DrawOrder | null;
+    dispatchEqnMethod(name: string, params: any): BaseAnnotationFunction | Fraction | Matrix | Lines | Scale | Container | Offset | Color | Opacity | DrawOrder | null;
     /**
      * Equation container function
      * @see {@link EQN_Container} for description and examples
@@ -3309,6 +3591,22 @@ export declare class EquationFunctions {
      * @see {@link EQN_Color} for description and examples
      */
     color(options: EQN_Color): Color;
+    /**
+     * Equation opacity function
+     * @see {@link EQN_Opacity} for description and examples
+     */
+    opacity(options: EQN_Opacity): Opacity;
+    /**
+     * Equation back function
+     * @see {@link EQN_Back} for description and examples
+     */
+    back(options: EQN_Back): DrawOrder;
+    /**
+     * Equation front function
+     * @see {@link EQN_Front} for description and examples
+     */
+    front(options: EQN_Front): DrawOrder;
+    drawOrder(options: EQN_Front | EQN_Back, front: boolean): DrawOrder;
     /**
      * Equation fraction function
      * @see {@link EQN_Fraction} for description and examples

package/types/js/figure/FigurePrimitives/FigureElementPrimitive2DText.d.ts

@@ -108,7 +108,7 @@ export default class FigureElementPrimitive2DText extends FigureElementPrimitive
      * @return {FigureFont}
      */
     getFont(): FigureFont;
-    setColor(color: TypeColor, setDefault?: boolean): void;
+    setColor(color: TypeColor, setDefault?: boolean, from?: string | null): void;
     stateSet(): void;
     measureAndAlignText(): void;
     _getStateProperties(options: {

package/types/js/figure/FigurePrimitives/FigureElementPrimitiveGLText.d.ts

@@ -81,7 +81,7 @@ export default class FigureElementPrimitiveGLText extends FigureElementPrimitive
      * @param {OBJ_Font} font
      */
     setFont(font: OBJ_Font): void;
-    setColor(color: TypeColor, setDefault?: boolean): void;
+    setColor(color: TypeColor, setDefault?: boolean, from?: string | null): void;
     calcBorderAndBounds(): void;
     calcBorder(): void;
     stateSet(): void;