sellmate-design-system-react 9.0.0-beta.8 → 9.0.0-beta.80

package/dist/components/STable/README.md

@@ -8,29 +8,33 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `columns?` | `STableColumn[]` | `[]` |  |
-| `rows?` | `SRow[]` | `[]` |  |
+| `columns?` | `STableColumn<TRow>[]` | `[]` |  |
+| `headerGroups?` | `STableHeaderGroup[]` | — | 상위 그룹 헤더. 지정하면 기존 컬럼 헤더가 두 번째 행에 렌더링된다. |
+| `rows?` | `TRow[]` | `[]` |  |
 | `rowKey?` | `string` | `'id'` | 행 식별 필드 |
 | `selectable?` | `boolean` | `false` | 행 선택 체크박스 |
-| `selected?` | `SRow[]` | `[]` |  |
+| `dragSelectable?` | `boolean` | `false` | 행을 드래그해서 고른다. 기본 `false`. 고르는 수단만 다를 뿐 `selectable` 과 같은 선택이다 — `selected` · `onSelectedChange` · `isRowSelectable` 을 그대로 쓴다. 체크박스 열은 생기지 않고, 대신 고른 구간이 배경색과 바깥 테두리로 표시된다. **`selectable` 과 함께 켜면 `selectable` 이 이긴다** — 체크박스가 있는 표에서 드래그까지 걸리면 글자를 긁으려던 손이 선택을 갈아치운다. 둘 다 필요해 보이면 체크박스 쪽만 남긴다. 누른 자리가 구간의 기준점이고, 끌어간 자리까지가 구간이다. **새로 끌면 이전 선택은 풀린다** — 기존 선택에 더하려면 `Ctrl`(macOS 는 `Cmd`)을 짚고 끈다. 잠긴 행(`isRowSelectable`)은 구간 안에 있어도 그냥 지나간다. **켜 두면 셀 안의 글자를 긁어 복사할 수 없다** — 끌기가 곧 선택이라 글자 선택과 같은 손짓을 두고 다툰다. 값을 복사해 가는 표에는 켜지 않는다. 셀 안의 버튼·입력은 그대로 눌린다. |
+| `contextMenuItems?` | `STableContextMenuItem[]` | — | 드래그 선택에서 **행을 오른쪽 클릭했을 때** 커서 자리에 뜨는 메뉴의 항목. 주지 않거나 비면 메뉴가 뜨지 않고 브라우저 기본 메뉴가 나온다. **`dragSelectable` 에서만 동작한다** — 체크박스 모드에서는 무시된다. 고르지 않은 행에서 누르면 **그 행만 고른 뒤** 열린다. 메뉴가 다룰 대상과 화면에 칠해진 것이 어긋나지 않게 하기 위함이다. 잠긴 행(`isRowSelectable`) 위에서는 열리지 않는다 — 고를 수 없는 행을 대상으로 삼을 수 없기 때문이다. |
+| `isRowSelectable?` | `(row: TRow) => boolean` | — | 이 행을 고를 수 있는가. 주지 않으면 모든 행을 고를 수 있다. 고를 수 없는 행은 체크박스가 잠기고, **전체 선택·Shift 구간 선택의 셈에서도 빠진다** — 잠긴 행이 셈에 남으면 "전부 선택됨"에 닿지 못해 헤더 체크박스가 해제 방향으로 가지 못한다. 목록에서 지워 버리는 것과 다르다. 실패 0건인 차수처럼 **자리는 보여야 하지만 대상이 될 수는 없는 행**에 쓴다. 아예 대상이 아니라면 `rows` 에서 거르는 편이 낫다. 잠금은 그리기 시점의 판정일 뿐이라, 이미 `selected` 에 든 행이 나중에 잠겨도 DS 가 빼지 않는다(제어 상태를 말없이 바꾸지 않는다). 다만 헤더의 전체 해제로는 걷어낼 수 있다. |
+| `selected?` | `TRow[]` | `[]` |  |
+| `sort?` | `STableSort \| null` | `null` | 정렬 상태 (controlled). `null`·미지정이면 정렬 없음. 컴포넌트는 정렬 상태를 갖지 않는다 — 서버 정렬이면 이 값이 곧 조회 조건이고, 뒤로가기·새로고침·링크 공유로 복원돼야 하므로 진실은 URL·store 쪽에 있어야 한다. 행을 실제로 정렬하는 것도 소비 앱 몫이다 (`STable` 은 받은 순서대로 그린다). |
 | `resizable?` | `boolean` | `false` | 컬럼 너비 조절 |
 | `width?` | `string` | — |  |
 | `height?` | `string` | — |  |
-| `stickyHeader?` | `boolean` | — |  |
 | `stickyColumn?` | `STableStickyColumn` | — | 고정할 좌/우 컬럼 수 |
 | `radius?` | `'default' \| 'useTop' \| 'full'` | `'default'` | border-radius 제어 |
 | `bordered?` | `boolean` | `true` | 바깥 테두리. 기본은 `true`. `SSectionHeaderCard` 의 `padding="none"` 안에 넣어 카드 가장자리까지 채울 때 `false` 로 끈다 — 카드가 이미 바깥 테두리를 그리므로, 켜 두면 1px 두 개가 나란히 놓여 그 변만 2px 로 보인다. 페이지네이션 바의 테두리와 1px 겹침(`-mt-px`)도 함께 꺼진다. 본문 테두리가 없으면 겹칠 대상이 없어, 그대로 두면 페이지네이션만 테두리를 갖고 1px 어긋난다. |
