Refactor form field controllers to use AuthenticatorTextFieldController

- Updated all form fields to replace TextEditingController with AuthenticatorTextFieldController.
- Modified constructors and properties across various form fields including ConfirmSignUpFormField, EmailSetupFormField, PhoneNumberField, ResetPasswordFormField, SignInFormField, SignUpFormField, and VerifyUserFormField.
- Adjusted tests to accommodate the new controller type, ensuring compatibility and functionality remain intact.

Author: angelorodem

packages/authenticator/amplify_authenticator/CHANGELOG.md

@@ -1,15 +1,3 @@
-## 2.4.0
-
-### Features
-
-- feat(authenticator): Add TextEditingController support to form fields
-  - Added `AuthenticatorTextFieldController` class for programmatic control of form fields
-  - All text-based form fields now accept an optional `controller` parameter
-  - Enables pre-populating fields (e.g., from GPS/API data) and auto-filling verification codes
-  - Bidirectional sync between controller and internal state
-  - Compatible with standard `TextEditingController` for flexibility
-- feat(authenticator): Allow SignUpFormField inputs to be disabled or hidden so apps can prefill values programmatically or keep legacy attributes off-screen
-
 ## 2.3.8
 
 ### Chores

packages/authenticator/amplify_authenticator/example/lib/authenticator_with_controllers.dart

@@ -97,19 +97,28 @@ class _AuthenticatorWithControllersState
       signUpForm: SignUpForm.custom(
         fields: [
           // Username field with controller - can be pre-populated or modified
-          SignUpFormField.username(controller: _usernameController),
+          SignUpFormField.username(
+            authenticatorTextFieldController: _usernameController,
+          ),
 
           // Email field with controller
-          SignUpFormField.email(controller: _emailController, required: true),
+          SignUpFormField.email(
+            authenticatorTextFieldController: _emailController,
+            required: true,
+          ),
 
           SignUpFormField.password(),
           SignUpFormField.passwordConfirmation(),
 
           // Address field with controller - can be populated from GPS/API
-          SignUpFormField.address(controller: _addressController),
+          SignUpFormField.address(
+            authenticatorTextFieldController: _addressController,
+          ),
 
           // Phone number field with controller
-          SignUpFormField.phoneNumber(controller: _phoneController),
+          SignUpFormField.phoneNumber(
+            authenticatorTextFieldController: _phoneController,
+          ),
         ],
       ),
 

packages/authenticator/amplify_authenticator/lib/amplify_authenticator.dart

@@ -43,7 +43,8 @@ export 'package:amplify_authenticator/src/utils/dial_code_options.dart'
     show DialCodeOptions;
 
 export 'src/controllers/authenticator_text_field_controller.dart';
-export 'src/enums/enums.dart' show AuthenticatorStep, Gender;
+export 'src/enums/enums.dart'
+    show AuthenticatorStep, AuthenticatorTextEnabledOverride, Gender;
 export 'src/l10n/auth_strings_resolver.dart' hide ButtonResolverKeyType;
 export 'src/models/authenticator_exception.dart';
 export 'src/models/totp_options.dart';

packages/authenticator/amplify_authenticator/lib/src/enums/authenticator_text_enabled_override.dart

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/// Enum for overriding the enabled state of a form field.
+enum AuthenticatorTextEnabledOverride {
+  /// Use the default enabled state.
+  defaultSetting,
+
+  /// Force the field to be enabled.
+  enabled,
+
+  /// Force the field to be disabled.
+  disabled,
+}

packages/authenticator/amplify_authenticator/lib/src/enums/enums.dart

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export 'authenticator_step.dart';
+export 'authenticator_text_enabled_override.dart';
 export 'confirm_signin_types.dart';
 export 'confirm_signup_types.dart';
 export 'email_setup_types.dart';

packages/authenticator/amplify_authenticator/lib/src/mixins/authenticator_text_field.dart

@@ -19,7 +19,8 @@ mixin AuthenticatorTextField<
   bool _controllerUpdateScheduled = false;
 
   @protected
