@topvisor/ui 1.1.0 → 1.2.0

package/src/core/core/core.ts

@@ -0,0 +1,287 @@
+import { reactive, watch } from 'vue';
+import { isApp, isMobile, isRetina } from '@/core/utils/device';
+import Events from '@/core/core/events';
+import state from '@/core/core/state';
+import options from '@/core/core/options';
+import preloaders from '@/core/core/preloaders';
+import type { Options as TopNoticeOptions } from '@/components/core/notice/utils';
+import type { Style as TopNoticeStyle } from '@/components/core/notice/item/types';
+
+/**
+ * Статический класс с текущим состоянимем UI
+ *
+ * @docs https://ui.topvisor.com/?path=/docs/core-core--docs
+ */
+export default class Core {
+
+	static state = reactive({ ...state });
+
+	static preloaders = preloaders;
+
+	static widthForMobile = options.widthForMobile;
+
+	static themeName = options.themeName;
+
+	static matchMediaIsMobile?: MediaQueryList;
+
+	static $? = $;
+
+	static Events = Events;
+
+	/**
+	 * Различные флаги, необходимые для работы UI
+	 */
+	static flags = reactive({ needLoadNotice: false });
+
+	static _setState() {
+		this.$ = $;
+
+		Core.matchMediaIsMobile = window.matchMedia(`(max-width: ${Core.widthForMobile}px)`);
+
+		Core.state.isMobileUA = isMobile();
+		Core.state.isRetina = isRetina();
+		Core.state.isApp = isApp();
+
+		Core.useDocumentClassModificators();
+
+		Core.useIsHidden();
+
+		Core.setStateByWindowSize();
+
+		// пересчет значений, зависящих от размеров окна
+		// todo Исправить опечатку
+		Core.Events.addOnReize(Core.onResize);
+
+		Core.onResize();
+
+		Core.saveToCookie();
+
+		Core.useCtrlClasses();
+	}
+
+	private static useDocumentClassModificators() {
+		// При наблюдении за Map нет oldValue
+		watch(() => [...Core.state.documentClassModificators], (newValue, oldValue) => {
+			let classesDeleted = new Set<string>();
+
+			oldValue?.forEach(([_id, className]) => classesDeleted.add(className));
+			newValue.forEach(([_id, className]) => classesDeleted.delete(className));
+
+			classesDeleted.forEach((className) => document.documentElement.classList.remove(className));
+
+			newValue.forEach(([_id, className]) => document.documentElement.classList.add(className));
+		}, { immediate: true });
+	}
+
+	private static useIsHidden() {
+		document.addEventListener('visibilitychange', () => {
+			Core.state.isHidden = document.hidden;
+		});
+
+		Core.state.isHidden = document.hidden;
+	}
+
+	private static setStateByWindowSize() {
+		Core.state.isMobile = !!Core.matchMediaIsMobile?.matches;
+		Core.state.isLandscape = (window.innerWidth > window.innerHeight);
+		Core.state.isPortrait = !Core.state.isLandscape;
+		Core.state.size = (window.innerWidth > window.innerHeight) ? window.innerWidth : window.innerHeight;
+
+		Core.saveToCookie();
+	}
+
+	private static onResize() {
+		Core.setStateByWindowSize();
+	}
+
+	/**
+	 * Сохранить информацию об устройстве в cookie
+	 */
+	private static saveToCookie() {
+		const device = [
+			1,
+			window.innerWidth,
+			window.innerHeight,
+			window.devicePixelRatio,
+			Number(Core.state.isMobile),
+			Number(Core.state.isRetina),
+		];
+
+		document.cookie = 'device=' + device.join(',') + '; path=/;';
+	}
+
+	/**
+	 * Добавить установку класса при нажатии ctrl (cmd) / alt
+	 */
+	private static useCtrlClasses() {
+		const bodyClassList = document.body.classList;
+
+		document.addEventListener('keydown', (e) => {
+			if (e.ctrlKey || e.metaKey) bodyClassList.add('top-body-press_ctrl');
+			if (e.altKey) bodyClassList.add('top-body-press_alt');
+		});
+
+		document.addEventListener('keyup', () => bodyClassList.remove('top-body-press_ctrl', 'top-body-press_alt'));
+		document.addEventListener('keypress', () => bodyClassList.remove('top-body-press_ctrl', 'top-body-press_alt'));
+
+		window.addEventListener('blur', () => bodyClassList.remove('top-body-press_ctrl', 'top-body-press_alt'));
+	}
+
+	/**
+	 * Вывести на экране сообщение в стилизации под push уведомление
+	 *
+	 * Для удобства работы со словарем, принимает один парамтер `text` и первую строку из него использует как `title`.
+	 * Данное поведение можно изменить, передав в параметрах `options.title`
+	 *
+	 * Для вывода используется компонент TopNotice, требует его подклчючения
+	 *
+	 * @docs https://ui.topvisor.com/?path=/docs/components-core-notice--docs
+	 */
+	static notice = async (text: string, style: TopNoticeStyle, options?: TopNoticeOptions) => {
+		Core.flags.needLoadNotice = true;
+
+		const noticeComponet = await import('@/components/core/notice/notice.vue');
+
+		return noticeComponet.show(text, style, options);
+	};
+
+	/**
+	 * Вставить css стили на страницу по ссылке с автоматическим добавлением правил media
+	 *
+	 * Правила media:
+	 * - Файлы *.m.css будут грузиться, только на экранах с шириной менее, чем Core.widthForMobile
+	 * - Файлы *.pc.css будут грузиться, только на экранах с шириной более, чем Core.widthForMobile
+	 *
+	 * Настройкой Core.widthForMobile можно управлять через plugin: @topvisor/ui/plugin/core
+	 *
+	 * @param fileNames - список ссылок на css файлы
+	 * @param useSync - использовать синхронную загрузку css, только для css с того же домена. В синхронном режиме стили предзагружаются независимо от
+	 * media
+	 */
+	static insertCSSLinkToPage = (fileNames: Array<string>, useSync = false) => {
+		const cssFilesByOptions = new Map();
+		cssFilesByOptions.set('::', []);
+
+		fileNames.forEach(filename => {
+			let m = false;
+			let pc = false;
+
+			if (filename.match(/\.m\./)) {
+				m = true;
+			}
+			if (filename.match(/\.pc\./)) {
+				pc = true;
+			}
+
+			const key = `${m}:${pc}`;
+			if (!cssFilesByOptions.has(key)) {
+				cssFilesByOptions.set(`${m}:${pc}`, []);
+			}
+			cssFilesByOptions.get(`${m}:${pc}`).push(filename);
+		});
+
+		const promises: Array<Promise<unknown>> = [];
+
+		cssFilesByOptions.forEach((fileNames, options: string) => {
+			if (!fileNames.length) {
+				return;
+			}
+
+			const [m, pc] = options.split(':').map(item => item === 'true');
+
+			let media = 'all';
+			if (m) {
+				media = '(max-width: ' + Core.widthForMobile + 'px)';
+			}
+			if (pc) {
+				media = '(min-width: ' + Core.widthForMobile + 'px)';
+			}
+
+			const promisesI = Core._insertToPage(fileNames, media, useSync);
+			promisesI.forEach(promise => promises.push(promise));
+		});
+
+		return Promise.all(promises);
+	};
+
+	private static _insertToPage = (fileNames: Array<string>, media: string, useSync: boolean) => {
+		const promises: Array<Promise<unknown>> = [];
+
+		fileNames.forEach(fileName => {
+			// синхронная загрузка, чтобы функция не выполнилась раньше загрузки стилей
+			if (useSync) {
+				const request = new XMLHttpRequest();
+				request.open('GET', fileName, false);
+				request.send();
+			}
+
+			const id = 'topCSSLink-' + fileName.replace(/\W/g, '-');
+
+			// стиль уже загружен
+			if (window.hasOwnProperty(id)) return;
+
+			let resolve: Function;
+			let reject: Function;
+			const promise = new Promise((_resolve, _reject) => {
+				resolve = _resolve;
+				reject = _reject;
+			});
+			promises.push(promise);
+
+			const elLink = document.createElement('link');
+			elLink.id = id;
+			elLink.rel = 'stylesheet';
+			elLink.media = media;
+			elLink.href = fileName;
+			elLink.onload = () => resolve();
+			elLink.onerror = () => reject();
+
+			document.head.append(elLink);
+		});
+
+		return promises;
+	};
+
+	/**
+	 * Вставить css стили на страницу с автоматическим добавлением правил media
+	 *
+	 * Загрузка с Vite:
+	 *
+	 * ```js
+	 * import style from '/style.css?inline';
+	 *
+	 * insertToPageAsInine(style);
+	 * ```
+	 *
+	 * Загрузка с fetch:
+	 *
+	 * ```js
+	 * const style = await fetch('./style.css');
+	 *
+	 * insertToPageAsInine(style);
+	 * ```
+	 *
+	 * @param style - css стили в строке
+	 * @param type - если указать 'm' или 'pc', то стили будут применяться по условию в зависимости от настройки this.widthForMobile
+	 *
+	 * @see insertToPage
+	 */
+	static insertStyleToPage = (style: string, type: '' | 'm' | 'pc' = '') => {
+		let media = 'all';
+
+		if (type === 'm') {
+			media = '(max-width: ' + Core.widthForMobile + 'px)';
+		}
+
+		if (type === 'pc') {
+			media = '(min-width: ' + Core.widthForMobile + 'px)';
+		}
+
+		const elStyle = document.createElement('style');
+		elStyle.innerHTML = style;
+		elStyle.media = media;
+
+		document.head.append(elStyle);
+	};
+
+}

