[SuperEditor] - Make all DocumentNodes immutable (Resolves #2166) (#2384)

Author: matthew-carroll

super_editor/clones/quill/lib/editor/editor.dart

@@ -226,14 +226,19 @@ class ClearTextAttributionsCommand extends EditCommand {
         resizeSpansToFitInRange: true,
       );
       for (final span in spans) {
-        node.text = AttributedText(
-          node.text.text,
-          node.text.spans.copy()
-            ..removeAttribution(
-              attributionToRemove: span.attribution,
-              start: span.start,
-              end: span.end,
+        document.replaceNode(
+          oldNode: node,
+          newNode: node.copyTextNodeWith(
+            text: AttributedText(
+              node.text.text,
+              node.text.spans.copy()
+                ..removeAttribution(
+                  attributionToRemove: span.attribution,
+                  start: span.start,
+                  end: span.end,
+                ),
             ),
+          ),
         );
 
         executor.logChanges([

super_editor/lib/src/core/document.dart

@@ -55,14 +55,28 @@ abstract class Document implements Iterable<DocumentNode> {
   /// given [node] in this [Document], or null if the given [node]
   /// is the first node, or the given [node] does not exist in this
   /// [Document].
+  @Deprecated("Use getNodeBeforeById() instead")
   DocumentNode? getNodeBefore(DocumentNode node);
 
+  /// Returns the [DocumentNode] that appears immediately before the
+  /// node with the given [nodeId] in this [Document], or `null` if
+  /// the matching node is the first node in the document, or no such
+  /// node exists.
+  DocumentNode? getNodeBeforeById(String nodeId);
+
   /// Returns the [DocumentNode] that appears immediately after the
   /// given [node] in this [Document], or null if the given [node]
   /// is the last node, or the given [node] does not exist in this
   /// [Document].
+  @Deprecated("Use getNodeAfterById() instead")
   DocumentNode? getNodeAfter(DocumentNode node);
 
+  /// Returns the [DocumentNode] that appears immediately after the
+  /// node with the given [nodeId] in this [Document], or `null` if
+  /// the matching node is the last node in the document, or no such
+  /// node exists.
+  DocumentNode? getNodeAfterById(String nodeId);
+
   /// Returns the [DocumentNode] at the given [position], or [null] if
   /// no such node exists in this [Document].
   DocumentNode? getNode(DocumentPosition position);
@@ -308,14 +322,43 @@ class DocumentPosition {
 }
 
 /// A single content node within a [Document].
-abstract class DocumentNode implements ChangeNotifier {
+@immutable
+abstract class DocumentNode {
   DocumentNode({
     Map<String, dynamic>? metadata,
   }) : _metadata = metadata ?? {};
 
+  /// Adds [addedMetadata] to this nodes [metadata].
+  ///
+  /// This protected method is intended to be used only during constructor
+  /// initialization by subclasses, so that subclasses can inject needed metadata
+  /// during construction time. This special method is provided because [DocumentNode]s
+  /// are otherwise immutable.
+  ///
+  /// For example, a `ParagraphNode` might need to ensure that its block type
+  /// metadata is set to `paragraphAttribution`:
+  ///
+  ///     ParagraphNode({
+  ///       required super.id,
+  ///       required super.text,
+  ///       this.indent = 0,
+  ///       super.metadata,
+  ///     }) {
+  ///       if (getMetadataValue("blockType") == null) {
+  ///         initAddToMetadata({"blockType": paragraphAttribution});
+  ///       }
+  ///     }
+  ///
+  @protected
+  void initAddToMetadata(Map<String, dynamic> addedMetadata) {
+    _metadata.addAll(addedMetadata);
+  }
+
   /// ID that is unique within a [Document].
   String get id;
 
+  bool get isDeletable => _metadata[NodeMetadata.isDeletable] != false;
+
   /// Returns the [NodePosition] that corresponds to the beginning
   /// of content in this node.
   ///
@@ -380,49 +423,31 @@ abstract class DocumentNode implements ChangeNotifier {
   }
 
   /// Returns all metadata attached to this [DocumentNode].
-  Map<String, dynamic> get metadata => _metadata;
+  Map<String, dynamic> get metadata => Map.from(_metadata);
 
   final Map<String, dynamic> _metadata;
 
-  /// Sets all metadata for this [DocumentNode], removing all
-  /// existing values.
-  set metadata(Map<String, dynamic>? newMetadata) {
-    if (const DeepCollectionEquality().equals(_metadata, newMetadata)) {
-      return;
-    }
-
-    _metadata.clear();
-    if (newMetadata != null) {
-      _metadata.addAll(newMetadata);
-    }
-    notifyListeners();
-  }
-
   /// Returns `true` if this node has a non-null metadata value for
   /// the given metadata [key], and returns `false`, otherwise.
   bool hasMetadataValue(String key) => _metadata[key] != null;
 
   /// Returns this node's metadata value for the given [key].
   dynamic getMetadataValue(String key) => _metadata[key];
 
-  /// Sets this node's metadata value for the given [key] to the given
-  /// [value], and notifies node listeners that a change has occurred.
-  void putMetadataValue(String key, dynamic value) {
-    if (_metadata[key] == value) {
-      return;
-    }
+  /// Returns a copy of this [DocumentNode] with [newProperties] added to
+  /// the node's metadata.
+  ///
+  /// If [newProperties] contains keys that already exist in this node's
+  /// metadata, the existing properties are overwritten by [newProperties].
+  DocumentNode copyWithAddedMetadata(Map<String, dynamic> newProperties);
 
-    _metadata[key] = value;
-    notifyListeners();
-  }
+  /// Returns a copy of this [DocumentNode], replacing its existing
+  /// metadata with [newMetadata].
+  DocumentNode copyAndReplaceMetadata(Map<String, dynamic> newMetadata);
 
   /// Returns a copy of this node's metadata.
   Map<String, dynamic> copyMetadata() => Map.from(_metadata);
 
-  DocumentNode copy();
-
-  bool get isDeletable => _metadata[NodeMetadata.isDeletable] != false;
-
   @override
   bool operator ==(Object other) =>
       identical(this, other) ||

super_editor/lib/src/core/editor.dart

@@ -1067,7 +1067,7 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
   }) : _nodes = nodes ?? [] {
     _refreshNodeIdCaches();
 
-    _latestNodesSnapshot = _nodes.map((node) => node.copy()).toList();
+    _latestNodesSnapshot = List.from(_nodes);
   }
 
   /// Creates an [Document] with a single [ParagraphNode].
@@ -1153,13 +1153,23 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
 
   @override
   DocumentNode? getNodeBefore(DocumentNode node) {
-    final nodeIndex = getNodeIndexById(node.id);
+    return getNodeBeforeById(node.id);
+  }
+
+  @override
+  DocumentNode? getNodeBeforeById(String nodeId) {
+    final nodeIndex = getNodeIndexById(nodeId);
     return nodeIndex > 0 ? getNodeAt(nodeIndex - 1) : null;
   }
 
   @override
   DocumentNode? getNodeAfter(DocumentNode node) {
-    final nodeIndex = getNodeIndexById(node.id);
+    return getNodeAfterById(node.id);
+  }
+
+  @override
+  DocumentNode? getNodeAfterById(String nodeId) {
+    final nodeIndex = getNodeIndexById(nodeId);
     return nodeIndex >= 0 && nodeIndex < _nodes.length - 1 ? getNodeAt(nodeIndex + 1) : null;
   }
 
@@ -1196,20 +1206,20 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
 
   /// Inserts [newNode] immediately before the given [existingNode].
   void insertNodeBefore({
-    required DocumentNode existingNode,
+    required String existingNodeId,
     required DocumentNode newNode,
   }) {
-    final nodeIndex = _nodes.indexOf(existingNode);
+    final nodeIndex = getNodeIndexById(existingNodeId);
     _nodes.insert(nodeIndex, newNode);
     _refreshNodeIdCaches();
   }
 
   /// Inserts [newNode] immediately after the given [existingNode].
   void insertNodeAfter({
-    required DocumentNode existingNode,
+    required String existingNodeId,
     required DocumentNode newNode,
   }) {
-    final nodeIndex = _nodes.indexOf(existingNode);
+    final nodeIndex = getNodeIndexById(existingNodeId);
     if (nodeIndex >= 0 && nodeIndex < _nodes.length) {
       _nodes.insert(nodeIndex + 1, newNode);
       _refreshNodeIdCaches();
@@ -1235,14 +1245,17 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
   }
 
   /// Deletes the given [node] from the [Document].
-  bool deleteNode(DocumentNode node) {
+  bool deleteNode(String nodeId) {
     bool isRemoved = false;
 
-    isRemoved = _nodes.remove(node);
-    if (isRemoved) {
-      _refreshNodeIdCaches();
+    final index = getNodeIndexById(nodeId);
+    if (index < 0) {
+      return false;
     }
 
+    _nodes.removeAt(index);
+    _refreshNodeIdCaches();
+
     return isRemoved;
   }
 
@@ -1269,13 +1282,14 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
   }
 
   /// Replaces the given [oldNode] with the given [newNode]
+  @Deprecated("Use replaceNodeById() instead")
   void replaceNode({
     required DocumentNode oldNode,
     required DocumentNode newNode,
   }) {
     final index = _nodes.indexOf(oldNode);
 
-    if (index != -1) {
+    if (index >= 0) {
       _nodes.removeAt(index);
       _nodes.insert(index, newNode);
       _refreshNodeIdCaches();
@@ -1284,7 +1298,25 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
     }
   }
 
-  /// Returns `true` if the content of the [other] [Document] is equivalent
+  /// Replaces the node with the given [nodeId] with the given [newNode].
+  ///
+  /// Throws an exception if no node exists with the given [nodeId].
+  void replaceNodeById(
+    String nodeId,
+    DocumentNode newNode,
+  ) {
+    final index = getNodeIndexById(nodeId);
+
+    if (index >= 0) {
+      _nodes.removeAt(index);
+      _nodes.insert(index, newNode);
+      _refreshNodeIdCaches();
+    } else {
+      throw Exception('Could not find node with ID: $nodeId');
+    }
+  }
+
+  /// Returns [true] if the content of the [other] [Document] is equivalent
   /// to the content of this [Document].
   ///
   /// Content equivalency compares types of content nodes, and the content
@@ -1348,7 +1380,7 @@ class MutableDocument with Iterable<DocumentNode> implements Document, Editable
   void reset() {
     _nodes
       ..clear()
-      ..addAll(_latestNodesSnapshot.map((node) => node.copy()).toList());
+      ..addAll(_latestNodesSnapshot);
     _refreshNodeIdCaches();
 
     _didReset = true;

super_editor/lib/src/default_editor/blockquote.dart

@@ -409,9 +409,10 @@ class SplitBlockquoteCommand extends EditCommand {
     final endText = splitPosition.offset < text.length ? text.copyText(splitPosition.offset) : AttributedText();
 
     // Change the current node's content to just the text before the caret.
-    // TODO: figure out how node changes should work in terms of
-    //       a DocumentEditorTransaction (#67)
-    blockquote.text = startText;
+    document.replaceNodeById(
+      blockquote.id,
+      blockquote.copyParagraphWith(text: startText),
+    );
 
     // Create a new node that will follow the current node. Set its text
     // to the text that was removed from the current node.
@@ -424,7 +425,7 @@ class SplitBlockquoteCommand extends EditCommand {
 
     // Insert the new node after the current node.
     document.insertNodeAfter(
-      existingNode: node,
+      existingNodeId: node.id,
       newNode: newNode,
     );
 

super_editor/lib/src/default_editor/box_component.dart

@@ -15,6 +15,7 @@ import '../core/document_layout.dart';
 final _log = Logger(scope: 'box_component.dart');
 
 /// Base implementation for a [DocumentNode] that only supports [UpstreamDownstreamNodeSelection]s.
+@immutable
 abstract class BlockNode extends DocumentNode {
   BlockNode({
     Map<String, dynamic>? metadata,