Skip to content

[WIP][RFC] NodeState plus $config protocol#7189

Closed
etrepum wants to merge 51 commits intofacebook:mainfrom
etrepum:state-v2
Closed

[WIP][RFC] NodeState plus $config protocol#7189
etrepum wants to merge 51 commits intofacebook:mainfrom
etrepum:state-v2

Conversation

@etrepum
Copy link
Copy Markdown
Collaborator

@etrepum etrepum commented Feb 16, 2025 •
edited
Loading

Superseded by #7258

Description

Exploratory fork of #7117 also exploring how to work around the fact that we can't really properly type things like updateFromJSON, etc.

See also #6998 discussion.

The short story is that this sort of thing will let us get better type-level information about nodes. We can't have node.getType() ever give a more specific type than string but we could write a $getType(node) that does infer to the exact type if we want. Same thing for node.exportJSON() and similar methods.

It also facilitates scrapping all of the node subclass boilerplate, except for this one method, so long as the class has a compatible signature (trivial constructor)

Example of extension and inference capability from the tests 
const numberState = createState('numberState', {
  parse: (v) => (typeof v === 'number' ? v : 0),
});
const boolState = createState('boolState', {parse: Boolean});
class StateNode extends TestNode {
  $config() {
    return this.config('state', {
      extends: TestNode,
      stateConfigs: [{flat: true, stateConfig: numberState}, boolState],
    });
  }
  getNumber() {
    return $getState(this, numberState);
  }
  setNumber(valueOrUpdater: StateValueOrUpdater<typeof numberState>): this {
    return $setState(this, numberState, valueOrUpdater);
  }
}

const extraState = createState('extra', {parse: String});
class ExtraStateNode extends StateNode {
  $config() {
    return this.config('extra-state', {
      extends: StateNode,
      stateConfigs: [{flat: true, stateConfig: extraState}],
    });
  }
}

type _TestExtraStateNodeExportJSON = Expect<
  Equal<
    ExtraStateNodeExportJSON,
    {
      state?:
        | (Record<string, unknown> & {
            boolState?: boolean | undefined;
          })
        | undefined;
      version: number;
      type: 'extra-state';
      numberState?: number | undefined;
      extra?: string | undefined;
    }
  >
>;

How it works

The proposed protocol for declaring nodes would scale down to something like this:

class CustomTextNode extends TextNode {
  $config() {
    return this.config('custom-text', {extends: TextNode});
  }
}

The two method interface is useful for TypeScript reasons, basically. The outer getStaticNodeConfig (could come up with a shorter and/or more memorable name) is the API and the this.configureNode(…) is a helper method that has the right generics to make it easy to return something with the right shape and type. The types are very delicate, if you don't have all of the annotations just right then the type will simplify into something without information that can be extracted. Basically it is just returning an object like this, but in a way where TypeScript doesn't collapse the type into something simpler (kind of like using as const or satisfies in the right place):

{'custom-text': {type: 'custom-text', extends: TextNode}}

On the LexicalEditor side, during createEditor, CustomTextNode.prototype.$config() is called and can grab the type and any other useful metadata (e.g. a defined transform, registered state, anything else we want to put in there). For compatibility reasons it will also monkeypatch getType, importJSON, and clone static methods onto the node class if they are not already there. It adds a module global variable to inject cloned node keys so it doesn't need to break any compatibility with multi-argument constructors, it only requires that they have a 0-argument form.

I've also put a $create method in there which reduces the boilerplate and increases the efficiency there, assuming that we'd be willing to deprecate with in the node overrides and go directly to withKlass so that we don't have to construct any intermediate garbage when that's configured.

I think this covers most of the breaking-ish changes I would want to make to the lowest level stuff, in exchange for better DX and no loss of performance (probably better, even if just code size improves).

Future direction

I think this is where we fix the rest of the #6998 things here with some combination of middleware-style functions or automatic super calls (like $afterCloneFrom) instead of methods so that we can control things better without variance violations.

