Merge pull request #129 from ArturAssisComp/main

Implement the API modifications

Author: deandreamatias

.gitignore

@@ -33,13 +33,13 @@ build/
 pubspec.lock
 
 # Android related
-**/android/**/gradle-wrapper.jar
-**/android/.gradle
-**/android/captures/
-**/android/gradlew
-**/android/gradlew.bat
-**/android/local.properties
-**/android/**/GeneratedPluginRegistrant.java
+example/android_backup/**/gradle-wrapper.jar
+example/android_backup/.gradle
+example/android_backup/captures/
+example/android_backup/gradlew
+example/android_backup/gradlew.bat
+example/android_backup/local.properties
+example/android_backup/**/GeneratedPluginRegistrant.java
 
 # iOS/XCode related
 **/ios/**/*.mode1v3

README.md

@@ -418,3 +418,37 @@ Take a look at [our fantastic ecosystem](https://github.com/flutter-form-builder
 ## Thanks to
 
 [All contributors](https://github.com/flutter-form-builder-ecosystem/form_builder_validators/graphs/contributors)
+
+
+# API changes draft
+During the process of exploration of new possibilities for the new API, I realized that there are
+basically three layers of validators: required layer, type layer and the specialized layer. Instead of
+repeating the computations for required and type layer for each validator composition, it is possible
+to decouple them, avoiding this redundancy and taking benefits from the Dart compiler.
+    
+During the exploration, I implemented some elementary validators that would make it possible, by
+composition, to create more sophisticated validators. The recipe is simple, start with a (not)required
+validator, add a type validator, and then chain as many specialized validators as you want.
+
+```dart
+// In this example, we build a validator composing a required, with a numeric and then a max.
+// The logic result is: required && numeric && max(70)
+
+final validator = ValidatorBuilder.required(and: <Validator<Object, num>>[
+      ValidatorBuilder.numeric(
+          errorText: 'La edad debe ser numérica.',
+          and: <BaseElementaryValidator<num, dynamic>>[
+            ValidatorBuilder.max(70),
+          ])
+    ]).validate;
+```
+
+I needed to change a little bit the approach. Instead of composing directly the validators as 
+FormFieldValidator's, one level of indirection was necessary, using a ValidatorBuilder instead.
+Thus, we first build the validator and then create the validation method calling validate.
+
+I implemented some examples that are related to some examples from example/main.dart. The new
+API examples are implemented in example/api_refactoring_main.dart. I recorded a video showing the
+execution of the examples and explaining the new api ideas.
+
+Please, give me the necessary feedback for me to continue the work.

example/.gitignore

@@ -40,6 +40,6 @@ app.*.symbols
 app.*.map.json
 
 # Android Studio will place build artifacts here
-/android/app/debug
-/android/app/profile
-/android/app/release
+/android_backup/app/debug
+/android_backup/app/profile
+/android_backup/app/release

example/.metadata

@@ -4,7 +4,7 @@
 # This file should be version controlled and should not be manually edited.
 
 version:
-  revision: "5dcb86f68f239346676ceb1ed1ea385bd215fba1"
+  revision: "2663184aa79047d0a33a14a3b607954f8fdd8730"
   channel: "stable"
 
 project_type: app
@@ -13,23 +13,26 @@ project_type: app
 migration:
   platforms:
     - platform: root
-      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
-      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
     - platform: android
-      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
-      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
     - platform: ios
-      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
-      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+    - platform: linux
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
     - platform: macos
-      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
-      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
     - platform: web
-      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
-      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
     - platform: windows
-      create_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
-      base_revision: 5dcb86f68f239346676ceb1ed1ea385bd215fba1
+      create_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
+      base_revision: 2663184aa79047d0a33a14a3b607954f8fdd8730
 
   # User provided section
 

example/android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip

example/lib/basic_examples.dart

@@ -0,0 +1,69 @@
+import 'package:flutter/material.dart';
+import 'package:form_builder_validators/form_builder_validators.dart'
+    show Validators;
+
+/// Basic examples involving only one validator per example
+class BasicExamplesPage extends StatelessWidget {
+  /// Constructs a new instance of the [BasicExamplesPage] class.
+  const BasicExamplesPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+          title: const Text('Basic Examples (one validator per example)')),
+      body: Padding(
+        padding: const EdgeInsets.all(8),
+        child: SingleChildScrollView(
+          child: Column(
+            children: <Widget>[
+              // Core validators
+              Text(
+                'Core Validators',
+                style: TextStyle(fontWeight: FontWeight.bold, fontSize: 24),
+              ),
+              Align(
+                alignment: Alignment.centerLeft,
+                child: Text(
+                  'Equality Validators',
+                  style: TextStyle(fontWeight: FontWeight.bold, fontSize: 18),
+                ),
+              ),
+              TextFormField(
+                decoration: const InputDecoration(
+                    labelText:
+                        'Type "I want to delete" to confirm the action.'),
+                autovalidateMode: AutovalidateMode.onUserInteraction,
+                validator: Validators.isEqual('I want to delete'),
+              ),
+              TextFormField(
+                decoration: const InputDecoration(
+                    labelText: 'Username (should not be "RESERVED")'),
+                autovalidateMode: AutovalidateMode.onUserInteraction,
+                validator: Validators.isNotEqual('RESERVED'),
+              ),
+              Align(
+                alignment: Alignment.centerLeft,
+                child: Text(
+                  'Required Error Message',
+                  style: TextStyle(fontWeight: FontWeight.bold, fontSize: 18),
+                ),
+              ),
+              TextFormField(
+                decoration:
+                    const InputDecoration(labelText: 'Input must not be null'),
+                autovalidateMode: AutovalidateMode.onUserInteraction,
+                validator: (String? input) {
+                  final String? isRequiredMsg = Validators.isRequired()(input);
+                  return isRequiredMsg
+                      ?.toUpperCase()
+                      .replaceFirst('OVERRIDE: ', '');
+                },
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}