sellmate-design-system-react 9.0.0-beta.3 → 9.0.0-beta.30

package/dist/components/SSystemActionButton/README.md

@@ -0,0 +1,134 @@
+# SSystemActionButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSystemActionButtonAccount
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'account'` | — | 계정 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option?` | `never` | — | 아이콘이 `user` 로 고정이라 받을 것이 없다 |
+
+### SSystemActionButtonBase
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SSystemActionButtonColor` | — | 색상(놓이는 표면). light = 흰 면, dark = 오션블루 면, darker = 네이비 면. 기본 `'light'` |
+| `disabled?` | `boolean` | — | 비활성 여부. 기본 `false` |
+
+### SSystemActionButtonSelect
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'select'` | — | 화살표만 붙는 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option` | `SSystemActionButtonIconOption` | — | 선행 아이콘 |
+
+### SSystemActionButtonStatus
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'status'` | — | 라벨 자리에 상태 태그가 들어가는 행 |
+| `label?` | `never` | — | 태그가 라벨 자리를 차지하므로 받지 않는다 |
+| `option?` | `SSystemActionButtonStatusOption` | — | 상태 태그 |
+
+### SSystemActionButtonText
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'switch' \| 'subSelect'` | — | 우측에 문구가 붙는 행. switch = 보조 조작 문구, subSelect = 지금 선택된 값 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option` | `SSystemActionButtonTextOption` | — | 선행 아이콘 + 우측 액션 텍스트 |
+
+## Types
+
+### SSystemActionButtonColor
+
+```ts
+export type SSystemActionButtonColor = (typeof SYSTEM_ACTION_BUTTON_COLORS)[number];
+```
+
+### SSystemActionButtonIconOption
+
+```ts
+/** 선행 아이콘만 받는 타입(`select`)의 option */
+export interface SSystemActionButtonIconOption {
+  /** 선행 아이콘명 */
+  icon: SIconName;
+}
+```
+
+### SSystemActionButtonStatusOption
+
+```ts
+/** `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 */
+export interface SSystemActionButtonStatusOption {
+  /** 상태 태그 색 */
+  color?: STagColor;
+  /** 상태 태그 텍스트 */
+  label?: string;
+}
+```
+
+### SSystemActionButtonTextOption
+
+```ts
+/** 우측 액션 텍스트까지 받는 타입(`switch` · `subSelect`)의 option */
+export interface SSystemActionButtonTextOption extends SSystemActionButtonIconOption {
+  /** 우측 액션 텍스트 */
+  text?: string;
+}
+```
+
+### SYSTEM_ACTION_BUTTON_COLORS
+
+```ts
+/**
+ * SSystemActionButton 설정.
+ *
+ * 토큰은 GNB system 패널 한 벌(`--cmp-gnb-system-*`)을 그대로 쓴다.
+ *   행 공통(높이·라운드·아이콘 프레임·라벨)  → --cmp-gnb-system-item-*
+ *   색(color 축) light / dark / darker        → --cmp-gnb-system-item-<color>-*
+ *   우측 액션(패딩·간격·아이콘·텍스트색)      → --cmp-gnb-system-actionButton-*
+ *
+ * 타이포그래피는 CSS 변수가 아니라 `.typo-*` 프리셋으로 나온다.
+ *   item.label              → typo-body-sm-semibold  (12/600/20)
+ *   actionButton.switch     → typo-field-sm-default   (12/400/20)
+ *   actionButton.selectData → typo-control-xs-medium  (12/500/20)
+ */
+
+/** 색상(표면). light = 흰 면, dark = 오션블루 면, darker = 네이비 면 */
+export const SYSTEM_ACTION_BUTTON_COLORS = ['light', 'dark', 'darker'] as const;
+```
+
+## Dependencies
+
+### Used by
+
+ - [SGnbSystem](../SGnbSystem)
+
+### Depends on
+
+- [SIcon](../SIcon)
+- [STag](../STag)
+
+### Graph
+
+```mermaid
+graph TD;
+  SSystemActionButton --> SIcon
+  SSystemActionButton --> STag
+  SGnbSystem --> SSystemActionButton
+  style SSystemActionButton fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SSystemActionButton/SSystemActionButton.d.ts

