DayPicker

DayPicker — низкоуровневая подсистема сетки дней, на которой строится стек календаря.

Пропсы корня

Проп	Тип	По умолчанию
`month`	`string`	—
Видимый месяц — строка `YYYY-MM-DD` любого дня в нём. По умолчанию — текущий месяц.
`calendar`	`CalendarSystem`	`gregorianCalendar`
Календарная система, в которой строится сетка месяца. По умолчанию — григорианский календарь.
`locale`	`string`	`getDefaultLocale()`
Локаль BCP 47 для подписей и первого дня недели, например `de-DE`. По умолчанию — локаль среды выполнения, как у `Intl`.
`size`	`DataGridPickerSize`	`'xs'`
Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам.
`variant`	`DataGridPickerVariant`	—
Предустановка внешнего вида пикера.
`selection`	`S`	`'single'`
Режим выбора. `'single'` — одновременно можно выбрать только одну ячейку; `'multiple'` — независимый множественный выбор (переключение по ячейке); `'range'` — выбор диапазона между двумя точками (Shift + стрелки или перетаскивание указателем)
`disabled`	`DataGridDisabled<string>`	—
Предикат или набор отключённых ячеек. Может быть: функцией `(key) => boolean`; массивом отключённых ключей; одним ключом. Отключённые ячейки нельзя выбрать или сфокусировать.
`excludeDisabled`	`boolean`	—
—
`expandable`	`boolean`	`true`
Включает расширение диапазонов выбора (Shift + стрелка или перетаскивание мышью).
`defaultActive`	`string`	—
Неконтролируемая начальная активная ячейка.
`active`	`string`	—
Контролируемая активная ячейка.
`selected`	`S extends "single" ? string \| null : string[]`	—
Контролируемые выбранные ячейки. В режиме `'single'` значение `null` означает контролируемое состояние без выбора.
`defaultSelected`	`S extends "single" ? string : string[]`	—
Неконтролируемые изначально выбранные ячейки.
`from`	`string`	—
Границы диапазона. Если заданы, ограничивают выбор ячейками между `from` и `to` на основе функции `compare`.
`to`	`string`	—
—
`resolveRange`	`(start: DataGridResolveValue<K>, end: DataGridResolveValue<K>, grid: Grid<HTMLElement, K>) => K[]`	—
Собственная логика построения диапазона для `selection="range"`. По начальному и конечному значениям возвращает список ключей, образующих диапазон.
`equals`	`(start: K \| undefined, end: K \| undefined) => boolean`	—
Собственная функция сравнения двух ключей ячеек на равенство. По умолчанию — строгое равенство (`===`).
`compare`	`(a: K, b: K) => -1 \| 0 \| 1`	—
Собственная функция упорядочивания двух ключей ячеек. Должна возвращать `-1`, `0` или `1`.
`onSelectCell`	`(value: S extends 'single' ? K : K[]) => void`	—
Вызывается, когда пользователь выбирает ячейку. Получает список ключей выбранных ячеек.
`onChangeActive`	`(active: K) => void`	—
Вызывается при изменении активной (сфокусированной) ячейки.
`ref`	`Ref<HTMLDivElement>`	—
Ref на корневой элемент сетки.
`apiRef`	`Ref<DataGridApiRef<string>>`	—
Ref на императивный API сетки. Предоставляет низкоуровневые структуры для сложных сценариев: `grid` — помощник навигации по матрице; `keyMap` — Map`<K, [row, col]>` для быстрого поиска
`wrap`	`DataGridWrap`	—
Режим зацикливания навигации. 'horizontal' — переход по столбцам в пределах строки; 'vertical' — переход по строкам в пределах столбца; 'both' — оба поведения; undefined — без зацикливания
`exclude`	`DataGridExclude<string>`	—
Исключает ячейки из обхода фокусом. Может быть: одним ключом; массивом ключей; предикатом `(key) => boolean`
`rowDelta`	`number`	—
Шаг навигации по строкам для PageUp/PageDown. `undefined` — переход к первой/последней строке; `number` — сдвиг на N строк относительно текущей
`onArrow`	`(e: KeyboardEvent<HTMLDivElement>, node: MatrixNode<HTMLElement, K>, prevNode: MatrixNode<HTMLElement, K>) => void`	—
Вызывается на каждом шаге навигации стрелками после смены фокуса

