Expense Form BLoC — submission event and error handling
epic-travel-expense-registration-ui-task-007 — Wire the BLoC submit event through ExpenseValidationService and ExpenseSubmissionService. On validation failure emit a field-level error state mapping to plain-language error messages from the error message registry. On network failure emit a retryable error state. On success emit a submitted state carrying the new expense ID for the confirmation view. Implement per-field error display in the form.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Use a sealed class (Dart 3) for ExpenseFormState to get exhaustive pattern matching in BlocBuilder. The submit event handler should follow the sequence: (1) emit loading state, (2) call validation service, (3) if errors return validation error state early, (4) call submission service in try/catch, (5) on catch emit network error, (6) on success emit submitted. Keep the BLoC free of direct Supabase calls — all I/O goes through the service layer. The error message registry should be a simple Map
Use transformEvents with sequential transformer to prevent duplicate submissions from rapid taps. Register the BLoC with BlocProvider above the route to survive navigation events during the multi-step flow.
Testing Requirements
Unit tests using flutter_test and bloc_test package. Test the BLoC in isolation by mocking ExpenseValidationService and ExpenseSubmissionService. Scenarios: (1) all fields valid → submitted state with correct expense ID; (2) one required field empty → validation error state with correct field key and plain-language message; (3) multiple fields invalid simultaneously → all errors present in single emission; (4) network timeout → network error state with retryable=true; (5) Supabase returns 409 conflict → specific error message; (6) retry after network error succeeds → submitted state. Widget tests for the form should verify error text appears beneath the correct field after validation error state.
Aim for 100% branch coverage on ExpenseFormBloc event handlers.
The image_picker Flutter plugin requires platform-specific permissions (NSPhotoLibraryUsageDescription, camera permission) and behaves differently across iOS and Android versions. Permission denial or plugin misconfiguration can silently prevent receipt attachment.
Mitigation & Contingency
Mitigation: Configure all required permission strings in Info.plist and AndroidManifest.xml during initial plugin setup. Use the permission_handler package to check and request permissions before launching the picker, with clear user-facing explanations. Test on both platforms across at least two OS versions.
Contingency: If image_picker proves unreliable on a specific platform version, fall back to file_picker as an alternative that uses the OS document picker interface, which requires fewer permissions on some Android versions.
The expense form BLoC manages interconnected state across expense type selection, field visibility, receipt requirement, threshold evaluation, and submission flow. Incorrect state transitions can cause UI inconsistencies such as required receipt indicator not updating after amount change, or form appearing valid when mutual exclusion is violated.
Mitigation & Contingency
Mitigation: Model BLoC states as sealed classes with exhaustive pattern matching. Write state transition unit tests covering every combination of: type selection change, amount field change above/below threshold, receipt attachment/removal, and offline mode toggle. Use bloc_test for comprehensive state sequence assertions.
Contingency: If BLoC complexity becomes unmanageable, split into two BLoCs — one for type selection/exclusion state and one for field values/submission — coordinating via a parent provider, accepting the small overhead of inter-BLoC communication.
The expense type selector must enforce mutual exclusion visually by disabling options and showing conflict tooltips, while remaining fully accessible to screen reader users who cannot perceive visual disable states. Incorrect semantics labelling will fail WCAG 2.2 AA requirements critical for Blindeforbundet and HLF users.
Mitigation & Contingency
Mitigation: Use Flutter Semantics widgets to explicitly set disabled state and provide conflict explanations as semanticLabel strings on disabled options. Run accessibility audits with TalkBack and VoiceOver during widget development, not post-completion. Reference the project's accessibility test harness for required test coverage.
Contingency: If custom widget accessibility is difficult to certify, implement the selector as a standard Flutter Radio/Checkbox group with built-in accessibility semantics and an explanatory Text widget below each conflicting option, sacrificing visual elegance for guaranteed WCAG compliance.