KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

rajveermalviya · 2025-04-01T16:40:56Z

Stacked on top of: #1408

Web	Flutter

Related: #46

gnprice · 2025-04-22T23:25:56Z

lib/model/content.dart

+sealed class KatexNode extends ContentNode {
+  const KatexNode({super.debugHtmlNode});
+}
+
+class KatexSpanNode extends KatexNode {


One point that I noticed while developing #1478 (and checking how my draft of that branch interacted with this PR): it'd be good for this commit:
e268041 content: Handle vertical offset spans in KaTeX content

to get split up like so:

First, an NFC prep commit introduces the distinction between KatexNode and KatexSpanNode. At this stage, the latter is the only subclass of the former.

Then another commit makes the substantive changes this commit is about, including introducing the sibling subclasses KatexVlistNode and KatexVlistRowNode.

One reason that'd be useful is that the split between KatexNode and KatexSpanNode is somewhat nontrivial in itself: some of the references to KatexNode continue to say KatexNode, while others switch to saying KatexSpanNode, so the commit is expressing meaningful information by its choices of which references go which way.

gnprice · 2025-04-29T20:26:45Z

It seems like this had slipped through the cracks :-) but it looks ready for review, so I applied the label.

Also rebased now that #1478 is merged, so this now contains only the changes that are specific to this PR.

PIG208

Thanks for the PR! I think the last few commits will need some tests for the more complicated parts. I went over the changes and left some comments, but haven't extensively tested the changes manually yet.

PIG208 · 2025-05-01T21:33:07Z

lib/model/katex.dart

+            _logError('KaTeX: Unsupported CSS property: $property of '
+              'type ${expression.runtimeType}');


One other possibility for this to be logged is when _getEm returns null. I think for debugging purpose, including the value expression might be helpful.

PIG208 · 2025-05-01T21:36:31Z

lib/model/katex.dart

+    if (expression is css_visitor.EmTerm && expression.value is num) {
+      return (expression.value as num).toDouble();
+    }
+    return null;


Let's perhaps have a short dartdoc on what this does and what null means, since the if (…Em != null) continue;'s make this return value quite relevant.

PIG208 · 2025-05-01T21:41:53Z

lib/model/katex.dart

+  final double? heightEm;
+  final double? marginRightEm;
+  final double? topEm;
+  final double? verticalAlignEm;


I think it's a good idea to separate them into groups; to add on this, how about having a short comment before each group explaining how we group them together (like we do with design variables)?

PIG208 · 2025-05-01T21:45:35Z

lib/widgets/content.dart

+    }
+
+    return Container(
+      margin: styles.marginRightEm != null && !styles.marginRightEm!.isNegative


Hmm, !styles.marginRightEm!.isNegative seems a bit contrived. I think isNegative negated is not as clear as >= 0. However, do we need the margin when marginRightEm is 0?

PIG208 · 2025-05-01T21:50:05Z

lib/model/katex.dart

+      styles: inlineStyles != null
+        ? styles.merge(inlineStyles)
+        : styles,


Having tests for this (the case when there are both inline styles and others) might be useful. Not sure how common that is.

PIG208 · 2025-05-01T22:30:18Z

lib/widgets/content.dart

+        child: RichText(text: TextSpan(
+          children: List.unmodifiable(row.nodes.map((e) {
+            return WidgetSpan(
+              alignment: PlaceholderAlignment.baseline,
+              baseline: TextBaseline.alphabetic,
+              child: switch (e) {
+                KatexSpanNode() => _KatexSpan(e),
+                KatexVlistNode() => _KatexVlist(e),
+                KatexNegativeMarginNode() => _KatexNegativeMargin(e),
+              });
+          })))));


looks like this can be replaced with _KatexNodeList(nodes: row.nodes)

PIG208 · 2025-05-01T22:30:41Z

lib/widgets/content.dart

+      child: Text.rich(TextSpan(
+        children: List.unmodifiable(node.nodes.map((e) {
+          return WidgetSpan(
+            alignment: PlaceholderAlignment.baseline,
+            baseline: TextBaseline.alphabetic,
+            child: switch (e) {
+              KatexSpanNode() => _KatexSpan(e),
+              KatexVlistNode() => _KatexVlist(e),
+              KatexNegativeMarginNode() => _KatexNegativeMargin(e),
+            });
+        })))));


_KatexNodeList also seems helpful here.

PIG208 · 2025-05-01T22:34:06Z

