Multi-User Selection

[matthew-carroll]

Super Editor would like to support rendering multiple user selections at the same time. Recent work on super_text_layout makes the rendering possible, but we still need to expose appropriate APIs at the super_editor level.

Ideally, multi-user selection management should be simple and easy, but it also shouldn't make single-user selection any more complicated than it already is. The average use-case is single-user selection, and that's likely to be true forever.

How can we offer multi-user selection controls without making single-user selection more tedious?

What needs to be tracked?

Multi-user selection obviously requires tracking multiple DocumentSelections. But it also requires tracking more than that. To update a given selection, or to remove it, the selection must be linked to the corresponding user.

However, as we consider rendering multiple selections, it's worth considering a feature like "find", which highlights every span of text in the document that matches a given search query. The "find" use-case also requires multiple selections, but those selections are not tied to a specific user. The primary goal at this point is multi-user selection, but it would be a win to leave the door open for multi-selection controlled by any given feature, such as find.

With whatever information is tracked, the selections should be listenable, individually. It's reasonable to assume that super_editor would like to repaint only what's necessary, and part of this optimization requires that super_editor be aware of which selections changed, and which selections didn't. For example, a selection is likely to sit within a single paragraph. In such a situation, super_editor should not repaint the other 20 paragraphs in that same document.

Representing multiple selections

User selection is currently owned by an object of type DocumentComposer. The selection is queried and set with the selection property. Selection change notifications are sent through a selectionNotifier property.

Given that a SuperEditor document should always have at least one user, and there's always a "primary" user, super_editor can retain the existing selection properties, as-is.

Additional selections can be added as a collection within the DocumentComposer:

class DocumentComposer {
  // ...existing implementation elided.

  DocumentSelection? getNonPrimarySelectionById(String id) {...}

  Set<NonPrimarySelection> getAllNonPrimarySelections() {...}

  void setNonPrimarySelection(NonPrimarySelection selection) {...}

  void addNonPrimarySelectionListener(NonPrimarySelectionListener listener) {...}

  void removeNonPrimarySelectionListener(NonPrimarySelectionListener listener) {...}
}

abstract class NonPrimarySelectionListener {
  void onSelectionAdded(NonPrimarySelection selection);

  void onSelectionChanged(NonPrimarySelection selection);

  void onSelectionRemoved(String id);
}

class NonPrimarySelection {
  final String id;
  final DocumentSelection selection;
}

The name NonPrimarySelection isn't great. I'm open to suggestions. But the above API should make it clear how one would add, change, and remove non-primary selections for any purpose. For multi-user selection, the ID for the non-primary selection could be the user's ID. If non-primary users can select multiple regions, then the ID could add a suffix, e.g., "user1234_1" and "user1234_2".

Display user names attached to carets

Superlist would like to display the name of each user next to that user's caret.

Additional user metadata could be attached to each NonPrimarySelection, but the diversity of use-cases for selection metadata is unbounded. Instead, super_editor should make any desired caret decoration possible.

Where should a caret be rendered?

Decorating a caret with a user name brings us to an existing issue in super_editor. Currently, super_editor asks each component in the document to render a caret (when using mouse input). This delegation makes it easy for the caret to look very different depending on the type of content. For example, an image might paint a caret very differently from a paragraph of text.

Painting the caret within each component created a problem for super_editor's mobile implementation. On mobile, the caret is visibly a document-wide control. On Android, for example, the caret includes a drag handle, which allows the user to drag that caret throughout the document. It's impractical to delegate caret drawing to individual components when the user can drag the caret across the document. For this reason, I filed:

• Change desktop/mouse caret to be global #404
• Add an anchor system to SuperEditor widget #424

Assuming that super_editor offered a generic overlay anchoring system, the users' carets could be displayed in that document-wide overlay. Each caret could connect to a LayerLink to allow any other content to layout near the caret. Or, that overlay system could make it easy for apps to draw custom carets, thereby allowing Superlist to paint their own carets with user names next to them.

Next steps

1. Do a sanity check on this write-up
2. Implement multiple selections in the DocumentComposer
3. Design and implement a document overlay for all global controls, like carets
4. Add any remaining APIs that are needed to display user names with the carets in the overlay

[matthew-carroll]

@roughike @miguelcmedeiros can you two take a look at this proposal and let me know if you have any suggestions?

[miguelcmedeiros]

@matthew-carroll

I would love to help you with a better name for NonPrimarySelection, but the only thing that comes to mind is ExtraSelection... 💩

The proposal for the change in DocumentComposer seems reasonable 👍

[roughike]

Seems just what we need, I have just a couple questions:

• Just wondering - what is the use case for NonPrimarySelectionListener? Is this how the non-primary selection would be rendered by super_editor users, or is it just for the overlay (=some user avatar/name/initials)?
• What is the proposed API for modifying an existing non-primary selection? Does setNonPrimarySelection multiple times with a NonPrimarySelection that matches an existing id work?

[matthew-carroll]

The NonPrimarySelectionListener is the mechanism by which things are notified when any non-primary selection changes. The existing selection API only notifies when the primary selection changes, so that wouldn't work for additional selections. And we want to notify listeners per-selection, so that it's easy to make surgical updates. The NonPrimarySelectionListener makes that possible. You can add more than one listener, in case multiple things care about the non-primary selections.

To change a non-primary selection, as you suggested, you would call setNonPrimarySelection with a NonPrimarySelection, which includes the ID of the selection, and the selection value. That call will either result in a new selection being added, an existing selection being changed, or a selection being removed (if the selection value is null).

Does that make sense?

[roughike]

Sounds good. Seems like the API does have everything we need.