feat(authenticator): expose optional TextEditingController and improve sync timing

- Add nullable controller getter to AuthenticatorFormField and include it in diagnostics
- Add debugFillProperties implementations to form field widgets to surface the controller prop
- Rework text controller sync logic in AuthenticatorTextField and AuthenticatorUsernameField:
  - Skip syncing in initState and avoid syncing during build
  - Schedule post-frame callbacks in didChangeDependencies to first apply controller->state (if controller has initial text) then sync state->controller
- Minor conditional/formatting cleanup in username field sync

Author: angelorodem

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

@@ -68,14 +68,25 @@ mixin AuthenticatorTextField<
   void initState() {
     super.initState();
     _maybeUpdateEffectiveController();
-    _syncControllerText(force: true);
+    // Skip sync in initState since 'state' isn't available yet
   }
 
   @override
   void didChangeDependencies() {
     super.didChangeDependencies();
     _maybeUpdateEffectiveController();
-    _syncControllerText();
+    // 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();
+        }
+        // Then sync state -> controller to ensure they're in sync
+        _syncControllerText();
+      }
+    });
   }
 
   @override
@@ -105,14 +116,13 @@ mixin AuthenticatorTextField<
       ).obscureTextToggleValue,
       builder: (BuildContext context, bool toggleObscureText, Widget? _) {
         final obscureText = this.obscureText && toggleObscureText;
-        _syncControllerText();
+        // Don't sync during build
         return TextFormField(
           style: enabled
               ? null
               : TextStyle(color: Theme.of(context).disabledColor),
           controller: _effectiveController,
-          initialValue:
-              _effectiveController == null ? initialValue : null,
+          initialValue: _effectiveController == null ? initialValue : null,
           enabled: enabled,
           validator: widget.validatorOverride ?? validator,
           onChanged: onChanged,

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

@@ -69,7 +69,8 @@ mixin AuthenticatorUsernameField<
   }
 
   void _syncControllerText({bool force = false}) {
-    if (_controller == null || selectedUsernameType == UsernameType.phoneNumber) {
+    if (_controller == null ||
+        selectedUsernameType == UsernameType.phoneNumber) {
       return;
     }
 
@@ -93,14 +94,24 @@ mixin AuthenticatorUsernameField<
   void initState() {
     super.initState();
     _updateController();
-    _syncControllerText(force: true);
+    // Skip sync in initState since 'state' isn't available yet
   }
 
   @override
   void didChangeDependencies() {
     super.didChangeDependencies();
     _updateController();
-    _syncControllerText();
+    // 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();
+        }
+        // Then sync state -> controller to ensure they're in sync
+        _syncControllerText();
+      }
+    });
   }
 
   @override
@@ -327,7 +338,7 @@ mixin AuthenticatorUsernameField<
     }
 
     _updateController();
-    _syncControllerText();
+    // Don't sync during build
 
     return TextFormField(
       style: enabled ? null : TextStyle(color: Theme.of(context).disabledColor),

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

@@ -96,6 +96,9 @@ abstract class AuthenticatorFormField<
   /// Autocomplete hints to override the default value
   final Iterable<String>? autofillHints;
 
+  /// Optional text controller exposed by text-driven form fields.
+  TextEditingController? get controller => null;
+
   /// Whether the field is required in the form.
   ///
   /// Defaults to `false`.
@@ -126,6 +129,9 @@ abstract class AuthenticatorFormField<
       ..add(DiagnosticsProperty<bool?>('requiredOverride', requiredOverride))
       ..add(EnumProperty<UsernameType?>('usernameType', usernameType))
       ..add(IterableProperty<String>('autofillHints', autofillHints));
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
   }
 }
 

packages/authenticator/amplify_authenticator/lib/src/widgets/form_fields/confirm_sign_in_form_field.dart

