React Utility Kit 🚀

🌍 Язык: English | Русский

📑 Содержание

• Что решает
• Установка
• Принципы архитектуры
• Обзор компонентов
  • 🎬 Компоненты анимации
  • 🤝 Компоненты взаимодействия
  • 🔄 Компоненты итерации
  • 🧭 Компоненты навигации
  • ⚡ Компоненты производительности
  • 🏪 Компоненты управления состоянием
  • 🎨 UI компоненты
  • 🔧 Утилитарные компоненты
• Быстрый старт
• Требования
• Участие в разработке
• Лицензия
• Ссылки

Комплексная библиотека утилитарных React компонентов со строгой поддержкой TypeScript, разработанная для современных React 19 приложений. Создана с акцентом на производительность, типобезопасность и удобство разработки.

🎯 Что решает

React Utility Kit решает распространённые задачи разработки, предоставляя:

• 🔄 Управление состоянием: Лёгкие, типобезопасные решения без глобальных хранилищ
• ⚡ Оптимизация производительности: Ленивая загрузка, мемоизация и эффективные паттерны рендеринга
• 🎨 UI утилиты: Условный рендеринг, анимации и интерактивные компоненты
• 🔧 Инструменты разработчика: Утилиты отладки, внедрение зависимостей и помощники разработки
• 📱 Обработка взаимодействий: Жесты касания, управление фокусом и обработка пользовательского ввода
• 🚀 Современные паттерны: Render props, составные компоненты и код без эффектов

🛠️ Установка

npm install react-utility-kit
# или
yarn add react-utility-kit
# или
pnpm add react-utility-kit

🏗️ Принципы архитектуры

• Слабая связанность, высокая сплочённость: Каждый компонент самодостаточен и сфокусирован
• Код без эффектов: Минимальное использование useEffect для лучшей производительности
• Паттерн Render Props: Гибкая композиция компонентов
• Паттерны слотов: Расширяемая архитектура компонентов
• GRASP паттерны: Принципы объектно-ориентированного проектирования
• Инверсия зависимостей: Гибкая и тестируемая структура кода
• Единственная ответственность: Каждый компонент имеет одну чёткую цель
• Строгая типизация: Полная поддержка TypeScript со строгими типами

📦 Обзор компонентов

🎬 Компоненты анимации

Ticker

Назначение: Операции на основе интервалов с автоматической очисткой и управлением состоянием

• 📖 Документация: English | Русский
• Случаи использования: Таймеры, операции опроса, обновления в реальном времени, анимации
• Ключевые возможности: Управление запуск/остановка/перезапуск, подсчёт тиков, автоматическая очистка

Cycle

Назначение: Циклическое управление состоянием и переходы

• 📖 Документация: English | Русский
• Случаи использования: Навигация карусели, пошаговые мастера, машины состояний
• Ключевые возможности: Навигация вперёд/назад, управление циклом, сохранение состояния

🤝 Компоненты взаимодействия

Focus

Назначение: Продвинутое управление фокусом и навигация с клавиатуры

• 📖 Документация: English | Русский
• Случаи использования: Доступность, навигация с клавиатуры, захват фокуса
• Ключевые возможности: Автофокус, восстановление фокуса, обработка событий клавиатуры

Tap

Назначение: Улучшенные взаимодействия касания и клика

• 📖 Документация: English | Русский
• Случаи использования: Взаимодействия с кнопками, распознавание жестов, обработка касаний
• Ключевые возможности: Обнаружение множественных касаний, распознавание жестов, делегирование событий

GesturePad

Назначение: Продвинутое распознавание и обработка жестов касания

• 📖 Документация: English | Русский
• Случаи использования: Обнаружение свайпов, масштабирование щипком, приложения для рисования
• Ключевые возможности: Поддержка мультитач, распознавание жестов, настраиваемые обработчики

🔄 Компоненты итерации

For

Назначение: Декларативный рендеринг списков с расширенными возможностями

• 📖 Документация: English | Русский
• Случаи использования: Динамические списки, рендеринг данных, отображение коллекций
• Ключевые возможности: Отслеживание индексов, обработка пустого состояния, типобезопасная итерация

