feat(math): implement m:nary n-ary operator converter (#2752)

* feat(math): implement m:nary n-ary operator converter (closes #2602)

Made-with: Cursor

* fix(math): parse full ST_OnOff values in nary converter

Made-with: Cursor

* fix(math): spec-compliant m:nary defaults + fill missing naryPr props (SD-2381)

- m:limLoc (§22.1.2.53): absent element now uses operator-character
  heuristic — integrals default to subSup, non-integrals to undOvr.
  <m:limLoc/> with no val attribute defaults to undOvr per spec.
- m:sub/m:sup (§22.1.2.70): treat as actually absent when the element
  is missing, not just when a hide flag is set — indefinite integrals
  now render as bare <mo> instead of <msubsup> with empty <mrow/> slots.
- m:chr (§22.1.2.20): <m:chr/> with no val renders an empty operator
  instead of silently defaulting to the integral glyph.
- m:grow (§22.1.2.72): when explicitly OFF, emit largeop="false"
  stretchy="false" on the <mo> so the renderer doesn't enlarge.
- Helper type is OmmlJsonNode (no more typeof subHide). JSDoc documents
  all 6 output shapes.

Tests:
- 10 new unit tests in omml-to-mathml.test.ts covering every ECMA-376
  spec path for m:nary (subHide true/bare/OFF, limLoc no-val, chr no-val,
  operator heuristic, m:grow suppression, etc).
- New behavior fixture math-nary-tests.docx (13 scenarios) + 9 Playwright
  tests in math-equations.spec.ts. Fixture uploaded to the shared R2
  corpus as rendering/sd-2381-nary-scenarios.docx for layout/visual.

* fix(math): subHide/supHide only hide empty placeholders, not content (SD-2381)

Per ECMA-376 §22.1.2.72, the subHide/supHide flags control whether EMPTY
m:sub/m:sup limits are rendered as a placeholder character or hidden.
When the limit has content, it must always be rendered regardless of
the flag — matching Word's actual behavior.

Previous code hid the entire slot whenever the hide flag was ON, which
silently dropped content. For example, an integral with sub="0", sup="1",
and subHide=true was rendering as ∫¹ instead of ∫₀¹.

- hasSub/hasSup now check meaningful content (ignoring m:ctrlPr, the
  formatting-hint child Word emits inside empty limit elements).
- The hide flag only suppresses the slot when the limit is empty/absent.
- Updated 3 unit tests that encoded the incorrect semantics; added a new
  regression test for "content overrides hide" and a test confirming
  m:ctrlPr-only limits are treated as empty.
- Updated the behavior test for the same scenarios.

* fix(math): promote hidden limit content into opposite slot (matches Word)

Follow-up to the previous subHide/supHide fix. When m:subHide is ON and
m:sub has content, Word doesn't simply suppress the slot — it promotes
the sub content into the sup slot, prepended to any existing sup content
(symmetric for supHide: sup content appended to sub). This preserves any
author-entered content even when a file is hand-crafted with conflicting
hide+content OMML.

Before: an integral with m:sub="0", m:sup="1", m:subHide="true" rendered
as <msubsup><mo>∫</mo><mrow>0</mrow><mrow>1</mrow></msubsup> (∫ with 0
below and 1 above — stacked).

After: renders as <msup><mo>∫</mo><mrow>01</mrow></msup>, matching
Word's ∫^{01} where 0 appears to the left of 1 in the superscript.

- Compute renderSubChildren / renderSupChildren with promotion, then pass
  those arrays to convertChildren.
- Strip m:ctrlPr before the check so Word's "empty with formatting hint"
  pattern still resolves to bare <mo>.
- Replaced the "content always wins over hide" unit test with two tests
  anchoring the promotion (sub→sup, sup→sub).
- Updated the behavior test for scenarios 8/9 to assert msup with "01".

---------

Co-authored-by: Caio Pizzol <caiopizzol@icloud.com>
Co-authored-by: Caio Pizzol <caio@harbourshare.com>

Author: 3 people

packages/layout-engine/painters/dom/src/features/math/converters/index.ts

@@ -20,3 +20,4 @@ export { convertEquationArray } from './equation-array.js';
 export { convertRadical } from './radical.js';
 export { convertLowerLimit } from './lower-limit.js';
 export { convertUpperLimit } from './upper-limit.js';
+export { convertNary } from './nary.js';

packages/layout-engine/painters/dom/src/features/math/converters/nary.ts

@@ -0,0 +1,150 @@
+import type { MathObjectConverter, OmmlJsonNode } from '../types.js';
+
+const MATHML_NS = 'http://www.w3.org/1998/Math/MathML';
+
+/** Default n-ary operator character when m:chr is absent: integral sign (∫, U+222B). */
+const DEFAULT_NARY_CHAR = '\u222B';
+
+/**
+ * Integral-like operators (∫∬∭∮∯∰∱∲∳), which default to side-limits (subSup).
+ * Non-integrals (∑, ∏, ⋃, ...) default to under/over limits (undOvr) in display mode.
+ */
+const INTEGRAL_CHARS = /^[\u222B-\u2233]$/;
+
+/**
+ * Convert m:nary (n-ary operator) to MathML.
+ *
+ * OMML structure:
+ *   m:nary → m:naryPr (optional: m:chr@m:val, m:limLoc@m:val, m:subHide, m:supHide),
+ *            m:sub (lower limit, optional), m:sup (upper limit, optional), m:e (body)
+ *
+ * MathML shape depends on which limits are shown and the limit location:
+ *
+ *   Both limits, subSup (default for integrals):
+ *     <mrow><msubsup><mo>∫</mo><mrow>sub</mrow><mrow>sup</mrow></msubsup><mrow>body</mrow></mrow>
+ *   Both limits, undOvr (default for ∑, ∏, ⋃, ...):
+ *     <mrow><munderover><mo>∑</mo><mrow>sub</mrow><mrow>sup</mrow></munderover><mrow>body</mrow></mrow>
+ *
+ *   Only sub:      <msub>   / <munder>  + <mo> + <mrow>sub</mrow>
+ *   Only sup:      <msup>   / <mover>   + <mo> + <mrow>sup</mrow>
+ *   Neither:       bare <mo> inside the outer <mrow>
+ *
+ * @spec ECMA-376 §22.1.2.70 (m:nary), §22.1.2.72 (m:naryPr),
+ *       §22.1.2.53 (m:limLoc), §22.1.2.20 (m:chr), §22.9.2.7 (ST_OnOff)
+ */
+export const convertNary: MathObjectConverter = (node, doc, convertChildren) => {
+  const elements = node.elements ?? [];
+  const naryPr = elements.find((e) => e.name === 'm:naryPr');
+  const sub = elements.find((e) => e.name === 'm:sub');
+  const sup = elements.find((e) => e.name === 'm:sup');
+  const body = elements.find((e) => e.name === 'm:e');
+
+  const chr = naryPr?.elements?.find((e) => e.name === 'm:chr');
+  const limLoc = naryPr?.elements?.find((e) => e.name === 'm:limLoc');
+  const subHide = naryPr?.elements?.find((e) => e.name === 'm:subHide');
+  const supHide = naryPr?.elements?.find((e) => e.name === 'm:supHide');
+  const grow = naryPr?.elements?.find((e) => e.name === 'm:grow');
+
+  // §22.1.2.20 m:chr defaults:
+  //   element absent       → U+222B (integral)
+  //   element present      → m:val (empty string if val attribute absent)
+  const opChar = chr === undefined ? DEFAULT_NARY_CHAR : (chr.attributes?.['m:val'] ?? '');
+
+  // §22.1.2.53 m:limLoc defaults:
+  //   element absent                  → operator-character heuristic (integrals → subSup, others → undOvr)
+  //   element present, m:val absent   → undOvr
+  //   element present with m:val      → use m:val
+  const limLocVal = limLoc?.attributes?.['m:val'];
+  const isUndOvr =
+    limLocVal === 'undOvr' ||
+    (limLoc !== undefined && limLocVal === undefined) ||
+    (limLoc === undefined && opChar !== '' && !INTEGRAL_CHARS.test(opChar));
+
+  /** ST_OnOff true values per §22.9.2.7: '1', 'true', or bare-element (no attributes). */
+  const isStOnOffTrue = (el?: OmmlJsonNode) =>
+    el !== undefined &&
+    (el.attributes?.['m:val'] === '1' ||
+      el.attributes?.['m:val'] === 'on' ||
+      el.attributes?.['m:val'] === 'true' ||
+      !el.attributes);
+
+  const subHidden = isStOnOffTrue(subHide);
+  const supHidden = isStOnOffTrue(supHide);
+
+  // Strip m:ctrlPr (formatting hint only) to get each limit's meaningful children.
+  const stripCtrl = (el?: OmmlJsonNode) => (el?.elements ?? []).filter((e) => e.name !== 'm:ctrlPr');
+  const subChildren = stripCtrl(sub);
+  const supChildren = stripCtrl(sup);
+
+  // Word's behavior for subHide/supHide (§22.1.2.72):
+  //   - Empty limit + hide flag ON → suppress the placeholder slot.
+  //   - Non-empty limit + hide flag ON → promote the content into the opposite
+  //     slot (sub → prepended to sup, sup → appended to sub). Word does this so
+  //     author-entered content is never silently dropped.
+  const promotedToSup = subHidden && !supHidden ? subChildren : [];
+  const promotedToSub = supHidden && !subHidden ? supChildren : [];
+  const renderSubChildren = subHidden ? [] : [...subChildren, ...promotedToSub];
+  const renderSupChildren = supHidden ? [] : [...promotedToSup, ...supChildren];
+
+  // A slot is rendered if it has content OR if the element is present for an
+  // empty placeholder (§22.1.2.70 says sub/sup are optional — absent means no slot).
+  const hasSub = renderSubChildren.length > 0 || (sub !== undefined && !subHidden);
+  const hasSup = renderSupChildren.length > 0 || (sup !== undefined && !supHidden);
+
+  // §22.1.2.72 m:grow: default is ON (operator grows with operand). When explicitly OFF,
+  // suppress enlargement by setting largeop="false" — MathML's operator dictionary otherwise
+  // applies largeop/stretchy automatically for standard n-ary glyphs.
+  const growOff = grow !== undefined && !isStOnOffTrue(grow);
+
+  const mo = doc.createElementNS(MATHML_NS, 'mo');
+  mo.textContent = opChar;
+  if (growOff) {
+    mo.setAttribute('largeop', 'false');
+    mo.setAttribute('stretchy', 'false');
+  }
+
+  let operatorEl: Element;
+
+  if (hasSub && hasSup) {
+    const tag = isUndOvr ? 'munderover' : 'msubsup';
+    operatorEl = doc.createElementNS(MATHML_NS, tag);
+    operatorEl.appendChild(mo);
+
+    const subRow = doc.createElementNS(MATHML_NS, 'mrow');
+    subRow.appendChild(convertChildren(renderSubChildren));
+    operatorEl.appendChild(subRow);
+
+    const supRow = doc.createElementNS(MATHML_NS, 'mrow');
+    supRow.appendChild(convertChildren(renderSupChildren));
+    operatorEl.appendChild(supRow);
+  } else if (hasSub) {
+    const tag = isUndOvr ? 'munder' : 'msub';
+    operatorEl = doc.createElementNS(MATHML_NS, tag);
+    operatorEl.appendChild(mo);
+
+    const subRow = doc.createElementNS(MATHML_NS, 'mrow');
+    subRow.appendChild(convertChildren(renderSubChildren));
+    operatorEl.appendChild(subRow);
+  } else if (hasSup) {
+    const tag = isUndOvr ? 'mover' : 'msup';
+    operatorEl = doc.createElementNS(MATHML_NS, tag);
+    operatorEl.appendChild(mo);
+
+    const supRow = doc.createElementNS(MATHML_NS, 'mrow');
+    supRow.appendChild(convertChildren(renderSupChildren));
+    operatorEl.appendChild(supRow);
+  } else {
+    operatorEl = mo;
+  }
+
+  const wrapper = doc.createElementNS(MATHML_NS, 'mrow');
+  wrapper.appendChild(operatorEl);
+
+  const bodyRow = doc.createElementNS(MATHML_NS, 'mrow');
+  bodyRow.appendChild(convertChildren(body?.elements ?? []));
+  if (bodyRow.childNodes.length > 0) {
+    wrapper.appendChild(bodyRow);
+  }
+
+  return wrapper;
+};