---

## 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
<script lang="ts">
import { toIso } from '@urbicon-ui/blocks/date';

const holidays = new Set([new Date(2026, 11, 24), new Date(2026, 11, 25)].map(toIso));
</script>

<DatePicker
bind:value={deadline}
label="Deadline"
minDate={new Date()}
maxDate={new Date(2026, 11, 31)}
isDateDisabled={(d) => holidays.has(toIso(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 |  | Extra classes merged onto the positioning wrapper, the `base` slot. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| 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. |
| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for the displayed date. |
| error | `string` | no |  | Error message shown below the input. |
| fixedWeeks | `boolean` | no | true | Always show 6 week rows, so the overlay keeps its height while paging months. Set `false` to let it shrink to 4 or 5 rows. |
| helper | `string` | no |  | Helper text shown below the input. |
| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no | 'outlined' | Input variant. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Disables every day it returns `true` for, on top of `minDate`/`maxDate` — the one way to disable single days, whether a rule (weekends) or a list (holidays). The calendar cannot pick a disabled day, though its arrow keys land on it, and a typed one is rejected as out of range when it is committed. It receives a `Date` of its own for each day — read only its calendar day. It runs again when `$state` it reads changes. Compare calendar days, not `Date` objects (`list.includes(d)` matches nothing): keep a list as a `Set` of `toIso` keys from `@urbicon-ui/blocks/date` and pass `(d) => blocked.has(toIso(d))`. It must not throw; the calendar does not catch it. |
| label | `string` | no |  | Label above the input. |
| locale | `string` | no | 'auto' | BCP 47 locale tag for date formatting — month names, weekday names and the header title. Defaults to `'auto'`, which follows the active `<I18nProvider>` locale, so an app that already declares its language does not have to repeat it here. SSR-safe: the locale comes from context, so the server and the client resolve the same tag (`Intl` with `undefined` would follow the runtime and disagree across hydration). Falls back to the base locale (`en`) when no provider is mounted. Pass an explicit tag (e.g. `'de-DE'`, `'ja-JP'`) to override. |
| maxDate | `Date` | no |  | Latest selectable date. |
| minDate | `Date` | no |  | Earliest selectable date. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset forwarded to the inner Input. |
| 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. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| 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' | Component size. |
| slotClasses | `Partial<Record<DatePickerSlots, string>>` | no |  | Per-slot class overrides. `base` is the positioning wrapper the field and the popover anchor sit in, `iconButton` the clear / open-calendar buttons in the field's right-icon area. The field itself is an `Input` and the overlay a `Calendar`; restyle those under their own names. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip the default tv() classes of the wrapper AND of the Input, Popover and Calendar it renders; `slotClasses` and `class` then stand alone. |
| 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 `DatePickerProps.onValueChange`. 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 `DatePickerProps.name` is set. |
| weekStartsOn | `WeekdayIndex` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |

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

### Types
```ts
interface DatePickerPreset {
label: string;
  value: Date;
}
```

```ts
interface DateRangePreset {
label: string;
  value: DateRange;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MonthIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
```

```ts
type WeekdayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6
```

```ts
interface DateRange {
start: Date;
  end: Date;
}
```

```ts
type DateFormatOptions = Intl.DateTimeFormatOptions
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `iconButton`