Improve documentation readme about migration #146

ArturAssisComp · 2025-02-06T13:56:34Z

Connection with issue(s)

Close #131

Connected to #???

Solution description

Screenshots or Videos

To Do

Read contributing guide
Check the original issue to confirm it is fully satisfied
Add solution description to help guide reviewers
Add unit test to verify new or fixed behaviour
If apply, add documentation to code properties and package readme

ArturAssisComp · 2025-02-06T13:57:46Z

@deandreamatias I created this PR to do the item 2

codecov · 2025-02-06T14:01:50Z

Codecov Report

Attention: Patch coverage is 87.87879% with 12 lines in your changes missing coverage. Please review.

Project coverage is 98.11%. Comparing base (1834d8e) to head (359c8d2).
Report is 1 commits behind head on refactor_2024_11.

Files with missing lines	Patch %	Lines
lib/src/validators/file_validators.dart	71.79%	11 Missing ⚠️
lib/src/validators/string_validators.dart	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                 Coverage Diff                  @@
##           refactor_2024_11     #146      +/-   ##
====================================================
- Coverage             98.74%   98.11%   -0.64%     
====================================================
  Files                   111      112       +1     
  Lines                  1510     1588      +78     
====================================================
+ Hits                   1491     1558      +67     
- Misses                   19       30      +11

