sellmate-design-system-react 9.0.0-beta.13 → 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/SCard/SCard.d.ts

@@ -3,5 +3,5 @@ export interface SCardProps extends HTMLAttributes<HTMLDivElement> {
     /** 테두리 표시 여부 */
     bordered?: boolean;
 }
-/** SCard — sd-card 포팅. 라운드 8px, 흰 배경, 옵션 테두리. */
+/** SCard — sd-card 포팅. 라운드 8px, 흰 배경, 옵션 테두리. 콘텐츠는 라운드 경계에서 잘린다. */
 export declare const SCard: import("react").ForwardRefExoticComponent<SCardProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SGnb/gnb.config.d.ts

@@ -162,3 +162,8 @@ export declare function findGnbRailValue(items: SGnbMenuItem[], value: string):
 export declare function findGnbSiblingValues(items: SGnbMenuItem[], value: string): string[];
 /** value 로 선택된 아이템의 조상 value 목록(자기 자신 제외)을 반환 → 자동 펼침용 */
 export declare function findGnbAncestors(items: SGnbMenuItem[], value: string): string[];
+/**
+ * value 를 가진 아이템 아래의 **하위 가지**(children 을 가진 자손) value 목록을 반환.
+ * 부모를 펼칠 때 그 아래 가지도 전부 함께 펼치는 용도 — 리프는 펼침 대상이 아니라 제외한다.
+ */
+export declare function findGnbDescendantBranchValues(items: SGnbMenuItem[], value: string): string[];

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

@@ -3373,7 +3373,11 @@ var SCard = /* @__PURE__ */ react.forwardRef(function SCard2({ bordered = false,
     "div",
     {
       ref,
-      className: cn("h-fit rounded-[8px] bg-white", bordered && "border border-grey-30", className),
+      className: cn(
+        "h-fit overflow-hidden rounded-[8px] bg-white",
+        bordered && "border border-grey-30",
+        className
+      ),
       ...rest,
       children
     }
@@ -8329,6 +8333,29 @@ function findGnbAncestors(items, value) {
   };
   return walk(items, []) ?? [];
 }
+function findGnbDescendantBranchValues(items, value) {
+  const find = (list) => {
+    for (const item of list) {
+      if (item.value === value) return item;
+      if (item.children) {
+        const found = find(item.children);
+        if (found) return found;
+      }
+    }
+    return void 0;
+  };
+  const collect = (list, acc) => {
+    for (const item of list) {
+      if (item.children && item.children.length > 0) {
+        acc.push(item.value);
+        collect(item.children, acc);
+      }
+    }
+    return acc;
+  };
+  const target = find(items);
+  return target?.children ? collect(target.children, []) : [];
+}
 var LABEL_TIP_HIDE_DELAY_MS = 100;
 var DEPTH_PADDING_LEFT = (M, depth) => depth === 1 ? M.depth1PaddingLeft : depth === 2 ? M.depth2PaddingLeft : M.depth3PaddingLeft;
 var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
@@ -8369,8 +8396,12 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
   const H = GNB_HEADER[header];
   const M = GNB_MENU[type];
   const C = GNB_COLORS[color];
+  const branchWithDescendants = (key) => [
+    key,
+    ...findGnbDescendantBranchValues(items, key)
+  ];
   const [expandedKeys, setExpandedKeys] = react.useState(
-    () => new Set(findGnbAncestors(items, value))
+    () => new Set(findGnbAncestors(items, value).flatMap(branchWithDescendants))
   );
   const [hoveredKey, setHoveredKey] = react.useState(null);
   const [labelTip, setLabelTip] = react.useState(null);
@@ -8417,12 +8448,15 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
     () => findGnbRailValue(items, value) ?? items[0]?.value
   );
   react.useEffect(() => {
-    const ancestors = findGnbAncestors(items, value);
-    if (ancestors.length === 0) return;
+    const keys = findGnbAncestors(items, value).flatMap((ancestor) => [
+      ancestor,
+      ...findGnbDescendantBranchValues(items, ancestor)
+    ]);
+    if (keys.length === 0) return;
     setExpandedKeys((prev) => {
-      if (ancestors.every((a) => prev.has(a))) return prev;
+      if (keys.every((key) => prev.has(key))) return prev;
       const next = new Set(prev);
-      ancestors.forEach((a) => next.add(a));
+      keys.forEach((key) => next.add(key));
       return next;
     });
   }, [items, value]);
@@ -8439,10 +8473,12 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
     setExpandedKeys((prev) => {
       const next = new Set(prev);
       if (next.has(key)) {
-        next.delete(key);
+        branchWithDescendants(key).forEach((descendant) => next.delete(descendant));
       } else {
-        findGnbSiblingValues(items, key).forEach((sibling) => next.delete(sibling));
-        next.add(key);
+        findGnbSiblingValues(items, key).forEach(
+          (sibling) => branchWithDescendants(sibling).forEach((descendant) => next.delete(descendant))
+        );
+        branchWithDescendants(key).forEach((descendant) => next.add(descendant));
       }
       return next;
     });
@@ -11430,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
+                                        }
+                                      ) })
                                     ] })
                                   }
                                 ),