@weing-dev/ui-kit-primitive

weing 어드민/서비스 프런트의 공통 UI 프리미티브 패키지. 폼·네비게이션·피드백·표시·데이터(차트/테이블/캘린더/에디터/비디오)까지 화면 구성에 필요한 컴포넌트를 한곳에서 제공한다. 대부분 Compound 컴포넌트 패턴(Button.Root + Button.Text …)과 CSS 변수 토큰 테마로 만들어져 있다.

화면/마크업 작업 전 필독 (사람·에이전트 공통) 새 컴포넌트를 만들기 전에 에이전트 UI 가이드 → docs/ui-kit-agent-guide.md 를 먼저 확인하라. 아래 카탈로그의 40개 컴포넌트가 대부분의 화면 요구를 이미 커버한다. 중복 구현은 피한다.

관련 문서:

• 에이전트 UI 가이드 — 목적→컴포넌트 매핑, 전체 API 카탈로그, 합성 예시, 소비 컨벤션, 금지/함정. (마크업 에이전트의 1차 참조 문서)
• 서브패스 import 가이드 — 번들 분리를 위한 서브패스별 import 규칙.

컴포넌트 인덱스

import 서브패스는 @weing-dev/ui-kit-primitive/<서브패스>. 자세한 props·예시는 에이전트 UI 가이드 참조.

Form — /form

| 컴포넌트 | 용도 | 구조 | | --- | --- | --- | | Button | 액션 버튼(로딩·아이콘·텍스트 합성) | Root / Text / Icon | | TextInput | 한 줄 텍스트 입력(라벨·지우기·아이콘) | Root / Label / Input / Erase / HelperText | | TextArea | 여러 줄 입력(자동 높이·글자수) | Root / Label / Input / Erase / HelperText / TextCount | | Dropdown | 단일/다중 셀렉트(검색·popper) | Root / Trigger / Menu / Item | | CheckBox | 체크박스(단일/다중) | Root / Trigger / Label / HelperText | | Radio | 라디오(그룹 단일 선택) | Root / Trigger / Label / HelperText | | Switch | on/off 토글 | Root / Trigger / Label | | Cascader | 계층형 다단계 선택 | Root / Menu / Column / Item | | OTPInput | 고정 자리수 코드 입력 | Root / Input | | Slider | 단일/범위 슬라이더 | Root / Progress / Thumb / Marks | | Stepper | 다단계 진행 표시 | Root / Step | | TimeInput | 시작~종료 시간 범위 | Root / Label / InputWrapper / Input / Colon / Separator / TimeRange / HelperText | | MobilePicker | 휠(드럼) 피커 | Root / Column / Item | | HelperText | 입력 하단 상태 안내 문구 | 단일 |

Navigation — /navigation

| 컴포넌트 | 용도 | 구조 | | --- | --- | --- | | Tab | 탭 + 패널 전환 | Root / List / Item / Panels / Panel | | Accordion | 펼침/접힘 영역 | Root / Trigger / Item | | Breadcrumb | 경로 내비게이션 | List / Link / Separator / Ellipsis | | Pagination | 페이지네이션(offset/limit) | Root / PageList / PageItem / Prev / Next | | LNB | 좌측 글로벌 메뉴(+makeNavigation) | Root / Logo / List / Item | | List | 단일 행 리스트 아이템 | 단일 | | ScrollSpy | 스크롤 위치 추적 훅 | useScrollSpy 훅 |

Feedback — /feedback

| 컴포넌트 | 용도 | 구조 | | --- | --- | --- | | Modal | 포털 딤드 모달 | 단일(visible/onClose/dimmedColor) | | Popup | Popover API 팝업(+usePopup) | Root / Layer / Dimmed / Contents | | Sheet | 드래그 가능한 4방향 시트 | Root / Content / Dimmed |

Display — /display

| 컴포넌트 | 용도 | 구조 | | --- | --- | --- | | Label | 상태/카테고리 라벨(태그) | 단일 | | Chips | 선택 가능한 칩 | 단일 | | Badge | 카운트/점 배지 오버레이 | 단일 | | Avatar | 프로필 이미지(+그룹) | Item / Group | | Thumbnail | 업로드·수정·삭제 썸네일 | Root / Image / Upload / EmptyImage / RemoveButton / EditButton | | Comment | 상태 아이콘 + 보조 메시지 | 단일 | | Divider | 구분선 | 단일 | | LazyImage | 지연 로딩 이미지 | 단일 | | QRCode | QR 코드 | 단일 | | BarCode | EAN8/EAN13 바코드 | 단일 |

Data / Heavy (전용 서브패스 + 일부 CSS 별도)

| 컴포넌트 | 서브패스 | 비고 | | --- | --- | --- | | Table | /table | @tanstack/react-table와 조합, 렌더 전용 | | BarChart LineChart PieChart DoughnutChart | /chart | chart.js 기반, ChartThemeProvider | | Calendar ScrollCalendar WeeklyCalendar | /calendar | dayjs 기반 | | Editor | /editor | Quill, editor/style.css 별도 import 필수 | | VideoPlayer | /video-player | Video.js, video-player/style.css 별도 import 필수 | | Icon IconProvider ICON_NAMES | /icon | 레지스트리 기반, 앱 루트를 IconProvider로 감싸야 함 |

미사용/비공개(쓰지 말 것): Dialog(빈 스텁), WisywygEditor(레거시, 미export — 신규는 Editor 사용), radar 차트(미export).

임포트 시 실제 로드량 확인 방법

특정 export만 import 했을 때 실제 로드량을 확인하려면:

1. 소비 앱에서 production 빌드 후 번들 분석기로 청크 크기 확인
2. 빌드 산출물을 서빙한 뒤 브라우저 Network 탭에서 JS 파일 크기 비교

모노레포에서 이 패키지를 소스로 참조하면 번들러가 tree-shaking으로 필요한 부분만 포함한다. 무거운 의존성(차트·에디터·비디오·테이블)은 서브패스가 의도적으로 분리돼 있으니 루트 배럴 대신 서브패스 import를 권장한다(근거).

아이콘 추가

public/static/icon에 SVG를 넣고 pnpm icons:create 실행 → svgr이 src/components/Icons/*.tsx를 생성하고 generate-icon-names.cjs가 ICON_NAMES를 재생성한다. ICON_NAMES는 수기 작성하지 않는다.

빌드

pnpm build   # tsc -b && vite build && vite build --config vite.icon.config.ts

메인 라이브러리는 vite.config.ts, 서브패스 청크는 vite.icon.config.ts(이름은 icon이지만 chart·form 등 전 엔트리 포함).