Merge pull request #1107 from mathjax/fix/lazy-performance

Improve speech performance, especially for lazy typesetting

Author: zorkow

ts/a11y/explorer/KeyExplorer.ts

@@ -29,7 +29,7 @@ import type { ExplorerMathItem } from '../explorer.js';
 import {Explorer, AbstractExplorer} from './Explorer.js';
 import {ExplorerPool} from './ExplorerPool.js';
 import {MmlNode} from '../../core/MmlTree/MmlNode.js';
-import { honk, InPlace, Timing } from '../speech/SpeechUtil.js';
+import { honk, InPlace } from '../speech/SpeechUtil.js';
 import {Sre} from '../sre.js';
 
 
@@ -447,10 +447,9 @@ export class SpeechExplorer extends AbstractExplorer<string> implements KeyExplo
    * @override
    */
   public Start() {
-    // In case the speech is not attached yet, we restart the explorer after a
-    // fashion.
+    // In case the speech is not attached yet, we generate it
     if (this.item.state() < STATE.ATTACHSPEECH) {
-      setTimeout(() => this.Start(), Timing.INITIAL);
+      this.item.attachSpeech(this.document);
     };
     if (!this.attached) return;
     if (this.node.hasAttribute('tabindex')) {
@@ -464,7 +463,7 @@ export class SpeechExplorer extends AbstractExplorer<string> implements KeyExplo
       this.current = this.node.querySelector(`[data-semantic-id="${this.restarted}"]`)
       if (!this.current) {
         const dummies = Array.from(
-          this.node.querySelectorAll(`[data-semantic-type="dummy"]`))
+          this.node.querySelectorAll('[data-semantic-type="dummy"]'))
           .map(x => x.getAttribute('data-semantic-id'))
         let internal = this.generators.element.querySelector(
           `[data-semantic-id="${this.restarted}"]`);

ts/a11y/semantic-enrich.ts

@@ -30,7 +30,7 @@ import {MathML} from '../input/mathml.js';
 import {SerializedMmlVisitor} from '../core/MmlTree/SerializedMmlVisitor.js';
 import {OptionList, expandable} from '../util/Options.js';
 import {Sre} from './sre.js';
-import { buildSpeech, Timing } from './speech/SpeechUtil.js';
+import { buildSpeech } from './speech/SpeechUtil.js';
 import { GeneratorPool } from './speech/GeneratorPool.js';
 
 /*==========================================================================*/
@@ -45,12 +45,12 @@ export type Constructor<T> = new(...args: any[]) => T;
 /**
  * Add STATE value for being enriched (after COMPILED and before TYPESET)
  */
-newState('ENRICHED', 30);
+newState('ENRICHED', STATE.COMPILED + 10);
 
 /**
- * Add STATE value for adding speech (after TYPESET)
+ * Add STATE value for adding speech (after INSERTED)
  */
-newState('ATTACHSPEECH', 205);
+newState('ATTACHSPEECH', STATE.INSERTED + 10);
 
 /*==========================================================================*/
 
@@ -242,7 +242,7 @@ export function EnrichedMathItemMixin<N, T, D, B extends Constructor<AbstractMat
      *
      * @return {[string, string]} Pair comprising speech and braille.
      */
-    private existingSpeech(): [string, string] {
+    protected existingSpeech(): [string, string] {
       const attributes = this.root.attributes;
       let speech = attributes.get('aria-label') as string;
       if (!speech) {
@@ -378,6 +378,11 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
         enrich:       [STATE.ENRICHED],
         attachSpeech: [STATE.ATTACHSPEECH]
       }),
+      speechTiming: {
+        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
+      },
       sre: expandable({
         speech: 'none',                    // by default no speech is included
         locale: 'en',                      // switch the locale
@@ -391,6 +396,16 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
       })
     };
 
+    /**
+     * The list of MathItems that need to be processed for speech
+     */
+    protected awaitingSpeech: MathItem<N, T, D>[];
+
+    /**
+     * The identifier from setTimeout for the next speech loop
+     */
+    protected speechTimeout: number = 0;
+
     /**
      * Enrich the MathItem class used for this MathDocument, and create the
      *   temporary MathItem used for enrchment
@@ -414,47 +429,41 @@ export function EnrichedMathDocumentMixin<N, T, D, B extends MathDocumentConstru
         );
     }
 
-    private DELAY: number = Timing.INITIAL;
-    private awaitingSpeech: MathItem<N, T, D>[] = [];
-
     /**
      * Attach speech from a MathItem to a node
      */
     public attachSpeech() {
       if (!this.processed.isSet('attach-speech')) {
         if (this.options.enableSpeech || this.options.enableBraille) {
+          if (this.speechTimeout) {
+            clearTimeout(this.speechTimeout);
+            this.speechTimeout = 0;
+          }
           this.awaitingSpeech = Array.from(this.math);
-          this.attachSpeechStart();
+          this.speechTimeout = setTimeout(
+            () => this.attachSpeechLoop(),
+            this.options.speechTiming.initial
+          );
         }
-      }
-      return this;
-    }
-
-    /**
-     * Start attaching speech to nodes.
-     */
-    private attachSpeechStart() {
-      if (this.awaitingSpeech.length) {
-        setTimeout(
-          () => this.attachSpeechLoop(),
-          this.DELAY);
-      } else {
         this.processed.set('attach-speech');
       }
+      return this;
     }
 
     /**
      * Loops through math items to attach speech until the timeout threshold is reached.
      */
-    private attachSpeechLoop() {
+    protected attachSpeechLoop() {
+      const timing = this.options.speechTiming;
+      const awaitingSpeech = this.awaitingSpeech;
       const timeStart = new Date().getTime();
-      const timeEnd = timeStart + Timing.THRESHOLD;
-      while (this.awaitingSpeech.length && new Date().getTime() < timeEnd) {
-        const math = this.awaitingSpeech.shift();
+      const timeEnd = timeStart + timing.threshold;
+      do {
+        const math = awaitingSpeech.shift();
         (math as EnrichedMathItem<N, T, D>).attachSpeech(this);
-      }
-      this.DELAY = Timing.INTERMEDIATE;
-      this.attachSpeechStart();
+      } while (awaitingSpeech.length && new Date().getTime() < timeEnd);
+      this.speechTimeout = awaitingSpeech.length ?
+        setTimeout(() => this.attachSpeechLoop(), timing.intermediate) : 0;
     }
 
     /**

ts/a11y/speech/GeneratorPool.ts

@@ -161,9 +161,9 @@ export class GeneratorPool<N, T, D> {
   public computeSpeech(node: N, mml: string): [string, string] {
     this.element = Sre.parseDOM(mml);
     const xml = this.prepareXml(node);
-    const speech = this.speechGenerator.getSpeech(xml, this.element);
-    const braille = this.brailleGenerator.getSpeech(xml, this.element);
-    if (this.options.enableSpeech || this.options.enableBraille) {
+    const speech = this.options.enableSpeech ? this.speechGenerator.getSpeech(xml, this.element) : '';
+    const braille = this.options.enableBraille ? this.brailleGenerator.getSpeech(xml, this.element) : '';
+    if (speech || braille) {
       this.setAria(node, xml, this.options.sre.locale);
     }
     return [speech, braille];

ts/a11y/speech/SpeechUtil.ts

@@ -191,7 +191,7 @@ export function buildLabel(
  * @param {string} speech The speech string.
  * @param {string=} locale An optional locale.
  * @param {string=} rate The base speech rate.
- * @return {[string, SsmlElement[]]} The speech with the ssml annotation structure 
+ * @return {[string, SsmlElement[]]} The speech with the ssml annotation structure
  */
 export function buildSpeech(speech: string, locale: string = 'en',
                             rate: string = '100'): [string, SsmlElement[]] {
@@ -223,12 +223,3 @@ export enum InPlace {
   SUMMARY
 }
 
-/**
- * Some timing constants for asynchronous speech computation.
- */
-export const Timing = {
-  THRESHOLD: 250,
-  INITIAL: 100,
-  INTERMEDIATE: 10
-};
-

ts/ui/lazy/LazyHandler.ts

@@ -23,9 +23,9 @@
 
 import {MathDocumentConstructor, ContainerList} from '../../core/MathDocument.js';
 import {MathItem, STATE, newState} from '../../core/MathItem.js';
-import {HTMLMathItem} from '../../handlers/html/HTMLMathItem.js';
 import {HTMLDocument} from '../../handlers/html/HTMLDocument.js';
 import {HTMLHandler} from '../../handlers/html/HTMLHandler.js';
+import {EnrichedMathItem} from '../../a11y/semantic-enrich.js';
 import {handleRetriesFor} from '../../util/Retries.js';
 import {OptionList} from '../../util/Options.js';
 
@@ -151,7 +151,7 @@ export interface LazyMathItem<N, T, D> extends MathItem<N, T, D> {
  * @template D  The Document class
  * @template B  The MathItem class to extend
  */
-export function LazyMathItemMixin<N, T, D, B extends Constructor<HTMLMathItem<N, T, D>>>(
+export function LazyMathItemMixin<N, T, D, B extends Constructor<EnrichedMathItem<N, T, D>>>(
   BaseMathItem: B
 ): Constructor<LazyMathItem<N, T, D>> & B {
 
@@ -260,6 +260,19 @@ export function LazyMathItemMixin<N, T, D, B extends Constructor<HTMLMathItem<N,
       }
     }
 
+    /**
+     * Only add speech when we are actually typesetting
+     *
+     * @override
+     */
+    public attachSpeech = (document: LazyMathDocument<N, T, D>) => {
+      if (this.state() >= STATE.ATTACHSPEECH) return;
+      if (!this.lazyTypeset) {
+        super.attachSpeech?.(document);
+      }
+      this.state(STATE.ATTACHSPEECH);
+    }
+
   };
 
 }
@@ -325,8 +338,14 @@ B extends MathDocumentConstructor<HTMLDocument<N, T, D>>>(
      */
     public static OPTIONS: OptionList = {
       ...BaseDocument.OPTIONS,
-      lazyMargin: '200px',
+      lazyMargin: '500px',
       lazyAlwaysTypeset: null,
+      speechTiming: {
+        ...(BaseDocument.OPTIONS.speechTiming || {}),
+        initial: 150,
+        threshold: 100,
+        intermediate: 10
+      },
       renderActions: {
         ...BaseDocument.OPTIONS.renderActions,
         lazyAlways: [STATE.LAZYALWAYS, 'lazyAlways', '', false]
@@ -390,7 +409,7 @@ B extends MathDocumentConstructor<HTMLDocument<N, T, D>>>(
       //  Use the LazyMathItem for math items
       //
       this.options.MathItem =
-        LazyMathItemMixin<N, T, D, Constructor<HTMLMathItem<N, T, D>>>(this.options.MathItem);
+        LazyMathItemMixin<N, T, D, Constructor<EnrichedMathItem<N, T, D>>>(this.options.MathItem);
       //
       //  Allocate a process bit for lazyAlways
       //