[lexical] Feature: registerMutationListener should initialize its existing nodes

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

@@ -109,26 +109,28 @@ function CodeActionMenuContainer({
     };
   }, [shouldListenMouseMove, debouncedOnMouseMove]);
 
-  editor.registerMutationListener(CodeNode, (mutations) => {
-    editor.getEditorState().read(() => {
-      for (const [key, type] of mutations) {
-        switch (type) {
-          case 'created':
-            codeSetRef.current.add(key);
-            setShouldListenMouseMove(codeSetRef.current.size > 0);
-            break;
-
-          case 'destroyed':
-            codeSetRef.current.delete(key);
-            setShouldListenMouseMove(codeSetRef.current.size > 0);
-            break;
-
-          default:
-            break;
+  useEffect(() => {
+    return editor.registerMutationListener(CodeNode, (mutations) => {
+      editor.getEditorState().read(() => {
+        for (const [key, type] of mutations) {
+          switch (type) {
+            case 'created':
+              codeSetRef.current.add(key);
+              break;
+
+            case 'destroyed':
+              codeSetRef.current.delete(key);
+              break;
+
+            default:
+              break;
+          }
         }
-      }
+      });
+      setShouldListenMouseMove(codeSetRef.current.size > 0);
     });
-  });
+  }, [editor]);
+
   const normalizedLang = normalizeCodeLang(lang);
   const codeFriendlyName = getLanguageFriendlyName(lang);
 

packages/lexical-react/src/LexicalTableOfContentsPlugin.tsx

@@ -230,6 +230,8 @@ export function TableOfContentsPlugin({children}: Props): JSX.Element {
           setTableOfContents(currentTableOfContents);
         });
       },
+      // Initialization is handled separately
+      {skipInitialization: true},
     );
 
     // Listen to text node mutation updates
@@ -254,6 +256,8 @@ export function TableOfContentsPlugin({children}: Props): JSX.Element {
           }
         });
       },
