Feat: support for dynamic placeholders

[CatHood0]

Description

Added placeholderConfig parameter to allow us to build placeholders dynamically depending on what attribute we want and cursorPlaceholderConfig that allows to the devs add a placeholder at the right (if we are using a LTR language) of the cursor (only when the paragraph and it does not contains any block attribute or selection)

For example, if we only want to display placeholders for Headers and Lists, then we would set it up like this:

configurations: QuillEditorConfigurations(
  // We can use this instance to avoid use this functionality:
  // CursorPlaceholderConfig.noPlaceholder()
  // Or, if we want to add our custom settings, we can configure manually
  // CursorPlaceholderConfig(text: "our_text'', textStyle: TextStyle(), show: true, offset: Offset(0, 2));
  // At this example case, we use this instance (just for showcases)
  cursorPlaceholderConfig: CursorPlaceholderConfig.basic(), 
  placeholderConfig:
    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 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),
            );
          },
      },
   ),
),

Preview

Web

test_web_placeholders.mp4

Desktop

desktop_placeholders.mp4

Android

fixed_text_scale.mp4

Related Issues

N/A

• ✨ New feature: Adds new functionality without breaking existing features.
• 🛠️ Bug fix: Resolves an issue without altering current behavior.
• 🧹 Code refactor: Code restructuring that does not affect behavior.
• ❌ Breaking change: Alters existing functionality and requires updates.
• 🧪 Tests: Adds new tests or modifies existing tests.
• 📝 Documentation: Updates or additions to documentation.
• 🗑️ Chore: Routine tasks, or maintenance.
• ✅ Build configuration change: Changes to build or deploy processes.

TODO

• We must also make a cursor placeholder that appears at the same offset of the caret on any empty line (if the line has not block or embed attributes)
• We must make possible add custom block attributes keys (we need to add some validations because we don't want to add any non block attribute)
• Make this feature completely optional.
• We need to add support for web
• Rename classes related to placeholders (only those added by this PR).
• Fix placeholder position on mobile devices.
• Provide a way to calculate correctly the offset of the placeholder (only for cursor)
• Test it on all platforms (this is an issue by itself because i don't have IOS or Mac devices)
• Test if the feature could cause any issue if we have a line with several block attributes applied
• Test cursor placeholder
• Add documentation about this feature.

[EchoEllet]

Thank you for working on this.

Please refer to Flutter Documentation style. Most of the old / original / legacy codebase, most packages and projects follow this style.

Documentation is important, I prefer if feature X doesn't exist if it could have poor documentation, and it's one of the main reasons we don't understand most of the codebase. I haven't done it in a good way previously but the goal is to improve the new changes.

[EchoEllet]

This is not formatted properly, formatting is important for consistent codebase docs, and handling conflicts, not necessarily for the final output.

The general idea is to follow the Dart and Flutter style for writing docs. The lints and checks will be updated later.

[EchoEllet]

Please follow the Flutter/Dart style for writing docs (see example doc comment).

Try to remove the redundancy, keeping it as short as possible without details loss (not necessarily short), avoid let us, assume that you want to ..., we, you, and our in docs.

While our current doc comments are not qualified enough, I would like to improve, not add more things to improve on the list. I will update this soon, currently, I'm fixing #2394 and other related issues in flutter_quill_extensions (broken behavior on desktop and web platforms), once I'm done, I will handle all of the nits soon.

[CatHood0]

I haven't focused on improving the documentation yet. As you said before, I will follow the documentation style you mentioned, however, my priority at the moment is to check that all the functionality is working as it should. Once I can see that everything is working correctly, I will take the time to create more documentation (not only adding doc comments but also adding files for the official documentation of the package)

[EchoEllet]

Responding to a comment: Let's keep it for now, this is a separate issue and there is already much to do on our list.

[EchoEllet]

Dots are not used in most of the doc comments.