package/src/core/core/events/resize.ts

@@ -0,0 +1,47 @@
+import { debounce } from '@/core/utils/lodash';
+
+const onResizeDelay = 100;
+
+type TopUIEvent = UIEvent & { topEvent: { widthDiff: number, hightDiff: number } }
+
+/**
+ * Установленные обрабочики на событие изменения размеров окна
+ */
+const onResizeListeners: Map<(e: TopUIEvent) => any, (e: TopUIEvent) => any> = new Map();
+
+// зафиксированное состояние размеров окна
+const windowSize = {
+	width: window.innerWidth,
+	height: window.innerHeight,
+};
+
+/**
+ * Добавить обработчик на событие изменения размеров экрана
+ * вызов таких обработчиков будет опмизирован и объединен в одно событие
+ */
+export const addOnReize = (listener: (this: HTMLElement, e: TopUIEvent) => void) => {
+	onResizeListeners.set(listener, listener);
+};
+
+/**
+ * Удаление обработчика на событие изменений размеров экрана
+ */
+export const removeOnResize = (listener: (this: HTMLElement, e: TopUIEvent) => void) => {
+	onResizeListeners.delete(listener);
+};
+
+const onResize = debounce((e: UIEvent) => {
+	const topUIEvent = e as TopUIEvent;
+
+	topUIEvent.topEvent = {
+		widthDiff: windowSize.width - window.innerWidth,
+		hightDiff: windowSize.height - window.innerHeight,
+	};
+
+	windowSize.width = window.innerWidth;
+	windowSize.height = window.innerHeight;
+
+	onResizeListeners.forEach((callback) => callback(topUIEvent));
+}, onResizeDelay);
+
+window.addEventListener('resize', onResize);

