bloc

Bloc Skill

Design, implement, and test state management using the bloc and flutter_bloc libraries.

When to Use

Use this skill when:

• Creating a new Cubit or Bloc for a feature.
• Modeling state (choosing between sealed classes and a single state class with status enum).
• Wiring BlocBuilder, BlocListener, BlocConsumer, or BlocProvider in the widget tree.
• Writing unit tests for a Cubit or Bloc.
• Deciding between Cubit and Bloc.
• Refactoring existing state management to follow bloc conventions.

---

1. Cubit vs Bloc

Situation	Use
Simple state, no events needed	Cubit
Complex flows, event traceability needed	Bloc
Advanced event processing (debounce, throttle)	Bloc with event transformers

Default to Cubit. Refactor to Bloc only when requirements grow.

---

2. Naming Conventions

Events (Bloc only)

• Named in past tense: LoginButtonPressed, UserProfileLoaded.
• Format: BlocSubject + optional noun + verb.
• Initial load event: BlocSubjectStarted (e.g., AuthenticationStarted).
• Base event class: BlocSubjectEvent.

States

• Named as nouns (states are snapshots in time).
• Base state class: BlocSubjectState.
• Sealed subclasses: BlocSubject + Initial | InProgress | Success | Failure.
  • Example: LoginInitial, LoginInProgress, LoginSuccess, LoginFailure.
• Single-class approach: BlocSubjectState + BlocSubjectStatus enum (initial, loading, success, failure).

---

3. Modeling State

When to use a sealed class with subclasses

• States are well-defined and mutually exclusive.
• Type-safe exhaustive switch is desired.
• Subclass-specific properties exist.

@immutable
sealed class LoginState extends Equatable {
  const LoginState();
}

final class LoginInitial extends LoginState {
  @override
  List<Object?> get props => [];
}

final class LoginInProgress extends LoginState {
  @override
  List<Object?> get props => [];
}

final class LoginSuccess extends LoginState {
  const LoginSuccess(this.user);
  final User user;
  @override
  List<Object?> get props => [user];
}

final class LoginFailure extends LoginState {
  const LoginFailure(this.message);
  final String message;
  @override
  List<Object?> get props => [message];
}