form_builder_validators Improve documentation readme about migration

Connection with issue(s)

Close #???

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

Feb 06 '25 13:02 ArturAssisComp

@deandreamatias I created this PR to do the item 2

Feb 06 '25 13:02 ArturAssisComp

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 :warning:
lib/src/validators/string_validators.dart	0.00%	1 Missing :warning:

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%)`	:arrow_down:

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

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

Feb 06 '25 14:02 codecov[bot]

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.
[x] 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

[x] 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.
[x] 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.
[x] 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.
[x] 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

[x] 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.
[x] 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.
[x] TODO FormBuilderValidators.lowercase() - requires the field's value to be lowercase.
[x] 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.
[x] TODO FormBuilderValidators.maxWordsCount() - requires the word count of the field's value to be less than or equal to the provided maximum count.
[x] 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

[ ] TODO FormBuilderValidators.city() - requires the field's value to be a valid city name.
[ ] TODO FormBuilderValidators.country() - requires the field's value to be a valid country name.
[ ] TODO FormBuilderValidators.firstName() - requires the field's value to be a valid first name.
[ ] TODO FormBuilderValidators.lastName() - requires the field's value to be a valid last name.
[ ] TODO FormBuilderValidators.passportNumber() - requires the field's value to be a valid passport number.
[ ] TODO FormBuilderValidators.ssn() - requires the field's to be a valid SSN (Social Security Number).
[ ] TODO FormBuilderValidators.state() - requires the field's value to be a valid state name.
[ ] TODO FormBuilderValidators.street() - requires the field's value to be a valid street name.
[ ] TODO FormBuilderValidators.username() - requires the field's to be a valid username that matched required conditions.
[ ] TODO FormBuilderValidators.zipCode() - requires the field's to be a valid zip code.

Feb 27 '25 21:02 ArturAssisComp

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

Feb 28 '25 06:02 deandreamatias

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')`

Mar 10 '25 13:03 ArturAssisComp

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.

Mar 24 '25 18:03 deandreamatias

~~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.

Mar 28 '25 22:03 ArturAssisComp

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

Mar 29 '25 00:03 ArturAssisComp

@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 😅

Mar 29 '25 09:03 deandreamatias

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)

Mar 30 '25 10:03 deandreamatias

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.

Apr 17 '25 16:04 deandreamatias

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

Jul 24 '25 22:07 ArturAssisComp

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

Jul 25 '25 07:07 deandreamatias