@khanacademy/math-input 16.5.1 → 17.0.1

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

@@ -1,82 +1,82 @@
 import MathQuill from "mathquill";
 
-import type {MathQuillInterface, MathFieldConfig} from "./mathquill-types";
+import type {
+    MathQuillInterface,
+    MathFieldConfig,
+    MathFieldInterface,
+} from "./mathquill-types";
 
 // We only need one MathQuill instance (referred to as MQ in the docs)
 // and that contains some MQ constants and the MathField constructor
-export const mathQuillInstance = MathQuill.getInterface(
-    2,
-) as MathQuillInterface;
+export const mathQuillInstance: MathQuillInterface = MathQuill.getInterface(3);
 
-function createBaseConfig(): MathFieldConfig {
-    return {
-        // LaTeX commands that, when typed, are immediately replaced by the
-        // appropriate symbol. This does not include ln, log, or any of the
-        // trig functions; those are always interpreted as commands.
-        autoCommands: "pi theta phi sqrt nthroot",
-        // Most of these autoOperatorNames are simply the MathQuill defaults.
-        // We have to list them all in order to add the `sen` operator (see
-        // comment below).
-        autoOperatorNames: [
-            "arccos",
-            "arcsin",
-            "arctan",
-            "arg",
-            "cos",
-            "cosh",
-            "cot",
-            "coth",
-            "csc",
-            "deg",
-            "det",
-            "dim",
-            "exp",
-            "gcd",
-            "hom",
-            "inf",
-            "ker",
-            "lg",
-            "lim",
-            "liminf",
-            "limsup",
-            "ln",
-            "log",
-            "max",
-            "min",
-            "Pr",
-            "projlim",
-            "sec",
-            // sen is used instead of sin in e.g. Portuguese
-            "sen",
-            "sin",
-            "sinh",
-            "sup",
-            "tan",
-            "tanh",
-        ].join(" "),
+const createBaseConfig = (): MathFieldConfig => ({
+    // LaTeX commands that, when typed, are immediately replaced by the
+    // appropriate symbol. This does not include ln, log, or any of the
+    // trig functions; those are always interpreted as commands.
+    autoCommands: "pi theta phi sqrt nthroot",
+    // Most of these autoOperatorNames are simply the MathQuill defaults.
+    // We have to list them all in order to add the `sen` operator (see
+    // comment below).
+    autoOperatorNames: [
+        "arccos",
+        "arcsin",
+        "arctan",
+        "arg",
+        "cos",
+        "cosh",
+        "cot",
+        "coth",
+        "csc",
+        "deg",
+        "det",
+        "dim",
+        "exp",
+        "gcd",
+        "hom",
+        "inf",
+        "ker",
+        "lg",
+        "lim",
+        "liminf",
+        "limsup",
+        "ln",
+        "log",
+        "max",
+        "min",
+        "Pr",
+        "projlim",
+        "sec",
+        // sen is used instead of sin in e.g. Portuguese
+        "sen",
+        "sin",
+        "sinh",
+        "sup",
+        "tan",
+        "tanh",
+    ].join(" "),
 
-        // Pop the cursor out of super/subscripts on arithmetic operators
-        // or (in)equalities.
-        charsThatBreakOutOfSupSub: "+-*/=<>≠≤≥",
+    // Pop the cursor out of super/subscripts on arithmetic operators
+    // or (in)equalities.
+    charsThatBreakOutOfSupSub: "+-*/=<>≠≤≥",
 
-        // Prevent excessive super/subscripts or fractions from being
-        // created without operands, e.g. when somebody holds down a key
-        supSubsRequireOperand: true,
+    // Prevent excessive super/subscripts or fractions from being
+    // created without operands, e.g. when somebody holds down a key
+    supSubsRequireOperand: true,
 
-        // The name of this option is somewhat misleading, as tabbing in
-        // MathQuill breaks you out of a nested context (fraction/script)
-        // if you're in one, but moves focus to the next input if you're
-        // not. Spaces (with this option enabled) are just ignored in the
-        // latter case.
-        //
-        // TODO(alex): In order to allow inputting mixed numbers, we will
-        // have to accept spaces in certain cases. The desired behavior is
-        // still to escape nested contexts if currently in one, but to
-        // insert a space if not (we don't expect mixed numbers in nested
-        // contexts). We should also limit to one consecutive space.
-        spaceBehavesLikeTab: true,
-    };
-}
+    // The name of this option is somewhat misleading, as tabbing in
+    // MathQuill breaks you out of a nested context (fraction/script)
+    // if you're in one, but moves focus to the next input if you're
+    // not. Spaces (with this option enabled) are just ignored in the
+    // latter case.
+    //
+    // TODO(alex): In order to allow inputting mixed numbers, we will
+    // have to accept spaces in certain cases. The desired behavior is
+    // still to escape nested contexts if currently in one, but to
+    // insert a space if not (we don't expect mixed numbers in nested
+    // contexts). We should also limit to one consecutive space.
+    spaceBehavesLikeTab: true,
+});
 
 /**
  * Creates a new [MathField](http://docs.mathquill.com/en/latest/Api_Methods/#mqmathfieldhtml_element-config)
@@ -92,7 +92,7 @@ function createBaseConfig(): MathFieldConfig {
 export function createMathField(
     container: HTMLDivElement | HTMLSpanElement,
     configCallback?: (baseConfig: MathFieldConfig) => MathFieldConfig,
-) {
+): MathFieldInterface {
     const baseConfig = createBaseConfig();
     const config = configCallback ? configCallback(baseConfig) : baseConfig;
 

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

@@ -1,346 +1,16 @@
 import type Key from "../../data/keys";
+import type MathQuill from "mathquill";
 
-export interface MathQuillInterface {
-    L: -1;
-    R: 1;
+export type MathQuillInterface = MathQuill.v3.API;
 
-    /**
-     * Creates an editable MathQuill initialized with the contents of the HTML
-     * element and returns a MathField object.
-     *
-     * If the given element is already an editable math field, this will return
-     * a new editable MathField object with the same `.id`. If the element is a
-     * different type of MathQuill, this will return `null`.
-     */
-    MathField: (
-        mount: HTMLDivElement | HTMLSpanElement,
-        config: MathFieldConfig,
-    ) => MathFieldInterface;
-}
-
-type MathQuillDirection = MathQuillInterface["L"] | MathQuillInterface["R"];
-
-export type MathFieldConfig = {
-    /**
-     * If spaceBehavesLikeTab is true the keystrokes {Shift-,}Spacebar will
-     * behave like {Shift-,}Tab escaping from the current block (as opposed
-     * to the default behavior of inserting a Space character).
-     */
-    spaceBehavesLikeTab?: boolean;
-
-    /**
-     * This allows you to change the way the left and right keys move the
-     * cursor when there are items of different height, like fractions.
-     *
-     * By default, the Left and Right keys move the cursor through all
-     * possible cursor positions in a particular order: right into a
-     * fraction puts the cursor at the left end of the numerator, right out
-     * of the numerator puts the cursor at the left end of the denominator,
-     * and right out of the denominator puts the cursor to the right of the
-     * fraction. Symmetrically, left into a fraction puts the cursor at the
-     * right end of the denominator, etc.
-     *
-     * If instead you want right to always visually go right, and left to always go
-     * visually left, you can set leftRightIntoCmdGoes to 'up' or 'down' so that
-     * left and right go up or down (respectively) into commands. For example, 'up'
-     * means that left into a fraction goes up into the numerator and right out of
-     * the numerator skips the denominator and puts the cursor to the right of the
-     * fraction. This behavior can be seen in the Desmos calculator. If this
-     * property is set to 'down' instead, the numerator is harder to navigate to,
-     * like in the Mac OS X built-in app Grapher.
-     */
-    leftRightIntoCmdGoes?: "up" | "down";
-
-    /**
-     * If restrictMismatchedBrackets is true then you can type [a,b) and
-     * (a,b], but if you try typing [x} or \langle x|, you'll get [{x}] or
-     * \langle|x|\rangle instead. This lets you type (|x|+1) normally;
-     * otherwise, you'd get \left( \right| x \left| + 1 \right).
-     */
-    restrictMismatchedBrackets?: boolean;
-
-    /**
-     * If sumStartsWithNEquals is true then when you type \sum, \prod, or
-     * \coprod, the lower limit starts out with n=, e.g. you get the LaTeX
-     * \sum_{n=}^{ }, rather than empty by default.
-     */
-    sumStartsWithNEquals?: boolean;
-
-    /**
-     * supSubsRequireOperand disables typing of superscripts and subscripts
-     * when there's nothing to the left of the cursor to be exponentiated
-     * or subscripted. Prevents the especially confusing typo x^^2, which
-     * looks much like x^2.
-     */
-    supSubsRequireOperand?: boolean;
-
-    /**
-     * charsThatBreakOutOfSupSub takes a string of the chars that when
-     * typed, "break out" of superscripts and subscripts.
-     *
-     * Normally, to get out of a superscript or subscript, a user has to
-     * navigate out of it with the directional keys, a mouse click, tab, or
-     * Space if spaceBehavesLikeTab is true. For example, typing x^2n+y
-     * normally results in the LaTeX x^{2n+y}. If you wanted to get the
-     * LaTeX x^{2n}+y, the user would have to manually move the cursor out
-     * of the exponent.
-     *
-     * If this option was set to '+-', + and - would "break out" of the
-     * exponent. This doesn't apply to the first character in a superscript
-     * or subscript, so typing x^-6 still results in x^{-6}. The downside
-     * to setting this option is that in order to type x^{n+m}, a
-     * workaround like typing x^(n+m and then deleting the ( is required.
-     */
-    charsThatBreakOutOfSupSub?: string;
-
-    /**
-     * :shrug: Undocumented except for being shown in an example for
-     * configuration options.
-     */
-    autoSubscriptNumerals?: boolean;
-
-    /**
-     * autoCommands defines the set of commands automatically rendered by
-     * just typing the letters without typing a backslash first.
-     *
-     * This takes a string formatted as a space-delimited list of LaTeX
-     * commands. Each LaTeX command must be at least letters only with a
-     * minimum length of 2 characters.
-     *
-     * For example, with autoCommands set to 'pi theta', the word 'pi'
-     * automatically converts to the pi symbol and the word 'theta'
-     * automatically converts to the theta symbol.
-     */
-    autoCommands?: string;
-
-    /**
-     * autoOperatorNames overrides the set of operator names that
-     * automatically become non-italicized when typing the letters without
-     * typing a backslash first, like sin, log, etc.
-     *
-     * This defaults to the LaTeX built-in operator names (Section 3.17 of
-     * the Short Math Guide) with additional trig operators like sech,
-     * arcsec, arsinh, etc. If you want some of these italicized after
-     * setting this property, you will have to add them to the list.
-     *
-     * Just like autoCommands above, this takes a string formatted as a
-     * space-delimited list of LaTeX commands.
-     */
-    autoOperatorNames?: string;
-
-    /**
-     * maxDepth specifies the maximum number of nested MathBlocks. When
-     * maxDepth is set to 1, the user can type simple math symbols directly
-     * into the editor but not into nested MathBlocks, e.g. the numerator
-     * and denominator of a fraction.
-     *
-     * Nested content in latex rendered during initialization or pasted
-     * into mathquill is truncated to avoid violating maxDepth. When
-     * maxDepth is not set, no depth limit is applied by default.
-     */
-    maxDepth?: number;
-
-    /**
-     * substituteTextarea is a function that creates a focusable DOM
-     * element that is called when setting up a math field. Overwriting
-     * this may be useful for hacks like suppressing built-in virtual
-     * keyboards. It defaults to <textarea autocorrect=off .../>.
-     *
-     * For example, Desmos substitutes <span tabindex=0></span> on iOS to
-     * suppress the built-in virtual keyboard in favor of a custom math
-     * keypad that calls the MathQuill API. Unfortunately there's no
-     * universal check for a virtual keyboard or way to detect a
-     * touchscreen, and even if you could, a touchscreen ≠ virtual keyboard
-     * (Windows 8 and ChromeOS devices have both physical keyboards and
-     * touchscreens and iOS and Android devices can have Bluetooth
-     * keyboards). Desmos currently sniffs the user agent for iOS, so
-     * Bluetooth keyboards just don't work in Desmos on iOS. The tradeoffs
-     * are up to you.
-     */
-    substituteTextarea?: () => HTMLElement | undefined;
-
-    /**
-     * Handlers are called after a specified event. They are called
-     * directly on the handlers object passed in, preserving the this value
-     */
-    handlers?: {
-        edit?: (mathField: MathFieldInterface) => void;
-        enter?: (mathField: MathFieldInterface) => void;
-
-        moveOutOf?: (
-            direction: MathQuillDirection,
-            mathField: MathFieldInterface,
-        ) => void;
-        upOutOf?: (mathField: MathFieldInterface) => void;
-        downOutOf?: (mathField: MathFieldInterface) => void;
-
-        deleteOutOf?: (
-            direction: MathQuillDirection,
-            mathField: MathFieldInterface,
-        ) => void;
-        selectOutOf?: (
-            direction: MathQuillDirection,
-            mathField: MathFieldInterface,
-        ) => void;
-    };
-};
+export type MathFieldConfig = MathQuill.v3.Config;
 
 /**
  * Editable math fields have all of the above methods in addition to
  * the ones listed here.
  * https://docs.mathquill.com/en/latest/Api_Methods/
  */
