vgapp 0.7.8 → 0.8.0

package/app/modules/vgalert/readme.md

@@ -0,0 +1,242 @@
+# VGAlert — Модуль модальных окон подтверждения и уведомлений
+
+`VGAlert` — это мощный и гибкий JavaScript-модуль, предназначенный для отображения модальных окон подтверждения действий или информационных сообщений. Он интегрирован с системой `VGModal` и поддерживает AJAX-запросы, локализацию, кастомизацию кнопок, тем оформления и работу через `data`-атрибуты.
+
+---
+
+## ✅ Возможности
+
+- Отображение **подтверждающих алертов** (`confirm`) и **информационных сообщений** (`info`)
+- Поддержка **AJAX-запросов** после подтверждения
+- Полная **локализация** (настройка языка)
+- Гибкая **настройка кнопок** и сообщений
+- Поддержка **SVG-иконок** и тем стилей (`danger`, `warning`, `success`, `info`)
+- Работа как через **API**, так и через **`data`-атрибуты**
+- Интеграция с промисами (`Promise`)
+- Защита от **множественных одновременных вызовов**
+- Поддержка **клавиатурных сокращений** (Enter, Escape)
+
+---
+
+## 📦 Установка
+
+Модуль автоматически подключается при инициализации системы. Убедитесь, что подключены зависимости:
+```js
+import VGAlert from "./app/modules/vgalert/js/vgalert.js";
+```
+
+---
+
+## 🧩 Режимы работы
+
+### 1. `confirm` — Подтверждение действия
+Показывает два действия: **Подтвердить** и **Отмена**.
+
+### 2. `info` — Информационное сообщение
+Показывает только кнопку **ОК** (или "Продолжить").
+
+---
+
+## 🎨 Темы (`theme`)
+| Значение | Иконка | Назначение |
+|--------|--------|----------|
+| `danger` | ⚠️ | Опасные действия (удаление, сброс) |
+| `warning` | ⚠️ | Предупреждения |
+| `success` | ✅ | Успешные операции |
+| `info` | ℹ️ | Общая информация |
+
+---
+
+## 🧱 Вызов через JS (API)
+
+### Пример 1: Подтверждение удаления
+
+```js
+VGAlert.call({ 
+    mode: "confirm", 
+    theme: "danger", 
+    message: { 
+        title: "Вы уверены?", 
+        description: "Это действие нельзя отменить." 
+    }, 
+    buttons: { 
+        agree: { 
+            text: "Удалить", 
+            class: ["btn-danger"]
+        },
+        cancel: {
+            text: "Отмена", 
+            class: ["btn-outline-secondary"] 
+        } 
+    } 
+}).then(() => { // Выполнить AJAX-удаление
+	console.log("Пользователь подтвердил удаление");
+}).catch(() => { 
+	console.log("Пользователь отменил действие"); 
+});
+```
+
+### Пример 2: Информационное сообщение
+```js
+VGAlert.call({ 
+    mode: "info",
+    theme: "success",
+    message: {
+        title: "Успешно!", 
+        description: "Данные были сохранены."
+    }, 
+    buttons: { 
+        cancel: { 
+            text: "ОК", 
+            class: ["btn-success"] 
+        } 
+    } 
+});
+```
+
+---
+
+## 🔌 Работа с AJAX
+
+Модуль можно связать с AJAX-запросом, который выполнится после подтверждения:
+```js
+// Удалить запись 
+// Автоматически вызывается при клике
+VGAlert.confirm(element, { 
+    mode: "confirm", 
+    theme: "danger", 
+    message: { 
+        title: "Удалить?", 
+        description: "Вы действительно хотите удалить эту запись?" 
+    }, 
+    ajax: {
+        route: "/api/delete/123", 
+        method: "post",
+    }
+});
+```
+После подтверждения:
+- Выполняется `POST /api/delete/123`
+- Результат можно отследить через события
+
+---
+
+## 🔔 События
+
+Модуль генерирует события:
+
+| Событие | Описание |
+|--------|--------|
+| `vg.alert.accept` | Пользователь подтвердил действие |
+| `vg.alert.reject` | Пользователь отменил действие |
+| `vg.alert.finally` | Действие завершено (в любом случае) |
+| `vg.alert.loaded` | Получен ответ от сервера (если был AJAX) |
+
+```js 
+document.addEventListener('vg.alert.accept', function(e) { 
+    console.log('Подтверждено:', e.vgalert); 
+});
+```
+
+---
+
+## ⌨️ Клавиатурные комбинации
+
+- `Enter` — подтверждение (если фокус на кнопке "Подтвердить")
+- `Escape` — отмена (если `keyboard: true`)
+
+---
+
+## 🛠️ Конфигурация по умолчанию
+```js
+{ 
+    mode: "confirm", 
+    theme: "danger", 
+    modal: { 
+        centered: false,
+        backdrop: true, 
+        keyboard: true,
+        dismiss: true 
+    }, 
+    buttons: {
+        agree: { 
+            text: "Да", 
+            class: ["btn-primary"] }, 
+        cancel: { 
+            text: "Отмена", 
+            class: ["btn-secondary"] 
+        } 
+    },
+    message: { 
+        title: "Подтвердите действие", 
+        description: "Вы уверены, что хотите продолжить?" 
+    } 
+}
+```
+
+---
+
+## 🌐 Локализация
+
+Поддерживаются языки: `ru` (по умолчанию), `en`.
+
+Настройка языка:
+
+```js
+VGAlert.call(params, 'en');
+```
+Переводы хранятся в `lang_buttons` и `lang_messages`.
+
+---
+
+## 🧩 Кастомизация кнопок
+
+Поддерживает:
+- `tag: 'button' | 'a'`
+- `type` (для `<button>`)
+- `class` — массив CSS-классов
+- `attr` — любые дополнительные атрибуты
+- `element` — готовый HTML-код кнопки
+
+### Пример: кнопка-ссылка
+```js
+buttons: { 
+    agree: {
+        tag: "a", 
+        attr: {}, 
+        class: ["btn", "btn-info"], 
+        text: "Перейти в профиль" }, 
+    cancel: { 
+        text: "Закрыть"
+    } 
+}
+```
+
+---
+
+## 🚫 Ограничения
+
+- Нельзя открыть более одного `VGAlert` одновременно (защита от дублирования)
+- Если `isAlertOpen = true`, последующие вызовы будут отклонены с ошибкой
+
+---
+
+## 📎 Смотрите также
+
+- [`VGModal`](../vgmodal/readme.md) — основа модального окна
+- [`BaseModule`](../../base-module.js) — базовый класс модулей
+- [`lang`](../../../utils/js/components/lang.js) — система локализации
+
+---
+
+💡 **Совет**: Используйте `VGAlert` для критичных действий, где важно получить подтверждение от пользователя.
+
+---
+## 📄 Лицензия
+
+MIT — свободно используйте и модифицируйте.
+
+---
+
+> 🚀 Автор: VEGAS STUDIO (vegas-dev.com)
+> 📍 Поддерживается в проектах VEGAS

