fix(authenticator): defer controller->state updates to post-frame and stabilize sync

Buffer controller changes and apply them in a post-frame callback to avoid
calling setState during build. Normalize trailing whitespace when comparing
controller and state to reduce unnecessary writes. Ensure didUpdateWidget
sync runs after build and clear pending state on dispose. Add widget tests
covering typing, special keys, rapid updates, and controller interactions.

Author: angelorodem

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

@@ -4,6 +4,7 @@
 import 'package:amplify_authenticator/src/widgets/form.dart';
 import 'package:amplify_authenticator/src/widgets/form_field.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
 import 'package:flutter/services.dart';
 
 mixin AuthenticatorTextField<
@@ -14,6 +15,8 @@ mixin AuthenticatorTextField<
   TextEditingController? _effectiveController;
   bool _isApplyingControllerText = false;
   String? _lastSyncedControllerValue;
+  String? _pendingControllerText;
+  bool _controllerUpdateScheduled = false;
 
   @protected
   TextEditingController? get textController => null;
@@ -26,6 +29,7 @@ mixin AuthenticatorTextField<
     _effectiveController?.removeListener(_handleControllerChanged);
     _effectiveController = controller;
     _lastSyncedControllerValue = null;
+    _pendingControllerText = null;
     if (_effectiveController != null) {
       _effectiveController!.addListener(_handleControllerChanged);
     }
@@ -37,11 +41,27 @@ mixin AuthenticatorTextField<
       return;
     }
     final text = controller.text;
-    if (text == _lastSyncedControllerValue) {
+    if (text == _lastSyncedControllerValue && _pendingControllerText == null) {
       return;
     }
-    _lastSyncedControllerValue = text;
-    onChanged(text);
+    _pendingControllerText = text;
+    if (_controllerUpdateScheduled) {
+      return;
+    }
+    _controllerUpdateScheduled = true;
+    SchedulerBinding.instance.addPostFrameCallback((_) {
+      _controllerUpdateScheduled = false;
+      final pendingText = _pendingControllerText;
+      _pendingControllerText = null;
+      if (!mounted || pendingText == null) {
+        return;
+      }
+      if (pendingText == _lastSyncedControllerValue) {
+        return;
+      }
+      _lastSyncedControllerValue = pendingText;
+      onChanged(pendingText);
+    });
   }
 
   void _syncControllerText({bool force = false}) {
@@ -50,8 +70,16 @@ mixin AuthenticatorTextField<
       return;
     }
     final target = initialValue ?? '';
-    if (!force && controller.text == target) {
-      _lastSyncedControllerValue = controller.text;
+    final controllerText = controller.text;
+    if (!force && controllerText == target) {
+      _lastSyncedControllerValue = controllerText;
+      return;
+    }
+
+    final normalizedController = controllerText.trimRight();
+    final normalizedTarget = target.trimRight();
+    if (normalizedController == normalizedTarget) {
+      _lastSyncedControllerValue = controllerText;
       return;
     }
     _isApplyingControllerText = true;
@@ -61,6 +89,7 @@ mixin AuthenticatorTextField<
       composing: TextRange.empty,
     );
     _lastSyncedControllerValue = target;
+    _pendingControllerText = null;
     _isApplyingControllerText = false;
   }
 
@@ -93,13 +122,19 @@ mixin AuthenticatorTextField<
   void didUpdateWidget(covariant T oldWidget) {
     super.didUpdateWidget(oldWidget);
     _maybeUpdateEffectiveController();
-    _syncControllerText(force: true);
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (mounted) {
+        _syncControllerText(force: true);
+      }
+    });
   }
 
   @override
   void dispose() {
     _effectiveController?.removeListener(_handleControllerChanged);
     _effectiveController = null;
+    _pendingControllerText = null;
+    _controllerUpdateScheduled = false;
     super.dispose();
   }
 
