startup.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  Implements a startup module that allows dynamically
 *                loaded components to register themselves, and then
 *                creates MathJax methods for typesetting and converting
 *                math based on the registered components.
 *
 * @author dpvc@mathjax.org (Davide Cervone)
 */

import {MathJax as MJGlobal, MathJaxObject as MJObject,
        MathJaxConfig as MJConfig, combineWithMathJax, combineDefaults} from './global.js';

import {MathDocument} from '../core/MathDocument.js';
import {MmlNode} from '../core/MmlTree/MmlNode.js';
import {Handler} from '../core/Handler.js';
import {InputJax} from '../core/InputJax.js';
import {OutputJax} from '../core/OutputJax.js';
import {CommonOutputJax} from '../output/common/OutputJax.js';
import {DOMAdaptor} from '../core/DOMAdaptor.js';
import {PrioritizedList} from '../util/PrioritizedList.js';
import {OptionList, OPTIONS} from '../util/Options.js';

import {TeX} from '../input/tex.js';


/**
 * Update the configuration structure to include the startup configuration
 */
export interface MathJaxConfig extends MJConfig {
  startup?: {
    input?: string[];        // The names of the input jax to use
    output?: string;         // The name for the output jax to use
    handler?: string;        // The handler to register
    adaptor?: string;        // The name for the DOM adaptor to use
    document?: any;          // The document (or fragment or string) to work in
    elements?: any[];        // The elements to typeset (default is document body)
    typeset?: boolean;       // Perform initial typeset?
    ready?: () => void;      // Function to perform when components are ready
    pageReady?: () => void;  // Function to perform when page is ready
    invalidOption?: 'fatal' | 'warn'; // Do invalid options produce a warning, or throw an error?
    optionError?: (message: string, key: string) => void,  // Function to report invalid options
    [name: string]: any;     // Other configuration blocks
  };
}

/**
 * Generic types for the standard MathJax objects
 */
export type MATHDOCUMENT = MathDocument<any, any, any>;
export type HANDLER = Handler<any, any, any>;
export type DOMADAPTOR = DOMAdaptor<any, any, any>;
export type INPUTJAX = InputJax<any, any, any>;
export type OUTPUTJAX = OutputJax<any, any, any>;
export type COMMONJAX = CommonOutputJax<any, any, any, any, any, any, any>;
export type TEX = TeX<any, any, any>;

/**
 * A function to extend a handler class
 */
export type HandlerExtension = (handler: HANDLER) => HANDLER;

/**
 * Update the MathJax object to inclide the startup information
 */
export interface MathJaxObject extends MJObject {
  config: MathJaxConfig;
  startup: {
    constructors: {[name: string]: any};
    input: INPUTJAX[];
    output: OUTPUTJAX;
    handler: HANDLER;
    adaptor: DOMADAPTOR;
    elements: any[];
    document: MATHDOCUMENT;
    promise: Promise<void>;
    /* tslint:disable:jsdoc-require */
    registerConstructor(name: string, constructor: any): void;
    useHandler(name: string, force?: boolean): void;
    useAdaptor(name: string, force?: boolean): void;
    useOutput(name: string, force?: boolean): void;
    useInput(name: string, force?: boolean): void;
    extendHandler(extend: HandlerExtension): void;
    toMML(node: MmlNode): string;
    defaultReady(): void;
    defaultPageReady(): Promise<void>;
    getComponents(): void;
    makeMethods(): void;
    makeTypesetMethods(): void;
    makeOutputMethods(iname: string, oname: string, input: INPUTJAX): void;
    makeMmlMethods(name: string, input: INPUTJAX): void;
    makeResetMethod(name: string, input: INPUTJAX): void;
    getInputJax(): INPUTJAX[];
    getOutputJax(): OUTPUTJAX;
    getAdaptor(): DOMADAPTOR;
    getHandler(): HANDLER;
    /* tslint:enable */
  };
  [name: string]: any;    // Needed for the methods created by the startup module
}

/*
 * Access to the browser document
 */
declare var global: {document: Document};

/**
 * The implementation of the startup module
 */
export namespace Startup {

  /**
   * The array of handler extensions
   */
  const extensions = new PrioritizedList<HandlerExtension>();

  let visitor: any;  // the visitor for toMML();
  let mathjax: any;  // the mathjax variable from mathjax.js

  /**
   * The constructors (or other data) registered by the loaded packages
   */
  export const constructors: {[name: string]: any} = {};

  /**
   * The array of InputJax instances (created after everything is loaded)
   */
  export let input: INPUTJAX[] = [];

