[SuperEditor][Markdown] - Parse images with captions immediately above them (Resolves #3041) (#3042)

matthew-carroll · matthew-carroll · commit 4ebf89896f51 · 2026-06-10T20:04:47.000-07:00
- BREAKING: Force all TextNode 'textAlign' properties to use Strings instead of randomly switching between Strings and TextAligns.
diff --git a/super_editor/lib/src/default_editor/tables/table_markdown.dart b/super_editor/lib/src/default_editor/tables/table_markdown.dart
@@ -49,7 +49,7 @@ class MarkdownTableComponentBuilder implements ComponentBuilder {
                 nodeId: cell.id,
                 createdAt: cell.metadata[NodeMetadata.createdAt],
                 text: cell.text,
-                textAlign: cell.getMetadataValue(TextNodeMetadata.textAlign) ?? TextAlign.left,
+                textAlign: _maybeParseTextAlign(cell.getMetadataValue(TextNodeMetadata.textAlign)) ?? TextAlign.left,
                 textStyleBuilder: noStyleBuilder,
                 padding: const EdgeInsets.all(8.0),
                 //       ^ Default padding, can be overridden through the stylesheet.
@@ -62,6 +62,16 @@ class MarkdownTableComponentBuilder implements ComponentBuilder {
     );
   }
 
+  TextAlign? _maybeParseTextAlign(String? textAlign) {
+    return switch (textAlign) {
+      'left' => TextAlign.left,
+      'center' => TextAlign.center,
+      'right' => TextAlign.right,
+      'justify' => TextAlign.justify,
+      _ => null,
+    };
+  }
+
   @override
   Widget? createComponent(
       SingleColumnDocumentComponentContext componentContext, SingleColumnLayoutComponentViewModel componentViewModel) {
diff --git a/super_editor/lib/src/default_editor/text.dart b/super_editor/lib/src/default_editor/text.dart
@@ -15,8 +15,8 @@ import 'package:super_editor/src/core/edit_context.dart';
 import 'package:super_editor/src/core/editor.dart';
 import 'package:super_editor/src/core/styles.dart';
 import 'package:super_editor/src/default_editor/attributions.dart';
-import 'package:super_editor/src/default_editor/text_ai.dart';
 import 'package:super_editor/src/default_editor/text/custom_underlines.dart';
+import 'package:super_editor/src/default_editor/text_ai.dart';
 import 'package:super_editor/src/infrastructure/_logging.dart';
 import 'package:super_editor/src/infrastructure/attributed_text_styles.dart';
 import 'package:super_editor/src/infrastructure/composable_text.dart';
@@ -38,7 +38,18 @@ class TextNode extends DocumentNode {
     required this.id,
     required this.text,
     super.metadata,
-  });
+  }) {
+    if (metadata['textAlign'] == null) {
+      initAddToMetadata({
+        'textAlign': 'left',
+      });
+    } else {
+      assert(
+        metadata['textAlign'] is String?,
+        'Expected "textAlign" metadata to be of type String, but got: ${metadata['textAlign']}',
+      );
+    }
+  }
 
   @override
   final String id;
diff --git a/super_editor/lib/src/infrastructure/serialization/html/html_table.dart b/super_editor/lib/src/infrastructure/serialization/html/html_table.dart
@@ -1,4 +1,3 @@
-import 'package:flutter/material.dart';
 import 'package:super_editor/src/core/document.dart';
 import 'package:super_editor/src/default_editor/selection_upstream_downstream.dart';
 import 'package:super_editor/src/default_editor/tables/table_block.dart';
@@ -111,15 +110,15 @@ extension TableBlockNodeToHtml on TableBlockNode {
 
   String _getTextAlignStyle(TextNode cell) {
     final textAlign = cell.getMetadataValue('textAlign');
-    if (textAlign == TextAlign.left) {
-      // Default alignment is left, so we don't need to specify it.
-      return '';
-    }
     final textAlignString = switch (textAlign) {
-      TextAlign.center => 'center',
-      TextAlign.right => 'right',
+      'center' => 'center',
+      'right' => 'right',
       _ => 'left',
     };
+    if (textAlign == 'left') {
+      // Default alignment is left, so we don't need to specify it.
+      return '';
+    }
     return textAlign != null ? ' style="text-align:$textAlignString"' : '';
   }
 }
