flutter-state

You are implementing state management for a Flutter feature using Cubit + RxDart.

Three Patterns by Use Case

Choose based on the skill argument, if one was given, or on the context of the feature:

• simple — basic async operations (load data, submit form)
• stream — real-time data via RxDart BehaviorSubject
• event-bus — cross-module communication via Broker

Pattern 1: Simple Cubit (default)

Best for: load list, submit form, CRUD

<feature>_status.dart:

abstract class <Feature>Status {
  const <Feature>Status();
}

class <Feature>Initial extends <Feature>Status {
  const <Feature>Initial();
}

class <Feature>Loading extends <Feature>Status {
  const <Feature>Loading();
}

class <Feature>Success extends <Feature>Status {
  final List<<Entity>> items;
  const <Feature>Success(this.items);
}

class <Feature>Failure extends <Feature>Status {
  final String message;
  const <Feature>Failure(this.message);
}

<feature>_controller.dart:

import 'package:flutter_bloc/flutter_bloc.dart';
import '<feature>_status.dart';

class <Feature>Controller extends Cubit<<Feature>Status> {
  final Get<Feature>Usecase _get<Feature>;

  <Feature>Controller(this._get<Feature>)
      : super(const <Feature>Initial());

  Future<void> load() async {
    emit(const <Feature>Loading());
    try {
      final items = await _get<Feature>.call();
      emit(<Feature>Success(items));
    } catch (e) {
      emit(<Feature>Failure(e.toString()));
    }
  }

  Future<void> refresh() => load();
}

In screen:

BlocBuilder<<Feature>Controller, <Feature>Status>(
  builder: (context, status) => switch (status) {
    <Feature>Loading()  => const Center(child: CircularProgressIndicator()),
    <Feature>Failure(:final message) => Center(child: Text(message)),
    <Feature>Success(:final items)   => _buildList(items),
    _                                => const SizedBox.shrink(),
  },
),

Pattern 2: Stream Cubit (real-time)

Best for: live order updates, command status, POS terminal events

<feature>_controller.dart:

import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:rxdart/rxdart.dart';
import '<feature>_status.dart';

class <Feature>Controller extends Cubit<<Feature>Status> {
  final <Feature>Repository _repository;
  final _subject = BehaviorSubject<List<<Entity>>>();
  StreamSubscription? _sub;

  <Feature>Controller(this._repository) : super(const <Feature>Initial());

  Stream<List<<Entity>>> get stream => _subject.stream;

  Future<void> watch() async {
    emit(const <Feature>Loading());
    try {
      _sub = _repository
          .watchAll()
          .debounceTime(const Duration(milliseconds: 300))
          .listen(
            (items) {
              _subject.add(items);
              emit(<Feature>Success(items));
            },
            onError: (e) => emit(<Feature>Failure(e.toString())),
          );
    } catch (e) {
      emit(<Feature>Failure(e.toString()));
    }
  }

  @override
  Future<void> close() {
    _sub?.cancel();
    _subject.close();
    return super.close();
  }
}

Pattern 3: Event Bus (cross-module)

Best for: payment completion → order refresh, command events, notifications

Publishing an event (in sender controller):

class PaymentController extends Cubit<PaymentStatus> {
  final Broker _broker;

  PaymentController(this._broker, ...) : super(const PaymentInitial());

  Future<void> confirmPayment(String commandId) async {
    // ... process payment
    _broker.dispatch(BrokerEvent(
      kind: 'payment.confirmed',
      data: {'commandId': commandId},
    ));
  }
}

Consuming an event (in receiver controller):

class CommandController extends Cubit<CommandStatus> {
  final Broker _broker;
  StreamSubscription? _paymentSub;

  CommandController(this._broker, ...) : super(const CommandInitial()) {
    _listenToPayments();
  }

  void _listenToPayments() {
    _paymentSub = _broker
        .on('payment.confirmed')
        .listen((event) => refresh());
  }

  @override
  Future<void> close() {
    _paymentSub?.cancel();
    return super.close();
  }
}

Consumer widget (subscribes during module load):

class PaymentConsumer {
  final Broker broker;
  StreamSubscription? _sub;

  PaymentConsumer({required this.broker});

  void start() {
    _sub = broker.on('order.created').listen((event) {
      // react to event
    });
  }

  void dispose() => _sub?.cancel();
}

Status State Design Rules

1. Use abstract class (not sealed — Dart sealed requires same file)
2. Each status is a separate class extending the abstract base
3. States are immutable — use const constructors
4. Success state carries data as final fields
5. Failure state carries only final String message
6. Never embed logic in status classes — only data

Controller Rules

1. Extends Cubit<T> — not Bloc<Event, State> (simpler for most cases)
2. Methods are Future<void> for async, void for sync
3. Always emit(Loading()) before async calls
4. Always wrap async in try/catch → emit Failure
5. Cancel all subscriptions in close()
6. Never call emit() after close() — check !isClosed if needed

Instructions

1. Read the existing controller in the module if one exists
2. Choose the right pattern based on whether the feature needs real-time data or cross-module events
3. Create _status.dart and _controller.dart files
4. Update the module's DI registration (see /flutter-di skill)
5. Update the screen to use BlocBuilder or BlocListener appropriately
6. Use switch expressions for status handling in UI (cleaner than if/else)