@x-plat/design-system 0.9.0 → 0.11.0

package/dist/status-njWqQWFV.d.cts

@@ -0,0 +1,20 @@
+/**
+ * 상태 색 공통 어휘.
+ *
+ * "이 요소가 어떤 상태인가" 를 색으로 나타낼 때 쓴다. 컴포넌트마다 다른 단어를
+ * 쓰지 않도록 한 곳에 모은다.
+ *
+ * 모양·동작 변형은 이것이 아니라 `variant` prop 으로 받는다. 둘은 다른 축이다.
+ */
+/** 모든 상태 색 컴포넌트가 공통으로 받는 값 */
+type StatusType = "primary" | "success" | "error" | "warning" | "info";
+/**
+ * 예전 이름. `brand` 는 `primary` 와 같은 것을 가리켰다.
+ *
+ * @deprecated `"primary"` 를 쓸 것. 기존 사용처가 깨지지 않도록 계속 받는다.
+ */
+type LegacyStatusType = "brand";
+/** 컴포넌트가 받는 타입. 새 이름과 예전 이름을 모두 허용한다 */
+type StatusTypeInput = StatusType | LegacyStatusType;
+
+export type { LegacyStatusType as L, StatusTypeInput as S };

package/dist/status-njWqQWFV.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 상태 색 공통 어휘.
+ *
+ * "이 요소가 어떤 상태인가" 를 색으로 나타낼 때 쓴다. 컴포넌트마다 다른 단어를
+ * 쓰지 않도록 한 곳에 모은다.
+ *
+ * 모양·동작 변형은 이것이 아니라 `variant` prop 으로 받는다. 둘은 다른 축이다.
+ */
+/** 모든 상태 색 컴포넌트가 공통으로 받는 값 */
+type StatusType = "primary" | "success" | "error" | "warning" | "info";
+/**
+ * 예전 이름. `brand` 는 `primary` 와 같은 것을 가리켰다.
+ *
+ * @deprecated `"primary"` 를 쓸 것. 기존 사용처가 깨지지 않도록 계속 받는다.
+ */
+type LegacyStatusType = "brand";
+/** 컴포넌트가 받는 타입. 새 이름과 예전 이름을 모두 허용한다 */
+type StatusTypeInput = StatusType | LegacyStatusType;
+
+export type { LegacyStatusType as L, StatusTypeInput as S };

package/guidelines/AGENT_PROMPT.md

@@ -593,12 +593,27 @@ CSS 변수 `--semantic-{category}-{role}` 사용.
 
 | 카테고리 | 컴포넌트 |
 |---|---|
-| 입력 | `Button`, `Input`, `PasswordInput`, `TextArea`, `Select`, `CheckBox`, `Radio`, `Switch`, `DatePicker`, `Calendar` |
-| 표시 | `Table`, `Box`, `Tag`, `Chip`, `Avatar`, `NotificationBadge`, `Skeleton`, `Spinner`, `Divider`, `EmptyState`, `Progress` |
+| 입력 | `Button`, `Input`, `PasswordInput`, `TextArea`, `Select`, `CheckBox`, `Radio`, `Switch`, `DatePicker`, `TimePicker`, `Calendar` |
+| 표시 | `Table`, `Box`, `Tag`, `Chip`, `Avatar`, `NotificationBadge`, `Skeleton`, `Spinner`, `Divider`, `EmptyState`, `Progress`, `Stat` |
 | 오버레이 | `Modal`, `Drawer`, `PopOver`, `Tooltip`, `Alert`, `Toast` (`ToastProvider` 필요) |
 | 네비 | `Tab`, `CardTab`, `Breadcrumb`, `Pagination`, `Steps`, `Dropdown`, `Link`, `LinkButton` |
 | 미디어 | `Video`, `FileUpload`, `ImageSelector`, `Swiper` |
-| 기타 | `Accordion`, `Chart`, `HtmlTypeWriter` |
+| 기타 | `Accordion`, `Chart`, `HtmlTypeWriter`, `Editor` |
+
+### 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) 참고.
 
 ---
 

