figureone 1.4.1 → 1.5.0

package/index.js

@@ -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
@@ -21442,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);
     }
   }, {
@@ -21634,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);
@@ -21651,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
+          });
+        }
       }
     }
   }, {
@@ -21729,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');
@@ -21813,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();
@@ -21840,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({
@@ -21855,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() {
@@ -21871,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);
       }
     }
   }, {
@@ -21986,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;
       }
@@ -22542,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();
@@ -22587,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",
@@ -80795,8 +80920,8 @@ var tools = {
  */
 
 var Fig = {
-  version: "1.4.1",
-  gitHash: "2fa15b061",
+  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.1",
+  "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
@@ -979,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;
 }