@x-plat/design-system 0.8.3 → 0.10.0

package/dist/status-g_KP3qT6.d.cts

@@ -0,0 +1,8 @@
+/**
+ * 예전 이름. `brand` 는 `primary` 와 같은 것을 가리켰다.
+ *
+ * @deprecated `"primary"` 를 쓸 것. 기존 사용처가 깨지지 않도록 계속 받는다.
+ */
+type LegacyStatusType = "brand";
+
+export type { LegacyStatusType as L };

package/dist/status-g_KP3qT6.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 예전 이름. `brand` 는 `primary` 와 같은 것을 가리켰다.
+ *
+ * @deprecated `"primary"` 를 쓸 것. 기존 사용처가 깨지지 않도록 계속 받는다.
+ */
+type LegacyStatusType = "brand";
+
+export type { LegacyStatusType as L };

package/dist/validation-Dqo1zqhT.d.cts

@@ -0,0 +1,13 @@
+/**
+ * 폼 컨트롤 공통 검증 타입.
+ *
+ * 모든 폼 컴포넌트가 같은 모양으로 에러·경고·안내를 받는다.
+ * 렌더는 `components/FieldMessage` 가 전담한다.
+ */
+type ValidationStatus = "error" | "warning" | "success" | "default";
+interface Validation {
+    status: ValidationStatus;
+    message: string;
+}
+
+export type { Validation as V };

package/dist/validation-Dqo1zqhT.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 폼 컨트롤 공통 검증 타입.
+ *
+ * 모든 폼 컴포넌트가 같은 모양으로 에러·경고·안내를 받는다.
+ * 렌더는 `components/FieldMessage` 가 전담한다.
+ */
+type ValidationStatus = "error" | "warning" | "success" | "default";
+interface Validation {
+    status: ValidationStatus;
+    message: string;
+}
+
+export type { Validation as V };

package/guidelines/AGENT_PROMPT.md

@@ -600,6 +600,21 @@ CSS 변수 `--semantic-{category}-{role}` 사용.
 | 미디어 | `Video`, `FileUpload`, `ImageSelector`, `Swiper` |
 | 기타 | `Accordion`, `Chart`, `HtmlTypeWriter` |
 
+### prop 규약 — `type` 과 `variant` 는 다른 축이다
+
+| prop | 뜻 | 값 |
+|---|---|---|
+| `type` | **상태 색** — 이 요소가 어떤 상태인가 | `primary` `success` `error` `warning` `info` |
+| `variant` | **모양·동작 변형** — 어떻게 생겼는가 | 컴포넌트마다 다름 (`outlined`/`toggle`/`dark` 등) |
+
+- 상태 색의 `primary` 는 예전에 `brand` 였다. **`brand` 도 계속 받지만 새 코드는 `primary`** 를 쓴다.
+- `Chart`·`Tab`·`Tooltip`·`Tag` 는 모양 변형을 예전에 `type` 으로 받았다. **`variant` 로 쓸 것.**
+  `type` 도 아직 받지만 deprecated 이고, 둘 다 주면 `variant` 가 이긴다.
+- 폼 컨트롤의 검증 메시지는 전부 `validations` 다. [form.md](./components/form.md) 참고.
+- **`Modal` 을 조건부 렌더하지 말 것.** `{open && <MyModal/>}` 은 닫는 애니메이션을
+  없앤다. `<MyModal isOpen={open}/>` 로 계속 마운트한다 — 닫히면 스스로 `null` 을
+  돌려주므로 DOM 에 안 남는다. [overlay.md](./components/overlay.md) 참고.
+
 ---
 
 ## 추가 참조 (필요 시 fetch)

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/form.md

@@ -1,5 +1,31 @@
 # 폼 컨트롤: CheckBox / Radio / Switch
 
+## 검증 메시지 — 모든 폼 컴포넌트 공통
+
+폼 컨트롤은 **전부 같은 `validations` prop** 으로 에러·경고·안내를 받는다.
+컴포넌트마다 다른 이름이나 모양을 쓰지 않는다.
+
+```tsx
+<Input validations={[{ status: "error", message: "필수 항목입니다" }]} />
+<Select validations={[{ status: "error", message: "선택해 주세요" }]}>…</Select>
+<CheckBox label="동의" validations={[{ status: "error", message: "동의가 필요합니다" }]} />
+```
+
+| | |
+|---|---|
+| 타입 | `{ status: "error" \| "warning" \| "success" \| "default"; message: string }[]` |
+| 적용 | `Input` `PasswordInput` `TextArea` `AutoResizeTextArea` `Select` `CheckBox` `Radio` `Switch` `ChatInput` `FileUpload` `ImageSelector` |
+| 렌더 | `FieldMessage` 가 전담 — 아이콘·색·간격이 한 곳에 모여 있다 |
+
+- 배열이라 **여러 줄을 동시에** 보여줄 수 있다 (비밀번호 규칙 등).
+- `status: "error"` 가 하나라도 있으면 내부 컨트롤에 **`aria-invalid` 가 자동으로** 붙는다.
+- `validations` 를 주지 않으면 **DOM 이 전혀 바뀌지 않는다.** 래퍼도 생기지 않는다.
+
+`Select` 의 `error?: boolean` 은 메시지 없이 테두리만 붉게 할 때를 위해 남아 있다.
+`validations` 와 함께 쓰면 둘 중 하나만 참이어도 에러 스타일이 적용된다.
+
+---
+
 ## CheckBox
 
 ```tsx

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.8.3",
+  "version": "0.10.0",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",