@x-plat/design-system 0.10.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,12 @@ 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` 는 다른 축이다
 

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

package/dist/status-g_KP3qT6.d.cts

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

package/dist/status-g_KP3qT6.d.ts

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