Prepared Docs

Overview

AdvancedDateRangePicker from @prepared911/ui-calendar lets operators express date constraints as inequalities rather than contiguous calendar spans. A SegmentedControl at the top switches between three modes—Before, After, Between—and the body renders the corresponding DatePicker configuration. The component is built for filter and search surfaces where "on or before Jan 1", "after 6pm yesterday", and "between Oct 1 and Nov 30" all need to coexist in one control.

Values use the discriminated union AdvancedDateRangeValue keyed by mode:

When to use

Supervisor analytics and incident search filters. Operators reason about flagged incidents with phrases like "created before this shift" or "between our peak hours": the inequality mental model matches the task.
Radio dialogue search. Narrowing transmissions by a deadline ("after the incident was dispatched") or a window ("between 21:00 and 22:00 on March 3") benefits from explicit Before / After modes instead of a contiguous range.
Audit trails. Before / After modes keep half-open ranges expressible without a sentinel "today" or "epoch" end.

When not to use

Simple contiguous ranges. If the only shape is Start → End, use DatePicker in Range mode: the SegmentedControl is overhead without new capability.
Window queries only. If the product never needs Before or After semantics, pass rangeOnly to hide the mode strip and keep the grid; users see one cleaner control.
Time of day matters. Use AdvancedDateTimeRangePicker.
Time-only constraints. Use AdvancedTimeRangePicker (shared pattern, no calendar).

Composition

Mode strip. SegmentedControl with three SegmentedControlItems: Before, After, Between. Hidden when rangeOnly is true.
Calendar body. DatePicker rendered in the mode's configuration:
- Before / After: Single mode; the selected date is the bound.
- Between: Range mode; both endpoints are selectable.
Optional Apply / Reset. When onApply is provided, the component defers onChange until Apply fires and shows a Reset button.

Types

The three modes are carried in AdvancedDateRangeValue's discriminated mode field:

Mode	Selection	Semantics
`Before`	one date	the constraint is "≤ selected date"
`After`	one date	the constraint is "≥ selected date"
`Between`	two dates	inclusive range `[startDate, endDate]`

Switching modes preserves compatible fields (a Between end becomes the Before date; an After start becomes the Between start) so operators don't lose context when changing their mind mid-selection.

Behavior and states

