# @cloud-ru/ds-carousel

> Компонент горизонтальной прокрутки слайдов — стрелки, пагинация, свайп, автопрокрутка, infinite scroll и multi-item отображение.

Docs: /snack-v2/components/carousel/

## Установка

```sh
pnpm add @cloud-ru/ds-carousel
```

## Когда использовать

- Галереи изображений и медиа.
- Онбординг с несколькими шагами.
- Секции «Похожие товары», «Недавние проекты» — несколько карточек в viewport (`showItems > 1`).

Когда **не** нужен: для табличных данных (используйте `@cloud-ru/ds-tabs`), для форм (обычная вертикальная прокрутка), для длинных списков (виртуализация).

## API

### Carousel
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `arrows` | `boolean` | `true` | no | Использовать стрелки для переключения страниц |
| `autoSwipe` | `number` | — | no | Автоматическое переключение слайдов в секундах |
| `children` | `ReactElement<any, string \| JSXElementConstructor<any>>[]` | — | yes | Массив айтемов |
| `className` | `string` | — | no | CSS - класснейм |
| `controlsVisibility` | `always \| hover` | `hover` | no | Управление видимостью стрелок: 'hover' — по ховеру, 'always' — всегда |
| `data-test-id` | `string` | — | no |  |
| `gap` | `string` | `var(--dimension-2m)` | no | Расстояние между айтемами |
| `infiniteScroll` | `boolean` | `false` | no | Цикличная прокрутка |
| `pagination` | `boolean` | `true` | no | Использовать пагинацию для переключения страниц |
| `scrollBy` | `number` | `Math.trunc(show)` | no | Сдвиг айтемов при смене 1 страницы |
| `showItems` | `number` | `1` | no | Кол-во отображаемых единовременно айтемов |
| `state` | `{ page: number; onChange(page: number): void; }` | — | no | Управление состоянием извне |
| `swipe` | `boolean` | `true` | no | Переключение страниц свайпом |
| `swipeActivateLength` | `number` | `48` | no | Минимальная длина в px для активации свайпа |
| `transition` | `number` | `0.4` | no | Время переключения 1 страницы (в s) |

#### Related types
- `ControlsVisibility` = `always | hover`

### Control
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `className` | `string` | — | no |  |
| `data-test-id` | `string` | — | no |  |
| `direction` | `next \| prev` | — | yes |  |
| `onClick` | `(() => void)` | — | no |  |

### ItemProvider
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `gap` | `string` | — | no |  |
| `page` | `number` | — | yes |  |
| `scrollBy` | `number` | — | yes |  |
| `showItems` | `number` | — | yes |  |
| `slideCallback` | `(direction: number) => void` | — | yes |  |
| `swipe` | `boolean` | — | yes |  |
| `swipeActivateLength` | `number` | — | yes |  |
| `transition` | `number` | — | yes |  |

## Примеры

### Basic

```tsx
import { Carousel } from '@cloud-ru/ds-carousel';

export function Basic() {
  return (
    <div style={{ width: 480 }}>
      <Carousel>
        <div style={{ height: 180, background: '#4f46e5', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 1
        </div>
        <div style={{ height: 180, background: '#0ea5e9', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 2
        </div>
      </Carousel>
    </div>
  );
}
```

### Infinite

```tsx
import { Carousel } from '@cloud-ru/ds-carousel';

export function Infinite() {
  return (
    <div style={{ width: 480 }}>
      <Carousel infiniteScroll autoSwipe={3}>
        <div style={{ height: 180, background: '#10b981', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 1
        </div>
        <div style={{ height: 180, background: '#f59e0b', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 2
        </div>
        <div style={{ height: 180, background: '#ec4899', color: '#fff', display: 'grid', placeItems: 'center' }}>
          Slide 3
        </div>
      </Carousel>
    </div>
  );
}
```

### ThreePerView

```tsx
import { Carousel } from '@cloud-ru/ds-carousel';

export function ThreePerView() {
  return (
    <div style={{ width: 600 }}>
      <Carousel showItems={3} gap='12px'>
        {Array.from({ length: 6 }).map((_, i) => (
          <div
            key={i}
            style={{ height: 120, background: '#f3f4f6', display: 'grid', placeItems: 'center', borderRadius: 8 }}
          >
            Card {i + 1}
          </div>
        ))}
      </Carousel>
    </div>
  );
}
```