Receipt Capture Widget
Component Detail
Description
Reusable widget for capturing or selecting a receipt photo via the device camera or gallery using image_picker. Displays the attached image thumbnail, upload progress, and removal option. Enforces the configurable receipt threshold requirement by signalling mandatory attachment status to the parent form.
receipt-capture-widget
Summaries
The Receipt Capture Widget directly supports financial compliance and audit readiness by ensuring employees attach photographic evidence to expense claims whenever a configurable spending threshold is met. This reduces the risk of fraudulent or undocumented reimbursements, strengthens internal controls, and minimises exposure during external audits. Because the component is shared across all expense entry flows in the mobile application, it delivers consistent policy enforcement without requiring duplicate development investment. The ability to enforce mandatory attachment rules dynamically — based on claim amount — means the organisation can tighten or relax its receipt policy without a software release, providing operational agility that directly reduces administrative overhead and accelerates reimbursement cycles.
As a shared mobile component, the Receipt Capture Widget must be delivered and stabilised before any expense entry feature reaches testing, making it a critical-path dependency for the entire submission workflow. Development effort covers image_picker integration, Supabase Storage upload with progress feedback, thumbnail rendering, and the threshold-driven required/optional state signal to parent forms. Testing must cover camera and gallery permissions on both iOS and Android, upload failure and retry scenarios, large image handling, and offline edge cases. Because multiple features consume this widget, a defect here has wide blast radius — regression testing should accompany every change.
Coordinate closely with the receipt-storage-adapter team on upload contract and error codes to avoid integration delays.
The Receipt Capture Widget integrates with the device camera and photo gallery via the image_picker package, handles the full upload lifecycle through receipt-storage-adapter, and exposes a clean callback-based contract to parent forms. The build(isRequired, currentImageUrl) interface initialises display state, while onImageSelected, onImageRemoved, onUploadComplete, and onUploadError form the event surface that parent widgets subscribe to. setRequired(bool) allows dynamic threshold enforcement at runtime without rebuilding the widget tree. Upload progress is tracked internally and reflected in the UI, isolating parent forms from storage implementation details.
State management should guard against concurrent uploads and rapid selection changes. The widget owns the receipt data model interaction — parents receive only the final Supabase Storage URL, keeping storage concerns encapsulated. Test with mock receipt-storage-adapter to validate error propagation and required-state signalling independently of network conditions.
Responsibilities
- Launch image_picker for camera or gallery selection
- Display upload progress and attached image thumbnail
- Signal required/optional state based on expense amount threshold
- Emit uploaded Supabase Storage URL to parent form
Interfaces
build(isRequired, currentImageUrl)
onImageSelected(file)
onImageRemoved()
onUploadComplete(storageUrl)
onUploadError(error)
setRequired(bool)
Relationships
Used Integrations (1)
External integrations and APIs this component relies on