vgapp 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# VEGAS-APP 0.8.2 (Январь, 4, 2025)
+* Оптимизирован модуль VGRollup, см. файл readme.md
+* Оптимизирован модуль VGSidebar, см. файл readme.md
+* Оптимизирован модуль VGTabs, см. файл readme.md
+* Оптимизирован модуль VGSpy, см. файл readme.md
+* Оптимизирован модуль VGToast, см. файл readme.md
+* Оптимизирован и дополнен модуль VGSelect, см. файл readme.md
+
+---
+
 # VEGAS-APP 0.8.1 (Январь, 2, 2025)
 * Оптимизирован и дополнен модуль VGLoadMore, см. файл readme.md
 

package/app/langs/en/buttons.json

@@ -12,5 +12,13 @@
     "show": "I'm showing you...",
     "text-ajax": "Upload more",
     "text-more": "Show more"
+  },
+  "rollup": {
+    "less": "Roll up",
+    "show": "Show",
+    "more": " more "
+  },
+  "select": {
+    "load-more": "Upload more"
   }
 }

package/app/langs/en/messages.json

@@ -28,5 +28,8 @@
     "title": "Default header",
     "description": "Description of the current action",
     "reason": "Alert already open"
+  },
+  "select": {
+    "loading": "Loading"
   }
 }

package/app/langs/en/titles.json

@@ -2,5 +2,8 @@
   "errors": {
     "title": "Error",
     "titles": "Errors"
+  },
+  "select": {
+    "search": "Search..."
   }
 }

package/app/langs/ru/buttons.json

@@ -12,5 +12,13 @@
     "show": "Показываю...",
     "text-ajax": "Загрузить еще",
     "text-more": "Показать еще"
+  },
+  "rollup": {
+    "less": "Свернуть",
+    "show": "Показать",
+    "more": " еще "
+  },
+  "select": {
+    "load-more": "Загрузить еще"
   }
 }

package/app/langs/ru/messages.json

@@ -28,5 +28,8 @@
     "title": "Заголовок по умолчанию",
     "description": "Описание текущего действия",
     "reason": "Алерт уже открыт"
+  },
+  "select": {
+    "loading": "Загрузка"
   }
 }

package/app/langs/ru/titles.json

@@ -2,5 +2,8 @@
   "errors": {
     "title": "Ошибка",
     "titles": "Ошибки"
+  },
+  "select": {
+    "search": "Поиск..."
   }
 }

package/app/modules/vgloadmore/js/vgloadmore.js

@@ -3,10 +3,65 @@ import EventHandler from "../../../utils/js/dom/event";
 import { execute, isObject, mergeDeepObject, normalizeData } from "../../../utils/js/functions";
 import Selectors from "../../../utils/js/dom/selectors";
 import { Manipulator } from "../../../utils/js/dom/manipulator";
-import {lang_buttons} from "../../../utils/js/components/lang";
+import { lang_buttons } from "../../../utils/js/components/lang";
+
+/**
+ * @typedef {Object} VGLoadMoreParams
+ * @property {string} [lang='ru'] - Язык интерфейса (используется для локализации)
+ * @property {number} limit - Количество элементов, загружаемых за один раз
+ * @property {number} offset - Начальный сдвиг при загрузке
+ * @property {boolean} output - Вставлять ли ответ в DOM
+ * @property {boolean} autohide - Автоматически скрывать/удалять кнопку при достижении конца
+ * @property {boolean} animate - Анимировать появление новых элементов
+ * @property {string} append - Позиция вставки: 'after' (в конец) или 'before' (в начало)
+ * @property {string} mode - Режим загрузки: 'button' или 'scroll'
+ * @property {number} threshold - Отступ в пикселях для срабатывания при прокрутке
+ * @property {boolean} debug - Включить отладочные сообщения в консоли
+ * @property {boolean} detach - Удалять кнопку из DOM после использования
+ * @property {Object} button - Настройки кнопки
+ * @property {string} button.text - Текст кнопки по умолчанию
+ * @property {string} button.send - Текст во время AJAX-загрузки
+ * @property {string} button.show - Текст во время статической загрузки
+ * @property {boolean} button.loader - Показывать лоадер
+ * @property {string[]} button.classes - CSS-классы кнопки
+ * @property {Object} ajax - Настройки AJAX-запроса
+ * @property {string} ajax.route - URL для загрузки данных
+ * @property {string} ajax.target - Селектор контейнера для вставки
+ * @property {string} ajax.method - HTTP-метод ('get', 'post')
+ * @property {boolean} ajax.loader - Использовать лоадер
+ * @property {boolean} ajax.once - Загружать только один раз
+ * @property {boolean} ajax.output - Выводить ли ответ
+ * @property {Object} ajax.data - Дополнительные данные для запроса
+ */
+
+/**
+ * @class VGLoadMore
+ * @extends BaseModule
+ * @description
+ * Модуль подгрузки контента по кнопке или при прокрутке.
+ * Поддерживает как статическую подгрузку скрытых элементов из DOM,
+ * так и AJAX-загрузку с сервера. Имеет гибкую настройку через data-атрибуты,
+ * поддержку языков, анимаций и отладку.
+ *
+ * @example
+ * <!-- Простая подгрузка по кнопке -->
+ * <div data-vgloadmore data-limit="3" data-elements="item">
+ *     <div class="item vg-collapse">Элемент 1</div>
+ *     <div class="item vg-collapse">Элемент 2</div>
+ *     ...
+ * </div>
+ *
+ * @example
+ * <!-- AJAX-подгрузка при прокрутке -->
+ * <div data-vgloadmore
+ *      data-ajax-route="/api/load"
+ *      data-mode="scroll"
+ *      data-threshold="200">
+ * </div>
+ */
 
 const NAME = 'loadmore';
