---

## Calendar
Flexible calendar component with month, year, week, and day views.
Renders timed appointments, multi-day spans and recurrence on a time grid, with
event display, date selection and configurable layout. For a headless grid that
buckets your own domain content (meals, shifts, bookings) per day, use `Planner`.

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

### Examples
```svelte
<Calendar
  events={wasteEvents}
  categories={wasteCategories}
  bind:value={selectedDate}
  showEventList
  showLegend
  locale="de-DE"
/>
```

```svelte
<Calendar view="week" bind:value={selectedDate} />
```

```svelte
<Calendar selectionMode="range" bind:value={dateRange}>
  {#snippet children()}
    <CalendarHeader showViewSwitcher />
    <CalendarGrid />
  {/snippet}
</Calendar>
```

### Variants
- variant: bordered, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CalendarVariants | `VariantProps` | no |  | Styling variants from CalendarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| agendaDays | `number` | no | 30 | Number of days shown in agenda view. |
| animated | `boolean` | no | true | Enable animated transitions for navigation. |
| categories | `CalendarEventCategory[]` | no | [] | Event categories for color coding and legend. |
| children | `Snippet` | no |  | Default children snippet for custom layout composition. |
| class | `string` | no |  | Extra CSS classes on the root element. |
| dayCell | `Snippet<[DayCellContext]>` | no |  | Custom snippet for rendering a day cell. |
| defaultDate | `Date` | no |  | Initial reference day the grid is anchored on, without selecting it. Use this to open a **week** or **day** view on a specific week — `defaultMonth`/ `defaultYear` resolve to the 1st, whose week can fall mostly in the previous month. Ignored when `value` is set (the selection anchors instead); takes priority over `defaultMonth`/`defaultYear`. Read at mount only. |
| defaultMonth | `number` | no |  | Initial displayed month (0–11). Used only when `value` and `defaultDate` are unset; when `value` is provided, the calendar opens on the value's month. Best for month/year views — for week/day views prefer `defaultDate`. Defaults to current month. |
| defaultYear | `number` | no |  | Initial displayed year. Used only when `value` is unset; when `value` is provided, the calendar opens on the value's year. Defaults to current year. |
| disabled | `boolean` | no | false | Disable the entire calendar. |
| disabledDates | `Date[]` | no |  | Specific dates that are disabled (not selectable). |
| draggable | `boolean` | no | false | Enable drag & drop to move events between dates. |
| eventItem | `Snippet<[EventItemContext]>` | no |  | Custom snippet for rendering an event item in the detail list. |
| eventPopover | `boolean` | no | false | Show a rich popover on hover/focus for days with events (month view). |
| events | `CalendarEvent[]` | no | [] | Array of events to display on the calendar. |
| fixedWeeks | `boolean` | no | false | Always show 6 weeks in the grid. |
| header | `Snippet<[HeaderContext]>` | no |  | Custom snippet for the header area. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Function to test whether a date is disabled. |
| locale | `string` | no | 'de-DE' | BCP 47 locale tag for date formatting. |
| maxDate | `Date` | no |  | Latest selectable/navigable date. |
| minDate | `Date` | no |  | Earliest selectable/navigable date. |
| miniCalendarPosition | `'left' | 'right'` | no | 'left' | Position of the mini calendar sidebar. |
| mint | `MintProp` | no |  | Micro-interaction preset. |
| onDateClick | `(date: Date) => void` | no |  | Fires when a date cell is clicked (regardless of selection change). |
| onDateCreate | `(date: Date, view: CalendarViewMode) => void` | no |  | Fires on double-click on a day cell for event creation. The consumer shows their own form. |
| onDayChange | `(date: Date) => void` | no |  | Fires when the displayed day changes (day view). |
| onEventClick | `(event: CalendarEvent) => void` | no |  | Fires when an event is clicked. |
| onEventMove | `(event: CalendarEvent, newStart: Date, newEnd: Date) => void` | no |  | Fires when an event is moved via drag & drop. |
| onEventResize | `(event: CalendarEvent, newEnd: Date) => void` | no |  | Fires when an event is resized via drag handle. |
| onMonthChange | `(month: number, year: number) => void` | no |  | Fires when the displayed month/year changes via navigation. |
| onTimeSlotCreate | `(start: Date, end: Date) => void` | no |  | Fires on click on an empty time slot for event creation. Returns default 1h duration. |
| onValueChange | `(value: CalendarSelection) => void` | no |  | Fires when the selected date(s) change. |
| onViewChange | `(view: CalendarViewMode) => void` | no |  | Fires when the view mode changes. |
| onWeekChange | `(weekStart: Date) => void` | no |  | Fires when the displayed week changes (week view). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Calendar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| resizable | `boolean` | no | false | Enable resize handles on timed events in the time grid. |
| selectionMode | `'single' | 'range' | 'multiple'` | no | 'single' | SelectionMode property for the Calendar component |
| showEventList | `boolean` | no |  | Whether to show the detail list when a date is selected. Auto-enabled when events are provided. |
| showLegend | `boolean` | no |  | Whether to show the built-in legend. Defaults to true when categories are provided. |
| showMiniCalendar | `boolean` | no | false | Show a mini month calendar sidebar (week/day/agenda views). |
| showOutsideDays | `boolean` | no | true | Show days from previous/next months to fill the grid. |
| showTimeGrid | `boolean` | no |  | Show time grid in week/day views. Auto-detected from events with allDay: false. |
| showViewSwitcher | `boolean` | no | true | Show the view switcher in the header. |
| showWeekNumbers | `boolean` | no | false | Show ISO week numbers in the left margin. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Calendar |
| slotClasses | `Partial<Record<CalendarSlots, string>>` | no |  | Per-slot class overrides. |
| swipeable | `boolean` | no | true | Enable swipe gestures for touch navigation. |
| timeGridEndHour | `number` | no | 20 | Last visible hour in time grid (exclusive). |
| timeGridInterval | `30 | 60` | no | 60 | Time slot interval in minutes. |
| timeGridStartHour | `number` | no | 7 | First visible hour in time grid. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. |
| value | `CalendarSelection` | no |  | Currently selected date(s). Supports bind:value. |
| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style variant for the Calendar component |
| view | `CalendarViewMode` | no | 'month' | Active view mode. Supports bind:view. |
| views | `CalendarViewMode[]` | no | ['month', 'week', 'day', 'year', 'agenda'] | Which views appear in the view switcher. |
| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |

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