Feat: support for dynamic placeholders

example/lib/screens/quill/quill_screen.dart

@@ -124,6 +124,32 @@ class _QuillScreenState extends State<QuillScreen> {
                 child: MyQuillEditor(
                   controller: _controller,
                   configurations: QuillEditorConfigurations(
+                    cursorParagrahPlaceholderConfiguration:
+                        CursorParagrahPlaceholderConfiguration
+                            .withPlaceholder(),
+                    placeholderComponentsConfiguration:
+                        PlaceholderComponentsConfiguration(
+                      builders: {
+                        Attribute.header.key: (Attribute attr, style) {
+                          final values = [32, 30, 24, 22, 18, 16];
+                          final level = attr.value as int?;
+                          if (level == null) return null;
+                          final fontSize =
+                              values[(level - 1 <= 0 ? 0 : level - 1)];
+                          return PlaceholderArguments(
+                            placeholderText: 'Header $level',
+                            style: TextStyle(fontSize: fontSize.toDouble())
+                                .merge(style.copyWith(color: Colors.grey)),
+                          );
+                        },
+                        Attribute.list.key: (Attribute attr, style) {
+                          return PlaceholderArguments(
+                            placeholderText: 'List item',
+                            style: style.copyWith(color: Colors.grey),
+                          );
+                        },
+                      },
+                    ),
                     characterShortcutEvents: standardCharactersShortcutEvents,
                     spaceShortcutEvents: standardSpaceShorcutEvents,
                     searchConfigurations: const QuillSearchConfigurations(

lib/flutter_quill.dart

@@ -21,6 +21,7 @@ export 'src/editor/editor.dart';
 export 'src/editor/embed/embed_editor_builder.dart';
 export 'src/editor/provider.dart';
 export 'src/editor/raw_editor/builders/leading_block_builder.dart';
+export 'src/editor/raw_editor/builders/placeholder/placeholder_configuration.dart';
 export 'src/editor/raw_editor/config/events/events.dart';
 export 'src/editor/raw_editor/config/raw_editor_configurations.dart';
 export 'src/editor/raw_editor/quill_single_child_scroll_view.dart';
@@ -30,6 +31,7 @@ export 'src/editor/spellchecker/spellchecker_service.dart';
 export 'src/editor/spellchecker/spellchecker_service_provider.dart';
 export 'src/editor/style_widgets/style_widgets.dart';
 export 'src/editor/widgets/cursor.dart';
+export 'src/editor/widgets/cursor_configuration/cursor_configuration.dart';
 export 'src/editor/widgets/default_styles.dart';
 export 'src/editor/widgets/link.dart';
 export 'src/editor/widgets/text/utils/text_block_utils.dart';

lib/src/editor/config/editor_configurations.dart

@@ -12,8 +12,10 @@ import '../../toolbar/theme/quill_dialog_theme.dart';
 import '../editor_builder.dart';
 import '../embed/embed_editor_builder.dart';
 import '../raw_editor/builders/leading_block_builder.dart';
+import '../raw_editor/builders/placeholder/placeholder_configuration.dart';
 import '../raw_editor/config/events/events.dart';
 import '../raw_editor/raw_editor.dart';
+import '../widgets/cursor_configuration/cursor_configuration.dart';
 import '../widgets/default_styles.dart';
 import '../widgets/delegate.dart';
 import '../widgets/link.dart';
@@ -36,6 +38,8 @@ class QuillEditorConfigurations extends Equatable {
     this.padding = EdgeInsets.zero,
     this.characterShortcutEvents = const [],
     this.spaceShortcutEvents = const [],
+    this.placeholderComponentsConfiguration,
+    this.cursorParagrahPlaceholderConfiguration,
     this.autoFocus = false,
     this.expands = false,
     this.placeholder,
@@ -153,6 +157,40 @@ class QuillEditorConfigurations extends Equatable {
   ///```
   final List<SpaceShortcutEvent> spaceShortcutEvents;
 
+  /// Whether the line is empty, this let us add a placeholder
+  ///
+  /// _Note: these placeholders are limited only to lines with block styles_
+  ///
+  /// ### Example
+  ///
+  /// Assume that you want to show only a placeholder text for the header items,
+  /// so, we only need to configure `placeholderComponentsConfiguration` like:
+  ///
+  ///```dart
+  ///final configuration = PlaceholderComponentsConfiguration(
+  ///  builders: <String, PlaceholderConfigurationBuilder>{
+  ///   Attribute.header.key: (Attribute attr, style) {
+  ///     final values = [30, 27, 22];
+  ///     final level = attr.value as int?;
+  ///     if (level == null) return null;
+  ///       final fontSize = values[level - 1];
+  ///       return PlaceholderArguments(
+  ///         placeholderText: 'Header $level',
+  ///         style: TextStyle(fontSize: fontSize.toDouble()).merge(style),
+  ///       );
+  ///   },
+  /// },
+  /// // if you use custom attribute keys into the `builders` param, them you will need to implement that
+  /// // here too
+  /// customBlockAttributesKeys: null,
+  ///),
+  ///```
+  final PlaceholderComponentsConfiguration? placeholderComponentsConfiguration;
+
+  /// This argument configure how will be showed the placeholder at right or left of the cursor
+  final CursorParagrahPlaceholderConfiguration?
+      cursorParagrahPlaceholderConfiguration;
+
   /// Whether the text can be changed.
   ///
   /// When this is set to `true`, the text cannot be modified
@@ -519,9 +557,12 @@ class QuillEditorConfigurations extends Equatable {
     GlobalKey<EditorState>? editorKey,
     TextSelectionThemeData? textSelectionThemeData,
     LeadingBlockNodeBuilder? customLeadingBlockBuilder,
+    PlaceholderComponentsConfiguration? placeholderComponentsConfiguration,
     bool? requestKeyboardFocusOnCheckListChanged,
     QuillEditorElementOptions? elementOptions,
     QuillEditorBuilder? builder,
+    CursorParagrahPlaceholderConfiguration?
+        cursorParagrahPlaceholderConfiguration,
     TextMagnifierConfiguration? magnifierConfiguration,
     TextInputAction? textInputAction,
     bool? enableScribble,
@@ -531,6 +572,11 @@ class QuillEditorConfigurations extends Equatable {
   }) {
     return QuillEditorConfigurations(
       sharedConfigurations: sharedConfigurations ?? this.sharedConfigurations,
+      cursorParagrahPlaceholderConfiguration:
+          cursorParagrahPlaceholderConfiguration ??
+              this.cursorParagrahPlaceholderConfiguration,
+      placeholderComponentsConfiguration: placeholderComponentsConfiguration ??
+          this.placeholderComponentsConfiguration,
       customLeadingBlockBuilder:
           customLeadingBlockBuilder ?? this.customLeadingBlockBuilder,
       // ignore: deprecated_member_use_from_same_package

lib/src/editor/editor.dart

@@ -26,6 +26,7 @@ import 'config/editor_configurations.dart';
 import 'editor_builder.dart';
 import 'embed/embed_editor_builder.dart';
 import 'provider.dart';
+import 'raw_editor/builders/placeholder/placeholder_builder_internal.dart';
 import 'raw_editor/config/raw_editor_configurations.dart';
 import 'raw_editor/raw_editor.dart';
 import 'widgets/box.dart';
@@ -286,6 +287,13 @@ class QuillEditorState extends State<QuillEditor>
     final showSelectionToolbar = configurations.enableInteractiveSelection &&
         configurations.enableSelectionToolbar;
 
+    final placeholderBuilder =
+        widget.configurations.placeholderComponentsConfiguration == null
+            ? null
+            : PlaceholderBuilder(
+                configuration:
+                    widget.configurations.placeholderComponentsConfiguration!);
+
     final child = FlutterQuillLocalizationsWidget(
       child: QuillEditorProvider(
         controller: controller,
@@ -295,6 +303,9 @@ class QuillEditorState extends State<QuillEditor>
             key: _editorKey,
             controller: controller,
             configurations: QuillRawEditorConfigurations(
+              cursorParagrahPlaceholderConfiguration:
+                  widget.configurations.cursorParagrahPlaceholderConfiguration,
+              placeholderBuilder: placeholderBuilder,
               characterShortcutEvents:
                   widget.configurations.characterShortcutEvents,
               spaceShortcutEvents: widget.configurations.spaceShortcutEvents,
@@ -1447,6 +1458,7 @@ class RenderEditor extends RenderEditableContainerBox
           child.getCaretPrototype(child.globalToLocalPosition(textPosition));
       _floatingCursorRect =
           sizeAdjustment.inflateRect(caretPrototype).shift(boundedOffset);
+
       _cursorController
           .setFloatingCursorTextPosition(_floatingCursorTextPosition);
     } else {

lib/src/editor/raw_editor/builders/placeholder/placeholder_builder_internal.dart

@@ -0,0 +1,121 @@
+// This file is only for internal use
+import 'package:flutter/material.dart'
+    show
+        Align,
+        Alignment,
+        StrutStyle,
+        Text,
+        TextAlign,
+        TextDirection,
+        TextStyle,
+        TextWidthBasis,
+        WidgetSpan,
+        immutable;
+import 'package:meta/meta.dart';
+import '../../../../document/attribute.dart' show Attribute, AttributeScope;
+import '../../../../document/nodes/line.dart';
+import 'placeholder_configuration.dart';
+
+/// This is the black list of the keys that cannot be
+/// used or permitted by the builder
+// ignore: unnecessary_late
+late final List<String> _blackList = List.unmodifiable(<String>[
+  Attribute.align.key,
+  Attribute.direction.key,
+  Attribute.lineHeight.key,
+  Attribute.indent.key,
+  ...Attribute.inlineKeys,
+  ...Attribute.ignoreKeys,
+]);
+
+@experimental
+@immutable
+class PlaceholderBuilder {
+  const PlaceholderBuilder({
+    required this.configuration,
+  });
+
+  final PlaceholderComponentsConfiguration configuration;
+
+  Map<String, PlaceholderConfigurationBuilder> get builders =>
+      configuration.builders;
+  Set<String>? get customBlockAttributesKeys =>
+      configuration.customBlockAttributesKeys;
+
+  /// Check if this node need to show a placeholder
+  @experimental
+  (bool, String) shouldShowPlaceholder(Line node) {
+    if (builders.isEmpty) return (false, '');
+    var shouldShow = false;
+    var key = '';
+    for (final exclusiveKey in <dynamic>{
+      ...Attribute.exclusiveBlockKeys,
+      ...?customBlockAttributesKeys
+    }) {
+      if (node.style.containsKey(exclusiveKey) &&
+          node.style.attributes[exclusiveKey]?.scope == AttributeScope.block &&
+          !_blackList.contains(exclusiveKey)) {
+        shouldShow = true;
+        key = exclusiveKey;
+        break;
+      }
+    }
+    // we return if should show placeholders and the key of the attr that matches to get it directly
+    // avoiding an unnecessary traverse into the attributes of the node
+    return (node.isEmpty && shouldShow, key);
+  }
+
+  /// Build is similar to build method from any widget but
+  /// this only has the responsability of create a WidgetSpan to be showed
+  /// by the line when the node is empty
+  ///
+  /// Before use this, we should always use [shouldShowPlaceholder] to avoid
+  /// show any placeholder where is not needed
+  @experimental
+  WidgetSpan? build({
+    required Attribute blockAttribute,
+    required TextStyle lineStyle,
+    required TextDirection textDirection,
+    required StrutStyle strutStyle,
+    required TextAlign align,
+  }) {
+    if (builders.isEmpty) return null;
+    final configuration =
+        builders[blockAttribute.key]?.call(blockAttribute, lineStyle);
+    // we don't need to add a placeholder that is null or contains a empty text
+    if (configuration == null || configuration.placeholderText.trim().isEmpty) {
+      return null;
+    }
+    final textWidget = Text(
+      configuration.placeholderText,
+      style: configuration.style,
+      textDirection: textDirection,
+      softWrap: true,
+      strutStyle: strutStyle,
+      textAlign: align,
+      textWidthBasis: TextWidthBasis.longestLine,
+    );
+    // we use [Align] widget to take whole the available width
+    // when the line has not defined an alignment.
+    //
+    // this behavior is different when the align is left or justify, because
+    // if we align to the center (example) the line, align as we say, will take the whole
+    // width, creating a visual unexpected behavior where the caret being putted
+    // at the offset 0 (you can think this like the caret appears at the first char
+    // of the line when it is aligned at the left side instead appears at the middle
+    // if the line is centered)
+    //
+    // # !Note:
+    // this code is subject to changes because we need to get a better solution
+    // to this implementation
+    return WidgetSpan(
+      style: lineStyle,
+      child: align != TextAlign.left && align != TextAlign.justify
+          ? textWidget
+          : Align(
+              alignment: Alignment.centerLeft,
+              child: textWidget,
+            ),
+    );
+  }
+}

lib/src/editor/raw_editor/builders/placeholder/placeholder_configuration.dart

@@ -0,0 +1,47 @@
+import 'package:flutter/material.dart' show TextStyle, immutable;
+import '../../../../document/attribute.dart';
+
+typedef PlaceholderConfigurationBuilder = PlaceholderArguments? Function(
+    Attribute, TextStyle);
+
+@immutable
+class PlaceholderComponentsConfiguration {
+  const PlaceholderComponentsConfiguration({
+    required this.builders,
+    this.customBlockAttributesKeys,
+  });
+
+  factory PlaceholderComponentsConfiguration.base() {
+    return const PlaceholderComponentsConfiguration(builders: {});
+  }
+
+  /// These attributes are used with the default ones
+  /// to let us add placeholder to custom block attributes
+  final Set<String>? customBlockAttributesKeys;
+  final Map<String, PlaceholderConfigurationBuilder> builders;
+
+  PlaceholderComponentsConfiguration copyWith({
+    Map<String, PlaceholderConfigurationBuilder>? builders,
+    Set<String>? customBlockAttributesKeys,
+  }) {
+    return PlaceholderComponentsConfiguration(
+      builders: builders ?? this.builders,
+      customBlockAttributesKeys:
+          customBlockAttributesKeys ?? this.customBlockAttributesKeys,
+    );
+  }
+}
+
+@immutable
+
+/// Represents the arguments that builds the text that will
+/// be displayed
+class PlaceholderArguments {
+  const PlaceholderArguments({
+    required this.placeholderText,
+    required this.style,
+  });
+
+  final String placeholderText;
+  final TextStyle style;
+}

lib/src/editor/raw_editor/config/raw_editor_configurations.dart

@@ -36,7 +36,9 @@ import '../../../editor/widgets/default_styles.dart';
 import '../../../editor/widgets/delegate.dart';
 import '../../../editor/widgets/link.dart';
 import '../../../toolbar/theme/quill_dialog_theme.dart';
+import '../../widgets/cursor_configuration/cursor_configuration.dart';
 import '../builders/leading_block_builder.dart';
+import '../builders/placeholder/placeholder_builder_internal.dart';
 import 'events/events.dart';
 
 @immutable
@@ -52,6 +54,8 @@ class QuillRawEditorConfigurations extends Equatable {
     required this.autoFocus,
     required this.characterShortcutEvents,
     required this.spaceShortcutEvents,
+    this.placeholderBuilder,
+    this.cursorParagrahPlaceholderConfiguration,
     @Deprecated(
         'controller should be passed directly to the editor - this parameter will be removed in future versions.')
     this.controller,
@@ -137,6 +141,10 @@ class QuillRawEditorConfigurations extends Equatable {
   ///```
   final List<CharacterShortcutEvent> characterShortcutEvents;
 
+  /// Contains all necessary logic to build the placeholder
+  /// given for the devs
+  final PlaceholderBuilder? placeholderBuilder;
+
   /// Contains all the events that will be handled when
   /// space key is pressed
   ///
@@ -159,6 +167,10 @@ class QuillRawEditorConfigurations extends Equatable {
   ///```
   final List<SpaceShortcutEvent> spaceShortcutEvents;
 
+  /// This argument configure how will be showed the placeholder at right or left of the cursor
+  final CursorParagrahPlaceholderConfiguration?
+      cursorParagrahPlaceholderConfiguration;
+
   /// Additional space around the editor contents.
   final EdgeInsetsGeometry padding;