<!-- source-hash: c8a503e7c476a61ed70475150ecd1672 -->
A composable date picker component supporting both single-date and date-range selection modes, built on `react-day-picker` and `@radix-ui/react-popover` with Flamingo's design system tokens.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `DatePickerProps` | Type | Union of `SingleDatePickerProps` \| `RangeDatePickerProps` |
| `DatePickerMode` | Type | `"single"` \| `"range"` |
| `DatePickerBaseProps` | Interface | Shared props: `placeholder`, `disabled`, `fromDate`, `toDate`, `label`, `error`, `invalid`, `locale` |
| `SingleDatePickerProps` | Interface | Extends base; `value: Date`, `onChange: (date) => void` |
| `RangeDatePickerProps` | Interface | Extends base; `value: DateRange`, `onChange: (range) => void` |
| `DatePickerCalendar` | Component | Internal calendar renderer with custom nav and range styling |
| `CalendarNavButton` | Component | Chevron nav button wrapping Flamingo `Button` |

## Usage Example

```typescript
// Single date picker
<DatePicker
  mode="single"
  label="Start Date"
  value={selectedDate}
  onChange={(date) => setSelectedDate(date)}
  fromDate={new Date()}
/>

// Date range picker (dual month)
<DatePicker
  mode="range"
  label="Date Range"
  numberOfMonths={2}
  value={range}
  onChange={(range) => setRange(range)}
  error={formError}
  invalid={!!formError}
/>
```

## Key Behaviors

- **Single mode**: renders one `DayPicker` month with custom nav header
- **Range mode**: supports 1 or 2 simultaneous months; range start/end use accent color (`--ods-accent`), range middle uses `--ods-open-yellow-light`
- **Popover trigger**: displays a calendar icon with formatted date or placeholder text; applies red border when `invalid={true}`
- **Month navigation**: controlled internally via `useState<Date>`, independent of `DayPicker`'s built-in nav (hidden via `hideNavigation`)
- **Locale support**: passes `locale` prop directly to `DayPicker` for i18n formatting