diff --git a/super_editor/lib/src/infrastructure/serialization/markdown/document_to_markdown_serializer.dart b/super_editor/lib/src/infrastructure/serialization/markdown/document_to_markdown_serializer.dart
@@ -2,7 +2,6 @@ import 'dart:ui';
 
 import 'package:attributed_text/attributed_text.dart';
 import 'package:flutter/foundation.dart';
-import 'package:markdown/markdown.dart' hide Document;
 import 'package:super_editor/src/core/document.dart';
 import 'package:super_editor/src/core/document_selection.dart';
 import 'package:super_editor/src/default_editor/attributions.dart';
@@ -14,7 +13,6 @@ import 'package:super_editor/src/default_editor/selection_upstream_downstream.da
 import 'package:super_editor/src/default_editor/tables/table_block.dart';
 import 'package:super_editor/src/default_editor/tasks.dart';
 import 'package:super_editor/src/default_editor/text.dart';
-
 import 'package:super_editor/src/infrastructure/serialization/markdown/super_editor_syntax.dart';
 
 /// Serializes the given [doc] to Markdown text.
diff --git a/super_editor/lib/src/infrastructure/serialization/markdown/markdown_to_document_parsing.dart b/super_editor/lib/src/infrastructure/serialization/markdown/markdown_to_document_parsing.dart
@@ -213,13 +213,25 @@ class _MarkdownToDocument implements md.NodeVisitor {
         if (blockImage != null) {
           _addImage(blockImage);
         } else {
-          final attributedText = parseInlineMarkdown(
-            element.textContent,
-            inlineMarkdownSyntaxes: inlineMarkdownSyntaxes,
-            inlineHtmlSyntaxes: inlineHtmlSyntaxes,
-            encodeHtml: encodeHtml,
-          );
-          _addParagraph(attributedText, element.attributes);
+          final captionAndImage = _maybeParseImageWithCaption(element.textContent);
+          if (captionAndImage != null) {
+            final captionText = parseInlineMarkdown(
+              captionAndImage.caption,
+              inlineMarkdownSyntaxes: inlineMarkdownSyntaxes,
+              inlineHtmlSyntaxes: inlineHtmlSyntaxes,
+              encodeHtml: encodeHtml,
+            );
+            _addParagraph(captionText, element.attributes);
+            _addImage(captionAndImage.image);
+          } else {
+            final attributedText = parseInlineMarkdown(
+              element.textContent,
+              inlineMarkdownSyntaxes: inlineMarkdownSyntaxes,
+              inlineHtmlSyntaxes: inlineHtmlSyntaxes,
+              encodeHtml: encodeHtml,
+            );
+            _addParagraph(attributedText, element.attributes);
+          }
         }
 
         break;
@@ -328,28 +340,25 @@ class _MarkdownToDocument implements md.NodeVisitor {
         break;
     }
 
-    final textAlign = element.attributes['textAlign'];
     _content.add(
       ParagraphNode(
         id: Editor.createNodeId(),
         text: _parseInlineText(element.textContent),
         metadata: {
           'blockType': headerAttribution,
-          'textAlign': textAlign,
+          'textAlign': element.attributes['textAlign'] ?? 'left',
         },
       ),
     );
   }
 
   void _addParagraph(AttributedText attributedText, Map<String, String> attributes) {
-    final textAlign = attributes['textAlign'];
-
     _content.add(
       ParagraphNode(
         id: Editor.createNodeId(),
         text: attributedText,
         metadata: {
-          'textAlign': textAlign,
+          'textAlign': attributes['textAlign'] ?? 'left',
         },
       ),
     );
@@ -480,6 +489,25 @@ class _MarkdownToDocument implements md.NodeVisitor {
       syntax: syntax,
     );
   }
+
+  /// If the last line of [markdown] is a block image and there is at least one
+  /// preceding line (the caption), returns a [_CaptionAndImage] containing the
+  /// caption text and the parsed image. Otherwise returns `null`.
+  _CaptionAndImage? _maybeParseImageWithCaption(String markdown) {
+    final newlineIndex = markdown.lastIndexOf('\n');
+    if (newlineIndex < 0) {
+      return null;
+    }
+
+    final lastLine = markdown.substring(newlineIndex + 1);
+    final image = _maybeParseBlockImage(lastLine);
+    if (image == null) {
+      return null;
+    }
+
+    final caption = markdown.substring(0, newlineIndex);
+    return _CaptionAndImage(caption: caption, image: image);
+  }
 }
 
 /// Converts a deserialized Markdown element into a [DocumentNode].
