vgapp 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -1,13 +1,50 @@
-# VEGAS-APP 1.2.2 (Июнь, 16, 2026)
+# VEGAS-APP 1.2.5 (Июнь, 25, 2026)
+## Новые фичи
+* Добавлен новый модуль `VGTooltip` с режимами `tooltip` и `popover`, Data API, автопозиционированием, fallback placement, закрытием по `Esc` и клику вне элемента.
+* В `VGAlert` добавлен режим рендера `render.type = 'overlay'` для встраивания alert поверх текущей `.vg-modal` или `.vg-sidebar`.
+
+## Изменения
+* В `VGAlert` рендер modal/overlay унифицирован: контейнер и экземпляр рендера создаются один раз, удалены отладочные `console.log`, закрытие вынесено в общий helper.
+* В `VGAlert` отмена confirm теперь корректно отклоняет `Promise`, а обработчик `vg.modal.hide` подписывается только для modal-режима и срабатывает один раз.
+* В `VGTooltip` глобальные обработчики `Esc` и клика вне элемента переведены на работу со всеми открытыми экземплярами, а сброс placement-классов вынесен в общий список.
+* Обновлена документация `VGAlert` и `VGTooltip`, из директории `app/modules/vgalert/js/old/` удалены устаревшие файлы.
+* Обновлена версия пакета в `package.json`: `1.2.4` -> `1.2.5`.
+
+---
+
+# VEGAS-APP 1.2.4 (Июнь, 19, 2026)
+## Новые фичи
+* В `VGModal` добавлены параметры `persistent` и `state` для opt-in persistent-модалок и сохранения состояния drag/resize через `localStorage`.
+
+## Изменения
+* В `VGModal` persistent-модалки исключены из селектора обычных открытых окон и больше не закрываются автоматически при открытии следующей модалки.
+* В `VGModal` сохранение и восстановление inline-состояния диалога и контента встроено в цикл `show/hide`, включая поддержку пользовательского `state.key`.
+* В `VGModal` при `backdrop: true` клик по backdrop закрывает активную модалку через экземпляр текущего окна, а логика закрытия вынесена из общего `Backdrop`.
+* В `VGModal` при `backdrop: false` модалка больше не блокирует страницу: добавлен `pointer-events: none` на контейнер и отдельная ветка корректного cleanup без backdrop.
+* Обновлена версия пакета в `package.json`: `1.2.3` -> `1.2.4`.
+
+---
+
+# VEGAS-APP 1.2.3 (Июнь, 16, 2026)
+## Изменения
+* В `VGToast` исправлен lifecycle `show/hide/dispose`: добавлены защита от повторного hide, очистка отложенного скрытия и проверки актуального элемента в async callback.
+* В `VGToast` `shown/hidden` больше не срабатывают по уже удалённому экземпляру, а `_isShown()` стал null-safe.
+* В `VGFormSender` параметр `alert.toast.closeModalsBeforeToast` по умолчанию переключён в `true`, чтобы перед показом toast закрывались открытые модалки.
+* В событие `vg.modal.loaded` добавлен `relatedTarget`, чтобы обработчики загрузки получали элемент-источник открытия модалки.
+* Обновлена версия пакета в `package.json`: `1.2.2` -> `1.2.3`.
+
+---
+# VEGAS-APP 1.2.2 (Июнь, 16, 2026)
 ## Новые фичи
 * В VGFiles добавлена настройка кнопок подтверждения удаления через `removes.buttons`, `removes.single.buttons` и `removes.all.buttons`.
 * В VGFormSender добавлены опции `alert.modal.closeModalsBeforeModal` и `alert.toast.closeModalsBeforeToast` для управления закрытием открытых модалок перед показом alert-modal или toast.
 
-## Изменения
-* В VGFormSender при `alert.modal.closeModalsBeforeModal = false` новая alert-modal открывается поверх существующей модалки, получает класс `vg-modal-stacked` и повышенный `z-index`.
-* В VGFormSender закрытие открытых Bootstrap/VGModal модалок вынесено в общий helper.
-* В VGFormSender служебный параметр `closeModalsBeforeToast` не передается в настройки VGToast.
-* Обновлена версия пакета в `package.json`: `1.2.1` -> `1.2.2`.
+## Изменения
+* В VGFormSender при `alert.modal.closeModalsBeforeModal = false` новая alert-modal открывается поверх существующей модалки, получает класс `vg-modal-stacked` и повышенный `z-index`.
+* В VGFormSender закрытие открытых Bootstrap/VGModal модалок вынесено в общий helper.
+* В VGFormSender служебный параметр `closeModalsBeforeToast` не передается в настройки VGToast.
+* В VGModal persistent-модалка помечается отдельным признаком и не влияет на расчёт открытых модалок, а клик по backdrop закрывает именно активную модалку.
+* Обновлена версия пакета в `package.json`: `1.2.1` -> `1.2.2`.
 
 ---
 

