[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,55 @@
+# 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: unknown) => (typeof value === 'string' ? value : undefined),
+});
+
+// USAGE
+const textNode = $createTextNode();
+textNode.setState(color, "blue");
+const textColor = textNode.getState(color) // -> "blue"
+```
+
+Inside state, you can put any serializable json value except null. Our recommendation is to always use TypeScript in strict mode, so you don't have to worry about these things!
+
+### 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,47 @@ 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 | null | boolean | State};
+type StateValue = string | number | boolean | null | undefined | State;
+interface StateKey<
+  K extends string = string,
+  V extends StateValue = StateValue,
+> {
+  readonly key: K;
+  // Here we are storing a default for convenience
+  readonly value: DeepImmutable<V>;
+  readonly parse: (value: unknown) => V;
+}
+interface StateKeyConfig<V extends StateValue = StateValue> {
+  readonly parse: (value: unknown) => V;
+}
+type StateKeyConfigValue<T extends StateKeyConfig> = ReturnType<T['parse']>;
+
+const stateStore = new Map<string, StateKeyConfig>();
+
+// 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>> {
+  if (stateStore.has(key)) {
+    throw new Error(
+      `There has been an attempt to register a state with the key "${key}", but it is already registered.`,
+    );
+  }
+  stateStore.set(key, config);
+  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 +240,20 @@ export class LexicalNode {
   __prev: null | NodeKey;
   /** @internal */
   __next: null | NodeKey;
+  /** @internal */
+  __state: DeepImmutable<State> = {};
+
+  getState<T extends StateKey>(k: T): T['value'] {
+    const self = this.getLatest();
+    // If the state is not set, return the default value
+    return k.parse(self.__state[k.key]);
+  }
+
+  setState<T extends StateKey>(k: T, v: T['value']): this {
+    const self = this.getWritable();
+    self.__state = {...self.__state, [k.key]: v};
+    return self;
+  }
 
   // Flow doesn't support abstract classes unfortunately, so we can't _force_
   // subclasses of Node to implement statics. All subclasses of Node should have
@@ -286,6 +342,7 @@ export class LexicalNode {
     this.__parent = prevNode.__parent;
     this.__next = prevNode.__next;
     this.__prev = prevNode.__prev;
+    this.__state = prevNode.__state || {};
   }
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -882,9 +939,23 @@ export class LexicalNode {
    *
    * */
   exportJSON(): SerializedLexicalNode {
+    const state: State = {};
+    Object.entries(this.__state).forEach(([key, value]) => {
+      const config = stateStore.get(key);
+      if (!config) {
+        throw new Error(
+          `There has been an attempt to export a state with the key "${key}", but it is not registered.`,
+        );
+      }
+      // We don't export state if it's the default value
+      if (value !== config.parse(undefined)) {
+        state[key] = value;
+      }
+    });
     return {
       type: this.__type,
       version: 1,
+      ...(objectIsEmpty(state) ? {} : {state}),
     };
   }
 
@@ -934,6 +1005,7 @@ export class LexicalNode {
   updateFromJSON(
     serializedNode: LexicalUpdateJSON<SerializedLexicalNode>,
   ): this {
+    this.__state = serializedNode.state || {};
     return this;
   }
 
@@ -1289,3 +1361,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 objectIsEmpty(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: '',