@x-plat/design-system 0.4.6 → 0.5.1

package/guidelines/components/data-display.md

@@ -0,0 +1,96 @@
+# 데이터 표시: Divider / EmptyState / Skeleton / Spinner
+
+## Divider
+
+구분선을 표시한다.
+
+```tsx
+import { Divider } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 방향 |
+
+```tsx
+<Divider />
+<Divider orientation="vertical" />
+```
+
+---
+
+## EmptyState
+
+빈 상태 안내를 표시한다.
+
+```tsx
+import { EmptyState } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| icon | `ReactNode` | 기본 폴더 아이콘 | 상단 아이콘 |
+| title | `string` | `"데이터가 없습니다"` | 제목 |
+| description | `string` | — | 부가 설명 |
+| action | `ReactNode` | — | 하단 액션 영역 (버튼 등) |
+
+```tsx
+<EmptyState
+  title="검색 결과가 없습니다"
+  description="다른 키워드로 검색해 보세요."
+  action={<Button type="primary">전체 목록</Button>}
+/>
+```
+
+---
+
+## Skeleton
+
+로딩 플레이스홀더를 표시한다.
+
+```tsx
+import { Skeleton } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| variant | `"text" \| "circular" \| "rectangular"` | `"text"` | 형태 |
+| width | `string \| number` | — | 너비 |
+| height | `string \| number` | — | 높이 |
+
+```tsx
+<Skeleton variant="text" width="200px" />
+<Skeleton variant="circular" width={48} height={48} />
+<Skeleton variant="rectangular" width="100%" height={120} />
+```
+
+---
+
+## Spinner
+
+로딩 인디케이터를 표시한다.
+
+```tsx
+import { Spinner } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 크기 |
+| type | `"brand" \| "success" \| "error" \| "warning" \| "info"` | `"brand"` | 색상 타입 |
+
+```tsx
+<Spinner />
+<Spinner size="lg" type="success" />
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 영역 구분선 | Divider |
+| 데이터가 없는 상태 안내 | EmptyState |
+| 콘텐츠 로딩 전 자리 차지 | Skeleton |
+| 로딩 중 표시 (인디케이터) | Spinner |

package/guidelines/components/datepicker.md

@@ -0,0 +1,60 @@
+# DatePicker: Calendar / DatePicker 4종
+
+## Calendar
+
+달력을 표시한다. 이벤트 표시와 `renderDay` 커스텀을 지원한다.
+
+```tsx
+<Calendar
+  events={[{ date: "2026-03-15", type: "success" }]}
+  renderDay={(date) => <span>{date.getDate()}</span>}
+/>
+```
+
+---
+
+## SingleDatePicker
+
+단일 날짜를 선택한다.
+
+```tsx
+<SingleDatePicker value={date} onChange={(d) => setDate(d)} />
+```
+
+## RangeDatePicker
+
+날짜 범위를 선택한다.
+
+```tsx
+<RangeDatePicker startDate={start} endDate={end} onChange={handleRange} />
+```
+
+## InputDatePicker
+
+Input + 드롭다운 형태이다.
+
+```tsx
+<InputDatePicker value={date} onChange={(d) => setDate(d)} />
+```
+
+## PopupDatePicker
+
+버튼 + 모달 형태이다.
+
+```tsx
+<PopupDatePicker
+  type="single"
+  component={<Button>날짜 선택</Button>}
+  value={date}
+  onChange={(d) => setDate(d)}
+/>
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 달력 표시 / 이벤트 | Calendar |
+| 날짜 선택 | DatePicker (Single/Range/Input/Popup) |

package/guidelines/components/dropdown.md

