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]

I appreciate your contributions, but please consider creating issues before working on them because I'm not with the idea of adding this feature or any new similar features. The editor is just not stable.

It was much better before, and so far, we haven't addressed many regressions affecting production apps. Users have already started to migrate away from the project and use alternatives.

See #2445 issue as one of mant examples, they are also many major bugs that aren't being reported.

Adding new features that cause issues will require others to take responsibility for maintaining them. We don't have enough tests, and we have already discussed this many times.

I prefer stability, especially with the current state, even if the progress is slower. If we can't fix the current issues, then it's better not to make the project any less stable.

I will create one issue for such discussions because I don't want to repeat it everywhere.

@singerdmx
I will leave the decision to you as I don't have a very strong opinion about the close.

Adding features that we're not certain about, then fixing them later once users start reporting them comes at a high price.

[CatHood0]

@EchoEllet I didn't plan on adding this feature at the moment. I just wanted to verify that everything was in order and finish the changes. I have the same opinion on this point, I would prefer this feature to be merged after solving most of the bugs we have at the moment.

@singerdmx by now, i would prefer that this PR remain unmerged for now, and wait for a much more stable version without so many issues of the project.

[EchoEllet]

I would prefer this feature to be merged after solving most of the bugs we have at the moment.

There is no ETA for a more stable version. Last year, we discussed this, and it's seems everyone excited and has high expectations, but all that happens is that the magnifier was introduced with many major bugs and fixed yesterday after many months, which simply makes the experience similar or even less stable than before.

I would prefer this feature to be merged after solving most of the bugs we have at the moment.

Some users are using older versions and sticking to them due to such issues, and this is not the kind of developer and user experience I'm looking forward to.

And because of that, we're not certain if this PR will ever get merged, which is why I suggest creating issues for future PRs. I'm mainly concerned we end up closing many PRs that would discourage contributors with the time they have already spent.

[CatHood0]

I will close the PR as not only are we not in a position to add new features at the moment, but it will also likely be a long time before it is even merged into the stable branch.