MonoBloc

https://github.com/westito/mono_bloc
Admin
MonoBloc is a Dart/Flutter package that simplifies BLoC architecture by allowing developers to...
Tokens:36,259
Snippets:208
Trust Score:5.8
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### MonoBloc Setup and Generation Commands

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

These bash commands are used for setting up the project, running the code generator, executing tests, and publishing packages.

```bash
sip setup                    # Install dependencies
./scripts/generate.sh        # Run build_runner for all packages
./scripts/tests.sh           # Clean, generate, run all tests
./scripts/publish.sh         # Publish packages to pub.dev
```

--------------------------------

### Install Application Bundle (CMake)

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/CMakeLists.txt

This section details the installation process for the Mono Bloc application. It configures the installation prefix, cleans the build bundle directory, and installs the executable, Flutter ICU data, core Flutter library, bundled plugin libraries, native assets, and application assets. It also conditionally installs the AOT library for non-Debug builds.

```cmake
# === Installation ===
# By default, "installing" just makes a relocatable bundle in the build
# directory.
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

# Start with a clean build bundle directory every time.
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Create MonoBloc Counter Example (Dart)

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Example of creating a simple CounterBloc using MonoBloc annotations. Events are defined as methods, and the initial state is set.

```dart
import 'package:mono_bloc/mono_bloc.dart';

part 'counter_bloc.g.dart';

@MonoBloc()
class CounterBloc extends _$CounterBloc<int> {
  CounterBloc() : super(0);

  @event
  int _onIncrement() => state + 1;

  @event
  int _onDecrement() => state - 1;

  @event
  int _onReset() => 0;
}
```

--------------------------------

### Integration Test Example with blocTest

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Demonstrates how to write integration tests for bloc behavior using the `blocTest` function. This test verifies that the bloc emits states in the expected sequence after an action is performed. It assumes the existence of `TestBloc` and `TestState` classes.

```dart
// Located in test/*/*.dart with corresponding .g.dart files
blocTest<TestBloc, TestState>(
  'emits states in sequence',
  build: () => TestBloc(),
  act: (bloc) => bloc.increment(),
  expect: () => [TestState(1)],
);
```

--------------------------------

### CMake Installation Rules for Application Components

Source: https://github.com/westito/mono_bloc/blob/main/example/windows/CMakeLists.txt

Configures the installation process for the application, including setting the installation prefix, installing the main executable, Flutter ICU data, libraries, bundled plugin libraries, native assets, and application assets. It ensures files are copied to the correct destinations for runtime execution.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Install mono_bloc_flutter Package

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc_flutter/README.md

Add mono_bloc_flutter and mono_bloc_generator to your project dependencies. The mono_bloc_generator is used for code generation and build_runner is required for running the generator.

```yaml
dependencies:
  flutter:
    sdk: flutter
  mono_bloc_flutter: ^1.0.0

dev_dependencies:
  mono_bloc_generator: ^1.0.0
  build_runner: ^2.10.0
```

--------------------------------

### MonoBloc Analyzer API Patterns in Dart

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Examples of how to interact with the Dart Analyzer API to access source file information, type display strings, and cast parameters.

```dart
// Access source file
element.library.firstFragment.source.fullName

// Get display string (no withNullability parameter)
type.getDisplayString()

// Cast parameters
action.parameters.cast<FormalParameterElement>()
```

--------------------------------

### Dart Bloc Event Calling Example

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Shows how to call bloc events after they are generated, with underscores and prefixes removed.

```dart
void main() {
  final bloc = CounterBloc();
  bloc.increment();  // Calls _onIncrement
  bloc.loadTodos();  // Calls _onLoadTodos
}
```

--------------------------------

### MonoBloc Package-Specific Commands

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Commands for managing dependencies, running code generation, and executing tests for individual MonoBloc packages.

```bash
# Generator (most development happens here)
cd mono_bloc_generator
dart run build_runner build --delete-conflicting-outputs
dart test -r failures-only && echo 'TEST PASS'
dart test test/generator/specific_test.dart

# Core package
cd mono_bloc
dart test -r failures-only && echo 'TEST PASS'

# Flutter packages
cd mono_bloc_flutter && flutter test -r failures-only
cd mono_bloc_hooks && flutter test -r failures-only

# Example app
cd example
dart run build_runner build --delete-conflicting-outputs
flutter test -r failures-only && echo 'TEST PASS'
```

--------------------------------

### Dependency Installation (YAML)

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc_hooks/README.md

This snippet shows how to add the necessary dependencies to your pubspec.yaml file. It includes mono_bloc_hooks, mono_bloc_flutter, flutter_hooks, and development dependencies for code generation.

```yaml
dependencies:
  flutter:
    sdk: flutter
  mono_bloc_flutter: ^1.0.0  # Exports flutter_bloc + mono_bloc
  mono_bloc_hooks: ^1.0.0
  flutter_hooks: ^0.21.0  # Required peer dependency

