DatePicker

DatePicker is the type-and-pick date field: a text input you can type a date into and a calendar you can pick from, on garn's shared field surface (the same appearance × size grid as Input and Select). A single format prop — date-fns tokens like dd.MM.yyyy or MMM d, yyyy — drives the display, the parse, and the placeholder, so the control round-trips in whatever format you set while the committed value stays a native Date (onValueChange always hands back a Date). Typing parses on blur/Enter and reverts to the last valid value on garbage; picking a day fills the field.

DateRangePicker is the sibling export for a { start, end } range — a dual-month calendar with optional preset shortcuts ("Last 7 days", "This month"). Both share one field + popover core with the Calendar and Popover components, so they can't drift from the rest of the form family. Reach for the bare Calendar instead when the month should always be visible inline; reach for Input when the value isn't a date.

Pair every picker with a Label, and let format document the shape. A placeholder shows the expected pattern, not the field's name — associate a real Label (or Form's wiring). Pick a format that matches your users' locale expectations; it drives typing and display, so they stay in sync.

Constrain to valid dates. Use minDate/maxDate and isDateUnavailable to disable out-of-range and blackout days in the calendar and reject them on typed entry — don't accept-then-error. The calendar's navigation is bounded to the same range.

Signal validity through state. Set aria-invalid on error (the field reddens border + ring) and wire the message via aria-describedby (Form does this). Keep the control keyboard-operable: ArrowDown opens, Enter commits a typed value, Escape closes, and the calendar grid is fully navigable.

Wire format: calendar dates are zoneless. With name, the hidden form input posts a plain yyyy-MM-dd string (the <input type="date"> wire format) — DateRangePicker posts <name>-start/<name>-end in the same shape. The value is never UTC-shifted through an ISO instant; if your backend truly wants an instant, convert the Date from onValueChange yourself (lib/date-io holds the family's serializers).