Implement pipeline stage progress indicator widget
epic-bufdir-data-aggregation-ui-task-002 — Build the AggregationProgressIndicator Flutter widget that renders the four-stage pipeline (fetching → categorising → deduplicating → distributing) as a visual step progression. Each stage shows an icon, label, and active/completed/pending state. The widget listens to the BLoC stream and animates transitions between stages. Must use design token colours and spacing, with WCAG 2.2 AA compliant contrast ratios.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use BlocSelector
Wrap each _StageStep in a Semantics widget with a dynamically constructed label: '${stage.label}, ${stateDescription}' where stateDescription is 'pending', 'in progress', or 'completed'. For icons, use Flutter's built-in Icons constants (Icons.download_rounded for fetching, Icons.category_outlined for categorising, Icons.filter_alt_outlined for deduplicating, Icons.send_rounded for distributing) unless the project has a custom icon set.
Testing Requirements
Unit and widget tests using flutter_test. Test cases: (1) widget renders all four stages when BLoC is in AggregationInitial; (2) for each AggregationStage value, the corresponding stage node shows active styling and all prior stages show completed styling; (3) BlocSelector is used — emit an unrelated state and verify the widget does not rebuild unnecessarily using a render count tracker; (4) golden tests for each active-stage permutation saved under test/goldens/aggregation_progress/; (5) Semantics tree test verifying each stage has a descriptive label. Use pumpAndSettle() after emitting a new stage to ensure animations complete before asserting visual state.
For NHF with 1,400 local chapters, rendering a geographic breakdown as a flat list in the AggregationSummaryWidget would produce an unscrollable wall of data that is unusable on a mobile screen. Coordinators need to verify geographic completeness before export, but the raw chapter list is too long to review.
Mitigation & Contingency
Mitigation: Design the geographic distribution section as a collapsible two-level hierarchy: regions are shown expanded by default with their aggregate count, individual chapters are collapsed under each region and expandable on tap. Show only non-zero regions by default with a 'show empty regions' toggle.
Contingency: If the hierarchical display is too complex to implement before the submission deadline, fall back to a region-only summary view with a total count of active chapters per region and a note that chapter-level detail is available in the full export file.
The aggregation BLoC must handle a multi-stage async pipeline with partial success states, warning accumulation across stages, and retry logic for individual failed stages. If the state model is too simplistic (e.g., loading/success/error), warning states and partial results will be lost on retry, confusing coordinators who see warnings disappear and reappear.
Mitigation & Contingency
Mitigation: Model the BLoC state as a rich sealed class hierarchy: AggregationIdle, AggregationRunning(stage, completedStages, accumulatedWarnings), AggregationComplete(result, warnings), AggregationFailed(failedStage, accumulatedWarnings, error). Accumulated warnings persist across retry attempts so coordinators see the full warning history.
Contingency: If state management complexity causes repeated bugs near the deadline, simplify to a single AggregationResult value object that captures success, warnings, and error as nullable fields, and drive both UI components from that single object rather than a live BLoC stream.