Tvist

Слайдер с широким API для современного веба

📦 Установка

npm install tvist

Скачать для браузера (без npm)

Минифицированная сборка для подключения через <script> лежит в папке browser-build/ в репозитории (после npm run build:browser). В браузере глобальная переменная — TvistV1 (версионированное имя, чтобы на одной странице можно было использовать несколько версий Tvist без конфликтов).

• JS: tvist.min.js · jsDelivr CDN
• CSS: tvist.css · jsDelivr CDN

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/VladimirIvanin/tvist@main/browser-build/tvist.css">
<script src="https://cdn.jsdelivr.net/gh/VladimirIvanin/tvist@main/browser-build/tvist.min.js"></script>
<script>
  const slider = new TvistV1('#slider', { perPage: 1, drag: true });
</script>

✨ Возможности

• 📖 Широкое API — десятки опций, методы, события и подключаемые модули под полный контроль
• 🖱️ Drag & Drop — touch/mouse с rubberband эффектом, free mode с momentum scroll
• 🎨 Navigation — стрелки с disabled состояниями
• 📊 Pagination — bullets, fraction, progress
• ⏰ Autoplay — с паузами и остановками
• 📱 Responsive — container-first: размеры и perPage от контейнера, breakpoints по окну или контейнеру
• 🔄 Loop — бесконечная прокрутка
• 🖼️ LazyLoad — ленивая загрузка изображений
• ✨ Effects — fade, cube эффекты переходов
• 🔗 Thumbs — связь основного слайдера с миниатюрами
• 📐 Grid — сеточная раскладка слайдов
• 🎬 Marquee — режим бегущей строки
• 📜 Scrollbar — кастомный скроллбар для навигации
• 0️⃣ Zero deps — нет внешних зависимостей

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

Разметка:

<div id="slider" class="tvist-v1">
  <div class="tvist-v1__container">
    <div class="tvist-v1__slide">Слайд 1</div>
    <div class="tvist-v1__slide">Слайд 2</div>
    <div class="tvist-v1__slide">Слайд 3</div>
  </div>
</div>

Подключение и инициализация:

import Tvist from 'tvist';
import 'tvist/dist/tvist.css';

const slider = new Tvist('#slider', {
  perPage: 3,
  gap: 20,
  drag: true,
  arrows: true,
  pagination: { type: 'bullets' },
  autoplay: 3000,
  breakpoints: {
    768: { perPage: 2 },
    480: { perPage: 1 }
  }
});

📖 Документация

🌐 Онлайн документация

Интерактивные примеры и документация доступны на GitHub Pages:

https://vladimirivanin.github.io/tvist/

📚 Примеры

• Все примеры - интерактивные примеры на одной странице
• Basic - базовый пример с основными функциями
• Modules Demo - демонстрация всех модулей
• Loop Mode - бесконечная прокрутка

💻 Локальная разработка

# Запустить Sandbox (песочница для экспериментов)
npm run dev

# Запустить документацию (включая примеры)
npm run docs:dev

# Собрать и просмотреть production версию документации
npm run build:docs
npm run preview:docs

🛠️ Разработка

Быстрый старт для разработчиков

# Клонировать репозиторий
git clone https://github.com/VladimirIvanin/tvist.git
cd tvist

# Установить зависимости
npm install

# Запустить Sandbox
npm run dev

Dev-сервер откроется на http://localhost:3000 с песочницей. Документация доступна на http://localhost:5173.

Доступные команды

npm run dev              # Запуск песочницы (sandbox)
npm run docs:dev         # Запуск документации и примеров
npm run dev:watch        # Dev + проверка типов
npm run build            # Production сборка библиотеки
npm run build:browser    # Только минифицированная сборка для браузера (browser-build/)
npm run build:docs       # Сборка документации и примеров
npm run test             # Запуск тестов
npm run test:ui          # UI для тестов
npm run test:coverage    # Покрытие кодом
npm run lint             # Проверка кода
npm run format           # Форматирование
npm run typecheck        # Проверка типов

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

tvist/
├── src/               # Исходники
│   ├── core/          # Ядро библиотеки
│   ├── modules/       # Модули
│   ├── utils/         # Утилиты
│   └── styles/        # SCSS стили
├── sandbox/           # Песочница для экспериментов
├── docs/              # Документация и примеры
│   ├── demos/         # Исходный код примеров
│   └── public/        # Статика
├── tests/             # Тесты
└── dist/              # Сборка библиотеки

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

Мы приветствуем ваш вклад! См. CONTRIBUTING.md для деталей.

📄 Лицензия

MIT © Tvist Contributors