feat: Support matrix*, pmatrix*, bmatrix*, Bmatrix*, vmatrix*, and Vmatrix*. (#2488)

* Support matrix*, pmatrix*, bmatrix*, Bmatrix*, vmatrix*, and Vmatrix*

* Add tests and docs

* Delete screeshotter tests

* Fix column alignment and add bogus screenshot files

* Update real Chrome and Firefox screenshots.

* Update Safari screenshot

* Dedupe code in array.js

* Edit payload in array.js

* Edit again, correctly this time.

docs/support_table.md

@@ -174,7 +174,9 @@ table td {
 |\blacktriangleright|$\blacktriangleright$||
 |\bm|$\bm{AaBb}$|`\bm{AaBb}`|
 |{Bmatrix}|$\begin{Bmatrix}a&b\\c&d\end{Bmatrix}$|`\begin{Bmatrix}`<br>&nbsp;&nbsp;&nbsp;`a & b \\`<br>&nbsp;&nbsp;&nbsp;`c & d`<br>`\end{Bmatrix}`|
+|{Bmatrix*}|$\begin{Bmatrix*}[r]0&-1\\-1&0\end{Bmatrix*}$|`\begin{Bmatrix*}[r]`<br>&nbsp;&nbsp;&nbsp;`0 & -1 \\`<br>&nbsp;&nbsp;&nbsp;`-1 & 0`<br>`\end{Bmatrix*}`|
 |{bmatrix}|$\begin{bmatrix}a&b\\c&d\end{bmatrix}$|`\begin{bmatrix}`<br>&nbsp;&nbsp;&nbsp;`a & b \\`<br>&nbsp;&nbsp;&nbsp;`c & d`<br>`\end{bmatrix}`|
+|{bmatrix*}|$\begin{bmatrix*}[r]0&-1\\-1&0\end{bmatrix*}$|`\begin{bmatrix*}[r]`<br>&nbsp;&nbsp;&nbsp;`0 & -1 \\`<br>&nbsp;&nbsp;&nbsp;`-1 & 0`<br>`\end{bmatrix*}`|
 |\bmod|$a \bmod b$|`a \bmod b`|
 |\bold|$\bold{AaBb123}$|`\bold{AaBb123}`|
 |\boldsymbol|$\boldsymbol{AaBb}$|`\boldsymbol{AaBb}`|
@@ -664,6 +666,7 @@ use `\ce` instead|
 |\mathtt|$\mathtt{AaBb123}$|`\mathtt{AaBb123}`|
 |\matrix|<span style="color:firebrick;">Not supported</span>|See `{matrix}`|
 |{matrix}|$\begin{matrix}a&b\\c&d\end{matrix}$|`\begin{matrix}`<br>&nbsp;&nbsp;&nbsp;`a & b \\`<br>&nbsp;&nbsp;&nbsp;`c & d`<br>`\end{matrix}`|
+|{matrix*}|$\begin{matrix*}[r]0&-1\\-1&0\end{matrix*}$|`\begin{matrix*}[r]`<br>&nbsp;&nbsp;&nbsp;`0 & -1 \\`<br>&nbsp;&nbsp;&nbsp;`-1 & 0`<br>`\end{matrix*}`|
 |\max|$\max$||
 |\mbox|<span style="color:firebrick;">Not supported</span>||
 |\md|<span style="color:firebrick;">Not supported</span>||
@@ -828,6 +831,7 @@ use `\ce` instead|
 |\pm|$\pm$||
 |\pmatrix|<span style="color:firebrick;">Not supported</span>|See `{pmatrix}`|
 |{pmatrix}|$\begin{pmatrix}a&b\\c&d\end{pmatrix}$|`\begin{pmatrix}`<br>&nbsp;&nbsp;&nbsp;`a & b \\`<br>&nbsp;&nbsp;&nbsp;`c & d`<br>`\end{pmatrix}`
+|{pmatrix*}|$\begin{pmatrix*}[r]0&-1\\-1&0\end{pmatrix*}$|`\begin{pmatrix*}[r]`<br>&nbsp;&nbsp;&nbsp;`0 & -1 \\`<br>&nbsp;&nbsp;&nbsp;`-1 & 0`<br>`\end{pmatrix*}`|
 |\pmb|$\pmb{\mu}$|`\pmb{\mu}`|
 |\pmod|$x\pmod a$|`x\pmod a`|
 |\pod|$x \pod a$|`x \pod a`|
@@ -1187,7 +1191,9 @@ use `\ce` instead|
 |\vfill|<span style="color:firebrick;">Not supported</span>||
 |\vline|<span style="color:firebrick;">Not supported</span>|[Issue #269](https://github.com/KaTeX/KaTeX/issues/269)|
 |{Vmatrix}|$\begin{Vmatrix}a&b\\c&d\end{Vmatrix}$|`\begin{Vmatrix}`<br>&nbsp;&nbsp;&nbsp;`a & b \\`<br>&nbsp;&nbsp;&nbsp;`c & d`<br>`\end{Vmatrix}`|
+|{Vmatrix*}|$\begin{Vmatrix*}[r]0&-1\\-1&0\end{Vmatrix*}$|`\begin{Vmatrix*}[r]`<br>&nbsp;&nbsp;&nbsp;`0 & -1 \\`<br>&nbsp;&nbsp;&nbsp;`-1 & 0`<br>`\end{Vmatrix*}`|
 |{vmatrix}|$\begin{vmatrix}a&b\\c&d\end{vmatrix}$|`\begin{vmatrix}`<br>&nbsp;&nbsp;&nbsp;`a & b \\`<br>&nbsp;&nbsp;&nbsp;`c & d`<br>`\end{vmatrix}`|
+|{vmatrix*}|$\begin{vmatrix*}[r]0&-1\\-1&0\end{vmatrix*}$|`\begin{vmatrix*}[r]`<br>&nbsp;&nbsp;&nbsp;`0 & -1 \\`<br>&nbsp;&nbsp;&nbsp;`-1 & 0`<br>`\end{vmatrix*}`|
 |\vphantom|$\overline{\vphantom{M}a}$|`\overline{\vphantom{M}a}`|
 |\Vvdash|$\Vvdash$||
 

docs/supported.md

@@ -93,7 +93,9 @@ $( \big( \Big( \bigg( \Bigg($ `( \big( \Big( \bigg( \Bigg(`
 
 </div>
 
-KaTeX also supports `darray`, `dcases`, and `drcases`.
+KaTeX also supports `darray`, `dcases`, and `drcases`, which apply `displaystyle`.
+
+And KaTeX supports `matrix*`, `pmatrix*`, `bmatrix*`, `Bmatrix*`, `vmatrix*`, and `Vmatrix*`, which take an optional argument to set column alignment, as in `\begin{matrix}[1]`, `\begin{matrix}[c]`, or `\begin{matrix}[r]`.
 
 Acceptable line separators include: `\\`, `\cr`, `\\[distance]`, and `\cr[distance]`. *Distance* can be written with any of the [KaTeX units](#units).
 

src/environments/array.js

@@ -754,6 +754,8 @@ defineEnvironment({
 
 // The matrix environments of amsmath builds on the array environment
 // of LaTeX, which is discussed above.
+// The mathtools package adds starred versions of the same environments.
+// These have an optional argument to choose left|center|right justification.
 defineEnvironment({
     type: "array",
     names: [
@@ -763,6 +765,12 @@ defineEnvironment({
         "Bmatrix",
         "vmatrix",
         "Vmatrix",
+        "matrix*",
+        "pmatrix*",
+        "bmatrix*",
+        "Bmatrix*",
+        "vmatrix*",
+        "Vmatrix*",
     ],
     props: {
         numArgs: 0,
@@ -775,11 +783,38 @@ defineEnvironment({
             "Bmatrix": ["\\{", "\\}"],
             "vmatrix": ["|", "|"],
             "Vmatrix": ["\\Vert", "\\Vert"],
-        }[context.envName];
+        }[context.envName.replace("*", "")];
         // \hskip -\arraycolsep in amsmath
-        const payload = {hskipBeforeAndAfter: false};
+        let colAlign = "c";
+        const payload = {
+            hskipBeforeAndAfter: false,
+            cols: [{type: "align", align: colAlign}],
+        };
+        if (context.envName.charAt(context.envName.length - 1) === "*") {
+            // It's one of the mathtools starred functions.
+            // Parse the optional alignment argument.
+            const parser = context.parser;
+            parser.consumeSpaces();
+            if (parser.fetch().text === "[") {
+                parser.consume();
+                parser.consumeSpaces();
+                colAlign = parser.fetch().text;
+                if ("lcr".indexOf(colAlign) === -1) {
+                    throw new ParseError("Expected l or c or r", parser.nextToken);
+                }
+                parser.consume();
+                parser.consumeSpaces();
+                parser.expect("]");
+                parser.consume();
+                payload.cols = [{type: "align", align: colAlign}];
+            }
+        }
         const res: ParseNode<"array"> =
             parseArray(context.parser, payload, dCellStyle(context.envName));
+        // Populate cols with the correct number of column alignment specs.
+        res.cols = new Array(res.body[0].length).fill(
+            {type: "align", align: colAlign}
+        );
         return delimiters ? {
             type: "leftright",
             mode: context.mode,

test/__snapshots__/katex-spec.js.snap

@@ -115,6 +115,16 @@ exports[`A begin/end parser should grab \\arraystretch 1`] = `
         }
       ]
     ],
+    "cols": [
+      {
+        "type": "align",
+        "align": "c"
+      },
+      {
+        "type": "align",
+        "align": "c"
+      }
+    ],
     "hLinesBeforeRow": [
       [
       ],

test/katex-spec.js

@@ -1300,6 +1300,17 @@ describe("A begin/end parser", function() {
         const parse = getParsed`\def\arraystretch{1.5}\begin{matrix}a&b\\c&d\end{matrix}`;
         expect(parse).toMatchSnapshot();
     });
+
+    it("should allow an optional argument in {matrix*} and company.", function() {
+        expect("\\begin{matrix*}[r] a & -1 \\\\ -1 & d \\end{matrix*}").toBuild();
+        expect("\\begin{pmatrix*}[r] a & -1 \\\\ -1 & d \\end{pmatrix*}").toBuild();
+        expect("\\begin{bmatrix*}[r] a & -1 \\\\ -1 & d \\end{bmatrix*}").toBuild();
+        expect("\\begin{Bmatrix*}[r] a & -1 \\\\ -1 & d \\end{Bmatrix*}").toBuild();
+        expect("\\begin{vmatrix*}[r] a & -1 \\\\ -1 & d \\end{vmatrix*}").toBuild();
+        expect("\\begin{Vmatrix*}[r] a & -1 \\\\ -1 & d \\end{Vmatrix*}").toBuild();
+        expect("\\begin{matrix*} a & -1 \\\\ -1 & d \\end{matrix*}").toBuild();
+        expect("\\begin{matrix*}[] a & -1 \\\\ -1 & d \\end{matrix*}").not.toParse();
+    });
 });
 
 describe("A sqrt parser", function() {

test/screenshotter/ss_data.yaml

@@ -244,6 +244,7 @@ MathOp: a\mathop+b\mathop:c\mathop{\delta}e\mathop{\textrm{and}}f\mathrel{\matho
 MathRm: \mathrm{Ax2k\breve{a}\omega\Omega\imath+\KaTeX}
 MathSf: \mathsf{Ax2k\breve{a}\omega\Omega\imath+\KaTeX}
 MathScr: \mathscr{Ax2k\breve{a}\omega\Omega\imath+\KaTeX}
+MathtoolsMatrix: \begin{matrix*}[l] a & -1 \\ -1 & d \end{matrix*} \; \begin{pmatrix*}[r] a & -1 \\ -1 & d \end{pmatrix*}
 MathTt: \mathtt{Ax2k\breve{a}\omega\Omega\imath+\KaTeX}
 Mod: |
     \begin{array}{cc}