# @cloud-ru/ds-stepper

> Адаптивный индикатор прогресса для многошаговых сценариев — единый render-prop API, раскладка из AdaptiveProvider.

Docs: /snack-v2/components/stepper/

## Установка

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

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

- Многошаговые формы, где пользователю важно видеть прогресс и (на desktop) описание каждого шага.
- Процессы с валидацией между шагами (submit → backend check → next).

## API

### DesktopStep
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `className` | `string` | — | no | CSS-класс |
| `data-test-id` | `string` | — | no | data-test-id |
| `hideTailLine` | `boolean` | — | no | Скрыть хвост-линию: нужно сторям, которые показывают шаг в отрыве от ряда |
| `step` | `StepViewData` | — | yes | Данные шага для отображения |

### DesktopStepper
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `allowFreeNavigation` | `boolean` | `false` | no | Позволяет свободно переключаться между разными шагами без валидации |
| `children` | `(params: StepperApi) => ReactElement<any, string \| JSXElementConstructor<any>>` | — | yes | Render function. Принимает `stepper` — JSX-элемент степпера, а также api: `goNext`, `goPrev`, `resetValidation`, `setValidator`, `isCompleted`, `currentStepIndex`, `stepCount`. |
| `className` | `string` | — | no | CSS-класс |
| `data-test-id` | `string` | — | no | data-test-id |
| `defaultCurrentStepIndex` | `number` | `0` | no | Индекс текущего шага по-дефолту |
| `onChangeCurrentStep` | `((newValue: number, prevValue: number) => void)` | — | no | Колбек смены текущего степа |
| `onCompleteChange` | `((isCompleted: boolean) => void)` | — | no | Колбек изменения завершённости |
| `steps` | `StepData[]` | — | yes | Массив шагов |
| `validator` | `StepsValidator` | — | no | Валидатор шагов. Выполняется при смене шага. Принимает первым аргументом индекс текущего, вторым — индекс нового шага. Возвращает Promise<boolean>: false → шаг помечается как Rejected. |

### MobileStep
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `data-test-id` | `string` | — | no | data-test-id |
| `step` | `StepViewData` | — | yes | Данные шага для отображения |

### MobileStepper
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `allowFreeNavigation` | `boolean` | `false` | no | Позволяет свободно переключаться между разными шагами без валидации |
| `children` | `(params: StepperApi) => ReactElement<any, string \| JSXElementConstructor<any>>` | — | yes | Render function. Принимает `stepper` — JSX-элемент степпера, а также api: `goNext`, `goPrev`, `resetValidation`, `setValidator`, `isCompleted`, `currentStepIndex`, `stepCount`. |
| `className` | `string` | — | no | CSS-класс |
| `data-test-id` | `string` | — | no | data-test-id |
| `defaultCurrentStepIndex` | `number` | `0` | no | Индекс текущего шага по-дефолту |
| `onChangeCurrentStep` | `((newValue: number, prevValue: number) => void)` | — | no | Колбек смены текущего степа |
| `onCompleteChange` | `((isCompleted: boolean) => void)` | — | no | Колбек изменения завершённости |
| `steps` | `StepData[]` | — | yes | Массив шагов |
| `validator` | `StepsValidator` | — | no | Валидатор шагов. Выполняется при смене шага. Принимает первым аргументом индекс текущего, вторым — индекс нового шага. Возвращает Promise<boolean>: false → шаг помечается как Rejected. |

### StepIcon
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `className` | `string` | — | no | CSS-класс |
| `number` | `number` | — | yes | Порядковый номер шага (1-based) |
| `state` | `completed \| current \| loading \| rejected \| waiting` | — | yes | Состояние шага |

