Feat: support for dynamic placeholders

example/lib/main.dart

@@ -52,8 +52,7 @@ class _HomePageState extends State<HomePage> {
           }
           // Save the image somewhere and return the image URL that will be
           // stored in the Quill Delta JSON (the document).
-          final newFileName =
-              'image-file-${DateTime.now().toIso8601String()}.png';
+          final newFileName = 'image-file-${DateTime.now().toIso8601String()}.png';
           final newPath = path.join(
             io.Directory.systemTemp.path,
             newFileName,
@@ -86,9 +85,8 @@ class _HomePageState extends State<HomePage> {
             icon: const Icon(Icons.output),
             tooltip: 'Print Delta JSON to log',
             onPressed: () {
-              ScaffoldMessenger.of(context).showSnackBar(const SnackBar(
-                  content:
-                      Text('The JSON Delta has been printed to the console.')));
+              ScaffoldMessenger.of(context)
+                  .showSnackBar(const SnackBar(content: Text('The JSON Delta has been printed to the console.')));
               debugPrint(jsonEncode(_controller.document.toDelta().toJson()));
             },
           ),
@@ -127,11 +125,8 @@ class _HomePageState extends State<HomePage> {
                 buttonOptions: QuillSimpleToolbarButtonOptions(
                   base: QuillToolbarBaseButtonOptions(
                     afterButtonPressed: () {
-                      final isDesktop = {
-                        TargetPlatform.linux,
-                        TargetPlatform.windows,
-                        TargetPlatform.macOS
-                      }.contains(defaultTargetPlatform);
+                      final isDesktop = {TargetPlatform.linux, TargetPlatform.windows, TargetPlatform.macOS}
+                          .contains(defaultTargetPlatform);
                       if (isDesktop) {
                         _editorFocusNode.requestFocus();
                       }
@@ -147,6 +142,35 @@ class _HomePageState extends State<HomePage> {
                 controller: _controller,
                 config: QuillEditorConfig(
                   placeholder: 'Start writing your notes...',
+                  characterShortcutEvents: standardCharactersShortcutEvents,
+                  spaceShortcutEvents: standardSpaceShorcutEvents,
+                  cursorPlaceholderConfig: CursorPlaceholderConfig(
+                    text: 'Write something...',
+                    textStyle: TextStyle(color: Colors.grey, fontStyle: FontStyle.italic),
+                    show: true,
+                    offset: Offset(3.5, 2) 
+                  ),
+                  placeholderComponentsConfiguration: PlaceholderConfig(
+                    builders: {
+                      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(
+                          placeholderText: 'Header $level',
+                          style:
+                              TextStyle(fontSize: fontSize.toDouble()).merge(style.copyWith(color: Colors.grey)),
+                        );
+                      },
+                      Attribute.list.key: (Attribute attr, style) {
+                        return PlaceholderTextBuilder(
+                          placeholderText: 'List item',
+                          style: style.copyWith(color: Colors.grey),
+                        );
+                      },
+                    },
+                  ),
                   padding: const EdgeInsets.all(16),
                   embedBuilders: [
                     ...FlutterQuillEmbeds.editorBuilders(
@@ -193,8 +217,7 @@ class TimeStampEmbed extends Embeddable {
 
   static const String timeStampType = 'timeStamp';
 
-  static TimeStampEmbed fromDocument(Document document) =>
-      TimeStampEmbed(jsonEncode(document.toDelta().toJson()));
+  static TimeStampEmbed fromDocument(Document document) => TimeStampEmbed(jsonEncode(document.toDelta().toJson()));
 
   Document get document => Document.fromJson(jsonDecode(data));
 }

example/pubspec.lock

@@ -13,18 +13,18 @@ packages:
     dependency: transitive
     description:
       name: async
-      sha256: d2872f9c19731c2e5f10444b14686eb7cc85c76274bd6c16e1816bff9a3bab63
+      sha256: "947bfcf187f74dbc5e146c9eb9c0f10c9f8b30743e341481c1e2ed3ecc18c20c"
       url: "https://pub.dev"
     source: hosted
-    version: "2.12.0"
+    version: "2.11.0"
   boolean_selector:
     dependency: transitive
     description:
       name: boolean_selector
-      sha256: "8aab1771e1243a5063b8b0ff68042d67334e3feab9e95b9490f9a6ebf73b42ea"
+      sha256: "6cfb5af12253eaf2b368f07bacc5a80d1301a071c73360d746b7f2e32d762c66"
       url: "https://pub.dev"
     source: hosted
-    version: "2.1.2"
+    version: "2.1.1"
   characters:
     dependency: transitive
     description:
@@ -45,18 +45,18 @@ packages:
     dependency: transitive
     description:
       name: clock
-      sha256: fddb70d9b5277016c77a80201021d40a2247104d9f4aa7bab7157b7e3f05b84b
+      sha256: cb6d7f03e1de671e34607e909a7213e31d7752be4fb66a86d29fe1eb14bfb5cf
       url: "https://pub.dev"
     source: hosted
-    version: "1.1.2"
+    version: "1.1.1"
   collection:
     dependency: transitive
     description:
       name: collection
-      sha256: a1ace0a119f20aabc852d165077c036cd864315bd99b7eaa10a60100341941bf
+      sha256: ee67cb0715911d28db6bf4af1026078bd6f0128b07a5f66fb2ed94ec6783c09a
       url: "https://pub.dev"
     source: hosted
-    version: "1.19.0"
+    version: "1.18.0"
   cross_file:
     dependency: transitive
     description:
@@ -93,10 +93,10 @@ packages:
     dependency: transitive
     description:
       name: fake_async
-      sha256: "6a95e56b2449df2273fd8c45a662d6947ce1ebb7aafe80e550a3f68297f3cacc"
+      sha256: "511392330127add0b769b75a987850d136345d9227c6b94c96a04cf4a391bf78"
       url: "https://pub.dev"
     source: hosted
-    version: "1.3.2"
+    version: "1.3.1"
   ffi:
     dependency: transitive
     description:
@@ -286,10 +286,10 @@ packages:
     dependency: transitive
     description:
       name: http_parser
-      sha256: "76d306a1c3afb33fe82e2bbacad62a61f409b5634c915fceb0d799de1a913360"
+      sha256: "2aa08ce0341cc9b354a498388e30986515406668dbcc4f7c950c3e715496693b"
       url: "https://pub.dev"
     source: hosted
-    version: "4.1.1"
+    version: "4.0.2"
   image_picker:
     dependency: transitive
     description:
@@ -366,18 +366,18 @@ packages:
     dependency: transitive
     description:
       name: leak_tracker
-      sha256: c35baad643ba394b40aac41080300150a4f08fd0fd6a10378f8f7c6bc161acec
+      sha256: "3f87a60e8c63aecc975dda1ceedbc8f24de75f09e4856ea27daf8958f2f0ce05"
       url: "https://pub.dev"
     source: hosted
-    version: "10.0.8"
+    version: "10.0.5"
   leak_tracker_flutter_testing:
     dependency: transitive
     description:
       name: leak_tracker_flutter_testing
-      sha256: f8b613e7e6a13ec79cfdc0e97638fddb3ab848452eff057653abd3edba760573
+      sha256: "932549fb305594d82d7183ecd9fa93463e9914e1b67cacc34bc40906594a1806"
       url: "https://pub.dev"
     source: hosted
-    version: "3.0.9"
+    version: "3.0.5"
   leak_tracker_testing:
     dependency: transitive
     description:
@@ -390,10 +390,10 @@ packages:
     dependency: transitive
     description:
       name: lints
-      sha256: "4a16b3f03741e1252fda5de3ce712666d010ba2122f8e912c94f9f7b90e1a4c3"
+      sha256: "3315600f3fb3b135be672bf4a178c55f274bebe368325ae18462c89ac1e3b413"
       url: "https://pub.dev"
     source: hosted
-    version: "5.1.0"
+    version: "5.0.0"
   markdown:
     dependency: transitive
     description:
@@ -438,10 +438,10 @@ packages:
     dependency: "direct main"
     description:
       name: path
-      sha256: "75cca69d1490965be98c73ceaea117e8a04dd21217b37b292c9ddbec0d955bc5"
+      sha256: "087ce49c3f0dc39180befefc60fdb4acd8f8620e5682fe2476afd0b3688bb4af"
       url: "https://pub.dev"
     source: hosted
-    version: "1.9.1"
+    version: "1.9.0"
   photo_view:
     dependency: transitive
     description:
@@ -534,7 +534,7 @@ packages:
     dependency: transitive
     description: flutter
     source: sdk
-    version: "0.0.0"
+    version: "0.0.99"
   source_span:
     dependency: transitive
     description:
@@ -547,10 +547,10 @@ packages:
     dependency: transitive
     description:
       name: stack_trace
-      sha256: "9f47fd3630d76be3ab26f0ee06d213679aa425996925ff3feffdec504931c377"
+      sha256: "73713990125a6d93122541237550ee3352a2d84baad52d375a4cad2eb9b7ce0b"
       url: "https://pub.dev"
     source: hosted
-    version: "1.12.0"
+    version: "1.11.1"
   stream_channel:
     dependency: transitive
     description:
@@ -563,10 +563,10 @@ packages:
     dependency: transitive
     description:
       name: string_scanner
-      sha256: "0bd04f5bb74fcd6ff0606a888a30e917af9bd52820b178eaa464beb11dca84b6"
+      sha256: "556692adab6cfa87322a115640c11f13cb77b3f076ddcc5d6ae3c20242bedcde"
       url: "https://pub.dev"
     source: hosted
-    version: "1.4.0"
+    version: "1.2.0"
   term_glyph:
     dependency: transitive
     description:
@@ -579,10 +579,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: "664d3a9a64782fcdeb83ce9c6b39e78fd2971d4e37827b9b06c3aa1edc5e760c"
+      sha256: "5b8a98dafc4d5c4c9c72d8b31ab2b23fc13422348d2997120294d3bac86b4ddb"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.3"
+    version: "0.7.2"
   typed_data:
     dependency: transitive
     description:
@@ -723,10 +723,10 @@ packages:
     dependency: transitive
     description:
       name: vm_service
-      sha256: "0968250880a6c5fe7edc067ed0a13d4bae1577fe2771dcf3010d52c4a9d3ca14"
+      sha256: "5c5f338a667b4c644744b661f309fb8080bb94b18a7e91ef1dbd343bed00ed6d"
       url: "https://pub.dev"
     source: hosted
-    version: "14.3.1"
+    version: "14.2.5"
   web:
     dependency: transitive
     description:
@@ -744,5 +744,5 @@ packages:
     source: hosted
     version: "5.8.0"
 sdks:
-  dart: ">=3.6.0-0 <4.0.0"
+  dart: ">=3.5.0 <4.0.0"
   flutter: ">=3.24.0"

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/editor/config/editor_config.dart

@@ -9,9 +9,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';
@@ -26,6 +28,8 @@ class QuillEditorConfig {
   const QuillEditorConfig({
     this.scrollable = true,
     this.padding = EdgeInsets.zero,
+    this.placeholderComponentsConfiguration,
+    this.cursorPlaceholderConfig,
     @experimental this.characterShortcutEvents = const [],
     @experimental this.spaceShortcutEvents = const [],
     this.autoFocus = false,
@@ -137,6 +141,39 @@ class QuillEditorConfig {
   @experimental
   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 PlaceholderConfig? placeholderComponentsConfiguration;
+
+  /// This argument configure how will be showed the placeholder at right or left of the cursor
+  final CursorPlaceholderConfig? cursorPlaceholderConfig;
+
   /// A handler for keys that are pressed when the editor is focused.
   ///
   /// This feature is supported on **desktop devices only**.
@@ -505,7 +542,9 @@ class QuillEditorConfig {
     ContentInsertionConfiguration? contentInsertionConfiguration,
     GlobalKey<EditorState>? editorKey,
     TextSelectionThemeData? textSelectionThemeData,
+    PlaceholderConfig? placeholderComponentsConfiguration,
     bool? requestKeyboardFocusOnCheckListChanged,
+    CursorPlaceholderConfig? cursorPlaceholderConfig,
     TextMagnifierConfiguration? magnifierConfiguration,
     TextInputAction? textInputAction,
     bool? enableScribble,
@@ -514,6 +553,11 @@ class QuillEditorConfig {
     void Function(TextInputAction action)? onPerformAction,
   }) {
     return QuillEditorConfig(
+      cursorPlaceholderConfig:
+          cursorPlaceholderConfig ??
+              this.cursorPlaceholderConfig,
+      placeholderComponentsConfiguration: placeholderComponentsConfiguration ??
+          this.placeholderComponentsConfiguration,
       customLeadingBlockBuilder:
           customLeadingBlockBuilder ?? this.customLeadingBlockBuilder,
       placeholder: placeholder ?? this.placeholder,