bloc

Bloc

State management library for Dart and Flutter using the BLoC (Business Logic Component) pattern to separate business logic from the presentation layer.

---

Core Standards

Apply these standards to ALL Bloc/Cubit work:

• Use blocTest() from package:bloc_test for all Bloc and Cubit tests — never raw test() with manual stream assertions
• Use package:mocktail for mocking — never package:mockito
• No bloc-to-bloc direct dependencies — blocs communicate through the UI or shared repositories
• Page/View separation — Page provides the Bloc/Cubit via BlocProvider, View consumes via BlocBuilder/BlocListener
• Sealed classes for events and multi-state types — enables exhaustive pattern matching with Dart 3 switch
• Equatable for all states and events — extend Equatable and override props for value equality
• Business logic in Bloc/Cubit only — never in widgets, pages, or views
• Single responsibility — one Bloc/Cubit per feature concern
• Emit only after async checks — use emit only inside the handler callback

---

Cubit vs Bloc

Aspect	Cubit	Bloc
API	Functions → emit(state)	Events → on<Event> → emit(state)
Complexity	Low	Higher
Traceability	Less (no event log)	Full (events + transitions)
When to use	Simple state, UI-driven logic	Complex flows, event-driven, transforms
Testing	Call methods, assert states	Add events, assert states

Cubit Example

class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);

  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
}

Bloc Example

sealed class CounterEvent extends Equatable {
  const CounterEvent();

  @override
  List<Object> get props => [];
}

final class CounterIncrementPressed extends CounterEvent {}
final class CounterDecrementPressed extends CounterEvent {}

class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(0) {
    on<CounterIncrementPressed>((event, emit) => emit(state + 1));
    on<CounterDecrementPressed>((event, emit) => emit(state - 1));
  }
}