1# Bloc State Management
2 
3## When to Use Bloc
4 
5Use **Bloc/Cubit** when you need:
6 
7* Explicit event → state transitions
8* Complex business logic
9* Predictable, testable flows
10* Clear separation between UI and logic
11 
12| Use Case               | Recommended |
13| ---------------------- | ----------- |
14| Simple mutable state   | Riverpod    |
15| Event-driven workflows | Bloc        |
16| Forms, auth, wizards   | Bloc        |
17| Feature modules        | Bloc        |
18 
19---
20 
21## Core Concepts
22 
23| Concept | Description            |
24| ------- | ---------------------- |
25| Event   | User/system input      |
26| State   | Immutable UI state     |
27| Bloc    | Event → State mapper   |
28| Cubit   | State-only (no events) |
29 
30---
31 
32## Basic Bloc Setup
33 
34### Event
35 
36```dart
37sealed class CounterEvent {}
38 
39final class CounterIncremented extends CounterEvent {}
40 
41final class CounterDecremented extends CounterEvent {}
42```
43 
44### State
45 
46```dart
47class CounterState {
48  final int value;
49 
50  const CounterState({required this.value});
51 
52  CounterState copyWith({int? value}) {
53    return CounterState(value: value ?? this.value);
54  }
55}
56```
57 
58### Bloc
59 
60```dart
61import 'package:flutter_bloc/flutter_bloc.dart';
62 
63class CounterBloc extends Bloc<CounterEvent, CounterState> {
64  CounterBloc() : super(const CounterState(value: 0)) {
65    on<CounterIncremented>((event, emit) {
66      emit(state.copyWith(value: state.value + 1));
67    });
68 
69    on<CounterDecremented>((event, emit) {
70      emit(state.copyWith(value: state.value - 1));
71    });
72  }
73}
74```
75 
76---
77 
78## Cubit (Recommended for Simpler Logic)
79 
80```dart
81class CounterCubit extends Cubit<int> {
82  CounterCubit() : super(0);
83 
84  void increment() => emit(state + 1);
85  void decrement() => emit(state - 1);
86}
87```
88 
89---
90 
91## Providing Bloc to the Widget Tree
92 
93```dart
94BlocProvider(
95  create: (_) => CounterBloc(),
96  child: const CounterScreen(),
97);
98```
99 
100Multiple blocs:
101 
102```dart
103MultiBlocProvider(
104  providers: [
105    BlocProvider(create: (_) => AuthBloc()),
106    BlocProvider(create: (_) => ProfileBloc()),
107  ],
108  child: const AppRoot(),
109);
110```
111 
112---
113 
114## Using Bloc in Widgets
115 
116### BlocBuilder (UI rebuilds)
117 
118```dart
119class CounterScreen extends StatelessWidget {
120  const CounterScreen({super.key});
121 
122  @override
123  Widget build(BuildContext context) {
124    return BlocBuilder<CounterBloc, CounterState>(
125      buildWhen: (prev, curr) => prev.value != curr.value,
126      builder: (context, state) {
127        return Text(
128          state.value.toString(),
129          style: Theme.of(context).textTheme.displayLarge,
130        );
131      },
132    );
133  }
134}
135```
136 
137---
138 
139### BlocListener (Side Effects)
140 
141```dart
142BlocListener<AuthBloc, AuthState>(
143  listenWhen: (prev, curr) => curr is AuthFailure,
144  listener: (context, state) {
145    if (state is AuthFailure) {
146      ScaffoldMessenger.of(context)
147          .showSnackBar(SnackBar(content: Text(state.message)));
148    }
149  },
150  child: const LoginForm(),
151);
152```
153 
154---
155 
156### BlocConsumer (Builder + Listener)
157 
158```dart
159BlocConsumer<FormBloc, FormState>(
160  listener: (context, state) {
161    if (state.status == FormStatus.success) {
162      context.pop();
163    }
164  },
165  builder: (context, state) {
166    return ElevatedButton(
167      onPressed: state.isValid
168          ? () => context.read<FormBloc>().add(FormSubmitted())
169          : null,
170      child: const Text('Submit'),
171    );
172  },
173);
174```
175 
176---
177 
178## Accessing Bloc Without Rebuilds
179 
180```dart
181context.read<CounterBloc>().add(CounterIncremented());
182```
183 
184⚠️ **Never use `watch` inside callbacks**
185 
186---
187 
188## Async Bloc Pattern (API Calls)
189 
190```dart
191on<UserRequested>((event, emit) async {
192  emit(const UserState.loading());
193 
194  try {
195    final user = await repository.fetchUser();
196    emit(UserState.success(user));
197  } catch (e) {
198    emit(UserState.failure(e.toString()));
199  }
200});
201```
202 
203---
204 
205## Bloc + GoRouter (Auth Guard Example)
206 
207```dart
208redirect: (context, state) {
209  final authState = context.read<AuthBloc>().state;
210 
211  if (authState is Unauthenticated) {
212    return '/login';
213  }
214  return null;
215}
216```
217 
218---
219 
220## Testing Bloc
221 
222```dart
223blocTest<CounterBloc, CounterState>(
224  'emits incremented value',
225  build: () => CounterBloc(),
226  act: (bloc) => bloc.add(CounterIncremented()),
227  expect: () => [
228    const CounterState(value: 1),
229  ],
230);
231```
232 
233---
234 
235## Best Practices (MUST FOLLOW)
236 
237✅ Immutable states
238✅ Small, focused blocs
239✅ One feature = one bloc
240✅ Use Cubit when possible
241✅ Test all blocs
242 
243❌ No UI logic inside blocs
244❌ No context usage inside blocs
245❌ No mutable state
246❌ No massive “god blocs”
247 
248---
249 
250## Quick Reference
251 
252| Widget            | Purpose              |
253| ----------------- | -------------------- |
254| BlocBuilder       | UI rebuild           |
255| BlocListener      | Side effects         |
256| BlocConsumer      | Both                 |
257| BlocProvider      | Dependency injection |
258| MultiBlocProvider | Multiple blocs       |
259 
260