Implement Approval Action Bottom Sheet
epic-expense-approval-workflow-coordinator-ui-task-013 — Create the ApprovalActionBottomSheet Flutter widget used for single-claim review. Display claim summary metadata (submitter, amount, expense types, receipt thumbnails), provide Approve and Reject buttons with optional justification text input, and integrate with ApprovalWorkflowService. Include claim status audit timeline inline and support accessible modal navigation patterns.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Use DraggableScrollableSheet or showModalBottomSheet with isScrollControlled: true to handle variable content height. Wrap the sheet in a BlocProvider scoped to the sheet's lifecycle — do not share the parent queue BLoC. Use a local ApprovalActionCubit with states: ApprovalActionIdle, ApprovalActionLoading, ApprovalActionSuccess, ApprovalActionError. Emit a result event (approved/rejected claimId) back to the parent via a callback or BlocListener before popping.
Receipt thumbnails should use CachedNetworkImage with a placeholder shimmer. For the audit timeline, use a ListView.builder with a custom TimelineTile widget — avoid nested scrolling conflicts by using NeverScrollableScrollPhysics on the inner list and letting the outer DraggableScrollableSheet handle scrolling. Justification field should auto-focus when Reject is tapped using FocusNode.requestFocus() after the animation settles. Design tokens must be used for all colors — never hardcode hex values.
Testing Requirements
Unit tests (flutter_test): test BLoC state transitions for approve/reject actions including loading, success, and error states; mock ApprovalWorkflowService to verify correct method calls with claim ID and justification text. Widget tests: verify all metadata fields render correctly for a fixture claim; verify Approve button is present and Reject reveals text field; verify audit timeline renders N events in correct order; verify close button dismisses the sheet. Accessibility tests: verify Semantics tree has labels on all interactive widgets; verify focus order is logical. Edge case tests: empty audit timeline renders gracefully; very long justification text does not overflow layout; network error during approve/reject surfaces error widget.
Maintaining multi-select state across paginated list pages is architecturally complex in Flutter with Riverpod/BLoC. If the selection state is stored in the widget tree rather than the state layer, page transitions and list redraws can silently clear selections, causing coordinators to lose their multi-select and re-enter it.
Mitigation & Contingency
Mitigation: Store the selected claim ID set in a dedicated Riverpod StateNotifier outside the paginated list widget tree. The paginated list reads selection state from this provider and does not own it. Selection persists independently of list scroll position or page loads.
Contingency: If cross-page selection proves prohibitively complex, limit bulk selection to the currently visible page (add a clear warning in the UI) and prioritise single-page bulk approval for the initial release.
If a coordinator has the queue open while another coordinator approves claims from the same queue (possible in large organisations with shared chapter coverage), the Realtime update may arrive out of order or be missed during a reconnect, leaving the first coordinator's view stale and allowing them to attempt to approve an already-actioned claim.
Mitigation & Contingency
Mitigation: The ApprovalWorkflowService's optimistic locking (from the foundation epic) will catch the concurrent edit at the database level. The CoordinatorReviewQueueScreen should handle the resulting ConcurrencyException by removing the claim from the local list and showing a brief snackbar: 'This claim was already actioned by another coordinator.'
Contingency: Add a queue staleness indicator (a subtle 'last updated X seconds ago' label) and a manual refresh button as a fallback for coordinators who notice inconsistencies.
The end-to-end test requirement that a peer mentor receives a push notification within 30 seconds of coordinator approval depends on FCM delivery latency, which is outside the application's control and can vary significantly in CI/CD environments.
Mitigation & Contingency
Mitigation: Structure end-to-end tests to verify notification intent (correct FCM payload dispatched, correct Realtime event emitted) rather than actual device delivery timing. Use test doubles for FCM delivery in automated tests and reserve real-device delivery tests for manual pre-release validation.
Contingency: If notification timing requirements must be validated in automation, instrument the ApprovalNotificationService with a test hook that records dispatch timestamps and assert against those rather than actual FCM callbacks.