package/src/core/core/events.ts

@@ -0,0 +1,6 @@
+import { addOnReize, removeOnResize } from './events/resize';
+
+export default {
+	addOnReize,
+	removeOnResize,
+};

package/src/core/core/jQuery.mdx

@@ -0,0 +1,41 @@
+# jQuery
+
+jQuery можно использовать только **понимая** необходимость этого, во всех остальных случаях необходимо искать решения во Vue и использовать чистый js.
+
+**UI не включает в себя jQuery**, при необходимости его нужно подклчюить на сайте перед подключением UI. Если jQuery не загружен, компоненты не будут
+реализовывать функционал, который от него зависит.
+
+> jQuery в UI используется как набор не реактивных **утилит**
+
+> Посредству общего ядра jQuery реализует удобные инетрфейсы **Datepicker** и **Dialog**, которые полностью выигрывают свои альтернативы по **объему**
+> кода и по **скорости**
+
+## Для чего нужен jQuery в UI:
+
+- Для подключения функциаонльно сложных компонентов, вне видимости приложения Vue
+    - Datepicker
+    - Dialog
+    - Autocomplete
+- Для подключения виджетов с визуальным оформлением и поддержкой работы на разных устройствах:
+    - Sortable
+    - Draggable
+- Использование утилит при работе с `DOM` вне Vue:
+    - Упрощенный синтаксис для работы с `DOM`, а значит меньшие затраты по времени на разработку и меньший вес сборки
+    - `$.animate` - реализация анимаций элементов
+    - `$.data` - сохранение данных в `DOM` элементе с поддержкой разных типов
+
+## Какие есть альтернативы jQuery, исследования от 2024 года:
+
+- Для **Datepicker** в сообществе Vue есть несколько альтернатив, наиболее полная из них, которая предоставляет практически такой же интерфейс как `$.
+dialog` по размеру превышает весь **jQuery** вместе с его **Dialog**, а из-за того, что используются реактивные состояния, более требовательна к
+  ресурсам
+- Для **Sortable** есть альтернатива, предоставляемая https://vueuse.org/, в которой используется https://github.com/SortableJS/Sortable. Данное
+  решение имеет более огарниченные возможности, а по весу сопоставимо с `$.sortable`
+- Для **Dialog** альтеранив не нашлось. Каждая сторонняя UI самостоятельно реализует диалоговые окна, и центролизованной библиотеки, которая могла
+  бы генерировать окна со всей их событийной моделью, на данный момент кроме `$.dialog` нет
+
+Благодаря единому ядру **jQuery** предлагает решения, которые написаны лаконичным коротким синтаксисом, благодаря чему его бибилиотеки весят меньше
+всех альтернатив.
+
+Благодаря долгому присутсвтивию в Web **jQuery** предоставила решения с наиболее широкими настройками, не заточенными под определенные современные
+js фреймворки.