  /**
   * The OutputJax instance (created after everything is loaded)
   */
  export let output: OUTPUTJAX = null;

  /**
   * The Handler instance (created after everything is loaded)
   */
  export let handler: HANDLER = null;

  /**
   * The DOMAdaptor instance (created after everything is loaded)
   */
  export let adaptor: DOMADAPTOR = null;

  /**
   * The elements to process (set when typeset or conversion method is called)
   */
  export let elements: any[] = null;

  /**
   * The MathDocument instance being used (based on the browser DOM or configuration value)
   */
  export let document: MATHDOCUMENT = null;

  /**
   * The function that resolves the first promise defined below
   *   (called in the defaultReady() function when MathJax is finished with
   *    its initial typesetting)
   */
  export let promiseResolve: () => void;
  /**
   * The function that rejects the first promise defined below
   *   (called in the defaultReady() function when MathJax's initial
   *    typesetting fails)
   */
  export let promiseReject: (reason: any) => void;

  /**
   * The promise for the startup process (the initial typesetting).
   * It is resolves or rejected in the ready() function.
   */
  export let promise = new Promise<void>((resolve, reject) => {
    promiseResolve = resolve;
    promiseReject = reject;
  });

  /**
   * A promise that is resolved when the page contents are available
   * for processing.
   */
  export let pagePromise = new Promise<void>((resolve, _reject) => {
    const doc = global.document;
    if (!doc || !doc.readyState || doc.readyState === 'complete' || doc.readyState === 'interactive') {
      resolve();
    } else {
      const listener = () => resolve();
      doc.defaultView.addEventListener('load', listener, true);
      doc.defaultView.addEventListener('DOMContentLoaded', listener, true);
    }
  });

  /**
   * @param {MmlNode} node   The root of the tree to convert to serialized MathML
   * @return {string}        The serialized MathML from the tree
   */
  export function toMML(node: MmlNode): string {
    return visitor.visitTree(node, document);
  }

  /**
   * @param {string} name      The identifier for the constructor
   * @param {any} constructor  The constructor function for the named object
   */
  export function registerConstructor(name: string, constructor: any) {
    constructors[name] = constructor;
  }

  /**
   * @param {string} name      The identifier for the Handler to use
   * @param {boolean} force    True to force the Handler to be used even if one is already registered
   */
  export function useHandler(name: string, force: boolean = false) {
    if (!CONFIG.handler || force) {
      CONFIG.handler = name;
    }
  }

  /**
   * @param {string} name      The identifier for the DOMAdaptor to use
   * @param {boolean} force    True to force the DOMAdaptor to be used even if one is already registered
   */
  export function useAdaptor(name: string, force: boolean = false) {
    if (!CONFIG.adaptor || force) {
      CONFIG.adaptor = name;
    }
  }

  /**
   * @param {string} name      The identifier for the InputJax to use
   * @param {boolean} force    True to force the InputJax to be used even if the configuration already
   *                             included an array of input jax
   */
  export function useInput(name: string, force: boolean = false) {
    if (!inputSpecified || force) {
      CONFIG.input.push(name);
    }
  }

  /**
   * @param {string} name      The identifier for the OutputJax to use
   * @param {boolean} force    True to force the OutputJax to be used even if one is already registered
   */
  export function useOutput(name: string, force: boolean = false) {
    if (!CONFIG.output || force) {
      CONFIG.output = name;
    }
  }

  /**
   * @param {HandlerExtension} extend    A function to extend the handler class
   * @param {number} priority            The priority of the extension
   */
  export function extendHandler(extend: HandlerExtension, priority: number = 10) {
    extensions.add(extend, priority);
  }

  /**
   * The default ready() function called when all the packages have been loaded,
   * which creates the various objects needed by MathJax, creates the methods
   * based on the loaded components, and does the initial typesetting.
   *
   * Setting MathJax.startup.ready in the configuration will
   * override this, but you can call MathJax.startup.defaultReady()
   * within your own ready function if needed, or can use the
   * individual methods below to perform portions of the default
   * startup actions.
   */
  export function defaultReady() {
    getComponents();
    makeMethods();
    pagePromise
      .then(() => CONFIG.pageReady())  // usually the initial typesetting call
      .then(() => promiseResolve())
      .catch((err) => promiseReject(err));
  }

  /**
   * The default pageReady() function called when the page is ready to be processed,
   * which returns the function that performs the initial typesetting, if needed.
   *
   * Setting Mathjax.startup.pageReady in the configuration will override this.
   */
  export function defaultPageReady() {
    return (CONFIG.typeset && MathJax.typesetPromise ?
            MathJax.typesetPromise(CONFIG.elements) as Promise<void> :
            Promise.resolve());
  }