Также принимает все атрибуты <div>.

Дочерние части

DayPickerLayout
DayPickerRowGroup
DayPickerRow
DayPickerItem
DayPickerCell
DayPickerScroller
DayPickerScrollerContent
DayPickerScrollerLayout

`DayPickerItem`

Проп	Тип	По умолчанию
`range`	`DataGridPickerItemRangePosition`	—
Необязательный визуальный индикатор положения ячейки в диапазоне. Одно из: `"start" \| "between" \| "end"`. Если не задан, компонент вычисляет его автоматически по контексту выбора.
`size`	`DataGridPickerSize`	—
Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам.
`value`	`DataGridCellKey`	—
Логическое значение, связанное с этой ячейкой сетки. Используется как уникальный ключ выбора ячейки.
`variant`	`DataGridPickerVariant`	—
Предустановка внешнего вида пикера.
`disabled`	`boolean`	—
Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid
`ref`	`Ref<HTMLDivElement>`	—
Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией `itemRef([row, col], key)`, если ячейка не исключена.
`col`обязательный	`number`	—
Индекс столбца ячейки (с 0). Вместе с индексом строки из контекста строки образует координаты сетки: `[row, col]`.
`asChild`	`boolean`	`false`
Если `true`, рендерит дочерние элементы через `Slot` и передаёт пропсы и ref дочернему элементу вместо использования нативного `<div>`.
`excluded`	`boolean`	—
Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid

Также принимает все атрибуты <div>.

`DayPickerCell`

Проп	Тип	По умолчанию
`size`	`DataGridPickerSize`	—
Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам.
`range`	`DataGridPickerItemRangePosition`	—
Необязательный визуальный индикатор положения ячейки в диапазоне. Одно из: `"start" \| "between" \| "end"`. Если не задан, компонент вычисляет его автоматически по контексту выбора.
`variant`	`DataGridPickerVariant`	—
Предустановка внешнего вида пикера.
`disabled`	`boolean`	—
Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid
`ref`	`Ref<HTMLDivElement>`	—
Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией `itemRef([row, col], key)`, если ячейка не исключена.
`asChild`	`boolean`	`false`
Если `true`, рендерит дочерние элементы через `Slot` и передаёт пропсы и ref дочернему элементу вместо использования нативного `<div>`.
`excluded`	`boolean`	—
Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid

Также принимает все атрибуты <div>.

`DayPickerRow`

Проп	Тип	По умолчанию
`row`обязательный	`number`	—
Индекс строки (с нуля) для всех дочерних ячеек. Передаётся потомкам через контекст.

Также принимает все атрибуты <div>.

`DayPickerRowGroup`

Проп	Тип	По умолчанию
`scope`	`DataGridScope`	—
Проп `scope` обязателен и идентифицирует логическую группу ячеек, которые рендерит эта группа строк. При использовании с `DataGridIndexedSnapScroller` scope обычно совпадает с текущим индексом или страницей. Scope позволяет DataGrid вернуть фокус на первую доступную ячейку, когда индекс меняется и рендерятся новые ячейки.

Также принимает все атрибуты <div>.

`DayPickerLayout`

