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

README.md

@@ -12,7 +12,6 @@ see the [milestones][] and the [project board][].
 [milestones]: https://github.com/zulip/zulip-flutter/milestones?direction=asc&sort=title
 [project board]: https://github.com/orgs/zulip/projects/5/views/4
 
-
 ## Using Zulip
 
 To use Zulip on iOS or Android, install the [official mobile Zulip client][].

assets/KaTeX/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2020 Khan Academy and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lib/licenses.dart

@@ -12,6 +12,9 @@ import 'package:flutter/services.dart';
 Stream<LicenseEntry> additionalLicenses() async* {
   // Alphabetic by path.
 
+  yield LicenseEntryWithLineBreaks(
+    ['KaTeX'],
+    await rootBundle.loadString('assets/KaTeX/LICENSE'));
   yield LicenseEntryWithLineBreaks(
     ['Noto Color Emoji'],
     await rootBundle.loadString('assets/Noto_Color_Emoji/LICENSE'));

lib/model/binding.dart

@@ -83,6 +83,13 @@ abstract class ZulipBinding {
   /// a widget tree may not exist.
   Future<GlobalStore> getGlobalStore();
 
+  /// Get the app's singleton [GlobalStore] if already loaded, else null.
+  ///
+  /// Where possible, use [GlobalStoreWidget.of] to get access to a [GlobalStore].
+  /// Use this method only in contexts where getting access to a [BuildContext]
+  /// is inconvenient.
+  GlobalStore? getGlobalStoreSync();
+
   /// Like [getGlobalStore], but assert this method was not previously called.
   ///
   /// This is used by the implementation of [GlobalStoreWidget],
@@ -333,8 +340,17 @@ class LiveZulipBinding extends ZulipBinding {
   }
 
   @override
-  Future<GlobalStore> getGlobalStore() => _globalStore ??= LiveGlobalStore.load();
-  Future<GlobalStore>? _globalStore;
+  Future<GlobalStore> getGlobalStore() {
+    return _globalStoreFuture ??= LiveGlobalStore.load().then((store) {
+      return _globalStore = store;
+    });
+  }
+
+  @override
+  GlobalStore? getGlobalStoreSync() => _globalStore;
+
+  Future<GlobalStore>? _globalStoreFuture;
+  GlobalStore? _globalStore;
 
   @override
   Future<GlobalStore> getGlobalStoreUniquely() {

lib/model/content.dart

@@ -6,6 +6,7 @@ import 'package:html/parser.dart';
 import '../api/model/model.dart';
 import '../api/model/submessage.dart';
 import 'code_block.dart';
+import 'katex.dart';
 
 /// A node in a parse tree for Zulip message-style content.
 ///
@@ -341,22 +342,124 @@ class CodeBlockSpanNode extends ContentNode {
 }
 
 class MathBlockNode extends BlockContentNode {
-  const MathBlockNode({super.debugHtmlNode, required this.texSource});
+  const MathBlockNode({
+    super.debugHtmlNode,
+    required this.texSource,
+    required this.nodes,
+  });
 
   final String texSource;
 
+  /// Parsed KaTeX node tree to be used for rendering the KaTeX content.
+  ///
+  /// It will be null if the parser encounters an unsupported HTML element or
+  /// CSS style, indicating that the widget should render the [texSource] as a
+  /// fallback instead.
+  final List<KatexNode>? nodes;
+
   @override
-  bool operator ==(Object other) {
-    return other is MathBlockNode && other.texSource == texSource;
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(StringProperty('texSource', texSource));
   }
 
   @override
-  int get hashCode => Object.hash('MathBlockNode', texSource);
+  List<DiagnosticsNode> debugDescribeChildren() {
+    return nodes?.map((node) => node.toDiagnosticsNode()).toList() ?? const [];
+  }
+}
+
+sealed class KatexNode extends ContentNode {
+  const KatexNode({super.debugHtmlNode});
+}
+
+class KatexSpanNode extends KatexNode {
+  const KatexSpanNode({
+    required this.styles,
+    required this.text,
+    required this.nodes,
+    super.debugHtmlNode,
+  }) : assert((text != null) ^ (nodes != null));
+
+  final KatexSpanStyles styles;
+
+  /// The text this KaTeX node contains.
+  ///
+  /// It will be null if [nodes] is non-null.
+  final String? text;
+
+  /// The child nodes of this node in the KaTeX HTML tree.
+  ///
+  /// It will be null if [text] is non-null.
+  final List<KatexNode>? nodes;
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
-    properties.add(StringProperty('texSource', texSource));
+    properties.add(DiagnosticsProperty<KatexSpanStyles>('styles', styles));
+    properties.add(StringProperty('text', text));
+  }
+
+  @override
+  List<DiagnosticsNode> debugDescribeChildren() {
+    return nodes?.map((node) => node.toDiagnosticsNode()).toList() ?? const [];
+  }
+}
+
+class KatexVlistNode extends KatexNode {
+  const KatexVlistNode({
+    required this.rows,
+    super.debugHtmlNode,
+  });
+
+  final List<KatexVlistRowNode> rows;
+
+  @override
+  List<DiagnosticsNode> debugDescribeChildren() {
+    return rows.map((row) => row.toDiagnosticsNode()).toList();
+  }
+}
+
+class KatexVlistRowNode extends ContentNode {
+  const KatexVlistRowNode({
+    required this.verticalOffsetEm,
+    this.nodes = const [],
+  });
+
+  final double verticalOffsetEm;
+  final List<KatexNode> nodes;
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(StringProperty('verticalOffsetEm', '$verticalOffsetEm'));
+  }
+
+  @override
+  List<DiagnosticsNode> debugDescribeChildren() {
+    return nodes.map((node) => node.toDiagnosticsNode()).toList();
+  }
+}
+
+class KatexNegativeMarginNode extends KatexNode {
+  const KatexNegativeMarginNode({
+    required this.marginRightEm,
+    required this.nodes,
+    super.debugHtmlNode,
+  });
+
+  final double marginRightEm;
+  final List<KatexNode> nodes;
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(StringProperty('marginRightEm', '$marginRightEm'));
+  }
+
+  @override
+  List<DiagnosticsNode> debugDescribeChildren() {
+    return nodes.map((node) => node.toDiagnosticsNode()).toList();
   }
 }
 