package/guidelines/Guidelines.md

@@ -66,7 +66,10 @@ React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1
    - [Dropdown](./components/dropdown.md)
    - [파일 & 미디어](./components/file-media.md) - FileUpload, ImageSelector, Video
    - [Swiper](./components/swiper.md)
+   - [Editor](./components/editor.md)
    - [Link](./components/link.md)
+   - [Stat](./components/stat.md)
+   - [TimePicker](./components/time-picker.md)
    - [HtmlTypeWriter](./components/html-typewriter.md)
 4. **컴포지션**
    - [Grid](./composition/grid.md) - Grid 시스템, 위젯 패턴

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

@@ -0,0 +1,86 @@
+# Editor
+
+외부 라이브러리 없이 자체 구현한 리치 텍스트 에디터. **HTML 문자열**을 주고받는다.
+
+```tsx
+const [html, setHtml] = useState("");
+
+<Editor value={html} onChange={setHtml} />
+<Editor toolbar={["bold", "italic", "link"]} minHeight={300} />
+<Editor onImageUpload={async (file) => await uploadToS3(file)} />
+```
+
+<!-- props:Editor -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| value | `string` | `""` | HTML 문자열. 외부에서 setter 와 함께 controlled 로 사용 |
+| onChange | `(html: string) => void` | - | 내용 변경 콜백 (HTML) |
+| placeholder | `string` | `"내용을 입력하세요"` | placeholder |
+| readOnly | `boolean` | `false` | 읽기 전용 |
+| toolbar | `EditorToolbarItem[]` | `DEFAULT_TOOLBAR` | 툴바 표시 항목. 기본: 전체 |
+| enableSlashCommand | `boolean` | `true` | "/" 입력 시 슬래시 명령 popup. 기본 true |
+| enableMarkdownShortcuts | `boolean` | `true` | 마크다운 단축키 (`# `, `- ` 등). 기본 true |
+| onImageUpload | `(file: File) => Promise<string>` | - | 이미지 업로드 핸들러. 반환된 URL 이 src 로 사용. 없으면 URL 입력 prompt |
+| minHeight | `number` | `200` | 최소 높이 (px). 기본 200 |
+
+`*` = 필수
+<!-- /props:Editor -->
+
+## 툴바
+
+기본은 13종 전부다. `toolbar` 로 골라서 줄일 수 있다.
+
+`bold` `italic` `underline` `strikethrough` `code` `heading` `list` `ordered-list`
+`blockquote` `code-block` `link` `image` `divider`
+
+## 마크다운 단축키
+
+줄 맨 앞에서 아래를 치고 **스페이스**를 누르면 변환된다. `enableMarkdownShortcuts={false}` 로 끈다.
+
+| 입력 | 결과 |
+|---|---|
+| `#` `##` `###` | 제목 1·2·3 |
+| `-` `*` | 글머리 기호 목록 |
+| `1.` | 번호 매기기 목록 |
+| `>` | 인용 |
+
+## 슬래시 명령
+
+`/` 를 치면 블록 삽입 메뉴가 뜬다. 방향키로 고르고 Enter 로 넣는다.
+`enableSlashCommand={false}` 로 끈다.
+
+## 코드 블록
+
+여러 줄을 선택하고 코드 블록을 누르면 **하나의** `<pre><code>` 가 된다.
+블록마다 따로 만들어지지 않는다.
+
+```
+Enter   코드 블록 안에서 줄바꿈 (블록이 쪼개지지 않는다)
+Tab     공백 2칸 들여쓰기 (포커스가 밖으로 나가지 않는다)
+Enter × 빈 줄 둘이 이어지면 코드 블록을 빠져나온다
+```
+
+코드 블록 안에서 다시 코드 블록을 누르면 **해제**되어 일반 단락으로 돌아간다.
+
+## 코드 블록 안에서는
+
+- **서식 툴바가 먹지 않는다.** 코드에 `<strong>` 이나 `<a>` 가 섞이면 복사해서
+  실행할 수 없는 글자가 된다. 코드 블록 토글만 받는다.
+- **마크다운 단축키와 슬래시 메뉴가 뜨지 않는다.** 코드에 `# ` 이나 `/` 는 흔하다.
+- **붙여넣기는 순수 텍스트로만** 들어간다.
+
+## 붙여넣기
+
+붙여넣는 HTML 은 항상 정화된다. 허용 태그 밖은 자식을 살려 벗겨내고,
+`script`·`style`·`iframe` 같은 것은 **내용까지 통째로** 버린다.
+`javascript:` 와 `data:text/html` URL 도 제거된다.
+
+## 값 다루기
+
+`value` 는 controlled 다. `onChange` 가 준 HTML 을 그대로 다시 넣어도 커서가 튀지 않는다 —
+에디터가 자기가 내보낸 값인지 구분한다.
+
+- **외부에서 값을 바꾸면**(폼 리셋 등) 에디터가 그 값으로 다시 그린다. 이때 캐럿 위치는
+  유지되지 않는다. 사용자가 입력 중일 때 밖에서 덮어쓰지 않는 편이 낫다.
+- 저장할 때는 받은 HTML 을 **서버에서 한 번 더 정화**한다. 브라우저 정화는 표시용이지
+  신뢰 경계가 아니다.

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,24 @@
 # 폼 컨트롤: CheckBox / Radio / Switch
 
