gsap-carousel/README.md

# Only Task 

Тестовое задание для only.digital

## 🚀 Технологии

- **React 19** - библиотека для создания пользовательских интерфейсов
- **TypeScript 5** - типизированный JavaScript
- **GSAP** - библиотека для плавных анимаций
- **Swiper** - современная библиотека для каруселей
- **Webpack 5** - сборщик модулей
- **SCSS** - препроцессор CSS с модулями
- **Jest** - фреймворк для тестирования
- **ESLint + Prettier** - линтинг и форматирование кода

## 📋 Требования

- **Node.js** >= 18.0.0
- **pnpm** >= 8.0.0

## 🛠️ Установка

1. Клонируйте репозиторий:
```bash
git clone <repository-url>
cd only-task
```

2. Установите зависимости:
```bash
pnpm install
```

## 🎯 Доступные команды

### Разработка

```bash
# Запуск dev-сервера на порту 3000
pnpm dev
```

Приложение будет доступно по адресу: http://localhost:3000

### Сборка

```bash
# Production сборка
pnpm build:prod

# Development сборка
pnpm build:dev
```

Результат сборки будет в папке `dist/`

### Тестирование

```bash
# Запуск всех unit-тестов
pnpm test:unit

# Проверка типов TypeScript
pnpm type-check
```

### Линтинг

```bash
# Проверка JavaScript/TypeScript кода
pnpm lint

# Автоматическое исправление ошибок
pnpm lint --fix

# Проверка стилей (SCSS)
pnpm lint:styles

# Автоматическое исправление стилей
pnpm lint:styles --fix
```

### Storybook

```bash
# Запуск Storybook для разработки компонентов
pnpm storybook

# Сборка статической версии Storybook
pnpm build-storybook
```

### Pre-push проверки

```bash
# Запуск всех проверок перед push
pnpm pre-push
```

Эта команда выполняет:
- ✅ Проверку типов TypeScript
- ✅ Линтинг кода
- ✅ Линтинг стилей
- ✅ Запуск unit-тестов
- ✅ Production сборку

## 📁 Структура проекта

```
only-task/
├── config/              # Конфигурация сборки
│   ├── build/          # Webpack конфигурация
│   ├── jest/           # Jest конфигурация
│   └── storybook/      # Storybook конфигурация
├── dist/               # Production сборка (генерируется)
├── src/                # Исходный код
│   ├── app/           # Корневой компонент приложения
│   ├── entities/      # Бизнес-сущности (типы данных)
│   ├── shared/        # Переиспользуемые компоненты и утилиты
│   │   ├── assets/   # Статические ресурсы (SVG, изображения)
│   │   └── ui/       # UI компоненты (Button, Card)
│   └── widgets/       # Сложные компоненты (TimeFrameSlider)
├── .husky/            # Git hooks
├── package.json       # Зависимости и скрипты
└── tsconfig.json      # Конфигурация TypeScript
```

## 🎨 Основные компоненты

### TimeFrameSlider
Главный виджет приложения, объединяющий круговую временную шкалу и карусель событий.

**Особенности:**
- Интерактивная круговая диаграмма с периодами
- Плавные GSAP анимации при переключении
- Адаптивный дизайн для мобильных, планшетов и десктопа
- Кастомная навигация

### CircleTimeline
Круговая временная шкала с точками периодов.

**Особенности:**
- Автоматический поворот к активному периоду
- Клик по точкам для переключения
- Анимация заголовков периодов

### EventsCarousel
Карусель исторических событий с использованием Swiper.

**Особенности:**
- Адаптивное количество слайдов
- Кастомная навигация
- Плавная анимация появления/исчезновения

## ⚡ Оптимизация производительности

Проект оптимизирован для production:

- ✅ **Code splitting** - разделение на chunks (vendors, runtime, main)
- ✅ **Tree shaking** - удаление неиспользуемого кода
- ✅ **Gzip compression** - сжатие файлов (~68% уменьшение размера)
- ✅ **Minification** - минификация JS и CSS
- ✅ **CSS Modules** - изолированные стили компонентов
- ✅ **Babel caching** - кеширование для быстрой пересборки

**Размер бандла:**
- Uncompressed: ~371 KiB
- Gzipped: ~117 KiB

## 🧪 Тестирование

Проект покрыт unit-тестами:

- ✅ Тесты компонентов (Button, Card, CircleTimeline, TimeFrameSlider, EventsCarousel)
- ✅ Тесты утилит (calculateCoordinates)
- ✅ Моки для GSAP и Swiper
- ✅ 39 тестов, 100% успешных

## 📱 Адаптивность

Приложение адаптировано для всех устройств:

- **Desktop** (>1440px) - полная версия с круговой диаграммой
- **Tablet** (768px - 1024px) - оптимизированная версия
- **Mobile** (<768px) - упрощенная версия с навигацией внизу

## 🔧 Конфигурация

### Webpack
- Babel для транспиляции (быстрее ts-loader)
- CSS Modules для изоляции стилей
- SVGR для импорта SVG как React компонентов
- Hot Module Replacement для разработки
- Bundle Analyzer для анализа размера

### TypeScript
- Strict mode включен
- Path aliases (`@/*` → `src/*`)
- Проверка типов отдельно от сборки

### ESLint
- Правила для React, TypeScript, Jest
- Prettier интеграция
- Import sorting

## 🤝 Git Hooks

Pre-push hook автоматически запускает:
1. Type checking
2. ESLint
3. Stylelint
4. Unit tests
5. Production build

Это гарантирует, что в репозиторий попадает только рабочий код.

## 📝 Лицензия

ISC

**Приятной разработки! 🚀**