mono_bloc_flutter library

Flutter widgets and utilities for MonoBloc.

This package provides Flutter-specific widgets for handling MonoBloc actions, which are side effects like navigation, dialogs, and snackbars.

Usage with `when()`

Use inline callbacks for simple action handling:

import 'package:mono_bloc_flutter/mono_bloc_flutter.dart';

// In your widget tree:
MonoBlocActionListener<CartBloc>(
  actions: CartBlocActions.when(
    showNotification: (context, message, type) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(message)),
      );
    },
    navigateToCheckout: (context) {
      Navigator.pushNamed(context, '/checkout');
    },
  ),
  child: CartPage(),
)

Usage with `of()`

For cleaner code, implement the generated actions interface:

class CartPage extends StatelessWidget implements CartBlocActions {
  const CartPage({super.key});

  @override
  void showNotification(BuildContext context, String message, NotificationType type) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(message)));
  }

  @override
  void navigateToCheckout(BuildContext context) {
    Navigator.pushNamed(context, '/checkout');
  }

  @override
  Widget build(BuildContext context) {
    return MonoBlocActionListener<CartBloc>(
      actions: CartBlocActions.of(this),  // Wire this instance as handler
      child: CartContent(),
    );
  }
}

When to use which pattern:

when() - Inline callbacks, good for simple pages with few actions
of() - Interface implementation, better for complex pages or reusable handlers

Classes

ActionStreamable: Interface for objects that provide an action stream.
AsyncMonoBloc: Marks a class for MonoBloc code generation with async state management.
Bloc<Event, State>: Takes a Stream of Events as input and transforms them into a Stream of States as output.
BlocBase<State>: An interface for the core functionality implemented by both Bloc and Cubit.
BlocBuilder, S>: BlocBuilder handles building a widget in response to new states. BlocBuilder is analogous to StreamBuilder but has simplified API to reduce the amount of boilerplate code needed as well as bloc-specific performance improvements. Please refer to BlocListener if you want to "do" anything in response to state changes such as navigation, showing a dialog, etc...
BlocBuilderBase, S>: Base class for widgets that build themselves based on interaction with a specified bloc.
BlocConsumer, S>: BlocConsumer exposes a builder and listener in order react to new states. BlocConsumer is analogous to a nested BlocListener and BlocBuilder but reduces the amount of boilerplate needed. BlocConsumer should only be used when it is necessary to both rebuild UI and execute other reactions to state changes in the bloc.
BlocEventSink<Event extends Object?>: An ErrorSink that supports adding events.
BlocListener, S>: Takes a BlocWidgetListener and an optional bloc and invokes the listener in response to state changes in the bloc. It should be used for functionality that needs to occur only in response to a state change such as navigation, showing a SnackBar, showing a Dialog, etc... The listener is guaranteed to only be called once for each state change unlike the builder in BlocBuilder.
BlocListenerBase, S>: Base class for widgets that listen to state changes in a specified bloc.
BlocObserver: An interface for observing the behavior of Bloc instances.
BlocProvider<T extends StateStreamableSource<Object?>>: Takes a create function that is responsible for creating the Bloc or Cubit and a child which will have access to the instance via BlocProvider.of(context). It is used as a dependency injection (DI) widget so that a single instance of a Bloc or Cubit can be provided to multiple widgets within a subtree.
BlocSelector, S, T>: BlocSelector is analogous to BlocBuilder but allows developers to filter updates by selecting a new value based on the bloc state. Unnecessary builds are prevented if the selected value does not change.
Change<State>: A Change represents the change from one State to another. A Change consists of the currentState and nextState.
Closable: An object that must be closed when no longer in use.
Cubit<State>: A Cubit is similar to Bloc but has no notion of events and relies on methods to emit new states.
Emittable<State extends Object?>: An object that can emit new states.
EmittableStateStreamableSource<State>: A StateStreamableSource that can emit new states.
Emitter<State>: An Emitter is a class which is capable of emitting new states.
ErrorSink: A generic destination for errors.
FlutterMonoBlocActions: Base class for action handlers in Flutter projects.
FutureOr<T>: A type representing values that are either Future<T> or T.
MonoActions: Marks a mixin as containing action methods for MonoBloc.
MonoAsyncEmitter<S>
MonoAsyncSeqEmitter<S>: Wrapper around Emitter that provides convenient methods for async operations.
MonoAsyncValue<T>: Represents an asynchronous operation state with loading, data, or error. Similar to AsyncSnapshot but with additional error handling utilities.
MonoBloc: Marks a class for MonoBloc code generation.
MonoBlocActionListener: A Flutter widget that listens to actions from a MonoBloc and executes corresponding handlers with access to BuildContext.
MonoBlocActions: Base class for action handlers in pure Dart projects.
MonoEvent: Marks a method as an event handler in MonoBloc.
MonoEventTransformer: Wrapper for bloc_concurrency transformers to avoid type conflicts and provide type-safe transformers for MonoBloc queues.
MonoInit: Marks a method to be called during bloc initialization.
MonoOnError: Marks a method as an error handler for event errors.
MonoOnEvent: Marks a method as an event interceptor that runs before event processing.
MonoStackTrace: Utility for filtering and combining stack traces in MonoBloc error handling.
MultiBlocListener: Merges multiple BlocListener widgets into one widget tree.
MultiBlocObserver: A BlocObserver which supports registering multiple BlocObserver instances. This is useful when maintaining multiple BlocObserver instances for different functions e.g. LoggingBlocObserver, ErrorReportingBlocObserver.
MultiBlocProvider: Merges multiple BlocProvider widgets into one widget tree.
MultiRepositoryProvider: Merges multiple RepositoryProvider widgets into one widget tree.
RepositoryProvider<T>: Takes a create function that is responsible for creating the repository and a child which will have access to the repository via RepositoryProvider.of(context). It is used as a dependency injection (DI) widget so that a single instance of a repository can be provided to multiple widgets within a subtree.
StateStreamable<State>: A Streamable that provides synchronous access to the current state.
StateStreamableSource<State>: A StateStreamable that must be closed when no longer in use.
Streamable<State extends Object?>: An object that provides access to a stream of states over time.
Transition<Event, State>: A Transition is the change from one state to another. Consists of the currentState, an event, and the nextState.