+## 라벨 — label / required
+
+`Input` `TextArea` `AutoResizeTextArea` `ChatInput` `Select` `Switch` 가 `label` 을 받는다.
+`htmlFor` 가 자동으로 연결되어 **라벨을 클릭하면 컨트롤에 포커스**가 간다.
+
+```tsx
+<Input label="이름" required value={v} onChange={onChange} />
+<Select label="담당자" validations={[{ status: "error", message: "선택해 주세요" }]}>…</Select>
+```
+
+- `required` 는 라벨 뒤에 `*` 를 붙인다. 표시 전용이라 검증은 하지 않는다 —
+  실제 검증은 `validations` 로 전달한다.
+- `id` 를 직접 주면 그 값이 쓰인다. 안 주면 `React.useId()` 로 만든다.
+- `CheckBox` `Radio` `FileUpload` `ImageSelector` 는 **자체 `label` 이 이미 있다.**
+  컨트롤 옆에 붙는 형태라 의미가 달라서 그대로 둔다.
+- `label` 도 `validations` 도 없으면 **래퍼가 생기지 않는다.** DOM 이 전과 같다.
+
+---
+
 ## 검증 메시지 — 모든 폼 컴포넌트 공통
 
 폼 컨트롤은 **전부 같은 `validations` prop** 으로 에러·경고·안내를 받는다.

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/guidelines/components/stat.md

@@ -0,0 +1,31 @@
+# Stat
+
+대시보드에서 **큰 숫자 하나를 강조**하는 타일. 값·단위·증감·설명을 한 묶음으로 보여준다.
+
+```tsx
+<Stat label="총 호출 수" value="1,240" unit="회"
+      trend={{ direction: "up", value: "12.4%" }} description="최근 7일" />
+
+<Stat size="lg" type="error" label="비용" value="$1.76" />
+```
+
+<!-- props:Stat -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| label * | `ReactNode` | - | 지표 이름 (예: "총 호출 수") |
+| value * | `ReactNode` | - | 강조할 값. 포맷은 호출부가 정한다 (천 단위 구분·통화 기호 등) |
+| unit | `ReactNode` | - | 값 뒤에 붙는 단위 (예: "원", "회"). 값보다 작게 표시된다 |
+| description | `ReactNode` | - | 값 아래 보조 설명 |
+| trend | `{ direction: "up" \| "down" \| "flat"; value: ReactNode; }` | - | 증감 표시. `value` 는 이미 포맷된 문자열을 그대로 쓴다 (예: "+12.4%"). `direction` 이 색과 화살표를 정한다 |
+| icon | `ReactNode` | - | 값 왼쪽에 놓을 아이콘 |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 타일 크기 |
+| type | `StatusTypeInput` | `"primary"` | 값 색. 상태를 나타낼 때 쓴다 |
+
+`*` = 필수
+<!-- /props:Stat -->
+
+- `value` 는 **이미 포맷된 값**을 받는다. 천 단위 구분·통화 기호는 호출부가 정한다.
+- `trend.value` 도 포맷된 문자열이다 (`"12.4%"`). `direction` 이 색과 화살표를 정한다 —
+  `up` 초록, `down` 빨강, `flat` 회색.
+- `type` 은 **값 글자색**이다. 임계치를 넘었을 때 `error` 같은 식으로 쓴다.
+- 숫자는 `tabular-nums` 로 자릿수가 흔들리지 않는다.