Проп	Тип	По умолчанию
`children`обязательный	`ReactNode`	—
Шаблон ячейки дня, рендерится один раз для каждого дня сетки. День читается через `useDayPickerCellContext()`; обычно `<DayPickerCell />`.
`rows`	`number`	`6`
Количество строк сетки (обычно 5 или 6 в зависимости от месяца).
`month`	`string`	—
Месяц для рендера — строка `YYYY-MM-DD` любого дня в нём. По умолчанию — месяц родительского DayPicker.
`offset`	`number`	`0`
Индекс страницы, который сохраняет индексы строк уникальными, когда несколько месяцев рендерятся рядом (например, скроллером).
`includeOverflowDays`	`boolean`	`false`
Рендерить ли дни предыдущего и следующего месяцев, чтобы заполнить всю сетку. Если false, лишние ячейки пустые или отключены.
`locale`	`string`	—
Локаль для форматирования подписи дня. По умолчанию — локаль пикера.
`format`	`Intl.DateTimeFormatOptions['day']`	`'numeric'`
Формат отображения дня (Intl.DateTimeFormat). Пример: "numeric", "2-digit".
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	—
Определяет первый день недели. 0 = воскресенье, 1 = понедельник, … 6 = суббота.
`scope`	`DataGridScope`	—
Проп `scope` обязателен и идентифицирует логическую группу ячеек, которые рендерит эта группа строк. При использовании с `DataGridIndexedSnapScroller` scope обычно совпадает с текущим индексом или страницей. Scope позволяет DataGrid вернуть фокус на первую доступную ячейку, когда индекс меняется и рендерятся новые ячейки.

Также принимает все атрибуты <div>.

`DayPickerScroller`

Проп	Тип	По умолчанию
`onChangePeriod`	`(month: string) => void`	—
Вызывается, когда страница месяца прокручивается в область видимости, с первым днём этого месяца в виде строки `YYYY-MM-DD` в календарной системе DayPicker.
`defaultMonth`	`string`	—
Начальный месяц для неконтролируемого использования вне DayPicker — строка `YYYY-MM-DD` любого дня в нём. По умолчанию — текущий месяц.
`start`	`number`	`-2`
Начальный индекс для генерации исходной последовательности страниц. Служит логической точкой отсчёта для скользящего окна индексов.
`startDir`	`-1 \| 1`	`1`
Направление, в котором растёт начальная последовательность индексов. `1` — индексы растут вправо (0, 1, 2…); `-1` — индексы убывают вправо (0, -1, -2…). Управляет порядком роста начального массива индексов.
`size`	`number`	`5`
Количество сегментов индексов, отрендеренных одновременно. Определяет размер виртуального «окна», по которому скроллер сдвигается при навигации влево или вправо.
`shift`	`number`	`2`
Количество страниц, добавляемых, когда прокрутка доходит до конца окна, чтобы быстрый свайп продолжался. Когда прокрутка останавливается, окно заново центрируется на странице привязки.
`index`	`number`	—
Управляет текущим активным логическим индексом. Если задан, скроллер держит этот индекс в области видимости: прокручивает к нему, если это возможно, или при необходимости перестраивает окно.
`preserveScroll`	`boolean`	`true`
Сохраняет текущий привязанный элемент после изменения содержимого (например, когда страницы добавляются в начало или конец). Если `true`, скроллер восстановит тот же индекс привязки через мгновенный `scrollIntoView`.
`apiRef`	`Ref<IndexedSnapScrollerApiRef>`	—
Предоставляет императивный API скроллера. Позволяет управлять им программно, например прокручивать к индексу или сбрасывать виртуальное окно.
`onOffset`	`(value: number) => void`	—
Вызывается, когда окно растёт у края. `-1` — прокрутка остановилась на первой странице (левый/верхний край); `+1` — прокрутка дошла до конца (правый/нижний край). Полезно для бесконечной подгрузки: добавляйте страницы в конец или в начало в зависимости от направления.
`ref`	`Ref<HTMLDivElement>`	—
Ref на элемент скроллера.
`defaultIndex`	`number`	—
Начальный индекс элемента, к которому выполняется привязка при монтировании.
`onScrollSnapChange`	`(element: HTMLElement, index: number) => void`	—
Вызывается, когда операция прокрутки с привязкой полностью завершена и скроллер остановился на новом индексе привязки. Колбэк вызывается после завершения всех анимаций прокрутки и привязки, когда активная позиция привязки считается стабильной.
`onScrollSnapChanging`	`(element: HTMLElement, index: number) => void`	—
Вызывается, пока операция прокрутки с привязкой идёт и активный индекс привязки ещё меняется. Колбэк может вызываться несколько раз за одну прокрутку или свайп, пока скроллер приближается к конечной позиции привязки. Полезен для оптимистичных обновлений интерфейса, превью или синхронизации промежуточного состояния во время прокрутки.

