프로젝트 소개

@lh-ui/share는 lh-ui 컴포넌트 패밀리의 유일한 프레임워크 비종속 공유 레이어입니다.

컴포넌트 라이브러리에서 “프레임워크와 무관한 절반”을 꺼내어 별도 저장소로 만들었습니다: 클래스명 계산, 상태 머신, 접근성 속성 팩, 배치 엔진, 가상 스크롤, 테마 토큰, 국제화 문구, 컴포넌트 스타일 소스. 각 단말 UI 라이브러리(lh-ui-plus / lh-ui-vue2 / lh-ui-react / lh-ui-uniapp)는 릴리스 시 npm 의존성으로 이 패키지를 사용하고, 패밀리 내 로컬 개발에서는 이 저장소의 소스를 고치면 각 UI 라이브러리에 즉시 반영되며 빌드나 릴리스가 필요 없습니다.

왜 이 레이어가 필요한가

컴포넌트 라이브러리의 논리 중 실제로 프레임워크의 반응성에 의존하는 부분은 극히 일부입니다:

어떤 클래스명을 추가해야 하는지는 (size, disabled) => string의 순수 계산입니다.
드롭다운 패널이 어느 쪽으로 뒤집힐지는 기하학적 계산입니다.
리스트가 몇 행을 렌더링할지는 인덱스 구간 계산입니다.
“확인” 버튼의 문구는 언어 팩 조회입니다.

이것들을 순수 함수로 가라앉히면, 네 단말은 각자 따로 작성하고, 각자 따로 틀리고, 각자 따로 고칠 필요가 없어집니다. 프레임워크 계층에 남는 일은 하나뿐입니다: 순수 함수의 출력을 템플릿에 묶고, 사용자 입력을 순수 함수로 되돌려 보내는 것.

저장소에 무엇이 있는가

레이어	내용	개수
`src/core/<컴포넌트>/`	컴포넌트 순수 함수(logic.ts / types.ts), 프레임워크 import 없음	56개 컴포넌트
`src/core/shared/`	컴포넌트 횡단 공유 코어(popper / virtual / sx / keyboard / focus-trap …)	12개 모듈
`src/theme/`	테마 TS 측: 타입 + 5개 프리셋 + 런타임 원시	—
`styles/`	컴포넌트 BEM 스타일 유일 소스 + `theme/common/*.scss` 토큰	58세트 컴포넌트 스타일
`src/locales/`	국제화(LhLocale은 순수 이벤트 에미터) + 6개 언어 골격	—
`src/constants/` `src/types/` `src/utils/`	상수 / 타입 / 순수 유틸리티(createNamespace 포함)	—

집계 기준: core는 56개 컴포넌트 디렉터리, styles는 58세트입니다 —— layout / tree-select는 스타일 소스가 있지만 논리는 모두 UI 계층에 있고(레이아웃 컨테이너, 트리 선택기의 프레임워크 측 접착), config는 스타일 디렉터리에서 config-provider라는 이름을 씁니다. 자세한 내용은 패키지 구조를 참고하세요.

설계 원칙

프레임워크 의존성 없음: src/ 안에서 import 'vue' | 'react' | '@dcloudio/*'를 금지하며, CI grep 게이트가 지킵니다. 이 패키지는 external: []로 완전한 무의존성 번들입니다.
스타일 단일 소스: styles/는 패밀리 전체의 컴포넌트 BEM 스타일 유일 소스이며, 어떤 UI 라이브러리도 로컬에 컴포넌트 scss 사본을 가져서는 안 됩니다. 단말 간 전환 클래스명 차이는 transition.scss의 3개 mixin이 통합합니다.
단위 테스트 유일 사본: core 단위 테스트는 이 저장소의 tests/unit/에만 있으며, 세 라이브러리가 이 결과를 공유하고 복사하지 않습니다.
반응성은 UI 계층으로: core는 데이터만 만들고, 구독 / 반응성 연결은 각 UI 라이브러리에 속합니다. 그래서 LhLocale은 순수 에미터이며, version의 자동 증가로 각 단말이 자신의 메커니즘으로 다시 렌더링합니다.
밝은색 / 어두운색 동등 대우: 모든 컴포넌트는 기본적으로 밝은색과 어두운색을 지원하며, 컴포넌트는 var(--lh-*, fallback)으로만 토큰을 소비합니다. 어두운색 완전성은 verify:styles의 7번째 항목이 지킵니다.

아닌 것

UI 라이브러리가 아닙니다: 이 패키지는 아무것도 렌더링하지 않고, 컴포넌트 런타임이 없습니다. 바로 쓸 수 있는 컴포넌트를 원하면 @lh-ui/vue3 / @lh-ui/vue2 등 각 단말 라이브러리를 설치하세요.
어떤 UI 라이브러리, 어떤 프레임워크에도 의존하지 않습니다: 가장 아래 계층으로, 의존될 뿐 의존하지 않습니다.
배포 형태는 책임지지 않습니다: 테마 맞춤 설정이 만들어내는 것은 <style> 텍스트와 CSS 변수이며, 이를 DOM에 어떻게 주입할지는 각 단말의 ConfigProvider가 정합니다.

패밀리 구성

lh-ui/
├── lh-ui-share/      ← 이 저장소: 프레임워크 비종속 공유 레이어(core / theme / styles / locales)
├── lh-ui-plus/       Vue3 단말(라이브러리 진입점에서 전체 스타일 side-effect 주입)
├── lh-ui-vue2/       Vue2 단말(필요에 따라 theme.css + style/<name> import)
├── lh-ui-react/      React 단말
├── lh-ui-uniapp/     uniapp 단말
├── docs/             패밀리 문서 사이트(별도 저장소)
└── native/           네이티브 단말(android / ios / harmony, applicationId는 top.lhgb.* 사용)

릴리스 순서는 강제 제약입니다: share가 먼저 릴리스되고, UI 라이브러리가 그 뒤를 따릅니다. share가 바뀌면 → 체인지셋 작성 → 릴리스 → 각 라이브러리에서 pnpm up @lh-ui/share로 회귀합니다.

다음 단계

시작하기 —— 패키지 설치, 스타일 import, 첫 순수 함수 실행
패키지 진입점과 하위 경로 —— 77개 내보내기 키를 필요에 따라 고르는 법
각 단말에서의 사용 —— Vue3 / Vue2 / React / uniapp 연결 예제