-| `noDataLabel?` | `string` | `'데이터가 없습니다.'` |  |
-| `noDataSlot?` | `ReactNode` | — | 데이터가 없을 때 body 영역 전체를 대체하는 슬롯. 지정하면 `noDataLabel` 대신 이 콘텐츠가 헤더 아래 영역을 채우며, 버튼 등 인터랙션도 동작한다. |
-| `isLoading?` | `boolean` | `false` |  |
-| `dense?` | `boolean` | `false` |  |
-| `noHover?` | `boolean` | `false` | true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 |
+| `emptyLabel?` | `string` | `'데이터가 없습니다.'` |  |
+| `emptySlot?` | `ReactNode` | — | 데이터가 없을 때 body 영역 전체를 대체하는 슬롯. 지정하면 `emptyLabel` 대신 이 콘텐츠가 헤더 아래 영역을 채우며, 버튼 등 인터랙션도 동작한다. |
+| `loading?` | `boolean` | `false` |  |
+| `dense?` | `boolean` | `false` | 행 높이를 좁게 (세로 여백만 줄인다 — 좌우 패딩은 그대로). **시작 밀도이자 밀도 토글의 스위치다.** 켜면 하단 바 우측에 `좁게 보기` · `넓게 보기` 토글이 붙는다 — 페이지네이션이 없으면 이 바를 토글만 담아 그린다. 누른 뒤의 밀도는 테이블이 내부 상태로 들고 가므로 `onDenseChange` 를 받지 않아도 토글은 동작하고, 넓게 본 뒤에도 토글은 그대로 남는다(붙일지는 이 prop 이 정한다). 이 prop 값이 바뀌면 내부 밀도도 그 값으로 맞춰진다. |
+| `hoverable?` | `boolean` | `true` | 행에 마우스를 올렸을 때 hover 배경(grey_05)을 표시할지. 기본 `true` — `false` 면 표시하지 않는다 |
 | `pagination?` | `STablePagination` | — | 페이지네이션 (있으면 하단 표시) |
-| `useInternalPagination?` | `boolean` | `false` | 테이블 내부에서 페이지네이션을 직접 관리 (rows를 내부 슬라이싱) |
-| `useRowsPerPageSelect?` | `boolean` | `false` | 페이지당 행 수 셀렉트 표시 |
+| `internalPagination?` | `boolean` | `false` | 테이블 내부에서 페이지네이션을 직접 관리 (rows를 내부 슬라이싱) |
+| `showRowsPerPageSelect?` | `boolean` | `false` | 페이지당 행 수 셀렉트 표시 |
 | `rowsPerPageOption?` | `SSelectOption[]` | `DEFAULT_ROWS_PER_PAGE_OPTION` |  |
-| `useVirtualScroll?` | `boolean` | `false` | 가상 스크롤 |
-| `rowHeight?` | `number` | — |  |
+| `virtualScroll?` | `boolean` | `false` | 가상 스크롤 |
+| `rowHeight?` | `number` | — | 행 높이의 **출발점**(px). 미지정이면 밀도에 따라 44 / 32. 행마다 높이가 달라도 된다 — 화면에 나온 행은 실제 높이를 재서 덮으므로, 이 값은 **아직 안 그려진 행의 추정치**이자 행의 최소 높이일 뿐이다. 실측이 쌓일수록 뒤쪽 추정도 그 평균으로 수렴한다. 그래서 높이가 제각각인 표에서 "가장 흔한 높이"를 넣어 두면 충분하다. 값이 실제와 멀수록 아직 안 그려진 구간의 스크롤바 길이만 덜 정확할 뿐, 그리는 위치는 어긋나지 않는다. |
 | `virtualBuffer?` | `number` | `5` |  |
 | `virtualEndThreshold?` | `number` | `10` |  |
 | `tableId?` | `string` | — | 테이블 식별자 (없으면 자동 생성) |