package/app/modules/vgcollapse/js/vgcollapse.js

@@ -1,11 +1,46 @@
+/**
+ * @class VGCollapse
+ * @extends BaseModule
+ * @classdesc Класс для реализации поведения "collapse" (раскрытие/свертывание элементов) с поддержкой анимации, AJAX-загрузки и иерархической структуры.
+ *
+ * Поддерживает переключение видимости контента по клику на элементы с атрибутом `data-vg-toggle="collapse"`.
+ * Может работать в вертикальном и горизонтальном режимах, управлять aria-атрибутами и состоянием кнопок.
+ *
+ * @param {HTMLElement} element - Основной элемент, к которому применяется collapse.
+ * @param {Object} params - Параметры конфигурации.
+ * @param {boolean} [params.toggle=true] - Автоматически переключать состояние при инициализации.
+ * @param {string|HTMLElement|null} [params.parent=null] - Родительский контейнер, ограничивающий поиск дочерних collapse-элементов.
+ * @param {Object} params.ajax - Настройки AJAX-загрузки контента.
+ * @param {string} params.ajax.route - URL-адрес для запроса.
+ * @param {string} params.ajax.target - CSS-селектор, куда вставлять ответ.
+ * @param {string} params.ajax.method='get' - HTTP-метод запроса.
+ * @param {boolean} params.ajax.loader=false - Показывать ли лоадер при загрузке.
+ * @param {boolean} params.ajax.once=true - Загружать контент только один раз.
+ * @param {boolean} params.ajax.output=true - Вставлять ли ответ в DOM.
+ *
+ * @example
+ * const collapse = new VGCollapse(document.getElementById('myCollapse'), {
+ *   toggle: true,
+ *   parent: '#accordion'
+ * });
+ *
+ * @example
+ * <div id="accordion">
+ *   <div class="vg-collapse" id="collapseOne">
+ *     <button data-vg-toggle="collapse" data-target="#collapseOne">Toggle</button>
+ *   </div>
+ * </div>
+ */
 import BaseModule from "../../base-module";
