app/node_modules/mathjax-full/ts/a11y/explorer.ts

/*************************************************************
 *
 *  Copyright (c) 2018-2022 The MathJax Consortium
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

/**
 * @fileoverview  Mixin that implements the Explorer
 *
 * @author dpvc@mathjax.org (Davide Cervone)
 */

import {Handler} from '../core/Handler.js';
import {MmlNode} from '../core/MmlTree/MmlNode.js';
import {MathML} from '../input/mathml.js';
import {STATE, newState} from '../core/MathItem.js';
import {EnrichedMathItem, EnrichedMathDocument, EnrichHandler} from './semantic-enrich.js';
import {MathDocumentConstructor} from '../core/MathDocument.js';
import {OptionList, expandable} from '../util/Options.js';
import {SerializedMmlVisitor} from '../core/MmlTree/SerializedMmlVisitor.js';
import {MJContextMenu} from '../ui/menu/MJContextMenu.js';

import {Explorer} from './explorer/Explorer.js';
import * as ke from './explorer/KeyExplorer.js';
import * as me from './explorer/MouseExplorer.js';
import {TreeColorer, FlameColorer} from './explorer/TreeExplorer.js';
import {LiveRegion, ToolTip, HoverRegion} from './explorer/Region.js';

import {Submenu} from 'mj-context-menu/js/item_submenu.js';

import Sre from './sre.js';

/**
 * Generic constructor for Mixins
 */
export type Constructor<T> = new(...args: any[]) => T;

/**
 * Shorthands for types with HTMLElement, Text, and Document instead of generics
 */
export type HANDLER = Handler<HTMLElement, Text, Document>;
export type HTMLDOCUMENT = EnrichedMathDocument<HTMLElement, Text, Document>;
export type HTMLMATHITEM = EnrichedMathItem<HTMLElement, Text, Document>;
export type MATHML = MathML<HTMLElement, Text, Document>;

/*==========================================================================*/

/**
 * Add STATE value for having the Explorer added (after TYPESET and before INSERTED or CONTEXT_MENU)
 */
newState('EXPLORER', 160);

/**
 * The properties added to MathItem for the Explorer
 */
export interface ExplorerMathItem extends HTMLMATHITEM {

  /**
   * @param {HTMLDocument} document  The document where the Explorer is being added
   * @param {boolean} force          True to force the explorer even if enableExplorer is false
   */
  explorable(document: HTMLDOCUMENT, force?: boolean): void;

  /**
   * @param {HTMLDocument} document  The document where the Explorer is being added
   */
  attachExplorers(document: HTMLDOCUMENT): void;
}

/**
 * The mixin for adding the Explorer to MathItems
 *
 * @param {B} BaseMathItem      The MathItem class to be extended
 * @param {Function} toMathML   The function to serialize the internal MathML
 * @returns {ExplorerMathItem}  The Explorer MathItem class
 *
 * @template B  The MathItem class to extend
 */
