Custom Date Range Picker
Component Detail
Description
Reusable date range selection widget used when predefined presets do not cover the required period. Enforces logical date ordering and surfaces accessibility-compliant calendar controls.
custom-date-range-picker
Summaries
The Custom Date Range Picker enables reporting staff to define arbitrary date windows when the standard fiscal period presets do not match their needs — for example, for ad-hoc reviews, audits, or special grant periods. As a shared, reusable component, it eliminates the need to build and maintain multiple date selection implementations across different parts of the application, which directly reduces development and maintenance cost. It is built with accessibility compliance in mind, ensuring the application meets inclusive design obligations and reduces legal and reputational risk. Organizations benefit from a consistent, validated input experience wherever date range selection is required.
The Custom Date Range Picker is a shared component with low internal complexity but broad impact across the application due to its reuse across multiple features. Because it is shared, any change to this component can affect every feature that consumes it — making thorough testing and a stable API critical before it is integrated. Development effort is one to two days for the core widget, plus additional effort for accessibility compliance verification (screen reader labels, focus management, keyboard navigation). Coordinate with all consuming feature teams to agree on the onRangeSelected callback contract before finalizing.
Plan for regression testing across all consuming contexts whenever this component is updated.
Custom Date Range Picker is a reusable Flutter widget marked is_shared, meaning it is consumed across multiple features and must maintain a stable public API. It exposes four interfaces: build(BuildContext), onRangeSelected(DateTimeRange) callback emitted on valid selection, setInitialRange(DateTimeRange?) for pre-populating state, and clearSelection() for resetting. Internally it manages start and end date state independently and validates that start precedes end before emitting via onRangeSelected — invalid ranges should display an inline error rather than emitting. It has no service dependencies, making it fully unit-testable in isolation.
Accessibility requirements mean all calendar controls must include semantic labels for screen readers. Because this is a shared component, version it carefully: any interface change requires coordinating updates across all consuming widgets. Consider wrapping it in an InheritedWidget or provider if theme customization is needed per feature context.
Responsibilities
- Allow start and end date selection
- Validate that start date precedes end date
- Emit DateTimeRange on change
Interfaces
build(BuildContext)
onRangeSelected(DateTimeRange)
setInitialRange(DateTimeRange?)
clearSelection()