# DataGrid: API

## API корня

`DataGrid` — корневой контейнер активной ячейки и навигации с клавиатуры.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref на корневой элемент сетки. |
| `apiRef` | `Ref<DataGridApiRef<K>>` | — | Нет | Ref на императивный API сетки. Предоставляет низкоуровневые структуры для сложных сценариев: `grid` — помощник навигации по матрице; `keyMap` — Map`<K, [row, col]>` для быстрого поиска |
| `wrap` | `DataGridWrap` | — | Нет | Режим зацикливания навигации. 'horizontal' — переход по столбцам в пределах строки; 'vertical' — переход по строкам в пределах столбца; 'both' — оба поведения; undefined — без зацикливания |
| `defaultActive` | `K` | `''` | Нет | Неконтролируемый начальный ключ активной (сфокусированной) ячейки. |
| `active` | `K` | — | Нет | Контролируемый ключ активной (сфокусированной) ячейки. |
| `onChangeActive` | `(active: K) => void` | — | Нет | Вызывается при изменении ключа активной (сфокусированной) ячейки. |
| `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 дочерних частей

## `DataGridRowGroup`

Группирует строки для регистрации в навигации.

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

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

## `DataGridRow`

Единица регистрации строки.

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

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

## `DataGridCell`

Единица регистрации ячейки.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `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>`.

## Хуки

## `useDataGridContext`

Продвинутый хук для координации на уровне корня сетки.

## `useDataGridRowContext`

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

## Типы

| Тип | Определение | Примечания |
| --- | --- | --- |
| `DataGridCellKey` | контракт ключа ячейки | Обычно строится из строки и столбца. |
| `DataGridCoordinates` | форма координат строка/столбец | Используется логикой навигации. |
| `DataGridWrap` | объединение режимов переноса | По горизонтали, по вертикали или в обе стороны. |
| `DataGridExclude` | контракт исключений | Управление навигацией в разреженной сетке. |
| `DataGridApiRef` | контракт API ref | Продвинутые интеграции. |
| `DataGridScope` | идентификатор области | При необходимости разделяет логические группы сеток. |

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

- Активная ячейка может быть контролируемой или неконтролируемой.
- Навигация зависит от порядка регистрации строк и ячеек.
- Исключения и режим переноса напрямую влияют на модель клавиатуры.
- Корень — фундаментальный слой; семантику выбора и пикера добавляют производные компоненты.

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

- Для статичного отображения данных предпочитайте `Table`.
- Используйте правила исключений, когда видимая матрица разрежена.
- Используйте `rowDelta`, когда PageUp/PageDown должны сдвигать на фиксированное число строк, а не прыгать к краям.
- Тщательно перепроверяйте интерактивное содержимое внутри ячеек.