export function ExplorerMathItemMixin<B extends Constructor<HTMLMATHITEM>>(
  BaseMathItem: B,
  toMathML: (node: MmlNode) => string
): Constructor<ExplorerMathItem> & B {

  return class extends BaseMathItem {

    /**
     * The Explorer objects for this math item
     */
    protected explorers: {[key: string]: Explorer} = {};

    /**
     * The currently attached explorers
     */
    protected attached: string[] = [];

    /**
     * True when a rerendered element should restart these explorers
     */
    protected restart: string[] = [];

    /**
     * True when a rerendered element should regain the focus
     */
    protected refocus: boolean = false;

    /**
     * Save explorer id during rerendering.
     */
    protected savedId: string = null;

    /**
     * Add the explorer to the output for this math item
     *
     * @param {HTMLDocument} document   The MathDocument for the MathItem
     * @param {boolean} force           True to force the explorer even if enableExplorer is false
     */
    public explorable(document: ExplorerMathDocument, force: boolean = false) {
      if (this.state() >= STATE.EXPLORER) return;
      if (!this.isEscaped && (document.options.enableExplorer || force)) {
        const node = this.typesetRoot;
        const mml = toMathML(this.root);
        if (this.savedId) {
          this.typesetRoot.setAttribute('sre-explorer-id', this.savedId);
          this.savedId = null;
        }
        // Init explorers:
        this.explorers = initExplorers(document, node, mml);
        this.attachExplorers(document);
      }
      this.state(STATE.EXPLORER);
    }

    /**
     * Attaches the explorers that are currently meant to be active given
     * the document options. Detaches all others.
     * @param {ExplorerMathDocument} document The current document.
     */
    public attachExplorers(document: ExplorerMathDocument) {
      this.attached = [];
      let keyExplorers = [];
      for (let key of Object.keys(this.explorers)) {
        let explorer = this.explorers[key];
        if (explorer instanceof ke.AbstractKeyExplorer) {
          explorer.AddEvents();
          explorer.stoppable = false;
          keyExplorers.unshift(explorer);
        }
        if (document.options.a11y[key]) {
          explorer.Attach();
          this.attached.push(key);
        } else {
          explorer.Detach();
        }
      }
      // Ensure that the last currently attached key explorer stops propagating
      // key events.
      for (let explorer of keyExplorers) {
        if (explorer.attached) {
          explorer.stoppable = true;
          break;
        }
      }
    }

    /**
     * @override
     */
    public rerender(document: ExplorerMathDocument, start: number = STATE.RERENDER) {
      this.savedId = this.typesetRoot.getAttribute('sre-explorer-id');
      this.refocus = (window.document.activeElement === this.typesetRoot);
      for (let key of this.attached) {
        let explorer = this.explorers[key];
        if (explorer.active) {
          this.restart.push(key);
          explorer.Stop();
        }
      }
      super.rerender(document, start);
    }

    /**
     * @override
     */
    public updateDocument(document: ExplorerMathDocument) {
      super.updateDocument(document);
      this.refocus && this.typesetRoot.focus();
      this.restart.forEach(x => this.explorers[x].Start());
      this.restart = [];
      this.refocus = false;
    }

  };

}

/**
 * The functions added to MathDocument for the Explorer
 */
export interface ExplorerMathDocument extends HTMLDOCUMENT {

  /**
   * The objects needed for the explorer
   */
  explorerRegions: ExplorerRegions;

  /**
   * Add the Explorer to the MathItems in the MathDocument
   *
   * @returns {MathDocument}   The MathDocument (so calls can be chained)
   */
  explorable(): HTMLDOCUMENT;

}

/**
 * The mixin for adding the Explorer to MathDocuments
 *
 * @param {B} BaseDocument      The MathDocument class to be extended
 * @returns {ExplorerMathDocument}  The extended MathDocument class
 */
export function ExplorerMathDocumentMixin<B extends MathDocumentConstructor<HTMLDOCUMENT>>(
  BaseDocument: B
): MathDocumentConstructor<ExplorerMathDocument> & B {

  return class extends BaseDocument {

    /**
     * @override
     */
    public static OPTIONS: OptionList = {
      ...BaseDocument.OPTIONS,
      enableExplorer: true,
      renderActions: expandable({
        ...BaseDocument.OPTIONS.renderActions,
        explorable: [STATE.EXPLORER]
      }),
      sre: expandable({
        ...BaseDocument.OPTIONS.sre,
        speech: 'shallow',                 // overrides option in EnrichedMathDocument
      }),
      a11y: {
        align: 'top',                      // placement of magnified expression
        backgroundColor: 'Blue',           // color for background of selected sub-expression
        backgroundOpacity: 20,             // opacity for background of selected sub-expression
        braille: false,                    // switch on Braille output
        flame: false,                      // color collapsible sub-expressions
        foregroundColor: 'Black',          // color to use for text of selected sub-expression
        foregroundOpacity: 100,            // opacity for text of selected sub-expression
        highlight: 'None',                 // type of highlighting for collapsible sub-expressions
        hover: false,                      // show collapsible sub-expression on mouse hovering
        infoPrefix: false,                 // show speech prefixes on mouse hovering
        infoRole: false,                   // show semantic role on mouse hovering
        infoType: false,                   // show semantic type on mouse hovering
        keyMagnifier: false,               // switch on magnification via key exploration
        magnification: 'None',             // type of magnification
        magnify: '400%',                   // percentage of magnification of zoomed expressions
        mouseMagnifier: false,             // switch on magnification via mouse hovering
        speech: true,                      // switch on speech output
        subtitles: true,                   // show speech as a subtitle
        treeColoring: false,               // tree color expression
        viewBraille: false                 // display Braille output as subtitles
      }
    };

    /**
     * The objects needed for the explorer
     */
    public explorerRegions: ExplorerRegions;

    /**
     * Extend the MathItem class used for this MathDocument
     *   and create the visitor and explorer objects needed for the explorer
     *
     * @override
     * @constructor
     */
    constructor(...args: any[]) {
      super(...args);
      const ProcessBits = (this.constructor as typeof BaseDocument).ProcessBits;
      if (!ProcessBits.has('explorer')) {
        ProcessBits.allocate('explorer');
      }
      const visitor = new SerializedMmlVisitor(this.mmlFactory);
      const toMathML = ((node: MmlNode) => visitor.visitTree(node));
      this.options.MathItem = ExplorerMathItemMixin(this.options.MathItem, toMathML);
      // TODO: set backward compatibility options here.
      this.explorerRegions = initExplorerRegions(this);
    }

    /**
     * Add the Explorer to the MathItems in this MathDocument
     *
     * @return {ExplorerMathDocument}   The MathDocument (so calls can be chained)
     */
    public explorable(): ExplorerMathDocument {
      if (!this.processed.isSet('explorer')) {
        if (this.options.enableExplorer) {
          for (const math of this.math) {
            (math as ExplorerMathItem).explorable(this);
          }
        }
        this.processed.set('explorer');
      }
      return this;
    }

    /**
     * @override
     */
    public state(state: number, restore: boolean = false) {
      super.state(state, restore);
      if (state < STATE.EXPLORER) {
        this.processed.clear('explorer');
      }
      return this;
    }

  };

}