Repeat

Назначение: Повторяющийся рендеринг компонентов с логикой на основе счётчика

• 📖 Документация: English | Русский
• Случаи использования: Звёздные рейтинги, точки пагинации, повторяющиеся элементы
• Ключевые возможности: Рендеринг на основе счётчика, доступ к индексу, оптимизация производительности

🧭 Компоненты навигации

MicroRoute

Назначение: Лёгкое решение для клиентской маршрутизации

• 📖 Документация: English | Русский
• Случаи использования: SPA маршрутизация, условная навигация, рендеринг на основе URL
• Ключевые возможности: Сопоставление паттернов, извлечение параметров, обработка 404

⚡ Компоненты производительности

Lazy

Назначение: Ленивая загрузка компонентов и разделение кода

• 📖 Документация: English | Русский
• Случаи использования: Разделение кода, оптимизация производительности, динамические импорты
• Ключевые возможности: Интеграция с Suspense, границы ошибок, стратегии предзагрузки

Static

Назначение: Оптимизация статического контента и мемоизация

• 📖 Документация: English | Русский
• Случаи использования: Тяжёлые вычисления, дорогие рендеры, статический контент
• Ключевые возможности: Автоматическая мемоизация, отслеживание зависимостей, инвалидация кэша

Bound

Назначение: Рендеринг на основе границ и обнаружение области просмотра

• 📖 Документация: English | Русский
• Случаи использования: Бесконечная прокрутка, оптимизация области просмотра, ленивый рендеринг
• Ключевые возможности: Intersection Observer, обнаружение области просмотра, оптимизация производительности

🏪 Компоненты управления состоянием

Atom

Назначение: Лёгкое атомарное управление состоянием

• 📖 Документация: English | Русский
• Случаи использования: Глобальное состояние, общие данные, реактивные обновления
• Ключевые возможности: Типобезопасные атомы, автоматические подписки, минимальный шаблонный код

Toggle

Назначение: Управление булевым состоянием с расширенными возможностями

• 📖 Документация: English | Русский
• Случаи использования: Управление модалами, флаги функций, булевы переключатели
• Ключевые возможности: Действия переключения, сохранение состояния, обработка колбэков

Live

Назначение: Получение данных в реальном времени и живые обновления

• 📖 Документация: English | Русский
• Случаи использования: Дашборды реального времени, живые потоки данных, операции опроса
• Ключевые возможности: Автоматический опрос, обработка ошибок, оптимистичные обновления

Cache

Назначение: Интеллектуальное кэширование и сохранение данных

• 📖 Документация: English | Русский
• Случаи использования: Кэширование ответов API, дорогие вычисления, сохранение данных
• Ключевые возможности: Поддержка TTL, инвалидация кэша, бэкенды хранения

🎨 UI компоненты

Show

Назначение: Условный рендеринг с расширенными возможностями

• 📖 Документация: English | Русский
• Случаи использования: Условный UI, флаги функций, адаптивный дизайн
• Ключевые возможности: Множественные условия, резервный контент, типобезопасные предикаты

Gate

Назначение: Контроль доступа и рендеринг на основе разрешений

• 📖 Документация: English | Русский
• Случаи использования: Разрешения пользователей, доступ к функциям, UI на основе ролей
• Ключевые возможности: Проверка разрешений, валидация ролей, контроль доступа

Lock

Назначение: Блокировка UI и предотвращение взаимодействий

• 📖 Документация: English | Русский
• Случаи использования: Состояния загрузки, отправка форм, асинхронные операции
• Ключевые возможности: Блокировка взаимодействий, визуальная обратная связь, обработка таймаутов

Scroll

Назначение: Продвинутое управление и контроль прокрутки

• 📖 Документация: English | Русский
• Случаи использования: Плавная прокрутка, восстановление позиции прокрутки, анимации на основе прокрутки
• Ключевые возможности: Программная прокрутка, отслеживание позиции прокрутки, плавное поведение

Zoom

