vgapp 0.7.8 → 0.8.0

package/app/modules/vgcollapse/readme.md

@@ -0,0 +1,56 @@
+# VGCollapse
+
+**VGCollapse** — это легковесный и гибкий JavaScript-модуль для создания анимированных блоков с возможностью сворачивания/разворачивания содержимого. Подходит для аккордеонов, скрытых форм, FAQ-секций и других интерактивных элементов, где нужно управлять видимостью контента.
+
+---
+
+## ✅ Возможности
+
+- Плавная анимация открытия/закрытия (через `height` и `overflow`)
+- Поддержка нескольких экземпляров на одной странице
+- Работа без jQuery — чистый ES6+
+- Возможность инициализации вручную или через data-атрибуты
+- Совместимость с динамически добавленным контентом
+
+---
+
+## 📦 Установка
+
+Подключите JS-файл в проект:
+
+```js
+ import VGCollapse from './path/to/vgcollapse.js';
+ ```
+
+---
+
+## 🧱 HTML Структура
+
+```html
+<a href="#example-simple" data-vg-toggle="collapse" aria-expanded="true" class="btn btn-primary" data-hide-text="Скрыть контент" data-show-text="Показать контент">Скрыть контент</a>
+<div class="vg-collapse show" id="example-simple">
+	Lorem ipsum dolor sit amet, consectetur adipisicing elit. Adipisci eligendi magnam
+	minus nihil quaerat.
+</div>
+```
+
+---
+
+## ⚙️ Инициализация
+
+### 1. Через data-атрибуты (авто-инициализация)
+
+Добавьте `data-vg-collapse` — модуль автоматически найдёт и инициализирует все блоки.
+
+---
+
+## 📝 Заметки
+
+- Контент должен быть видим при инициализации, чтобы корректно рассчитать высоту.
+- Не используйте `display: none` на контейнере при инициализации.
+- Поддерживает современные браузеры (включая Edge, не поддерживает IE11).
+
+---
+
+> 🚀 Автор: VEGAS STUDIO (vegas-dev.com)
+> 📍 Поддерживается в проектах VEGAS

package/app/modules/vgcollapse/scss/_variables.scss

@@ -0,0 +1,5 @@
+$collapse-accordion-map: (
+		border: 1px solid $border-color,
+		border-radius: $border-radius,
+		padding: 1rem
+);

package/app/modules/vgcollapse/scss/vgcollapse.scss

@@ -0,0 +1,41 @@
+/**
+*--------------------------------------------------------------------------
+* Модуль: VGCollapse, реализация vg-accordion
+* Автор: Vegas DEV
+* Лицензия: смотри LICENSE
+*--------------------------------------------------------------------------
+**/
+
+@import "../../../utils/scss/functions";
+@import "../../../utils/scss/mixin";
+@import "../../../utils/scss/variables";
+@import "variables";
+
+
+.vg-accordion {
+	@include mix-vars('accordion', $collapse-accordion-map);
+	position: relative;
+	border: var(--vg-accordion-border);
+	border-radius: var(--vg-accordion-border-radius);
+
+	&-item {
+		border-top: 0;
+		border-left: 0;
+		border-right: 0;
+		border-bottom: var(--vg-accordion-border);
+
+		&:last-child {
+			border: none;
+		}
+	}
+
+	&-button {
+		display: block;
+		padding: var(--vg-accordion-padding);
+	}
+
+	&-content {
+		display: block;
+		padding: var(--vg-accordion-padding);
+	}
+}

package/app/modules/vgdropdown/js/vgdropdown.js

@@ -3,10 +3,19 @@ import EventHandler from "../../../utils/js/dom/event";
 import Selectors from "../../../utils/js/dom/selectors";
 import {isDisabled, mergeDeepObject, noop} from "../../../utils/js/functions";
 import Placement from "../../../utils/js/components/placement";
-import Overflow from "../../../utils/js/components/overflow";
-import Backdrop from "../../../utils/js/components/backdrop";
-import {dismissTrigger} from "../../module-fn";
 
