sellmate-design-system-react 9.0.0-beta.9 → 9.0.0-beta.90

package/dist/components/SChatMessage/SChatMessage.d.ts

@@ -0,0 +1,135 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+/** 메시지가 오는 쪽 — 받은 메시지(incoming)는 왼쪽, 보낸 메시지(outgoing)는 오른쪽에 선다. */
+export declare const CHAT_MESSAGE_DIRECTIONS: readonly ["incoming", "outgoing"];
+export type SChatMessageDirection = (typeof CHAT_MESSAGE_DIRECTIONS)[number];
+/**
+ * 말풍선의 종류.
+ * - `default` 사람이 직접 쓴 메시지
+ * - `template` 미리 등록된 서식으로 보내진 메시지
+ * - `admin` 관리자·시스템이 보낸 메시지
+ *
+ * **보낸 메시지에서만 면이 갈린다.** 셋 다 사업자 쪽이 보내는 것이라 받은 메시지에는
+ * 뜻이 없고, 받은 메시지는 무엇으로 보냈든 같은 면으로 선다.
+ */
+export declare const CHAT_MESSAGE_VARIANTS: readonly ["default", "template", "admin"];
+export type SChatMessageVariant = (typeof CHAT_MESSAGE_VARIANTS)[number];
+/** 상대가 내 메시지를 읽었는지. 시각 왼쪽에 붙는다. */
+export declare const CHAT_MESSAGE_READ_STATUSES: readonly ["read", "unread"];
+export type SChatMessageReadStatus = (typeof CHAT_MESSAGE_READ_STATUSES)[number];
+export interface SChatMessageProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * 받은 메시지(왼쪽)인지 보낸 메시지(오른쪽)인지.
+     *
+     * **아바타와 이름 유무도 여기서 갈린다** — 받은 메시지에만 아바타와 `sender` 가 선다.
+     * 보낸 메시지는 내가 보냈다는 것이 자리로 이미 드러나 얼굴도 이름도 필요 없다.
+     */
+    direction: SChatMessageDirection;
+    /**
+     * 말풍선 위에 붙는 보낸 사람 이름. 없으면 자리째 빠진다.
+     *
+     * **받은 메시지에만 쓰인다** — 보낸 메시지에는 넘겨도 그리지 않는다(`direction` 참고).
+     * 앱이 데이터를 한 번만 매핑해 방향과 무관하게 넘길 수 있도록 막지 않고 무시한다.
+     */
+    sender?: ReactNode;
+    /**
+     * 말풍선 아래에 붙는 시각. 표기는 앱이 정해 문자열로 넘긴다 — 대화 화면의 시각은
+     * `오후 5:52` 처럼 읽는 표기를 쓰므로 카드가 서식을 강제하지 않는다 (AGENTS.md §1-4 예외).
+     */
+    time?: ReactNode;
+    /**
+     * 상대가 읽었는지. 시각 왼쪽에 `읽음`·`안 읽음` 으로 붙고, 주지 않으면 표시하지 않는다.
+     *
+     * **내가 보낸 메시지에만 붙인다** — 받은 메시지에 읽음 표시를 다는 것은 뜻이 없다.
+     */
+    readStatus?: SChatMessageReadStatus;
+    /**
+     * 아바타 이미지 경로. 없으면 사람 아이콘 자리표시가 선다.
+     *
+     * **받은 메시지에만 쓰인다** — 보낸 메시지에는 아바타가 서지 않는다(`direction` 참고).
+     */
+    avatarSrc?: string;
+    /** 아바타 대체 텍스트 */
+    avatarAlt?: string;
+    /**
+     * 받은 메시지에 아바타 칸을 세울지. 끄면 **칸 자체가 빠져** 말풍선이 행 왼쪽 끝에서 시작한다.
+     *
+     * 챗봇 답변처럼 **말하는 상대가 하나뿐인 대화**에서 끈다 — 얼굴로 가를 사람이 없으니 칸이
+     * 폭만 먹는다. 여러 사람이 말하는 대화에서는 켜 둔다.
+     *
+     * **한 대화 안에서는 모든 받은 메시지에 같은 값을 준다** — 섞으면 말풍선 시작선이 묶음마다
+     * 44px 씩 어긋난다. 끈 대화에서 `continued` 는 이름만 숨긴다(비워 둘 아바타 자리가 없다).
+     *
+     * 보낸 메시지에는 원래 아바타가 없으므로 영향이 없다.
+     */
+    showAvatar?: boolean;
+    /**
+     * 같은 사람이 이어서 말한 묶음인지. 켜면 **아바타와 `sender` 를 그리지 않는다** —
+     * 말풍선이 위 묶음과 같은 선에서 시작해 한 사람의 말로 이어 읽힌다.
+     *
+     * 받은 메시지에서는 아바타 자리를 비워 둔 채 남긴다 — 안 남기면 말풍선이 44px 왼쪽으로 밀려
+     * 위 묶음과 어긋난다. 보낸 메시지는 아바타가 없으므로 이름만 숨긴다.
+     *
+     * `time`·`readStatus` 는 그대로 나온다. 시간이 벌어져 묶음을 나눴어도 얼굴은 한 번만 보이면
+     * 되고 시각은 묶음마다 필요하기 때문이다.
+     *
+     * **얼마나 벌어져야 묶음을 나눌지는 앱이 정한다** — 30분이든 하루든 대화의 성격에 달렸으므로
+     * 컴포넌트는 기준을 갖지 않고 스위치만 연다.
+     */
+    continued?: boolean;
+    /**
+     * 말풍선 종류. `template` 은 미리 등록된 서식으로, `admin` 은 관리자·시스템이 보낸
+     * 메시지임을 각각 다른 면으로 드러낸다. 면 색은 토큰이 정하므로 여기서 색을 정하지 않는다.
+     *
+     * **보낸 메시지(`direction="outgoing"`)에만 쓰인다** — 받은 메시지에는 넘겨도 그리지 않는다.
+     * 셋 다 사업자 쪽이 보내는 것이라 받은 쪽에는 뜻이 없다. 앱이 메시지를 한 번만 매핑해
+     * 방향과 무관하게 넘길 수 있도록 막지 않고 무시한다.
+     */
+    variant?: SChatMessageVariant;
+    /**
+     * 시각 아래에 붙는 동작 슬롯. 없으면 그 줄이 통째로 빠진다.
+     *
+     * 「상담원 연결」처럼 **이 메시지에 이어서 할 수 있는 동작**이 오는 자리다. 무엇을 놓을지는
+     * 앱이 정하고, 메시지는 줄로 세우고 방향에 맞춰 정렬하는 것까지만 한다.
+     *
+     * 시각과 같은 선에서 시작한다 — 말풍선 끝에서 한 칸 안이다.
+     */
+    actions?: ReactNode;
+    /**
+     * 말풍선 목록. **한 항목이 말풍선 하나**가 되어 위에서 아래로 쌓인다.
+     *
+     * 한 사람이 연달아 말하면 아바타·이름·시각은 한 번만 서고 말풍선만 늘어난다 —
+     * 그 묶음이 이 컴포넌트 한 개다. 말풍선 안에는 글뿐 아니라 버튼 같은 요소도 올 수 있다.
+     */
+    messages?: ReactNode[];
+    /**
+     * 말풍선 아래에 붙는 파일 목록. **한 항목이 칸 하나**가 되어 위에서 아래로 쌓인다.
+     *
+     * `SChatFile` 을 넣는 자리다 — 말풍선과 달리 면으로 감싸지 않고 넘긴 것을 그대로 세운다.
+     * 파일 칸은 제 면·선·라운드를 이미 갖고 있어 한 번 더 감싸면 칸이 두 겹으로 보인다.
+     *
+     * **`messages` 대신 여기로 넘긴다.** `messages` 로 넘기면 말풍선 면에 감싸여 그렇게 된다.
+     *
+     * 아바타·이름·시각·읽음 표시는 글 메시지와 똑같이 이 컴포넌트가 그린다 — 파일을 보낸 것도
+     * 대화의 한 줄이므로 행 규칙을 따로 갖지 않는다.
+     */
+    attachments?: ReactNode[];
+}
+/**
+ * SChatMessage — 대화 화면에서 한 사람이 한 번에 말한 묶음.
+ *
+ * 아바타·보낸 사람(받은 메시지만)·말풍선·시각을 한 줄로 세운다. **말풍선은 `messages` 항목 수만큼 쌓이고**
+ * 아바타·이름·시각은 그 묶음에 한 번만 붙는다 — 연달아 말한 여러 줄이 한 덩어리로 읽힌다.
+ *
+ * 시각 아래에 동작을 붙여야 하면 `actions` 슬롯에 넣는다 — 시각과 같은 선에서 시작해 방향에
+ * 맞춰 정렬된다.
+ *
+ * 시간이 벌어져 묶음을 나눠야 하는데 말한 사람은 같을 때는 `continued` 를 켠다 — 아바타 자리는
+ * 유지한 채 얼굴과 이름만 빠져, 두 묶음이 한 사람의 말로 이어 읽힌다.
+ `direction` 하나로 받은 메시지(왼쪽)와
+ * 보낸 메시지(오른쪽)가 갈리고, 그에 따라 정렬과 말풍선 색이 함께 뒤집힌다.
+ *
+ * **말풍선 폭은 내용이 정한다** — 짧은 메시지는 글자만큼만 차지하고, 길면 접힌다. 다만 반대편
+ * 끝까지 가지는 않는다: 받은 메시지는 오른쪽, 보낸 메시지는 왼쪽에 여백이 남아 어느 쪽이 말한
+ * 것인지가 폭으로도 읽힌다. 대화 폭을 더 좁히려면 이 컴포넌트가 아니라 담는 쪽을 좁힌다.
+ */
+export declare const SChatMessage: import("react").ForwardRefExoticComponent<SChatMessageProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SChatMessage/index.d.ts