/*==========================================================================*/

/**
 * Add Explorer functions to a Handler instance
 *
 * @param {Handler} handler   The Handler instance to enhance
 * @param {MathML} MmlJax     A MathML input jax to be used for the semantic enrichment
 * @returns {Handler}         The handler that was modified (for purposes of chainging extensions)
 */
export function ExplorerHandler(handler: HANDLER, MmlJax: MATHML = null): HANDLER {
  if (!handler.documentClass.prototype.enrich && MmlJax) {
    handler = EnrichHandler(handler, MmlJax);
  }
  handler.documentClass = ExplorerMathDocumentMixin(handler.documentClass as any);
  return handler;
}


/*==========================================================================*/

/**
 * The regions objects needed for the explorers.
 */
export type ExplorerRegions = {
  speechRegion?: LiveRegion,
  brailleRegion?: LiveRegion,
  magnifier?: HoverRegion,
  tooltip1?: ToolTip,
  tooltip2?: ToolTip,
  tooltip3?: ToolTip
};


/**
 * Initializes the regions needed for a document.
 * @param {ExplorerMathDocument} document The current document.
 */
function initExplorerRegions(document: ExplorerMathDocument) {
  return {
    speechRegion: new LiveRegion(document),
    brailleRegion: new LiveRegion(document),
    magnifier: new HoverRegion(document),
    tooltip1: new ToolTip(document),
    tooltip2: new ToolTip(document),
    tooltip3: new ToolTip(document)
  };
}



/**
 * Type of explorer initialization methods.
 * @type {(ExplorerMathDocument, HTMLElement, any[]): Explorer}
 */
type ExplorerInit = (doc: ExplorerMathDocument,
                     node: HTMLElement, ...rest: any[]) => Explorer;

/**
 *  Generation methods for all MathJax explorers available via option settings.
 */