package/README.md

@@ -38,7 +38,8 @@ npm i vgapp
 - `VGSidebar` — боковые панели с управлением открытием/закрытием.
 - `VGSpy` — scroll‑spy для подсветки активных ссылок по секциям.
 - `VGTabs` — вкладки с переключением контента и поддержкой URL/hash.
-- `VGToast` — всплывающие уведомления со стеком и автозакрытием.
+- `VGToast` — всплывающие уведомления со стеком и автозакрытием.
+- `VGTooltip` — tooltip/popover подсказки с Data API, автопозиционированием и закрытием по `Esc`/клику вне элемента.
 
 ## Authors
 

package/app/modules/vgalert/js/vgalert.js

@@ -3,64 +3,12 @@ import VGModal from "../../vgmodal";
 
 import { isElement, isVisible, makeRandomString, mergeDeepObject } from "../../../utils/js/functions";
 import { getSVG } from "../../module-fn";
-import { Classes} from "../../../utils/js/dom/manipulator";
+import {Classes, Manipulator} from "../../../utils/js/dom/manipulator";
 import Selectors from "../../../utils/js/dom/selectors";
 import EventHandler from "../../../utils/js/dom/event";
 import {lang_buttons, lang_messages} from "../../../utils/js/components/lang";
 import Html from "../../../utils/js/components/templater";
