figureone 1.4.0 → 1.5.0

package/index.js

@@ -17227,7 +17227,7 @@ 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.
+  // Equation.getFunctionElements 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;
@@ -17877,7 +17877,7 @@ 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.
+  // Equation.getFunctionElements to look up the contents of a sub-tree.
 
   function BaseEquationFunction(content, glyph, options) {
     var _this;
@@ -20257,6 +20257,32 @@ var GoToFormAnimationStep = /*#__PURE__*/function (_TriggerAnimationStep2) {
  * * {@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
@@ -21282,34 +21308,37 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
     }
 
     /**
-     * Return all the elements inside the named equation function within a given
-     * form.
+     * Return all the elements inside the named equation function within a 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.
+     * With `mode: 'all'` (default), walks the entire tree, collects every
+     * matching function (including those nested inside other matches), and
+     * returns the de-duplicated union of their elements. With `mode: 'first'`,
+     * returns only the elements inside the first matching function found by a
+     * depth-first traversal.
+     *
+     * If `formName` is `null` (default), the current form is used.
      *
      * 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 {string | null} [formName] (`null` — uses current form)
+     * @param {'first' | 'all'} [mode] (`'all'`)
      * @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';
+    key: "getFunctionElements",
+    value: function getFunctionElements(name) {
+      var formName = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
+      var mode = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'all';
       var includeHidden = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
-      var form = this.eqn.forms[formName];
+      var resolvedFormName = formName == null ? this.eqn.currentForm : formName;
+      var form = this.eqn.forms[resolvedFormName];
       if (form == null) {
         return [];
       }
@@ -21439,6 +21468,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
       this.stopAnimating(how, '_Equation', true);
       this.stopAnimating(how, '_EquationColor', true);
       this.stopAnimating(how, '_EquationAnimateColor', true);
+      this.stopAnimating(how, '_EquationFormStep', true);
       this.stopPulsing(how);
     }
   }, {
@@ -21631,13 +21661,26 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
     /**
      * Show equation form
      */
+    /**
+     * 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.
+     */
   }, {
     key: "showForm",
     value: function showForm() {
       var formOrName = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.eqn.currentForm;
       var animationStop = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : true;
+      var notify = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
       _superPropGet(Equation, "show", this, 3)([]);
-      // this.custom.settingForm = true;
       var form = formOrName;
       if (typeof formOrName === 'string') {
         form = this.getForm(formOrName);
@@ -21648,6 +21691,12 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
         this.render(animationStop);
         this.fnMap.exec(form.onTransition);
         this.fnMap.exec(form.onShow);
+        if (notify) {
+          this.notifications.publish('formChanged', {
+            phase: 'showForm',
+            form: form
+          });
+        }
       }
     }
   }, {
@@ -21726,7 +21775,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
           // this.stopEquationAnimating('complete');
           var currentForm = this.getCurrentForm();
           if (currentForm != null) {
-            this.showForm(currentForm);
+            this.showForm(currentForm, true, false);
           }
         } else {
           // this.stopEquationAnimating('cancel');
@@ -21810,20 +21859,65 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
         }
       }
       if (duration === 0) {
-        this.showForm(form);
+        this.notifications.publish('formChanged', {
+          phase: 'goToFormStart',
+          form: form,
+          fromForm: options.fromWhere
+        });
+        this.showForm(form, true, false);
         this.fnMap.exec(options.callback);
+        this.notifications.publish('formChanged', {
+          phase: 'goToFormStep',
+          form: form,
+          fromForm: options.fromWhere,
+          progress: 1
+        });
+        this.notifications.publish('formChanged', {
+          phase: 'goToFormEnd',
+          form: form,
+          fromForm: options.fromWhere
+        });
       } else {
         this.eqn.isAnimating = true;
         this.fnMap.exec(onTransition);
+        // Set the current form before publishing goToFormStart so listeners
+        // that call getCurrentForm() see the target form, matching the payload.
+        this.setCurrentForm(form);
+        this.notifications.publish('formChanged', {
+          phase: 'goToFormStart',
+          form: form,
+          fromForm: options.fromWhere
+        });
+        var stepStarted = false;
         var end = function end() {
           _this1.fnMap.exec(form.onShow);
           _this1.eqn.isAnimating = false;
           _this1.fnMap.exec(options.callback);
+          // Cancelling the step ticker stops any further frame callbacks
+          // after end(). It cannot retract a step(p:1) the ticker may have
+          // already published earlier in this frame, so the ticker callback
+          // also skips p===1 — the manual publish below is the single
+          // canonical terminal step event.
+          if (stepStarted) {
+            _this1.stopAnimating('cancel', '_EquationFormStep', true);
+          }
+          _this1.notifications.publish('formChanged', {
+            phase: 'goToFormStep',
+            form: form,
+            fromForm: options.fromWhere,
+            progress: 1
+          });
+          _this1.notifications.publish('formChanged', {
+            phase: 'goToFormEnd',
+            form: form,
+            fromForm: options.fromWhere
+          });
         };
+        var totalTime = 0;
         if (options.animate === 'move') {
-          form.animatePositionsTo(options.delay, options.dissolveOutTime, duration, options.dissolveInTime, end, options.fromWhere, false);
+          totalTime = form.animatePositionsTo(options.delay, options.dissolveOutTime, duration, options.dissolveInTime, end, options.fromWhere, false);
         } else if (options.animate === 'dissolveInThenMove') {
-          form.animatePositionsTo(options.delay, options.dissolveOutTime, duration, options.dissolveInTime, end, options.fromWhere, true);
+          totalTime = form.animatePositionsTo(options.delay, options.dissolveOutTime, duration, options.dissolveInTime, end, options.fromWhere, true);
         } else if (options.animate === 'moveFrom' && this.eqn.formRestart != null && this.eqn.formRestart.moveFrom != null) {
           var moveFrom = this.eqn.formRestart.moveFrom;
           var target = this.getPosition();
@@ -21837,7 +21931,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
             start = (0,_tools_g2__WEBPACK_IMPORTED_MODULE_0__.getPoint)(this.eqn.formRestart.moveFrom);
           }
           var showFormCallback = function showFormCallback() {
-            _this1.showForm(form.name, false);
+            _this1.showForm(form.name, false, false);
           };
           this.fnMap.add('_equationShowFormCallback', showFormCallback);
           this.animations["new"]('_Equation').dissolveOut({
@@ -21852,6 +21946,14 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
             target: target,
             duration: duration
           }).whenFinished(end).start();
+          if (duration != null) {
+            totalTime = options.delay + options.dissolveOutTime + 0.01 + duration;
+          } else {
+            // duration is null — the position step computes a velocity-based
+            // move time internally. Read it back from the chain we just
+            // started so the step ticker still covers the full animation.
+            totalTime = this.animations.getRemainingTime('_Equation');
+          }
         } else if (options.animate === 'pulse' && this.eqn.formRestart != null && this.eqn.formRestart.pulse != null) {
           var pulse = this.eqn.formRestart.pulse;
           var newEnd = function newEnd() {
@@ -21868,11 +21970,30 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
               });
             }
           };
