DataGridPicker

DataGridPicker — визуальный слой пикера поверх DataGridSelectable.

API корня

Проп	Тип	По умолчанию
`size`	`DataGridPickerSize`	`'md'`
Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам.
`variant`	`DataGridPickerVariant`	`'secondary'`
Предустановка внешнего вида пикера.
`selection`	`S`	`'single'`
Режим выбора. `'single'` — одновременно можно выбрать только одну ячейку; `'multiple'` — независимый множественный выбор (переключение по ячейке); `'range'` — выбор диапазона между двумя точками (Shift + стрелки или перетаскивание указателем)
`disabled`	`DataGridDisabled<K>`	—
Предикат или набор отключённых ячеек. Может быть: функцией `(key) => boolean`; массивом отключённых ключей; одним ключом. Отключённые ячейки нельзя выбрать или сфокусировать.
`excludeDisabled`	`boolean`	`true`
—
`expandable`	`boolean`	`true`
Включает расширение диапазонов выбора (Shift + стрелка или перетаскивание мышью).
`defaultActive`	`K`	—
Неконтролируемая начальная активная ячейка.
`active`	`K`	—
Контролируемая активная ячейка.
`selected`	`S extends "single" ? K \| null : K[]`	—
Контролируемые выбранные ячейки. В режиме `'single'` значение `null` означает контролируемое состояние без выбора.
`defaultSelected`	`S extends "single" ? K : K[]`	—
Неконтролируемые изначально выбранные ячейки.
`from`	`K`	—
Границы диапазона. Если заданы, ограничивают выбор ячейками между `from` и `to` на основе функции `compare`.
`to`	`K`	—
—
`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<K>>`	—
Ref на императивный API сетки. Предоставляет низкоуровневые структуры для сложных сценариев: `grid` — помощник навигации по матрице; `keyMap` — Map`<K, [row, col]>` для быстрого поиска
`wrap`	`DataGridWrap`	`'horizontal'`
Режим зацикливания навигации. 'horizontal' — переход по столбцам в пределах строки; 'vertical' — переход по строкам в пределах столбца; 'both' — оба поведения; undefined — без зацикливания
`exclude`	`DataGridExclude<K>`	—
Исключает ячейки из обхода фокусом. Может быть: одним ключом; массивом ключей; предикатом `(key) => boolean`
`rowDelta`	`number`	—
Шаг навигации по строкам для PageUp/PageDown. `undefined` — переход к первой/последней строке; `number` — сдвиг на N строк относительно текущей
`onArrow`	`(e: KeyboardEvent<HTMLDivElement>, node: MatrixNode<HTMLElement, K>, prevNode: MatrixNode<HTMLElement, K>) => void`	—
Вызывается на каждом шаге навигации стрелками после смены фокуса

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

API дочерних частей

`DataGridPickerRowGroup`

Группирует строки пикера и может задавать scope страницы в композициях со скроллером.

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

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

`DataGridPickerRow`

Одна строка пикера.

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

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

`DataGridPickerItem`

Выбираемый элемент пикера.

Проп	Тип	По умолчанию
`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>.

`DataGridPickerScroller`

Необязательная обёртка-скроллер для постраничного вывода.

Проп	Тип	По умолчанию
`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>.

`DataGridPickerScrollerContent`

Обёртка содержимого страницы скроллера.

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

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

Хуки

`useDataGridPickerContext`

Продвинутый хук для чтения текущих размера и варианта пикера внутри собственных обёрток элементов.

Типы

Тип	Определение	Примечания
`DataGridPickerProps<K, S>`	тип пропсов корня	Расширяет `DataGridSelectableProps<K, S>`.
`DataGridPickerItemProps`	пропсы элемента пикера	Поверхность выбираемого элемента.
`DataGridPickerRowProps`	пропсы строки	Метаданные координат строки.
`DataGridPickerRowGroupProps`	пропсы группы строк	Группировка с учётом `scope`.
`DataGridPickerScrollerProps`	пропсы скроллера	Постраничный макет пикера.
`DataGridPickerScrollerContentProps`	пропсы содержимого скроллера	Обёртка содержимого страницы.

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

Поведение выбора берётся из DataGridSelectable.
Размер и вариант передаются через контекст пикера.
Композиции со скроллером добавляют идентичность страницы поверх того же движка выбора.

Заметки по интеграции

Используйте scope группы строк в постраничных композициях пикера, где важна идентичность страницы.
Предпочитайте обёртки более высокого уровня, такие как DayPicker, MonthPicker или YearPicker, когда предметная семантика уже смоделирована.
Сохраняйте стабильность ключей и порядок выбора в соответствии с видимым макетом пикера.