Руководство по участию

Приветствуются изменения в @lh-ui/share. Данный документ — жёсткие ограничения для участия в совместной работе: большинство соглашений здесь — не стилевые предпочтения, а предпосылка того, что всё будет корректно работать в четырёх UI-библиотеках.

Шесть красных линий

1. В src/ запрещены любые зависимости от фреймворков

// ❌ категорически запрещено
import { ref } from 'vue'
import { useState } from 'react'
import { ... } from '@dcloudio/uniapp'

// ✅ разрешены только чистые функции и типы
export function computeSomething(input: Foo): Bar { ... }

Почему: share — единственный общий слой, не зависящий от фреймворка во всей семье. Один import 'vue' — и React-версия с uniapp-версией становятся непригодны. В CI есть гейт на основе grep.

Подключение реактивности относится к каждому UI-слою (ref() / useState() / useSyncExternalStore()), а core выдаёт только чистые данные. См. проект lhlocale: чистый генератор событий, который каждая сторона сама превращает в сигнал перерендера.

2. styles/ —— единственный источник стилей компонентов

• Запрещено копировать стили в какую-либо UI-библиотеку и править их там.
• Любые изменения стилей происходят только в этом репозитории.

Межплатформенные различия transition-классов унифицированы тремя transition-mixin-ами; в стилях компонентов запрещено писать двойные имена классов вручную — везде используется @include. Если состояние нужно повесить на узел-потомок, передаётся второй параметр.

3. Unit-тесты core существуют в единственном экземпляре

tests/unit/ — результат тестов, разделяемый тремя библиотеками. UI-библиотекам запрещено копировать unit-тесты core из этого репозитория.

4. Границы в 1px должны были иметь маркер /* hairline */ —— упразднено

uniapp v3 выводит px напрямую, больше не перетранслирует rpx, и маркер hairline потерял назначение (см. docs/bugfix-log.md, D-02). 65 исторических марок внутри styles/ сохранены как обычные комментарии; для новых границ в 1px маркер не нужен. Структурные границы (2px / 3px) и так никогда не маркировались.

5. Порядок релизов: сначала share, затем UI-библиотеки

Изменение share → changeset → релиз → регрессия в каждой библиотеке через pnpm up @lh-ui/share. Пропускать нельзя — релиз UI-библиотек зависит от уже опубликованного tarball’а share.

6. Собственные символы обязаны иметь префикс LH

При добавлении новых констант / типов / интерфейсов соблюдайте сразу, не оставляйте на потом под единое переименование (историческое переименование — см. changeset lh-prefix-naming).

Соглашения об именовании

Выровнены с docs/project/development-guide.md в репозитории plus и едины для всей семьи:

