@weing-dev/ui-kit-primitive 0.5.0 → 0.5.2

package/README.md

@@ -1,65 +1,102 @@
 # `@weing-dev/ui-kit-primitive`
 
-외부 프로젝트에서 **패키지 서브패스별로 무엇을 import 할지** 정리한 문서: [서브패스 import 가이드](./docs/subpath-imports.md).
+weing 어드민/서비스 프런트의 **공통 UI 프리미티브** 패키지. 폼·네비게이션·피드백·표시·데이터(차트/테이블/캘린더/에디터/비디오)까지 화면 구성에 필요한 컴포넌트를 한곳에서 제공한다. 대부분 **Compound 컴포넌트 패턴**(`Button.Root` + `Button.Text` …)과 **CSS 변수 토큰 테마**로 만들어져 있다.
 
----
+> **화면/마크업 작업 전 필독 (사람·에이전트 공통)**
+> 새 컴포넌트를 만들기 전에 **[에이전트 UI 가이드 → `docs/ui-kit-agent-guide.md`](./docs/ui-kit-agent-guide.md)** 를 먼저 확인하라.
+> 아래 카탈로그의 40개 컴포넌트가 대부분의 화면 요구를 이미 커버한다. 중복 구현은 피한다.
 
-# React + TypeScript + Vite
+관련 문서:
+- **[에이전트 UI 가이드](./docs/ui-kit-agent-guide.md)** — 목적→컴포넌트 매핑, 전체 API 카탈로그, 합성 예시, 소비 컨벤션, 금지/함정. (마크업 에이전트의 1차 참조 문서)
+- **[서브패스 import 가이드](./docs/subpath-imports.md)** — 번들 분리를 위한 서브패스별 import 규칙.
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+---
 
-Currently, two official plugins are available:
+## 컴포넌트 인덱스
+
+import 서브패스는 `@weing-dev/ui-kit-primitive/<서브패스>`. 자세한 props·예시는 [에이전트 UI 가이드](./docs/ui-kit-agent-guide.md) 참조.
+
+### 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).
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+---
 
-## Expanding the ESLint configuration
+## 임포트 시 실제 로드량 확인 방법
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+특정 export만 import 했을 때 실제 로드량을 확인하려면:
 
-- Configure the top-level `parserOptions` property like this:
+1. 소비 앱에서 production 빌드 후 번들 분석기로 청크 크기 확인
+2. 빌드 산출물을 서빙한 뒤 브라우저 Network 탭에서 JS 파일 크기 비교
 
-```js
-export default tseslint.config({
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
-```
+모노레포에서 이 패키지를 **소스로** 참조하면 번들러가 tree-shaking으로 필요한 부분만 포함한다. 무거운 의존성(차트·에디터·비디오·테이블)은 서브패스가 의도적으로 분리돼 있으니 **루트 배럴 대신 서브패스 import**를 권장한다([근거](./docs/subpath-imports.md)).
 
-- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
-- Optionally add `...tseslint.configs.stylisticTypeChecked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
-
-```js
-// eslint.config.js
-import react from 'eslint-plugin-react'
-
-export default tseslint.config({
-  // Set the react version
-  settings: { react: { version: '18.3' } },
-  plugins: {
-    // Add the react plugin
-    react,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended rules
-    ...react.configs.recommended.rules,
-    ...react.configs['jsx-runtime'].rules,
-  },
-})
-```
+## 아이콘 추가
 
-## 임포트 시 실제 로드량 확인 방법
+`public/static/icon`에 SVG를 넣고 `pnpm icons:create` 실행 → svgr이 `src/components/Icons/*.tsx`를 생성하고 `generate-icon-names.cjs`가 `ICON_NAMES`를 재생성한다. `ICON_NAMES`는 수기 작성하지 않는다.
 
-특정 export(예: `Icon`, `ICON_NAMES`)만 import 했을 때 실제로 얼마나 로드되는지 확인하려면:
+## 빌드
 
-1. **소비 앱(Storybook 등)에서 production 빌드** 후 번들 분석기로 해당 패키지/청크 크기 확인
-2. **실제 전송량**: 빌드 결과를 서빙한 뒤 브라우저 개발자도구 → Network 탭에서 JS 파일 크기 확인. Icon만 쓰는 페이지와 ICON_NAMES만 쓰는 페이지를 나눠 비교하면 됨
+```bash
+pnpm build   # tsc -b && vite build && vite build --config vite.icon.config.ts
+```
 
-모노레포에서 이 패키지를 **소스로** 참조하면 번들러가 tree-shaking으로 필요한 부분만 포함한다.
+메인 라이브러리는 `vite.config.ts`, 서브패스 청크는 `vite.icon.config.ts`(이름은 icon이지만 chart·form 등 전 엔트리 포함).