Refactor the project structure without breaking changes

[EchoEllet]

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.

[CatHood0]

I think we should either use GitHub wiki or a Website

I think the same. Navigating between markdown files sometimes becomes quite uncomfortable and is sometimes limited in terms of the styles it can contain. A separate page for documentation would make this point easier.

I don't know too much about the Web (besides the basics with HTML, CSS, and Typescript, with a little bit of Node), but if you need help I can give you a hand

[EchoEllet]

I tried GitBook and I don't know what you think of what I achieved: Flutter Quill Documentation

The search functionality and the HTML static file generation already give a better developer experience with minimal efforts.

Some styles and features have broken since some of them are GitHub specific.

Did you try GitBook while we were discussing this?

[CatHood0]

Did you try GitBook while we were discussing this?

Yeah, it was more out of curiosity than anything else. If it is not what is needed for now I will remove the link. Anyway, I just wanted to see how good GitBook was for creating these types of documentation pages (it's actually much more comfortable than navigating between markdown files, i guess).

[EchoEllet]

Yeah, it was more out of curiosity than anything else. If it is not what is needed for now I will remove the link.

I don't see any disadvantages of having this feature at the moment. I still prefer to focus one thing at a time and plan how we do something before doing it to produce a better result.

Anyway, I just wanted to see how good GitBook was for creating these types of documentation pages (it's actually much more comfortable than navigating between markdown files).

Yes, until now, it has had pretty good results without changing much. Did you use GitHub integration?

Regarding our previous discussion, if you have suggestions or anything that could be improved or fixed, I'm open to all feedback.

[CatHood0]

Did you use GitHub integration?

Yes, it was pretty quick to actually log in via Github. I think this is a pretty good option since it is fast and if you copy content, whether Markdown or HTML, it formats it automatically.

[EchoEllet]

If it is not what is needed for now I will remove the link.

Regarding the docs, already tried it and it requires minimal changes, more than what I expected.
You can restore the docs website using GitBook so we can start improving the docs and update it since some parts of it are GitHub specific.

[CatHood0]

The first structure I can think of is

It seems like a good project structure to me. It is easy to handle and leaves the characteristics of the package at a glance. However, I imagine that the translations would go into the common folder, right?

[EchoEllet]

 I imagine that the translations would go into the common folder, right?

Or, in it's own directory to make it more accessible, we could also move the arb files outside of the lib directory since the Dart files will be generated from them.

[EchoEllet]

Closing this discussion as we have moved it to Issue #2031.