Слой	Правило	Пример
Корень обратного домена	top.lhgb (www.lhgb.top наоборот)	корень именования всех репозиториев семьи; homepage / repository / author в package.json используют lhgb.top
Имена JS / npm-пакетов	scope @lh-ui/*	точка в имени npm-пакета не допускается, обратный домен уходит в слой метаданных
Константы	LH_XXX, LH_<модуль>_<концепция>	LH_SIZE_DEFAULT, LH_THEME_PRESETS
Константы значений по умолчанию	суффикс DEFAULT	LH_DRAWER_DIRECTION_DEFAULT
Типы / интерфейсы	LhXxx	LhThemePreset, LhSxProps
Модульные синглтоны / объекты в lowerCamelCase	lhXxx	lhlocale
BEM class-имена	lh-xxx	lh-button__text--disabled
name компонента	LhXxx	name: 'LhButton'

Реестр исключений

Устоявшиеся имена, для которых префикс не обязателен (перед изменением регистрируйте здесь причину):

• Экспорт языковых пакетов zhCN / enUS — стандартное именование locale, к тому же все три UI-библиотеки реэкспортируют их как публичный API; переименование нанесло бы слишком большой урон.
• Строковые значения имён preset’ов темы (name: 'cerblue' и т. п.) — это значения конфигурации, которые пользователи пишут в theme компонента ConfigProvider; изменение сломает конфигурации всех пользователей downstream. Соответствующие TS-идентификаторы по-прежнему имеют префикс (LhCerblue).
• Символы экспорта сторонних зависимостей — префикс не требуется.

Ответственность каталогов

Каталог	Ответственность
src/core/<name>/	чистая функциональная логика компонента (logic.ts / types.ts / index.ts), нулевой импорт фреймворков
src/core/shared/	общее ядро, разделяемое между компонентами (12 модулей, см. обзор)
src/theme/	TS-сторона темы (типы + пять preset’ов)
src/constants/ / src/locales/ / src/types/ / src/utils/	константы / языковые пакеты / типы / чистые утилиты
styles/	единственный источник BEM-стилей компонентов (<name>/index.scss + theme/common/*.scss)
tests/unit/	единственная копия unit-тестов core
scripts/	сценарии сборки и проверок
docs/	сайт документации (Astro Starlight), не входит в npm-артефакт

Соглашения о сообщениях коммитов

• Комментарии и сообщения коммитов пишутся на китайском языке.
• Сообщение коммита пишется на исходном markdown и очень подробно: строка заголовка + описание области + список добавленных / изменённых файлов + таблица ключевых решений + статус проверки.
• Конфигурация Prettier: одинарные кавычки, без точек с запятой, 2 пробела, printWidth 100. pnpm format покрывает только конфигурационные файлы; остальное выравнивается вручную.

Чек-лист добавления нового компонента core

1. Трёхэлементный набор src/core/<name>/{logic,types,index}.ts
2. tests/unit/core/<name>.spec.ts
3. Экспорт в src/core/index.ts
4. styles/<name>/index.scss (иначе на одном из концов не будет стилевого артефакта — молчаливый пропуск)
5. changeset (minor)

Затем выполняются:

pnpm test && pnpm lint && pnpm typecheck
pnpm build                    # sync:exports генерирует новый ключ exports
pnpm verify:dts && pnpm verify:styles

Чек-лист перед PR

• В src/ нет ни одного import 'vue' | 'react' | '@dcloudio/*' (красная линия 1)
• Изменения стилей только в styles/ (красная линия 2)
• Цвета везде var(--lh-*, fallback), новых жёстко заданных цветовых значений нет
• Новые transition-классы идут через mixin, без прямого написания -enter-from / -leave-from
• Новые токены — в var.scss; если значение — интерполяция #{$lh-*}, то в var-dark.scss есть соответствующее переопределение
• Новые символы несут префикс LH / Lh (красная линия 6)
• pnpm test / pnpm lint / pnpm typecheck проходят
• После pnpm build проходят pnpm verify:dts / pnpm verify:styles
• Есть changeset с корректным уровнем
• У нового компонента есть styles/<name>/index.scss и существует tests/unit/core/<name>.spec.ts (красная линия 3)
• Если изменялись токены / class-имена / иконки — выполнен pnpm docs:data для обновления данных документации

Известенные задачи (записаны как будущие changeset’ы, можно брать в работу)

«Специальная задача по токенам высоты»:

1. Высоты контролов не унифицированы (input 37 / select 32 / cascader 27→32 / date-time 33 / input-number 32); корневая причина — отсутствие токена --lh-control-height-* в var.scss
2. Асимметричный padding-top: 16px у --has-label в input
3. Несовпадение значений размеров у spinner и icon для одного и того же имени ступени (small 16 vs 14)
4. У галочки checkbox фиксированные top:2/left:5 вместо центрирования по 50% (для рамки 16px это правильно, при изменении размера — смещается)
5. translate(-50%,-50%) у switch дублируется как жёстко заданные значения в base и keyframes

Связанные документы

• Введение в проект —— место share в семье
• Соглашения об именовании —— полная версия правил именования
• Стратегия инъекции стилей на концах —— механизм, обеспечивающий красную линию 2
• Система проверок —— проверки, которые нужно выполнить перед PR
• Процесс выпуска релиза —— полный процесс по красной линии 5