-          form.allHideShow(options.delay, options.dissolveOutTime, options.blankTime, options.dissolveInTime, newEnd);
+          var hideShowTime = form.allHideShow(options.delay, options.dissolveOutTime, options.blankTime, options.dissolveInTime, newEnd);
+          totalTime = hideShowTime + (pulse.duration != null ? pulse.duration : 0);
         } else {
-          form.allHideShow(options.delay, options.dissolveOutTime, options.blankTime, options.dissolveInTime, end);
+          totalTime = form.allHideShow(options.delay, options.dissolveOutTime, options.blankTime, options.dissolveInTime, end);
+        }
+        if (totalTime > 0) {
+          this.animations["new"]('_EquationFormStep').custom({
+            callback: function callback(p) {
+              // Skip the terminal tick — end() publishes the canonical
+              // step(p:1) so the ticker would otherwise duplicate it (and
+              // CustomAnimationStep can land on p=1 twice via
+              // nextFrame + finish()).
+              if (p >= 1) return;
+              _this1.notifications.publish('formChanged', {
+                phase: 'goToFormStep',
+                form: form,
+                fromForm: options.fromWhere,
+                progress: p
+              });
+            },
+            duration: totalTime
+          }).start();
+          stepStarted = true;
         }
-        this.setCurrentForm(form);
       }
     }
   }, {
@@ -21983,7 +22104,7 @@ var Equation = /*#__PURE__*/function (_FigureElementCollect) {
         this.eqn.isAnimating = false;
         var currentForm = this.getCurrentForm();
         if (currentForm != null) {
-          this.showForm(currentForm);
+          this.showForm(currentForm, true, false);
         }
         return;
       }
@@ -22539,8 +22660,8 @@ var EquationForm = /*#__PURE__*/function (_Elements) {
       if (elementsToShow.length === 0 && elementsShown.length === 0) {
         if (callback != null) {
           callback(false);
-          return;
         }
+        return 0;
       }
       var dissolveOutCallback = function dissolveOutCallback() {
         _this3.setPositions();
@@ -22584,6 +22705,13 @@ var EquationForm = /*#__PURE__*/function (_Elements) {
           delay: blankTime
         }).start();
       });
