[lexical] Feature: add a generic state property to all nodes

[GermanJablo]

This PR enables adding arbitrary state to nodes with automatic JSON serialization.

Motivation:

1. Easier node customization

The following compares adding a 'color' property to a text node using the current node replacement API versus the state API in this PR.

With node replacement API

// IMPLEMENTATION
export type SerializedColoredTextNode = Spread<
{
  color: string;
  type: 'colored';
  version: 1;
},
SerializedTextNode
>;

export class ColoredNode extends TextNode {
__color: string;

constructor(text: string, color?: string, key?: NodeKey): void {
  super(text, key);
  this.__color = color || "defaultColor";
}

static getType(): string {
  return 'colored';
}

setColor(color: string) {
  const self = this.getWritable();
  self.__color = color;
}

getColor(): string {
  const self = this.getLatest();
  return self.__color;
}

static clone(node: ColoredNode): ColoredNode {
  return new ColoredNode(node.__text, node.__color, node.__key);
}

createDOM(config: EditorConfig): HTMLElement {
  const element = super.createDOM(config);
  element.style.color = this.__color || "defaultColor";
  return element;
}

updateDOM(prevNode: ColoredNode, dom: HTMLElement, config: EditorConfig): boolean {
  const isUpdated = super.updateDOM(prevNode, dom, config);
  if (prevNode.__color !== this.__color) {
    dom.style.color = this.__color;
  }
  return isUpdated;
}

static importJSON(serializedNode: SerializedMentionNode): MentionNode {
  const node = new ColoredNode(serializedNode.text, node.serializedNode.color);
  node.setFormat(serializedNode.format);
  node.setDetail(serializedNode.detail);
  node.setMode(serializedNode.mode);
  node.setStyle(serializedNode.style);
  return node;
}

exportJSON(): SerializedHeadingNode {
  return {
    ...super.exportJSON(),
    color: this.getColor()
    tag: this.getTag(),
    type: 'colored',
    version: 1,
  };
}
}

export const nodes = [
  ColoredNode,
  {
    replace: TextNode,
    with: (node: TextNode) => new ColoredNode(node.__text),
    withKlass: ColoredNode,
  },
  // ...
]

// USAGE
const textNode = $createTextNode();
textNode.setColor("blue");
const textColor = textNode.getColor() // "blue"

With state API

// IMPLEMENTATION
const color = createStateKey('color', {
  parse: (value: unknown) => (typeof value === 'string' ? value : undefined),
});

// USAGE
const textNode = new TextNode();
textNode.setState(color, "blue");
const textColor = textNode.getState(color) // "blue"

2. Composability

If two users replace the same node with the node replacement API, the system fails.
This is particularly relevant when you do not fully control the codebase. For example, when installing a Lexical plugin that requires a custom node.

3. Document metadata

Sometimes it can be useful to store some metadata about the document, such as its ID or creation date.
It can also sometimes be useful to store maps for faster lookups. For example, the comments plugin could have a map of comment IDs to node keys.
This API allows storing that information in RootNode.

---

Notes:

• This PR is a new iteration of [lexical][@lexical/selection] Feature: add a generic classes property to all nodes for easier customization #6929 but less opinionated and with a more limited scope.
• This API does not come with opinions on how to render the state or serialize it to HTML. Therefore, the example comparison with node replacement API from section 1 is not entirely fair right now since it does not include create/updateDOM. However, the plan is to soon provide a plugin to handle this.
• The API design is the brainchild of @etrepum. Credit to him for also guiding the development.

[vercel]

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

Name	Status	Preview	Comments	Updated (UTC)
lexical	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 10, 2025 9:26pm
lexical-playground	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 10, 2025 9:26pm

[github-actions]

size-limit report 📦

Path	Size
lexical - cjs	29.26 KB (+0.66% 🔺)
lexical - esm	29.06 KB (+0.68% 🔺)
@lexical/rich-text - cjs	38.22 KB (+0.28% 🔺)
@lexical/rich-text - esm	31.13 KB (+0.68% 🔺)
@lexical/plain-text - cjs	36.84 KB (+0.73% 🔺)
@lexical/plain-text - esm	28.37 KB (+0.54% 🔺)
@lexical/react - cjs	40.06 KB (+0.39% 🔺)
@lexical/react - esm	32.58 KB (+0.93% 🔺)

[GermanJablo]

Something I thought about but haven't tested yet is whether it would work to use a private javascript property instead.

[GermanJablo]

The reason I suggest using bracket-notation here is to give these properties more privacy in a safer way than the __ prefix.
In LexicalNode, I've defined __state because it's a pattern that's already all over the codebase and because the property is not enumerable.

see microsoft/TypeScript#19335 (comment)