package/guidelines/components/time-picker.md

@@ -0,0 +1,49 @@
+# TimePicker
+
+시각을 고르는 드롭다운. `"HH:mm"` 24시간 문자열을 주고받는다.
+
+```tsx
+<TimePicker label="시작 시각" value={time} onChange={setTime} />
+<TimePicker value={time} onChange={setTime} step={15} min="09:00" max="18:00" />
+<TimePicker value={time} onChange={setTime} use12Hours />   {/* 화면만 "오후 2:30" */}
+```
+
+<!-- props:TimePicker -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| value | `string` | - | `"HH:mm"` 24시간 표기. 비어 있으면 placeholder 가 보인다 |
+| onChange | `(value: string) => void` | - | 시각을 고르면 `"HH:mm"` 로 준다 |
+| step | `number` | `30` | 목록 간격(분). 기본 30 — 30이면 하루 48개가 나온다 |
+| min | `string` | - | 고를 수 있는 가장 이른 시각 `"HH:mm"` |
+| max | `string` | - | 고를 수 있는 가장 늦은 시각 `"HH:mm"` |
+| use12Hours | `boolean` | `false` | 오전/오후 12시간 표기로 보여준다. onChange 는 그대로 24시간 `"HH:mm"` |
+| placeholder | `string` | `"시각 선택"` | 비어 있을 때 표시할 안내 글자 |
+| disabled | `boolean` | `false` |  |
+| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
+| label | `ReactNode` | - | 컨트롤 위에 붙는 라벨. 클릭하면 컨트롤에 포커스가 간다 |
+| required | `boolean` | - | 라벨 뒤에 필수 표시(*)를 붙인다 |
+| validations | `Validation[]` | - | 컨트롤 아래에 표시할 검증 메시지. DS 폼 컴포넌트 공통 |
+
+`*` = 필수
+<!-- /props:TimePicker -->
+
+## DatePicker 와 함께 쓰기
+
+**`DatePicker` 는 날짜 전용이다.** 날짜와 시각이 함께 필요하면 둘을 나란히 두고
+호출부에서 합친다.
+
+```tsx
+<InputDatePicker value={date} onChange={setDate} />
+<TimePicker value={time} onChange={setTime} />
+// 저장할 때 합친다
+const [h, m] = time.split(":").map(Number);
+const at = new Date(date); at.setHours(h, m, 0, 0);
+```
+
+`DatePicker` 에 시간을 끼워 넣지 않은 이유는, 하위 4종(Input/Popup/Range/Single)이
+모두 시각을 0으로 맞춘 날짜 비교를 전제하고 있어서다. 거기에 시간을 넣으면 기존
+사용처의 min/max 판정이 조용히 달라진다.
+
+- `use12Hours` 는 **표시만** 바꾼다. `onChange` 는 늘 `"HH:mm"` 24시간이다.
+- `step` 은 분 단위다. 기본 30이면 하루 48개가 나온다.
+- 라벨·검증은 다른 폼 컨트롤과 같다. [form.md](./form.md) 참고.

package/package.json

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