Sys - Maintainable Architecture

[adrian-moisa]

It will be a while until visual editor is all packed up and ready to serve duty. At best at least 1 month until we get testing and docs such that we can provide a better service. (I mean it's currently usable as it is a direct clone of Flutter Quill). I've been already going trough the steps to setup the repo. There's a lot to review. Today I started work on the cleanup effort. There's a lot to unpack here. My first goal, not have files with over 300 LOC. And to split in modules. Plus rename / document where necessary to make it easy to follow the code flow.

Join on discord to get advice and help or follow us on YouTube Visual Coding to learn more about the architecture of Visual Editor and other Flutter apps.

[adrian-moisa]

Making good progress on the refactoring

just a small hint how bad it is/was...
the entry file had 2000 LOC and 8 freaking classes....
editor.dart is now spread in several files. I'll have more work to do in order to properly document them.

[adrian-moisa]

I've completed the task of splitting everything into modules. Here's a breakdown of the numbers so far.

before

after

new modules

[apalala-dev]

Great work already 💪

I have a few other things in mind that might improve the usage of this package as well.

Tuple package dependency

Atm, there is a dependency to the tuple package which I think should be either removed or should be exposed so visual-editor users won't have to import the tuple package as well.
I add to import the package manually to edit the lineSpacing for instance:

quill.VisualEditor(
                customStyles: quill.DefaultStyles(
                    paragraph: quill.DefaultTextBlockStyle(
                  Theme.of(context).textTheme.bodyText2!,
                  const Tuple2(8, 0),
                  const Tuple2(0, 0),
                  null,
                )),
// ....
)

This seems to have been used a lot in the package.
However, having a Tuple instead of a concrete class makes the implementation quite obscure. Here for instance, I don't see why the lineSpacing is not a simple double instead of a Tuple.

Name conflicts

Some names in the package are very generic and might insert name conflicts when using VisualEditor.
For instance, there is the Text class which extends Leaf. There is already a very common Text class in Flutter which might make people have conflicts.

It is more a problem for new users since one just needs to use an alias for the import as a workaround, but I guess a TextLeaf would have been easier.

[adrian-moisa]

@apalala-dev Fully agree with both comments. You are very right to say that Tuple obscures meaning. I'll add this to my refactorings list. As for the Text name conflict I'm already aware and working to get rid of it. I've encountered it myself many times. High prio. Once again. Thank you for the thorough feedback! It's much appreciated.

[adrian-moisa]

The RawEditor is getting in a far better shape. As you can see, everything is now split in nicely named services. This will pay big dividends in the long run.

[adrian-moisa]

Major Milestone - Editor and RawEditor classes are finally merged in one single widget 🥳

After several weeks of refactoring I've finally been able to puzzle together the role of each layer in the hierarchy of Quill. Eventually I figured out that there is no fundamental distinction between QuillEditor (aka VisualEditor) and RawEditor. For a very long time I was deeply confused what is the meaning of Editor vs RawEditor. This was one of the most confusing parts of the codebase. Now no longer, they are fused in one single widget and the build() method is now crystal clear as you can see bellow.

Still a lot more work ahead. However this marks a major point in the refactoring process. We are over the (complexity) hill. From here on it should be a lot easier to continue the refactoring effort. Also a lot easier to provide documentation since now, it makes a lot more sense. I'm also very happy to report that we don't have too many regressions so far out of this refactoring. I did my best to constantly check that we are retaining all features.

By now I have content and scripts for 6 episodes (and 40 more planned ahead). I will start allocating time for the voice overs to start releasing them.

[adrian-moisa]

I've reached a point where I consider the main project structure clean enough to be easily maintainable (at least by myself). I still have a lot of work to do in documentation and testing department, but this will come in time as I work on other features. From here on I continue work on the code base in a need to have order. Further code improvements will be done as part of ongoing features tickets or bugs. So this one will be closed.

The current state of the editor is unstable. It has a few new issues stemming from the refactoring effort. So until it's not clean enough I don't plan to release it on pub.dev. Until then it can be imported straight from github.

visual_editor:
  git: https://github.com/visual-space/visual-editor.git

By now I've collected materials for the first 6 episodes. I'll be working in the background to get them edited and uploaded on our YT channel.