---

## DatePicker
Date input with calendar popup for selecting a single date. Supports min/max constraints, disabled dates, and format customization.

The `value` prop accepts either a `Date` or an ISO timestamp string —
useful when surrounding state is hydrated from JSON or a SQL driver
that serialises timestamps as strings. `onValueChange` always reports
back a `Date` (or `undefined`); use `toDateInputValue` from
`@urbicon-ui/blocks` to project it back into a string state.

**Import:** `import { DatePicker } from '@urbicon-ui/blocks';`

### Examples
```svelte
<DatePicker
  bind:value={selectedDate}
  label="Date of birth"
  placeholder="Select a date"
  locale="en-US"
  clearable
/>
```

```svelte
<script>
import { DatePicker, toDateInputValue } from '@urbicon-ui/blocks';
let isoDate = $state('2026-04-22T08:00:00Z');
</script>
<DatePicker
value={isoDate}
onValueChange={(d) => (isoDate = toDateInputValue(d))}
label="Period start"
/>
```

```svelte
<DatePicker
  bind:value={deadline}
  label="Deadline"
  minDate={new Date()}
  maxDate={new Date(2026, 11, 31)}
  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
  required
  error={deadlineError}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| calendarVariant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style of the calendar popup. |
| class | `string` | no |  | Additional CSS classes to apply to the DatePicker component |
| clearable | `boolean` | no | true | Allow clearing the selected date. |
| closeOnClickOutside | `boolean` | no | true | Whether the popover closes on outside click. |
| closeOnEscape | `boolean` | no | true | Whether the popover closes on Escape key. |
| closeOnSelect | `boolean` | no | true | Close popover after selecting a date. |
| defaultMonth | `MonthIndex` | no |  | Default month shown when the picker opens without a value. `0`–`11`. |
| defaultYear | `number` | no |  | Default year shown when the picker opens without a value. |
| disabled | `boolean` | no | false | Disable the entire picker. |
| disabledDates | `Date[]` | no |  | Specific dates that are disabled. |
| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for the displayed date. |
| error | `string` | no |  | Error message shown below the input. |
| fixedWeeks | `boolean` | no | false | Always show 6 weeks. |
| helper | `string` | no |  | Helper text shown below the input. |
| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no | 'outlined' | InputVariant property for the DatePicker component |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate that disables specific dates. Errors thrown by the predicate are caught and logged; the date is then treated as allowed so a faulty consumer callback can't take the picker down. |
| label | `string` | no |  | Label above the input. |
| locale | `string` | no | 'de-DE' | BCP 47 locale for date formatting and calendar. |
| maxDate | `Date` | no |  | Latest selectable date. |
| minDate | `Date` | no |  | Earliest selectable date. |
| mint | `MintProp` | no |  | Micro-interaction preset. |
| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the serialized date — matching what the user picked, so the visible input's locale-formatted display string is never submitted instead.  Empty / unset values submit as `""` so the field still appears in the FormData payload. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes. |
| onValueChange | `(value: Date | undefined) => void` | no |  | Fires when the selected date changes. |
| placeholder | `string` | no |  | Placeholder when no date is selected. |
| required | `boolean` | no | false | Mark input as required. |
| showOutsideDays | `boolean` | no | true | Show days from adjacent months. |
| showWeekNumbers | `boolean` | no | false | Show ISO week numbers. |
| size | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no | 'md' | Size variant that controls dimensions and spacing of the DatePicker |
| value | `Date | string | null` | no |  | Currently selected date. Supports bind:value. Accepts a `Date`, an ISO timestamp string, or `null` / `undefined`. Internally coerced to a `Date`; the picker emits `Date` instances via . When both `bind:value` and `onValueChange` are wired, both fire on every user-driven change — pick one to drive side-effects (saves, analytics) to avoid duplicates. |
| valueFormat | `'date' | 'iso'` | no | 'date' | Format used to serialise the date for the hidden form input. - `'date'` (default): `YYYY-MM-DD` in the local timezone — matches   the native `<input type="date">` payload and Zod schemas like   `z.string().regex(/^\d{4}-\d{2}-\d{2}$/).transform((v) => new Date(v))`. - `'iso'`: full ISO-8601 with `Z` suffix (UTC). Use this when the   downstream schema expects a parseable timestamp string (e.g. a   Drizzle `timestamp({ withTimezone: true, mode: 'date' })` column).  Only relevant when  is set. |
| weekStartsOn | `WeekdayIndex` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)