Refactor code

[deandreamatias]

Thanks to all contribution and specially to @martijn00, this package increase the number of validators available to use. This changes, open a new situation to solve that is: How separated the validators?

Currently, we have a form_builder_validators.dart file with all validators and form_field_validator_extensions.dart with some extension methods.
To avoid more than 1000 lines of code on form_builder_validators.dart, I think that need refactor FormBuilderValidators class.

Things that we need to reach:

• Redistribute lines of code in different files
• Also, create tests files separated
• Avoid, ever than possible, breaking changes for users
• Improve a way to find the code
• Document more easily for users and maintainers

Proposes:

1. Create a class for each validator, with responsibilities of this validator, like:

import 'package:flutter/widgets.dart';

import '../../localization/l10n.dart';

/// [FormFieldValidator] that requires the field's value to be a valid email address.
/// This validator checks if the field's value is a valid email address.
///
/// ## Parameters:
/// - [errorText] The error message to display when the email is invalid.
///
/// {@macro email_template}
class EmailValidator {
  static FormFieldValidator<String> validator({
    String? errorText,
  }) =>
      (valueCandidate) =>
          (valueCandidate?.isNotEmpty ?? false) && !_isEmail(valueCandidate!)
              ? errorText ?? FormBuilderLocalizations.current.emailErrorText
              : null;
}

/// {@template email_template}
/// This regex matches an email address.
///
/// - It allows various characters, including letters, digits, and special characters.
/// - It supports international characters.
/// - It checks for the presence of an "@" symbol followed by a valid domain name.
///
/// Examples: user@example.com, user.name+tag@example.co.uk
/// {@endtemplate}
RegExp _email = RegExp(
  r"^((([a-z]|\d|[!#\$%&'*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))$",
);

/// check if the string [str] is an email
bool _isEmail(String str) => _email.hasMatch(str.toLowerCase());

2. Call this class on , like:

  static FormFieldValidator<String> email({String? errorText}) =>
      EmailValidator.validator(errorText: errorText);

3. Create templates and use macros for dart documentation: TODO
4. Create tests for each validator class
5. Divide this validator classes by folders
   
6. Improve documentation on readme
7. Maybe, create abstract or other base class to reuse structure

[martijn00]

I agree with this proposal that a cleanup is good. Personally i don't mind a breaking change to fix some fundamental things. I think the null and empty check needs to be aligned on all of them. Maybe it is possible to make 1 check for null or empty and return the same message on that check and then if not continue to the real validator?

To duplicate every method in the main file is not great for maintainability. I'm trying to think of other ways to keep backwards compat, maybe using part of, but can't figure it out yet.

How would you imagine a base or abstract class or method? Somthing like this:

abstract class BaseValidator<T> {
  final String? errorText;

  BaseValidator({this.errorText});

  String? validate(T? valueCandidate);

  String? call(T? valueCandidate) {
    if (valueCandidate == null ||
        (valueCandidate is String && valueCandidate.trim().isEmpty) ||
        (valueCandidate is Iterable && valueCandidate.isEmpty) ||
        (valueCandidate is Map && valueCandidate.isEmpty)) {
      return errorText ?? FormBuilderLocalizations.current.requiredErrorText;
    }
    return validate(valueCandidate);
  }
}

Example:

class MaxValidator<T> extends BaseValidator<T> {
  final num max;
  final bool inclusive;

  MaxValidator({required this.max, this.inclusive = true, String? errorText}) : super(errorText: errorText);

  @override
  String? validate(T? valueCandidate) {
    final number = valueCandidate is num
        ? valueCandidate
        : num.tryParse(valueCandidate.toString());

    if (number != null && (inclusive ? number > max : number >= max)) {
      return errorText ?? FormBuilderLocalizations.current.maxErrorText(max);
    }
    return null;
  }
}

Example using type:

class MinWordsCountValidator extends BaseValidator<String> {
  final int minCount;
  final bool allowEmpty;

  MinWordsCountValidator({
    required this.minCount,
    this.allowEmpty = false,
    String? errorText,
  }) : super(errorText: errorText);

  @override
  String? validate(String? valueCandidate) {
    int valueWordsCount = 0;

    if (valueCandidate != null && valueCandidate.trim().isNotEmpty) {
      valueWordsCount = valueCandidate.trim().split(RegExp(r'\s+')).length;
    }

    if (valueWordsCount < minCount && (!allowEmpty || valueWordsCount > 0)) {
      return errorText ??
          FormBuilderLocalizations.current.minWordsCountErrorText(minCount);
    }
    return null;
  }
}

Sample with regex that user can change:

/// Default email regex pattern
RegExp _defaultEmailRegex = RegExp(
  r"^((([a-z]|\d|[!#\$%&'*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([a-z]|\d|[\u00A0-\xD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\xD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\xD7FF\uF900-\xFDCF\uFDF0-\xFFEF])*([a-z]|\d|[\u00A0-\xD7FF\uF900-\xFDCF\uFDF0-\xFFEF])))\.)+(([a-z]|[\u00A0-\xD7FF\uF900-\xFDCF\uFDF0-\xFFEF])|(([a-z]|[\u00A0-\xD7FF\uF900-\xFDCF\uFDF0-\xFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\xD7FF\uF900-\xFDCF\uFDF0-\xFFEF])*([a-z]|[\u00A0-\xD7FF\uF900-\xFDCF\uFDF0-\xFFEF])))$",
);

class EmailValidator extends BaseValidator<String> {
  final RegExp emailRegex;

  EmailValidator({
    String? errorText,
    RegExp? emailRegex,
  })  : emailRegex = emailRegex ?? _defaultEmailRegex,
        super(errorText: errorText);

  @override
  String? validate(String? valueCandidate) {
    return emailRegex.hasMatch(valueCandidate!.toLowerCase())
        ? null
        : errorText ?? FormBuilderLocalizations.current.emailErrorText;
  }
}

Would it be an idea to let users override the regex or check for a validator? Or maybe implement their own in the user code and add it to the validators using an interface?

[deandreamatias]

Yeah @martijn00, a breaking change to improve package is nice, but that should try to avoid.

About the suggestions:

1. The part of is a thing that Dart isn't recommend for no generation codes https://dart.dev/effective-dart/usage
2. I love it the way to use call and validate methods on abstract class

I will create a new PR with a sample propose with one example of each type validator and we can discuss more about the final picture

[deandreamatias]

PR created #110