# DataGridSelectable: API

## API корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `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' — переход по столбцам в пределах строки; '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 дочерних частей

## `DataGridSelectableRowGroup`

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

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `scope` | `DataGridScope` | — | Нет | Необязательная логическая группа для ячеек сетки. Позволяет DataGrid считать ячейки частью одной страницы или раздела. |

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

## `DataGridSelectableRow`

Одна строка ячеек матрицы.

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

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

## `DataGridSelectableCell`

Одна выбираемая ячейка.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | — | Нет | Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid |
| `col` | `number` | — | Да | Индекс столбца ячейки (с 0). Вместе с индексом строки из контекста строки образует координаты сетки: `[row, col]`. |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией `itemRef([row, col], key)`, если ячейка не исключена. |
| `cellKey` | `DataGridCellKey` | — | Нет | Стабильный ключ, идентифицирующий ячейку в матрице DataGrid. Если не задан, ключ выводится из row/col как `${row}:${col}`. |
| `asChild` | `boolean` | `false` | Нет | Если `true`, рендерит дочерние элементы через `Slot` и передаёт пропсы и ref дочернему элементу вместо использования нативного `<div>`. |
| `excluded` | `boolean` | — | Нет | Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid |

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

- модель ключей ячеек должна оставаться стабильной между рендерами

## Хуки

## `useDataGridSelectableContext`

Продвинутый хук для чтения состояния выбора и отключённости в собственных обёртках ячеек.

## Типы

| Тип | Определение | Примечания |
| --- | --- | --- |
| `DataGridSelectableProps<K, S>` | тип пропсов корня | Расширяет `DataGridProps<K>`. |
| `DataGridSelectableRowGroupProps` | пропсы группы строк | Группировка и поведение областей. |
| `DataGridSelectableRowProps` | пропсы строки | Метаданные координаты строки. |
| `DataGridSelectableCellProps` | пропсы ячейки | Координата ячейки и пропсы рендера. |
| `DataGridSelection` | `'single' \| 'multiple' \| 'range'` | Режим выбора. |
| `DataGridDisabled<K>` | тип карты отключённых ячеек | Предикат, список или ключ. |

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

- Активное и выбранное состояния могут быть как контролируемыми, так и неконтролируемыми.
- Режим диапазона использует логику расширения, управляемую клавиатурой и движением указателя.
- Отключённые и исключённые ячейки меняют и выбор, и навигацию.

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

- Сохраняйте стабильный порядок ключей при использовании `compare` и логики диапазонов.
- Используйте `DataGridPicker`, когда визуальный слой пикера должен быть стандартным.
- Проверяйте перетаскивание указателем, расширение с `Shift` и циклическую навигацию вместе в реальных сценариях.