Feat: support for dynamic placeholders

doc/placeholders_introduction.md

@@ -0,0 +1,77 @@
+# ✏️ Placeholders
+
+> A **placeholder** is visible text that serves as a guide or instruction for the user when a text field or editable area is empty.
+
+In **Flutter Quill**, there are three scenarios where **placeholders** can appear:
+
+- When the document is empty, a placeholder will appear at the beginning.
+- When a dynamic placeholder is configured, it can display custom guide text anywhere in the document.
+- When a cursor placeholder is set up, it appears whenever a line is completely empty.
+
+### 💡 How to Display a Placeholder When the Document is Empty
+
+To configure this, you need to use the `QuillEditorConfig` class:
+
+```dart
+final config = QuillEditorConfig(
+    placeholder: 'Start writing your notes...',
+);
+```
+
+### 🔎 What Are Dynamic Placeholders?
+
+**Dynamic placeholders** are not static or predetermined; they are **generated or adjusted automatically** based on the context of the content or the attributes applied to the text in the editor.
+
+These **placeholders** appear only when specific conditions are met, such as:
+
+- The block is empty.
+- No additional text attributes (e.g., styles or links) are applied.
+
+#### 🛠️ How to Create a Dynamic Placeholder
+
+Here's a simple example:
+
+If you want to display guide text only when a header is applied and the line with this attribute is empty, you can use the following code:
+
+```dart
+final config = QuillEditorConfig(
+    placeholderConfig: PlaceholderConfig(
+      builders: {
+        Attribute.header.key: (Attribute attr, TextStyle style) {
+          // In this case, we will only support header levels h1 to h3
+          final values = [30, 27, 22];
+          final level = attr.value as int?;
+          if (level == null) return null;
+          final fontSize = values[(level - 1 < 0 || level - 1 > 3 ? 0 : level - 1)];
+          return PlaceholderTextBuilder(
+              text: 'Header $level',
+              style: TextStyle(
+                  fontSize: fontSize.toDouble())
+              .merge(style.copyWith(
+                  color: Colors.grey)),
+         ); 
+      },
+   ),      
+);
+```
+
+### 🔎 What Are Cursor Placeholders?
+
+**Cursor placeholders** appear when a line is completely empty and has no attributes applied. These placeholders automatically appear at the same level as the cursor, though their position can be adjusted using the `offset` parameter in the `CursorPlaceholderConfig` class.
+
+Here's a simple implementation example:
+
+```dart
+final config = QuillEditorConfig(
+    cursorPlaceholderConfig: CursorPlaceholderConfig(
+        text: 'Write something...',
+        textStyle: TextStyle(
+            color: Colors.grey, 
+            fontStyle: FontStyle.italic,
+        ),
+        show: true,
+        offset: Offset(3.5, 2),
+    ),
+);
+```
+

lib/flutter_quill.dart

@@ -18,13 +18,15 @@ export 'src/document/style.dart';
 export 'src/editor/editor.dart';
 export 'src/editor/embed/embed_editor_builder.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_config.dart';
 export 'src/editor/raw_editor/quill_single_child_scroll_view.dart';
 export 'src/editor/raw_editor/raw_editor.dart';
 export 'src/editor/raw_editor/raw_editor_state.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/common/extensions/nodes_ext.dart

@@ -0,0 +1,10 @@
+import '../../document/nodes/node.dart';
+
+extension NodesCheckingExtension on Node {
+  bool isNodeInline() {
+    for (final attr in style.attributes.values) {
+      if (!attr.isInline) return false;
+    }
+    return true;
+  }
+}

lib/src/editor/config/editor_config.dart

@@ -8,9 +8,11 @@ import '../../document/nodes/node.dart';
 import '../../toolbar/theme/quill_dialog_theme.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/config/raw_editor_config.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';