-const NAME_KEY = 'vg.loadmore';
+const NAME_KEY = 'vg.' + NAME;
 const SELECTOR_DATA_TOGGLE = '[data-vg-toggle="loadmore"]';
 const SELECTOR_DATA_MODULE = '[data-vgloadmore]';
 
@@ -17,9 +72,29 @@ const CLASS_NAME_SHOW = 'show';
 const EVENT_KEY_CLICK_DATA_API = `click.${NAME_KEY}.data.api`;
 
 class VGLoadMore extends BaseModule {
+	/**
+	 * Имя модуля
+	 * @type {string}
+	 */
+	static get NAME() { return NAME; }
+
+	/**
+	 * Ключ события модуля
+	 * @type {string}
+	 */
+	static get NAME_KEY() { return NAME_KEY; }
+
+	/**
+	 * @private
+	 */
 	constructor(element, params) {
 		super(element, params);
 
+		/**
+		 * Параметры модуля
+		 * @type {VGLoadMoreParams}
+		 * @private
+		 */
 		this._params = this._getParams(element, mergeDeepObject({
 			lang: document.documentElement.lang || 'ru',
 			limit: 0,
@@ -50,10 +125,28 @@ class VGLoadMore extends BaseModule {
 			}
 		}, params));
 
+		/**
+		 * Обсервер пересечения (для режима scroll)
+		 * @type {IntersectionObserver|null}
+		 * @private
+		 */
 		this._observer = null;
+
+		/**
+		 * Режим прокрутки включён
+		 * @type {boolean}
+		 * @private
+		 */
 		this._isScrollMode = this._params.mode === 'scroll';
+
+		/**
+		 * Элемент является триггером (имеет data-vg-toggle)
+		 * @type {boolean}
+		 * @private
+		 */
 		this._isToggleElement = element.hasAttribute('data-vg-toggle');
 
+		// Локализация текстов кнопок
 		this._params.button.send = lang_buttons(this._params.lang, NAME)['send'];
 		this._params.button.show = lang_buttons(this._params.lang, NAME)['show'];
 
@@ -70,15 +163,20 @@ class VGLoadMore extends BaseModule {
 		}
 	}
 
-	static get NAME() { return NAME; }
-	static get NAME_KEY() { return NAME_KEY; }
-
+	/**
+	 * Инициализация, если элемент — кнопка-триггер
+	 * @private
+	 */
 	_initializeAsButton() {
 		if (this._isScrollMode) {
 			this._initScrollMode();
 		}
 	}
 
+	/**
+	 * Инициализация контейнера с элементами
+	 * @private
+	 */
 	_initializeContainer() {
 		const { elements: itemClass, limit } = this._params;
 		const container = this._element;
@@ -104,6 +202,11 @@ class VGLoadMore extends BaseModule {
 		}
 	}
 
+	/**
+	 * Создаёт и вставляет кнопку управления
+	 * @param {HTMLElement} container - Контейнер, рядом с которым вставляется кнопка
+	 * @private
+	 */
 	_createAndInsertButton(container) {
 		const button = document.createElement('button');
 		const buttonText = normalizeData(container.dataset.buttonText) || this._params.button.text;
@@ -136,11 +239,19 @@ class VGLoadMore extends BaseModule {
 		container.parentNode.insertBefore(button, container.nextSibling);
 	}
 
+	/**
+	 * Инициализирует режим прокрутки
+	 * @private
+	 */
 	_initScrollMode() {
 		this._setupIntersectionObserver();
 		this._observeLastVisibleItem();
 	}
 
+	/**
+	 * Настраивает IntersectionObserver для отслеживания видимости последнего элемента
+	 * @private
+	 */
 	_setupIntersectionObserver() {
 		if (this._observer) return;
 
@@ -158,6 +269,10 @@ class VGLoadMore extends BaseModule {
 		});
 	}
 
+	/**
+	 * Начинает отслеживание последнего видимого элемента
+	 * @private
+	 */
 	_observeLastVisibleItem() {
 		if (!this._observer) return;
 
@@ -173,6 +288,13 @@ class VGLoadMore extends BaseModule {
 		}
 	}
 
+	/**
+	 * Основной метод подгрузки — вызывается по клику или при прокрутке
+	 * @param {Function} [callback] - Колбэк, вызываемый после загрузки
+	 * @fires VGLoadMore#vg.loadmore.before.load
+	 * @fires VGLoadMore#vg.loadmore.loaded
+	 * @public
+	 */
 	toggle(callback) {
 		this._params.debug && console.log('[VGLoadMore] toggle()');
 
@@ -187,6 +309,11 @@ class VGLoadMore extends BaseModule {
 		this._params.ajax.route ? this.ajax(callback) : this.staticLoad(callback);
 	}
 
+	/**
+	 * Выполняет AJAX-запрос для подгрузки данных
+	 * @param {Function} [callback] - Колбэк после завершения
+	 * @private
+	 */
 	ajax(callback) {
 		const targetSelector = this._params.ajax.target?.trim();
 		let targetEl = null;
@@ -194,16 +321,16 @@ class VGLoadMore extends BaseModule {
 		if (targetSelector) {
 			targetEl = Selectors.find(targetSelector);
 		} else {
-			targetEl = this._element
+			targetEl = this._element;
 		}
 
-		const originalText = this._params.button.text;
-
 		if (!targetEl) {
 			console.error('[VGLoadMore] target элемент не найден:', this._params.ajax.target);
 			return;
 		}
 
+		const originalText = this._params.button.text;
+
 		this._params.ajax.data = { limit: this._params.limit, offset: this._params.offset };
 
 		this._route((status, data, responseTarget) => {
@@ -233,6 +360,11 @@ class VGLoadMore extends BaseModule {
 		});
 	}
 
+	/**
+	 * Подгружает элементы из DOM (статический режим)
+	 * @param {Function} [callback] - Колбэк после завершения
+	 * @private
+	 */
 	staticLoad(callback) {
 		const container = Selectors.find(this._params.target) || this._element.parentNode;
 		const items = Selectors.findAll(`.${this._params.elements}`, container);
@@ -270,6 +402,11 @@ class VGLoadMore extends BaseModule {
 		execute(callback, [this, this._element]);
 	}
 
+	/**
+	 * Восстанавливает состояние кнопки (включает, устанавливает текст)
+	 * @param {string} text - Текст кнопки
+	 * @private
+	 */
 	_restoreElementState(text) {
 		const isButton = this._isToggleElement || this._element.tagName === 'BUTTON';
 		if (isButton && !this._isScrollMode) {
@@ -278,6 +415,10 @@ class VGLoadMore extends BaseModule {
 		}
 	}
 
+	/**
+	 * Автоматически скрывает или удаляет элемент при завершении
+	 * @private
+	 */
 	_autohideTrigger() {
 		if (this._isScrollMode) {
 			this._observer?.disconnect();
@@ -287,12 +428,19 @@ class VGLoadMore extends BaseModule {
 		}
 	}
 
+	/**
+	 * Полная деинициализация модуля
+	 * @override
+	 */
 	dispose() {
 		this._observer?.disconnect();
 		super.dispose();
 	}
 }
 
+/**
+ * Автоматическая инициализация на элементах с data-vgloadmore
+ */
 EventHandler.on(document, 'DOMContentLoaded', () => {
 	Selectors.findAll(SELECTOR_DATA_MODULE).forEach(el => {
 		!el.dataset.initialized && VGLoadMore.getOrCreateInstance(el);
@@ -300,6 +448,9 @@ EventHandler.on(document, 'DOMContentLoaded', () => {
 	});
 });
 
+/**
+ * Обработка кликов по элементам с data-vg-toggle="loadmore"
+ */
 EventHandler.on(document, EVENT_KEY_CLICK_DATA_API, SELECTOR_DATA_TOGGLE, function (event) {
 	['A', 'AREA'].includes(this.tagName) && event.preventDefault();
 	VGLoadMore.getOrCreateInstance(this).toggle();