Wrapped Summary BLoC

The Wrapped Summary BLoC has medium complexity and sits at the integration boundary between the UI and three backend services — annual-stats-aggregation-service, summary-share-service, and summary-offline-cache — making it a coordination risk point. It should be implemented after its service dependencies are at least partially stable, with mock implementations used during early development. The event model (LoadSummary, ChangePeriod, ShareSlide, NavigateSlide) should be agreed with the UI team before implementation to avoid interface churn. State emissions (loading, loaded, error, offline) drive all UI transitions, so state completeness must be validated during QA.

The offline state path requires specific test scenarios where network availability changes mid-session. Regression coverage should include period switching while a load is in progress, and share failure handling to ensure the UI receives an actionable error state.

The Wrapped Summary BLoC follows the flutter_bloc pattern: it extends Bloc, registers event handlers in the constructor, and emits typed states to the UI stream. The LoadSummary handler should first check the offline cache via summary-offline-cache, emit an OfflineState with cached data if the network is unavailable, and otherwise delegate to annual-stats-aggregation-service. The ChangePeriod handler should cancel any in-flight load and re-trigger LoadSummary for the new period. The ShareSlide handler delegates to summary-share-service and emits a ShareSuccessState or ShareErrorState based on the result.

Use a Completer or CancelableOperation if the aggregation service call must be cancellable mid-flight. The close() override must cancel subscriptions and in-flight futures to prevent state emissions after the BLoC is disposed. Consider using an equatable-based state hierarchy for efficient state comparison and to prevent redundant UI rebuilds.