let allExplorers: {[options: string]: ExplorerInit} = {
  speech: (doc: ExplorerMathDocument, node: HTMLElement, ...rest: any[]) => {
    let explorer = ke.SpeechExplorer.create(
      doc, doc.explorerRegions.speechRegion, node, ...rest) as ke.SpeechExplorer;
    explorer.speechGenerator.setOptions({
      locale: doc.options.sre.locale, domain: doc.options.sre.domain,
      style: doc.options.sre.style, modality: 'speech'});
    // This weeds out the case of providing a non-existent locale option.
    let locale = explorer.speechGenerator.getOptions().locale;
    if (locale !== Sre.engineSetup().locale) {
      doc.options.sre.locale = Sre.engineSetup().locale;
      explorer.speechGenerator.setOptions({locale: doc.options.sre.locale});
    }
    explorer.showRegion = 'subtitles';
    return explorer;
  },
  braille: (doc: ExplorerMathDocument, node: HTMLElement, ...rest: any[]) => {
    let explorer = ke.SpeechExplorer.create(
      doc, doc.explorerRegions.brailleRegion, node, ...rest) as ke.SpeechExplorer;
    explorer.speechGenerator.setOptions({locale: 'nemeth', domain: 'default',
                                         style: 'default', modality: 'braille'});
    explorer.showRegion = 'viewBraille';
    return explorer;
  },
  keyMagnifier: (doc: ExplorerMathDocument, node: HTMLElement, ...rest: any[]) =>
    ke.Magnifier.create(doc, doc.explorerRegions.magnifier, node, ...rest),
  mouseMagnifier: (doc: ExplorerMathDocument, node: HTMLElement, ..._rest: any[]) =>
    me.ContentHoverer.create(doc, doc.explorerRegions.magnifier, node,
                             (x: HTMLElement) => x.hasAttribute('data-semantic-type'),
                             (x: HTMLElement) => x),
  hover: (doc: ExplorerMathDocument, node: HTMLElement, ..._rest: any[]) =>
    me.FlameHoverer.create(doc, null, node),
  infoType: (doc: ExplorerMathDocument, node: HTMLElement, ..._rest: any[]) =>
    me.ValueHoverer.create(doc, doc.explorerRegions.tooltip1, node,
                           (x: HTMLElement) => x.hasAttribute('data-semantic-type'),
                           (x: HTMLElement) => x.getAttribute('data-semantic-type')),
  infoRole: (doc: ExplorerMathDocument, node: HTMLElement, ..._rest: any[]) =>
    me.ValueHoverer.create(doc, doc.explorerRegions.tooltip2, node,
                           (x: HTMLElement) => x.hasAttribute('data-semantic-role'),
                           (x: HTMLElement) => x.getAttribute('data-semantic-role')),
  infoPrefix: (doc: ExplorerMathDocument, node: HTMLElement, ..._rest: any[]) =>
    me.ValueHoverer.create(doc, doc.explorerRegions.tooltip3, node,
                           (x: HTMLElement) => x.hasAttribute('data-semantic-prefix'),
                           (x: HTMLElement) => x.getAttribute('data-semantic-prefix')),
  flame: (doc: ExplorerMathDocument, node: HTMLElement, ..._rest: any[]) =>
    FlameColorer.create(doc, null, node),
  treeColoring: (doc: ExplorerMathDocument, node: HTMLElement, ...rest: any[]) =>
    TreeColorer.create(doc, null, node, ...rest)
};


/**
 * Initialises explorers for a document.
 * @param {ExplorerMathDocument} document The target document.
 * @param {HTMLElement} node The node explorers will be attached to.
 * @param {string} mml The corresponding Mathml node as a string.
 * @return {Explorer[]} A list of initialised explorers.
 */
function initExplorers(document: ExplorerMathDocument, node: HTMLElement, mml: string): {[key: string]: Explorer} {
  let explorers: {[key: string]: Explorer} = {};
  for (let key of Object.keys(allExplorers)) {
    explorers[key] = allExplorers[key](document, node, mml);
  }
  return explorers;
}


/* Context Menu Interactions */

/**
 * Sets a list of a11y options for a given document.
 * @param {HTMLDOCUMENT} document The current document.
 * @param {{[key: string]: any}} options Association list for a11y option value pairs.
 */
export function setA11yOptions(document: HTMLDOCUMENT, options: {[key: string]: any}) {
  let sreOptions = Sre.engineSetup() as {[name: string]: string};
  for (let key in options) {
    if (document.options.a11y[key] !== undefined) {
      setA11yOption(document, key, options[key]);
      if (key === 'locale') {
        document.options.sre[key] = options[key];
      }
      continue;
    }
    if (sreOptions[key] !== undefined) {
      document.options.sre[key] = options[key];
    }
  }
  // Reinit explorers
  for (let item of document.math) {
    (item as ExplorerMathItem).attachExplorers(document as ExplorerMathDocument);
  }
}


/**
 * Sets a single a11y option for a menu name.
 * @param {HTMLDOCUMENT} document The current document.
 * @param {string} option The option name in the menu.
 * @param {string|boolean} value The new value.
 */
export function setA11yOption(document: HTMLDOCUMENT, option: string, value: string | boolean) {
  switch (option) {
  case 'magnification':
    switch (value) {
    case 'None':
      document.options.a11y.magnification = value;
      document.options.a11y.keyMagnifier = false;
      document.options.a11y.mouseMagnifier = false;
      break;
    case 'Keyboard':
      document.options.a11y.magnification = value;
      document.options.a11y.keyMagnifier = true;
      document.options.a11y.mouseMagnifier = false;
      break;
    case 'Mouse':
      document.options.a11y.magnification = value;
      document.options.a11y.keyMagnifier = false;
      document.options.a11y.mouseMagnifier = true;
      break;
    }
    break;
  case 'highlight':
    switch (value) {
    case 'None':
      document.options.a11y.highlight = value;
      document.options.a11y.hover = false;
      document.options.a11y.flame = false;
      break;
    case 'Hover':
      document.options.a11y.highlight = value;
      document.options.a11y.hover = true;
      document.options.a11y.flame = false;
      break;
    case 'Flame':
      document.options.a11y.highlight = value;
      document.options.a11y.hover = false;
      document.options.a11y.flame = true;
      break;
    }
    break;
  default:
    document.options.a11y[option] = value;
  }
}