dev_dependencies:
  mono_bloc_generator: ^1.0.0
  build_runner: ^2.10.0
```

--------------------------------

### MonoBloc Generator Architecture Pipeline

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

The pipeline illustrates the flow of code generation, starting from source code and ending with generated Dart files.

```plaintext
Source Code (.dart)
    ↓
BlocVisitor (analyzer)
    ↓
BlocElement / MethodElement (models)
    ↓
Writers (code_builder)
    ↓
Generated Code (.g.dart)
```

--------------------------------

### Actions Pattern Implementation with @MonoActions and @MonoBloc

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Explains the Actions pattern for handling side effects like navigation or notifications. It shows how to define actions in a private mixin annotated with `@MonoActions()` and how a bloc can extend a generated base class that includes these actions. The example also covers shared actions by implementing a public base mixin.

```dart
// 1. Define actions in a private mixin with @MonoActions()
@MonoActions()
mixin _MyBlocActions {
  void navigateTo(String route);
  void showError(String message);
}

// 2. Bloc extends generated base class (actions mixin included automatically)
// DO NOT add 'with _MyBlocActions' - it's already in _$MyBloc
@MonoBloc()
class MyBloc extends _$MyBloc<MyState> {
  MyBloc() : super(MyState());
  
  @event
  Future<MyState> _onSubmit() async {
    navigateTo('/success');  // Call action
    return state.copyWith(submitted: true);
  }
}
```

```dart
mixin ErrorHandlerActions {
  void showError(String message);
}

@MonoActions()
mixin _OrderBlocActions implements ErrorHandlerActions {
  void navigateToOrder(String orderId);
}
```

--------------------------------

### Use Generated MonoBloc Counter (Dart)

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Example of how to instantiate and use the generated CounterBloc. Demonstrates calling the generated event methods and accessing the state.

```dart
void main() {
  final bloc = CounterBloc();
  
  // Generated methods - clean and type-safe
  bloc.increment();
  bloc.decrement();
  bloc.reset();
  
  print(bloc.state); // 0
}
```

--------------------------------

### Install MonoBloc Dependencies (Dart)

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Dependencies for pure Dart projects using MonoBloc. Includes the core library, the generator, and build_runner for code generation.

```yaml
dependencies:
  mono_bloc: ^1.0.0

dev_dependencies:
  mono_bloc_generator: ^1.0.0
  build_runner: ^2.10.0
```

--------------------------------

### Type Preservation Example: Typedef and Record

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Illustrates how the generator preserves exact type notation from the source code, including `typedef` and record types. It shows the correct generated output and contrasts it with an incorrect expansion, emphasizing the use of helper functions like `_readAllParameterTypesFromSource()` for accurate type resolution.

```dart
// Source
typedef OnComplete = void Function(bool);
void doAction(OnComplete callback, (String, int) data);

// Generated (preserves typedef and record)
final OnComplete callback;
final (String, int) data;

// NOT expanded to:
final void Function(bool) callback;  // Wrong!
```

--------------------------------

### Install MonoBloc Dependencies (Flutter)

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Dependencies for Flutter projects using MonoBloc. Includes the Flutter-specific export, the generator, and build_runner.

```yaml
dependencies:
  flutter:
    sdk: flutter
  mono_bloc_flutter: ^1.0.0  # Exports flutter_bloc + mono_bloc

dev_dependencies:
  mono_bloc_generator: ^1.0.0
  build_runner: ^2.10.0
```

--------------------------------

### MonoBloc Project Structure

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

The MonoBloc project is structured as a monorepo with four main packages: core, generator, Flutter widgets, and Flutter hooks, followed by an example application.

```plaintext
mono_bloc/           # Core: annotations, async helpers, utilities (pure Dart)
mono_bloc_generator/ # Code generator: visitors, writers, models
mono_bloc_flutter/   # Flutter widgets: MonoBlocActionListener
mono_bloc_hooks/     # Flutter hooks: useMonoAction
example/             # Demo Flutter app with all features
```

--------------------------------

### MonoBloc Feature Example with Dart

Source: https://github.com/westito/mono_bloc/blob/main/README.md

Demonstrates defining actions, sequential event processing, events with different return types (Future, Stream), concurrency control, preventing duplicate submissions, error handling, initialization, and integrating with Flutter UI using MonoBlocActionListener and Flutter Hooks.

```dart
import 'package:mono_bloc_flutter/mono_bloc_flutter.dart';

part 'todo_bloc.g.dart';

// 1. Define actions in a private mixin with @MonoActions()
@MonoActions()
mixin _TodoBlocActions {
  void showSuccess(String message);
  
  void navigateToDetail(String todoId);
}

