Implement ReceiptCameraSheet accessibility semantics
epic-receipt-capture-and-attachment-core-logic-task-010 — Add comprehensive VoiceOver and TalkBack accessibility support to ReceiptCameraSheet. Assign Semantics labels: 'Attach receipt, no receipt attached' / 'Receipt attached' for attachment state, 'Take photo with camera' and 'Choose from photo library' for action buttons. Implement focus trapping within the sheet and automatic focus restoration to the trigger button on dismissal.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Use the Semantics widget with label, hint, and button: true properties rather than relying on implicit semantics from InkWell alone — InkWell semantics are sometimes insufficient for complex layouts. For focus trapping, wrap the sheet content in a FocusScope with a canRequestFocus scope; use autofocus: true on the first button. For focus restoration, capture the FocusNode of the trigger before opening the sheet and call requestFocus() on it in the onClosed callback of showModalBottomSheet. The accessibility_preferences data model (font_scale_factor, contrast_mode) should inform styling but is consumed at the app theme level, not within this widget directly.
Avoid hardcoded announcement strings — define them in a SemanticLabels constants file for reuse and future localisation. Test with both VoiceOver (iOS) and TalkBack (Android) reading direction (RTL support may be relevant for future localisation).
Testing Requirements
Widget tests using flutter_test with SemanticsHandle: verify each interactive element has the correct semantics label and flags (isButton: true); verify Semantics node for attachment state reflects 'no receipt attached' and 'receipt attached' states; verify ExcludeSemantics applied to decorative dividers and backdrop. Use tester.getSemantics() to assert SemanticsNode properties. Manually verify VoiceOver traversal order on a physical iOS device and TalkBack on Android before marking complete — automated tests cannot fully validate real assistive technology behaviour.
Non-blocking upload creates a race condition: if the claim record is submitted and saved before the upload completes, the storage path may never be written to the claim_receipts table, leaving the claim with a missing receipt that was nonetheless required.
Mitigation & Contingency
Mitigation: Design the attachment service to queue a completion callback that writes the storage path to the claim record upon upload completion, even after the claim form has submitted. Use a local task queue with persistence to survive app backgrounding. Test the race condition explicitly with simulated slow uploads.
Contingency: If the async path association proves unreliable, fall back to blocking upload before claim submission with a clear progress indicator, accepting the UX trade-off in exchange for data integrity.
The offline capture requirement (cache locally, sync when connected) significantly increases state management complexity. If the offline queue is not durable, receipts captured without connectivity may be lost when the app is killed, causing claim submission failures users are not aware of.
Mitigation & Contingency
Mitigation: Persist the offline upload queue to local storage (e.g., Hive or SQLite) on every state transition. Implement background sync using WorkManager (Android) and BGTaskScheduler (iOS). Scope the initial delivery to online-only flow if offline sync cannot be adequately tested before release.
Contingency: Ship without offline support in the first release, displaying a clear 'Upload requires connection' message. Add offline sync as a follow-on task once the core online flow is validated in production.
The inline bottom sheet presentation within a multi-step wizard can conflict with existing modal navigation and back-button handling, particularly if the expense wizard itself uses nested navigation or custom route management.
Mitigation & Contingency
Mitigation: Review the expense wizard navigation architecture before implementation. Use showModalBottomSheet with barrier dismissal disabled to prevent accidental dismissal. Coordinate with the expense wizard team on modal stacking behavior and ensure the camera sheet does not interfere with wizard step transitions.
Contingency: If modal stacking causes navigation issues, present the camera sheet as a full-screen dialog using PageRouteBuilder with a transparent barrier, preserving wizard state via the existing Bloc while still appearing inline.