lib/widgets/content.dart

+}
+
+class _KatexNegativeMargin extends StatelessWidget {
+  const _KatexNegativeMargin(this.node);


Because the name implies that the margin should be negative, maybe we should also add assertions to ensure that that is true.

PIG208 · 2025-05-01T22:42:29Z

lib/model/katex.dart

  List<KatexNode> _parseChildSpans(dom.Element element) {
-    return List.unmodifiable(element.nodes.map((node) {
-      if (node case dom.Element(localName: 'span')) {
-        return _parseSpan(node);
-      } else {
+    var resultSpans = <KatexNode>[];
+    for (final node in element.nodes.reversed) {
+      if (node is! dom.Element || node.localName != 'span') {
        throw KatexHtmlParseError();
      }
-    }));
+
+      final span = _parseSpan(node);
+      resultSpans.add(span);
+
+      if (span is KatexSpanNode) {
+        final marginRightEm = span.styles.marginRightEm;
+        if (marginRightEm != null && marginRightEm.isNegative) {
+          final previousSpansReversed =
+            resultSpans.reversed.toList(growable: false);
+          resultSpans = [];
+          resultSpans.add(KatexNegativeMarginNode(
+            marginRightEm: marginRightEm,
+            nodes: previousSpansReversed));
+        }
+      }
+    }
+
+    return resultSpans.reversed.toList(growable: false);
  }


Neat solution! A bit tricky to understand. I think we can use QueueList (and with .addFirst) to avoid the hassle of reversing and unreversing the list.

It will be helpful to have tests for this.

PIG208 · 2025-05-01T22:51:55Z

lib/model/katex.dart

+          final pstrutStyles = _parseSpanInlineStyles(pstrutSpan)!;
+          final pstrutHeight = pstrutStyles.heightEm ?? 0;
+
+          // TODO handle negative right-margin inline style on row nodes.


Do we consider this complete after the final commit ("content: Support negative right-margin on KaTeX spans")? I'm not too sure if something else is left to be done here.

This seems to contradict with the earlier assumption that vlist elements contain only the height style.

This will prevent string interpolation being evaluated during release build. Especially useful in later commit where it becomes more expensive.

… nodes

rajveermalviya · 2025-05-20T17:59:03Z

Thanks for the review @PIG208! Pushed a new revision, PTAL.

I removed the commit for supporting negative margins from this PR, and will create a separate PR that introduces it again.

PIG208

Thanks! Left some comments.

While testing this, I ran into some issues with text scaling (the relevant commit is "content: Scale inline KaTeX content based on the surrounding text"); posted screenshots in one of the comments below.

Otherwise, this works pretty well!

PIG208 · 2025-05-20T21:19:43Z

lib/model/katex.dart

+        ? List<String>.unmodifiable(element.className.split(' '))
+        : const <String>[];


nit: indentation

PIG208 · 2025-05-20T21:25:52Z

test/widgets/content_test.dart

+        (ContentExample.mathBlockKatexVertical5, [
+          ('a', Offset(0.0, 4.16), Size(10.88, 25.0)),
+          ('b', Offset(10.88, -0.65), Size(8.82, 25.0)),
+          ('c', Offset(19.70, 4.16), Size(8.90, 25.0)),


Interesting setup! This resembles the golden tests that use images instead of offset/size values to verify rendering results.

PIG208 · 2025-05-20T21:26:41Z

test/widgets/content_test.dart

+      Future.value(fontFile.readAsBytesSync().buffer.asByteData());
+    await (FontLoader(fontName)..addFont(bytes)).load();
+  }
+}


nit: newline at the end

PIG208 · 2025-05-20T21:28:49Z

test/widgets/content_test.dart

@@ -1406,3 +1475,21 @@ void main() {
    });
  });
 }
