feat(core): support node with changeable children

packages/lexical-playground/src/nodes/PlaygroundNodes.ts

@@ -34,6 +34,7 @@ import {LayoutItemNode} from './LayoutItemNode';
 import {MentionNode} from './MentionNode';
 import {PageBreakNode} from './PageBreakNode';
 import {PollNode} from './PollNode';
+import {ReactListNode} from './ReactListNode';
 import {StickyNode} from './StickyNode';
 import {TweetNode} from './TweetNode';
 import {YouTubeNode} from './YouTubeNode';
@@ -74,6 +75,7 @@ const PlaygroundNodes: Array<Klass<LexicalNode>> = [
   LayoutContainerNode,
   LayoutItemNode,
   CardNode,
+  ReactListNode,
 ];
 
 export default PlaygroundNodes;

packages/lexical-playground/src/nodes/ReactListNode.tsx

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $applyNodeReplacement,
+  $createNestedRootNode,
+  $createParagraphNode,
+  $createTextNode,
+  $getNodeByKey,
+  $isNestedRootNode,
+  EXPERIMENTAL_DecoratorElementNode,
+  LexicalNode,
+  NodeKey,
+} from 'lexical';
+import * as React from 'react';
+
+export class ReactListNode extends EXPERIMENTAL_DecoratorElementNode<JSX.Element> {
+  static getType(): string {
+    return 'reactlist';
+  }
+
+  static clone(node: ReactListNode): ReactListNode {
+    return new ReactListNode(node.__key);
+  }
+
+  constructor(key?: NodeKey) {
+    super(key);
+  }
+
+  createDOM(): HTMLElement {
+    return document.createElement('div');
+  }
+
+  updateDOM(): false {
+    return false;
+  }
+
+  decorate(): JSX.Element {
+    return <ReactListComponent nodeKey={this.__key} />;
+  }
+}
+
+export function $createReactListNode(): ReactListNode {
+  return $applyNodeReplacement(new ReactListNode());
+}
+
+export function $isReactListNode(
+  node: LexicalNode | null | undefined,
+): node is ReactListNode {
+  return node instanceof ReactListNode;
+}
+
+function ReactListComponent({nodeKey}: {nodeKey: NodeKey}) {
+  const [editor] = useLexicalComposerContext();
+  const addAtBeginning = React.useCallback(() => {
+    editor.update(() => {
+      const node = $getNodeByKey(nodeKey);
+      if ($isReactListNode(node)) {
+        const paragraph = $createParagraphNode();
+        paragraph.append($createTextNode('New text'));
+        const nestedRoot = $createNestedRootNode();
+        nestedRoot.append(paragraph);
+        node.splice(0, 0, [nestedRoot]);
+      }
+    });
+  }, [editor, nodeKey]);
+  const childKeys = editor.getEditorState().read(() => {
+    const node = $getNodeByKey(nodeKey);
+    return $isReactListNode(node) ? node.getChildrenKeys() : [];
+  });
+  return (
+    <div
+      style={{
+        borderColor: 'black',
+        borderStyle: 'solid',
+        borderWidth: 1,
+      }}>
+      <button onClick={addAtBeginning}>Add one item at beginning</button>
+      {childKeys.map((childKey, index) => (
+        <ReactListItem key={childKey} index={index} nodeKey={childKey} />
+      ))}
+    </div>
+  );
+}
+
+function ReactListItem({
+  index,
+  nodeKey,
+}: {
+  index: number;
+  nodeKey: NodeKey;
+}): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  const onRef = React.useCallback(
+    (element: HTMLElement | null) => {
+      editor.setNestedRootElement(nodeKey, element);
+    },
+    [editor, nodeKey],
+  );
+  const removeSelf = React.useCallback(() => {
+    editor.update(() => {
+      const node = $getNodeByKey(nodeKey);
+      if ($isNestedRootNode(node)) {
+        node.remove();
+      }
+    });
+  }, [editor, nodeKey]);
+  const addOneAfter = React.useCallback(() => {
+    editor.update(() => {
+      const node = $getNodeByKey(nodeKey);
+      if ($isNestedRootNode(node)) {
+        const paragraph = $createParagraphNode();
+        paragraph.append($createTextNode('New text'));
+        const nestedRoot = $createNestedRootNode();
+        nestedRoot.append(paragraph);
+        node.insertAfter(nestedRoot);
+      }
+    });
+  }, [editor, nodeKey]);
+  return (
+    <div>
+      Item No.{index} Key:{nodeKey}
+      <div
+        style={{
+          borderColor: 'red',
+          borderStyle: 'solid',
+          borderWidth: 1,
+          minHeight: 30,
+          minWidth: 100,
+        }}
+        ref={onRef}
+      />
+      <button onClick={removeSelf}>Remove</button>
+      <button onClick={addOneAfter}>Add one after</button>
+    </div>
+  );
+}

packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx

@@ -78,6 +78,7 @@ import {IS_APPLE} from 'shared/environment';
 import useModal from '../../hooks/useModal';
 import catTypingGif from '../../images/cat-typing.gif';
 import {$createCardNode} from '../../nodes/CardNode';
+import {$createReactListNode} from '../../nodes/ReactListNode';
 import {$createStickyNode} from '../../nodes/StickyNode';
 import DropDown, {DropDownItem} from '../../ui/DropDown';
 import DropdownColorPicker from '../../ui/DropdownColorPicker';
@@ -1040,6 +1041,16 @@ export default function ToolbarPlugin({
             buttonLabel="Insert"
             buttonAriaLabel="Insert specialized editor node"
             buttonIconClassName="icon plus">
+            <DropDownItem
+              onClick={() => {
+                activeEditor.update(() => {
+                  const reactListNode = $createReactListNode();
+                  $insertNodeToNearestRoot(reactListNode);
+                });
+              }}
+              className="item">
+              <span className="text">React List Node</span>
+            </DropDownItem>
             <DropDownItem
               onClick={() => {
                 activeEditor.update(() => {

packages/lexical/src/LexicalEditor.ts

@@ -1043,12 +1043,18 @@ export class LexicalEditor {
         style.whiteSpace = 'pre-wrap';
         style.wordBreak = 'break-word';
         this._keyToDOMMap.set(key, nextNestedRootElement);
+        this._pendingNestedRootNodeKeys.add(key);
       } else {
         this._keyToDOMMap.delete(key);
+        // There are two cases that nextNestedRootElement is null:
+        // 1. The nested root node is removed from Lexical
+        // 2. The nested root node remains unchanged, but the HTML Element no longer exists
+        // Only in the second case, we need to further process Lexical node children.
+        if (this._editorState._nodeMap.get(key)) {
+          this._pendingNestedRootNodeKeys.add(key);
+        }
       }
 
-      this._pendingNestedRootNodeKeys.add(key);
-
       // Defer to next microtask, so multiple simultaneous root element update
       // can trigger only one reconciliation.
       queueMicrotask(() => {