Remove nodes list from Document to make Document immutable at API level (Resolves #2156) (#2158)

Author: matthew-carroll

super_editor/clones/quill/lib/app.dart

@@ -126,7 +126,7 @@ class _AlwaysTrailingParagraphReaction extends EditReaction {
   @override
   void modifyContent(EditContext editorContext, RequestDispatcher requestDispatcher, List<EditEvent> changeList) {
     final document = editorContext.find<MutableDocument>(Editor.documentKey);
-    final lastNode = document.nodes.lastOrNull;
+    final lastNode = document.lastOrNull;
 
     if (lastNode != null &&
         lastNode is ParagraphNode &&
@@ -140,7 +140,7 @@ class _AlwaysTrailingParagraphReaction extends EditReaction {
     // We need to insert a trailing empty paragraph.
     requestDispatcher.execute([
       InsertNodeAtIndexRequest(
-        nodeIndex: document.nodes.length,
+        nodeIndex: document.nodeCount,
         newNode: ParagraphNode(
           id: Editor.createNodeId(),
           text: AttributedText(""),

super_editor/example/lib/demos/in_the_lab/feature_action_tags.dart

@@ -63,7 +63,7 @@ class _ActionTagsFeatureDemoState extends State<ActionTagsFeatureDemo> {
     setState(() {
       _actions.clear();
 
-      for (final node in _document.nodes) {
+      for (final node in _document) {
         if (node is! TextNode) {
           continue;
         }

super_editor/example/lib/demos/in_the_lab/feature_stable_tags.dart

@@ -64,7 +64,7 @@ class _UserTagsFeatureDemoState extends State<UserTagsFeatureDemo> {
     setState(() {
       _users.clear();
 
-      for (final node in _document.nodes) {
+      for (final node in _document) {
         if (node is! TextNode) {
           continue;
         }

super_editor/example/lib/demos/super_reader/demo_super_reader.dart

@@ -109,19 +109,18 @@ class _SuperReaderDemoState extends State<SuperReaderDemo> {
   }
 
   void _selectAll() {
-    final nodes = _document.nodes;
-    if (nodes.isEmpty) {
+    if (_document.isEmpty) {
       return;
     }
 
     _selection.value = DocumentSelection(
       base: DocumentPosition(
-        nodeId: nodes.first.id,
-        nodePosition: nodes.first.beginningPosition,
+        nodeId: _document.first.id,
+        nodePosition: _document.first.beginningPosition,
       ),
       extent: DocumentPosition(
-        nodeId: nodes.last.id,
-        nodePosition: nodes.last.endPosition,
+        nodeId: _document.last.id,
+        nodePosition: _document.last.endPosition,
       ),
     );
   }

super_editor/example/lib/marketing_video/main_marketing_video.dart

@@ -31,8 +31,8 @@ class _MarketingVideoState extends State<MarketingVideo> {
     _composer = MutableDocumentComposer(
       initialSelection: DocumentSelection.collapsed(
         position: DocumentPosition(
-          nodeId: _document.nodes.first.id,
-          nodePosition: _document.nodes.first.endPosition,
+          nodeId: _document.first.id,
+          nodePosition: _document.first.endPosition,
         ),
       ),
     );
@@ -309,12 +309,12 @@ class DocumentEditingRobot {
             ChangeSelectionRequest(
               DocumentSelection(
                 base: DocumentPosition(
-                  nodeId: _document.nodes.first.id,
-                  nodePosition: _document.nodes.first.beginningPosition,
+                  nodeId: _document.first.id,
+                  nodePosition: _document.first.beginningPosition,
                 ),
                 extent: DocumentPosition(
-                  nodeId: _document.nodes.last.id,
-                  nodePosition: _document.nodes.last.endPosition,
+                  nodeId: _document.last.id,
+                  nodePosition: _document.last.endPosition,
                 ),
               ),
               SelectionChangeType.expandSelection,

super_editor/lib/src/core/document.dart

@@ -17,10 +17,22 @@ import 'package:flutter/widgets.dart';
 /// content.
 ///
 /// To edit the content of a document, see [DocumentEditor].
-abstract class Document {
-  /// Returns all of the content within the document as a list
-  /// of [DocumentNode]s.
-  List<DocumentNode> get nodes;
+abstract class Document implements Iterable<DocumentNode> {
+  /// The number of [DocumentNode]s in this [Document].
+  int get nodeCount;
+
+  /// Returns `true` if this [Document] has zero nodes, or `false` if it
+  /// has `1+ nodes.
+  @override
+  bool get isEmpty;
+
+  /// Returns the first [DocumentNode] in this [Document], or `null` if this
+  /// [Document] is empty.
+  DocumentNode? get firstOrNull;
+
+  /// Returns the last [DocumentNode] in this [Document], or `null` if this
+  /// [Document] is empty.
+  DocumentNode? get lastOrNull;
 
   /// Returns the [DocumentNode] with the given [nodeId], or [null]
   /// if no such node exists.
@@ -240,7 +252,7 @@ class DocumentPosition {
   ///
   /// ```dart
   /// final documentPosition = DocumentPosition(
-  ///   nodeId: documentEditor.document.nodes.first.id,
+  ///   nodeId: documentEditor.document.first.id,
   ///   nodePosition: TextNodePosition(offset: 1),
   /// );
   /// ```

super_editor/lib/src/core/document_selection.dart

@@ -376,11 +376,9 @@ extension InspectDocumentSelection on Document {
   /// from upstream to downstream.
   List<DocumentNode> getNodesInContentOrder(DocumentSelection selection) {
     final upstreamPosition = selectUpstreamPosition(selection.base, selection.extent);
-    final upstreamIndex = getNodeIndexById(upstreamPosition.nodeId);
     final downstreamPosition = selectDownstreamPosition(selection.base, selection.extent);
-    final downstreamIndex = getNodeIndexById(downstreamPosition.nodeId);
 
-    return nodes.sublist(upstreamIndex, downstreamIndex + 1);
+    return getNodesInside(upstreamPosition, downstreamPosition);
   }
 
   /// Given [docPosition1] and [docPosition2], returns the `DocumentPosition` that

super_editor/lib/src/core/editor.dart

@@ -631,7 +631,7 @@ class MergeRapidTextInputPolicy implements HistoryGroupingPolicy {
       return TransactionMerge.noOpinion;
     }
 
-    if (newTransaction.firstChangeTime.difference(previousTransaction.lastChangeTime!) > _maxMergeTime) {
+    if (newTransaction.firstChangeTime.difference(previousTransaction.lastChangeTime) > _maxMergeTime) {
       // The text insertions were far enough apart in time that we don't want to merge them.
       return TransactionMerge.noOpinion;
     }
@@ -989,7 +989,7 @@ class FunctionalEditListener implements EditListener {
 }
 
 /// An in-memory, mutable [Document].
-class MutableDocument implements Document, Editable {
+class MutableDocument with Iterable<DocumentNode> implements Document, Editable {
   /// Creates an in-memory, mutable version of a [Document].
   ///
   /// Initializes the content of this [MutableDocument] with the given [nodes],
@@ -1026,7 +1026,10 @@ class MutableDocument implements Document, Editable {
   final List<DocumentNode> _nodes;
 
   @override
-  List<DocumentNode> get nodes => UnmodifiableListView(_nodes);
+  int get nodeCount => _nodes.length;
+
+  @override
+  bool get isEmpty => _nodes.isEmpty;
 
   /// Maps a node id to its index in the node list.
   final Map<String, int> _nodeIndicesById = {};
@@ -1036,6 +1039,15 @@ class MutableDocument implements Document, Editable {
 
   final _listeners = <DocumentChangeListener>[];
 
+  @override
+  Iterator<DocumentNode> get iterator => _nodes.iterator;
+
+  @override
+  DocumentNode? get firstOrNull => _nodes.lastOrNull;
+
+  @override
+  DocumentNode? get lastOrNull => _nodes.lastOrNull;
+
   @override
   DocumentNode? getNodeById(String nodeId) {
     return _nodesById[nodeId];
@@ -1206,13 +1218,12 @@ class MutableDocument implements Document, Editable {
   /// ignores the runtime type of the [Document], itself.
   @override
   bool hasEquivalentContent(Document other) {
-    final otherNodes = other.nodes;
-    if (_nodes.length != otherNodes.length) {
+    if (_nodes.length != other.nodeCount) {
       return false;
     }
 
     for (int i = 0; i < _nodes.length; ++i) {
-      if (!_nodes[i].hasEquivalentContent(otherNodes[i])) {
+      if (!_nodes[i].hasEquivalentContent(other.getNodeAt(i)!)) {
         return false;
       }
     }
@@ -1277,7 +1288,7 @@ class MutableDocument implements Document, Editable {
       identical(this, other) ||
       other is MutableDocument &&
           runtimeType == other.runtimeType &&
-          const DeepCollectionEquality().equals(_nodes, other.nodes);
+          const DeepCollectionEquality().equals(_nodes, other._nodes);
 
   @override
   int get hashCode => _nodes.hashCode;

super_editor/lib/src/core/styles.dart

@@ -216,7 +216,7 @@ class _LastBlockMatcher implements _BlockMatcher {
 
   @override
   bool matches(Document document, DocumentNode node) {
-    return document.getNodeIndexById(node.id) == document.nodes.length - 1;
+    return document.getNodeIndexById(node.id) == document.nodeCount - 1;
   }
 }
 

super_editor/lib/src/default_editor/common_editor_operations.dart

@@ -209,21 +209,20 @@ class CommonEditorOperations {
   ///
   /// Always returns [true].
   bool selectAll() {
-    final nodes = document.nodes;
-    if (nodes.isEmpty) {
+    if (document.isEmpty) {
       return false;
     }
 
     editor.execute([
       ChangeSelectionRequest(
         DocumentSelection(
           base: DocumentPosition(
-            nodeId: nodes.first.id,
-            nodePosition: nodes.first.beginningPosition,
+            nodeId: document.first.id,
+            nodePosition: document.first.beginningPosition,
           ),
           extent: DocumentPosition(
-            nodeId: nodes.last.id,
-            nodePosition: nodes.last.endPosition,
+            nodeId: document.last.id,
+            nodePosition: document.last.endPosition,
           ),
         ),
         SelectionChangeType.expandSelection,
@@ -665,11 +664,11 @@ class CommonEditorOperations {
       return false;
     }
 
-    if (document.nodes.isEmpty) {
+    if (document.isEmpty) {
       return false;
     }
 
-    final firstNode = document.nodes.first;
+    final firstNode = document.first;
 
     if (expand) {
       final currentExtentNode = document.getNodeById(composer.selection!.extent.nodeId);
@@ -729,11 +728,11 @@ class CommonEditorOperations {
       return false;
     }
 
-    if (document.nodes.isEmpty) {
+    if (document.isEmpty) {
       return false;
     }
 
-    final lastNode = document.nodes.last;
+    final lastNode = document.last;
 
     if (expand) {
       final currentExtentNode = document.getNodeById(composer.selection!.extent.nodeId);