@topvisor/ui 1.0.42-date.2 → 1.0.42-dev.2

package/src/core/plugins/piniaTPA.ts

@@ -0,0 +1,432 @@
+import type { PiniaPluginContext, Store } from 'pinia';
+import { watch } from 'vue';
+import Core from '@/core/core/core';
+import { useI18n } from '@/core/plugins/i18n';
+import { debounce } from '@/core/utils/lodash';
+import { guestLinkToClipboard } from '@/core/utils/clipboard';
+import { camelToSnakeCase } from '@/core/utils/string.js';
+import type { paths as OpenAPIPaths } from 'topvisor-openapi/src/ts/Topvisor';
+import { getHash, setHash } from '@/core/utils/route';
+
+type OpenAPIPath = keyof OpenAPIPaths;
+
+class PiniaTPA {
+
+	readonly #storeId: string;
+	readonly #store: Store<string, any>;
+
+	/**
+	 * @deprecated
+	 */
+	readonly #Page: any;
+
+	readonly #user: any;
+	readonly #Api: any;
+
+	readonly #namesUrlHash: string[] = [];
+	readonly #namesStorage: string[] = [];
+	readonly #namesStorageLocal: string[] = [];
+	readonly #namesGuestLink: string[] = [];
+
+	constructor(context: Context) {
+		this.#store = context.store;
+		this.#storeId = this.#store.$id;
+
+		this.#Page = context.options.Page;
+
+		this.#user = context.options.user;
+		this.#Api = context.options.Api;
+
+		this.#namesUrlHash = context.options.tpaNamesUrlHash || [];
+		this.#namesStorage = context.options.tpaNamesStorage || [];
+		this.#namesStorageLocal = context.options.tpaNamesStorageLocal || [];
+		this.#namesGuestLink = context.options.tpaNamesGuestLink || [];
+
+		context.store.genGuestLink = <Path extends OpenAPIPath>(url: Path, data: any) => this.genGuestLink(url, data);
+
+		if (!this.#user.guest_data?.data) {
+			this.#loadFromStorage();
+			this.#loadFromStorage(true);
+
+			// настройки URL hash имеют приоритет
+			this.#loadFromHash();
+		}
+
+		// настройки гостевой ссылки имеют приоритет
+		this.#loadFromGuestLink();
+
+		this.#prepareParams();
+
+		const save = debounce(() => {
+			this.#saveInHash();
+			this.#saveInStorage();
+			this.#saveInStorage(true);
+		});
+
+		context.store.$subscribe(save);
+	}
+
+	/**
+	 * Сгенерировать гостевую ссылку
+	 *
+	 * Метод, путь к которому указан в url, должен возвращать сгенерированную ссылку
+	 */
+	async genGuestLink<Path extends OpenAPIPath>(url: Path, data: any) {
+		const dataGuestLink = this.#genOptionsForGuestLink();
+		data = Object.assign(data, Object.fromEntries(dataGuestLink));
+
+		const res = await this.#Api.gen(url, 'fetchColumn').call({} as any, data);
+
+		// @ts-ignore - метод, который скачивает файл не возвращает json
+		if (res?.errors) return;
+
+		// @ts-ignore - метод, который скачивает файл не возвращает json
+		await guestLinkToClipboard(res.result);
+	}
+
+	/**
+	 * Сгенерировать опции для гостевой ссылки
+	 */
+	#genOptionsForGuestLink() {
+		const data = new Map();
+
+		this.#namesGuestLink.forEach(name => {
+			// формат параметров API: snake_case
+			const nameSnakeCase = camelToSnakeCase(name);
+			data.set(nameSnakeCase, this.#store[name]);
+		});
+
+		return data;
+	}
+
+	/**
+	 * Установить опции из объекта без фиксации состояния
+	 */
+	#setOptions(data: Map<string, any>) {
+		data.forEach((value, name) => {
+			const currentValue = this.#store[name];
+
+			if (value === null || value === undefined) return;
+			if (currentValue === undefined) return;
+			if (!value?.constructor) return;
+			if (value.constructor !== currentValue.constructor) return;
+
+			// дополнительная проверка на формат даты
+			if (name.indexOf('date') === 0) {
+				if (Array.isArray(value)) {
+					// value.forEach((valueI) => {
+					// 	if (!/\d\d\d\d-\d\d-\d\d/.test(valueI)) return;
+					// });
+				} else {
+					if (typeof (value) === 'string') {
+						if (!/\d\d\d\d-\d\d-\d\d/.test(value)) return;
+					}
+				}
+			}
+
+			this.#store[name] = value;
+		});
+	}
+
+	/**
+	 * Сгенерировать Map объект с опциями со значениями в виде json строк
+	 */
+	#genDataFormat(data: Map<string, any>) {
+		const dataFormatted = new Map();
+
+		data.forEach((value, name) => {
+			if (value === null) return;
+
+			value = JSON.stringify(value);
+
+			dataFormatted.set(name, value);
+		});
+
+		return dataFormatted;
+	}
+
+	/**
+	 * Сгенерировать Map объект с опциями со значениями в оригинальном виде
+	 */
+	#genDataUnFormat(dataFormatted: Map<string, string>) {
+		const data: Map<string, any> = new Map();
+
+		dataFormatted.forEach((value, name) => {
+			if (value === null || value === undefined || value === 'false') return;
+
+			try {
+				if (typeof (value) === 'string' && !/^\d\d\d\d-\d\d-\d\d$/.test(value)) value = JSON.parse(value);
+
+				if (value === null || value === undefined || value === 'false') return;
+			} catch (e) {
+				// не json строка
+			}
+
+			data.set(name, value);
+		});
+
+		return data;
+	}
+
+	/**
+	 * Установить опции из хеша адреса страницы
+	 */
+	#loadFromHash() {
+		let dataHash: any;
+		try {
+			dataHash = JSON.parse(getHash(this.#storeId));
+		} catch (e) {
+
+		}
+		if (!dataHash) return;
+
+		const data: Map<string, any> = new Map();
+
+		this.#namesUrlHash.forEach((name) => {
+			const value = dataHash[name];
+			if (!value) return;
+
+			data.set(name, value);
+		});
+
+		this.#setOptions(data);
+	}
+
+	/**
+	 * Сохранить опции в хеш адреса страницы
+	 */
+	#saveInHash() {
+		const data = new Map();
+
+		this.#namesUrlHash.forEach((name) => {
+			const value = this.#store[name];
+
+			data.set(name, value);
+		});
+
+		const dataObject = Object.fromEntries(data);
+		const dataJSON = JSON.stringify(dataObject);
+
+		setHash(this.#storeId, dataJSON);
+	};
+
+	/**
+	 * Установить опции из localStorage
+	 * @param isLocal - сохранить с учетом адреса страницы
+	 */
+	#loadFromStorage(isLocal = false) {
+		const dataFormatted = new Map();
+
+		let names = this.#namesStorage;
+		let storageNamespace = 'state:' + this.#storeId;
+
+		if (isLocal) {
+			names = this.#namesStorageLocal;
+			storageNamespace = 'state:' + this.#storeId + ':' + location.pathname;
+		}
+
+		names.forEach((name) => {
+			const value = localStorage.getItem(storageNamespace + ':' + name);
+			dataFormatted.set(name, value);
+		});
+
+		const data = this.#genDataUnFormat(dataFormatted);
+
+		this.#setOptions(data);
+	}
+
+	/**
+	 * Сохранить опции в localStorage
+	 * @param isLocal - сохранить с учетом адреса страницы
+	 */
+	#saveInStorage(isLocal = false) {
+		const data = new Map();
+
+		let names = this.#namesStorage;
+		let storageNamespace = 'state:' + this.#storeId;
+
+		if (isLocal) {
+			names = this.#namesStorageLocal;
+			storageNamespace = 'state:' + this.#storeId + ':' + location.pathname;
+		}
+
+		names.forEach((name) => {
+			const value = this.#store[name];
+
+			data.set(name, value);
+		});
+
+		const dataFormatted = this.#genDataFormat(data);
+
+		names.forEach((name) => {
+			const value = dataFormatted.get(name);
+
+			localStorage.setItem(storageNamespace + ':' + name, value);
+		});
+	}
+
+	/**
+	 * Установить опции из гостевой ссылки
+	 */
+	#loadFromGuestLink() {
+		const guestData = this.#user?.guest_data?.data;
+		if (!guestData) return;
+
+		// общие правила для гостевых сессий
+		if (this.#user.id === -1) this.#user.positionsReverseDates = guestData.positionsReverseDates;
+
+		const dataFormatted = new Map();
+
+		this.#namesGuestLink.forEach((name) => {
+			const value = guestData[name];
+			dataFormatted.set(name, value);
+		});
+
+		const data = this.#genDataUnFormat(dataFormatted);
+
+		this.#setOptions(data);
+
+		const $guestTitle = $('.mod_guest_title');
+
+		// TODO: вынести в опции плагина
+		if (this.#store.competitorsIds?.length === 1 && this.#Page.page.data.competitors) {
+			let competitors = this.#Page.page.data.competitors.filter((competitor: any) => competitor.id === guestData.competitorsIds[0]);
+			if (competitors.length) {
+				$('a', $guestTitle).attr('href', 'http://' + competitors[0].url);
+				$('a', $guestTitle).text(competitors[0].name);
+			}
+		}
+	}
+
+	/**
+	 * Подготовить входные параметры перед инициализацией основного функционала
+	 *
+	 * Входные параметры устанавливаются при открытии страницы
+	 *
+	 * Входные параметры могут меняться пользоваталем и устаревать
+	 */
+	#prepareParams() {
+		// контролль за вводом регионов
+		// TODO: вынести в опции плагина
+		if (this.#store.regionsIndexes) {
+			watch(this.#store.regionsIndexes, (regionsIndexes) => {
+				if (!regionsIndexes.length) return;
+
+				// приведение типа
+				regionsIndexes.forEach((regionIndex: number, index: number) => regionsIndexes[index] = regionIndex);
+
+				// оставить только включенные регионы
+				// @ts-ignore
+				const mapSearchers = TplProjectSelectorRegion.genSearchersMap();
+
+				const availableRegionsIndexes: number[] = [];
+				mapSearchers.forEach((searcher: any) => {
+					searcher.regions.forEach((region: any) => {
+						if (region.index === -1) return;
+
+						availableRegionsIndexes.push(region.index);
+					});
+				});
+
+				this.#store.regionsIndexes = regionsIndexes.filter((regionIndex: number) => availableRegionsIndexes.includes(regionIndex));
+			}, { immediate: true });
+		}
+
+		// контролль за вводом конкурентов
+		// TODO: вынести в опции плагина
+		if (this.#store.competitorsIds) {
+			watch(this.#store.competitorsIds, (competitorsIds) => {
+				if (!competitorsIds.length) return;
+
+				// приведение типа
+				competitorsIds.forEach((competitorId: number, index: number) => competitorsIds[index] = competitorId);
+
+				// оставить только включенных конкурентов
+				const availableCompetitorsIds = [this.#Page.page.data.project.id];
+				this.#Page.page.data.project.competitors.forEach((competitor: any) => {
+					if (competitor.on >= 0) availableCompetitorsIds.push(competitor.id);
+				});
+
+				this.#store.competitorsIds = competitorsIds.filter((competitorId: number) => availableCompetitorsIds.includes(competitorId));
+			}, { immediate: true });
+		}
+	}
+
+}
+
+type Options = {
+	/**
+	 * TODO: Убрать из плагина
+	 */
+	Page: any,
+
+	/**
+	 * Объект с настройками пользователя
+	 */
+	user: any,
+
+	/**
+	 * Объект для работы с API
+	 *
+	 * См. на сайте: @/component/api/core/api.ts
+	 */
+	Api: any;
+
+	/**
+	 * Имена свойств для сохранения в URL
+	 */
+	tpaNamesUrlHash?: string[],
+
+	/**
+	 * Имена свойств для сохранения в localStorage
+	 */
+	tpaNamesStorage?: string[],
+
+	/**
+	 * Имена свойств для сохранения в localStorage с учетом пути URL
+	 *
+	 * Каждый URL будет работать со своим состоянием
+	 */
+	tpaNamesStorageLocal?: string[],
+
+	/**
+	 * Имена свойств для работы с гостевой ссылкой
+	 *
+	 * Для генерации гостевой ссылки используйте store.genGuestLink(data, url)
+	 */
+	tpaNamesGuestLink?: string[],
+};
+
+type Context = PiniaPluginContext & {
+	options: Options
+};
+
+/**
+ * Плагин tpa (Third-party access) для pinia
+ *
+ * Добавляет возможность сохранять и загружать данные в/из:
+ * 	- URL hash в адресе страницы
+ * 	- localStorage
+ * 	- гостевая ссылка
+ *
+ * Для подключения плагина нужно указань одну или несколько опций при определении defineStore():
+ * - tpaNamesUrlHash
+ * - tpaNamesStorage
+ * - tpaNamesStorageLocal
+ * - tpaNamesGuestLink
+ */
+export default (contextPinia: PiniaPluginContext) => {
+	const context = contextPinia as Context;
+
+	// плагин подключать не нужно
+	if (
+		!context.options.tpaNamesUrlHash?.length &&
+		!context.options.tpaNamesStorage?.length &&
+		!context.options.tpaNamesStorageLocal?.length &&
+		!context.options.tpaNamesGuestLink?.length
+	) {
+		return;
+	}
+
+	new PiniaTPA(context);
+}