Enums

MonoConcurrency: Defines how events are processed when multiple events are dispatched.

Mixins

MonoBlocActionMixin<A, S>: Mixin that adds action stream capability to a Bloc.

Extension Types

MonoSeqEmitter: Extension type that wraps Emitter for sequential blocs.

Extensions

ReadContext on BuildContext: Exposes the read method.
SelectContext on BuildContext: Adds a select method on BuildContext.
WatchContext on BuildContext: Exposes the watch method.

Constants

concurrentEvent → const MonoEvent: Shorthand constant for a concurrent event (processes in parallel)
droppableEvent → const MonoEvent: Shorthand constant for a droppable event (ignores new events while processing)
event → const MonoEvent: Shorthand constant for marking a method as an event handler
immutable → const Immutable: Used to annotate a class C. Indicates that C and all subtypes of C must be immutable.
onError → const MonoOnError: Shorthand constant for marking a method as an error handler
onEvent → const MonoOnEvent: Shorthand constant for marking a method as an event interceptor
onInit → const MonoInit: Shorthand constant for marking a method as an initialization handler
protected → const _Protected: Used to annotate an instance member in a class or mixin which is meant to be visible only within the declaring library, and to other instance members of the class or mixin, and their subtypes.
restartableEvent → const MonoEvent: Shorthand constant for a restartable event (cancels previous events)
sequentialEvent → const MonoEvent: Shorthand constant for a sequential event (processes in order)

Functions

unawaited(Future<void>? future) → void: Explicitly ignores a future.

Typedefs

BlocBuilderCondition<S> = bool Function(S previous, S current): Signature for the buildWhen function which takes the previous state and the current state and is responsible for returning a bool which determines whether to rebuild BlocBuilder with the current state.
BlocListenerCondition<S> = bool Function(S previous, S current): Signature for the listenWhen function which takes the previous state and the current state and is responsible for returning a bool which determines whether or not to call BlocWidgetListener of BlocListener with the current state.
BlocWidgetBuilder<S> = Widget Function(BuildContext context, S state): Signature for the builder function which takes the BuildContext and state and is responsible for returning a widget which is to be rendered. This is analogous to the builder function in StreamBuilder.
BlocWidgetListener<S> = void Function(BuildContext context, S state): Signature for the listener function which takes the BuildContext along with the state and is responsible for executing in response to state changes.
BlocWidgetSelector<S, T> = T Function(S state): Signature for the selector function which is responsible for returning a selected value, T, based on state.
EventHandler<Event, State> = FutureOr<void> Function(Event event, Emitter<State> emit): An event handler is responsible for reacting to an incoming Event and can emit zero or more states via the Emitter.
EventMapper<Event> = Stream<Event> Function(Event event): Signature for a function which converts an incoming event into an outbound stream of events. Used when defining custom EventTransformers.
EventTransformer<Event> = Stream<Event> Function(Stream<Event> events, EventMapper<Event> mapper): Used to change how events are processed. By default events are processed concurrently.
MonoBlocConcurrency = MonoEventTransformer: Deprecated alias for MonoEventTransformer.

Exceptions / Errors

ProviderNotFoundException: The error that will be thrown if Provider.of fails to find a Provider as an ancestor of the BuildContext used.

mono_bloc_flutter library

Usage with when()

Usage with of()

Classes

Enums

Mixins

Extension Types

Extensions

Constants

Functions

Typedefs

Exceptions / Errors

mono_bloc_flutter package

mono_bloc_flutter library

Usage with `when()`

Usage with `of()`