  /**
   * Create the instances of the registered components
   */
  export function getComponents() {
    visitor = new MathJax._.core.MmlTree.SerializedMmlVisitor.SerializedMmlVisitor();
    mathjax = MathJax._.mathjax.mathjax;
    input = getInputJax();
    output = getOutputJax();
    adaptor = getAdaptor();
    if (handler) {
      mathjax.handlers.unregister(handler);
    }
    handler = getHandler();
    if (handler) {
      mathjax.handlers.register(handler);
      document = getDocument();
    }
  }

  /**
   * Make the typeset and conversion methods based on the registered components
   *
   * If there are both input and output jax,
   *   Make Typeset() and TypesetPromise() methods using the given jax,
   *    and TypesetClear() to clear the existing math items
   * For each input jax
   *   Make input2mml() and input2mmlPromise() conversion methods and inputReset() method
   *   If there is a registered output jax
   *     Make input2output() and input2outputPromise conversion methods and outputStylesheet() method
   */
  export function makeMethods() {
    if (input && output) {
      makeTypesetMethods();
    }
    const oname = (output ? output.name.toLowerCase() : '');
    for (const jax of input) {
      const iname = jax.name.toLowerCase();
      makeMmlMethods(iname, jax);
      makeResetMethod(iname, jax);
      if (output) {
        makeOutputMethods(iname, oname, jax);
      }
    }
  }

  /**
   * Create the Typeset(elements?), TypesetPromise(elements?), and TypesetClear() methods.
   *
   * The first two call the document's render() function, the latter
   *   wrapped in handleRetriesFor() and returning the resulting promise.
   *
   * TypeseClear() clears all the MathItems from the document.
   */
  export function makeTypesetMethods() {
    MathJax.typeset = (elements: any[] = null) => {
      document.options.elements = elements;
      document.reset();
      document.render();
    };
    MathJax.typesetPromise = (elements: any[] = null) => {
      document.options.elements = elements;
      document.reset();
      return mathjax.handleRetriesFor(() => {
        document.render();
      });
    };
    MathJax.typesetClear = (elements: any[] = null) => {
      if (elements) {
        document.clearMathItemsWithin(elements);
      } else {
        document.clear();
      }
    };
  }

  /**
   * Make the input2output(math, options?) and input2outputPromise(math, options?) methods,
   *   and outputStylesheet() method, where "input" and "output" are replaced by the
   *   jax names (e.g., tex2chtml() and chtmlStyleSheet()).
   *
   * The first two perform the document's convert() call, with the Promise version wrapped in
   *   handlerRetriesFor() and returning the resulting promise.  The return value is the
   *   DOM object for the converted math.  Use MathJax.startup.adaptor.outerHTML(result)
   *   to get the serialized string version of the output.
   *
   * The outputStylesheet() method returns the styleSheet object for the output.
   * Use MathJax.startup.adaptor.innerHTML(MathJax.outputStylesheet()) to get the serialized
   *   version of the stylesheet.
   * The getMetricsFor(node, display) method returns the metric data for the given node
   *
   * @param {string} iname     The name of the input jax
   * @param {string} oname     The name of the output jax
   * @param {INPUTJAX} input   The input jax instance
   */
  export function makeOutputMethods(iname: string, oname: string, input: INPUTJAX) {
    const name = iname + '2' + oname;
    MathJax[name] =
      (math: string, options: OptionList = {}) => {
        options.format = input.name;
        return document.convert(math, options);
      };
    MathJax[name + 'Promise'] =
      (math: string, options: OptionList = {}) => {
        options.format = input.name;
        return mathjax.handleRetriesFor(() => document.convert(math, options));
      };
    MathJax[oname + 'Stylesheet'] = () => output.styleSheet(document);
    if ('getMetricsFor' in output) {
      MathJax.getMetricsFor = (node: any, display: boolean) => {
        return (output as COMMONJAX).getMetricsFor(node, display);
      };
    }
  }

  /**
   * Make the input2mml(math, options?) and input2mmlPromise(math, options?) methods,
   *   where "input" is replaced by the name of the input jax (e.g., "tex2mml").
   *
   * These convert the math to its serialized MathML representation.
   *   The second wraps the conversion in handleRetriesFor() and
   *   returns the resulting promise.
   *
   * @param {string} name     The name of the input jax
   * @param {INPUTJAX} input  The input jax itself
   */
  export function makeMmlMethods(name: string, input: INPUTJAX) {
    const STATE = MathJax._.core.MathItem.STATE;
    MathJax[name + '2mml'] =
      (math: string, options: OptionList = {}) => {
        options.end = STATE.CONVERT;
        options.format = input.name;
        return toMML(document.convert(math, options));
      };
    MathJax[name + '2mmlPromise'] =
      (math: string, options: OptionList = {}) => {
        options.end = STATE.CONVERT;
        options.format = input.name;
        return mathjax.handleRetriesFor(() => toMML(document.convert(math, options)));
      };
  }

