feat: Support custom attributes syntax to allow for multiple styles in the text rendering pipeline

packages/flame/lib/src/text/nodes/custom_text_node.dart

@@ -0,0 +1,27 @@
+import 'package:flame/src/text/nodes/inline_text_node.dart';
+import 'package:flame/text.dart';
+
+/// An [InlineTextNode] representing a span of text with a custom style applied.
+class CustomInlineTextNode extends InlineTextNode {
+  final String styleName;
+
+  CustomInlineTextNode(this.child, {required this.styleName});
+
+  CustomInlineTextNode.simple(String text, {required this.styleName})
+      : child = PlainTextNode(text);
+
+  final InlineTextNode child;
+
+  @override
+  void fillStyles(DocumentStyle stylesheet, InlineTextStyle parentTextStyle) {
+    style = FlameTextStyle.merge(
+          parentTextStyle,
+          stylesheet.getCustomStyle(styleName),
+        ) ??
+        stylesheet.text;
+    child.fillStyles(stylesheet, style);
+  }
+
+  @override
+  TextNodeLayoutBuilder get layoutBuilder => child.layoutBuilder;
+}

packages/flame/lib/src/text/nodes/inline_text_node.dart

@@ -9,6 +9,7 @@ import 'package:flame/text.dart';
 /// * ItalicTextNode - italic string
 /// * CodeTextNode - inline code string
 /// * StrikethroughTextNode - strikethrough string
