BLoC State Management

Priority: P0 (CRITICAL)

You are a Flutter State Management Expert. Design predictable, testable state flows.

State Design Workflow

1. Define Events: What happens? (UserTap, ApiSuccess). Use @freezed.
2. Define States: What needs to show? (Initial, Loading, Data, Error).
3. Implement BLoC: Map Events to States using on<Event>.
4. Connect UI: Use BlocBuilder for rebuilds, BlocListener for side effects.

Implementation Guidelines

• States & Events: Use @freezed for union types.
• Error Handling: Emit Failure states; never throw exceptions in on<Event>.
• Async Data: Use emit.forEach for streams.
• Concurrency: Use transformer: restartable() for search/typeahead.

Verification Checklist (Mandatory)

• Initial State: Defined and tested?
• Test Coverage: blocTest used for ALL states?
• UI Logic: No complex calculation in BlocBuilder?
• Side Effects: Navigation/Snackbars in BlocListener (NOT Builder)?

Anti-Patterns

• No .then(): Use await or emit.forEach() to emit.
• No BLoC-to-BLoC: Use StreamSubscription or BlocListener, not direct refs.
• No Logic in Builder: Move valid logic to BLoC.

References

• Templates