@@ -529,6 +529,14 @@ class _ConfirmSignInPhoneField extends ConfirmSignInFormField<String> {
   @override
   _ConfirmSignInPhoneFieldState createState() =>
       _ConfirmSignInPhoneFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _ConfirmSignInPhoneFieldState extends _ConfirmSignInTextFieldState
@@ -586,6 +594,14 @@ class _ConfirmSignInTextField extends ConfirmSignInFormField<String> {
 
   @override
   _ConfirmSignInTextFieldState createState() => _ConfirmSignInTextFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _ConfirmSignInTextFieldState extends _ConfirmSignInFormFieldState<String>

packages/authenticator/amplify_authenticator/lib/src/widgets/form_fields/confirm_sign_up_form_field.dart

@@ -142,6 +142,14 @@ class _ConfirmSignUpTextField extends ConfirmSignUpFormField<String> {
 
   @override
   _ConfirmSignUpTextFieldState createState() => _ConfirmSignUpTextFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _ConfirmSignUpTextFieldState extends _ConfirmSignUpFormFieldState<String>
@@ -217,6 +225,14 @@ class _ConfirmSignUpUsernameField
   @override
   _ConfirmSignUpUsernameFieldState createState() =>
       _ConfirmSignUpUsernameFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _ConfirmSignUpUsernameFieldState

packages/authenticator/amplify_authenticator/lib/src/widgets/form_fields/sign_in_form_field.dart

@@ -141,6 +141,14 @@ class _SignInTextField extends SignInFormField<String> {
 
   @override
   _SignInTextFieldState createState() => _SignInTextFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _SignInTextFieldState extends _SignInFormFieldState<String>
@@ -197,18 +205,25 @@ class _SignInUsernameField extends SignInFormField<UsernameInput> {
     super.validator,
     super.autofillHints,
     this.controller,
-  })
-    : super._(
-        key: key ?? keyUsernameSignInFormField,
-        titleKey: InputResolverKey.usernameTitle,
-        hintTextKey: InputResolverKey.usernameHint,
-        field: SignInField.username,
-      );
+  }) : super._(
+         key: key ?? keyUsernameSignInFormField,
+         titleKey: InputResolverKey.usernameTitle,
+         hintTextKey: InputResolverKey.usernameHint,
+         field: SignInField.username,
+       );
 
   final TextEditingController? controller;
 
   @override
   _SignInUsernameFieldState createState() => _SignInUsernameFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _SignInUsernameFieldState extends _SignInFormFieldState<UsernameInput>

packages/authenticator/amplify_authenticator/lib/src/widgets/form_fields/sign_up_form_field.dart

@@ -489,6 +489,14 @@ class _SignUpTextField extends SignUpFormField<String> {
 
   @override
   _SignUpTextFieldState createState() => _SignUpTextFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _SignUpTextFieldState extends _SignUpFormFieldState<String>
@@ -668,17 +676,24 @@ class _SignUpUsernameField extends SignUpFormField<UsernameInput> {
     super.validator,
     super.autofillHints,
     this.controller,
-  })
-    : super._(
-        field: SignUpField.username,
-        titleKey: InputResolverKey.usernameTitle,
-        hintTextKey: InputResolverKey.usernameHint,
-      );
+  }) : super._(
+         field: SignUpField.username,
+         titleKey: InputResolverKey.usernameTitle,
+         hintTextKey: InputResolverKey.usernameHint,
+       );
 
   final TextEditingController? controller;
 
   @override
   _SignUpUsernameFieldState createState() => _SignUpUsernameFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _SignUpUsernameFieldState extends _SignUpFormFieldState<UsernameInput>
@@ -704,6 +719,14 @@ class _SignUpPhoneField extends SignUpFormField<String> {
 
   @override
   _SignUpPhoneFieldState createState() => _SignUpPhoneFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _SignUpPhoneFieldState extends _SignUpTextFieldState

packages/authenticator/amplify_authenticator/lib/src/widgets/form_fields/verify_user_form_field.dart

@@ -78,6 +78,14 @@ class _VerifyUserTextField extends VerifyUserFormField<String> {
 
   @override
   _VerifyUserTextFieldState createState() => _VerifyUserTextFieldState();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties.add(
+      DiagnosticsProperty<TextEditingController?>('controller', controller),
+    );
+  }
 }
 
 class _VerifyUserTextFieldState extends _VerifyUserFormFieldState<String>