/**
 * Values for the ClearSpeak preference variables.
 */
let csPrefsSetting: {[pref: string]: string} = {};

/**
 * Generator of all variables for the Clearspeak Preference settings.
 * @param {MJContextMenu} menu The current context menu.
 * @param {string[]} prefs The preferences.
 */
let csPrefsVariables = function(menu: MJContextMenu, prefs: string[]) {
  let srVariable = menu.pool.lookup('speechRules');
  for (let pref of prefs) {
    if (csPrefsSetting[pref]) continue;
    menu.factory.get('variable')(menu.factory, {
      name: 'csprf_' + pref,
      setter: (value: string) => {
        csPrefsSetting[pref] = value;
          srVariable.setValue(
          'clearspeak-' +
              Sre.clearspeakPreferences.addPreference(
                Sre.clearspeakStyle(), pref, value)
        );
      },
      getter: () => { return csPrefsSetting[pref] || 'Auto'; }
    }, menu.pool);
  }
};

/**
 * Generate the selection box for the Clearspeak Preferences.
 * @param {MJContextMenu} menu The current context menu.
 * @param {string} locale The current locale.
 */
let csSelectionBox = function(menu: MJContextMenu, locale: string) {
  let prefs = Sre.clearspeakPreferences.getLocalePreferences();
  let props = prefs[locale];
  if (!props) {
    let csEntry = menu.findID('Accessibility', 'Speech', 'Clearspeak');
    if (csEntry) {
      csEntry.disable();
    }
    return null;
  }
  csPrefsVariables(menu, Object.keys(props));
  let items = [];
  for (const prop of Object.getOwnPropertyNames(props)) {
    items.push({
      'title': prop,
      'values': props[prop].map(x => x.replace(RegExp('^' + prop + '_'), '')),
      'variable': 'csprf_' + prop
    });
  }
  let sb = menu.factory.get('selectionBox')(menu.factory, {
    'title': 'Clearspeak Preferences',
    'signature': '',
    'order': 'alphabetic',
    'grid': 'square',
    'selections': items
  }, menu);
  return {'type': 'command',
          'id': 'ClearspeakPreferences',
          'content': 'Select Preferences',
          'action': () => sb.post(0, 0)};
};

/**
 * Creates dynamic clearspeak menu.
 * @param {MJContextMenu} menu The context menu.
 * @param {Submenu} sub The submenu to attach.
 */
let csMenu = function(menu: MJContextMenu, sub: Submenu) {
  let locale = menu.pool.lookup('locale').getValue() as string;
  const box = csSelectionBox(menu, locale);
  let items: Object[] = [];
  try {
    items = Sre.clearspeakPreferences.smartPreferences(
      menu.mathItem, locale);
  } catch (e) {
    console.log(e);
  }
  if (box) {
    items.splice(2, 0, box);
  }
  return menu.factory.get('subMenu')(menu.factory, {
    items: items,
    id: 'Clearspeak'
  }, sub);
};

MJContextMenu.DynamicSubmenus.set('Clearspeak', csMenu);

/**
 * Creates dynamic locale menu.
 * @param {MJContextMenu} menu The context menu.
 * @param {Submenu} sub The submenu to attach.
 */
let language = function(menu: MJContextMenu, sub: Submenu) {
  let radios: {type: string, id: string,
               content: string, variable: string}[] = [];
  for (let lang of Sre.locales.keys()) {
    if (lang === 'nemeth') continue;
    radios.push({type: 'radio', id: lang,
                 content: Sre.locales.get(lang) || lang, variable: 'locale'});
  }
  radios.sort((x, y) => x.content.localeCompare(y.content, 'en'));
  return menu.factory.get('subMenu')(menu.factory, {
    items: radios, id: 'Language'}, sub);
};

MJContextMenu.DynamicSubmenus.set('A11yLanguage', language);