[SuperEditor] Fix crash due to conflicting attributions in SelectedTextColorStrategy (Resolves #2084) (#2086)

Author: angelosilvestre

attributed_text/lib/src/attributed_text.dart

@@ -171,20 +171,48 @@ class AttributedText {
   /// Adds the given [attribution] to all characters within the given
   /// [range], inclusive.
   ///
-  /// When [autoMerge] is `true`, the new attribution is merged with any
-  /// preceding or following attribution whose [Attribution.canMergeWith] returns
-  /// `true`.
+  /// The effect of adding an attribution is straight forward when the text doesn't
+  /// contain any other attributions with the same ID. However, there are various
+  /// situations where the [attribution] can't necessarily co-exist with other
+  /// attribution spans that already exist in the text.
+  ///
+  /// Attribution overlaps can take one of two forms: mergeable or conflicting.
+  ///
+  /// ## Mergeable Attribution Spans
+  /// An example of a mergeable overlap is where two bold spans overlap each
+  /// other. All bold attributions are interchangeable, so when two bold spans
+  /// overlap, those spans can be merged together into a single span.
+  ///
+  /// However, mergeable overlapping spans are not automatically merged. Instead,
+  /// this decision is left to the user of this class. If you want [AttributedText] to
+  /// merge overlapping mergeable spans, pass `true` for [autoMerge]. Otherwise,
+  /// if [autoMerge] is `false`, an exception is thrown when two mergeable spans
+  /// overlap each other.
+  ///
+  ///
+  /// ## Conflicting Attribution Spans
+  /// An example of a conflicting overlap is where a black text color overlaps a red
+  /// text color. Text is either black, OR red, but never both. Therefore, the black
+  /// attribution cannot co-exist with the red attribution. Something must be done
+  /// to resolve this.
+  ///
+  /// There are two possible ways to handle conflicting overlaps. The new attribution
+  /// can overwrite the existing attribution where they overlap. Or, an exception can be
+  /// thrown. To overwrite the existing attribution with the new attribution, pass `true`
+  /// for [overwriteConflictingSpans]. Otherwise, if [overwriteConflictingSpans]
+  /// is `false`, an exception is thrown.
   void addAttribution(
     Attribution attribution,
     SpanRange range, {
     bool autoMerge = true,
+    bool overwriteConflictingSpans = false,
   }) {
     spans.addAttribution(
       newAttribution: attribution,
       start: range.start,
       end: range.end,
       autoMerge: autoMerge,
-      overwriteConflictingSpans: false,
+      overwriteConflictingSpans: overwriteConflictingSpans,
     );
     _notifyListeners();
   }

super_editor/lib/src/default_editor/layout_single_column/_styler_user_selection.dart

@@ -138,11 +138,15 @@ class SingleColumnLayoutSelectionStyler extends SingleColumnLayoutStylePhase {
             textSelection != null && _selectedTextColorStrategy != null && componentTextColor != null
                 ? (viewModel.text.copyText(0)
                   ..addAttribution(
-                      ColorAttribution(_selectedTextColorStrategy!(
-                        originalTextColor: componentTextColor,
-                        selectionHighlightColor: _selectionStyles.selectionColor,
-                      )),
-                      SpanRange(textSelection.start, textSelection.end - 1)))
+                    ColorAttribution(_selectedTextColorStrategy!(
+                      originalTextColor: componentTextColor,
+                      selectionHighlightColor: _selectionStyles.selectionColor,
+                    )),
+                    SpanRange(textSelection.start, textSelection.end - 1),
+                    // The selected range might already have a color attribution. We want to override it
+                    // with the selected text color.
+                    overwriteConflictingSpans: true,
+                  ))
                 : viewModel.text;
 
         viewModel

super_editor/pubspec.yaml

@@ -41,8 +41,8 @@ dependencies:
 dependency_overrides:
   #  # Override to local mono-repo path so devs can test this repo
   #  # against changes that they're making to other mono-repo packages
-#  attributed_text:
-#    path: ../attributed_text
+  attributed_text:
+    path: ../attributed_text
 #  super_text_layout:
 #    path: ../super_text_layout
 

super_editor/test/super_editor/supereditor_selection_test.dart

@@ -38,6 +38,56 @@ void main() {
         expect(richText.getSpanForPosition(const TextPosition(offset: 6))!.style!.color, Colors.white);
         expect(richText.getSpanForPosition(const TextPosition(offset: 10))!.style!.color, Colors.white);
       });
+
+      testWidgetsOnAllPlatforms("overrides existing color attributions", (tester) async {
+        final stylesheet = defaultStylesheet.copyWith(
+          selectedTextColorStrategy: ({required Color originalTextColor, required Color selectionHighlightColor}) {
+            return Colors.white;
+          },
+        );
+
+        // Pump an editor with green text throught the document.
+        await tester //
+            .createDocument()
+            .withCustomContent(
+              MutableDocument(
+                nodes: [
+                  ParagraphNode(
+                    id: '1',
+                    text: AttributedText(
+                      'Lorem ipsum dolor',
+                      AttributedSpans(
+                        attributions: [
+                          SpanMarker(
+                              attribution: const ColorAttribution(Colors.green),
+                              offset: 0,
+                              markerType: SpanMarkerType.start),
+                          SpanMarker(
+                              attribution: const ColorAttribution(Colors.green),
+                              offset: 16,
+                              markerType: SpanMarkerType.end),
+                        ],
+                      ),
+                    ),
+                  ),
+                ],
+              ),
+            )
+            .useStylesheet(stylesheet)
+            .pump();
+
+        // Double tap to select the word "Lorem".
+        await tester.doubleTapInParagraph('1', 2);
+
+        // Ensure that the first word is white and the rest is green.
+        final richText = SuperEditorInspector.findRichTextInParagraph('1');
+
+        expect(richText.getSpanForPosition(const TextPosition(offset: 0))!.style!.color, Colors.white);
+        expect(richText.getSpanForPosition(const TextPosition(offset: 4))!.style!.color, Colors.white);
+
+        expect(richText.getSpanForPosition(const TextPosition(offset: 5))!.style!.color, Colors.green);
+        expect(richText.getSpanForPosition(const TextPosition(offset: 16))!.style!.color, Colors.green);
+      });
     });
 
     testWidgetsOnArbitraryDesktop("calculates upstream document selection within a single node", (tester) async {