@@ -0,0 +1,49 @@
+# Dropdown
+
+액션 메뉴를 표시한다. `children`이 트리거 역할을 하며, 클릭 시 메뉴가 열린다.
+
+```tsx
+import { Dropdown } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| items `*` | `DropdownItem[]` | — | 메뉴 아이템 배열 |
+| children `*` | `ReactNode` | — | 트리거 요소 |
+
+### DropdownItem
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| key `*` | `string` | 고유 식별자 |
+| label `*` | `ReactNode` | 표시 텍스트 |
+| onClick | `() => void` | 클릭 콜백 |
+| disabled | `boolean` | 비활성화 |
+| danger | `boolean` | 위험 액션 스타일 (빨간색) |
+
+---
+
+## 사용 예시
+
+```tsx
+<Dropdown
+  items={[
+    { key: "edit", label: "수정", onClick: () => handleEdit() },
+    { key: "copy", label: "복사", onClick: () => handleCopy() },
+    { key: "delete", label: "삭제", onClick: () => handleDelete(), danger: true },
+  ]}
+>
+  <Button type="ghost">더보기</Button>
+</Dropdown>
+```
+
+---
+
+## 유사 컴포넌트 구분
+
+| 목적 | 사용할 것 |
+|------|----------|
+| 값 선택 (폼 필드) | Select |
+| 액션 실행 (메뉴) | Dropdown |

package/guidelines/components/feedback.md

@@ -0,0 +1,64 @@
+# 피드백: Alert / Toast / Badge
+
+## Alert
+
+인라인 알림을 표시한다.
+
+```tsx
+<Alert type="info">정보 메시지</Alert>
+<Alert type="success">성공</Alert>
+<Alert type="warning">경고</Alert>
+<Alert type="error" onClose={() => {}}>에러 (닫기 가능)</Alert>
+```
+
+| Prop | 설명 |
+|------|------|
+| type | `"info" \| "success" \| "warning" \| "error"` |
+| onClose | 닫기 버튼 콜백 (전달 시 닫기 버튼 표시) |
+
+---
+
+## Toast
+
+일시적 알림을 표시한다. **ToastProvider가 앱 최상위에 필수이다.**
+
+```tsx
+// 앱 루트
+<ToastProvider position="top-right">
+  <App />
+</ToastProvider>
+
+// 컴포넌트 내
+const { toast } = useToast();
+toast("success", "저장 완료");
+toast("error", "오류 발생", 5000);
+```
+
+`toast(type, message, duration?)` 형태로 호출한다.
+
+---
+
+## Badge
+
+카운트 또는 도트를 표시한다.
+
+```tsx
+<Badge type="error" count={5}><BellIcon /></Badge>
+<Badge type="success" dot><UserIcon /></Badge>
+```
+
+| Prop | 설명 |
+|------|------|
+| type | `"error" \| "success" \| "warning" \| "info" \| "brand"` |
+| count | 숫자 표시 |
+| dot | 도트만 표시 |
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 인라인 알림 (페이지 내 고정) | Alert |
+| 일시적 알림 (자동 사라짐) | Toast |
+| 카운트/상태 표시 | Badge |

package/guidelines/components/file-media.md

@@ -0,0 +1,95 @@
+# 파일/미디어: FileUpload / ImageSelector / Video
+
+## FileUpload
+
+파일 업로드 영역을 표시한다. 드래그 앤 드롭과 클릭 업로드를 모두 지원한다.
+
+```tsx
+import { FileUpload } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| accept | `string` | — | 허용 파일 타입 (예: `"image/*,.pdf"`) |
+| multiple | `boolean` | `false` | 다중 파일 허용 |
+| maxSize | `number` | — | 최대 파일 크기 (bytes). 초과 파일은 자동 필터 |
+| onChange | `(files: File[]) => void` | — | 파일 선택 콜백 |
+| label | `string` | `"파일을 드래그하거나 클릭하여 업로드"` | 안내 텍스트 |
+| description | `string` | — | 부가 설명 |
+
+```tsx
+<FileUpload
+  accept="image/*"
+  multiple
+  maxSize={5 * 1024 * 1024}
+  onChange={(files) => console.log(files)}
+  description="최대 5MB, 이미지만 허용"
+/>
+```
+
+---
+
+## ImageSelector
+
+단일 이미지를 선택/미리보기하는 컨트롤이다. controlled 방식으로 동작한다.
+
+```tsx
+import { ImageSelector } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| value | `File` | — | 선택된 이미지 파일 |
+| label | `string` | `"이미지 추가하기"` | 빈 상태 안내 텍스트 |
+| onChange | `(value: File \| undefined) => void` | — | 변경 콜백 (삭제 시 `undefined`) |
+
+```tsx
+const [image, setImage] = useState<File | undefined>();
+
+<ImageSelector value={image} onChange={setImage} />
+```
+
+---
+
+## Video
+
+비디오 플레이어를 표시한다. `controls={false}`이면 커스텀 재생/일시정지 오버레이를 표시한다. `ref`를 지원한다.
+
+```tsx
+import { Video } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| src `*` | `string` | — | 비디오 URL |
+| poster | `string` | — | 썸네일 이미지 URL |
+| controls | `boolean` | `true` | 네이티브 컨트롤 표시. `false`면 커스텀 오버레이 |
+| autoPlay | `boolean` | — | 자동 재생 |
+| muted | `boolean` | — | 음소거 |
+| loop | `boolean` | — | 반복 재생 |
+| playsInline | `boolean` | `true` | 인라인 재생 (모바일) |
+
+`HTMLVideoElement`의 나머지 속성도 전달 가능하다.
+
+```tsx
+const videoRef = useRef<HTMLVideoElement>(null);
+
+<Video
+  ref={videoRef}
+  src="/intro.mp4"
+  poster="/thumb.jpg"
+  controls={false}
+  muted
+  loop
+/>
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 파일 업로드 (범용) | FileUpload |
+| 이미지 1장 선택 + 미리보기 | ImageSelector |
+| 비디오 재생 | Video |

package/guidelines/components/form.md

@@ -0,0 +1,60 @@
+# 폼 컨트롤: CheckBox / Radio / Switch
+
+## CheckBox
+
+```tsx
+<CheckBox label="동의합니다" checked={checked} onChange={setChecked} />
+<CheckBox label="에러 상태" type="error" checked={false} />
+```
+
+| Prop | 설명 |
+|------|------|
+| label | 라벨 텍스트 |
+| checked | 체크 상태 |
+| type | `"brand" \| "success" \| "error" \| "warning" \| "info"` |
+
+---
+
+## Radio
+
+**RadioGroup 안에 Radio를 조합한다.**
+
+```tsx
+<RadioGroup name="fruit" value={value} onChange={(e) => setValue(e.target.value)}>
+  <Radio value="apple" label="사과" />
+  <Radio value="banana" label="바나나" />
+</RadioGroup>
+```
+
+| Prop (RadioGroup) | 설명 |
+|-------------------|------|
+| name | 그룹 이름 |
+| value | 선택된 값 |
+| onChange | 변경 콜백 |
+
+---
+
+## Switch
+
+**controlled 패턴**을 사용한다.
+
+```tsx
+<Switch value={isOn} onChange={setIsOn} />
+<Switch value={isOn} onChange={setIsOn} type="brand" />
+```
+
+| Prop | 설명 |
+|------|------|
+| value | 토글 상태 |
+| onChange | 변경 콜백 |
+| type | 스타일 타입 |
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 다중 선택 | CheckBox |
+| 단일 선택 (여러 옵션 중 하나) | Radio |
+| 켜기/끄기 토글 | Switch |

package/guidelines/components/html-typewriter.md

@@ -0,0 +1,38 @@
+# HtmlTypeWriter
+
+HTML 문자열을 한 글자씩 타이핑하는 효과를 표시한다. HTML 태그 구조를 유지하면서 텍스트만 순차적으로 렌더한다.
+
+```tsx
+import { HtmlTypeWriter } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| html `*` | `string` | — | 타이핑할 HTML 문자열 |
+| duration | `number` | `20` | 글자당 타이핑 간격 (ms) |
+| onDone | `() => void` | — | 타이핑 완료 콜백 |
+| onChange | `() => void` | — | 타이핑 진행 중 매 글자마다 호출 |
+
+---
+
+## 사용 예시
+
+```tsx
+<HtmlTypeWriter
+  html="<p>안녕하세요. <strong>타이핑</strong> 효과입니다.</p>"
+  duration={30}
+  onDone={() => console.log("타이핑 완료")}
+/>
+```
+
+### 동적 HTML 변경
+
+`html` prop이 변경되면 타이핑을 처음부터 다시 시작한다.
+
+```tsx
+const [content, setContent] = useState("<p>첫 번째 메시지</p>");
+
+<HtmlTypeWriter html={content} onDone={() => setContent("<p>두 번째 메시지</p>")} />
+```

