@topvisor/ui 1.0.42-dev.2 → 1.0.42-policy.0

package/src//320/221/321/213/321/201/321/202/321/200/321/213/320/271 /321/201/321/202/320/260/321/200/321/202.mdx"

@@ -1,181 +0,0 @@
-# Быстрый старт
-
-## Установка
-
-Установка **@topvisor/ui**:
-
-```bash
-npm install @topvisor/ui --save-dev
-```
-
-## Подключение
-
-### Стили UI:
-
-Стили компонентов грузятся вместе с компонентами и подклчюаются на страницу автоматически.
-
-Основные стили UI необходимо подключить вручную.
-
-Как модуль:
-
-```js
-// тут можно указать нужную тему
-import '@topvisor/ui/assets/light.css';
-
-import '@topvisor/ui/assets/core.css';
-import '@topvisor/ui/icomoon/style.css';
-```
-
-Как html:
-
-```html
-
-<!-- тут можно указать нужную тему -->
-<link href="https://cdn.jsdelivr.net/npm/@topvisor/ui/assets/theme/light.css" rel="stylesheet">
-
-<link href="https://cdn.jsdelivr.net/npm/@topvisor/ui/assets/core.css" rel="stylesheet">
-<link href="https://cdn.jsdelivr.net/npm/@topvisor/ui/icomoon/style.css" rel="stylesheet">
-```
-
-## Ядро UI, **corePlugin**:
-
-```js
-import { createApp } from 'vue';
-import { Core, corePlugin } from '@topvisor/ui/core/app';
-
-// ...
-
-const app = createApp({});
-
-// объект Core будет доступен в шаблонах через свойство $core
-app.use(corePlugin, {
-	widthForMobile: 900,
-	dateFormat: 'Y-m-d', // будет доступно в Core.state, можно менять
-	currency: 'USD', // будет доступно в Core.state, можно менять
-});
-
-// ...
-```
-
-## Cловарь, **i18nPlugin**:
-
-```js
-import { createApp } from 'vue';
-import { i18nPlugin, useI18n } from '@topvisor/ui/core/app';
-
-// ...
-
-const app = createApp({});
-
-const i18n = {
-	Common: {
-		// ...
-		Open: 'Open:',
-		Close: 'Close',
-		// ...
-	},
-	// ...
-};
-
-app.use(i18nPlugin, {
-	i18n, // доступно в js через useI18n() и  в шаблонах Vue через $i18n
-	lang: 'en', // для смены требуется перезагрузка страницы
-});
-```
-
-## Расширение Pinia для сохранения состояния, **piniaTPAPlugin**:
-
-```js
-import { createApp } from 'vue';
-import { createPinia } from 'pinia';
-import { piniaTPAPlugin } from '@topvisor/ui/core/app';
-
-// ...
-
-const app = createApp({});
-
-const pinia = createPinia();
-pinia.use(piniaTPAPlugin);
-
-this.app.use(pinia);
-```
-
-Использование **piniaTPAPlugin**:
-
-```js
-import { defineStore } from 'pinia'; // нет в публичном доступе
-// import API from '@topvisor/api'; // нет в публичном доступе
-
-const user = {
-	id: 12345,
-	guest_data: {
-		count: 5,
-	},
-};
-
-export const useMyStore = defineStore('myStore', () => {
-	const count = ref(0);
-
-	return { count };
-}, {
-	Api,
-	user,
-	tpaNamesUrlHash: ['count'],
-	tpaNamesStorage: ['count'],
-	tpaNamesStorageLocal: [],
-	tpaNamesGuestLink: ['count'],
-});
-```
-
-## Использование
-
-Для подключения компонента начните писать `<Top` и выберите из списка необходимый компонент.
-
-Подключение компонентов:
-
-```html
-
-<script lang="ts">
-	// import { TopButton } from '@topvisor/ui/forms/forms'; // можно не импортировать, загружается в corePlugin
-	import { TopEditInput } from '@topvisor/ui/formsExt/formsExt';
-
-	console.log(TopEditInput);
-</script>
-
-<template>
-	<TopButton styling="soft">Кнопка</TopButton>
-
-	<TopEditInput modelValue="text"></TopEditInput>
-</template>
-```
-
-Для использования директивы начните писать в атрибуте тега `v-top` и выберите из списка необходимую директиву.
-
-Использование директив:
-
-```html
-
-<template>
-	<TopInput v-top-focus></TopInput>
-</template>
-```
-
-## Рекомендации по производительности
-
-Не все модули нужны при загрузке страницы и их нет смысла грузить всегда. Пример таких модулей: TopNotice и TopDialog.
-Часть их функционала подгружается на сразу, а только при необходимости.
-
-Такой подход позволяет не грузить лишний код там, где в этом нет необходимости.
-Однако это может повлиять на визуальное впечатление, так как отлкик на дейсвтия будет замедлен.
-
-Чтобы улучшить взаимодейсвтие **Core** предоставялет предзагрузчики, которые позволят загрузить код модулей и улучшить определенные сценарии.
-
-```js
-import { Core } from '@topvisor/ui/core/app';
-
-setTimeout(() => {
-	Core.preloaders.TopNotice();
-	Core.preloaders.TopPopup();
-	Core.preloaders.TopDialog();
-}, 10000);
-```

