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

package/dist/components/SSelect/README.md

@@ -8,23 +8,33 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value?` | `(string \| number \| SSelectOption) \| (string \| number \| SSelectOption)[] \| null` | — | 선택 값. multi 타입이면 배열. emitValue=false(기본) 라운드트립을 위해 SSelectOption 객체도 허용 |
-| `emitValue?` | `boolean` | `false` | true면 SSelectOption 대신 원시값(string|number) 방출 |
+| `value?` | `(string \| number \| SSelectOption) \| (string \| number \| SSelectOption)[] \| null` | — | 선택 값. multi 타입이면 배열. 기본(valueAsPrimitive=false) 라운드트립을 위해 SSelectOption 객체도 허용 |
+| `valueAsPrimitive?` | `boolean` | `false` | `value`·`onValueChange` 가 옵션 객체 대신 원시값(string|number)을 주고받는다. **기본값 `false`(옵션 객체)는 유지한다** — 원본(sd-select) 호환 때문이고, 뒤집으면 이 값을 주지 않던 화면이 조용히 다른 모양의 값을 받게 되어 타입으로도 잡히지 않는다. 새로 쓰는 화면은 켜는 쪽이 다루기 쉽다 — 서버로 보내는 것도, 폼 상태에 담는 것도 결국 값 하나이기 때문이다. |
 | `name?` | `string` | — | 폼 연동용 name 속성 |
 | `options?` | `SSelectOption[]` | `[]` | 옵션 목록 (children으로 계층 표현) |
 | `type?` | `SSelectType` | `'default'` | 타입: default | multi | default_depth | multi_depth |
-| `useSearch?` | `boolean` | `false` | 검색 입력 사용 |
-| `useSelectAll?` | `boolean` | `false` | 전체선택 옵션 사용 (multi 전용) |
+| `valueDisplay?` | `SSelectValueDisplay` | `'text'` | 트리거에 선택값을 보여주는 방식. - `text`: 선택 라벨을 쉼표로 이어 한 줄로 보여준다. 넘치면 말줄임한다. - `chip`: 선택값마다 칩을 낸다. 칩의 × 를 누르면 그 값만 선택에서 빠지고, 드롭다운은 열리지 않는다. 칩이 한 줄을 넘으면 줄바꿈하고 트리거가 그만큼 높아진다. `chip` 은 `multi`·`multi_depth` 에서만 동작한다. 단일 선택 type 에서는 무시하고 `text` 로 보여준다. 전체 선택이면 칩 대신 `allSelectedLabel` 을 보여준다. `multi_depth` 에서 그룹의 하위 리프를 전부 고르면 리프 칩 대신 그룹명 칩 하나로 묶고, 그 칩의 × 는 그룹의 리프를 한꺼번에 뺀다. 비활성(select 자체나 해당 옵션)인 칩에는 × 를 내지 않는다. |
+| `showSearch?` | `boolean` | `false` | 검색 입력 사용 |
+| `showSelectAll?` | `boolean` | `false` | 전체선택 옵션 사용 (multi 전용) |
 | `allSelectedLabel?` | `string` | `'전체'` | 전체선택 레이블 |
 | `placeholder?` | `string` | `'선택'` | placeholder |
 | `disabled?` | `boolean` | `false` | 비활성 |
+| `clearable?` | `boolean` | `false` | 선택값 지우기(×) 버튼 노출. 선택값이 있고 비활성이 아닐 때만 나타나며, 누르면 드롭다운을 열지 않고 값만 비운다. |
 | `error?` | `boolean` | `false` | 에러 상태 |
 | `rules?` | `Rule[]` | — | 유효성 규칙 — 닫힐 때 자동 검증 |
 | `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
-| `dropdownHeight?` | `string` | `'260px'` | 드롭다운 최대 높이 |
+| `dropdownHeight?` | `string` | `'640px'` | 드롭다운 최대 높이. 기본 640px — 창이 이보다 작으면 창 안에 남는 만큼까지만 채워진다 |
 | `dropdownWidth?` | `string` | — | 드롭다운 너비 (없으면 트리거 너비). 창보다 넓게 줘도 창 폭까지만 벌어진다. |
 | `maxDropdownWidth?` | `string` | `'640px'` | 드롭다운 최대 너비. 창이 이보다 좁으면 창 폭이 상한이 된다. |
