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,133 @@
+// This file is only for internal use
+import 'package:flutter/material.dart'
+ show
+ Align,
+ Alignment,
+ CrossAxisAlignment,
+ Expanded,
+ MainAxisAlignment,
+ PlaceholderAlignment,
+ Row,
+ StrutStyle,
+ Text,
+ TextAlign,
+ TextBaseline,
+ 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
+@internal
+@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
+ @internal
+ (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
+ @internal
+ WidgetSpan? build({
+ required Attribute blockAttribute,
+ required TextStyle lineStyle,
+ required TextDirection textDirection,
+ required TextAlign align,
+ StrutStyle? strutStyle,
+ }) {
+ 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 [Row] widget with [Expanded] 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 the line to the center (example), row 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.end || align == TextAlign.center
+ ? textWidget
+ : Row(
+ children: [
+ Expanded(
+ 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;