vgapp 0.8.0 → 0.8.2

package/app/modules/vgrollup/js/vgrollup.js

@@ -1,7 +1,32 @@
 import BaseModule from "../../base-module";
-import {execute, isDisabled, mergeDeepObject} from "../../../utils/js/functions";
+import { execute, isDisabled, mergeDeepObject } from "../../../utils/js/functions";
 import EventHandler from "../../../utils/js/dom/event";
 import Selectors from "../../../utils/js/dom/selectors";
+import {lang_buttons} from "../../../utils/js/components/lang";
+import {Classes, Manipulator} from "../../../utils/js/dom/manipulator";
+
+/**
+ * @class VGRollup
+ * @extends BaseModule
+ * @description
+ * Модуль "Rollup" — реализует функционал сворачивания/разворачивания контента.
+ * Поддерживает два режима: текст (ограничение по высоте) и элементы (ограничение по количеству).
+ * Автоматически создаёт кнопку управления, если включена.
+ *
+ * @example
+ * // Инициализация через JS
+ * VGRollup.init(document.querySelector('.rollup'), {
+ *   height: 100,
+ *   button: {
+ *     enabled: true,
+ *     more: "Показать",
+ *     less: "Свернуть"
+ *   }
+ * });
+ *
+ * // Инициализация через data-атрибут
+ * // <div class="rollup" data-vg-rollup='{"height": 80, "button": {"more": "Еще"}}'>...</div>
+ */
 
 /**
  * Constants
@@ -10,18 +35,46 @@ const NAME = 'rollup';
 const NAME_KEY = 'vg.rollup';
 const CLASS_NAME_SHOW = 'show';
 const CLASS_NAME_HIDE = 'vg-rollup-display--none';
-const SELECTOR_DATA_TOGGLE= '[data-vg-toggle="rollup"]'
-
-const EVENT_KEY_HIDE   = `${NAME_KEY}.hide`;
-const EVENT_KEY_SHOW   = `${NAME_KEY}.show`;
+const SELECTOR_DATA_TOGGLE = '[data-vg-toggle="rollup"]';
 
+const EVENT_KEY_HIDE = `${NAME_KEY}.hide`;
+const EVENT_KEY_SHOW = `${NAME_KEY}.show`;
 const EVENT_KEY_CLICK_DATA_API = `click.${NAME_KEY}.data.api`;
 
-class VGRollup  extends BaseModule {
+class VGRollup extends BaseModule {
+
+	/**
+	 * @constructor
+	 * @param {HTMLElement} element - Основной контейнер контента.
+	 * @param {Object} params - Параметры конфигурации.
+	 * @param {Object} [params.lang = 'ru'] - Локализация
+	 * @param {string} [params.content='text'] - Режим: `'text'` (ограничение по высоте) или `'elements'` (по количеству).
+	 * @param {number} [params.cnt=0] - Количество видимых элементов в режиме `'elements'`.
+	 * @param {boolean} [params.fade=true] - Добавлять эффект затухания.
+	 * @param {boolean} [params.transition=false] - Включить CSS-анимацию при переключении.
+	 * @param {boolean} [params.number=false] - Показывать количество скрытых элементов.
+	 * @param {number} [params.height=0] - Высота в px, до которой сворачивается текст.
+	 * @param {Object} [params.ellipsis] - Настройки для многоточия.
+	 * @param {number|null} [params.ellipsis.line=null] - Количество строк перед обрезкой (только для `display: -webkit-box`).
+	 * @param {string} [params.more=' еще '] - Текст для отображения количества скрытых элементов.
+	 * @param {Object} [params.button] - Настройки кнопки.
+	 * @param {boolean} [params.button.enabled=true] - Показывать кнопку управления.
+	 * @param {string} [params.button.more="Показать"] - Текст кнопки для раскрытия.
+	 * @param {string} [params.button.less="Свернуть"] - Текст кнопки для сворачивания.
+	 *
+	 * @example
+	 * new VGRollup(document.querySelector('.rollup'), {
+	 *   content: 'elements',
+	 *   elements: 'item',
+	 *   cnt: 3,
+	 *   button: { more: 'Показать ещё', less: 'Свернуть' }
+	 * });
+	 */
 	constructor(element, params = {}) {
 		super(element, params);
 
 		this._params = this._getParams(element, mergeDeepObject({
+			lang: document.documentElement.lang || 'ru',
 			content: 'text',
 			cnt: 0,
 			fade: true,
@@ -33,12 +86,22 @@ class VGRollup  extends BaseModule {
 			},
 			more: ' еще ',
 			button: {
-				enable: true,
+				enabled: true,
 				more: "Показать",
 				less: "Свернуть"
 			}
 		}, params));
 
+		/**
+		 * CSS-классы, используемые модулем.
+		 * @type {Object}
+		 * @property {string} container - Базовый класс контейнера.
+		 * @property {string} hidden - Класс для скрытого состояния.
+		 * @property {string} fade - Класс для эффекта затухания.
+		 * @property {string} ellipsis - Класс для многоточия.
+		 * @property {string} button - Класс контейнера кнопки.
+		 * @property {string} transition - Класс для анимации.
+		 */
 		this.classes = {
 			container: 'vg-rollup',
 			hidden: "vg-rollup-content--hidden",
@@ -48,201 +111,306 @@ class VGRollup  extends BaseModule {
 			transition: "vg-rollup-content--transition"
 		};
 
-		this.total       = 0;
-		this.count       = 0;
+		/**
+		 * Общее количество элементов (в режиме `elements`).
+		 * @type {number}
+		 */
+		this.total = 0;
+
+		/**
+		 * Количество видимых элементов (в режиме `elements`).
+		 * @type {number}
+		 */
+		this.count = 0;
+
+		/**
+		 * Смещение для подгрузки (если используется).
+		 * @type {number}
+		 */
+		this.offset = 0;
+
+		/**
+		 * Флаг активности режима смещения.
+		 * @type {boolean}
+		 */
+		this.isOffset = false;
+
+		// Локализация текстов кнопок
+		this._params.button.more = lang_buttons(this._params.lang, NAME)['show'];
+		this._params.button.less = lang_buttons(this._params.lang, NAME)['less'];
+		this._params.more = lang_buttons(this._params.lang, NAME)['more'];
 
 		this.build();
 	}
 
-	static get NAME() {
-		return NAME;
-	}
+	/**
+	 * Имя модуля
+	 * @type {string}
+	 */
+	static get NAME() { return NAME; }
 
-	static get NAME_KEY() {
-		return NAME_KEY
-	}
+	/**
+	 * Ключ модуля (пространство имён событий)
+	 * @type {string}
+	 */
+	static get NAME_KEY() { return NAME_KEY; }
 
+	/**
+	 * Переключает состояние контента (свёрнут/развёрнут).
+	 * @param {HTMLElement} target - Целевой контейнер контента.
+	 * @param {HTMLElement} relatedTarget - Кнопка, вызвавшая переключение.
+	 * @static
+	 * @example
+	 * VGRollup.toggle(document.querySelector('.rollup'), buttonEl);
+	 */
 	static toggle(target, relatedTarget) {
 		const instance = VGRollup.getOrCreateInstance(target);
-		let isShown = instance.isShow();
+		const isShown = instance.isShow();
 
 		if (!isShown) {
-			instance._element.classList.add(CLASS_NAME_SHOW);
-			relatedTarget.innerHTML = instance._params.button.less;
-			relatedTarget.setAttribute("aria-expanded", true);
-
-			if (instance.offset > 0) {
-				if (instance.isOffset) {
-					relatedTarget.innerHTML = instance._params.button.more;
-					relatedTarget.setAttribute("aria-expanded", true);
-				} else {
-					relatedTarget.innerHTML = instance._params.button.less;
-					relatedTarget.setAttribute("aria-expanded", false);
-				}
-			}
-
-			instance.switch(instance._element, false);
-			EventHandler.trigger(instance._element, EVENT_KEY_SHOW, { relatedTarget });
+			instance._show(relatedTarget);
 		} else {
-			let textShowNum = '',
-				isShowNum = instance._params.number;
-
+			instance._hide(relatedTarget);
+		}
+	}
 
-			if (isShowNum) {
-				let sum = (instance.total) - (instance.count);
+	/**
+	 * Открывает (разворачивает) контент.
+	 * @param {HTMLElement} relatedTarget - Элемент, вызвавший событие (кнопка).
+	 * @private
+	 */
+	_show(relatedTarget) {
+		Classes.add(this._element, CLASS_NAME_SHOW);
+		relatedTarget.innerHTML = this._params.button.less;
+		Manipulator.set(relatedTarget, 'aria-expanded', 'true');
+
+		if (this.offset > 0) {
+			relatedTarget.innerHTML = this.isOffset ? this._params.button.more : this._params.button.less;
+			Manipulator.set(relatedTarget, 'aria-expanded', this.isOffset ? "true" : "false");
+		}
 
-				if (sum > 0) {
-					textShowNum = instance._params.more + sum;
-				}
-			}
+		this.switch(this._element, false);
+		EventHandler.trigger(this._element, EVENT_KEY_SHOW, { relatedTarget });
+	}
 
-			if (instance.isOffset) {
-				relatedTarget.setAttribute("aria-expanded", true);
-			} else {
-				relatedTarget.setAttribute("aria-expanded", false);
+	/**
+	 * Закрывает (сворачивает) контент.
+	 * @param {HTMLElement} relatedTarget - Элемент, вызвавший событие (кнопка).
+	 * @private
+	 */
+	_hide(relatedTarget) {
+		let buttonText = this._params.button.more;
+		const isShowNum = this._params.number;
+
+		if (isShowNum) {
+			const sum = this.total - this.count;
+			if (sum > 0) {
+				buttonText += this._params.more + sum;
 			}
+		}
 
-			instance._element.classList.remove(CLASS_NAME_SHOW);
-			relatedTarget.innerHTML = instance._params.button.more + textShowNum;
-			instance.switch(instance._element, true);
+		Classes.remove(this._element, CLASS_NAME_SHOW);
+		Manipulator.set(relatedTarget, 'aria-expanded', 'false');
+		relatedTarget.textContent = buttonText;
 
-			EventHandler.trigger(instance._element, EVENT_KEY_HIDE, { relatedTarget });
-		}
+		this.switch(this._element, true);
+		EventHandler.trigger(this._element, EVENT_KEY_HIDE, { relatedTarget });
 	}
 
+	/**
+	 * Инициализирует отображение контента и создаёт кнопку (если нужно).
+	 * @param {HTMLElement|null} el - Элемент, который нужно инициализировать.
+	 * @param {boolean} isButtonAppend - Разрешено ли добавление кнопки.
+	 * @example
+	 * instance.build(); // перестроить текущий элемент
+	 */
 	build(el = null, isButtonAppend = true) {
-		let _this = this,
-			element = el || _this._element,
-			self_height = element.clientHeight, set_height = _this._params.height || (self_height / 2);
-
-		element.classList.add(_this.classes.container)
-
-		let isFade =        _this._params.fade,
-			isTransition =  _this._params.transition,
-			isEllipsis =    _this._params.ellipsis.line !== null,
-			isButton =      _this._params.button.enable,
-			isShowNum =     _this._params.number;
-
-		if (!isButtonAppend) _this.switch(element);
-
-		if (self_height > set_height && _this._params.content === 'text') {
-			element.classList.add(_this.classes.hidden);
-			element.style.height = set_height + "px";
-
-			ellipsis();
-			transition();
-			fade();
-			button();
-		} else if (_this._params.content === 'elements') {
-			let elementClass = _this._params.elements || 'item',
-				items = element.querySelectorAll('.' + elementClass),
-				cnt = _this._params.cnt || 5,
-				i = 1;
-
-			_this.total = items.length;
-			_this.count = cnt;
-
-			for (const item of items) {
-				if (i > cnt) {
-					item.classList.add(CLASS_NAME_HIDE)
-				}
-
-				i++;
-			}
+		const element = el || this._element;
+		const selfHeight = element.clientHeight;
+		const setHeight = this._params.height || (selfHeight / 2);
+
+		const {
+			fade,
+			transition,
+			button,
+			number: showNum,
+			content,
+			elements: elementClass,
+			cnt,
+			ellipsis: ellipsisCfg
+		} = this._params;
+
+		const isEllipsis = ellipsisCfg.line !== null;
+		const isButton = button.enabled && isButtonAppend;
+
+		Classes.add(element, this.classes.container);
+
+		if (!isButtonAppend) {
+			this.switch(element);
+			return;
+		}
 
-			if (isButton === true) isButton = (i - 1) > cnt;
+		if (content === 'text' && selfHeight > setHeight) {
+			this._setupTextContent(element, setHeight, fade, transition, isEllipsis, ellipsisCfg.line, isButton, showNum);
+		} else if (content === 'elements') {
+			this._setupElementsContent(element, elementClass, cnt, fade, transition, isEllipsis, isButton, showNum);
+		}
+	}
 
-			ellipsis();
-			transition();
-			fade();
-			button();
+	/**
+	 * Настраивает контент типа 'text' (ограничение по высоте).
+	 * @param {HTMLElement} element - Контейнер текста.
+	 * @param {number} height - Высота, до которой обрезать.
+	 * @param {boolean} fade - Использовать затухание.
+	 * @param {boolean} transition - Использовать анимацию.
+	 * @param {boolean} isEllipsis - Использовать многоточие.
+	 * @param {number|null} line - Количество строк.
+	 * @param {boolean} isButton - Показывать кнопку.
+	 * @param {boolean} showNum - Показывать счётчик.
+	 * @private
+	 */
+	_setupTextContent(element, height, fade, transition, isEllipsis, line, isButton, showNum) {
+		Classes.add(element, this.classes.hidden);
+		element.style.height = height + "px";
+
+		if (isEllipsis && line) {
+			Classes.add(element, this.classes.ellipsis);
+			element.style.lineClamp  = Number(line);
+		} else if (isEllipsis) {
+			console.error("Переменная [data-line] или параметр[line] не должны быть пустыми");
 		}
 
-		function ellipsis() {
-			if (isEllipsis) {
-				let line = _this._params.ellipsis.line;
-				isFade = false;
+		if (transition) Classes.add(element, this.classes.transition);
+		if (fade) Classes.add(element, this.classes.fade);
 
-				if (line) {
-					element.classList.add(_this.classes.ellipsis);
-					element.style.webkitLineClamp = line;
-				} else {
-					console.error("Переменная [data-line] или параметр[line] не должны быть пустыми");
-				}
-			}
-		}
+		if (isButton) this._createButton(element, '', showNum);
+	}
 
-		// TODO no work
-		function transition() {
-			if (isTransition) {
-				element.classList.add(_this.classes.transition);
+	/**
+	 * Настраивает контент типа 'elements' (ограничение по количеству).
+	 * @param {HTMLElement} element - Контейнер элементов.
+	 * @param {string} elementClass - Класс видимых элементов.
+	 * @param {number} cnt - Количество видимых элементов.
+	 * @param {boolean} fade - Использовать затухание.
+	 * @param {boolean} transition - Использовать анимацию.
+	 * @param {boolean} isEllipsis - Использовать многоточие.
+	 * @param {boolean} isButton - Показывать кнопку.
+	 * @param {boolean} showNum - Показывать счётчик.
+	 * @private
+	 */
+	_setupElementsContent(element, elementClass, cnt, fade, transition, isEllipsis, isButton, showNum) {
+		const items = Selectors.findAll('.' + elementClass, element);
+		this.total = items.length;
+		this.count = cnt;
+
+		items.forEach((item, index) => {
+			if (index >= cnt) {
+				Classes.add(item, CLASS_NAME_HIDE);
 			}
-		}
+		});
 
-		function fade() {
-			if (isFade) {
-				element.classList.add(_this.classes.fade);
-			}
-		}
+		const shouldShowButton = isButton && items.length > cnt;
 
-		function button() {
-			if (isButtonAppend) {
-				element.setAttribute("id", element.id);
+		if (isEllipsis) Classes.add(element, this.classes.ellipsis);
+		if (transition) Classes.add(element, this.classes.transition);
+		if (fade) Classes.add(element, this.classes.fade);
 
-				if (isButton) {
-					let textShowNum = '';
+		if (shouldShowButton) {
+			const sum = this.total - this.count;
+			const textShowNum = showNum && sum > 0 ? this._params.more + sum : '';
+			this._createButton(element, textShowNum, false);
+		}
+	}
 
-					if (isShowNum) {
-						let sum = (_this.total) - (_this.count);
+	/**
+	 * Создаёт кнопку управления разворачиванием.
+	 * @param {HTMLElement} element - Целевой контейнер.
+	 * @param {string} textNum - Дополнительный текст (например, количество).
+	 * @param {boolean} showNum - Флаг отображения числа (не используется).
+	 * @private
+	 */
+	_createButton(element, textNum = '', showNum = false) {
+		if (!element.id) {
+			element.id = `vg-rollup-${Math.random().toString(36).substr(2, 9)}`;
+		}
 
-						if (sum > 0) {
-							textShowNum = _this._params.more + sum;
-						}
-					}
+		const btnTextMore = this._params.button.more;
+		const btnHTML = `<div class="${this.classes.button}">
+            <a href="#" aria-expanded="false" data-vg-toggle="rollup" data-vg-target="#${element.id}">
+                ${btnTextMore}${textNum}
+            </a>
+        </div>`;
 
-					let btnTextMore = _this._params.button.more;
-					element.insertAdjacentHTML("afterend", "<div  class=\"" + _this.classes.button + "\"><a href=\"#\" aria-expanded=\"false\" data-vg-toggle=\"rollup\" data-vg-target=\"#" + element.id + "\">" + btnTextMore + textShowNum + "</a></div>");
-				}
-			}
-		}
+		element.insertAdjacentHTML("afterend", btnHTML);
 	}
 
+	/**
+	 * Переключает состояние скрытия/показа контента.
+	 * @param {HTMLElement} el - Элемент контента.
+	 * @param {boolean} switcher - Если `true` — свернуть, иначе — полностью открыть.
+	 * @example
+	 * instance.switch(element, true); // свернуть
+	 * instance.switch(element, false); // развернуть
+	 */
 	switch(el, switcher = false) {
 		if (switcher && !this.isOffset) {
-			this.build(el, false);
+			const { content } = this._params;
+			const selfHeight = el.clientHeight;
+			const setHeight = this._params.height || selfHeight / 2;
 
-			if (this._params.offset > 0) {
-				this.offset = this._params.offset;
-				if (this.offset > 0) this.isOffset = true;
-			}
-		} else {
-			el.classList.remove(this.classes.hidden);
-			el.classList.remove(this.classes.ellipsis);
-			el.classList.remove(this.classes.fade);
+			if (content === 'text' && selfHeight > setHeight) {
+				Classes.add(el, this.classes.hidden);
+				el.style.height = setHeight + "px";
 
-			el.removeAttribute("style");
+				if (this._params.ellipsis.line) {
+					Classes.add(el, this.classes.ellipsis);
+					el.style.lineClamp = this._params.ellipsis.line;
+				}
 
-			if (this._params.content === 'elements') {
-				let className = this._params.elements;
+				if (this._params.fade) Classes.add(el, this.classes.fade);
+				if (this._params.transition) Classes.add(el, this.classes.transition);
+			} else if (content === 'elements') {
+				const items = Selectors.findAll('.' + this._params.elements, el);
+				items.forEach((item, index) => {
+					if (index >= this.count) {
+						Classes.add(item, CLASS_NAME_HIDE);
+					}
+				});
+			}
 
-				let items = Selectors.findAll('.' + className, el);
+			Classes.add(el, this.classes.container);
+		} else {
+			const { hidden, ellipsis, fade } = this.classes;
+			Classes.remove(el, [hidden, ellipsis, fade]);
+			Manipulator.remove(el, 'style');
 
-				if (items.length) {
-					items.forEach((item) => item.classList.remove(CLASS_NAME_HIDE))
-				}
+			if (this._params.content === 'elements') {
+				const items = Selectors.findAll('.' + this._params.elements, el);
+				items.forEach(item => Classes.remove(item, CLASS_NAME_HIDE));
 			}
 		}
 	}
 
+	/**
+	 * Проверяет, развёрнут ли контент.
+	 * @returns {boolean} `true`, если контент развёрнут.
+	 * @example
+	 * if (instance.isShow()) { ... }
+	 */
 	isShow() {
-		return this._element.classList.contains(CLASS_NAME_SHOW);
+		return Classes.has(this._element, CLASS_NAME_SHOW);
 	}
 
 	/**
-	 * Инициализация
-	 * @param element
-	 * @param params
-	 * @param callback
+	 * Инициализирует экземпляр VGRollup для элемента.
+	 * @param {HTMLElement} element - Целевой элемент.
+	 * @param {Object} params - Параметры конфигурации.
+	 * @param {Function} [callback] - Колбэк, вызываемый после инициализации.
+	 * @static
+	 * @example
+	 * VGRollup.init(document.querySelector('.rollup'), { height: 100 }, (instance) => {
+	 *   console.log('Rollup инициализирован:', instance);
+	 * });
 	 */
 	static init(element, params = {}, callback) {
 		const instance = VGRollup.getOrCreateInstance(element, params);
@@ -251,19 +419,19 @@ class VGRollup  extends BaseModule {
 }
 
 /**
- * Data API implementation
+ * Подключает обработчик кликов по data-атрибуту для автоматической инициализации.
+ * @listens click
+ * @event
  */
 EventHandler.on(document, EVENT_KEY_CLICK_DATA_API, SELECTOR_DATA_TOGGLE, function (event) {
-	const target = Selectors.getElementFromSelector(this);
-	if (!target) return;
-
 	if (['A', 'AREA'].includes(this.tagName)) {
-		event.preventDefault()
+		event.preventDefault();
 	}
 
-	if (isDisabled(this)) {
-		return
-	}
+	if (isDisabled(this)) return;
+
+	const target = Selectors.getElementFromSelector(this);
+	if (!target) return;
 
 	VGRollup.toggle(target, this);
 });