Также принимает все атрибуты <div>.

`DayPickerScrollerContent`

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLDivElement>`	—
Внешний ref на корневой элемент элемента. Объединяется с внутренним `itemRef(index)`, чтобы участвовать в логике привязки.
`asChild`	`boolean`	—
Рендерит содержимое как дочерний элемент (через `Slot`) вместо нативного `<div>`. Атрибуты и ref остаются привязанными к переданному дочернему элементу.

Также принимает все атрибуты <div>.

`DayPickerScrollerLayout`

Проп	Тип	По умолчанию
`children`обязательный	`ReactNode`	—
Шаблон ячейки дня, рендерится один раз для каждого дня сетки. День читается через `useDayPickerCellContext()`; обычно `<DayPickerCell />`.
`locale`	`string`	—
Локаль для форматирования подписи дня. По умолчанию — локаль пикера.
`rows`	`number`	`6`
Количество строк сетки (обычно 5 или 6 в зависимости от месяца).
`includeOverflowDays`	`boolean`	`false`
Рендерить ли дни предыдущего и следующего месяцев, чтобы заполнить всю сетку. Если false, лишние ячейки пустые или отключены.
`format`	`Intl.DateTimeFormatOptions['day']`	`"numeric"`
Формат отображения дня (Intl.DateTimeFormat). Пример: "numeric", "2-digit".
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	—
Определяет первый день недели. 0 = воскресенье, 1 = понедельник, … 6 = суббота.
`scope`	`DataGridScope`	—
Проп `scope` обязателен и идентифицирует логическую группу ячеек, которые рендерит эта группа строк. При использовании с `DataGridIndexedSnapScroller` scope обычно совпадает с текущим индексом или страницей. Scope позволяет DataGrid вернуть фокус на первую доступную ячейку, когда индекс меняется и рендерятся новые ячейки.

Также принимает все атрибуты <div>.

Типы

DayPickerProps
DayPickerLayoutProps
DayPickerRowGroupProps
DayPickerRowProps
DayPickerItemProps
DayPickerCellProps
DayPickerCellContextData
DayPickerScrollerProps
DayPickerScrollerContentProps
DayPickerScrollerLayoutProps

Модель состояния

Состояние выбора наследуется от DataGridPicker.
Ключи ячеек — дни YYYY-MM-DD; selected, from, to, disabled и active используют те же строки.
Корень предоставляет видимый month (его первый день) и calendar через useDayPickerContext.
createDayPickerGrid({ month, calendar, rows, offset, includeOverflowDays, weekStartsOn }) возвращает строки из { col, date, day, inCurrentMonth }.
Страницы скроллера — календарные месяцы, отсчитываемые от referenceMonth (useDayPickerScrollerContext); onChangePeriod получает первый день видимого месяца.
Дочерние элементы DayPickerLayout и DayPickerScrollerLayout — шаблон ячейки, который рендерится по разу на каждый день внутри контекста ячейки. Дочерние элементы обязательны; обычно это <DayPickerCell />, который показывает отформатированную подпись.
useDayPickerCellContext() возвращает { col, date, fields, label, inMonth }; date равен undefined для пустой ячейки за пределами месяца. Берите номера дней из label или fields, а не из ISO-строки date.
locale и calendar — пропсы корня; раскладки принимают собственное переопределение locale.