sellmate-design-system-react 9.0.0-beta.14 → 9.0.0-beta.15

package/AGENTS.md

@@ -854,6 +854,24 @@ const columns: STableColumn[] = [
 
 `0` 은 값이 있는 것이므로 하이픈으로 바꾸지 않는다 — `0원` 그대로 표시한다.
 
+#### 라벨만으로 뜻이 안 통하는 컬럼은 `helpText`
+
+헤더 라벨은 컬럼 폭 안에 들어가야 해서 짧아진다. **산출 기준·단위·상태 값의 뜻처럼 라벨에 담기지 않는 설명은 `column.helpText` 로 준다** — 라벨 뒤에 도움말 아이콘이 붙고 hover 하면 툴팁이 뜬다. 배열의 각 항목이 한 줄이다. `SKeyValueTable` 의 `field.helpText`, `SSectionHeaderCard` 의 `helpText` 와 같은 것이다.
+
+```tsx
+const columns: STableColumn[] = [
+  { name: 'orderCount', label: '주문 수', field: 'orderCount', width: '120px', align: 'right',
+    helpText: ['취소·반품을 제외한 확정 주문 수입니다.'],
+    format: (v: number) => `${Number(v).toLocaleString()}건` },
+  { name: 'status', label: '상태', field: 'status', width: '100px', align: 'center',
+    helpText: ['활성: 최근 30일 내 주문 있음', '보관됨: 거래 종료'] },
+];
+```
+
+- **`renderHeader` 로 헤더를 직접 만들어 `STooltip` 을 붙이지 않는다.** `renderHeader` 는 헤더 전체를 교체하므로 `helpText` 가 무시되고, 아이콘·크기·색·간격을 손으로 맞추게 된다.
+- **모든 컬럼에 달지 않는다.** 라벨로 뜻이 통하는 컬럼(`주문번호`·`상품명`)까지 붙이면 헤더가 아이콘으로 뒤덮여 정작 설명이 필요한 컬럼이 묻힌다.
+- 긴 문장을 넣는 자리가 아니다. 한 줄에 한 가지 사실만 담고, 그 이상은 페이지 상단 안내(`SCallout`)로 뺀다.
+
 ### 3-5. 버튼류
 
 | 상황 | 사용 |

package/dist/components/STable/README.md

@@ -83,6 +83,13 @@ export interface STableColumn {
   icon?: SIconName;
   /** 헤더 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
   iconColor?: SColor;
+  /**
+   * 헤더 라벨 뒤 도움말 툴팁 (각 항목이 한 줄). `SKeyValueTable` 의 `field.helpText` 와 같은 역할 —
+   * 라벨만으로 뜻이 통하지 않는 컬럼의 산출 기준·단위를 설명한다.
+   *
+   * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+   */
+  helpText?: string[];
   /**
    * 셀에 무엇이 들어가는지. 좌우 여백이 여기서 갈린다 — 기본은 `text`(넓게).
    *
@@ -172,6 +179,7 @@ export interface STableCellContext {
 - [SIcon](../SIcon)
 - [SPagination](../SPagination)
 - [SSelect](../SSelect)
+- [STooltip](../STooltip)
 
 ### Graph
 
@@ -182,5 +190,6 @@ graph TD;
   STable --> SIcon
   STable --> SPagination
   STable --> SSelect
+  STable --> STooltip
   style STable fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/STable/STable.d.ts

@@ -38,6 +38,13 @@ export interface STableColumn {
     icon?: SIconName;
     /** 헤더 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
     iconColor?: SColor;
+    /**
+     * 헤더 라벨 뒤 도움말 툴팁 (각 항목이 한 줄). `SKeyValueTable` 의 `field.helpText` 와 같은 역할 —
+     * 라벨만으로 뜻이 통하지 않는 컬럼의 산출 기준·단위를 설명한다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    helpText?: string[];
     /**
      * 셀에 무엇이 들어가는지. 좌우 여백이 여기서 갈린다 — 기본은 `text`(넓게).
      *

package/dist/components/STooltip/README.md

@@ -69,6 +69,7 @@ export type STooltipType = 'default' | 'danger' | 'warning' | 'accent';
  - [SKeyValueTable](../SKeyValueTable)
  - [SSectionHeaderCard](../SSectionHeaderCard)
  - [SStepper](../SStepper)
+ - [STable](../STable)
 
 ### Depends on
 
@@ -86,5 +87,6 @@ graph TD;
   SKeyValueTable --> STooltip
   SSectionHeaderCard --> STooltip
   SStepper --> STooltip
+  STable --> STooltip
   style STooltip fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/index.cjs

@@ -11466,7 +11466,21 @@ var STable = /* @__PURE__ */ react.forwardRef(function STable2({
                                     ),
                                     children: col.renderHeader ? col.renderHeader(col, i) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
                                       col.icon && /* @__PURE__ */ jsxRuntime.jsx(SIcon, { name: col.icon, size: 16, color: col.iconColor }),
-                                      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "truncate", children: col.label })
+                                      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "truncate", children: col.label }),
+                                      col.helpText && col.helpText.length > 0 && // 라벨이 좁아져 truncate 되더라도 아이콘까지 함께 줄어들면 안 되므로
+                                      // shrink-0 래퍼로 감싼다 (STooltip 의 className 은 본문 쪽으로 간다).
+                                      // 아이콘·크기·색은 SKeyValueTable 헤더 도움말과 동일하게 맞춘다.
+                                      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "inline-flex shrink-0", children: /* @__PURE__ */ jsxRuntime.jsx(
+                                        STooltip2,
+                                        {
+                                          trigger: "hover",
+                                          icon: "helpOutline",
+                                          iconSize: 12,
+                                          color: "var(--sys-color-fg-success)",
+                                          placement: "top",
+                                          message: col.helpText
+                                        }
+                                      ) })
                                     ] })
                                   }
                                 ),