sellmate-design-system-react 9.0.0-beta.50 → 9.0.0-beta.52

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

@@ -1,4 +1,4 @@
-import { type CSSProperties, type ReactNode } from 'react';
+import { type CSSProperties, type UIEvent as ReactUIEvent, type ReactNode } from 'react';
 import { type SSelectOption } from '../SSelect';
 export type SRow = Record<string, any>;
 /** `STableColumn.renderCell`에 전달되는 컨텍스트 */
@@ -172,6 +172,35 @@ 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 발생 */
@@ -188,6 +217,19 @@ export interface STableProps {
     rowKey?: string;
     /** 행 선택 체크박스 */
     selectable?: boolean;
+    /**
+     * 이 행을 고를 수 있는가. 주지 않으면 모든 행을 고를 수 있다.
+     *
+     * 고를 수 없는 행은 체크박스가 잠기고, **전체 선택·Shift 구간 선택의 셈에서도 빠진다** —
+     * 잠긴 행이 셈에 남으면 "전부 선택됨"에 닿지 못해 헤더 체크박스가 해제 방향으로 가지 못한다.
+     *
+     * 목록에서 지워 버리는 것과 다르다. 실패 0건인 차수처럼 **자리는 보여야 하지만 대상이 될 수는
+     * 없는 행**에 쓴다. 아예 대상이 아니라면 `rows` 에서 거르는 편이 낫다.
+     *
+     * 잠금은 그리기 시점의 판정일 뿐이라, 이미 `selected` 에 든 행이 나중에 잠겨도 DS 가 빼지
+     * 않는다(제어 상태를 말없이 바꾸지 않는다). 다만 헤더의 전체 해제로는 걷어낼 수 있다.
+     */
+    isRowSelectable?: (row: SRow) => boolean;
     selected?: SRow[];
     onSelectedChange?: (rows: SRow[]) => void;
     /**
@@ -257,9 +299,27 @@ export interface STableProps {
     onRowsPerPageChange?: (perPage: number) => void;
     /** 가상 스크롤 */
     virtualScroll?: boolean;
+    /**
+     * 행 높이의 **출발점**(px). 미지정이면 밀도에 따라 44 / 32.
+     *
+     * 행마다 높이가 달라도 된다 — 화면에 나온 행은 실제 높이를 재서 덮으므로, 이 값은
+     * **아직 안 그려진 행의 추정치**이자 행의 최소 높이일 뿐이다. 실측이 쌓일수록 뒤쪽
+     * 추정도 그 평균으로 수렴한다.
+     *
+     * 그래서 높이가 제각각인 표에서 "가장 흔한 높이"를 넣어 두면 충분하다. 값이 실제와
+     * 멀수록 아직 안 그려진 구간의 스크롤바 길이만 덜 정확할 뿐, 그리는 위치는 어긋나지 않는다.
+     */
     rowHeight?: number;
     virtualBuffer?: number;
     virtualEndThreshold?: number;
+    /**
+     * 본문이 스크롤될 때. **실제 스크롤에만 울린다** — 행 수·컬럼 폭·로딩이 바뀌어
+     * 내부에서 위치를 다시 잴 때는 오지 않는다.
+     *
+     * `onVirtualUpdate` 는 그리는 창이 바뀔 때만 오므로 그 사이 스크롤을 알 수 없다.
+     * 스크롤 위치를 읽어 두었다 되돌리는 것처럼 **위치 자체가 필요하면** 이쪽을 쓴다.
+     */
+    onScroll?: (event: ReactUIEvent<HTMLDivElement>) => void;
     onVirtualUpdate?: (range: {
         from: number;
         to: number;

package/dist/components/STableBar/README.md

@@ -8,6 +8,7 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `title?` | `ReactNode` | — | 건수 앞에 서는 제목 슬롯. 이 바가 무엇의 목록인지 말한다. 문자열을 주면 바의 기본 타이포로 그린다. 다른 모양이 필요하면 요소를 통째로 넘긴다 — 슬롯이라 안에 무엇이 오든 자리만 잡아 준다. |
 | `total?` | `number` | — | 전체 건수. 지정하면 "총 N 건" 을 표시한다 (천단위 구분 자동) |
 | `selected?` | `number` | — | 선택 건수. 지정하면 "N건 선택" 을 표시한다 |
 | `actions?` | `ReactNode` | — | 구분선 오른쪽 좌측 액션 영역 |

package/dist/components/STableBar/STableBar.d.ts

@@ -1,5 +1,12 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
-export interface STableBarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+export interface STableBarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {
+    /**
+     * 건수 앞에 서는 제목 슬롯. 이 바가 무엇의 목록인지 말한다.
+     *
+     * 문자열을 주면 바의 기본 타이포로 그린다. 다른 모양이 필요하면 요소를 통째로 넘긴다 —
+     * 슬롯이라 안에 무엇이 오든 자리만 잡아 준다.
+     */
+    title?: ReactNode;
     /** 전체 건수. 지정하면 "총 N 건" 을 표시한다 (천단위 구분 자동) */
     total?: number;
     /** 선택 건수. 지정하면 "N건 선택" 을 표시한다 */