package/guidelines/components/input.md

@@ -0,0 +1,55 @@
+# Input / PasswordInput / TextArea
+
+## Input
+
+```tsx
+<Input placeholder="이름" />
+<Input type="email" placeholder="이메일" />
+<Input
+  type="tel"
+  validations={[{ status: "error", message: "필수 항목입니다" }]}
+/>
+<Input suffix={<SearchIcon />} />
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| type | `"text" \| "number" \| "email" \| "tel"` | `"text"` | 입력 타입 |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 크기 |
+| validations | `{ status, message }[]` | - | 유효성 검사 |
+| suffix | `ReactNode` | - | 우측 아이콘 |
+
+`ref` 전달을 지원한다 (`HTMLInputElement`).
+
+---
+
+## PasswordInput
+
+비밀번호 입력 전용이다. 눈 아이콘으로 비밀번호 표시/숨김을 토글한다.
+
+```tsx
+<PasswordInput placeholder="비밀번호" />
+```
+
+---
+
+## TextArea
+
+자동 높이 조정을 지원한다. `ref` 전달을 지원한다 (`HTMLTextAreaElement`).
+
+```tsx
+<TextArea placeholder="내용을 입력하세요" />
+```
+
+---
+
+## 상태
+
+| 상태 | 설명 |
+|------|------|
+| default | 기본 |
+| hover | 마우스 오버 |
+| focused | 포커스 |
+| typing | 입력 중 |
+| filled | 입력 완료 |
+| disabled | 비활성화 |

package/guidelines/components/navigation.md

@@ -0,0 +1,80 @@
+# 내비게이션: Tab / CardTab / Breadcrumb / Pagination / Steps
+
+## Tab
+
+인덱스 기반 탭이다. 탭 영역만 제공한다.
+
+```tsx
+<Tab activeIndex={activeIndex} onChange={setActiveIndex} type="default">
+  <Tab.Item>탭1</Tab.Item>
+  <Tab.Item>탭2</Tab.Item>
+</Tab>
+```
+
+| Prop | 설명 |
+|------|------|
+| activeIndex | 활성 탭 인덱스 (controlled) |
+| type | `"default" \| "toggle"` |
+
+---
+
+## CardTab
+
+값 기반 탭이다. **CardTab.Panel만 children으로 허용한다.**
+
+```tsx
+<CardTab tabs={[{ value: "tab1", title: "탭1" }, { value: "tab2", title: "탭2" }]}>
+  <CardTab.Panel value="tab1">탭1 내용</CardTab.Panel>
+  <CardTab.Panel value="tab2">탭2 내용</CardTab.Panel>
+</CardTab>
+```
+
+---
+
+## Breadcrumb
+
+경로를 표시한다.
+
+```tsx
+<Breadcrumb items={[
+  { label: "홈", href: "/" },
+  { label: "설정", href: "/settings" },
+  { label: "프로필" },
+]} />
+```
+
+---
+
+## Pagination
+
+페이지네이션을 표시한다.
+
+```tsx
+<Pagination current={page} total={100} onChange={setPage} />
+```
+
+---
+
+## Steps
+
+단계 진행을 표시한다.
+
+```tsx
+<Steps
+  items={[
+    { title: "정보 입력" },
+    { title: "확인" },
+    { title: "완료" },
+  ]}
+  current={1}
+/>
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 탭 영역만 (콘텐츠는 직접 관리) | Tab |
+| 탭 + 패널 콘텐츠 | CardTab |

