sellmate-design-system-react 2.2.0 → 3.1.0

package/README.md

@@ -105,6 +105,91 @@ export function Example() {
 
 `SButton` 은 텍스트를 **`label`(문자열)로만** 받습니다 — `children` 은 받지 않으며, 아이콘은 `icon`/`rightIcon` 을 씁니다. 색상 prop 은 `color` 입니다(`variant` 아님).
 
+## 화면 작성 규칙 (AI 에이전트 포함)
+
+컴포넌트 조합·간격·타이포 등 **화면을 만들 때 지켜야 할 규칙**은 패키지에 함께 배포됩니다.
+
+| 파일 | 용도 |
+| --- | --- |
+| `node_modules/sellmate-design-system-react/AGENTS.md` | 사람이 읽는 사용 규칙서 |
+| `node_modules/sellmate-design-system-react/dist/llms.txt` | 규칙 + 토큰 어휘 + 전체 컴포넌트 Props 를 합친 AI 참조용 단일 문서 |
+| `node_modules/sellmate-design-system-react/dist/components/<이름>/README.md` | 컴포넌트별 Props/Events |
+
+Claude 등 AI 에이전트를 쓴다면 소비 앱의 `CLAUDE.md` 에 다음 한 줄을 넣어두면 됩니다.
+
+```md
+UI 작업 전 `node_modules/sellmate-design-system-react/dist/llms.txt` 를 먼저 읽을 것.
+```
+
+## ESLint 설정
+
+위 규칙 중 **정적으로 검출 가능한 것**은 린트로 강제할 수 있습니다. 소비 앱의 `eslint.config.mjs` 에 추가하세요.
+
+```js
+// eslint.config.mjs
+import sellmate from 'sellmate-design-system-react/eslint';
+
+export default [
+  // ... 기존 설정
+  ...sellmate.configs.recommended,
+];
+```
+
+| 규칙 | 기본 | 검출 대상 |
+| --- | --- | --- |
+| `sellmate/no-raw-html-control` | error | 대응 컴포넌트가 있는 생 HTML (`<button>` `<input>` `<select>` `<textarea>` `<table>` `<form>` `<dialog>` `<hr>` `<details>` `<progress>`), `alert()`/`confirm()` |
+| `sellmate/no-arbitrary-class` | error | **토큰이 있는 속성**(색·타이포·간격·모서리)의 임의 값 — `text-[14px]`, `bg-[#eee]`, `gap-[13px]`, `rounded-[5px]` |
+| `sellmate/no-off-scale-spacing` | error | 스케일 밖 간격 (`gap-13`, `p-15`) — Tailwind v4 에서 **조용히 무시되는** 값이라 눈으로 찾기 어렵다 |
+| `sellmate/table-numeric-align` | error | 숫자 컬럼(금액·수량 등)에 `align: 'right'` 누락 — **`--fix` 로 자동 교정** |
+| `sellmate/require-locale-number` | error | 숫자 컬럼의 `toLocaleString()` 누락 — 세 자리 콤마는 필수 |
+| `sellmate/prefer-typo-preset` | warn | `text-14 font-bold` 같은 낱개 조합 → `typo-*` 프리셋 |
+
+`className` 뿐 아니라 `cn()`/`clsx()` 인자, 템플릿 리터럴, 객체 키 안까지 검사합니다.
+
+### 일부러 잡지 않는 것
+
+과검출을 피하려고 다음은 기본 설정에서 **통과**시킵니다.
+
+```tsx
+// 디자인 토큰이 없는 앱 고유 레이아웃 치수 — 정당한 사용
+<div className="w-[280px] max-w-[1200px] grid-cols-[200px_1fr] top-[64px]" />
+
+// 토큰을 var() 로 참조하는 형태
+<div className="h-[var(--sys-size-control-md-height)]" />
+
+// 시각 요소가 없어 대체 컴포넌트가 없다
+<input type="hidden" name="csrf" />
+
+// 로고 SVG·본문 안 시맨틱 목록·DS 밖 컨트롤의 레이블
+<svg viewBox="0 0 24 24" />
+<ul><li>…</li></ul>
+```
+
+핵심은 **"디자인 토큰을 하드코딩하지 마라"** 이지 "임의 값을 절대 쓰지 마라" 가 아닙니다.
+
+### 더 엄격하게 / 더 느슨하게
+
+`configs.strict` 는 전 규칙을 error 로 올리고 `<ul>` `<ol>` `<li>` `<svg>` `<label>` 까지 검사합니다.
+
+```js
+export default [...sellmate.configs.strict];
+```
+
+규칙별 예외도 줄 수 있습니다.
+
+```js
+{
+  rules: {
+    // strict 를 쓰되 로고 SVG 는 허용
+    'sellmate/no-raw-html-control': ['error', { strict: true, allow: ['svg'] }],
+    // 그림자만 임의 값 허용
+    'sellmate/no-arbitrary-class': ['error', { ignorePrefixes: ['shadow'] }],
+  },
+}
+```
+
+허용 값 스케일은 `theme.css` 에서 **빌드 시 자동 추출**되므로 토큰이 바뀌면 규칙도 따라갑니다.
+
 ## 제공 컴포넌트
 
 분류는 `src/index.ts` 의 export 그룹과 동일합니다.

package/dist/components/SActionModal/README.md

@@ -0,0 +1,41 @@
+# SActionModal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SActionModal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — |  |
+| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) |
+| `modalTitle?` | `string` | `''` |  |
+| `button?` | `SActionModalButton` | — | 하단 액션 버튼 (주 액션 1개). 의도적으로 단수다 — 보조 버튼(취소·삭제 등)은 `footerLeft` 슬롯에 직접 배치한다. |
+| `footerLeft?` | `ReactNode` | — | footer 좌측 영역 (sd-action-modal 의 bottom-sub-content 슬롯). 보조 버튼이나 안내 문구를 넣는다. 버튼을 하나 더 쓰고 싶을 때 여기에 SButton 을 넣는다. |
+| `width?` | `number \| string` | — |  |
+| `height?` | `number \| string` | — |  |
+| `children?` | `ReactNode` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` |  |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SModalContainer](../SModalContainer)
+
+### Graph
+
+```mermaid
+graph TD;
+  SActionModal --> SButton
+  SActionModal --> SModalContainer
+  style SActionModal fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SBadge/README.md