// 2. Sequential mode - all events processed in order, waiting for each to finish
@MonoBloc(sequential: true)
class TodoBloc extends _$TodoBloc<TodoState> {
  TodoBloc() : super(TodoState());
  
  // 3. Events with different return types
  @event
  Future<TodoState> _onLoadTodos() async {
    final todos = await repository.fetchTodos();
    return state.copyWith(todos: todos);
  }
  
  @restartableEvent  // 4. Concurrency control - cancels previous search
  Stream<TodoState> _onSearch(String query) async* {
    yield state.copyWith(isSearching: true);
    final results = await repository.search(query);
    yield state.copyWith(isSearching: false, todos: results);
  }
  
  @event  // 5. Stream with loading/data yields for progressive updates
  Stream<TodoState> _onLoadFromMultipleSources() async* {
    yield state.copyWith(isLoading: true);
    final allTodos = <Todo>[];
    for (final source in TodoSource.values) {
      final todos = await repository.fetchFrom(source);
      allTodos.addAll(todos);
      yield state.copyWith(isLoading: false, todos: allTodos);
    }
  }
  
  @droppableEvent  // 6. Prevents duplicate submissions
  Future<TodoState> _onAddTodo(String title) async {
    final todo = await repository.add(title);
    showSuccess('Todo added!');  // Trigger action
    return state.copyWith(todos: [...state.todos, todo]);
  }
  
  @event
  Future<TodoState> _onToggleTodo(String id) async {
    final todos = state.todos.map((t) => t.id == id ? t.copyWith(completed: !t.completed) : t).toList();
    return state.copyWith(todos: todos);
  }
  
  @event
  Future<TodoState> _onDeleteTodo(String id) async {
    await repository.delete(id);
    navigateToDetail('list');  // Trigger navigation action
    return state.copyWith(todos: state.todos.where((t) => t.id != id).toList());
  }
  
  // 7. Error handling - centralized for all events
  @onError
  TodoState _onError(Object error, StackTrace stackTrace) {
    return state.copyWith(error: error.toString());
  }
  
  // 8. Initialization - runs automatically on creation
  @onInit
  void _onInit() {
    loadTodos();  // Dispatch event to load initial data
  }
}

// 9. Flutter integration - handle actions with MonoBlocActionListener
class TodoPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MonoBlocActionListener<TodoBloc>(
      actions: TodoBlocActions.when(
        showSuccess: (context, message) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text(message)),
          );
        },
        navigateToDetail: (context, todoId) {
          Navigator.pushNamed(context, '/detail', arguments: todoId);
        },
      ),
      child: BlocBuilder<TodoBloc, TodoState>(
        builder: (context, state) {
          // Build UI based on state
        },
      ),
    );
  }
}

// 10. Flutter Hooks support - cleaner action handling
class TodoPageWithHooks extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final bloc = useBloc<TodoBloc>();
    
    useMonoBlocActionListener(
      bloc,
      TodoBlocActions.when(
        showSuccess: (context, message) { /* Show snackbar */ },
        navigateToDetail: (context, todoId) { /* Navigate */ },
      ),
    );
    
    return BlocBuilder<TodoBloc, TodoState>(
      builder: (context, state) {
        // Build UI
      },
    );
  }
}

```

--------------------------------

### MonoBloc Imports for Flutter with Actions

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Shows the required setup for integrating MonoBloc into a Flutter project, including support for actions. It specifies the `mono_bloc_flutter` import and the `part` directive. It also demonstrates how to define action side-effects using `@MonoActions()` mixin.

```dart
import 'package:mono_bloc_flutter/mono_bloc_flutter.dart';

part 'my_bloc.g.dart';

@MonoActions()
mixin _MyBlocActions {
  void showMessage(String message);
}

// No need to add 'with _MyBlocActions' - it's included in _$MyBloc
@MonoBloc()
class MyBloc extends _$MyBloc<MyState> {
  MyBloc() : super(initialState);
  
  @event
  MyState _onEvent() => newState;
}
```

--------------------------------

### CMake Project Setup and Configuration

Source: https://github.com/westito/mono_bloc/blob/main/example/windows/CMakeLists.txt

Sets up the CMake version, project name, executable name, and handles multi-configuration generators. It defines build types and configures linker and compiler flags for different build modes.

```cmake
cmake_minimum_required(VERSION 3.14)
project(mono_bloc_example LANGUAGES CXX)

set(BINARY_NAME "mono_bloc_example")

cmake_policy(VERSION 3.14...3.25)

get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
  set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
    CACHE STRING "" FORCE)
else()
  if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    set(CMAKE_BUILD_TYPE "Debug" CACHE
      STRING "Flutter build mode" FORCE)
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
      "Debug" "Profile" "Release")
  endif()
