[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

.github/workflows/call-integration-tests.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.15.1]
+        node-version: [22.14.0]
     env:
       CI: true
     steps:
@@ -17,7 +17,6 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: npm
       - name: Install dependencies
         run: npm ci
       - run: npm run test-integration

packages/lexical-playground/src/nodes/PollNode.tsx

@@ -8,13 +8,14 @@
 
 import type {JSX} from 'react';
 
+import {makeStateWrapper} from '@lexical/utils';
 import {
+  createState,
   DecoratorNode,
   DOMConversionMap,
   DOMConversionOutput,
   DOMExportOutput,
   LexicalNode,
-  NodeKey,
   SerializedLexicalNode,
   Spread,
 } from 'lexical';
@@ -75,16 +76,44 @@ function $convertPollElement(domNode: HTMLElement): DOMConversionOutput | null {
   return null;
 }
 
-export class PollNode extends DecoratorNode<JSX.Element> {
-  __question: string;
-  __options: Options;
+function parseOptions(json: unknown): Options {
+  const options = [];
+  if (Array.isArray(json)) {
+    for (const row of json) {
+      if (
+        row &&
+        typeof row.text === 'string' &&
+        typeof row.uid === 'string' &&
+        Array.isArray(row.votes) &&
+        row.votes.every((v: unknown) => typeof v === 'number')
+      ) {
+        options.push(row);
+      }
+    }
+  }
+  return options;
+}
+
+const questionState = makeStateWrapper(
+  createState('question', {
+    parse: (v) => (typeof v === 'string' ? v : ''),
+  }),
+);
+const optionsState = makeStateWrapper(
+  createState('options', {
+    isEqual: (a, b) =>
+      a.length === b.length && JSON.stringify(a) === JSON.stringify(b),
+    parse: parseOptions,
+  }),
+);
 
+export class PollNode extends DecoratorNode<JSX.Element> {
   static getType(): string {
     return 'poll';
   }
 
   static clone(node: PollNode): PollNode {
-    return new PollNode(node.__question, node.__options, node.__key);
+    return new PollNode(node.__key);
   }
 
   static importJSON(serializedNode: SerializedPollNode): PollNode {
@@ -94,59 +123,56 @@ export class PollNode extends DecoratorNode<JSX.Element> {
     ).updateFromJSON(serializedNode);
   }
 
-  constructor(question: string, options: Options, key?: NodeKey) {
-    super(key);
-    this.__question = question;
-    this.__options = options;
-  }
-
-  exportJSON(): SerializedPollNode {
-    return {
-      ...super.exportJSON(),
-      options: this.__options,
-      question: this.__question,
-    };
-  }
+  getQuestion = questionState.makeGetterMethod<this>();
+  setQuestion = questionState.makeSetterMethod<this>();
+  getOptions = optionsState.makeGetterMethod<this>();
+  setOptions = optionsState.makeSetterMethod<this>();
 
-  addOption(option: Option): void {
-    const self = this.getWritable();
-    const options = Array.from(self.__options);
-    options.push(option);
-    self.__options = options;
+  addOption(option: Option): this {
+    return this.setOptions((options) => [...options, option]);
   }
 
-  deleteOption(option: Option): void {
-    const self = this.getWritable();
-    const options = Array.from(self.__options);
-    const index = options.indexOf(option);
-    options.splice(index, 1);
-    self.__options = options;
+  deleteOption(option: Option): this {
+    return this.setOptions((prevOptions) => {
+      const index = prevOptions.indexOf(option);
+      if (index === -1) {
+        return prevOptions;
+      }
+      const options = Array.from(prevOptions);
+      options.splice(index, 1);
+      return options;
+    });
   }
 
-  setOptionText(option: Option, text: string): void {
-    const self = this.getWritable();
-    const clonedOption = cloneOption(option, text);
-    const options = Array.from(self.__options);
-    const index = options.indexOf(option);
-    options[index] = clonedOption;
-    self.__options = options;
+  setOptionText(option: Option, text: string): this {
+    return this.setOptions((prevOptions) => {
+      const clonedOption = cloneOption(option, text);
+      const options = Array.from(prevOptions);
+      const index = options.indexOf(option);
+      options[index] = clonedOption;
+      return options;
+    });
   }
 
-  toggleVote(option: Option, clientID: number): void {
-    const self = this.getWritable();
-    const votes = option.votes;
-    const votesClone = Array.from(votes);
-    const voteIndex = votes.indexOf(clientID);
-    if (voteIndex === -1) {
-      votesClone.push(clientID);
-    } else {
-      votesClone.splice(voteIndex, 1);
-    }
-    const clonedOption = cloneOption(option, option.text, votesClone);
-    const options = Array.from(self.__options);
-    const index = options.indexOf(option);
-    options[index] = clonedOption;
-    self.__options = options;
+  toggleVote(option: Option, clientID: number): this {
+    return this.setOptions((prevOptions) => {
+      const index = prevOptions.indexOf(option);
+      if (index === -1) {
+        return prevOptions;
+      }
+      const votes = option.votes;
+      const votesClone = Array.from(votes);
+      const voteIndex = votes.indexOf(clientID);
+      if (voteIndex === -1) {
+        votesClone.push(clientID);
+      } else {
+        votesClone.splice(voteIndex, 1);
+      }
+      const clonedOption = cloneOption(option, option.text, votesClone);
+      const options = Array.from(prevOptions);
+      options[index] = clonedOption;
+      return options;
+    });
   }
 
   static importDOM(): DOMConversionMap | null {
@@ -165,10 +191,10 @@ export class PollNode extends DecoratorNode<JSX.Element> {
 
   exportDOM(): DOMExportOutput {
     const element = document.createElement('span');
-    element.setAttribute('data-lexical-poll-question', this.__question);
+    element.setAttribute('data-lexical-poll-question', this.getQuestion());
     element.setAttribute(
       'data-lexical-poll-options',
-      JSON.stringify(this.__options),
+      JSON.stringify(this.getOptions()),
     );
     return {element};
   }
@@ -186,16 +212,16 @@ export class PollNode extends DecoratorNode<JSX.Element> {
   decorate(): JSX.Element {
     return (
       <PollComponent
-        question={this.__question}
-        options={this.__options}
+        question={this.getQuestion()}
+        options={this.getOptions()}
         nodeKey={this.__key}
       />
     );
   }
 }
 
 export function $createPollNode(question: string, options: Options): PollNode {
-  return new PollNode(question, options);
+  return new PollNode().setQuestion(question).setOptions(options);
 }
 
 export function $isPollNode(

packages/lexical-utils/src/index.ts

@@ -17,6 +17,7 @@ import {
   $getRoot,
   $getSelection,
   $getSiblingCaret,
+  $getState,
   $isChildCaret,
   $isElementNode,
   $isRangeSelection,
@@ -25,6 +26,7 @@ import {
   $isTextNode,
   $rewindSiblingCaret,
   $setSelection,
+  $setState,
   $splitNode,
   type CaretDirection,
   type EditorState,
@@ -37,6 +39,8 @@ import {
   type NodeKey,
   RootMode,
   type SiblingCaret,
+  StateConfig,
+  ValueOrUpdater,
 } from 'lexical';
 // This underscore postfixing is used as a hotfix so we do not
 // export shared types from this module #5918
@@ -860,3 +864,86 @@ export function $getAdjacentSiblingOrParentSiblingCaret<
   }
   return nextCaret && [nextCaret, depthDiff];
 }
+
+/**
+ * A wrapper that creates bound functions and methods for the
+ * StateConfig to save some boilerplate when defining methods
+ * or exporting only the accessors from your modules rather
+ * than exposing the StateConfig directly.
+ */
+export interface StateConfigWrapper<K extends string, V> {
+  /** A reference to the stateConfig */
+  readonly stateConfig: StateConfig<K, V>;
+  /** `(node) => $getState(node, stateConfig)` */
+  readonly $get: <T extends LexicalNode>(node: T) => V;
+  /** `(node, valueOrUpdater) => $setState(node, stateConfig, valueOrUpdater)` */
+  readonly $set: <T extends LexicalNode>(
+    node: T,
+    valueOrUpdater: ValueOrUpdater<V>,
+  ) => T;
+  /** `[$get, $set]` */
+  readonly accessors: readonly [$get: this['$get'], $set: this['$set']];
+  /**
+   * `() => function () { return $get(this) }`
+   *
+   * Should be called with an explicit `this` type parameter.
+   *
+   * @example
+   * ```ts
+   * class MyNode {
+   *   // …
+   *   myGetter = myWrapper.makeGetterMethod<this>();
+   * }
+   * ```
+   */
+  makeGetterMethod<T extends LexicalNode>(): (this: T) => V;
+  /**
+   * `() => function (valueOrUpdater) { return $set(this, valueOrUpdater) }`
+   *
+   * Must be called with an explicit `this` type parameter.
+   *
+   * @example
+   * ```ts
+   * class MyNode {
+   *   // …
+   *   mySetter = myWrapper.makeSetterMethod<this>();
+   * }
+   * ```
+   */
+  makeSetterMethod<T extends LexicalNode>(): (
+    this: T,
+    valueOrUpdater: ValueOrUpdater<V>,
+  ) => T;
+}
+
+/**
+ * EXPERIMENTAL
+ *
+ * A convenience interface for working with {@link $getState} and
+ * {@link $setState}.
+ *
+ * @param stateConfig The stateConfig to wrap with convenience functionality
+ * @returns a StateWrapper
+ */
+export function makeStateWrapper<K extends string, V>(
+  stateConfig: StateConfig<K, V>,
+): StateConfigWrapper<K, V> {
+  const $get: StateConfigWrapper<K, V>['$get'] = (node) =>
+    $getState(node, stateConfig);
+  const $set: StateConfigWrapper<K, V>['$set'] = (node, valueOrUpdater) =>
+    $setState(node, stateConfig, valueOrUpdater);
+  return {
+    $get,
+    $set,
+    accessors: [$get, $set],
+    makeGetterMethod: () =>
+      function $getter() {
+        return $get(this);
+      },
+    makeSetterMethod: () =>
+      function $setter(valueOrUpdater) {
+        return $set(this, valueOrUpdater);
+      },
+    stateConfig,
+  };
+}