@x-plat/design-system 0.9.0 → 0.10.0

package/guidelines/components/card.md

@@ -14,9 +14,9 @@ import { Box } from "@x-plat/design-system";
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
 | children * | `ReactNode` | - |  |
-| title | `ReactNode` | - |  |
-| variant | `"outlined" \| "elevated" \| "flat"` | - |  |
-| padding | `"none" \| "sm" \| "md" \| "lg"` | - |  |
+| title | `ReactNode` | - | 상자 위쪽 제목 |
+| variant | `"outlined" \| "elevated" \| "flat"` | - | 테두리·그림자 방식 |
+| padding | `"none" \| "sm" \| "md" \| "lg"` | - | 안쪽 여백 |
 
 `*` = 필수
 <!-- /props:Box -->

package/guidelines/components/feedback.md

@@ -56,7 +56,7 @@ toast("error", "오류 발생", 5000);
 | children * | `ReactNode` | - | 뱃지가 올라탈 **대상**. 뱃지에 표시할 내용이 아니다. 보통 아이콘이나 버튼을 넣는다. |
 | count | `number` | - | 표시할 개수. `count` 나 `dot` 중 하나가 없으면 **뱃지가 렌더되지 않는다** (`type` 을 줘도 아무 일도 일어나지 않는다). `count={0}` 도 표시하지 않는다 — 읽지 않은 항목이 없으면 숨기는 동작이다. |
 | dot | `boolean` | `false` | 개수 대신 점만 표시한다. `count` 없이 "새 항목 있음" 만 알릴 때 쓴다 |
-| type | `"error" \| "success" \| "warning" \| "info" \| "brand"` | `"error"` | 뱃지 색. 뱃지가 렌더될 때만 의미가 있다 |
+| type | `NotificationBadgeType \| LegacyStatusType` | `"error"` | 뱃지 색. 뱃지가 렌더될 때만 의미가 있다 |
 | maxCount | `number` | `99` | `count` 가 이 값을 넘으면 `99+` 처럼 표시한다 |
 | size | `"sm" \| "md" \| "lg"` | `"md"` | 뱃지 크기. 대상의 크기가 아니다 |
 

package/guidelines/components/navigation.md

@@ -28,11 +28,12 @@ const [activeIndex, setActiveIndex] = useState(0);
 <!-- props:Tab -->
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
-| activeIndex * | `number` | - |  |
-| tabs * | `{ value: string \| number; title: string }[]` | - |  |
-| onChange * | `(value: { value: string \| number; title: string }, index: number) => void` | - |  |
-| type * | `"default" \| "toggle"` | - |  |
-| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
+| activeIndex * | `number` | - | 활성 탭 인덱스. controlled 전용이라 onChange 와 함께 쓴다 |
+| tabs * | `{ value: string \| number; title: string }[]` | - | 탭 목록. children 을 받지 않는다 |
+| onChange * | `(value: { value: string \| number; title: string }, index: number) => void` | - | 첫 인자가 탭 객체, **두 번째가 인덱스**다. setActiveIndex 를 그대로 넘기면 안 된다 |
+| variant | `"default" \| "toggle"` | - | 탭 모양. `default` 는 채워진 평면 탭, `toggle` 은 밑줄 인디케이터가 슬라이드 |
+| type | `"default" \| "toggle"` | - | **@deprecated** 모양 변형은 `variant` 로 받는다. `type` 은 상태 색 전용이다. 기존 사용처가 깨지지 않도록 계속 받는다 — 둘 다 주면 `variant` 가 이긴다. |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 탭 높이와 글자 크기 |
 
 `*` = 필수
 <!-- /props:Tab -->
@@ -130,13 +131,13 @@ const [activeIndex, setActiveIndex] = useState(0);
 <!-- props:Pagination -->
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
-| current * | `number` | - |  |
-| total * | `number` | - |  |
-| pageSize | `number` | `10` |  |
-| siblingCount | `number` | `1` |  |
-| onChange | `(page: number) => void` | - |  |
-| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
-| type | `"brand" \| "success" \| "error" \| "warning" \| "info"` | `"brand"` |  |
+| current * | `number` | - | 현재 페이지 (1부터 시작) |
+| total * | `number` | - | **전체 아이템 수**. 페이지 수가 아니다 |
+| pageSize | `number` | `10` | 한 페이지에 담기는 아이템 수. total 과 함께 페이지 수를 계산한다 |
+| siblingCount | `number` | `1` | 현재 페이지 좌우로 보여줄 번호 개수 |
+| onChange | `(page: number) => void` | - | 페이지를 누르면 새 페이지 번호를 준다 |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 버튼 크기 |
+| type | `PaginationType \| LegacyStatusType` | `"primary"` | 활성 페이지 색 |
 
 `*` = 필수
 <!-- /props:Pagination -->
