[lexical][lexical-list][lexical-markdown] Feature: resetOnCopyNode configuration to NodeState and LexicalNode.resetOnCopyNodeFrom hook (facebook#8221)

Author: etrepum

packages/lexical-list/src/LexicalListItemNode.ts

@@ -29,6 +29,7 @@ import {
 } from '@lexical/utils';
 import {
   $applyNodeReplacement,
+  $copyNode,
   $createParagraphNode,
   $isElementNode,
   $isParagraphNode,
@@ -300,13 +301,18 @@ export class ListItemNode extends ElementNode {
     }
   }
 
+  resetOnCopyNodeFrom(original: this): void {
+    super.resetOnCopyNodeFrom(original);
+    if (original.getChecked()) {
+      this.setChecked(false);
+    }
+  }
+
   insertNewAfter(
     _: RangeSelection,
     restoreSelection = true,
   ): ListItemNode | ParagraphNode {
-    const newElement = $createListItemNode()
-      .updateFromJSON(this.exportJSON())
-      .setChecked(this.getChecked() ? false : undefined);
+    const newElement = $copyNode(this);
 
     this.insertAfter(newElement, restoreSelection);
 

packages/lexical-markdown/src/MarkdownTransformers.ts

@@ -222,15 +222,17 @@ const ENDS_WITH = (regex: RegExp) =>
 
 export const listMarkerState = createState('mdListMarker', {
   parse: (v) => (typeof v === 'string' && /^[-*+]$/.test(v) ? v : '-'),
+  resetOnCopyNode: true,
 });
 
-export const codeFenceState = createState<string, string>('mdCodeFence', {
+export const codeFenceState = createState('mdCodeFence', {
   parse: (val) => {
     if (typeof val === 'string' && /^`{3,}$/.test(val)) {
       return val;
     }
     return '```';
   },
+  resetOnCopyNode: true,
 });
 
 const createBlockNode = (

packages/lexical-website/docs/concepts/node-cloning.md

@@ -60,6 +60,9 @@ function $duplicateNode(node: MyCustomNode) {
 ### What is `$copyNode`?
 
 `$copyNode` is the public API for creating a copy of a node with a new key. Use this when you need to create a duplicate node.
+By default, all properties and `NodeState` will be copied to the new node, and then `resetOnCopyNodeFrom` will be called to
+allow the node to optionally reset certain properties (and NodeState configured with `resetOnCopyNode: true`) to defaults
+(such as the checked state of a `ListItemNode`).
 
 ```typescript
 // ✅ Correct: Using $copyNode

packages/lexical/flow/Lexical.js.flow

@@ -457,6 +457,8 @@ declare export class LexicalNode {
   selectNext(anchorOffset?: number, focusOffset?: number): RangeSelection;
   markDirty(): void;
   reconcileObservedMutation(dom: HTMLElement, editor: LexicalEditor): void;
+  afterCloneFrom(prevNode: this): void;
+  resetOnCopyNodeFrom(original: this): void;
 }
 export type NodeMap = Map<NodeKey, LexicalNode>;
 
@@ -941,10 +943,7 @@ declare export function $hasAncestor(
   targetNode: LexicalNode,
 ): boolean;
 declare export function $cloneWithProperties<T: LexicalNode>(node: T): T;
-declare export function $copyNode(
-  node: ElementNode,
-  offset: number,
-): [ElementNode, ElementNode];
+declare export function $copyNode<T: LexicalNode>(node: T, skipReset?: boolean): T;
 declare export function $getEditor(): LexicalEditor;
 
 /**
@@ -1340,13 +1339,15 @@ declare export class StateConfig<K: string, V> {
   +unparse: (value: V) => mixed;
   +isEqual: (a: V, b: V) => boolean;
   +defaultValue: V;
+  +resetOnCopyNode: boolean;
   constructor(key: K, stateValueConfig: StateValueConfig<V>): this;
 }
 
 export type StateValueConfig<V> = {
   parse: (jsonValue: mixed) => V;
   unparse?: (parsed: V) => mixed;
   isEqual?: (a: V, b: V) => boolean;
+  resetOnCopyNode?: boolean;
 }
 
 export type UnionToIntersection<T> = (

packages/lexical/src/LexicalNode.ts

@@ -552,6 +552,17 @@ export class LexicalNode {
     }
   }
 
+  /**
+   * Reset state in this copy of originalNode, if necessary
+   *
+   * @param originalNode
+   */
+  resetOnCopyNodeFrom(originalNode: this): void {
+    if (this.__state) {
+      this.__state = this.__state.getWritable(this).resetOnCopyNode();
+    }
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   static importDOM?: () => DOMConversionMap<any> | null;
 

packages/lexical/src/LexicalNodeState.ts

@@ -223,6 +223,11 @@ export interface StateValueConfig<V> {
    * more appropriate for your use case.
    */
   isEqual?: (a: V, b: V) => boolean;
+  /**
+   * When a node is copied with {@link $copyNode} (not cloned), reset this
+   * value to the default.
+   */
+  resetOnCopyNode?: boolean;
 }
 
 /**
@@ -251,6 +256,7 @@ export class StateConfig<K extends string, V> {
    * the `defaultValue`, it will not be serialized to JSON.
    */
   readonly defaultValue: V;
+  readonly resetOnCopyNode: boolean;
   constructor(key: K, stateValueConfig: StateValueConfig<V>) {
     this.key = key;
     this.parse = stateValueConfig.parse.bind(stateValueConfig);
@@ -261,6 +267,7 @@ export class StateConfig<K extends string, V> {
       stateValueConfig,
     );
     this.defaultValue = this.parse(undefined);
+    this.resetOnCopyNode = stateValueConfig.resetOnCopyNode || false;
   }
 }
 
@@ -692,6 +699,16 @@ export class NodeState<T extends LexicalNode> {
     );
   }
 
+  /** @internal */
+  resetOnCopyNode(): this {
+    for (const stateConfig of this.knownState.keys()) {
+      if (stateConfig.resetOnCopyNode) {
+        this.knownState.set(stateConfig, stateConfig.defaultValue);
+      }
+    }
+    return this;
+  }
+
   /** @internal */
   updateFromKnown<K extends string, V>(
     stateConfig: StateConfig<K, V>,

packages/lexical/src/LexicalUtils.ts

@@ -1565,12 +1565,19 @@ export function $isRootOrShadowRoot(
  * separately added to the document, and it will not have any children.
  *
  * @param node - The node to be copied.
+ * @param skipReset - If true (default false) skip the call to resetOnCopyNodeFrom
  * @returns The copy of the node.
  */
-export function $copyNode<T extends LexicalNode>(node: T): T {
+export function $copyNode<T extends LexicalNode>(
+  node: T,
+  skipReset = false,
+): T {
   const copy = node.constructor.clone(node) as T;
   $setNodeKey(copy, null);
   copy.afterCloneFrom(node);
+  if (!skipReset) {
+    copy.resetOnCopyNodeFrom(node);
+  }
   return copy;
 }
 

packages/lexical/src/__tests__/unit/LexicalNodeState.test.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  $copyNode,
   $createParagraphNode,
   $createTextNode,
   $getRoot,
@@ -544,6 +545,116 @@ describe('LexicalNode state', () => {
           }
         });
       });
+
+      describe('resetOnCopyNode', () => {
+        test('state with resetOnCopyNode: true is reset when using $copyNode', () => {
+          const {editor} = testEnv;
+          const resetState = createState('resetState', {
+            parse: (v) => (typeof v === 'number' ? v : 0),
+            resetOnCopyNode: true,
+          });
+          editor.update(
+            () => {
+              const node = $createStateNode();
+              $setState(node, resetState, 42);
+              expect($getState(node, resetState)).toBe(42);
+
+              const copy = $copyNode(node);
+              expect($getState(copy, resetState)).toBe(0);
+              expect($getState(node, resetState)).toBe(42);
+            },
+            {discrete: true},
+          );
+        });
+
+        test('state with resetOnCopyNode: false is preserved when using $copyNode', () => {
+          const {editor} = testEnv;
+          const persistState = createState('persistState', {
+            parse: (v) => (typeof v === 'number' ? v : 0),
+            resetOnCopyNode: false,
+          });
+          editor.update(
+            () => {
+              const node = $createStateNode();
+              $setState(node, persistState, 42);
+              expect($getState(node, persistState)).toBe(42);
+
+              const copy = $copyNode(node);
+              expect($getState(copy, persistState)).toBe(42);
+              expect($getState(node, persistState)).toBe(42);
+            },
+            {discrete: true},
+          );
+        });
+
+        test('state without resetOnCopyNode option is preserved when using $copyNode', () => {
+          const {editor} = testEnv;
+          const defaultState = createState('defaultState', {
+            parse: (v) => (typeof v === 'number' ? v : 0),
+          });
+          editor.update(
+            () => {
+              const node = $createStateNode();
+              $setState(node, defaultState, 42);
+              expect($getState(node, defaultState)).toBe(42);
+
+              const copy = $copyNode(node);
+              expect($getState(copy, defaultState)).toBe(42);
+              expect($getState(node, defaultState)).toBe(42);
+            },
+            {discrete: true},
+          );
+        });
+
+        test('multiple states with different resetOnCopyNode configurations', () => {
+          const {editor} = testEnv;
+          const resetState = createState('resetState', {
+            parse: (v) => (typeof v === 'number' ? v : 0),
+            resetOnCopyNode: true,
+          });
+          const persistState = createState('persistState', {
+            parse: (v) => (typeof v === 'string' ? v : ''),
+            resetOnCopyNode: false,
+          });
+          const defaultState = createState('defaultState', {
+            parse: (v) => (typeof v === 'boolean' ? v : false),
+          });
+
+          editor.update(
+            () => {
+              const node = $createStateNode();
+              $setState(node, resetState, 100);
+              $setState(node, persistState, 'hello');
+              $setState(node, defaultState, true);
+
+              expect($getState(node, resetState)).toBe(100);
+              expect($getState(node, persistState)).toBe('hello');
+              expect($getState(node, defaultState)).toBe(true);
+
+              const copy = $copyNode(node);
+              expect($getState(copy, resetState)).toBe(0);
+              expect($getState(copy, persistState)).toBe('hello');
+              expect($getState(copy, defaultState)).toBe(true);
+
+              // Original node should be unchanged
+              expect($getState(node, resetState)).toBe(100);
+              expect($getState(node, persistState)).toBe('hello');
+              expect($getState(node, defaultState)).toBe(true);
+
+              const fullCopy = $copyNode(node, true);
+              // Original node should be unchanged
+              expect($getState(node, resetState)).toBe(100);
+              expect($getState(node, persistState)).toBe('hello');
+              expect($getState(node, defaultState)).toBe(true);
+              // Full copy should match all properties
+              expect($getState(fullCopy, resetState)).toBe(100);
+              expect($getState(fullCopy, persistState)).toBe('hello');
+              expect($getState(fullCopy, defaultState)).toBe(true);
+            },
+            {discrete: true},
+          );
+        });
+      });
     },
     {
       namespace: '',