mastro 2.0.0+2

mastro: ^2.0.0+2 copied to clipboard

• Updated documentation.

• Updated pubspec.yaml.

Added #

• New Components:

  • MastroZone: A unified replacement for MastroBuilder and TagBuilder. It supports both automatic state-driven updates and lightweight tag-based refreshes, with an optional shouldRebuild callback for fine-grained rebuild control.
  • TriggerableZone: New widget for imperative rebuilds using a TriggerableZoneController.
  • LifecycleZone: Simple widget for lifecycle hooks (onViewCreated, onViewDestroyed) without requiring a box.
  • MastroMemoryLeaksChecker: Debug tool for detecting undisposed resources (e.g., listeners, timers) in debug mode.
  • LogOptions and showMastroLogs(): Enhanced logging with global and instance-level configuration for state changes and diagnostics.
  • Autowire: Zone-based resource management for automatic cleanup of resources within box scopes.
  • DependenciesScope: Internal mechanism for implicit dependency tracking in Mastro.computed(...).

• New Features:

  • Mastro.computed(...): New method for derived values with implicit dependency tracking, replacing dependsOn and compute.
  • FAQ entry for logging: Added guidance on enabling logs using showMastroLogs() and LogOptions.

Changed #

• Renamed Components:

  • MastroView renamed to MastroWidget to align with Flutter conventions.
  • BoxProvider renamed to BoxScope.
  • MultiBoxProvider renamed to MultiBoxScope.
  • MastroScope renamed to MastroHooks.
  • OnPopScope renamed to OnPopHook.

• Updated Behavior:

  • MastroZone now handles both state and tag reactivity, replacing MastroBuilder and TagBuilder.
  • onViewAttached and onViewDetached now take ViewMetaData instead of MastroView for lifecycle hooks.

Removed #

• Mastro.dependsOn(...): Replaced by Mastro.computed(...) with implicit dependency capture.
• compute(): Fully removed in favor of Mastro.computed(...).
• RebuildBoundary: Replaced by TriggerableZone for imperative rebuilds.
• autoCleanupWhenAllViewsDetached and autoCleanupWhenUnmountedFromWidgetTree: Removed as cleanup is now handled internally via Autowire.

Fixed #

• Improved clarity in documentation for MastroZone usage, ensuring explicit state dependencies and tag-based refreshes are well-explained.
• Enhanced persistence documentation for PersistroLightro and PersistroMastro with clearer factory and codec examples.

Notes #

• Logging configuration is now more robust, with the addition of showMastroLogs() and LogOptions for better debugging control.
• Ensure MastroMemoryLeaksChecker.start() is called before runApp() in debug builds to leverage memory leak detection.

• Minor bug fixes and improvements.
• Updated documentation.

🚨 Breaking / Behaviour Changes #

• Removed MastroView.rebuild()
  The manual rebuild method has been deleted. Views should rebuild reactively via MastroBuilder, TagBuilder, and state updates.
• Removed standalone compute() on state
  All computed/derived wiring now goes through dependsOn([...], compute: ...). See the Migration Guide below.
• SEQUENTIAL events – waiting behaviour updated
  The semantics for waiting on EventRunningMode.sequential were refined. Each execute(...) now completes when its own enqueued item finishes, while the queue continues to drain in order. Code that implicitly relied on the first caller waiting for the entire queue to finish should be updated to await the specific calls it cares about

✨ Added #

• .safe on state containers (Basetro<T>.safe)
  A nullable accessor that returns null before a .late() state is initialized. Ideal for first-paint reads without throwing.
• clearDependencies() on Mastro<T>
  Removes all wired dependencies established via dependsOn(...) (idempotent). Use when changing the set of sources dynamically.

🔁 Changed #

• Derived values via dependsOn
dependsOn([...], compute: ...) now covers what compute() used to do and more:
  • Depend on multiple states simultaneously (value intersections).
  • Provide a compute function to set a derived value.
  • Notify‑only mode: omit compute to propagate changes without mutating the dependent’s .value.

• Minor bug fixes and improvements.
• README overhaul with clearer structure and richer explanations.

Breaking changes #

• Boxes
  • dispose() → cleanup() — Replace any dispose() overrides with cleanup() (call super.cleanup() inside).
  • New Callbacks mechanism:
    Old: Callbacks({'action': ({data}) { ... }})
    New: Callbacks.on('action', (data) { ... }).on(...).on(...)
• Initialization
  • MastroInit.init() is no longer available — use Persistro.initialize() for persistence setup.

Added #

• Providers: new flags
  • autoCleanupWhenUnmountedFromWidgetTree
  • autoCleanupWhenAllViewsDetached
    Behavior unchanged — both control when cleanup() is called automatically.
• Late state support: .late() for uninitialized state on both Lightro and Mastro, with helpers: isInitialized, ensureInitialized(), when(...), resetToUninitialized().
• AsyncState: new AsyncState<T> class for predefined async states (initial, loading, data, error), with .lightro / .mastro wrappers for reactive binding in UI.
• MastroBox: new autoCleanupWhenAllViewsDetached, onViewAttached, and onViewDetached hooks.
• Awaitable sequential events: each queued execute() in EventRunningMode.sequential now returns a Future that completes when that specific queued item finishes (per-type FIFO preserved).
• Rebuild utilities: added RebuildBoundary helper to force subtree rebuilds via a UniqueKey.
• ClassProvider.onDispose: allows running custom cleanup logic when a provided class instance is disposed.
• StaticWidgetProvider: new provider type for supplying static widget instances in the tree without rebuilds.
• Docs: new README with feature-based structure, Lightro vs Mastro comparison, AsyncState, local vs scoped boxes, lifecycle hooks, and MastroScope guidance.

Changed #

• Local boxes in views: recommended pattern is to pass a new box through the MastroView super constructor (commonly via a small factory/closure), while scoped boxes are provided via BoxProvider / MultiBoxProvider.
• Validation & observers (Mastro): clarified usage; validators can gate assignments and run onValidationError.

Improvements #

• Performance improvements in event execution and builder notifications.
• Builders responsiveness
  • MastroBuilder and TagBuilder now perform immediate rebuilds when safe (idle / transient / mid-frame) and defer with post-frame coalescing only during build/layout/paint.
  • Internal defer tokens prevent stale callbacks, avoiding jank with fast gestures.
• TagBuilder hot-swap safety: re-attaches when box changes in didUpdateWidget.
• Logging: state changes are now logged for easier debugging and tracking.
• Error handling: improved error messages for validation failures and runtime exceptions.
• Persistro: improved initialization flow and persistence operations; now initialized explicitly via Persistro.initialize() and supports more reliable state restoration and storage.

• Minor fixes and improvements.

• Minor fixes and improvements.
• Updated documentation.

• Updated documentation.

• Updated documentation.

• Updated documentation.

• First stable release
• Minor fixes and improvements.
• Updated documentation.

• Minor fixes and improvements.

• Updated documentation.

• Minor fixes.

• Minor fixes.

• Minor fixes.

• Minor fixes.

• Minor fixes and improvements.

• Initial release.