+/// * CustomTextNode - applies arbitrary attributes to a span of text
 /// * GroupTextNode - collection of multiple [InlineTextNode]'s to be joined one
 ///                   after the other.
 abstract class InlineTextNode extends TextNode<InlineTextStyle> {

packages/flame/lib/src/text/styles/document_style.dart

@@ -22,6 +22,7 @@ class DocumentStyle extends FlameTextStyle {
     InlineTextStyle? italicText,
     InlineTextStyle? codeText,
     InlineTextStyle? strikethroughText,
+    Map<String, InlineTextStyle>? customStyles,
     BlockStyle? paragraph,
     BlockStyle? header1,
     BlockStyle? header2,
@@ -38,6 +39,7 @@ class DocumentStyle extends FlameTextStyle {
           StrikethroughTextNode.defaultStyle,
           strikethroughText,
         ),
+        _customStyles = customStyles,
         _paragraph =
             FlameTextStyle.merge(ParagraphNode.defaultStyle, paragraph),
         _header1 = FlameTextStyle.merge(HeaderNode.defaultStyleH1, header1),
@@ -52,6 +54,7 @@ class DocumentStyle extends FlameTextStyle {
   final InlineTextStyle? _italicText;
   final InlineTextStyle? _codeText;
   final InlineTextStyle? _strikethroughText;
+  final Map<String, InlineTextStyle>? _customStyles;
   final BlockStyle? _paragraph;
   final BlockStyle? _header1;
   final BlockStyle? _header2;
@@ -106,6 +109,10 @@ class DocumentStyle extends FlameTextStyle {
   InlineTextStyle get codeText => _codeText!;
   InlineTextStyle get strikethroughText => _strikethroughText!;
 
+  InlineTextStyle? getCustomStyle(String className) {
+    return _customStyles?[className];
+  }
+
   /// Style for [ParagraphNode]s.
   BlockStyle get paragraph => _paragraph!;
 

packages/flame/lib/text.dart

@@ -18,6 +18,7 @@ export 'src/text/nodes/block_node.dart' show BlockNode;
 export 'src/text/nodes/bold_text_node.dart' show BoldTextNode;
 export 'src/text/nodes/code_text_node.dart' show CodeTextNode;
 export 'src/text/nodes/column_node.dart' show ColumnNode;
+export 'src/text/nodes/custom_text_node.dart' show CustomInlineTextNode;
 export 'src/text/nodes/document_root.dart' show DocumentRoot;
 export 'src/text/nodes/group_text_node.dart' show GroupTextNode;
 export 'src/text/nodes/header_node.dart' show HeaderNode;

packages/flame_markdown/example/assets/fire_and_ice.md

@@ -7,3 +7,5 @@ Some say in *ice*.
 From what I've tasted of >desire<,
 
 I hold with those who favor **fire**.
+
+[- by Robert Frost]{.author}

packages/flame_markdown/example/lib/main.dart

@@ -4,6 +4,7 @@ import 'package:flame/components.dart';
 import 'package:flame/flame.dart';
 import 'package:flame/game.dart';
 import 'package:flame/text.dart';
+import 'package:flame_markdown/custom_attribute_syntax.dart';
 import 'package:flame_markdown/flame_markdown.dart';
 import 'package:flutter/widgets.dart' hide Animation;
 import 'package:markdown/markdown.dart';
@@ -26,11 +27,19 @@ class MarkdownGame extends FlameGame {
             encodeHtml: false,
             inlineSyntaxes: [
               StrikethroughSyntax(),
+              CustomAttributeSyntax(),
             ],
           ),
         ),
         style: DocumentStyle(
           padding: const EdgeInsets.all(16),
+          customStyles: {
+            'author': InlineTextStyle(
+              color: const Color(0xFF888888),
+              fontSize: 16,
+              fontStyle: FontStyle.italic,
+            ),
+          },
         ),
         size: size,
       ),

packages/flame_markdown/example/pubspec.yaml

@@ -12,7 +12,7 @@ dependencies:
   flame_markdown: ^0.2.3+2
   flutter:
     sdk: flutter
-  markdown: ^7.1.1
+  markdown: ^7.3.0
 
 dev_dependencies:
   flame_lint: ^1.2.2

packages/flame_markdown/lib/custom_attribute_syntax.dart

@@ -0,0 +1,111 @@
+import 'package:markdown/markdown.dart';
+
+// cSpell:ignore charcode.dart (file name from another package)
+// NOTE: values obtained from file `charcode.dart` from the markdown package
+class _Chars {
+  /// Character `[`.
+  static const int leftBracket = 0x5B;
+
+  /// Character `{`.
+  static const int leftBrace = 0x7B;
+
+  /// Character `}`.
+  static const int rightBrace = 0x7D;
+}
+
+/// Allows for a toned-down version of custom attributes extension for markdown,
+/// inspired by the markdown-it-attrs package.
+///
+/// This allows users to specify a custom class name to a span of text:
+///
+/// ```markdown
+/// [This is a custom class]{.my-custom-class}
+/// This word will be [red]{.red} and this one will be [blue]{.blue}.
+/// ```
+///
+/// This is based on the standard Link markdown parser (which matches the
+/// `[text](url)` and `[text][ref]` syntaxes).
+class CustomAttributeSyntax extends LinkSyntax {
+  /// Creates a new custom attribute syntax.
+  CustomAttributeSyntax()
+      : super(
+          pattern: r'\[',
+          startCharacter: _Chars.leftBracket,
+        );
+
+  @override
+  Iterable<Node>? close(
+    InlineParser parser,
+    covariant SimpleDelimiter opener,
+    Delimiter? closer, {
+    required List<Node> Function() getChildren,
+    String? tag,
+  }) {
+    final text = parser.source.substring(opener.endPos, parser.pos);
+
+    // The current character is the `]` that closed the span text.
+    // The next character must be a `{`:
+    parser.advanceBy(1);
+    if (parser.isDone) {
+      return null; // not valid syntax - skip
+    }
+    final char = parser.charAt(parser.pos);
+    if (char != _Chars.leftBrace) {
+      return null; // not valid syntax - skip
+    }
+
+    final attributes = _parseAttributes(parser) ?? {};
+    final node = _createNode(text, attributes, getChildren: getChildren);
+    return [node];
+  }
+
+  /// Create this node represented by a span with custom attributes.
+  Node _createNode(
+    String text,
+    Map<String, String> attributes, {
+    required List<Node> Function() getChildren,
+  }) {
+    final children = getChildren();
+    final element = Element('span', children);
+    for (final attr in attributes.entries) {
+      element.attributes[attr.key] = attr.value;
+    }
+    return element;
+  }
+
+  /// At this point, we have parsed a custom tag opening `[`, and then a
+  /// matching closing `]`, and now [parser] is pointing at an opening `{`.
+  Map<String, String>? _parseAttributes(InlineParser parser) {
+    // Start walking to the character just after the opening `{`.
+    parser.advanceBy(1);
+
+    final buffer = StringBuffer();
+
+    while (true) {
+      final char = parser.charAt(parser.pos);
+      if (char == _Chars.rightBrace) {
+        final attributes = buffer.toString();
+        return _parseAttributeList(attributes);
+      }
+
+      buffer.writeCharCode(char);
+      parser.advanceBy(1);
+      if (parser.isDone) {
+        return null; // not valid syntax - skip
+      }
+    }
+  }
+
+  Map<String, String>? _parseAttributeList(String attributes) {
+    // Currently we only support one attribute being the class name.
+    // More support can be added in the future following the syntax from
+    // the markdown-it library.
+    final regex = RegExp(r'\.([a-zA-Z0-9_-]+)'); // matches `.class-name`
+    final content = attributes.trim();
+    final className = regex.firstMatch(content)?.group(1);
+    if (className == null) {
+      return null; // not valid syntax - skip
+    }
+    return {'class': className};
+  }
+}

packages/flame_markdown/lib/flame_markdown.dart

@@ -51,7 +51,20 @@ class FlameMarkdown {
         .map(_castCheck<InlineTextNode>)
         .toList();
     final child = _groupInlineChildren(children);
+
+    final customClassName = element.attributes['class'];
+    if (customClassName != null) {
+      if (element.tag != 'span') {
+        throw Exception(
+          'Invalid markdown structure: '
+          'Only <span> elements can have custom classes',
+        );
+      }
+      return CustomInlineTextNode(child, styleName: customClassName);
+    }
+
     return switch (element.tag) {
+      'span' => child,
       'h1' => HeaderNode(child, level: 1),
       'h2' => HeaderNode(child, level: 2),
       'h3' => HeaderNode(child, level: 3),

packages/flame_markdown/test/flame_markdown_test.dart

@@ -2,6 +2,7 @@ import 'dart:io';
 import 'dart:ui';
 
 import 'package:flame/text.dart';
+import 'package:flame_markdown/custom_attribute_syntax.dart';
 import 'package:flame_markdown/flame_markdown.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:markdown/markdown.dart';
@@ -299,6 +300,10 @@ void main() {
                 (node) => _expectPlain(node, '.'),
               ]);
             }),
+        // note: custom attribute is only parsed if enabled
+        (node) => _expectParagraph(node, (p) {
+              _expectPlain(p, '[- by Robert Frost]{.author}');
+            }),
       ]);
     });
 