+      // Initialization is handled separately
+      {skipInitialization: true},
     );
 
     return () => {

packages/lexical-react/src/LexicalTablePlugin.ts

@@ -38,7 +38,6 @@ import {
   $createParagraphNode,
   $getNodeByKey,
   $isTextNode,
-  $nodesOfType,
   COMMAND_PRIORITY_EDITOR,
 } from 'lexical';
 import {useEffect} from 'react';
@@ -129,17 +128,6 @@ export function TablePlugin({
       }
     };
 
-    // Plugins might be loaded _after_ initial content is set, hence existing table nodes
-    // won't be initialized from mutation[create] listener. Instead doing it here,
-    editor.getEditorState().read(() => {
-      const tableNodes = $nodesOfType(TableNode);
-      for (const tableNode of tableNodes) {
-        if ($isTableNode(tableNode)) {
-          initializeTableNode(tableNode);
-        }
-      }
-    });
-
     const unregisterMutationListener = editor.registerMutationListener(
       TableNode,
       (nodeMutations) => {

packages/lexical-website/docs/concepts/dom-events.md

@@ -30,20 +30,20 @@ This can be a simple, efficient way to handle some use cases, since it's not nec
 
 ## 2. Directly Attach Handlers
 
-In some cases, it may be better to attach an event handler directly to the underlying DOM node of each specific node. With this approach, you generally don't need to filter the event target in the handler, which can make it a bit simpler. It will also guarantee that you're handler isn't running for events that you don't care about. This approach is implemented via a [Mutation Listener](https://lexical.dev/docs/concepts/listeners).
+In some cases, it may be better to attach an event handler directly to the underlying DOM node of each specific node. With this approach, you generally don't need to filter the event target in the handler, which can make it a bit simpler. It will also guarantee that your handler isn't running for events that you don't care about. This approach is implemented via a [Mutation Listener](https://lexical.dev/docs/concepts/listeners).
 
 ```js
+const registeredElements: WeakSet<HTMLElement> = new WeakSet();
 const removeMutationListener = editor.registerMutationListener(nodeType, (mutations) => {
-    const registeredElements: WeakSet<HTMLElement> = new WeakSet();
     editor.getEditorState().read(() => {
         for (const [key, mutation] of mutations) {
             const element: null | HTMLElement = editor.getElementByKey(key);
             if (
-            // Updated might be a move, so that might mean a new DOM element
-            // is created. In this case, we need to add and event listener too.
-            (mutation === 'created' || mutation === 'updated') &&
-            element !== null &&
-            !registeredElements.has(element)
+                // Updated might be a move, so that might mean a new DOM element
+                // is created. In this case, we need to add and event listener too.
+                (mutation === 'created' || mutation === 'updated') &&
+                element !== null &&
+                !registeredElements.has(element)
             ) {
                 registeredElements.add(element);
                 element.addEventListener('click', (event: Event) => {

packages/lexical-website/docs/concepts/listeners.md

@@ -81,10 +81,14 @@ Get notified when a specific type of Lexical node has been mutated. There are th
 Mutation listeners are great for tracking the lifecycle of specific types of node. They can be used to
 handle external UI state and UI features relating to specific types of node.
 
+If any existing nodes are in the DOM, the listener will be called immediately with
+an updateTag of 'registerMutationListener' where all nodes have the 'created' NodeMutation.
+This behavior can be disabled with the skipInitialization option.
+
 ```js
 const removeMutationListener = editor.registerMutationListener(
   MyCustomNode,
-  (mutatedNodes) => {
+  (mutatedNodes, { updateTags, dirtyLeaves, prevEditorState }) => {
     // mutatedNodes is a Map where each key is the NodeKey, and the value is the state of mutation.
     for (let [nodeKey, mutation] of mutatedNodes) {
       console.log(nodeKey, mutation)

packages/lexical/flow/Lexical.js.flow

@@ -109,6 +109,9 @@ export type MutationListener = (
     prevEditorState: EditorState,
   },
 ) => void;
+export type MutationListenerOptions = {
+  skipInitialization?: boolean;
+};
 export type EditableListener = (editable: boolean) => void;
 type Listeners = {
   decorator: Set<DecoratorListener>,
@@ -178,6 +181,7 @@ declare export class LexicalEditor {
   registerMutationListener(
     klass: Class<LexicalNode>,
     listener: MutationListener,
+    options?: MutationListenerOptions,
   ): () => void;
   registerNodeTransform<T: LexicalNode>(
     klass: Class<T>,

packages/lexical/src/LexicalEditor.ts

@@ -211,6 +211,14 @@ export type MutatedNodes = Map<Klass<LexicalNode>, Map<NodeKey, NodeMutation>>;
 
 export type NodeMutation = 'created' | 'updated' | 'destroyed';
 
+export interface MutationListenerOptions {
+  /**
+   * Skip the initial call of the listener with pre-existing DOM nodes.
+   * Default is false.
+   */
+  skipInitialization?: boolean;
+}
+
 export type UpdateListener = (arg0: {
   dirtyElements: Map<NodeKey, IntentionallyMarkedAsDirtyElement>;
   dirtyLeaves: Set<NodeKey>;
@@ -825,13 +833,19 @@ export class LexicalEditor {
    * One common use case for this is to attach DOM event listeners to the underlying DOM nodes as Lexical nodes are created.
    * {@link LexicalEditor.getElementByKey} can be used for this.
    *
+   * If any existing nodes are in the DOM, the listener will be called immediately with
+   * an updateTag of 'registerMutationListener' where all nodes have the 'created' NodeMutation.
+   * This behavior can be disabled with the skipInitialization option.
+   *
    * @param klass - The class of the node that you want to listen to mutations on.
    * @param listener - The logic you want to run when the node is mutated.
+   * @param options - see {@link MutationListenerOptions}
    * @returns a teardown function that can be used to cleanup the listener.
    */
   registerMutationListener(
     klass: Klass<LexicalNode>,
     listener: MutationListener,
+    options?: MutationListenerOptions,
   ): () => void {
     let registeredNode = this._nodes.get(klass.getType());
 
@@ -862,12 +876,37 @@ export class LexicalEditor {
 
     const mutations = this._listeners.mutation;
     mutations.set(listener, klassToMutate);
+    if (!(options && options.skipInitialization)) {
+      this.initializeMutationListener(listener, klassToMutate);
+    }
 
     return () => {
       mutations.delete(listener);
     };
   }
 
+  /** @internal */
+  private initializeMutationListener(
+    listener: MutationListener,
+    klass: Klass<LexicalNode>,
+  ): void {
+    const prevEditorState = this._editorState;
+    const nodeMutationMap = new Map<string, NodeMutation>();
+    const klassType = klass.getType();
+    for (const [key, node] of prevEditorState._nodeMap) {
+      if (node.__type === klassType) {
+        nodeMutationMap.set(key, 'created');
+      }
+    }
+    if (nodeMutationMap.size > 0) {
+      listener(nodeMutationMap, {
+        dirtyLeaves: new Set(),
+        prevEditorState,
+        updateTags: new Set(['registerMutationListener']),
+      });
+    }
+  }
+
   /** @internal */
   private registerNodeTransformToKlass<T extends LexicalNode>(
     klass: Klass<T>,