templates/vitekit-claude/README.md

ViteKit Universal

Современный универсальный сборщик проектов с Vite + Twig + компонентами для быстрой разработки веб-приложений.

🚀 Особенности

• Быстрая сборка с Vite
• Шаблонизация с Twig
• Готовые UI компоненты (модалы, табы, аккордеон, уведомления)
• Адаптивная верстка с SCSS и Flexbox/Grid
• Оптимизация изображений и SVG спрайты
• Качество кода с ESLint, Prettier, Stylelint
• Модульная архитектура

📦 Установка и запуск

# Установка зависимостей
npm install

# Запуск сервера разработки
npm run dev

# Сборка для продакшена
npm run build

# Предварительный просмотр сборки
npm run preview

🏗️ Структура проекта

src/
├── components/         # UI компоненты
│   ├── ui/            # Базовые компоненты
│   └── blocks/        # Блоки страниц
├── layouts/           # Шаблоны страниц
├── pages/             # Страницы Twig
├── data/              # JSON данные для Twig
├── assets/            # Статические ресурсы
│   ├── images/        # Изображения
│   ├── icons/         # SVG иконки для спрайтов
│   └── fonts/         # Шрифты
├── styles/            # SCSS стили
│   ├── abstracts/     # Переменные, миксины
│   ├── base/          # Сброс стилей, типографика
│   ├── components/    # Стили компонентов
│   ├── layout/        # Стили макета
│   └── pages/         # Стили страниц
└── scripts/           # JavaScript
    ├── components/    # JS компоненты
    └── utils/         # Утилиты

🎯 Компоненты

Toast Уведомления ✨

• Исправлены стили позиционирования - правильный z-index и анимации
• Автоматическое скрытие через настраиваемое время
• Адаптивность для мобильных устройств
• Типизация: success, error, warning, info

ToastComponent.success('Операция успешна!', { 
  title: 'Готово!', 
  duration: 4000 
});

Модальные окна (MicroModal)

• Доступные модальные окна с ARIA
• Анимации открытия/закрытия
• Поддержка клавиатуры и фокуса

<button data-micromodal-trigger="modal-id">Открыть модал</button>

Табы (Адаптивные)

• Автоматическое превращение в аккордеон на мобильных
• Клавиатурная навигация (Arrow keys, Home, End)
• Плавные анимации переключения

<div class="tabs" data-tabs>
  <div class="tabs__nav">
    <button class="tabs__tab tabs__tab--active">Вкладка 1</button>
  </div>
  <div class="tabs__content">
    <div class="tabs__panel tabs__panel--active">Содержимое</div>
  </div>
</div>

Аккордеон

• Плавные CSS анимации с автоматическим расчетом высоты
• Поддержка множественного раскрытия
• Полная клавиатурная навигация и ARIA

<div class="accordion" data-accordion>
  <div class="accordion__item">
    <button class="accordion__header">Заголовок</button>
    <div class="accordion__content">Содержимое</div>
  </div>
</div>

🎨 SCSS Утилиты

Миксины для медиа-запросов

@include media-up('md') { /* >= 768px */ }
@include media-down('lg') { /* < 992px */ }
@include media-only('sm') { /* только для small */ }

Flexbox утилиты

@include flex-center;        // выравнивание по центру
@include flex-between;       // space-between
@include flex-column;        // flex-direction: column

Grid утилиты

@include grid-container(12, $spacing-base);  // 12 колонок
@include grid-column(6);                     // span 6 колонок

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

Vite

Настроен для работы с:

• Twig шаблонами
• SCSS с автоимпортом переменных
• Оптимизацией изображений
• SVG спрайтами
• Legacy поддержкой для старых браузеров

Linting

• ESLint для JavaScript
• Stylelint для SCSS
• Prettier для форматирования
• Husky для pre-commit хуков

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

Проект использует mobile-first подход с брейкпоинтами:

• sm: 576px
• md: 768px
• lg: 992px
• xl: 1200px
• 2xl: 1400px

🏗️ Page Controller Архитектура

ViteKit использует Page Controller Pattern для организации кода по страницам:

Автоматическая загрузка

// Файл: src/scripts/pages/about.js
// Загружается автоматически для about.html

export default class AboutPage extends Component {
  constructor() {
    super(document.body);
  }

  beforeInit() {
    // Логика до инициализации
  }

  bindEvents() {
    // События страницы
    this.addEventListener('click', this.handleClick);
  }

  afterInit() {
    // Логика после инициализации
  }
}

EventBus для связи компонентов

import { eventBus } from '../core/EventBus.js';

// Подписка на события
eventBus.on('user:login', this.onUserLogin.bind(this));

// Испускание событий
eventBus.emit('page:ready', { page: 'home' });

Утилиты производительности

import { debounce, throttle, memoize } from '@scripts/utils/performance.js';

// Debounce для поиска
const search = debounce(this.performSearch.bind(this), 300);

// Throttle для скролла
const onScroll = throttle(this.updateScrollPosition.bind(this), 16);

// Мемоизация тяжелых вычислений
const expensiveCalculation = memoize(this.calculate.bind(this));

🎛️ API компонентов

TabsComponent

const tabs = new TabsComponent(element, {
  activeClass: 'tabs__tab--active',
  keyboardNavigation: true,
  autoResponsive: true
});

tabs.next();      // следующая вкладка
tabs.prev();      // предыдущая вкладка
tabs.goTo(2);     // перейти к вкладке по индексу

AccordionComponent

const accordion = new AccordionComponent(element, {
  allowMultiple: false,
  animationDuration: 300,
  keyboardNavigation: true
});

accordion.open(0);     // открыть первый элемент
accordion.close(0);    // закрыть первый элемент
accordion.closeAll();  // закрыть все элементы

ToastComponent

// Базовые методы
ToastComponent.success('Успех!');
ToastComponent.error('Ошибка!');
ToastComponent.warning('Предупреждение!');
ToastComponent.info('Информация');

// Расширенные возможности
ToastComponent.promise(fetchData(), {
  loading: 'Загрузка...',
  success: 'Данные загружены!',
  error: 'Ошибка загрузки'
});

ToastComponent.confirm('Удалить элемент?').then(confirmed => {
  if (confirmed) {
    // Действие подтверждено
  }
});

🚀 Развертывание

# Сборка для продакшена
npm run build

# Файлы сборки будут в папке dist/

🤝 Вклад в проект

1. Fork проект
2. Создайте feature ветку
3. Commit изменения
4. Push в ветку
5. Создайте Pull Request

📝 Лицензия

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

🛠️ Технологии

• Vite - Сборщик
• Twig - Шаблонизатор
• SCSS - CSS препроцессор
• MicroModal - Модальные окна
• Toastify - Уведомления
• ESLint - Линтер JavaScript
• Prettier - Форматирование кода