+| `virtualBuffer?` | `number` | `DEFAULT_VIRTUAL_BUFFER` | 화면 위·아래로 더 그려둘 여유 행 수 — 빠르게 스크롤할 때 빈 칸이 보이지 않게 한다. 목록은 **언제나 보이는 범위만 렌더한다**(끄는 prop 은 없다). 그래서 여는 비용이 옵션 수와 무관하고, 이 값만이 DOM 에 남는 행 수를 정한다 — 한 화면 분량 + 앞뒤로 이만큼. |
+| `reachEndThreshold?` | `number` | `DEFAULT_REACH_END_THRESHOLD` | 목록 끝에서 이만큼 행이 남았을 때 `onReachEnd` 를 부른다 — 스크롤이 바닥에 닿기 전에 미리 받아 둔다. **한 페이지 크기보다 충분히 작게 잡는다.** 한 페이지가 드롭다운을 채우고도 이 문턱만큼 남기지 못하면, 페이지가 도착하는 족족 다음 페이지를 다시 청하게 된다 — 사용자가 스크롤을 하지 않아도 목록 전체를 받아 오므로 페이징을 한 의미가 사라진다. (한 페이지 50개 · 드롭다운에 20행이 보인다면 남는 것은 30행이므로, 문턱은 그보다 작아야 한다) |
+| `hasMore?` | `boolean` | `false` | 더 받아올 페이지가 남았는가. `false` 면 `onReachEnd` 를 더 부르지 않는다 |
+| `loading?` | `boolean` | `false` | 옵션을 받는 중 — 트리거의 펼침 아이콘 자리에 스피너를, 드롭다운 하단에 로딩 행을 낸다. 첫 조회(옵션이 아직 없을 때)든 다음 페이지든 같은 prop 이고, 그동안 `onReachEnd` 를 다시 부르지 않는다. 로딩 중에도 열 수 있다 — 서버 검색·페이징은 열린 채로 로딩을 오가므로, 열기를 막으면 닫았다 다시 연 사용자에게 클릭이 먹지 않는 고장으로 보인다. 받는 중에는 "표시할 항목이 없습니다."를 내지 않는다. 비활성이면 트리거 스피너를 내지 않는다 — 열 수 없는데 스피너가 돌면 "기다리면 열린다"로 읽힌다. |
+| `serverSearch?` | `boolean` | `false` | 검색을 서버로 넘긴다 — 내부 필터링을 하지 않고 `options` 를 받은 그대로 보여준다. `onSearchChange` 로 온 검색어에 맞는 목록을 소비 앱이 다시 내려줘야 한다. 켜면 검색바가 옵션 수와 무관하게 항상 나온다 — 검색 결과가 줄었다고 검색바가 사라지면 검색어를 지울 수단이 없어지기 때문이다. |
+| `searchDebounce?` | `number` | `DEFAULT_SEARCH_DEBOUNCE` | `serverSearch` 에서 검색어를 서버로 넘기기 전 기다리는 시간(ms) |
 | `label?` | `string` | — |  |
+| `labelPosition?` | `SFieldLabelPosition` | — | 레이블 위치 — `top` 이면 라벨이 컨트롤 위에 선다 (SField 로 그대로 넘어간다). |
+| `subLabel?` | `string` | — | 보조 레이블 — 레이블 오른쪽 같은 줄에 붙는다 (SField 로 그대로 넘어간다). |
 | `labelWidth?` | `number \| string` | — |  |
 | `icon?` | `SIconName` | — | 레이블 영역 아이콘 |
 | `iconColor?` | `SColor` | — |  |
@@ -33,7 +43,8 @@
 | `addonAlign?` | `SFieldAddonAlign` | — | 어드온 정렬 |
 | `hint?` | `string` | — |  |
 | `errorMessage?` | `string` | — |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. 셀렉트는 `maxLength` 개념이 없어 목록 최장값을 담는 등급으로 고른다. |
+| `size?` | `SFieldSize` | `'sm'` | 트리거 크기 (기본값 `'sm'`). 높이·패딩·간격·글자 크기를 `--cmp-select-{size}-*` 토큰으로 바꾼다. 드롭다운 목록은 크기와 무관하게 같다. `valueDisplay="chip"` 이면 `md` 는 SChip 과 같은 칩을, `sm` 은 28px 트리거에 맞춘 낮은 칩을 낸다. |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
@@ -41,8 +52,10 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onValueChange` | `(value: any) => void` | 값 변경 (sdUpdate). emitValue=false(기본)면 SSelectOption(들), true면 원시값 |
+| `onValueChange` | `(value: TValue) => void` | 값 변경. 기본은 SSelectOption(들)이 오고, `valueAsPrimitive` 면 원시값이 온다 |
 | `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
+| `onReachEnd` | `() => void` | 목록 끝이 가까워지면 부른다 — 다음 페이지를 받아 `options` 뒤에 이어붙이라는 신호다. `hasMore` 가 `false` 이거나 `loading` 중이면 부르지 않고, 같은 목록 길이로 두 번 부르지 않는다. **`options` 는 갈아끼우지 말고 이어붙인다.** depth 타입이면 이미 있는 그룹의 `children` 에 이어야 한다 — 같은 그룹을 새 항목으로 또 밀어 넣으면 목록에 같은 헤더가 두 번 뜬다. 아직 받지 않은 옵션은 라벨을 알 수 없다. 그래서 이 prop 을 쓰는 화면은 `valueAsPrimitive` 를 켜지 않는 편이 안전하다 — 기본값(옵션 객체)이면 선택값이 라벨을 함께 들고 다녀서, 그 옵션이 목록에서 사라져도 트리거에 이름이 그대로 남는다. |
+| `onSearchChange` | `(query: string) => void` | 검색어 변경. `serverSearch` 면 `searchDebounce` 만큼 묶어서 온다 |
 
 #### Methods (ref)
 
