Repository navigation
[lexical][lexical-extension][lexical-yjs][lexical-website] Feature: Add $deepCopy to the public API - #9936
[lexical][lexical-extension][lexical-yjs][lexical-website] Feature: Add $deepCopy to the public API#9936vishisht31 wants to merge 1 commit into
Conversation
…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
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
AI review status for this pull request.
|
lexical
@lexical/a11y
@lexical/clipboard
@lexical/code
@lexical/code-core
@lexical/code-prism
@lexical/code-shiki
@lexical/compiler
@lexical/devtools-core
@lexical/dragon
@lexical/eslint-plugin
@lexical/extension
@lexical/fast-check
@lexical/file
@lexical/hashtag
@lexical/headless
@lexical/history
@lexical/html
@lexical/internal
@lexical/link
@lexical/list
@lexical/mark
@lexical/markdown
@lexical/mdast
@lexical/offset
@lexical/overflow
@lexical/plain-text
@lexical/react
@lexical/rich-text
@lexical/selection
@lexical/table
@lexical/tailwind
@lexical/text
@lexical/utils
@lexical/y
@lexical/yjs
commit: |
There was a problem hiding this comment.
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.
- Excluded descendants inside a host that needs them (
packages/lexical/src/LexicalUtils.ts,$appendDeepCopyChildren). You asked for a view on theexcludeFromCopy('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:PageNodeandPageContentNodeboth returntruefromexcludeFromCopy(), so$deepCopy(page)returns aPageNodewhose children are the bare paragraphs, andgetContentNode()throws on the detached copy until thePagesExtensiontransform 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. - Test environment (
packages/lexical/src/__tests__/unit/LexicalDeepCopy.test.ts): AGENTS.md (Testing Strategy) asks for// @vitest-environment nodeafter the copyright header in unit tests that only exercise editor state, and this file never mounts a root element. - Shared walk (nit):
$serializeForDeepCopyis a third copy of the child-and-slot walk in$exportNodeToJSONand@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. - 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.
| target: SerializedLexicalNode[], | ||
| ): void { | ||
| for (const child of parent.getChildren()) { | ||
| if ($isElementNode(child) && child.excludeFromCopy('clone')) { |
There was a problem hiding this comment.
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. | ||
| * | ||
| */ |
There was a problem hiding this comment.
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.
Description
$copyNodeis 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$deepCopyhelpers already exist in the BlockId tests (BlockIdExtension.test.ts,BlockIdExtension.property.test.tsand the yjsblockIdPeers.ts).This PR adds
$deepCopy(node)tolexical. It returns a detached copy of the node and its whole subtree, named slots included, all with new keys. It serializes the subtree with$exportNodeJSONand parses it back with$parseSerializedNode, so the copy keeps everything a Lexical-JSON paste keeps, including NodeState.Behaviour worth reviewing:
$copyNode,resetOnCopyNodeFromis not called and NodeState declared withresetOnCopyNodekeeps its value. A copied list item stays checked and a copied block keeps its block id, the same as a paste.BlockIdExtensionalready repairs duplicate ids when the copy is inserted, and the existing BlockId tests that now use the public$deepCopystill pass.excludeFromCopy('clone'). I didn't find guidance on this in the issue, so this follows$appendNodesToJSONin@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.RootNode.importJSONreturns the existing root, so a copy would append the root's children into the live document.Other changes:
lexical, with a Flow declaration inLexical.js.flow.docs/concepts/node-cloning.mdgains a "Using$deepCopy" section, a note on choosing between$copyNodeand$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:Test plan
Before
$deepCopywas not exported fromlexical. Each BlockId test file defined its own copy, which didn't copy named slots or honourexcludeFromCopy.After
New
packages/lexical/src/__tests__/unit/LexicalDeepCopy.test.ts(14 tests):resetOnCopyNodestate, checked side by side with$copyNodeRun locally:
vitest --project unitforlexical,lexical-extension,lexical-yjsandlexical-clipboard: all pass exceptLexicalGeneratedJSON.test.ts, which fails the same way on a cleanmainon 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 becausepnpm run flowfails on Windows withspawn EINVAL; I'll open a separate issue about that.