🚀 Improvements #

• GetX / GetMaterialApp compatibility - ActionManagerProvider now works seamlessly with GetMaterialApp and other state management frameworks
• Smart overlay registration with retries - Automatic retry mechanism (up to 5 attempts) ensures overlay registration even when frameworks delay initialization
• Better framework support - Compatible with GetX, Provider, Riverpod, and other frameworks that wrap MaterialApp

🐛 Bug Fixes #

• Fixed overlay detection in GetMaterialApp - Uses Overlay.maybeOf() instead of Overlay.of() to prevent exceptions
• Added retry logic - Handles cases where overlay is not immediately available on first build
• Improved error messages - More specific guidance for different scenarios including GetMaterialApp

📝 Usage with GetX #

void main() {
  runApp(
    GetMaterialApp(
      home: ActionManagerProvider(
        child: HomePage(),
      ),
    ),
  );
}

✅ Testing #

• All 79 tests passing
• Verified compatibility with GetX framework

🐛 Bug Fixes #

• Fixed ActionManagerProvider overlay initialization - Now correctly uses existing MaterialApp overlay instead of creating a new one, preventing overlay conflicts
• Fixed loading counter management - Counter only increments when overlay is available, preventing state inconsistencies
• Improved placement guidance - Updated all documentation to clearly indicate ActionManagerProvider must be inside MaterialApp
• Better error messages - More helpful guidance when overlay is not properly configured

📝 Breaking Change Note #

IMPORTANT: ActionManagerProvider must be placed INSIDE MaterialApp, not wrapping it:

// ✅ Correct
MaterialApp(
  home: ActionManagerProvider(
    child: HomePage(),
  ),
)

// ❌ Incorrect
ActionManagerProvider(
  child: MaterialApp(...),
)

✅ Testing #

• All 79 tests passing
• Fixed unit tests to reflect corrected behavior

✨ New Features #

• Loading Overlay Support - Display fullscreen blocking loading during action execution
  • Added ActionManagerProvider widget (must be placed inside MaterialApp)
  • Added displayLoading parameter to dispatch() method
  • Added LoadingOverlayController for manual control
  • Automatic show/hide management with try-finally protection
  • Customizable loading widget via loadingBuilder parameter
  • Thread-safe with counter-based concurrent requests handling

🐛 Bug Fixes #

• Fixed overlay initialization - ActionManagerProvider now correctly registers with existing MaterialApp overlay instead of creating a new one
• Fixed counter management - Loading counter no longer increments when no overlay is registered, preventing state inconsistencies
• Improved error messages - Better guidance for correct ActionManagerProvider placement

📝 Usage #

// 1. Place ActionManagerProvider INSIDE MaterialApp
void main() {
  runApp(
    MaterialApp(
      home: ActionManagerProvider(
        child: HomePage(),
      ),
    ),
  );
}

// 2. Use displayLoading parameter
ActionManager.dispatch(
  AppAction.loadData,
  displayLoading: true,
);

🔧 New Components #

• ActionManagerProvider - Widget wrapper (place inside MaterialApp)
• LoadingOverlayController - Singleton controller for overlay management
• displayLoading parameter in ActionManager.dispatch()

✨ New Features #

• Added debug parameter to dispatch() method - Enable logging for specific dispatches without activating the global logger
  • Usage: ActionManager.dispatch(AppAction.updateUi, debug: true);
  • Useful for targeted debugging without flooding console with all action logs
  • Works independently from global logger.enabled setting

🔧 Changes #

• Logger now disabled by default - Changed ActionLogger.enabled default from kDebugMode to false
  • More predictable behavior in production and debug modes
  • Explicit activation required: ActionManager.configureLogger(enabled: true);
  • Reduces console noise for developers who don't need action logging

Migration Guide #

• If you relied on automatic logging in debug mode, explicitly enable it:

  ActionManager.configureLogger(enabled: true);
  

• Or use the new debug parameter for selective logging:

  ActionManager.dispatch(AppAction.test, debug: true);
  

🐛 Bug Fixes #

• Fixed ActionManagerWidget not rebuilding on duplicate actions - Widget now rebuilds every time the same action is dispatched, even with identical data
• Added internal event counter - Forces rebuild even when data hasn't changed, ensuring UI always responds to actions
• Fixed similar issue in ActionManagerMultiWidget - Applied same fix to ensure consistency

Context #

• Previous version (4.2.0) introduced an optimization to avoid rebuilds when data didn't change
• This optimization was too aggressive and prevented rebuilds when dispatching the same action multiple times
• Users reported that buttons triggering the same action with same data would not cause UI updates
• Fix ensures that any action dispatch triggers a rebuild, regardless of data equality

Example of Fixed Behavior #

// Before: Only first dispatch would cause rebuild
ActionManager.dispatch(AppActions.updLeftBar, data: LeftBarWidget.mainMenu);
ActionManager.dispatch(AppActions.updLeftBar, data: LeftBarWidget.mainMenu); // Would not rebuild ❌

// After: Both dispatches cause rebuild
ActionManager.dispatch(AppActions.updLeftBar, data: LeftBarWidget.mainMenu); // Rebuilds ✅
ActionManager.dispatch(AppActions.updLeftBar, data: LeftBarWidget.mainMenu); // Rebuilds ✅

🚨 BREAKING CHANGES #

• ActionManagerWidget builder signature changed - Now requires 3 parameters: (BuildContext context, T? data, Enum action) instead of 2
  • Migration: Add the action parameter to your builder function
  • Before: builder: (context, data) => Text('$data')
  • After: builder: (context, data, action) => Text('$data')

✨ New Features #

• Added action parameter to ActionManagerWidget builder - Now you can access the action being dispatched for debugging purposes
• Better debugging capabilities - Use the action parameter to log which action triggered the rebuild

