feat(authenticator): Add TextEditingController support to form fields

[angelorodem]

This PR adds TextEditingController support to Amplify Authenticator form fields, enabling developers to programmatically control text input fields during authentication flows. It also introduces per-field visibility and enabled-state overrides for Sign Up fields so apps can keep legacy attributes off-screen or block user edits while still syncing values via controllers.

cc: @tyllark

What was changed

• Added new AuthenticatorTextFieldController class that wraps Flutter's TextEditingController with identical semantics.
• Added optional controller parameter to all text-based form fields across all authentication steps:
  • SignIn (username, password)
  • SignUp (username, email, password, phone number, address, and all custom attributes)
  • ConfirmSignIn (verification code, new password, custom auth)
  • ConfirmSignUp (username, verification code)
  • ResetPassword (username, verification code, new password)
  • VerifyUser (verification code)
  • EmailSetup (email)
• Added visible (default true) and enabled overrides to every SignUpFormField factory so applications can hide fields while keeping controller updates, or disable manual editing for attributes filled from background processes.
• Implemented bidirectional synchronization between controllers and internal authenticator state, including post-frame buffering to avoid setState-during-build issues.
• Added proper lifecycle management with post-frame callbacks to ensure correct sync timing and included diagnostics exposure for controller, enabled, and visible values.

Why was this change made

Addresses the need for programmatic control over authenticator form fields to enable use cases such as:

• Pre-populating fields with data from external sources (GPS coordinates, API responses)
• Auto-filling verification codes from SMS or other sources
• Integration with third-party form validation libraries
• Dynamic form manipulation based on business logic
• Keeping legacy/system attributes hidden from end users while still providing values
• Disabling fields that should not accept manual input when values are provided automatically

How was this change tested

• Added comprehensive unit/widget test suite with 13 test cases covering:
  • Bidirectional sync between controller and state
  • Multiple controllers on different fields
  • Rapid text updates and special key handling
  • Standard TextEditingController compatibility
  • Initial value population from controllers
  • Controller disposal and lifecycle management
  • Hidden and disabled Sign Up fields continuing to sync via controllers without user interaction
• All existing tests pass (301 tests)
• Created example app (authenticator_with_controllers.dart) demonstrating real-world usage patterns

Related Issues

Fixes #6161

Migration Guide

This is a non-breaking change. Existing code continues to work without modifications. To use the new controller functionality:

// Create a controller
final usernameController = AuthenticatorTextFieldController(text: 'initial_value');

// Pass it to a form field
Authenticator(
  signUpForm: SignUpForm.custom(
    fields: [
      SignUpFormField.username(
        controller: usernameController,
        enabled: false, // optional
        visible: false, // optional
      ),
      // ... other fields
    ],
  ),
  // ...
);

// Update programmatically
usernameController.text = 'new_value';

// Dispose when done
usernameController.dispose();

Standard TextEditingController is also supported for flexibility.

Screenshots/Videos

Video.mp4

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[Copilot]

Pull Request Overview

This PR adds TextEditingController support to Amplify Authenticator form fields, enabling programmatic control over form field values. This feature allows developers to pre-populate fields with data from external sources (e.g., GPS, APIs) or auto-fill verification codes.

• Introduces AuthenticatorTextFieldController as a Flutter TextEditingController wrapper
• Adds optional controller parameter to all text-based form fields across sign-in, sign-up, verification, and password reset flows
• Implements bidirectional synchronization between controllers and internal authenticator state

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
authenticator_text_field_controller.dart	New controller class extending TextEditingController for authenticator fields
authenticator_text_field.dart	Adds controller sync logic to text field mixin with lifecycle management
authenticator_username_field.dart	Adds controller sync logic to username field mixin, handling phone number special case
sign_in_form_field.dart	Adds controller parameter to sign-in fields (username, password)
sign_up_form_field.dart	Adds controller parameter to sign-up fields (username, password, email, address, name, phone, etc.)
confirm_sign_in_form_field.dart	Adds controller parameter to confirm sign-in fields (password, verification code, attributes)
confirm_sign_up_form_field.dart	Adds controller parameter to confirm sign-up fields (username, verification code)
reset_password_form_field.dart	Adds controller parameter to reset password fields (verification code, new password, confirmation)
verify_user_form_field.dart	Adds controller parameter to user verification field
email_setup_form_field.dart	Adds controller parameter to email setup field
phone_number_field.dart	Adds controller parameter to phone number field
form_field.dart	Adds controller getter to base form field class
form_field_controller_test.dart	Comprehensive test suite validating controller sync behavior
authenticator_with_controllers.dart	Example app demonstrating controller usage
amplify_authenticator.dart	Exports the new AuthenticatorTextFieldController
CHANGELOG.md	Documents the new feature
main.dart	Adds commented example reference

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[angelorodem]

@tyllark could you please review?

[angelorodem]

Here is a real world usage of this PR, it also uses the hide functionality to hide and automatically fill the Address field of aws cognito using the other address info available on the form.

Video2.mp4