endif()

set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
set(CMAKE_CXX_FLAGS_PROFILE "${CMAKE_CXX_FLAGS_RELEASE}")

add_definitions(-DUNICODE -D_UNICODE)
```

--------------------------------

### Install MonoBloc Dependencies (Flutter + Hooks)

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Dependencies for Flutter projects using MonoBloc with flutter_hooks. Includes MonoBloc Flutter export, MonoBloc Hooks, flutter_hooks, the generator, and build_runner.

```yaml
dependencies:
  flutter:
    sdk: flutter
  mono_bloc_flutter: ^1.0.0  # Exports flutter_bloc + mono_bloc
  mono_bloc_hooks: ^1.0.0
  flutter_hooks: ^0.21.0

dev_dependencies:
  mono_bloc_generator: ^1.0.0
  build_runner: ^2.10.0
```

--------------------------------

### Automatic Initialization with @onInit in Dart

Source: https://context7.com/westito/mono_bloc/llms.txt

The @onInit annotation in MonoBloc allows methods to be automatically executed when a bloc instance is created. This is useful for performing setup tasks, such as loading initial data, subscribing to services, or initializing analytics. These methods are called after the bloc's constructor.

```dart
import 'package:mono_bloc/mono_bloc.dart';

part 'app_bloc.g.dart';

@MonoBloc()
class AppBloc extends _$AppBloc<AppState> {
  AppBloc() : super(const AppState());

  @onInit
  void _onInit() {
    // Called automatically after constructor
    loadUserPreferences();
    subscribeToNotifications();
  }

  @onInit
  void _initializeAnalytics() {
    analytics.initialize();
  }

  @event
  Future<AppState> _onLoadUserPreferences() async {
    final prefs = await prefsService.load();
    return state.copyWith(preferences: prefs);
  }

  @event
  void _onSubscribeToNotifications(_Emitter emit) {
    notificationService.stream.listen((notification) {
      emit(state.copyWith(notification: notification));
    });
  }
}

// Usage
void main() {
  final bloc = AppBloc(); // Automatically calls _onInit methods

  // User preferences and analytics already initialized
  bloc.stream.listen((state) {
    print('State: $state');
  });
}
```

--------------------------------

### MonoBloc Feature Example - Dart

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Demonstrates the full feature set of MonoBloc, including defining actions, sequential event processing, various event types (@event, @restartableEvent, @droppableEvent), stream-based state updates, error handling, initialization, and Flutter integration using MonoBlocActionListener and Flutter Hooks.

```dart
import 'package:mono_bloc_flutter/mono_bloc_flutter.dart';

part 'todo_bloc.g.dart';

// 1. Define actions in a private mixin with @MonoActions()
@MonoActions()
mixin _TodoBlocActions {
  void showSuccess(String message);
  
  void navigateToDetail(String todoId);
}

// 2. Sequential mode - all events processed in order, waiting for each to finish
@MonoBloc(sequential: true)
class TodoBloc extends _$TodoBloc<TodoState> {
  TodoBloc() : super(TodoState());
  
  // 3. Events with different return types
  @event
  Future<TodoState> _onLoadTodos() async {
    final todos = await repository.fetchTodos();
    return state.copyWith(todos: todos);
  }
  
  @restartableEvent  // 4. Concurrency control - cancels previous search
  Stream<TodoState> _onSearch(String query) async*
{
    yield state.copyWith(isSearching: true);
    final results = await repository.search(query);
    yield state.copyWith(isSearching: false, todos: results);
  }
  
  @event  // 5. Stream with loading/data yields for progressive updates
  Stream<TodoState> _onLoadFromMultipleSources() async*
{
    yield state.copyWith(isLoading: true);
    final allTodos = <Todo>[];
    for (final source in TodoSource.values) {
      final todos = await repository.fetchFrom(source);
      allTodos.addAll(todos);
      yield state.copyWith(isLoading: false, todos: allTodos);
    }
  }
  
  @droppableEvent  // 6. Prevents duplicate submissions
  Future<TodoState> _onAddTodo(String title) async {
    final todo = await repository.add(title);
    showSuccess('Todo added!');  // Trigger action
    return state.copyWith(todos: [...state.todos, todo]);
  }
  
  @event
  Future<TodoState> _onToggleTodo(String id) async {
    final todos = state.todos.map((t) => t.id == id ? t.copyWith(completed: !t.completed) : t).toList();
    return state.copyWith(todos: todos);
  }
  
  @event
  Future<TodoState> _onDeleteTodo(String id) async {
    await repository.delete(id);
    navigateToDetail('list');  // Trigger navigation action
    return state.copyWith(todos: state.todos.where((t) => t.id != id).toList());
  }
  
