# Компоненты

## Матрица «задача → компонент»

| Задача | Рекомендуемый компонент | Не использовать |
|--------|------------------------|-----------------|
| Отображение текста | Text, Heading | MUI Typography напрямую |
| Ссылка | Link | MUI Link напрямую |
| Действие | Button, IconButton | MUI Button напрямую |
| Ввод текста | TextField | MUI TextField напрямую |
| Выбор из списка | Select | MUI Select напрямую |
| Выбор опции | Checkbox | MUI Checkbox напрямую |
| Контейнер/фон | Surface | MUI Paper напрямую |
| Карточка | Card | MUI Card напрямую |
| Ярлык/тег | Chip | MUI Chip напрямую |
| Бейдж | Badge | MUI Badge напрямую |
| Уведомление | Alert | MUI Alert напрямую |
| Модальное окно | Dialog | MUI Dialog напрямую |
| Загрузка скелета | Skeleton | MUI Skeleton напрямую |
| Индикатор прогресса | Progress | MUI CircularProgress / LinearProgress напрямую |
| Финансовое значение | Money, Metric, PriceChange | сырое число |
| Таблица | DataTable | MUI Table напрямую |
| Поле формы | FormField | ручная связка label + helperText |
| Панель фильтров | FilterBar | ручная вёрстка фильтров |
| Пустое состояние | EmptyState | ручная вёрстка |
| Ошибка | ErrorState | ручная вёрстка |
| Загрузка | LoadingState | ручная вёрстка |

## Каталог компонентов

### Text

Отображение текста с заданным семантическим размером.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'body1' \| 'body2' \| 'caption' \| 'overline'` | `'body1'` |
| `color` | `'primary' \| 'secondary' \| 'disabled' \| 'inverse'` | `'primary'` |

### Heading

Заголовок.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h3'` |

### Link

Ссылка. Под капотом MUI Link с цветом `color.action.primary`.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `href` | `string` | — |
| `underline` | `'none' \| 'hover' \| 'always'` | `'hover'` |

### Button

Кнопка действия. Обёртка MUI Button.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'primary' \| 'secondary' \| 'danger'` | `'primary'` |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
| `loading` | `boolean` | `false` |

### IconButton

Кнопка-иконка. **Требует `label`** (aria-label).

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `label` | `string` | — |
| `size` | `'sm' \| 'md'` | `'md'` |

### TextField

Текстовое поле ввода.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `size` | `'sm' \| 'md'` | `'md'` |
| `fullWidth` | `boolean` | `true` |

### Select

Выпадающий список.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `size` | `'sm' \| 'md'` | `'md'` |
| `fullWidth` | `boolean` | `true` |

### Checkbox

Чекбокс.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `label` | `string` | — |

### Surface

Базовый контейнер с фоном и скруглением.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'default' \| 'subtle' \| 'raised'` | `'default'` |

### Card

Карточка. Поверхность с тенью.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `padding` | `'sm' \| 'md' \| 'lg'` | `'md'` |

### Chip

Компактный элемент для отображения тега или статуса.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'filled' \| 'outlined'` | `'filled'` |
| `color` | `'default' \| 'info' \| 'success' \| 'warning' \| 'error'` | `'default'` |

### Badge

Бейдж с числовым или текстовым значением.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'dot' \| 'standard'` | `'standard'` |
| `color` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |

### Alert

Уведомление. Использует `role="alert"`.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `severity` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |
| `title` | `string` | — |

### Dialog

Модальное окно. **Требует `title`**, содержит focus trap, закрывается по Escape.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `open` | `boolean` | — |
| `title` | `string` | — |
| `onClose` | `() => void` | — |

### Skeleton

Скелетон загрузки. `aria-hidden` по умолчанию.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `width` | `string \| number` | `'100%'` |
| `height` | `string \| number` | `20` |

### Progress

Индикатор прогресса. Поддерживает indeterminate-режим с `aria-busy`.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `variant` | `'determinate' \| 'indeterminate'` | `'indeterminate'` |
| `value` | `number` (0–100) | `0` |

### DataTable

Таблица данных на основе TanStack Table.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `columns` | `ColumnDef<T>[]` | — |
| `data` | `T[]` | — |
| `caption` | `string` | — |
| `density` | `'balanced' \| 'compact'` | `'balanced'` |

### Money

Финансовое значение с форматированием через `Intl.NumberFormat`.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `value` | `number` | — |
| `currency` | `string` | `'RUB'` |
| `locale` | `string` | `'ru-RU'` |

### Metric

Метрика: лейбл + значение + опционально supporting/trend.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `label` | `string` | — |
| `value` | `ReactNode` | — |
| `supporting` | `ReactNode` | — |
| `trend` | `'up' \| 'down' \| 'neutral'` | — |

### PriceChange

Изменение цены. Использует **текстовое направление** (не только цвет).

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `value` | `number` | — |
| `percent` | `number` | — |
| `variant` | `'absolute' \| 'percent' \| 'both'` | `'both'` |

### FormField

Обёртка для поля формы: label + helperText + error.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `label` | `string` | — |
| `error` | `string` | — |
| `helperText` | `string` | — |

### FilterBar

Панель фильтров с responsive-обёрткой.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `children` | `ReactNode` | — |

### EmptyState

Пустое состояние. **Требует `title`**.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `title` | `string` | — |
| `description` | `string` | — |
| `action` | `ReactNode` | — |

### ErrorState

Состояние ошибки. **Требует `title`**.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `title` | `string` | — |
| `description` | `string` | — |
| `onRetry` | `() => void` | — |

### LoadingState

Состояние загрузки. `aria-live="polite"`.

| Свойство | Тип | По умолчанию |
|----------|-----|--------------|
| `title` | `string` | — |