Form-Level Validation Rule

[eraps7]

Is your feature request related to a problem? Please describe.
Currently, the formz package excels at validating individual form fields and separating the validation logic. However, it lacks the ability to define a validation rule that applies to the entire form.

For instance, consider a use case where the user can look up a an employee by any 3 fields: phone number, first name, and last name. While formz allows validation for individual fields (e.g., ensuring phone number has 10 digits and names have at least two characters), there's no way to enforce that at least one field must be filled before submitting the search.

Describe the solution you'd like
One possible solution would involve introducing a mechanism to define form-level validation rules that can orchestrate the execution of individual field validators. In the example above, the form level validator would perform validation that least one of the three fields (phone number, first name, or last name) has a value before allowing form submission then to orchestrate the execution of individual field validators.

\\Something like
\\Form - Level validator
overide
ValidationError? validator(String value) {
  if (isAllSearchParametersEmpty(firstName: firstName, lastName: lastName, phone: phone)) {
    return AtLeastOneFieldNeededError();
  }
  //This idea
  // Directly call field validators here
  final phoneError = phone.validator();
  final firstNameError = firstName.validator();
  final lastNameError = lastName.validator();

  // Combine errors for a holistic form-level validation result
  return ... (logic to aggregate errors and return a representative error)
}

tiny code

/// ValidationError is an abstract class that is used to implement the builder pattern to create a validation error(s).
abstract class ValidationError {
  final String message;

  ValidationError(this.message);
}

I am happy create a pull request and discuss peoples thoughts on the best way to implement this

[codakkk]

Up

[tomarra]

Hi @eraps7 & @codakkk 👋 Thanks for opening this issue!

Overall it seems like what you're proposing here is actually doable with the formz as it exists today. Can we get a summary of the proposed implementation that you would be expecting? That way we can talk through a potential change before anyone invests time in writing code.

I'm going to label this as a P3 given that we don't have any use case driving this need but if either of you would like to help with an implementation and contribute it back I can find cycles from the VGV team to help review.

[codakkk]

Hi @eraps7 & @codakkk 👋 Thanks for opening this issue!

Overall it seems like what you're proposing here is actually doable with the formz as it exists today. Can we get a summary of the proposed implementation that you would be expecting? That way we can talk through a potential change before anyone invests time in writing code.

I'm going to label this as a P3 given that we don't have any use case driving this need but if either of you would like to help with an implementation and contribute it back I can find cycles from the VGV team to help review.

Well taking the following as example:

part 'exercise_form.freezed.dart';

@freezed
class ExerciseForm with _$ExerciseForm, FormzMixin {
  const ExerciseForm._();

  const factory ExerciseForm({
    @Default(ExerciseInput.pure()) ExerciseInput exercise,
    @Default(SetListInput.pure()) SetListInput sets,
    @Default(ExerciseNoteInput.pure()) ExerciseNoteInput note,
  }) = _ExerciseForm;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [
        exercise,
        sets,
        note,
      ];
}

@freezed
class SetForm with _$SetForm, FormzMixin {
  const SetForm._();

  const factory SetForm({
    @Default(RepTypeInput.pure()) RepTypeInput type,
    @Default(RepValueInput.pure()) RepValueInput value,
    @Default(false) bool isAMAP, // As Many As Possible
    @Default('') String note,
  }) = _RepsForm;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [
        type,
        value,
      ];
}

enum SetFormListInputError {
  empty,
}

class SetFormListInput
    extends FormzInput<List<SetForm>, SetFormListInputError> {
  const SetFormListInput.pure([super.value = const []]) : super.pure();

  const SetFormListInput.dirty(super.value) : super.dirty();

  @override
  SetFormListInputError? validator(List<SetForm> value) {
    return value.isEmpty ? SetFormListInputError.empty : null;
  }
}

I have a SetForm which describes a form for a single set in an exercise. Then I have a ExerciseForm which contains a SetFormListInput. The latter just checks whether the SetFormListInput's List<SetForm> is not empty. However, an ExerciseForm is valid only if ExerciseInput, SetListInput, ExerciseNoteInput are valid, thus adding them to the inputs get in ExerciseForm. To ensure accuracy, the SetFormListInput items should also be validated.. Is the following approach correct? Is the SetFormListInput a valid FormzInput?

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [
        exercise,
        sets,
        for (final input in sets.value) ...input.inputs,
        note,
      ];

[tomarra]

@codakkk Thanks for getting back to this and sorry about the delay in our response.

In reviewing this with the team the question came up if the example provided could be done with just pure Dart instead of including Freezed? We want to make sure we are actually fixing an issue in Formz instead of another package.

[codakkk]

@codakkk Thanks for getting back to this and sorry about the delay in our response.

In reviewing this with the team the question came up if the example provided could be done with just pure Dart instead of including Freezed? We want to make sure we are actually fixing an issue in Formz instead of another package.

