Complicated forms. Simple code.

class SignupFormController extends AdvancedFormController {
  SignupFormController() {
    registerFields([firstName, lastName]);
  }

  final firstName = AdvancedTextFieldController(
    validator: filled('First name is required'),
  );
  final lastName = AdvancedTextFieldController(
    validator: filled('Last name is required'),
  );

  Future<bool> submit() async {
    if (await validate()) {
      // The values were checked — send them.
      return true;
    }
    return false;
  }
}

class SignupForm extends StatefulWidget {
  const SignupForm({super.key});

  @override
  State<SignupForm> createState() => _SignupFormState();
}

class _SignupFormState extends State<SignupForm> {
  final _form = SignupFormController();

  @override
  void dispose() {
    _form.dispose(); // disposes the registered fields too
    super.dispose();
  }

  Future<void> _submit() async {
    final sent = await _form.submit();
    if (mounted) {
      ExampleLog.of(context).add(
        sent
            ? 'Welcome, ${_form.firstName.fieldValue}!'
            : 'Fix the errors above.',
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        _SignupTextField(field: _form.firstName, label: 'First name'),
        _SignupTextField(field: _form.lastName, label: 'Last name'),
        const SizedBox(height: 12),
        FilledButton(onPressed: _submit, child: const Text('Submit')),
      ],
    );
  }
}

class _SignupTextField extends StatelessWidget {
  const _SignupTextField({required this.field, required this.label});

  final AdvancedTextFieldController<String> field; // <String> is the error type
  final String label;

  @override
  Widget build(BuildContext context) {
    return AdvancedFieldBuilder<String, String>(
      field: field,
      builder: (context, state, _) => Padding(
        padding: const EdgeInsets.symmetric(vertical: 6),
        child: TextFormField(
          controller: field.textController,
          focusNode: field.focusNode,
          decoration: InputDecoration(labelText: label, errorText: state.error),
        ),
      ),
    );
  }
}

enum UsernameError { required, tooShort, taken, checkFailed }

class UsernameFormController extends AdvancedFormController {
  UsernameFormController()
    : super(validationMode: ValidationMode.onUserInteraction) {
    registerFields([username]);
  }

  late final username = AdvancedTextFieldController(
    validator:
        filled(UsernameError.required) &
        atLeastLength(3, UsernameError.tooShort),
    asyncValidation: AsyncValidation(
      validator: _isAvailable, // Future<UsernameError?> Function(String)
      debounce: const Duration(milliseconds: 400), // default 300 ms
      timeout: const Duration(seconds: 3), // default: no bound
      failureToError: (error, stackTrace) => UsernameError.checkFailed,
    ),
  );

  Future<UsernameError?> _isAvailable(String value) async {
    await Future<void>.delayed(const Duration(milliseconds: 700));
    if (value == 'boom') {
      throw Exception('the directory service is down');
    }
    const taken = {'alice', 'bob', 'admin'};
    return taken.contains(value) ? UsernameError.taken : null;
  }
}

class UsernameAvailabilityForm extends StatefulWidget {
  const UsernameAvailabilityForm({super.key});

  @override
  State<UsernameAvailabilityForm> createState() =>
      _UsernameAvailabilityFormState();
}

class _UsernameAvailabilityFormState extends State<UsernameAvailabilityForm> {
  final _form = UsernameFormController();

  @override
  void dispose() {
    _form.dispose();
    super.dispose();
  }

  Future<void> _submit() async {
    // Awaits the check in flight instead of failing a busy field.
    final ok = await _form.validate();
    if (mounted) {
      final name = _form.username.fieldValue;
      ExampleLog.of(context).add(ok ? '@$name is yours.' : 'Not submitted.');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        const DocsHint(
          'alice, bob and admin are taken. boom makes the check throw.',
        ),
        DocsFailureBanner(form: _form),
        DocsTextField(
          field: _form.username,
          label: 'Username',
          icon: Icons.person_outline,
          translateError: (error) => switch (error) {
            UsernameError.required => 'Pick a username',
            UsernameError.tooShort => 'At least 3 characters',
            UsernameError.taken => 'Already taken — try another',
            UsernameError.checkFailed => 'Could not check availability',
          },
        ),
        Row(
          children: [
            DocsFieldStatus(field: _form.username, label: 'status'),
            const Spacer(),
            DocsSubmitButton(form: _form, label: 'Claim', onPressed: _submit),
          ],
        ),
      ],
    );
  }
}