# Core/DatePickerField - Design

## Anatomy

The date picker combines a segmented date input with a calendar in a popover. Values use 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 value, or `defaultValue` for an uncontrolled initial value. The handler
receives `null` when the field is cleared.

### Placeholder

`placeholder` shows a single string when the field is empty and not focused. 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 value stays visible for reading and assistive technologies.

## Accessibility

### Keyboard and pointer behavior

* **Tab** moves focus into the segmented field or calendar trigger; **Shift+Tab** moves out.
* Arrow keys adjust focused segments; calendar grid follows standard date grid keyboard 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; placeholder disappears when the user types.

### Validation and state

Use `appearance="danger"` with error content in `helperText` for a consistent error treatment. Set `required` when the
field is 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.