README.md

---

[🌐 English](#english) | [🇷🇺 Русский](#russian)

---

![Demo](assets/gsap-carousel.gif)

---

# Only Task

A React-based UI component developed to explore advanced animation patterns using GSAP. This project focuses on synchronizing complex circular transitions with a dynamic content carousel.

## Technical Highlights

- **GSAP Integration**: Implementation of smooth, high-performance animations for state transitions
- **Circular Data Visualization**: An interactive timeline with selectable time periods
- **Adaptive Layout**: Fully responsive architecture supporting mobile, tablet, and desktop viewports
- **Custom Navigation**: Bespoke UI controls for seamless event browsing

## 🚀 Technologies

- **React 19** - User interface library
- **TypeScript 5** - Typed JavaScript
- **GSAP** - Smooth animation library
- **Swiper** - Modern carousel library
- **Webpack 5** - Module bundler
- **SCSS** - CSS preprocessor with modules
- **Jest** - Testing framework
- **ESLint + Prettier** - Code linting and formatting

## 📋 Requirements

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

## 🛠️ Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd gsap-carousel
```

2. Install dependencies:

```bash
pnpm install
```

## 🎯 Available Commands

### Development

```bash
# Start dev-server on port 3000
pnpm dev
```

The application will be available at: http://localhost:3000

### Build

```bash
# Production build
pnpm build:prod

# Development build
pnpm build:dev
```

The build result will be in the `dist/` folder

### Testing

```bash
# Run all unit tests
pnpm test:unit

# Check TypeScript types
pnpm type-check
```

### Linting

```bash
# Check JavaScript/TypeScript code
pnpm lint

# Auto-fix errors
pnpm lint --fix

# Check styles (SCSS)
pnpm lint:styles

# Auto-fix styles
pnpm lint:styles --fix
```

### Storybook

```bash
# Run Storybook for component development
pnpm storybook

# Build static version of Storybook
pnpm build-storybook
```

### Pre-push Checks

```bash
# Run all checks before push
pnpm pre-push
```

This command runs:

- ✅ TypeScript type checking
- ✅ Code linting
- ✅ Style linting
- ✅ Unit tests
- ✅ Production build

## 📁 Project Structure

```
gsap-carousel/
├── config/              # Build configuration
│   ├── build/          # Webpack configuration
│   ├── jest/           # Jest configuration
│   └── storybook/      # Storybook configuration
├── dist/               # Production build (generated)
├── src/                # Source code
│   ├── app/           # Root application component
│   ├── entities/      # Business entities (data types)
│   ├── shared/        # Reusable components and utilities
│   │   ├── assets/   # Static resources (SVG, images)
│   │   └── ui/       # UI components (Button, Card)
│   └── widgets/       # Complex components (TimeFrameSlider)
├── .husky/            # Git hooks
├── package.json       # Dependencies and scripts
└── tsconfig.json      # TypeScript configuration
```

## 🎨 Main Components

### TimeFrameSlider

The main application widget combining a circular timeline and an events carousel.

**Features:**

- Interactive circular chart with periods
- Smooth GSAP animations during transitions
- Responsive design for mobile, tablet, and desktop
- Custom navigation

### CircleTimeline

A circular timeline with period points.

**Features:**

- Auto-rotation to the active period
- Click on points to switch periods
- Period title animations

### EventsCarousel

Historical events carousel using Swiper.

**Features:**

- Adaptive number of slides
- Custom navigation
- Smooth appearance/disappearance animation

## ⚡ Performance Optimization

The project is optimized for production:

- ✅ **Code splitting** - chunk separation (vendors, runtime, main)
- ✅ **Tree shaking** - removal of unused code
- ✅ **Gzip compression** - file compression (~68% size reduction)
- ✅ **Minification** - JS and CSS minification
- ✅ **CSS Modules** - isolated component styles
- ✅ **Babel caching** - caching for fast rebuilds

**Bundle size:**

- Uncompressed: ~371 KiB
- Gzipped: ~117 KiB

## 🧪 Testing

The project is covered by unit tests:

- ✅ Component tests (Button, Card, CircleTimeline, TimeFrameSlider, EventsCarousel)
- ✅ Utility tests (calculateCoordinates)
- ✅ Mocks for GSAP and Swiper
- ✅ 39 tests, 100% successful

## 📱 Responsiveness

The application is adapted for all devices:

- **Desktop** (>1440px) - Full version with circular chart
- **Tablet** (768px - 1024px) - Optimized version
- **Mobile** (<768px) - Simplified version with bottom navigation

## 🔧 Configuration

### Webpack

- Babel for transpilation (faster than ts-loader)
- CSS Modules for style isolation
- SVGR for importing SVG as React components
- Hot Module Replacement for development
- Bundle Analyzer for size analysis

### TypeScript

- Strict mode enabled
- Path aliases (`@/*` → `src/*`)
- Type checking separate from build

### ESLint

- Rules for React, TypeScript, Jest
- Prettier integration
- Import sorting

## 🤝 Git Hooks

Pre-push hook automatically runs:

1. Type checking
2. ESLint
3. Stylelint
4. Unit tests
5. Production build

This ensures that only working code enters the repository.

## 📝 License

ISC

---

<a id="english"></a>

---

[🌍 Scroll to top](#) | [🇷🇺 Русский](#russian)

---

# Only Task

React-based UI component developed to explore advanced animation patterns using GSAP. This project focuses on synchronizing complex circular transitions with a dynamic content carousel.

## Technical Highlights

- **GSAP Integration**: Implementation of smooth, high-performance animations for state transitions
- **Circular Data Visualization**: An interactive timeline with selectable time periods
- **Adaptive Layout**: Fully responsive architecture supporting mobile, tablet, and desktop viewports
- **Custom Navigation**: Bespoke UI controls for seamless event browsing

## 🚀 Technologies

- **React 19** - User interface library
- **TypeScript 5** - Typed JavaScript
- **GSAP** - Smooth animation library
- **Swiper** - Modern carousel library
- **Webpack 5** - Module bundler
- **SCSS** - CSS preprocessor with modules
- **Jest** - Testing framework
- **ESLint + Prettier** - Code linting and formatting

## 📋 Requirements

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

## 🛠️ Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd gsap-carousel
```

2. Install dependencies:

```bash
pnpm install
```

## 🎯 Available Commands

### Development

```bash
# Start dev-server on port 3000
pnpm dev
```

The application will be available at: http://localhost:3000

### Build

```bash
# Production build
pnpm build:prod

# Development build
pnpm build:dev
```

The build result will be in the `dist/` folder

### Testing

```bash
# Run all unit tests
pnpm test:unit

# Check TypeScript types
pnpm type-check
```

### Linting

```bash
# Check JavaScript/TypeScript code
pnpm lint

# Auto-fix errors
pnpm lint --fix

# Check styles (SCSS)
pnpm lint:styles

# Auto-fix styles
pnpm lint:styles --fix
```

### Storybook

```bash
# Run Storybook for component development
pnpm storybook

# Build static version of Storybook
pnpm build-storybook
```

### Pre-push Checks

```bash
# Run all checks before push
pnpm pre-push
```

This command runs:

- ✅ TypeScript type checking
- ✅ Code linting
- ✅ Style linting
- ✅ Unit tests
- ✅ Production build

## 📁 Project Structure

```
gsap-carousel/
├── config/              # Build configuration
│   ├── build/          # Webpack configuration
│   ├── jest/           # Jest configuration
│   └── storybook/      # Storybook configuration
├── dist/               # Production build (generated)
├── src/                # Source code
│   ├── app/           # Root application component
│   ├── entities/      # Business entities (data types)
│   ├── shared/        # Reusable components and utilities
│   │   ├── assets/   # Static resources (SVG, images)
│   │   └── ui/       # UI components (Button, Card)
│   └── widgets/       # Complex components (TimeFrameSlider)
├── .husky/            # Git hooks
├── package.json       # Dependencies and scripts
└── tsconfig.json      # TypeScript configuration
```

## 🎨 Main Components

### TimeFrameSlider

The main application widget combining a circular timeline and an events carousel.

**Features:**

- Interactive circular chart with periods
- Smooth GSAP animations during transitions
- Responsive design for mobile, tablet, and desktop
- Custom navigation

### CircleTimeline

A circular timeline with period points.

**Features:**

- Auto-rotation to the active period
- Click on points to switch periods
- Period title animations

### EventsCarousel

Historical events carousel using Swiper.

**Features:**

- Adaptive number of slides
- Custom navigation
- Smooth appearance/disappearance animation

## ⚡ Performance Optimization

The project is optimized for production:

- ✅ **Code splitting** - chunk separation (vendors, runtime, main)
- ✅ **Tree shaking** - removal of unused code
- ✅ **Gzip compression** - file compression (~68% size reduction)
- ✅ **Minification** - JS and CSS minification
- ✅ **CSS Modules** - isolated component styles
- ✅ **Babel caching** - caching for fast rebuilds

**Bundle size:**

- Uncompressed: ~371 KiB
- Gzipped: ~117 KiB

## 🧪 Testing

The project is covered by unit tests:

- ✅ Component tests (Button, Card, CircleTimeline, TimeFrameSlider, EventsCarousel)
- ✅ Utility tests (calculateCoordinates)
- ✅ Mocks for GSAP and Swiper
- ✅ 39 tests, 100% successful

## 📱 Responsiveness

The application is adapted for all devices:

- **Desktop** (>1440px) - Full version with circular chart
- **Tablet** (768px - 1024px) - Optimized version
- **Mobile** (<768px) - Simplified version with bottom navigation

## 🔧 Configuration

### Webpack

- Babel for transpilation (faster than ts-loader)
- CSS Modules for style isolation
- SVGR for importing SVG as React components
- Hot Module Replacement for development
- Bundle Analyzer for size analysis

### TypeScript

- Strict mode enabled
- Path aliases (`@/*` → `src/*`)
- Type checking separate from build

### ESLint

- Rules for React, TypeScript, Jest
- Prettier integration
- Import sorting

## 🤝 Git Hooks

Pre-push hook automatically runs:

1. Type checking
2. ESLint
3. Stylelint
4. Unit tests
5. Production build

This ensures that only working code enters the repository.

## 📝 License

ISC

**Happy coding! 🚀**

---

<a id="russian"></a>

---

[🌍 Scroll to top](#) | [🌐 English](#english)

---

# Only Task

React-компонент UI для изучения продвинутых паттернов анимации с использованием GSAP. Проект фокусируется на синхронизации сложных круговых переходов с динамической каруселью контента.

## Технические особенности

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

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

- **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 gsap-carousel
```

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 сборку

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

```
gsap-carousel/
├── 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

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