sprof — UI Kit & Platform Library (PF)

Библиотека UI-компонентов и платформенного ядра для проектов на Vue 3 + Quasar 2. Используется во всех 8 клиентах: rdkb (hr/map/food/leiter/incident), portal, pros, ferma.

• P-компоненты — обёртки над Quasar (полный проброс props/slots/events)
• PF / PFM — платформенное ядро: helpers, store (BaseStore), FTSP, UI (Notify/Dialog), auth, модули (Tabs, Contacts, Schedule, Table, Menus, Forms)
• installSprof — регистрация всех P-компонентов + Quasar-плагинов одной строкой

📦 Установка

npm install sprof

Требования (peer dependencies)

| Пакет | Версия | Обязателен | | --- | --- | --- | | vue | ^3.4 | да | | quasar | ^2.21 | да | | axios | ^1.6 | нет (auth) | | vue-router | ^4.3 | нет |

Приложение должно использовать Quasar 2 — P-компоненты рендерят Q-компоненты напрямую (импортируют их из quasar), поэтому Quasar CSS уже должен быть подключён.

🚀 Подключение

// main.ts (или boot-файл Quasar)
import { createApp } from 'vue';
import { installSprof } from 'sprof';

const app = createApp(App);
installSprof(app); // Quasar-плагины Notify+Dialog + все P-компоненты
app.mount('#app');

Если Quasar уже настроен (Quasar CLI):

import { installSprof } from 'sprof';

export default boot(({ app }) => {
  installSprof(app, { quasarPlugins: false }); // плагины уже есть в quasar.config.ts
});

Типы глобальных P-компонентов

Декларация генерируется из реестров (scripts/gen-global-components.mjs) и поставляется в пакете. В проекте достаточно одного файла:

// src/types/sprof-components.d.ts
import type {} from 'sprof';
export {};

Ничего вручную дописывать не нужно — все 96 P-компонентов (атомы, молекулы, организмы) типизируются в шаблонах автоматически.

🧱 P-компоненты (обёртки над Quasar)

Общий принцип: весь API Quasar работает как есть — props/events передаются насквозь, слоты пробрасываются, :disable/color/size и др. имеют приоритет над P-пропсами.

Атомы (24)

| Компонент | Обёртка над | Особенности | | --- | --- | --- | | PButton | QBtn | нативный click, type=submit/reset, attrs-приоритет, legacy skin | | PInput | QInput | все слоты, v-model string/number/null, rules, width | | PSelect | QSelect | все слоты, модель any | | PCheckBox | QCheckbox | v-model boolean | | PToggle | QToggle | v-model boolean, label, size | | PDialog | QDialog | v-model boolean, persistent/maximized, слоты title/header/body/footer | | PChip | QChip | label/color/outline/removable, слоты avatar/remove | | PBadge | QBadge | label/color/outline/rounded/floating/multiLine | | PRadio | QRadio | v-model, label, size | | PInputNumber | QInput + QBtn | step/min/max, кнопки +/− | | PDateInput | QInput + QDate | универсальное поле даты: mask ДД.ММ.ГГГГ + popup, модель Date \| string | | PDatePicker / PInputDate | — | legacy-алиасы PDateInput (удаление — TECH_DEBT Т2) | | PTextarea | QInput | resize, mask | | PTooltip | QTooltip | timeout, позиционирование, typeStyle | | PString | QItemLabel | текст с цветом/размером, isHtml | | PLabelField | QItemLabel | подпись с отступами | | PFlex | div | flex-контейнер | | PList / PListItem | QList / QItem | списки | | PLeftSlider / PRightSlider / PTopSlider | QBtn | выдвижные панели | | PSticky | div | sticky-обёртка | | PTableToggle | QBtn | переключатель режима таблицы (используется в PTable модуля Table) |

Молекулы/организмы (основные)

PAdd, PDel, PModal, PContainer, PContainerStickyHead, PTabs, PUploaderFile, PUploaderImage, PAuthForm, PAuthModal, PPagination, PAutocomplete, PContactForm*, PTable*, PCrudList, POptionsListMany и др. — полный список в реестрах src/core/components/*/index.ts.

🏛 PF — платформенное ядро

| Объект | Описание | | --- | --- | | PF | helpers, store (BaseStore), FTSP, UI (Notify/Dialog), auth, types | | PFM | модули: Tabs, Contacts, Schedule, Table, Menus, Forms |

import { PF, PFM } from 'sprof';

🔄 Миграция q-* → P-*

Зачем: единые обёртки (проброс всего API Quasar) + платформенные типы + точка расширения.

| Было | Стало | Примечание | | --- | --- | --- | | <q-btn ...> | <PButton ...> | attrs совместимы; @click нативный | | <q-input ...> | <PInput ...> | все слоты/события работают | | <q-select ...> | <PSelect ...> | модель any | | <q-checkbox ...> | <PCheckBox ...> | | | <q-toggle ...> | <PToggle ...> | | | <q-dialog ...> | <PDialog ...> | | | <q-chip ...> | <PChip ...> | | | <q-badge ...> | <PBadge ...> | |

q-icon и низкоуровневые q-компоненты (q-card/q-item/q-td и т.п.) можно не переводить.

⚠️ Важно (баг 0.2.3/0.2.4): P-компоненты обязаны импортировать Q-компоненты из quasar явно — без этого в клиентах с auto-import Quasar элементы «пропадают» (Vue рендерит пустые <pbutton>/<qbtn>). Защита: тесты src/core/components/atoms/__consumer__/ и npm run check:dist.

🧪 Разработка

npm run test        # vitest (64 файла, 448 тестов)
npm run lint        # eslint src --fix
npm run lint:check  # eslint src (без мутаций, для CI)
npm run build       # сборка dist (ESM + UMD + d.ts)
npm run check:dist  # проверка бандла: нет resolveComponent("Q…")
npm run check:size  # size-limit (бюджеты бандла)
npm run test:e2e    # Playwright-смоук (e2e/app)
npm run storybook   # Storybook (документация компонентов)

Публикация

./publish.sh              # bump patch + тесты + сборка + npm publish (2FA) + git tag
# или вручную: npm run test && npm run build && npm run check:dist && npm publish

Либо GitHub Actions publish.yml (workflow_dispatch, OTP-инпут).

После публикации обновить клиентов: npm run update:clients — scripts/update-clients-sprof.sh (npm ×8 + пересборка dev-контейнеров; rdkb ×5, portal, pros, ferma).

Генерация типов GlobalComponents

node scripts/gen-global-components.mjs   # после добавления/удаления P-компонентов

📋 Полезное

• Реестр задач и роадмап — TASKS.md
• История изменений — CHANGELOG.md
• Заметки для агентов — AGENT.md