Hi @tomarra sorry about the delay in my response as well, I've been busy in the past few months.
If I recall the requirement here was to add a validation at Form level.
An example that comes to my mind right now is when I want to use the same FormzInput in more than one Form.

Say for example we have: Form1, Form2 and they both have an EmailInput we want the EmailInput mandatory for Form1 and not for Form2. From my understanding of the library, we have two ways to decide whether an input is mandatory:

1. Write two equal inputs but with different name and make sure it's not empty.
2. Write the Input adding a boolean flag describing whatever the input is mandatory

Case 1

This often leads to code duplication and can be error-prone.

enum EmailValidationError { invalid }

class EmailInput extends FormzInput<String, EmailValidationError>
    with FormzInputErrorCacheMixin {
  EmailInput.pure([super.value = '']) : super.pure();

  EmailInput.dirty([super.value = '']) : super.dirty();

  static final _emailRegExp = RegExp(
    r'^[a-zA-Z\d.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z\d-]+(?:\.[a-zA-Z\d-]+)*$',
  );

  @override
  EmailValidationError? validator(String value) {
    return _emailRegExp.hasMatch(value) ? null : EmailValidationError.invalid;
  }
}


enum MandatoryEmailValidationError { empty, invalid }

class MandatoryEmailInput extends FormzInput<String, MandatoryEmailValidationError>
    with FormzInputErrorCacheMixin {
  MandatoryEmailInput.pure([super.value = '']) : super.pure();

  MandatoryEmailInput.dirty([super.value = '']) : super.dirty();

  static final _emailRegExp = RegExp(
    r'^[a-zA-Z\d.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z\d-]+(?:\.[a-zA-Z\d-]+)*$',
  );

  @override
  MandatoryEmailValidationError? validator(String value) {
    if(value.isEmpty) return MandatoryEmailValidationError.empty;
    return _emailRegExp.hasMatch(value) ? null : MandatoryEmailValidationError.invalid;
  }
}

class Form1 with FormzMixin {
  Form1()  : email = MandatoryEmailInput.pure();

  final MandatoryEmailInput email;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [email];
}

class Form2 with FormzMixin {
  Form1()  : email = EmailInput.pure();

  final EmailInput email;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [email];
}

Case 2

While this reduces code duplication it can be error-prone when using dirty or pure constructor if the isMandatoryflag is not properly maintained.

enum EmailValidationError { empty, invalid }

class EmailInput extends FormzInput<String, EmailValidationError>
    with FormzInputErrorCacheMixin {
  EmailInput.pure(this.isMandatory, [super.value = '']) : super.pure();

  EmailInput.dirty(this.isMandatory, [super.value = '']) : super.dirty();

  final bool isMandatory;

  static final _emailRegExp = RegExp(
    r'^[a-zA-Z\d.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z\d-]+(?:\.[a-zA-Z\d-]+)*$',
  );

  @override
  EmailValidationError? validator(String value) {
    if(isMandatory && value.isEmpty) return EmailValidationError.empty;
    return _emailRegExp.hasMatch(value) ? null : EmailValidationError.invalid;
  }
}

class Form1 with FormzMixin {
  Form1()  : email = EmailInput.pure(true);

  final MandatoryEmailInput email;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [email];
}

class Form2 with FormzMixin {
  Form1()  : email = EmailInput.pure(false);

  final EmailInput email;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [email];
}

What could help in this situation is the following:

enum EmailValidationError { empty, invalid }

class EmailInput extends FormzInput<String, EmailValidationError>
    with FormzInputErrorCacheMixin {
  EmailInput.pure([super.value = '']) : super.pure();

  EmailInput.dirty([super.value = '']) : super.dirty();

  static final _emailRegExp = RegExp(
    r'^[a-zA-Z\d.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z\d-]+(?:\.[a-zA-Z\d-]+)*$',
  );

  @override
  EmailValidationError? validator(String value) {
    return _emailRegExp.hasMatch(value) ? null : EmailValidationError.invalid;
  }
}

enum Form1Errors {
  emptyEmail
}

class Form1 with FormzMixin<Form1Errors> {
  Form1()  : email = EmailInput.pure(true);

  final MandatoryEmailInput email;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [email];

  @override
  Form1Errors? validation() {
     if(email.isPure() || email.value.isEmpty) {
       return Form1Errors.emptyEmail;
     }
     return null;
  }
}

class Form1 with FormzMixin {
  Form1()  : email = EmailInput.pure(false);

  final EmailInput email;

  @override
  List<FormzInput<dynamic, dynamic>> get inputs => [email];
}

Another example is when working with lists of inputs, particularly when we're also interested in the size of the list. I can provide an example if needed.

I might have misunderstood something about the library, but these are my thoughts on the issue.
Feel free to reach out if you have questions. I can also create a pull request if the idea makes sense.