@@ -0,0 +1,79 @@
+import { type ButtonHTMLAttributes } from 'react';
+import { type SIconName } from '../SIcon';
+import { type STagColor } from '../STag';
+import { type SSystemActionButtonColor } from './systemActionButton.config';
+/** 선행 아이콘만 받는 타입(`select`)의 option */
+export interface SSystemActionButtonIconOption {
+    /** 선행 아이콘명 */
+    icon: SIconName;
+}
+/** 우측 액션 텍스트까지 받는 타입(`switch` · `subSelect`)의 option */
+export interface SSystemActionButtonTextOption extends SSystemActionButtonIconOption {
+    /** 우측 액션 텍스트 */
+    text?: string;
+}
+/** `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 */
+export interface SSystemActionButtonStatusOption {
+    /** 상태 태그 색 */
+    color?: STagColor;
+    /** 상태 태그 텍스트 */
+    label?: string;
+}
+/** 모든 타입이 공통으로 받는 props */
+export interface SSystemActionButtonBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'type' | 'children'> {
+    /** 색상(놓이는 표면). light = 흰 면, dark = 오션블루 면, darker = 네이비 면. 기본 `'light'` */
+    color?: SSystemActionButtonColor;
+    /** 비활성 여부. 기본 `false` */
+    disabled?: boolean;
+}
+/** 계정 행 — 아이콘이 `user` 로 고정이고 우측 액션이 없다 */
+export interface SSystemActionButtonAccountProps extends SSystemActionButtonBaseProps {
+    /** 계정 행 */
+    type: 'account';
+    /** 라벨 텍스트 */
+    label?: string;
+    /** 아이콘이 `user` 로 고정이라 받을 것이 없다 */
+    option?: never;
+}
+/** 화살표만 붙는 행 — 눌러 들어간다는 뜻 */
+export interface SSystemActionButtonSelectProps extends SSystemActionButtonBaseProps {
+    /** 화살표만 붙는 행 */
+    type: 'select';
+    /** 라벨 텍스트 */
+    label?: string;
+    /** 선행 아이콘 */
+    option: SSystemActionButtonIconOption;
+}
+/** 우측에 문구가 붙는 행 — `switch` 는 보조 조작 문구, `subSelect` 는 지금 선택된 값 */
+export interface SSystemActionButtonTextProps extends SSystemActionButtonBaseProps {
+    /** 우측에 문구가 붙는 행. switch = 보조 조작 문구, subSelect = 지금 선택된 값 */
+    type: 'switch' | 'subSelect';
+    /** 라벨 텍스트 */
+    label?: string;
+    /** 선행 아이콘 + 우측 액션 텍스트 */
+    option: SSystemActionButtonTextOption;
+}
+/** 라벨 자리에 상태 태그가 들어가는 행 */
+export interface SSystemActionButtonStatusProps extends SSystemActionButtonBaseProps {
+    /** 라벨 자리에 상태 태그가 들어가는 행 */
+    type: 'status';
+    /** 태그가 라벨 자리를 차지하므로 받지 않는다 */
+    label?: never;
+    /** 상태 태그 */
+    option?: SSystemActionButtonStatusOption;
+}
+/** `type` 으로 갈리는 판별 유니온. 타입에 맞지 않는 option 은 컴파일 단계에서 막힌다. */
+export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystemActionButtonSelectProps | SSystemActionButtonTextProps | SSystemActionButtonStatusProps;
+/**
+ * SSystemActionButton — GNB system 패널의 한 줄짜리 액션 버튼.
+ *
+ * 아이콘 프레임 + 라벨 + 우측 액션이 한 행에 붙고, 행 전체가 버튼이다. 무엇이 그려지는지는
+ * `type` 이 정하고(`account` `switch` `select` `subSelect` `status`), 타입마다 다른 값만
+ * `option` 으로 받는다. 선행 아이콘은 항상 있다 — `account` 는 `user` 고정, `status` 는 태그가
+ * 자리를 차지해 아이콘이 없고, 나머지는 `option.icon` 이 필수다.
+ *
+ * hover 하면 표면색이 한 단계 바뀌고, 어두운 색에서는 아이콘 프레임이 흰색으로 떠오른다.
+ * 상태는 default·hover 둘뿐이다 — 토큰에 selected 가 없다.
+ * 토큰은 `--cmp-gnb-system-item-*` · `--cmp-gnb-system-actionButton-*`.
+ */
+export declare const SSystemActionButton: import("react").ForwardRefExoticComponent<SSystemActionButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/SSystemActionButton/index.d.ts

