@x-plat/design-system 0.5.0 → 0.5.2

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 |

package/guidelines/components/select.md

@@ -0,0 +1,44 @@
+# Select
+
+**Select.Item만 children으로 허용한다.**
+
+```tsx
+<Select placeholder="선택하세요" onChange={(value, label) => console.log(value)}>
+  <Select.Item value="apple">사과</Select.Item>
+  <Select.Item value="banana">바나나</Select.Item>
+</Select>
+```
+
+## onChange
+
+`onChange(value: string, label: string)` 형태로 선택된 값과 라벨을 전달한다.
+
+## Controlled / Uncontrolled
+
+```tsx
+// controlled
+<Select value={selected} onChange={(v) => setSelected(v)}>
+  <Select.Item value="a">A</Select.Item>
+</Select>
+
+// uncontrolled
+<Select defaultValue="a">
+  <Select.Item value="a">A</Select.Item>
+</Select>
+```
+
+## 상태
+
+| 상태 | 설명 |
+|------|------|
+| error | 에러 표시 |
+| disabled | 비활성화 |
+
+---
+
+## 유사 컴포넌트 구분
+
+| 목적 | 사용할 것 |
+|------|----------|
+| 값 선택 (onChange) | Select |
+| 액션 메뉴 (onClick per item) | Dropdown |

package/guidelines/components/swiper.md

@@ -0,0 +1,84 @@
+# Swiper
+
+슬라이더/캐러셀을 표시한다. 드래그, 자동 재생, 루프를 지원하며 controlled/uncontrolled 모두 가능하다.
+
+```tsx
+import { Swiper } from "@xplat/design-system";
+import type { SwiperHandle } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| renderItems | `ReactNode[]` | `[]` | 슬라이드 아이템 배열 |
+| viewItemCount | `number` | `1` | 한 번에 보이는 아이템 수 |
+| maxItems | `number` | — | 최대 아이템 수 (초과 시 잘림) |
+| spaceBetween | `number` | `16` | 슬라이드 간격 (px) |
+| speed | `number` | `300` | 전환 속도 (ms) |
+| slideBy | `number` | `1` | 한 번에 이동할 슬라이드 수 |
+| auto | `boolean` | `false` | 자동 슬라이딩 |
+| autoplayDelay | `number` | `3000` | 오토플레이 간격 (ms) |
+| loop | `boolean` | `false` | 무한 루프 |
+| showProgress | `boolean` | `false` | 진행바 표시 |
+| index | `number` | — | 현재 인덱스 (controlled) |
+| onChange | `(index: number) => void` | — | 슬라이드 변경 콜백 |
+| swiperRef | `RefObject<SwiperHandle>` | — | 명령형 제어 ref |
+
+### SwiperHandle
+
+| 메서드 | 설명 |
+|--------|------|
+| `slidePrev()` | 이전 슬라이드로 이동 |
+| `slideNext()` | 다음 슬라이드로 이동 |
+| `slideTo(index)` | 특정 인덱스로 이동 |
+
+---
+
+## 사용 예시
+
+### 기본
+
+```tsx
+<Swiper
+  renderItems={[
+    <img src="/img1.jpg" />,
+    <img src="/img2.jpg" />,
+    <img src="/img3.jpg" />,
+  ]}
+/>
+```
+
+### 자동 재생 + 루프 + 진행바
+
+```tsx
+<Swiper
+  renderItems={slides}
+  auto
+  loop
+  showProgress
+  autoplayDelay={5000}
+/>
+```
+
+### 명령형 제어
+
+```tsx
+const ref = useRef<SwiperHandle>(null);
+
+<Swiper swiperRef={ref} renderItems={slides} />
+
+<button onClick={() => ref.current?.slidePrev()}>이전</button>
+<button onClick={() => ref.current?.slideNext()}>다음</button>
+```
+
+### 다중 아이템 뷰
+
+```tsx
+<Swiper
+  renderItems={cards}
+  viewItemCount={3}
+  spaceBetween={24}
+  slideBy={3}
+/>
+```

package/guidelines/components/table.md

@@ -0,0 +1,62 @@
+# Table
+
+**반드시 `Table > TableHead/TableBody > TableRow > TableCell` 구조를 따른다.**
+
+```tsx
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableCell>이름</TableCell>
+      <TableCell>나이</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>홍길동</TableCell>
+      <TableCell>30</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Props
+
+| Prop | 설명 |
+|------|------|
+| headerSticky | 헤더 고정 |
+| isSticky | 특정 셀 고정 |
+
+## TableRow type
+
+| type | 용도 |
+|------|------|
+| primary | 기본 행 |
+| secondary | 보조 행 (배경색 구분) |
+
+---
+
+## 올바른 예시
+
+```tsx
+<Table headerSticky>
+  <TableHead>
+    <TableRow>
+      <TableCell isSticky>이름</TableCell>
+      <TableCell>부서</TableCell>
+      <TableCell>직급</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow type="primary">
+      <TableCell isSticky>홍길동</TableCell>
+      <TableCell>개발팀</TableCell>
+      <TableCell>선임</TableCell>
+    </TableRow>
+    <TableRow type="secondary">
+      <TableCell isSticky>김철수</TableCell>
+      <TableCell>디자인팀</TableCell>
+      <TableCell>책임</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```