-  TextEditingController? get textController => null;
+  TextEditingController? get textController =>
+      widget.authenticatorTextFieldController;
 
   void _maybeUpdateEffectiveController() {
     final controller = textController;
@@ -69,13 +70,30 @@ mixin AuthenticatorTextField<
     if (controller == null) {
       return;
     }
+
+    // If there is a pending controller update, do not overwrite the controller
+    // with the state value, as the state value may be stale.
+    if (_pendingControllerText != null && !force) {
+      return;
+    }
+
     final target = initialValue ?? '';
     final controllerText = controller.text;
+
     if (!force && controllerText == target) {
       _lastSyncedControllerValue = controllerText;
       return;
     }
 
+    // If the controller has changed locally (user input) but the state
+    // has not changed from what we last synced, ignore the state value
+    // as it is likely stale.
+    if (!force &&
+        controllerText != _lastSyncedControllerValue &&
+        target == _lastSyncedControllerValue) {
+      return;
+    }
+
     final normalizedController = controllerText.trimRight();
     final normalizedTarget = target.trimRight();
     if (normalizedController == normalizedTarget) {
@@ -104,18 +122,31 @@ mixin AuthenticatorTextField<
   void didChangeDependencies() {
     super.didChangeDependencies();
     _maybeUpdateEffectiveController();
-    // Schedule both syncs after build completes
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (mounted) {
-        // First sync controller -> state if controller has initial text
-        if (_effectiveController != null &&
-            _lastSyncedControllerValue == null) {
-          _handleControllerChanged();
-        }
+    if (mounted) {
+      // First sync controller -> state if controller has initial text
+      if (_effectiveController != null &&
+          _lastSyncedControllerValue == null &&
+          _effectiveController!.text.isNotEmpty) {
+        final text = _effectiveController!.text;
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          if (!mounted) return;
+          _isApplyingControllerText = true;
+          try {
+            onChanged(text);
+            _lastSyncedControllerValue = text;
+          } finally {
+            _isApplyingControllerText = false;
+          }
+        });
+      } else {
         // Then sync state -> controller to ensure they're in sync
-        _syncControllerText();
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          if (mounted) {
+            _syncControllerText();
+          }
+        });
       }
-    });
+    }
   }
 
   @override
@@ -124,7 +155,7 @@ mixin AuthenticatorTextField<
     _maybeUpdateEffectiveController();
     WidgetsBinding.instance.addPostFrameCallback((_) {
       if (mounted) {
-        _syncControllerText(force: true);
+        _syncControllerText();
       }
     });
   }
@@ -144,7 +175,6 @@ mixin AuthenticatorTextField<
     final hintText = widget.hintText == null
         ? widget.hintTextKey?.resolve(context, inputResolver)
         : widget.hintText!;
-    _maybeUpdateEffectiveController();
     return ValueListenableBuilder<bool>(
       valueListenable: AuthenticatorFormState.of(
         context,

packages/authenticator/amplify_authenticator/lib/src/mixins/authenticator_username_field.dart

@@ -24,7 +24,8 @@ mixin AuthenticatorUsernameField<
   bool _controllerUpdateScheduled = false;
 
   @protected
-  TextEditingController? get textController => null;
+  TextEditingController? get textController =>
+      widget.authenticatorTextFieldController;
 
   void _updateController() {
     final controller = textController;
@@ -96,13 +97,28 @@ mixin AuthenticatorUsernameField<
       return;
     }
 
+    // If there is a pending controller update, do not overwrite the controller
+    // with the state value, as the state value may be stale.
+    if (_pendingControllerText != null && !force) {
+      return;
+    }
+
     final target = initialValue?.username ?? '';
     final controllerText = _controller!.text;
     if (!force && controllerText == target) {
       _lastSyncedText = controllerText;
       return;
     }
 
+    // If the controller has changed locally (user input) but the state
+    // has not changed from what we last synced, ignore the state value
+    // as it is likely stale.
+    if (!force &&
+        controllerText != _lastSyncedText &&
+        target == _lastSyncedText) {
+      return;
+    }
+
     final normalizedController = controllerText.trimRight();
     final normalizedTarget = target.trimRight();
     if (normalizedController == normalizedTarget) {
@@ -132,17 +148,33 @@ mixin AuthenticatorUsernameField<
   void didChangeDependencies() {
     super.didChangeDependencies();
     _updateController();
-    // Schedule both syncs after build completes
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (mounted) {
-        // First sync controller -> state if controller has initial text
-        if (_controller != null && _lastSyncedText == null) {
-          _handleControllerChanged();
-        }
+    if (mounted) {
+      // First sync controller -> state if controller has initial text
+      if (_controller != null &&
+          _lastSyncedText == null &&
+          _controller!.text.isNotEmpty) {
+        final text = _controller!.text;
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          if (!mounted) return;
+          _applyingControllerText = true;
+          try {
+            onChanged(
+              UsernameInput(type: selectedUsernameType, username: text),
+            );
+            _lastSyncedText = text;
+          } finally {
+            _applyingControllerText = false;
+          }
+        });
+      } else {
         // Then sync state -> controller to ensure they're in sync
-        _syncControllerText();
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          if (mounted) {
+            _syncControllerText();
+          }
+        });
       }
-    });
+    }
   }
 
   @override