package/src/core/plugins/plugins.mdx

@@ -0,0 +1,82 @@
+# Плагины
+
+Примеры использования смотрите в статье [Быстрый старт](?path=/docs/быстрый-старт--docs).
+
+## corePlugin
+
+Плагин для подключения UI к Vue приложению.
+
+Полное описание UI/Core см. [Core](?path=/docs/core-core--docs).
+
+## i18nPlugin
+
+Плагин для подключения словарей сайта к Vue приложению.
+
+Принимает набор словарей и текущий язык и предоставялет средства управлению ими.
+
+Примеры см. в JSDoc плагина.
+
+| Настройка плагина | Composables      | Доступ из шаблонов Vue |
+|-------------------|------------------|------------------------|
+| i18n              | useI18n()        | $i18n                  |
+| i18nLang          | useI18nLang()    | $i18nLang              |
+
+## piniaTPAPlugin
+
+Добавляет возможность сохранять и загружать данные в/из:
+
+- URL hash в адресе страницы
+- localStorage
+- гостевая ссылка
+
+Настройки для pinia **defineStore()**:
+
+| Название             | Описание                                                                                      |
+|----------------------|-----------------------------------------------------------------------------------------------|
+| user                 | Объект пользователя                                                                           |
+| Api                  | Объект работы с API                                                                           |
+| tpaNamesUrlHash      | Список свойств храналища, которые надо сохраняться в URL                                      |
+| tpaNamesStorage      | Список свойств храналища, которые надо сохраняться в localStorage                             |
+| tpaNamesStorageLocal | Список свойств храналища, которые надо сохраняться в localStorage только для текущей страницы |
+| tpaNamesGuestLink    | Список свойств храналища, которые надо сохраняться в гостевых ссылках                         |
+
+**Объект Api**: http client для работы с API. Определен только на сайте.
+
+> ### Идея 😛
+>
+> Вынести http client API в отдельный проект @topvisor/api и сдлеать настраиваемым для любого API в спецификации openapi на typescript.
+>
+> Разместить в публичный github без типов модели данных. Подключить на сайте с добавлегинем типов модели данных.
+>
+> **@topvisor/api**:
+>
+> - легковесный клиент API
+> - только современный fetch
+> - работает с любым API, описанным в спецификации openapi на typecript (https://openapi-ts.dev/)
+> - отображает подсказки в коде с описанием API
+> - не зависит от размеров API и ее документации
+>
+> 🤩 **Сделайте это и получите опыт в работе с публичными репозиториями!**
+
+**Объект user**
+
+| Свойство   | Описание                                                                    |
+|------------|-----------------------------------------------------------------------------|
+| id         | id аторизованного пользователя<br/>У неавторизованного пользователя id = -1 |
+| guest_data | Объект с предустановленными значениями для установки в Store                |
+
+## storeTPAPlugin
+
+Добавляет возможности сохранять состояние компонента с привязкой с экземпляру компонента.
+
+Аналогичен piniaTPAPlugin, но испоьзует контекст компонента, а не контектса приложения.
+
+
+> ### Не реализован 🤔
+>
+> На сайте используется устаревший способ настройки хранилища, подключение которого требует от разрабочтика больших усилий, чем простой вызов
+> **defineStore()**.
+>
+> Если столкнетесь с разработкой сохранения состояния допишите этот плагин и испоьзуйте его.
+>
+> 🤩 **Создайте удобный инструмент, который облегчит жизнь вашим коллегам-разработчикам, и поделитесь им со всеми!**

package/src/core/styles/CSS Variables.stories.ts

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import layoutCSS from '@/resources/styles/core/layout.css?inline';
+import Component from '@/storybook/components/cssVariables.vue';
+
+const meta = {
+	component: Component,
+	tags: ['!autodocs'],
+} satisfies Meta<typeof Component>;
+
+export const CSSVariables = {
+	name: 'CSS Variables',
+	args: {
+		style: layoutCSS,
+	},
+} satisfies StoryObj<typeof meta>;
+
+export default meta;

package/src/core/styles/styles.mdx

@@ -0,0 +1,26 @@
+# Основные стили и переменные
+
+Основные стили, классы и переменные доступны в:
+
+- после сборки: **assets/core.css**
+- до сборки: **src/resources/styles/core/*.css**
+
+## CSS Variables
+
+Основные css переменные для отсуптов и оформления элементов на странице.
+
+## Стили и css классы
+
+Компоненты должны использовать предоставляемые классы, вместо реализации своих аналогичных стилей.
+
+Стили макета содержат основные переменные и классы для расположения и оформления элементов на странице.
+
+## Стили и css классы
+
+[Общие модификаторы](?path=/docs/разработка-contributing-css-общие-модификаторы--docs)
+
+Атрибут **data-top-badge** - добавляет стили для вывода числа в бейдже
+
+```html
+<span data-top-badge="5"></span>
+```

package/src/core/theme/Variables.stories.ts

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { getCurrentCSS } from '@/../.storybook/TopTheme';
+import Component from '@/storybook/components/cssVariables.vue';
+
+const meta = {
+	component: Component,
+	tags: ['!autodocs'],
+} satisfies Meta<typeof Component>;
+
+export const Variables = {
+	args: {
+		style: getCurrentCSS(),
+	},
+} satisfies StoryObj<typeof meta>;
+
+export default meta;

package/src/core/theme/theme.mdx

@@ -0,0 +1,117 @@
+import { Canvas } from '@storybook/addon-docs/blocks';
+import { Mermaid } from 'mdx-mermaid/lib/Mermaid';
+
+# Темы оформления
+
+Каждая тема представляет собой набор переменных. Может включать в себя переменные для настройки любых стилей.
+
+Все темы должны реализовывать одинаковый набор переменных.
+
+После сборки стили темы раполагаются в папке: **assets/themes**.
+
+## Структура темы
+
+Рассмотрим на примере темвы **Light**:
+
+- **головной файл**: src/resources/styles/themes/**light.ts**
+- **переменные темы**: src/resources/styles/themes/light/**light.css**
+- **компоненты темы positions**: src/resources/styles/themes/light/**light-positions.css**
+
+<Mermaid chart={`flowchart TD
+subgraph s1["Theme Name"]
+themeName.css["themeName.css"]
+themeName-componentName-1.css("themeName-componentName.css")
+ThemeName-componentName-N.css("themeName-componentName.css")
+end
+A["Themes"] --> s1
+
+`} />
+
+## Компоненты темы
+
+**Компонент темы** - это переменные для конкретного компонента, описанные на уровне темы.
+
+Пример:
+
+```css
+:root {
+	/* Цвета топа для отчета по позициям */
+	--color-positions-table-top-1: #A3D1EE;
+	--color-positions-table-top-2: #B4D9F1;
+	--color-positions-table-top-3: #C3E1F4;
+}
+```
+
+**Основная задача компонентов**: реализовать более гибкую настройку тем там, где переменных темы недостаточно.
+
+> 📢 **Компонентов темы обычно не определяют css правила**
+>
+> Однако, в некоторых случаях их можно определять в контексте корня документа. Например, при смене состояния страницы.
+
+**Примеры компонентов:**
+
+- лого проекта
+- шапка сайта
+- футер сайта
+- личный кабинет
+
+Список компонентов темы определяется архитектором UI в соответсвие с требованиями оформления сайта.
+
+## Термины
+
+- **Палитра** - набор цветов определенного тона, определяется **именем** палитры и **индексом цвета**
+- **Группа** - набор цветов разделенных по типу использования, например для фона, текста и т.п.
+- **Компонент** - набор переменных разделенных по месту использования, с привязкой к конкретному разделу сайта или компоненту
+- **Индекс цвета** - номер цвета в **палитре**, в основном индексы перечисляются от 0 до 1000, от самомого светлого к самому темному (для светлой
+  темы и наоборо для темной)
+- **Базовый цвет** - освноной цвет темы, на котором располагается основной контент
+- **Инвертированный цвет** - противоположенный исходному цвет, получаемый переворотом палитры этого цвета (в общем случае не рекомендуется
+  к использованию)
+- **Цвет затемнения** - всегда затеменяющий цвет, независимо от темы
+- **Наложение цвета** - наложение одного цвета на другой, реализуется либо через функции css либо через прозрачность накладываемого цвета
+- **Фоновый цвет** - цвет для окраски фона элемента
+- **Фоновый передний цвет** - мягкий цвет для окраски фона элемента, **приближен к базовому цвету** тем самым создет мягкое выделение элемента
+
+## Основные цвета
+
+**Имя переменной** для цвета формируется из имени **группы** и имени его **палитры** по формату: `--color-{{ Группа }}-{{ Палитра }}-{{ Индекс }}`.
+
+Если **палитра не указана**, будет испоьзоваться стандартный цвет без примеси или цвет **theme**: `--color-{{ Группа }}-{{ Индекс }}`
+
+**Пример**:
+
+- **центральный** цвет палитры **primary**: `--color-primary-500`
+- **яркий** цвет для **фона** с отенком **primary**: `--color-bg-primary-1`
+    - то же самое с изменением на **1 тон**: `--color-bg-primary-2`
+- **нежный** цвет для **фона** с отенком **primary**: `--color-layout-front-1`
+- **прозрачная** подложка: `--color-layer-1`
+- **прозрачная** подложка с **позитивной** коннотацией: `--color-layer-positive-1`
+
+**Палитры:**
+
+- **theme** - определяет основные цвета темы, испольузется в основном для фона и линий
+- **base** - перебазирвоанный **theme** таким образом, чтобы начинаться с **базового цвета** (layout-front) темы, является сокращенной палитрой
+- **shading** - цвет затемнения **theme**, является сокращенной палитрой
+- **primary** - используется для оснвоных кнопок, ссылок и других элементах для базового акцента
+- **positive** - для выделения элементов с позитивной коннотацией: **продолжение**, **разрешение**, **успех**, **подъем**
+- **warning** - для выделения элементов, на которые надо **обратить внимание** без позитивной/негативной конатации
+- **negative** - для выделения элементов с негативной коннотацией: **остановка**, **запрет**, **ошибка**, **снижение**
+- **info** - альтернативная палитра, не связанная с остальными палитрами
+
+**Палитры в разработке:**
+
+**Группы:**
+
+- **bg** - фоновый цвет
+- **layer** - цвет с прозрачностью
+- **line** - цвет линий, обводок, разделителей столбцов и строк
+- **text** - цвет текста
+
+**Компоненты:**
+
+- **layout** - компонент каркаса сайта
+    - **layout-back** - задний цвет старницы
+    - **layout-header** - цвет шапки старницы
+    - **layout-middle** - дополнительный цвет, испоьзуемый для дополнительных панелей страницы, например левое меню
+    - **layout-front-1** - является **Базовым цветом**, используется для основного содержимого страницы
+    - **layout-front-\{\{ N }}** - цвет, на уровень выше, чем **layout-front-1**