@@ -0,0 +1 @@
+export { SChatMessage, CHAT_MESSAGE_DIRECTIONS, CHAT_MESSAGE_READ_STATUSES, CHAT_MESSAGE_VARIANTS, type SChatMessageDirection, type SChatMessageReadStatus, type SChatMessageVariant, type SChatMessageProps, } from './SChatMessage';

package/dist/components/SChatSystemMessage/README.md

@@ -0,0 +1,12 @@
+# SChatSystemMessage
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SChatSystemMessage
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message?` | `string[]` | — | 안내 문구. **항목 수만큼 알약이 쌓인다** — 서로 다른 시점에 일어난 사실은 한 알약에 몰아넣지 않고 항목을 나눈다 (`SChatMessage` 의 `messages` 와 같은 규칙). 각 항목은 **인라인 HTML 문자열을 받는다.** `<b>` `<strong>` `<i>` `<em>` `<br>` `<span>` `<a>` 만 살아남고 나머지 태그·속성과 `javascript:` 같은 위험한 스킴은 `sanitizeInlineHtml` 이 제거한다. 그래도 **서버·사용자가 만든 문자열을 그대로 넘기지 않는다** — 살균은 마지막 방어선이지 입력 검증의 대체가 아니다. ```tsx <SChatSystemMessage message={['<b>김상담</b> 상담사가 배정되었습니다.']} /> ``` |
+

package/dist/components/SChatSystemMessage/SChatSystemMessage.d.ts

@@ -0,0 +1,18 @@
+import { type HTMLAttributes } from 'react';
+export interface SChatSystemMessageProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * 안내 문구. **항목 수만큼 알약이 쌓인다** — 서로 다른 시점에 일어난 사실은
+     * 한 알약에 몰아넣지 않고 항목을 나눈다 (`SChatMessage` 의 `messages` 와 같은 규칙).
+     *
+     * 각 항목은 **인라인 HTML 문자열을 받는다.** `<b>` `<strong>` `<i>` `<em>` `<br>`
+     * `<span>` `<a>` 만 살아남고 나머지 태그·속성과 `javascript:` 같은 위험한 스킴은
+     * `sanitizeInlineHtml` 이 제거한다. 그래도 **서버·사용자가 만든 문자열을 그대로 넘기지 않는다** —
+     * 살균은 마지막 방어선이지 입력 검증의 대체가 아니다.
+     *
+     * ```tsx
+     * <SChatSystemMessage message={['<b>김상담</b> 상담사가 배정되었습니다.']} />
+     * ```
+     */
+    message?: string[];
+}
+export declare const SChatSystemMessage: import("react").ForwardRefExoticComponent<SChatSystemMessageProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SChatSystemMessage/index.d.ts

@@ -0,0 +1 @@
+export { SChatSystemMessage, type SChatSystemMessageProps } from './SChatSystemMessage';

package/dist/components/SCheckbox/README.md

@@ -11,6 +11,7 @@
 | `value?` | `SCheckboxValue` | `false` | 선택 상태. boolean(단일) / 배열(그룹) / null(indeterminate) |
 | `val?` | `unknown` | — | 배열(그룹) 모드에서 이 체크박스의 값 |
 | `label?` | `string` | `''` | 라벨 |
+| `ariaLabel?` | `string` | — | 스크린리더용 접근성 레이블. **`label` 이 없을 때만 준다** — 표의 행 선택처럼 라벨 글자 없이 서는 체크박스는 이것이 없으면 "체크박스" 로만 읽힌다. `label` 이 있으면 그 글자가 이미 이름이 된다. 둘 다 주면 이 값이 화면의 라벨을 덮어써 보이는 글자와 읽히는 이름이 갈린다. |
 | `disabled?` | `boolean` | `false` | 비활성 |
 | `inverse?` | `boolean` | `false` | 어두운 배경용 흰색 스타일 |
 | `className?` | `string` | — |  |
@@ -22,6 +23,14 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: boolean \| unknown[]) => void` | 값 변경 (sdUpdate) |
 
