[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-website/docs/concepts/node-replacement.md

@@ -1,12 +1,53 @@
+# 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 (Experimental)
+
+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.
+
+```ts
+// IMPLEMENTATION
+const colorState = createState('color', {
+  parse: (value: unknown) => (typeof value === 'string' ? value : undefined),
+});
+
+// USAGE
+const textNode = $createTextNode();
+colorState.$set(textNode, "blue");
+const textColor = colorState.$get(textNode) // -> "blue"
+```
+
+Inside state, you can put any serializable json value. 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. For example, if you are making a plugin called `awesome-lexical`, you could do:
+
+```ts
+const color = createState('awesome-lexical-color', /** your parse fn */)
+const bgColor = createState('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 = createState('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

@@ -22,6 +22,7 @@ import {
   type DecoratorNode,
   ElementNode,
 } from '.';
+import {NodeState, State} from './LexicalNodeState';
 import {
   $getSelection,
   $isNodeSelection,
@@ -59,6 +60,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;
 };
 
 /**
@@ -199,6 +201,18 @@ export class LexicalNode {
   /** @internal */
   __next: null | NodeKey;
 
+  /** @internal */
+  get __state() {
+    // @ts-expect-error
+    return this._state;
+  }
+
+  /** @internal */
+  set __state(value: NodeState) {
+    // @ts-expect-error
+    this._state = value;
+  }
+
   // Flow doesn't support abstract classes unfortunately, so we can't _force_
   // subclasses of Node to implement statics. All subclasses of Node should have
   // a static getType and clone method though. We define getType and clone here so we can call it
@@ -286,6 +300,7 @@ export class LexicalNode {
     this.__parent = prevNode.__parent;
     this.__next = prevNode.__next;
     this.__prev = prevNode.__prev;
+    this.__state = prevNode.__state || new NodeState();
   }
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -297,6 +312,12 @@ export class LexicalNode {
     this.__prev = null;
     this.__next = null;
     $setNodeKey(this, key);
+    Object.defineProperty(this, '_state', {
+      configurable: true,
+      enumerable: false,
+      value: new NodeState(),
+      writable: true,
+    });
 
     if (__DEV__) {
       if (this.__type !== 'root') {
@@ -882,9 +903,12 @@ export class LexicalNode {
    *
    * */
   exportJSON(): SerializedLexicalNode {
+    // eslint-disable-next-line dot-notation
+    const state = this.__state['toJSON']();
     return {
       type: this.__type,
       version: 1,
+      ...(objectIsEmpty(state) ? {} : {state}),
     };
   }
 
@@ -934,6 +958,8 @@ export class LexicalNode {
   updateFromJSON(
     serializedNode: LexicalUpdateJSON<SerializedLexicalNode>,
   ): this {
+    // eslint-disable-next-line dot-notation
+    this.__state['unknownState'] = serializedNode.state || {};
     return this;
   }
 
@@ -1289,3 +1315,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/LexicalNodeState.ts

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/* eslint-disable dot-notation */
+
+import {LexicalNode} from './LexicalNode';
+
+/**
+ * NOTE: we parse in getState and setState, but not in importJSON or exportJSON. Ideally,
+ * the normal thing would be the other way around. The reason we do it this way is because
+ * we don't have a composable way to declare states (or plugins), prior to creating the
+ * editor. Maybe later with something like https://lexical-builder.pages.dev/.
+ */
+
+export 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;
+
+export type State = {
+  [Key in string]?: string | number | boolean | null | undefined | State;
+};
+
+type StateValue = State[keyof State];
+
+export function createState<K extends string, T extends StateValue>(
+  key: K,
+  config: {parse: (value: unknown) => T},
+) {
+  // We create a stateConfig with a default value to save some work later
+  const stateConfig = {
+    defaultValue: config.parse(undefined),
+    key,
+    parse: config.parse,
+  };
+
+  const $get = (node: LexicalNode): DeepImmutable<T> => {
+    // 1. We first try to get the value from the knownState
+    const state = node.getLatest().__state;
+    const value = state['knownState'].get(stateConfig) as DeepImmutable<T>;
+    if (value !== undefined) {
+      return value;
+    }
+
+    // 2. If the value is not in the knownState, we try to get it from the unknownState
+    // and set it in the knownState Map (even if it's a default, so we don't parse again).
+    const unknownValue = state['unknownState'][key];
+    delete state['unknownState'][key];
+    const parsedValue = config.parse(unknownValue) as DeepImmutable<T>;
+    state['knownState'].set(stateConfig, parsedValue);
+
+    // We check collisions (the same string key used on the same node instance in 2 different `createState`)
+    // We could use a reverse map to avoid a lookup (Map<StateConfig, StateValue>), but it seems overkill.
+    state['knownState'].forEach((_, currentStateConfig) => {
+      if (
+        currentStateConfig.key === key &&
+        currentStateConfig !== stateConfig
+      ) {
+        throw new Error(`State key collision detected: ${key}`);
+      }
+    });
+
+    return parsedValue;
+  };
+
+  const $set = (node: LexicalNode, value: T) => {
+    const self = node.getWritable();
+    self.__state = self.__state['clone']();
+    const parsedValue = config.parse(value);
+    delete self.__state['unknownState'][key];
+    self.__state['knownState'].set(stateConfig, parsedValue);
+  };
+
+  return {$get, $set};
+}
+
+interface StateConfig<
+  K extends string = string,
+  V extends StateValue = StateValue,
+> {
+  readonly key: K;
+  readonly defaultValue: DeepImmutable<V>;
+  readonly parse: (value: unknown) => V;
+}
+
+export class NodeState {
+  /**
+   * State that has already been parsed in a get state, so it is safe. (can be returned with
+   * just a cast since the proof was given before).
+   *
+   * Note that it uses StateConfig, so in addition to (1) the CURRENT VALUE, it has access to
+   * (2) the State key (3) the DEFAULT VALUE and (4) the PARSE FUNCTION
+   */
+  private knownState: Map<StateConfig, StateValue> = new Map();
+
+  /**
+   * It is a copy of serializedNode.state that is made when JSON is imported but has not been parsed yet.
+   * It stays here until a get state requires us to parse it, and since we then know the value is safe we move it to knownState
+   *
+   * note that it uses string as keys instead of StateConfig so it has no way to parse at export time.
+   * In exportJSON, we only parse knownState to save the default value which is not exported.
+   * For safety, we parse unknownState in get state.
+   */
+  private unknownState: Record<string, unknown> = {};
+
+  private toJSON(): State {
+    const state = {...this.unknownState};
+    this.knownState.forEach((stateValue, stateConfig) => {
+      if (stateValue !== stateConfig.defaultValue) {
+        state[stateConfig.key] = stateConfig.parse(stateValue);
+      }
+    });
+    return state as State;
+  }
+
+  private clone() {
+    const newState = new NodeState();
+    newState.unknownState = {...this.unknownState};
+    newState.knownState = new Map(this.knownState);
+    return newState;
+  }
+}

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

@@ -36,7 +36,7 @@ import {
   TestInlineElementNode,
 } from '../utils';
 
-class TestNode extends LexicalNode {
+export class TestNode extends LexicalNode {
   static getType(): string {
     return 'test';
   }