feat: optional vertical alignment [t|b|c] for array and aligned environments

[edemaine]

What is the previous behavior before this PR?
\begin{array} and \begin{aligned} rendered any optional argument like [t].

What is the new behavior after this PR?
Matching LaTeX, \begin{array}, \begin{darray}, \begin{aligned}, \begin{alignedat}, \begin{gathered} (but not \begin{align}, \begin{alignat}, \begin{equation}, \begin{gather}, \begin{split} and starred variants, \begin{matrix} and variants, \begin{smallmatrix}, \begin{cases}) support custom vertical alignment via [t], [b], or [c] optional argument.

At least, that's the goal. I haven't been able to test this yet, or write tests, because of #3189, but I theorize that it or a slight variation will work.

Optional arguments in environments: Along the way, I had to add support for optional arguments in environments, which was silently ignored before. This only gets used in \begin{alignedat}[t]{2} because the optional argument is in the "correct" position before the required argument. We can't use it (without some modification) in \begin{array}{cc}[t] because the optional argument comes later. Turns out I was wrong, and the correct order is \begin{array}[t]{cc}, so I can use the optional argument parser in all cases.

Demo:

BREAKING CHANGE: Optional arguments used to be rendered in aligned environments, but now they are correctly processed (as they would in LaTeX). This is arguably a bug fix, but could break existing code like

\begin{aligned}
[hello] & [world] \\
\end{aligned}

Fixes #2172, fixes #2760

[codecov-commenter]

Codecov Report

Merging #3190 (24957a4) into master (610feae) will increase coverage by 0.03%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #3190      +/-   ##
==========================================
+ Coverage   93.94%   93.97%   +0.03%     
==========================================
  Files          87       88       +1     
  Lines        6344     6362      +18     
  Branches     1314     1320       +6     
==========================================
+ Hits         5960     5979      +19     
+ Misses        354      353       -1     
  Partials       30       30              

Impacted Files	Coverage Δ
src/environments/cd.js	99.15% <ø> (ø)
src/parseNode.js	73.33% <ø> (ø)
src/defineEnvironment.js	100.00% <100.00%> (ø)
src/environments/array.js	98.61% <100.00%> (+0.29%)	⬆️
src/macros.js	97.27% <0.00%> (-0.02%)	⬇️
src/defineMacro.js	100.00% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 610feae...24957a4. Read the comment docs.

[ronkok]

This is good stuff. It should get recognized in the documentation. Suggest modification of supported.md file:

In the Other KaTeX Environments table, to the row labeled gathered, etc., insert a line .".. take an optional argument [t|b|c] to set vertical alignment."

Revise one example environment to read

\def\arraystretch{1.5}
\begin{array}[c]{r|c:l}
   ab & c & de \\ \hline
   f  & g & h \\ \hdashline
   i  & j & k
\end{array}

There is a sentence that begins: "The {array} environment supports | ... ." It's an unusual sentence for this document, which doesn't do much explanation. The document just enumerates every KaTeX function and shows a working example of each. So that sentence is out of sync with the rest of the document. It should be either deleted or augmented with the {darray} environment and the new optional argument. I would be okay with either choice.

[pzinn]

it would be nice if this got approved!

[pzinn]

actually, I applied the patch and it doesn't seem to work too well for me:

$X=\begin{array}[t]{cc} 1 & 2 \\ 3 & 4\end{array}$

produces this: