## Руководство по RM UI Kit для ИИ‑агентов

Этот файл объясняет ИИ‑агентам, как устроен `rm.ui-kit`, где лежат основные части и куда вносить изменения, чтобы не потеряться.

### Общий обзор

- **Точка входа библиотеки**: `src/index.ts`  
  Отсюда реэкспортируются компоненты, типы, утилиты, composable‑хуки, плагины, сторы, модули и конфиги. Всё, что нужно публиковать наружу, в итоге должно быть доступно из этого файла.

- **Основное дерево ui‑кита**
  - `src/UI-kit/components` — визуальные Vue‑компоненты (атомы/молекулы).
  - `src/UI-kit/composables` — логические Vue composables, не завязанные на конкретный экран.
  - `src/UI-kit/utils` — чистые утилиты без Vue‑контекста.
  - `src/UI-kit/constants` — константы (цвета, иконки, локали и т.п.).
  - `src/UI-kit/types` — типы/enum’ы/интерфейсы для ui‑кита.
  - `src/UI-kit/plugins` — Vue‑плагины (установка ui‑кита, форматтеры, axios‑инстанс и т.п.).
  - `src/UI-kit/store` — pinia‑сторы, которые относятся к общему UI (например, модалки).
  - `src/UI-kit/assets` — scss, шрифты, иконки и прочие ассеты.

- **Бизнес‑модули поверх ui‑кита**
  - `src/modules/auth` — модуль авторизации.
  - `src/modules/documents` — модуль работы с документами.
  - `src/modules/form` — модуль динамических форм.
  - `src/configs` — общие конфиги (например, `uiKitI18n`).

Все они частично реэкспортируются через `src/index.ts`, поэтому используются как часть публичного API пакета.

---

## Структура и назначение папок

### `src/index.ts`

- **Что делает**: импортирует глобальные стили ui‑кита и реэкспортирует:
  - сторы из `src/UI-kit/store`;
  - типы из `src/UI-kit/types`;
  - утилиты из `src/UI-kit/utils`;
  - composables из `src/UI-kit/composables`;
  - плагины из `src/UI-kit/plugins`;
  - константы из `src/UI-kit/constants`;
  - UI‑компоненты (`UIButton`, `UILoader`, `UICard`, `UISwiper`, `UIInput`, `UIModal`, `UIDetailActionsSheet`, `UIDescription`, `UISvgIcon`, `UITitle`, `UIRadioButton`, `UISelect`, `UISteps`, `useToastNotification`, `ToastContainer`);
  - модуль форм (`ModuleForm`);
  - модуль документов (все типы/константы/компосаблы и компоненты `ModuleDocuments`, `ModuleDocumentsList`);
  - модуль авторизации (`AuthModule` и сопутствующие типы/компоненты);
  - общие `configs`.

- **Для ИИ‑агента**:  
  - Если добавляешь новый публичный компонент/утилиту/тип, проверь, экспортируется ли он из `src/index.ts` (напрямую или через промежуточный `index.ts` внутри папки).

### `src/UI-kit/components`

- **`components/UI`** — основные UI‑элементы:
  - `button/UIButton.vue`
  - `loader/UILoader.vue`
  - `card/UICard.vue`
  - `swiper/UISwiper.vue`
  - `inputs/UIInput.vue`, `inputs/LicensePlateInput.vue`
  - `modal/UIModal.vue`, `modal/UIModalContainer.vue`
  - `detail-actions-sheet/UIDetailActionsSheet.vue` — контекстный шит как в Роспиндосе: `Teleport` на `body`, затемнение + `backdrop-filter`, два блока с `border-radius: 14px` (список действий с иконкой слева и разделителями + отдельная «Отмена»), `v-model` видимости; пропсы `actions` (`id`, `label`, `icon`, `danger?`), `cancelLabel`, опционально `zIndex`; эмиты `select`, `close`.
  - `description/UIDescription.vue`
  - `svg-icon/UISvgIcon.vue`
  - `title/UITitle.vue`
  - `radio-button/UIRadioButton.vue`
  - `select/UISelect.vue`
  - `toaster/UIToaster.ts` — логика тостов (`useToastNotification`, `ToastContainer`).
  - `steps/UISteps.vue` — компонент‑стэппер (аналог breadcrumbs): нумерованные шаги, соединённые линией.

- **`components/UI/steps/UISteps.vue`** — стэппер / breadcrumbs:
  - Пропсы: `count: number` (кол‑во шагов), `activeStep: number` (активный и все предыдущие закрашиваются), `color?: string` (цвет линий и кружков, default `#047BEF`).
  - Эмит: `click(index: number)` — 1‑based индекс нажатого шага.
  - Фон прозрачный; активные/пройденные шаги — заливка цветом, остальные — только обводка.

- **`components/icons`** — иконки как Vue‑компоненты (паспорт, карта, машина и т.п.).  
  Используются в `UISvgIcon` и в конкретных UI‑элементах.

- **`components/common`** — общие вспомогательные компоненты (`CloseBtn.vue` и т.п.).

- **Storybook‑файлы** (`*.stories.ts`) находятся рядом с компонентами и служат примерами использования.
  Все компоненты в `components/UI` покрыты историями, включая `UISteps.stories.ts` (варианты: `Default`, `Interactive`, `AllCompleted`, `FirstStep`, `CustomColor`) и `UIDetailActionsSheet.stories.ts`.

- **Для ИИ‑агента**:
  - Новый базовый UI‑компонент → создавай в `components/UI/<feature>/<Name>.vue` + сторибук рядом.
  - Общая иконка → в `components/icons` и прокинуть её через `ui-icons.constant`/`UISvgIcon`, если нужно.

### `src/UI-kit/types`

- **`types/UI`** — ui‑ориентированные типы:
  - `ui-size.type.ts` — размеры (`UISize`).
  - `ui-color.type.ts` — палитра (`UIColor`, `UIColorName` и т.п.).
  - `ui-input.type.ts`, `ui-select.type.ts`, `ui-modal.type.ts`, `ui-button.type.ts`, `ui-icons.type.ts` и др.
- **Общие типы**:
  - `common.type.ts` — базовые общие типы.
  - `plugin.type.ts` — типы для Vue‑плагинов.
  - `language.type.ts` / `project-name.type.ts` / `iframe-hanlders.type.ts` / `paginated.type.ts` и пр.
- Все полезные наружу типы реэкспортируются из `src/UI-kit/types/index.ts`, а затем из `src/index.ts`.

- **Для ИИ‑агента**:
  - При добавлении новых enum’ов/типов для UI‑компонентов — клади их в `types/UI` и не забудь про реэкспорт в `types/index.ts`.
  - Если правишь сигнатуры публичных компонентов, сначала обнови типы, затем сами компоненты.

### `src/UI-kit/constants`

- **Файлы**:
  - `ui-color.constant.ts` — карта цветов для `UIColor` / `UIColorName`.
  - `ui-icons.constant.ts` — регистр доступных иконок для `UISvgIcon`.
  - `post-message.ts` — константы для postMessage‑взаимодействий.
  - `languages/*.ts` — базовые локализации ui‑кита (`defaultLocaleRu`, `defaultLocaleKg`, `defaultLocaleUz`, `defaultLocaleTj`), в том числе:
    - секция `ui.loader` с текстами лоадера:
      - `ru`: `title: 'Идёт загрузка...'`, `text: 'Пожалуйста, подождите'`;
      - `kg`: `title: 'Жүктөлүп жатат...'`, `text: 'Сураныч күтө туруңуз'`;
      - `uz`: `title: 'Юкланмоқда...'`, `text: 'Илтимос, кутинг'`;
      - `tj`: `title: 'Боркунӣ меояд...'`, `text: 'Лутфан интизор шавед'`.
- **`constants/index.ts`** реэкспортирует:
  - все ui‑константы (цвета, иконки, postMessage);
  - `defaultLocale*` для разных языков.

- **Для ИИ‑агента**:
  - Новый цвет/иконка → сначала добавь в соответствующую константу, затем используй в компонентах.
  - Новые ключи локализации для ui‑кита → расширяй `languages/*.ts` и проверь, что их видит `uiKitI18n`.

### `src/UI-kit/utils`

- **Назначение**: чистые утилиты, не привязанные к Vue‑компонентам:
  - `debounce.util.ts` — `debounce`.
  - `scroll-to-element.util.ts`, `scroll-to-top.util.ts`, `scroll-into-view.util.ts` — скролл‑утилиты.
  - `get-global-locale.util.ts` — выбор текущей локали.
  - `build-yup-chain.util.ts` — помощник для сборки Yup‑валидаторов.
  - `parent-message.util.ts` — работа с `postMessage`.
  - `copy-text.util.ts` (`textCopy`), `to-capitalize.util.ts`, `replace-value.util.ts`, `open-link.util.ts`, `get-html-link.util.ts`.
- Всё агрегируется через `src/UI-kit/utils/index.ts`, а затем из `src/index.ts`.

- **Для ИИ‑агента**:
  - Небизнесовая логика, которую можно переиспользовать в нескольких модулях → сюда.
  - Следи, чтобы утилиты оставались детерминированными и без прямого доступа к Vue‑инстансу.

### `src/UI-kit/composables`

- **Файлы**:
  - `useRequestHandler.ts` — обёртка над запросами.
  - `useIframeHandlers.ts` — обработчики взаимодействия через `iframe`.
  - `useBaseConnector.ts` — базовый коннектор для API.
  - `useCheckAppVersion.ts` — проверка версии приложения.
  - `useInfiniteScroll.ts` — бесконечный скролл.
  - `useQuery.ts` — работа с query‑параметрами.

- **Для ИИ‑агента**:
  - Общая бизнес‑логика, завязанная на Vue composition API, но не на конкретный экран → сюда.
  - Все публичные composables нужно экспортировать в `composables/index.ts`.

### `src/UI-kit/plugins`

- **`ui-kit-install.ts`** — главный плагин установки ui‑кита:
  - Регистрирует:
    - `autoAnimatePlugin`,
    - `Maska`,
    - `vue-toastification`,
    - внутренний `formatter` и `pluralEndings`,
    - `axios`‑плагин (`axiosUiKitConfig` через `provide`).
  - Интегрирует `uiKitI18n` из `src/configs/i18n.config.ts` в хост‑приложение:
    - если передан `i18n` — мёржит локали ui‑кита в локали хоста;
    - иначе подключает свой `uiKitI18n` как standalone.

- **`formatter.ts`** — плагин с форматтерами:
  - `formatDate`, `formatDateWithWordMonth`, `formatServerDate`, `formatAmount`, `formatPhone` и др.
  - Экспортируются как `app.config.globalProperties.$formatters`.

- **`plural-endings.ts`** — плагин склонений:
  - `app.config.globalProperties.$pluralEnds(number, titles)`.

- **`axios.ts`** — создаёт собственный `axios`‑инстанс с `baseURL` и пробрасывает его через `app.provide('axiosUiKitConfig', instance)`.

- **`plugins/index.ts`**:
  - экспортирует `formatter`, `pluralEndings`, `UIKitInstall`, `axios` для использования из пакета.

- **Для ИИ‑агента**:
  - Любой новый глобальный Vue‑плагин ui‑кита → создавай рядом и добавляй в `plugins/index.ts`.
  - В изменения `UIKitInstall` вноси осторожно: это критичный код интеграции библиотеки в хост‑приложение.

### `src/UI-kit/store`

- **`modal.store.ts`**:
  - Pinia‑стор `useUIModalStore` для управления стеком модальных окон.
  - Позволяет:
    - `openModal({ component, modalProps, componentProps, listeners })`;
    - `closeModal(id?)`;
    - `closeAllModals()` — сброс всего стека модалок;
    - `isOpen(id)`;
    - `updateModalProps`, `updateComponentProps`.
  - Экспортируется через `store/index.ts` → `src/index.ts`.

- **Для ИИ‑агента**:
  - Любое изменение поведения модалок нужно сначала отражать в сторе, а уже затем в `UIModal`/`UIModalContainer`.
  - Не добавляй в стор бизнес‑логику, не связанную с модальными окнами.

### `src/UI-kit/assets`

- **`assets/scss/index.scss`** — главный scss‑вход, который импортируется в `src/index.ts`.
- Содержит:
  - `common` стили (reset, typography, swiper и т.п.),
  - `mixins` (flex, отступы, типографика),
  - шрифты, переменные и прочее.
- В Storybook этот файл подключается напрямую через `import` в `.storybook/preview.ts` (не через `additionalData` препроцессора).
- Компоненты обращаются к миксинам явно: `@use '@/UI-kit/assets/scss/mixins/index.mixin'` — алиас `@` настроен в `.storybook/main.ts` через `viteFinal → resolve.alias`.

- **Для ИИ‑агента**:
  - Глобальные стили компонента (варианты темы, общие utility‑классы) — сюда.
  - Узкоспециальные стили компонента оставляй в `scoped` стилях самих `.vue`‑файлов.

---

## Бизнес‑модули, использующие ui‑kit

### `src/modules/auth`

- Содержит:
  - `AuthModule.vue` и формы авторизации (`AuthForm.vue`, `AuthCheckCodeForm.vue`);
  - сторы авторизации (`auth.store.ts`);
  - composables (`useAuthConnector`, `useInitAuthState` и др.);
  - типы и локализации модуля авторизации.
- Всё публичное собирается в `modules/auth/index.ts` и реэкспортируется из `src/index.ts`.

### `src/modules/documents`

- Модуль работы с документами:
  - контейнеры (`ModuleDocuments.vue`, `ModuleDocumentsList.vue`);
  - composables для схем полей, валидаций, изображений документов (`useModuleDocumentConnector`, `useDocumentModuleHandlers`, `usePrepareFields` и др.);
  - стор `module-document.store.ts`;
  - типы (`type/*.ts`) и `constants` (включая `validation` и `languages`).
- Экспортируется через `modules/documents/index.ts` и далее из `src/index.ts`.

### `src/modules/form`

- Генератор форм:
  - `ModuleForm.vue` — основной компонент.
  - `components/Field.vue` — отдельное поле.
  - `types` (например, `input-type.type.ts`) — типизация конфигурации полей.
- Публичные типы реэкспортируются через `modules/form/types/index.ts`.

### `src/configs`

- **`i18n.config.ts`**:
  - создаёт `uiKitI18n` с базовыми локалями ui‑кита (`defaultLocale*`) + локалями модулей (`moduleDocuments`, `moduleAuth` для `ru`, `uz`, `kg`, `tj`).
- **`configs/index.ts`**:
  - реэкспортирует `uiKitI18n` и дополнительные конфиги/типы/сторы, если появятся.

- **Для ИИ‑агента**:
  - Добавление новых текстов для ui‑кита или модулей → в соответствующие `languages/*.ts`, затем используй их через `uiKitI18n`/`$t`.

---

## Как ИИ‑агенту вносить изменения

### 1. Добавить новый UI‑компонент

1. Создай Vue‑компонент в `src/UI-kit/components/UI/<feature>/<Name>.vue`.
2. Добавь сторибук в соседний `*.stories.ts`, используя существующие истории как пример.
3. При необходимости добавь/обнови типы в `src/UI-kit/types/UI` и реэкспортируй их в `types/index.ts`.
4. Если компонент должен быть доступен как публичный API пакета — экспортируй его из `src/index.ts`.

### 2. Изменить существующий UI‑компонент

1. Найди компонент в `src/UI-kit/components/UI/...`.
2. Проверь связанные типы в `src/UI-kit/types/UI` и константы в `src/UI-kit/constants`.
3. Проверь сторибук‑примеры, чтобы не сломать основные сценарии.
4. Сохрани обратную совместимость публичных пропов/слотов, если это возможно.

### 3. Добавить composable/утилиту/константу

- **Composable** → `src/UI-kit/composables` + экспорт в `composables/index.ts`.
- **Утилита** → `src/UI-kit/utils` + экспорт в `utils/index.ts`.
- **Константа/локаль** → `src/UI-kit/constants` + экспорт в `constants/index.ts`.
- При необходимости не забудь про реэкспорт через `src/index.ts`.

### 4. Работа с плагинами и i18n

1. Любой новый глобальный плагин ui‑кита создавай в `src/UI-kit/plugins` и экспортируй в `plugins/index.ts`.
2. Если плагин должен подключаться автоматически при `UIKitInstall` — добавь его в `ui-kit-install.ts`.
3. Для новых локализаций:
   - дополни `src/UI-kit/constants/languages/*.ts` и/или `src/modules/*/constants/languages/*.ts`;
   - удостоверься, что они подхватываются в `src/configs/i18n.config.ts`.

---

## Навигационные подсказки для ИИ‑агента

- **Ищешь визуальный компонент?**  
  Сначала смотри `src/UI-kit/components/UI`, затем сторибуки рядом.

- **Ищешь бизнес‑логику без UI?**  
  Иди в `src/UI-kit/composables` или в соответствующий модуль в `src/modules/*`.

- **Ищешь общие вспомогательные функции?**  
  Смело ищи в `src/UI-kit/utils`.

- **Ищешь настройки локали или тексты?**  
  Для базовых UI‑текстов — `src/UI-kit/constants/languages/*.ts`,  
  для модулей — `src/modules/*/constants/languages/*.ts`,  
  итоговую сборку смотри в `src/configs/i18n.config.ts`.

- **Не уверен, экспортируется ли сущность наружу?**  
  Проверь сначала локальный `index.ts` (внутри папки), потом `src/index.ts`. Всё, что нужно потребителям пакета, должно быть доступно оттуда.