  /**
   * Creates the inputReset() method, where "input" is replaced by the input jax name (e.g., "texReset()).
   *
   * The texReset() method clears the equation numbers and labels
   *
   * @param {string} name     The name of the input jax
   * @param {INPUTJAX} input  The input jax itself
   */
  export function makeResetMethod(name: string, input: INPUTJAX) {
    MathJax[name + 'Reset'] = (...args: any[]) => input.reset(...args);
  }

  /**
   * @return {INPUTJAX[]}  The array of instances of the registered input jax
   */
  export function getInputJax(): INPUTJAX[] {
    const jax = [] as INPUTJAX[];
    for (const name of CONFIG.input) {
      const inputClass = constructors[name];
      if (inputClass) {
        jax.push(new inputClass(MathJax.config[name]));
      } else {
        throw Error('Input Jax "' + name + '" is not defined (has it been loaded?)');
      }
    }
    return jax;
  }

  /**
   * @return {OUTPUTJAX}   The instance of the registered output jax
   */
  export function getOutputJax(): OUTPUTJAX {
    const name = CONFIG.output;
    if (!name) return null;
    const outputClass = constructors[name];
    if (!outputClass) {
      throw Error('Output Jax "' + name + '" is not defined (has it been loaded?)');
    }
    return new outputClass(MathJax.config[name]);
  }

  /**
   * @return {DOMADAPTOR}  The instance of the registered DOMAdator (the registered constructor
   *                         in this case is a function that creates the adaptor, not a class)
   */
  export function getAdaptor(): DOMADAPTOR {
    const name = CONFIG.adaptor;
    if (!name || name === 'none') return null;
    const adaptor = constructors[name];
    if (!adaptor) {
      throw Error('DOMAdaptor "' + name + '" is not defined (has it been loaded?)');
    }
    return adaptor(MathJax.config[name]);
  }

  /**
   * @return {HANDLER}  The instance of the registered Handler, extended by the registered extensions
   */
  export function getHandler(): HANDLER {
    const name = CONFIG.handler;
    if (!name || name === 'none' || !adaptor) return null;
    const handlerClass = constructors[name];
    if (!handlerClass) {
      throw Error('Handler "' + name + '" is not defined (has it been loaded?)');
    }
    let handler = new handlerClass(adaptor, 5);
    for (const extend of extensions) {
      handler = extend.item(handler);
    }
    return handler;
  }

  /**
   * Create the document with the given input and output jax
   *
   * @param {any=} root        The Document to use as the root document (or null to use the configured document)
   * @returns {MathDocument}   The MathDocument with the configured input and output jax
   */
  export function getDocument(root: any = null): MathDocument<any, any, any> {
    return mathjax.document(root || CONFIG.document, {
        ...MathJax.config.options,
      InputJax: input,
      OutputJax: output
    });
  }
}

/**
 * Export the global MathJax object for convenience
 */
export const MathJax = MJGlobal as MathJaxObject;

/*
 * If the startup module hasn't been added to the MathJax variable,
 *   Add the startup configuration and data objects, and
 *   set the method for handling invalid options, if provided.
 */
if (typeof MathJax._.startup === 'undefined') {

  combineDefaults(MathJax.config, 'startup', {
    input: [],
    output: '',
    handler: null,
    adaptor: null,
    document: (typeof document === 'undefined' ? '' : document),
    elements: null,
    typeset: true,
    ready: Startup.defaultReady.bind(Startup),
    pageReady: Startup.defaultPageReady.bind(Startup)
  });
  combineWithMathJax({
    startup: Startup,
    options: {}
  });

  if (MathJax.config.startup.invalidOption) {
    OPTIONS.invalidOption = MathJax.config.startup.invalidOption;
  }
  if (MathJax.config.startup.optionError) {
    OPTIONS.optionError = MathJax.config.startup.optionError;
  }

}

/**
 * Export the startup configuration for convenience
 */
export const CONFIG = MathJax.config.startup;


/*
 * Tells if the user configuration included input jax or not
 */
const inputSpecified = CONFIG.input.length !== 0;