@khanacademy/math-input 2.0.0 → 4.0.0

package/src/components/input/mathquill-helpers.ts

@@ -0,0 +1,268 @@
+import {CursorContext} from "./cursor-contexts";
+import MQ from "./mathquill-instance";
+import {
+    MathFieldActionType,
+    MathFieldCursor,
+    MathFieldInterface,
+} from "./mathquill-types";
+
+const Numerals = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"];
+const GreekLetters = ["\\theta", "\\pi"];
+const Letters = [
+    "A",
+    "B",
+    "C",
+    "D",
+    "E",
+    "F",
+    "G",
+    "H",
+    "I",
+    "J",
+    "K",
+    "L",
+    "M",
+    "N",
+    "O",
+    "P",
+    "Q",
+    "R",
+    "S",
+    "T",
+    "U",
+    "V",
+    "W",
+    "X",
+    "Y",
+    "Z",
+];
+
+// We only consider numerals, variables, and Greek Letters to be proper
+// leaf nodes.
+const ValidLeaves = [
+    ...Numerals,
+    ...GreekLetters,
+    ...Letters.map((letter) => letter.toLowerCase()),
+    ...Letters.map((letter) => letter.toUpperCase()),
+];
+
+export function getCursor(mathField: MathFieldInterface): MathFieldCursor {
+    return mathField.__controller.cursor;
+}
+
+export function isFraction(node): boolean {
+    return node.jQ && node.jQ.hasClass("mq-fraction");
+}
+
+export function isNumerator(node): boolean {
+    return node.jQ && node.jQ.hasClass("mq-numerator");
+}
+
+export function isDenominator(node): boolean {
+    return node.jQ && node.jQ.hasClass("mq-denominator");
+}
+
+export function isSubScript(node): boolean {
+    // NOTE(charlie): MyScript has a structure whereby its superscripts seem
+    // to be represented as a parent node with 'mq-sup-only' containing a
+    // single child with 'mq-sup'.
+    return (
+        node.jQ &&
+        (node.jQ.hasClass("mq-sub-only") || node.jQ.hasClass("mq-sub"))
+    );
+}
+
+export function isSuperScript(node): boolean {
+    // NOTE(charlie): MyScript has a structure whereby its superscripts seem
+    // to be represented as a parent node with 'mq-sup-only' containing a
+    // single child with 'mq-sup'.
+    return (
+        node.jQ &&
+        (node.jQ.hasClass("mq-sup-only") || node.jQ.hasClass("mq-sup"))
+    );
+}
+
+export function isParens(node): boolean {
+    return node && node.ctrlSeq === "\\left(";
+}
+
+export function isLeaf(node): boolean {
+    return node && node.ctrlSeq && ValidLeaves.includes(node.ctrlSeq.trim());
+}
+
+export function isSquareRoot(node): boolean {
+    return (
+        node.blocks &&
+        node.blocks[0].jQ &&
+        node.blocks[0].jQ.hasClass("mq-sqrt-stem")
+    );
+}
+
+export function isNthRoot(node): boolean {
+    return (
+        node.blocks &&
+        node.blocks[0].jQ &&
+        node.blocks[0].jQ.hasClass("mq-nthroot")
+    );
+}
+
+export function isNthRootIndex(node): boolean {
+    return node.jQ && node.jQ.hasClass("mq-nthroot");
+}
+
+export function isInsideLogIndex(cursor: MathFieldCursor): boolean {
+    const grandparent = cursor.parent.parent;
+
+    if (grandparent && grandparent.jQ.hasClass("mq-supsub")) {
+        const command = maybeFindCommandBeforeParens(grandparent);
+
+        if (command && command.name === "\\log") {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+export function isInsideEmptyNode(cursor: MathFieldCursor): boolean {
+    return (
+        cursor[MQ.L] === MathFieldActionType.MQ_END &&
+        cursor[MQ.R] === MathFieldActionType.MQ_END
+    );
+}
+
+export function selectNode(node, cursor) {
+    cursor.insLeftOf(node);
+    cursor.startSelection();
+    cursor.insRightOf(node);
+    cursor.select();
+    cursor.endSelection();
+}
+
+/**
+ * Return the start node, end node, and full name of the command of which
+ * the initial node is a part, or `null` if the node is not part of a
+ * command.
+ *
+ * @param {node} initialNode - the node to included as part of the command
+ * @returns {null|object} - `null` or an object containing the start node
+ *                          (`startNode`), end node (`endNode`), and full
+ *                          name (`name`) of the command
+ */
+export function maybeFindCommand(initialNode) {
+    if (!initialNode) {
+        return null;
+    }
+
+    // MathQuill stores commands as separate characters so that
+    // users can delete commands one character at a time.  We iterate over
+    // the nodes from right to left until we hit a sequence starting with a
+    // '\\', which signifies the start of a command; then we iterate from
+    // left to right until we hit a '\\left(', which signifies the end of a
+    // command.  If we encounter any character that doesn't belong in a
+    // command, we return null.  We match a single character at a time.
+    // Ex) ['\\l', 'o', 'g ', '\\left(', ...]
+    const commandCharRegex = /^[a-z]$/;
+    const commandStartRegex = /^\\[a-z]$/;
+    const commandEndSeq = "\\left(";
+
+    // Note: We allowlist the set of valid commands, since relying solely on
+    // a command being prefixed with a backslash leads to undesired
+    // behavior. For example, Greek symbols, left parentheses, and square
+    // roots all get treated as commands.
+    const validCommands = ["\\log", "\\ln", "\\cos", "\\sin", "\\tan"];
+
+    let name = "";
+    let startNode;
+    let endNode;
+
+    // Collect the portion of the command from the current node, leftwards
+    // until the start of the command.
+    let node = initialNode;
+    while (node !== 0) {
+        const ctrlSeq = node.ctrlSeq.trim();
+        if (commandCharRegex.test(ctrlSeq)) {
+            name = ctrlSeq + name;
+        } else if (commandStartRegex.test(ctrlSeq)) {
+            name = ctrlSeq + name;
+            startNode = node;
+            break;
+        } else {
+            break;
+        }
+
+        node = node[MQ.L];
+    }
+
+    // If we hit the start of a command, then grab the rest of it by
+    // iterating rightwards to compute the full name of the command, along
+    // with its terminal node.
+    if (startNode) {
+        // Next, iterate from the start to the right.
+        node = initialNode[MQ.R];
+        while (node !== 0) {
+            const ctrlSeq = node.ctrlSeq.trim();
+            if (commandCharRegex.test(ctrlSeq)) {
+                // If we have a single character, add it to the command
+                // name.
+                name = name + ctrlSeq;
+            } else if (ctrlSeq === commandEndSeq) {
+                // If we hit the command end delimiter (the left
+                // parentheses surrounding its arguments), stop.
+                endNode = node;
+                break;
+            }
+
+            node = node[MQ.R];
+        }
+        if (validCommands.includes(name)) {
+            return {name, startNode, endNode};
+        } else {
+            return null;
+        }
+    } else {
+        return null;
+    }
+}
+
+/**
+ * Return the start node, end node, and full name of the command to the left
+ * of `\\left(`, or `null` if there is no command.
+ *
+ * @param {node} leftParenNode - node where .ctrlSeq == `\\left(`
+ * @returns {null|object} - `null` or an object containing the start node
+ *                          (`startNode`), end node (`endNode`), and full
+ *                          name (`name`) of the command
+ */
+export function maybeFindCommandBeforeParens(leftParenNode) {
+    return maybeFindCommand(leftParenNode[MQ.L]);
+}
+
+export function contextForCursor(cursor: MathFieldCursor): CursorContext {
+    // First, try to find any fraction to the right, unimpeded.
+    let visitor = cursor;
+    while (visitor[MQ.R] !== MathFieldActionType.MQ_END) {
+        if (isFraction(visitor[MQ.R])) {
+            return CursorContext.BEFORE_FRACTION;
+        } else if (!isLeaf(visitor[MQ.R])) {
+            break;
+        }
+        visitor = visitor[MQ.R];
+    }
+
+    // If that didn't work, check if the parent or grandparent is a special
+    // context, so that we can jump outwards.
+    if (isParens(cursor.parent && cursor.parent.parent)) {
+        return CursorContext.IN_PARENS;
+    } else if (isNumerator(cursor.parent)) {
+        return CursorContext.IN_NUMERATOR;
+    } else if (isDenominator(cursor.parent)) {
+        return CursorContext.IN_DENOMINATOR;
+    } else if (isSubScript(cursor.parent)) {
+        return CursorContext.IN_SUB_SCRIPT;
+    } else if (isSuperScript(cursor.parent)) {
+        return CursorContext.IN_SUPER_SCRIPT;
+    } else {
+        return CursorContext.NONE;
+    }
+}

package/src/components/input/mathquill-instance.ts

@@ -0,0 +1,5 @@
+import MathQuill from "mathquill";
+
+import {MathQuillInterface} from "./mathquill-types";
+
+export default MathQuill.getInterface(2) as MathQuillInterface;

package/src/components/input/mathquill-types.ts

@@ -0,0 +1,55 @@
+import Key from "../../data/keys";
+
+export interface MathQuillInterface {
+    L: "L";
+    R: "R";
+    MathField: (mount: HTMLDivElement, options: any) => MathFieldInterface;
+}
+
+export interface MathFieldInterface {
+    // Write LaTeX
+    // https://docs.mathquill.com/en/latest/Api_Methods/#writelatex_string
+    write: (input: string) => void;
+    // Enter a LaTeX command
+    // https://docs.mathquill.com/en/latest/Api_Methods/#cmdlatex_string
+    cmd: (input: string) => void;
+    // Simulates keystrokes given a string like "Ctrl-Home Del"
+    // https://docs.mathquill.com/en/latest/Api_Methods/#keystrokekeys
+    keystroke: (input: string) => void;
+    // Simulates typing text, one character at a time
+    // https://docs.mathquill.com/en/latest/Api_Methods/#typedtexttext
+    typedText: (input: string) => void;
+    // () => {}: Gets the contents as LaTeX
+    // (string) => {}: Sets the contents as LaTeX
+    // https://docs.mathquill.com/en/latest/Api_Methods/#latex
+    latex: (input?: string) => string;
+    // Moves the cursor to the end of the mathfield in the direction specified
+    // https://docs.mathquill.com/en/latest/Api_Methods/#movetodirenddirection
+    moveToDirEnd: (direction: "L" | "R") => void;
+    // Selects the contents
+    // https://docs.mathquill.com/en/latest/Api_Methods/#select
+    select: () => void;
+    // Clears the selection
+    // https://docs.mathquill.com/en/latest/Api_Methods/#clearselection
+    clearSelection: () => void;
+    // This isn't part of the MathQuill public API
+    // I don't know what it is and it feels wrong using it
+    __controller: any;
+}
+
+export enum MathFieldActionType {
+    WRITE = "write",
+    CMD = "cmd",
+    KEYSTROKE = "keystroke",
+    MQ_END = 0,
+}
+
+// The MathQuill MathField Cursor
+// it's not part of the public API for MathQuill,
+// we reach into the internals to get it
+export type MathFieldCursor = any;
+
+export type MathQuillUpdaterCallback = (
+    mathQuill: MathFieldInterface,
+    key: Key,
+) => void;

package/src/components/key-translator.ts

@@ -0,0 +1,209 @@
+import Key from "../data/keys";
+import {DecimalSeparator} from "../enums";
+import {decimalSeparator} from "../utils";
+
+import MQ from "./input/mathquill-instance";
+import {
+    MathFieldInterface,
+    MathQuillUpdaterCallback,
+} from "./input/mathquill-types";
+
+enum ActionType {
+    WRITE = "write",
+    CMD = "cmd",
+    KEYSTROKE = "keystroke",
+    MQ_END = 0,
+}
+
+const decimalSymbol = decimalSeparator === DecimalSeparator.COMMA ? "," : ".";
+
+function buildGenericCallback(
+    str: string,
+    type: ActionType = ActionType.WRITE,
+): MathQuillUpdaterCallback {
+    return function (mathQuill: MathFieldInterface) {
+        switch (type) {
+            case ActionType.WRITE: {
+                mathQuill.write(str);
+                return;
+            }
+            case ActionType.CMD: {
+                mathQuill.cmd(str);
+                return;
+            }
+            case ActionType.KEYSTROKE: {
+                mathQuill.keystroke(str);
+                return;
+            }
+        }
+    };
+}
+
+const keyToMathquillMap: Record<Key, MathQuillUpdaterCallback> = {
+    CDOT: buildGenericCallback("\\cdot"),
+    COS: buildGenericCallback("cos"),
+    DECIMAL: buildGenericCallback(decimalSymbol),
+    DIVIDE: buildGenericCallback("\\div"),
+    EQUAL: buildGenericCallback("="),
+    EXP: buildGenericCallback("^"),
+    EXP_2: buildGenericCallback("^2"),
+    EXP_3: buildGenericCallback("^3"),
+    GEQ: buildGenericCallback("\\geq"),
+    GT: buildGenericCallback(">"),
+    LEQ: buildGenericCallback("\\leq"),
+    LN: buildGenericCallback("\\ln"),
+    LOG: buildGenericCallback("\\log"),
+    LT: buildGenericCallback("<"),
+    MINUS: buildGenericCallback("-"),
+    NEGATIVE: buildGenericCallback("-"),
+    NEQ: buildGenericCallback("\\neq"),
+    PERCENT: buildGenericCallback("%"),
+    PERIOD: buildGenericCallback("."),
+    PLUS: buildGenericCallback("+"),
+    SIN: buildGenericCallback("sin"),
+    TAN: buildGenericCallback("tan"),
+    TIMES: buildGenericCallback("\\times"),
+
+    // The `FRAC_EXCLUSIVE` variant is handled manually, since we may need to do
+    // some additional navigation depending on the cursor position.
+    FRAC_INCLUSIVE: buildGenericCallback("/", ActionType.CMD),
+    LEFT_PAREN: buildGenericCallback("(", ActionType.CMD),
+    RIGHT_PAREN: buildGenericCallback(")", ActionType.CMD),
+    SQRT: buildGenericCallback("sqrt", ActionType.CMD),
+    PHI: buildGenericCallback("\\phi", ActionType.CMD),
+    PI: buildGenericCallback("pi", ActionType.CMD),
+    THETA: buildGenericCallback("theta", ActionType.CMD),
+    RADICAL: buildGenericCallback("nthroot", ActionType.CMD),
+
+    UP: buildGenericCallback("Up", ActionType.KEYSTROKE),
+    DOWN: buildGenericCallback("Down", ActionType.KEYSTROKE),
+
+    CUBE_ROOT: (mathQuill) => {
+        mathQuill.write("\\sqrt[3]{}");
+        mathQuill.keystroke("Left"); // under the root
+    },
+
+    FRAC_EXCLUSIVE: (mathQuill) => {
+        const cursor = mathQuill.__controller.cursor;
+        // If there's nothing to the left of the cursor, then we want to
+        // leave the cursor to the left of the fraction after creating it.
+        const shouldNavigateLeft = cursor[MQ.L] === ActionType.MQ_END;
+        mathQuill.cmd("\\frac");
+        if (shouldNavigateLeft) {
+            mathQuill.keystroke("Left");
+        }
+    },
+
+    LOG_B: (mathQuill) => {
+        mathQuill.typedText("log_");
+        mathQuill.keystroke("Right");
+        mathQuill.typedText("(");
+        mathQuill.keystroke("Left");
+        mathQuill.keystroke("Left");
+    },
+
+    LOG_N: (mathQuill) => {
+        mathQuill.write("log_{ }\\left(\\right)");
+        mathQuill.keystroke("Left"); // into parentheses
+        mathQuill.keystroke("Left"); // out of parentheses
+        mathQuill.keystroke("Left"); // into index
+    },
+
+    NTHROOT3: (mathQuill) => {
+        mathQuill.typedText("nthroot3");
+        mathQuill.keystroke("Right");
+    },
+
+    POW: (mathQuill) => {
+        const contents = mathQuill.latex();
+        mathQuill.typedText("^");
+
+        // If the input hasn't changed (for example, if we're
+        // attempting to add an exponent on an empty input or an empty
+        // denominator), insert our own "a^b"
+        if (mathQuill.latex() === contents) {
+            mathQuill.typedText("a^b");
+        }
+    },
+
+    // These need to be overwritten by the consumer
+    // if they're going to be used
+    FRAC: () => {},
+    RIGHT: () => {},
+    LEFT: () => {},
+    BACKSPACE: () => {},
+    DISMISS: () => {},
+    JUMP_OUT_PARENTHESES: () => {},
+    JUMP_OUT_EXPONENT: () => {},
+    JUMP_OUT_BASE: () => {},
+    JUMP_INTO_NUMERATOR: () => {},
+    JUMP_OUT_NUMERATOR: () => {},
+    JUMP_OUT_DENOMINATOR: () => {},
+    NOOP: () => {},
+    MANY: () => {},
+
+    NUM_0: buildGenericCallback("0"),
+    NUM_1: buildGenericCallback("1"),
+    NUM_2: buildGenericCallback("2"),
+    NUM_3: buildGenericCallback("3"),
+    NUM_4: buildGenericCallback("4"),
+    NUM_5: buildGenericCallback("5"),
+    NUM_6: buildGenericCallback("6"),
+    NUM_7: buildGenericCallback("7"),
+    NUM_8: buildGenericCallback("8"),
+    NUM_9: buildGenericCallback("9"),
+    a: buildGenericCallback("a"),
+    b: buildGenericCallback("b"),
+    c: buildGenericCallback("c"),
+    d: buildGenericCallback("d"),
+    e: buildGenericCallback("e"),
+    f: buildGenericCallback("f"),
+    g: buildGenericCallback("g"),
+    h: buildGenericCallback("h"),
+    i: buildGenericCallback("i"),
+    j: buildGenericCallback("j"),
+    k: buildGenericCallback("k"),
+    l: buildGenericCallback("l"),
+    m: buildGenericCallback("m"),
+    n: buildGenericCallback("n"),
+    o: buildGenericCallback("o"),
+    p: buildGenericCallback("p"),
+    q: buildGenericCallback("q"),
+    r: buildGenericCallback("r"),
+    s: buildGenericCallback("s"),
+    t: buildGenericCallback("t"),
+    u: buildGenericCallback("u"),
+    v: buildGenericCallback("v"),
+    w: buildGenericCallback("w"),
+    x: buildGenericCallback("x"),
+    y: buildGenericCallback("y"),
+    z: buildGenericCallback("z"),
+    A: buildGenericCallback("A"),
+    B: buildGenericCallback("B"),
+    C: buildGenericCallback("C"),
+    D: buildGenericCallback("D"),
+    E: buildGenericCallback("E"),
+    F: buildGenericCallback("F"),
+    G: buildGenericCallback("G"),
+    H: buildGenericCallback("H"),
+    I: buildGenericCallback("I"),
+    J: buildGenericCallback("J"),
+    K: buildGenericCallback("K"),
+    L: buildGenericCallback("L"),
+    M: buildGenericCallback("M"),
+    N: buildGenericCallback("N"),
+    O: buildGenericCallback("O"),
+    P: buildGenericCallback("P"),
+    Q: buildGenericCallback("Q"),
+    R: buildGenericCallback("R"),
+    S: buildGenericCallback("S"),
+    T: buildGenericCallback("T"),
+    U: buildGenericCallback("U"),
+    V: buildGenericCallback("V"),
+    W: buildGenericCallback("W"),
+    X: buildGenericCallback("X"),
+    Y: buildGenericCallback("Y"),
+    Z: buildGenericCallback("Z"),
+};
+
+export default keyToMathquillMap;