@@ -51,30 +64,70 @@
 | `focus` | `() => void` | 트리거 버튼에 포커스 (sdFocus) |
 | `open` | `() => void` | 드롭다운 열기 (sdOpen) |
 
+## Types
+
+### SSelectChangeValue
+
+```ts
+/**
+ * `onValueChange` 로 오는 값의 기본 타입.
+ *
+ * 실제 모양은 `type`(단일/multi)과 `valueAsPrimitive`(옵션 객체/원시값)의 조합으로 정해져 한 타입으로
+ * 적을 수 없다. 화면이 안다면 `<SSelect<string> valueAsPrimitive … />` 처럼 넘겨 좁힌다 — 넘기지 않은
+ * 기존 코드는 이 기본값으로 예전처럼 동작한다.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- 값 타입을 넘기지 않은 화면의 의도된 탈출구
+export type SSelectChangeValue = any;
+```
+
+### SSelectOption
+
+```ts
+export interface SSelectOption {
+  value: string | number;
+  label: string;
+  disabled?: boolean;
+  children?: SSelectOption[];
+}
+```
+
+### SSelectType
+
+```ts
+export type SSelectType = 'default' | 'multi' | 'default_depth' | 'multi_depth';
+```
+
+### SSelectValueDisplay
+
+```ts
+/** 트리거에 선택값을 보여주는 방식 — 쉼표로 이은 텍스트 | 값마다 칩 */
+export type SSelectValueDisplay = 'text' | 'chip';
+```
+
 ## Dependencies
 
 ### Used by
 
- - [SChipFilter](../SChipFilter)
  - [SKeyValueTable](../SKeyValueTable)
  - [STable](../STable)
 
 ### Depends on
 
+- [SCircleProgress](../SCircleProgress)
 - [SField](../SField)
-- [SGhostButton](../SGhostButton)
 - [SIcon](../SIcon)
 - [SPortal](../SPortal)