GermanJablo and others added 30 commits December 19, 2024 16:57
@GermanJablo
state to lexicalNode
a6288f9
@GermanJablo
Squashed commit of the following:
a90a719 
commit a62a1a6
Author: James Fitzsimmons <119275535+james-atticus@users.noreply.github.com>
Date:   Thu Jan 30 19:13:35 2025 +1100

    [lexical-mark] Feature: include inline decorator nodes in marks (facebook#7086)

commit 881c7fe
Author: Bob Ippolito <bob@redivi.com>
Date:   Thu Jan 30 00:13:00 2025 -0800

    [lexical-utils] Fix: Modify $reverseDfs to be a right-to-left variant of $dfs (facebook#7112)

commit ce2bb45
Author: Nigel Gutzmann <nigelgutzmann@gmail.com>
Date:   Wed Jan 29 14:41:12 2025 -0800

    [lexical-utils] Feature: add reverse dfs iterator (facebook#7107)

commit 3a140d2
Author: mohammed shaheer kp <72137242+mshaheerz@users.noreply.github.com>
Date:   Tue Jan 28 06:19:45 2025 +0530

    [lexical-playground] Bug Fix: Ensure Delete Node handles all node types (facebook#7096)

    Co-authored-by: shaheerkpzaigo <mohammedshaheer@zaigoinfotech.com>

commit 8e2ede2
Author: Adam Pugh <docadam@meta.com>
Date:   Mon Jan 27 18:49:38 2025 -0600

    Listeners Lexical: 3 updates to spelling and grammar - Update listeners.md  (facebook#7100)

commit 9fcc494
Author: Adam Pugh <docadam@meta.com>
Date:   Mon Jan 27 18:49:34 2025 -0600

    Lexical Docs: 2 updates to spelling README.md (facebook#7102)

commit 946a6df
Author: Adam Pugh <docadam@meta.com>
Date:   Mon Jan 27 18:49:29 2025 -0600

    Selection | Lexical: 1 Spelling Update Update selection.md (facebook#7103)

commit ce93ea6
Author: Adam Pugh <docadam@meta.com>
Date:   Mon Jan 27 18:49:25 2025 -0600

    Creating a React Plugin: 1 Grammar Update - Update create_plugin.md (facebook#7104)

commit ed29d89
Author: Adam Pugh <docadam@meta.com>
Date:   Mon Jan 27 18:49:21 2025 -0600

    Working with DOM Events: 2 Spelling and Grammar Updates Update dom-ev… (facebook#7105)

commit 212b70f
Author: James Fitzsimmons <119275535+james-atticus@users.noreply.github.com>
Date:   Mon Jan 27 08:48:09 2025 +1100

    [lexical-yjs] Bug Fix: handle text node being split by Yjs redo (facebook#7098)

commit 6a98a47
Author: Torleif Berger <torleif@outlook.com>
Date:   Fri Jan 24 21:46:45 2025 +0100

    [lexical-react] Bug Fix: Import `JSX` type from React to prevent "Cannot find namespace 'JSX'"-error when type-checking with React 19 (facebook#7080)

commit f8e5968
Author: Tetsuya <62472294+EruditionTu@users.noreply.github.com>
Date:   Sat Jan 25 04:06:57 2025 +0800

    [lexical] Chore: Rename variable and add comments for Safari compositing workaround (facebook#7092)

commit 81c9ab6
Author: Mateo Vuković <195247756+hellovuki@users.noreply.github.com>
Date:   Fri Jan 24 18:44:05 2025 +0100

    Fix: Use already defined RegisteredNodes type (facebook#7085)

commit 63958a2
Author: Sherry <potatowagon@meta.com>
Date:   Tue Jan 21 18:15:21 2025 +0800

    [playground] Bug fix: prevent growing whitespaces in markdown table toggle (facebook#7041)

    Co-authored-by: Bob Ippolito <bob@redivi.com>

commit d9f9924
Author: Sherry <potatowagon@meta.com>
Date:   Tue Jan 21 14:58:08 2025 +0800

    Unrevert [Breaking Change][lexical] Bug Fix: Commit updates on editor.setRootElement(null) facebook#7023 (facebook#7068)

commit 92fa0a3
Author: mohammed shaheer kp <72137242+mshaheerz@users.noreply.github.com>
Date:   Tue Jan 21 06:23:24 2025 +0530

    [lexical-playground] plugins TableOfContent Scroll smooth behaviour A… (facebook#7069)

commit 2e4a63e
Author: Ivaylo Pavlov <ivailo90@gmail.com>
Date:   Mon Jan 20 02:37:34 2025 +0000

    [lexical-playground] Fix Columns Layout Item Overflow (facebook#7066)

commit d319b07
Author: Bob Ippolito <bob@redivi.com>
Date:   Sun Jan 19 14:45:41 2025 -0800

    Change fork modules to use production only when NODE_ENV explicitly set to production (facebook#7065)

commit 46c9c2f
Author: CityHunter <62472294+EruditionTu@users.noreply.github.com>
Date:   Sat Jan 18 13:00:38 2025 +0800

    [lexical] Bug Fix: In the Safari browser, during the compositing event process, the delete key exhibits unexpected behavior. (facebook#7061)

    Co-authored-by: 涂博闻 <tubowen@moonshot.cn>

commit 92a1cd7
Author: Violet Rosenzweig <rosenzweig.violet@gmail.com>
Date:   Thu Jan 16 18:44:11 2025 -0500

    docs: Change "here" link to more descriptive text (facebook#7058)

commit f6377a3
Author: Aman Harwara <amanharwara@protonmail.com>
Date:   Fri Jan 17 02:08:17 2025 +0530

    [lexical-table] Bug Fix: Prevent error if pasted table has empty row (facebook#7057)

commit 0835029
Author: Aman Harwara <amanharwara@protonmail.com>
Date:   Fri Jan 17 00:18:08 2025 +0530

    [lexical-list] Bug Fix: Prevent error when calling formatList when selection is at root (facebook#6994)

commit 940435d
Author: Brayden <1311325+redstar504@users.noreply.github.com>
Date:   Wed Jan 15 16:10:01 2025 -0800

    fix: iOS Autocorrect strips formatting by reporting wrong dataType (facebook#5789)

    Co-authored-by: Bob Ippolito <bob@redivi.com>

commit 136a565
Author: Aman Harwara <amanharwara@protonmail.com>
Date:   Thu Jan 16 04:48:32 2025 +0530

    [lexical-yjs] Feature: Allow passing in custom `syncCursorPositions` function to collab hook (facebook#7053)

commit 415c576
Author: Maksim Horbachevsky <fantactuka@gmail.com>
Date:   Wed Jan 15 18:18:03 2025 -0500

    fix: triple click around inline elements (links) (facebook#7055)

commit a3ef4f3
Author: Ivaylo Pavlov <ivailo90@gmail.com>
Date:   Wed Jan 15 23:15:39 2025 +0000

    [lexical-table] Support table alignment (facebook#7044)

commit 29d733c
Author: Sherry <potatowagon@meta.com>
Date:   Wed Jan 15 21:50:07 2025 +0800

    Revert [Breaking Change][lexical] Bug Fix: Commit updates on editorSetRootElement(null) (facebook#7023) (facebook#7052)

commit 65ce66a
Author: Bob Ippolito <bob@redivi.com>
Date:   Tue Jan 14 14:57:54 2025 -0800

    [lexical] Bug Fix: Normalize selection after applyDOMRange to account for Firefox differences (facebook#7050)

commit bbc07af
Author: Bob Ippolito <bob@redivi.com>
Date:   Tue Jan 14 08:55:46 2025 -0800

    [*] Bug Fix: Use GITHUB_OUTPUT instead of GITHUB_ENV for size-limit action (facebook#7051)

commit c8f27ed
Author: Bob Ippolito <bob@redivi.com>
Date:   Tue Jan 14 06:36:13 2025 -0800

    [Breaking Change][*] Chore: Use terser for optimizing cjs prod build (facebook#7047)

commit 8bd22d5
Author: Bob Ippolito <bob@redivi.com>
Date:   Mon Jan 13 07:09:31 2025 -0800

    [lexical] Bug Fix: Handle MutationObserver/input event re-ordering when using contentEditable inside of an iframe (facebook#7045)

commit 930629c
Author: Ivaylo Pavlov <ivailo90@gmail.com>
Date:   Sat Jan 11 06:03:30 2025 +0000

    Clean up nested editor update (facebook#7039)

commit bd874a3
Author: Bob Ippolito <bob@redivi.com>
Date:   Fri Jan 10 15:23:54 2025 -0800

    [Breaking Change][lexical][lexical-selection][lexical-list] Bug Fix: Fix infinite loop when splitting invalid ListItemNode (facebook#7037)

commit 541fa43
Author: Bob Ippolito <bob@redivi.com>
Date:   Thu Jan 9 12:42:23 2025 -0800

    v0.23.1 (facebook#7035)

    Co-authored-by: Lexical GitHub Actions Bot <>

commit d7abafd
Author: Bob Ippolito <bob@redivi.com>
Date:   Thu Jan 9 08:33:12 2025 -0800

    [Breaking Change][lexical] Bug Fix: Commit updates on editor.setRootElement(null) (facebook#7023)

commit 6add515
Author: Bob Ippolito <bob@redivi.com>
Date:   Wed Jan 8 17:27:15 2025 -0800

    [lexical] Fix TabNode deserialization regression  (facebook#7031)

commit 33e3677
Author: Maksim Horbachevsky <fantactuka@gmail.com>
Date:   Wed Jan 8 14:59:03 2025 -0500

    [lexical-react] Feature: Merge TabIndentionPlugin and ListMaxIndentLevelPlugin plugins (facebook#7018)

commit 7de86e4
Author: James Fitzsimmons <119275535+james-atticus@users.noreply.github.com>
Date:   Wed Jan 8 09:45:25 2025 +1100

    [lexical-mark] Bug Fix: reverse ternary in MarkNode.addID (facebook#7020)

commit 7961130
Author: Bob Ippolito <bob@redivi.com>
Date:   Sun Jan 5 13:55:25 2025 -0800

    v0.23.0 (facebook#7017)

    Co-authored-by: Lexical GitHub Actions Bot <>

commit 2b4252d
Author: Aman Harwara <amanharwara@protonmail.com>
Date:   Sat Jan 4 11:31:19 2025 +0530

    [lexical-yjs] Feature: Expose function to get anchor and focus nodes for given user awareness state (facebook#6942)

commit 8100d6d
Author: Ivaylo Pavlov <ivailo90@gmail.com>
Date:   Sat Jan 4 01:12:04 2025 +0000

    [lexical-playground] Fix table hover actions button position (facebook#7011)

commit bd1ef2a
Author: Bob Ippolito <bob@redivi.com>
Date:   Fri Jan 3 14:25:31 2025 -0800

    [lexical] Bug Fix: Fix registerNodeTransform regression introduced in facebook#6894 (facebook#7016)

commit 85c08b6
Author: Christian Grøngaard <christian@groengaard.dk>
Date:   Thu Jan 2 00:20:20 2025 +0100

    [lexical-playground] Refactor: switch headings test file names (facebook#7008)

commit 7c21d4f
Author: Bob Ippolito <bob@redivi.com>
Date:   Wed Jan 1 12:48:12 2025 -0800

    [Breaking Change][lexical] Feature: Add updateFromJSON and move more textFormat/textStyle to ElementNode (facebook#6970)

commit aaa9009
Author: Bob Ippolito <bob@redivi.com>
Date:   Wed Jan 1 07:50:39 2025 -0800

    [lexical] Bug Fix: Fix getNodes over-selection (facebook#7006)

commit 803391d
Author: Sherry <potatowagon@meta.com>
Date:   Tue Dec 31 11:26:17 2024 +0800

    [__test__] npm upgrade astro (facebook#7001)

commit 684352b
Author: Christian Grøngaard <christian@groengaard.dk>
Date:   Mon Dec 30 05:12:45 2024 +0100

    Documentation: Fix typo "nest nest"->"nest" in README.md (facebook#7000)

    Co-authored-by: Bob Ippolito <bob@redivi.com>

commit 27b75cc
Author: Sherry <potatowagon@meta.com>
Date:   Fri Dec 27 11:06:29 2024 +0800

    [__tests__] npm upgrade next (facebook#6996)

commit 05ddbcc
Author: Simon <bauchet.simon@gmail.com>
Date:   Thu Dec 26 03:37:50 2024 +0100

    [lexical] Bug Fix: Flow is missing some variables and functions (facebook#6977)

commit e79c946
Author: Sherry <potatowagon@meta.com>
Date:   Tue Dec 24 09:54:46 2024 +0800

    v0.22.0 (facebook#6993)

    Co-authored-by: Lexical GitHub Actions Bot <>

commit c415f7a
Author: Sam Zhou <sam@developersam.com>
Date:   Mon Dec 23 10:31:36 2024 -0800

    [lexical-react] Refactor: Replace `React$MixedElement` and `React$Node` with `React.MixedElement` and `React.Node` (facebook#6984)

commit c844a4d
Author: Sherry <potatowagon@meta.com>
Date:   Tue Dec 24 02:30:52 2024 +0800

    [lexical] Fix flow error: change this to any (facebook#6992)

commit 6190033
Author: Germán Jabloñski <43938777+GermanJablo@users.noreply.github.com>
Date:   Mon Dec 23 05:19:27 2024 -0300

    Refactor: exportJSON (facebook#6983)

commit e0dafb8
Author: Germán Jabloñski <43938777+GermanJablo@users.noreply.github.com>
Date:   Sat Dec 21 13:59:01 2024 -0300

    feature: expose forEachSelectedTextNode (facebook#6981)

    Co-authored-by: Bob Ippolito <bob@redivi.com>

commit 23715f5
Author: Alex <UlopLT@gmail.com>
Date:   Fri Dec 20 18:23:27 2024 +0300

    [lexical][lexical-table] Bug fix: TablePlugin:  - check is current selection in target table node (facebook#6979)

    Co-authored-by: alazarev <alazarev@megaputer.ru>
@GermanJablo
first version with default value
448e2af
@GermanJablo
make state json serializable
bf70110
@GermanJablo
add import and export json tests
6ebd4e5
@GermanJablo
getState returns immutable types
e46d735
@GermanJablo
fix tests
e404d32
@GermanJablo
Merge remote-tracking branch 'origin/main' into state
c1cfce4
@GermanJablo
add docs
6d00c64
@GermanJablo
remove readonly property
e0c5945
@GermanJablo
add paragraph in docs about json serializable values
7728780
@GermanJablo
better example in docs. getState does not necessarily return undefined.
d807d4f
@GermanJablo
use $createTextNode()
90a032b
@GermanJablo
fix type
c663540
@GermanJablo
create a new object in setState
113a4f1
@GermanJablo
fix unit test
91148f3
@GermanJablo @etrepum
Update packages/lexical/src/LexicalNode.ts
47435b0 
Co-authored-by: Bob Ippolito <bob@redivi.com>
@GermanJablo @etrepum
Update packages/lexical/src/LexicalNode.ts
fb7e164 
Co-authored-by: Bob Ippolito <bob@redivi.com>
@GermanJablo @etrepum
Update packages/lexical/src/LexicalNode.ts
eab152e 
Co-authored-by: Bob Ippolito <bob@redivi.com>
@GermanJablo @etrepum
Update packages/lexical/src/LexicalNode.ts
d2b4f21 
Co-authored-by: Bob Ippolito <bob@redivi.com>
@GermanJablo
add null to State type, fix parse function in test
2bc4a0e
@GermanJablo
add Bob's test about previous reconciled versions of the node
fca2071
@GermanJablo
improve parse functions in tests again
8cf6855
@GermanJablo
add stateStore to register state keys
abd3d3e
@GermanJablo
BIG CHANGE - state as class
3f8bba0
@GermanJablo
improvements
4624e2f
@etrepum
Refactor with optimizations and collab support
a62cf45
@etrepum
Merge remote-tracking branch 'origin/main' into state
bdd3971
@etrepum
Minimize the API and move convenience methods to @lexical/utils
27910f2
@etrepum
Rename valueToJSON to unparse, use longer stateConfig naming for vari…
9499667 
…ables
@etrepum etrepum changed the title [WIP] NodeState plus getStaticNodeConfig [WIP] NodeState plus $config protocol Feb 17, 2025
@etrepum etrepum changed the title [WIP] NodeState plus $config protocol [WIP][RFC] NodeState plus $config protocol Feb 17, 2025
@etrepum etrepum mentioned this pull request Feb 18, 2025
Merged
@etrepum etrepum mentioned this pull request Feb 27, 2025
Merged
@etrepum
Copy link
Copy Markdown
Collaborator Author

etrepum commented Feb 27, 2025

Superseded by #7258

@etrepum etrepum closed this Feb 27, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zurfyx zurfyx Awaiting requested review from zurfyx zurfyx will be requested when the pull request is marked ready for review zurfyx is a code owner

@fantactuka fantactuka Awaiting requested review from fantactuka fantactuka will be requested when the pull request is marked ready for review fantactuka is a code owner

@acywatson acywatson Awaiting requested review from acywatson acywatson will be requested when the pull request is marked ready for review acywatson is a code owner

@ivailop7 ivailop7 Awaiting requested review from ivailop7 ivailop7 will be requested when the pull request is marked ready for review ivailop7 is a code owner

@potatowagon potatowagon Awaiting requested review from potatowagon potatowagon will be requested when the pull request is marked ready for review potatowagon is a code owner

@takuyakanbr takuyakanbr Awaiting requested review from takuyakanbr takuyakanbr will be requested when the pull request is marked ready for review takuyakanbr is a code owner

Assignees

No one assigned

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@etrepum @facebook-github-bot @GermanJablo