package/guidelines/composition/grid.md

@@ -0,0 +1,95 @@
+# Grid 시스템
+
+페이지 레이아웃과 컴포넌트 내부 배치 모두 Grid를 사용한다.
+
+```tsx
+import { FullGrid, FullScreen, GridItem } from "@x-plat/design-system/layout";
+```
+
+## 컴포넌트
+
+| 컴포넌트 | 용도 |
+|---------|------|
+| FullGrid | 12컬럼 그리드 컨테이너 |
+| FullScreen | 전체 화면 그리드 |
+| GridItem | 그리드 아이템 |
+
+## gap
+
+```tsx
+<FullGrid gap={16}>
+  <GridItem column={6}>왼쪽</GridItem>
+  <GridItem column={6}>오른쪽</GridItem>
+</FullGrid>
+```
+
+---
+
+## 반응형 브레이크포인트
+
+| 브레이크포인트 | 범위 | 최대 컬럼 |
+|---------------|------|-----------|
+| laptop (default) | 1024px ~ | 12 |
+| tablet | 768px ~ 1024px | 8 |
+| mobile | ~ 768px | 4 |
+
+## Column 상속 규칙
+
+하위 브레이크포인트를 지정하지 않으면 상위 값을 상속한다.
+
+```tsx
+<GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+  내용
+</GridItem>
+```
+
+---
+
+## 위젯 패턴
+
+### 대시보드
+
+```tsx
+<FullGrid>
+  <GridItem column={{ default: 4, tablet: 4, mobile: 4 }}>
+    <Card>위젯 A</Card>
+  </GridItem>
+  <GridItem column={{ default: 4, tablet: 4, mobile: 4 }}>
+    <Card>위젯 B</Card>
+  </GridItem>
+  <GridItem column={{ default: 4, tablet: 8, mobile: 4 }}>
+    <Card>위젯 C</Card>
+  </GridItem>
+</FullGrid>
+```
+
+### 폼
+
+```tsx
+<FullGrid>
+  <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+    <Input placeholder="이름" />
+  </GridItem>
+  <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+    <Input placeholder="이메일" type="email" />
+  </GridItem>
+  <GridItem column={{ default: 12, tablet: 8, mobile: 4 }}>
+    <Button type="primary">저장</Button>
+  </GridItem>
+</FullGrid>
+```
+
+### 중첩 Grid
+
+```tsx
+<Card title="사용자 정보">
+  <FullGrid>
+    <GridItem column={{ default: 3, tablet: 2, mobile: 4 }}>
+      <Avatar name="홍길동" size="lg" />
+    </GridItem>
+    <GridItem column={{ default: 9, tablet: 6, mobile: 4 }}>
+      <Input placeholder="이름" />
+    </GridItem>
+  </FullGrid>
+</Card>
+```