+- [SSearchInput](../SSearchInput)
 
 ### Graph
 
 ```mermaid
 graph TD;
+  SSelect --> SCircleProgress
   SSelect --> SField
-  SSelect --> SGhostButton
   SSelect --> SIcon
   SSelect --> SPortal
-  SChipFilter --> SSelect
+  SSelect --> SSearchInput
   SKeyValueTable --> SSelect
   STable --> SSelect
   style SSelect fill:#f9f,stroke:#333,stroke-width:4px

package/dist/components/SSelect/SSelect.d.ts

@@ -1,55 +1,157 @@
-import { type CSSProperties } from 'react';
+import { type CSSProperties, type ForwardedRef, type ReactElement } from 'react';
 import { type Rule } from '../../lib/form';
-import { type SFieldAddonAlign } from '../SField';
+import { type SFieldAddonAlign, type SFieldLabelPosition, type SFieldSize } from '../SField';
 import { type SIconName } from '../SIcon';
 import { type SColor } from '../../lib/color';
 import { type STooltipProps } from '../STooltip';
-import { type SSelectOption, type SSelectType } from './select.config';
-export type { SSelectOption, SSelectType } from './select.config';
+import { type SSelectOption, type SSelectType, type SSelectValueDisplay } from './select.config';
+import { type SFieldWidth } from '../../lib/field-width';
+export type { SSelectOption, SSelectType, SSelectValueDisplay } from './select.config';
 export interface SSelectHandle {
     /** 트리거 버튼에 포커스 (sdFocus) */
     focus: () => void;
     /** 드롭다운 열기 (sdOpen) */
     open: () => void;
 }
-export interface SSelectProps {
-    /** 선택 값. multi 타입이면 배열. emitValue=false(기본) 라운드트립을 위해 SSelectOption 객체도 허용 */
+/**
+ * `onValueChange` 로 오는 값의 기본 타입.
+ *
+ * 실제 모양은 `type`(단일/multi)과 `valueAsPrimitive`(옵션 객체/원시값)의 조합으로 정해져 한 타입으로
+ * 적을 수 없다. 화면이 안다면 `<SSelect<string> valueAsPrimitive … />` 처럼 넘겨 좁힌다 — 넘기지 않은
+ * 기존 코드는 이 기본값으로 예전처럼 동작한다.
+ */
+export type SSelectChangeValue = any;
+export interface SSelectProps<TValue extends SSelectChangeValue = SSelectChangeValue> {
+    /** 선택 값. multi 타입이면 배열. 기본(valueAsPrimitive=false) 라운드트립을 위해 SSelectOption 객체도 허용 */
     value?: (string | number | SSelectOption) | (string | number | SSelectOption)[] | null;
-    /** 값 변경 (sdUpdate). emitValue=false(기본)면 SSelectOption(들), true면 원시값 */
-    onValueChange?: (value: any) => void;
+    /** 값 변경. 기본은 SSelectOption(들)이 오고, `valueAsPrimitive` 면 원시값이 온다 */
+    onValueChange?: (value: TValue) => void;
     /** 열림/닫힘 변경 (sdDropDownShow) */
     onOpenChange?: (open: boolean) => void;
-    /** true면 SSelectOption 대신 원시값(string|number) 방출 */
-    emitValue?: boolean;
+    /**
+     * `value`·`onValueChange` 가 옵션 객체 대신 원시값(string|number)을 주고받는다.
+     *
+     * **기본값 `false`(옵션 객체)는 유지한다** — 원본(sd-select) 호환 때문이고, 뒤집으면 이 값을
+     * 주지 않던 화면이 조용히 다른 모양의 값을 받게 되어 타입으로도 잡히지 않는다.
+     *
+     * 새로 쓰는 화면은 켜는 쪽이 다루기 쉽다 — 서버로 보내는 것도, 폼 상태에 담는 것도
+     * 결국 값 하나이기 때문이다.
+     */
+    valueAsPrimitive?: boolean;
     /** 폼 연동용 name 속성 */
     name?: string;
     /** 옵션 목록 (children으로 계층 표현) */
     options?: SSelectOption[];
     /** 타입: default | multi | default_depth | multi_depth */
     type?: SSelectType;
+    /**
+     * 트리거에 선택값을 보여주는 방식.
+     * - `text`: 선택 라벨을 쉼표로 이어 한 줄로 보여준다. 넘치면 말줄임한다.
+     * - `chip`: 선택값마다 칩을 낸다. 칩의 × 를 누르면 그 값만 선택에서 빠지고, 드롭다운은 열리지 않는다.
+     *   칩이 한 줄을 넘으면 줄바꿈하고 트리거가 그만큼 높아진다.
+     *
+     * `chip` 은 `multi`·`multi_depth` 에서만 동작한다. 단일 선택 type 에서는 무시하고 `text` 로 보여준다.
+     * 전체 선택이면 칩 대신 `allSelectedLabel` 을 보여준다.
+     * `multi_depth` 에서 그룹의 하위 리프를 전부 고르면 리프 칩 대신 그룹명 칩 하나로 묶고,
+     * 그 칩의 × 는 그룹의 리프를 한꺼번에 뺀다.
+     * 비활성(select 자체나 해당 옵션)인 칩에는 × 를 내지 않는다.
+     */
+    valueDisplay?: SSelectValueDisplay;
     /** 검색 입력 사용 */
-    useSearch?: boolean;
+    showSearch?: boolean;
     /** 전체선택 옵션 사용 (multi 전용) */
-    useSelectAll?: boolean;
+    showSelectAll?: boolean;
     /** 전체선택 레이블 */
     allSelectedLabel?: string;
     /** placeholder */
     placeholder?: string;
     /** 비활성 */
     disabled?: boolean;
+    /**
+     * 선택값 지우기(×) 버튼 노출. 선택값이 있고 비활성이 아닐 때만 나타나며,
+     * 누르면 드롭다운을 열지 않고 값만 비운다.
+     */
+    clearable?: boolean;
     /** 에러 상태 */
     error?: boolean;
     /** 유효성 규칙 — 닫힐 때 자동 검증 */
     rules?: Rule[];
     /** 레이블 툴팁 상세 옵션 */
     labelTooltipProps?: Partial<STooltipProps>;
-    /** 드롭다운 최대 높이 */
+    /** 드롭다운 최대 높이. 기본 640px — 창이 이보다 작으면 창 안에 남는 만큼까지만 채워진다 */
     dropdownHeight?: string;
     /** 드롭다운 너비 (없으면 트리거 너비). 창보다 넓게 줘도 창 폭까지만 벌어진다. */
     dropdownWidth?: string;
     /** 드롭다운 최대 너비. 창이 이보다 좁으면 창 폭이 상한이 된다. */
     maxDropdownWidth?: string;
+    /**
+     * 화면 위·아래로 더 그려둘 여유 행 수 — 빠르게 스크롤할 때 빈 칸이 보이지 않게 한다.
+     *
+     * 목록은 **언제나 보이는 범위만 렌더한다**(끄는 prop 은 없다). 그래서 여는 비용이 옵션
+     * 수와 무관하고, 이 값만이 DOM 에 남는 행 수를 정한다 — 한 화면 분량 + 앞뒤로 이만큼.
+     */
+    virtualBuffer?: number;
+    /**
+     * 목록 끝이 가까워지면 부른다 — 다음 페이지를 받아 `options` 뒤에 이어붙이라는 신호다.
+     * `hasMore` 가 `false` 이거나 `loading` 중이면 부르지 않고, 같은 목록 길이로 두 번 부르지 않는다.
+     *
+     * **`options` 는 갈아끼우지 말고 이어붙인다.** depth 타입이면 이미 있는 그룹의 `children`
+     * 에 이어야 한다 — 같은 그룹을 새 항목으로 또 밀어 넣으면 목록에 같은 헤더가 두 번 뜬다.
+     *
+     * 아직 받지 않은 옵션은 라벨을 알 수 없다. 그래서 이 prop 을 쓰는 화면은
+     * `valueAsPrimitive` 를 켜지 않는 편이 안전하다 — 기본값(옵션 객체)이면 선택값이 라벨을
+     * 함께 들고 다녀서, 그 옵션이 목록에서 사라져도 트리거에 이름이 그대로 남는다.
+     */
+    onReachEnd?: () => void;
+    /**
+     * 목록 끝에서 이만큼 행이 남았을 때 `onReachEnd` 를 부른다 — 스크롤이 바닥에 닿기 전에 미리 받아 둔다.
+     *
+     * **한 페이지 크기보다 충분히 작게 잡는다.** 한 페이지가 드롭다운을 채우고도 이 문턱만큼
+     * 남기지 못하면, 페이지가 도착하는 족족 다음 페이지를 다시 청하게 된다 — 사용자가 스크롤을
+     * 하지 않아도 목록 전체를 받아 오므로 페이징을 한 의미가 사라진다.
+     * (한 페이지 50개 · 드롭다운에 20행이 보인다면 남는 것은 30행이므로, 문턱은 그보다 작아야 한다)
+     */
+    reachEndThreshold?: number;
+    /** 더 받아올 페이지가 남았는가. `false` 면 `onReachEnd` 를 더 부르지 않는다 */
+    hasMore?: boolean;
+    /**
+     * 옵션을 받는 중 — 트리거의 펼침 아이콘 자리에 스피너를, 드롭다운 하단에 로딩 행을 낸다.
+     * 첫 조회(옵션이 아직 없을 때)든 다음 페이지든 같은 prop 이고, 그동안 `onReachEnd` 를 다시 부르지 않는다.
+     *
+     * 로딩 중에도 열 수 있다 — 서버 검색·페이징은 열린 채로 로딩을 오가므로, 열기를 막으면
+     * 닫았다 다시 연 사용자에게 클릭이 먹지 않는 고장으로 보인다. 받는 중에는 "표시할 항목이
+     * 없습니다."를 내지 않는다.
+     *
+     * 비활성이면 트리거 스피너를 내지 않는다 — 열 수 없는데 스피너가 돌면 "기다리면 열린다"로 읽힌다.
+     */
+    loading?: boolean;
+    /**
+     * 검색을 서버로 넘긴다 — 내부 필터링을 하지 않고 `options` 를 받은 그대로 보여준다.
+     * `onSearchChange` 로 온 검색어에 맞는 목록을 소비 앱이 다시 내려줘야 한다.
+     *
+     * 켜면 검색바가 옵션 수와 무관하게 항상 나온다 — 검색 결과가 줄었다고 검색바가 사라지면
+     * 검색어를 지울 수단이 없어지기 때문이다.
+     */
+    serverSearch?: boolean;
+    /** 검색어 변경. `serverSearch` 면 `searchDebounce` 만큼 묶어서 온다 */
+    onSearchChange?: (query: string) => void;
+    /** `serverSearch` 에서 검색어를 서버로 넘기기 전 기다리는 시간(ms) */
+    searchDebounce?: number;
     label?: string;
+    /**
+     * 레이블 위치 — `top` 이면 라벨이 컨트롤 위에 선다 (SField 로 그대로 넘어간다).
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    labelPosition?: SFieldLabelPosition;
+    /**
+     * 보조 레이블 — 레이블 오른쪽 같은 줄에 붙는다 (SField 로 그대로 넘어간다).
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    subLabel?: string;
     labelWidth?: number | string;
     /** 레이블 영역 아이콘 */
     icon?: SIconName;
@@ -62,8 +164,26 @@ export interface SSelectProps {
     addonAlign?: SFieldAddonAlign;
     hint?: string;
     errorMessage?: string;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     * 셀렉트는 `maxLength` 개념이 없어 목록 최장값을 담는 등급으로 고른다.
+     */
+    width?: SFieldWidth;
+    /**
+     * 트리거 크기 (기본값 `'sm'`). 높이·패딩·간격·글자 크기를 `--cmp-select-{size}-*` 토큰으로 바꾼다.
+     * 드롭다운 목록은 크기와 무관하게 같다.
+     * `valueDisplay="chip"` 이면 `md` 는 SChip 과 같은 칩을, `sm` 은 28px 트리거에 맞춘 낮은 칩을 낸다.
+     */
+    size?: SFieldSize;
     className?: string;
     style?: CSSProperties;
 }
-export declare const SSelect: import("react").ForwardRefExoticComponent<SSelectProps & import("react").RefAttributes<SSelectHandle>>;
+/**
+ * 값 타입을 받는 제네릭 컴포넌트로 내보낸다 — `forwardRef` 는 타입 파라미터를 지워 버리므로
+ * 바깥 시그니처만 다시 씌운다(STable·SDraggableList 와 같은 방식).
+ */
+export declare const SSelect: <TValue extends SSelectChangeValue = SSelectChangeValue>(props: SSelectProps<TValue> & {
+    ref?: ForwardedRef<SSelectHandle>;
+}) => ReactElement | null;

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

@@ -1 +1 @@
-export { SSelect, type SSelectHandle, type SSelectProps, type SSelectOption, type SSelectType, } from './SSelect';
+export { SSelect, type SSelectHandle, type SSelectProps, type SSelectChangeValue, type SSelectOption, type SSelectType, type SSelectValueDisplay, } from './SSelect';

package/dist/components/SSelect/select.config.d.ts

@@ -5,6 +5,8 @@ export interface SSelectOption {
     children?: SSelectOption[];
 }
 export type SSelectType = 'default' | 'multi' | 'default_depth' | 'multi_depth';
+/** 트리거에 선택값을 보여주는 방식 — 쉼표로 이은 텍스트 | 값마다 칩 */
+export type SSelectValueDisplay = 'text' | 'chip';
 export interface FlatOption {
     value: string;
     label: string;
@@ -29,3 +31,18 @@ export declare function collectGroupLeafValues(flat: FlatOption[], groupIndex: n
 export declare const isHtmlLabel: (label: string) => boolean;
 /** HTML 라벨에서 태그를 제거한 텍스트 (검색 매칭용, 원본 extractText) */
 export declare const extractText: (html: string) => string;
+/**
+ * 아직 한 번도 그려지지 않은 행의 **추정** 높이(px). 리프 옵션은 세로 패딩 4px + 행간 20px
+ * 이라 보통 이 값이지만, 그룹 헤더나 큰 글씨가 섞인 라벨은 다르다 — 화면에 나온 행은
+ * 실측으로 덮이므로(`lib/row-metrics.ts`) 이 값은 처음 스크롤바 길이를 잡는 출발점일 뿐이다.
+ */
+export declare const OPTION_ROW_HEIGHT = 28;
+/**
+ * 화면 위·아래로 더 그려둘 기본 여유 행 수.
+ * 640px 드롭다운이 20행 남짓 보이므로, 앞뒤 10행이면 한 화면을 굴리는 동안 빈 칸이 보이지 않는다.
+ */
+export declare const DEFAULT_VIRTUAL_BUFFER = 10;
+/** 목록 끝에서 이만큼 행이 남았을 때 다음 페이지를 청하는 기본값 */
+export declare const DEFAULT_REACH_END_THRESHOLD = 10;
+/** `serverSearch` 에서 검색어를 서버로 넘기기 전 기다리는 기본 시간(ms) */
+export declare const DEFAULT_SEARCH_DEBOUNCE = 300;

package/dist/components/SSkeleton/README.md

@@ -0,0 +1,55 @@
+# SSkeleton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSkeleton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SSkeletonType` | `'rect'` | 자리표시 모양 - `rect`: 사각형. 폭은 부모를, 높이는 한 줄 높이를 따른다 — 이미지·카드 영역은 `height` 를 준다 - `circle`: 원형(아바타 등) - `text`: 텍스트 한 줄. 부모 타이포의 line-height 를 따르고 세로로 절반만 칠한다 - `button`·`input`·`tag`·`checkbox`·`radio`·`switch`: 해당 컴포넌트 기본 size 의 크기·모서리 |
+| `animation?` | `SSkeletonAnimation` | `'wave'` | 로딩 애니메이션 - `wave`: 하이라이트 띠가 왼쪽에서 오른쪽으로 지나간다 - `pulse`: 크기가 숨쉬듯 줄었다 커진다. 블록 전체가 움직이므로 아바타처럼 작은 모양에만 쓴다 - `fade`: 투명도가 숨쉬듯 바뀐다 - `none`: 애니메이션 없음 OS 의 동작 줄이기 설정이 켜져 있으면 어떤 값이든 멈춘다. |
+| `animationSpeed?` | `number` | `1500` | 애니메이션 한 주기 (ms) |
+| `square?` | `boolean` | `false` | 모서리를 각지게 |
+| `bordered?` | `boolean` | `false` | 테두리 |
+| `size?` | `string \| number` | — | 가로·세로를 한 번에 지정. `width`·`height` 가 있으면 그쪽이 우선한다. 숫자는 px |
+| `width?` | `string \| number` | — | 폭. 숫자는 px |
+| `height?` | `string \| number` | — | 높이. 숫자는 px |
+
+## Types
+
+### SSkeletonType
+
+```ts
+export type SSkeletonType = (typeof SKELETON_TYPES)[number];
+```
+
+### SSkeletonAnimation
+
+```ts
+export type SSkeletonAnimation = (typeof SKELETON_ANIMATIONS)[number];
+```
+
+### SKELETON_TYPES
+
+```ts
+export const SKELETON_TYPES = [
+  'rect',
+  'circle',
+  'text',
+  'button',
+  'input',
+  'tag',
+  'checkbox',
+  'radio',
+  'switch',
+] as const;
+```
+
+### SKELETON_ANIMATIONS
+
+```ts
+export const SKELETON_ANIMATIONS = ['wave', 'pulse', 'fade', 'none'] as const;
+```
+