Flag	Coverage Δ
unittests	`98.11% <87.87%> (-0.64%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ArturAssisComp · 2025-02-27T21:22:51Z

I am writing the migration guide now.
While I am doing that, I would like to know what are the validators from the following list that will be implemented in the new api?

Datetime validators

TODO FormBuilderValidators.date() - requires the field's value to be a valid date string.
TODO FormBuilderValidators.time() - requires the field's value to be a valid time string.
TODO FormBuilderValidators.timeZone() - requires the field's value to be a valid time zone.

File validators

TODO FormBuilderValidators.fileExtension() - requires the field's value to a valid file extension.
TODO FormBuilderValidators.fileName() - requires the field's to be a valid file name.
TODO FormBuilderValidators.fileSize() - requires the field's to be less than the max size.
TODO FormBuilderValidators.mimeType() - requires the field's value to a valid MIME type.
TODO FormBuilderValidators.path() - requires the field's to be a valid file or folder path.

Finance validators

TODO FormBuilderValidators.bic() - requires the field's to be a valid BIC.
TODO FormBuilderValidators.creditCardCVC() - requires the field's value to be a valid credit card CVC number.
TODO FormBuilderValidators.creditCardExpirationDate() - requires the field's value to be a valid credit card expiration date and can check if not expired yet.
TODO FormBuilderValidators.iban() - requires the field's to be a valid IBAN.

Miscellaneous validators

TODO FormBuilderValidators.base64() - requires the field's to be a valid base64 string.
TODO FormBuilderValidators.colorCode() - requires the field's value to be a valid color code.
TODO FormBuilderValidators.duns() - requires the field's value to be a valid DUNS.
TODO FormBuilderValidators.isbn() - requires the field's to be a valid ISBN.
TODO FormBuilderValidators.json() - requires the field's to be a valid json string.
TODO FormBuilderValidators.languageCode() - requires the field's to be a valid language code.
TODO FormBuilderValidators.licensePlate() - requires the field's to be a valid license plate.
TODO FormBuilderValidators.vin() - requires the field's to be a valid VIN number.

Network validators

TODO FormBuilderValidators.email() - requires the field's value to be a valid email address.
TODO FormBuilderValidators.latitude() - requires the field's to be a valid latitude. - FormBuilderValidators.longitude() - requires the field's to be a valid longitude.
TODO FormBuilderValidators.macAddress() - requires the field's to be a valid MAC address.
TODO FormBuilderValidators.phoneNumber() - requires the field's value to be a valid phone number.
TODO FormBuilderValidators.portNumber() - requires the field's to be a valid port number.

Numeric validators

TODO FormBuilderValidators.evenNumber() - requires the field's to be an even number.
TODO FormBuilderValidators.negativeNumber() - requires the field's to be a negative number.
TODO FormBuilderValidators.notZeroNumber() - requires the field's to be not a number zero.
TODO FormBuilderValidators.oddNumber() - requires the field's to be an odd number.
TODO FormBuilderValidators.positiveNumber() - requires the field's to be a positive number.
TODO FormBuilderValidators.prime() - requires the field's to be a prime number.

String validators

TODO FormBuilderValidators.endsWith() - requires the substring to be the end of the field's value.
TODO FormBuilderValidators.startsWith() - requires the substring to be the start of the field's value.
TODO FormBuilderValidators.lowercase() - requires the field's value to be lowercase.
TODO FormBuilderValidators.uppercase() - requires the field's value to be uppercase.
TODO FormBuilderValidators.matchNot() - requires the field's value to not match the provided regex pattern.
TODO FormBuilderValidators.alphabetical() - requires the field's to contain only alphabetical characters.
TODO FormBuilderValidators.maxWordsCount() - requires the word count of the field's value to be less than or equal to the provided maximum count.
TODO FormBuilderValidators.minWordsCount() - requires the word count of the field's value to be greater than or equal to the provided minimum count.
TODO FormBuilderValidators.singleLine() - requires the field's string to be a single line of text.

User Information validators

deandreamatias · 2025-02-28T06:44:10Z

I will take a look and check. When ready, will write a comment

ArturAssisComp · 2025-03-10T13:18:40Z

Added the first migration instructions below. Please, check if they are very clear. Otherwise, I refactor them for them to be clearer.

### v11 to v12
- Deprecate `FormBuilderValidators` class with its static methods as validators.
- Instead, you should use `Validators` class.
- Instructions on how to update each old API validator to the new API equivalent:
  - **checkNullOrEmpty**: Before specifying the equivalent to each validator, it is important to deal with the `checkNullOrEmpty` parameter. Every validator from the old API has this parameters, thus we are going to use this section to specify how to handle this situation for most of the cases and we will assume that this aspect is already handled for the following sections:
    - `checkNullOrEmpty = true`: Given the old api: `FormBuilderValidators.someValidator(..., checkNullOrEmpty:true)`, the equivalent in the new API is `Validators.required(Validators.someEquivalentValidator(...))`.
    - `checkNullOrEmpty = false`: Given the old api: `FormBuilderValidators.someValidator(..., checkNullOrEmpty:false)`, the equivalent in the new API is `Validators.optional(Validators.someEquivalentValidator(...))`.
  - Bool validators
    - For this group of validators, it is expected to receive a `String` as user input. Thus, if your
    form widget does not guarantee a `String` input (it may receive an `Object`), you must wrap the 
    equivalent validator with the type validator for strings. Thus, instead of 
    `Validators.hasMin<Something>Chars(...)`, use `Validators.string(Validators.hasMin<Something>Chars(...))`
        - `FormBuilderValidators.hasLowercaseChars(atLeast: n, regex: reg, errorText: 'some error')` is 
        equivalent to `Validators.hasMinLowercaseChars(min: n, customLowercaseCounter:(input)=>reg.allMatches(input).length, hasMinLowercaseCharsMsg:(_, __)=>'some error')`
        - `FormBuilderValidators.hasNumericChars(atLeast: n, regex: reg, errorText: 'some error')` is
          equivalent to `Validators.hasMinNumericChars(min: n, customNumericCounter:(input)=>reg.allMatches(input).length, hasMinNumericCharsMsg:(_, __)=>'some error')`
        - `FormBuilderValidators.hasSpecialChars(atLeast: n, regex: reg, errorText: 'some error')` is
          equivalent to `Validators.hasMinSpecialChars(min: n, customSpecialCounter:(input)=>reg.allMatches(input).length, hasMinSpecialCharsMsg:(_, __)=>'some error')`
        - `FormBuilderValidators.hasUppercaseChars(atLeast: n, regex: reg, errorText: 'some error')` is
          equivalent to `Validators.hasMinUppercaseChars(min: n, customUppercaseCounter:(input)=>reg.allMatches(input).length, hasMinUppercaseCharsMsg:(_, __)=>'some error')`

deandreamatias · 2025-03-24T18:42:35Z

About validators on new API.
I finished the checklist. To confirm, this validators should be on new API:

FormBuilderValidators.fileSize()
FormBuilderValidators.bic()
FormBuilderValidators.iban()
FormBuilderValidators.colorCode()
FormBuilderValidators.isbn()
FormBuilderValidators.email()
FormBuilderValidators.macAddress()
FormBuilderValidators.lowercase()
FormBuilderValidators.uppercase()
FormBuilderValidators.maxWordsCount()
FormBuilderValidators.minWordsCount()

Will be ideal that in some way we preserve the reference to old validators code.
Maybe on changelog can add a link to 11.0.0 branch of Github and the list of all removed validators. With this, the users could see the implementation code and implement with new API if need.

ArturAssisComp · 2025-03-28T22:41:20Z

~~I created a branch called v11.1.2 to use as reference for the validators that are not implemented in the new API.~~
Oh, I will use permalink instead. this branch will not be necessary anymore.

ArturAssisComp · 2025-03-29T00:51:27Z

@deandreamatias , what option do you think is clearer (A or B) to show the old api and the equivalent/close for the new api?

deandreamatias · 2025-03-29T09:07:09Z

@deandreamatias , what option do you think is clearer (A or B) to show the old api and the equivalent/close for the new api?

A is 1000% better 😅

deandreamatias · 2025-03-30T10:53:01Z

I think that is better create a separeted markdown file for migration, because is really big.
The recommended is to create it inside a path call doc/ https://dart.dev/tools/pub/package-layout#documentation. The name of file could be migration.md (very intuitve hehehe)

deandreamatias · 2025-04-17T16:46:24Z

I was reviewing the issues and I think this #131 is probably solved with the new API.
Maybe you can put it as related in the MR.

ArturAssisComp · 2025-07-24T22:54:12Z

Should I update intl version to 20? the CI is complaining. Maybe that break code that is using the older version (19).

deandreamatias · 2025-07-25T07:47:35Z

On main branch is updated. I need update flutter-form-builder-ecosystem:refactor_2024_11 branch

deandreamatias · 2025-03-24T18:43:29Z

README-updated.md

+- Deprecate `FormBuilderValidators` class with its static methods as validators.
+- Instead, you should use `Validators` class.


This would be a single line

deandreamatias · 2025-03-24T18:46:48Z

README-updated.md

+    - `FormBuilderValidators.maxLength(n, errorText:'some error')` is equivalent to
+      `Validators.maxLength(n, maxLengthMsg: (_, __)=>'some error')`
+    - `FormBuilderValidators.minLength(n, errorText:'some error')` is equivalent to
+      `Validators.minLength(n, minLengthMsg: (_, __)=>'some error')`


I think that this implementation is "intuitive". I don't know if is need

deandreamatias · 2025-07-27T12:35:16Z

README.md

+- TODO [ ] `Validators.notContains(substring)` - Checks if the field does not contain the `substring`.
+- TODO [ ] `FormBuilderValidators.endsWith()` - requires the substring to be the end of the field's value.
+- TODO [ ] `FormBuilderValidators.notEndsWith()` - requires the substring not to be the end of the field's value.
+- TODO [ ] `FormBuilderValidators.startsWith()` - requires the substring to be the start of the field's value.
+- TODO [ ] `FormBuilderValidators.notStartsWith()` - requires the substring not to be the start of the field's value.
+- TODO [ ] `FormBuilderValidators.lowercase()` - requires the field's value to be lowercase.
+- TODO [ ] `FormBuilderValidators.uppercase()` - requires the field's value to be uppercase.
+- `Validators.hasMinUppercaseChars(min:min)` - Checks if the field has a minimum number of uppercase chars.
+- TODO [ ] `Validators.hasMaxUppercaseChars(max:max)` - Checks if the field has a maximum number of uppercase chars.
+- `Validators.hasMinLowercaseChars(min:min)` - Checks if the field has a minimum number of lowercase chars.
+- TODO [ ] `Validators.hasMaxLowercaseChars(max:max)` - Checks if the field has a maximum number of lowercase chars.
+- `Validators.hasMinNumericChars(min:min)` - Checks if the field has a minimum number of numeric chars.
+- TODO [ ] `Validators.hasMaxNumericChars(max:max)` - Checks if the field has a maximum number of numeric chars.
+- `Validators.hasMinSpecialChars(min:min)` - Checks if the field has a minimum number of special chars.
+- TODO [ ] `Validators.hasMaxSpecialChars(max:max)` - Checks if the field has a maximum number of special chars.
+- `Validators.match(regExp)` - Checks if the field matches with the regular expression `regExp`.
+- TODO [ ] `Validators.notMatch(regExp)` - Checks if the field does not match with the regular expression `regExp`.
+- `Validators.uuid()` - Checks if the field is a valid Universally Unique Identifier (UUID).
+- TODO [ ] `FormBuilderValidators.maxWordsCount()` - requires the word count of the field's value to be less than or equal to the provided maximum count.
+- TODO [ ] `FormBuilderValidators.minWordsCount()` - requires the word count of the field's value to be greater than or equal to the provided minimum count.


Missing TODOs?

deandreamatias · 2025-07-27T12:37:32Z

README.md

+        (String? val) {
+            if (val != null) {
+              final int? number = int.tryParse(val);
+              // todo bug here: if it is not int, it accepts negative


deandreamatias · 2025-07-27T12:39:54Z

README.md

+  return (userInput != null && userInput % 2 == 0) ? null : 'This field must be even';
+}
+```
+The challenge with the previous approach is that we must handle null checks in every validator


