figureone 1.5.0 → 1.7.1

package/llms-full.txt

@@ -20,6 +20,10 @@ Colors are `[r, g, b, a]` with values 0-1. Default scene is `[-1, -1, 2, 2]` (x,
 | lineWidth | number | | Default line width |
 | length | number | | Default primary dimension |
 | backgroundColor | TypeColor | | Background color |
+| textStyle | `'italic'` \| `'normal'` | `'italic'` | Default equation text style (also settable on FigurePrimitives and Equation) |
+| antialias | boolean | `true` | Enable WebGL anti-aliasing |
+| atlasScale | number | `2` | GL text atlas texture resolution relative to 1:1 pixel mapping |
+| onWebGLUnavailable | () => void | | Callback fired once during construction if no WebGL context is available (figure is still created but renders nothing) |
 
 ### Key Figure Methods
 
@@ -45,6 +49,11 @@ figure.resize();          // Resize after container change
 figure.animateNextFrame(); // Request next animation frame
 figure.isAnimating();     // Check if any animation running
 
+// WebGL context state
+figure.webglAvailable;    // false if no live WebGL context (e.g. context lost)
+figure.notifications.add('contextLost', () => { /* context removed by browser */ });
+figure.notifications.add('contextRestored', () => { /* context returned */ });
+
 // Coordinate transforms
 figure.transformPoint(point, fromSpace, toSpace);
 figure.spaceTransformMatrix(fromSpace, toSpace);
@@ -92,6 +101,7 @@ Path to figure element(s) within a collection. Supports multiple formats:
 | underline | boolean \| object | `false` | Underline options |
 | outline | boolean \| object | `false` | Outline options |
 | render | `'gl'` \| `'2d'` \| `'html'` | `'gl'` | Render target |
+| atlasId | string | | Share a single GL atlas texture across text elements with different sizes (elements with the same `atlasId` reuse one atlas) |
 
 ### OBJ_Texture
 
@@ -119,6 +129,11 @@ Path to figure element(s) within a collection. Supports multiple formats:
 | defaultColor | TypeColor | | Color when undimmed |
 | scenarios | OBJ_Scenarios | | Named presets |
 | scene | Scene \| OBJ_Scene | | Custom scene |
+| isFormIgnored | boolean | `false` | Exclude from equation form changes — skipped by form layout, show/hide, transform/color sets, and `elementMods`, so its user-applied transform, color, and visibility persist across `showForm` / `goToForm` (contributes zero size to layout) |
+| allowSetColor | `'all'` \| `'opacity'` \| `'none'` | `'all'` | Freeze color: `'opacity'` allows only the alpha channel to change; `'none'` blocks all `setColor` |
+| ignoreSetColor | string \| string[] | `[]` | Source label(s) whose tagged `setColor` commands are ignored (e.g. the equation's default `'form'` color cascade), while explicit/untagged commands (`dim`/`undim`, direct `setColor`) are still honored |
+
+These element properties are also settable at runtime; `setColor(color, setDefault?, from?)` takes an optional `from` source label that is matched against `ignoreSetColor`.
 
 ### OBJ_Collection
 
@@ -1252,6 +1267,26 @@ Array: `{ color: [content, [r, g, b, a]] }`
 | color | TypeColor | | Color to apply |
 | fullContentBounds | boolean | `false` | Use full bounds |
 
+#### EQN_Opacity (`opacity`)
+Array: `{ opacity: [content, opacity_value] }`. Wraps a phrase in an opacity multiplier that cascades multiplicatively through nested `opacity` wrappers (outer `0.5` × inner `0.5` = `0.25` on inner content). The cascaded opacity is assigned to each wrapped element whenever the form is shown, overriding externally-set element opacity — set `ignoreOpacity: true` on the form to suppress this and preserve external opacities.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| content | TypeEquationPhrase | | Content |
+| opacity | number | | Opacity multiplier in range `[0, 1]` |
+| fullContentBounds | boolean | `false` | Use full bounds |
+
+#### EQN_Front (`front`) / EQN_Back (`back`)
+Array: `{ front: [content, num] }` / `{ back: [content, num] }`. Reorder a phrase's elements within the equation's draw stack, per-form. All elements in `content` move together as a group, keeping their relative draw order. Applied whenever the form is shown, relative to the equation's natural definition order, so each form deterministically defines its own stacking. The same operations are available as `front` / `back` element mods (e.g. `elementMods: { a: { back: {} } }`).
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| content | TypeEquationPhrase | | Content |
+| num | number | | `front`: places to move forward (positive) or `\|num\|` places behind the front (negative). `back`: places to move back (positive) or `\|num\|` places ahead of the back (negative). With `before`/`after`, it's the offset from the anchor (default `0`). If omitted with no anchor, moves fully to front/back |
+| before | string \| string[] | | Anchor element name(s) — position the group just before (behind) the most-back anchor |
+| after | string \| string[] | | Anchor element name(s) — position the group just after (in front of) the most-front anchor |
+| fullContentBounds | boolean | `false` | Use full bounds |
+
 #### EQN_Container (`container`)
 Array: `{ container: [content, width] }`
 
@@ -1452,10 +1487,17 @@ forms: {
     scale: { elementName: 1.5 },     // Per-element target scales during animation
     fromPrev: { elementName: 'otherElement' }, // Animate from another element's position
     fromNext: { elementName: 'otherElement' }, // Animate from another element's position (reverse)
+    ignoreColor: false,              // true preserves externally-set element colors (suppresses color cascade)
+    ignoreOpacity: false,            // true preserves externally-set element opacities (suppresses opacity cascade)
+    elementMods: {                   // Per-element property mods applied when form shows
+      elementName: { back: {} },     // e.g. front/back reorder mods (see EQN_Front/EQN_Back)
+    },
   },
 }
 ```
 
+Every equation layout function (container, frac, matrix, brac, annotate, color, opacity, front, back, etc.) also accepts an optional `name` property — purely a label with no layout effect, used to address the function's sub-tree via `eqn.getFunctionElements(name)`.
+
 ### Forms and Animation
 
 ```js
@@ -1474,9 +1516,24 @@ const eqn = figure.add({
 });
 
 eqn.showForm('1');
+eqn.showForm('1', false);            // notify=false suppresses the formChanged event for this call
 eqn.goToForm({ form: '2', delay: 1, duration: 1.5, animate: 'move' });
 eqn.nextForm();   // Navigate formSeries
 eqn.prevForm();
+
+// Element lookup within forms
+eqn.getFormElements(formName, includeHidden?);   // All elements in a form
+eqn.getPhraseElements(phrase);                    // All elements in a phrase
+// Elements inside a named layout function (any function tagged with `name`).
+// (name, formName? = current, mode? = 'all', includeHidden? = false).
+// mode 'first' = first match; 'all' = de-duplicated union across all matches.
+eqn.getFunctionElements('myFrac');
+```
+
+`Equation` publishes a `formChanged` notification whenever the displayed form may have changed, with payload `{ phase, form, fromForm?, progress? }`. `phase` is one of: `'showForm'` (form set via `showForm`; suppress with `notify: false`), `'goToFormStart'`, `'goToFormStep'` (per animation frame, with `progress` 0–1; a final step with `progress: 1` precedes the end), `'goToFormEnd'`. `fromForm` is present only on the `goToForm*` phases.
+
+```js
+eqn.notifications.add('formChanged', ({ phase, form, progress }) => { /* drive UI */ });
 ```
 
 ### Phrases (reusable sub-expressions)
@@ -1488,6 +1545,14 @@ eqn.prevForm();
 }
 ```
 
+### LaTeX Parsing
+`Fig.latexToFigureOne(latex)` converts a LaTeX math expression into `{ elements, form }` for use in an equation definition (basic support).
+
+```js
+const { elements, form } = Fig.latexToFigureOne('\\frac{a}{b} = c');
+figure.add({ make: 'equation', elements, forms: { base: form } });
+```
+
 ---
 
 ## 7. Animation System

package/llms.txt

@@ -24,6 +24,8 @@ figure.add({ make: 'triangle', width: 0.5, height: 0.5, color: [1, 0, 0, 1] });
 
 Colors are `[r, g, b, a]` with values 0-1. Coordinates default to a scene of `[-1, -1, 2, 2]` (x, y, width, height). Override with `new Fig.Figure({ scene: [-2, -2, 4, 4] })`.
 
+Other `Fig.Figure` options: `textStyle` (`'italic'` default | `'normal'` — default equation text style), `antialias` (default `true`), `atlasScale` (GL text atlas resolution, default `2`), `onWebGLUnavailable` (callback if no WebGL context). Check `figure.webglAvailable` and subscribe to `contextLost` / `contextRestored` notifications for runtime WebGL context transitions.
+
 ## Core Concepts
 
 - **Figure** — top-level container that manages all elements and rendering
@@ -105,6 +107,9 @@ All elements accept these common options alongside shape-specific ones:
 - `color` — `[r, g, b, a]`
 - `position` — `[x, y]` shorthand for translation
 - `rotation` — rotation in radians
+- `isFormIgnored` — exclude from equation form changes (its transform/color/visibility persist across `showForm`/`goToForm`)
+- `allowSetColor` — `'all'` (default), `'opacity'` (alpha only), or `'none'` to freeze color
+- `ignoreSetColor` — source label(s) whose tagged `setColor` is ignored (e.g. the equation's `'form'` color cascade), while explicit commands still apply
 
 When `options` is used, shape-specific properties go inside it:
 
@@ -256,9 +261,14 @@ Any element type can be created inline in forms using `make`:
 | `prodOf` | `{ prodOf: { symbol, content, from, to } }` | Product |
 | `scale` | `{ scale: [content, scale_factor] }` | Scale content |
 | `color` | `{ color: [content, [r,g,b,a]] }` | Color content |
+| `opacity` | `{ opacity: [content, 0.3] }` | Opacity multiplier (cascades multiplicatively through nesting) |
+| `front` | `{ front: [content, num] }` | Bring content forward in draw stack (per-form); supports `before`/`after` anchors |
+| `back` | `{ back: [content, num] }` | Send content back in draw stack (per-form); supports `before`/`after` anchors |
 | `container` | `{ container: { content, width, ... } }` | Fixed-size container |
 | `lines` | `{ lines: { content: [...], justify } }` | Multi-line layout |
 
+Any layout function also accepts a `name` label to address its elements via `eqn.getFunctionElements(name)`. Form objects accept `ignoreColor` / `ignoreOpacity` to preserve externally-set element color/opacity (suppress the cascade).
+
 ### Symbols
 
 Define symbols in `elements` with `{ symbol: 'type' }`:
@@ -302,9 +312,12 @@ const eqn = figure.add({
 });
 
 eqn.showForm('1');
+eqn.showForm('1', false);   // notify=false suppresses the formChanged event
 eqn.goToForm({ form: '2', delay: 1, duration: 1.5, animate: 'move' });
 ```
 
+Equation publishes a `formChanged` notification with payload `{ phase, form, fromForm?, progress? }`, where `phase` is `'showForm'`, `'goToFormStart'`, `'goToFormStep'` (with `progress` 0–1), or `'goToFormEnd'`. Use `eqn.getFunctionElements(name)` to fetch elements inside a named layout function.
+
 Use `formSeries` to define an ordered list of forms, then navigate with `eqn.nextForm()` and `eqn.prevForm()`.
 
 Use `phrases` to define reusable sub-expressions:
@@ -529,6 +542,10 @@ new Fig.Transform()            // Transform builder
   .scale(sx, sy)
 Fig.round(value, precision)    // Round to N decimal places
 
+// Convert a LaTeX math expression to an equation form (basic support)
+const { elements, form } = Fig.latexToFigureOne('\\frac{a}{b} = c');
+figure.add({ make: 'equation', elements, forms: { base: form } });
+
 // Color format: [r, g, b, a] with values 0 to 1
 // [1, 0, 0, 1] = red, [0, 0, 1, 0.5] = semi-transparent blue
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.5.0",
+  "version": "1.7.1",
   "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.
@@ -825,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;

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;