## date_picker (`poetry_date_picker`)

A date field that opens a calendar popover for selection.

Class: Poetry::Ui::DatePicker::Component - BEM block `poetry-ui-date_picker`.
- `caption_layout:` (symbol) - default "label" - Forwarded to the wrapped Calendar: :dropdown swaps the caption for month + year selects (the date-of-birth recipe - min:/max: bound the year list).
- `label:` (string) - The trigger's accessible name (aria-label).
- `mode:` (symbol) - default "single" - :single or :range (two-date selection; the trigger shows the joined pair).
- `name:` (string) - required - The form field name - required; the chosen date posts as ISO.
- `placeholder:` (string) - default "Pick a date" - Trigger text while nothing is chosen.
- `variant:` (symbol) - default "button" - :button (the default trigger) or :input - a text field that accepts a typed date (parseable text re-selects the calendar) with a calendar icon-button opening the popover. Single mode only.
- PART `date-picker` - Root wrapper - the glue controller (formats the trigger label, closes on pick) around the composed Popover + Calendar
- WIRING root: `poetry--core--date-picker` registers; values placeholder, mode (if range?); actions picked on poetry:calendar:change
- WIRING label: `poetry--core--date-picker` targets label
- WIRING input: `poetry--core--date-picker` actions inputChanged on input, inputKeydown on keydown; targets input
- RULE: name: is REQUIRED - the chosen date posts as an ISO string (the Calendar's hidden input).
- RULE: value: preselects a date (a Date or ISO string) - the trigger shows it formatted, no JS needed.
- RULE: min:/max: bound the selectable range; the label + placeholder are the trigger's text.
- RULE: key:/id: forwards to the composed Popover - a keyed DatePicker renders cache-stable popover ids.
- RULE: variant: :input renders a text field with a calendar button - typed parseable dates re-select the calendar; single mode only.
- RULE: For an always-visible grid use Calendar directly - DatePicker is the field+popover form.