@@ -842,6 +870,13 @@ class _HeaderWithAlignmentSyntax extends md.BlockSyntax {
   }
 }
 
+class _CaptionAndImage {
+  const _CaptionAndImage({required this.caption, required this.image});
+
+  final String caption;
+  final _MarkdownImage image;
+}
+
 class _MarkdownImage {
   _MarkdownImage({
     required this.url,
diff --git a/super_editor/lib/src/infrastructure/serialization/markdown/table.dart b/super_editor/lib/src/infrastructure/serialization/markdown/table.dart
@@ -1,5 +1,3 @@
-import 'dart:ui';
-
 import 'package:markdown/markdown.dart' as md;
 import 'package:super_editor/src/core/document.dart';
 import 'package:super_editor/src/core/editor.dart';
@@ -55,7 +53,7 @@ extension ElementTableExtension on md.Element {
           ),
           metadata: const {
             NodeMetadata.blockType: tableHeaderAttribution,
-            TextNodeMetadata.textAlign: TextAlign.center,
+            TextNodeMetadata.textAlign: 'center',
           },
         ),
       );
@@ -81,17 +79,17 @@ extension ElementTableExtension on md.Element {
             throw Exception('Table body cells must be <td> elements');
           }
           final textAlign = switch ((headerRow.children![i] as md.Element).attributes['align']) {
-            'left' => TextAlign.left,
-            'center' => TextAlign.center,
-            'right' => TextAlign.right,
-            _ => TextAlign.left,
+            'left' => 'left',
+            'center' => 'center',
+            'right' => 'right',
+            _ => 'left',
           };
 
           row.add(TextNode(
             id: Editor.createNodeId(),
             text: parseInlineMarkdown(cellElement.textContent),
             metadata: {
-              if (textAlign != TextAlign.left) TextNodeMetadata.textAlign: textAlign,
+              if (textAlign != 'left') TextNodeMetadata.textAlign: textAlign,
             },
           ));
         }
diff --git a/super_editor/lib/src/infrastructure/serialization/quill/serializing/serializers.dart b/super_editor/lib/src/infrastructure/serialization/quill/serializing/serializers.dart
@@ -298,8 +298,9 @@ class TextBlockDeltaSerializer implements DeltaSerializer {
     final blockAttributes = <String, dynamic>{};
 
     // Add all the block-level formats that aren't mutually exclusive.
-    if (textBlock.metadata["textAlign"] != null) {
-      blockAttributes["align"] = textBlock.metadata["textAlign"];
+    final textAlign = textBlock.metadata["textAlign"];
+    if (textAlign != null && textAlign != "left") {
+      blockAttributes["align"] = textAlign;
     }
 
     final blockType = textBlock.metadata["blockType"] as Attribution?;
diff --git a/super_editor/test/infrastructure/serialization/html/document_to_html_test.dart b/super_editor/test/infrastructure/serialization/html/document_to_html_test.dart
@@ -1,5 +1,3 @@
-import 'dart:ui';
-
 import 'package:flutter_test/flutter_test.dart';
 import 'package:super_editor/super_editor.dart';
 
@@ -665,12 +663,12 @@ void main() {
                   TextNode(
                     id: "1.1.1",
                     text: AttributedText("Value 1.1"),
-                    metadata: const {"textAlign": TextAlign.right},
+                    metadata: const {"textAlign": "right"},
                   ),
                   TextNode(
                     id: "1.1.2",
                     text: AttributedText("Value 1.2"),
-                    metadata: const {"textAlign": TextAlign.center},
+                    metadata: const {"textAlign": "center"},
                   ),
                 ],
               ],
diff --git a/super_editor/test/infrastructure/serialization/markdown/super_editor_markdown_test.dart b/super_editor/test/infrastructure/serialization/markdown/super_editor_markdown_test.dart
diff --git a/super_editor/test/infrastructure/serialization/markdown/table_parser_test.dart b/super_editor/test/infrastructure/serialization/markdown/table_parser_test.dart
diff --git a/super_editor/test/infrastructure/serialization/quill/parsing/parsing_test.dart b/super_editor/test/infrastructure/serialization/quill/parsing/parsing_test.dart
diff --git a/super_editor_clipboard/test/copy_and_paste_test.dart b/super_editor_clipboard/test/copy_and_paste_test.dart
