figureone 1.3.0 → 1.4.0

package/index.js

@@ -17225,6 +17225,10 @@ function offsetLocationForGlyphs(glyphs, offset) {
   });
 }
 var BaseAnnotationFunction = /*#__PURE__*/function () {
+  // Optional caller-supplied identifier, assigned post-dispatch by
+  // EquationFunctions.eqnMethod. Has no layout effect; used by
+  // Equation.getElementsInForm to look up the contents of a sub-tree.
+
   function BaseAnnotationFunction(content, annotations, glyphs, options) {
     var showContent = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : true;
     _classCallCheck(this, BaseAnnotationFunction);
@@ -17236,6 +17240,7 @@ var BaseAnnotationFunction = /*#__PURE__*/function () {
     this.showContent = showContent;
     this.scale = 1;
     this.color = null;
+    this.functionName = null;
   }
   return _createClass(BaseAnnotationFunction, [{
     key: "_dup",
@@ -17870,6 +17875,10 @@ function _setPrototypeOf(t, e) { return _setPrototypeOf = Object.setPrototypeOf
 
 
 var BaseEquationFunction = /*#__PURE__*/function (_Elements) {
+  // Optional caller-supplied identifier, assigned post-dispatch by
+  // EquationFunctions.eqnMethod. Has no layout effect; used by
+  // Equation.getElementsInForm to look up the contents of a sub-tree.
+
   function BaseEquationFunction(content, glyph, options) {
     var _this;
     var showContent = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : true;
@@ -17908,6 +17917,7 @@ var BaseEquationFunction = /*#__PURE__*/function (_Elements) {
     });
     _this.options = options;
     _this.showContent = showContent;
+    _this.functionName = null;
     return _this;
   }
   _inherits(BaseEquationFunction, _Elements);
@@ -19441,11 +19451,12 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _DrawingObjects_TextObject_TextObject__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(/*! ../DrawingObjects/TextObject/TextObject */ "./src/js/figure/DrawingObjects/TextObject/TextObject.ts");
 /* harmony import */ var _Elements_Element__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(/*! ./Elements/Element */ "./src/js/figure/Equation/Elements/Element.ts");
 /* harmony import */ var _Elements_BaseAnnotationFunction__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(/*! ./Elements/BaseAnnotationFunction */ "./src/js/figure/Equation/Elements/BaseAnnotationFunction.ts");
-/* harmony import */ var _EquationForm__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(/*! ./EquationForm */ "./src/js/figure/Equation/EquationForm.ts");
-/* harmony import */ var _tools_htmlGenerator__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(/*! ../../tools/htmlGenerator */ "./src/js/tools/htmlGenerator.ts");
-/* harmony import */ var _EquationSymbols__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(/*! ./EquationSymbols */ "./src/js/figure/Equation/EquationSymbols.ts");
-/* harmony import */ var _EquationFunctions__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(/*! ./EquationFunctions */ "./src/js/figure/Equation/EquationFunctions.ts");
-/* harmony import */ var _Animation_Animation__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ../Animation/Animation */ "./src/js/figure/Animation/Animation.ts");
+/* harmony import */ var _Elements_BaseEquationFunction__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(/*! ./Elements/BaseEquationFunction */ "./src/js/figure/Equation/Elements/BaseEquationFunction.ts");
+/* harmony import */ var _EquationForm__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(/*! ./EquationForm */ "./src/js/figure/Equation/EquationForm.ts");
+/* harmony import */ var _tools_htmlGenerator__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(/*! ../../tools/htmlGenerator */ "./src/js/tools/htmlGenerator.ts");
+/* harmony import */ var _EquationSymbols__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(/*! ./EquationSymbols */ "./src/js/figure/Equation/EquationSymbols.ts");
+/* harmony import */ var _EquationFunctions__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ./EquationFunctions */ "./src/js/figure/Equation/EquationFunctions.ts");
+/* harmony import */ var _Animation_Animation__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! ../Animation/Animation */ "./src/js/figure/Animation/Animation.ts");
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
@@ -19480,6 +19491,7 @@ function _setPrototypeOf(t, e) { return _setPrototypeOf = Object.setPrototypeOf
 
 
 
+
 // import HTMLObject from '../DrawingObjects/HTMLObject/HTMLObject';
 
 
@@ -20178,7 +20190,7 @@ var NextFormAnimationStep = /*#__PURE__*/function (_TriggerAnimationStep) {
   }
   _inherits(NextFormAnimationStep, _TriggerAnimationStep);
   return _createClass(NextFormAnimationStep);
-}(_Animation_Animation__WEBPACK_IMPORTED_MODULE_10__.TriggerAnimationStep);
+}(_Animation_Animation__WEBPACK_IMPORTED_MODULE_11__.TriggerAnimationStep);
 /**
  * GoToForm form animation step
  *
@@ -20229,7 +20241,7 @@ var GoToFormAnimationStep = /*#__PURE__*/function (_TriggerAnimationStep2) {
   }
   _inherits(GoToFormAnimationStep, _TriggerAnimationStep2);
   return _createClass(GoToFormAnimationStep);
-}(_Animation_Animation__WEBPACK_IMPORTED_MODULE_10__.TriggerAnimationStep); // export const foo = () => {};
+}(_Animation_Animation__WEBPACK_IMPORTED_MODULE_11__.TriggerAnimationStep); // export const foo = () => {};
 // An Equation is a collection of elements that can be arranged into different
 // forms.
 // Equation allows setting of forms, and navigating through form series
