@topvisor/ui 1.0.19 → 1.0.20-selector2-3

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/224/320/276/320/277/320/276/320/273/320/275/320/270/321/202/320/265/320/273/321/214/320/275/320/260/321/217 /320/273/320/270/321/202/320/265/321/200/320/260/321/202/321/203/321/200/320/260.mdx"

@@ -0,0 +1,15 @@
+# Дополнительная литература
+
+- [package.json](https://docs.npmjs.com/cli/v9/configuring-npm/package-json)
+- [tsconfig.json](https://www.typescriptlang.org/tsconfig/)
+- [Vue](https://vuejs.org/)
+- [Vite](https://vitejs.dev/)
+- [Storybook](https://storybook.js.org/)
+- пример UI-kit vue от GitLab:
+    - [Исходники](https://gitlab.com/-/ide/project/gitlab-org/gitlab-ui/edit/main/-/src/components/base/button/button.vue)
+    - [Storybook](https://gitlab-org.gitlab.io/gitlab-ui/)
+- [TypeScript](https://www.typescriptlang.org/docs/) - весь js код мы пишем на **TypeScript**
+- [TypeDoc](https://typedoc.org/) - утилита для автоматической **генерации документации** из TypeScript
+- [Markdown](https://markdown.land/) - полная документация по синтаксису **Markdown**
+- [Mermaid Chart](https://www.mermaidchart.com/) - редактор **Mermaid** для построения графиков
+- [Faker](https://fakerjs.dev/) - интструмент для **генерации данных для примеров** и тестов

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/320/260/320/275/320/264/320/260/321/200/321/202/321/213 /320/272/320/276/320/264/320/260//320/235/320/260/321/201/321/202/321/200/320/276/320/271/320/272/320/260 IDE.mdx"

@@ -0,0 +1,45 @@
+# IDE
+
+## IntelliJ IDEA
+
+Все рекомендуемые настройки уже расположены в настрйоках проекта в папке /.idea. Эти настройки будут применены автоматически.
+
+Дополнительно настройте:
+
+- включить **Vue**: `File | Settings | Languages & Frameworks | TypeScript | Vue`
+- включить опцию **Ensure every saved file ends with a line break**: `File | Settings | Editor | General`
+- выключить опцию **Reformat again**: `File | Settings | Editor | General | Smart Keys`
+- включить опции при сохранении: `File | Settings | Tools | Actions on Save`
+    - **Reformat code**
+    - **Run code clenup**
+- включить опции при сохранении: `File | Settings | Build, Execution, Deployment | Deployment | Options`
+  - **upload changes**: always
+  - **delete remove files**
+- для корректного автоформата добавьте расширение ***.mdx** в **Markdown**: `File | Settings | Editor | File Types`
+
+**Преимещуства**:
+
+- Комлпексные решения для разработки (не требует настройки плагинов)
+- Много расширений
+- Скорость работы
+
+**Недостатки**:
+
+- Платный
+
+## Visual Studio Code
+
+Все рекомендуемые настройки уже расположены в настрйоках проекта в папке /.vscode. Эти настройки будут применены автоматически.
+
+**Преимещуства**:
+
+- Быстрая утановка
+- Много расширений
+- Может быть встроен в браузер
+- Бесплатный
+
+**Недостатки**:
+
+- Не комлпексные решения для разработки, требуется установка расширений для каждой специализации разрабокти
+- Расширения снижают скорость работы IDE
+- Нет поддержки работы с FTP из коробки

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/320/260/320/275/320/264/320/260/321/200/321/202/321/213 /320/272/320/276/320/264/320/260//320/236/321/204/320/276/321/200/320/274/320/273/320/265/320/275/320/270/320/265 /320/272/320/276/320/264/320/260.mdx"

@@ -0,0 +1,31 @@
+# Оформление кода
+
+Для phpStorm все правила автоформата настроены.
+
+Включите у себя автоформат при сохраении файла, чтобы он применялся автоматичсески.
+
+<table>
+	<tr>
+		<th>Название</th>
+		<th>Значение</th>
+	</tr>
+	<tr>
+		<td>Отступы</td>
+		<td>tab (количество пробелов не важно)</td>
+	</tr>
+	<tr>
+		<td>Разделитель строк</td>
+		<td>\r\n</td>
+	</tr>
+	<tr>
+		<td>Стиль кода</td>
+		<td>K&R (1TBS)</td>
+	</tr>
+</table>
+
+Для JavaScript используются рекомендации [JavaScript Standard Style](https://github.com/standard/standard/blob/master/RULES.md) со следющими
+изменениями:
+
+* SPACE_BEFORE_METHOD_PARENTHESES = false
+* USE_SEMICOLON_AFTER_STATEMENT = true
+* USE_TAB_CHARACTER = true

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/320/260/320/275/320/264/320/260/321/200/321/202/321/213 /320/272/320/276/320/264/320/260//320/241/321/202/320/260/320/275/320/264/320/260/321/200/321/202/321/213 /320/272/320/276/320/264/320/260.mdx"

@@ -0,0 +1,29 @@
+# Стандарты кода
+
+Позвольте рассказать о стандартах js и о том, как это здорово. 👍
+
+Бытует мнение, что стандарты это набор правил, которые можно запихнуть в линтер и не думать о них.
+Давайте развенчаем этот миф и обратим внимание, что это опыт огромного сообщества разрабочтиков, который поможет избежать распространненых ошибок.
+
+- 🚀 изучив руководство ваша продуктивность написания кода увеличится;
+- 🤝 код, написанный по стандартам будет читаться проще другими разработчиками;
+- 🧐 в нем будет читаться ход ваших мыслей;
+- 💡 вероятность ошибок будет уменьшаться, так как в рекомендациях учтен опыт других разработчиков;
+- 🤖 имена переменных, группировка кода на логические блоки, выбор типа переменных и многое другое — это то, что ИИ не способно сделать правильно.
+  Правила такого рода не могут быть автоформатом и должны применяться осознанно.
+
+Рекомендации от разработчиков модуля **JavaScript Standard Style**:
+
+- [js](https://github.com/standard/standard/blob/master/RULES.md) - использется для автоформата в настройках IDE, см. **Оформление кода**
+
+Опыт разработчиков **Google**:
+
+- [js](https://google.github.io/styleguide/jsguide.html)
+- [js c переводом](https://rostislavdugin.github.io/styleguide/jsguide.html)
+- [html и css](https://google.github.io/styleguide/htmlcssguide.html)
+
+Опыт разработчиков **Airbnb**:
+
+- [js](https://github.com/airbnb/javascript#performance)
+- [js c переводом](https://github.com/leonidlebedev/javascript-airbnb/)
+- [html и css](https://github.com/standard/standard/blob/master/RULES.md)

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/321/200/321/203/320/272/321/202/321/203/321/200/320/260 UI//320/232/320/276/320/274/320/277/320/276/320/275/320/265/320/275/321/202/321/213//320/232/320/276/320/274/320/277/320/276/320/275/320/265/320/275/321/202/321/213.mdx"

@@ -0,0 +1,41 @@
+# Компоненты
+
+Имена компонентов должны быть уникальными, независимо от бибилиотеки, в которой находятся компоненты.
+
+
+Сборка производится в **библиотеки** - единые точки входа для ее компонентов.
+
+Для определения библиотеки нужно создать **entry** файл и перечислить в нем импорты и экспорты всех его **компонентов**.
+
+В **entry** файле можно перечислить **типы** предосталяемые компонентами и их **утилиты**.
+Утилиты должны экспоритроваться сквозным методом через export / from.
+
+## Структура бибилиотеки
+
+- каждый компонент принадлежит определенной бибилиотеке
+- все компоненты располагаются в папке бибилиотеки: `src/components/{{ libName }}`
+- папка компонента: `src/components/{{ libName }}/{{ componentName }}`
+- каждая бибилиотека собирается в отельный пакет (bundle) с именем, равным имени **entry** файла
+- entry файл для бибилиотеки: `src/components/{{ libName }}/{{ libName }}.ts`
+
+## Структура компонента
+
+Структура компонентов в библиотеке, пути указаны от корня компонента:
+
+- основной файл: `./{{ componentName }}.vue`
+- типы компонента (например: props, slots и emits): `./types.ts`
+- утилиты:
+    - `./utils.ts`
+    - `./utils/{{ utilsName }}.ts`
+- стили компонента (при вынесении из SFC):
+    - `./style.css`
+    - `./style/{{ styleName }}.css`
+- истории storybook: `./{{ componentName }}.stories.ts`
+- дополниетельные файлы для историй storybook: `./{{ componentName }}/stories/*`
+
+## Пример
+
+Для примера, см. реализацию ui / forms / TopButton 
+
+- src/components/forms/forms.ts
+- src/components/forms/forms/button/button.vue

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/321/200/321/203/320/272/321/202/321/203/321/200/320/260 UI//320/232/320/276/320/274/320/277/320/276/320/275/320/265/320/275/321/202/321/213//320/241/321/202/320/270/320/273/320/270 /320/272/320/276/320/274/320/277/320/276/320/275/320/265/320/275/321/202/321/213.mdx"

@@ -0,0 +1,58 @@
+# Стили компонентов
+
+[Общая статья про стили](?path=/docs/разработка-contributing-css-стили--docs).
+
+## Стандартное использование
+
+Стили прописываются в SFC в `<style>`;
+
+Можно выносить стили в отдельные файлы и импорт их в SFC:
+
+```
+
+<style>
+	@import "./style/{{ componentName или styleName }}.css";
+</style>
+```
+
+Стили, прописанные в SFC, при сборке будут расположены в папке `assets/{{ componentName }}.css`.
+
+**Исключение**: Все стили forms будут расположены в `assets/forms`, это необходимо для быстрой загрузки основных стилей UI.
+
+При стандартном использовании стили компонента будут **автоматически** загружены вместе с компоненом сразу и добавлены на страницу, перед его
+отрисовкой через `Core.insertCSSLinkToPage()`.
+
+## Загрузки стилей по требованию
+
+Стили располагаются в папке с компонентом, но не добавляются в SFC.
+
+Такие стилей не будут добавлены в сборку css, поэтому с ними можно работать рапрямую в js:
+
+```js
+// @/component/example/lib/preview.ts
+
+import Core from '@/core/core/core';
+import style from './style/{{ styleName }}.css?inline';
+import styleM from './style/{{ styleName }}.m.css?inline';
+import stylePC from './style/{{ styleName }}.pc.css?inline';
+
+Core.insertStyleToPage(style);
+Core.insertStyleToPage(styleM, 'm');
+Core.insertStyleToPage(stylePC, 'pc');
+
+export const open = () => {
+	//...	
+};
+```
+
+При таком использовании стили будут внедрены прямо в js файл.
+
+Затем в нужное время загрузить модуль:
+
+```html
+<!-- @/component/example/preview/preview.vue -->
+
+<template>
+	<button @click="import('@/component/example/lib/preview.ts').then(previewLib => previewLib.open())"></button>
+</template>
+```

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/321/200/321/203/320/272/321/202/321/203/321/200/320/260 UI//320/241/321/202/321/200/321/203/320/272/321/202/321/203/321/200/320/260 UI.mdx"

@@ -0,0 +1,11 @@
+# Структура UI
+
+- **public** - предустановленные файлы сборки, которые будут добавлены в сборку как есть
+- **src/components** - vue компоненты
+- **src/resources/core** - общие стили
+- **src/resources/themes** - стили тем оформления
+- **src/core** - другие файлы
+    - **src/core/composables** - утилиты сопоставления (composables)
+    - **src/core/directives** - vue директивы
+    - **src/core/plugins** - vue плагины
+    - **src/core/utils** - утилиты

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)//320/241/321/202/321/200/321/203/320/272/321/202/321/203/321/200/320/260 UI//320/243/321/202/320/270/320/273/320/270/321/202/321/213.mdx"

@@ -0,0 +1,5 @@
+# Утилиты
+
+Расположение набора утилит: `src/core/utils/{{ package }}.ts`
+
+Набор утилит должен содержать именованные экспорта функции с полными и уникальными названиями.

package/tsconfig.json

@@ -0,0 +1,91 @@
+{
+	"compilerOptions": {
+		// Most non-library projects don't need to emit declarations.
+		// So we add this option by default to make the config more friendly to most users.
+		"noEmit": true,
+		// When type-checking with solution-style tsconfigs, though with `noEmit: true`, there won't
+		// be any `.d.ts` files emitted, but tsc still writes a `.tsbuildinfo` file to the `outDir`
+		// for each project. If we don't explicitly set the `outDir`, it will be in the same folder
+		// as the `tsconfig.json` file, which would look messy.
+		// Setting it to `./dist/` isn't ideal either, because it would pollute the `dist` folder.
+		// So we set it to a hidden folder in `node_modules` to avoid polluting the project root.
+		// FIXME:
+		// This caused a regression: https://github.com/vuejs/tsconfig/issues/27
+		// Need to find a better solution.
+		// "outDir": "./node_modules/.cache/vue-tsbuildinfo",
+
+		// As long as you are using a build tool, we recommend you to author and ship in ES modules.
+		// Even if you are targeting Node.js, because
+		//  - `CommonJS` is too outdated
+		//  - the ecosystem hasn't fully caught up with `Node16`/`NodeNext`
+		// This recommendation includes environments like Vitest, Vite Config File, Vite SSR, etc.
+		"module": "ESNext",
+
+		// We expect users to use bundlers.
+		// So here we enable some resolution features that are only available in bundlers.
+		"moduleResolution": "bundler",
+		"resolveJsonModule": true,
+
+		// `allowImportingTsExtensions` can only be used when `noEmit` or `emitDeclarationOnly` is set.
+		// But `noEmit` may cause problems with solution-style tsconfigs:
+		// <https://github.com/microsoft/TypeScript/issues/49844>
+		// And `emitDeclarationOnly` is not always wanted.
+		// Considering it's not likely to be commonly used in Vue codebases, we don't enable it here.
+
+		// Required in Vue projects
+		"jsx": "preserve",
+		"jsxImportSource": "vue",
+
+		// `"noImplicitThis": true` is part of `strict`
+		// Added again here in case some users decide to disable `strict`.
+		// This enables stricter inference for data properties on `this`.
+		"noImplicitThis": true,
+		"strict": true,
+
+		// <https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#verbatimmodulesyntax>
+		// Any imports or exports without a type modifier are left around. This is important for `<script setup>`.
+		// Anything that uses the type modifier is dropped entirely.
+		"verbatimModuleSyntax": true,
+
+		// A few notes:
+		// - Vue 3 supports ES2016+
+		// - For Vite, the actual compilation target is determined by the
+		//   `build.target` option in the Vite config.
+		//   So don't change the `target` field here. It has to be
+		//   at least `ES2020` for dynamic `import()`s and `import.meta` to work correctly.
+		// - If you are not using Vite, feel free to overwrite the `target` field.
+		"target": "ESNext",
+		// For spec compilance.
+		// `true` by default if the `target` is `ES2020` or higher.
+		// Explicitly set it to `true` here in case some users want to overwrite the `target`.
+		"useDefineForClassFields": true,
+
+		// Recommended
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+
+		// See <https://github.com/vuejs/vue-cli/pull/5688>
+		"skipLibCheck": true,
+		"baseUrl": ".",
+		"paths": {
+			"@/*": [
+				"src/*"
+			]
+		},
+
+		"types": [
+			"node",
+			"vite/client",
+			"jquery",
+			"jqueryui"
+		],
+
+		"noImplicitAny": false
+	},
+
+	"include": [
+		".storybook/**/*",
+		"build/**/*",
+		"src/**/*"
+	]
+}

package/typedoc.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://typedoc.org/schema.json",
+	"readme": "none",
+	"plugin": [
+		"typedoc-plugin-markdown",
+		"typedoc-plugin-mdn-links"
+	],
+	"entryFileName": "Docs",
+	"fileExtension": ".mdx",
+	"indexFormat": "table",
+	"parametersFormat": "table",
+	"useHTMLEncodedBrackets": true,
+	"hidePageHeader": true,
+	"hideBreadcrumbs": true,
+	"hideGroupHeadings": true,
+	"useCodeBlocks": true,
+	"markdownItOptions": {
+		"linkify": true
+	}
+}

package/vite.config.ts

@@ -0,0 +1,148 @@
+import { basename, dirname, resolve } from 'path';
+import { glob } from 'glob';
+import type { UserConfig } from 'vite';
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+// import dynamicImport from 'vite-plugin-dynamic-import';
+import type { PluginOptions } from 'vite-plugin-dts';
+import dts from 'vite-plugin-dts';
+import cssModules from './build/cssModules';
+import rollupOptions from './build/rollup.config';
+import autoloadCSS from './build/plugin/autoloadCSS';
+import amdFix from './build/plugin/amdFix';
+
+const dtsOptions = {
+	insertTypesEntry: true,
+	staticImport: true,
+
+	// перечислить все файлы, входящие в сборку
+	include: [
+		resolve(__dirname, './src/components/*/**'),
+		resolve(__dirname, './src/core/**'),
+	],
+	exclude: [
+		resolve(__dirname, './**/*.stories.*'),
+	],
+} satisfies PluginOptions;
+
+const config: UserConfig = {
+	css: {
+		modules: cssModules,
+	},
+	resolve: {
+		alias: [
+			{
+				find: '@',
+				replacement: resolve(__dirname, './src'),
+			},
+			// см. /.storybook/preview-head.html
+			{
+				find: 'jquery',
+				replacement: resolve(__dirname, './src/storybook/jquery.ts'),
+			},
+		],
+	},
+	publicDir: 'public',
+	appType: 'custom',
+	preview: {
+		cors: {
+			origin: '*',
+		},
+		proxy: {
+			//  редирект на .js для esm
+			'^.*(?<!\.js|\.ts|\.css|\.md)$': {
+				target: 'http://localhost:4173',
+				rewrite: (path) => path + '.js',
+			},
+		},
+	},
+	build: {
+		lib: {
+			entry: {} as Record<string, string>,
+			name: '@topvisor/ui',
+			formats: [
+				'es',
+
+				// @ts-ignore - fix requirejs: этого значения нет в интерфейсе, используется вместо umd формата, который не поддерживает Multiple entry points
+				'amd',
+			],
+		},
+		// outDir: 'dist',
+
+		/**
+		 * по умолчанию vite использует es2020
+		 * - es2022 - минимальная версия с поддержкой safari15
+		 * - safari15 - требуется для приватных методов класса
+		 * - firefox90 - требуется для приватных методов класса
+		 */
+		target: ['es2022', 'edge89', 'firefox90', 'chrome89', 'safari15'],
+		// minify: false,
+		sourcemap: true,
+		manifest: false,
+		emptyOutDir: true,
+		cssCodeSplit: true,
+		assetsInlineLimit: 0,
+		rollupOptions,
+	},
+};
+
+/**
+ * Добавить entry, точки входа сборки
+ * @param entryPathes - пути к .ts файлам, задающим правила export
+ * @param distDir - в какую папку выполнить сборку
+ */
+function appendPathesToEntry(entryPathes: string[], distDir?: string): void {
+	entryPathes.forEach(entryPath => {
+		let dirName = basename(dirname(entryPath)).replace('.ts', '');
+		let name = basename(entryPath).replace('.ts', '');
+
+		name = dirName + '/' + name;
+
+		if (distDir) {
+			name = distDir + '/' + name;
+		}
+
+		if (config.build.lib) {
+			config.build.lib.entry[name] = entryPath;
+		}
+	});
+}
+
+const corePathes = glob.sync('./src/core/app.ts');
+appendPathesToEntry(corePathes);
+
+// const corePathes2 = glob.sync(['./src/core/plugin/plugin.ts', './src/core/directives/*.ts']);
+// appendPathesToEntry(corePathes2, 'core');
+
+const utilsPathes = glob.sync('./src/core/utils/*.ts');
+appendPathesToEntry(utilsPathes);
+
+const componentsLibsPathes = glob.sync('./src/components/*/*.ts');
+appendPathesToEntry(componentsLibsPathes);
+
+const cssCorePathes = glob.sync('./src/resources/styles/core/**/*.ts');
+appendPathesToEntry(cssCorePathes, 'for-delete');
+
+const cssThemePathes = glob.sync('./src/resources/styles/themes/**/*.ts');
+appendPathesToEntry(cssThemePathes, 'for-delete');
+
+// @ts-ignore
+export default defineConfig((env) => {
+	const plugins = [
+		vue(),
+		autoloadCSS(),
+
+		// должен выполняться после autoloadCSS(), так как требует опредления путей к css
+		amdFix(),
+	];
+
+	if (env.mode === 'preview') {
+		config.build.minify = false;
+	} else {
+		plugins.push(dts(dtsOptions));
+	}
+
+	config.plugins = plugins;
+
+	return config;
+});