package/src/core/core/options.ts

@@ -0,0 +1,51 @@
+/**
+ * Конфигурация UI
+ *
+ * Начальные значений устанавилаются при подклчюении Core во Vue приложение через app.use(PluginCore, options)
+ */
+export default {
+
+	/**
+	 * Имя темы оформления
+	 *
+	 * В данный момент не используется для загрузки css
+	 *
+	 * @todo Реализовать загрузки и замену css темы на стороне UI
+	 *
+	 * @see https://ui.topvisor.com/?path=/docs/core-theme--docs
+	 */
+	themeName: 'light' as 'light' | 'dark' | string,
+
+	/**
+	 * CSS-классы модификаторы для документа страницы
+	 *
+	 * Могут испоьзвоаться компонентами для включения необхоимых режимов отображения страницы
+	 *
+	 * Разные компоненты могут добавлять один и тот же класс, чтобы не было конфликтов каждый компонент управляет только своим классом:
+	 * - Ключ - уникальное имя компонента, например в setup: `const uid = Math.random();`
+	 * - Значение - класс модификатора
+	 */
+	documentClassModificators: new Map<string | number, string>(),
+
+	/**
+	 * Базовая ширина страницы для отображения ПК / Мобильной версии сайта
+	 *
+	 * @see Core state isMobile
+	 */
+	widthForMobile: 900,
+
+	/**
+	 * Формат даты, который будет испоьзоваться по умолчанию для вывода даты, как правило, завсит от текущего пользователя
+	 */
+	dateFormat: 'Y-m-d',
+
+	/**
+	 * Валюта, которая будет испоьзоваться по умолчанию, как правило, завсит от текущего пользователя
+	 */
+	currency: 'USD' as 'RUB' | 'USD' | 'EUR',
+
+	/**
+	 * Для Москвы: +0300
+	 */
+	gmt: new Date().toString().match(/GMT(\S+)/)?.[1] as string,
+};