@@ -324,6 +329,93 @@ void main() {
             }),
       ]);
     });
+
+    test('custom attributes can be enabled', () {
+      const markdown =
+          'This one will be [red]{.red} and this one will be [blue]{.blue}.';
+      final doc = FlameMarkdown.toDocument(
+        markdown,
+        document: Document(
+          encodeHtml: false,
+          inlineSyntaxes: [
+            CustomAttributeSyntax(),
+          ],
+        ),
+      );
+
+      _expectDocument(doc, [
+        (node) => _expectParagraph(node, (p) {
+              _expectGroup(p, [
+                (node) => _expectPlain(node, 'This one will be '),
+                (node) => _expectCustom(node, 'red', styleName: 'red'),
+                (node) => _expectPlain(node, ' and this one will be '),
+                (node) => _expectCustom(node, 'blue', styleName: 'blue'),
+                (node) => _expectPlain(node, '.'),
+              ]);
+            }),
+      ]);
+
+      final element = doc.format(
+        DocumentStyle(
+          width: 1000,
+          text: InlineTextStyle(
+            fontSize: 12,
+          ),
+          customStyles: {
+            'red': InlineTextStyle(
+              color: const Color(0xFFFF0000),
+            ),
+            'blue': InlineTextStyle(
+              color: const Color(0xFF0000FF),
+            ),
+          },
+        ),
+      );
+
+      _expectElementGroup(element, [
+        (el) => _expectElementGroup(el, [
+              (el) => _expectElementGroupText(el, [
+                    (el) => _expectElementTextPainter(
+                          el,
+                          'This one will be ',
+                          const TextStyle(
+                            fontSize: 12,
+                          ),
+                        ),
+                    (el) => _expectElementTextPainter(
+                          el,
+                          'red',
+                          const TextStyle(
+                            fontSize: 12,
+                            color: Color(0xFFFF0000),
+                          ),
+                        ),
+                    (el) => _expectElementTextPainter(
+                          el,
+                          ' and this one will be ',
+                          const TextStyle(
+                            fontSize: 12,
+                          ),
+                        ),
+                    (el) => _expectElementTextPainter(
+                          el,
+                          'blue',
+                          const TextStyle(
+                            fontSize: 12,
+                            color: Color(0xFF0000FF),
+                          ),
+                        ),
+                    (el) => _expectElementTextPainter(
+                          el,
+                          '.',
+                          const TextStyle(
+                            fontSize: 12,
+                          ),
+                        ),
+                  ]),
+            ]),
+      ]);
+    });
   });
 }
 
@@ -374,6 +466,18 @@ void _expectPlain(InlineTextNode node, String text) {
   expect(span.text, text);
 }
 
+void _expectCustom(
+  InlineTextNode node,
+  String text, {
+  required String styleName,
+}) {
+  expect(node, isA<CustomInlineTextNode>());
+  final custom = node as CustomInlineTextNode;
+  expect(custom.child, isA<PlainTextNode>());
+  expect((custom.child as PlainTextNode).text, text);
+  expect(custom.styleName, styleName);
+}
+
 void _expectCode(InlineTextNode node, String text) {
   expect(node, isA<CodeTextNode>());
   final content = (node as CodeTextNode).child;