+/**
+ * Константы, используемые в модуле выпадающего списка.
+ * @type {Object}
+ * @property {string} NAME - Имя модуля.
+ * @property {string} NAME_KEY - Уникальный ключ модуля с префиксом.
+ * @property {string} CLASS_NAME_SHOW - CSS-класс для отображения элемента.
+ * @property {string} CLASS_NAME_FADE - CSS-класс для эффекта затухания.
+ * @property {string} CLASS_NAME_OPEN - CSS-класс для немигающего открытия.
+ * @property {string} TARGET_CONTAINER - Класс контейнера выпадающего меню.
+ * @property {string} PARENT_CONTAINER - Класс родительского контейнера.
+ * @property {string} SELECTOR_DATA_TOGGLE - Селектор элемента-переключателя.
+ */
 const NAME             = 'dropdown';
 const NAME_KEY         = 'vg.dropdown';
 const CLASS_NAME_SHOW  = 'show';
@@ -16,26 +25,75 @@ const TARGET_CONTAINER = 'vg-dropdown-content';
 const PARENT_CONTAINER = 'vg-dropdown';
 const SELECTOR_DATA_TOGGLE = '[data-vg-toggle="dropdown"]';
 
+/**
+ * События, генерируемые модулем.
+ * @type {Object}
+ */
 const EVENT_KEY_HIDE   = `${NAME_KEY}.hide`;
 const EVENT_KEY_HIDDEN = `${NAME_KEY}.hidden`;
 const EVENT_KEY_SHOW   = `${NAME_KEY}.show`;
 const EVENT_KEY_SHOWN  = `${NAME_KEY}.shown`;
-
-const EVENT_KEYUP_DATA_API =     `keyup.${NAME_KEY}.data.api`;
-const EVENT_KEYDOWN_DATA_API =   `keydown.${NAME_KEY}.data.api`;
-const EVENT_CLICK_DATA_API =     `click.${NAME_KEY}.data.api`;
+const EVENT_KEY_LOADED = `${NAME_KEY}.loaded`;
+
+/**
+ * Делегированные события на уровне документа.
+ * @type {Object}
+ */
+const EVENT_KEYUP_DATA_API     = `keyup.${NAME_KEY}.data.api`;
+const EVENT_KEYDOWN_DATA_API   = `keydown.${NAME_KEY}.data.api`;
+const EVENT_CLICK_DATA_API     = `click.${NAME_KEY}.data.api`;
 const EVENT_MOUSEOVER_DATA_API = `mouseover.${NAME_KEY}.data.api`;
