[SuperEditor] Expand usability of HintComponentBuilder. (Resolves #2655)

[angelosilvestre]

[SuperEditor] Expand usability of HintComponentBuilder. (Resolves #2655)

This PR modifies the HintComponentBuilder to make it possible to use it in the demo_text_with_hint.dart demo.

The basic and attributed named constructors were introduced. I used only two constructors with optional properties because, if we declare a separate constructor for each combination of parameters, there will be a lot of constructors.

I had to modify the HintComponentBuilder existing constructor to remove the const keyword, so this is a breaking change. The fix is as simple as removing the const keyword at the constructor's calls.

The demo was modified to use the HintComponentBuilder. I used a bottom navigation bar to make it possible to use the demo on mobile.

I simplified the existing logic to decide whether the hint should be displayed to document.length == 1, because the node's index cannot be bigger than zero if there is a single node in the document, so that check was irrelevant.

All places that were using the existing constructor were updated.

Screen.Recording.2025-11-10.at.15.40.57.mov

[matthew-carroll]

@angelosilvestre what do you think about naming the constructors richText() and plainText() to somewhat match other named constructors that we have?

One case that we probably want to support is where a title has a value at the top of a document, but the first paragraph below it still shows a hint. I think this happens, for example, with Notion documents. Is that possible with your changes?

[angelosilvestre]

@matthew-carroll

@angelosilvestre what do you think about naming the constructors richText() and plainText() to somewhat match other named constructors that we have?

Sounds reasonable, updated.

One case that we probably want to support is where a title has a value at the top of a document, but the first paragraph below it still shows a hint. I think this happens, for example, with Notion documents. Is that possible with your changes?

Yes, it can be achieved with the following code:

HintComponentBuilder.richText(
  AttributedText(
    'Content goes here...',
    AttributedSpans(
      attributions: [
        const SpanMarker(attribution: italicsAttribution, offset: 13, markerType: SpanMarkerType.start),
        const SpanMarker(attribution: italicsAttribution, offset: 16, markerType: SpanMarkerType.end),
      ],
    ),
  ),
  hintStyleBuilder: (context, attributions) => _textStyleBuilder(attributions).copyWith(
    color: const Color(0xFFDDDDDD),
  ),
  shouldShowHint: (document, node) =>
      // Show the hint only if the first node is a header and the second node is an empty paragraph.
      document.getNodeAt(0)!.getMetadataValue(NodeMetadata.blockType) == header1Attribution &&
      document.getNodeIndexById(node.id) == 1 &&
      node.getMetadataValue(NodeMetadata.blockType) == paragraphAttribution &&
      node.text.isEmpty,
),

Screen.Recording.2025-12-08.at.14.37.02.mov