Назначение: Функциональность масштабирования и изменения размера

• 📖 Документация: English | Русский
• Случаи использования: Просмотрщики изображений, интерфейсы карт, масштабируемый контент
• Ключевые возможности: Управление масштабом, ограничения масштаба, управление центральной точкой

🔧 Утилитарные компоненты

Debug

Назначение: Инструменты отладки и инспекции для разработки

• 📖 Документация: English | Русский
• Случаи использования: Отладка разработки, инспекция состояния, мониторинг производительности
• Ключевые возможности: Логирование пропсов, отслеживание рендеров, метрики производительности

Compose

Назначение: Композиция компонентов и паттерны высшего порядка

• 📖 Документация: English | Русский
• Случаи использования: Композиция компонентов, HOC паттерны, вложение провайдеров
• Ключевые возможности: Композиция множественных провайдеров, слияние пропсов, типобезопасность

Mirror

Назначение: Зеркалирование и синхронизация компонентов

• 📖 Документация: English | Русский
• Случаи использования: Синхронизация компонентов, зеркалирование состояния, параллельный рендеринг
• Ключевые возможности: Синхронизация состояния, зеркалирование пропсов, двунаправленные обновления

Mapper

Назначение: Утилиты трансформации и маппинга данных

• 📖 Документация: English | Русский
• Случаи использования: Трансформация API ответов, нормализация данных, конвейерная обработка, валидация
• Ключевые возможности: Поддержка TypeScript, валидация Zod, паттерны композиции, оптимизация производительности

Experiment

Назначение: A/B тестирование и экспериментирование с функциями

• 📖 Документация: English | Русский
• Случаи использования: A/B тестирование, флаги функций, экспериментальные возможности
• Ключевые возможности: Выбор вариантов, отслеживание экспериментов, статистический анализ

Dependency

Назначение: Внедрение зависимостей и управление сервисами

• 📖 Документация: English | Русский
• Случаи использования: Внедрение сервисов, управление зависимостями, тестируемая архитектура
• Ключевые возможности: Типобезопасное внедрение, иерархия провайдеров, жизненный цикл сервисов

Resource

Назначение: Управление асинхронными ресурсами с состояниями загрузки

• 📖 Документация: English | Русский
• Случаи использования: Загрузка данных API, асинхронные операции, интеграция с FSD архитектурой
• Ключевые возможности: Состояния загрузки, обработка ошибок, отмена запросов, отслеживание зависимостей

🚀 Быстрый старт

import { Show, For, Ticker, Lazy } from 'react-utility-kit';

function App() {
  return (
    <div>
      {/* Условный рендеринг */}
      <Show when={user.isLoggedIn}>
        <Dashboard />
      </Show>
      
      {/* Рендеринг списка */}
      <For each={items}>
        {(item, index) => <Item key={item.id} data={item} />}
      </For>
      
      {/* Функциональность таймера */}
      <Ticker interval={1000} maxTicks={60}>
        {({ count, isRunning, start, stop }) => (
          <div>
            <span>Таймер: {count}с</span>
            <button onClick={isRunning ? stop : start}>
              {isRunning ? 'Стоп' : 'Старт'}
            </button>
          </div>
        )}
      </Ticker>
      
      {/* Ленивая загрузка */}
      <Lazy loader={() => import('./HeavyComponent')}>
        <div>Загрузка...</div>
      </Lazy>
    </div>
  );
}

📋 Требования

• React: ^19.1.1
• TypeScript: ^5.0.0 (рекомендуется)
• Node.js: ^18.0.0

🤝 Участие в разработке

Мы приветствуем вклад в развитие! Пожалуйста, ознакомьтесь с нашим Руководством по участию для получения подробностей.

📄 Лицензия

MIT License - см. файл LICENSE для подробностей.

🔗 Ссылки

• 📦 NPM пакет: react-utility-kit
• 📚 Документация: GitHub репозиторий
• 🐛 Проблемы: GitHub Issues
• 💬 Обсуждения: GitHub Discussions

Сделано с ❤️ Павлом Мельником