package/dist/components/SSkeleton/SSkeleton.d.ts

@@ -0,0 +1,39 @@
+import { type HTMLAttributes } from 'react';
+import { type SSkeletonAnimation, type SSkeletonType } from './skeleton.config';
+export interface SSkeletonProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * 자리표시 모양
+     * - `rect`: 사각형. 폭은 부모를, 높이는 한 줄 높이를 따른다 — 이미지·카드 영역은 `height` 를 준다
+     * - `circle`: 원형(아바타 등)
+     * - `text`: 텍스트 한 줄. 부모 타이포의 line-height 를 따르고 세로로 절반만 칠한다
+     * - `button`·`input`·`tag`·`checkbox`·`radio`·`switch`: 해당 컴포넌트 기본 size 의 크기·모서리
+     */
+    type?: SSkeletonType;
+    /**
+     * 로딩 애니메이션
+     * - `wave`: 하이라이트 띠가 왼쪽에서 오른쪽으로 지나간다
+     * - `pulse`: 크기가 숨쉬듯 줄었다 커진다. 블록 전체가 움직이므로 아바타처럼 작은 모양에만 쓴다
+     * - `fade`: 투명도가 숨쉬듯 바뀐다
+     * - `none`: 애니메이션 없음
+     *
+     * OS 의 동작 줄이기 설정이 켜져 있으면 어떤 값이든 멈춘다.
+     */
+    animation?: SSkeletonAnimation;
+    /** 애니메이션 한 주기 (ms) */
+    animationSpeed?: number;
+    /** 모서리를 각지게 */
+    square?: boolean;
+    /** 테두리 */
+    bordered?: boolean;
+    /** 가로·세로를 한 번에 지정. `width`·`height` 가 있으면 그쪽이 우선한다. 숫자는 px */
+    size?: string | number;
+    /** 폭. 숫자는 px */
+    width?: string | number;
+    /** 높이. 숫자는 px */
+    height?: string | number;
+}
+/**
+ * SSkeleton — 데이터가 오기 전 콘텐츠 자리를 같은 모양으로 채워 두는 자리표시. Quasar QSkeleton 모티브.
+ * 장식이라 보조기기에는 숨긴다(`aria-hidden`). 로딩 중이라는 사실은 감싸는 영역에 `aria-busy` 로 알린다.
+ */
+export declare const SSkeleton: import("react").ForwardRefExoticComponent<SSkeletonProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,2 @@
+export { SSkeleton, type SSkeletonProps } from './SSkeleton';
+export { SKELETON_TYPES, SKELETON_ANIMATIONS, SKELETON_TYPE_CONFIG, type SSkeletonType, type SSkeletonAnimation, } from './skeleton.config';