Add the version of previous approach, like ( < v11.x.x)

deandreamatias · 2025-07-27T12:41:56Z

README.md

+}
+```
+
+This package introduces a more precise approach that separates null-value handling from the actual


Suggested change

This package introduces a more precise approach that separates null-value handling from the actual

From version 12.x.x, this package introduces a more precise approach that separates null-value handling from the actual

deandreamatias · 2025-07-27T12:49:46Z

doc/migration.md

+  citiesWhitelist: ['CityA', 'CityB', 'CityC'],
+  citiesBlacklist: ['CityD', 'CityE'],


All reference to whiteList will be allowList and blackList will be blockList

deandreamatias · 2025-07-27T16:46:50Z

example/lib/generic_examples.dart

 import 'package:form_builder_validators/form_builder_validators.dart'
-    show Validators, Validator;
+    show Validator, Validators;



Is this still necessary? The show

ArturAssisComp added 2 commits February 6, 2025 10:55

first commit

09a4514

Merge remote-tracking branch 'origin/main'

c8860fc

ArturAssisComp marked this pull request as draft February 6, 2025 13:56

Merge branch 'refactor_2024_11' into main

c0d388a

ArturAssisComp added 14 commits February 10, 2025 11:29

add how it works section

960707b

update string session

ddd9cbd

add user information, network, and finance validators

74dbe1a

add other sections: collection, datetime, generic types, numeric,

d5c5ceb

add type validator to readme

72e0c71

add core validators section to readme.

a8c391b

fix the contents section

411dda1

remove the verb 'is' from equality validators

dec4504

remove the verb 'is' from required validators

70c7594

remove the verb 'is' from the type validators

a592233

remove the verb 'is' from dateTime validators

38084a8

remove the verb 'is' from generic validators

8b235d1

update readme

484e639

update readme

ee762d7

Add the first migration instructions

330caf4

add more breaking changes instructions

b223f31

add changelog to core validators

9d559b9

refactor breaking changes and add more items to it

a5bd74b

ArturAssisComp added 6 commits April 2, 2025 22:27

implement max file size validator

e12df52

add some migration items and the validator bic

684d899

add some examples and add more migration items

5cd2eb8

implement iban validators for the new api

51e1d84

implement notInList validators and add more migration guide items.

ef2ff20

update readme

5536724

ArturAssisComp added 6 commits April 24, 2025 21:49

add some migrations

db85c06

add examples and more migrations

359c8d2

add macAddress validator

e8be0ed

add some items to changelog and suggest the validator satisfy

cc05703

add migration for numeric types

c75a7c5

update the string validation migrations

312a5bd

github-actions bot added the Stale label Jul 14, 2025

ArturAssisComp added 3 commits July 23, 2025 20:05

implement use case migration guide.

dd50648

Finished migration guide

1720602

add satisfy validator

f5b0d28

github-actions bot removed the Stale label Jul 24, 2025

ArturAssisComp added 3 commits July 24, 2025 18:22

add colorCode validator

f9a362c

add isbn validator

2d1eb9b

update last details

568ba66

ArturAssisComp marked this pull request as ready for review July 24, 2025 22:46

ArturAssisComp requested a review from deandreamatias July 24, 2025 22:47

Merge branch 'refactor_2024_11' into main

f18cd7e

deandreamatias reviewed Jul 27, 2025

View reviewed changes

		- Deprecate `FormBuilderValidators` class with its static methods as validators.
		- Instead, you should use `Validators` class.

	This package introduces a more precise approach that separates null-value handling from the actual
	From version 12.x.x, this package introduces a more precise approach that separates null-value handling from the actual

		citiesWhitelist: ['CityA', 'CityB', 'CityC'],
		citiesBlacklist: ['CityD', 'CityE'],

Uh oh!

Improve documentation readme about migration #146

Are you sure you want to change the base?

Improve documentation readme about migration #146

Uh oh!

Conversation

ArturAssisComp commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Connection with issue(s)

Solution description

Screenshots or Videos

To Do

Uh oh!

ArturAssisComp commented Feb 6, 2025

Uh oh!

codecov bot commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ArturAssisComp commented Feb 27, 2025 • edited by deandreamatias Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Datetime validators

File validators

Finance validators

Miscellaneous validators

Network validators

Numeric validators

String validators

User Information validators

Uh oh!

deandreamatias commented Feb 28, 2025

Uh oh!

ArturAssisComp commented Mar 10, 2025

Uh oh!

deandreamatias commented Mar 24, 2025

Uh oh!

ArturAssisComp commented Mar 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ArturAssisComp commented Mar 29, 2025

Uh oh!

deandreamatias commented Mar 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

deandreamatias commented Mar 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

deandreamatias commented Apr 17, 2025

Uh oh!

ArturAssisComp commented Jul 24, 2025

Uh oh!

deandreamatias commented Jul 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ArturAssisComp commented Feb 6, 2025 •

edited

Loading

codecov bot commented Feb 6, 2025 •

edited

Loading

ArturAssisComp commented Feb 27, 2025 •

edited by deandreamatias

Loading

ArturAssisComp commented Mar 28, 2025 •

edited

Loading

deandreamatias commented Mar 29, 2025 •

edited

Loading

deandreamatias commented Mar 30, 2025 •

edited

Loading