package/src/core/core/preloaders.ts

@@ -0,0 +1,31 @@
+/**
+ * Набор функцией, реализующих загрузку модулей системы, которые рекомендуется загружать в отложенном режиме
+ *
+ * Функции выполняют загрузку в память полный код модулей и компонентов
+ */
+export default class {
+
+	/**
+	 * Загрузить в память полный функционал TopNotice
+	 */
+	static async TopNotice() {
+		// Core.flags.needLoadNotice = true;
+		await import('@/components/core/notice/notice.vue');
+	}
+
+	/**
+	 * Загрузить в память полный функционал TopPopup
+	 */
+	static async TopPopup() {
+		await import('@/components/popup/lib/popup');
+	}
+
+	/**
+	 * Загрузить в память полный функционал TopDialog
+	 */
+	static async TopDialog() {
+		const { TopDialogWorker } = await import('@/core/app');
+		await TopDialogWorker.getDialogsUtils();
+	}
+
+};

package/src/core/core/state.ts

@@ -0,0 +1,61 @@
+import options from './options';
+
+/**
+ * State UI для взаимодейсвтиями с приложениями Vue
+ */
+const state = {
+	/**
+	 * CSS-классы модификаторы для документа страницы
+	 */
+	documentClassModificators: options.documentClassModificators,
+
+	dateFormat: options.dateFormat,
+	currency: options.currency,
+	gmt: options.gmt,
+
+	/**
+	 * Device by size
+	 *
+	 * @see Core widthForMobile
+	 */
+	isMobile: false,
+
+	/**
+	 * Device by user agent
+	 */
+	isMobileUA: false,
+
+	/**
+	 * true, если плотность пикселей экрана больше 1
+	 */
+	isRetina: false,
+
+	/**
+	 * true, елси это приложение
+	 */
+	isApp: false,
+
+	/**
+	 * true при горизонтальном расположении устройства
+	 */
+	isLandscape: true,
+
+	/**
+	 * true при вертикальном расположении устройства
+	 */
+	isPortrait: false,
+
+	/**
+	 * Максимальная сторона страницы
+	 */
+	size: 0,
+
+	/**
+	 * true, если страница скрыта
+	 *
+	 * Не меняйте это значение вручную
+	 */
+	isHidden: false,
+};
+
+export default state;

package/src/core/directives/data.mdx

@@ -0,0 +1,24 @@
+# v-top-data
+
+Сохранение данных в элементе.
+
+Используется для реализации сложной логики между Vue приложением и обычным js.
+
+Используйте с осторожностью, если вы разрабатываете компонент Vue, который не должны взаимодействовать с обычным js, не используйте эту директиву.
+
+Директива добавлена для демонстрации приема обмена данными без создания дополнительных глобальных состояний.
+
+## Пример использования
+
+```html
+
+<TopInput v-top-data:text="12345"/>
+<TopInput v-top-data:text2="'12345'"/>
+```
+
+```js
+import { storage } from '@topvisor/ui/core/utils/dom';
+
+storage(el, 'text'); // 12345
+storage(el, 'text2'); // "12345"
+```

package/src/core/directives/data.ts