package/dist/components/SSkeleton/skeleton.config.d.ts

@@ -0,0 +1,22 @@
+export declare const SKELETON_TYPES: readonly ["rect", "circle", "text", "button", "input", "tag", "checkbox", "radio", "switch"];
+export type SSkeletonType = (typeof SKELETON_TYPES)[number];
+export declare const SKELETON_ANIMATIONS: readonly ["wave", "pulse", "fade", "none"];
+export type SSkeletonAnimation = (typeof SKELETON_ANIMATIONS)[number];
+/**
+ * type 별 기본 크기·모서리. 값이 없는 축은 내용(공백 한 글자)과 부모 폭을 따른다.
+ * DS 모양(button·input…)은 해당 컴포넌트의 **기본 size** 토큰을 그대로 가리켜
+ * 토큰이 바뀌어도 실제 컴포넌트와 어긋나지 않는다. 폭은 토큰이 없어 Quasar 기본값을 따른다.
+ */
+export declare const SKELETON_TYPE_CONFIG: Record<SSkeletonType, {
+    width?: string;
+    height?: string;
+    radius: string;
+}>;
+export declare const SKELETON_COLORS: {
+    /** Quasar rgba(0,0,0,.12) ≈ 흰 바탕 위 #E1E1E1 */
+    bg: string;
+    /** Quasar rgba(0,0,0,.05) 테두리 — 배경보다 한 단계 짙게 */
+    border: string;
+    /** Quasar rgba(255,255,255,.5) 하이라이트 띠 */
+    wave: string;
+};

