katex 0.10.1 → 0.12.0

package/contrib/render-a11y-string/render-a11y-string.js

@@ -0,0 +1,712 @@
+// @flow
+/**
+ * renderA11yString returns a readable string.
+ *
+ * In some cases the string will have the proper semantic math
+ * meaning,:
+ *   renderA11yString("\\frac{1}{2}"")
+ *   -> "start fraction, 1, divided by, 2, end fraction"
+ *
+ * However, other cases do not:
+ *   renderA11yString("f(x) = x^2")
+ *   -> "f, left parenthesis, x, right parenthesis, equals, x, squared"
+ *
+ * The commas in the string aim to increase ease of understanding
+ * when read by a screenreader.
+ */
+
+// NOTE: since we're importing types here these files won't actually be
+// included in the build.
+import type {Atom} from "../../src/symbols";
+import type {AnyParseNode} from "../../src/parseNode";
+import type {SettingsOptions} from "../../src/Settings";
+
+// $FlowIgnore: we import the types directly anyways
+import katex from "katex";
+
+const stringMap = {
+    "(": "left parenthesis",
+    ")": "right parenthesis",
+    "[": "open bracket",
+    "]": "close bracket",
+    "\\{": "left brace",
+    "\\}": "right brace",
+    "\\lvert": "open vertical bar",
+    "\\rvert": "close vertical bar",
+    "|": "vertical bar",
+    "\\uparrow": "up arrow",
+    "\\Uparrow": "up arrow",
+    "\\downarrow": "down arrow",
+    "\\Downarrow": "down arrow",
+    "\\updownarrow": "up down arrow",
+    "\\leftarrow": "left arrow",
+    "\\Leftarrow": "left arrow",
+    "\\rightarrow": "right arrow",
+    "\\Rightarrow": "right arrow",
+    "\\langle": "open angle",
+    "\\rangle": "close angle",
+    "\\lfloor": "open floor",
+    "\\rfloor": "close floor",
+    "\\int": "integral",
+    "\\intop": "integral",
+    "\\lim": "limit",
+    "\\ln": "natural log",
+    "\\log": "log",
+    "\\sin": "sine",
+    "\\cos": "cosine",
+    "\\tan": "tangent",
+    "\\cot": "cotangent",
+    "\\sum": "sum",
+    "/": "slash",
+    ",": "comma",
+    ".": "point",
+    "-": "negative",
+    "+": "plus",
+    "~": "tilde",
+    ":": "colon",
+    "?": "question mark",
+    "'": "apostrophe",
+    "\\%": "percent",
+    " ": "space",
+    "\\ ": "space",
+    "\\$": "dollar sign",
+    "\\angle": "angle",
+    "\\degree": "degree",
+    "\\circ": "circle",
+    "\\vec": "vector",
+    "\\triangle": "triangle",
+    "\\pi": "pi",
+    "\\prime": "prime",
+    "\\infty": "infinity",
+    "\\alpha": "alpha",
+    "\\beta": "beta",
+    "\\gamma": "gamma",
+    "\\omega": "omega",
+    "\\theta": "theta",
+    "\\sigma": "sigma",
+    "\\lambda": "lambda",
+    "\\tau": "tau",
+    "\\Delta": "delta",
+    "\\delta": "delta",
+    "\\mu": "mu",
+    "\\rho": "rho",
+    "\\nabla": "del",
+    "\\ell": "ell",
+    "\\ldots": "dots",
+    // TODO: add entries for all accents
+    "\\hat": "hat",
+    "\\acute": "acute",
+};
+
+const powerMap = {
+    "prime": "prime",
+    "degree": "degrees",
+    "circle": "degrees",
+    "2": "squared",
+    "3": "cubed",
+};
+
+const openMap = {
+    "|": "open vertical bar",
+    ".": "",
+};
+
+const closeMap = {
+    "|": "close vertical bar",
+    ".": "",
+};
+
+const binMap = {
+    "+": "plus",
+    "-": "minus",
+    "\\pm": "plus minus",
+    "\\cdot": "dot",
+    "*": "times",
+    "/": "divided by",
+    "\\times": "times",
+    "\\div": "divided by",
+    "\\circ": "circle",
+    "\\bullet": "bullet",
+};
+
+const relMap = {
+    "=": "equals",
+    "\\approx": "approximately equals",
+    "≠": "does not equal",
+    "\\geq": "is greater than or equal to",
+    "\\ge": "is greater than or equal to",
+    "\\leq": "is less than or equal to",
+    "\\le": "is less than or equal to",
+    ">": "is greater than",
+    "<": "is less than",
+    "\\leftarrow": "left arrow",
+    "\\Leftarrow": "left arrow",
+    "\\rightarrow": "right arrow",
+    "\\Rightarrow": "right arrow",
+    ":": "colon",
+};
+
+const accentUnderMap = {
+    "\\underleftarrow": "left arrow",
+    "\\underrightarrow": "right arrow",
+    "\\underleftrightarrow": "left-right arrow",
+    "\\undergroup": "group",
+    "\\underlinesegment": "line segment",
+    "\\utilde": "tilde",
+};
+
+type NestedArray<T> = Array<T | NestedArray<T>>;
+
+const buildString = (
+    str: string,
+    type: Atom | "normal",
+    a11yStrings: NestedArray<string>,
+) => {
+    if (!str) {
+        return;
+    }
+
+    let ret;
+
+    if (type === "open") {
+        ret = str in openMap ? openMap[str] : stringMap[str] || str;
+    } else if (type === "close") {
+        ret = str in closeMap ? closeMap[str] : stringMap[str] || str;
+    } else if (type === "bin") {
+        ret = binMap[str] || str;
+    } else if (type === "rel") {
+        ret = relMap[str] || str;
+    } else {
+        ret = stringMap[str] || str;
+    }
+
+    // If the text to add is a number and there is already a string
+    // in the list and the last string is a number then we should
+    // combine them into a single number
+    if (
+        /^\d+$/.test(ret) &&
+        a11yStrings.length > 0 &&
+        // TODO(kevinb): check that the last item in a11yStrings is a string
+        // I think we might be able to drop the nested arrays, which would make
+        // this easier to type - $FlowFixMe
+        /^\d+$/.test(a11yStrings[a11yStrings.length - 1])
+    ) {
+        a11yStrings[a11yStrings.length - 1] += ret;
+    } else if (ret) {
+        a11yStrings.push(ret);
+    }
+};
+
+const buildRegion = (
+    a11yStrings: NestedArray<string>,
+    callback: (regionStrings: NestedArray<string>) => void,
+) => {
+    const regionStrings: NestedArray<string> = [];
+    a11yStrings.push(regionStrings);
+    callback(regionStrings);
+};
+
+const handleObject = (
+    tree: AnyParseNode,
+    a11yStrings: NestedArray<string>,
+    atomType: Atom | "normal",
+) => {
+     // Everything else is assumed to be an object...
+    switch (tree.type) {
+        case "accent": {
+            buildRegion(a11yStrings, (a11yStrings) => {
+                buildA11yStrings(tree.base, a11yStrings, atomType);
+                a11yStrings.push("with");
+                buildString(tree.label, "normal", a11yStrings);
+                a11yStrings.push("on top");
+            });
+            break;
+        }
+
+        case "accentUnder": {
+            buildRegion(a11yStrings, (a11yStrings) => {
+                buildA11yStrings(tree.base, a11yStrings, atomType);
+                a11yStrings.push("with");
+                buildString(accentUnderMap[tree.label], "normal", a11yStrings);
+                a11yStrings.push("underneath");
+            });
+            break;
+        }
+
+        case "accent-token": {
+            // Used internally by accent symbols.
+            break;
+        }
+
+        case "atom": {
+            const {text} = tree;
+            switch (tree.family) {
+                case "bin": {
+                    buildString(text, "bin", a11yStrings);
+                    break;
+                }
+                case "close": {
+                    buildString(text, "close", a11yStrings);
+                    break;
+                }
+                // TODO(kevinb): figure out what should be done for inner
+                case "inner": {
+                    buildString(tree.text, "inner", a11yStrings);
+                    break;
+                }
+                case "open": {
+                    buildString(text, "open", a11yStrings);
+                    break;
+                }
+                case "punct": {
+                    buildString(text, "punct", a11yStrings);
+                    break;
+                }
+                case "rel": {
+                    buildString(text, "rel", a11yStrings);
+                    break;
+                }
+                default: {
+                    (tree.family: empty);
+                    throw new Error(`"${tree.family}" is not a valid atom type`);
+                }
+            }
+            break;
+        }
+
+        case "color": {
+            const color = tree.color.replace(/katex-/, "");
+
+            buildRegion(a11yStrings, (regionStrings) => {
+                regionStrings.push("start color " + color);
+                buildA11yStrings(tree.body, regionStrings, atomType);
+                regionStrings.push("end color " + color);
+            });
+            break;
+        }
+
+        case "color-token": {
+            // Used by \color, \colorbox, and \fcolorbox but not directly rendered.
+            // It's a leaf node and has no children so just break.
+            break;
+        }
+
+        case "delimsizing": {
+            if (tree.delim && tree.delim !== ".") {
+                buildString(tree.delim, "normal", a11yStrings);
+            }
+            break;
+        }
+
+        case "genfrac": {
+            buildRegion(a11yStrings, (regionStrings) => {
+                // genfrac can have unbalanced delimiters
+                const {leftDelim, rightDelim} = tree;
+
+                // NOTE: Not sure if this is a safe assumption
+                // hasBarLine true -> fraction, false -> binomial
+                if (tree.hasBarLine) {
+                    regionStrings.push("start fraction");
+                    leftDelim && buildString(leftDelim, "open", regionStrings);
+                    buildA11yStrings(tree.numer, regionStrings, atomType);
+                    regionStrings.push("divided by");
+                    buildA11yStrings(tree.denom, regionStrings, atomType);
+                    rightDelim && buildString(rightDelim, "close", regionStrings);
+                    regionStrings.push("end fraction");
+                } else {
+                    regionStrings.push("start binomial");
+                    leftDelim && buildString(leftDelim, "open", regionStrings);
+                    buildA11yStrings(tree.numer, regionStrings, atomType);
+                    regionStrings.push("over");
+                    buildA11yStrings(tree.denom, regionStrings, atomType);
+                    rightDelim && buildString(rightDelim, "close", regionStrings);
+                    regionStrings.push("end binomial");
+                }
+            });
+            break;
+        }
+
+        case "kern": {
+            // No op: we don't attempt to present kerning information
+            // to the screen reader.
+            break;
+        }
+
+        case "leftright": {
+            buildRegion(a11yStrings, (regionStrings) => {
+                buildString(tree.left, "open", regionStrings);
+                buildA11yStrings(tree.body, regionStrings, atomType);
+                buildString(tree.right, "close", regionStrings);
+            });
+            break;
+        }
+
+        case "leftright-right": {
+            // TODO: double check that this is a no-op
+            break;
+        }
+
+        case "lap": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "mathord": {
+            buildString(tree.text, "normal", a11yStrings);
+            break;
+        }
+
+        case "op": {
+            const {body, name} = tree;
+            if (body) {
+                buildA11yStrings(body, a11yStrings, atomType);
+            } else if (name) {
+                buildString(name, "normal", a11yStrings);
+            }
+            break;
+        }
+
+        case "op-token": {
+            // Used internally by operator symbols.
+            buildString(tree.text, atomType, a11yStrings);
+            break;
+        }
+
+        case "ordgroup": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "overline": {
+            buildRegion(a11yStrings, function(a11yStrings) {
+                a11yStrings.push("start overline");
+                buildA11yStrings(tree.body, a11yStrings, atomType);
+                a11yStrings.push("end overline");
+            });
+            break;
+        }
+
+        case "phantom": {
+            a11yStrings.push("empty space");
+            break;
+        }
+
+        case "raisebox": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "rule": {
+            a11yStrings.push("rectangle");
+            break;
+        }
+
+        case "sizing": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "spacing": {
+            a11yStrings.push("space");
+            break;
+        }
+
+        case "styling": {
+            // We ignore the styling and just pass through the contents
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "sqrt": {
+            buildRegion(a11yStrings, (regionStrings) => {
+                const {body, index} = tree;
+                if (index) {
+                    const indexString = flatten(
+                        buildA11yStrings(index, [], atomType)).join(",");
+                    if (indexString === "3") {
+                        regionStrings.push("cube root of");
+                        buildA11yStrings(body, regionStrings, atomType);
+                        regionStrings.push("end cube root");
+                        return;
+                    }
+
+                    regionStrings.push("root");
+                    regionStrings.push("start index");
+                    buildA11yStrings(index, regionStrings, atomType);
+                    regionStrings.push("end index");
+                    return;
+                }
+
+                regionStrings.push("square root of");
+                buildA11yStrings(body, regionStrings, atomType);
+                regionStrings.push("end square root");
+            });
+            break;
+        }
+
+        case "supsub": {
+            const {base, sub, sup} = tree;
+            let isLog = false;
+
+            if (base) {
+                buildA11yStrings(base, a11yStrings, atomType);
+                isLog = base.type === "op" && base.name === "\\log";
+            }
+
+            if (sub) {
+                const regionName = isLog ? "base" : "subscript";
+                buildRegion(a11yStrings, function(regionStrings) {
+                    regionStrings.push(`start ${regionName}`);
+                    buildA11yStrings(sub, regionStrings, atomType);
+                    regionStrings.push(`end ${regionName}`);
+                });
+            }
+
+            if (sup) {
+                buildRegion(a11yStrings, function(regionStrings) {
+                    const supString = flatten(
+                        buildA11yStrings(sup, [], atomType)).join(",");
+
+                    if (supString in powerMap) {
+                        regionStrings.push(powerMap[supString]);
+                        return;
+                    }
+
+                    regionStrings.push("start superscript");
+                    buildA11yStrings(sup, regionStrings, atomType);
+                    regionStrings.push("end superscript");
+                });
+            }
+            break;
+        }
+
+        case "text": {
+            // TODO: handle other fonts
+            if (tree.font === "\\textbf") {
+                buildRegion(a11yStrings, function(regionStrings) {
+                    regionStrings.push("start bold text");
+                    buildA11yStrings(tree.body, regionStrings, atomType);
+                    regionStrings.push("end bold text");
+                });
+                break;
+            }
+            buildRegion(a11yStrings, function(regionStrings) {
+                regionStrings.push("start text");
+                buildA11yStrings(tree.body, regionStrings, atomType);
+                regionStrings.push("end text");
+            });
+            break;
+        }
+
+        case "textord": {
+            buildString(tree.text, atomType, a11yStrings);
+            break;
+        }
+
+        case "smash": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "enclose": {
+            // TODO: create a map for these.
+            // TODO: differentiate between a body with a single atom, e.g.
+            // "cancel a" instead of "start cancel, a, end cancel"
+            if (/cancel/.test(tree.label)) {
+                buildRegion(a11yStrings, function(regionStrings) {
+                    regionStrings.push("start cancel");
+                    buildA11yStrings(tree.body, regionStrings, atomType);
+                    regionStrings.push("end cancel");
+                });
+                break;
+            } else if (/box/.test(tree.label)) {
+                buildRegion(a11yStrings, function(regionStrings) {
+                    regionStrings.push("start box");
+                    buildA11yStrings(tree.body, regionStrings, atomType);
+                    regionStrings.push("end box");
+                });
+                break;
+            } else if (/sout/.test(tree.label)) {
+                buildRegion(a11yStrings, function(regionStrings) {
+                    regionStrings.push("start strikeout");
+                    buildA11yStrings(tree.body, regionStrings, atomType);
+                    regionStrings.push("end strikeout");
+                });
+                break;
+            }
+            throw new Error(
+                `KaTeX-a11y: enclose node with ${tree.label} not supported yet`);
+        }
+
+        case "vphantom": {
+            throw new Error("KaTeX-a11y: vphantom not implemented yet");
+        }
+
+        case "hphantom": {
+            throw new Error("KaTeX-a11y: hphantom not implemented yet");
+        }
+
+        case "operatorname": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "array": {
+            throw new Error("KaTeX-a11y: array not implemented yet");
+        }
+
+        case "raw": {
+            throw new Error("KaTeX-a11y: raw not implemented yet");
+        }
+
+        case "size": {
+            // Although there are nodes of type "size" in the parse tree, they have
+            // no semantic meaning and should be ignored.
+            break;
+        }
+
+        case "url": {
+            throw new Error("KaTeX-a11y: url not implemented yet");
+        }
+
+        case "tag": {
+            throw new Error("KaTeX-a11y: tag not implemented yet");
+        }
+
+        case "verb": {
+            buildString(`start verbatim`, "normal", a11yStrings);
+            buildString(tree.body, "normal", a11yStrings);
+            buildString(`end verbatim`, "normal", a11yStrings);
+            break;
+        }
+
+        case "environment": {
+            throw new Error("KaTeX-a11y: environment not implemented yet");
+        }
+
+        case "horizBrace": {
+            buildString(`start ${tree.label.slice(1)}`, "normal", a11yStrings);
+            buildA11yStrings(tree.base, a11yStrings, atomType);
+            buildString(`end ${tree.label.slice(1)}`, "normal", a11yStrings);
+            break;
+        }
+
+        case "infix": {
+            // All infix nodes are replace with other nodes.
+            break;
+        }
+
+        case "includegraphics": {
+            throw new Error("KaTeX-a11y: includegraphics not implemented yet");
+        }
+
+        case "font": {
+            // TODO: callout the start/end of specific fonts
+            // TODO: map \BBb{N} to "the naturals" or something like that
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "href": {
+            throw new Error("KaTeX-a11y: href not implemented yet");
+        }
+
+        case "cr": {
+            // This is used by environments.
+            throw new Error("KaTeX-a11y: cr not implemented yet");
+        }
+
+        case "underline": {
+            buildRegion(a11yStrings, function(a11yStrings) {
+                a11yStrings.push("start underline");
+                buildA11yStrings(tree.body, a11yStrings, atomType);
+                a11yStrings.push("end underline");
+            });
+            break;
+        }
+
+        case "xArrow": {
+            throw new Error("KaTeX-a11y: xArrow not implemented yet");
+        }
+
+        case "mclass": {
+            // \neq and \ne are macros so we let "htmlmathml" render the mathmal
+            // side of things and extract the text from that.
+            const atomType = tree.mclass.slice(1);
+            // $FlowFixMe: drop the leading "m" from the values in mclass
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        case "mathchoice": {
+            // TODO: track which which style we're using, e.g. dispaly, text, etc.
+            // default to text style if even that may not be the correct style
+            buildA11yStrings(tree.text, a11yStrings, atomType);
+            break;
+        }
+
+        case "htmlmathml": {
+            buildA11yStrings(tree.mathml, a11yStrings, atomType);
+            break;
+        }
+
+        case "middle": {
+            buildString(tree.delim, atomType, a11yStrings);
+            break;
+        }
+
+        case "internal": {
+            // internal nodes are never included in the parse tree
+            break;
+        }
+
+        case "html": {
+            buildA11yStrings(tree.body, a11yStrings, atomType);
+            break;
+        }
+
+        default:
+            (tree.type: empty);
+            throw new Error("KaTeX a11y un-recognized type: " + tree.type);
+    }
+};
+
+const buildA11yStrings = (
+    tree: AnyParseNode | AnyParseNode[],
+    a11yStrings: NestedArray<string> = [],
+    atomType: Atom | "normal",
+) => {
+    if (tree instanceof Array) {
+        for (let i = 0; i < tree.length; i++) {
+            buildA11yStrings(tree[i], a11yStrings, atomType);
+        }
+    } else {
+        handleObject(tree, a11yStrings, atomType);
+    }
+
+    return a11yStrings;
+};
+
+
+const flatten = function(array) {
+    let result = [];
+
+    array.forEach(function(item) {
+        if (item instanceof Array) {
+            result = result.concat(flatten(item));
+        } else {
+            result.push(item);
+        }
+    });
+
+    return result;
+};
+
+const renderA11yString = function(text: string, settings?: SettingsOptions) {
+
+    const tree = katex.__parse(text, settings);
+    const a11yStrings = buildA11yStrings(tree, [], "normal");
+    return flatten(a11yStrings).join(", ");
+};
+
+export default renderA11yString;