@@ -20430,8 +20442,8 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
         layout: optionsToUse.formDefaults.layout,
         ignoreColor: optionsToUse.formDefaults.ignoreColor
       },
-      functions: new _EquationFunctions__WEBPACK_IMPORTED_MODULE_9__.EquationFunctions(_this.elements, _this.addElementFromKey.bind(_this), _this.getExistingOrAddSymbol.bind(_this), _this.makeInlineElement.bind(_this)),
-      symbols: new _EquationSymbols__WEBPACK_IMPORTED_MODULE_8__["default"](_this.shapes, _this.color),
+      functions: new _EquationFunctions__WEBPACK_IMPORTED_MODULE_10__.EquationFunctions(_this.elements, _this.addElementFromKey.bind(_this), _this.getExistingOrAddSymbol.bind(_this), _this.makeInlineElement.bind(_this)),
+      symbols: new _EquationSymbols__WEBPACK_IMPORTED_MODULE_9__["default"](_this.shapes, _this.color),
       font: optionsToUse.font,
       textFont: optionsToUse.textFont,
       // fontText: optionsToUse.fontText,
@@ -20531,7 +20543,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
       o.delay = 0;
       o.setToEnd = '_showForm';
       o.timeKeeper = _this.timeKeeper;
-      return new _Animation_Animation__WEBPACK_IMPORTED_MODULE_10__.TriggerAnimationStep(o);
+      return new _Animation_Animation__WEBPACK_IMPORTED_MODULE_11__.TriggerAnimationStep(o);
     };
     _this.animations.customSteps.push({
       step: _this.animations.goToForm.bind(_this),
@@ -20577,7 +20589,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
       o.delay = 0;
       o.setToEnd = '_showForm';
       o.timeKeeper = _this.timeKeeper;
-      return new _Animation_Animation__WEBPACK_IMPORTED_MODULE_10__.TriggerAnimationStep(o);
+      return new _Animation_Animation__WEBPACK_IMPORTED_MODULE_11__.TriggerAnimationStep(o);
     };
     _this.animations.customSteps.push({
       step: _this.animations.nextForm.bind(_this),
@@ -21221,7 +21233,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
     key: "checkFixTo",
     value: function checkFixTo(fixTo, formElements) {
       if (typeof fixTo === 'string') {
-        var element = (0,_EquationFunctions__WEBPACK_IMPORTED_MODULE_9__.getFigureElement)(this, fixTo);
+        var element = (0,_EquationFunctions__WEBPACK_IMPORTED_MODULE_10__.getFigureElement)(this, fixTo);
         if (element != null && formElements.indexOf(element) >= 0) {
           return element;
         }
@@ -21239,7 +21251,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
     key: "createForm",
     value: function createForm() {
       var elements = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.elements;
-      return new _EquationForm__WEBPACK_IMPORTED_MODULE_6__["default"](elements, {
+      return new _EquationForm__WEBPACK_IMPORTED_MODULE_7__["default"](elements, {
         getAllElements: this.getChildren.bind(this),
         hideAll: this.hideAll.bind(this),
         show: this.show.bind(this),
@@ -21269,6 +21281,87 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
       return this.eqn.forms[form].content[0].getAllElements(includeHidden);
     }
 
+    /**
+     * Return all the elements inside the named equation function within a given
+     * form.
+     *
+     * Any equation function (container, fraction, matrix, etc.) can be tagged
+     * with a `name` property in its options — this has no layout effect, but
+     * makes the function's sub-tree addressable here.
+     *
+     * With `mode: 'first'` (default), returns the elements inside the first
+     * matching function found by a depth-first traversal. With `mode: 'all'`,
+     * walks the entire tree, collects every matching function (including those
+     * nested inside other matches), and returns the de-duplicated union of
+     * their elements.
+     *
+     * Returns an empty array if the form does not exist, or no matching
+     * function is found.
+     *
+     * @param {string} formName
+     * @param {string} name
+     * @param {'first' | 'all'} [mode] (`'first'`)
+     * @param {boolean} [includeHidden] (`false`)
+     * @return {Array<FigureElement>}
+     */
+  }, {
+    key: "getElementsInForm",
+    value: function getElementsInForm(formName, name) {
+      var mode = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'first';
+      var includeHidden = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
+      var form = this.eqn.forms[formName];
+      if (form == null) {
+        return [];
+      }
+      // Single typed accessor that hides the structural differences between
+      // Elements (.content: ElementInterface[]) and BaseAnnotationFunction
+      // (.content: ElementInterface + .annotations[].content). All `as any`
+      // casts for this walk live here.
+      var childrenOf = function childrenOf(node) {
+        var out = [];
+        var c = node.content;
+        if (Array.isArray(c)) {
+          out.push.apply(out, _toConsumableArray(c));
+        } else if (c != null) {
+          out.push(c);
+        }
+        var annotations = node.annotations;
+        if (Array.isArray(annotations)) {
+          annotations.forEach(function (a) {
+            if (a != null && a.content != null) out.push(a.content);
+          });
+        }
+        return out;
+      };
+      var matches = [];
+      var _walk = function walk(nodes) {
+        for (var i = 0; i < nodes.length; i += 1) {
+          var node = nodes[i];
+          if ((node instanceof _Elements_BaseEquationFunction__WEBPACK_IMPORTED_MODULE_6__["default"] || node instanceof _Elements_BaseAnnotationFunction__WEBPACK_IMPORTED_MODULE_5__["default"]) && node.functionName === name) {
+            matches.push(node);
+            if (mode === 'first') return true;
+          }
+          if (_walk(childrenOf(node))) return true;
+        }
+        return false;
+      };
+      _walk(form.content);
+      if (matches.length === 0) {
+        return [];
+      }
+      var seen = new Set();
+      var out = [];
+      matches.forEach(function (m) {
+        m.getAllElements(includeHidden).forEach(function (el) {
+          if (!seen.has(el)) {
+            seen.add(el);
+            out.push(el);
+          }
+        });
+      });
+      return out;
+    }
+
     /**
      * Return all the elements that are used in an equation phrase.
      * @param {TypeEquationPhrase} phrase
@@ -21403,7 +21496,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
         var newMods = {};
         Object.keys(elementMods).forEach(function (elementName) {
           var mods = elementMods[elementName];
-          var figureElement = (0,_EquationFunctions__WEBPACK_IMPORTED_MODULE_9__.getFigureElement)(_this9, elementName);
+          var figureElement = (0,_EquationFunctions__WEBPACK_IMPORTED_MODULE_10__.getFigureElement)(_this9, elementName);
           if (figureElement != null) {
             newMods[elementName] = {
               element: figureElement,
@@ -21416,7 +21509,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
       var transformTranslation = function transformTranslation(trans) {
         var newTranslation = {};
         Object.keys(trans).forEach(function (elementName) {
-          var figureElement = (0,_EquationFunctions__WEBPACK_IMPORTED_MODULE_9__.getFigureElement)(_this9, elementName);
+          var figureElement = (0,_EquationFunctions__WEBPACK_IMPORTED_MODULE_10__.getFigureElement)(_this9, elementName);
           var mods = trans[elementName];
           var direction;
           var style;
@@ -21594,7 +21687,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
     value: function getForm(formOrName
     // subForm: ?string,
     ) {
-      if (formOrName instanceof _EquationForm__WEBPACK_IMPORTED_MODULE_6__["default"]) {
+      if (formOrName instanceof _EquationForm__WEBPACK_IMPORTED_MODULE_7__["default"]) {
         return formOrName;
       }
       if (formOrName in this.eqn.forms) {
@@ -21938,7 +22031,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
     ) {
       var form = this.getForm(formOrName);
       if (form != null && form.description != null) {
-        return _tools_htmlGenerator__WEBPACK_IMPORTED_MODULE_7__.applyModifiers(form.description, form.modifiers);
+        return _tools_htmlGenerator__WEBPACK_IMPORTED_MODULE_8__.applyModifiers(form.description, form.modifiers);
       }
       return '';
     }
@@ -22741,9 +22834,10 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _Elements_Scale__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(/*! ./Elements/Scale */ "./src/js/figure/Equation/Elements/Scale.ts");
 /* harmony import */ var _Elements_Container__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(/*! ./Elements/Container */ "./src/js/figure/Equation/Elements/Container.ts");
 /* harmony import */ var _Elements_BaseAnnotationFunction__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(/*! ./Elements/BaseAnnotationFunction */ "./src/js/figure/Equation/Elements/BaseAnnotationFunction.ts");
-/* harmony import */ var _Symbols_Line__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ./Symbols/Line */ "./src/js/figure/Equation/Symbols/Line.ts");
-/* harmony import */ var _Elements_Offset__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! ./Elements/Offset */ "./src/js/figure/Equation/Elements/Offset.ts");
-/* harmony import */ var _Elements_Color__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(/*! ./Elements/Color */ "./src/js/figure/Equation/Elements/Color.ts");
+/* harmony import */ var _Elements_BaseEquationFunction__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ./Elements/BaseEquationFunction */ "./src/js/figure/Equation/Elements/BaseEquationFunction.ts");
+/* harmony import */ var _Symbols_Line__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! ./Symbols/Line */ "./src/js/figure/Equation/Symbols/Line.ts");
+/* harmony import */ var _Elements_Offset__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(/*! ./Elements/Offset */ "./src/js/figure/Equation/Elements/Offset.ts");
+/* harmony import */ var _Elements_Color__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(/*! ./Elements/Color */ "./src/js/figure/Equation/Elements/Color.ts");
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
@@ -22773,6 +22867,7 @@ function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e
 
 
 
+
 // import type {
 //   EQN_Annotation, EQN_EncompassGlyph, EQN_LeftRightGlyph, EQN_TopBottomGlyph,
 // } from './Elements/BaseAnnotationFunction';
@@ -22893,6 +22988,9 @@ function getFigureElement(elementsObject, name) {
  * @property {boolean} [fullContentBounds] - (`false`)
  * @property {boolean} [showContent] - if `false`, a container will be created
  * around the content, but the content will not be shown (`true`)
+ * @property {string} [name] - optional identifier (available on every equation
+ * function). Has no effect on layout, but allows the function's contents to be
+ * looked up later with {@link Equation.getElementsInForm} (`null`)
  *
  * @see To test examples, append them to the
  * <a href="#drawing-boilerplate">boilerplate</a>
@@ -25529,6 +25627,18 @@ var EquationFunctions = /*#__PURE__*/function () {
   }, {
     key: "eqnMethod",
     value: function eqnMethod(name, params) {
+      var result = this.dispatchEqnMethod(name, params);
+      // Allow any equation function to be tagged with a caller-supplied
+      // `name` via its options object. The tag has no layout effect; it's
+      // used by Equation.getElementsInForm to look up the function's sub-tree.
+      if (result != null && params != null && !Array.isArray(params) && _typeof(params) === 'object' && params.name != null && (result instanceof _Elements_BaseEquationFunction__WEBPACK_IMPORTED_MODULE_10__["default"] || result instanceof _Elements_BaseAnnotationFunction__WEBPACK_IMPORTED_MODULE_9__["default"])) {
+        result.functionName = params.name;
+      }
+      return result;
+    }
+  }, {
+    key: "dispatchEqnMethod",
+    value: function dispatchEqnMethod(name, params) {
       if (name === 'frac') {
         return this.frac(params);
       }
@@ -25723,7 +25833,7 @@ var EquationFunctions = /*#__PURE__*/function () {
           fullContentBounds: fullContentBounds
         };
         var o = (0,_tools_tools__WEBPACK_IMPORTED_MODULE_1__.joinObjects)(defaultOptions, optionsIn);
-        return new _Elements_Offset__WEBPACK_IMPORTED_MODULE_11__["default"]([this.contentToElement(content)], [], o);
+        return new _Elements_Offset__WEBPACK_IMPORTED_MODULE_12__["default"]([this.contentToElement(content)], [], o);
       } catch (e) {
         throw new Error("FigureOne Equation Offset Error: ".concat(e.message));
       }
@@ -26229,7 +26339,7 @@ var EquationFunctions = /*#__PURE__*/function () {
           fullContentBounds: fullContentBounds
         };
         var o = (0,_tools_tools__WEBPACK_IMPORTED_MODULE_1__.joinObjects)(defaultOptions, optionsIn);
-        return new _Elements_Color__WEBPACK_IMPORTED_MODULE_12__["default"]([this.contentToElement(content)], [], o);
+        return new _Elements_Color__WEBPACK_IMPORTED_MODULE_13__["default"]([this.contentToElement(content)], [], o);
       } catch (e) {
         throw new Error("FigureOne Equation Color Error: ".concat(e.message));
       }
@@ -27462,7 +27572,7 @@ var EquationFunctions = /*#__PURE__*/function () {
           });
         }
         var glyph = this.getExistingOrAddSymbol(symbol);
-        if (glyph instanceof _Symbols_Line__WEBPACK_IMPORTED_MODULE_10__["default"]) {
+        if (glyph instanceof _Symbols_Line__WEBPACK_IMPORTED_MODULE_11__["default"]) {
           annotations[0].offset = [0, commentSpaceToUse + contentSpaceToUse];
           return this.annotate({
             content: content,
@@ -27545,7 +27655,7 @@ var EquationFunctions = /*#__PURE__*/function () {
           });
         }
         var glyph = this.getExistingOrAddSymbol(symbol);
-        if (glyph instanceof _Symbols_Line__WEBPACK_IMPORTED_MODULE_10__["default"]) {
+        if (glyph instanceof _Symbols_Line__WEBPACK_IMPORTED_MODULE_11__["default"]) {
           annotations[0].offset = [0, -commentSpaceToUse - contentSpaceToUse];
           return this.annotate({
             content: content,
@@ -80682,8 +80792,8 @@ var tools = {
  */
 
 var Fig = {
-  version: "1.3.0",
-  gitHash: "3aa02f880",
+  version: "1.4.0",
+  gitHash: "77f124c53",
   tools: tools,
   Figure: _js_figure_Figure__WEBPACK_IMPORTED_MODULE_5__["default"],
   Recorder: _js_figure_Recorder_Recorder__WEBPACK_IMPORTED_MODULE_7__.Recorder,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.3.0",
+  "version": "1.4.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/Equation/Elements/BaseAnnotationFunction.d.ts

@@ -101,6 +101,7 @@ export default class BaseAnnotationFunction implements ElementInterface {
     annotations: Array<EQN_Annotation>;
     glyphs: EQN_Glyphs;
     options: Record<string, any>;
+    functionName: string | null;
     constructor(content: ElementInterface, annotations: Array<EQN_Annotation>, glyphs: EQN_Glyphs, options: Record<string, any>, showContent?: boolean);
     _dup(namedCollection?: Record<string, any>): any;
     cleanup(): void;

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

@@ -10,6 +10,7 @@ export default class BaseEquationFunction extends Elements {
     glyphHeights: Array<number>;
     showContent: boolean;
     options: Record<string, any>;
+    functionName: string | null;
     constructor(content: Elements | null | Array<Elements | null>, glyph: Symbol | null | undefined | Array<Symbol | null | undefined>, options: Record<string, any>, showContent?: boolean);
     _dup(namedCollection?: Record<string, any>): any;
     getAllElements(includeHidden?: boolean): any[];

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

@@ -906,6 +906,30 @@ export declare class Equation extends FigureElementCollection {
      * @return {Array<FigureElement>}
      */
     getFormElements(form: string, includeHidden?: boolean): (FigureElementCollection | FigureElementPrimitive | ElementInterface)[];
+    /**
+     * Return all the elements inside the named equation function within a given
+     * form.
+     *
+     * Any equation function (container, fraction, matrix, etc.) can be tagged
+     * with a `name` property in its options — this has no layout effect, but
+     * makes the function's sub-tree addressable here.
+     *
+     * With `mode: 'first'` (default), returns the elements inside the first
+     * matching function found by a depth-first traversal. With `mode: 'all'`,
+     * walks the entire tree, collects every matching function (including those
+     * nested inside other matches), and returns the de-duplicated union of
+     * their elements.
+     *
+     * Returns an empty array if the form does not exist, or no matching
+     * function is found.
+     *
+     * @param {string} formName
+     * @param {string} name
+     * @param {'first' | 'all'} [mode] (`'first'`)
+     * @param {boolean} [includeHidden] (`false`)
+     * @return {Array<FigureElement>}
+     */
+    getElementsInForm(formName: string, name: string, mode?: 'first' | 'all', includeHidden?: boolean): any[];
     /**
      * Return all the elements that are used in an equation phrase.
      * @param {TypeEquationPhrase} phrase

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

@@ -170,6 +170,9 @@ export type TypeEquationPhrase = string | number | {
  * @property {boolean} [fullContentBounds] - (`false`)
  * @property {boolean} [showContent] - if `false`, a container will be created
  * around the content, but the content will not be shown (`true`)
+ * @property {string} [name] - optional identifier (available on every equation
+ * function). Has no effect on layout, but allows the function's contents to be
+ * looked up later with {@link Equation.getElementsInForm} (`null`)
  *
  * @see To test examples, append them to the
  * <a href="#drawing-boilerplate">boilerplate</a>
@@ -236,6 +239,7 @@ export type EQN_Container = {
     scale?: number;
     fullContentBounds?: boolean;
     showContent?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     (number | null | undefined),
@@ -288,6 +292,7 @@ export type EQN_Offset = {
     offset?: TypeParsablePoint;
     inSize?: boolean;
     fullContentBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     (TypeParsablePoint | null | undefined),
@@ -411,6 +416,7 @@ export type EQN_Fraction = {
     offsetY?: number;
     baseline?: 'numerator' | 'denominator' | 'vinculum';
     fullContentBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     string,
@@ -486,6 +492,7 @@ export type EQN_Scale = {
     content: TypeEquationPhrase;
     scale?: number;
     fullContentBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     (number | null | undefined),
@@ -564,6 +571,7 @@ export type EQN_Color = {
     content: TypeEquationPhrase;
     color: TypeColor;
     fullContentBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     TypeColor,
@@ -677,6 +685,7 @@ export type EQN_Bracket = {
     descent?: number;
     fullContentBounds?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     string,
     TypeEquationPhrase,
@@ -812,6 +821,7 @@ export type EQN_Root = {
     rootScale?: number;
     fullContentBounds?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     string,
     TypeEquationPhrase,
@@ -928,6 +938,7 @@ export type EQN_Strike = {
     leftSpace?: number;
     fullContentBounds?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     string,
@@ -1045,6 +1056,7 @@ export type EQN_Box = {
     leftSpace?: number;
     fullContentBounds?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     string,
@@ -1092,6 +1104,7 @@ export type EQN_TouchBox = {
     rightSpace?: number;
     bottomSpace?: number;
     leftSpace?: number;
+    name?: string;
 } | [
     TypeEquationPhrase,
     string,
@@ -1232,6 +1245,7 @@ export type EQN_Bar = {
     descent?: number;
     fullContentBounds?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     (string | null | undefined),
@@ -1403,6 +1417,7 @@ export type EQN_Integral = {
     toYAlign?: 'bottom' | 'top' | 'middle' | 'baseline' | number;
     fullBoundsContent?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     (string | null | undefined),
     (TypeEquationPhrase | null | undefined),
@@ -1543,6 +1558,7 @@ export type EQN_SumOf = {
     toOffset?: TypeParsablePoint;
     fullBoundsContent?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     (string | null | undefined),
     TypeEquationPhrase,
@@ -1675,6 +1691,7 @@ export type EQN_ProdOf = {
     toOffset?: TypeParsablePoint;
     fullBoundsContent?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     (string | null | undefined),
     TypeEquationPhrase,
@@ -1764,6 +1781,7 @@ export type EQN_Subscript = {
     scale?: number;
     offset?: TypeParsablePoint;
     inSize: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     TypeEquationPhrase,
@@ -1831,6 +1849,7 @@ export type EQN_Superscript = {
     scale?: number;
     offset?: TypeParsablePoint;
     inSize: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     TypeEquationPhrase,
@@ -1900,6 +1919,7 @@ export type EQN_SuperscriptSubscript = {
     superscriptOffset?: TypeParsablePoint;
     subscriptOffset?: TypeParsablePoint;
     inSize?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     TypeEquationPhrase,
@@ -2012,6 +2032,7 @@ export type EQN_Comment = {
     inSize?: boolean;
     fullContentBounds?: boolean;
     useFullBounds?: boolean;
+    name?: string;
 } | [
     TypeEquationPhrase,
     TypeEquationPhrase,
@@ -2108,6 +2129,7 @@ export type EQN_StrikeComment = {
     space?: number;
     scale?: number;
     commentSpace?: number;
+    name?: string;
 } | [
     (TypeEquationPhrase | null | undefined),
     (string | null | undefined),
@@ -2184,6 +2206,7 @@ export type EQN_Pad = {
     right?: number;
     bottom?: number;
     left?: number;
+    name?: string;
 } | [
     TypeEquationPhrase,
     (number | null | undefined),
@@ -2306,6 +2329,7 @@ export type EQN_Matrix = {
     yAlign?: 'baseline' | 'middle';
     brac?: EQN_Bracket;
     fullContentBounds?: boolean;
+    name?: string;
 } | [
     ([number, number] | null | undefined),
     (string | null | undefined),
@@ -2460,6 +2484,7 @@ export type EQN_Lines = {
     space?: number;
     yAlign?: 'bottom' | 'top' | 'middle' | number;
     fullContentBounds?: boolean;
+    name?: string;
 };
 /**
  * Annotation options object.
@@ -3214,6 +3239,7 @@ export type EQN_Annotate = {
     leftSpace?: number;
     rightSpace?: number;
     contentScale?: number;
+    name?: string;
 };
 /**
  * Equation Functions.
@@ -3247,6 +3273,7 @@ export declare class EquationFunctions {
     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;
     /**
      * Equation container function
      * @see {@link EQN_Container} for description and examples