[State Restoration] Restorable FormField and TextFormField (#78835)

* Restorable FormField and TextFormField

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

@@ -4,6 +4,8 @@
 
 import 'framework.dart';
 import 'navigator.dart';
+import 'restoration.dart';
+import 'restoration_properties.dart';
 import 'will_pop_scope.dart';
 
 /// An optional container for grouping together multiple form field widgets
@@ -170,7 +172,7 @@ class FormState extends State<Form> {
     widget.onChanged?.call();
 
     _hasInteractedByUser = _fields
-        .any((FormFieldState<dynamic> field) => field._hasInteractedByUser);
+        .any((FormFieldState<dynamic> field) => field._hasInteractedByUser.value);
     _forceRebuild();
   }
 
@@ -331,14 +333,15 @@ class FormField<T> extends StatefulWidget {
     this.autovalidate = false,
     this.enabled = true,
     AutovalidateMode? autovalidateMode,
+    this.restorationId,
   }) : assert(builder != null),
        assert(
          autovalidate == false ||
          autovalidate == true && autovalidateMode == null,
          'autovalidate and autovalidateMode should not be used together.',
        ),
-        autovalidateMode = autovalidateMode ??
-          (autovalidate ? AutovalidateMode.always : AutovalidateMode.disabled),
+       autovalidateMode = autovalidateMode ??
+         (autovalidate ? AutovalidateMode.always : AutovalidateMode.disabled),
        super(key: key);
 
   /// An optional method to call with the final value when the form is saved via
@@ -399,16 +402,30 @@ class FormField<T> extends StatefulWidget {
   )
   final bool autovalidate;
 
+  /// Restoration ID to save and restore the state of the form field.
+  ///
+  /// Setting the restoration ID to a non-null value results in whether or not
+  /// the form field validation persists.
+  ///
+  /// The state of this widget is persisted in a [RestorationBucket] claimed
+  /// from the surrounding [RestorationScope] using the provided restoration ID.
+  ///
+  /// See also:
+  ///
+  ///  * [RestorationManager], which explains how state restoration works in
+  ///    Flutter.
+  final String? restorationId;
+
   @override
   FormFieldState<T> createState() => FormFieldState<T>();
 }
 
 /// The current state of a [FormField]. Passed to the [FormFieldBuilder] method
 /// for use in constructing the form field's widget.