-import {mergeDeepObject, reflow} from "../../../utils/js/functions";
+import {getElement, mergeDeepObject, reflow} from "../../../utils/js/functions";
 import EventHandler from "../../../utils/js/dom/event";
 import Selectors from "../../../utils/js/dom/selectors";
 import {Manipulator} from "../../../utils/js/dom/manipulator";
 
 /**
- * Constants
+ * Константы, используемые в классе VGCollapse.
+ * @private
+ * @type {Object}
  */
 const NAME = 'collapse';
 const NAME_KEY = 'vg.collapse';
@@ -14,21 +49,36 @@ const CLASS_NAME_COLLAPSE = 'vg-collapse';
 const CLASS_NAME_COLLAPSING = 'vg-collapsing';
 const CLASS_NAME_COLLAPSED = 'vg-collapsed';
 const CLASS_NAME_DEEPER_CHILDREN = `:scope .${CLASS_NAME_COLLAPSE} .${CLASS_NAME_COLLAPSE}`;
+const CLASS_NAME_HORIZONTAL = 'vg-collapse-horizontal';
 
-const SELECTOR_DATA_TOGGLE= '[data-vg-toggle="collapse"]';
-const SELECTOR_ACTIVES = '.collapse.show, .collapse.collapsing';
+const SELECTOR_DATA_TOGGLE = '[data-vg-toggle="collapse"]';
+const SELECTOR_ACTIVES = '.vg-collapse.show, .vg-collapse.vg-collapsing';
 
-const EVENT_KEY_HIDE   = `${NAME_KEY}.hide`;
+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_KEY_SHOW = `${NAME_KEY}.show`;
+const EVENT_KEY_SHOWN = `${NAME_KEY}.shown`;
+const EVENT_KEY_LOADED = `${NAME_KEY}.loaded`;
 
 const EVENT_KEY_CLICK_DATA_API = `click.${NAME_KEY}.data.api`;
 
