Mileage Entry Form
Component Detail
Description
The primary Flutter form screen allowing peer mentors to log a mileage claim. Renders origin, optional destination, and distance fields with pre-filled defaults, and triggers real-time reimbursement display as the user types. Follows WCAG 2.2 AA contrast and label requirements.
mileage-entry-form
Summaries
The Mileage Entry Form is the primary interface through which peer mentors submit travel reimbursement claims, making it one of the highest-impact screens in the entire application. A clear, fast, and accessible form directly reduces claim submission errors, lowers administrative follow-up costs, and ensures peer mentors are reimbursed accurately and promptly — a key factor in mentor satisfaction and retention. The pre-filled distance default and real-time reimbursement preview give mentors immediate confidence that their claim is correct before submission, reducing disputes and correction cycles. Compliance with WCAG 2.2 AA accessibility standards also ensures the organisation meets its inclusion obligations and avoids accessibility-related liability across its volunteer workforce.
The Mileage Entry Form is a medium-complexity UI component with four direct dependencies: the real-time reimbursement display widget, the distance input field, the route input fields widget, and the mileage claim service. All four must reach a stable API contract before this form can be fully integrated and tested end-to-end, making dependency sequencing a key scheduling concern. Accessibility compliance (WCAG 2.2 AA) requires a dedicated accessibility audit pass, ideally with assistive technology testing on both iOS and Android, which should be budgeted as a separate QA workstream. The pre-fill behaviour from local cache introduces a stateful edge case requiring specific test scenarios for first-use, cache-clear, and offline conditions.
Plan for at least one integration testing sprint before this screen reaches user acceptance testing.
The Mileage Entry Form is a stateful Flutter screen that orchestrates four child components via explicit callback interfaces: onDistanceChanged, onOriginChanged, onDestinationChanged, onSubmit, and showValidationErrors. It coordinates with RealtimeReimbursementDisplay by passing the current distance value downward on every onDistanceChanged event, keeping reactive calculation at the widget layer rather than in BLoC state. The prefillDistance method should fetch the cached last-used value from local storage during initState and pass it to DistanceInputField via its defaultKm constructor parameter. Validation is synchronous and field-level, with errors surfaced through showValidationErrors as a Map keyed by field name.
Submission delegates to MileageClaimService, which owns the async network call; the form should disable the submit button and show a loading indicator during in-flight requests to prevent double-submission.
Responsibilities
- Render origin and optional destination input fields with privacy-aware placeholder text
- Pre-fill the distance field with the last-used value fetched from local cache
- Coordinate with the real-time reimbursement display widget on distance changes
- Validate required fields and surface inline error messages before submission
- Invoke the mileage claim submission service on form confirmation
Interfaces
build(BuildContext context)
onDistanceChanged(double km)
onOriginChanged(String origin)
onDestinationChanged(String? destination)
onSubmit()
showValidationErrors(Map<String, String> errors)
prefillDistance(double defaultKm)
resetForm()
Relationships
Dependencies (4)
Components this component depends on