@@ -117,6 +152,7 @@ mixin AuthenticatorTextField<
       builder: (BuildContext context, bool toggleObscureText, Widget? _) {
         final obscureText = this.obscureText && toggleObscureText;
         // Don't sync during build
+        final shouldHandleChangeImmediately = _effectiveController == null;
         return TextFormField(
           style: enabled
               ? null
@@ -125,7 +161,7 @@ mixin AuthenticatorTextField<
           initialValue: _effectiveController == null ? initialValue : null,
           enabled: enabled,
           validator: widget.validatorOverride ?? validator,
-          onChanged: onChanged,
+          onChanged: shouldHandleChangeImmediately ? onChanged : null,
           autocorrect: false,
           decoration: InputDecoration(
             labelText: labelText,

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

@@ -9,6 +9,7 @@ import 'package:amplify_authenticator/src/utils/validators.dart';
 import 'package:amplify_authenticator/src/widgets/component.dart';
 import 'package:amplify_authenticator/src/widgets/form_field.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
 
 mixin AuthenticatorUsernameField<
   FieldType extends Enum,
@@ -19,6 +20,8 @@ mixin AuthenticatorUsernameField<
   UsernameType? _controllerUsernameType;
   bool _applyingControllerText = false;
   String? _lastSyncedText;
+  String? _pendingControllerText;
+  bool _controllerUpdateScheduled = false;
 
   @protected
   TextEditingController? get textController => null;
@@ -42,6 +45,7 @@ mixin AuthenticatorUsernameField<
     _controller = controller;
     _controllerUsernameType = type;
     _lastSyncedText = null;
+    _pendingControllerText = null;
 
     if (_controller != null && shouldListen) {
       _controller!.addListener(_handleControllerChanged);
@@ -55,17 +59,35 @@ mixin AuthenticatorUsernameField<
     }
 
     final text = controller.text;
-    if (text == _lastSyncedText) {
+    if (text == _lastSyncedText && _pendingControllerText == null) {
       return;
     }
 
-    _lastSyncedText = text;
-    _applyingControllerText = true;
-    try {
-      onChanged(UsernameInput(type: selectedUsernameType, username: text));
-    } finally {
-      _applyingControllerText = false;
+    _pendingControllerText = text;
+    if (_controllerUpdateScheduled) {
+      return;
     }
+    _controllerUpdateScheduled = true;
+    SchedulerBinding.instance.addPostFrameCallback((_) {
+      _controllerUpdateScheduled = false;
+      final pendingText = _pendingControllerText;
+      _pendingControllerText = null;
+      if (!mounted || pendingText == null) {
+        return;
+      }
+      if (pendingText == _lastSyncedText) {
+        return;
+      }
+      _applyingControllerText = true;
+      try {
+        onChanged(
+          UsernameInput(type: selectedUsernameType, username: pendingText),
+        );
+        _lastSyncedText = pendingText;
+      } finally {
+        _applyingControllerText = false;
+      }
+    });
   }
 
   void _syncControllerText({bool force = false}) {
@@ -75,8 +97,16 @@ mixin AuthenticatorUsernameField<
     }
 
     final target = initialValue?.username ?? '';
-    if (!force && _controller!.text == target) {
-      _lastSyncedText = _controller!.text;
+    final controllerText = _controller!.text;
+    if (!force && controllerText == target) {
+      _lastSyncedText = controllerText;
+      return;
+    }
+
+    final normalizedController = controllerText.trimRight();
+    final normalizedTarget = target.trimRight();
+    if (normalizedController == normalizedTarget) {
+      _lastSyncedText = controllerText;
       return;
     }
 
@@ -87,6 +117,7 @@ mixin AuthenticatorUsernameField<
       composing: TextRange.empty,
     );
     _lastSyncedText = target;
+    _pendingControllerText = null;
     _applyingControllerText = false;
   }
 
@@ -118,13 +149,19 @@ mixin AuthenticatorUsernameField<
   void didUpdateWidget(covariant T oldWidget) {
     super.didUpdateWidget(oldWidget);
     _updateController();
-    _syncControllerText(force: true);
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (mounted) {
+        _syncControllerText(force: true);
+      }
+    });
   }
 
   @override
   void dispose() {
     _controller?.removeListener(_handleControllerChanged);
     _controller = null;
+    _pendingControllerText = null;
+    _controllerUpdateScheduled = false;
     super.dispose();
   }
 
@@ -310,8 +347,8 @@ mixin AuthenticatorUsernameField<
     final inputResolver = stringResolver.inputs;
     final hintText = inputResolver.resolve(context, hintKey);
 
-    void onChanged(String username) {
-      return this.onChanged(
+    void handleChanged(String username) {
+      return onChanged(
         UsernameInput(type: selectedUsernameType, username: username),
       );
     }
@@ -327,7 +364,7 @@ mixin AuthenticatorUsernameField<
       return AuthenticatorPhoneField<FieldType>(
         field: widget.field,
         requiredOverride: true,
-        onChanged: onChanged,
+        onChanged: handleChanged,
         validator: validator,
         enabled: enabled,
         errorMaxLines: errorMaxLines,
@@ -340,13 +377,19 @@ mixin AuthenticatorUsernameField<
     _updateController();
     // Don't sync during build
 
+    final controllerInUse = _controller != null;
+
     return TextFormField(
       style: enabled ? null : TextStyle(color: Theme.of(context).disabledColor),
       controller: _controller,
       initialValue: _controller == null ? initialValue?.username : null,
       enabled: enabled,
       validator: validator,
-      onChanged: onChanged,
+      onChanged: (username) {
+        if (!controllerInUse) {
+          handleChanged(username);
+        }
+      },
       autocorrect: false,
       decoration: InputDecoration(
         prefixIcon: prefix,