Distance Input Field Widget
Component Detail
Description
A numeric Flutter input field for entering kilometres driven. Accepts a pre-filled default from the last-used distance cache and fires a callback on every value change so the parent form can update the real-time reimbursement display immediately.
distance-input-field
Summaries
The Distance Input Field is the core data-entry point for mileage claims, directly determining the accuracy of every reimbursement calculation in the system. By pre-populating the field with the mentor's last-used distance value, the design reduces friction for repeat claimants, speeds up the submission process, and decreases the likelihood of entry errors caused by manual re-typing of common distances. This translates into fewer correction requests, lower administrative overhead, and faster payment cycles — all of which contribute to a more efficient and mentor-friendly reimbursement programme. The field's real-time change callback also enables the live payout preview that gives mentors immediate confidence in their submission before they commit.
The Distance Input Field is a low-complexity, zero-dependency widget that can be delivered early and used as a stable building block for the mileage entry form. The pre-fill behaviour from the last-used distance cache introduces a dependency on the local caching layer, which should be confirmed as a stable API before integration testing begins. QA must cover the full range of numeric edge cases: zero, negative numbers, non-numeric input, very large values, and decimal precision handling across device locales that use comma versus period as the decimal separator. The validate method's contract — returning a nullable String error message — must be agreed with the parent form team before integration to ensure consistent error-surfacing behaviour.
Helper text indicating the source of the default value should be reviewed for clarity during UX sign-off.
The Distance Input Field is a stateless Flutter widget with a required nullable defaultKm constructor parameter and a required onChanged callback. The input should use TextInputType.numberWithOptions(decimal: true) to present the numeric keyboard and accept decimal distances. The validate method returns a nullable String following Flutter's standard FormField validator contract, checking for positive non-zero numeric values and rejecting blank or non-parseable input. Pre-fill the TextEditingController with defaultKm?.toString() in initState if the parameter is non-null; handle the controller lifecycle correctly by disposing it in dispose to prevent memory leaks.
Emit onChanged on every TextEditingController listener event so the parent form can update the RealtimeReimbursementDisplay on each keystroke. Use the design token for helperText colour to display the default-value source hint subtly without competing visually with the input label or validation error message.
Responsibilities
- Render a numeric keyboard input pre-populated with the suggested default distance
- Validate that the entered value is a positive number
- Emit onChanged events for real-time downstream calculation
- Show a subtle helper text indicating the source of the default value
Interfaces
DistanceInputField({required double? defaultKm, required onChanged})
build(BuildContext context)
validate() → String?
getCurrentValue() → double?