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

.eslintrc.js

@@ -88,7 +88,10 @@ module.exports = {
         ],
         '@typescript-eslint/ban-ts-comment': OFF,
         '@typescript-eslint/no-this-alias': OFF,
-        '@typescript-eslint/no-unused-vars': [ERROR, {args: 'none'}],
+        '@typescript-eslint/no-unused-vars': [
+          ERROR,
+          {args: 'none', argsIgnorePattern: '^_', varsIgnorePattern: '^_'},
+        ],
         'header/header': [2, 'scripts/www/headerTemplate.js'],
       },
     },
@@ -226,8 +229,6 @@ module.exports = {
 
     'no-unused-expressions': ERROR,
 
-    'no-unused-vars': [ERROR, {args: 'none'}],
-
     'no-use-before-define': OFF,
 
     // Flow fails with with non-string literal keys

packages/lexical-table/src/__tests__/unit/LexicalTableSelection.test.tsx

@@ -134,6 +134,7 @@ describe('table selection', () => {
       __parent: null,
       __prev: null,
       __size: 1,
+      __state: {},
       __style: '',
       __textFormat: 0,
       __textStyle: '',
@@ -150,6 +151,7 @@ describe('table selection', () => {
       __parent: 'root',
       __prev: null,
       __size: 1,
+      __state: {},
       __style: '',
       __textFormat: 0,
       __textStyle: '',
@@ -163,6 +165,7 @@ describe('table selection', () => {
       __next: null,
       __parent: paragraphKey,
       __prev: null,
+      __state: {},
       __style: '',
       __text: 'Hello world',
       __type: 'text',

packages/lexical-website/docs/concepts/node-replacement.md

@@ -1,12 +1,49 @@
+# Node Customization
 
+Originally the only way to customize nodes was using the node replacement API. Recently we have introduced a second way with the `state` property which has some advantages described below.
+
+## State (New)
+
+The advantages of using state over the replacement API are:
+1. Easier (less boilerplate)
+2. Composable (multiple plugins extending the same node causes failures)
+3. Allows metadata: useful for adding things to the RootNode.
+
+All you need to do is define keys with `createStateKey`, and then use it with the `setState` and `getState` methods.
+
+```ts
+// IMPLEMENTATION
+const color = createStateKey('color', { parse: (value) => value as string });
+
+// USAGE
+const textNode = new TextNode();
+textNode.setState(color, "blue");
+const textColor = textNode.getState(color) // -> "blue"
+```
+
+Important: we recommend that you use prefixes with low collision probability when defining state keys. For example, if you are making a plugin called `awesome-lexical`, you could do:
+
+```ts
+const color = createStateKey('awesome-lexical-color', /** your parse fn */)
+const bgColor = createStateKey('awesome-lexical-bg-color', /** your parse fn */)
+
+// Or you can add all your state inside an object:
+type AwesomeLexical = {
+  color?: string;
+  bgColor?: string;
+  padding?: number
+}
+const awesomeLexical = createStateKey('awesome-lexical', /** your parse fn which returns AwesomeLexical type */)
+
+```
 
 # Node Overrides / Node Replacements
 
 Some of the most commonly used Lexical Nodes are owned and maintained by the core library. For example, ParagraphNode, HeadingNode, QuoteNode, List(Item)Node etc - these are all provided by Lexical packages, which provides an easier out-of-the-box experience for some editor features, but makes it difficult to override their behavior. For instance, if you wanted to change the behavior of ListNode, you would typically extend the class and override the methods. However, how would you tell Lexical to use *your* ListNode subclass in the ListPlugin instead of using the core ListNode? That's where Node Overrides can help.
 
 Node Overrides allow you to replace all instances of a given node in your editor with instances of a different node class. This can be done through the nodes array in the Editor config:
 
-```
+```ts
 const editorConfig = {
     ...
     nodes=[

packages/lexical/src/LexicalNode.ts

@@ -59,6 +59,7 @@ export type SerializedLexicalNode = {
   type: string;
   /** A numeric version for this schema, defaulting to 1, but not generally recommended for use */
   version: number;
+  state?: State;
 };
 
 /**
@@ -184,6 +185,39 @@ export type DOMExportOutput = {
 
 export type NodeKey = string;
 
+type DeepImmutable<T> = T extends Map<infer K, infer V>
+  ? ReadonlyMap<DeepImmutable<K>, DeepImmutable<V>>
+  : T extends Set<infer S>
+  ? ReadonlySet<DeepImmutable<S>>
+  : T extends object
+  ? {
+      readonly [K in keyof T]: DeepImmutable<T[K]>;
+    }
+  : T;
+type State = {[Key in string]?: string | number | boolean | State};
+type StateValue = string | number | boolean | State;
+interface StateKey<
+  K extends string = string,
+  V extends StateValue = StateValue,
+> {
+  key: K;
+  // Here we are storing a default for convenience
+  value: DeepImmutable<V>;
+  parse: (value: unknown) => V;
+}
+interface StateKeyConfig<V extends StateValue = StateValue> {
+  parse: (value: unknown) => V;
+}
+type StateKeyConfigValue<T extends StateKeyConfig> = ReturnType<T['parse']>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createStateKey<K extends string, T extends StateKeyConfig<any>>(
+  key: K,
+  config: T,
+): StateKey<K, StateKeyConfigValue<T>> {
+  return {key, parse: config.parse, value: config.parse(undefined)};
+}
+
 export class LexicalNode {
   // Allow us to look up the type including static props
   ['constructor']!: KlassConstructor<typeof LexicalNode>;
@@ -198,6 +232,19 @@ export class LexicalNode {
   __prev: null | NodeKey;
   /** @internal */
   __next: null | NodeKey;
+  /** @internal */
+  readonly __state: DeepImmutable<State> = {};
+
+  getState<T extends StateKey>(k: T): T['value'] | undefined {
+    const self = this.getLatest();
+    // If the state is not set, return the default value
+    return self.__state[k.key] ?? k.parse(undefined);
+  }
+
+  setState<T extends StateKey>(k: T, v: T['value']) {
+    const self = this.getWritable();
+    (self.__state as State)[k.key] = v;
+  }
 
   // Flow doesn't support abstract classes unfortunately, so we can't _force_
   // subclasses of Node to implement statics. All subclasses of Node should have
@@ -885,6 +932,7 @@ export class LexicalNode {
     return {
       type: this.__type,
       version: 1,
+      ...(objetcIsEmpty(this.__state) ? {} : {state: this.__state}),
     };
   }
 
@@ -934,6 +982,8 @@ export class LexicalNode {
   updateFromJSON(
     serializedNode: LexicalUpdateJSON<SerializedLexicalNode>,
   ): this {
+    // @ts-expect-error - only exception.
+    this.__state = serializedNode.state || {};
     return this;
   }
 
@@ -1289,3 +1339,14 @@ export function insertRangeAfter(
     currentNode = currentNode.insertAfter(nodeToInsert);
   }
 }
+
+/**
+ * The best way to check if an object is empty in O(1)
+ * @see https://stackoverflow.com/a/59787784/10476393
+ */
+function objetcIsEmpty(obj: object) {
+  for (const key in obj) {
+    return false;
+  }
+  return true;
+}

packages/lexical/src/__tests__/unit/LexicalEditor.test.tsx

@@ -1206,6 +1206,7 @@ describe('LexicalEditor tests', () => {
           __parent: null,
           __prev: null,
           __size: 1,
+          __state: {},
           __style: '',
           __textFormat: 0,
           __textStyle: '',
@@ -1222,6 +1223,7 @@ describe('LexicalEditor tests', () => {
           __parent: 'root',
           __prev: null,
           __size: 0,
+          __state: {},
           __style: '',
           __textFormat: 0,
           __textStyle: '',
@@ -1295,6 +1297,7 @@ describe('LexicalEditor tests', () => {
           __parent: null,
           __prev: null,
           __size: 1,
+          __state: {},
           __style: '',
           __textFormat: 0,
           __textStyle: '',
@@ -1311,6 +1314,7 @@ describe('LexicalEditor tests', () => {
           __parent: 'root',
           __prev: null,
           __size: 1,
+          __state: {},
           __style: '',
           __textFormat: 0,
           __textStyle: '',
@@ -1324,6 +1328,7 @@ describe('LexicalEditor tests', () => {
           __next: null,
           __parent: paragraphKey,
           __prev: null,
+          __state: {},
           __style: '',
           __text: 'Hello world',
           __type: 'text',
@@ -1379,6 +1384,7 @@ describe('LexicalEditor tests', () => {
           __parent: null,
           __prev: null,
           __size: 1,
+          __state: {},
           __style: '',
           __textFormat: 0,
           __textStyle: '',
@@ -1395,6 +1401,7 @@ describe('LexicalEditor tests', () => {
           __parent: 'root',
           __prev: null,
           __size: 1,
+          __state: {},
           __style: '',
           __textFormat: 0,
           __textStyle: '',
@@ -1408,6 +1415,7 @@ describe('LexicalEditor tests', () => {
           __next: null,
           __parent: paragraphKey,
           __prev: null,
+          __state: {},
           __style: '',
           __text: 'Hello world',
           __type: 'text',
@@ -2900,6 +2908,7 @@ describe('LexicalEditor tests', () => {
           __next: null,
           __parent: null,
           __prev: null,
+          __state: {},
           __style: '',
           __text: 'yolo',
           __type: 'text',

packages/lexical/src/__tests__/unit/LexicalEditorState.test.ts

@@ -62,6 +62,7 @@ describe('LexicalEditorState tests', () => {
         __parent: null,
         __prev: null,
         __size: 1,
+        __state: {},
         __style: '',
         __textFormat: 0,
         __textStyle: '',
@@ -78,6 +79,7 @@ describe('LexicalEditorState tests', () => {
         __parent: 'root',
         __prev: null,
         __size: 1,
+        __state: {},
         __style: '',
         __textFormat: 0,
         __textStyle: '',
@@ -91,6 +93,7 @@ describe('LexicalEditorState tests', () => {
         __next: null,
         __parent: '1',
         __prev: null,
+        __state: {},
         __style: '',
         __text: 'foo',
         __type: 'text',
@@ -150,6 +153,7 @@ describe('LexicalEditorState tests', () => {
               __parent: null,
               __prev: null,
               __size: 0,
+              __state: {},
               __style: '',
               __textFormat: 0,
               __textStyle: '',