# Calendar

A month-grid date picker with optional month-picking mode and `Temporal.PlainDate` binding.

## Usage

Use standalone.
```svelte
<Calendar {...props} />
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props. While `picking`, `children` renders inside `middle` and wins over the embedded `MonthPicker`.

```svelte
<div class="whole" role="group">
  <div class="top">
    <button class="left" type="button">{left}</button>
    <button class="label" type="button">{label}</button>
    <button class="right" type="button">{right}</button>
  </div>
  <div class="middle">
    <div class="main" role="grid">
      <div class="aux" role="row" data-header>
        <span class="extra" role="columnheader" data-header>{weekday}</span>
      </div>
      <div class="aux" role="row">
        <button class="extra" role="gridcell">{day}</button>
      </div>
    </div>
    {#if children}{children}{:else}<MonthPicker />{/if} while picking
  </div>
  <div class="bottom" conditional>{bottom}</div>
</div>
```

- Left and right buttons page `display`; the label button toggles `picking`.
- While picking, `children` renders in the middle slot and wins over the embedded `MonthPicker`.
- The `bottom` snippet receives a control object (`setToday`, `clear`), the `picking` state, and the variant.
- Enabled day clicks and Enter or Space select one `Temporal.PlainDate`.
- Day cells expose `data-today`, `data-selected`, `data-outside`, `data-disabled`, and `data-weekday`.
- The weekday header row and each week row both use the `aux` part; only the header row and its column headers carry `data-header`, which separates header-only from day-only styling.
- Arrow keys, Home, End, PageUp, PageDown, and Shift+PageUp/PageDown update roving focus.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `value` | `Temporal.PlainDate` | - | Bindable selected date |
| `display` | `Temporal.PlainYearMonth` | - | Bindable shown year-month for calendar paging |
| `picking` | `boolean` | `false` | Bindable state that shows the embedded `MonthPicker` instead of the day grid |
| `min` | `Temporal.PlainDate` | - | Lower date bound; dates before it are disabled |
| `max` | `Temporal.PlainDate` | - | Upper date bound; dates after it are disabled |
| `isDisabled` | `(d: Temporal.PlainDate) => boolean` | - | Custom predicate that disables matching dates |
| `outsideDays` | `boolean` | `false` | Show outside-month days in the grid |
| `fixedWeeks` | `boolean` | `false` | Render a fixed six-week grid |
| `firstDayOfWeek` | `number` | `0` | First weekday, where `0` = Sunday |
| `locale` | `string` | - | Locale for weekday and heading labels |
| `label` | `Snippet` | - | Heading snippet |
| `left` | `Snippet` | - | Previous-button snippet |
| `right` | `Snippet` | - | Next-button snippet |
| `weekday` | `Snippet` | - | Weekday label snippet |
| `day` | `Snippet` | - | Day cell snippet |
| `bottom` | `Snippet` | - | Bottom-area snippet; receives a control object (`setToday`, `clear`), the `picking` state, and the variant |
| `children` | `Snippet` | - | Overrides the middle slot while picking; wins over `monthPicker` |
| `monthPicker` | `MonthPickerProps` | - | Nested config bag spread into the embedded `MonthPicker`; `Calendar` owns the displayed month, bounds, and variant |
| `transition` | `TransitionProp` | - | Optional transition function and params for switching between the day grid and month picker |
| `pageTransition` | `TransitionProp` | - | Optional transition that slides the day grid when `display` pages |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Variant passed to navigation and container parts |
## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

Selected days render with `active`, disabled days render with `inactive`, and other day cells use `neutral`. Navigation and container parts receive the supplied `variant`.

### Default Class Name

`svs-calendar`

## Behavior

- Left/right buttons page `display`; the label toggles the picking slot.
- While picking, `children` renders in the middle slot and wins over the embedded `MonthPicker`.
- The `bottom` snippet receives a control object (`setToday`, `clear`), the `picking` state, and the variant.
- Enabled day clicks and Enter/Space select a single `Temporal.PlainDate`.
- Day cells expose `data-today`, `data-selected`, `data-outside`, `data-disabled`, and `data-weekday`.
- Arrow, Home/End, PageUp/PageDown, and Shift+PageUp/PageDown update roving focus.
- The grid re-keys when `display` changes; optional `pageTransition` applies to the day-grid page change.

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowLeft` / `ArrowRight` | Moves focus one day backward or forward |
| `ArrowUp` / `ArrowDown` | Moves focus one week backward or forward |
| `Home` / `End` | Moves focus to the start or end of the focused week |
| `PageUp` / `PageDown` | Moves focus one month backward or forward |
| `Shift` + `PageUp` / `Shift` + `PageDown` | Moves focus one year backward or forward |
| `Enter` / `Space` | Selects the focused day |
Clicking an enabled day also selects it.

### ARIA Roles and Attributes

The component applies these automatically:

- Root (`whole`): `role="group"` and `aria-label` generated from the current displayed month.
- Caption button (`label`): `aria-expanded` for the month/year picker state.
- Grid (`main`): `role="grid"` and `aria-labelledby` pointing to the caption button; it contains weekday and week rows.
- Weekday row (`aux`): `role="row"` containing column headers.
- Weekday header: `role="columnheader"` with an `aria-label` for the full weekday name.
- Day cell: `role="gridcell"`, roving `tabindex`, `aria-selected`, `aria-disabled`, `aria-current="date"` on today, and a per-date `aria-label`.

The root already has a built-in accessible name such as the current month. Provide clear custom `label`, `left`, `right`, and day snippets if you replace the default visible text.

## Exports

### Types

```ts
interface CalendarProps {
  value?: Temporal.PlainDate; // bindable; selected date
  display?: Temporal.PlainYearMonth; // bindable; shown month
  picking?: boolean; // bindable (false)
  min?: Temporal.PlainDate;
  max?: Temporal.PlainDate;
  isDisabled?: (d: Temporal.PlainDate) => boolean;
  outsideDays?: boolean; // (false)
  fixedWeeks?: boolean; // (false)
  firstDayOfWeek?: number; // (0=Sun)
  locale?: string;
  label?: Snippet<[Temporal.PlainYearMonth, string, boolean]>;
  left?: Snippet<[string]>;
  right?: Snippet<[string]>;
  weekday?: Snippet<[number, string]>;
  day?: Snippet<[DayCtx]>;
  bottom?: Snippet<[CalendarCtl, boolean, string]>;
  children?: Snippet;
  monthPicker?: Omit<MonthPickerProps, "value" | "min" | "max" | "variant">;
  transition?: TransitionProp;
  pageTransition?: TransitionProp;
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
}
type CalendarReqdProps = never;
type CalendarBindProps = "value" | "display" | "picking";
type DayCtx = {
  date: Temporal.PlainDate;
  variant: string;
  weekday: number;
  today: boolean;
  selected: boolean;
  outside: boolean;
  disabled: boolean;
};
type CalendarCtl = {
  setToday: () => void;
  clear: () => void;
};
type TransitionProp = {
  fn?: (node: HTMLElement, params: any, options: { direction: "in" | "out" | "both" }) => import("svelte/transition").TransitionConfig;
  params?: unknown;
};
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=CalendarBasic.svelte
<script lang="ts">
  import { Calendar } from "svseeds";

  let value = $state<Temporal.PlainDate>();
  const childStyle1 = {
    whole: "relative flex items-center rounded-md bg-white dark:bg-black",
    left: "absolute inset-y-0 inset-x-1 my-auto h-7 rounded-md opacity-30 bg-black dark:bg-white pointer-events-none",
  };
  const childStyle2 = {
    whole: "w-35 h-30 overflow-hidden rounded-md",
    middle: "h-full",
    label: {
      base: "flex h-8 items-center justify-end",
      active: "font-bold",
    },
    aux: "hidden",
    extra: "inset-0 bg-linear-to-b from-white via-transparent to-white dark:from-black dark:to-black",
  };
  const childStyle3 = {
    ...childStyle2,
    whole: "w-35 h-30 overflow-hidden rounded-md",
    label: {
      base: "flex ps-4 h-8 items-center justify-start",
      active: "font-bold",
    },
  };
  const childProps = {
    styling: childStyle1,
    left,
    yearLabel: (y: number) => String(y),
    monthLabel: (m: number) => String(m).padStart(2, "0"),
    year: { styling: childStyle2 },
    month: { styling: childStyle3 },
  };
  const styling = {
    whole: "w-72 rounded-md border bg-white p-3 dark:bg-black",
    top: "mb-3 flex items-center gap-2",
    left: "px-2 py-1 rounded-md border text-sm cursor-pointer",
    label: "min-w-0 flex-1 cursor-pointer rounded-md border px-2 py-1 text-sm font-bold",
    right: "px-2 py-1 rounded-md border text-sm cursor-pointer",
    middle: "overflow-hidden",
    aux: "grid grid-cols-7 gap-1 pb-1 font-bold",
    main: "grid gap-1 outline-hidden",
    extra: {
      base: "flex size-8 items-center justify-center rounded-md text-sm data-header:data-[weekday=0]:text-red-500 data-outside:text-gray-400 data-today:font-bold data-today:not-data-selected:bg-gray-400",
      active: "bg-teal-500 font-bold",
      inactive: "text-gray-400",
    },
  };
  const myProps = {
    styling,
    monthPicker: childProps,
    outsideDays: true,
  };
</script>

<div class="flex flex-col items-center gap-3">
  <Calendar bind:value {...myProps}>
    {#snippet left()}{"<"}{/snippet}
    {#snippet right()}{">"}{/snippet}
  </Calendar>
  <div class="text-sm">Selected: {value?.toString() ?? "Pick a day"}</div>
</div>
{#snippet left()}{/snippet}
```
### With Interactive Variant

**Code**

```svelte src=CalendarPract.svelte
<script lang="ts">
  import { cubicInOut } from "svelte/easing";
  import { Calendar } from "svseeds";

  let { variant = $bindable() } = $props();
  let value = $state<Temporal.PlainDate>();
  function slide(_node: HTMLElement, params: { dir?: number; duration?: number }, { direction }: { direction: "in" | "out" | "both" }) {
    const dir = params.dir ?? 0;
    const entering = direction === "in";
    return {
      duration: params.duration ?? 250,
      easing: cubicInOut,
      css: (t: number) => {
        const offset = (1 - t) * (entering ? dir : -dir) * 100;
        const overlay = entering ? "" : "position:absolute;inset:0;";
        return `${overlay}transform:translateX(${offset}%);`;
      },
    };
  }

  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const childStyle1 = {
    whole: "relative flex items-center rounded-md bg-white dark:bg-black",
    left: "absolute inset-y-0 inset-x-1 my-auto h-7 rounded-md opacity-30 bg-black dark:bg-white pointer-events-none",
  };
  const childStyle2 = {
    whole: "w-35 h-30 overflow-hidden rounded-md",
    middle: "h-full",
    label: {
      base: "flex h-8 items-center justify-end",
      active: "font-bold",
    },
    aux: "hidden",
    extra: "inset-0 bg-linear-to-b from-white via-transparent to-white dark:from-black dark:to-black",
  };
  const childStyle3 = {
    ...childStyle2,
    whole: "w-35 h-30 overflow-hidden rounded-md",
    label: {
      base: "flex ps-4 h-8 items-center justify-start",
      active: "font-bold",
    },
  };
  const childProps = {
    styling: childStyle1,
    left,
    yearLabel: (y: number) => String(y),
    monthLabel: (m: number) => String(m).padStart(2, "0"),
    year: { styling: childStyle2 },
    month: { styling: childStyle3 },
  };
  const styling = {
    whole: {
      base: "w-72 rounded-md border bg-white p-3 dark:bg-black",
      ...variantStyle,
    },
    top: "mb-3 flex items-center gap-2",
    left: "px-2 py-1 rounded-md border text-sm cursor-pointer order-2",
    label: "min-w-0 flex-1 cursor-pointer px-2 font-bold underline order-1",
    right: "px-2 py-1 rounded-md border text-sm cursor-pointer order-3",
    middle: "relative overflow-hidden",
    aux: "grid grid-cols-7 gap-1 not-data-header:pb-1 data-header:font-bold data-header:border-b border-gray-400",
    main: "grid gap-1 outline-hidden",
    extra: {
      base: "flex size-8 items-center justify-center rounded-md text-sm data-header:data-[weekday=0]:text-red-500 data-outside:text-gray-400 data-today:not-data-selected:bg-gray-400",
      active: "bg-teal-500 font-bold",
      inactive: "text-gray-400",
    },
    bottom: "pt-3 text-center",
  };
  const myProps = {
    styling,
    monthPicker: childProps,
    outsideDays: true,
    fixedWeeks: true,
    pageTransition: { fn: slide },
  };
</script>

<div class="flex flex-col items-center gap-3">
  <Calendar bind:value {variant} {...myProps}>
    {#snippet label(ym)}
      {ym.toString()}
    {/snippet}
    {#snippet left()}{"<"}{/snippet}
    {#snippet right()}{">"}{/snippet}
    {#snippet bottom(ctl)}
      <button class="rounded-md border px-3 py-1 text-sm cursor-pointer" type="button" onclick={ctl.setToday}>Today</button>
    {/snippet}
  </Calendar>
  <div class="text-sm">Selected: {value?.toString() ?? "Pick a day"}</div>
</div>
{#snippet left()}{/snippet}
```