RemoteMutationObserver improvements (#583)

Author: lemonmade

.changeset/big-lions-train.md

@@ -0,0 +1,28 @@
+---
+'@remote-dom/core': minor
+---
+
+Improved `RemoteMutationObserver` to support automatic emptying and observing multiple nodes
+
+If you are observing a multi-node list — such as a `DocumentFragment` or `<template>` element — you can now provide a custom `id` option when observing each node. This allows you to treat the observer as a kind of "virtual root" for a list of nodes, similar to the role the `DocumentFragment` plays in the DOM. You are responsible for giving each node a unique ID, and this class will take care of correctly attaching that node to the root of the remote tree.
+
+```js
+const observer = new RemoteMutationObserver(connection);
+
+let id = 0;
+for (const child of documentFragment.childNodes) {
+  observer.observe(child, {
+    id: `DocumentFragment:${id++}`,
+  });
+}
+```
+
+You can also now provide an `empty` option to `RemoteMutationObserver.disconnect()` in order to clear out children in remote environment:
+
+```js
+const observer = new RemoteMutationObserver(connection);
+
+observer.observe(container);
+
+observer.disconnect({empty: true});
+```

.changeset/eleven-sloths-worry.md

@@ -0,0 +1,5 @@
+---
+'@remote-dom/core': minor
+---
+
+Expose `remoteId()` and `setRemoteId()` for getting and setting a Node's remote ID

packages/core/source/elements.ts

@@ -26,6 +26,8 @@ export {RemoteEvent} from './elements/RemoteEvent.ts';
 export {RemoteMutationObserver} from './elements/RemoteMutationObserver.ts';
 
 export {
+  remoteId,
+  setRemoteId,
   connectRemoteNode,
   disconnectRemoteNode,
   serializeRemoteNode,

packages/core/source/elements/RemoteMutationObserver.ts

@@ -1,9 +1,9 @@
 import {
   remoteId,
+  setRemoteId,
   connectRemoteNode,
   disconnectRemoteNode,
   serializeRemoteNode,
-  REMOTE_IDS,
 } from './internals.ts';
 import {
   ROOT_ID,
@@ -32,7 +32,10 @@ import type {RemoteConnection, RemoteMutationRecord} from '../types.ts';
  * observer.observe(document.body);
  */
 export class RemoteMutationObserver extends MutationObserver {
-  constructor(private readonly connection: RemoteConnection) {
+  readonly connection: RemoteConnection;
+  readonly #observed: Set<Node>;
+
+  constructor(connection: RemoteConnection) {
     super((records) => {
       const addedNodes: Node[] = [];
       const remoteRecords: RemoteMutationRecord[] = [];
@@ -102,6 +105,9 @@ export class RemoteMutationObserver extends MutationObserver {
 
       connection.mutate(remoteRecords);
     });
+
+    this.connection = connection;
+    this.#observed = new Set();
   }
 
   /**
@@ -112,6 +118,18 @@ export class RemoteMutationObserver extends MutationObserver {
   observe(
     target: Node,
     options?: MutationObserverInit & {
+      /**
+       * The ID of the root element. If you do not provide an ID, a default value
+       * considered to be the “root” element will be used. This means that its remote
+       * attributes, properties, event listeners, and children will all be sent as the root
+       * element to the remote receiver.
+       *
+       * You need to override the default behavior if you are wanting to observe a set of
+       * nodes, and send each of them to the remote receiver. This may be needed when observing
+       * a `DocumentFragment` or `<template>` element, which allow for multiple children.
+       */
+      id?: string;
+
       /**
        * Whether to send the initial state of the tree to the mutation
        * callback.
@@ -121,24 +139,37 @@ export class RemoteMutationObserver extends MutationObserver {
       initial?: boolean;
     },
   ) {
-    REMOTE_IDS.set(target, ROOT_ID);
+    const id = options?.id ?? ROOT_ID;
+    setRemoteId(target, id);
+    this.#observed.add(target);
 
     if (options?.initial !== false && target.childNodes.length > 0) {
-      const records: RemoteMutationRecord[] = [];
-
-      for (let i = 0; i < target.childNodes.length; i++) {
-        const node = target.childNodes[i]!;
-        connectRemoteNode(node, this.connection);
-
-        records.push([
-          MUTATION_TYPE_INSERT_CHILD,
-          ROOT_ID,
-          serializeRemoteNode(node),
-          i,
+      if (id !== ROOT_ID) {
+        this.connection.mutate([
+          [
+            MUTATION_TYPE_INSERT_CHILD,
+            ROOT_ID,
+            serializeRemoteNode(target),
+            this.#observed.size - 1,
+          ],
         ]);
-      }
+      } else if (target.childNodes.length > 0) {
+        const records: RemoteMutationRecord[] = [];
+
+        for (let i = 0; i < target.childNodes.length; i++) {
+          const node = target.childNodes[i]!;
+          connectRemoteNode(node, this.connection);
+
+          records.push([
+            MUTATION_TYPE_INSERT_CHILD,
+            ROOT_ID,
+            serializeRemoteNode(node),
+            i,
+          ]);
+        }
 
-      this.connection.mutate(records);
+        this.connection.mutate(records);
+      }
     }
 
     super.observe(target, {
@@ -149,6 +180,30 @@ export class RemoteMutationObserver extends MutationObserver {
       ...options,
     });
   }
+
+  disconnect({empty = false}: {empty?: boolean} = {}) {
+    if (empty && this.#observed.size > 0) {
+      const records: RemoteMutationRecord[] = [];
+
+      for (const node of this.#observed) {
+        disconnectRemoteNode(node);
+        const id = remoteId(node);
+
+        if (id === ROOT_ID) {
+          for (let i = 0; i < node.childNodes.length; i++) {
+            records.push([MUTATION_TYPE_REMOVE_CHILD, id, 0]);
+          }
+        } else {
+          records.push([MUTATION_TYPE_REMOVE_CHILD, ROOT_ID, 0]);
+        }
+      }
+
+      this.connection.mutate(records);
+    }
+
+    this.#observed.clear();
+    super.disconnect();
+  }
 }
 
 function indexOf(node: Node, list: NodeList) {

packages/core/source/elements/RemoteRootElement.ts

@@ -2,12 +2,12 @@ import {ROOT_ID, MUTATION_TYPE_INSERT_CHILD} from '../constants.ts';
 import type {RemoteConnection, RemoteMutationRecord} from '../types.ts';
 
 import {
+  setRemoteId,
   remoteConnection,
   connectRemoteNode,
   serializeRemoteNode,
   updateRemoteElementProperty,
   callRemoteElementMethod,
-  REMOTE_IDS,
 } from './internals.ts';
 
 /**
@@ -35,7 +35,7 @@ import {
 export class RemoteRootElement extends HTMLElement {
   constructor() {
     super();
-    REMOTE_IDS.set(this, ROOT_ID);
+    setRemoteId(this, ROOT_ID);
   }
 
   connect(connection: RemoteConnection): void {

packages/core/source/elements/internals.ts

@@ -27,12 +27,16 @@ export function remoteId(node: Node) {
   let remoteID = REMOTE_IDS.get(node);
   if (remoteID == null) {
     remoteID = String(id++);
-    REMOTE_IDS.set(node, remoteID);
+    setRemoteId(node, remoteID);
   }
 
   return remoteID;
 }
 
+export function setRemoteId(node: Node, id: string) {
+  REMOTE_IDS.set(node, id);
+}
+
 export const REMOTE_PROPERTIES = new WeakMap<Node, Record<string, any>>();
 
 /**