Deferred commits. When onApply is provided, the picker tracks in-progress selection internally and only commits on Apply. onReset (or the built-in Reset when hideReset is false) returns the control to an empty selection.
Navigation bounds. disableFuture, disablePastDates, and disableFutureDates all route to the underlying DatePicker's MonthCaption, so the month and year Selects stay in sync with what's selectable.
Mode switching. Changing modes mid-flight keeps the most recently entered dates where they map cleanly; ambiguous fields clear rather than guessing.
Popover vs inline. AdvancedDateRangePicker is usually rendered inside a Popover (see dispatch's CustomTimeRangePopoverContent); the component itself has no trigger, so the consuming surface handles open state.

Customization

rangeOnly. Hides the mode strip and always uses Between. Pick this when the product has no inequality semantics: it's a lighter UI.
hideMonthYearSelect. Drops the MonthCaption selects for narrow popovers.
disableFuture / disablePastDates / disableFutureDates. Constraint knobs; pick the narrowest that matches the query (disabling future dates for past-event filters prevents "show me incidents from next week").
hideReset. Hide the Reset button when the surrounding surface already has clear-all affordances (a filter chip's X, a form reset).

Best practices

Default to Between when the operator almost always wants a window; default to Before / After when half-open ranges are the common case.
Pair with onApply in filter popovers so dispatching queries stays explicit.
Mirror the committed value in a visible pill or summary outside the popover so operators can confirm "before Mar 3" at a glance.
Use disableFutureDates for historical-only filters; the MonthCaption will stop at today automatically.

Don't

Don't render this picker without a surrounding accessible name: the mode strip changes the meaning of the grid and screen readers need to know what "Before" refers to.
Don't use AdvancedDateRangePicker when the product only ever needs Between: rangeOnly or a plain DatePicker Range is less noise.
Don't allow the operator to Apply with an incomplete Between selection; validate or disable Apply until both endpoints are set.

Accessibility

The mode strip is a SegmentedControl; the grid is a DatePicker. Both handle their own keyboard semantics, but the component does not announce mode changes or the committed value—your surrounding UI has to surface them. See the Accessibility page for the full contract, including focus handoff between the mode strip and grid.

Date Picker: the underlying calendar grid.
Advanced Date Time Range Picker: same modes, plus time-of-day.
Date Input: a field-anchored variant when operators need to type a date.

Event Recurrence Picker / Accessibility

Advanced Date Range Picker / API and Development

Overview

Values use the discriminated union AdvancedDateRangeValue keyed by mode:

When to use

Supervisor analytics and incident search filters. Operators reason about flagged incidents with phrases like "created before this shift" or "between our peak hours": the inequality mental model matches the task.
Radio dialogue search. Narrowing transmissions by a deadline ("after the incident was dispatched") or a window ("between 21:00 and 22:00 on March 3") benefits from explicit Before / After modes instead of a contiguous range.
Audit trails. Before / After modes keep half-open ranges expressible without a sentinel "today" or "epoch" end.

When not to use

Simple contiguous ranges. If the only shape is Start → End, use DatePicker in Range mode: the SegmentedControl is overhead without new capability.
Window queries only. If the product never needs Before or After semantics, pass rangeOnly to hide the mode strip and keep the grid; users see one cleaner control.
Time of day matters. Use AdvancedDateTimeRangePicker.
Time-only constraints. Use AdvancedTimeRangePicker (shared pattern, no calendar).

Composition

Mode strip. SegmentedControl with three SegmentedControlItems: Before, After, Between. Hidden when rangeOnly is true.
Calendar body. DatePicker rendered in the mode's configuration:
- Before / After: Single mode; the selected date is the bound.
- Between: Range mode; both endpoints are selectable.
Optional Apply / Reset. When onApply is provided, the component defers onChange until Apply fires and shows a Reset button.

Types

The three modes are carried in AdvancedDateRangeValue's discriminated mode field:

Mode	Selection	Semantics
`Before`	one date	the constraint is "≤ selected date"
`After`	one date	the constraint is "≥ selected date"
`Between`	two dates	inclusive range `[startDate, endDate]`

Switching modes preserves compatible fields (a Between end becomes the Before date; an After start becomes the Between start) so operators don't lose context when changing their mind mid-selection.

Behavior and states

Deferred commits. When onApply is provided, the picker tracks in-progress selection internally and only commits on Apply. onReset (or the built-in Reset when hideReset is false) returns the control to an empty selection.
Navigation bounds. disableFuture, disablePastDates, and disableFutureDates all route to the underlying DatePicker's MonthCaption, so the month and year Selects stay in sync with what's selectable.
Mode switching. Changing modes mid-flight keeps the most recently entered dates where they map cleanly; ambiguous fields clear rather than guessing.
Popover vs inline. AdvancedDateRangePicker is usually rendered inside a Popover (see dispatch's CustomTimeRangePopoverContent); the component itself has no trigger, so the consuming surface handles open state.

Customization

rangeOnly. Hides the mode strip and always uses Between. Pick this when the product has no inequality semantics: it's a lighter UI.
hideMonthYearSelect. Drops the MonthCaption selects for narrow popovers.
disableFuture / disablePastDates / disableFutureDates. Constraint knobs; pick the narrowest that matches the query (disabling future dates for past-event filters prevents "show me incidents from next week").
hideReset. Hide the Reset button when the surrounding surface already has clear-all affordances (a filter chip's X, a form reset).

Best practices

Default to Between when the operator almost always wants a window; default to Before / After when half-open ranges are the common case.
Pair with onApply in filter popovers so dispatching queries stays explicit.
Mirror the committed value in a visible pill or summary outside the popover so operators can confirm "before Mar 3" at a glance.
Use disableFutureDates for historical-only filters; the MonthCaption will stop at today automatically.

Don't

Don't render this picker without a surrounding accessible name: the mode strip changes the meaning of the grid and screen readers need to know what "Before" refers to.
Don't use AdvancedDateRangePicker when the product only ever needs Between: rangeOnly or a plain DatePicker Range is less noise.
Don't allow the operator to Apply with an incomplete Between selection; validate or disable Apply until both endpoints are set.