overlay_layers 2.0.0

overlay_layers: ^2.0.0 copied to clipboard

Features #

• 🎉 Modal Support: New interchangeable modal system
  • ModalController: Controller for managing modals with open(), close(), and updateModalData() methods
  • ModalDataContext: Access and update modal data from within modal widgets
  • Interchangeable behavior: Only one modal can be displayed at a time - opening a new modal automatically closes the previous one
  • Modal widgets: ModalScaffold, AnimatedModal, and SlideUpModal for building modal UIs
  • Same type-safe data passing and lifecycle management as popups
  • Full API parity with popup system
  • New files: lib/src/modal/modal_controller.dart, lib/src/modal/modal_widgets.dart

Example:

// Open a modal (automatically closes any existing modal)
ModalController.of(context).open(
  builder: (context) => MyModalWidget(),
  options: OverlayCreateOptions(initialData: {'title': 'Hello'}),
);

// Access data inside modal
final modal = ModalDataContext.of<Map<String, dynamic>>(context);
modal.updateModalData({'title': 'Updated'});
modal.close();

Bug Fixes #

• Fixed data update functionality: Overlay data updates now trigger UI rebuilds correctly

  • The OverlayEntry builder was capturing the original overlay reference in a closure
  • When updatePopupData() or updateModalData() was called, data was updated but UI didn't reflect changes
  • Solution: Builder now looks up current overlay from manager's list on each rebuild
  • Changes in lib/src/core/overlay_manager.dart

• Fixed type cast error with Map<String, dynamic>: Resolved runtime exception when merging map data

  • Error: type '_Map<dynamic, dynamic>' is not a subtype of type 'Map<String, dynamic>' in type cast
  • Occurred when calling updatePopupData() or updateModalData() with Map<String, dynamic> data
  • Solution: Added explicit handling for Map<String, dynamic> type in _mergeData method
  • Changes in lib/src/core/overlay_manager.dart

Technical Details #

Data Update Fix - Before (Broken):

final entry = OverlayEntry(
  builder: (context) => _OverlayDataProvider(
    overlay: overlay, // Stale reference!
    manager: this,
    child: Builder(builder: builder),
  ),
);

Data Update Fix - After (Fixed):

final entry = OverlayEntry(
  builder: (context) {
    final currentOverlay = _overlays.firstWhere((o) => o.id == id);
    return _OverlayDataProvider(
      overlay: currentOverlay, // Fresh data on each rebuild!
      manager: this,
      child: Builder(builder: builder),
    );
  },
);

Migration from v1.0.0 #

No breaking changes. Simply update to v2.0.0 to get:

• ✅ New modal support with full feature set
• ✅ Fixed data update functionality for popups
• ✅ Resolved type cast errors

BREAKING CHANGES #

This is a major architectural refactor that uses Flutter's native Overlay system. The package now works immediately without any wrapper widgets.

Removed Components

• OverlayRoot: No longer needed. Remove all OverlayRoot wrappers from your app.
• OverlayContainer: No longer needed. Overlays render through Flutter's native Overlay.
• OverlayProvider: Removed entirely. Replaced with singleton pattern.

API Changes

• PopupController.updateData() → PopupController.updatePopupData(): Method renamed for clarity
• PopupDataContext.updateData() → PopupDataContext.updatePopupData(): Method renamed for clarity
• OverlayManager.createOverlay(): Now requires BuildContext parameter
• OverlayManager: Now uses singleton pattern with OverlayManager.instance
• PopupController.of(): Now uses singleton automatically, no provider needed
• OverlayManager.custom(): New constructor for custom manager instances (advanced use)

Migration Guide

Before (v0.2.0):

// App setup
OverlayRoot(
  child: MaterialApp(home: MyApp()),
)

// Update popup data
controller.updateData(id, data);
popup.updateData(data);

After (v1.0.0):

// App setup - No wrapper needed! Uses singleton automatically
MaterialApp(home: MyApp())

// Update popup data - Renamed methods
controller.updatePopupData(id, data);
popup.updatePopupData(data);

// Access global singleton (advanced)
final overlays = OverlayManager.instance.overlays;

// Or create custom manager (rare)
final customManager = OverlayManager.custom();
PopupController.withManager(context, customManager).open(...);

Features #

• Native Flutter Overlay integration: Built on OverlayEntry API for better performance
• No setup required: Works immediately with any Flutter app (MaterialApp, CupertinoApp, etc.)
• Singleton pattern: Global OverlayManager.instance provides automatic access everywhere
• Popup support: Multiple popups can coexist simultaneously
• Simplified architecture: Removed custom overlay system and provider pattern, uses Flutter's standard approach
• Better performance: Individual entry updates via markNeedsBuild() instead of full Stack rebuilds

Implementation Details #

• OverlayManager now creates and manages Flutter OverlayEntry instances
• Uses Overlay.of(context, rootOverlay: true) for predictable overlay placement
• Entries removed via entry.remove() with proper lifecycle management
• Data updates trigger entry.markNeedsBuild() for efficient rendering
• Controllers store BuildContext to access native Overlay

Documentation #

• Updated README.md with new Quick Start guide
• Updated CLAUDE.md with v1.0.0 architecture details
• Added migration guide for v0.2.0 users
• Updated API reference with renamed methods

Features #

• Flexible overlay rendering with includeContainer parameter (lib/src/core/overlay_manager.dart:158)
  • Added includeContainer boolean parameter to OverlayRoot (defaults to true)
  • When true: Automatically includes OverlayContainer in a Stack for immediate overlay support
  • When false: Allows manual placement of OverlayContainer for advanced layout control
  • Enables precise control over where overlays render in the widget tree
  • Useful for complex UIs where overlays should only cover specific sections

Documentation #

• Enhanced architecture documentation (lib/src/core/overlay_manager.dart:132-146)
  • Added comprehensive doc comments explaining the provider pattern
  • Documented the relationship between OverlayRoot, OverlayProvider, and OverlayContainer
  • Clarified when and how to use includeContainer parameter
  • Added examples for both automatic and manual container placement

Code Quality #

• Formatting standardization: Applied consistent Dart formatting throughout the codebase
  • Simplified export statements in lib/overlay_layers.dart
  • Streamlined constructor formatting
  • Improved method call formatting with compact arrow function syntax
  • Consistent line breaking in lib/src/core/overlay_manager.dart

Breaking Changes: None - fully backward compatible. Existing code works without modification.

• Initial public release to pub.dev with popup support, overlay management system, type-safe data passing, positioning system