Skip to content

[lexical][lexical-extension][lexical-yjs][lexical-website] Feature: Add $deepCopy to the public API - #9936

Open
vishisht31 wants to merge 1 commit into
meta:mainfrom
vishisht31:feature/public-deep-copy
Open

vishisht31 wants to merge 1 commit into
meta:mainfrom
vishisht31:feature/public-deep-copy

Conversation

@vishisht31

Copy link
Copy Markdown
Contributor

Description

$copyNode is shallow: the copy has no children. Lexical has no public way to copy a node together with its subtree, so a "Duplicate block" feature means writing a recursive copy by hand. Three identical private $deepCopy helpers already exist in the BlockId tests (BlockIdExtension.test.ts, BlockIdExtension.property.test.ts and the yjs blockIdPeers.ts).

This PR adds $deepCopy(node) to lexical. It returns a detached copy of the node and its whole subtree, named slots included, all with new keys. It serializes the subtree with $exportNodeJSON and parses it back with $parseSerializedNode, so the copy keeps everything a Lexical-JSON paste keeps, including NodeState.

Behaviour worth reviewing:

  • No reset. Unlike $copyNode, resetOnCopyNodeFrom is not called and NodeState declared with resetOnCopyNode keeps its value. A copied list item stays checked and a copied block keeps its block id, the same as a paste. BlockIdExtension already repairs duplicate ids when the copy is inserted, and the existing BlockId tests that now use the public $deepCopy still pass.
  • excludeFromCopy('clone'). I didn't find guidance on this in the issue, so this follows $appendNodesToJSON in @lexical/clipboard: an excluded descendant element is left out and its children take its place, without its own NodeState or slots. The node passed in, and each slot value, are always copied. I'm happy to change this if you'd prefer another rule.
  • Slots. These are copied recursively, which the old test helper didn't do. A slot name that resolves to no node throws, matching the clipboard export.
  • RootNode. This throws. RootNode.importJSON returns the existing root, so a copy would append the root's children into the live document.

Other changes:

  • Exported from lexical, with a Flow declaration in Lexical.js.flow.
  • The three private helpers are removed, and the BlockId extension and collab tests use the public export.
  • docs/concepts/node-cloning.md gains a "Using $deepCopy" section, a note on choosing between $copyNode and $deepCopy, and an example under "Copying Nodes".

This change is backwards compatible: it adds an export and changes no existing API.

Closes #9898

Changeset

.changeset/lexical-deep-copy.md:

---
'lexical': patch
---

[feature] Add `$deepCopy` to copy a node together with its children and slots

Test plan

Before

$deepCopy was not exported from lexical. Each BlockId test file defined its own copy, which didn't copy named slots or honour excludeFromCopy.

After

New packages/lexical/src/__tests__/unit/LexicalDeepCopy.test.ts (14 tests):

  • copies the node and all descendants with new keys, keeping text and format
  • returns a detached copy that doesn't alias the original
  • keeps NodeState on the node and its descendants
  • copies named slots, slots on a decorator host, and slots nested in slots and children
  • doesn't reset resetOnCopyNode state, checked side by side with $copyNode
  • leaves out descendants excluded from clones, keeps their children, and doesn't carry over their slots or state
  • always copies the node passed in, even if it is excluded from clones
  • copies a text node and an empty element
  • leaves the original untouched when the copy is never inserted
  • refuses the RootNode and leaves the document unchanged
  • throws in a read-only context

Run locally:

  • vitest --project unit for lexical, lexical-extension, lexical-yjs and lexical-clipboard: all pass except LexicalGeneratedJSON.test.ts, which fails the same way on a clean main on my Windows checkout. It looks like a CRLF line-ending issue and is unrelated to this change.
  • pnpm run tsc: no errors.
  • flow full-check: 0 errors. I ran it directly because pnpm run flow fails on Windows with spawn EINVAL; I'll open a separate issue about that.
  • ESLint and Prettier: clean on the changed files.

…dd $deepCopy to the public API

$copyNode copies only the node itself, so duplicating a block with its
content meant writing a recursive copy by hand. Three identical private
$deepCopy helpers already existed in the BlockId tests.

Add $deepCopy(node) to lexical. It returns a detached copy of the node and
its whole subtree, named slots included, all with new keys. The copy is
made by serializing the subtree and parsing it back, so it keeps
everything a Lexical-JSON paste keeps, including NodeState:

- resetOnCopyNodeFrom is not called and resetOnCopyNode state is kept,
  unlike $copyNode.
- A descendant element whose excludeFromCopy('clone') returns true is
  left out and its children take its place, as with the clipboard. The
  node passed in and each slot value are always copied.
- The RootNode cannot be copied: RootNode.importJSON returns the existing
  root, so parsing would append the copy to the live document.

The private helpers in the BlockIdExtension and BlockId collab tests are
replaced by the public export. The Node Cloning docs gain a $deepCopy
section and a note on choosing between it and $copyNode.

Closes meta#9898
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
lexical Ready Ready Preview Nov 17, 2026 6:02pm UTC
lexical-playground Ready Ready Preview Nov 17, 2026 6:02pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Nov 17, 2026
@rootnode-bot

rootnode-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 17, 2026, 6:15 PM UTC

@pkg-pr-new

pkg-pr-new Bot commented Nov 17, 2026

Copy link
Copy Markdown
lexical

npm i https://pkg.pr.new/lexical@9936

@lexical/a11y

npm i https://pkg.pr.new/@lexical/a11y@9936

@lexical/clipboard

npm i https://pkg.pr.new/@lexical/clipboard@9936

@lexical/code

npm i https://pkg.pr.new/@lexical/code@9936

@lexical/code-core

