katex 0.16.46 → 0.17.0

package/src/defineFunction.ts

@@ -1,24 +1,26 @@
 import type Parser from "./Parser";
-import type {ParseNode, AnyParseNode, NodeType, UnsupportedCmdParseNode}
-    from "./parseNode";
 import type Options from "./Options";
 import type {ArgType, BreakToken} from "./types";
+import type {AnyParseNode, NodeType, ParseNode, UnsupportedCmdParseNode} from "./types/nodes";
 import type {HtmlDomNode} from "./domTree";
 import type {Token} from "./Token";
 import type {MathDomNode} from "./mathMLTree";
 
 /** Context provided to function handlers for error messages. */
-export type FunctionContext = {
-    funcName: string;
+export type FunctionContext<FUNCNAME extends string = string> = {
+    funcName: FUNCNAME;
     parser: Parser;
     token?: Token;
     breakOnTokenText?: BreakToken;
 };
 
-export type FunctionHandler<NODETYPE extends NodeType> = (
-    context: FunctionContext,
+export type FunctionHandler<
+    NODETYPE extends NodeType,
+    FUNCNAME extends string = string,
+> = (
+    context: FunctionContext<FUNCNAME>,
     args: AnyParseNode[],
-    optArgs: (AnyParseNode | null | undefined)[],
+    optArgs: (AnyParseNode | null)[],
 ) => UnsupportedCmdParseNode | ParseNode<NODETYPE>;
 // Note: reverse the order of the return type union will cause a flow error.
 // See https://github.com/facebook/flow/issues/3663.
@@ -34,104 +36,109 @@ export type MathMLBuilder<NODETYPE extends NodeType> =
 export type HtmlBuilderSupSub<NODETYPE extends NodeType> =
     (group: ParseNode<"supsub"> | ParseNode<NODETYPE>, options: Options) => HtmlDomNode;
 
-export type FunctionPropSpec = {
-    // The number of arguments the function takes.
+/**
+ * Parser-facing function spec.  Optional properties should use the defaults
+ * documented below.
+ */
+export type FunctionSpec<
+    NODETYPE extends NodeType,
+    FUNCNAME extends string = string,
+> = {
+    /**
+     * Unique string to differentiate parse nodes.
+     * Also determines the type of the value returned by `handler`.
+     */
+    type: NODETYPE;
+
+    /** The number of arguments the function takes. */
     numArgs: number;
 
-    // An array corresponding to each argument of the function, giving the
-    // type of argument that should be parsed. Its length should be equal
-    // to `numOptionalArgs + numArgs`, and types for optional arguments
-    // should appear before types for mandatory arguments.
+    /**
+     * An array corresponding to each argument of the function, giving the
+     * type of argument that should be parsed. Its length should be equal
+     * to `numOptionalArgs + numArgs`, and types for optional arguments
+     * should appear before types for mandatory arguments.
+     */
     argTypes?: ArgType[];
 
-    // Whether it expands to a single token or a braced group of tokens.
-    // If it's grouped, it can be used as an argument to primitive commands,
-    // such as \sqrt (without the optional argument) and super/subscript.
+    /**
+     * Whether it expands to a single token or a braced group of tokens.
+     * If it's grouped, it can be used as an argument to primitive commands,
+     * such as \sqrt (without the optional argument) and super/subscript.
+     * (default false)
+     */
     allowedInArgument?: boolean;
 
-    // Whether or not the function is allowed inside text mode
-    // (default false)
+    /**
+     * Whether or not the function is allowed inside text mode
+     * (default false)
+     */
     allowedInText?: boolean;
 
-    // Whether or not the function is allowed inside text mode
-    // (default true)
+    /**
+     * Whether or not the function is allowed inside math mode
+     * (default true)
+     */
     allowedInMath?: boolean;
 
-    // (optional) The number of optional arguments the function
-    // should parse. If the optional arguments aren't found,
-    // `null` will be passed to the handler in their place.
-    // (default 0)
+    /**
+     * The number of optional arguments the function should parse. If the
+     * optional arguments aren't found, `null` will be passed to the handler in
+     * their place.
+     * (default 0)
+     */
     numOptionalArgs?: number;
 
-    // Must be true if the function is an infix operator.
+    /** Must be true if the function is an infix operator. */
     infix?: boolean;
 
-    // Whether or not the function is a TeX primitive.
+    /** Whether or not the function is a TeX primitive. */
     primitive?: boolean;
-};
 
-type FunctionDefSpec<NODETYPE extends NodeType> = {
-    // Unique string to differentiate parse nodes.
-    // Also determines the type of the value returned by `handler`.
-    type: NODETYPE;
-
-    // The first argument to defineFunction is a single name or a list of names.
-    // All functions named in such a list will share a single implementation.
-    names: Array<string>;
-
-    // Properties that control how the functions are parsed.
-    props: FunctionPropSpec;
-
-    // The handler is called to handle these functions and their arguments and
-    // returns a `ParseNode`.
-    handler: FunctionHandler<NODETYPE> | null | undefined;
+    /**
+     * The handler is called to handle these functions and their arguments and
+     * returns a `ParseNode`.  It must be specified unless it's handled directly
+     * in the parser.
+     */
+    handler: FunctionHandler<NODETYPE, FUNCNAME> | null | undefined;
+};
 
-    // This function returns an object representing the DOM structure to be
-    // created when rendering the defined LaTeX function.
-    // This should not modify the `ParseNode`.
+/**
+ * Builder fields consumed during registration.  These are stored separately in
+ * `_htmlGroupBuilders` and `_mathmlGroupBuilders`, and are not used by Parser.
+ */
+export type FunctionBuilders<NODETYPE extends NodeType> = {
+    /**
+     * This function returns an object representing the DOM structure to be
+     * created when rendering the defined LaTeX function.
+     * This should not modify the `ParseNode`.
+     */
     htmlBuilder?: HtmlBuilder<NODETYPE>;
 
-    // This function returns an object representing the MathML structure to be
-    // created when rendering the defined LaTeX function.
-    // This should not modify the `ParseNode`.
+    /**
+     * This function returns an object representing the MathML structure to be
+     * created when rendering the defined LaTeX function.
+     * This should not modify the `ParseNode`.
+     */
     mathmlBuilder?: MathMLBuilder<NODETYPE>;
 };
 
 /**
- * Final function spec for use at parse time.
- * This is almost identical to `FunctionPropSpec`, except it
- * 1. includes the function handler, and
- * 2. requires all arguments except argTypes.
- * It is generated by `defineFunction()` below.
+ * Full registration spec passed to `defineFunction`.  It combines the
+ * parser-facing fields with optional builder fields and the names being
+ * registered.
  */
-export type FunctionSpec<NODETYPE extends NodeType> = {
-    type: NODETYPE; // Need to use the type to avoid error. See NOTES below.
-    numArgs: number;
-    argTypes?: ArgType[];
-    allowedInArgument: boolean;
-    allowedInText: boolean;
-    allowedInMath: boolean;
-    numOptionalArgs: number;
-    infix: boolean;
-    primitive: boolean;
-
-    // FLOW TYPE NOTES: Doing either one of the following two
-    //
-    // - removing the NODETYPE type parameter in FunctionSpec above;
-    // - using ?FunctionHandler<NODETYPE> below;
-    //
-    // results in a confusing flow typing error:
-    //   "string literal `styling`. This type is incompatible with..."
-    // pointing to the definition of `defineFunction` and finishing with
-    //   "some incompatible instantiation of `NODETYPE`"
-    //
-    // Having FunctionSpec<NODETYPE> above and FunctionHandler<*> below seems to
-    // circumvent this error. This is not harmful for catching errors since
-    // _functions is typed FunctionSpec<*> (it stores all TeX function specs).
-
-    // Must be specified unless it's handled directly in the parser.
-    handler: FunctionHandler<NodeType> | null | undefined;
-};
+type FunctionDefSpec<
+    NODETYPE extends NodeType,
+    NAMES extends readonly string[],
+> =
+    FunctionSpec<NODETYPE, NAMES[number]> & FunctionBuilders<NODETYPE> & {
+        /**
+         * The first argument to defineFunction is a single name or a list of names.
+         * All functions named in such a list will share a single implementation.
+         */
+        names: NAMES;
+    };
 
 /**
  * All registered functions.
@@ -159,30 +166,17 @@ export const _htmlGroupBuilders: Record<string, HtmlBuilder<any>> = {};
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const _mathmlGroupBuilders: Record<string, MathMLBuilder<any>> = {};
 
-export default function defineFunction<NODETYPE extends NodeType>({
-    type,
-    names,
-    props,
-    handler,
-    htmlBuilder,
-    mathmlBuilder,
-}: FunctionDefSpec<NODETYPE>) {
-    // Set default values of functions
-    const data = {
-        type,
-        numArgs: props.numArgs,
-        argTypes: props.argTypes,
-        allowedInArgument: !!props.allowedInArgument,
-        allowedInText: !!props.allowedInText,
-        allowedInMath: (props.allowedInMath === undefined)
-            ? true
-            : props.allowedInMath,
-        numOptionalArgs: props.numOptionalArgs || 0,
-        infix: !!props.infix,
-        primitive: !!props.primitive,
-        handler,
-    };
+export default function defineFunction<
+    NODETYPE extends NodeType,
+    const NAMES extends readonly string[],
+>(
+    data: FunctionDefSpec<NODETYPE, NAMES>,
+) {
+    const {type, names, htmlBuilder, mathmlBuilder} = data;
     for (let i = 0; i < names.length; ++i) {
+        // To avoid destructuring and rebuilding an object,
+        // we store the entire FunctionDefSpec object,
+        // even though Parser only needs the FunctionSpec fields.
         _functions[names[i]] = data;
     }
     if (type) {
@@ -207,14 +201,12 @@ export function defineFunctionBuilders<NODETYPE extends NodeType>({
     htmlBuilder?: HtmlBuilder<NODETYPE>;
     mathmlBuilder: MathMLBuilder<NODETYPE>;
 }) {
-    defineFunction({
-        type,
-        names: [],
-        props: {numArgs: 0},
-        handler() { throw new Error('Should never be called.'); },
-        htmlBuilder,
-        mathmlBuilder,
-    });
+    if (htmlBuilder) {
+        _htmlGroupBuilders[type] = htmlBuilder;
+    }
+    if (mathmlBuilder) {
+        _mathmlGroupBuilders[type] = mathmlBuilder;
+    }
 }
 
 export const normalizeArgument = function(arg: AnyParseNode): AnyParseNode {

package/src/environments/array.ts

@@ -15,8 +15,8 @@ import * as html from "../buildHTML";
 import * as mml from "../buildMathML";
 
 import type Parser from "../Parser";
-import type {ParseNode, AnyParseNode} from "../parseNode";
 import type {StyleStr, Mode} from "../types";
+import type {AnyParseNode, ParseNode} from "../types/nodes";
 import type {HtmlBuilder, MathMLBuilder} from "../defineFunction";
 import type {HtmlDomNode} from "../domTree";
 
@@ -703,7 +703,6 @@ const alignedHandler = function(context: EnvContextLike, args: AnyParseNode[]) {
         validateAmsEnvironmentContext(context);
     }
     const cols: AlignSpec[] = [];
-    const separationType: ColSeparationType = context.envName.includes("at") ? "alignat" : "align";
     const isSplit = context.envName === "split";
     const res = parseArray(context.parser,
         {
@@ -711,7 +710,7 @@ const alignedHandler = function(context: EnvContextLike, args: AnyParseNode[]) {
             addJot: true,
             autoTag: isSplit ? undefined : getAutoTag(context.envName),
             emptySingleRow: true,
-            colSeparationType: separationType,
+            colSeparationType: context.envName.includes("at") ? "alignat" : "align",
             maxNumCols: isSplit ? 2 : undefined,
             leqno: context.parser.settings.leqno,
         },
@@ -893,8 +892,7 @@ defineEnvironment({
                 payload.cols = [{type: "align", align: colAlign}];
             }
         }
-        const res: ParseNode<"array"> =
-            parseArray(context.parser, payload, dCellStyle(context.envName));
+        const res = parseArray(context.parser, payload, dCellStyle(context.envName));
         // Populate cols with the correct number of column alignment specs.
         const numCols = Math.max(0, ...res.body.map(row => row.length));
         res.cols = new Array(numCols).fill(
@@ -1006,8 +1004,7 @@ defineEnvironment({
                 postgap: 0,
             }],
         };
-        const res: ParseNode<"array"> =
-            parseArray(context.parser, payload, dCellStyle(context.envName));
+        const res = parseArray(context.parser, payload, dCellStyle(context.envName));
         return {
             type: "leftright",
             mode: context.mode,
@@ -1124,11 +1121,10 @@ defineMacro("\\notag", "\\nonumber");
 defineFunction({
     type: "text", // Doesn't matter what this is.
     names: ["\\hline", "\\hdashline"],
-    props: {
-        numArgs: 0,
-        allowedInText: true,
-        allowedInMath: true,
-    },
+    numArgs: 0,
+    allowedInText: true,
+    allowedInMath: true,
+
     handler(context, args) {
         throw new ParseError(
             `${context.funcName} valid only within array environment`);

package/src/environments/cd.ts

@@ -8,7 +8,8 @@ import ParseError from "../ParseError";
 import {makeEm} from "../units";
 
 import type Parser from "../Parser";
-import type {ParseNode, AnyParseNode} from "../parseNode";
+import type {AnyParseNode, ParseNode} from "../types/nodes";
+import type {Slice4} from "../types";
 
 const cdArrowFunctionName: Record<string, string> = {
     ">": "\\\\cdrightarrow",
@@ -247,17 +248,16 @@ export function parseCD(parser: Parser): ParseNode<"array"> {
 defineFunction({
     type: "cdlabel",
     names: ["\\\\cdleft", "\\\\cdright"],
-    props: {
-        numArgs: 1,
-    },
+    numArgs: 1,
     handler({parser, funcName}, args) {
         return {
             type: "cdlabel",
             mode: parser.mode,
-            side: funcName.slice(4),
+            side: funcName.slice(4) as Slice4<typeof funcName>,
             label: args[0],
         };
     },
+
     htmlBuilder(group, options) {
         const newOptions = options.havingStyle(options.style.sup());
         const label = wrapFragment(
@@ -291,9 +291,8 @@ defineFunction({
 defineFunction({
     type: "cdlabelparent",
     names: ["\\\\cdparent"],
-    props: {
-        numArgs: 1,
-    },
+    numArgs: 1,
+
     handler({parser}, args) {
         return {
             type: "cdlabelparent",
@@ -301,6 +300,7 @@ defineFunction({
             fragment: args[0],
         };
     },
+
     htmlBuilder(group, options) {
         // Wrap the vertical arrow and its labels.
         // The parent gets position: relative. The child gets position: absolute.

package/src/functions/accent.ts

@@ -10,9 +10,9 @@ import {makeEm} from "../units";
 import * as html from "../buildHTML";
 import * as mml from "../buildMathML";
 
-import type {ParseNode, AnyParseNode} from "../parseNode";
 import type {HtmlBuilderSupSub, MathMLBuilder} from "../defineFunction";
 import type {HtmlDomNode} from "../domTree";
+import type {AnyParseNode, ParseNode} from "../types/nodes";
 
 const getBaseSymbol = (group: HtmlDomNode): SymbolNode | undefined => {
     if (group instanceof SymbolNode) {
@@ -100,7 +100,7 @@ export const htmlBuilder: HtmlBuilderSupSub<"accent"> = (grp, options) => {
             width = svgData.vec[1];
         } else {
             accent = makeOrd({type: "textord", mode: group.mode, text: group.label},
-                options, "textord");
+                options);
             accent = assertSymbolDomNode(accent);
             // Remove the italic correction of the accent, because it only serves to
             // shift the accent over to a place we don't want.
@@ -223,9 +223,8 @@ defineFunction({
         "\\Overrightarrow", "\\overleftrightarrow", "\\overgroup",
         "\\overlinesegment", "\\overleftharpoon", "\\overrightharpoon",
     ],
-    props: {
-        numArgs: 1,
-    },
+    numArgs: 1,
+
     handler: (context, args) => {
         const base = normalizeArgument(args[0]);
 
@@ -244,6 +243,7 @@ defineFunction({
             base: base,
         };
     },
+
     htmlBuilder,
     mathmlBuilder,
 });
@@ -255,12 +255,11 @@ defineFunction({
         "\\'", "\\`", "\\^", "\\~", "\\=", "\\u", "\\.", '\\"',
         "\\c", "\\r", "\\H", "\\v", "\\textcircled",
     ],
-    props: {
-        numArgs: 1,
-        allowedInText: true,
-        allowedInMath: true, // unless in strict mode
-        argTypes: ["primitive"],
-    },
+    numArgs: 1,
+    allowedInText: true,
+    allowedInMath: true, // unless in strict mode
+    argTypes: ["primitive"],
+
     handler: (context, args) => {
         const base = args[0];
         let mode = context.parser.mode;
@@ -280,6 +279,4 @@ defineFunction({
             base: base,
         };
     },
-    htmlBuilder,
-    mathmlBuilder,
 });

package/src/functions/accentunder.ts

@@ -7,7 +7,7 @@ import {stretchyMathML, stretchySvg} from "../stretchy";
 import * as html from "../buildHTML";
 import * as mml from "../buildMathML";
 
-import type {ParseNode} from "../parseNode";
+import type {ParseNode} from "../types/nodes";
 
 defineFunction({
     type: "accentUnder",
@@ -15,9 +15,8 @@ defineFunction({
         "\\underleftarrow", "\\underrightarrow", "\\underleftrightarrow",
         "\\undergroup", "\\underlinesegment", "\\utilde",
     ],
-    props: {
-        numArgs: 1,
-    },
+    numArgs: 1,
+
     handler: ({parser, funcName}, args) => {
         const base = args[0];
         return {
@@ -27,6 +26,7 @@ defineFunction({
             base: base,
         };
     },
+
     htmlBuilder: (group: ParseNode<"accentUnder">, options) => {
         // Treat under accents much like underlines.
         const innerGroup = html.buildGroup(group.base, options);

package/src/functions/arrow.ts

@@ -6,7 +6,7 @@ import {stretchyMathML, stretchySvg} from "../stretchy";
 import * as html from "../buildHTML";
 import * as mml from "../buildMathML";
 
-import type {ParseNode} from "../parseNode";
+import type {ParseNode} from "../types/nodes";
 import type {MathDomNode} from "../mathMLTree";
 
 // Helper function
@@ -33,10 +33,9 @@ defineFunction({
         // The next 3 functions are here only to support the {CD} environment.
         "\\\\cdrightarrow", "\\\\cdleftarrow", "\\\\cdlongequal",
     ],
-    props: {
-        numArgs: 1,
-        numOptionalArgs: 1,
-    },
+    numArgs: 1,
+    numOptionalArgs: 1,
+
     handler({parser, funcName}, args, optArgs) {
         return {
             type: "xArrow",
@@ -46,6 +45,7 @@ defineFunction({
             below: optArgs[0],
         };
     },
+
     htmlBuilder(group: ParseNode<"xArrow">, options) {
         const style = options.style;
 

package/src/functions/char.ts

@@ -8,10 +8,9 @@ import {assertNodeType} from "../parseNode";
 defineFunction({
     type: "textord",
     names: ["\\@char"],
-    props: {
-        numArgs: 1,
-        allowedInText: true,
-    },
+    numArgs: 1,
+    allowedInText: true,
+
     handler({parser}, args) {
         const arg = assertNodeType(args[0], "ordgroup");
         const group = arg.body;

package/src/functions/color.ts

@@ -2,7 +2,7 @@ import defineFunction, {ordargument} from "../defineFunction";
 import {makeFragment} from "../buildCommon";
 import {MathNode} from "../mathMLTree";
 import {assertNodeType} from "../parseNode";
-import type {AnyParseNode} from "../parseNode";
+import type {AnyParseNode} from "../types/nodes";
 import type {HtmlBuilder, MathMLBuilder} from "../defineFunction";
 
 import * as html from "../buildHTML";
@@ -36,11 +36,10 @@ const mathmlBuilder: MathMLBuilder<"color"> = (group, options) => {
 defineFunction({
     type: "color",
     names: ["\\textcolor"],
-    props: {
-        numArgs: 2,
-        allowedInText: true,
-        argTypes: ["color", "original"],
-    },
+    numArgs: 2,
+    allowedInText: true,
+    argTypes: ["color", "original"],
+
     handler({parser}, args) {
         const color = assertNodeType(args[0], "color-token").color;
         const body = args[1];
@@ -51,6 +50,7 @@ defineFunction({
             body: (ordargument(body) as AnyParseNode[]),
         };
     },
+
     htmlBuilder,
     mathmlBuilder,
 });
@@ -58,11 +58,10 @@ defineFunction({
 defineFunction({
     type: "color",
     names: ["\\color"],
-    props: {
-        numArgs: 1,
-        allowedInText: true,
-        argTypes: ["color"],
-    },
+    numArgs: 1,
+    allowedInText: true,
+    argTypes: ["color"],
+
     handler({parser, breakOnTokenText}, args) {
         const color = assertNodeType(args[0], "color-token").color;
 
@@ -82,6 +81,4 @@ defineFunction({
             body,
         };
     },
-    htmlBuilder,
-    mathmlBuilder,
 });

package/src/functions/cr.ts

@@ -10,11 +10,9 @@ import {assertNodeType} from "../parseNode";
 defineFunction({
     type: "cr",
     names: ["\\\\"],
-    props: {
-        numArgs: 0,
-        numOptionalArgs: 0,
-        allowedInText: true,
-    },
+    numArgs: 0,
+    numOptionalArgs: 0,
+    allowedInText: true,
 
     handler({parser}, args, optArgs) {
         const size = parser.gullet.future().text === "[" ?

package/src/functions/def.ts

@@ -62,10 +62,9 @@ defineFunction({
         "\\global", "\\long",
         "\\\\globallong", // can’t be entered directly
     ],
-    props: {
-        numArgs: 0,
-        allowedInText: true,
-    },
+    numArgs: 0,
+    allowedInText: true,
+
     handler({parser, funcName}) {
         parser.consumeSpaces();
         const token = parser.fetch();
@@ -87,11 +86,10 @@ defineFunction({
 defineFunction({
     type: "internal",
     names: ["\\def", "\\gdef", "\\edef", "\\xdef"],
-    props: {
-        numArgs: 0,
-        allowedInText: true,
-        primitive: true,
-    },
+    numArgs: 0,
+    allowedInText: true,
+    primitive: true,
+
     handler({parser, funcName}) {
         let tok = parser.gullet.popToken();
         const name = tok.text;
@@ -168,11 +166,10 @@ defineFunction({
         "\\let",
         "\\\\globallet", // can’t be entered directly
     ],
-    props: {
-        numArgs: 0,
-        allowedInText: true,
-        primitive: true,
-    },
+    numArgs: 0,
+    allowedInText: true,
+    primitive: true,
+
     handler({parser, funcName}) {
         const name = checkControlSequence(parser.gullet.popToken());
         parser.gullet.consumeSpaces();
@@ -192,11 +189,10 @@ defineFunction({
         "\\futurelet",
         "\\\\globalfuture", // can’t be entered directly
     ],
-    props: {
-        numArgs: 0,
-        allowedInText: true,
-        primitive: true,
-    },
+    numArgs: 0,
+    allowedInText: true,
+    primitive: true,
+
     handler({parser, funcName}) {
         const name = checkControlSequence(parser.gullet.popToken());
         const middle = parser.gullet.popToken();