### Stepper
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `allowFreeNavigation` | `boolean` | — | no | Позволяет свободно переключаться между разными шагами без валидации |
| `children` | `(params: StepperApi) => ReactElement<any, string \| JSXElementConstructor<any>>` | — | yes | Render function. Принимает `stepper` — JSX-элемент степпера, а также api: `goNext`, `goPrev`, `resetValidation`, `setValidator`, `isCompleted`, `currentStepIndex`, `stepCount`. |
| `className` | `string` | — | no | CSS-класс |
| `data-test-id` | `string` | — | no | data-test-id |
| `defaultCurrentStepIndex` | `number` | — | no | Индекс текущего шага по-дефолту |
| `onChangeCurrentStep` | `((newValue: number, prevValue: number) => void)` | — | no | Колбек смены текущего степа |
| `onCompleteChange` | `((isCompleted: boolean) => void)` | — | no | Колбек изменения завершённости |
| `steps` | `StepData[]` | — | yes | Массив шагов |
| `validator` | `StepsValidator` | — | no | Валидатор шагов. Выполняется при смене шага. Принимает первым аргументом индекс текущего, вторым — индекс нового шага. Возвращает Promise<boolean>: false → шаг помечается как Rejected. |

#### Related types
- `StepData` (interface)
- `StepperApi` (interface)
- `StepsValidator` (alias)

## Примеры

### BasicFlow

```tsx
import { Button } from '@cloud-ru/ds-button';
import { Stepper } from '@cloud-ru/ds-stepper';

export function BasicFlow() {
  return (
    <Stepper steps={[{ title: 'Данные' }, { title: 'Проверка' }, { title: 'Готово' }]}>
      {({ stepper, goNext, goPrev, currentStepIndex, stepCount, isCompleted }) => (
        <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
          {stepper}
          <div style={{ display: 'flex', gap: 8 }}>
            <Button
              label='Назад'
              view='outline'
              appearance='neutral'
              size='s'
              onClick={() => goPrev()}
              disabled={currentStepIndex === 0}
            />
            <Button
              label={currentStepIndex === stepCount - 1 ? 'Завершить' : 'Далее'}
              appearance='primary'
              size='s'
              onClick={() => goNext()}
              disabled={isCompleted}
            />
          </div>
        </div>
      )}
    </Stepper>
  );
}
```

### MobileLayout

```tsx
import { AdaptiveProvider, LAYOUT_TYPE } from '@cloud-ru/ds-adaptive';
import { Button } from '@cloud-ru/ds-button';
import { Stepper } from '@cloud-ru/ds-stepper';

export function MobileLayout() {
  return (
    <AdaptiveProvider layoutType={LAYOUT_TYPE.Mobile}>
      <Stepper steps={[{ title: 'Данные' }, { title: 'Проверка' }, { title: 'Готово' }]}>
        {({ stepper, goNext, goPrev, currentStepIndex, stepCount, isCompleted }) => (
          <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
            {stepper}
            <div style={{ display: 'flex', gap: 8 }}>
              <Button
                label='Назад'
                view='outline'
                appearance='neutral'
                size='s'
                onClick={() => goPrev()}
                disabled={currentStepIndex === 0}
              />
              <Button
                label={currentStepIndex === stepCount - 1 ? 'Завершить' : 'Далее'}
                appearance='primary'
                size='s'
                onClick={() => goNext()}
                disabled={isCompleted}
              />
            </div>
          </div>
        )}
      </Stepper>
    </AdaptiveProvider>
  );
}
```

### WithValidator

```tsx
import { Button } from '@cloud-ru/ds-button';
import { Stepper, StepsValidator } from '@cloud-ru/ds-stepper';
import { useRef } from 'react';

export function WithValidator() {
  const attempts = useRef(0);
  const validator: StepsValidator = async () => {
    attempts.current += 1;
    return attempts.current >= 2;
  };

  return (
    <Stepper steps={[{ title: 'Данные' }, { title: 'Проверка' }, { title: 'Готово' }]} validator={validator}>
      {({ stepper, goNext, resetValidation }) => (
        <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
          {stepper}
          <div style={{ display: 'flex', gap: 8 }}>
            <Button label='Сброс' view='outline' appearance='neutral' size='s' onClick={resetValidation} />
            <Button label='Далее' appearance='primary' size='s' onClick={() => goNext()} />
          </div>
        </div>
      )}
    </Stepper>
  );
}
```