  // 7. Error handling - centralized for all events
  @onError
  TodoState _onError(Object error, StackTrace stackTrace) {
    return state.copyWith(error: error.toString());
  }
  
  // 8. Initialization - runs automatically on creation
  @onInit
  void _onInit() {
    loadTodos();  // Dispatch event to load initial data
  }
}

// 9. Flutter integration - handle actions with MonoBlocActionListener
class TodoPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MonoBlocActionListener<TodoBloc>(
      actions: TodoBlocActions.when(
        showSuccess: (context, message) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text(message)),
          );
        },
        navigateToDetail: (context, todoId) {
          Navigator.pushNamed(context, '/detail', arguments: todoId);
        },
      ),
      child: BlocBuilder<TodoBloc, TodoState>(
        builder: (context, state) {
          // Build UI based on state
        },
      ),
    );
  }
}

// 10. Flutter Hooks support - cleaner action handling
class TodoPageWithHooks extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final bloc = useBloc<TodoBloc>();
    
    useMonoBlocActionListener(
      bloc,
      TodoBlocActions.when(
        showSuccess: (context, message) { /* Show snackbar */ },
        navigateToDetail: (context, todoId) { /* Navigate */ },
      ),
    );
    
    return BlocBuilder<TodoBloc, TodoState>(
      builder: (context, state) {
        // Build UI
      },
    );
  }
}

```

--------------------------------

### MonoBloc Troubleshooting Commands

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Bash commands to resolve common issues like cache problems or analyze code for errors.

```bash
# Cache issues - delete .dart_tool before testing
rm -rf .dart_tool && dart test -r failures-only

# Analysis errors only
dart analyze | grep error
```

--------------------------------

### Set Project and Executable Names (CMake)

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/CMakeLists.txt

This snippet defines the minimum required CMake version, the project name, and the name of the executable. It also sets the unique GTK application identifier. These settings are fundamental for project setup and identification.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "mono_bloc_example")
# The unique GTK application identifier for this application. See:
# https://wiki.gnome.org/HowDoI/ChooseApplicationID
set(APPLICATION_ID "com.example.mono_bloc_example")
```

--------------------------------

### Regenerate Project and Run Tests

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Provides a command-line sequence to resolve common test failures after making changes to the MonoBloc project. This involves deleting the `.dart_tool` directory, rebuilding the project using `build_runner`, and then running tests with a filter for failures.

```bash
rm -rf .dart_tool
dart run build_runner build --delete-conflicting-outputs
dart test -r failures-only
```

--------------------------------

### MonoBloc Stream-based Events for Progressive Updates

Source: https://context7.com/westito/mono_bloc/llms.txt

Events can return streams to emit multiple states over time, enabling progressive updates. This example shows a TodoBloc that searches across multiple sources and yields state updates after each source completes, followed by a final state. It also includes an auto-incrementing counter stream.

```dart
import 'package:mono_bloc/mono_bloc.dart';

part 'todo_bloc.g.dart';

@MonoBloc()
class TodoBloc extends _$TodoBloc<TodoState> {
  TodoBloc() : super(const TodoState());

  // Stream with progressive loading from multiple sources
  @restartableEvent
  Stream<TodoState> _onSearchAcrossSources(String query) async*
    yield state.copyWith(loading: true, results: []);

    final allResults = <Todo>[];
    for (final source in [Source.local, Source.cloud, Source.cache]) {
      final results = await source.search(query);
      allResults.addAll(results);

      // Yield after each source completes
      yield state.copyWith(
        results: allResults,
        loadedSources: state.loadedSources + 1,
      );
    }

    yield state.copyWith(loading: false);
  }

  // Stream with auto-increment counter
  @event
  Stream<TodoState> _onAutoCount(int max) async*
    for (int i = 0; i < max; i++) {
      await Future.delayed(Duration(seconds: 1));
      yield state.copyWith(count: i);
    }
  }
}

// Usage
void main() {
  final bloc = TodoBloc();

  bloc.stream.listen((state) {
    print('Results: ${state.results.length}, Sources: ${state.loadedSources}');
  });

  bloc.searchAcrossSources('flutter');
  // Emits progressive updates as each source completes
}
```

--------------------------------

### Dart Mono Bloc Initialization with @onInit

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Demonstrates how to use the @onInit annotation to run initialization code automatically when a bloc is created. Initialization methods should return void and dispatch events.

```dart
@MonoBloc()
class MyBloc extends _$MyBloc<MyState> {
  MyBloc() : super(MyState.initial());

  @onInit
  void _onInit() {
    loadItems();  // Dispatch event to load data
  }

  @event
  Future<MyState> _onLoadItems() async {
    final items = await repository.fetchAll();
    return MyState(items: items);
  }
}
```