@@ -25,6 +27,8 @@ class QuillEditorConfig {
   const QuillEditorConfig({
     this.scrollable = true,
     this.padding = EdgeInsets.zero,
+    @experimental this.placeholderConfig,
+    @experimental this.cursorPlaceholderConfig,
     @experimental this.characterShortcutEvents = const [],
     @experimental this.spaceShortcutEvents = const [],
     this.autoFocus = false,
@@ -135,6 +139,40 @@ class QuillEditorConfig {
   @experimental
   final List<SpaceShortcutEvent> spaceShortcutEvents;
 
+  /// Configuration for displaying placeholders in empty lines or near the cursor.
+  ///
+  /// ### Example
+  ///
+  /// To show a placeholder text specifically for header items:
+  ///
+  /// ```dart
+  /// final configuration = PlaceholderConfig(
+  ///   builders: <String, PlaceholderComponentBuilder>{
+  ///     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 < 0 || level - 1 > 3 ? 0 : level - 1)];
+  ///       return PlaceholderTextBuilder(
+  ///         text: 'Header $level',
+  ///         style: TextStyle(fontSize: fontSize.toDouble()).merge(style),
+  ///       );
+  ///     },
+  ///   },
+  ///   // If using custom attributes, register their keys here.
+  ///   customBlockAttributesKeys: null,
+  /// );
+  /// ```
+  @experimental
+  final PlaceholderConfig? placeholderConfig;
+
+  /// Configures how a placeholder is displayed relative to the cursor.
+  ///
+  /// This argument specifies the appearance, style, and position of a placeholder
+  /// shown at the cursor's location in an empty line.
+  @experimental
+  final CursorPlaceholderConfig? cursorPlaceholderConfig;
+
   /// A handler for keys that are pressed when the editor is focused.
   ///
   /// This feature is supported on **desktop devices only**.
@@ -501,14 +539,19 @@ class QuillEditorConfig {
     ContentInsertionConfiguration? contentInsertionConfiguration,
     GlobalKey<EditorState>? editorKey,
     TextSelectionThemeData? textSelectionThemeData,
+    PlaceholderConfig? placeholderConfig,
     bool? requestKeyboardFocusOnCheckListChanged,
+    CursorPlaceholderConfig? cursorPlaceholderConfig,
     TextInputAction? textInputAction,
     bool? enableScribble,
     void Function()? onScribbleActivated,
     EdgeInsets? scribbleAreaInsets,
     void Function(TextInputAction action)? onPerformAction,
   }) {
     return QuillEditorConfig(
+      cursorPlaceholderConfig:
+          cursorPlaceholderConfig ?? this.cursorPlaceholderConfig,
+      placeholderConfig: placeholderConfig ?? this.placeholderConfig,
       customLeadingBlockBuilder:
           customLeadingBlockBuilder ?? this.customLeadingBlockBuilder,
       placeholder: placeholder ?? this.placeholder,

lib/src/editor/editor.dart

@@ -16,6 +16,7 @@ import '../document/nodes/container.dart' as container_node;
 import '../document/nodes/leaf.dart';
 import 'config/editor_config.dart';
 import 'embed/embed_editor_builder.dart';
+import 'raw_editor/builders/placeholder/placeholder_builder.dart';
 import 'raw_editor/config/raw_editor_config.dart';
 import 'raw_editor/raw_editor.dart';
 import 'widgets/box.dart';
@@ -253,13 +254,17 @@ class QuillEditorState extends State<QuillEditor>
 
     final showSelectionToolbar = configurations.enableInteractiveSelection &&
         configurations.enableSelectionToolbar;
-
+    final placeholderBuilder = widget.config.placeholderConfig == null
+        ? null
+        : PlaceholderBuilder(configuration: widget.config.placeholderConfig!);
     final child = QuillRawEditor(
       key: _editorKey,
       controller: controller,
       config: QuillRawEditorConfig(
         characterShortcutEvents: widget.config.characterShortcutEvents,
         spaceShortcutEvents: widget.config.spaceShortcutEvents,
+        cursorPlaceholderConfig: widget.config.cursorPlaceholderConfig,
+        placeholderBuilder: placeholderBuilder,
         onKeyPressed: widget.config.onKeyPressed,
         customLeadingBuilder: widget.config.customLeadingBlockBuilder,
         focusNode: widget.focusNode,
@@ -1377,6 +1382,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.dart

@@ -0,0 +1,119 @@
+@internal
+library;
+
+import 'package:flutter/material.dart';
+import 'package:meta/meta.dart';
+import '../../../../document/attribute.dart' show Attribute, AttributeScope;
+import '../../../../document/nodes/line.dart';
+import 'placeholder_configuration.dart';
+
+// The black list of the keys that can not be used or permitted by the builder.
+final List<String> _blackList = List.unmodifiable(<String>[
+  Attribute.align.key,
+  Attribute.direction.key,
+  Attribute.lineHeight.key,
+  Attribute.indent.key,
+  ...Attribute.inlineKeys,
+  ...Attribute.ignoreKeys,
+]);
+
+/// A utility class for managing placeholder rendering logic in a document editor.
+///
+/// The `PlaceholderBuilder` is responsible for determining when a placeholder
+/// should be displayed in an empty node and for constructing the corresponding
+/// visual representation.
+///
+/// - [configuration]: An instance of [PlaceholderConfig] containing placeholder
+///   rendering rules and attribute customizations.
+@experimental
+@immutable
+class PlaceholderBuilder {
+  const PlaceholderBuilder({
+    required this.configuration,
+  });
+
+  final PlaceholderConfig configuration;
+
+  Map<String, PlaceholderComponentBuilder> get builders =>
+      configuration.builders;
+  Set<String>? get customBlockAttributesKeys =>
+      configuration.customBlockAttributesKeys;
+
+  /// Determines whether a given [Line] node should display a placeholder.
+  ///
+  /// This method checks if the node is empty and contains a block-level attribute
+  /// matching a builder key or custom attribute, excluding keys in the blacklist.
+  ///
+  /// Returns a tuple:
+  /// - [bool]: Whether a placeholder should be shown.
+  /// - [String]: The key of the matching attribute, if applicable.
+  @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);
+  }
+
+  /// Constructs a [WidgetSpan] for rendering a placeholder in an empty line.
+  ///
+  /// This method creates a visual representation of the placeholder based on
+  /// the block attribute and style configurations provided. Use [shouldShowPlaceholder]
+  /// before invoking this method to ensure the placeholder is needed.
+  @experimental
+  WidgetSpan? build({
+    required Attribute blockAttribute,
+    required TextStyle lineStyle,
+    required TextAlign align,
+    TextDirection? textDirection,
+    StrutStyle? strutStyle,
+    TextScaler? textScaler,
+  }) {
+    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.text.trim().isEmpty) {
+      return null;
+    }
+    final textWidget = Text(
+      configuration.text,
+      style: configuration.style,
+      textDirection: textDirection,
+      softWrap: true,
+      strutStyle: strutStyle,
+      textAlign: align,
+      textScaler: textScaler,
+      textWidthBasis: TextWidthBasis.longestLine,
+    );
+
+    // Use a [Row] with [Expanded] for placeholders in lines without explicit alignment.
+    // This ensures the placeholder spans the full width, avoiding unexpected alignment issues.
+    return WidgetSpan(
+      style: lineStyle,
+      child: align == TextAlign.end || align == TextAlign.center
+          ? textWidget
+          : Row(
+              children: [
+                Expanded(
+                  child: textWidget,
+                ),
+              ],
+            ),
+    );
+  }
+}

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

@@ -0,0 +1,56 @@
+import 'package:flutter/material.dart' show TextStyle;
+import 'package:meta/meta.dart' show experimental, immutable;
+import '../../../../document/attribute.dart';
+
+typedef PlaceholderComponentBuilder = PlaceholderTextBuilder? Function(
+    Attribute, TextStyle);
+
+/// Configuration class for defining how placeholders are handled in the editor.
+///
+/// The `PlaceholderConfig` allows customization of placeholder behavior by
+/// providing builders for rendering specific components and defining custom
+/// attribute keys that should be recognized during the placeholder build process.
+///
+/// - [builders]: A map associating placeholder keys with their respective
+///   component builders, allowing custom rendering logic.
+/// - [customBlockAttributesKeys]: A set of additional attribute keys to include
+///   in placeholder processing. By default, only predefined keys are considered.
+@experimental
+@immutable
+class PlaceholderConfig {
+  const PlaceholderConfig({
+    required this.builders,
+    this.customBlockAttributesKeys,
+  });
+
+  factory PlaceholderConfig.base() {
+    return const PlaceholderConfig(builders: {});
+  }
+
+  /// Add custom keys here to include them in placeholder builds, as external keys are ignored by default.
+  final Set<String>? customBlockAttributesKeys;
+  final Map<String, PlaceholderComponentBuilder> builders;
+
+  PlaceholderConfig copyWith({
+    Map<String, PlaceholderComponentBuilder>? builders,
+    Set<String>? customBlockAttributesKeys,
+  }) {
+    return PlaceholderConfig(
+      builders: builders ?? this.builders,
+      customBlockAttributesKeys:
+          customBlockAttributesKeys ?? this.customBlockAttributesKeys,
+    );
+  }
+}
+
+/// Represents the text that will be displayed
+@immutable
+class PlaceholderTextBuilder {
+  const PlaceholderTextBuilder({
+    required this.text,
+    required this.style,
+  });
+
+  final String text;
+  final TextStyle style;
+}