-const EVENT_MOUSEOUT_DATA_API =  `mouseout.${NAME_KEY}.data.api`;
-
+const EVENT_MOUSEOUT_DATA_API  = `mouseout.${NAME_KEY}.data.api`;
+
+/**
+ * Компонент выпадающего списка (Dropdown).
+ *
+ * @extends BaseModule
+ *
+ * @example
+ * const dropdown = new VGDropdown(document.querySelector('[data-vg-toggle="dropdown"]'), {
+ *   placement: 'bottom-start',
+ *   hover: true,
+ *   animation: {
+ *     enable: true,
+ *     in: 'animate__fadeIn',
+ *     out: 'animate__fadeOut',
+ *     delay: 150
+ *   }
+ * });
+ *
+ * @example <caption>Инициализация через data-атрибуты</caption>
+ * <div class="vg-dropdown">
+ *   <button data-vg-toggle="dropdown" aria-expanded="false">Меню</button>
+ *   <div class="vg-dropdown-content">Содержимое меню</div>
+ * </div>
+ */
 class VGDropdown extends BaseModule {
+	/**
+	 * Создаёт экземпляр VGDropdown.
+	 *
+	 * @param {HTMLElement} element - Элемент-переключатель (кнопка).
+	 * @param {Object} [params] - Пользовательские параметры.
+	 * @param {string} [params.placement='auto'] - Позиция выпадающего окна: 'top', 'bottom', 'left', 'right', 'auto' и т.д.
+	 * @param {boolean} [params.hover=false] - Открывать по наведению мыши.
+	 * @param {Object} [params.ajax] - Параметры AJAX-загрузки.
+	 * @param {string} [params.ajax.route=''] - URL для загрузки контента.
+	 * @param {string} [params.ajax.target=''] - Селектор внутри drop для вставки данных.
+	 * @param {string} [params.ajax.method='get'] - HTTP-метод.
+	 * @param {boolean} [params.ajax.loader=false] - Показывать ли лоадер.
+	 * @param {boolean} [params.ajax.once=false] - Загружать один раз.
+	 * @param {boolean} [params.ajax.output=true] - Вставлять ли ответ в DOM.
+	 * @param {Object} [params.animation] - Настройки анимации.
+	 * @param {boolean} [params.animation.fade=false] - Использовать fade-анимацию.
+	 * @param {boolean} [params.animation.enable=false] - Включить CSS-анимации.
+	 * @param {string} [params.animation.in='animate__flipInY'] - Класс для анимации входа.
+	 * @param {string} [params.animation.out='animate__flipOutY'] - Класс для анимации выхода.
+	 * @param {number} [params.animation.delay=300] - Задержка перед завершением скрытия (в мс).
+	 */
 	constructor(element, params) {
 		super(element, params);
 
 		let defaultParams = {
-			backdrop: false,
-			overflow: false,
-			keyboard: false,
-			timeoutAnimation: 10,
 			placement: 'auto',
 			hover: false,
 			ajax: {
@@ -71,18 +129,36 @@ class VGDropdown extends BaseModule {
 		this._animation(this._drop, VGDropdown.NAME_KEY, this._params.animation);
 	}
 
+	/**
+	 * Возвращает имя компонента.
+	 * @return {string}
+	 */
 	static get NAME() {
 		return NAME;
 	}
 
+	/**
+	 * Возвращает уникальный ключ компонента.
+	 * @return {string}
+	 */
 	static get NAME_KEY() {
 		return NAME_KEY;
 	}
 
+	/**
+	 * Переключает состояние выпадающего списка (открыто/закрыто).
+	 * @return {void}
+	 */
 	toggle() {
 		return this._isShown() ? this.hide() : this.show();
 	}
 
+	/**
+	 * Открывает выпадающий список.
+	 * @fires VGDropdown#show - Перед открытием.
+	 * @fires VGDropdown#shown - После открытия.
+	 * @return {void}
+	 */
 	show() {
 		if (isDisabled(this._element) || this._isShown()) return;
 
@@ -101,18 +177,12 @@ class VGDropdown extends BaseModule {
 		this._element.classList.add(CLASS_NAME_SHOW);
 		this._drop.classList.add(CLASS_NAME_SHOW);
 		this._setPlacement();
-		this._route();
-
-		if (this._params.backdrop && !this._params.hover) {
-			Backdrop.show();
-		}
-
-		if (this._params.overflow) {
-			Overflow.append();
-			document.body.classList.add('dropdown-open');
-		}
 
 		const completeCallback = () => {
+			this._route((status, data) => {
+				EventHandler.trigger(this._element, EVENT_KEY_LOADED, { stats: status, data });
+			});
+
 			if (this.isFade) {
 				this._drop.classList.add(CLASS_NAME_FADE);
 			} else if (!this.isAnimation) {
@@ -124,19 +194,39 @@ class VGDropdown extends BaseModule {
 		this._queueCallback(completeCallback, this._drop, this.isAnimation || this.isFade, 50);
 	}
 
+	/**
+	 * Закрывает выпадающий список.
+	 * @fires VGDropdown#hide - Перед закрытием.
+	 * @fires VGDropdown#hidden - После закрытия.
+	 * @return {void}
+	 */
 	hide() {
 		if (isDisabled(this._element) || !this._isShown()) return;
 		this._completeHide({ relatedTarget: this._element });
 	}
 
+	/**
+	 * Удаляет инстанс компонента и очищает обработчики событий.
+	 * @return {void}
+	 */
 	dispose() {
 		super.dispose();
 	}
 
+	/**
+	 * Проверяет, открыто ли выпадающее меню.
+	 * @return {boolean} - `true`, если открыто.
+	 * @private
+	 */
 	_isShown() {
 		return this._element.classList.contains(CLASS_NAME_SHOW);
 	}
 
+	/**
+	 * Полностью закрывает меню с анимацией и callback.
+	 * @param {Object} relatedTarget - Событие-инициатор.
+	 * @private
+	 */
 	_completeHide(relatedTarget) {
 		const hideEvent = EventHandler.trigger(this._drop, EVENT_KEY_HIDE, relatedTarget);
 		if (hideEvent.defaultPrevented) return;
@@ -156,19 +246,6 @@ class VGDropdown extends BaseModule {
 			this._drop.classList.remove(CLASS_NAME_OPEN);
 		}
 
-		if (this._params.backdrop && !this._params.hover) {
-			Backdrop.hide(() => {
-				if (this._params.overflow) {
-					Overflow.destroy();
-				}
-			});
-		}
-
-		if (this._params.overflow) {
-			Overflow.destroy();
-			document.body.classList.remove('dropdown-open');
-		}
-
 		setTimeout(() => {
 			const completeCallback = () => {
 				this._drop.classList.remove(CLASS_NAME_SHOW);
@@ -178,6 +255,10 @@ class VGDropdown extends BaseModule {
 		}, this._params.animation.delay);
 	}
 
+	/**
+	 * Устанавливает позицию выпадающего окна с помощью вспомогательного класса Placement.
+	 * @private
+	 */
 	_setPlacement() {
 		if (!this._drop) return;
 
@@ -209,6 +290,12 @@ class VGDropdown extends BaseModule {
 		this._isPlacement = true;
 	}
 
+	/**
+	 * Инициализирует компонент на указанном элементе и устанавливает обработчики событий.
+	 * @param {HTMLElement} element - Элемент-переключатель.
+	 * @param {Object} [params] - Параметры инициализации.
+	 * @return {VGDropdown} - Экземпляр компонента.
+	 */
 	static init(element, params = {}) {
 		const instance = VGDropdown.getOrCreateInstance(element, params);
 
@@ -253,8 +340,15 @@ class VGDropdown extends BaseModule {
 			event.preventDefault();
 			instance.toggle();
 		});
+
+		return instance;
 	}
 
+	/**
+	 * Скрывает все открытые выпадающие списки.
+	 * @param {Event} event - Событие, инициировавшее скрытие.
+	 * @static
+	 */
 	static hideOpenToggles(event) {
 		const openToggles = Selectors.findAll(`${SELECTOR_DATA_TOGGLE}:not(.disabled):not(:disabled).${CLASS_NAME_SHOW}`);
 		for (const toggle of openToggles) {
@@ -279,6 +373,11 @@ class VGDropdown extends BaseModule {
 		}
 	}
 
+	/**
+	 * Обработчик клавиатурных событий (стрелки, Esc).
+	 * @param {KeyboardEvent} event - Клавиатурное событие.
+	 * @static
+	 */
 	static keydownHandler(event) {
 		const isInput = /input|textarea/i.test(event.target.tagName);
 		const isEscapeEvent = event.key === 'Escape';
@@ -307,6 +406,11 @@ class VGDropdown extends BaseModule {
 		}
 	}
 
+	/**
+	 * Обработчик кликов и Tab для закрытия выпадающих списков.
+	 * @param {Event} event - Событие (click или keyup).
+	 * @static
+	 */
 	static clearDrops(event) {
 		if (event.button === 2 || (event.type === 'keyup' && event.key !== 'Tab')) {
 			return;
@@ -315,6 +419,4 @@ class VGDropdown extends BaseModule {
 	}
 }
 
-dismissTrigger(VGDropdown);
-
 export default VGDropdown;

package/app/modules/vgdropdown/readme.md

@@ -0,0 +1,225 @@
+# VGDropdown — Модуль выпадающего списка
+
+**VGDropdown** — это универсальный и гибко настраиваемый JavaScript-компонент для создания интерактивных 
+выпадающих меню (dropdown) в веб-интерфейсах. Поддерживает позиционирование, анимации, AJAX-загрузку контента,
+работу с hover/кликами, клавиатурную навигацию и доступность.
+
+---
+
+## 📌 Основные возможности
+
+- Открытие/закрытие по клику или наведению (`hover`)
+- Поддержка **автоматического позиционирования** (с учётом границ экрана и overflow)
+- Полная **клавиатурная навигация** (стрелки, Esc, Tab)
+- **AJAX-загрузка контента** динамически
+- **CSS-анимации** (вход/выход) с использованием Animate.css
+- Поддержка **fade-эффектов** и кастомных задержек
+- Автоматическое закрытие других открытых dropdown'ов
+- Полная **доступность (a11y)**: `aria-expanded`
+- Совместимость с **мобильными устройствами**
+- Гибкая инициализация: через JS или `data-*` атрибуты
+
+---
+
+## 🧩 Структура HTML
+
+```bladehtml
+<div class="vg-dropdown">
+    <a href="#" data-vg-toggle="dropdown" data-params='{"hover": "true"}' ( или data-hover="true") class="btn btn-primary" aria-expanded="false">Open</a>
+    <div class="vg-dropdown-content">
+        <div class="vg-dropdown-container">
+            <ul class="list-group">
+                <li class="list-group-item"><a href="#">Home</a></li>
+                <li class="list-group-item"><a href="#">Services</a></li>
+                <li class="list-group-item"><a href="#">About</a></li>
+                <li class="list-group-item"><a href="#">Contacts</a></li>
+            </ul>
+        </div>
+    </div>
+</div>
+```
+
+> 💡 Убедитесь, что `.vg-dropdown-content` находится внутри `.vg-dropdown`, либо укажите селектор явно через `data-vg-target`.
+
+---
+
+## ⚙️ Параметры инициализации
+
+| Параметр | Тип | По умолчанию | Описание                                                                      |
+|--------|------|-------------|-------------------------------------------------------------------------------|
+| `placement` | `string` | `'auto'` | Позиция меню: `'top-start'`, `'bottom-start'`, `'left-start'`, `'right-start'`, `'auto'` и т.д. |
+| `hover` | `boolean` | `false` | Открывать при наведении мыши (на десктопе)                                    |
+| `animation.fade` | `boolean` | `true` | Добавить класс `fade` при показе                                              |
+| `animation.enable` | `boolean` | `false` | Включить CSS-анимации                                                         |
+| `animation.in` | `string` | `'animate__flipInY'` | Класс анимации входа (например, Animate.css)                                  |
+| `animation.out` | `string` | `'animate__flipOutY'` | Класс анимации выхода                                                         |
+| `animation.delay` | `number` | `300` | Задержка перед удалением `.show` (в мс)                                       |
+| `ajax.route` | `string` | `''` | URL для загрузки контента                                                     |
+| `ajax.target` | `string` | `''` | Селектор внутри `.vg-dropdown-content` для вставки данных                     |
+| `ajax.method` | `string` | `'get'` | HTTP-метод запроса                                                            |
+| `ajax.loader` | `boolean` | `false` | Показывать лоадер при загрузке                                                |
+| `ajax.once` | `boolean` | `false` | Загружать контент только один раз                                             |
+| `ajax.output` | `boolean` | `true` | Вставлять ответ в DOM                                                         |
+
+---
+
+## 🚀 Инициализация
+
+### Через JavaScript
+```js 
+import VGDropdown from 'app/modules/vgdropdown/js/vgdropdown';
+
+const dropdown = new VGDropdown(document.querySelector('[data-vg-toggle="dropdown"]'), { 
+    placement: 'bottom-start', 
+    hover: true, 
+    animation: { 
+        enable: true, 
+        in: 'animate__fadeInDown', 
+        out: 'animate__fadeOutUp', 
+        delay: 200
+    }, 
+    ajax: { 
+        route: '',
+        target: '', 
+        method: 'get', 
+        once: true
+	} 
+});
+```
+
+> Атрибуты автоматически преобразуются в параметры:  
+> `data-placement` → `placement`  
+> `data-ajax-route` → `ajax.route`
+
+---
+
+## 🔁 Методы
+
+| Метод | Описание |
+|------|--------|
+| `.toggle()` | Переключает состояние (открыть/закрыть) |
+| `.show()` | Открывает меню |
+| `.hide()` | Закрывает меню |
+| `.dispose()` | Удаляет экземпляр и обработчики событий |
+| `.getInstance(element)` | Получить существующий экземпляр |
+| `.getOrCreateInstance(element, params)` | Получить или создать экземпляр |
+
+```js
+VGDropdown.getOrCreateInstance().hide(); // Закрыть drop
+```
+---
+
+## 📣 События
+
+VGDropdown генерирует пользовательские события.
+
+| Событие | Срабатывает | Детали (`event.detail`) |
+|--------|-------------|-------------------------|
+| `vg.dropdown.show` | Перед открытием | `relatedTarget` — кнопка |
+| `vg.dropdown.shown` | После открытия | `relatedTarget` |
+| `vg.dropdown.hide` | Перед закрытием | `relatedTarget` |
+| `vg.dropdown.hidden` | После закрытия | `relatedTarget` |
+| `vg.dropdown.loaded` | После AJAX-загрузки | `stats`, `data` |
+
+```js
+dropdown._drop.addEventListener('vg.dropdown.shown', (e) => { 
+    console.log('Дроп открыт', e.detail.relatedTarget); 
+});
+```
+
+---
+
+## 🖱️ Поведение при наведении (`hover`)
+
+```js 
+hover: true
+```
+
+- Работает только на десктопах (`!isMobileDevice()`)
+- Автоматически закрывается при уходе курсора
+- Не конфликтует с другими открытыми меню
+
+---
+
+## 🔁 AJAX-загрузка контента
+
+```js
+ajax: {
+    route: '/menu', 
+    target: '#drop-content', // Целевой селектор внутри .vg-dropdown-container
+    method: 'get', 
+    once: true, 
+    loader: false, 
+    output: true 
+}
+```
+- Контент загружается при первом открытии (если `once: true`)
+- Ответ вставляется в указанный селектор
+- Генерируется событие `vg.dropdown.loaded`
+
+---
+
+## 🎨 Анимации
+
+Поддерживается два режима:
+
+### 1. Fade (CSS)
+### 2. CSS-анимации (через Animate.css)
+```js
+animation: { enable: true, in: 'animate__fadeInUp', out: 'animate__fadeOutDown' }
+```
+> Убедитесь, что подключили animate.css или свои классы анимаций.
+
+---
+
+## 📱 Адаптивность и мобильные устройства
+
+- На мобильных устройствах `hover` отключается
+- При открытии временно блокируются `mouseover` события на других элементах (для стабильности)
+- Поддерживает тач-события корректно
+
+---
+
+## 🔐 Доступность (a11y)
+
+- `aria-expanded` автоматически обновляется
+- Поддержка клавиатуры: **Enter**, **Space**, **Esc**, **↑↓**
+- Закрытие при клике вне или нажатии `Tab`
+
+---
+## 🧰 Статические методы
+
+| Метод | Описание |
+|------|--------|
+| `VGDropdown.hideOpenToggles(event)` | Закрывает все открытые меню |
+| `VGDropdown.keydownHandler(event)` | Обработчик клавиш |
+| `VGDropdown.clearDrops(event)` | Обработчик кликов вне и Tab |
+
+---
+
+## 📦 CSS-классы
+
+| Класс | Назначение |
+|------|----------|
+| `.vg-dropdown` | Родительский контейнер |
+| `.vg-dropdown-content` | Выпадающее меню |
+| `.show` | Показывает элемент |
+| `.fade` | Эффект затухания |
+| `.open` | Альтернатива fade (без анимации) |
+| `[data-vg-toggle="dropdown"]` | Кнопка-переключатель |
+
+---
+
+## 📄 Лицензия
+
+MIT — свободное использование и модификация.
+
+---
+
+🛠 Разработано с использованием современных паттернов и лучших практик.  
+Создано для масштабируемых, доступных и красивых интерфейсов.
+
+---
+
+> 🚀 Автор: VEGAS STUDIO (vegas-dev.com)
+> 📍 Поддерживается в проектах VEGAS