+## Types
+
+### SCheckboxValue
+
+```ts
+export type SCheckboxValue = boolean | unknown[] | null;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SCheckbox/SCheckbox.d.ts

@@ -9,6 +9,14 @@ export interface SCheckboxProps {
     onValueChange?: (value: boolean | unknown[]) => void;
     /** 라벨 */
     label?: string;
+    /**
+     * 스크린리더용 접근성 레이블. **`label` 이 없을 때만 준다** — 표의 행 선택처럼 라벨 글자 없이 서는
+     * 체크박스는 이것이 없으면 "체크박스" 로만 읽힌다.
+     *
+     * `label` 이 있으면 그 글자가 이미 이름이 된다. 둘 다 주면 이 값이 화면의 라벨을 덮어써 보이는
+     * 글자와 읽히는 이름이 갈린다.
+     */
+    ariaLabel?: string;
     /** 비활성 */
     disabled?: boolean;
     /** 어두운 배경용 흰색 스타일 */
@@ -20,4 +28,4 @@ export interface SCheckboxProps {
  * SCheckbox — sd-checkbox 포팅 (Radix SCheckbox).
  * boolean(단일)·배열(그룹, val 필요)·null(indeterminate) 지원, inverse 스타일.
  */
-export declare function SCheckbox({ value, val, onValueChange, label, disabled, inverse, className, style, }: SCheckboxProps): import("react").JSX.Element;
+export declare function SCheckbox({ value, val, onValueChange, label, ariaLabel, disabled, inverse, className, style, }: SCheckboxProps): import("react").JSX.Element;

package/dist/components/SChip/README.md

@@ -8,6 +8,7 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `color?` | `SChipColor` | — | 색상. 주지 않으면 기본 회색 칩이다. 색은 기본 상태에만 입힌다 — error·편집 중·disabled 는 상태 토큰이 우선한다. 색상은 컴포넌트 토큰 `--cmp-chip-chip-<color>-{bg,content,border}` 를 참조한다. |
 | `name?` | `string` | — | 폼 연동용 name |
 | `value?` | `string` | `''` | 칩 텍스트 값 |
 | `error?` | `boolean` | — | 에러 상태 |
@@ -35,6 +36,30 @@
 | `focus` | `() => void` | 편집 input에 포커스합니다. |
 | `getNativeElement` | `() => HTMLElement \| null` | 네이티브 편집 엘리먼트를 반환합니다. |
 
+## Types
+
+### SChipColor
+
+```ts
+export type SChipColor = (typeof CHIP_COLORS)[number];
+```
+
+### CHIP_COLORS
+
+```ts
+export const CHIP_COLORS = [
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'blue',
+  'darkblue',
+  'indigo',
+  'purple',
+  'grey',
+] as const;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SChip/SChip.d.ts

@@ -1,6 +1,14 @@
 import { type CSSProperties } from 'react';
 import { type Rule } from '../../lib/form';
+export declare const CHIP_COLORS: readonly ["red", "orange", "yellow", "green", "blue", "darkblue", "indigo", "purple", "grey"];
+export type SChipColor = (typeof CHIP_COLORS)[number];
 export interface SChipProps {
+    /**
+     * 색상. 주지 않으면 기본 회색 칩이다.
+     * 색은 기본 상태에만 입힌다 — error·편집 중·disabled 는 상태 토큰이 우선한다.
+     * 색상은 컴포넌트 토큰 `--cmp-chip-chip-<color>-{bg,content,border}` 를 참조한다.
+     */
+    color?: SChipColor;
     /** 폼 연동용 name */
     name?: string;
     /** 칩 텍스트 값 */

package/dist/components/SChip/index.d.ts

@@ -1 +1 @@
-export { SChip, type SChipHandle, type SChipProps } from './SChip';
+export { SChip, CHIP_COLORS, type SChipColor, type SChipHandle, type SChipProps } from './SChip';