package/guidelines/components/overlay.md

@@ -0,0 +1,72 @@
+# 오버레이: Modal / Drawer / PopOver / Tooltip
+
+모두 **controlled 패턴**을 사용한다 (`isOpen`, `onClose`).
+
+---
+
+## Modal
+
+중앙 다이얼로그를 표시한다.
+
+```tsx
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
+  <h2>제목</h2>
+  <p>내용</p>
+</Modal>
+```
+
+---
+
+## Drawer
+
+사이드 패널을 표시한다.
+
+```tsx
+<Drawer isOpen={isOpen} onClose={handleClose} placement="right" width={400}>
+  <p>사이드 패널</p>
+</Drawer>
+```
+
+| Prop | 설명 |
+|------|------|
+| placement | `"left" \| "right"` |
+| width | 패널 너비 |
+
+---
+
+## PopOver
+
+트리거 요소 기반 팝오버를 표시한다.
+
+```tsx
+<PopOver
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  trigger={<Button>열기</Button>}
+>
+  <p>팝오버 내용</p>
+</PopOver>
+```
+
+---
+
+## Tooltip
+
+부가 정보를 표시한다. **description이 필수이다.** children이 트리거이다.
+
+```tsx
+<Tooltip description="도움말 텍스트">
+  <Button>호버하세요</Button>
+</Tooltip>
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 전체 화면 차단 (확인/취소) | Modal |
+| 사이드 패널 (상세 정보/폼) | Drawer |
+| 트리거 기반 부가 정보 | PopOver |
+| 간단한 설명 텍스트 | Tooltip |