-
-/**
- * @typedef {Object} AjaxParams
- * @property {string} route - URL-адрес для AJAX-запроса.
- * @property {string} target - Селектор элемента, куда будет вставлен ответ.
- * @property {string} method - HTTP-метод ('get', 'post' и т.д.).
- * @property {boolean} loader - Показывать ли индикатор загрузки.
- * @property {boolean} once - Выполнить запрос только один раз.
- * @property {boolean} output - Выводить ли результат в целевой элемент.
- */
-
-/**
- * @typedef {Object} ModalParams
- * @property {boolean} centered - Центрировать ли модальное окно по вертикали.
- * @property {boolean|string} backdrop - Фоновая подложка ('static', true, false).
- * @property {boolean} overflow - Разрешить прокрутку фона при открытом окне.
- * @property {boolean} keyboard - Закрывать по нажатию Escape.
- * @property {boolean} dismiss - Закрывать при клике по подложке.
- * @property {Object} animation - Параметры анимации.
- * @property {boolean} animation.enable - Включить анимацию.
- * @property {string} animation.in - Класс анимации входа.
- * @property {string} animation.out - Класс анимации выхода.
- * @property {number} animation.delay - Задержка перед показом (мс).
- * @property {number} animation.duration - Длительность анимации (мс).
- */
-
-/**
- * @typedef {Object} ButtonConfig
- * @property {string} [element] - Готовый HTML-элемент кнопки.
- * @property {'button'|'a'} [tag='button'] - Тип элемента.
- * @property {string} [type='button'] - Атрибут type (для <button>).
- * @property {Object.<string, string>} [attr] - Дополнительные атрибуты.
- * @property {string} toggle - Атрибут данных для управления.
- * @property {string[]} class - CSS-классы кнопки.
- * @property {string} text - Текст кнопки.
- */
-
-/**
- * @typedef {Object} MessageConfig
- * @property {string} title - Заголовок сообщения.
- * @property {string} description - Описание/текст сообщения.
- */
-
-/**
- * @typedef {Object} AlertParams
- * @property {AjaxParams} ajax - Параметры AJAX-запроса.
- * @property {ModalParams} modal - Параметры модального окна.
- * @property {'confirm'|'info'} mode - Режим алерта: подтверждение или информационное.
- * @property {'danger'|'warning'|'success'|'info'} theme - Тема оформления.
- * @property {{agree: ButtonConfig, cancel: ButtonConfig}} buttons - Конфигурация кнопок.
- * @property {MessageConfig} message - Сообщение и заголовок.
- * @property {string} [icon] - SVG-иконка, соответствующая теме.
- */
+import Params from "../../../utils/js/components/params";
 
 /**
  * Константы
@@ -75,38 +23,14 @@ const NAME_KEY = "vg.alert";
 // Глобальная блокировка: предотвращаем открытие нескольких алертов
 let isAlertOpen = false;
 
-/**
- * Класс VGAlert — модальное окно подтверждения или информационное уведомление.
- *
- * @class
- * @example
- * VGAlert.call({
- *   mode: 'confirm',
- *   theme: 'danger',
- *   message: {
- *     title: 'Вы уверены?',
- *     description: 'Это действие нельзя отменить.'
- *   },
- *   buttons: {
- *     agree: { text: 'Удалить', class: ['btn-danger'] },
- *     cancel: { text: 'Отмена' }
- *   }
- * }).then(() => {
- *   console.log('Подтверждено');
- * }).catch(() => {
- *   console.log('Отменено');
- * });
- */
 class VGAlert {
-	/**
-	 * Создаёт экземпляр VGAlert.
-	 *
-	 * @param {AlertParams} params - Пользовательские параметры.
-	 * @param {'ru'|'en'} [lang='ru'] - Язык интерфейса.
-	 */
 	constructor(params = {}, lang = 'ru') {
 		this.lang = lang;
 		this._defaultParams = {
+			render: {
+				type: "modal", // modal or overlay,
+				dismiss: false,
+			},
 			ajax: {
 				route: "",
 				target: "",
@@ -169,29 +93,55 @@ class VGAlert {
 		this._params = this._setParams(params);
 	}
 
-	/**
-	 * Открывает алерт и возвращает Promise.
-	 *
-	 * @static
-	 * @param {AlertParams} options - Параметры алерта.
-	 * @param {'ru'|'en'} [lang='ru'] - Язык.
-	 * @returns {Promise<{accepted: boolean, timestamp: Date}>} Результат взаимодействия.
-	 * @throws {Error} Если алерт уже открыт.
-	 */
 	static call(options = {}, lang = 'ru') {
 		const context = new VGAlert(options, lang);
 
 		if (isAlertOpen) return Promise.reject({ accepted: false, reason: lang_messages(context.lang, NAME_KEY).reason });
 		isAlertOpen = true;
 
-		let modal = context._buildModal();
-		modal.show();
+		const getContainer = () => {
+			if (context._params.render.type === "overlay") {
+				const overlay = context._buildOverlay();
+				return {
+					element: overlay.element,
+					render: overlay.render,
+					type: 'overlay'
+				}
+			} else if (context._params.render.type === "modal") {
+				const modal = context._buildModal();
+				return {
+					element: modal._element,
+					render: modal,
+					type: 'modal'
+				}
+			}
+		};
+
+		const {element: container, render, type} = getContainer();
+
+		if (type === 'modal') {
+			render.show();
+		}
 
-		const container = modal._element;
 		const agreeBtn = Selectors.find(`[${DATA_AGREE}]`, container);
 		const cancelBtn = Selectors.find(`[${DATA_CANCEL}]`, container);
 
 		return new Promise((resolve, reject) => {
+			const closeAlert = () => {
+				if (type === 'modal') {
+					render.hide();
+					return;
+				}
+
+				if (type === 'overlay') {
+					container.remove();
+
+					if (context._params.render.dismiss) {
+						render.hide();
+					}
+				}
+			};
+
 			const handleAgree = (e) => {
 				e.preventDefault();
 				cleanup();
@@ -199,12 +149,17 @@ class VGAlert {
 					accepted: true,
 					timestamp: new Date(),
 				});
-				modal.hide();
+				closeAlert();
 			};
 
 			const handleCancel = (e) => {
 				e.preventDefault();
-				modal.hide();
+				cleanup();
+				reject({
+					accepted: false,
+					timestamp: new Date(),
+				});
+				closeAlert();
 			};
 
 			const handleKeydown = (e) => {
@@ -235,26 +190,21 @@ class VGAlert {
 			}
 
 			document.addEventListener("keydown", handleKeydown);
-			container.addEventListener("vg.modal.hide", () => {
-				cleanup();
-				reject({
-					accepted: false,
-					timestamp: new Date(),
-				});
-			});
+
+			if (type === 'modal') {
+				container.addEventListener("vg.modal.hide", () => {
+					cleanup();
+					reject({
+						accepted: false,
+						timestamp: new Date(),
+					});
+				}, {once: true});
+			}
 
 			container.focus();
 		});
 	}
 
-	/**
-	 * Инициирует алерт подтверждения на основе DOM-элемента.
-	 *
-	 * @static
-	 * @param {HTMLElement} elem - Элемент, вызвавший алерт.
-	 * @param {AlertParams} options - Параметры алерта.
-	 * @returns {void}
-	 */
 	static confirm(elem, options = {}) {
 		let lang = 'ru';
 
@@ -269,13 +219,6 @@ class VGAlert {
 		instance.run(VGAlert);
 	}
 
-	/**
-	 * Слияние пользовательских параметров с дефолтными.
-	 *
-	 * @private
-	 * @param {AlertParams} params - Пользовательские параметры.
-	 * @returns {AlertParams} Полный объект параметров.
-	 */
 	_setParams(params) {
 		const merged = mergeDeepObject(this._defaultParams, params);
 		merged.buttons = mergeDeepObject(this._elementsDefault.buttons, merged.buttons);
@@ -285,68 +228,88 @@ class VGAlert {
 		return merged;
 	}
 
-	/**
-	 * Создаёт и возвращает экземпляр модального окна с контентом алерта.
-	 *
-	 * @private
-	 * @returns {VGModal} Экземпляр модального окна.
-	 */
 	_buildModal() {
-		const id = `${CLASS_NAME_ALERT}-${crypto.randomUUID ? crypto.randomUUID().slice(0, 8) : makeRandomString()}`;
-		const $modal = Selectors.find(`.${CLASS_NAME_ALERT}-modal`);
-		if ($modal) $modal.remove();
+		const id = `${CLASS_NAME_ALERT}-${makeRandomString()}`;
 
-		const html = Html('dom');
+		return VGModal.build(id, this._params.modal, (modal) => {
+			modal._element.classList.add(`${CLASS_NAME_ALERT}-modal`);
+			const body = Selectors.find(".vg-modal-body", modal._element);
+			body.append(this._buildContent());
+		});
+	}
 
-		return VGModal.build(id, this._params.modal, (modalInstance) => {
-			const element = modalInstance._element;
-			element.classList.add(`${CLASS_NAME_ALERT}-modal`);
-			element.setAttribute("role", "alertdialog");
-			element.setAttribute("aria-modal", "true");
+	_buildContent() {
+		const html = Html('dom');
 
-			const $body = Selectors.find(".vg-modal-body", element);
-			if (!$body) return;
+		let icon = null;
 
-			let icon = null;
-			if (this._params.icon) {
-				icon = html.div({class: `${CLASS_NAME_ALERT}-content--icon`}, this._params.icon, {isHTML: true});
-			}
+		if (this._params.icon) {
+			icon = html.div(
+				{class: `${CLASS_NAME_ALERT}-content--icon`},
+				this._params.icon,
+				{isHTML: true}
+			);
+		}
 
-			const buttons = document.createElement("div");
-			Classes.add(buttons, "vg-alert-buttons");
+		const buttons = document.createElement("div");
+		Classes.add(buttons, "vg-alert-buttons");
 
-			if (this._params.mode === "confirm") {
-				this._createButton(buttons, "cancel");
-				this._createButton(buttons, "agree");
-			}
+		if (this._params.mode === "confirm") {
+			this._createButton(buttons, "cancel");
+			this._createButton(buttons, "agree");
+		}
 
-			if (this._params.mode === "info") {
-				this._createButton(buttons, "cancel");
-			}
+		if (this._params.mode === "info") {
+			this._createButton(buttons, "cancel");
+		}
 
-			let wrapper = html.div({class: `${CLASS_NAME_ALERT}-wrapper ${CLASS_NAME_ALERT}-${this._params.theme}`}, [
-				html.div({class: `${CLASS_NAME_ALERT}-content`}, [
-					icon,
-					html.div({class: `${CLASS_NAME_ALERT}-content--message`}, [
-						html.div({class: `${CLASS_NAME_ALERT}-content--title`}, this._params.message.title),
-						html.div({class: `${CLASS_NAME_ALERT}-content--description`}, this._params.message.description),
-					])
-				]),
+		return html.div(
+			{class: `${CLASS_NAME_ALERT}-wrapper ${CLASS_NAME_ALERT}-${this._params.theme}`},
+			[
+				html.div(
+					{class: `${CLASS_NAME_ALERT}-content`},
+					[
+						icon,
+						html.div(
+							{class: `${CLASS_NAME_ALERT}-content--message`},
+							[
+								html.div(
+									{class: `${CLASS_NAME_ALERT}-content--title`},
+									this._params.message.title
+								),
+								html.div(
+									{class: `${CLASS_NAME_ALERT}-content--description`},
+									this._params.message.description
+								)
+							]
+						)
+					]
+				),
 				buttons
-			]);
+			]
+		);
+	}
 
-			$body.appendChild(wrapper);
-		});
+	_buildOverlay() {
+		let targetContainers = ['.vg-modal', '.vg-sidebar'];
+		const containerWrap = this._params.relatedTarget.closest(targetContainers.join(', '));
+
+		const modal = VGModal.getOrCreateInstance(containerWrap);
+		const container = Selectors.find('.vg-modal-content', modal._element) || containerWrap;
+
+		const overlay = document.createElement('div');
+
+		overlay.className = `${CLASS_NAME_ALERT}-overlay`;
+		overlay.append(this._buildContent());
+
+		container.append(overlay);
+
+		return {
+			element: overlay,
+			render: modal,
+		};
 	}
 
-	/**
-	 * Создаёт кнопку и добавляет её в контейнер.
-	 *
-	 * @private
-	 * @param {HTMLElement} container - Родительский элемент.
-	 * @param {'agree'|'cancel'} key - Ключ кнопки.
-	 * @returns {void}
-	 */
 	_createButton(container, key) {
 		const button = this._params.buttons[key];
 		if (!button || button.element) {
@@ -385,51 +348,25 @@ const EVENT_KEY_ACCEPT  = `${NAME_KEY}.accept`;
 const EVENT_KEY_REJECT  = `${NAME_KEY}.reject`;
 const EVENT_KEY_FINALLY = `${NAME_KEY}.finally`;
 
-/**
- * Класс для работы с алертами по data-атрибутам.
- *
- * @class
- * @extends BaseModule
- * @example
- * <button data-vg-toggle="alert" data-ajax-route="/delete/1">Удалить</button>
- */
 class VGAlertConfirm extends BaseModule {
-	/**
-	 * Создаёт экземпляр VGAlertConfirm.
-	 *
-	 * @param {HTMLElement} element - DOM-элемент.
-	 * @param {AlertParams} options - Параметры.
-	 */
 	constructor(element, options = {}) {
 		super(element);
 		this._params = this._getParams(element, mergeDeepObject({}, options));
 	}
 
-	/**
-	 * Возвращает имя модуля.
-	 * @returns {string}
-	 */
 	static get NAME() {
 		return NAME;
 	}
 
-	/**
-	 * Возвращает ключевое имя с префиксом.
-	 * @returns {string}
-	 */
 	static get NAME_KEY() {
 		return NAME_KEY;
 	}
 
-	/**
-	 * Запускает логику алерта: вызывает модальное окно и обрабатывает результат.
-	 *
-	 * @param {typeof VGAlert} AlertClass - Класс алерта.
-	 * @returns {void}
-	 */
 	run(AlertClass) {
 		if (this._params.mode !== "confirm") return;
 
+		this._params.relatedTarget = this._element;
+
 		AlertClass.call(this._params)
 			.then((resolve) => {
 				if (!resolve.accepted) return Promise.reject(resolve);
@@ -447,12 +384,6 @@ class VGAlertConfirm extends BaseModule {
 			});
 	}
 
-	/**
-	 * Выполняет AJAX-запрос после подтверждения.
-	 *
-	 * @private
-	 * @returns {Promise<Object>} Ответ от сервера.
-	 */
 	_ajax() {
 		return new Promise((resolve) => {
 			this._route((status, data) => {
@@ -482,4 +413,4 @@ EventHandler.on(document, EVENT_KEY_CLICK_DATA_API, SELECTOR_DATA_TOGGLE, functi
 	});
 });
 
-export default VGAlert;
+export default VGAlert;