+
+Future<void> _loadKatexFonts() async {


We have a similar thing in emoji_reactoins_test.dart:

Future<void> prepare() async { addTearDown(testBinding.reset); await testBinding.globalStore.add(eg.selfAccount, eg.initialSnapshot()); store = await testBinding.globalStore.perAccount(eg.selfAccount.id); await store.addUser(eg.selfUser); // TODO do this more centrally, or put in reusable helper final Future<ByteData> font = rootBundle.load('assets/Source_Sans_3/SourceSans3VF-Upright.otf'); final fontLoader = FontLoader('Source Sans 3')..addFont(font); await fontLoader.load(); }

Sharing the helper is not necessary for this PR, but it looks like something we can extract to reuse in the future.

PIG208 · 2025-05-20T21:34:21Z

lib/model/katex.dart

+          break;
+
+        // TODO handle skipped class declarations between .mspace and
+        //   .thinbox .


nit: should this be .msupsub?

PIG208 · 2025-05-20T22:04:54Z

lib/widgets/content.dart

@@ -850,8 +860,7 @@ class _Katex extends StatelessWidget {
    return Directionality(
      textDirection: TextDirection.ltr,
      child: DefaultTextStyle(
-        style: kBaseKatexTextStyle.copyWith(
-          color: ContentTheme.of(context).textStylePlainParagraph.color),
+        style: mkBaseKatexTextStyle(textStyle),


Not entirely sure why, but math nested in headings doesn't seem to be visible:

PIG208 · 2025-05-20T22:11:25Z

lib/widgets/content.dart

@@ -850,8 +860,7 @@ class _Katex extends StatelessWidget {
    return Directionality(
      textDirection: TextDirection.ltr,
      child: DefaultTextStyle(
-        style: kBaseKatexTextStyle.copyWith(
-          color: ContentTheme.of(context).textStylePlainParagraph.color),
+        style: mkBaseKatexTextStyle(textStyle),


Another issue is that the math content seems to get scaled more than normal text, and the smaller the text is (in normal font size), the more scaled it gets.

normal larger font

PIG208 · 2025-05-20T22:18:45Z

lib/model/katex.dart

+                rows.add(KatexVlistRowNode(
+                  verticalOffsetEm: topEm + pstrutHeight,
+                    node: KatexSpanNode(
+                      styles: styles,
+                      text: null,
+                      nodes: _parseChildSpans(otherSpans))));


nit: indentation

PIG208 · 2025-05-20T22:36:32Z

lib/widgets/content.dart

-    return widget;
+
+    if (styles.verticalAlignEm != null && styles.heightEm != null) {
+      assert(widget == defaultWidget);


I think this assertion is based on the broader assumption that some inline styles never co-occur to vertical-align or height. This seems like something we can comment on.

This applies the correct font scaling if the KaTeX content is inside a header.

And rename previous type to KatexSpanNode, also while making it a subtype of KatexNode.

In KaTeX HTML it is used to set the baseline of the content in a span, so handle it separately here.

And inline the behaviour for `inline: false` in MathBlock widget.

Implement handling most common types of `vlist` spans.

gnprice · 2025-05-29T18:05:46Z

test/widgets/content_test.dart


      fontSize = 4.976 * fontSize;
      checkKatexText(tester, '2',
        fontFamily: 'KaTeX_Main',
        fontSize: fontSize,
-        fontHeight: kBaseKatexTextStyle.height!);
+        fontHeight: baseTextStyle.height!);
    });

    testWidgets('displays KaTeX content with different delimiter sizing', (tester) async {


+ // TODO: Re-enable this test after adding support for parsing + // `vertical-align` in inline styles. Currently it fails + // because `strut` span has `vertical-align`. + // + // testWidgets('displays KaTeX content with different delimiter sizing', (tester) async {

Instead of commenting out the whole test (which makes the diff big), pass skip: true. For examples, see git grep -A2 skip: test/.

The other reason skip: is better than commenting out is that it makes the test case still exist in the test framework and get counted; the total number of skipped tests is printed after the number of passed and failed tests. That's helpful for occasionally sweeping to confirm we don't have tests accidentally left skipped that might point to live bugs.

gnprice · 2025-05-29T18:10:57Z

test/model/content_test.dart

                styles: KatexSpanStyles(fontSizeEm: 0.5), // .reset-size6.size1
                text: '0',
                nodes: null),
            ]),
        ]),
    ]);

-  static final mathBlockKatexNestedSizing = ContentExample(
+  static const mathBlockKatexNestedSizing = ContentExample(


+ // TODO: Re-enable this test after adding support for parsing + // `vertical-align` in inline styles. Currently it fails + // because `strut` span has `vertical-align`. + // + // static const mathBlockKatexDelimSizing = ContentExample(

Similarly, use skip: true instead of commenting.

For this test, that requires a bit of setup to make this file's helpers and the "all content examples are tested" check handle the skip: argument. I've just pushed a small added commit at the end of this PR branch to do that:
f9a79d8 content test [nfc]: Enable skips in testParseExample and testParse

So please rebase that to earlier in the branch as needed, and then write:

testParseExample(ContentExample.mathBlockKatexNestedSizing, skip: true);

rajveermalviya mentioned this pull request Apr 1, 2025

Support TeX content in message list #1335

Closed

rajveermalviya force-pushed the pr-tex-content-2 branch from d00e10f to 7ff4f9e Compare April 1, 2025 19:31

gnprice mentioned this pull request Apr 2, 2025

KaTeX (1/n): Initial support for displaying basic KaTeX content #1408

Merged

rajveermalviya force-pushed the pr-tex-content-2 branch from 7ff4f9e to c0dd0a1 Compare April 22, 2025 15:23

gnprice mentioned this pull request Apr 22, 2025

Refactor parts of initial KaTeX handling #1478

Merged

gnprice reviewed Apr 22, 2025

View reviewed changes

rajveermalviya force-pushed the pr-tex-content-2 branch 2 times, most recently from b17033a to 16cb28f Compare April 24, 2025 08:21

gnprice added the maintainer review PR ready for review by Zulip maintainers label Apr 29, 2025

gnprice assigned PIG208 Apr 29, 2025

gnprice force-pushed the pr-tex-content-2 branch from 16cb28f to 376cfe7 Compare April 29, 2025 20:25

PIG208 reviewed May 1, 2025

View reviewed changes

rajveermalviya force-pushed the pr-tex-content-2 branch from 376cfe7 to d879646 Compare May 5, 2025 07:10

rajveermalviya force-pushed the pr-tex-content-2 branch 3 times, most recently from d4202c7 to 49d724d Compare May 19, 2025 18:08

rajveermalviya added 3 commits May 19, 2025 23:40

content test [nfc]: Use const for math block tests

2732beb

content [nfc]: Inline _logError in _KatexParser._parseSpan

860dd00

This will prevent string interpolation being evaluated during release build. Especially useful in later commit where it becomes more expensive.

content [nfc]: Refactor _KatexParser._parseChildSpans to take list of…

0a47cc5

… nodes

rajveermalviya force-pushed the pr-tex-content-2 branch 2 times, most recently from c917d14 to ec14306 Compare May 20, 2025 17:45

rajveermalviya requested a review from PIG208 May 20, 2025 17:59

PIG208 reviewed May 20, 2025

View reviewed changes

gnprice assigned chrisbobbe and unassigned PIG208 May 29, 2025

rajveermalviya added 3 commits May 29, 2025 20:27

content: Scale inline KaTeX content based on the surrounding text

ebf0e7e

This applies the correct font scaling if the KaTeX content is inside a header.

content: Populate debugHtmlNode for KatexNode

7fdb8ff

content: Support parsing and handling inline styles for KaTeX content

ab66402

rajveermalviya added 8 commits May 29, 2025 20:59

content [nfc]: Reintroduce KatexNode as a base sealed class

7dd43c9

And rename previous type to KatexSpanNode, also while making it a subtype of KatexNode.

content: Handle 'strut' span in KaTeX content

63fc8e5

In KaTeX HTML it is used to set the baseline of the content in a span, so handle it separately here.

content: Ignore more KaTeX classes that don't have CSS definition

fd95d67

content: Handle 'mspace' and 'msupsub' KaTeX CSS classes

19eb7b2

content: Handle positive margin-right and margin-left in KaTeX spans

0855abc

content: Handle 'top' property in KaTeX span inline style

cab0f49

content [nfc]: Remove the inline property in _Katex widget

cfcbc5b

And inline the behaviour for `inline: false` in MathBlock widget.

content: Handle vertical offset spans in KaTeX content

0e00af6

Implement handling most common types of `vlist` spans.

rajveermalviya force-pushed the pr-tex-content-2 branch from ec14306 to 0e00af6 Compare May 29, 2025 15:42

content test [nfc]: Enable skips in testParseExample and testParse

f9a79d8

gnprice reviewed May 29, 2025

View reviewed changes

		_logError('KaTeX: Unsupported CSS property: $property of '
		'type ${expression.runtimeType}');

		? List<String>.unmodifiable(element.className.split(' '))
		: const <String>[];

KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

Are you sure you want to change the base?

KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

Uh oh!

Conversation

rajveermalviya commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gnprice commented Apr 29, 2025

Uh oh!

PIG208 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rajveermalviya commented May 20, 2025

Uh oh!

PIG208 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rajveermalviya commented Apr 1, 2025 •

edited

Loading