@@ -151,7 +183,7 @@ mixin AuthenticatorUsernameField<
     _updateController();
     WidgetsBinding.instance.addPostFrameCallback((_) {
       if (mounted) {
-        _syncControllerText(force: true);
+        _syncControllerText();
       }
     });
   }
@@ -366,11 +398,14 @@ mixin AuthenticatorUsernameField<
         requiredOverride: true,
         onChanged: handleChanged,
         validator: validator,
-        enabled: enabled,
+        enabled: enabled
+            ? AuthenticatorTextEnabledOverride.enabled
+            : AuthenticatorTextEnabledOverride.disabled,
         errorMaxLines: errorMaxLines,
         initialValue: state.username,
         autofillHints: autofillHints,
-        controller: textController,
+        authenticatorTextFieldController:
+            textController as AuthenticatorTextFieldController?,
       );
     }
 

packages/authenticator/amplify_authenticator/lib/src/widgets/form_field.dart

@@ -99,12 +99,13 @@ abstract class AuthenticatorFormField<
   final Iterable<String>? autofillHints;
 
   /// Optional text controller exposed by text-driven form fields.
-  TextEditingController? get controller => null;
+  AuthenticatorTextFieldController? get authenticatorTextFieldController =>
+      null;
 
   /// Whether the field can receive manual input.
   ///
   /// When `null`, the widget decides its enabled state.
-  final bool? enabledOverride;
+  final AuthenticatorTextEnabledOverride? enabledOverride;
 
   /// Whether the field should be rendered.
   ///
@@ -143,9 +144,17 @@ abstract class AuthenticatorFormField<
       ..add(EnumProperty<UsernameType?>('usernameType', usernameType))
       ..add(IterableProperty<String>('autofillHints', autofillHints))
       ..add(
-        DiagnosticsProperty<TextEditingController?>('controller', controller),
+        DiagnosticsProperty<AuthenticatorTextFieldController?>(
+          'authenticatorTextFieldController',
+          authenticatorTextFieldController,
+        ),
+      )
+      ..add(
+        EnumProperty<AuthenticatorTextEnabledOverride?>(
+          'enabledOverride',
+          enabledOverride,
+        ),
       )
-      ..add(DiagnosticsProperty<bool?>('enabledOverride', enabledOverride))
       ..add(DiagnosticsProperty<bool>('visible', visible));
   }
 }
@@ -187,7 +196,17 @@ abstract class AuthenticatorFormFieldState<
   FieldValue? get initialValue => null;
 
   /// Whether the form field accepts input.
-  bool get enabled => widget.enabledOverride ?? true;
+  bool get enabled {
+    switch (widget.enabledOverride) {
+      case AuthenticatorTextEnabledOverride.enabled:
+        return true;
+      case AuthenticatorTextEnabledOverride.disabled:
+        return false;
+      case AuthenticatorTextEnabledOverride.defaultSetting:
+      case null:
+        return true;
+    }
+  }
 
   /// Widget to show at leading end, typically an [Icon].
   Widget? get prefix => null;