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

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

@@ -20,16 +20,34 @@ 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;
     /** 표시 포맷 */
@@ -38,6 +56,21 @@ export interface STableColumn {
     icon?: SIconName;
     /** 헤더 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
     iconColor?: SColor;
+    /**
+     * 헤더 라벨 뒤 도움말 툴팁 (각 항목이 한 줄). `SKeyValueTable` 의 `field.helpText` 와 같은 역할 —
+     * 라벨만으로 뜻이 통하지 않는 컬럼의 산출 기준·단위를 설명한다.
+     *
+     * `renderHeader` 로 헤더를 통째로 교체하면 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    helpText?: string[];
+    /**
+     * 정렬 가능한 열인지. 켜면 헤더 라벨 뒤에 정렬 버튼이 붙는다 — 누르는 곳은 그 버튼뿐이고
+     * 헤더 셀 전체가 클릭 영역이 되지는 않는다.
+     *
+     * 정렬 상태는 컴포넌트가 갖지 않는다 — `STable` 의 `sort` · `onSortChange` 로 주고받는다.
+     * `renderHeader` 로 헤더를 통째로 교체하면 버튼도 그리지 않는다 (헤더 전체가 소비 앱 책임).
+     */
+    sortable?: boolean;
     /**
      * 셀에 무엇이 들어가는지. 좌우 여백이 여기서 갈린다 — 기본은 `text`(넓게).
      *
@@ -69,6 +102,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;
@@ -78,6 +122,12 @@ export interface STableStickyColumn {
     left?: number;
     right?: number;
 }
+/** 정렬 상태 — 어느 열을 어느 방향으로 정렬했는가 */
+export interface STableSort {
+    /** 정렬 기준 컬럼의 `name` */
+    name: string;
+    dir: 'asc' | 'desc';
+}
 /** STable ref 명령형 API (sd-table @Method 대응) */
 export interface STableHandle {
     /** 행 선택 여부 */
@@ -109,6 +159,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;
@@ -175,3 +238,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 STableCellContext, type STablePagination, type STableStickyColumn, type STableHandle, type SRow, } from './STable';

package/dist/components/STextarea/README.md

@@ -27,7 +27,7 @@
 | `hint?` | `string` | — |  |
 | `error?` | `boolean` | — |  |
 | `errorMessage?` | `string` | — |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `disabled?` | `boolean` | `false` |  |
 | `readOnly?` | `boolean` | `false` |  |
 | `className?` | `string` | — |  |

package/dist/components/STextarea/STextarea.d.ts

@@ -4,6 +4,7 @@ import { type SIconName } from '../SIcon';
 import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
+import { type SFieldWidth } from '../../lib/field-width';
 export interface STextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
     /** 값 (제어) */
     value?: string;
@@ -41,7 +42,12 @@ export interface STextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextArea
     hint?: string;
     error?: boolean;
     errorMessage?: string;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     disabled?: boolean;
     readOnly?: boolean;
     className?: string;

package/dist/components/STimePicker/README.md

@@ -16,7 +16,7 @@
 | `clearable?` | `boolean` | `false` |  |
 | `useMeridiem?` | `boolean` | — | 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. |
 | `minuteStep?` | `number` | `1` |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `name?` | `string` | — |  |
 | `rules?` | `Rule[]` | — |  |
 | `status?` | `SFieldStatus` | — |  |

package/dist/components/STimePicker/STimePicker.d.ts

@@ -5,6 +5,7 @@ import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
 import { type STimePickerSize, type STimePickerType } from './timepicker.config';
+import { type SFieldWidth } from '../../lib/field-width';
 export type { STimePickerSize, STimePickerType } from './timepicker.config';
 export interface STimePickerProps {
     /** 선택 시간 (HH:mm) */
@@ -22,7 +23,12 @@ export interface STimePickerProps {
     /** 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. */
     useMeridiem?: boolean;
     minuteStep?: number;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     name?: string;
     rules?: Rule[];
     status?: SFieldStatus;

package/dist/components/STimePicker/timepicker.config.d.ts

@@ -1,3 +1,4 @@
+import { type SFieldWidthGrade } from '../../lib/field-width';
 export type STimePickerSize = 'sm' | 'md';
 export type STimePickerType = 'default' | 'midday';
 export type STimePickerMeridiem = 'AM' | 'PM';
@@ -13,10 +14,11 @@ export declare const TIMEPICKER_SIZE_CONFIG: Record<STimePickerSize, {
     minWidth: number;
     fieldMinWidth: number;
     /**
-     * 필드 상한. 값 길이가 HH:mm 으로 정해져 있어, width="100%" 를 받아도 행 전체로
+     * 필드 상한(폭 등급). 값 길이가 HH:mm 으로 정해져 있어, width="100%" 를 받아도 행 전체로
      * 늘어나지 않게 막는다 (SKeyValueTable 이 모든 컨트롤에 100% 를 넘긴다).
+     * px 가 아니라 등급으로 두어 `--cmp-field-width-*` 가 바뀌면 함께 따라가게 한다.
      */
-    fieldMaxWidth: number;
+    fieldMaxWidth: SFieldWidthGrade;
 }>;
 export declare function clampTimePart(value: number, min: number, max: number): number;
 export declare function padTimePart(value: number): string;

package/dist/components/STimeRangePicker/README.md

@@ -17,7 +17,7 @@
 | `useMeridiem?` | `boolean` | — | 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. |
 | `minuteStep?` | `number` | `1` |  |
 | `rangeOrder?` | `STimeRangePickerRangeOrder` | `'strict'` | 범위 순서 정책. strict는 시작 시간이 종료 시간보다 늦어지지 않도록 보정합니다. |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `name?` | `string` | — |  |
 | `rules?` | `Rule[]` | — |  |
 | `status?` | `SFieldStatus` | — |  |

package/dist/components/STimeRangePicker/STimeRangePicker.d.ts

@@ -6,6 +6,7 @@ import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
 import { type STimeRangePickerRangeOrder, type STimeRangePickerSize, type STimeRangePickerType, type STimeRangeValue } from './time-range-picker.config';
 export type { STimeRangePickerSize, STimeRangePickerRangeOrder, STimeRangePickerType, STimeRangeValue, } from './time-range-picker.config';
+import { type SFieldWidth } from '../../lib/field-width';
 export interface STimeRangePickerProps {
     /** 선택 시간 범위 [시작, 종료] (HH:mm) */
     value?: STimeRangeValue;
@@ -24,7 +25,12 @@ export interface STimeRangePickerProps {
     minuteStep?: number;
     /** 범위 순서 정책. strict는 시작 시간이 종료 시간보다 늦어지지 않도록 보정합니다. */
     rangeOrder?: STimeRangePickerRangeOrder;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     name?: string;
     rules?: Rule[];
     status?: SFieldStatus;

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
 ```