@reco-inc/upbox-ui 0.1.1

package/README.md

@@ -0,0 +1,217 @@
+# @reco-inc/upbox-ui
+
+Upbox Design System - Vue 3 Component Library
+
+## Storybook
+
+[Live Storybook](https://reco-inc.github.io/upbox-ui/)
+
+## Installation
+
+```bash
+# npm
+npm install @reco-inc/upbox-ui
+
+# pnpm
+pnpm add @reco-inc/upbox-ui
+```
+
+저장소는 private 이지만 패키지는 npm public 레지스트리에 배포되므로, 설치에 별도 인증이 필요 없다.
+
+## Setup (Tailwind v4)
+
+### 1. CSS Import
+
+```css
+/* style.css */
+@import "tailwindcss";
+@import "@reco-inc/upbox-ui/style.css";   /* 컴파일된 라이브러리 CSS */
+@import "@reco-inc/upbox-ui/theme.css";   /* @theme 토큰 등록 */
+@source "../node_modules/@reco-inc/upbox-ui/dist/**/*.mjs";
+```
+
+### 2. Vue Template Autocomplete (권장)
+
+Consumer 프로젝트의 `env.d.ts` 또는 `vite-env.d.ts`에 추가:
+
+```ts
+/// <reference types="@reco-inc/upbox-ui/global" />
+```
+
+이렇게 하면 `.vue` 파일 `<template>`에서 컴포넌트 자동완성이 동작합니다.
+
+### 3. Use Components
+
+```vue
+<script setup lang="ts">
+import { Button, Card, CardHeader, CardTitle, CardContent } from '@reco-inc/upbox-ui'
+</script>
+
+<template>
+  <Card>
+    <CardHeader>
+      <CardTitle>Title</CardTitle>
+    </CardHeader>
+    <CardContent>
+      <Button variant="primary" size="regular">Click</Button>
+    </CardContent>
+  </Card>
+</template>
+```
+
+### 4. i18n (필수)
+
+일부 컴포넌트(`DropdownFilter`, `FileUploader`, `TimePicker` 등)는 소비 앱의 `useI18n()` 으로
+문구를 찾습니다. 기본 문구는 DS 가 갖고 있으니, 앱 메시지 아래에 깔아 주세요.
+
+```ts
+import { createI18n } from 'vue-i18n'
+// 컴포넌트를 물지 않는 i18n 전용 진입점. root barrel 로 받으면 문구 하나 때문에
+// 컴포넌트 번들 전체가 딸려 온다
+import { mergeMessages } from '@reco-inc/upbox-ui/i18n'
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'ko',
+  // 같은 키가 양쪽에 있으면 앱 메시지가 이깁니다
+  messages: mergeMessages({ ko: appKo, en: appEn }),
+})
+```
+
+깔지 않으면 화면에 `common.search` 같은 키 문자열이 그대로 노출됩니다.
+DS 가 문구를 제공하지 않는 로케일(예: `jp`)은 앱 메시지를 그대로 둡니다.
+
+문구를 바꾸고 싶으면 두 가지 방법이 있습니다.
+
+- 한 곳만 바꿀 때는 컴포넌트 props (`search-placeholder`, `select-all-text` 등)
+- 앱 전체에서 바꿀 때는 앱 메시지에 같은 키를 정의
+
+## Components
+
+| Category | Components |
+|----------|-----------|
+| General | Button, IconButton, TextButton, Fab, Badge, BadgeDivider, Tag, Spinner, Skeleton, Empty, Stepper |
+| Layout | PageHeader |
+| Form | TextField, Textarea, NumberField, SearchField, Checkbox, Toggle, RadioGroup, RadioGroupField, Select, SelectField, Label, FieldContainer (vee-validate), InputFrame, InputGroup |
+| Data Display | Card, Table, DataTable, Accordion, Avatar, Tabs, TabsBar, Separator |
+| Overlay | Dialog, Modal, Sheet, Drawer, Popover, Tooltip, Toast |
+| Navigation | Breadcrumb, Pagination, Sidebar, DropdownMenu |
+| Filter | DropdownFilter, FilterChip |
+| Date | Calendar, DatePicker, DatePeriodPicker, TimePicker, DateMove (+ Mobile variants) |
+| File | FileUploader |
+
+### Flat vs Compound
+
+일부 컴포넌트는 자주 쓰는 형태를 **flat(props 중심) API**로 제공하고, 같은 primitive 위에서 자유 조합이 필요할 땐 **compound**를 그대로 사용합니다 (escape hatch).
+
+| Flat (흔한 케이스) | Compound (자유 조합) |
+|----|----|
+| `Modal` (title/description/confirm·cancel/actions) | `Dialog` + `DialogContent`/`Header`/`Footer`… |
+| `DataTable` (`:columns`/`:rows`/선택/슬롯) | `Table` + `TableHeader`/`Row`/`Cell`… |
+| `TabsBar` (`:items`) | `Tabs` + `TabsList`/`Trigger`/`Content` |
+| `SelectField` (`:options`) | `Select` + `SelectTrigger`/`Content`/`Item` |
+| `RadioGroupField` (`:options`) | `RadioGroup` + `RadioGroupItem` |
+| `DropdownFilter` (`:options`) | `DropdownMenu` + … |
+
+## Design Tokens
+
+CSS variables for colors, typography, spacing are included in `style.css`.
+
+### Color System
+
+Figma 팔레트 이름을 그대로 사용:
+
+- `grey` (10-100): Grayscale
+- `navy` (20-100): Brand / primary CTA
+- `blue` (20-100): Informative
+- `green` (20-100): Positive
+- `red` (20-100): Negative / destructive
+- `orange` (20-100): Warning
+
+### Dark Mode
+
+Add `class="dark"` to the root element. All color tokens automatically invert.
+
+## Development
+
+```bash
+pnpm install        # Install dependencies
+pnpm build          # Build library
+pnpm dev            # Watch mode
+pnpm typecheck      # Type check
+pnpm storybook      # Storybook dev server (localhost:6006)
+pnpm release        # 릴리스 (아래 "배포 & 업데이트" 참고)
+```
+
+## 배포 & 업데이트
+
+npm public 레지스트리(`@reco-inc/upbox-ui`)로 배포한다. 저장소는 private 이고 빌드 산출물만 공개된다.
+
+### 릴리스
+
+```bash
+pnpm release          # patch  0.1.0 -> 0.1.1
+pnpm release minor    # minor  0.1.0 -> 0.2.0
+pnpm release major    # major  0.1.0 -> 1.0.0
+pnpm release 0.4.2    # 특정 버전 지정
+```
+
+한 번 실행하면 아래를 순서대로 처리한다.
+
+1. `pnpm build` 후 `dist/` 가 바뀌었으면 함께 커밋
+2. `package.json` 버전 bump + 커밋 + `v0.1.1` 태그 생성
+3. `git push --follow-tags`
+4. `gh release create` 로 GitHub Release 발행
+5. Release 발행에 반응해 `.github/workflows/publish-npm.yml` 이 npm 에 배포
+
+`main` 이 아니거나, 커밋 안 된 변경이 있거나, `origin/main` 과 어긋나면 중단한다.
+소스만 커밋해 두면 `dist/` 재빌드·커밋은 릴리스 스크립트가 알아서 한다.
+
+### 배포 인증
+
+CI 배포에는 저장소 secret `NPM_TOKEN` 이 필요하다. npmjs 에서 **granular access token**
+을 발급해 등록한다 — `@reco-inc` **스코프** 선택 / Read and write / IP 제한은 비워둔다
+(GitHub Actions 러너 IP 가 고정이 아니다).
+
+```bash
+gh secret set NPM_TOKEN --repo RECO-Inc/upbox-ui
+```
+
+로컬에서 직접 `npm publish` 하는 경우, 계정에 2FA 가 걸려 있으면 OTP 를 넘겨야 한다.
+
+```bash
+npm publish --otp=123456
+```
+
+> `.npmrc` 에 `@reco-inc:registry` 를 두지 않는다. scope registry 설정은
+> `publishConfig.registry` 보다 우선하므로 배포 대상이 조용히 바뀐다.
+
+### Consumer 프로젝트 업데이트
+
+```bash
+pnpm update @reco-inc/upbox-ui
+```
+
+### Stories 추가/수정 시
+
+- Stories 파일 수정 후 `pnpm build` → dist 의 `.stories.d.ts` 도 함께 커밋
+- `main` 브랜치 push 시 Storybook 이 GitHub Pages 에 자동 배포됨
+
+### 새 컴포넌트 추가 시 체크리스트
+
+1. `src/components/<name>/` 에 컴포넌트 생성
+2. `src/components/<name>/index.ts` 에서 export
+3. `src/index.ts` 에 `export * from './components/<name>'` 추가
+4. `src/global.ts` 에 GlobalComponents 타입 선언 추가
+5. Stories 파일 작성
+6. `pnpm build` 후 dist 포함하여 커밋
+
+## Tech Stack
+
+- Vue 3 + TypeScript
+- Tailwind CSS + CSS Variables (Design Tokens)
+- Reka UI (Headless components)
+- Class Variance Authority (Variant system)
+- Vite (Library mode build)
+- vite-plugin-dts (Type declaration generation)
+- Storybook (Component documentation & playground)