vgapp 0.8.0 → 0.8.2

package/app/modules/vgspy/readme.md

@@ -0,0 +1,105 @@
+# VGSpy — Модуль отслеживания прокрутки (Scroll Spy)
+
+`VGSpy` — это JavaScript-модуль, реализующий функционал **"spy"** (шпион), который автоматически подсвечивает активные пункты навигации в зависимости от текущей позиции прокрутки страницы. Поддерживает плавную прокрутку, работу с кастомными контейнерами и вложенными элементами (например, выпадающими списками).
+
+---
+
+## 📌 Возможности
+
+- ✅ Автоматическое выделение активного пункта навигации при прокрутке.
+- ✅ Поддержка прокрутки как всего окна, так и внутренних контейнеров с `overflow`.
+- ✅ Плавная прокрутка к секциям по клику на ссылки.
+- ✅ Поддержка вложенных структур: навигация, списки, выпадающие меню.
+- ✅ Гибкая настройка через `data-*` атрибуты или JavaScript.
+- ✅ Использование `IntersectionObserver` для высокой производительности.
+- ✅ Совместимость с модульной системой `VG`.
+
+---
+
+## 🧩 Использование
+
+### HTML
+
+Добавьте атрибут `data-vg-toggle="spy"` к навигационному элементу (например, `.nav` или `.list-group`), и убедитесь, что ссылки ведут на якоря (например, `href="#section1"`).
+
+```html
+<ul class="list flex-column vg-spy" data-vg-toggle="spy" id="vgspy-sidebar">
+    <li><a href="#linkFirstBlock">Первый блок</a></li>
+    <li><a href="#linkSecondBlock">Второй блок</a></li>
+    <li><a href="#linkThirdBlock">Третий блок</a></li>
+    <li><a href="#linkFourthBlock">Четвертый блок</a></li>
+    <li><a href="#linkFifthBlock">Пятый блок</a>
+        <ul>
+            <li><a href="#linkFifthBlockPathOne">Пятый блок. Часть первая</a></li>
+        </ul>
+    </li>
+    <li><a href="#linkSixthBlock">Шестой блок</a></li>
+</ul>
+```
+
+> 💡 Если используется прокрутка внутри контейнера (не `window`), укажите `target` (см. ниже).
+
+---
+
+## ⚙️ Параметры
+
+| Параметр | Тип | По умолчанию | Описание |
+|--------|------|-------------|----------|
+| `offset` | `number` | `null` | *(устарело)* Смещение активации (в пикселях). Используйте `rootMargin` вместо этого. |
+| `rootMargin` | `string` | `'0px 0px -25%'` | Отступы для `IntersectionObserver`. Управляет, насколько "внутрь" должна зайти секция, чтобы стать активной. |
+| `smoothScroll` | `boolean` | `true` | Включить плавную прокрутку при клике на якорные ссылки. |
+| `target` | `HTMLElement \| string` | элемент с `data-vg-toggle="spy"` | Контейнер, внутри которого происходит прокрутка. Если не указан — используется `window`. |
+| `threshold` | `number[] \| string` | `[0.1, 0.5, 1]` | Пороги видимости (от 0 до 1), при которых срабатывает активация. Можно передать строку: `'0.1, 0.5, 1'`. |
+
+---
+
+## 📣 События
+
+| Событие | Описание | `event.relatedTarget` |
+|-------|--------|---------------------|
+| `activate.vg.spy` | Срабатывает при активации нового пункта навигации | Ссылка, которая стала активной |
+
+## 🧱 Поддерживаемые структуры
+
+- `.nav`, `.nav-link`, `.nav-item`
+- `.list-group`, `.list-group-item`
+- Вложенные `.vg-dropdown` с `.vg-dropdown-item`
+- Произвольные контейнеры с `href="#id"` ссылками
+
+---
+
+## 🔧 Методы
+
+| Метод | Описание |
+|------|--------|
+| `refresh()` | Перезапускает модуль: пересканирует ссылки и секции, пересоздаёт observer. |
+| `dispose()` | Удаляет observer и освобождает ресурсы. |
+
+---
+
+## 🧪 Производительность
+
+- Используется `IntersectionObserver` — не нагружает страницу.
+- Плавная прокрутка отключается, если `smoothScroll: false`.
+- Поддержка `requestAnimationFrame` не требуется — логика основана на нативных браузерных событиях.
+
+---
+
+## 📚 Заметки
+
+- Убедитесь, что все целевые секции имеют `id`, соответствующий `href` ссылки.
+- Секции должны быть видимы (`display: block`, `visibility: visible`).
+- Работает с динамически добавленным контентом, но требует вызова `refresh()` после вставки.
+
+---
+
+
+## 📝 Лицензия
+
+MIT. Свободно использовать и модифицировать.
+
+---
+
+📌 *Разработано в рамках фронтенд-системы VG Modules.*
+> 🚀 Автор: VEGAS STUDIO (vegas-dev.com)
+> 📍 Поддерживается в проектах VEGAS