Improve documentation readme about migration

[ArturAssisComp]

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

[ArturAssisComp]

@deandreamatias I created this PR to do the item 2

[codecov]

Codecov Report

Attention: Patch coverage is 95.23810% with 1 line in your changes missing coverage. Please review.

Project coverage is 98.74%. Comparing base (1834d8e) to head (b223f31).
Report is 1 commits behind head on refactor_2024_11.

Files with missing lines	Patch %	Lines
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.74%           
=================================================
  Files                   111      111           
  Lines                  1510     1510           
=================================================
  Hits                   1491     1491           
  Misses                   19       19           

Flag	Coverage Δ
unittests	98.74% <95.23%> (ø)

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]

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

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

[deandreamatias]

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

[ArturAssisComp]

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]

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.