-class FormFieldState<T> extends State<FormField<T>> {
-  T? _value;
-  String? _errorText;
-  bool _hasInteractedByUser = false;
+class FormFieldState<T> extends State<FormField<T>> with RestorationMixin {
+  late T? _value = widget.initialValue;
+  final RestorableStringN _errorText = RestorableStringN(null);
+  final RestorableBool _hasInteractedByUser = RestorableBool(false);
 
   /// The current value of the form field.
   T? get value => _value;
@@ -416,10 +433,10 @@ class FormFieldState<T> extends State<FormField<T>> {
   /// The current validation error returned by the [FormField.validator]
   /// callback, or null if no errors have been triggered. This only updates when
   /// [validate] is called.
-  String? get errorText => _errorText;
+  String? get errorText => _errorText.value;
 
   /// True if this field has any validation errors.
-  bool get hasError => _errorText != null;
+  bool get hasError => _errorText.value != null;
 
   /// True if the current value is valid.
   ///
@@ -440,8 +457,8 @@ class FormFieldState<T> extends State<FormField<T>> {
   void reset() {
     setState(() {
       _value = widget.initialValue;
-      _hasInteractedByUser = false;
-      _errorText = null;
+      _hasInteractedByUser.value = false;
+      _errorText.value = null;
     });
     Form.of(context)?._fieldDidChange();
   }
@@ -462,7 +479,7 @@ class FormFieldState<T> extends State<FormField<T>> {
 
   void _validate() {
     if (widget.validator != null)
-      _errorText = widget.validator!(_value);
+      _errorText.value = widget.validator!(_value);
   }
 
   /// Updates this field's state to the new value. Useful for responding to
@@ -474,7 +491,7 @@ class FormFieldState<T> extends State<FormField<T>> {
   void didChange(T? value) {
     setState(() {
       _value = value;
-      _hasInteractedByUser = true;
+      _hasInteractedByUser.value = true;
     });
     Form.of(context)?._fieldDidChange();
   }
@@ -492,9 +509,12 @@ class FormFieldState<T> extends State<FormField<T>> {
   }
 
   @override
-  void initState() {
-    super.initState();
-    _value = widget.initialValue;
+  String? get restorationId => widget.restorationId;
+
+  @override
+  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
+    registerForRestoration(_errorText, 'error_text');
+    registerForRestoration(_hasInteractedByUser, 'has_interacted_by_user');
   }
 
   @override
@@ -511,7 +531,7 @@ class FormFieldState<T> extends State<FormField<T>> {
           _validate();
           break;
         case AutovalidateMode.onUserInteraction:
-          if (_hasInteractedByUser) {
+          if (_hasInteractedByUser.value) {
             _validate();
           }
           break;

packages/flutter/test/material/text_form_field_restoration_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+const String text = 'Hello World! How are you? Life is good!';
+const String alternativeText = 'Everything is awesome!!';
+
+void main() {
+  testWidgets('TextField restoration', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const MaterialApp(
+        restorationScopeId: 'app',
+        home: TestWidget(),
+      ),
+    );
+
+    await restoreAndVerify(tester);
+  });
+
+  testWidgets('TextField restoration with external controller', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const MaterialApp(
+        restorationScopeId: 'root',
+        home: TestWidget(
+          useExternal: true,
+        ),
+      ),
+    );
+
+    await restoreAndVerify(tester);
+  });
+
+  testWidgets('State restoration (No Form ancestor) - onUserInteraction error text validation', (WidgetTester tester) async {
+    String? errorText(String? value) => '$value/error';
+    late GlobalKey<FormFieldState<String>> formState;
+
+    Widget builder() {
+      return MaterialApp(
+        restorationScopeId: 'app',
+        home: MediaQuery(
+          data: const MediaQueryData(devicePixelRatio: 1.0),
+          child: Directionality(
+            textDirection: TextDirection.ltr,
+            child: Center(
+              child: StatefulBuilder(
+                builder: (BuildContext context, StateSetter state) {
+                  formState = GlobalKey<FormFieldState<String>>();
+                  return Material(
+                    child: TextFormField(
+                      key: formState,
+                      autovalidateMode: AutovalidateMode.onUserInteraction,
+                      restorationId: 'text_form_field',
+                      initialValue: 'foo',
+                      validator: errorText,
+                    ),
+                  );
+                },
+              ),
+            ),
+          ),
+        ),
+      );
+    }
+
+    await tester.pumpWidget(builder());
+
+    // No error text is visible yet.
+    expect(find.text(errorText('foo')!), findsNothing);
+
+    await tester.enterText(find.byType(TextFormField), 'bar');
+    await tester.pumpAndSettle();
+    expect(find.text(errorText('bar')!), findsOneWidget);
+
+    final TestRestorationData data = await tester.getRestorationData();
+    await tester.restartAndRestore();
+    // Error text should be present after restart and restore.
+    expect(find.text(errorText('bar')!), findsOneWidget);
+
+    // Resetting the form state should remove the error text.
+    formState.currentState!.reset();
+    await tester.pumpAndSettle();
+    expect(find.text(errorText('bar')!), findsNothing);
+    await tester.restartAndRestore();
+    // Error text should still be removed after restart and restore.
+    expect(find.text(errorText('bar')!), findsNothing);
+
+    await tester.restoreFrom(data);
+    expect(find.text(errorText('bar')!), findsOneWidget);
+  });
+
+  testWidgets('State Restoration (No Form ancestor) - validator sets the error text only when validate is called', (WidgetTester tester) async {
+    String? errorText(String? value) => '$value/error';
+    late GlobalKey<FormFieldState<String>> formState;
+
+    Widget builder(AutovalidateMode mode) {
+      return MaterialApp(
+        restorationScopeId: 'app',
+        home: MediaQuery(
+          data: const MediaQueryData(devicePixelRatio: 1.0),
+          child: Directionality(
+            textDirection: TextDirection.ltr,
+            child: Center(
+              child: StatefulBuilder(
+                builder: (BuildContext context, StateSetter state) {
+                  formState = GlobalKey<FormFieldState<String>>();
+                  return Material(
+                    child: TextFormField(
+                      key: formState,
+                      restorationId: 'form_field',
+                      autovalidateMode: mode,
+                      initialValue: 'foo',
+                      validator: errorText,
+                    ),
+                  );
+                },
+              ),
+            ),
+          ),
+        ),
+      );
+    }
+
+    // Start off not autovalidating.
+    await tester.pumpWidget(builder(AutovalidateMode.disabled));
+
+    Future<void> checkErrorText(String testValue) async {
+      formState.currentState!.reset();
+      await tester.pumpWidget(builder(AutovalidateMode.disabled));
+      await tester.enterText(find.byType(TextFormField), testValue);
+      await tester.pump();
+
+      // We have to manually validate if we're not autovalidating.
+      expect(find.text(errorText(testValue)!), findsNothing);
+      formState.currentState!.validate();
+      await tester.pump();
+      expect(find.text(errorText(testValue)!), findsOneWidget);
+      final TestRestorationData data = await tester.getRestorationData();
+      await tester.restartAndRestore();
+      // Error text should be present after restart and restore.
+      expect(find.text(errorText(testValue)!), findsOneWidget);
+
+      formState.currentState!.reset();
+      await tester.pumpAndSettle();
+      expect(find.text(errorText(testValue)!), findsNothing);
+
+      await tester.restoreFrom(data);
+      expect(find.text(errorText(testValue)!), findsOneWidget);
+
+      // Try again with autovalidation. Should validate immediately.
+      formState.currentState!.reset();
+      await tester.pumpWidget(builder(AutovalidateMode.always));
+      await tester.enterText(find.byType(TextFormField), testValue);
+      await tester.pump();
+
+      expect(find.text(errorText(testValue)!), findsOneWidget);
+      await tester.restartAndRestore();
+      // Error text should be present after restart and restore.
+      expect(find.text(errorText(testValue)!), findsOneWidget);
+    }
+
+    await checkErrorText('Test');
+    await checkErrorText('');
+  });
+}
+
+Future<void> restoreAndVerify(WidgetTester tester) async {
+  expect(find.text(text), findsNothing);
+  expect(tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels, 0);
+
+  await tester.enterText(find.byType(TextFormField), text);
+  await skipPastScrollingAnimation(tester);
+  expect(tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels, 0);
+
+  await tester.drag(find.byType(Scrollable), const Offset(0, -80));
+  await skipPastScrollingAnimation(tester);
+
+  expect(find.text(text), findsOneWidget);
+  expect(tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels, 60);
+
+  await tester.restartAndRestore();
+
+  expect(find.text(text), findsOneWidget);
+  expect(tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels, 60);
+
+  final TestRestorationData data = await tester.getRestorationData();
+
+  await tester.enterText(find.byType(TextFormField), alternativeText);
+  await skipPastScrollingAnimation(tester);
+  await tester.drag(find.byType(Scrollable), const Offset(0, 80));
+  await skipPastScrollingAnimation(tester);
+
+  expect(find.text(text), findsNothing);
+  expect(tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels, isNot(60));
+
+  await tester.restoreFrom(data);
+
+  expect(find.text(text), findsOneWidget);
+  expect(tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels, 60);
+}
+
+class TestWidget extends StatefulWidget {
+  const TestWidget({Key? key, this.useExternal = false}) : super(key: key);
+
+  final bool useExternal;
+
+  @override
+  TestWidgetState createState() => TestWidgetState();
+}
+
+class TestWidgetState extends State<TestWidget> with RestorationMixin {
+  final RestorableTextEditingController controller = RestorableTextEditingController();
+
+  @override
+  String get restorationId => 'widget';
+
+  @override
+  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
+    registerForRestoration(controller, 'controller');
+  }
+
+  @override
+  void dispose() {
+    controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Material(
+      child: Align(
+        alignment: Alignment.center,
+        child: SizedBox(
+          width: 50,
+          child: TextFormField(
+            restorationId: 'text',
+            maxLines: 3,
+            controller: widget.useExternal ? controller.value : null,
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+Future<void> skipPastScrollingAnimation(WidgetTester tester) async {
+  await tester.pump();
+  await tester.pump(const Duration(milliseconds: 200));
+}