@@ -822,23 +925,25 @@ class ImageEmojiNode extends EmojiNode {
 }
 
 class MathInlineNode extends InlineContentNode {
-  const MathInlineNode({super.debugHtmlNode, required this.texSource});
+  const MathInlineNode({
+    super.debugHtmlNode,
+    required this.texSource,
+    required this.nodes,
+  });
 
   final String texSource;
-
-  @override
-  bool operator ==(Object other) {
-    return other is MathInlineNode && other.texSource == texSource;
-  }
-
-  @override
-  int get hashCode => Object.hash('MathInlineNode', texSource);
+  final List<KatexNode>? nodes;
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
     properties.add(StringProperty('texSource', texSource));
   }
+
+  @override
+  List<DiagnosticsNode> debugDescribeChildren() {
+    return nodes?.map((node) => node.toDiagnosticsNode()).toList() ?? const [];
+  }
 }
 
 class GlobalTimeNode extends InlineContentNode {
@@ -864,52 +969,6 @@ class GlobalTimeNode extends InlineContentNode {
 
 ////////////////////////////////////////////////////////////////
 
-String? _parseMath(dom.Element element, {required bool block}) {
-  final dom.Element katexElement;
-  if (!block) {
-    assert(element.localName == 'span' && element.className == 'katex');
-
-    katexElement = element;
-  } else {
-    assert(element.localName == 'span' && element.className == 'katex-display');
-
-    if (element.nodes.length != 1) return null;
-    final child = element.nodes.single;
-    if (child is! dom.Element) return null;
-    if (child.localName != 'span') return null;
-    if (child.className != 'katex') return null;
-    katexElement = child;
-  }
-
-  // Expect two children span.katex-mathml, span.katex-html .
-  // For now we only care about the .katex-mathml .
-  if (katexElement.nodes.isEmpty) return null;
-  final child = katexElement.nodes.first;
-  if (child is! dom.Element) return null;
-  if (child.localName != 'span') return null;
-  if (child.className != 'katex-mathml') return null;
-
-  if (child.nodes.length != 1) return null;
-  final grandchild = child.nodes.single;
-  if (grandchild is! dom.Element) return null;
-  if (grandchild.localName != 'math') return null;
-  if (grandchild.attributes['display'] != (block ? 'block' : null)) return null;
-  if (grandchild.namespaceUri != 'http://www.w3.org/1998/Math/MathML') return null;
-
-  if (grandchild.nodes.length != 1) return null;
-  final greatgrand = grandchild.nodes.single;
-  if (greatgrand is! dom.Element) return null;
-  if (greatgrand.localName != 'semantics') return null;
-
-  if (greatgrand.nodes.isEmpty) return null;
-  final descendant4 = greatgrand.nodes.last;
-  if (descendant4 is! dom.Element) return null;
-  if (descendant4.localName != 'annotation') return null;
-  if (descendant4.attributes['encoding'] != 'application/x-tex') return null;
-
-  return descendant4.text.trim();
-}
-
 /// Parser for the inline-content subtrees within Zulip content HTML.
 ///
 /// The only entry point to this class is [parseBlockInline].
@@ -920,9 +979,12 @@ String? _parseMath(dom.Element element, {required bool block}) {
 class _ZulipInlineContentParser {
   InlineContentNode? parseInlineMath(dom.Element element) {
     final debugHtmlNode = kDebugMode ? element : null;
-    final texSource = _parseMath(element, block: false);
-    if (texSource == null) return null;
-    return MathInlineNode(texSource: texSource, debugHtmlNode: debugHtmlNode);
+    final parsed = parseMath(element, block: false);
+    if (parsed == null) return null;
+    return MathInlineNode(
+      texSource: parsed.texSource,
+      nodes: parsed.nodes,
+      debugHtmlNode: debugHtmlNode);
   }
 
   UserMentionNode? parseUserMention(dom.Element element) {
@@ -1624,10 +1686,11 @@ class _ZulipContentParser {
     })());
 
     final firstChild = nodes.first as dom.Element;
-    final texSource = _parseMath(firstChild, block: true);
-    if (texSource != null) {
+    final parsed = parseMath(firstChild, block: true);
+    if (parsed != null) {
       result.add(MathBlockNode(
-        texSource: texSource,
+        texSource: parsed.texSource,
+        nodes: parsed.nodes,
         debugHtmlNode: kDebugMode ? firstChild : null));
     } else {
       result.add(UnimplementedBlockContentNode(htmlNode: firstChild));
@@ -1659,10 +1722,11 @@ class _ZulipContentParser {
       if (child case dom.Text(text: '\n\n')) continue;
 
       if (child case dom.Element(localName: 'span', className: 'katex-display')) {
-        final texSource = _parseMath(child, block: true);
-        if (texSource != null) {
+        final parsed = parseMath(child, block: true);
+        if (parsed != null) {
           result.add(MathBlockNode(
-            texSource: texSource,
+            texSource: parsed.texSource,
+            nodes: parsed.nodes,
             debugHtmlNode: debugHtmlNode));
           continue;
         }