-export interface MathFieldInterface {
-    /**
-     * Any element that has been turned into a MathQuill instance can be
-     * reverted.
-     */
-    revert: () => void;
-
-    /**
-     * MathQuill uses computed dimensions, so if they change (because an
-     * element was mathquill-ified before it was in the visible HTML DOM, or
-     * the font size changed), then you'll need to tell MathQuill to recomput
-     */
-    reflow: () => void;
-
-    /** Returns the root HTML element. */
-    el: () => HTMLElement;
-
-    /**
-     * Puts the focus on the editable field.
-     * http://docs.mathquill.com/en/latest/Api_Methods/#focus
-     */
-    focus: () => MathFieldInterface;
-
-    /**
-     * Removes focus from the editable field.
-     * http://docs.mathquill.com/en/latest/Api_Methods/#blur
-     */
-    blur: () => MathFieldInterface;
-
-    /**
-     * Write the given LaTeX at the current cursor position. If the
-     * cursor does not have focus, writes to last position the cursor
-     * occupied in the editable field.
-     *
-     * ```
-     * // writes ' - 1' to mathField at the cursor position
-     * mathField.write(' - 1');
-     * ```
-     *
-     * https://docs.mathquill.com/en/latest/Api_Methods/#writelatex_string
-     */
-    write: (latex_string: string) => MathFieldInterface;
-
-    /**
-     * Enter a LaTeX command at the current cursor position or with the
-     * current selection. If the cursor does not have focus, it writes it
-     * to last position the cursor occupied in the editable field.
-     *
-     * ```
-     * // writes a square root command at the cursor position
-     * mathField.cmd('\\sqrt');
-     * ```
-     *
-     * https://docs.mathquill.com/en/latest/Api_Methods/#cmdlatex_string
-     */
-    cmd: (latex_string: string) => MathFieldInterface;
-
-    /**
-     * Selects the contents (just like on textareas and on inputs).
-     *
-     * 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;
-
-    /**
-     * Move the cursor to the left end of the editable field. horthand
-     * for .moveToDirEnd(L)
-     */
-    moveToLeftEnd: () => void;
-
-    /**
-     * Move the cursor to the right end of the editable field. horthand
-     * for .moveToDirEnd(R)
-     */
-    moveToRightEnd: () => void;
-
-    /**
-     * Moves the cursor to the end of the mathfield in the direction
-     * specified. The direction can be one of MQ.L or MQ.R. These are
-     * constants, where MQ.L === -MQ.R and vice versa. This function
-     * may be easier to use than moveToLeftEnd or moveToRightEnd if
-     * used in the moveOutOf handler.
-     *
-     * https://docs.mathquill.com/en/latest/Api_Methods/#movetodirenddirection
-     */
-    moveToDirEnd: (direction: MathQuillDirection) => void;
-
-    /**
-     * Simulates keystrokes given a string like "Ctrl-Home Del", a
-     * whitespace-delimited list of key inputs with optional prefixes.
-     *
-     * ```
-     * mathField.keystroke('Shift-Left'); // Selects character before the current cursor position
-     * ```
-     *
-     * https://docs.mathquill.com/en/latest/Api_Methods/#keystrokekeys
-     */
-    keystroke: (keys: string) => MathFieldInterface;
-
-    /**
-     * Simulates typing text, one character at a time from where the
-     * cursor currently is. This is supposed to be identical to what
-     * would happen if a user were typing the text in.
-     *
-     * Types part of the demo from mathquill.com without delays between keystrokes
-     * ```
-     * mathField.typedText('x=-b\\pm \\sqrt b^2 -4ac');
-     * ```
-     *
-     * https://docs.mathquill.com/en/latest/Api_Methods/#typedtexttext
-     */
-    typedText: (text: string) => MathFieldInterface;
-
-    /**
-     * When called withot any pramaters, gets the contents as LaTeX
-     * When passed a string, sets the contents as LaTeX
-     *
-     * https://docs.mathquill.com/en/latest/Api_Methods/#latex
-     */
-    latex: (input?: string) => string;
-
-    /** Changes the configuration of just this math field. */
-    config: (new_config: MathFieldConfig) => void;
-
-    /**
-     * KA Custom helper in our MathQuill fork check to see if cursor is on
-     * right end
-     */
-    cursorAtRightEnd: () => boolean;
-
-    /**
-     * KA Custom helper in our MathQuill fork check to see if cursor is on left
-     * end
-     */
-    cursorAtLeftEnd: () => boolean;
-
-    /**
-     * This isn't part of the MathQuill public API
-     * I don't know what it is and it feels wrong using it
-     *
-     * @deprecated This is internal and shouldn't be used.
-     */
-    __controller: any;
-}
+export type MathFieldInterface = MathQuill.v3.EditableMathQuill;
 
 export enum MathFieldActionType {
     WRITE = "write",

package/src/components/key-handlers/handle-arrow.ts

@@ -1,7 +1,6 @@
 import {
     maybeFindCommand,
     maybeFindCommandBeforeParens,
-    getCursor,
 } from "../input/mathquill-helpers";
 import {mathQuillInstance} from "../input/mathquill-instance";
 import {MathFieldActionType} from "../input/mathquill-types";
@@ -61,7 +60,7 @@ function handleRightArrow(
 }
 
 export default function handleArrow(mathField: MathFieldInterface, key: Key) {
-    const cursor = getCursor(mathField);
+    const cursor = mathField.cursor();
 
     if (key === "LEFT") {
         handleLeftArrow(mathField, cursor);

package/src/components/key-handlers/handle-backspace.ts

@@ -6,7 +6,6 @@ import {
     isInsideLogIndex,
     isInsideEmptyNode,
     selectNode,
-    getCursor,
     maybeFindCommandBeforeParens,
 } from "../input/mathquill-helpers";
 import {mathQuillInstance} from "../input/mathquill-instance";
@@ -52,7 +51,8 @@ function handleBackspaceInRootIndex(
 
         selectNode(grandparent, cursor);
 
-        const rootIsEmpty = grandparent.blocks[1].jQ.text() === "";
+        const rootIsEmpty =
+            (grandparent.blocks[1]._el as HTMLElement).textContent === "";
 
         if (rootIsEmpty) {
             // If there is not content under the root then simply delete
@@ -70,7 +70,7 @@ function handleBackspaceInRootIndex(
 
             // Adjust the cursor to be to the left the sqrt.
             if (reinsertionPoint === MathFieldActionType.MQ_END) {
-                mathField.moveToDirEnd(mathQuillInstance.L);
+                mathField.moveToLeftEnd();
             } else {
                 cursor.insRightOf(reinsertionPoint);
             }
@@ -107,9 +107,8 @@ function handleBackspaceInLogIndex(
 
         cursor.select();
         cursor.endSelection();
-
         const isLogBodyEmpty =
-            grandparent[mathQuillInstance.R].contentjQ.text() === "";
+            grandparent[mathQuillInstance.R]._el.textContent === "";
 
         if (isLogBodyEmpty) {
             // If there's no content inside the log's parens then delete the
@@ -198,7 +197,7 @@ function handleBackspaceInsideParens(
 
     if (grandparent[mathQuillInstance.L].sub) {
         // if there is a subscript
-        if (grandparent[mathQuillInstance.L].sub.jQ.text()) {
+        if (grandparent[mathQuillInstance.L].sub._el.textContent) {
             // and it contains text
             // move the cursor to the right end of the subscript
             cursor.insAtRightEnd(grandparent[mathQuillInstance.L].sub);
@@ -237,7 +236,7 @@ function handleBackspaceAfterLigaturedSymbol(mathField: MathFieldInterface) {
  * See inline comments for precise behavior of different cases.
  */
 function handleBackspace(mathField: MathFieldInterface) {
-    const cursor = getCursor(mathField);
+    const cursor = mathField.cursor();
     if (!cursor.selection) {
         const parent = cursor.parent;
         const grandparent = parent.parent;

package/src/components/key-handlers/handle-exponent.ts

@@ -1,4 +1,3 @@
-import {getCursor} from "../input/mathquill-helpers";
 import {mathQuillInstance} from "../input/mathquill-instance";
 import {MathFieldActionType} from "../input/mathquill-types";
 
@@ -12,7 +11,7 @@ export default function handleExponent(
     mathField: MathFieldInterface,
     key: Key,
 ) {
-    const cursor = getCursor(mathField);
+    const cursor = mathField.cursor();
     // If there's an invalid operator preceding the cursor (anything that
     // knowingly cannot be raised to a power), add an empty set of
     // parentheses and apply the exponent to that.

package/src/components/key-handlers/handle-jump-out.ts

@@ -3,7 +3,6 @@ import {
     isFraction,
     isParens,
     getCursorContext,
-    getCursor,
 } from "../input/mathquill-helpers";
 import {mathQuillInstance} from "../input/mathquill-instance";
 import {MathFieldActionType} from "../input/mathquill-types";
@@ -24,7 +23,7 @@ const KeysForJumpContext = {
  * Advances the cursor to the next logical position.
  */
 function handleJumpOut(mathField: MathFieldInterface, key: Key): void {
-    const cursor = getCursor(mathField);
+    const cursor = mathField.cursor();
     const context = getCursorContext(mathField);
 
     // Validate that the current cursor context matches the key's intent.

package/src/components/key-handlers/key-translator.ts

@@ -106,7 +106,7 @@ const keyToMathquillMap: Record<Key, MathFieldUpdaterCallback> = {
     },
 
     FRAC_EXCLUSIVE: (mathQuill) => {
-        const cursor = mathQuill.__controller.cursor;
+        const cursor = mathQuill.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 =