--------------------------------

### Configure C++ Executable Build with CMake

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/runner/CMakeLists.txt

This snippet sets up the C++ executable for the project using CMake. It defines the executable name, lists source files, applies standard build settings, adds preprocessor definitions for the application ID, and links necessary libraries such as Flutter and GTK. It also specifies include directories.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Add preprocessor definitions for the application ID.
add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")

# Add dependency libraries. Add any application-specific dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)

target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
```

--------------------------------

### MonoBloc Negative Tests in Dart

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Dart test cases to ensure that invalid source code inputs result in specific, helpful error messages.

```dart
test('rejects public mixin with @MonoActions', () async {
  expect(
    () => generateForSource(invalidSource),
    throwsA(isA<InvalidGenerationSourceError>().having(
      (e) => e.message,
      'message',
      contains('must be private'),
    )),
  );
});
```

--------------------------------

### MonoBloc Generator Output Tests in Dart

Source: https://github.com/westito/mono_bloc/blob/main/AGENTS.md

Dart test cases to verify that the code generator produces output containing expected code patterns.

```dart
test('generates event with trace field', () async {
  final result = await generateForSource(source);
  expect(result, contains('final StackTrace trace;'));
  expect(result, contains('trace = StackTrace.current'));
});
```

--------------------------------

### Import mono_bloc_flutter Package

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc_flutter/README.md

To use the features provided by the mono_bloc_flutter package, import it with a single import statement.

```dart
import 'package:mono_bloc_flutter/mono_bloc_flutter.dart';
```

--------------------------------

### Actions Pattern: Bloc Implementation in Dart

Source: https://github.com/westito/mono_bloc/blob/main/mono_bloc/README.md

Implements a bloc class that extends a generated base class including the actions mixin. This example shows how to trigger actions like `trackAnalyticsEvent`, `navigateToConfirmation`, and `showNotification` within bloc event handlers.

```dart
@MonoBloc()
class CheckoutBloc extends _$CheckoutBloc<CheckoutState> {
  CheckoutBloc() : super(CheckoutState());
  
  // Events - modify state as usual
  @event
  Future<CheckoutState> _onSubmitOrder(Order order) async {
    try {
      final orderId = await repository.submitOrder(order);
      
      // Trigger actions during event processing
      trackAnalyticsEvent('order_submitted', {'orderId': orderId});
      navigateToConfirmation(orderId);
      showNotification(
        message: 'Order submitted successfully!',
        type: NotificationType.success,
      );
      
      return state.copyWith(isProcessing: false);
    } catch (e) {
      showNotification(
        message: 'Failed to submit order',
        type: NotificationType.error,
      );
      rethrow;
    }
  }
}
```

--------------------------------

### CMake: System Dependency Checks (PkgConfig)

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/flutter/CMakeLists.txt

This section uses PkgConfig to find and check for required system libraries: GTK, GLIB, and GIO. It ensures these dependencies are available and provides imported targets for linking against them. This is crucial for Flutter's Linux desktop integration.

```cmake
# System-level dependencies.
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```

--------------------------------

### CMake: Configure Flutter Library and Wrapper

Source: https://github.com/westito/mono_bloc/blob/main/example/windows/flutter/CMakeLists.txt

This snippet demonstrates how to configure the Flutter library and its C++ wrapper using CMake. It sets include directories, links libraries, and adds dependencies for the Flutter library and wrapper targets.

```cmake
cmake_minimum_required(VERSION 3.14)

set(EPHEMERAL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ephemeral")

# Configuration provided via flutter tool.
include(${EPHEMERAL_DIR}/generated_config.cmake)

# TODO: Move the rest of this into files in ephemeral. See
# https://github.com/flutter/flutter/issues/57146.
set(WRAPPER_ROOT "${EPHEMERAL_DIR}/cpp_client_wrapper")

# Set fallback configurations for older versions of the flutter tool.
if (NOT DEFINED FLUTTER_TARGET_PLATFORM)
  set(FLUTTER_TARGET_PLATFORM "windows-x64")
endif()

# === Flutter Library ===
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/flutter_windows.dll")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/windows/app.so" PARENT_SCOPE)

list(APPEND FLUTTER_LIBRARY_HEADERS
  "flutter_export.h"
  "flutter_windows.h"
  "flutter_messenger.h"
  "flutter_plugin_registrar.h"
  "flutter_texture_registrar.h"
)
list(TRANSFORM FLUTTER_LIBRARY_HEADERS PREPEND "${EPHEMERAL_DIR}/")
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}.lib")
add_dependencies(flutter flutter_assemble)