@@ -41,24 +45,127 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onSelectedChange` | `(rows: SRow[]) => void` |  |
+| `onContextMenuItemClick` | `(value: string \| number, rows: TRow[]) => void` | 메뉴 항목을 골랐을 때. 고른 항목의 `value` 와 **그 메뉴가 다루는 행들**이 함께 온다. 행 목록은 메뉴가 열린 시점에 확정되므로 `selected` 를 따로 읽지 않아도 된다 — 오른쪽 클릭이 선택을 바꾸는 경우(고르지 않은 행)에도 바뀐 뒤의 행이 온다. |
+| `onSelectedChange` | `(rows: TRow[]) => void` |  |
+| `onSortChange` | `(sort: STableSort \| null) => void` | 정렬 헤더 클릭 (`asc → desc → 해제` 3단). 해제되면 `null` 이 온다. 다중 정렬은 1차 안에서 지원하지 않는다. |
+| `onDenseChange` | `(dense: boolean) => void` | 밀도 변경 (하단 바의 밀도 토글을 눌렀을 때). 표시는 테이블이 알아서 바꾸므로 받지 않아도 되고, 사용자가 고른 밀도를 다음 방문까지 기억해 두려는(로컬 저장 등) 페이지만 받으면 된다. |
 | `onPageChange` | `(page: number) => void` |  |
 | `onRowsPerPageChange` | `(perPage: number) => void` |  |
+| `onScroll` | `(event: ReactUIEvent<HTMLDivElement>) => void` | 본문이 스크롤될 때. **실제 스크롤에만 울린다** — 행 수·컬럼 폭·로딩이 바뀌어 내부에서 위치를 다시 잴 때는 오지 않는다. `onVirtualUpdate` 는 그리는 창이 바뀔 때만 오므로 그 사이 스크롤을 알 수 없다. 스크롤 위치를 읽어 두었다 되돌리는 것처럼 **위치 자체가 필요하면** 이쪽을 쓴다. |
 | `onVirtualUpdate` | `(range: { from: number; to: number }) => void` |  |
 | `onVirtualReachEnd` | `(info: { from: number; to: number; rowCount: number; threshold: number; }) =>…` |  |
-| `onRowClick` | `(row: SRow) => void` | 행 클릭 |
+| `onRowClick` | `(row: TRow) => void` | 행 클릭 |
+| `onRowDoubleClick` | `(row: TRow) => void` | 행 더블클릭. 목록에서 상세를 여는 것처럼 **한 번 누르는 것과 다른 일**을 걸 때 쓴다. 더블클릭도 클릭 두 번이라 `onRowClick` 과 함께 주면 **`onRowClick` 이 두 번 먼저 울린다** — 둘을 함께 쓰려면 `onRowClick` 은 두 번 울려도 결과가 같은 일(행 강조 등)이어야 한다. 선택 체크박스 열과 셀 안의 버튼·링크·입력 위에서 한 더블클릭은 행 더블클릭이 아니다 — 체크박스를 빠르게 두 번 누르거나 입력의 글자를 더블클릭으로 고르다 상세가 열리지 않게 한다. |
 
 #### Methods (ref)
 
 | Method | Type | Description |
 |--------|------|-------------|
-| `isRowSelected` | `(row: SRow) => boolean` | 행 선택 여부 |
-| `getIsAllChecked` | `(rows: SRow[]) => boolean \| null` | 주어진 행들의 전체 선택 상태 (true/false/null=indeterminate) |
-| `getPaginationInfo` | `<union 2종>` | 내부 페이지네이션 정보 (useInternalPagination 아니면 null) |
+| `isRowSelected` | `(row: TRow) => boolean` | 행 선택 여부 |
+| `getIsAllChecked` | `(rows: TRow[]) => boolean \| null` | 주어진 행들의 전체 선택 상태 (true/false/null=indeterminate) |
+| `getPaginationInfo` | `<union 2종>` | 내부 페이지네이션 정보 (internalPagination 아니면 null) |
 | `getStickyStyle` | `(colIdx: number) => CSSProperties` | 컬럼 sticky 스타일 (CSS 변수 + 고정폭) |
+| `getScrollElement` | `() => HTMLDivElement \| null` | 본문의 세로 스크롤 컨테이너. 본문이 슬롯으로 대체됐거나 아직 안 그려졌으면 `null`. 스크롤 위치를 읽고 되돌리거나, 표 안에서 스크롤 여지를 재야 할 때 쓴다 — **DOM 을 뒤져 컨테이너를 찾지 않는다.** 내부 구조는 예고 없이 바뀐다. ⚠️ `virtualScroll` 에서 **위치를 픽셀로 저장했다 되돌리는 것은 미덥지 않다.** 다시 그릴 때 아직 안 그려진 행은 추정 높이로 잡히므로, 실측이 쌓이기 전의 같은 `scrollTop` 이 다른 행을 가리킨다. 그 경우엔 위치가 아니라 **보고 있던 행**을 기억해 두는 편이 맞다. |
+| `getFirstVisibleRow` | `() => number` | 지금 본문 맨 위에 걸린 행의 인덱스 (`rows` 기준). 행이 없으면 `0`. **스크롤 위치를 저장할 때는 픽셀이 아니라 이 값을 저장한다** — `virtualScroll` 에서 픽셀은 좌표계가 실측으로 움직이는 값이라, 되돌릴 때 다른 행을 가리킨다. |
+| `scrollToRow` | `(index: number) => void` | 그 행이 본문 맨 위에 오도록 스크롤한다 (`rows` 기준 인덱스, 범위를 벗어나면 잘린다). `virtualScroll` 에서는 **실측이 정착할 때까지 그 행을 계속 다시 겨냥한다** — 옮기는 시점의 좌표는 아직 추정치라 한 번만 옮기면 몇 행씩 밀린다. 사용자가 직접 스크롤하면 겨냥을 놓는다. 페이지네이션을 쓰는 표에서는 **지금 페이지에 그려진 행만** 닿는다 — 다른 페이지의 행이라면 페이지를 먼저 옮긴다. |
 | `setRowCount` | `(count: number) => void` | 가상 스크롤 총 행 수 설정 |
-| `updateRowSelect` | `(row: SRow) => void` | 단일 행 선택 토글 (sd-table updateRowSelect) — onSelectedChange 발생 |
-| `toggleSelectAll` | `(checked: boolean, rows: SRow[]) => void` | 주어진 행들 전체 선택/해제 (sd-table toggleSelectAll) — onSelectedChange 발생 |
+| `updateRowSelect` | `(row: TRow) => void` | 단일 행 선택 토글 (sd-table updateRowSelect) — onSelectedChange 발생 |
+| `toggleSelectAll` | `(checked: boolean, rows: TRow[]) => void` | 주어진 행들 전체 선택/해제 (sd-table toggleSelectAll) — onSelectedChange 발생 |
+
+## Types
+
+### SRow
+
+```ts
+/**
+ * 행 데이터의 기본 타입 — 키만 아는 느슨한 레코드다.
+ *
+ * 행 타입을 알면 `STableColumn<Order>[]` · `<STable<Order> rows={orders} />` 처럼 넘겨 좁힌다.
+ * 그러면 `render`·`format`·`onRowClick` 이 `Order` 를 받는다. 넘기지 않은 기존 코드는 이 기본값으로
+ * 예전처럼 동작한다 — 기본값을 `unknown` 으로 바꾸면 `row.statusLabel` 같은 코드가 전부 깨진다.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- 행 타입을 넘기지 않은 화면의 의도된 탈출구
+export type SRow = Record<string, any>;
+```
+
+### STableColumn
+
+```ts
+/**
+ * `autoWidth` 스페이서 열은 값을 그리지 않으므로 `field` 를 생략할 수 있다.
+ * 그 밖의 열은 값 접근자가 있어야 한다.
+ */
+export type STableColumn<TRow extends SRow = SRow> = STableColumnBase<TRow> &
+  (
+    | { autoWidth: true; field?: STableColumnField<TRow> }
+    | { autoWidth?: false; field: STableColumnField<TRow> }
+  );
+```
+
+### STableHeaderGroup
+
+```ts
+/** 2단 헤더의 상위 셀. columnNames는 visible 컬럼 기준으로 연속되어야 한다. */
+export interface STableHeaderGroup {
+  label?: ReactNode;
+  columnNames: string[];
+  rowSpan?: 1 | 2;
+  align?: 'left' | 'center' | 'right';
+  className?: string;
+  style?: CSSProperties;
+  render?: () => ReactNode;
+}
+```
+
+### STableContextMenuItem
+
+```ts
+/** 오른쪽 클릭 메뉴의 항목 한 줄 */
+export interface STableContextMenuItem {
+  /** 클릭 시 `onContextMenuItemClick` 으로 돌아오는 값 */
+  value: string | number;
+  label: string;
+  icon?: SIconName;
+  disabled?: boolean;
+}
+```
+
+### STableSort
+
+```ts
+/** 정렬 상태 — 어느 열을 어느 방향으로 정렬했는가 */
+export interface STableSort {
+  /** 정렬 기준 컬럼의 `name` */
+  name: string;
+  dir: 'asc' | 'desc';
+}
+```
+
+### STableStickyColumn
+
+```ts
+export interface STableStickyColumn {
+  left?: number;
+  right?: number;
+}
+```
+
+### STablePagination
+
+```ts
+export interface STablePagination {
+  page: number;
+  rowsPerPage: number;
+  lastPage?: number;
+}
+```
+
+### STableColumnField
+
+```ts
+/** 값 접근: 필드명 또는 접근 함수 */
+export type STableColumnField<TRow extends SRow = SRow> = string | ((row: TRow) => unknown);
+```
 
 ## Dependencies
 
@@ -66,9 +173,13 @@
 
 - [SCheckbox](../SCheckbox)
 - [SCircleProgress](../SCircleProgress)
+- [SDivider](../SDivider)
+- [SGhostButton](../SGhostButton)
 - [SIcon](../SIcon)
 - [SPagination](../SPagination)
 - [SSelect](../SSelect)
+- [STextLink](../STextLink)
+- [STooltip](../STooltip)
 
 ### Graph
 
@@ -76,8 +187,12 @@
 graph TD;
   STable --> SCheckbox
   STable --> SCircleProgress
+  STable --> SDivider
+  STable --> SGhostButton
   STable --> SIcon
   STable --> SPagination
   STable --> SSelect
+  STable --> STextLink
+  STable --> STooltip
   style STable fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -1,14 +1,35 @@
-import { type CSSProperties, type ReactNode } from 'react';
-import { type SColor } from '../../lib/color';
+import { type CSSProperties, type UIEvent as ReactUIEvent, type ForwardedRef, type ReactElement, type ReactNode } from 'react';
 import { type SIconName } from '../SIcon';
 import { type SSelectOption } from '../SSelect';
+/**
+ * 행 데이터의 기본 타입 — 키만 아는 느슨한 레코드다.
+ *
+ * 행 타입을 알면 `STableColumn<Order>[]` · `<STable<Order> rows={orders} />` 처럼 넘겨 좁힌다.
+ * 그러면 `render`·`format`·`onRowClick` 이 `Order` 를 받는다. 넘기지 않은 기존 코드는 이 기본값으로
+ * 예전처럼 동작한다 — 기본값을 `unknown` 으로 바꾸면 `row.statusLabel` 같은 코드가 전부 깨진다.
+ */
 export type SRow = Record<string, any>;
+/**
+ * 셀 값(`format`·`render` 가 받는 값)의 타입.
+ *
+ * 행 타입을 좁히지 않았으면(`SRow`) 예전처럼 느슨하게 받고, 좁혔으면 `unknown` 이다 — `field` 가
+ * 접근 함수일 수도 있어 행 타입만으로는 값의 타입을 정할 수 없으므로 받는 쪽이 확인한다.
+ */
+export type STableCellValue<TRow extends SRow = SRow> = SRow extends TRow ? any : unknown;
+/** 오른쪽 클릭 메뉴의 항목 한 줄 */
+export interface STableContextMenuItem {
+    /** 클릭 시 `onContextMenuItemClick` 으로 돌아오는 값 */
+    value: string | number;
+    label: string;
+    icon?: SIconName;
+    disabled?: boolean;
+}
 /** `STableColumn.renderCell`에 전달되는 컨텍스트 */
-export interface STableCellContext {
-    row: SRow;
+export interface STableCellContext<TRow extends SRow = SRow> {
+    row: TRow;
     /** `field` + `format`이 적용된 표시 값 */
-    value: any;
-    column: STableColumn;
+    value: STableCellValue<TRow>;
+    column: STableColumn<TRow>;
     /** 보이는 컬럼 기준 인덱스 */
     colIndex: number;
     /** 현재 렌더 중인 행 목록 기준 인덱스 (페이지/가상 스크롤 윈도우 기준) */
@@ -20,24 +41,85 @@ export interface STableCellContext {
     /** STable이 이 셀에 적용하려던 스타일 (패딩·정렬·폭·sticky offset 포함) */
     style: CSSProperties;
 }
-export interface STableColumn {
+/** 값 접근: 필드명 또는 접근 함수 */
+export type STableColumnField<TRow extends SRow = SRow> = string | ((row: TRow) => unknown);
+interface STableColumnBase<TRow extends SRow = SRow> {
     name: string;
     label: string;
-    /** 값 접근: 필드명 또는 접근 함수 */
-    field: string | ((row: SRow) => any);
     align?: 'left' | 'center' | 'right';
-    width?: string;
-    /** 고정폭 없이 자동 너비 (sticky/resize 계산에서 제외) */
+    /**
+     * 컬럼 너비. **px 로만 준다** — 숫자는 px 로 해석하고, 문자열은 `'120px'` 형태만 받는다.
+     *
+     * % · `clamp()` · `min()` 은 쓰지 않는다. 폭은 `<colgroup>` 의 `<col width>` 로 들어가는데
+     * 테이블이 `table-fixed` 라 함수형 값은 계산되지 않고 통째로 무시된다 — 화면은 조용히
+     * auto 폭으로 떨어진다. `'30%'` 는 더 나쁘게 30px 로 읽힌다.
+     *
+     * 생략하면 기본 120px 이다. 내용이 들어가는 열은 값 길이에 맞춰 폭을 명시한다 —
+     * 폭을 주지 않은 열만 다른 열에 눌려 무너지거나 늘어난다.
+     */
+    width?: number | `${number}px`;
+    /**
+     * 고정폭 없이 남은 폭을 흡수한다 (sticky/resize 계산에서 제외).
+     *
+     * **남은 폭을 먹는 스페이서 열 하나에만 쓴다.** 내용이 들어가는 열에 주면 폭이 다른 열에
+     * 좌우돼 화면마다 달라진다 — 내용 열은 px 로 폭을 명시한다.
+     */
     autoWidth?: boolean;
-    /** 리사이즈 최소/최대 너비 (px) */
+    /**
+     * 리사이즈 하한/상한 (px). **`resizable` 로 끄는 손잡이의 이동 범위일 뿐, 레이아웃에는
+     * 관여하지 않는다** — 폭을 주지 않은 열이 이 값 안에서 잡히는 것이 아니다.
+     */
     minWidth?: number;
     maxWidth?: number;
     /** 표시 포맷 */
-    format?: (value: any, row: SRow) => string;
+    format?: (value: STableCellValue<TRow>, row: TRow) => string;
     visible?: boolean;
-    icon?: SIconName;
-    /** 헤더 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
-    iconColor?: SColor;
+    /**
+     * 헤더 라벨 뒤 도움말 툴팁 (각 항목이 한 줄). `SKeyValueTable` 의 `field.helpText` 와 같은 역할 —
+     * 라벨만으로 뜻이 통하지 않는 컬럼의 산출 기준·단위를 설명한다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    helpText?: string[];
+    /**
+     * 라벨 뒤 필수 표시(`*`). `SKeyValueTable` 의 `field.required` 와 같은 규칙 —
+     * 그 열의 값을 반드시 채워야 하는 입력 열에만 쓴다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    required?: boolean;
+    /**
+     * **지금 이 화면에 머문 채로** 값을 고치는 열. 라벨 뒤에 `pageEdit` 표식이 붙는다.
+     *
+     * 셀에서 바로 고치는 것도, 수정 모달·바텀시트를 띄워 고치는 것도 모두 이쪽이다 —
+     * 모달은 현재 화면 **위에** 겹쳐 뜰 뿐 화면을 떠나는 것이 아니라서 `navigable` 이 아니다.
+     *
+     * **표식일 뿐 버튼이 아니다** — 실제로 고치는 UI 는 셀(`render`)이 그린다. 표식만 켜 두면
+     * 고칠 수 있다고 해 놓고 고칠 방법이 없는 열이 된다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    editable?: boolean;
+    /**
+     * 눌러서 **이 화면을 떠나** 다른 화면으로 가는 열 — 새 창·새 팝업으로 띄우거나 페이지를
+     * 이동한다. 라벨 뒤에 `pageMove` 표식이 붙는다.
+     *
+     * 모달로 처리하는 열은 화면을 떠나지 않으므로 여기에 해당하지 않는다. 모달에서 값을 고치면
+     * `editable`, 고치지 않고 보여주기만 하면 둘 다 붙이지 않는다.
+     *
+     * **표식일 뿐 버튼이 아니다** — 화면을 여는 것은 셀(`render`)의 링크·클릭이 한다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    navigable?: boolean;
+    /**
+     * 정렬 가능한 열인지. 켜면 헤더 라벨 뒤에 정렬 버튼이 붙는다 — 누르는 곳은 그 버튼뿐이고
+     * 헤더 셀 전체가 클릭 영역이 되지는 않는다.
+     *
+     * 정렬 상태는 컴포넌트가 갖지 않는다 — `STable` 의 `sort` · `onSortChange` 로 주고받는다.
+     * `renderHeader` 로 헤더를 통째로 교체하면 버튼도 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    sortable?: boolean;
     /**
      * 셀에 무엇이 들어가는지. 좌우 여백이 여기서 갈린다 — 기본은 `text`(넓게).
      *
@@ -49,7 +131,7 @@ export interface STableColumn {
      */
     contentType?: 'text' | 'control';
     /** 셀 커스텀 렌더 (React 확장) — `<td>` 안쪽 내용만 교체한다 */
-    render?: (row: SRow, value: any) => ReactNode;
+    render?: (row: TRow, value: STableCellValue<TRow>) => ReactNode;
     /**
      * 셀(`<td>`) 자체를 커스텀 렌더 (React 확장). 반환한 엘리먼트가 그대로 `<td>`가 되므로
      * `colSpan` / `rowSpan`을 직접 지정할 수 있다. `render`보다 우선한다.
@@ -60,15 +142,26 @@ export interface STableColumn {
      * - 병합은 sticky 컬럼(인덱스 기준 offset 계산)과 함께 쓰지 않는 것을 전제로 한다.
      *   `rowSpan`은 행을 잘라 쓰는 가상 스크롤 / 내부 페이지네이션과 경계에서 어긋날 수 있다.
      */
-    renderCell?: (ctx: STableCellContext) => ReactNode;
+    renderCell?: (ctx: STableCellContext<TRow>) => ReactNode;
     /** 헤더 셀 커스텀 렌더 (React 확장) */
-    renderHeader?: (column: STableColumn, index: number) => ReactNode;
+    renderHeader?: (column: STableColumn<TRow>, index: number) => ReactNode;
     /** 본문 셀 커스텀 클래스. 함수를 주면 행마다 다른 클래스를 반환할 수 있다 */
-    tdClass?: string | ((row: SRow) => string | undefined);
+    tdClass?: string | ((row: TRow) => string | undefined);
     /** 헤더 셀 커스텀 클래스/스타일 (sd-table thClass/thStyle) */
     thClass?: string;
     thStyle?: CSSProperties;
 }
+/**
+ * `autoWidth` 스페이서 열은 값을 그리지 않으므로 `field` 를 생략할 수 있다.
+ * 그 밖의 열은 값 접근자가 있어야 한다.
+ */
+export type STableColumn<TRow extends SRow = SRow> = STableColumnBase<TRow> & ({
+    autoWidth: true;
+    field?: STableColumnField<TRow>;
+} | {
+    autoWidth?: false;
+    field: STableColumnField<TRow>;
+});
 export interface STablePagination {
     page: number;
     rowsPerPage: number;
@@ -78,13 +171,29 @@ export interface STableStickyColumn {
     left?: number;
     right?: number;
 }
+/** 정렬 상태 — 어느 열을 어느 방향으로 정렬했는가 */
+export interface STableSort {
+    /** 정렬 기준 컬럼의 `name` */
+    name: string;
+    dir: 'asc' | 'desc';
+}
+/** 2단 헤더의 상위 셀. columnNames는 visible 컬럼 기준으로 연속되어야 한다. */
+export interface STableHeaderGroup {
+    label?: ReactNode;
+    columnNames: string[];
+    rowSpan?: 1 | 2;
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+    style?: CSSProperties;
+    render?: () => ReactNode;
+}
 /** STable ref 명령형 API (sd-table @Method 대응) */
-export interface STableHandle {
+export interface STableHandle<TRow extends SRow = SRow> {
     /** 행 선택 여부 */
-    isRowSelected: (row: SRow) => boolean;
+    isRowSelected: (row: TRow) => boolean;
     /** 주어진 행들의 전체 선택 상태 (true/false/null=indeterminate) */
-    getIsAllChecked: (rows: SRow[]) => boolean | null;
-    /** 내부 페이지네이션 정보 (useInternalPagination 아니면 null) */
+    getIsAllChecked: (rows: TRow[]) => boolean | null;
+    /** 내부 페이지네이션 정보 (internalPagination 아니면 null) */
     getPaginationInfo: () => {
         startIndex: number;
         endIndex: number;
@@ -93,28 +202,119 @@ export interface STableHandle {
     } | null;
     /** 컬럼 sticky 스타일 (CSS 변수 + 고정폭) */
     getStickyStyle: (colIdx: number) => CSSProperties;
+    /**
+     * 본문의 세로 스크롤 컨테이너. 본문이 슬롯으로 대체됐거나 아직 안 그려졌으면 `null`.
+     *
+     * 스크롤 위치를 읽고 되돌리거나, 표 안에서 스크롤 여지를 재야 할 때 쓴다 —
+     * **DOM 을 뒤져 컨테이너를 찾지 않는다.** 내부 구조는 예고 없이 바뀐다.
+     *
+     * ⚠️ `virtualScroll` 에서 **위치를 픽셀로 저장했다 되돌리는 것은 미덥지 않다.** 다시 그릴 때
+     * 아직 안 그려진 행은 추정 높이로 잡히므로, 실측이 쌓이기 전의 같은 `scrollTop` 이 다른 행을
+     * 가리킨다. 그 경우엔 위치가 아니라 **보고 있던 행**을 기억해 두는 편이 맞다.
+     */
+    getScrollElement: () => HTMLDivElement | null;
+    /**
+     * 지금 본문 맨 위에 걸린 행의 인덱스 (`rows` 기준). 행이 없으면 `0`.
+     *
+     * **스크롤 위치를 저장할 때는 픽셀이 아니라 이 값을 저장한다** — `virtualScroll` 에서
+     * 픽셀은 좌표계가 실측으로 움직이는 값이라, 되돌릴 때 다른 행을 가리킨다.
+     */
+    getFirstVisibleRow: () => number;
+    /**
+     * 그 행이 본문 맨 위에 오도록 스크롤한다 (`rows` 기준 인덱스, 범위를 벗어나면 잘린다).
+     *
+     * `virtualScroll` 에서는 **실측이 정착할 때까지 그 행을 계속 다시 겨냥한다** — 옮기는
+     * 시점의 좌표는 아직 추정치라 한 번만 옮기면 몇 행씩 밀린다. 사용자가 직접 스크롤하면
+     * 겨냥을 놓는다.
+     *
+     * 페이지네이션을 쓰는 표에서는 **지금 페이지에 그려진 행만** 닿는다 — 다른 페이지의
+     * 행이라면 페이지를 먼저 옮긴다.
+     */
+    scrollToRow: (index: number) => void;
     /** 가상 스크롤 총 행 수 설정 */
     setRowCount: (count: number) => void;
     /** 단일 행 선택 토글 (sd-table updateRowSelect) — onSelectedChange 발생 */
-    updateRowSelect: (row: SRow) => void;
+    updateRowSelect: (row: TRow) => void;
     /** 주어진 행들 전체 선택/해제 (sd-table toggleSelectAll) — onSelectedChange 발생 */
-    toggleSelectAll: (checked: boolean, rows: SRow[]) => void;
+    toggleSelectAll: (checked: boolean, rows: TRow[]) => void;
 }
-export interface STableProps {
-    columns?: STableColumn[];
-    rows?: SRow[];
+export interface STableProps<TRow extends SRow = SRow> {
+    columns?: STableColumn<TRow>[];
+    /** 상위 그룹 헤더. 지정하면 기존 컬럼 헤더가 두 번째 행에 렌더링된다. */
+    headerGroups?: STableHeaderGroup[];
+    rows?: TRow[];
     /** 행 식별 필드 */
     rowKey?: string;
     /** 행 선택 체크박스 */
     selectable?: boolean;
-    selected?: SRow[];
-    onSelectedChange?: (rows: SRow[]) => void;
+    /**
+     * 행을 드래그해서 고른다. 기본 `false`.
+     *
+     * 고르는 수단만 다를 뿐 `selectable` 과 같은 선택이다 — `selected` · `onSelectedChange` ·
+     * `isRowSelectable` 을 그대로 쓴다. 체크박스 열은 생기지 않고, 대신 고른 구간이 배경색과
+     * 바깥 테두리로 표시된다.
+     *
+     * **`selectable` 과 함께 켜면 `selectable` 이 이긴다** — 체크박스가 있는 표에서 드래그까지
+     * 걸리면 글자를 긁으려던 손이 선택을 갈아치운다. 둘 다 필요해 보이면 체크박스 쪽만 남긴다.
+     *
+     * 누른 자리가 구간의 기준점이고, 끌어간 자리까지가 구간이다. **새로 끌면 이전 선택은 풀린다** —
+     * 기존 선택에 더하려면 `Ctrl`(macOS 는 `Cmd`)을 짚고 끈다. 잠긴 행(`isRowSelectable`)은
+     * 구간 안에 있어도 그냥 지나간다.
+     *
+     * **켜 두면 셀 안의 글자를 긁어 복사할 수 없다** — 끌기가 곧 선택이라 글자 선택과 같은 손짓을
+     * 두고 다툰다. 값을 복사해 가는 표에는 켜지 않는다. 셀 안의 버튼·입력은 그대로 눌린다.
+     */
+    dragSelectable?: boolean;
+    /**
+     * 드래그 선택에서 **행을 오른쪽 클릭했을 때** 커서 자리에 뜨는 메뉴의 항목.
+     * 주지 않거나 비면 메뉴가 뜨지 않고 브라우저 기본 메뉴가 나온다.
+     *
+     * **`dragSelectable` 에서만 동작한다** — 체크박스 모드에서는 무시된다.
+     *
+     * 고르지 않은 행에서 누르면 **그 행만 고른 뒤** 열린다. 메뉴가 다룰 대상과 화면에 칠해진
+     * 것이 어긋나지 않게 하기 위함이다. 잠긴 행(`isRowSelectable`) 위에서는 열리지 않는다 —
+     * 고를 수 없는 행을 대상으로 삼을 수 없기 때문이다.
+     */
+    contextMenuItems?: STableContextMenuItem[];
+    /**
+     * 메뉴 항목을 골랐을 때. 고른 항목의 `value` 와 **그 메뉴가 다루는 행들**이 함께 온다.
+     *
+     * 행 목록은 메뉴가 열린 시점에 확정되므로 `selected` 를 따로 읽지 않아도 된다 — 오른쪽
+     * 클릭이 선택을 바꾸는 경우(고르지 않은 행)에도 바뀐 뒤의 행이 온다.
+     */
+    onContextMenuItemClick?: (value: string | number, rows: TRow[]) => void;
+    /**
+     * 이 행을 고를 수 있는가. 주지 않으면 모든 행을 고를 수 있다.
+     *
+     * 고를 수 없는 행은 체크박스가 잠기고, **전체 선택·Shift 구간 선택의 셈에서도 빠진다** —
+     * 잠긴 행이 셈에 남으면 "전부 선택됨"에 닿지 못해 헤더 체크박스가 해제 방향으로 가지 못한다.
+     *
+     * 목록에서 지워 버리는 것과 다르다. 실패 0건인 차수처럼 **자리는 보여야 하지만 대상이 될 수는
+     * 없는 행**에 쓴다. 아예 대상이 아니라면 `rows` 에서 거르는 편이 낫다.
+     *
+     * 잠금은 그리기 시점의 판정일 뿐이라, 이미 `selected` 에 든 행이 나중에 잠겨도 DS 가 빼지
+     * 않는다(제어 상태를 말없이 바꾸지 않는다). 다만 헤더의 전체 해제로는 걷어낼 수 있다.
+     */
+    isRowSelectable?: (row: TRow) => boolean;
+    selected?: TRow[];
+    onSelectedChange?: (rows: TRow[]) => void;
+    /**
+     * 정렬 상태 (controlled). `null`·미지정이면 정렬 없음.
+     *
+     * 컴포넌트는 정렬 상태를 갖지 않는다 — 서버 정렬이면 이 값이 곧 조회 조건이고,
+     * 뒤로가기·새로고침·링크 공유로 복원돼야 하므로 진실은 URL·store 쪽에 있어야 한다.
+     * 행을 실제로 정렬하는 것도 소비 앱 몫이다 (`STable` 은 받은 순서대로 그린다).
+     */
+    sort?: STableSort | null;
+    /**
+     * 정렬 헤더 클릭 (`asc → desc → 해제` 3단). 해제되면 `null` 이 온다.
+     * 다중 정렬은 1차 안에서 지원하지 않는다.
+     */
+    onSortChange?: (sort: STableSort | null) => void;
     /** 컬럼 너비 조절 */
     resizable?: boolean;
     width?: string;
     height?: string;
-    /** @deprecated 헤더는 항상 세로 스크롤에서 제외되어 고정됩니다 (body만 세로 스크롤) */
-    stickyHeader?: boolean;
     /** 고정할 좌/우 컬럼 수 */
     stickyColumn?: STableStickyColumn;
     /** border-radius 제어 */
@@ -129,30 +329,63 @@ export interface STableProps {
      * 없어, 그대로 두면 페이지네이션만 테두리를 갖고 1px 어긋난다.
      */
     bordered?: boolean;
-    noDataLabel?: string;
+    emptyLabel?: string;
     /**
      * 데이터가 없을 때 body 영역 전체를 대체하는 슬롯.
-     * 지정하면 `noDataLabel` 대신 이 콘텐츠가 헤더 아래 영역을 채우며, 버튼 등 인터랙션도 동작한다.
+     * 지정하면 `emptyLabel` 대신 이 콘텐츠가 헤더 아래 영역을 채우며, 버튼 등 인터랙션도 동작한다.
+     */
+    emptySlot?: ReactNode;
+    loading?: boolean;
+    /**
+     * 행 높이를 좁게 (세로 여백만 줄인다 — 좌우 패딩은 그대로).
+     *
+     * **시작 밀도이자 밀도 토글의 스위치다.** 켜면 하단 바 우측에 `좁게 보기` · `넓게 보기` 토글이
+     * 붙는다 — 페이지네이션이 없으면 이 바를 토글만 담아 그린다.
+     *
+     * 누른 뒤의 밀도는 테이블이 내부 상태로 들고 가므로 `onDenseChange` 를 받지 않아도 토글은
+     * 동작하고, 넓게 본 뒤에도 토글은 그대로 남는다(붙일지는 이 prop 이 정한다). 이 prop 값이
+     * 바뀌면 내부 밀도도 그 값으로 맞춰진다.
      */
-    noDataSlot?: ReactNode;
-    isLoading?: boolean;
     dense?: boolean;
-    /** true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 */
-    noHover?: boolean;
+    /**
+     * 밀도 변경 (하단 바의 밀도 토글을 눌렀을 때). 표시는 테이블이 알아서 바꾸므로 받지 않아도 되고,
+     * 사용자가 고른 밀도를 다음 방문까지 기억해 두려는(로컬 저장 등) 페이지만 받으면 된다.
+     */
+    onDenseChange?: (dense: boolean) => void;
+    /** 행에 마우스를 올렸을 때 hover 배경(grey_05)을 표시할지. 기본 `true` — `false` 면 표시하지 않는다 */
+    hoverable?: boolean;
     /** 페이지네이션 (있으면 하단 표시) */
     pagination?: STablePagination;
     onPageChange?: (page: number) => void;
     /** 테이블 내부에서 페이지네이션을 직접 관리 (rows를 내부 슬라이싱) */
-    useInternalPagination?: boolean;
+    internalPagination?: boolean;
     /** 페이지당 행 수 셀렉트 표시 */
-    useRowsPerPageSelect?: boolean;
+    showRowsPerPageSelect?: boolean;
     rowsPerPageOption?: SSelectOption[];
     onRowsPerPageChange?: (perPage: number) => void;
     /** 가상 스크롤 */
-    useVirtualScroll?: boolean;
+    virtualScroll?: boolean;
+    /**
+     * 행 높이의 **출발점**(px). 미지정이면 밀도에 따라 44 / 32.
+     *
+     * 행마다 높이가 달라도 된다 — 화면에 나온 행은 실제 높이를 재서 덮으므로, 이 값은
+     * **아직 안 그려진 행의 추정치**이자 행의 최소 높이일 뿐이다. 실측이 쌓일수록 뒤쪽
+     * 추정도 그 평균으로 수렴한다.
+     *
+     * 그래서 높이가 제각각인 표에서 "가장 흔한 높이"를 넣어 두면 충분하다. 값이 실제와
+     * 멀수록 아직 안 그려진 구간의 스크롤바 길이만 덜 정확할 뿐, 그리는 위치는 어긋나지 않는다.
+     */
     rowHeight?: number;
     virtualBuffer?: number;
     virtualEndThreshold?: number;
+    /**
+     * 본문이 스크롤될 때. **실제 스크롤에만 울린다** — 행 수·컬럼 폭·로딩이 바뀌어
+     * 내부에서 위치를 다시 잴 때는 오지 않는다.
+     *
+     * `onVirtualUpdate` 는 그리는 창이 바뀔 때만 오므로 그 사이 스크롤을 알 수 없다.
+     * 스크롤 위치를 읽어 두었다 되돌리는 것처럼 **위치 자체가 필요하면** 이쪽을 쓴다.
+     */
+    onScroll?: (event: ReactUIEvent<HTMLDivElement>) => void;
     onVirtualUpdate?: (range: {
         from: number;
         to: number;
@@ -166,12 +399,25 @@ export interface STableProps {
     /** 테이블 식별자 (없으면 자동 생성) */
     tableId?: string;
     /** 행 클릭 */
-    onRowClick?: (row: SRow) => void;
+    onRowClick?: (row: TRow) => void;
+    /**
+     * 행 더블클릭. 목록에서 상세를 여는 것처럼 **한 번 누르는 것과 다른 일**을 걸 때 쓴다.
+     *
+     * 더블클릭도 클릭 두 번이라 `onRowClick` 과 함께 주면 **`onRowClick` 이 두 번 먼저 울린다** —
+     * 둘을 함께 쓰려면 `onRowClick` 은 두 번 울려도 결과가 같은 일(행 강조 등)이어야 한다.
+     *
+     * 선택 체크박스 열과 셀 안의 버튼·링크·입력 위에서 한 더블클릭은 행 더블클릭이 아니다 —
+     * 체크박스를 빠르게 두 번 누르거나 입력의 글자를 더블클릭으로 고르다 상세가 열리지 않게 한다.
+     */
+    onRowDoubleClick?: (row: TRow) => void;
     className?: string;
     style?: CSSProperties;
 }
 /**
- * STable — sd-table 포팅. 컬럼/행 + 선택 + sticky 헤더/컬럼 + 리사이즈 +
- * 내부 페이지네이션 + rows-per-page + 가상 스크롤 + 로딩 + dense.
+ * 행 타입을 받는 제네릭 컴포넌트로 내보낸다 — `forwardRef` 는 타입 파라미터를 지워 버리므로
+ * 바깥 시그니처만 다시 씌운다(SDraggableList 와 같은 방식). 구현 안쪽은 `SRow` 로 다룬다.
  */
-export declare const STable: import("react").ForwardRefExoticComponent<STableProps & import("react").RefAttributes<STableHandle>>;
+export declare const STable: <TRow extends SRow = SRow>(props: STableProps<TRow> & {
+    ref?: ForwardedRef<STableHandle<TRow>>;
+}) => ReactElement | null;
+export {};