Login Form BLoC
Component Detail
Description
BLoC (or Riverpod StateNotifier) managing the complete state of the login form. Handles field input events, triggers validation, dispatches authentication requests to the auth service, and exposes UI states: idle, loading, success, and error.
login-form-bloc
Summaries
The Login Form BLoC is the operational core of the user authentication experience, directly governing whether customers can access the product at all. By managing the complete lifecycle of the sign-in interaction — from the moment a user begins typing to the final success or error outcome — this component ensures the business can deliver a reliable, trustworthy first impression. Its precise error-state differentiation (network failure vs. wrong credentials vs.
server error) reduces user frustration and support escalation, as customers receive actionable feedback rather than generic error messages. A robust login foundation also reduces security incidents from improper state handling, protecting both customer data and the company's regulatory standing.
This medium-complexity component is on the critical path for the authentication feature and must be delivered before any downstream work that depends on an authenticated session. It has two hard dependencies — the credential-validator and the auth-service — meaning those components must be at minimum interface-stable before integration testing can begin. Plan for three delivery phases: (1) state machine scaffolding and unit tests for idle/loading/success/error transitions, (2) integration with credential-validator for real-time field validation, and (3) integration with auth-service for end-to-end login flow. Budget extra QA time for edge cases: simultaneous rapid input events, network timeout simulation, and state recovery after backgrounding the app mid-login.
Implemented using Flutter BLoC or Riverpod StateNotifier pattern. The state machine covers four distinct states: idle (initial), loading (auth request in flight), success (authenticated), and error (with a typed error discriminator for network, invalid-credentials, and server-side failures). Core event inputs are onEmailChanged(String), onPasswordChanged(String), onSubmitRequested(), and onReset(). The BLoC delegates validation to the credential-validator dependency synchronously on each field change event, and dispatches async auth requests to auth-service on submit.
Use stream-based state emission (LoginState stream) so the UI layer can reactively rebuild without polling. Dirty-field tracking is essential — validation errors must only surface after the user has interacted with a field, not on initial render. Dispose all stream subscriptions in dispose() to prevent memory leaks, particularly important given auth flows that may be interrupted by navigation events.
Responsibilities
- Manage email and password field values and dirty state
- Trigger real-time and on-submit validation
- Coordinate authentication request lifecycle (idle → loading → success/error)
- Emit granular error states distinguishing network, credential, and server failures
Interfaces
add(LoginEvent)
stream LoginState
onEmailChanged(String)
onPasswordChanged(String)
onSubmitRequested()
onReset()
dispose()
Relationships
Dependencies (2)
Components this component depends on