# Core/DateRangePickerField - Design

## Anatomy

The date range picker combines two segmented date inputs (start and end) with a range calendar in a popover. Values use
[`RangeValue`](https://react-spectrum.adobe.com/react-aria/DateRangePicker.html) over types from
[`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) (for example `CalendarDate`). The
visible format follows the user’s locale.

## Properties

### Label

Provide a visible `label` so the control has a clear accessible name. If another element acts as the label, wire the
relationship with `aria-labelledby` or `aria-label` instead.

### Value

Use `value` with `onChange` for a controlled range, or `defaultValue` for an uncontrolled initial range. The handler
receives `null` when the field is cleared. Each bound is a `DateValue` consistent with your generic (for example
both `CalendarDate`).

### Placeholder

`placeholder` is a pair of strings (`[start, end]`) shown when neither bound is set and the inputs are not
focus-within, with a swap icon between them. Prefer `helperText` for requirements or instructions that must stay
visible.

### Helper text

Helper text sits below the field for requirements, hints, or errors. Pair `appearance="danger"` with error copy so
the invalid state is clear visually and to assistive technologies.

### Layout

`layout` can be **vertical** (label above) or **horizontal** (label on the leading side). Prefer vertical; use
horizontal when horizontal space is tight.

## Feedback

### Appearance

`appearance` supports **default**, **danger** (invalid / error), and **warning**. Danger also drives the invalid
state for accessibility in addition to any explicit `isInvalid` flag.

### Disabled

Disabled fields cannot be edited and do not receive focus. Values are not submitted with native form submission.

### Read-only

Read-only fields cannot be edited; the range stays visible for reading and assistive technologies.

## Accessibility

### Keyboard and pointer behavior

* **Tab** moves focus into the segmented fields or calendar trigger; **Shift+Tab** moves out.
* Arrow keys adjust focused segments; the range calendar grid follows standard date grid and range selection patterns when
  the popover is open.
* **Space** / **Enter** on the calendar button opens the popover where supported by the platform pattern.

### Labeling and instructions

Provide a visible `label` or an accessible name via `aria-label` / `aria-labelledby`. Do not rely on `placeholder` alone
for the accessible name. Prefer persistent `helperText` for requirements; the string placeholder hides when the user
focuses or enters either bound.

### Validation and state

Use `appearance="danger"` with error content in `helperText` for a consistent error treatment. Set `required` when both
bounds are mandatory. Disabled fields are not interactive and are excluded from native submission; read-only fields keep
their values visible but are not editable.

Ensure focus indicators remain visible (at least 2px, 3:1 contrast) and interactive targets meet at least 24×24 CSS
pixels where applicable.