# IndexedSnapScroller: API

## Пропсы корня

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

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

- `IndexedSnapScrollerContent`: шаблон содержимого, привязанный к текущему виртуальному индексу.

### `IndexedSnapScrollerContent`

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

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

## Типы

- `IndexedSnapScrollerProps`
- `IndexedSnapScrollerContentProps`
- `IndexedSnapScrollerApiRef`

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

- Корень управляет скользящим окном логических индексов.
- Контролируемый `index` может либо прокрутить к существующему элементу, либо вызвать сброс окна.
- Пока прокрутка доходит до конца, страницы добавляются, чтобы она могла продолжаться; когда прокрутка останавливается, окно заново центрируется на привязанной странице.
- `next()` / `prev()` отсчитывают от страницы, к которой уже движется прокрутка, и сначала расширяют окно, если цель за его пределами.