katex: Handle position & top property in span inline styles

Allowing support for handling KaTeX HTML for big operators.

Fixes: #1671

Author: rajveermalviya

lib/model/katex.dart

@@ -637,6 +637,7 @@ class _KatexParser {
       marginLeftEm: _takeStyleEm(inlineStyles, 'margin-left'),
       marginRightEm: _takeStyleEm(inlineStyles, 'margin-right'),
       color: _takeStyleColor(inlineStyles, 'color'),
+      position: _takeStylePosition(inlineStyles, 'position'),
       // TODO handle more CSS properties
     );
     if (inlineStyles != null && inlineStyles.isNotEmpty) {
@@ -646,10 +647,10 @@ class _KatexParser {
         _hasError = true;
       }
     }
-    // Currently, we expect `top` to only be inside a vlist, and
-    // we handle that case separately above.
-    if (styles.topEm != null) {
-      throw _KatexHtmlParseError('unsupported inline CSS property: top');
+    if (styles.topEm != null && styles.position != KatexSpanPosition.relative) {
+      // The meaning of `top` would be different without `position: relative`.
+      throw _KatexHtmlParseError(
+        'unsupported inline CSS property "top" given "position: ${styles.position}"');
     }
 
     String? text;
@@ -771,6 +772,34 @@ class _KatexParser {
     _hasError = true;
     return null;
   }
+
+  /// Remove the given property from the given style map,
+  /// and parse as a CSS position value.
+  ///
+  /// If the property is present but is not a valid CSS position value,
+  /// record an error and return null.
+  ///
+  /// If the property is absent, return null with no error.
+  ///
+  /// If the map is null, treat it as empty.
+  ///
+  /// To produce the map this method expects, see [_parseInlineStyles].
+  KatexSpanPosition? _takeStylePosition(Map<String, css_visitor.Expression>? styles, String property) {
+    final expression = styles?.remove(property);
+    if (expression == null) return null;
+    if (expression case css_visitor.LiteralTerm(:final value)) {
+      if (value case css_visitor.Identifier(:final name)) {
+        if (name == 'relative') {
+          return KatexSpanPosition.relative;
+        }
+      }
+    }
+    assert(debugLog('KaTeX: Unsupported value for CSS property $property,'
+      ' expected a CSS position value: ${expression.toDebugString()}'));
+    unsupportedInlineCssProperties.add(property);
+    _hasError = true;
+    return null;
+  }
 }
 
 enum KatexSpanFontWeight {
@@ -788,6 +817,10 @@ enum KatexSpanTextAlign {
   right,
 }
 
+enum KatexSpanPosition {
+  relative,
+}
+
 class KatexSpanColor {
   const KatexSpanColor(this.r, this.g, this.b, this.a);
 
@@ -840,6 +873,7 @@ class KatexSpanStyles {
   final KatexSpanTextAlign? textAlign;
 
   final KatexSpanColor? color;
+  final KatexSpanPosition? position;
 
   const KatexSpanStyles({
     this.widthEm,
@@ -853,6 +887,7 @@ class KatexSpanStyles {
     this.fontStyle,
     this.textAlign,
     this.color,
+    this.position,
   });
 
   @override
@@ -869,6 +904,7 @@ class KatexSpanStyles {
     fontStyle,
     textAlign,
     color,
+    position,
   );
 
   @override
@@ -884,7 +920,8 @@ class KatexSpanStyles {
       other.fontWeight == fontWeight &&
       other.fontStyle == fontStyle &&
       other.textAlign == textAlign &&
-      other.color == color;
+      other.color == color &&
+      other.position == position;
   }
 
   @override
@@ -901,6 +938,7 @@ class KatexSpanStyles {
     if (fontStyle != null) args.add('fontStyle: $fontStyle');
     if (textAlign != null) args.add('textAlign: $textAlign');
     if (color != null) args.add('color: $color');
+    if (position != null) args.add('position: $position');
     return '${objectRuntimeType(this, 'KatexSpanStyles')}(${args.join(', ')})';
   }
 
@@ -917,6 +955,7 @@ class KatexSpanStyles {
     bool fontStyle = true,
     bool textAlign = true,
     bool color = true,
+    bool position = true,
   }) {
     return KatexSpanStyles(
       widthEm: widthEm ? this.widthEm : null,
@@ -930,6 +969,7 @@ class KatexSpanStyles {
       fontStyle: fontStyle ? this.fontStyle : null,
       textAlign: textAlign ? this.textAlign : null,
       color: color ? this.color : null,
+      position: position ? this.position : null,
     );
   }
 }

lib/widgets/katex.dart

@@ -96,10 +96,10 @@ class _KatexSpan extends StatelessWidget {
     }
 
     final styles = node.styles;
-
-    // Currently, we expect `top` to be only present with the
-    // vlist inner row span, and parser handles that explicitly.
-    assert(styles.topEm == null);
+    if (styles.topEm != null) {
+      // The meaning of `top` would be different without `position: relative`.
+      assert(styles.position == KatexSpanPosition.relative);
+    }
 
     final fontFamily = styles.fontFamily;
     final fontSize = switch (styles.fontSizeEm) {
@@ -183,6 +183,18 @@ class _KatexSpan extends StatelessWidget {
       widget = Padding(padding: margin, child: widget);
     }
 
+    switch (styles.position) {
+      case KatexSpanPosition.relative:
+        if (styles.topEm case final topEm?) {
+          widget = Transform.translate(
+            offset: Offset(0, topEm * em),
+            child: widget);
+        }
+
+      case null:
+        break;
+    }
+
     return widget;
   }
 }

test/model/katex_test.dart

@@ -644,6 +644,62 @@ class KatexExample extends ContentExample {
       ]),
     ]);
 
