Merge pull request #1113 from mathjax/speech-promise

make typesetPromise() wait for speech to be attached, add synchronous option, and copy ARIA labels to internal MathML

Author: dpvc

ts/a11y/semantic-enrich.ts

@@ -151,7 +151,7 @@ export function EnrichedMathItemMixin<N, T, D, B extends Constructor<AbstractMat
     public generatorPool = new GeneratorPool<N, T, D>();
 
     /**
-     *  The MathML adaptor.
+     *  The MathML serializer
      */
     public toMathML = toMathML;
 
@@ -285,9 +285,11 @@ export function EnrichedMathItemMixin<N, T, D, B extends Constructor<AbstractMat
       const node = this.typesetRoot;
       if (speech && options.enableSpeech) {
         adaptor.setAttribute(node, 'aria-label', speech as string);
+        this.root.attributes.set('aria-label', speech);
       }
       if (braille && options.enableBraille) {
         adaptor.setAttribute(node, 'aria-braillelabel', braille as string);
+        this.root.attributes.set('aria-braillelabel', braille);
       }
       for (const child of adaptor.childNodes(node) as N[]) {
         adaptor.setAttribute(child, 'aria-hidden', 'true');
@@ -379,6 +381,7 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
         attachSpeech: [STATE.ATTACHSPEECH]
       }),
       speechTiming: {
+        asynchronous: true,                // true to allow screen updates while adding speech, false to not
         initial: 100,                      // initial delay until starting to add speech
         threshold: 250,                    // time (in milliseconds) to process speech before letting screen update
         intermediate: 10                   // delay after processing speech reaches the threshold
@@ -406,6 +409,11 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
      */
     protected speechTimeout: number = 0;
 
+    /**
+     * The function to resolve when the speech loop finishes
+     */
+    protected attachSpeechDone: () => void;
+
     /**
      * Enrich the MathItem class used for this MathDocument, and create the
      *   temporary MathItem used for enrchment
@@ -435,21 +443,46 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
     public attachSpeech() {
       if (!this.processed.isSet('attach-speech')) {
         if (this.options.enableSpeech || this.options.enableBraille) {
-          if (this.speechTimeout) {
-            clearTimeout(this.speechTimeout);
-            this.speechTimeout = 0;
+          if (this.options.speechTiming.asynchronous) {
+            this.attachSpeechAsync();
+          } else {
+            this.attachSpeechSync();
           }
-          this.awaitingSpeech = Array.from(this.math);
-          this.speechTimeout = setTimeout(
-            () => this.attachSpeechLoop(),
-            this.options.speechTiming.initial
-          );
         }
         this.processed.set('attach-speech');
       }
       return this;
     }
 
+    /**
+     * Add speech synchronously (e.g., for use in node applications on the server)
+     */
+    protected attachSpeechSync() {
+      for (const math of this.math) {
+        (math as EnrichedMathItem<N, T, D>).attachSpeech(this);
+      }
+    }
+
+    /**
+     * Add speech in small chunks, allowing screen updates in between
+     * (e.g., helpful with lazy typesetting)
+     */
+    protected attachSpeechAsync() {
+      if (this.speechTimeout) {
+        clearTimeout(this.speechTimeout);
+        this.speechTimeout = 0;
+        this.attachSpeechDone();
+      }
+      this.awaitingSpeech = Array.from(this.math);
+      this.renderPromises.push(new Promise<void>((ok, _fail) => {
+        this.attachSpeechDone = ok;
+      }));
+      this.speechTimeout = setTimeout(
+        () => this.attachSpeechLoop(),
+        this.options.speechTiming.initial
+      );
+    }
+
     /**
      * Loops through math items to attach speech until the timeout threshold is reached.
      */
@@ -462,8 +495,12 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
         const math = awaitingSpeech.shift();
         (math as EnrichedMathItem<N, T, D>).attachSpeech(this);
       } while (awaitingSpeech.length && new Date().getTime() < timeEnd);
-      this.speechTimeout = awaitingSpeech.length ?
-        setTimeout(() => this.attachSpeechLoop(), timing.intermediate) : 0;
+      if (awaitingSpeech.length) {
+        this.speechTimeout = setTimeout(() => this.attachSpeechLoop(), timing.intermediate);
+      } else {
+        this.speechTimeout = 0;
+        this.attachSpeechDone();
+      }
     }
 
     /**

ts/components/startup.ts

@@ -301,7 +301,8 @@ export namespace Startup {
 
   /**
    * The default pageReady() function called when the page is ready to be processed,
-   * which returns the function that performs the initial typesetting, if needed.
+   * which returns a promise that does any initial font loading, plus the initial
+   * typesetting, if needed.
    *
    * Setting Mathjax.startup.pageReady in the configuration will override this.
    */
@@ -310,7 +311,8 @@ export namespace Startup {
             (output as COMMONJAX).font.loadDynamicFiles() : Promise.resolve())
       .then(CONFIG.typeset && MathJax.typesetPromise ?
             () => typesetPromise(CONFIG.elements) :
-            Promise.resolve());
+            Promise.resolve())
+      .then(() => promiseResolve());
   }
 
   /**
@@ -321,6 +323,9 @@ export namespace Startup {
     document.reset();
     return mathjax.handleRetriesFor(() => {
       document.render();
+      const promise = Promise.all(document.renderPromises);
+      document.renderPromises = [];
+      return promise;
     });
   }
 

ts/core/MathDocument.ts

@@ -30,7 +30,6 @@ import {MmlNode, TextNode} from './MmlTree/MmlNode.js';
 import {MmlFactory} from '../core/MmlTree/MmlFactory.js';
 import {DOMAdaptor} from '../core/DOMAdaptor.js';
 import {BitField, BitFieldClass} from '../util/BitField.js';
-
 import {PrioritizedList} from '../util/PrioritizedList.js';
 
 /*****************************************************************/
@@ -319,6 +318,11 @@ export interface MathDocument<N, T, D> {
    */
   renderActions: RenderList<N, T, D>;
 
+  /**
+   * The promises that indicate when rendering is fully complete
+   */
+  renderPromises: Promise<void>[];
+
   /**
    * This object tracks what operations have been performed, so that (when
    *  asynchronous operations are used), the ones that have already been
@@ -602,6 +606,11 @@ export abstract class AbstractMathDocument<N, T, D> implements MathDocument<N, T
    */
   public renderActions: RenderList<N, T, D>;
 
+  /**
+   * The render action promise list
+   */
+  public renderPromises: Promise<void>[];
+
   /**
    * The bit-field used to tell what steps have been taken on the document (for retries)
    */
@@ -640,6 +649,7 @@ export abstract class AbstractMathDocument<N, T, D> implements MathDocument<N, T
     this.options = userOptions(defaultOptions({}, CLASS.OPTIONS), options);
     this.math = new (this.options['MathList'] || DefaultMathList)();
     this.renderActions = RenderList.create<N, T, D>(this.options['renderActions']);
+    this.renderPromises = [];
     this.processed = new AbstractMathDocument.ProcessBits();
     this.outputJax = this.options['OutputJax'] || new DefaultOutputJax<N, T, D>();
     let inputJax = this.options['InputJax'] || [new DefaultInputJax<N, T, D>()];
@@ -694,6 +704,7 @@ export abstract class AbstractMathDocument<N, T, D> implements MathDocument<N, T
    * @override
    */
   public render() {
+    this.renderPromises = [];
     this.renderActions.renderDoc(this);
     return this;
   }