# Calendar

Вбудована сітка місяця з вибором дати або діапазону і повним клавіатурним контрактом grid.


Сітка місяця, яку видно завжди. Не заміна
[`UiDatePicker`](https://ui.tatet.net/docs/components/date-picker): той лишається тонкою
обгорткою над нативним `<input type="date">` і лишається типовою порадою
для однієї дати у формі.

`UiCalendar` існує для того, чого нативний пікер не вміє: діапазони,
предикат недоступних днів, два місяці поруч і завжди відкрита сітка.


Example (app/demos/calendar/CalendarBasic.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiCalendar from '~/components/ui/UiCalendar.vue'

// Дата фіксована, щоб демо виглядало однаково в прередері й у браузері.
const TODAY = new Date(2026, 7, 17)
const picked = ref<Date | null>(new Date(2026, 7, 17))

const formatted = new Intl.DateTimeFormat('uk-UA', { dateStyle: 'long' })
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <div class="rounded-card border border-line bg-card p-3">
      <UiCalendar
        v-model="picked"
        :today="TODAY"
        :min="new Date(2026, 6, 1)"
        :max="new Date(2026, 8, 30)"
        show-week-numbers
        aria-label="Дата візиту"
      />
    </div>
    <p class="text-sm text-muted">
      Обрано: <span class="text-ink">{{ picked ? formatted.format(picked) : 'нічого' }}</span>
    </p>
  </div>
</template>

```


## Дати без бібліотеки дат

Бібліотека не має зовнішніх залежностей, тож уся арифметика — у
`app/utils/calendar.ts`. Там діє одне жорстке правило: **нова дата
будується конструктором `new Date(рік, місяць, день)`**, ніколи додаванням
мілісекунд.

`date.getTime() + 86_400_000` — це не «наступний день», а «рівно 24
години». У ніч переходу на зимовий час доба триває 25 годин, і такий
«наступний день» лишається у вчорашньому; навесні — перестрибує. Сітка
місяця тоді втрачає або дублює день **двічі на рік**, і відтворити це
можна лише в ті самі вихідні.

Друга пастка того ж роду — `setMonth`. Для 31 січня плюс місяць він дає
3 березня, бо 31 лютого не існує. `addMonths` затискає день до останнього в
місяці, інакше PageDown із січня вів би в березень, оминаючи лютий.

## Завжди шість рядків

Сітка — це завжди 42 комірки. Місяць, що вміщається у п'ять тижнів, усе
одно малює шість рядків.

Причина не косметична: змінна висота панелі під час гортання всередині
закріпленого попапа щоразу перезапускає логіку перевороту, і панель видимо
стрибає над полем і під нього. З `showOutsideDays: false` зайві дні
лишаються **порожніми комірками**, а не зникають із DOM — `role="grid"`
вимагає однакової кількості клітинок у кожному рядку.

## Клавіатура


Example (app/demos/calendar/CalendarRange.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiCalendar from '~/components/ui/UiCalendar.vue'

const TODAY = new Date(2026, 7, 17)
const range = ref<[Date, Date] | null>([new Date(2026, 7, 10), new Date(2026, 7, 19)])

// Вихідні недоступні: predicate лишає день фокусованим, але не обираним.
function isWeekend(date: Date) {
  return date.getDay() === 0 || date.getDay() === 6
}

const formatted = new Intl.DateTimeFormat('uk-UA', { dateStyle: 'medium' })
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <div class="rounded-card border border-line bg-card p-3">
      <UiCalendar
        v-model="range"
        mode="range"
        :months="2"
        :today="TODAY"
        :disabled-date="isWeekend"
        aria-label="Період бронювання"
      />
    </div>
    <p class="text-sm text-muted">
      Період:
      <span class="text-ink">
        {{ range ? `${formatted.format(range[0])} — ${formatted.format(range[1])}` : 'не обрано' }}
      </span>
    </p>
  </div>
</template>

```


Рівно один день у всьому віджеті має `tabindex="0"` — той, що у фокусі;
решта отримують `-1`. Початковий фокус: обрана дата → початок діапазону →
сьогодні (кожна — лише якщо вона в показаних місяцях) → перший доступний
день.

Гортання кнопками чи `v-model:month` переносить фокусований день у
показаний місяць — той самий день місяця. Поки цього не було, фокусований
день виїжджав з екрана, жодна клітинка не мала `tabindex="0"`, і Tab
перестрибував сітку. З двома місяцями дні сусіднього місяця, що дублюють
видимі дати (1–11 жовтня в хвості вересня), зупинкою Tab не бувають:
фокус завжди на «справжній» клітинці.

| Клавіші | Дія |
|---|---|
| `←` `→` | ∓1 день |
| `↑` `↓` | ∓1 тиждень |
| `Home` `End` | початок і кінець тижня, у якому фокус |
| `PageUp` `PageDown` | ∓1 місяць |
| `Shift+PageUp` `Shift+PageDown` | ∓1 рік |
| `Enter` `Space` | обрати день |
| `Escape` | скасувати незавершений діапазон |

Клавіші з таблиці працюють лише на днях сітки. Кнопки «Попередній» і
«Наступний місяць» (як і кнопки в слотах `header`/`footer`) — звичайні
кнопки: Enter і пробіл на них гортають, а не обирають сфокусований день.

Вихід фокуса за межі показаних місяців гортає їх сам і емітить
`update:month`. Рух **затискається** по `min`/`max`, а не блокується: інакше
межа перетворюється на невидиму стіну, з якої не зрозуміло, як вибратись.

Недоступні дні позначені `aria-disabled`, а **не** атрибутом `disabled` —
інакше стрілками неможливо перескочити заблокований тиждень.

`Escape` обробляється лише тоді, коли є що скасовувати. Якщо незавершеного
діапазону немає, подія йде далі — і панель, у якій календар лежить,
закривається сама.

## API

[Props, events, slots, exposed API (JSON)](https://ui.tatet.net/api/component-meta/UiCalendar)

## Коли використовувати

- Вибір діапазону дат.
- Форми, де корисно бачити місяць цілком: бронювання, розклад, зайняті дні.
- Коли частину днів треба заблокувати за правилом.

## Коли НЕ використовувати

- Для однієї дати у звичайній формі — беріть
  [`UiDatePicker`](https://ui.tatet.net/docs/components/date-picker): нативний пікер дає
  безкоштовний мобільний інтерфейс і локаль системи.
- Для дати народження: рік зручніше набрати з клавіатури, ніж догортати.
- Для періоду з пресетами над таблицею — це вже
  [`UiDateRangePicker`](https://ui.tatet.net/docs/components/date-range-picker).

## Доступність

Сітка — справжня `<table role="grid">` з `<caption>`-заголовком через
`aria-labelledby`. Підпис місяця має `aria-live="polite"`: без нього
PageUp/PageDown міняє місяць беззвучно.

Кожен день — кнопка з `aria-label` у форматі «12 серпня 2026 р., середа».
Саме число сховано через `aria-hidden`. Голе «12» у сітці, яку читають
клітинка за клітинкою, не несе нічого, а зв'язок із заголовками рядка й
колонки в `role="grid"` оголошується ненадійно в різних парах
браузер + скрінрідер.

Кінці діапазону додають до назви « — початок періоду» і « — кінець
періоду»: візуального виділення самого по собі не чути. `aria-selected`
стоїть на обох кінцях і на всіх днях між ними — це і є виділення.

Сьогоднішній день несе `aria-current="date"`.

## Деталі реалізації

Назви місяців і днів тижня беруться з `Intl.DateTimeFormat` за `locale`.
Заголовок колонки має повну назву в `aria-label` і скорочену — видиму:
«пн» на око, «понеділок» на слух.

Props `today` існує заради детермінізму. Без нього прередер малює один
місяць, а браузер за добу — інший, і тест із фіксованою датою неможливий.


## Event descriptions

- `update:modelValue`: Обрана дата або кортеж `[початок, кінець]`. У режимі діапазону приходить лише коли відомі ОБИДВА кінці.
- `update:month`: Показаний місяць змінився — гортанням або виходом фокуса за його межі.


[Source files, dependencies and ZIP](https://ui.tatet.net/registry/components/calendar.json)