package/src//320/223/320/260/320/271/320/264/320/273/320/260/320/271/320/275.mdx

@@ -1,120 +0,0 @@
-# Гайдлайн
-
-**Гайдлайн** — это рекомендации ведения разработки в проекте.
-
-Для удобстава использования гайдлайна, при его написании используются общепринятые подходы.
-Добавление **нестандартных практик** не рекомендуется.
-Ссылки на **общепринятые стандарты** рекомендуются.
-
-## Стандарты оформления кода
-
-[Оформление кода](?path=/docs/разработка-contributing-стандарты-кода-оформление-кода--docs)
-
-## Гайдлайны компонентов
-
-Компонент может иметь собственные рекомендации по гайдлайну. В этом случае они должны быть описаны в документации самого компонента.
-
-Пример такого компонента:  [TopDialog](?path=/docs/components-dialog-dialog--docs).
-
-## Composables и Утилиты
-
-В экосистеме Vue 3 часто встречаются два подхода к организации повторно используемой логики: **composables** и **утилиты**.
-Оба подхода полезны, но они служат разным целям.
-
-**Утилиты** — это обычные функции, не использующие реактивность Vue.
-Их можно применять в любом месте: внутри компонентов, вне компонентов, даже в Node.js или других проектах.
-
-**Composables** — это функции, которые используют реактивные API из Vue (ref, computed, watch, и т.д.).
-Они позволяют организовать бизнес-логику и переиспользовать ее между компонентами.
-
-Из-за реактивности и жизненного цикла Vue возможны повышенные затраты ресурсов, поэтому следует осознанно подходить к выбору, что использовать:
-Composables или Утилиты.
-
-### Структура
-
-Создание отдельных папок `composables` / `utils` **рекомендуется**:
-
-- Упрощает навигацию и поиск логики
-- Поддерживает порядок в проекте
-- Следует принятой практике в Vue/Nuxt-сообществах
-
-```
-MyComponent/
-│
-├── composables/
-│   ├── useAuth.ts
-│   └── useTheme.ts
-│
-├── utils/
-│   ├── capitalize.ts
-│   └── formatDate.ts
-```
-
-### Таблица сравнения
-
-| Характеристика                                    | Utilities                             | Composables                    |
-|---------------------------------------------------|---------------------------------------|--------------------------------|
-| Использует `ref`, `reactive`, `watch`, `computed` | ❌ Нет                                 | ✅ Да                           |
-| Может использовать lifecycle-хуки                 | ❌ Нет                                 | ✅ Да                           |
-| Vue-специфично                                    | ❌ Нет                                 | ✅ Да                           |
-| Универсальность                                   | ✅ Можно использовать где угодно       | ❌ Только внутри Vue-приложений |
-| Пример применения                                 | Форматирование, валидация, математика | Работа с состоянием            |
-
-## Composables
-
-### Общие правила
-
-- Каждый composable должен быть в **отдельном файле** с **именованным экспортом**. Имя файла и имя функции должны совпадать и начинаться с `use`.
-
-  **Примеры:**
-
-	- `useAuth.ts` → `export const useAuth = () => { ... }`
-	- `useScrollPosition.ts` → `export const useScrollPosition = () => { ... }`
-
-- **JSDoc-документация рекомендуется**, особенно для публичных composables или тех, которые планируются к повторному использованию. Комментарий может
-  содержать:
-	- Назначение функции
-	- Параметры — только если требуется описание (если описание не нужно, параметр в JSDoc не указывается)
-	- Описание возвращаемых значений
-	- Пример использования (если возможно)
-
-### Что нельзя
-
-- Использовать `default export`
-- Экспортировать несколько функций из одного файла
-- Давать общее или неинформативное имя (`useStuff`, `useData`, и т.п.)
-
-### Пример
-
-<details>
-<summary>useModal.ts</summary>
-
-```ts
-/**
- * Управление состоянием модального окна
- *
- * @returns - Состояние модального окна и функции управления
- * @example
- * const { isOpen, open, close } = useModal()
- */
-export const useModal = () => {
-		const isOpen = ref(false);
-
-		const open = () => { isOpen.value = true; };
-		const close = () => { isOpen.value = false; };
-
-		return { isOpen, open, close };
-	};
-```
-
-</details>
-
-### Обязательные требования
-
-| Правило                              | Обязательно |
-|--------------------------------------|-------------|
-| Один файл — один composable          | ✅           |
-| Именованный экспорт                  | ✅           |
-| Имя начинается с `use`               | ✅           |
-| Имя файла совпадает с именем функции | ✅           |
-| Документация через JSDoc             | ⚠️          |

