[WIP][lexical[lexical-utils] Feature: NodeCaret abstraction for traversals and ranges

[etrepum]

Description

NOTE: This is a work in progress, not a finalized proposal

A fair amount of bugs and complexity in our code results from ambiguity and awkwardness around traversing the node tree, as well as issues around coordinates becoming stale after mutations. This is a draft in-progress proposal for a new set of abstractions that can be used in place of the typical PointType and RangeSelection to work through these sorts of traversal use cases with hopefully fewer bugs.

There are two major deficiencies that the design of NodeCaret hopes to address:

• PointType is not directional, and it's also not possible to infer a direction from a collapsed RangeSelection.
• Dealing with the borders of an ElementNode is full of quirks, especially when empty, frequently causing over-selection or under-selection or just having to frequently branch for empty and non-empty cases.
• Instability of PointType when doing anything "before" the point (e.g. inserting a node before a point "moves" the logical location of the point to the newly inserted node)

At this time there's no special support for TextNode. A NodeCaret is a triple of:

• type: 'breadth' | 'depth'
• origin: LexicalNode - the "anchor" of this caret
• direction: 'next' if the caret points after this node (towards the next sibling for breadth, towards the first child for depth) and 'previous' if the caret points before this node (towards the previous sibling for breadth, towards the last child for depth)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
lexical	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 16, 2025 5:55am
lexical-playground	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 16, 2025 5:55am

[github-actions]

size-limit report 📦

Path	Size
lexical - cjs	30.45 KB (+4.88% 🔺)
lexical - esm	30.28 KB (+4.9% 🔺)
@lexical/rich-text - cjs	39.4 KB (+3.78% 🔺)
@lexical/rich-text - esm	30.92 KB (+0.02% 🔺)
@lexical/plain-text - cjs	37.97 KB (+3.99% 🔺)
@lexical/plain-text - esm	28.23 KB (+0.35% 🔺)
@lexical/react - cjs	41.21 KB (+3.57% 🔺)
@lexical/react - esm	32.36 KB (+0.23% 🔺)