A DecoratorNode is the primary mechanism for plugging Svelte components into the Lexical editor. It allows Lexical to manage the node's lifecycle while delegating the actual UI rendering to Svelte via a decorator listener.
Execution Order
When a decorator node is created or modified, the following sequence occurs:
- Reconciler starts
DecoratorNode.createDOM: Called when a node is first created or re-created (e.g., during drag-and-drop). It creates the target DOM element where the Svelte component will live.DecoratorNode.decorate: Called whenever node properties change. It returns the component and its props (or a function to update props in Svelte 5 using $state runes).- Reconciler ends
- Mutation Listeners: Called to signal if a node was
created, updated, or destroyed. - Decorator Listener: Registered via
registerDecoratorListener. This is where the actual Svelte rendering takes place. Note that the listener receives the full list of decorator nodes in the document, not just the changed ones.
Key Constraints
- Ephemeral Objects: Decorator nodes (like
ImageNode) are frequently cloned and replaced to maintain the undo/redo stack. Do not hold direct references to a Decorator Node object. Instead, store the nodeKey and retrieve the node using editor.getElementByKey(nodeKey) when needed. - Data Storage: Nodes should only hold data within their own properties. Do not attempt to store external references inside the node instance.
/* Conceptual execution flow summary */
// 1. Reconciler starts
// 2. createDOM()
// 3. decorate()
// 4. Reconciler ends
// 5. Mutation Listeners (created, updated, destroyed)
// 6. Decorator Listener (renders via Svelte)