package/src//320/230/320/275/321/204/320/276/321/200/320/274/320/260/321/206/320/270/321/217 /320/276 /321/201/320/261/320/276/321/200/320/272/320/265.mdx"

@@ -1,14 +0,0 @@
-import test from "../package.json?raw";
-import { Markdown } from "@storybook/addon-docs/blocks";
-
-# Информация о сборке
-
-Информацию о готовой сборке см. на странице npm проекта: [@topvisor/ui](https://www.npmjs.com/package/@topvisor/ui).
-
-Информация о текущей сборке, **package.json**:
-
-<Markdown>
-	{`\`\`\`json
-    ${test}
-    \`\`\``}
-</Markdown>

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)/CSS/FAQ.mdx"

@@ -1,43 +0,0 @@
-# FAQ
-
-**Почему используется camelCase?**
-
-> Для возможности использования одинарных разделителей, код становится чище
-
-> Чтобы имя блока сответствовало имени компонента
-
-**Почему в css модулях не добавляется хеш?**
-
-> В UI-kit принято использовать понятные и чистые имена классов
-
-> Упрощается процесс поиска нужного компонента или его элемента
-
-**Зачем нужно следовать правилам БЭМ, если есть правила сборки css модуля?**
-
-> Чтобы было можно быстро разобраться, к какому компоненту приналежит тот или иной класс
-
-> Чтобы код следовал единому стилю
-
-**Зачем нужен css модуль, если есть БЭМ?**
-
-> В правила преобразовавний классов можно вынести рутинные действия, например добавление префикса, характеризующего namespace / workspace
-
-> IDE поддерижвает автозаполнения классов модулей и навигацию по ним
-
-> Позволяет использовать дополнительные плагины для добавления полезного функционала
-
-**SSR с отдельной сборкой решает проблему размера сборки, зачем нужные ленивые компоненты?**
-
-> SPA приложение предполагает смену страниц без перезагрузки, поэтому отдельные сборки для каждой страницы будут приводить
-> к дублям стилей при переходе между страницами. Так как страниц много, то возникнет ситуация, при которой кеш таких стилей будет мало полезен.
-
-> Такие сборки придется дополнительно настраивать и следить за выгрзкой дублей стилей между разными сборками разных страниц.
-
-> Автосборки SSR действительно удобны, однако если решить этот вопрос на этапе преоктировки UI, то таких проблем в SSR удастся избежать.
-
-**Как поменять какие компоненты и стили надо грузить при загрузке страницы, а какие в отложенном режиме?**
-
-> Сразу надо грузить те кмопоненты, которые должны быть отрисованы в момент загрузки текстовой страницы, например /forms/ и /content/.
-
-> Если потребуется мгновенная отрисовка компонента на какой-то странице, в самом вверху этой страницы можно указать прямую ссылку на css компонента.
-> Данный вопрос выходит за рамки UI-kit. Читайте: [CLS](https://web.dev/i18n/en/cls/).

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

@@ -1,155 +0,0 @@
-import { Markdown } from '@storybook/addon-docs/blocks';
-
-# Общие модификаторы
-
-Формат имени класса модификатора состояний: `top-{{stateName}}`.
-
-Расположение общих модификаторов до предкомпиляции: src/resources/styles/core/modifiers/*.css.
-
-Отличие модификаторов от компонентов заключается в том, что модификаторы не являются самостоятельными и реализуются только в связке с компонентами.
-
-## Модификаторы состояния
-
-<table>
-    <tr>
-        <th>Класс</th>
-        <th>Описание</th>
-    </tr>
-    <tr>
-        <td>.top-inited</td>
-        <td>
-            Признак готовности js, настраивается в каждом компоненте отдельно.
-            Ранее исползовался в чиcтом js для исключения скачков при загрузке страницы.
-
-            Во Vue для динамически подключаемых компонентов без SSR используется иной подход.
-
-            <details>
-                <summary>см. пример для Vue</summary>
-                
-                html:
-
-                ```html
-                <example-component></example-component> <!-- html до отрисовки Vue -->
-                <div class="top-exampleComponent"></div> <!-- html после отрисовки Vue -->
-                ```
-
-
-                Стили:
-                
-                ```css
-                example-component{ height: 200px; } /* стили для заглушки компонента до его отрисовки */
-                .top-exampleComponent{ height: 200px; } /* обычные стили компонента */
-                ```
-            </details>
-            
-        </td>
-    </tr>
-    <tr>
-        <td>.top-error</td>
-        <td>Модификатор ошибки</td>
-    </tr>
-    <tr>
-        <td>.top-changed</td>
-        <td>Модификатор изменения</td>
-    </tr>
-    <tr>
-        <td>.top-disabled</td>
-        <td>Модификатор блокированности</td>
-    </tr>
-    <tr>
-        <td>.top-active</td>
-        <td>Модификатор активности, выбора элемента</td>
-    </tr>
-    <tr>
-        <td>.top-hightlight</td>
-        <td>Модификатор подсветки</td>
-    </tr>
-
-</table>
-
-## Модфикаторы видимости
-
-<table>
-    <tr>
-        <th>Класс</th>
-        <th>Описание</th>
-    </tr>
-    <tr>
-        <td>.top-hidden</td>
-        <td>скрыть элемент (display: none !important)</td>
-    </tr>
-    <tr>
-        <td>.top-unvisible</td>
-        <td>скрыть элемент, элемент по прежнему будет считаться видимым</td>
-    </tr>
-    <tr>
-        <td>.top-only_admin</td>
-        <td>отображать только для админов</td>
-    </tr>
-    <tr>
-        <td>.top-only_pc</td>
-        <td>отображать только для ПК версии</td>
-    </tr>
-    <tr>
-        <td>.top-only_mobile</td>
-        <td>отображать только для мобильной версии</td>
-    </tr>
-    <tr>
-        <td>.top-only_ru</td>
-        <td>отображать только в русской языковой версии</td>
-    </tr>
-    <tr>
-        <td>.top-only_en</td>
-        <td>отображать только в английской языковой версии</td>
-    </tr>
-</table>
-
-## Модфикаторы размера
-
-<table>
-    <tr>
-        <th>Класс</th>
-        <th>Описание</th>
-    </tr>
-    <tr>
-        <td>.top-size_xs</td>
-        <td>XS</td>
-    </tr>
-    <tr>
-        <td>.top-size_s</td>
-        <td>S</td>
-    </tr>
-    <tr>
-        <td>.top-size_m</td>
-        <td>M, стандартный размер, как если бы модификатор не указывался</td>
-    </tr>
-    <tr>
-        <td>.top-size_l</td>
-        <td>L</td>
-    </tr>
-    <tr>
-        <td>.top-size_xl</td>
-        <td>XL</td>
-    </tr>
-</table>
-
-## Модфикаторы разметки
-
-<table>
-    <tr>
-        <th>Класс</th>
-        <th>Описание</th>
-    </tr>
-    <tr>
-        <td>.top-ellipsis</td>
-        <td>Оформление строк с сокращением под три точки</td>
-    </tr>
-    <tr>
-        <td>.top-ellipsis2</td>
-        <td>Оформление строк в две строки с сокращением под три точки</td>
-    </tr>
-    <tr>
-        <td>.top-ellipsis3</td>
-        <td>Оформление строк в три строки с сокращением под три точки</td>
-    </tr>
-</table>

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)/CSS//320/237/320/265/321/200/320/265/320/274/320/265/320/275/320/275/321/213/320/265.mdx"

@@ -1,35 +0,0 @@
-# Переменне
-
-Правила определения переменных:
-
-- переменные задаются в `:root{ }`
-- формат имени цвета палитры: `--color-{{ colorName }}-{{ от 0 до 1000 }}`
-- формат имени цвета темы: `--color-{{ colorName }}-{{ colorModificator }}`
-- формат имени переменной компонента: `--top-{{ componentName }}-{{ cssPropertyName }}`
-
-См. также:
-
-* [Темы](/docs/core-theme--docs)
-
-## Примеры
-
-Переменная темы не ассоциируется с цветом и описывает только сущность:
-
-```css
-/* light.css */
-
-:root {
-	--color-primary-500: rgba(10, 108, 255, 1);
-}
-```
-
-Переменная компонента buttonExample:
-
-```css
-/* buttonExample.vue */
-
-:root {
-	--top-buttonExample-color: var(--color-primary-500); /* стиль color, который зависит от темы */
-	--top-buttonExample-font-size: 24px; /* стиль font-size */
-}
-```

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)/CSS//320/237/321/200/320/265/320/264/320/277/321/200/320/276/321/206/320/265/321/201/321/201/320/276/321/200/321/213.mdx"

@@ -1,15 +0,0 @@
-# Предпроцессоры
-
-Предпроцессоры в проекте **не используются**.
-
-Используется css модуль: [PostCSS](https://postcss.org/).
-
-Благодаря правильно продуманной структуре компонентов и современных возможностей CSS вам
-не придется делать сложных правил CSS. Если же вы с ними столкнулись, задумайтесь, возможно что-то делаете не так.
-
-В некоторых случаях предпроцессоры могут быть полезны, например для генерации переменных на основе определенных условий
-с помощью функций, которых нет в css. Однако распространенные задачи решаются плагинами postcss, которые способны реализовать необходимый функционал.
-При этом достаточно гибко. Например: [postcss-color-mod-function](https://github.com/csstools/postcss-color-mod-function).
-
-Таким образом снимаются требования к разработчику на профильное знание css препроцессоров и снижается уровень входа.
-Одновременно с этим в проекте испоьзуются самые современные средства для работы с css.

package/src//320/240/320/260/320/267/321/200/320/260/320/261/320/276/321/202/320/272/320/260 (Contributing)/CSS//320/240/320/265/320/272/320/276/320/274/320/265/320/275/320/264/320/260/321/206/320/270/320/270 /320/221/320/255/320/234.mdx"

@@ -1,56 +0,0 @@
-# Рекомендации БЭМ
-
-Подробнее о БЭМ: [https://ru.bem.info/](https://ru.bem.info/).
-
-Проект @topvisor/ui не следуют всем правилам БЭМ, тем не менее следуют их рекомендациям.
-
-При написании компонента следует использовать рекомендации БЭМ со следующими правилами:
-
-- все классы имют префикс "top-"
-- имя блока должно соответствовать имени компонента в camelCase
-- имена сущностей (блок, элемент, имя модификатора и значение модификатора) пишутся в camelCase
-- элемент отделяется от блока нижним подчеркиванием: "_"
-- модификаторы отделяется дефисом: "-"
-- значение модификатора отделяется от имени модификатора подчеркиванием: "_"
-- булевы модификаторы рекомендуется писать без указания значения
-
-## Структура класса соответствует схеме
-
-**top-blockName_elementName-modifierName_modifierValue**
-
-## Все варианты
-
-- top-blockName
-- top-blockName-modifierName
-- top-blockName-modifierName_modifierValue
-- top-blockName_elementName
-- top-blockName_elementName-modifierName
-- top-blockName_elementName-modifierName_modifierValue
-
-## Примеры
-
-Компонент ButtonExample с подсказкой, модификаторами номера и фокуса.
-
-```css
-:root {
-	--top-buttonExample-color: var(--color-white);
-	--top-buttonExample-background-color: var(--color-primary);
-}
-
-.top-buttonExample { }
-/* блок */
-.top-buttonExample_hint { }
-/* элемент подсказки */
-
-.top-buttonExample-focus { }
-/* модификатор фокуса на блоке */
-.top-buttonExample_hint-focus { }
-/* модификатор фокуса на элементе подсказки */
-
-.top-buttonExample-number_1 { }
-/* модификатор номера со значением 1 */
-.top-buttonExample-number_2 { }
-/* модификатор номера со значением 2 */
-.top-buttonExample-number_3 { }
-/* модификатор номера со значением 3 */
-```