Time Window Selector
Component Detail
Description
Segmented control or tab bar widget allowing the user to switch between current month, quarter, and year time windows. Emits a TimeWindow value upstream to trigger data refresh. Preserves selected window in local state across screen rebuilds.
time-window-selector
Summaries
The Time Window Selector gives every user a consistent and intuitive way to control the reporting period they are viewing across the entire application. By standardizing the month, quarter, and year options into a single reusable control, the organization ensures that all statistics screens speak the same language — coordinators, peer mentors, and administrators all filter data through the same three time horizons that align with NHF reporting cycles. This consistency reduces user confusion, shortens onboarding time for new coordinators, and ensures that data comparisons between screens are always apples-to-apples. A well-designed time filter directly supports better decision-making and reduces the likelihood of coordinators drawing conclusions from mismatched data windows.
The Time Window Selector is a low-complexity, self-contained widget with no external dependencies, making it one of the safest deliverables in the mobile component inventory. It can be built and unit-tested in isolation early in the sprint, then dropped into any statistics screen as those screens reach integration. Because it preserves selected state across rebuilds, QA should verify state restoration after hot-reload, navigation back-and-forth, and OS-level interruptions (calls, backgrounding). There is no backend dependency, so it introduces no scheduling risk tied to API readiness.
The primary delivery risk is UI consistency — the segmented control or tab bar styling must align with the design system across all screen sizes and OS versions targeted by the application.
Time Window Selector is a stateful Flutter widget that encapsulates a single piece of UI state: the currently selected TimeWindow enum value (month, quarter, year). It exposes a constructor callback onChanged and an optional initialWindow parameter, keeping the API minimal and composable. Internal state is managed with setState or a lightweight local ValueNotifier — no Riverpod or BLoC needed given its scope. The widget renders a SegmentedButton or TabBar depending on design spec, and calls onChanged immediately on tap via onWindowTap, allowing parent screens like stats-screen-coordinator to trigger data refreshes reactively.
State is preserved across rebuilds because the widget holds its own local state rather than relying on parent rebuilds to pass the selected value back down. Keep the TimeWindow enum definition in a shared types file so all consuming screens reference the same values without duplication.
Responsibilities
- Render selectable time window options (month, quarter, year)
- Emit selected time window to parent via callback
- Maintain and restore selected state
Interfaces
TimeWindowSelector({required void Function(TimeWindow) onChanged, TimeWindow initialWindow})
onWindowTap(TimeWindow window)
getSelectedWindow() TimeWindow
Relationships
Dependents (2)
Components that depend on this component