Mutable List interface for children and childNodes

web/CHANGELOG.md

@@ -8,6 +8,9 @@
 - Added `URL.toDart` and `Uri.toJS` extension methods.
 - Added missing `Document` and `Window` pointer event getters: `onDrag*`,
   `onTouch*`, `onMouse*`.
+- Added `JSLiveNodeListWrapper` to support mutable operations on node lists. 
+- Added `childNodesAsList` to `Node` and `childrenAsList` to `Element` via 
+  extensions.  
 
 ## 1.1.1
 

web/lib/src/helpers/extensions.dart

@@ -25,6 +25,7 @@ import 'dart:convert';
 import 'dart:js_interop';
 
 import '../dom.dart';
+import 'lists.dart';
 
 export 'cross_origin.dart'
     show CrossOriginContentWindowExtension, CrossOriginWindowExtension;
@@ -103,3 +104,14 @@ extension UriToURL on Uri {
     }
   }
 }
+
+extension NodeExtension on Node {
+  /// Returns [childNodes] as a modifiable [List].
+  List<Node> get childNodesAsList => JSLiveNodeListWrapper(this, childNodes);
+}
+
+extension ElementExtension on Element {
+  /// Returns [children] as a modifiable [List].
+  List<Element> get childrenAsList =>
+      JSLiveNodeListWrapper<Element, HTMLCollection, Element>(this, children);
+}

web/lib/src/helpers/lists.dart

@@ -4,6 +4,7 @@
 
 import 'dart:collection';
 import 'dart:js_interop';
+import '../dom/dom.dart';
 
 /// `_JSList` acts as a wrapper around a JS list object providing an interface to
 /// access the list items and list length while also allowing us to specify the
@@ -69,3 +70,56 @@ class JSImmutableListWrapper<T extends JSObject, U extends JSObject>
   @override
   U elementAt(int index) => this[index];
 }
+
+/// A wrapper for live node lists. `NodeList` and `HTMLCollection` that are
+/// [live](https://developer.mozilla.org/en-US/docs/Web/API/NodeList#live_vs._static_nodelists)
+/// can be safely modified at runtime. This requires an instance of `P`, a
+/// container that elements would be added to or removed from.
+class JSLiveNodeListWrapper<P extends Node, T extends JSObject, U extends Node>
+    extends JSImmutableListWrapper<T, U> {
+  final P parentNode;
+
+  JSLiveNodeListWrapper(this.parentNode, super.original);
+
+  @override
+  set length(int value) {
+    if (value > length) {
+      throw UnsupportedError('Cannot add null to live node List.');
+    }
+    for (var i = length - 1; i >= value; i--) {
+      parentNode.removeChild(_jsList.item(i));
+    }
+  }
+
+  @override
+  void operator []=(int index, U value) {
+    RangeError.checkValidRange(index, null, length);
+    parentNode.replaceChild(value, _jsList.item(index));
+  }
+
+  @override
+  void add(U element) {
+    // `ListMixin` implementation only works for lists that allow `null`.
+    parentNode.appendChild(element);
+  }
+
+  @override
+  bool remove(Object? element) {
+    // ignore: invalid_runtime_check_with_js_interop_types
+    if ((element is JSAny?) && (element?.isA<Node>() ?? false)) {
+      if ((element as Node).parentNode == parentNode) {
+        parentNode.removeChild(element);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  @override
+  void removeRange(int start, int end) {
+    RangeError.checkValidRange(start, end, length);
+    for (var i = 0; i < end - start; i++) {
+      parentNode.removeChild(this[start]);
+    }
+  }
+}

web/test/helpers_test.dart

@@ -40,6 +40,84 @@ void main() {
     expect(() => dartList[0], returnsNormally);
   });
 
+  test('modify child nodes using JSLiveNodeListWrapper', () {
+    final div = (document.createElement('div'))
+      ..append(document.createElement('div')..textContent = 'e1')
+      ..append(document.createElement('div')..textContent = 'e2')
+      ..append(document.createElement('div')..textContent = 'e3');
+
+    final childNodesList = div.childNodesAsList;
+    final childrenList = div.childrenAsList;
+
+    // Ensure initial list length is correct.
+    expect(childNodesList.length, 3);
+    expect(childrenList.length, 3);
+
+    childrenList.removeWhere((node) => node.textContent == 'e2');
+
+    // Ensure both list were updated.
+    expect(childNodesList.length, 2);
+    expect(childrenList.length, 2);
+
+    // add node via children
+    childrenList.add(document.createElement('div')..textContent = 'e4');
+    // add node via childNodes
+    childNodesList.add(document.createElement('div')..textContent = 'e5');
+    // add node directly to parent
+    div.appendChild(document.createElement('div')..textContent = 'e6');
+
+    // Ensure 3 elements were added to both lists
+    expect(childNodesList.length, 5);
+    expect(childrenList.length, 5);
+
+    // add only text nodes
+    childNodesList
+        .addAll([document.createTextNode('t1'), document.createTextNode('t2')]);
+
+    // Ensure only childNodes list changed
+    expect(childNodesList.map((e) => e.textContent).join(), 'e1e3e4e5e6t1t2');
+    expect(childrenList.map((e) => e.textContent).join(), 'e1e3e4e5e6');
+
+    // replace element with text node
+    childNodesList[2] = document.createTextNode('t3');
+
+    // test retainWhere, keep Elements only
+    childNodesList.retainWhere((e) => e.isA<Element>());
+
+    // Ensure only text nodes were removed
+    expect(childNodesList.length, 4);
+    expect(childrenList.length, 4);
+
+    // test removeRange
+    childrenList.removeRange(1, 3);
+
+    // Ensure 2 elements were removed
+    expect(childNodesList.map((e) => e.textContent).join(), 'e1e6');
+    expect(childrenList.map((e) => e.textContent).join(), 'e1e6');
+
+    // test []= range exception
+    expect(() => childNodesList[10] = document.createTextNode('nope'),
+        throwsRangeError);
+
+    // test remove
+    final removeMe = childNodesList[0];
+    expect(childNodesList.remove(removeMe), true);
+    expect(childNodesList.length, 1);
+
+    // test remove with objects that are not in list
+    expect(childNodesList.remove(removeMe), false);
+    expect(childNodesList.remove(null), false);
+    // ignore: collection_methods_unrelated_type
+    expect(childNodesList.remove('test'), false);
+
+    final differentParentDiv = document.createElement('div');
+    document.createElement('div').append(differentParentDiv);
+    expect(childNodesList.remove(differentParentDiv), false);
+
+    // test if nothing was removed
+    expect(childNodesList.length, 1);
+  });
+
   test('responseHeaders transforms headers into a map', () async {
     final request = XMLHttpRequest()
       ..open('GET', 'www.google.com')