+      if (elementsToShow.length > 0) {
+        cumTime += blankTime + showTime;
+      }
+      // Upper bound on the total animation time: when elementsToDelayShowing
+      // finish their dissolveIn. elementsToShowAfterDissolve are scheduled with
+      // `delay: blankTime` (not `cumTime + blankTime`) so they may finish earlier.
+      return cumTime;
     }
   }, {
     key: "applyElementMods",
@@ -22990,7 +23118,7 @@ function getFigureElement(elementsObject, name) {
  * 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`)
+ * looked up later with {@link Equation.getFunctionElements} (`null`)
  *
  * @see To test examples, append them to the
  * <a href="#drawing-boilerplate">boilerplate</a>
@@ -25630,7 +25758,7 @@ var EquationFunctions = /*#__PURE__*/function () {
       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.
+      // used by Equation.getFunctionElements 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;
       }
@@ -80792,8 +80920,8 @@ var tools = {
  */
 
 var Fig = {
-  version: "1.4.0",
-  gitHash: "77f124c53",
+  version: "1.5.0",
+  gitHash: "2390662f6",
   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.4.0",
+  "version": "1.5.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/Equation.d.ts

@@ -726,6 +726,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
@@ -907,29 +933,30 @@ export declare class Equation extends FigureElementCollection {
      */
     getFormElements(form: string, includeHidden?: boolean): (FigureElementCollection | FigureElementPrimitive | ElementInterface)[];
     /**
-     * Return all the elements inside the named equation function within a given
-     * form.
+     * Return all the elements inside the named equation function within a 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.
+     * With `mode: 'all'` (default), walks the entire tree, collects every
+     * matching function (including those nested inside other matches), and
+     * returns the de-duplicated union of their elements. With `mode: 'first'`,
+     * returns only the elements inside the first matching function found by a
+     * depth-first traversal.
+     *
+     * If `formName` is `null` (default), the current form is used.
      *
      * 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 {string | null} [formName] (`null` — uses current form)
+     * @param {'first' | 'all'} [mode] (`'all'`)
      * @param {boolean} [includeHidden] (`false`)
      * @return {Array<FigureElement>}
      */
-    getElementsInForm(formName: string, name: string, mode?: 'first' | 'all', includeHidden?: boolean): any[];
+    getFunctionElements(name: string, formName?: string | null, mode?: 'first' | 'all', includeHidden?: boolean): any[];
     /**
      * Return all the elements that are used in an equation phrase.
      * @param {TypeEquationPhrase} phrase
@@ -978,7 +1005,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

@@ -133,7 +133,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

@@ -172,7 +172,7 @@ export type TypeEquationPhrase = string | number | {
  * 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`)
+ * looked up later with {@link Equation.getFunctionElements} (`null`)
  *
  * @see To test examples, append them to the
  * <a href="#drawing-boilerplate">boilerplate</a>