Add .moveNode() to MutableDocument & DocumentEditorTransaction (#634)

Author: roughike

super_editor/lib/src/core/document_editor.dart

@@ -100,6 +100,14 @@ class DocumentEditorTransaction {
     _document.deleteNodeAt(index);
   }
 
+  /// Moves a [DocumentNode] matching the given [nodeId] from its current index
+  /// in the [Document] to the given [targetIndex].
+  ///
+  /// If none of the nodes in this document match [nodeId], throws an error.
+  void moveNode({required String nodeId, required int targetIndex}) {
+    _document.moveNode(nodeId: nodeId, targetIndex: targetIndex);
+  }
+
   /// Replaces the given [oldNode] with the given [newNode]
   void replaceNode({
     required DocumentNode oldNode,
@@ -273,6 +281,22 @@ class MutableDocument with ChangeNotifier implements Document {
     return isRemoved;
   }
 
+  /// Moves a [DocumentNode] matching the given [nodeId] from its current index
+  /// in the [Document] to the given [targetIndex].
+  ///
+  /// If none of the nodes in this document match [nodeId], throws an error.
+  void moveNode({required String nodeId, required int targetIndex}) {
+    final node = getNodeById(nodeId);
+    if (node == null) {
+      throw Exception('Could not find node with nodeId: $nodeId');
+    }
+
+    if (nodes.remove(node)) {
+      nodes.insert(targetIndex, node);
+      notifyListeners();
+    }
+  }
+
   /// Replaces the given [oldNode] with the given [newNode]
   void replaceNode({
     required DocumentNode oldNode,

super_editor/test/src/core/document_editor_test.dart

@@ -3,6 +3,105 @@ import 'package:super_editor/super_editor.dart';
 
 void main() {
   group('MutableDocument', () {
+    group('.moveNode()', () {
+      test('when the document is empty, throws an exception', () {
+        final document = MutableDocument(nodes: []);
+        expect(
+          () => document.moveNode(nodeId: 'does-not-exist', targetIndex: 0),
+          throwsException,
+        );
+      });
+
+      test('when the node does not exist in the document, throws an exception', () {
+        final node = ParagraphNode(id: 'move-me', text: AttributedText());
+        final document = MutableDocument(
+          nodes: [
+            HorizontalRuleNode(id: '0'),
+            node,
+            HorizontalRuleNode(id: '2'),
+          ],
+        );
+
+        expect(
+          () => document.moveNode(nodeId: 'does-not-exist', targetIndex: 0),
+          throwsException,
+        );
+      });
+
+      test('when the given target index is negative, throws a RangeError', () {
+        final node = ParagraphNode(id: 'move-me', text: AttributedText());
+        final document = MutableDocument(
+          nodes: [
+            HorizontalRuleNode(id: '0'),
+            node,
+            HorizontalRuleNode(id: '2'),
+          ],
+        );
+
+        expect(
+          () => document.moveNode(nodeId: 'move-me', targetIndex: -1),
+          throwsRangeError,
+        );
+      });
+
+      test('when the given target index is out of document bounds, throws a RangeError', () {
+        final node = ParagraphNode(id: 'move-me', text: AttributedText());
+        final document = MutableDocument(
+          nodes: [
+            HorizontalRuleNode(id: '0'),
+            node,
+            HorizontalRuleNode(id: '2'),
+          ],
+        );
+
+        expect(
+          () => document.moveNode(nodeId: 'move-me', targetIndex: 3),
+          throwsRangeError,
+        );
+      });
+
+      test('when the node exists in the document, and the targetIndex is valid, moves it to the given target index', () {
+        final node = ParagraphNode(id: 'move-me', text: AttributedText());
+        final document = MutableDocument(
+          nodes: [
+            HorizontalRuleNode(id: '0'),
+            node,
+            HorizontalRuleNode(id: '2'),
+          ],
+        );
+
+        document.moveNode(nodeId: 'move-me', targetIndex: 0);
+        expect(
+          document.nodes,
+          [
+            node, // Node exists at index 0
+            HorizontalRuleNode(id: '0'),
+            HorizontalRuleNode(id: '2'),
+          ],
+        );
+
+        document.moveNode(nodeId: 'move-me', targetIndex: 2);
+        expect(
+          document.nodes,
+          [
+            HorizontalRuleNode(id: '0'),
+            HorizontalRuleNode(id: '2'),
+            node, // Node exists at index 2
+          ],
+        );
+
+        document.moveNode(nodeId: 'move-me', targetIndex: 1);
+        expect(
+          document.nodes,
+          [
+            HorizontalRuleNode(id: '0'),
+            node, // Node exists at index 1
+            HorizontalRuleNode(id: '2'),
+          ],
+        );
+      });
+    });
+
     test('it replaces one node by another ', () {
       final oldNode = ParagraphNode(id: 'old', text: AttributedText());
       final document = MutableDocument(