Структура файлов библиотеки

Библиотека Driver.js организована так, чтобы обеспечивать простую интеграцию и масштабируемость при использовании в веб-проектах. Основные компоненты распределены по логическим модулям, что позволяет подключать только необходимые части и упрощает поддержку.

Основные директории и файлы

1. dist/ Содержит готовые для использования сборки библиотеки:

   • driver.js – основная не минифицированная версия библиотеки для разработки и отладки.
   • driver.min.js – минифицированная версия, оптимизированная для продакшн-сборок.
   • driver.css – базовые стили для отображения подсветок и тултипов.

   Этот каталог используется при подключении библиотеки через <script> и <link> без сборщиков типа Webpack или Vite.

2. src/ Исходный код библиотеки на ES6, разделённый на модули:

   • Driver.js – главный модуль, реализующий логику шагов и навигации.
   • Step.js – модуль, отвечающий за отдельный шаг турa: хранение целевого элемента, заголовка, описания и настроек позиции тултипа.
   • Utils.js – вспомогательные функции для вычислений положения элементов, проверок видимости и управления DOM.
   • Template.js – шаблоны HTML и CSS для тултипов и оверлеев, которые потом вставляются динамически.

   Использование модулей позволяет легко расширять библиотеку и подключать кастомные шаги без вмешательства в основной код.

3. types/ Содержит определения типов для TypeScript:

   • index.d.ts – описание всех публичных методов, опций и интерфейсов, включая DriverOptions и StepOptions. Наличие этих типов упрощает автодополнение в IDE и обеспечивает строгую типизацию при использовании библиотеки в TypeScript-проектах.

4. examples/ Примеры использования библиотеки:

   • Простейшие пошаговые туры по странице.
   • Интерактивные демонстрации с кастомной анимацией тултипов.
   • Настройки, изменяющие поведение оверлея и навигационных кнопок.

   Примеры включают HTML, JS и CSS, что позволяет быстро понять принцип работы без изучения исходного кода.

5. package.json Определяет зависимости, скрипты сборки и метаданные пакета:

   • Скрипты сборки: build, watch, lint.
   • Основная точка входа: "main": "dist/driver.js" для CommonJS и "module": "dist/driver.esm.js" для ESM.
   • Подключение внешних зависимостей минимально, что обеспечивает лёгкость библиотеки.

6. README.md и документация Содержат базовое описание установки, настройки и использования. Обычно включают инструкции по инициализации объекта Driver, настройке шагов и кастомизации стилей.

Взаимодействие модулей

Driver.js построен на объектно-ориентированной архитектуре:

• Driver создаёт экземпляр тура и управляет переходом между шагами.
• Step инкапсулирует данные для отдельного шага: целевой элемент (element), текст (description), заголовок (title) и позицию тултипа (position).
• Utils выполняет вычисления позиции тултипа относительно целевого элемента и окна браузера, проверяет видимость и адаптирует оверлей под размеры экрана.
• Template формирует HTML-разметку и применяет CSS-классы для тултипов, кнопок навигации и затемнённого фона.

Все модули связаны через импорты и экспортируются как единый объект для конечного использования, что делает библиотеку гибкой и расширяемой.

Конфигурационные файлы сборки

1. rollup.config.js Определяет правила сборки:

   • Форматы экспорта (cjs, esm, iife).
   • Минификация кода для продакшн-сборок.
   • Интеграция с PostCSS для обработки стилей.

2. .babelrc или babel.config.js Настройки транспиляции ES6+ кода в совместимый с браузерами стандарт ES5. Используется для обеспечения кроссбраузерности, особенно в старых версиях Internet Explorer и Safari.

Структура стилей

Файл driver.css содержит:

• Стили оверлея (.driver-overlay) с прозрачностью и плавной анимацией.
• Стили тултипа (.driver-tooltip) с позиционированием и стрелками, указывающими на целевой элемент.
• Стили навигационных кнопок (Next, Previous, Close).
• Адаптивные медиа-запросы для корректного отображения на мобильных устройствах.

Для кастомизации допустимо подключать собственные CSS-файлы и переопределять классы по необходимости.

Итоговая логика работы

• Инициализация: создаётся экземпляр Driver с набором шагов (steps) и глобальными опциями (opacity, padding, allowClose).
• Навигация: Driver управляет переходами между шагами, используя внутренние методы moveNext(), movePrevious() и reset().
• Отрисовка: каждый шаг создаёт тултип и оверлей на основе шаблонов, позиционирует их с помощью утилит и отображает анимацию.
• Завершение: тур может быть закрыт в любой момент через кнопку закрытия или программно методом reset().

Структура файлов Driver.js спроектирована с прицелом на модульность, лёгкую интеграцию и расширяемость, обеспечивая разработчикам полный контроль над поведением интерактивных туров.