figureone 1.5.0 → 1.7.1

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;