From 1c81deaed0bde3f3eeefa461b01e4e79e9b649c7 Mon Sep 17 00:00:00 2001 From: Ilia Mashkov Date: Sun, 23 Nov 2025 14:47:07 +0300 Subject: [PATCH] =?UTF-8?q?feat:=20=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=20=D1=84=D0=B0=D0=B9=D0=BB=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 231 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6650a26 --- /dev/null +++ b/README.md @@ -0,0 +1,231 @@ +# Only Task - Интерактивная временная шкала + +Современное React-приложение с интерактивной круговой временной шкалой и каруселью исторических событий. + +## 🚀 Технологии + +- **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 +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 + +## 👨‍💻 Разработка + +Для разработки рекомендуется: +1. Запустить `pnpm dev` для dev-сервера +2. Использовать `pnpm storybook` для разработки компонентов в изоляции +3. Писать тесты для новых компонентов +4. Следовать существующей структуре проекта + +--- + +**Приятной разработки! 🚀**