Skip to content

Refactor templates to convert <N, T, D> to <DOM> to reduce number of templates. - #1562

Draft
dpvc wants to merge 3 commits into
developfrom
refactor/NTD-to-DOM
Draft

Refactor templates to convert <N, T, D> to <DOM> to reduce number of templates.#1562
dpvc wants to merge 3 commits into
developfrom
refactor/NTD-to-DOM

Conversation

@dpvc

@dpvc dpvc commented Sep 2, 2026

Copy link
Copy Markdown
Member

This PR builds on the idea of the DOM type introduced in #1554 in order to reduce the number of template variables used in the various classes that require information about the DOM nodes being used. In the past, we used <N, T, D> for this, but this PR changes that to use <DOM>, as in the various option types added in #1554, so something like MathDocument<N, T, D> now becomes MathDocumetn<DOM>. To access the N, T, and D values, the class uses N<DOM>, TandD` instead. This helps clarify that the type refers to a DOM node type. This reduces the templates from three to just one in many cases.

The biggest impact is in the ts/output/common files, where there were 12 template variables. By merging N, T, and D into DOM, and combing the five font-based template values into a single COMMON_FONT (or CHTML_FONT or SVG_FONT) type, those templates are cut in half, to only six. The other four are interdependent and I could don't find an away to combine them into a single type, but six is still better than 12. That reduces the need for /* prettier-ignore */ statements, and shortens up the template declarations considerably. The cost is using N<DOM> rather than N, but as mentioned above, I think that actually helps clarify what these values are. But it also allow <N<DOM>, T<DOM>, D<DOM>> that was introduced in #1554 to be replaced by <DOM>, so that is a savings as well.

In addition to removing /* prettier-ignore */ for the extensive template usage, I tried to remove /* prettier-ignore */ in other cases that were just there for comments, so you will see some comment adjustments for that purpose. I also did some alignment adjustments in the comments that had gotten skewed due to earlier changes, so you might want to view this with white-space changes hidden.

Some modules used explicit <HTMLElement, Text, Document> template values; these are replaced by <HTML_DOM> where HTML_DOM comes from ts/types/dom/html.ts as part of the new typing system.

There is really nothing else going on in this PR, so although there are a lot of files involved (anything that uses MathItem or MathDocument, which is just about everything), the changes are really just in the templates.

One issue to consider, however, is that this is a potentially breaking change to people using MathJax in Typescript projects, as something like new TeX<HTMLElement, Text, Document>() will have to be changed to new TeX<HTML_DOM>() and HTML_DOM will need to be imported. But the new HTML_DOM should make such things easier, especially for node use, where new TeX<LITE_DOM> with one import for LITE_DOM is easier than importing LiteElement, LiteText, and LiteDocument from three separate files, and using new TeX<LiteElement, LiteText, LiteDocument>(). So I think this (along with the new typing mechanism) will be a welcome change for developers.

@dpvc
dpvc requested a review from zorkow September 2, 2026 15:12
@dpvc dpvc added this to the v4.2 milestone Sep 2, 2026
@codecov

codecov Bot commented Sep 2, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.17298% with 223 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.50%. Comparing base (106e5ac) to head (b99d9f8).

Files with missing lines Patch % Lines
ts/adaptors/HTMLAdaptor.ts 79.84% 26 Missing ⚠️
ts/output/chtml/Wrappers/munderover.ts 82.11% 22 Missing ⚠️
ts/output/common.ts 86.02% 19 Missing ⚠️
ts/core/MathDocument.ts 89.61% 16 Missing ⚠️
ts/output/common/LinebreakVisitor.ts 72.00% 14 Missing ⚠️
ts/output/chtml/Wrappers/mtable.ts 76.78% 13 Missing ⚠️
ts/output/chtml/Wrappers/mrow.ts 86.84% 10 Missing ⚠️
ts/output/common/Wrappers/maction.ts 92.17% 9 Missing ⚠️
ts/core/MmlTree/MathMLVisitor.ts 0.00% 8 Missing ⚠️
ts/output/chtml/Wrapper.ts 81.57% 7 Missing ⚠️
... and 27 more
Additional details and impacted files
@@             Coverage Diff             @@
##           develop    #1562      +/-   ##
===========================================
- Coverage    87.12%   86.50%   -0.62%     
===========================================
  Files          392      392              
  Lines        89098    85308    -3790     
  Branches      5046     5040       -6     
===========================================
- Hits         77628    73798    -3830     
- Misses       11450    11510      +60     
+ Partials        20        0      -20     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dpvc dpvc modified the milestones: v4.2, v5.0 Sep 4, 2026
@dpvc
dpvc marked this pull request as draft September 4, 2026 17:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant