[lexical] Feature: Add mutatedNodes to UpdateListener payload

packages/lexical/src/LexicalEditor.ts

@@ -231,14 +231,60 @@ export interface MutationListenerOptions {
 
 const DEFAULT_SKIP_INITIALIZATION = false;
 
-export type UpdateListener = (arg0: {
+/**
+ * The payload passed to an UpdateListener
+ */
+export interface UpdateListenerPayload {
+  /**
+   * A Map of NodeKeys of ElementNodes to a boolean that is true
+   * if the node was intentionally mutated ('unintentional' mutations
+   * are triggered when an indirect descendant is marked dirty)
+   */
   dirtyElements: Map<NodeKey, IntentionallyMarkedAsDirtyElement>;
+  /**
+   * A Set of NodeKeys of all nodes that were marked dirty that
+   * do not inherit from ElementNode.
+   */
   dirtyLeaves: Set<NodeKey>;
+  /**
+   * The new EditorState after all updates have been processed,
+   * equivalent to `editor.getEditorState()`
+   */
   editorState: EditorState;
+  /**
+   * The Map of LexicalNode constructors to a `Map<NodeKey, NodeMutation>`,
+   * this is useful when you have a mutation listener type use cases that
+   * should apply to all or most nodes. Will be null if no DOM was mutated,
+   * such as when only the selection changed.
+   *
+   * Added in v0.28.0
+   */
+  mutatedNodes: null | MutatedNodes;
+  /**
+   * For advanced use cases only.
+   *
+   * Tracks the keys of TextNode descendants that have been merged
+   * with their siblings by normalization. Note that these keys may
+   * not exist in either editorState or prevEditorState and generally
+   * this is only used for conflict resolution edge cases in collab.
+   */
   normalizedNodes: Set<NodeKey>;
+  /**
+   * The previous EditorState that is being discarded
+   */
   prevEditorState: EditorState;
+  /**
+   * The set of tags added with update options or {@link $addUpdateTag},
+   * node that this includes all tags that were processed in this
+   * reconciliation which may have been added by separate updates.
+   */
   tags: Set<string>;
-}) => void;
+}
+
+/**
+ * A listener that gets called after the editor is updated
+ */
+export type UpdateListener = (payload: UpdateListenerPayload) => void;
 
 export type DecoratorListener<T = never> = (
   decorator: Record<NodeKey, T>,
@@ -304,30 +350,27 @@ type Commands = Map<
   LexicalCommand<unknown>,
   Array<Set<CommandListener<unknown>>>
 >;
-type Listeners = {
-  decorator: Set<DecoratorListener>;
+
+export interface Listeners {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  decorator: Set<DecoratorListener<any>>;
   mutation: MutationListeners;
   editable: Set<EditableListener>;
   root: Set<RootListener>;
   textcontent: Set<TextContentListener>;
   update: Set<UpdateListener>;
-};
+}
 
-export type Listener =
-  | DecoratorListener
-  | EditableListener
-  | MutationListener
-  | RootListener
-  | TextContentListener
-  | UpdateListener;
-
-export type ListenerType =
-  | 'update'
-  | 'root'
-  | 'decorator'
-  | 'textcontent'
-  | 'mutation'
-  | 'editable';
+export type SetListeners = {
+  [K in keyof Listeners as Listeners[K] extends Set<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (...args: any[]) => void
+  >
+    ? K
+    : never]: Listeners[K] extends Set<(...args: infer Args) => void>
+    ? Args
+    : never;
+};
 
 export type TransformerType = 'text' | 'decorator' | 'element' | 'root';
 

packages/lexical/src/LexicalUpdates.ts

@@ -18,10 +18,10 @@ import {
   EditorUpdateOptions,
   LexicalCommand,
   LexicalEditor,
-  Listener,
   MutatedNodes,
   RegisteredNodes,
   resetEditor,
+  SetListeners,
   Transform,
 } from './LexicalEditor';
 import {
@@ -685,6 +685,7 @@ export function $commitPendingUpdates(
     dirtyElements,
     dirtyLeaves,
     editorState: pendingEditorState,
+    mutatedNodes,
     normalizedNodes,
     prevEditorState: recoveryEditorState || currentEditorState,
     tags,
@@ -729,19 +730,20 @@ function triggerMutationListeners(
   }
 }
 
-export function triggerListeners(
-  type: 'update' | 'root' | 'decorator' | 'textcontent' | 'editable',
+export function triggerListeners<T extends keyof SetListeners>(
+  type: T,
   editor: LexicalEditor,
   isCurrentlyEnqueuingUpdates: boolean,
-  ...payload: unknown[]
+  ...payload: SetListeners[T]
 ): void {
   const previouslyUpdating = editor._updating;
   editor._updating = isCurrentlyEnqueuingUpdates;
 
   try {
-    const listeners = Array.from<Listener>(editor._listeners[type]);
+    const listeners = Array.from(
+      editor._listeners[type] as Set<(...args: SetListeners[T]) => void>,
+    );
     for (let i = 0; i < listeners.length; i++) {
-      // @ts-ignore
       listeners[i].apply(null, payload);
     }
   } finally {

packages/lexical/src/__tests__/unit/LexicalEditor.test.tsx

@@ -26,10 +26,13 @@ import {
   $createParagraphNode,
   $createRangeSelection,
   $createTextNode,
+  $extendCaretToRange,
+  $getChildCaret,
   $getEditor,
   $getNearestNodeFromDOMNode,
   $getNodeByKey,
   $getRoot,
+  $isElementNode,
   $isParagraphNode,
   $isTextNode,
   $parseSerializedNode,
@@ -49,6 +52,7 @@ import {
   ParagraphNode,
   RootNode,
   TextNode,
+  UpdateListenerPayload,
 } from 'lexical';
 import * as React from 'react';
 import {
@@ -76,6 +80,78 @@ import {
   TestTextNode,
 } from '../utils';
 
+function $getAllNodes(): Set<LexicalNode> {
+  const root = $getRoot();
+  const set = new Set<LexicalNode>();
+  for (const {origin} of $extendCaretToRange($getChildCaret(root, 'next'))) {
+    set.add(origin);
+  }
+  set.add(root);
+  return set;
+}
+
+function computeUpdateListenerPayload(
+  editor: LexicalEditor,
+  prevEditorState: EditorState,
+  hasDOM: boolean,
+): UpdateListenerPayload {
+  return editor.read((): UpdateListenerPayload => {
+    const dirtyElements: UpdateListenerPayload['dirtyElements'] = new Map();
+    const dirtyLeaves: UpdateListenerPayload['dirtyLeaves'] = new Set();
+    const mutatedNodes: UpdateListenerPayload['mutatedNodes'] = new Map();
+    const tags: UpdateListenerPayload['tags'] = new Set();
+    const normalizedNodes: UpdateListenerPayload['normalizedNodes'] = new Set();
+    if (hasDOM) {
+      for (const node of prevEditorState.read($getAllNodes)) {
+        const key = node.getKey();
+        const klass = node.constructor;
+        const m = mutatedNodes.get(klass) || new Map();
+        m.set(key, 'destroyed');
+        mutatedNodes.set(klass, m);
+      }
+    }
+    for (const node of $getAllNodes()) {
+      const key = node.getKey();
+      if ($isElementNode(node)) {
+        dirtyElements.set(key, true);
+      } else {
+        dirtyLeaves.add(key);
+      }
+      if (hasDOM) {
+        const klass = node.constructor;
+        const m = mutatedNodes.get(klass) || new Map();
+        m.set(
+          key,
+          prevEditorState.read(() =>
+            $getNodeByKey(key) ? 'updated' : 'created',
+          ),
+        );
+        mutatedNodes.set(klass, m);
+      }
+    }
+    // This looks like a corner case in element tracking where
+    // dirtyElements has keys that were destroyed!
+    for (const [klass, m] of mutatedNodes) {
+      if ($isElementNode(klass.prototype)) {
+        for (const [nodeKey, value] of m) {
+          if (value === 'destroyed') {
+            dirtyElements.set(nodeKey, true);
+          }
+        }
+      }
+    }
+    return {
+      dirtyElements,
+      dirtyLeaves,
+      editorState: editor.getEditorState(),
+      mutatedNodes,
+      normalizedNodes,
+      prevEditorState,
+      tags,
+    };
+  });
+}
+
 describe('LexicalEditor tests', () => {
   let container: HTMLElement;
   let reactRoot: Root;
@@ -468,6 +544,7 @@ describe('LexicalEditor tests', () => {
     init();
     const onUpdate = jest.fn();
     editor.registerUpdateListener(onUpdate);
+    const prevEditorState = editor.getEditorState();
     editor.update(() => {
       $setSelection($createRangeSelection());
       editor.update(() => {
@@ -484,6 +561,10 @@ describe('LexicalEditor tests', () => {
       .read(() => $getRoot().getTextContent());
     expect(textContent).toBe('Sync update');
     expect(onUpdate).toHaveBeenCalledTimes(1);
+    // Calculate an expected update listener paylaod
+    expect(onUpdate.mock.calls).toEqual([
+      [computeUpdateListenerPayload(editor, prevEditorState, false)],
+    ]);
   });
 
   it('update does not call onUpdate callback when no dirty nodes', () => {
@@ -1773,6 +1854,8 @@ describe('LexicalEditor tests', () => {
 
     const paragraphNodeMutations = jest.fn();
     const textNodeMutations = jest.fn();
+    const onUpdate = jest.fn();
+    editor.registerUpdateListener(onUpdate);
     editor.registerMutationListener(ParagraphNode, paragraphNodeMutations, {
       skipInitialization: false,
     });
@@ -1781,6 +1864,7 @@ describe('LexicalEditor tests', () => {
     });
     const paragraphKeys: string[] = [];
     const textNodeKeys: string[] = [];
+    let prevEditorState = editor.getEditorState();
 
     // No await intentional (batch with next)
     editor.update(() => {
@@ -1803,10 +1887,25 @@ describe('LexicalEditor tests', () => {
       textNodeKeys.push(textNode3.getKey());
     });
 
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    // Calculate an expected update listener paylaod
+    expect(onUpdate.mock.lastCall).toEqual([
+      computeUpdateListenerPayload(editor, prevEditorState, true),
+    ]);
+
+    prevEditorState = editor.getEditorState();
     await editor.update(() => {
       $getRoot().clear();
     });
 
+    expect(onUpdate).toHaveBeenCalledTimes(2);
+    // Calculate an expected update listener payload after destroying
+    // everything
+    expect(onUpdate.mock.lastCall).toEqual([
+      computeUpdateListenerPayload(editor, prevEditorState, true),
+    ]);
+
+    prevEditorState = editor.getEditorState();
     await editor.update(() => {
       const root = $getRoot();
       const paragraph = $createParagraphNode();
@@ -1818,6 +1917,13 @@ describe('LexicalEditor tests', () => {
       root.append(paragraph);
     });
 
+    expect(onUpdate).toHaveBeenCalledTimes(3);
+    // Calculate an expected update listener payload after destroying
+    // everything
+    expect(onUpdate.mock.lastCall).toEqual([
+      computeUpdateListenerPayload(editor, prevEditorState, true),
+    ]);
+
     expect(paragraphNodeMutations.mock.calls.length).toBe(3);
     expect(textNodeMutations.mock.calls.length).toBe(2);
 
@@ -2444,6 +2550,7 @@ describe('LexicalEditor tests', () => {
     init();
     const onUpdate = jest.fn();
     editor.registerUpdateListener(onUpdate);
+    const prevEditorState = editor.getEditorState();
     editor.update(
       () => {
         $getRoot().append(
@@ -2460,6 +2567,10 @@ describe('LexicalEditor tests', () => {
       .read(() => $getRoot().getTextContent());
     expect(textContent).toBe('Sync update');
     expect(onUpdate).toHaveBeenCalledTimes(1);
+    // Calculate an expected update listener paylaod
+    expect(onUpdate.mock.calls).toEqual([
+      [computeUpdateListenerPayload(editor, prevEditorState, false)],
+    ]);
   });
 
   it('can use discrete after a non-discrete update to flush the entire queue', () => {

packages/lexical/src/index.ts

@@ -148,6 +148,7 @@ export type {
   Spread,
   Transform,
   UpdateListener,
+  UpdateListenerPayload,
 } from './LexicalEditor';
 export {
   COMMAND_PRIORITY_CRITICAL,