+  static final bigOperators = KatexExample.block(
+    r'big operators: \int',
+    // https://chat.zulip.org/#narrow/channel/7-test-here/topic/Rajesh/near/2240766
+    r'\int',
+    '<p>'
+      '<span class="katex-display"><span class="katex">'
+        '<span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mo>∫</mo></mrow><annotation encoding="application/x-tex">\\int</annotation></semantics></math></span>'
+        '<span class="katex-html" aria-hidden="true">'
+          '<span class="base">'
+            '<span class="strut" style="height:2.2222em;vertical-align:-0.8622em;"></span>'
+            '<span class="mop op-symbol large-op" style="margin-right:0.44445em;position:relative;top:-0.0011em;">∫</span></span></span></span></span></p>', [
+      KatexSpanNode(nodes: [
+        KatexStrutNode(heightEm: 2.2222, verticalAlignEm: -0.8622),
+        KatexSpanNode(
+          styles: KatexSpanStyles(
+            topEm: -0.0011,
+            marginRightEm: 0.44445,
+            fontFamily: 'KaTeX_Size2',
+            position: KatexSpanPosition.relative),
+          text: '∫'),
+      ]),
+    ]);
+
+  static final colonEquals = KatexExample.block(
+    r'\colonequals relation',
+    // https://chat.zulip.org/#narrow/channel/7-test-here/topic/Rajesh/near/2244936
+    r'\colonequals',
+    '<p>'
+      '<span class="katex-display"><span class="katex">'
+        '<span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mo><mi mathvariant="normal">≔</mi></mo></mrow><annotation encoding="application/x-tex">\\colonequals</annotation></semantics></math></span>'
+        '<span class="katex-html" aria-hidden="true">'
+          '<span class="base">'
+            '<span class="strut" style="height:0.4306em;"></span>'
+            '<span class="mrel">'
+              '<span class="mrel">'
+                '<span class="mop" style="position:relative;top:-0.0347em;">:</span></span>'
+              '<span class="mrel">'
+                '<span class="mspace" style="margin-right:-0.0667em;"></span></span>'
+              '<span class="mrel">=</span></span></span></span></span></span></p>', [
+      KatexSpanNode(nodes: [
+        KatexStrutNode(heightEm: 0.4306, verticalAlignEm: null),
+        KatexSpanNode(nodes: [
+          KatexSpanNode(nodes: [
+            KatexSpanNode(
+              styles: KatexSpanStyles(topEm: -0.0347, position: KatexSpanPosition.relative),
+              text: ':'),
+          ]),
+          KatexSpanNode(nodes: [
+            KatexSpanNode(nodes: []),
+            KatexNegativeMarginNode(leftOffsetEm: -0.0667, nodes: []),
+          ]),
+          KatexSpanNode(text: '='),
+        ]),
+      ]),
+    ]);
+
   static final nulldelimiter = KatexExample.block(
     r'null delimiters, like `\left.`',
     // https://chat.zulip.org/#narrow/channel/7-test-here/topic/Rajesh/near/2205534
@@ -695,6 +751,8 @@ void main() async {
   testParseExample(KatexExample.textColor);
   testParseExample(KatexExample.customColorMacro);
   testParseExample(KatexExample.phantom);
+  testParseExample(KatexExample.bigOperators);
+  testParseExample(KatexExample.colonEquals);
   testParseExample(KatexExample.nulldelimiter);
 
   group('parseCssHexColor', () {

test/widgets/katex_test.dart

@@ -73,6 +73,10 @@ void main() {
         ('X', Offset(0.00, 7.04), Size(17.03, 25.00)),
         ('n', Offset(17.03, 15.90), Size(8.63, 17.00)),
       ]),
+      (KatexExample.colonEquals, skip: false, [
+        (':', Offset(0.00, 3.45), Size(5.72, 25.00)),
+        ('=', Offset(5.72, 3.92), Size(16.00, 25.00)),
+      ]),
       (KatexExample.nulldelimiter, skip: false, [
         ('a', Offset(2.47, 3.36), Size(10.88, 25.00)),
         ('b', Offset(15.81, 3.36), Size(8.82, 25.00)),