@@ -0,0 +1,2 @@
+export { SSystemActionButton, type SSystemActionButtonProps, type SSystemActionButtonBaseProps, type SSystemActionButtonAccountProps, type SSystemActionButtonSelectProps, type SSystemActionButtonTextProps, type SSystemActionButtonStatusProps, type SSystemActionButtonIconOption, type SSystemActionButtonTextOption, type SSystemActionButtonStatusOption, } from './SSystemActionButton';
+export { SYSTEM_ACTION_BUTTON_COLORS, SYSTEM_ACTION_BUTTON_TYPES, SYSTEM_ACTION_BUTTON_COLOR_CONFIG, SYSTEM_ACTION_BUTTON_TYPE_CONFIG, SYSTEM_ACTION_BUTTON_LAYOUT, type SSystemActionButtonColor, type SSystemActionButtonType, } from './systemActionButton.config';

package/dist/components/SSystemActionButton/systemActionButton.config.d.ts

@@ -0,0 +1,87 @@
+import type { SIconName } from '../SIcon';
+/**
+ * SSystemActionButton 설정.
+ *
+ * 토큰은 GNB system 패널 한 벌(`--cmp-gnb-system-*`)을 그대로 쓴다.
+ *   행 공통(높이·라운드·아이콘 프레임·라벨)  → --cmp-gnb-system-item-*
+ *   색(color 축) light / dark / darker        → --cmp-gnb-system-item-<color>-*
+ *   우측 액션(패딩·간격·아이콘·텍스트색)      → --cmp-gnb-system-actionButton-*
+ *
+ * 타이포그래피는 CSS 변수가 아니라 `.typo-*` 프리셋으로 나온다.
+ *   item.label              → typo-body-sm-semibold  (12/600/20)
+ *   actionButton.switch     → typo-field-sm-default   (12/400/20)
+ *   actionButton.selectData → typo-control-xs-medium  (12/500/20)
+ */
+/** 색상(표면). light = 흰 면, dark = 오션블루 면, darker = 네이비 면 */
+export declare const SYSTEM_ACTION_BUTTON_COLORS: readonly ["light", "dark", "darker"];
+export type SSystemActionButtonColor = (typeof SYSTEM_ACTION_BUTTON_COLORS)[number];
+/**
+ * 행 구성.
+ * - `account` — 계정 행. 아이콘이 `user` 로 고정이고 우측 액션이 없다
+ * - `switch` — 보조 조작 문구 + 새로고침 아이콘
+ * - `select` — 화살표만. 눌러 들어간다는 뜻
+ * - `subSelect` — 지금 선택돼 있는 값 + 화살표
+ * - `status` — 라벨 자리에 상태 태그가 들어가고 화살표가 붙는다
+ */
+export declare const SYSTEM_ACTION_BUTTON_TYPES: readonly ["account", "switch", "select", "subSelect", "status"];
+export type SSystemActionButtonType = (typeof SYSTEM_ACTION_BUTTON_TYPES)[number];
+/** 우측 액션 텍스트의 색·타이포가 어느 토큰 그룹을 쓰는지 (토큰의 하위 그룹명과 같다) */
+export type SystemActionButtonActionTextToken = 'switch' | 'selectData';
+export interface SystemActionButtonColorTokens {
+    /** 행 배경 (기본) */
+    bg: string;
+    /** 행 배경 (hover·selected) */
+    bgHover: string;
+    /** 아이콘 프레임 배경 (기본) */
+    iconBg: string;
+    /** 아이콘 프레임 배경 (hover·selected) */
+    iconBgHover: string;
+    /** 아이콘 글리프색 (기본) */
+    iconGlyph: string;
+    /** 아이콘 글리프색 (hover·selected) */
+    iconGlyphHover: string;
+    /** 라벨 텍스트색 */
+    text: string;
+    /** 우측 액션 텍스트색 (토큰 그룹별) */
+    actionText: Record<SystemActionButtonActionTextToken, string>;
+    /** 우측 액션 아이콘색 */
+    actionIcon: string;
+}
+export declare const SYSTEM_ACTION_BUTTON_COLOR_CONFIG: Record<SSystemActionButtonColor, SystemActionButtonColorTokens>;
+export interface SystemActionButtonTypeSpec {
+    /** 선행 아이콘 고정값. 있으면 `option.icon` 을 받지 않는다 */
+    fixedIcon?: SIconName;
+    /** 우측 액션 텍스트의 색·타이포. 없으면 텍스트를 그리지 않는다 */
+    actionText?: {
+        token: SystemActionButtonActionTextToken;
+        typo: string;
+    };
+    /** 우측 액션 아이콘. 타입이 정하므로 밖에서 바꾸지 않는다 */
+    actionIcon?: {
+        name: SIconName;
+        size: string;
+    };
+}
+/** 타입이 정하는 고정 구성 — 무엇이 그려지는가 */
+export declare const SYSTEM_ACTION_BUTTON_TYPE_CONFIG: Record<SSystemActionButtonType, SystemActionButtonTypeSpec>;
+/** 치수 — 전부 토큰 참조 */
+export declare const SYSTEM_ACTION_BUTTON_LAYOUT: {
+    /** 행 높이 */
+    readonly height: string;
+    /** 행 라운드 */
+    readonly radius: string;
+    /** 아이콘 프레임 한 변 */
+    readonly iconFrame: string;
+    /** 아이콘 글리프 크기 */
+    readonly iconGlyph: string;
+    /** 아이콘 프레임 라운드 */
+    readonly iconRadius: string;
+    /** 아이콘 프레임 ↔ 라벨 간격 */
+    readonly iconLabelGap: string;
+    /** 좌측 여백 */
+    readonly paddingLeft: string;
+    /** 우측 여백 */
+    readonly paddingRight: string;
+    /** 액션 텍스트 ↔ 액션 아이콘 간격 */
+    readonly actionGap: string;
+};