@@ -0,0 +1,25 @@
+# SBadge
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBadge
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SBadgeColor` | `'blue'` | 뱃지 색상 |
+
+## Dependencies
+
+### Used by
+
+ - [SList](../SList)
+
+### Graph
+
+```mermaid
+graph TD;
+  SList --> SBadge
+  style SBadge fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SBarcodeInput/README.md

@@ -0,0 +1,64 @@
+# SBarcodeInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBarcodeInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| number \| null` | — |  |
+| `size?` | `SBarcodeInputSize` | `'sm'` |  |
+| `clearable?` | `boolean` | `false` |  |
+| `autoFocus?` | `boolean` | — |  |
+| `name?` | `string` | — |  |
+| `placeholder?` | `string` | `'입력해 주세요.'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `focused?` | `boolean` | — |  |
+| `hovered?` | `boolean` | — |  |
+| `prefix?` | `ReactNode` | — | 입력 앞 슬롯 |
+| `suffix?` | `ReactNode` | — | 입력 뒤 슬롯 |
+| `inputClass?` | `string` | — |  |
+| `inputStyle?` | `CSSProperties` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 값 변경 (sdUpdate) |
+| `onFocus` | `() => void` |  |
+| `onBlur` | `() => void` |  |
+
+## Dependencies
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SBarcodeInput --> SField
+  SBarcodeInput --> SGhostButton
+  style SBarcodeInput fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SButton/README.md

@@ -0,0 +1,49 @@
+# SButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SButtonColor` | `'primary'` | 색상 — sd-button preset의 색 계열 |
+| `outline?` | `boolean` | `false` | 아웃라인(테두리) 스타일. primary·neutral·danger 만 지원 (secondary 는 무시) |
+| `size?` | `SButtonSize` | `'sm'` | 크기 |
+| `icon?` | `SIconName` | — | 레이블 왼쪽 아이콘 |
+| `rightIcon?` | `SIconName` | — | 레이블 오른쪽 아이콘 |
+| `label?` | `string` | — | 버튼 텍스트 (문자열만 — 아이콘은 icon/rightIcon 사용) |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SConfirmModal](../SConfirmModal)
+ - [SDropdownButton](../SDropdownButton)
+ - [SKeyValueTable](../SKeyValueTable)
+ - [SLoadingModal](../SLoadingModal)
+ - [SPopover](../SPopover)
+ - [SPopup](../SPopup)
+ - [SToast](../SToast)
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+```mermaid
+graph TD;
+  SButton --> SIcon
+  SActionModal --> SButton
+  SConfirmModal --> SButton
+  SDropdownButton --> SButton
+  SKeyValueTable --> SButton
+  SLoadingModal --> SButton
+  SPopover --> SButton
+  SPopup --> SButton
+  SToast --> SButton
+  style SButton fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SCalendar/README.md

@@ -0,0 +1,42 @@
+# SCalendar
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCalendar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 날짜 (YYYY-MM-DD) |
+| `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] (빈 문자열이면 제한 없음) |
+| `events?` | `SCalendarEventGroup[]` | — | 이벤트 그룹 (날짜별 점) |
+| `elevated?` | `boolean` | `false` | 카드 그림자 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
+| `onViewChange` | `(v: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
+
+## Dependencies
+
+### Used by
+
+ - [SDatePicker](../SDatePicker)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SCalendar --> SGhostButton
+  SDatePicker --> SCalendar
+  style SCalendar fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SCallout/README.md

@@ -0,0 +1,29 @@
+# SCallout
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCallout
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SCalloutType` | `'default'` | 콜아웃 타입 (색상·아이콘·타이틀 결정) |
+| `message?` | `SCalloutMessage[]` | `[]` | 표시할 메시지 목록 (배열 중첩으로 depth 표현). 각 문자열은 인라인 HTML(`<b>`, `<a>` 등)을 허용하며 sanitizeInlineHtml 로 살균 후 렌더된다. |
+| `children?` | `ReactNode` | — | message 대신 직접 본문을 넣을 때 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+```mermaid
+graph TD;
+  SCallout --> SIcon
+  style SCallout fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SCallout/SCallout.cjs

@@ -17,6 +17,75 @@ function cn(...inputs) {
   return twMerge(clsx.clsx(inputs));
 }
 
+// src/lib/sanitize-inline-html.ts
+var ALLOWED_INLINE_TAGS = /* @__PURE__ */ new Set(["A", "B", "STRONG", "I", "EM", "BR", "SPAN"]);
+var ALLOWED_ATTRS_BY_TAG = {
+  A: /* @__PURE__ */ new Set(["href", "target", "rel", "class"])
+};
+var COMMON_ALLOWED_ATTRS = /* @__PURE__ */ new Set(["class"]);
+var SAFE_HREF_RE = /^(https?:|mailto:|tel:|\/|#|\.)/i;
+var DROP_CONTENT_TAGS = /* @__PURE__ */ new Set([
+  "SCRIPT",
+  "STYLE",
+  "IFRAME",
+  "OBJECT",
+  "EMBED",
+  "META",
+  "LINK",
+  "BASE",
+  "NOSCRIPT",
+  // SVG/MATH 는 foreign-content 파싱 모드로 전환되어 재직렬화 시 다른 트리로
+  // 재파싱될 수 있다(mXSS 벡터). 인라인 라벨에 필요 없으므로 통째로 제거한다.
+  "SVG",
+  "MATH",
+  "TEMPLATE"
+]);
+var escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+var sanitizeNode = (node) => {
+  if (node.nodeType === Node.COMMENT_NODE) {
+    node.remove();
+    return;
+  }
+  if (node.nodeType !== Node.ELEMENT_NODE) return;
+  const element = node;
+  const tagName = element.tagName;
+  if (DROP_CONTENT_TAGS.has(tagName)) {
+    element.remove();
+    return;
+  }
+  Array.from(element.childNodes).forEach((child) => sanitizeNode(child));
+  if (ALLOWED_INLINE_TAGS.has(tagName)) {
+    if (element.hasAttribute("className")) {
+      const val = element.getAttribute("className");
+      element.removeAttribute("className");
+      if (!element.hasAttribute("class")) element.setAttribute("class", val);
+    }
+    const allowedAttrs = ALLOWED_ATTRS_BY_TAG[tagName] ?? COMMON_ALLOWED_ATTRS;
+    Array.from(element.attributes).forEach((attr) => {
+      if (!allowedAttrs.has(attr.name)) element.removeAttribute(attr.name);
+    });
+    if (tagName === "A") {
+      const href = element.getAttribute("href");
+      if (href !== null && href !== "" && !SAFE_HREF_RE.test(href)) element.removeAttribute("href");
+      if (element.hasAttribute("target")) {
+        element.setAttribute("rel", "noopener noreferrer");
+      }
+    }
+    return;
+  }
+  const parent = element.parentNode;
+  if (parent == null) return;
+  while (element.firstChild) parent.insertBefore(element.firstChild, element);
+  parent.removeChild(element);
+};
+var sanitizeInlineHtml = (value) => {
+  if (typeof document === "undefined") return escapeHtml(value);
+  const template = document.createElement("template");
+  template.innerHTML = value;
+  Array.from(template.content.childNodes).forEach((child) => sanitizeNode(child));
+  return template.innerHTML;
+};
+
 // src/lib/color.ts
 var COLOR_KEYS = [
   "white",
@@ -2867,7 +2936,13 @@ function renderItems(message, depth = 1) {
           className: cn("flex items-start", isDepth2 && "pl-[32px]"),
           children: [
             /* @__PURE__ */ jsxRuntime.jsx("span", { className: "w-[24px] shrink-0 text-center", "aria-hidden": true, children: isDepth2 ? "\u2022" : "-" }),
-            /* @__PURE__ */ jsxRuntime.jsx("p", { className: "m-0 min-w-0 flex-1 break-words", children: m })
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "p",
+              {
+                className: "m-0 min-w-0 flex-1 break-words",
+                dangerouslySetInnerHTML: { __html: sanitizeInlineHtml(m) }
+              }
+            )
           ]
         },
         `${depth}-${i}-${out.length}`