Build CustomDateRangePicker widget
epic-bufdir-report-period-selection-foundation-task-006 — Implement an accessible Flutter date range picker widget that provides dual calendar controls for selecting start and end dates. Must enforce logical date ordering (end >= start), provide clear error feedback when ordering is violated, support keyboard navigation, announce selection changes to screen readers via semantics labels, and meet WCAG 2.2 AA contrast ratios using the project design token color palette.
Acceptance Criteria
Technical Requirements
Implementation Notes
Build as a StatefulWidget that internally manages _startDate and _endDate state. Consider wrapping Flutter's built-in CalendarDatePicker or showDateRangePicker as a base — if the built-in widget does not meet accessibility or design requirements, implement a custom grid using a Table widget with GestureDetector cells. Implement date ordering validation in a private _validateAndEmit() method called after every selection change. Use ExcludeSemantics judiciously — never suppress screen reader access to interactive elements.
Apply the project design token system for all colours: use token references such as AppColors.primary for selected state, AppColors.error for the error indicator. Ensure keyboard focus is managed with FocusNode and FocusTraversalGroup so Tab moves logically from start to end picker. Announce selection changes using SemanticsService.announce() or by updating a live Semantics node.
Testing Requirements
Widget tests using flutter_test. Test cases: (1) initial values pre-populate both pickers correctly, (2) selecting end < start shows inline error and does not invoke onChange, (3) correcting the order clears the error and invokes onChange with a valid DateTimeRange, (4) onChange fires with the correct DateTimeRange when both dates are valid, (5) Semantics labels are present on selected date cells, (6) keyboard navigation moves focus between days (simulate key events with tester.sendKeyEvent), (7) touch target size >= 48 dp for day cells and navigation arrows. Include a golden test for default, selected-range, and error states.
Supabase RLS policies for period preset configuration may be missing or incorrectly scoped, causing one organisation's presets to leak to another or write operations to fail silently.
Mitigation & Contingency
Mitigation: Define and review RLS policies for the bufdir_period_presets table in the migration file before any repository code is written. Include an integration test that verifies cross-organisation isolation using two distinct org credentials.
Contingency: If RLS is misconfigured in production, immediately disable the period preset fetch endpoint and fall back to hardcoded global presets until the policy is corrected and redeployed.
The activities table may lack a composite index on (organisation_id, activity_date), causing the range count query in BufdirAggregationRepository to perform a full table scan and exceed acceptable response time for large organisations.
Mitigation & Contingency
Mitigation: Add a migration that creates a composite index on (organisation_id, activity_date) as part of this epic. Benchmark the count query against a representative dataset (10 000+ rows) before marking the epic complete.
Contingency: If query latency is unacceptable after indexing, move the count query to a Supabase RPC function that leverages a materialised view or partial index, accepting a slight staleness window.
Flutter's native date picker widgets have known accessibility gaps (missing semantic labels, non-standard focus traversal) that may prevent WCAG 2.2 AA compliance out of the box, requiring a custom implementation.
Mitigation & Contingency
Mitigation: Evaluate third-party accessible date picker packages (e.g., table_calendar with custom semantics) against WCAG 2.2 AA criteria before beginning implementation. Document the chosen approach in the epic kick-off.
Contingency: If no package meets accessibility requirements, implement a simple text-field-based date entry with explicit semantic labels and format hints as an accessible fallback, deferring a fully visual calendar to a later iteration.