package/dist/components/STable/README.md

@@ -9,20 +9,23 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `columns?` | `STableColumn[]` | `[]` |  |
+| `headerGroups?` | `STableHeaderGroup[]` | — | 상위 그룹 헤더. 지정하면 기존 컬럼 헤더가 두 번째 행에 렌더링된다. |
 | `rows?` | `SRow[]` | `[]` |  |
 | `rowKey?` | `string` | `'id'` | 행 식별 필드 |
 | `selectable?` | `boolean` | `false` | 행 선택 체크박스 |
 | `selected?` | `SRow[]` | `[]` |  |
+| `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` |  |
+| `dense?` | `boolean` | `false` | 행 높이를 좁게 (세로 여백만 줄인다 — 좌우 패딩은 그대로). **시작 밀도이자 밀도 토글의 스위치다.** 켜면 하단 바 우측에 `좁게 보기` · `넓게 보기` 토글이 붙는다 — 페이지네이션이 없으면 이 바를 토글만 담아 그린다. 누른 뒤의 밀도는 테이블이 내부 상태로 들고 가므로 `onDenseChange` 를 받지 않아도 토글은 동작하고, 넓게 본 뒤에도 토글은 그대로 남는다(붙일지는 이 prop 이 정한다). 이 prop 값이 바뀌면 내부 밀도도 그 값으로 맞춰진다. |
 | `noHover?` | `boolean` | `false` | true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 |
 | `pagination?` | `STablePagination` | — | 페이지네이션 (있으면 하단 표시) |
 | `useInternalPagination?` | `boolean` | `false` | 테이블 내부에서 페이지네이션을 직접 관리 (rows를 내부 슬라이싱) |