npm i https://pkg.pr.new/@lexical/code-core@9936

@lexical/code-prism

npm i https://pkg.pr.new/@lexical/code-prism@9936

@lexical/code-shiki

npm i https://pkg.pr.new/@lexical/code-shiki@9936

@lexical/compiler

npm i https://pkg.pr.new/@lexical/compiler@9936

@lexical/devtools-core

npm i https://pkg.pr.new/@lexical/devtools-core@9936

@lexical/dragon

npm i https://pkg.pr.new/@lexical/dragon@9936

@lexical/eslint-plugin

npm i https://pkg.pr.new/@lexical/eslint-plugin@9936

@lexical/extension

npm i https://pkg.pr.new/@lexical/extension@9936

@lexical/fast-check

npm i https://pkg.pr.new/@lexical/fast-check@9936

@lexical/file

npm i https://pkg.pr.new/@lexical/file@9936

@lexical/hashtag

npm i https://pkg.pr.new/@lexical/hashtag@9936

@lexical/headless

npm i https://pkg.pr.new/@lexical/headless@9936

@lexical/history

npm i https://pkg.pr.new/@lexical/history@9936

@lexical/html

npm i https://pkg.pr.new/@lexical/html@9936

@lexical/internal

npm i https://pkg.pr.new/@lexical/internal@9936

@lexical/link

npm i https://pkg.pr.new/@lexical/link@9936

@lexical/list

npm i https://pkg.pr.new/@lexical/list@9936

@lexical/mark

npm i https://pkg.pr.new/@lexical/mark@9936

@lexical/markdown

npm i https://pkg.pr.new/@lexical/markdown@9936

@lexical/mdast

npm i https://pkg.pr.new/@lexical/mdast@9936

@lexical/offset

npm i https://pkg.pr.new/@lexical/offset@9936

@lexical/overflow

npm i https://pkg.pr.new/@lexical/overflow@9936

@lexical/plain-text

npm i https://pkg.pr.new/@lexical/plain-text@9936

@lexical/react

npm i https://pkg.pr.new/@lexical/react@9936

@lexical/rich-text

npm i https://pkg.pr.new/@lexical/rich-text@9936

@lexical/selection

npm i https://pkg.pr.new/@lexical/selection@9936

@lexical/table

npm i https://pkg.pr.new/@lexical/table@9936

@lexical/tailwind

npm i https://pkg.pr.new/@lexical/tailwind@9936

@lexical/text

npm i https://pkg.pr.new/@lexical/text@9936

@lexical/utils

npm i https://pkg.pr.new/@lexical/utils@9936

@lexical/y

npm i https://pkg.pr.new/@lexical/y@9936

@lexical/yjs

npm i https://pkg.pr.new/@lexical/yjs@9936

commit: d145eca

@rootnode-bot rootnode-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, the change looks good. $deepCopy is a clean additive export: the TypeScript signature, the Flow declaration, the JSDoc, the new node-cloning.md section and the changeset all agree, and replacing the three private test helpers with the public export is a nice cleanup. Everything below is optional and non-blocking.

  1. Excluded descendants inside a host that needs them (packages/lexical/src/LexicalUtils.ts, $appendDeepCopyChildren). You asked for a view on the excludeFromCopy('clone') rule, so here is the case it handles worst. Because the node passed in is always kept while excluded descendants are spliced out, a host whose required child excludes itself comes back without that child. The playground has such a pair: PageNode and PageContentNode both return true from excludeFromCopy(), so $deepCopy(page) returns a PageNode whose children are the bare paragraphs, and getContentNode() throws on the detached copy until the PagesExtension transform re-wraps it after insertion. The clipboard never builds that shape for this pair, because the page is excluded too. Two ways forward: copy excluded descendants faithfully (a duplicate in the model is not a clipboard export), or keep the splice and say in the JSDoc and the docs page that such a host has to normalize its children. Either way, a test for that case would pin the chosen behaviour, since it becomes public API with this export.
  2. Test environment (packages/lexical/src/__tests__/unit/LexicalDeepCopy.test.ts): AGENTS.md (Testing Strategy) asks for // @vitest-environment node after the copyright header in unit tests that only exercise editor state, and this file never mounts a root element.
  3. Shared walk (nit): $serializeForDeepCopy is a third copy of the child-and-slot walk in $exportNodeToJSON and @lexical/clipboard's $appendNodesToJSON, and its comment asks future editors to keep the three in step. A shared walk that takes a child filter would remove that drift risk.
  4. Test plan: AGENTS.md (Commits and Pull Requests) asks for the command you ran and its real output pasted under Before and After, rather than a description of the result.

Automated review (maintainer link)

target: SerializedLexicalNode[],
): void {
for (const child of parent.getChildren()) {
if ($isElementNode(child) && child.excludeFromCopy('clone')) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional: since the node passed in is always kept but excluded descendants are spliced here, a host whose required child excludes itself comes back without it. The playground's PageNode/PageContentNode pair both return true from excludeFromCopy(), so $deepCopy(page) yields a PageNode with bare paragraphs as children and getContentNode() throws on the detached copy (the PagesExtension transform repairs it only after insertion). Consider copying excluded descendants faithfully, or documenting that such a host must normalize its children, and add a test for whichever rule you keep.

* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
*/

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: AGENTS.md (Testing Strategy) asks for // @vitest-environment node after the copyright header in unit tests that only exercise editor state; this file never mounts a root element.

This branch was successfully deployed

2 active deployments
Preview – lexical — d145eca6 Deployed Nov 17, 2026 by vercel[bot]
Preview – lexical-playground — d145eca6 Deployed Nov 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Add $deepCopy util function to public API

1 participant