feat: Html converter package (#1523)

* Html converter package

.github/workflows/main.yml

@@ -27,6 +27,9 @@ jobs:
 
       - name: Install flutter_quill_test dependencies
         run: flutter pub get -C flutter_quill_test
+      
+      - name: Install quill_html_converter dependencies
+        run: flutter pub get -C packages/quill_html_converter
 
       - name: Run flutter analysis
         run: flutter analyze

README.md

@@ -33,8 +33,8 @@ Pub: [FlutterQuill]
 ## Table of contents
 - [Flutter Quill](#flutter-quill)
   - [Table of contents](#table-of-contents)
-  - [Installation](#installation)
   - [Screenshots](#screenshots)
+  - [Installation](#installation)
   - [Usage](#usage)
   - [Migration](#migration)
   - [Input / Output](#input--output)
@@ -53,6 +53,20 @@ Pub: [FlutterQuill]
   - [Testing](#testing)
   - [Contributors](#contributors)
 
+## Screenshots
+
+<details>
+<summary>Tap to show/hide screenshots</summary>
+
+<br>
+
+<img src="./example/assets/images/1.png" width="150" alt="Screenshot 1">
+<img src="./example/assets/images/2.png" width="150" alt="Screenshot 2">
+<img src="./example/assets/images/3.png" width="150" alt="Screenshot 3">
+<img src="./example/assets/images/4.png" width="150" alt="Screenshot 4">
+
+</details>
+
 ## Installation
 
 ```yaml
@@ -86,20 +100,6 @@ Compatible versions:
 
 Theses versions are tested and well supported, you shouldn't get a build failure
 
-## Screenshots
-
-<details>
-<summary>Tap to show/hide screenshots</summary>
-
-<br>
-
-<img src="./example/assets/images/1.png" width="150" alt="Screenshot 1">
-<img src="./example/assets/images/2.png" width="150" alt="Screenshot 2">
-<img src="./example/assets/images/3.png" width="150" alt="Screenshot 3">
-<img src="./example/assets/images/4.png" width="150" alt="Screenshot 4">
-
-</details>
-
 ## Usage
 
 See the `example` directory for a minimal example of how to use FlutterQuill.  You typically just need to instantiate a controller:
@@ -326,7 +326,12 @@ Open this [page](./doc/translation.md) for more info
 ## Conversion to HTML
 
 Having your document stored in Quill Delta format is sometimes not enough. Often you'll need to convert
-it to other formats such as HTML in order to publish it, or send an email. One option is to use
+it to other formats such as HTML in order to publish it, or send an email.
+
+You have two options:
+
+1. Using [quill_html_converter](./packages/quill_html_converter/) to convert to/from HTML, the package is not ready yet
+2. Another option is to use
 [vsc_quill_delta_to_html](https://pub.dev/packages/vsc_quill_delta_to_html) to convert your document
 to HTML. This package has full support for all Quill operations - including images, videos, formulas,
 tables, and mentions. Conversion can be performed in vanilla Dart (i.e., server-side or CLI) or in Flutter.

example/lib/pages/home_page.dart

@@ -18,6 +18,7 @@ import 'package:flutter_quill_extensions/presentation/embeds/widgets/image.dart'
 import 'package:image_cropper/image_cropper.dart';
 import 'package:path/path.dart' as path;
 import 'package:path_provider/path_provider.dart';
+import 'package:quill_html_converter/quill_html_converter.dart';
 
 import '../widgets/time_stamp_embed_widget.dart';
 import 'read_only_page.dart';
@@ -120,10 +121,12 @@ class _HomePageState extends State<HomePage> {
                 ),
               ),
               IconButton(
-                onPressed: () => _insertTimeStamp(
+                onPressed: () {
-                  _controller,
+                  _insertTimeStamp(
-                  DateTime.now().toString(),
+                    _controller,
-                ),
+                    DateTime.now().toString(),
+                  );
+                },
                 icon: const Icon(Icons.add_alarm_rounded),
               ),
               IconButton(
@@ -264,6 +267,28 @@ class _HomePageState extends State<HomePage> {
                     }
                   },
                 ),
+                ListTile(
+                  title: const Text('Convert to/from HTML'),
+                  onTap: () async {
+                    final scaffoldMessenger = ScaffoldMessenger.of(context);
+                    final navigator = Navigator.of(context);
+                    try {
+                      final html = _controller.document.toDelta().toHtml();
+                      _controller.document =
+                          Document.fromDelta(DeltaHtmlExt.fromHtml(html));
+                    } catch (e) {
+                      scaffoldMessenger.showSnackBar(
+                        SnackBar(
+                          content: Text(
+                            'Error while convert to/from HTML: ${e.toString()}',
+                          ),
+                        ),
+                      );
+                    } finally {
+                      navigator.pop();
+                    }
+                  },
+                ),
                 _buildMenuBar(context),
               ],
             ),

example/pubspec.yaml

@@ -17,8 +17,10 @@ dependencies:
   path_provider: ^2.1.1
   # filesystem_picker: ^4.0.0
   file_picker: ^6.1.1
-  flutter_quill: ^8.4.1
+  flutter_quill: ^8.5.1
-  flutter_quill_extensions: ^0.6.5
+  flutter_quill_extensions: ^0.6.7
+  quill_html_converter:
+    path: ../packages/quill_html_converter
   path: ^1.8.3
   desktop_drop: ^0.4.4
   image_cropper: ^5.0.0

packages/README.md

@@ -3,4 +3,12 @@
 This folder contains packages that add more features to the [FlutterQuill](../README.md) 
 that might be outside of the packages main purpose
 
-This page will be updated soon.
+Pub: [quill_html_converter](https://pub.dev/packages/quill_html_converter)
+
+## Table of contents
+- [Flutter Quill Packages](#flutter-quill-packages)
+  - [Table of contents](#table-of-contents)
+  - [Packages](#packages)
+
+## Packages
+- [quill_html_converter](./quill_html_converter/)

packages/quill_html_converter/.gitignore

@@ -0,0 +1,30 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+.packages
+build/

packages/quill_html_converter/.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "d211f42860350d914a5ad8102f9ec32764dc6d06"
+  channel: "stable"
+
+project_type: package

packages/quill_html_converter/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1-experimental.1
+
+* initial release.

packages/quill_html_converter/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Flutter Quill Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/quill_html_converter/README.md

@@ -0,0 +1,41 @@
+# Flutter Quill HTML
+A extension for [flutter_quill](https://pub.dev/packages/flutter_quill) package to add support for dealing with conversion to/from html
+
+It uses [vsc_quill_delta_to_html](https://pub.dev/packages/vsc_quill_delta_to_html) package to convert the the delta to HTML
+
+This library is **experimental** and the support might be dropped at anytime.
+
+## Features
+
+```markdown
+- Easy to use
+- Support Flutter Quill package
+```
+
+## Getting started
+
+```yaml
+dependencies:
+  quill_html_converter: ^<latest-version-here>
+```
+
+## Usage
+
+First, you need to [setup](../../README.md#usage) the `flutter_quill` first
+
+Then you can simply convert to/from HTML
+
+```dart
+import 'package:quill_html_converter/quill_html_converter.dart';
+
+// Convert Delta to HTML
+final html = _controller.document.toDelta().toHtml();
+
+// Load Delta document using HTML
+_controller.document =
+    Document.fromDelta(DeltaHtmlExt.fromHtml(html));
+```
+
+## Additional information
+
+This will be updated soon.

packages/quill_html_converter/analysis_options.yaml

@@ -0,0 +1,36 @@
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  errors:
+    undefined_prefixed_name: ignore
+    unsafe_html: ignore
+linter:
+  rules:
+    always_declare_return_types: true
+    always_put_required_named_parameters_first: true
+    annotate_overrides: true
+    avoid_empty_else: true
+    avoid_escaping_inner_quotes: true
+    avoid_print: true
+    avoid_redundant_argument_values: true
+    avoid_types_on_closure_parameters: true
+    avoid_void_async: true
+    cascade_invocations: true
+    directives_ordering: true
+    omit_local_variable_types: true
+    prefer_const_constructors: true
+    prefer_const_constructors_in_immutables: true
+    prefer_const_declarations: true
+    prefer_final_fields: true
+    prefer_final_in_for_each: true
+    prefer_final_locals: true
+    prefer_initializing_formals: true
+    prefer_int_literals: true
+    prefer_interpolation_to_compose_strings: true
+    prefer_relative_imports: true
+    prefer_single_quotes: true
+    sort_constructors_first: true
+    sort_unnamed_constructors_first: true
+    unnecessary_lambdas: true
+    unnecessary_parenthesis: true
+    unnecessary_string_interpolations: true

packages/quill_html_converter/lib/quill_html_converter.dart

@@ -0,0 +1,60 @@
+library quill_html_converter;
+
+import 'dart:convert' show jsonDecode;
+
+import 'package:delta_markdown_converter/delta_markdown_converter.dart'
+    as delta_markdown show markdownToDelta;
+import 'package:flutter_quill/flutter_quill.dart' show Delta;
+import 'package:html2md/html2md.dart' as html2md;
+import 'package:vsc_quill_delta_to_html/vsc_quill_delta_to_html.dart'
+    as conventer show ConverterOptions, QuillDeltaToHtmlConverter;
+
+typedef ConverterOptions = conventer.ConverterOptions;
+
+/// A extension for [Delta] which comes from `flutter_quill` to extends
+/// the functionality of it to support converting the [Delta] to/from HTML
+extension DeltaHtmlExt on Delta {
+  /// Convert the [Delta] instance to HTML Raw string
+  ///
+  /// It will run using the following steps:
+  ///
+  /// 1. Convert the [Delta] to json using [toJson]
+  /// 2. Cast the json map as `List<Map<String, dynamic>>`
+  /// 3. Pass it to the conventer `vsc_quill_delta_to_html` which is a package
+  /// that designed specifically for converting the quill delta to html
+  String toHtml({ConverterOptions? options}) {
+    final json = toJson();
+    final html = conventer.QuillDeltaToHtmlConverter(
+      List.castFrom(json),
+      options,
+    ).convert();
+    return html;
+  }
+
+  /// Convert the HTML Raw string to [Delta]
+  ///
+  /// It will run using the following steps:
+  ///
+  /// 1. Convert the html to markdown string using `html2md` package
+  /// 2. Convert the markdown string to quill delta json string
+  /// 3. Decode the delta json string to [Delta]
+  ///
+  /// for more [info](https://github.com/singerdmx/flutter-quill/issues/1100)
+  static Delta fromHtml(String html) {
+    final markdown = html2md
+        .convert(
+          html,
+        )
+        .replaceAll('unsafe:', '');
+    final deltaJsonString = delta_markdown.markdownToDelta(markdown);
+    final deltaJson = jsonDecode(deltaJsonString);
+    if (deltaJson is! List) {
+      throw ArgumentError(
+        'The delta json string should be of type list when jsonDecode() it',
+      );
+    }
+    return Delta.fromJson(
+      deltaJson,
+    );
+  }
+}

packages/quill_html_converter/pubspec.yaml

@@ -0,0 +1,36 @@
+name: quill_html_converter
+description: A extension for flutter_quill package to add support for dealing with conversion to/from html
+version: 0.0.1-experimental.1
+homepage: https://github.com/singerdmx/flutter-quill/tree/master/packages/quill_html_converter
+repository: https://github.com/singerdmx/flutter-quill/tree/master/packages/quill_html_converter
+
+topics:
+ - ui
+ - widgets
+ - widget
+ - rich-text-editor
+ - quill
+
+environment:
+  sdk: '>=3.1.5 <4.0.0'
+  flutter: ">=1.17.0"
+
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_quill: ^8.5.1
+  vsc_quill_delta_to_html: ^1.0.3
+  html2md: ^1.3.1
+  # markdown: ^7.1.1
+  charcode: ^1.3.1
+  collection: ^1.17.2
+  delta_markdown_converter: ^0.0.2
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  flutter_lints: ^3.0.1
+
+flutter:
+
+  uses-material-design: true

packages/quill_html_converter/pubspec_overrides.yaml.g

@@ -0,0 +1,3 @@
+dependency_overrides:
+  flutter_quill:
+    path: ../../

packages/quill_html_converter/test/quill_html_converter.dart

@@ -0,0 +1,7 @@
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('No tests for now', () {
+    expect(true, true);
+  });
+}

scripts/disable_local_dev.sh

@@ -19,4 +19,9 @@ rm flutter_quill_test/pubspec_overrides.yaml
 
 echo ""
 
+echo "Disable local development for all the other packages..."
+rm packages/quill_html_converter/pubspec_overrides.yaml
+
+echo ""
+
 echo "Local development for all libraries has been disabled, please 'flutter pub get' for each one of them"

scripts/enable_local_dev.sh

@@ -19,4 +19,9 @@ cp flutter_quill_test/pubspec_overrides.yaml.g flutter_quill_test/pubspec_overri
 
 echo ""
 
+echo "Enable local development for all the other packages..."
+cp packages/quill_html_converter/pubspec_overrides.yaml.g packages/quill_html_converter/pubspec_overrides.yaml
+
+echo ""
+
 echo "Local development for all libraries has been enabled, please 'flutter pub get' for each one of them"