# === Wrapper ===
list(APPEND CPP_WRAPPER_SOURCES_CORE
  "core_implementations.cc"
  "standard_codec.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_CORE PREPEND "${WRAPPER_ROOT}/")
list(APPEND CPP_WRAPPER_SOURCES_PLUGIN
  "plugin_registrar.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_PLUGIN PREPEND "${WRAPPER_ROOT}/")
list(APPEND CPP_WRAPPER_SOURCES_APP
  "flutter_engine.cc"
  "flutter_view_controller.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_APP PREPEND "${WRAPPER_ROOT}/")

# Wrapper sources needed for a plugin.
add_library(flutter_wrapper_plugin STATIC
  ${CPP_WRAPPER_SOURCES_CORE}
  ${CPP_WRAPPER_SOURCES_PLUGIN}
)
apply_standard_settings(flutter_wrapper_plugin)
set_target_properties(flutter_wrapper_plugin PROPERTIES
  POSITION_INDEPENDENT_CODE ON)
set_target_properties(flutter_wrapper_plugin PROPERTIES
  CXX_VISIBILITY_PRESET hidden)
target_link_libraries(flutter_wrapper_plugin PUBLIC flutter)
target_include_directories(flutter_wrapper_plugin PUBLIC
  "${WRAPPER_ROOT}/include"
)
add_dependencies(flutter_wrapper_plugin flutter_assemble)

# Wrapper sources needed for the runner.
add_library(flutter_wrapper_app STATIC
  ${CPP_WRAPPER_SOURCES_CORE}
  ${CPP_WRAPPER_SOURCES_APP}
)
apply_standard_settings(flutter_wrapper_app)
target_link_libraries(flutter_wrapper_app PUBLIC flutter)
target_include_directories(flutter_wrapper_app PUBLIC
  "${WRAPPER_ROOT}/include"
)
add_dependencies(flutter_wrapper_app flutter_assemble)

```

--------------------------------

### Filter Specific Event Type with @onEvent in Dart

Source: https://github.com/westito/mono_bloc/blob/main/README.md

This Dart code example shows how to apply an @onEvent filter to a specific event type, '_LoadDataEvent'. The _onLoadDataFilter method checks if the bloc is already loading and prevents the 'loadData' event from being processed if it is, effectively guarding against race conditions.

```dart
@AsyncMonoBloc()
class DataBloc extends _$DataBloc<Data> {
  DataBloc() : super(const MonoAsyncValue.withData(initialData));

  @event
  Future<Data> _onLoadData() async {
    return await repository.loadData();
  }

  @event
  Future<Data> _onRefreshData() async {
    return await repository.refreshData();
  }

  /// Only filter the loadData event
  @onEvent
  bool _onLoadDataFilter(_LoadDataEvent event) {
    // Skip loadData if already loading
    if (state.isLoading) {
      print('Skipping loadData - already loading');
      return false;
    }
    return true;
  }

  // refreshData is not filtered, can run anytime
}
```

--------------------------------

### CMake: Custom Build Command for Flutter Tool Backend

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/flutter/CMakeLists.txt

This `add_custom_command` defines a build step that executes the Flutter tool backend script. It's designed to run every time due to the use of a `_phony_` target, as there's no direct mechanism to track all inputs/outputs of the Flutter tool. The command is set up to use environment variables and passes build configuration parameters.

```cmake
# === Flutter tool backend ===
# _phony_ is a non-existent file to force this command to run every time, 
# since currently there's no way to get a full input/output list from the
# flutter tool.
add_custom_command(
  OUTPUT ${FLUTTER_LIBRARY} ${FLUTTER_LIBRARY_HEADERS}
    ${CMAKE_CURRENT_BINARY_DIR}/_phony_
  COMMAND ${CMAKE_COMMAND} -E env
    ${FLUTTER_TOOL_ENVIRONMENT}
    "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
  VERBATIM
)
add_custom_target(flutter_assemble DEPENDS
  "${FLUTTER_LIBRARY}"
  ${FLUTTER_LIBRARY_HEADERS}
)
```

--------------------------------

### Include Generated Plugins (CMake)

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/CMakeLists.txt

This command includes the CMake file responsible for generating plugin build rules. These rules manage the building of plugins and their integration into the application.

```cmake
# Generated plugin build rules, which manage building the plugins and adding
# them to the application.
include(flutter/generated_plugins.cmake)
```

--------------------------------

### MonoBloc Emitter Pattern for Multiple State Emissions

Source: https://context7.com/westito/mono_bloc/llms.txt

The _Emitter parameter provides fine-grained control over state emissions, allowing for multiple state changes within a single event handler. This example demonstrates phased loading of data with progressive updates and synchronous resetting of multiple state properties.

```dart
import 'package:mono_bloc/mono_bloc.dart';

part 'data_bloc.g.dart';

@MonoBloc()
class DataBloc extends _$DataBloc<DataState> {
  DataBloc() : super(const DataState());

  // Multiple emissions with _Emitter
  @event
  Future<void> _onLoadData(_Emitter emit) async {
    // Phase 1: Loading
    emit(state.copyWith(loading: true, progress: 0.0));

    // Phase 2: Fetch users
    final users = await api.fetchUsers();
    emit(state.copyWith(users: users, progress: 0.33));

    // Phase 3: Fetch posts
    final posts = await api.fetchPosts();
    emit(state.copyWith(posts: posts, progress: 0.66));

    // Phase 4: Fetch comments
    final comments = await api.fetchComments();
    emit(state.copyWith(comments: comments, progress: 1.0));

    // Phase 5: Complete
    emit(state.copyWith(loading: false));
  }

  // Synchronous multiple emissions
  @event
  void _onReset(_Emitter emit) {
    emit(state.copyWith(users: []));
    emit(state.copyWith(posts: []));
    emit(state.copyWith(comments: []));
    emit(const DataState());
  }
}

// Usage
void main() {
  final bloc = DataBloc();

  bloc.stream.listen((state) {
    print('Progress: ${state.progress * 100}%');
  });

  bloc.loadData(); // Emits 5 states showing progressive loading
}
```

--------------------------------

### Configure Application Target with CMake

Source: https://github.com/westito/mono_bloc/blob/main/example/windows/runner/CMakeLists.txt

Defines the main executable target for the application, listing all necessary source files and resource files. It integrates with Flutter's build system by including generated plugin registration files. This configuration is essential for building the runner executable.

```cmake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Add preprocessor definitions for the build version.
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION=\"${FLUTTER_VERSION}\" ")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MAJOR=${FLUTTER_VERSION_MAJOR}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MINOR=${FLUTTER_VERSION_MINOR}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_PATCH=${FLUTTER_VERSION_PATCH}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_BUILD=${FLUTTER_VERSION_BUILD}")

# Disable Windows macros that collide with C++ standard library functions.
target_compile_definitions(${BINARY_NAME} PRIVATE "NOMINMAX")

# Add dependency libraries and include directories. Add any application-specific
# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_link_libraries(${BINARY_NAME} PRIVATE "dwmapi.lib")
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### MonoBloc Concurrency Transformers (@restartable, @droppable, @sequential)

Source: https://context7.com/westito/mono_bloc/llms.txt

Control concurrent event processing using built-in transformers like @restartableEvent (cancel previous), @droppableEvent (ignore new), and @sequentialEvent (process one by one). The default '@event' processes concurrently. This example demonstrates their usage within a Dart SearchBloc.

```dart
import 'package:mono_bloc/mono_bloc.dart';

part 'search_bloc.g.dart';

@MonoBloc()
class SearchBloc extends _$SearchBloc<SearchState> {
  SearchBloc() : super(const SearchState());

  // Restartable: cancel previous search when new one arrives
  @restartableEvent
  Future<SearchState> _onSearch(String query) async {
    final results = await api.search(query);
    return state.copyWith(results: results);
  }

  // Droppable: ignore new submissions while processing
  @droppableEvent
  Future<SearchState> _onSubmitForm(FormData data) async {
    await api.submit(data);
    return state.copyWith(submitted: true);
  }

  // Sequential: process one at a time
  @sequentialEvent
  Future<SearchState> _onLoadPage(int page) async {
    final data = await api.loadPage(page);
    return state.copyWith(page: page, data: data);
  }

  // Concurrent: process in parallel (default)
  @event
  Future<SearchState> _onLoadMetadata() async {
    final metadata = await api.getMetadata();
    return state.copyWith(metadata: metadata);
  }
}

// Usage
void main() {
  final bloc = SearchBloc();

  // Rapid typing: previous searches are cancelled
  bloc.search('fl');
  bloc.search('flu');
  bloc.search('flutt');
  bloc.search('flutter'); // Only this completes

  // Double-click: second click ignored while first processes
  bloc.submitForm(data);
  bloc.submitForm(data); // Ignored
}
```

--------------------------------

### CMake: List Prepending Function

Source: https://github.com/westito/mono_bloc/blob/main/example/linux/flutter/CMakeLists.txt

A custom CMake function to prepend a prefix to each element in a list. This is a workaround for older CMake versions (pre-3.10) that lack the `list(TRANSFORM ... PREPEND ...)` command. It iterates through the list, adds the prefix to each element, and updates the original list variable.

```cmake
function(list_prepend LIST_NAME PREFIX)
    set(NEW_LIST "")
    foreach(element ${${LIST_NAME}})
        list(APPEND NEW_LIST "${PREFIX}${element}")
    endforeach(element)
    set(${LIST_NAME} "${NEW_LIST}" PARENT_SCOPE)
endfunction()
```
Tokens:
Raw