@@ -41,6 +44,8 @@
 | Event | Type | Description |
 |-------|------|-------------|
 | `onSelectedChange` | `(rows: SRow[]) => void` |  |
+| `onSortChange` | `(sort: STableSort \| null) => void` | 정렬 헤더 클릭 (`asc → desc → 해제` 3단). 해제되면 `null` 이 온다. 다중 정렬은 1차 안에서 지원하지 않는다. |
+| `onDenseChange` | `(dense: boolean) => void` | 밀도 변경 (하단 바의 밀도 토글을 눌렀을 때). 표시는 테이블이 알아서 바꾸므로 받지 않아도 되고, 사용자가 고른 밀도를 다음 방문까지 기억해 두려는(로컬 저장 등) 페이지만 받으면 된다. |
 | `onPageChange` | `(page: number) => void` |  |
 | `onRowsPerPageChange` | `(perPage: number) => void` |  |
 | `onVirtualUpdate` | `(range: { from: number; to: number }) => void` |  |
@@ -59,15 +64,92 @@
 | `updateRowSelect` | `(row: SRow) => void` | 단일 행 선택 토글 (sd-table updateRowSelect) — onSelectedChange 발생 |
 | `toggleSelectAll` | `(checked: boolean, rows: SRow[]) => void` | 주어진 행들 전체 선택/해제 (sd-table toggleSelectAll) — onSelectedChange 발생 |
 
+## Types
+
+### STableColumn
+
+```ts
+/**
+ * `autoWidth` 스페이서 열은 값을 그리지 않으므로 `field` 를 생략할 수 있다.
+ * 그 밖의 열은 값 접근자가 있어야 한다.
+ */
+export type STableColumn = STableColumnBase &
+  (
+    { autoWidth: true; field?: STableColumnField } | { autoWidth?: false; field: STableColumnField }
+  );
+```
+
+### 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;
+}
+```
+
+### SRow
+
+```ts
+export type SRow = Record<string, any>;
+```
+
+### 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 = string | ((row: SRow) => any);
+```
+
 ## Dependencies
 
 ### Depends on
 
 - [SCheckbox](../SCheckbox)
 - [SCircleProgress](../SCircleProgress)
+- [SDivider](../SDivider)
+- [SGhostButton](../SGhostButton)
 - [SIcon](../SIcon)
 - [SPagination](../SPagination)
 - [SSelect](../SSelect)
+- [STextLink](../STextLink)
+- [STooltip](../STooltip)
 
 ### Graph
 
@@ -75,8 +157,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,6 +1,4 @@
 import { type CSSProperties, type ReactNode } from 'react';
-import { type SColor } from '../../lib/color';
-import { type SIconName } from '../SIcon';
 import { type SSelectOption } from '../SSelect';
 export type SRow = Record<string, any>;
 /** `STableColumn.renderCell`에 전달되는 컨텍스트 */
@@ -20,24 +18,88 @@ export interface STableCellContext {
     /** STable이 이 셀에 적용하려던 스타일 (패딩·정렬·폭·sticky offset 포함) */
     style: CSSProperties;
 }
