Refactor the project structure without breaking changes

[EchoEllet]

Discussed in #2016

^{Originally posted by EchoEllet July 15, 2024}
When the project first started out, it was simpler and had fewer features, so the project structure was suitable.

Our current project structure is optimized for smaller-scale projects and lacks the scalability required for our current use case.

$ tree -d ./lib
./lib
└── src
    ├── extensions
    ├── l10n
    │   ├── extensions
    │   ├── generated
    │   └── widgets
    ├── models
    │   ├── config
    │   │   ├── editor
    │   │   │   └── elements
    │   │   │       └── list
    │   │   ├── others
    │   │   ├── raw_editor
    │   │   └── toolbar
    │   │       └── buttons
    │   ├── documents
    │   │   └── nodes
    │   ├── rules
    │   ├── structs
    │   └── themes
    ├── packages
    │   └── quill_markdown
    ├── services
    │   └── clipboard
    ├── utils
    │   └── web_package
    └── widgets
        ├── editor
        ├── others
        ├── quill
        ├── raw_editor
        ├── style_widgets
        ├── toolbar
        │   ├── base_button
        │   └── buttons
        │       ├── alignment
        │       ├── color
        │       ├── hearder_style
        │       └── search
        │           └── legacy
        └── utils

Let us start with the flutter_quill package since most of the code is there.

I can think of different ways to solve this and make it more scalable, for now, we will focus on consistently moving the files and directories, rather than splitting and changing the naming of classes and files.

This change doesn't require any breaking changes as long as the developer doesn't import directly from the src, the IDE by default doesn't import anything from the src directory, and the analysis will give a warning too.

As long as the developer imports only the public APIs from flutter_quill:

import 'package:flutter_quill/flutter_quill.dart';

It should not be a breaking change if they use the same version for flutter_quill and flutter_quill_extensions since the extensions package import API that's not exposed publicly.

The first structure I can think of is:

common // For the shared code for all directories/modules
controller // For QuillController and related functionalities
editor // QuillEditor, QuillRawEditor, and related classes and files
toolbar // The QuillToolbar and QuillSimpleToolbar
editor_toolbar_shared // Anything that's shared between the toolbar and the editor outside of the controller and other modules
styles // For everything related to styling (e.g., QuillEditorBulletPoint, QuillEditorCheckboxPoint, QuillEditorNumberPoint, QuillStyles, Style, etc...)
attributes // Example: https://github.com/singerdmx/flutter-quill/blob/master/lib/src/models/documents/attribute.dart
rules // https://github.com/singerdmx/flutter-quill/tree/master/lib/src/models/rules
document // Document and related classes
delta // For anything that's specific to the `flutter_quill` instead of `dart_quill_delta`
packages // For the local packages that are usually a fork of other packages that are either modified or updated

This is also known as modular architecture or feature-based structure.

Each directory/module has its own directories and files in an organized way, so instead of having all the utilities in one place for all features, each feature has its own utils.

[!NOTE]
This is an initial project structure proposal to address our requirements. It's a starting point and should be refined through thoughtful planning and further discussion.
I would like to hear your suggestions before we start working on this.

[!TIP]
We should also consider improving the docs since at the moment it's quite minimal, I think we should either use GitHub wiki or a Website, navigating between too many markdown files might not provide a suitable experience for the developer. However, I would keep this suggestion for later. We can still use Markdown files for the website so we can revert easily later though it will be faster since we can generate HTML and CSS directly from Markdown.