forms-and-input

Forms and input

Text input is where most disposal leaks, un-localized strings, and jank enter a Flutter app. A form is a small state machine: fields hold text, a FormState validates them, and a ViewModel owns anything that touches the network or the clock. Keep those three responsibilities separate.

Read the reference for the task at hand:

• references/validation-sync-and-async.md — sync validator returning localized String?, AutovalidateMode choice, and the debounced-async-in-a-Notifier pattern (why async must NOT live in the sync validator).
• references/focus-and-keyboard.md — FocusNode lifecycle, traversal order, autofocus, FocusTraversalGroup, TextInputAction, onFieldSubmitted/onEditingComplete, keyboardType, autofillHints, TextInputFormatter, keyboard-avoidance.

Run scripts/check_forms.sh before a PR.

Non-negotiable rules

1. Every TextEditingController and FocusNode created in a State is disposed in dispose(). They hold native resources and listeners; a leak survives the widget and fires callbacks against a dead tree. If the value must outlive the widget, hold it in a Notifier instead — see state-management-riverpod.
2. Validator messages are localized, never hardcoded. A validator returns AppLocalizations.of(context).fieldRequired, not 'Required'. Error text is user-facing UI copy and is owned by i18n-rtl-l10n. The check_forms.sh grep fails on string literals returned from a validator.
3. The sync validator is pure and instant — no await, no network, no Future. FormFieldValidator<T> is String? Function(T?); it cannot be async and Flutter calls it synchronously during layout. Availability/uniqueness checks belong in a Notifier (rule 4).
4. Async validation lives in a debounced Riverpod Notifier and surfaces through state. Debounce with a dart:async Timer (kept deterministic in tests via fakeAsync, not by the clock), run the check, and expose AsyncValue/a sealed status the field reads via InputDecoration.errorText. Any timestamp the check records comes from ref.read(clockProvider).now(), never DateTime.now() — the Clock seam is owned by service-boundary-and-native. Never block a keystroke on I/O. See async-safety for cancel-on-dispose.
5. Submit-enabled is DERIVED from validity, never stored as a separate bool. A stored _isValid flag drifts out of sync with the fields. Compute it from FormState/Notifier state at build time. See flutter-performance (derive-don't-store).
6. A keystroke rebuilds one field, not the whole form. Give each field its own controller/FormField; do not lift raw text into a top-level setState/watch that rebuilds every sibling. Scope rebuilds with small widgets and ref.watch(....select(...)). See widget-composition and flutter-performance.
7. Choose AutovalidateMode deliberately. Default to AutovalidateMode.onUserInteraction: silent until the user touches a field, then live. Never always (screams before the user types). Validate-on-submit only for short forms where per-field feedback is noise.
8. Keyboard type, capitalization, and autofill are declared per field. keyboardType, textCapitalization, autofillHints, and TextInputFormatters are structural input contracts, not decoration. A missing autofillHints breaks OS autofill and password managers.
9. Errors are announced, not just colored. InputDecoration.labelText/errorText carry semantics that screen readers read on change; never signal an error with color alone. See accessibility-as-code.