package/dist/components/SSplitter/README.md

@@ -12,7 +12,7 @@
 | `defaultValue?` | `number` | — | 첫 패널 초기 크기. uncontrolled. 기본은 '%' 면 50, 'px' 면 240 |
 | `unit?` | `SSplitterUnit` | `'%'` | 모델·limits 를 읽는 단위 |
 | `limits?` | `readonly [number, number]` | — | [최소, 최대]. 생략하면 '%' 는 [10, 90], 'px' 는 [50, Infinity] |
-| `emitImmediately?` | `boolean` | `false` | 드래그하는 동안에도 onValueChange 를 계속 보낸다 |
+| `updateWhileDragging?` | `boolean` | `false` | 드래그하는 동안에도 `onValueChange` 를 계속 보낸다. 기본은 놓는 순간 한 번만 — 미리보기는 컴포넌트가 내부에서 그리므로, 값을 저장하는 쪽이 프레임마다 불릴 이유가 없다. 패널 크기에 맞춰 밖의 무언가를 실시간으로 다시 그려야 할 때만 켠다. |
 | `vertical?` | `boolean` | `false` | true면 패널을 위아래로 쌓는다 (Quasar q-splitter 의 horizontal 에 해당) |
 | `disabled?` | `boolean` | `false` | true면 크기를 바꿀 수 없다. 커서도 구분선도 나오지 않는다 |
 | `dividerClassName?` | `string` | — | 구분선에 얹을 클래스 |
