One-Shot UI Side Effects in BlocSignal: Snackbars, Dialogs, and Navigation Without State Pollution

 ┌────────────────────────────────────────────────────────┐
 │                   State vs. Effects                    │
 ├────────────────────────────┬───────────────────────────┤
 │ Persistent State           │ Ephemeral Side-Effect     │
 ├────────────────────────────┼───────────────────────────┤
 │ • Survived by UI rebuilds  │ • Consumed once & gone    │
 │ • Represented in signals   │ • Triggered by an event   │
 │ • Backed by equality diffs │ • Zero domain state footprint │
 └────────────────────────────┴───────────────────────────┘

// Emitting a reset state immediately after error
emit(AuthFailure(error));
emit(AuthInitial()); // Extra emission, extra microtask, extra rebuild!

class AuthState {
  final String? errorSnackbarMessage;
  final bool hasShownSnackbar; // Manual bookkeeping everywhere!
}

ElevatedButton(
  onPressed: () async {
    final cubit = context.read<AuthCubit>();

    // 1. Await domain logic completion
    await cubit.signIn(emailController.text, passwordController.text);

    // 2. Safe async context guard
    if (!context.mounted) return;

    // 3. Inspect settled state synchronously with Dart pattern matching
    switch (cubit.stateValue) {
      case AuthSuccess(:final user):
        Navigator.of(context).pushReplacementNamed('/dashboard');
      case AuthFailure(:final error):
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text(error)),
        );
      case _:
        break;
    }
  },
  child: const Text('Log In'),
)

import 'dart:async';
import 'package:bloc_signals/bloc_signals.dart';

/// Mixin that adds one-shot presentation event broadcasting to any [BlocSignalBase].
mixin BlocSignalPresentationMixin<Event, State> on BlocSignalBase<State> {
  final _presentationController = StreamController<Event>.broadcast();

  /// Stream of one-shot presentation events.
  Stream<Event> get presentationStream => _presentationController.stream;

  /// Dispatches a one-shot presentation event to active UI listeners.
  void emitPresentation(Event event) {
    if (!isClosed) {
      _presentationController.add(event);
    }
  }

  @override
  Future<void> close() {
    _presentationController.close();
    return super.close();
  }
}

import 'dart:async';
import 'package:flutter/widgets.dart';
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';

/// Listens to one-shot presentation events from a [BlocSignalBase] with [BlocSignalPresentationMixin].
class BlocSignalPresentationListener<
        B extends BlocSignalPresentationMixin<Event, dynamic>, Event>
    extends StatefulWidget {
  const BlocSignalPresentationListener({
    required this.listener,
    this.bloc,
    this.child,
    super.key,
  });

  final B? bloc;
  final void Function(BuildContext context, Event event) listener;
  final Widget? child;

  @override
  State<BlocSignalPresentationListener<B, Event>> createState() =>
      _BlocSignalPresentationListenerState<B, Event>();
}

class _BlocSignalPresentationListenerState<
        B extends BlocSignalPresentationMixin<Event, dynamic>, Event>
    extends State<BlocSignalPresentationListener<B, Event>> {
  StreamSubscription<Event>? _subscription;
  B? _resolvedBloc;

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    final bloc = widget.bloc ?? context.read<B>();
    if (_resolvedBloc != bloc) {
      _unsubscribe();
      _resolvedBloc = bloc;
      _subscribe();
    }
  }

  void _subscribe() {
    _subscription = _resolvedBloc?.presentationStream.listen((event) {
      if (mounted) widget.listener(context, event);
    });
  }

  void _unsubscribe() {
    _subscription?.cancel();
    _subscription = null;
  }

  @override
  void dispose() {
    _unsubscribe();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => widget.child ?? const SizedBox.shrink();
}

import 'package:bloc_signals/bloc_signals.dart';

// 1. Define one-shot presentation events as a sealed hierarchy
sealed class CheckoutPresentationEvent {}

class ShowErrorToast extends CheckoutPresentationEvent {
  ShowErrorToast(this.message);
  final String message;
}

class LaunchPaymentGateway extends CheckoutPresentationEvent {
  LaunchPaymentGateway(this.invoiceUrl);
  final String invoiceUrl;
}

// 2. Attach the mixin to your Cubit or Bloc
class CheckoutCubit extends CubitSignal<CheckoutState>
    with BlocSignalPresentationMixin<CheckoutPresentationEvent, CheckoutState> {
  CheckoutCubit() : super(initialState: CheckoutInitial());

  Future<void> processPayment() async {
    emit(CheckoutProcessing());
    try {
      final invoice = await paymentApi.createInvoice();
      emit(CheckoutSuccess());

      // Emit one-shot navigation/payment launch event
      emitPresentation(LaunchPaymentGateway(invoice.url));
    } catch (e) {
      emit(CheckoutFailure(e.toString()));

      // Emit transient error toast event
      emitPresentation(ShowErrorToast("Payment failed: ${e.toString()}"));
    }
  }
}

class CheckoutView extends StatelessWidget {
  const CheckoutView({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocSignalPresentationListener<CheckoutCubit, CheckoutPresentationEvent>(
      listener: (context, event) {
        switch (event) {
          case ShowErrorToast(:final message):
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text(message),
                backgroundColor: Colors.redAccent,
              ),
            );
          case LaunchPaymentGateway(:final invoiceUrl):
            launchUrl(Uri.parse(invoiceUrl));
        }
      },
      child: Scaffold(
        appBar: AppBar(title: const Text('Checkout')),
        body: const CheckoutBody(),
      ),
    );
  }
}