Chore: improved general API (#6)

Co-authored-by: CatHood0 <santiagowmar@gmail.com>

Author: CatHood0

analysis_options.yaml

@@ -1,5 +1,28 @@
+include: package:flutter_lints/flutter.yaml
+
 analyzer:
   errors:
     depend_on_referenced_packages: ignore
     prefer_const_literals_to_create_immutables: ignore
-include: package:flutter_lints/flutter.yaml
+  language:
+    strict-raw-types: true 
+
+linter:
+  rules:
+    hash_and_equals: true
+    implicit_reopen: true
+    cancel_subscriptions: true
+    close_sinks: true
+    avoid_web_libraries_in_flutter: true
+    avoid_type_to_string: true
+    avoid_relative_lib_imports: true
+    avoid_empty_else: true
+    avoid_dynamic_calls: false 
+    unnecessary_statements: true
+    use_key_in_widget_constructors: true
+    prefer_conditional_assignment: true
+    prefer_const_declarations: true
+    use_string_buffers: true
+    valid_regexps: true
+    control_flow_in_finally: true
+    always_specify_types: false 

lib/blocks/document.dart lib/core/blocks/document.dartlib/blocks/document.dart renamed to lib/core/blocks/document.dart

@@ -42,19 +42,21 @@ class Line {
     String? id,
     Map<String, dynamic>? attributes,
   })  : _fragments = List.from(
-          [
+          <dynamic>[
             TextFragment(
               data: data,
               attributes: attributes,
             )
           ],
         ),
         id = id == null || id.trim().isEmpty ? nanoid(8) : id,
-        _sealed = data == '\n' || data is Map ? true : false;
+        _sealed = data == '\n' || data is Map ? true : false; 
 
-  Line.newLine({String? id})
-      : _fragments = List.from(
-          [
+  Line.newLine({
+    String? id,
+    @visibleForTesting bool enableTesting = false,
+  })  : _fragments = List.from(
+          <dynamic>[
             TextFragment(
               data: '\n',
             )
@@ -134,7 +136,7 @@ class Line {
       throw StateError(
           'Element of type ${fragment.runtimeType} cannot be inserted before at $index when $runtimeType is sealed');
     }
-    _fragments.insert(index - 1, fragment);
+    insertAt(index - 1, fragment);
     return;
   }
 
@@ -159,6 +161,8 @@ class Line {
     if (areAttributesEquals) {
       final String previousData = previous.data as String;
       final String newData = '$previousData${fragment.data}';
+      // does not require a reorganization of siblings
+      // since we're merging two fragments in just one
       _fragments[lastIndex] = TextFragment(
         data: newData,
         attributes: previous.attributes,
@@ -183,26 +187,48 @@ class Line {
     );
   }
 
+  /// Get a secure copy of the fragments into this Line
   List<TextFragment> get fragments =>
       List<TextFragment>.unmodifiable(_fragments);
+
+  /// Get all direct instances of the fragments into this Line
+  ///
+  /// This is called `unsafeLines` because this ones can be modified
+  /// but, all the changes won't be notified to this Line (like reorganizing
+  /// siblings)
+  List<TextFragment> unsafeFragments() => _fragments;
+
   @visibleForTesting
+  @Deprecated('rawFragments is no longer '
+      'used and will be removed '
+      'in future releases. '
+      'Please, use unsafeFragments instead')
   List<TextFragment> get rawFragments => _fragments;
+
   int get length => _fragments.length;
-  bool get isSingle => _fragments.length == 1;
+
+  bool get isSingle => length == 1;
+
   String get toPlainText => _fragments
       .map<String>(
         (TextFragment e) => e.data is! String ? '' : e.data.toString(),
       )
       .join();
+
   int get textLength => _fragments
       .map<int>(
         (TextFragment e) => e.data is! String ? 1 : e.data.toString().length,
       )
       .fold(0, (int a, int b) => a + b);
+
   bool get isNewLine => isSingle ? _fragments.single.data == '\n' : false;
+
   bool get isSealed => _sealed;
+
   bool get isEmbedFragment => _fragments.single.data is Map<String, dynamic>;
+
   bool get isTextInsert => _fragments.isEmpty || _fragments.first.data != '\n';
+
   TextFragment? get first => _fragments.firstOrNull;
   TextFragment? get last => _fragments.lastOrNull;
   bool get isEmpty => _fragments.isEmpty;
@@ -224,15 +250,16 @@ class Line {
         ..write(indent);
       return str;
     }).join();
-    return '${indent}Line: <Sealed value:$_sealed> [\n$rawFragments${'$indent  '}]';
+    final String sealedStr = _sealed ? ' <Sealed>' : "";
+    return '${indent}Line:$sealedStr [\n$rawFragments${'$indent  '}]';
   }
 
   TextFragment elementAt(int index) {
-    return _fragments.elementAt(index);
+    return _fragments[index];
   }
 
   TextFragment? elementAtOrNull(int index) {
-    return _fragments.elementAtOrNull(index);
+    return index < 0 || index >= length ? null : _fragments[index];
   }
 
   TextFragment operator [](int index) {
@@ -243,12 +270,37 @@ class Line {
     _fragments[index] = fragment;
   }
 
+  bool equals(covariant Line other, {bool full = false}) {
+    if (full) {
+      return id == other.id &&
+          _equality.equals(
+            _fragments,
+            other._fragments,
+          ) &&
+          fullHashCode == other.fullHashCode;
+    }
+
+    return this == other;
+  }
+
   @override
   bool operator ==(covariant Line other) {
     if (identical(this, other)) return true;
-    return const ListEquality().equals(_fragments, other._fragments);
+    return _equality.equals(
+      _fragments,
+      other._fragments,
+    );
   }
 
   @override
-  int get hashCode => Object.hashAll([_fragments]);
+  int get hashCode => Object.hashAll(<Object?>[
+        _fragments,
+      ]);
+
+  int get fullHashCode => Object.hashAll(<Object?>[
+        id,
+        _fragments,
+      ]);
 }
+
+const ListEquality<TextFragment> _equality = ListEquality();

lib/blocks/line.dart lib/core/blocks/line.dartlib/blocks/line.dart renamed to lib/core/blocks/line.dart

@@ -312,7 +312,8 @@ class Paragraph {
       throw StateError(
           'Element of type ${fragment.runtimeType} cannot be inserted when $runtimeType is sealed');
     }
-    _lines[_lines.length - 1].addFragment(fragment);
+    final Line line = _lines[_lines.length - 1];
+    line.addFragment(fragment);
   }
 
   void removeLastLineIfNeeded() {

lib/blocks/paragraph.dart lib/core/blocks/paragraph.dartlib/blocks/paragraph.dart renamed to lib/core/blocks/paragraph.dart

@@ -1,4 +1,5 @@
 import 'package:collection/collection.dart';
+import 'package:flutter_quill_delta_easy_parser/extensions/extensions.dart';
 
 class TextFragment {
   /// The main data object associated with the line.
@@ -13,6 +14,18 @@ class TextFragment {
     this.attributes,
   });
 
+  /// Determines if this contains a custom object
+  bool get isEmbedFragment => data is! String;
+
+  /// Determines if this contains plain text
+  bool get isText => data is String;
+
+  /// Determines if this `TextFragment` is fully empty
+  /// with no data into it
+  bool get isBlank => isText
+      ? data.cast<String>().trim().isEmpty
+      : data.cast<dynamic>().isEmpty;
+
   /// Sets the attributes of the line to [attrs].
   ///
   /// If [attrs] is `null`, no changes are made to the current attributes.
@@ -31,22 +44,52 @@ class TextFragment {
   /// Creates a deep copy of the current [TextFragment] instance.
   TextFragment get clone => TextFragment(data: data, attributes: attributes);
 
+  /// Get the string contained by this fragment
+  ///
+  /// Return an empty string if the element is an embed fragment
+  String getTextValue() {
+    if (isEmbedFragment) return "";
+    return data.cast<String>();
+  }
+
+  /// Get the object contained by this fragment
+  T? getValue<T extends Object>() {
+    return data.castOrNull<T>();
+  }
+
+  /// Get the object map contained by this fragment
+  Map<String, dynamic> getEmbedValue() {
+    return getValue<Map<String, dynamic>>()!;
+  }
+
   /// Clears the data and attributes of the line, setting them to `null`.
+  @Deprecated(
+      'cleanLine is no longer used and will be removed in future releases. Use cleanAttributes instead')
   void cleanLine() {
+    data is String ? data = '' : data = <String, dynamic>{};
+    attributes = null;
+  }
+
+  /// Clears the data and attributes of the line, setting them to `null`.
+  void cleanAttributes() {
     attributes = null;
   }
 
   @override
   String toString() {
     attributes ??= null;
-    return 'TextFragment: "${data is String ? '$data'.replaceAll('\n', '\\n') : data}"${attributes == null ? '' : ', attributes: $attributes'}';
+    return 'TextFragment: "${data is String ? '$data'.replaceAll('\n', '\\n') : data}'
+        '"${attributes == null ? '' : ', attributes: $attributes'}';
   }
 
   @override
   bool operator ==(covariant TextFragment other) {
     if (identical(this, other)) return true;
     return (data is Map && other.data is Map
-            ? _equality.equals(data as Map, other.data as Map)
+            ? _equality.equals(
+                data as Map,
+                other.data as Map,
+              )
             : data == other.data) &&
         _equality.equals(
           attributes,
@@ -58,4 +101,5 @@ class TextFragment {
   int get hashCode => Object.hash(data, attributes);
 }
 
+// ignore: always_specify_types, strict_raw_type
 const MapEquality _equality = MapEquality();