@@ -23,5 +23,20 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onValueChange` | `(value: number) => void` | 크기가 확정될 때. emitImmediately 가 아니면 드래그를 놓는 순간 한 번만 온다 |
+| `onValueChange` | `(value: number) => void` | 크기가 확정될 때. `updateWhileDragging` 이 아니면 드래그를 놓는 순간 한 번만 온다 |
+
+## Types
+
+### SSplitterUnit
+
+```ts
+/** 모델·limits 를 읽는 단위. Quasar QSplitter 의 `unit` 과 같다. */
+export type SSplitterUnit = (typeof SSPLITTER_UNITS)[number];
+```
+
+### SSPLITTER_UNITS
+
+```ts
+export const SSPLITTER_UNITS = ['%', 'px'] as const;
+```
 

package/dist/components/SSplitter/SSplitter.d.ts

@@ -7,14 +7,18 @@ export interface SSplitterProps extends Omit<HTMLAttributes<HTMLDivElement>, 'de
     value?: number;
     /** 첫 패널 초기 크기. uncontrolled. 기본은 '%' 면 50, 'px' 면 240 */
     defaultValue?: number;
-    /** 크기가 확정될 때. emitImmediately 가 아니면 드래그를 놓는 순간 한 번만 온다 */
+    /** 크기가 확정될 때. `updateWhileDragging` 이 아니면 드래그를 놓는 순간 한 번만 온다 */
     onValueChange?: (value: number) => void;
     /** 모델·limits 를 읽는 단위 */
     unit?: SSplitterUnit;
     /** [최소, 최대]. 생략하면 '%' 는 [10, 90], 'px' 는 [50, Infinity] */
     limits?: readonly [number, number];
-    /** 드래그하는 동안에도 onValueChange 를 계속 보낸다 */
-    emitImmediately?: boolean;
+    /**
+     * 드래그하는 동안에도 `onValueChange` 를 계속 보낸다. 기본은 놓는 순간 한 번만 —
+     * 미리보기는 컴포넌트가 내부에서 그리므로, 값을 저장하는 쪽이 프레임마다 불릴 이유가 없다.
+     * 패널 크기에 맞춰 밖의 무언가를 실시간으로 다시 그려야 할 때만 켠다.
+     */
+    updateWhileDragging?: boolean;
     /** true면 패널을 위아래로 쌓는다 (Quasar q-splitter 의 horizontal 에 해당) */
     vertical?: boolean;
     /** true면 크기를 바꿀 수 없다. 커서도 구분선도 나오지 않는다 */

package/dist/components/SStepper/README.md

@@ -30,6 +30,32 @@
 | `showItemTooltip` | `() => void` | error 아이템 중 첫 번째에 툴팁을 연다. error 아이템이 없으면 아무 일도 일어나지 않는다. |
 | `hideItemTooltip` | `() => void` | 열려있는 커스텀 툴팁을 닫는다. 활성 단계(value prop)가 바뀌면 별도 호출 없이도 자동으로 닫힌다. |
 
+## Types
+
+### SStepperItem
+
+```ts
+export type SStepperItem = {
+  label: string;
+  value?: string;
+  group?: string;
+  completed?: boolean;
+  error?: boolean;
+};
+```
+
+### SStepperSize
+
+```ts
+export type SStepperSize = (typeof STEPPER_SIZES)[number];
+```
+
+### STEPPER_SIZES
+
+```ts
+export const STEPPER_SIZES = ['sm', 'lg'] as const;
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SSwitch/README.md

@@ -11,7 +11,6 @@
 | `value?` | `boolean` | `false` | on/off 상태 |
 | `leftLabel?` | `string` | — | 스위치 좌측 라벨 |
 | `rightLabel?` | `string` | — | 스위치 우측 라벨 |
-| `label?` | `string` | — |  |
 | `disabled?` | `boolean` | `false` | 비활성 |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
@@ -22,3 +21,16 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: boolean) => void` | 변경 (sdUpdate) |
 
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Graph
+
+```mermaid
+graph TD;
+  SKeyValueTable --> SSwitch
+  style SSwitch fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SSwitch/SSwitch.d.ts

@@ -6,8 +6,6 @@ export interface SSwitchProps {
     leftLabel?: string;
     /** 스위치 우측 라벨 */
     rightLabel?: string;
-    /** @deprecated `rightLabel` 사용. 우측 라벨(하위호환) */
-    label?: string;
     /** 비활성 */
     disabled?: boolean;
     /** 변경 (sdUpdate) */
@@ -16,4 +14,4 @@ export interface SSwitchProps {
     style?: CSSProperties;
 }
 /** SSwitch — sd-switch 포팅 (Radix SSwitch). 32×20 트랙, 16 노브. 좌/우 라벨 지원. */
-export declare function SSwitch({ value, leftLabel, rightLabel, label, disabled, onValueChange, className, style, }: SSwitchProps): import("react").JSX.Element;
+export declare function SSwitch({ value, leftLabel, rightLabel, disabled, onValueChange, className, style, }: SSwitchProps): import("react").JSX.Element;