Участие

Добро пожаловать в контрибьюторы lh-ui-plus! Этот документ описывает процесс участия в разработке.

Предварительные требования

• Node.js 18+
• Установка зависимостей через pnpm
• Базовые навыки работы с Git

Установка зависимостей

git clone https://github.com/lhgb-top/lh-ui-plus.git
cd lh-ui-plus
pnpm install

Процесс разработки

1. Запуск dev-сервера

pnpm dev

2. Запуск тестов

pnpm test:unit      # unit-тесты слоя Core
pnpm test:components  # интеграционные тесты компонентов
pnpm test            # все тесты

3. Проверка типов

pnpm typecheck

4. Линтинг

pnpm lint
pnpm lint:fix       # автоисправление

5. Сборка

pnpm build

6. Документация

pnpm docs:dev

Добавление нового компонента

Полный процесс описан в AGENTS.md, раздел «Adding or changing a component».

Краткие шаги:

1. @lh-ui/share, src/core/<name>/ — основная логика + unit-тесты (выполняется в репозитории share, здесь подключается как npm-зависимость)
2. packages/components/<name>/ — обёртка компонента Vue
3. packages/components/index.ts — регистрация в lhComponents
4. src/index.ts — обновление точки входа
5. tests/unit/components-registry.spec.ts — обновление ожидаемого массива
6. tests/components/<name>.spec.ts — тесты компонента
7. docs/components/<name>.md — страница документации
8. docs/.vitepress/config.ts — навигация в боковом меню

Команды проверки:

pnpm lint          # 0 ошибок, 0 предупреждений
pnpm typecheck     # нет вывода
pnpm vitest run    # все тесты проходят
pnpm docs:build    # сборка проходит

Развёртывание сайта документации

Путь развёртывания сайта документации централизованно задаётся в docs/.env.production (единый источник истины), production-сборка запускается напрямую:

pnpm docs:build

Переменная окружения	Описание	Значение по умолчанию	Пример
DOCS_BASE	base-путь сайта, должен начинаться и заканчиваться косой чертой	/	/lhui/vue3/
DOCS_HOSTNAME	канонический домен сайта, используется для sitemap и SEO-метатегов	https://www.lhgb.top	https://your-site.com

Обе переменные влияют на пути к ресурсам, sitemap, SEO-теги вроде og:url, а также на robots.txt, перегенерируемый в конце сборки.

Почему переменные в .env, а не в командной строке: встроенная загрузка env в Vite происходит после вычисления пользовательского config, поэтому docs/.vitepress/config.ts должен явно вызывать loadEnv, чтобы прочитать эти значения при production-сборке; кроме того, MSYS в Windows Git Bash преобразует инлайн DOCS_BASE=/lhui/vue3/ в абсолютный локальный путь. Временное переопределение через инлайн-переменные по-прежнему работает (DOCS_BASE=/xxx/ pnpm docs:build), но для обычных развёртываний надёжнее менять .env.production.

Соглашение об едином префиксе развёртывания

Навигационная страница библиотек компонентов LH-UI портала lhgb (www.lhgb.top) (/ui) использует единое соглашение /lhui/{имя-библиотеки}/ для путей развёртывания сайтов документации, не привязываясь к названиям фреймворков. Эта библиотека (версия для Vue 3) развёртывается по адресу /lhui/vue3/ (записано в docs/.env.production), команда production-сборки:

pnpm docs:build

Собранные артефакты загружаются на сервер в /home/webuser/nginx/lh-ui/vue3/ (авторитетная справочная копия Nginx location находится в семейном файле docs/部署/nginx-lhui.conf.md, а боевая версия — на сервере в /etc/nginx/conf.d/nginx.conf). Все восемь сайтов семейства развёрнуты по этому соглашению:

Репозиторий	base	каталог alias	cleanUrls
lh-ui-plus (эта библиотека)	/lhui/vue3/	/home/webuser/nginx/lh-ui/vue3/	нет
lh-ui-vue2	/lhui/vue2/	/home/webuser/nginx/lh-ui/vue2/	нет (VuePress 1.x)
lh-ui-react	/lhui/react/	/home/webuser/nginx/lh-ui/react/	нет
lh-ui-uniapp	/lhui/uniapp/	/home/webuser/nginx/lh-ui/uniapp/	да
lh-ui-android	/lhui/android/	/home/webuser/nginx/lh-ui/android/	да
lh-ui-ios	/lhui/ios/	/home/webuser/nginx/lh-ui/ios/	да
lh-ui-harmony	/lhui/harmony/	/home/webuser/nginx/lh-ui/harmony/	да
lh-ui-windows	/lhui/windows/	/home/webuser/nginx/lh-ui/windows/	да

Четыре сайта направления native (android / ios / harmony / windows) — это статические HTML-симуляторы, встроенные в VitePress-сайты, и развёртываются так же, как четыре сайта направления web. Новые библиотеки добавляют собственные location и .env.production по шаблону /lhui/{имя-библиотеки}/.

Для сайтов с cleanUrls (uniapp и четыре нативных) Nginx-директива try_files должна содержать $uri.html, иначе URL без расширения не найдут предрендерённые .html; для сайтов без cleanUrls эта директива не нужна. Подробнее см. раздел «три контракта» в справочной копии.

Стандарты кода

• CSS-классы используют префикс lh- (например lh-button__text--primary)
• Composables должны использовать префикс Lh (например useLhConfigProvider)
• Объекты-константы именуются в верхнем регистре snake_case (например LH_TYPES_CONST)
• Псевдонимы путей: ~/* → packages/* (этот репозиторий); фреймворконезависимая логика и стили — в @lh-ui/share, подключаются через npm-подпути (@lh-ui/share/core/*, @lh-ui/share/styles/*)
• Форматирование: одинарные кавычки, без точек с запятой, отступ 2 пробела, ширина строки 100 символов

Стандарты коммитов

feat: новый компонент Select — выпадающий список
fix: исправление потери фокуса в Input
docs: обновление документации по установке
test: добавление граничных тестов для Button
refactor: рефакторинг реактивной логики ConfigProvider

Соглашения об ИИ

Проект поддерживается с помощью AI-агентов. Команды проверки запускаются пользователями вручную; ИИ не запускает тесты и сборки автоматически.