# Date time picker

An instant, picked as wall-clock time in a chosen zone.

Import from `@a31labs/rax/date-picker`.

## Usage

```tsx
<DateTimePicker value={instant} onValueChange={setInstant} timeZone="Europe/Vienna" />
// value is a Date (an instant) or null
```

## Rules

Built on `react-day-picker` (^10, an optional peer dependency: install it only in apps that pick dates). The root `@a31labs/rax` entry never imports it.

Values are plain strings or instants, never ambiguous Dates:
- `DatePicker`: `value: string | null` as `YYYY-MM-DD`, a plain date with no time and no zone. It renders and emits the same day in every time zone.
- `DateRangePicker`: `value: { from: string; to: string } | null` of plain dates. Two months side by side (one below 640px, or set `months`), the first click starts a range and the second completes it (a second click before the first swaps them). `presets` (`{ label, range(today) }[]`, default `DEFAULT_PRESETS`: Today, Last 7 days, Last 30 days, This month, Last month) sit in a list beside the calendar, clamped to `min`/`max` (a preset entirely outside them is disabled); `[]` hides it. `name` posts `<name>_from` and `<name>_to`.
- `TimeInput`: `value: string | null` as `HH:mm` (24h), a native time field with Input's look; native input props go to the input.
- `DateTimePicker`: `value: Date | null`, an instant. Picked and shown as wall-clock time in `timeZone` (IANA name, default the viewer's), with the calendar and a time field in the popover. `name` posts the instant as an ISO string (UTC). A skipped time on a spring-forward day moves forward past the gap (02:30 becomes 03:30); a repeated time on a fall-back day takes the earlier instant, for 30-minute, 1-hour and 2-hour shifts alike.

Shared props: `min`, `max` (plain dates; days outside are disabled and navigation stops there; an invalid value, or `min` after `max`, is ignored), `disabled`, `readOnly` (does not open and does not block submit), `required` (blocks form submit when empty and hides clear), `name`, `form`, `placeholder`, `locale` (BCP 47, default the browser's; captions, weekdays, day labels and the trigger are formatted with `Intl.DateTimeFormat`), `weekStartsOn` (default from the locale), `clearable` (default true), `today` (a plain date, for demos and tests), `defaultOpen`, `container`, `labels` (`clear`, `popup`, `presets`, `time`, `nav`: the copy that is not a date; preset names come from `presets`, the empty text from `placeholder`), plus native button props for the trigger (`ref`, `id`, `aria-*`, `onBlur`), so it works inside Field. `className` goes to the wrapper. Invalid incoming values render as empty.

The trigger is a button with Input's height, edge, radius and focus ring, a calendar icon and the formatted value (`dateStyle: "medium"`, a range as `1–7 Mar 2026`); typing a date is not supported. The clear button sits inside the trigger's edge but outside the trigger button. The calendar opens in the floating layer above dialogs; Escape closes it first and focus returns to the trigger. Opened by the user, it moves focus to the selected day (or today); open from the first render (`defaultOpen`), it leaves focus where it is. Day cells are 40px (44px on coarse pointers); today is bold and underlined, the selected day is accent with accent-ink, a range middle is accent-soft, disabled days are ink-3 with no hover. The library's stylesheet is not used; its parts are renamed `rax-cal-*`. Month navigation ("Next month (April 2026)") and "Today" come from `Intl.RelativeTimeFormat` for the locale; selection is announced through `aria-selected`. On the server and during hydration the trigger shows the raw value (`2026-03-01`) and formats it after mount, because the default locale and zone differ between server and browser; pass `locale` (and `timeZone` for DateTimePicker) to format on the server too. `parsePlainDate` and `formatPlainDate` convert between `YYYY-MM-DD` and local-midnight Dates.

Page: https://rax.a31.at/components/date-time-picker