@@ -169,9 +170,9 @@ const [activeIndex, setActiveIndex] = useState(0);
 <!-- props:Steps -->
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
-| items * | `{ title: string; description?: string }[]` | - |  |
-| current * | `number` | - |  |
-| type | `"brand" \| "success" \| "error" \| "warning" \| "info"` | `"brand"` |  |
+| items * | `{ title: string; description?: string }[]` | - | 단계 목록. 순서대로 그려진다 |
+| current * | `number` | - | 진행 중인 단계 인덱스 (0부터). 앞은 완료, 뒤는 대기로 표시된다 |
+| type | `StepsType \| LegacyStatusType` | `"primary"` | 완료·진행 단계의 색 |
 
 `*` = 필수
 <!-- /props:Steps -->

package/guidelines/components/overlay.md

@@ -15,6 +15,44 @@
 </Modal>
 ```
 
+<!-- props:Modal -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| isOpen * | `boolean` | - |  |
+| onClose * | `() => void` | - |  |
+| children | `ReactNode` | - |  |
+
+`*` = 필수
+<!-- /props:Modal -->
+
+### 조건부 렌더하지 말 것
+
+```tsx
+{open && <MyModal />}        // ❌ 닫는 애니메이션이 안 돈다
+<MyModal isOpen={open} />    // ✅
+```
+
+`Modal` 은 `isOpen` 이 `false` 가 되면 **애니메이션이 끝난 뒤에** 스스로 사라진다.
+호출부가 통째로 걷어내면 `isOpen={false}` 를 받아 볼 틈이 없어 그냥 없어진다.
+
+`isOpen` 이 `false` 인 동안 `Modal` 은 `null` 을 돌려주므로 **계속 마운트해 둬도
+DOM 에 아무것도 남지 않는다.** 조건부 렌더가 필요 없다.
+
+**깨지지 않고 애니메이션만 조용히 빠지는** 종류라 버그로 안 보인다. 새 화면을 만들 때
+특히 조심할 것.
+
+### 열 때마다 대상이 다른 모달
+
+계속 마운트해 두면 안쪽 폼이 첫 렌더에서 잡은 상태가 남는다. **열릴 때만 바뀌는 `key`**
+를 줘서 그때 새로 만든다. 닫을 때는 `key` 가 안 바뀌므로 애니메이션이 끝까지 돈다.
+
+```tsx
+<EditForm key={editingId ?? "none"} isOpen={!!editingId} target={editingId} />
+```
+
+이때 제목 같은 표시값은 **폼이 자기 상태에서** 가져가야 한다. 닫히는 동안 prop 은 이미
+비어 있어서, 그대로 쓰면 `수정 — undefined` 가 사라지는 상자에 스친다.
+
 ---
 
 ## Drawer
@@ -65,11 +103,12 @@
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
 | children * | `ReactNode` | - |  |
-| title | `ReactNode` | - |  |
-| description | `ReactNode` | - |  |
-| type | `"dark" \| "light"` | `"dark"` |  |
+| title | `ReactNode` | - | 말풍선 첫 줄. 굵게 표시된다 |
+| description | `ReactNode` | - | 말풍선 본문. title 과 둘 중 하나는 있어야 뜬다 |
+| variant | `"dark" \| "light"` | - | 말풍선 배색 |
+| type | `"dark" \| "light"` | - | **@deprecated** 모양 변형은 `variant` 로 받는다. `type` 은 상태 색 전용이다. 기존 사용처가 깨지지 않도록 계속 받는다 — 둘 다 주면 `variant` 가 이긴다. |
 | follow | `boolean` | `false` | 커서를 따라다닌다. 기본값은 `false` — 트리거 요소 기준으로 고정된다 (PopOver/Dropdown/Select 와 같은 방식). 넓은 영역 안에서 **가리키는 지점**이 의미를 가질 때만 켠다. 버튼이나 아이콘처럼 대상이 작은 경우는 고정이 읽기 편하다. |
-| disabled | `boolean` | `false` |  |
+| disabled | `boolean` | `false` | 말풍선을 띄우지 않는다 |
 
 `*` = 필수
 <!-- /props:Tooltip -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-plat/design-system",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",