Flat selection design

[doodlewind]

Here we explain the basic design principles for working with native DOM selection in BlockSuite.

Natively, a DOM selection is composed with anchorNode and focusNode. This can be used for indexing a sub-tree. But for rich text editing, this API surface leaks many edge cases to be handled manually. For example, suppose we have 3 lines of text (3 paragraph blocks):

<p>123</p>
<p>456</p>
<p>789</p>

And for a rich text editor, similar content can also be expressed in this way:

<p><b>123</b></p>
<p>456</p>
<p><b>789</b></p>

In both cases, we can perform a range selection from 2 to 8 (23 456 78 get selected), but the resulting DOM range can be very different, which is challenging to work with.

The proposed solution is to make our selection representation flat. To do this, Quill's getSelection API is a great fit. This { index: number, length: number } interface is excellent for updating our text model (code), whose result won't be affected by nested tags for rich text formatting.

Also, BlockSuite is designed to support the co-existing of different rich text editor instances. For the example above, we have three Quill instances:

123 // block 1 with a standalone quill instance inside
456 // block 2 with a standalone quill instance inside
789 // block 3 with a standalone quill instance inside

So based on this approach, when we select from 2 to 8, the flat selection should be modeled in this way:

blocks: [1, 2, 3] // selected block ids
start: { index: 1, length: 2 } // the selected `23` in first selected block
end: { index: 0, length: 2 } // the selected `78` in last selected block

However, when the native DOM selection covers different quill instances, Quill's getSelection API doesn't work (returns null). So we need to support our range selection representation by ourselves. We already have getQuillIndexByNativeSelection that provides the corresponding underlying capabilities. But we still need further engineering effort to get a reusable selection representation with handy APIs.

cc @lawvs @DiamondThree @SaikaSakura @JimmFly @thorseraq

[SaikaSakura]

I think we can use ourselves data model to describe selection information . And we should use same data model in other features like copy / paste or comment . But it most like native browser selection , like :

type selectionInfo = {
  start: {blockId: string , offset: number},
  end: {blockId: string , offset: number}
}

It is easy for selection coordinating . If we list all selected blocks , it may change to a complex problem .

And we should provide more pure functions and methods like :

function getSelectedIdsBySelectionInfo(selectionInfo: selectionInfo): string[];
function getSelectedBlocksBySelectionInfo: (
  selectionInfo: selectionInfo
) : Blocks[];

interface Selection {
  getSelectedBlockIds: () => string[];
  getSelectedBlocks: () => Blocks[];
}

[doodlewind]

When compared to the native selection, IMO, the SelectionInfo here should also contain all blocks being selected in between. Otherwise, we need to manually compute all the blocks covered by the native selection, which is very error-prone.

Notice that the scope of "selection" is pretty broad, so a NativeSelection representation here may be more appropriate.

[SaikaSakura]

We can provide stable function to compute witch blocks are selected , it equals we just provide before and end information. May be the before and end infor is a array , if the documents has random order in endless mode .

[colelawrence]

This sounds very similar to how ProseMirror manages selections, except it seems like ProseMirror might be a bit easier to operate on since the rules are very consistent for the whole tree (e.g. every spot on the document inside or outside an element has a different position) & you can always easily determine if something is on the selection or outside it with greater than or less than comparisons.

How does this design compare?

Can you represent a selection of <p>|<b>Text differently than <p><b>|Text?

[doodlewind]

Can you represent a selection of <p>|<b>Text differently than <p><b>|Text?

They would be the same with the { index, length } representation. And for updating text models, I think separating them is unnecessary. What's important here is to have APIs for controlling inline format inheriting. This is critical when the cursor is put at the end of something like <code>some inline code</code>. In this case, we need to be able to control if the next character should have the inline code format. This could be easily toggled by other APIs provided by the rich text editor.

[colelawrence]

Is this discussion specific only to quill? I think I'd benefit from a list of survive ways this has been approached and the pros and cons of the approach described, here.

[doodlewind]

Eventually, we can have our rich text library to replace Quill. Still, I believe if that editor exists, it will also reuse the { index: number, length: number } representation for native in-block selection. And we can build the somewhat like { selectedBlocks: Block[], start: { index, length }, end: { index, length } } interface for native multi-block selection on top of that.