-export interface STableColumn {
+/** 값 접근: 필드명 또는 접근 함수 */
+export type STableColumnField = string | ((row: SRow) => any);
+interface STableColumnBase {
     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;
     visible?: boolean;
-    icon?: SIconName;
-    /** 헤더 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
-    iconColor?: SColor;
+    /**
+     * 헤더 라벨 뒤 도움말 툴팁 (각 항목이 한 줄). `SKeyValueTable` 의 `field.helpText` 와 같은 역할 —
+     * 라벨만으로 뜻이 통하지 않는 컬럼의 산출 기준·단위를 설명한다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    helpText?: string[];
+    /**
+     * 라벨 뒤 필수 표시(`*`). `SKeyValueTable` 의 `field.required` 와 같은 규칙 —
+     * 그 열의 값을 반드시 채워야 하는 입력 열에만 쓴다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    required?: boolean;
+    /**
+     * 셀 값을 직접 고칠 수 있는 열. 라벨 뒤에 `pageEdit` 표식이 붙는다.
+     *
+     * **표식일 뿐 버튼이 아니다** — 실제로 고치는 UI 는 셀(`render`)이 그린다. 표식만 켜 두면
+     * 고칠 수 있다고 해 놓고 고칠 방법이 없는 열이 된다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    editable?: boolean;
+    /**
+     * 셀을 눌러 다른 화면으로 넘어가는 열. 라벨 뒤에 `pageMove` 표식이 붙는다.
+     *
+     * **표식일 뿐 버튼이 아니다** — 넘어가는 것은 셀(`render`)의 링크·클릭이 한다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    navigable?: boolean;
+    /**
+     * 정렬 가능한 열인지. 켜면 헤더 라벨 뒤에 정렬 버튼이 붙는다 — 누르는 곳은 그 버튼뿐이고
+     * 헤더 셀 전체가 클릭 영역이 되지는 않는다.
+     *
+     * 정렬 상태는 컴포넌트가 갖지 않는다 — `STable` 의 `sort` · `onSortChange` 로 주고받는다.
+     * `renderHeader` 로 헤더를 통째로 교체하면 버튼도 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    sortable?: boolean;
+    /**
+     * 셀에 무엇이 들어가는지. 좌우 여백이 여기서 갈린다 — 기본은 `text`(넓게).
+     *
+     * 자기 폭을 가진 컨트롤(`SInput`·`SNumberInput`·`SSelect` 등)이 들어가는 열은 `control` 로 준다.
+     * 텍스트와 같은 넓은 여백을 두면 컨트롤이 쓸 폭이 그만큼 줄어 같은 열 폭에서도 좁아 보인다.
+     *
+     * `SKeyValueTable` 은 `field.type` 으로 이 판정을 스스로 하지만, `STable` 의 셀은 소비 앱이 넘긴
+     * 임의의 `render` 결과라 컴포넌트가 알 수 없다. 그래서 열 단위로 받는다.
+     */
+    contentType?: 'text' | 'control';
     /** 셀 커스텀 렌더 (React 확장) — `<td>` 안쪽 내용만 교체한다 */
     render?: (row: SRow, value: any) => ReactNode;
     /**
@@ -59,6 +121,17 @@ export interface STableColumn {
     thClass?: string;
     thStyle?: CSSProperties;
 }
+/**
+ * `autoWidth` 스페이서 열은 값을 그리지 않으므로 `field` 를 생략할 수 있다.
+ * 그 밖의 열은 값 접근자가 있어야 한다.
+ */
+export type STableColumn = STableColumnBase & ({
+    autoWidth: true;
+    field?: STableColumnField;
+} | {
+    autoWidth?: false;
+    field: STableColumnField;
+});
 export interface STablePagination {
     page: number;
     rowsPerPage: number;
@@ -68,6 +141,22 @@ 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 {
     /** 행 선택 여부 */
@@ -92,6 +181,8 @@ export interface STableHandle {
 }
 export interface STableProps {
     columns?: STableColumn[];
+    /** 상위 그룹 헤더. 지정하면 기존 컬럼 헤더가 두 번째 행에 렌더링된다. */
+    headerGroups?: STableHeaderGroup[];
     rows?: SRow[];
     /** 행 식별 필드 */
     rowKey?: string;
@@ -99,6 +190,19 @@ export interface STableProps {
     selectable?: boolean;
     selected?: SRow[];
     onSelectedChange?: (rows: SRow[]) => void;
+    /**
+     * 정렬 상태 (controlled). `null`·미지정이면 정렬 없음.
+     *
+     * 컴포넌트는 정렬 상태를 갖지 않는다 — 서버 정렬이면 이 값이 곧 조회 조건이고,
+     * 뒤로가기·새로고침·링크 공유로 복원돼야 하므로 진실은 URL·store 쪽에 있어야 한다.
+     * 행을 실제로 정렬하는 것도 소비 앱 몫이다 (`STable` 은 받은 순서대로 그린다).
+     */
+    sort?: STableSort | null;
+    /**
+     * 정렬 헤더 클릭 (`asc → desc → 해제` 3단). 해제되면 `null` 이 온다.
+     * 다중 정렬은 1차 안에서 지원하지 않는다.
+     */
+    onSortChange?: (sort: STableSort | null) => void;
     /** 컬럼 너비 조절 */
     resizable?: boolean;
     width?: string;
@@ -109,6 +213,16 @@ export interface STableProps {
     stickyColumn?: STableStickyColumn;
     /** border-radius 제어 */
     radius?: 'default' | 'useTop' | 'full';
+    /**
+     * 바깥 테두리. 기본은 `true`.
+     *
+     * `SSectionHeaderCard` 의 `padding="none"` 안에 넣어 카드 가장자리까지 채울 때 `false` 로 끈다 —
+     * 카드가 이미 바깥 테두리를 그리므로, 켜 두면 1px 두 개가 나란히 놓여 그 변만 2px 로 보인다.
+     *
+     * 페이지네이션 바의 테두리와 1px 겹침(`-mt-px`)도 함께 꺼진다. 본문 테두리가 없으면 겹칠 대상이
+     * 없어, 그대로 두면 페이지네이션만 테두리를 갖고 1px 어긋난다.
+     */
+    bordered?: boolean;
     noDataLabel?: string;
     /**
      * 데이터가 없을 때 body 영역 전체를 대체하는 슬롯.
@@ -116,7 +230,22 @@ export interface STableProps {
      */
     noDataSlot?: ReactNode;
     isLoading?: boolean;
+    /**
+     * 행 높이를 좁게 (세로 여백만 줄인다 — 좌우 패딩은 그대로).
+     *
+     * **시작 밀도이자 밀도 토글의 스위치다.** 켜면 하단 바 우측에 `좁게 보기` · `넓게 보기` 토글이
+     * 붙는다 — 페이지네이션이 없으면 이 바를 토글만 담아 그린다.
+     *
+     * 누른 뒤의 밀도는 테이블이 내부 상태로 들고 가므로 `onDenseChange` 를 받지 않아도 토글은
+     * 동작하고, 넓게 본 뒤에도 토글은 그대로 남는다(붙일지는 이 prop 이 정한다). 이 prop 값이
+     * 바뀌면 내부 밀도도 그 값으로 맞춰진다.
+     */
     dense?: boolean;
+    /**
+     * 밀도 변경 (하단 바의 밀도 토글을 눌렀을 때). 표시는 테이블이 알아서 바꾸므로 받지 않아도 되고,
+     * 사용자가 고른 밀도를 다음 방문까지 기억해 두려는(로컬 저장 등) 페이지만 받으면 된다.
+     */
+    onDenseChange?: (dense: boolean) => void;
     /** true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 */
     noHover?: boolean;
     /** 페이지네이션 (있으면 하단 표시) */
@@ -155,3 +284,4 @@ export interface STableProps {
  * 내부 페이지네이션 + rows-per-page + 가상 스크롤 + 로딩 + dense.
  */
 export declare const STable: import("react").ForwardRefExoticComponent<STableProps & import("react").RefAttributes<STableHandle>>;
+export {};

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

@@ -1 +1 @@
-export { STable, type STableProps, type STableColumn, type STableCellContext, type STablePagination, type STableStickyColumn, type STableHandle, type SRow, } from './STable';
+export { STable, type STableProps, type STableColumn, type STableColumnField, type STableSort, type STableHeaderGroup, type STableCellContext, type STablePagination, type STableStickyColumn, type STableHandle, type SRow, } from './STable';