@@ -0,0 +1,25 @@
+import type { DirectiveBinding, ObjectDirective } from 'vue';
+
+let storage: any;
+
+/**
+ * Сохранить данные в элементе
+ *
+ * Для доступа к данным можно воспользоваться ui/utils/dom storage()
+ */
+const data = {
+	mounted: async (el: HTMLElement, binding: DirectiveBinding) => {
+		if (!storage) {
+			const UtilsDom = await import('@/core/utils/dom');
+
+			storage = UtilsDom.storage;
+		}
+
+		const name = binding.arg;
+		const value = binding.value;
+
+		storage(el, name, value);
+	},
+};
+
+export default data;

package/src/core/directives/focus.mdx

@@ -0,0 +1,28 @@
+# v-top-focus
+
+Фокусировка на элементе сразу после его отображения.
+
+Фокусировкой можно управлять через значение директивы.
+
+Если выбрано несколько будет выбран первый.
+
+## Значение
+
+Директива в качестве значения принимает `boolean`: если установен `false` фокус выполняться не будет
+
+## Модификаторы
+
+Директива в качестве значения принимает объект с одним свойством:
+
+- **onupdate**: выполнять фокусировку при динамической установке значения
+
+## Пример использования
+
+```html
+
+<!-- Добавление директивы -->
+<TopInput v-top-focus/>
+
+<!-- Условное добавление директивы -->
+<TopInput v-top-focus="enabled"/>
+```

package/src/core/directives/focus.ts

@@ -0,0 +1,73 @@
+import type { DirectiveBinding } from 'vue';
+
+type Binding = DirectiveBinding<boolean, 'onupdate'>;
+
+let UtilsLodash: typeof import('@/core/utils/lodash');
+
+/**
+ * Список элементов, на которых бала запрошена фокусировка, для дедупликации фокусировок
+ */
+let elsActive: HTMLElement[] = [];
+
+/**
+ * Функция скролла с дедупликацией
+ */
+let focusOnElActiveDebounce: Function;
+
+/**
+ * Выполнить фокусировку на активном элементе
+ *
+ * Если фокусирока запрошена на несколько элементов, будет выбран первый элемент
+ */
+const focusOnElActive = async () => {
+	const { isVisible } = await import('@/core/utils/dom');
+	elsActive = elsActive.filter(isVisible)
+
+	if (!elsActive.length) return;
+
+	const el = elsActive[0];
+
+	el.focus();
+
+	// // UX: Если выбрано несколько чекбоксов или радио после выбора фокусировка будет снята, чтобы не делать выбор за пользователя
+	// if (elsActive.length && el.nodeName === 'INPUT') {
+	// 	const type = (el as HTMLInputElement).type;
+	// 	if (type === 'checkbox' || type === 'radio') el.blur();
+	// }
+
+	elsActive = [];
+};
+
+/**
+ * Выполнить дедуплицированную фокусировку на элементе
+ */
+const focusOnElDebounce = async (el: HTMLElement) => {
+	if (!UtilsLodash) UtilsLodash = await import('@/core/utils/lodash');
+	if (!focusOnElActiveDebounce) focusOnElActiveDebounce = UtilsLodash.debounce(focusOnElActive, 30);
+
+	elsActive.push(el);
+
+	focusOnElActiveDebounce();
+};
+
+/**
+ * Фокусировка на элементе сразу после его отображения
+ */
+const focus = {
+	mounted: function (el: HTMLElement, binding: Binding) {
+		el['__TOP_V_FOCUS_VALUE'] = binding.value ?? true;
+
+		if (binding.value ?? true) focusOnElDebounce(el);
+	},
+
+	updated: function (el: HTMLElement, binding: Binding) {
+		if (!binding.modifiers.onupdate) return;
+
+		if (el['__TOP_V_FOCUS_VALUE'] === (binding.value ?? true)) return;
+		el['__TOP_V_FOCUS_VALUE'] = binding.value ?? true;
+
+		if (binding.value ?? true) focusOnElDebounce(el);
+	},
+};
+
+export default focus;