Generalize super_selectable_text to super_text

[matthew-carroll]

super_editor has a widget called SuperSelectableText, which renders text with a selection and a caret (but no gestures).

SuperSelectableText currently supports a single text selection and a single caret. This support needs to expand to include multiple selections and multiple carets.

This is a good time to consider the most appropriate way to further generalize SuperSelectableText.

Generalizing for multiple selections

My first thought about generalizing SuperSelectableText is to go from one constructor, to three constructors, as follows:

final standard = SuperSelectableText(
  text: myText,
  selection: mySelection,
  showCaret: true,
);

final multiSelect = SuperSelectableText.multiSelection(
  text: myText,
  selections: userSelections,
);

final custom = SuperSelectableText.custom(
  text: myText,
  backgroundBuilder: mySelectionBuilder,
  foregroundBuilder: myCaretBuilder,
);

The custom() constructor takes widget builders, which are also provided a TextLayout to paint and position content based on text layout:

Widget myCaretBuilder(BuildContext context, TextLayout textLayout) {
  return SomeTextOverlayWidget();
}

Including selection gestures

We recently extracted SuperSelectableText and TextLayout into a new package called super_selectable_text.

Developers might use this package directly, for non-document use-cases. For this reason, we should consider adding support for selection gestures within the super_selectable_text package.

We could provide gesture support in at least two ways. First, we could provide a widget that adds a GestureDetector:

GlobalKey _textId;
TextSelection _selection;

Widget build(context) {
  return GestureDetector(
    onPanStart: _onPanStart,
    onPanUpdate: _onPanUpdate,
    child: SuperSelectableText.plain(
      id: _textId,
      text: widget.text,
      selection: _selection,
      // ...
    ),
  );
}

A limitation of this approach is that the selection widget has to choose the specific type of SuperSelectableText (single selection vs multi-selection). We could resolve that limitation by taking in a builder that creates the desired SuperSelectableText, which gives the developer the choice about how to build a SuperSelectableText.

A second approach would be to use the foreground builder in SuperSelectableText to respond to gestures:

Widget build(context) {
  return SuperSelectableText.custom(
    text: widget.text,
    backgroundBuilder: _defaultBackgroundBuilder,
    foregroundBuilder: (context, textLayout) {
      return Stack(
        children: [
          _defaultForegroundBuilder,
          Positioned.fill(
            child: GestureDetector(
              onPanStart: _onPanStart,
              onPanUpdate: _onPanUpdate,
            ),
          ),
        ],
      );
    },
  );
}

Here, again, if the above build() method is placed within a widget in super_selectable_text, then this widget has to impose the configuration of the inner SuperSelectableText, which is constricting for app devs. On the other hand, we could offer developers just the GestureDetector that goes in the foregroundBuilder and then let app devs assemble, as desired.

New package name and widget name

Given that super_selectable_text includes an interface called TextLayout, I'm wondering if the package should instead be called super_text.

Additionally, if we add new widgets/APIs for selection gestures, is the SuperSelectableText widget still named correctly? The SuperSelectableText widget paints a selection and caret, but it doesn't include gesture support. The division between painting and gestures is a good thing, but the name might suggest to users that it includes gestures, when it doesn't. Is there a better name?

[matthew-carroll]

@miguelcmedeiros @venkatd @Jethro87 - can each of you take a look at this proposal and let me know what you think?

[venkatd]

@matthew-carroll I think super_text makes sense as a package name. In the future, other things related purely to text could live in this package.

Perhaps SuperTextField could be named something like SuperTextOverlay? Or is that too similar to the Overlay in the Flutter framework?

I would expect SuperSelectableText to be like SelectableText, but better. Like how SuperTextField is like TextField, but better.

So, if we rename it, we might want to re-introduce a SuperSelectableText that composes the gesture detection and the painting so it's got a batteries-included usage.

[miguelcmedeiros]

@matthew-carroll
I think it would be useful if this package provides a SuperSelectableText that allows multiple text styles, paints selection and caret and does gesture detection, like SelectableText from Flutter SDK does, but more powerful 🙂.

The widget that does not include gesture detection (handle by caller like in SuperEditor), but paints the selection and caret could be called something like RawSuperSelectableText.

We could consider that SuperSelectableText only supports single caret scenario while RawSuperSelectableText supports both single and multi caret scenarios.

This way the package can offer a high-level widget (SuperSelectableText) that serves most use-cases and a low-level widget (RawSuperSelectableText) that can be used by the few use-cases that are not supported by SuperSelectableText (like SuperEditor).