added more documentation about classes and functions

CHANGELOG.md

@@ -1,6 +1,11 @@
+## 1.2.3
+
+* doc(README): added more documentation about CustomHtmlPart
+* doc: added more doc comments about general functionalities of the classes and methods
+
 ## 1.2.2
 
-* Feat: added support for data-checked attribute for <li> tags
+* Feat: added support for data-checked attribute for `<li>`  tags
 * Fix: removed duplicated getting inline attributes at resolveCurrentElement
 
 ## 1.2.1

README.md

@@ -7,57 +7,57 @@ This is a Dart package that converts HTML input into Quill Delta format, which i
 ## Supported tags
 
 ```html
-    Text Formatting
+    <!--Text Formatting-->
         <b>, <strong>: Bold text 
         <i>, <em>: Italic text
         <u>, <ins>: Underlined text
         <s>, <del>: Strikethrough text
         <sup>: Superscript text
         <sub>: Subscript text
 
-    Headings
+    <!--Headings-->
         <h1> to <h6>: Headings of various levels
 
-    Lists
+    <!--Lists-->
         <ul>: Unordered lists
         <ol>: Ordered lists
         <li>: List items
         <li data-checked="true">: Check lists 
         <input type="checkbox">: Another alternative to make a check lists
 
-    Links
+    <!--Links-->
         <a>: Hyperlinks with support for the href attribute
 
-    Images
-        <img>: Images with support for the src, alt, and width attributes
+    <!--Images-->
+        <img>: Images with support for the src
 
-    Videos 
+    <!--Videos -->
         <iframe>, <video>: Videos with support for the src
 
-    Blockquotes
+    <!--Blockquotes-->
         <blockquote>: Block quotations
 
-    Code Blocks
+    <!--Code Blocks-->
         <pre>, <code>: Code blocks
 
-    Text Alignment, inline text align and direction
+    <!--Text Alignment, inline text align and direction-->
         <p style="text-align:left|center|right|justify">: Paragraph style alignment
         <p align="left|center|right|justify">: Paragraph alignment
         <p dir="rtl">: Paragraph direction 
 
-    Text attributes
-        <p style="line-height: 1.0;font-size: 12;font-family: Times New Roman;color:#ffffff">: Inline attributes
+    <!--Text attributes-->
+        <p style="line-height: 1.0px;font-size: 12px;font-family: Times New Roman;color:#ffffff">: Inline attributes
 
-    Custom Blocks  
+    <!--Custom Blocks-->
         <pullquote data-author="john">: Custom html
 
 ```
 
 ## Not supported tags
 
 ```html
-  Text indent
-  <p style="padding: 10px">: indented paragraph
+  <!--Text indent-->
+  <p style="padding: 10px"> 
 ```
 
 ## Getting Started
@@ -66,7 +66,7 @@ Add the dependency to your pubspec.yaml:
 
 ```yaml
 dependencies:
-  flutter_quill_delta_from_html: ^1.2.2
+  flutter_quill_delta_from_html: ^1.2.3
 ```
 
 Then, import the package and use it in your Flutter application:
@@ -98,6 +98,10 @@ import 'package:html/dom.dart' as dom;
 class PullquoteBlock extends CustomHtmlPart {
   @override
   bool matches(dom.Element element) {
+    //you can put here the validation that you want
+    //
+    // To detect a <p>, you just need to do something like: 
+    // element.localName == 'p'
     return element.localName == 'pullquote';
   }
 
@@ -107,6 +111,12 @@ class PullquoteBlock extends CustomHtmlPart {
     final Map<String, dynamic> attributes = currentAttributes != null ? Map.from(currentAttributes) : {};
 
     // Extract custom attributes from the <pullquote> element
+    // The attributes represents the data into a html tag
+    // at this point, <pullquote> should have these attributes
+    //
+    // <pullquote data-author="John Doe" data-style="italic">
+    // These attributes can be optional, so do you need to ensure to not use "!" 
+    // to avoid any null conflict
     final author = element.attributes['data-author'];
     final style = element.attributes['data-style'];
 

lib/parser/colors.dart

@@ -1,5 +1,6 @@
 ///validate the string color to avoid unsupported colors
 String validateAndGetColor(String colorString) {
+  //verify if the color already is a hex
   if (colorString.startsWith('#')) return colorString;
   return colorToHex(colorString);
 }

lib/parser/custom_html_part.dart

@@ -4,9 +4,13 @@ import 'package:html/dom.dart' as dom;
 /// Interface for defining a custom block handler.
 abstract class CustomHtmlPart {
   /// Determines if this custom block handler matches the given HTML element.
+  /// If you want to detect, by example, a `<div>` you need to make something like
+  /// `element.localName == 'div'` 
+  /// And this just will match with any `<div>` tag
   bool matches(dom.Element element);
 
-  /// Converts the HTML element into Delta operations.
+  /// Converts the `HTML` element into `Delta` operations.
+  /// It's called when `matches` return true
   List<Operation> convert(dom.Element element,
       {Map<String, dynamic>? currentAttributes});
 }

lib/parser/html_to_delta.dart

@@ -16,6 +16,7 @@ class HtmlToDelta {
     this.customBlocks,
   }) {
     htmlToOp = htmlToOperations ?? DefaultHtmlToOperations();
+    //this part ensure to set the customBlocks passed at the constructor
     htmlToOp.setCustomBlocks(customBlocks ?? []);
   }
 
@@ -34,6 +35,8 @@ class HtmlToDelta {
     final List<dom.Node> nodesToProcess = $body?.nodes ?? $html?.nodes ?? $document.nodes;
 
     for (var node in nodesToProcess) {
+      //first just verify if the customBlocks aren't empty and then store on them to
+      //validate if one of them make match with the current Node
       if (customBlocks != null && customBlocks!.isNotEmpty && node is dom.Element) {
         for (var customBlock in customBlocks!) {
           if (customBlock.matches(node)) {

lib/parser/html_to_operation.dart

@@ -10,10 +10,14 @@ abstract class HtmlOperations {
   List<CustomHtmlPart>? customBlocks;
 
   ///Use this method to add full logic for comparate which type html tag is the current item on loop
+  ///By default this just verify and call the others methods, and override it is optional
   List<Operation> resolveCurrentElement(dom.Element element) {
     List<Operation> ops = [];
     if (element.localName == null) return ops;
     //inlines
+    //the current element could be into a <li> then it's node can be
+    //a <strong> or a <em>, or even a <span> then we first need to verify
+    //if a inline an store into it to parse the attributes as we need
     if (isInline(element.localName!)) {
       final Delta delta = Delta();
       final Map<String, dynamic> attributes = {};
@@ -66,7 +70,11 @@ abstract class HtmlOperations {
   ///Used when detect a link html tag <blockquote>
   List<Operation> blockquoteToOp(dom.Element element);
 
-  void setCustomBlocks(List<CustomHtmlPart> customBlocks) {
+  void setCustomBlocks(List<CustomHtmlPart> customBlocks, {bool overrideCurrentBlocks = false}) {
+    if (this.customBlocks != null && !overrideCurrentBlocks) {
+      this.customBlocks!.addAll(customBlocks);
+      return;
+    }
     this.customBlocks = [...customBlocks];
   }
 }
@@ -254,12 +262,20 @@ class DefaultHtmlToOperations extends HtmlOperations {
   @override
   List<Operation> videoToOp(dom.Element element) {
     final String src = element.attributes['src'] ?? '';
+    final String sourceSrc =
+        element.nodes.where((node) => node.nodeType == dom.Node.ELEMENT_NODE).firstOrNull?.attributes['src'] ?? '';
     if (src.isNotEmpty) {
       return [
         Operation.insert('\n'),
         Operation.insert({'video': src})
       ];
     }
+    if (sourceSrc.isNotEmpty) {
+      return [
+        Operation.insert('\n'),
+        Operation.insert({'video': sourceSrc})
+      ];
+    }
     return [];
   }
 

lib/parser/html_utils.dart

@@ -70,6 +70,7 @@ Map<String, dynamic> parseStyleAttribute(String style) {
 }
 
 ///Store within the node getting text nodes, spans nodes, link nodes, and attributes to apply for the delta
+///This only used store the inline attributes or tags into a <p> or a <h1> or <span> without insert block attributes
 void processNode(
   dom.Node node,
   Map<String, dynamic> attributes,
@@ -99,6 +100,7 @@ void processNode(
         }
       }
     } else {
+      ///the current node is <span>
       if (node.isSpan) {
         final spanAttributes = parseStyleAttribute(node.attributes['style'] ?? '');
         if (addSpanAttrs) {
@@ -107,18 +109,21 @@ void processNode(
           newAttributes.addAll({...spanAttributes});
         }
       }
+      ///the current node is <a>
       if (node.isLink) {
         final String? src = node.attributes['href'];
         if (src != null) {
           newAttributes['link'] = src;
         }
       }
+      ///the current node is <br>
       if (node.isBreakLine) {
         newAttributes.remove('align');
         newAttributes.remove('direction');
         delta.insert('\n', newAttributes);
       }
     }
+    ///Store on the nodes into the current one
     for (final child in node.nodes) {
       processNode(child, newAttributes, delta, addSpanAttrs: addSpanAttrs);
     }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: flutter_quill_delta_from_html
 description: "Convert easily HTML inputs content to Quill Delta format"
-version: 1.2.2
+version: 1.2.3
 homepage:
 repository: https://github.com/CatHood0/flutter_quill_delta_from_html/
 issue_tracker: https://github.com/CatHood0/flutter_quill_delta_from_html/issues
@@ -14,7 +14,6 @@ dependencies:
     sdk: flutter
   dart_quill_delta: ^9.5.12
   html: ^0.15.4
-  meta: ^1.12.0
 
 dev_dependencies:
   flutter_test: