Real-Time Reimbursement Display Widget
Component Detail
Description
A stateful Flutter widget that reactively shows the calculated payout as the peer mentor enters or adjusts the distance. Calculation is performed in the widget layer (not BLoC) to keep the UI responsive and avoid unnecessary state management overhead for a purely derived value.
realtime-reimbursement-display
Summaries
The Real-Time Reimbursement Display Widget delivers immediate financial transparency to peer mentors as they enter their travel distance, showing the exact payout they will receive before they commit to submitting a claim. This instant feedback eliminates uncertainty, builds trust in the reimbursement process, and significantly reduces the number of claims submitted with incorrect distances that require administrative correction. By keeping mentors informed in real time, the organisation demonstrates a commitment to fair and transparent compensation, which contributes directly to mentor engagement and programme retention. The widget's lightweight design also ensures the expense submission process remains fast and responsive, supporting a positive overall user experience that reflects well on the programme.
The Real-Time Reimbursement Display Widget is a low-complexity, zero-dependency component that can be developed and unit-tested in complete isolation from the rest of the mileage claim feature. Its stateless calculation approach means there is no asynchronous behaviour to test and no external service calls to mock, resulting in a short, predictable test cycle. The primary delivery risk is ensuring the per-km rate value is correctly propagated from the application configuration layer into the parent form and then into this widget — this data-flow contract should be confirmed early in the sprint to avoid late integration surprises. Currency formatting must be validated against the target locale during QA, particularly for edge cases such as zero distance, maximum claim limits, and very small decimal values.
The Real-Time Reimbursement Display is a stateful Flutter widget that receives distanceKm and ratePerKm as required constructor parameters and recomputes the display amount locally via _computeAmount on every rebuild triggered by parent state changes. No BLoC or provider subscription is needed — the parent form widget drives rebuilds by passing updated distance values on every onDistanceChanged callback, keeping the reactive data flow simple and predictable. The formatCurrency helper should use the intl package's NumberFormat.currency with the correct locale and symbol for consistent rendering across device locales. Apply design token typography classes to the amount display to ensure it visually matches the broader design system.
Edge cases to handle: negative or zero distance (display zero or hide the widget), and null rate (show a loading placeholder rather than a calculated zero).
Responsibilities
- Receive the current distance value and the per-km rate as inputs
- Compute the gross reimbursement amount locally in the widget
- Display the formatted currency amount with real-time updates on every keystroke
- Apply design token typography and color for the amount highlight
Interfaces
ReimbursementDisplay({required double distanceKm, required double ratePerKm})
build(BuildContext context)
_computeAmount(double km, double rate) → double
formatCurrency(double amount) → String