+const WIDTH = 'width';
+const HEIGHT = 'height';
+
 class VGCollapse extends BaseModule {
+	/**
+	 * Создает экземпляр VGCollapse.
+	 * @param {HTMLElement} element - DOM-элемент, к которому применяется collapse.
+	 * @param {Object} params - Параметры инициализации.
+	 */
 	constructor(element, params = {}) {
 		super(element, params);
 
+		/**
+		 * Объединённые параметры с учётом значений по умолчанию и переданных пользователем.
+		 * @type {Object}
+		 * @private
+		 */
 		this._params = this._getParams(element, mergeDeepObject({
 			toggle: true,
 			parent: null,
@@ -37,13 +87,31 @@ class VGCollapse extends BaseModule {
 				target: '',
 				method: 'get',
 				loader: false,
-				once: false,
+				once: true,
 				output: true,
 			}
 		}, params));
 
-		this._isTransitioning = false
-		this._triggerArray = []
+		/**
+		 * Родительский элемент (если задан).
+		 * @type {HTMLElement|null}
+		 * @private
+		 */
+		this._params.parent = getElement(this._params.parent) || null;
+
+		/**
+		 * Флаг, указывающий на переход (анимацию).
+		 * @type {boolean}
+		 * @private
+		 */
+		this._isTransitioning = false;
+
+		/**
+		 * Массив элементов, которые управляют этим collapse (например, кнопки).
+		 * @type {HTMLElement[]}
+		 * @private
+		 */
+		this._triggerArray = [];
 
 		const toggleList = Selectors.findAll(SELECTOR_DATA_TOGGLE);
 
@@ -52,7 +120,7 @@ class VGCollapse extends BaseModule {
 			const filterElement = Selectors.findAll(selector).filter(foundElement => foundElement === this._element);
 
 			if (selector !== null && filterElement.length) {
-				this._triggerArray.push(elem)
+				this._triggerArray.push(elem);
 			}
 		}
 
@@ -67,112 +135,172 @@ class VGCollapse extends BaseModule {
 		}
 	}
 
+	/**
+	 * Возвращает статическое имя модуля.
+	 * @returns {string} Имя модуля.
+	 * @static
+	 */
 	static get NAME() {
 		return NAME;
 	}
 
+	/**
+	 * Возвращает статический ключ модуля (используется для событий и хранения экземпляров).
+	 * @returns {string} Ключ модуля.
+	 * @static
+	 */
 	static get NAME_KEY() {
-		return NAME_KEY
+		return NAME_KEY;
 	}
 
+	/**
+	 * Переключает состояние collapse: если скрыт — показывает, если показан — скрывает.
+	 * @param {EventTarget} [relatedTarget] - Связанный элемент (опционально).
+	 * @returns {void}
+	 */
 	toggle(relatedTarget) {
 		return !this._isShown() ? this.show(relatedTarget) : this.hide();
 	}
 
+	/**
+	 * Открывает collapse с анимацией и, при необходимости, AJAX-загрузкой.
+	 * @emits VGCollapse#show - Перед началом открытия.
+	 * @emits VGCollapse#shown - После завершения открытия.
+	 * @emits VGCollapse#loaded - После загрузки AJAX-контента (если используется).
+	 * @returns {void}
+	 */
 	show() {
-		const _this = this;
-
-		if (_this._isTransitioning || _this._isShown()) return;
+		if (this._isTransitioning || this._isShown()) {
+			return;
+		}
 
 		let activeChildren = [];
 
-		if (_this._params.parent) {
+		if (this._params.parent) {
 			activeChildren = this._getFirstLevelChildren(SELECTOR_ACTIVES)
 				.filter(element => element !== this._element)
 				.map(element => VGCollapse.getOrCreateInstance(element, { toggle: false }));
 		}
 
-		if (activeChildren.length && activeChildren[0]._isTransitioning) return;
+		if (activeChildren.length && activeChildren[0]._isTransitioning) {
+			return;
+		}
 
-		const startEvent = EventHandler.trigger(_this._element, EVENT_KEY_SHOW);
-		if (startEvent.defaultPrevented) return;
+		const startEvent = EventHandler.trigger(this._element, EVENT_KEY_SHOW);
+		if (startEvent.defaultPrevented) {
+			return;
+		}
 
 		for (const activeInstance of activeChildren) {
 			activeInstance.hide();
 		}
 
-		_this._element.classList.remove(CLASS_NAME_COLLAPSE)
-		_this._element.classList.add(CLASS_NAME_COLLAPSING)
+		const dimension = this._getDimension();
 
-		_this._element.style.height = 0;
+		this._element.classList.remove(CLASS_NAME_COLLAPSE);
+		this._element.classList.add(CLASS_NAME_COLLAPSING);
 
-		_this._addAriaAndCollapsedClass(_this._triggerArray, true);
-		_this._isTransitioning = true;
+		this._element.style[dimension] = '0';
 
-		_this._route();
+		this._addAriaAndCollapsedClass(this._triggerArray, true);
+		this._isTransitioning = true;
 
 		const complete = () => {
-			_this._isTransitioning = false;
+			this._isTransitioning = false;
 
-			_this._element.classList.remove(CLASS_NAME_COLLAPSING);
-			_this._element.classList.add(CLASS_NAME_COLLAPSE, CLASS_NAME_SHOW);
+			this._element.classList.remove(CLASS_NAME_COLLAPSING);
+			this._element.classList.add(CLASS_NAME_COLLAPSE, CLASS_NAME_SHOW);
 
-			_this._element.style.height = '';
-			EventHandler.trigger(_this._element, EVENT_KEY_SHOWN);
-		}
+			this._element.style[dimension] = '';
+
+			this._route((status, data) => {
+				EventHandler.trigger(this._element, EVENT_KEY_LOADED, { stats: status, data });
+			});
 
-		_this._queueCallback(complete, _this._element, true);
+			EventHandler.trigger(this._element, EVENT_KEY_SHOWN);
+		};
 
-		const scrollSize = `scrollHeight`;
-		_this._element.style.height = `${_this._element[scrollSize]}px`;
+		const capitalizedDimension = dimension[0].toUpperCase() + dimension.slice(1);
+		const scrollSize = `scroll${capitalizedDimension}`;
+
+		this._queueCallback(complete, this._element, true);
+		this._element.style[dimension] = `${this._element[scrollSize]}px`;
 	}
 
+	/**
+	 * Скрывает collapse с анимацией.
+	 * @emits VGCollapse#hide - Перед началом скрытия.
+	 * @emits VGCollapse#hidden - После завершения скрытия.
+	 * @returns {void}
+	 */
 	hide() {
-		const _this = this;
+		if (this._isTransitioning || !this._isShown()) {
+			return;
+		}
+
+		const startEvent = EventHandler.trigger(this._element, EVENT_KEY_HIDE);
+		if (startEvent.defaultPrevented) {
+			return;
+		}
 
-		if (_this._isTransitioning || !_this._isShown()) return;
+		const dimension = this._getDimension();
 
-		const startEvent = EventHandler.trigger(_this._element, EVENT_KEY_HIDE)
-		if (startEvent.defaultPrevented) return;
+		this._element.style[dimension] = `${this._element.getBoundingClientRect()[dimension]}px`;
 
-		_this._element.style.height = `${this._element.getBoundingClientRect().height}px`;
-		reflow(_this._element);
+		reflow(this._element);
 
-		_this._element.classList.add(CLASS_NAME_COLLAPSING);
-		_this._element.classList.remove(CLASS_NAME_COLLAPSE, CLASS_NAME_SHOW);
+		this._element.classList.add(CLASS_NAME_COLLAPSING);
+		this._element.classList.remove(CLASS_NAME_COLLAPSE, CLASS_NAME_SHOW);
 
-		for (const trigger of _this._triggerArray) {
+		for (const trigger of this._triggerArray) {
 			const element = Selectors.getElementFromSelector(trigger);
 
-			if (element && !_this._isShown(element)) {
-				_this._addAriaAndCollapsedClass([trigger], false);
+			if (element && !this._isShown(element)) {
+				this._addAriaAndCollapsedClass([trigger], false);
 			}
 		}
 
-		_this._isTransitioning = true
+		this._isTransitioning = true;
 
 		const complete = () => {
-			_this._isTransitioning = false;
-			_this._element.classList.remove(CLASS_NAME_COLLAPSING);
-			_this._element.classList.add(CLASS_NAME_COLLAPSE);
-			EventHandler.trigger(_this._element, EVENT_KEY_HIDDEN);
-		}
+			this._isTransitioning = false;
+			this._element.classList.remove(CLASS_NAME_COLLAPSING);
+			this._element.classList.add(CLASS_NAME_COLLAPSE);
+			EventHandler.trigger(this._element, EVENT_KEY_HIDDEN);
+		};
+
+		this._element.style[dimension] = '';
 
-		_this._element.style.height = '';
-		_this._queueCallback(complete, _this._element, true);
+		this._queueCallback(complete, this._element, true);
 	}
 
+	/**
+	 * Удаляет экземпляр collapse и очищает память.
+	 * @returns {void}
+	 */
 	dispose() {
 		super.dispose();
 	}
 
+	/**
+	 * Проверяет, является ли элемент открытым.
+	 * @param {HTMLElement} [element=this._element] - Элемент для проверки.
+	 * @returns {boolean} `true`, если элемент имеет класс `.show`.
+	 * @private
+	 */
 	_isShown(element = this._element) {
 		return element.classList.contains(CLASS_NAME_SHOW);
 	}
 
+	/**
+	 * Добавляет или удаляет aria-атрибуты и классы у управляющих элементов.
+	 * @param {HTMLElement[]} triggerArray - Массив элементов управления.
+	 * @param {boolean} isOpen - Состояние: открыто или закрыто.
+	 * @private
+	 */
 	_addAriaAndCollapsedClass(triggerArray, isOpen) {
 		if (!triggerArray.length) {
-			return
+			return;
 		}
 
 		for (const element of triggerArray) {
@@ -180,43 +308,69 @@ class VGCollapse extends BaseModule {
 		}
 	}
 
+	/**
+	 * Инициализирует дочерние collapse-элементы, если указан родитель.
+	 * @private
+	 */
 	_initializeChildren() {
 		if (!this._params.parent) return;
 
 		const children = this._getFirstLevelChildren(SELECTOR_DATA_TOGGLE);
 
 		for (const element of children) {
-			const selected = Selectors.getElementFromSelector(element)
+			const selected = Selectors.getElementFromSelector(element);
 
 			if (selected) {
-				this._addAriaAndCollapsedClass([element], this._isShown(selected))
+				this._addAriaAndCollapsedClass([element], this._isShown(selected));
 			}
 		}
 	}
 
+	/**
+	 * Возвращает дочерние элементы первого уровня (без вложенных).
+	 * @param {string} selector - CSS-селектор для поиска.
+	 * @returns {HTMLElement[]} Массив найденных элементов.
+	 * @private
+	 */
 	_getFirstLevelChildren(selector) {
-		const children = Selectors.find(CLASS_NAME_DEEPER_CHILDREN, this._params.parent);
-		return Selectors.find(selector, this._params.parent).filter(element => !children.includes(element));
+		const children = Selectors.findAll(CLASS_NAME_DEEPER_CHILDREN, this._params.parent);
+		return Selectors.findAll(selector, this._params.parent).filter(element => !children.includes(element));
 	}
 
+	/**
+	 * Обновляет состояние кнопки: классы, текст, aria-expanded.
+	 * @param {HTMLElement} element - Кнопка, управляющая collapse.
+	 * @param {boolean} isOpen - Текущее состояние (открыто/закрыто).
+	 * @private
+	 */
 	_changeStateButton(element, isOpen) {
 		element.classList.toggle(CLASS_NAME_COLLAPSED, !isOpen);
 		element.setAttribute('aria-expanded', isOpen);
 		element.innerHTML = Manipulator.get(element, `data-${isOpen ? 'hide' : 'show'}-text`) || element.innerHTML;
 	}
+
+	/**
+	 * Определяет, по какой оси происходит анимация (высота или ширина).
+	 * @returns {string} `'height'` или `'width'`.
+	 * @private
+	 */
+	_getDimension() {
+		return this._element.classList.contains(CLASS_NAME_HORIZONTAL) ? WIDTH : HEIGHT;
+	}
 }
 
 /**
- * Data API implementation
+ * Реализация Data API: автоматическая инициализация по атрибуту `data-vg-toggle="collapse"`.
+ * @listens document#click
  */
 EventHandler.on(document, EVENT_KEY_CLICK_DATA_API, SELECTOR_DATA_TOGGLE, function (event) {
 	if (event.target.tagName === 'A' || (event.delegateTarget && event.delegateTarget.tagName === 'A')) {
-		event.preventDefault()
+		event.preventDefault();
 	}
 
 	Selectors.getMultipleElementsFromSelector(this).forEach(function (element) {
-		VGCollapse.getOrCreateInstance(element, {toggle: false}).toggle();
+		VGCollapse.getOrCreateInstance(element, { toggle: false }).toggle();
 	});
-})
+});
 
 export default VGCollapse;