🐛 Bug Fixes #

• Fixed excessive rebuilds in ActionManagerWidget - Widget now only rebuilds when data actually changes, not on every dispatch
• Fixed excessive rebuilds in ActionManagerMultiWidget - Widget now only rebuilds when event data changes, not on every dispatch

Improved #

• Performance optimization - Added equality check before calling setState() to prevent unnecessary rebuilds
• Better efficiency - Widgets are more performant when multiple dispatches occur with the same data
• Enhanced developer experience - Action parameter helps identify which action triggered a rebuild

Example #

ActionManagerWidget<bool>(
  action: AppAction.displayForm,
  builder: (context, display, action) {
    debugPrint('Action: $action'); // For debugging
    if (display == true) return MyForm();
    return const SizedBox.shrink();
  },
)

✨ New Features #

• Added ActionManagerWidget<T> - Reactive widget that automatically rebuilds when a specific action is dispatched
• Added ActionManagerMultiWidget - Reactive widget that rebuilds when any of multiple actions is dispatched

Features #

ActionManagerWidget

A stateful widget that:

• Automatically subscribes to an action on initState
• Calls setState() when the action is dispatched
• Auto-cancels subscription on dispose
• Supports optional placeholder before first event
• Type-safe with generic data type

Example:

ActionManagerWidget<User>(
  action: AppAction.userUpdated,
  placeholder: CircularProgressIndicator(),
  builder: (context, user) {
    return Text('User: ${user?.name ?? "none"}');
  },
)

ActionManagerMultiWidget

Listens to multiple actions and provides the full ActionEvent:

ActionManagerMultiWidget(
  actions: [AppAction.userUpdated, AppAction.userLoggedIn],
  builder: (context, event) {
    return Text('Last action: ${event?.action.name}');
  },
)

Added #

• New file: lib/src/action_manager_widget.dart
• 10 new widget tests (64 total tests passing)
• Exported widgets in main library file

Improved #

• Simplified reactive UI patterns - no need for manual StreamSubscription management
• Better separation of concerns - widgets handle their own lifecycle

🚨 BREAKING CHANGES #

• Removed streamOf<T>() method - Use ActionManager.stream.where((a) => a.action == yourAction) instead for filtering streams by action

✨ Improvements #

• Simplified dispatch logic - Removed internal complexity while maintaining all functionality
• More predictable stream behavior - Stream always emits events even without registered handlers
• Better code maintainability - Cleaner, more straightforward implementation

Migration Guide #

If you were using streamOf<T>():

Before:

final subscription = ActionManager.streamOf<String>(AppAction.test)
    .listen((action) {
  print(action.data);
});

After:

final subscription = ActionManager.stream
    .where((a) => a.action == AppAction.test)
    .listen((action) {
  print(action.data as String?);
});

Or simply use the higher-level listen() API:

final subscription = ActionManager.listen<String>(
  AppAction.test,
  (data) => print(data),
);

🚨 BREAKING CHANGES #

• Renamed Action class to ActionEvent to avoid naming conflicts with Flutter SDK's built-in Action class
• This change affects all code that directly instantiates or references the Action class

Why This Change? #

The Flutter SDK includes a built-in Action class in package:flutter/src/widgets/actions.dart. Using a class with the same name in this package could cause naming conflicts and ambiguity in applications that use both Flutter's actions system and this action manager.

Migration Guide #

The ActionManager API remains unchanged. If you were only using the high-level API (ActionManager.dispatch, ActionManager.on, etc.), no changes are needed.

If you were directly instantiating or type-checking against the Action class:

Before:

final action = Action<String>.now(AppAction.test, data: 'test');
if (myVar is Action<String>) { ... }

After:

final action = ActionEvent<String>.now(AppAction.test, data: 'test');
if (myVar is ActionEvent<String>) { ... }

Changed #

• Renamed Action<T> class to ActionEvent<T>
• Updated FullActionHandler<T> typedef to use ActionEvent<T>
• Updated internal references in ActionManager and ActionLogger
• Updated all tests (48 tests passing)
• Updated documentation and examples
• No analysis issues

Fixed #

• Eliminated potential naming conflicts with Flutter SDK's Action class
• Improved clarity and semantic meaning of the action event class

🚨 BREAKING CHANGES #

• Renamed ActionDispatcher to ActionManager to avoid naming conflicts with Flutter's built-in ActionDispatcher class
• Renamed file action_dispatcher.dart to action_manager.dart

Migration Guide #

Simply replace all instances of ActionDispatcher with ActionManager in your code:

Before:

ActionDispatcher.dispatch(AppAction.test);
ActionDispatcher.on<String>(AppAction.test, (data) {});

After:

ActionManager.dispatch(AppAction.test);
ActionManager.on<String>(AppAction.test, (data) {});

Changed #

• All ActionDispatcher references updated to ActionManager throughout the library
• Updated all documentation (README.md, project.md)
• Updated all examples and tests
• All 48 tests passing
• No analysis issues

Added #

• Comprehensive test suite with 48 tests covering all library methods
• Tests for Action class (creation, equality, hashCode, toString)
• Tests for ActionDispatcher dispatch, registration, and unregistration
• Tests for reactive streams (listen, stream, streamOf)
• Tests for metadata and statistics tracking
• Tests for error handling and resilience
• Tests for ActionLogger configuration
• Integration tests for complex workflows

Improved #

• Enhanced code formatting across all files
• Better test coverage and reliability
• Improved documentation in test files

Added #

• Initial release
• Core ActionDispatcher with enum-based actions
• Type-safe action handlers
• Built-in debugging and introspection
• Reactive StreamSubscription support
• Comprehensive documentation and examples
• Unit tests with full coverage
• Example application demonstrating key features