Introduce new Form validation method #135578

SharbelOkzan · 2023-09-27T10:06:21Z

Introduced validateGranually which, apart from announcing the errors to the UI, returns a Map<Key, bool> providing more granular validation details: The results of calling validate on each FormField and their corresponding widget keys.

related issue: FormState validation method to return a Map of the validation status of children FormField(s) #135363

Pre-launch Checklist

I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
I read the [Tree Hygiene] wiki page, which explains my responsibilities.
I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
I signed the [CLA].
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is [test-exempt].
All existing and new tests are passing.

google-cla · 2023-09-27T10:06:25Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

LongCatIsLooong · 2023-09-29T00:40:32Z

packages/flutter/lib/src/widgets/form.dart

+  /// to the invalid field(s) using their widget key(s).
+  ///
+  /// The form will rebuild to report the results.
+  Map<Key, bool> validateGranually() {


Maybe just return a collection of fields that hasError?

Also the method name doesn't seem very self-explanatory when I first read it.

Maybe just return a collection of fields that hasError?

I'm avoiding returning the field itself because FormFieldState doesn't look like a class that's meant to be exposed to a public API. Otherwise, why _fields in FormState has no public getter in the first place? imo FormFieldState is a public class only to be used as a param to the builder when extending FormField.

Please lmk if you disagree. In that case, we have two better approaches to achieving #135363 :

We can add a public getter for _fields and revert all the changes, as the user would be able to call isValid on the fields individually.

We return a collection of all the fields with error as you're suggesting, thus resolving your other comment below regarding only including keyed fields.

Also the method name doesn't seem very self-explanatory when I first read it.

I totally agree but couldn't come up with a better name. Any suggestions?

Maybe:

validateAndGetResults

validateWithResults

getInvalidFields (if we decided to return only the fields with error as you're suggesting)

..?
Optimally, I'd call this method validate and call the old method validateAll, but it's a breaking change so I don't think it's an option.

FormFieldState is meant to be public I think (it has public methods, e.g., https://master-api.flutter.dev/flutter/widgets/FormFieldState/save.html). Also Keys aren't necessarily unique.

@LongCatIsLooong I think it's the responsibility of the user to use unique keys for widgets that share a parent, otherwise they will get a "Duplicate Key found" error

Yeah but FormFields don't have to share a parent. The Form just has to be the ancestor of all the fields.

@LongCatIsLooong They will still get "Duplicate Key found" error in that case too. Using unique keys is the user's responsibility, even before this pr.

While GlobalKeys must be unique in the widget tree, Keys don't have to be unique.

packages/flutter/lib/src/widgets/form.dart

LongCatIsLooong · 2023-09-29T00:45:19Z

packages/flutter/lib/src/widgets/form.dart

    bool hasError = false;
    String errorMessage = '';
    for (final FormFieldState<dynamic> field in _fields) {
      hasError = !field.validate() || hasError;
      errorMessage += field.errorText ?? '';
+      final Key? key = field.widget.key;
+      if (key != null) {
+        fieldsValidationStatus[key] = field.validate();


validate() is called twice in this method.

Also I think we probably shouldn't change _validate's implementation like this. validate only returns a bool and the Map populated ends up getting thrown away.

validate() is called twice in this method.

You're right 👍 I'll fix.

the Map populated ends up getting thrown away.

The map is used in the new method validateGranulay.
validate and validateGranulay should share the same logic except for the returned value. That's why I added the wrapper class _FormValidationStatus and avoided duplicating code, for example, the code for announcing the error.
I could extract the shared code to a private method and call it in _validate and validateGranualy, but any future changes that involve performing some side effects on validation will also need to be written twice.
It's just an opinion, please lmk if you disagree I'll make the changes by extraction.

@SharbelOkzan Would it work if you passed a optional map to the _validate method?

So it would be

Map<Key, bool> validateGranually() { final Map<Key, bool> results = <Key, bool>{}; _hasInteractedByUser = true; _forceRebuild(); _validate(results); return results; } bool validate() { _hasInteractedByUser = true; _forceRebuild(); return _validate(); } bool _validate([Map<Key, bool>? optionalResults]) { // This can also be _validate({}) for named params. bool hasError = false; String errorMessage = ''; for (final FormFieldState<dynamic> field in _fields) { hasError = !field.validate() || hasError; errorMessage += field.errorText ?? ''; final Key? key = field.widget.key; if (optionalResults != null && key != null) { optionalResults[key] = field.validate(); } } if (errorMessage.isNotEmpty) { final TextDirection directionality = Directionality.of(context); if (defaultTargetPlatform == TargetPlatform.iOS) { unawaited(Future<void>(() async { await Future<void>.delayed(_kIOSAnnouncementDelayDuration); SemanticsService.announce(errorMessage, directionality, assertiveness: Assertiveness.assertive); })); } else { SemanticsService.announce(errorMessage, directionality, assertiveness: Assertiveness.assertive); } } return !hasError; }

@Renzo-Olivares Yes, but I thought pure functions are preferred. Anw I updated pr with your suggestion 👍

Piinks · 2023-10-17T22:14:24Z

(triage) @SharbelOkzan @LongCatIsLooong what's the status of this PR?

Renzo-Olivares · 2023-10-17T22:19:51Z

packages/flutter/lib/src/widgets/form.dart

@@ -293,19 +293,45 @@ class FormState extends State<Form> {
  /// returns true if there are no errors.
  ///
  /// The form will rebuild to report the results.
+  /// See also: [validateGranually]


nit: this should be formatted like other See also: in the framework.

For example from SelectableRegion:

/// See also: /// * [SelectableRegion], which provides an overview of the selection system.

Renzo-Olivares · 2023-10-17T22:37:31Z

packages/flutter/lib/src/widgets/form.dart

@@ -611,3 +637,19 @@ enum AutovalidateMode {
  /// interaction.
  onUserInteraction,
 }
+
+// Used to encapsultae `Form`'s validation state.


nit: encapsultae -> encapsulate.

nit: Form's -> Forms I think.

Renzo-Olivares · 2023-10-17T22:38:02Z

packages/flutter/lib/src/widgets/form.dart

@@ -611,3 +637,19 @@ enum AutovalidateMode {
  /// interaction.
  onUserInteraction,
 }
+
+// Used to encapsultae `Form`'s validation state.
+// Having all vlaues of `fieldsValidationStatus` as true is not a guarantee


nit: vlaues -> values.

Renzo-Olivares · 2023-10-17T22:38:55Z

packages/flutter/lib/src/widgets/form.dart

+// Having all vlaues of `fieldsValidationStatus` as true is not a guarantee
+// of a valid form. Fields with no keys are skipped in this
+// Map.
+// a Form with no validation erros is only represented by setting `isValid` to true.


nit: Capitalize a in this sentence.

nit: erros -> errors.

Renzo-Olivares

Hi @SharbelOkzan, thank you for the contribution! This change sounds reasonable to me, I have made a few comments regarding some implementation details. Let me know what you think.

SharbelOkzan · 2023-10-18T14:36:36Z

Thanks @Renzo-Olivares. Updated, sorry for the many typos

Renzo-Olivares · 2023-10-18T17:13:49Z

packages/flutter/lib/src/widgets/form.dart

@@ -293,18 +293,46 @@ class FormState extends State<Form> {
  /// returns true if there are no errors.
  ///
  /// The form will rebuild to report the results.
+  /// See also:


nit: should have an empty new line before this line.

Hi @Renzo-Olivares , done. Anything else I should fix?

LongCatIsLooong · 2023-10-30T17:08:30Z

See this comment: #135578 (comment).

SharbelOkzan · 2023-11-04T23:42:07Z

@LongCatIsLooong Sorry for the delay, pr updated.

LongCatIsLooong · 2023-11-05T02:12:39Z

packages/flutter/lib/src/widgets/form.dart

@@ -291,18 +291,44 @@ class FormState extends State<Form> {
  /// returns true if there are no errors.
  ///
  /// The form will rebuild to report the results.
+  ///
+  /// See also:
+  ///  * [validateGranularly], which returns a [Map] describing the validation


Looks like it's no longer a Map?

"which also validates descendant FormFields, but instead returns fields with errors" or something similar?

LongCatIsLooong · 2023-11-05T02:20:55Z

packages/flutter/lib/src/widgets/form.dart

  bool validate() {
    _hasInteractedByUser = true;
    _forceRebuild();
    return _validate();
  }

-  bool _validate() {
+
+  /// Validates every [FormField]s that is a descendant of this [Form], and


FormFields -> FormField

LongCatIsLooong · 2023-11-05T02:22:30Z

packages/flutter/lib/src/widgets/form.dart

-  bool _validate() {
+
+  /// Validates every [FormField]s that is a descendant of this [Form], and
+  /// returns a [List] of [FormFieldState] of the invalid field(s) only, if any.


Does the order matter? Should we return an unordered collection instead?

The order could matter. It doesn't have to be predictable but has to be consistent. i.e. validateGranularly().first should return the same field as long as it's still invalid.

I replaced List with Set, but I don't think we can replace it with something not ordered like HashSet. Let me know if you have other collections in mind.

The rest of the comments are addressed too.

LongCatIsLooong · 2023-11-05T02:23:52Z

packages/flutter/lib/src/widgets/form.dart

+  /// Validates every [FormField]s that is a descendant of this [Form], and
+  /// returns a [List] of [FormFieldState] of the invalid field(s) only, if any.
+  ///
+  /// To get the absolute validation value of the Form, Consider using [validate]


Maybe turn this into a "Seealso".

LongCatIsLooong · 2023-11-05T02:25:56Z

packages/flutter/lib/src/widgets/form.dart

+  ///
+  /// To get the absolute validation value of the Form, Consider using [validate]
+  ///
+  /// Common usage of this method is when you need draw the user's attention


Maybe: This method can be useful when ... / can be used to highlight fields with errors.

LongCatIsLooong · 2023-11-05T02:34:47Z

packages/flutter/lib/src/widgets/form.dart

+  /// to the invalid field(s) using their widget key(s).
+  ///
+  /// The form will rebuild to report the results.
+  List<FormFieldState<dynamic>> validateGranularly() {


nit: dynamic -> Object?

LongCatIsLooong · 2023-11-05T02:37:33Z

packages/flutter/lib/src/widgets/form.dart

+  ///
+  /// The form will rebuild to report the results.
+  List<FormFieldState<dynamic>> validateGranularly() {
+    final List<FormFieldState<dynamic>> invalidFields = List<FormFieldState<dynamic>>.empty(growable: true);


use List literal to instantiate this instead? (also why List?)

LongCatIsLooong · 2023-12-05T23:15:48Z

packages/flutter/lib/src/widgets/form.dart

+  /// returns a [Set] of [FormFieldState] of the invalid field(s) only, if any.
+  ///
+  /// This method can be useful to highlight field(s) with errors,
+  /// possibly using their widget key(s).


Looks like the documentation here needs updating?

It still holds IMO. The widget keys are still most likely what the user will use to highlight fields with errors on the screen.

If you have the states you don't need keys no?

^^ maybe this can just be This method can be useful to highlight field(s) with errors.

LongCatIsLooong · 2023-12-05T23:19:51Z

packages/flutter/lib/src/widgets/form.dart

+  ///
+  /// See also:
+  ///  * [validate], which also validates descendant [FormField]s,
+  /// and return true if there are no errors


missing "." at the end.

nit: "but returns a boolean value indicating whether the [Form] has invalid user inputs" or something like that?

That's actually the docs for validate, it was there before this pr, I just copied it to the "see also".

LongCatIsLooong · 2023-12-05T23:23:21Z

packages/flutter/lib/src/widgets/form.dart

+  ///
+  /// See also:
+  ///  * [validateGranularly], which also validates descendant [FormField]s,
+  /// but instead returns a [Set] of fields with errors


missing "." at the end of the sentence.

LongCatIsLooong

LGTM modulo nits.

LongCatIsLooong · 2023-12-18T19:18:59Z

packages/flutter/lib/src/widgets/form.dart

+  /// returns a [Set] of [FormFieldState] of the invalid field(s) only, if any.
+  ///
+  /// This method can be useful to highlight field(s) with errors,
+  /// possibly using their widget key(s).


If you have the states you don't need keys no?

Renzo-Olivares

LGTM pending the comment regarding keys.

SharbelOkzan · 2024-01-03T22:38:56Z

LGTM pending the comment regarding keys.

Thanks @Renzo-Olivares. Updated.

flutter/flutter@126302d...b840a60 2024-01-10 [email protected] Roll Flutter Engine from 3269fd84460d to b361a60ae224 (1 revision) (flutter/flutter#141271) 2024-01-10 [email protected] Roll Flutter Engine from a5d446da5495 to 3269fd84460d (1 revision) (flutter/flutter#141264) 2024-01-10 [email protected] Roll Flutter Engine from 3ccf66bed335 to a5d446da5495 (2 revisions) (flutter/flutter#141252) 2024-01-10 [email protected] Roll Flutter Engine from e57e418c02ae to 3ccf66bed335 (1 revision) (flutter/flutter#141241) 2024-01-10 [email protected] Roll Flutter Engine from 7e6f3d847e01 to e57e418c02ae (1 revision) (flutter/flutter#141240) 2024-01-10 [email protected] Roll Flutter Engine from 1cf2e0a603c7 to 7e6f3d847e01 (1 revision) (flutter/flutter#141237) 2024-01-10 [email protected] Roll Flutter Engine from 32bbf8be8d2c to 1cf2e0a603c7 (1 revision) (flutter/flutter#141232) 2024-01-10 [email protected] Roll Flutter Engine from 5b9d2132b7cd to 32bbf8be8d2c (1 revision) (flutter/flutter#141229) 2024-01-10 [email protected] Roll Flutter Engine from 941f268fc8bb to 5b9d2132b7cd (1 revision) (flutter/flutter#141228) 2024-01-10 [email protected] Roll Flutter Engine from 542fea9edae4 to 941f268fc8bb (3 revisions) (flutter/flutter#141224) 2024-01-10 [email protected] `NestedScrollView`'s outer scrollable jumping with `BouncingScrollPhysics` due to `double` precision errors (flutter/flutter#138319) 2024-01-10 [email protected] Roll Flutter Engine from 8c1501f3956d to 542fea9edae4 (1 revision) (flutter/flutter#141217) 2024-01-10 [email protected] Fix or except leaks. (flutter/flutter#141081) 2024-01-09 [email protected] Roll Flutter Engine from 693af0c699c5 to 8c1501f3956d (1 revision) (flutter/flutter#141215) 2024-01-09 [email protected] TextStyle: In copyWith, stop ignoring debugLabel when receiver has none (flutter/flutter#141141) 2024-01-09 [email protected] Roll Flutter Engine from a35e3b026e1d to 693af0c699c5 (5 revisions) (flutter/flutter#141209) 2024-01-09 [email protected] Replace deprecated `exists` in podhelper.rb (flutter/flutter#141169) 2024-01-09 [email protected] Correctly handle null case in ProcessText.queryTextActions (flutter/flutter#141205) 2024-01-09 [email protected] Add environment variable to leak tracking bots. (flutter/flutter#141137) 2024-01-09 [email protected] Reapply "Dynamic view sizing" (#140165) (flutter/flutter#140918) 2024-01-09 [email protected] Introduce new Form validation method (flutter/flutter#135578) 2024-01-09 [email protected] Update `RouteObserver` example and fix an error thrown (flutter/flutter#141166) 2024-01-09 [email protected] Upgrade leak_tracker. (flutter/flutter#141153) 2024-01-09 [email protected] [ci.yaml] Do not run packaging test on presubmit (flutter/flutter#141192) 2024-01-09 [email protected] Roll Flutter Engine from 036b39fa47fa to a35e3b026e1d (6 revisions) (flutter/flutter#141191) 2024-01-09 [email protected] Run tests on iOS 16 or iOS 17 (flutter/flutter#141178) 2024-01-09 [email protected] Remove conditions that depend on order. (flutter/flutter#141183) 2024-01-09 [email protected] Roll Flutter Engine from b3c8597df0e2 to 036b39fa47fa (1 revision) (flutter/flutter#141179) 2024-01-09 [email protected] resolved the issue of indeterminate CircularProgressIndicator.adaptive on Darwin (flutter/flutter#140947) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

introduced validateGranually to FormState

03dbdfe

github-actions bot added the framework flutter/packages/flutter repository. See also f: labels. label Sep 27, 2023

Removed taboo words from comments

58b69f3

Renzo-Olivares added the a: text input Entering text in a text field or keyboard related problems label Sep 27, 2023

Renzo-Olivares mentioned this pull request Sep 28, 2023

FormState validation method to return a Map of the validation status of children FormField(s) #135363

Closed

2 tasks

Renzo-Olivares requested review from LongCatIsLooong and Renzo-Olivares September 28, 2023 21:51

LongCatIsLooong reviewed Sep 29, 2023

View reviewed changes

Renzo-Olivares reviewed Oct 17, 2023

View reviewed changes

SharbelOkzan added 3 commits October 18, 2023 16:20

fix typos and docs formatting

bccf8c5

Use a Map reference to return validation results

1c43aee

Remove duplicated method call

05d300b

Remove deleted class docs

53b0e83

Renzo-Olivares reviewed Oct 18, 2023

View reviewed changes

added empty line to docs

7de28b0

SharbelOkzan requested review from Renzo-Olivares and LongCatIsLooong October 28, 2023 09:32

SharbelOkzan added 2 commits November 4, 2023 23:52

return List of invalid fields instead of a Map

60bb5da

Merge remote-tracking branch 'upstream/master'

edabb16

LongCatIsLooong reviewed Nov 5, 2023

View reviewed changes

use Set instead of a List

bfbfd5b

SharbelOkzan requested a review from LongCatIsLooong November 11, 2023 18:44

LongCatIsLooong reviewed Dec 5, 2023

View reviewed changes

fix punctuation

674febb

github-actions bot removed the a: text input Entering text in a text field or keyboard related problems label Dec 16, 2023

Merge remote-tracking branch 'upstream/master'

97d8e29

SharbelOkzan requested a review from LongCatIsLooong December 16, 2023 16:51

LongCatIsLooong approved these changes Dec 18, 2023

View reviewed changes

Merge branch 'master' into master

904a1c9

Renzo-Olivares approved these changes Jan 2, 2024

View reviewed changes

Update validateGranularly doc comments

01e22aa

Renzo-Olivares added the autosubmit Merge PR when tree becomes green via auto submit App label Jan 9, 2024

auto-submit bot merged commit 0c40f21 into flutter:master Jan 9, 2024

engine-flutter-autoroll mentioned this pull request Jan 10, 2024

Roll Flutter from 126302dfb44c to b840a60d7d3f (29 revisions) flutter/packages#5855

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jan 10, 2024

0c40f21 Introduce new Form validation method (flutter/flutter#135578)

469a2cf

HansMuller mentioned this pull request Jan 19, 2024

Flutter Framework Team: Notable Commits #121415

Closed

tomarra mentioned this pull request May 23, 2024

Evaluate New Form Validation in Flutter 3.22.0 VeryGoodOpenSource/formz#122

Open

deandreamatias mentioned this pull request Jan 5, 2025

Implement the API modifications flutter-form-builder-ecosystem/form_builder_validators#129

Merged

5 tasks

Introduce new Form validation method #135578

Introduce new Form validation method #135578

Uh oh!

Conversation

SharbelOkzan commented Sep 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

google-cla bot commented Sep 27, 2023

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!

Choose a reason for hiding this comment

Uh oh!

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!

Piinks commented Oct 17, 2023

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!

Renzo-Olivares left a comment

Choose a reason for hiding this comment

Uh oh!

SharbelOkzan commented Oct 18, 2023

Uh oh!

Renzo-Olivares Oct 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LongCatIsLooong commented Oct 30, 2023

Uh oh!

SharbelOkzan commented Nov 4, 2023

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!

SharbelOkzan commented Sep 27, 2023 •

edited

Loading

Renzo-Olivares Oct 18, 2023 •

edited

Loading