Add node replacement system to core

[trueadm]

This PR extends on the work from #2924.

Instead of defining a proxy that the user must remember to invoke, we can instead opt nodes into replacement in their factory function $createXNode using the new exported function $applyNodeReplacement. Then when defining the nodes array for editor config, we can supply an object in the form of:

{
  nodes: […SomeNodes, { replace: MyNode, with(node) { return $createMyNode() }]
}

This should address the issues on the above PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
lexical	✅ Ready (Inspect)	Visit Preview	Nov 17, 2022 at 4:15PM (UTC)
lexical-playground	✅ Ready (Inspect)	Visit Preview	Nov 17, 2022 at 4:15PM (UTC)

[fantactuka]

Should name be more generic to allow easier extension in future? Eg if we introduce something else than replace/with options $nodeFactory/$createNode/etc

[trueadm]

I'm not sure we'd ever want to introduce $nodeFactory/$createNode as it would be such a large breaking change that it would cause a ton of churn for no real gains.

[zurfyx]

Thank you @trueadm! Stamping to unblock but I share the same sentiment as @fantactuka. I feel like a more generic name (just the term) would give us space to expand this in the future with further validation or other stuff without a breaking changes. I am personally for $createNote

[zurfyx]

Suggested change

	node: LexicalNode,
	node: N,

This will guarantee that the return is the same or an extended node?

[trueadm]

They aren't the same though. The extended node is a subclass of N, not N.

[trueadm]

@zurfyx I don't understand how $createNote would work here, can you explain? Are you suggesting removing the new SomeNode pattern? If so, that's not going to scale or work with type systems.

[zurfyx]

@zurfyx I don't understand how $createNote would work here, can you explain? Are you suggesting removing the new SomeNode pattern? If so, that's not going to scale or work with type systems.

I was thinking that something like $createNode(() => new SomeNode) could maybe give us more flexibility later. But in any case, what you propose is still extensible later if we need to

[trueadm]

$createNode(() => new SomeNode) doesn't seem to do what it says, as in you can still create the node without using $createNode, which means the lines are blurred.

[acywatson]

This looks right. Nice work.

[acywatson]

Actually what happens if I override TextNode or something and then copy and paste into a Lexical editor that doesn't have that override? I guess we'll fallback to HTML. Maybe that's the best we can do here.

[nerdess]

@trueadm can you please post a concrete example on how to use this:

{
  nodes: […SomeNodes, { replace: MyNode, with(node) { return $createMyNode() }]
}

E.g. I want to replace the ParagraphNode with a custom version but I struggle how to inject my ParagraphNodeCustom into Lexical.

---

edit: actually, I just found this in the docs and the code in the sandbox is exactly what I was looking for: https://lexical.dev/docs/concepts/node-replacement