sellmate-design-system-react 9.0.0-beta.9 → 9.0.0-beta.91

package/dist/components/SSlider/README.md

@@ -0,0 +1,86 @@
+# SSlider
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSlider
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `V` | — | 값 (제어). **`number` 면 단일, `[시작, 끝]` 이면 범위 슬라이더**가 된다 — 손잡이 개수와 `onValueChange` 가 돌려주는 모양이 이 값을 따른다. 범위는 두 손잡이가 서로를 넘어가지 않는다. |
+| `min?` | `number` | `0` | 최솟값 |
+| `max?` | `number` | `100` | 최댓값 |
+| `step?` | `number` | `1` | 한 칸 크기. 값은 `min` 에서 이 간격으로만 움직인다 |
+| `marks?` | `boolean \| SSliderMark[]` | — | 눈금. `true` 면 `step` 마다 점을 찍고, 배열이면 그 위치에만 찍는다(라벨을 함께 줄 수 있다). 고를 수 있는 값이 몇 개 안 될 때 어디서 멈추는지 보여 주는 용도다 — `step` 이 촘촘하면 `true` 대신 배열로 대표 위치만 준다. |
+| `showValue?` | `SSliderShowValue` | `'drag'` | 값 말풍선 표시 시점. - `drag` — 드래그·키보드 조작 중, 손잡이에 마우스를 올렸을 때만 보인다 - `always` — 늘 보인다. 값을 숫자로 따로 보여 주지 않는 자리에서 쓴다 - `none` — 보이지 않는다. 옆에 값을 따로 적어 둘 때 쓴다 `none` 이 아니면 말풍선 자리만큼 위쪽 공간을 미리 잡아 두어, 나타날 때 레이아웃이 밀리지 않는다. |
+| `formatValue?` | `(value: number) => string` | `String` | 말풍선·스크린리더에 읽히는 값 표기 (예: `v => \`${v}%\``) |
+| `size?` | `SFieldSize` | `'sm'` | 크기 — 다른 필드와 나란히 놓일 때 라벨과 높이를 맞추는 등급이다. 슬라이더 모양 자체는 같다. |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — 조작이 끝날 때(`onValueCommit` 시점)와 SForm 제출 시 검증 |
+| `name?` | `string` | — | 폼 연동용 name |
+| `status?` | `SFieldStatus` | — | 필드 상태 ('default' | 'pass' | 'error') |
+| `label?` | `string` | — | 레이블 텍스트. 손잡이의 접근성 이름으로도 쓰인다 |
+| `labelPosition?` | `SFieldLabelPosition` | — | 레이블 위치 — `top` 이면 라벨이 컨트롤 위에 선다 (SField 로 그대로 넘어간다). |
+| `subLabel?` | `string` | — | 보조 레이블 — 레이블 오른쪽 같은 줄에 붙는다 (SField 로 그대로 넘어간다). |
+| `labelWidth?` | `number \| string` | — | 레이블 너비 (숫자=px) |
+| `icon?` | `SIconName` | — | 레이블 영역 아이콘 |
+| `iconColor?` | `SColor` | — | 레이블 영역 아이콘 색상 |
+| `labelTooltip?` | `string` | — | 레이블 툴팁 텍스트 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
+| `hint?` | `string` | — | 하단 힌트 |
+| `error?` | `boolean` | — | 에러 상태 |
+| `errorMessage?` | `string` | — | 에러 메시지 |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급 · 숫자=px · CSS 길이. 기본은 부모 폭을 채운다. |
+| `disabled?` | `boolean` | `false` | 비활성 — 조작·포커스가 모두 막힌다 |
+| `readOnly?` | `boolean` | `false` | 읽기 전용 — 값은 그대로 보이고 키보드 포커스는 받지만 값이 바뀌지 않는다 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: V) => void` | 값 변경 (sdUpdate) — 드래그 중 매 step 마다 호출된다 |
+| `onValueCommit` | `(value: V) => void` | 조작이 끝났을 때 한 번 호출된다 (포인터를 놓을 때, 키보드로 한 칸 움직일 때). 값을 서버에 보내거나 목록을 다시 불러오는 등 **매 step 마다 하면 안 되는 일**은 여기서 한다. |
+
+## Types
+
+### SSliderValue
+
+```ts
+/** 단일 값은 `number`, 범위는 `[시작, 끝]` */
+export type SSliderValue = number | [number, number];
+```
+
+### SSliderMark
+
+```ts
+/** 눈금 하나 */
+export interface SSliderMark {
+  /** 눈금 위치 값 (`min`~`max`) */
+  value: number;
+  /** 눈금 아래 라벨. 없으면 점만 찍힌다 */
+  label?: string;
+}
+```
+
+### SSliderShowValue
+
+```ts
+/** 값 말풍선을 언제 보일지 */
+export type SSliderShowValue = 'none' | 'drag' | 'always';
+```
+
+## Dependencies
+
+### Depends on
+
+- [SField](../SField)
+
+### Graph
+
+```mermaid
+graph TD;
+  SSlider --> SField
+  style SSlider fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SSlider/SSlider.d.ts

@@ -0,0 +1,149 @@
+import { type CSSProperties, type ReactElement, type RefAttributes } from 'react';
+import { type SFieldSize, type SFieldStatus, type SFieldLabelPosition } from '../SField';
+import { type SIconName } from '../SIcon';
+import { type STooltipProps } from '../STooltip';
+import { type SColor } from '../../lib/color';
+import { type Rule } from '../../lib/form';
+import { type SFieldWidth } from '../../lib/field-width';
+/** 단일 값은 `number`, 범위는 `[시작, 끝]` */
+export type SSliderValue = number | [number, number];
+/** 값 말풍선을 언제 보일지 */
+export type SSliderShowValue = 'none' | 'drag' | 'always';
+/** 눈금 하나 */
+export interface SSliderMark {
+    /** 눈금 위치 값 (`min`~`max`) */
+    value: number;
+    /** 눈금 아래 라벨. 없으면 점만 찍힌다 */
+    label?: string;
+}
+export interface SSliderProps<V extends SSliderValue = number> {
+    /**
+     * 값 (제어). **`number` 면 단일, `[시작, 끝]` 이면 범위 슬라이더**가 된다 —
+     * 손잡이 개수와 `onValueChange` 가 돌려주는 모양이 이 값을 따른다.
+     * 범위는 두 손잡이가 서로를 넘어가지 않는다.
+     */
+    value?: V;
+    /** 값 변경 (sdUpdate) — 드래그 중 매 step 마다 호출된다 */
+    onValueChange?: (value: V) => void;
+    /**
+     * 조작이 끝났을 때 한 번 호출된다 (포인터를 놓을 때, 키보드로 한 칸 움직일 때).
+     * 값을 서버에 보내거나 목록을 다시 불러오는 등 **매 step 마다 하면 안 되는 일**은 여기서 한다.
+     */
+    onValueCommit?: (value: V) => void;
+    /** 최솟값 */
+    min?: number;
+    /** 최댓값 */
+    max?: number;
+    /** 한 칸 크기. 값은 `min` 에서 이 간격으로만 움직인다 */
+    step?: number;
+    /**
+     * 눈금. `true` 면 `step` 마다 점을 찍고, 배열이면 그 위치에만 찍는다(라벨을 함께 줄 수 있다).
+     * 고를 수 있는 값이 몇 개 안 될 때 어디서 멈추는지 보여 주는 용도다 —
+     * `step` 이 촘촘하면 `true` 대신 배열로 대표 위치만 준다.
+     */
+    marks?: boolean | SSliderMark[];
+    /**
+     * 값 말풍선 표시 시점.
+     * - `drag` — 드래그·키보드 조작 중, 손잡이에 마우스를 올렸을 때만 보인다
+     * - `always` — 늘 보인다. 값을 숫자로 따로 보여 주지 않는 자리에서 쓴다
+     * - `none` — 보이지 않는다. 옆에 값을 따로 적어 둘 때 쓴다
+     *
+     * `none` 이 아니면 말풍선 자리만큼 위쪽 공간을 미리 잡아 두어, 나타날 때 레이아웃이 밀리지 않는다.
+     */
+    showValue?: SSliderShowValue;
+    /** 말풍선·스크린리더에 읽히는 값 표기 (예: `v => \`${v}%\``) */
+    formatValue?: (value: number) => string;
+    /**
+     * 크기 — 다른 필드와 나란히 놓일 때 라벨과 높이를 맞추는 등급이다. 슬라이더 모양 자체는 같다.
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    size?: SFieldSize;
+    /** 유효성 규칙 — 조작이 끝날 때(`onValueCommit` 시점)와 SForm 제출 시 검증 */
+    rules?: Rule[];
+    /** 폼 연동용 name */
+    name?: string;
+    /**
+     * 필드 상태 ('default' | 'pass' | 'error')
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    status?: SFieldStatus;
+    /** 레이블 텍스트. 손잡이의 접근성 이름으로도 쓰인다 */
+    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;
+    /**
+     * 레이블 너비 (숫자=px)
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    labelWidth?: number | string;
+    /**
+     * 레이블 영역 아이콘
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    icon?: SIconName;
+    /**
+     * 레이블 영역 아이콘 색상
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    iconColor?: SColor;
+    /**
+     * 레이블 툴팁 텍스트
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    labelTooltip?: string;
+    /**
+     * 레이블 툴팁 상세 옵션
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    labelTooltipProps?: Partial<STooltipProps>;
+    /** 하단 힌트 */
+    hint?: string;
+    /** 에러 상태 */
+    error?: boolean;
+    /** 에러 메시지 */
+    errorMessage?: string;
+    /**
+     * 컨트롤 너비 — 폭 등급 · 숫자=px · CSS 길이. 기본은 부모 폭을 채운다.
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    width?: SFieldWidth;
+    /** 비활성 — 조작·포커스가 모두 막힌다 */
+    disabled?: boolean;
+    /** 읽기 전용 — 값은 그대로 보이고 키보드 포커스는 받지만 값이 바뀌지 않는다 */
+    readOnly?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SSlider — 끌어서 수치 하나 또는 범위를 고르는 필드 (Radix Slider 기반).
+ * SField 를 테두리 없이 두르고, 라벨·힌트·에러·SForm 검증은 다른 필드와 같게 동작한다.
+ */
+export declare const SSlider: <V extends SSliderValue = number>(props: SSliderProps<V> & RefAttributes<HTMLDivElement>) => ReactElement;

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

@@ -0,0 +1 @@
+export { SSlider, type SSliderProps, type SSliderValue, type SSliderShowValue, type SSliderMark, } from './SSlider';

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;

package/dist/components/SSystemActionButton/README.md

@@ -0,0 +1,246 @@
+# SSystemActionButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSystemActionButtonAccount
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'account'` | — | 계정 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option` | `SSystemActionButtonAccountOption` | — | 누르면 뜨는 계정 리스트박스. **필수다** — 계정 행은 늘 이 패널의 트리거이고, 눌러도 아무것도 뜨지 않는 계정 행은 없다. 아이콘은 `user` 로 고정이라 여기서 받지 않는다. |
+
+### SSystemActionButtonBase
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SSystemActionButtonColor` | — | 색상(놓이는 표면). light = 흰 면, dark = 오션블루 면, darker = 네이비 면. 기본 `'light'` |
+| `disabled?` | `boolean` | — | 비활성 여부. 기본 `false` |
+
+### SSystemActionButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'account' \| 'select' \| 'switch' \| 'subSelect' \| 'status'` | — | 계정 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option?` | `<union 5종>` | — | 누르면 뜨는 계정 리스트박스. **필수다** — 계정 행은 늘 이 패널의 트리거이고, 눌러도 아무것도 뜨지 않는 계정 행은 없다. 아이콘은 `user` 로 고정이라 여기서 받지 않는다. |
+
+### SSystemActionButtonSelect
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'select'` | — | 화살표만 붙는 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option?` | `SSystemActionButtonIconOption` | — | 선행 아이콘. 아이콘 없이 라벨만 두는 행이면 통째로 생략한다 |
+
+### SSystemActionButtonStatus
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'status'` | — | 라벨 자리에 상태 태그가 들어가는 행 |
+| `label?` | `never` | — | 태그가 라벨 자리를 차지하므로 받지 않는다 |
+| `option` | `SSystemActionButtonStatusOption` | — | 상태 태그 + 고를 목록. **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거다. |
+
+### SSystemActionButtonSubSelect
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'subSelect'` | — | 우측에 지금 선택된 값이 붙는 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option` | `SSystemActionButtonSubSelectOption` | — | 선행 아이콘 + 우측 값 + 고를 목록 |
+
+### SSystemActionButtonSwitch
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'switch'` | — | 우측에 보조 조작 문구가 붙는 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option?` | `SSystemActionButtonTextOption` | — | 선행 아이콘 + 우측 액션 텍스트. 둘 다 두지 않으면 통째로 생략한다 |
+
+### SSystemActionButtonText
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'switch' \| 'subSelect'` | — | 우측에 보조 조작 문구가 붙는 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option?` | `SSystemActionButtonTextOption \| SSystemActionButtonSubSelectOption` | — | 선행 아이콘 + 우측 액션 텍스트. 둘 다 두지 않으면 통째로 생략한다 |
+
+## Types
+
+### SSystemActionButtonAccountOption
+
+```ts
+/**
+ * `account` 타입의 option — 행을 눌렀을 때 뜨는 계정 리스트박스.
+ * 내용(이메일·이름·권한·행들)은 `SAccountListBox` 와 같다.
+ *
+ * **뜨는 자리는 받지 않는다.** 계정 행이 놓인 자리가 정한다 — 판이면 행 위로 · 왼쪽 끝에 맞춰,
+ * 전폭 상단바면 행 아래로 · 오른쪽 끝에 맞춰 펼친다(시안). 화면마다 고를 값이 아니라,
+ * prop 으로 열면 같은 계정 행이 앱마다 다른 방향으로 뜬다.
+ */
+export interface SSystemActionButtonAccountOption extends SAccountListBoxContent {
+  /**
+   * 리스트박스 열림 상태를 밖에서 쥔다(controlled). 주지 않으면 버튼이 스스로 여닫는다.
+   * 행을 담은 쪽이 닫아야 하는 자리가 있어 열어 둔 통로다 — 리스트박스는 SPortal 로 떠 있어
+   * 트리거가 화면에서 빠져도(GNB 를 접으면 메뉴 컬럼이 미끄러져 나간다) 따라 사라지지 않는다.
+   */
+  open?: boolean;
+  /** 리스트박스 열림/닫힘 변경 */
+  onOpenChange?: (open: boolean) => void;
+}
+```
+
+### SSystemActionButtonColor
+
+```ts
+export type SSystemActionButtonColor = (typeof SYSTEM_ACTION_BUTTON_COLORS)[number];
+```
+
+### SSystemActionButtonIconOption
+
+```ts
+/** 선행 아이콘만 받는 타입(`select`)의 option */
+export interface SSystemActionButtonIconOption {
+  /** 선행 아이콘명. 주지 않으면 아이콘 프레임 없이 라벨부터 시작한다 */
+  icon?: SIconName;
+}
+```
+
+### SSystemActionButtonStatusOption
+
+```ts
+/**
+ * `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 + 고를 목록.
+ *
+ * `options` 는 **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거이고, 지금 상태(`value`)에
+ * 해당하는 칸의 색·이름이 곧 태그가 된다. 보여주기만 하는 상태 줄이 필요하면 이 버튼이 아니라
+ * `STag` 를 쓴다.
+ */
+export interface SSystemActionButtonStatusOption {
+  /** 지금 상태. `options` 에서 같은 `value` 를 찾아 그 색·이름으로 태그를 그린다 */
+  value?: string;
+  /** 고를 수 있는 상태. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+  options: SSystemActionButtonStatusMenuOption[];
+  /** 메뉴에서 상태를 고름. 고르면 메뉴가 닫힌다 */
+  onChange?: (value: string) => void;
+}
+```
+
+### SSystemActionButtonSubSelectOption
+
+```ts
+/**
+ * `subSelect` 타입의 option — 지금 값 + 고를 목록.
+ *
+ * `options` 는 **필수다** — `subSelect` 는 "지금 값이 적혀 있고 눌러서 바꾸는 행"이라, 눌러도
+ * 아무것도 뜨지 않으면 그것은 `select`(눌러 들어가는 행)이지 `subSelect` 가 아니다.
+ */
+export interface SSystemActionButtonSubSelectOption extends SSystemActionButtonIconOption {
+  /**
+   * 선행 아이콘. `select` · `switch` 와 달리 **필수다** — 우측이 지금 값에 쓰이는 행이라
+   * 라벨 왼쪽까지 비면 무엇에 대한 값인지 가리키는 것이 라벨 글자 하나뿐이 된다.
+   */
+  icon: SIconName;
+  /**
+   * 지금 값. `options` 에서 같은 `value` 를 찾아 우측에 그 `label` 로 적는다
+   * (못 찾으면 `value` 가 그대로 남는다).
+   */
+  value?: string;
+  /** 고를 수 있는 값. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+  options: SSystemActionButtonMenuOption[];
+  /** 메뉴에서 값을 고름. 고르면 메뉴가 닫힌다 */
+  onChange?: (value: string) => void;
+}
+```
+
+### SSystemActionButtonTextOption
+
+```ts
+/** 우측 액션 텍스트까지 받는 타입(`switch`)의 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;
+```
+
+### SSystemActionButtonStatusMenuOption
+
+```ts
+/** 상태 메뉴의 한 칸 — 점과 글자가 그 상태의 색으로 함께 물든다 */
+export interface SSystemActionButtonStatusMenuOption extends SSystemActionButtonMenuOption {
+  /** 상태 색. 기본 `'blue'` */
+  color?: STagColor;
+}
+```
+
+### SSystemActionButtonMenuOption
+
+```ts
+/** 값 고르기 메뉴의 한 칸 */
+export interface SSystemActionButtonMenuOption {
+  /** 값. `option.value` 와 맞춰 지금 값을 가린다 */
+  value: string;
+  /** 화면에 적히는 이름 */
+  label: string;
+}
+```
+
+## Dependencies
+
+### Used by
+
+ - [SGnbSystem](../SGnbSystem)
+
+### Depends on
+
+- [SAccountListBox](../SAccountListBox)
+- [SIcon](../SIcon)
+- [STag](../STag)
+
+### Graph
+
+```mermaid
+graph TD;
+  SSystemActionButton --> SAccountListBox
+  SSystemActionButton --> SIcon
+  SSystemActionButton --> STag
+  SGnbSystem --> SSystemActionButton
+  style SSystemActionButton fill:#f9f,stroke:#333,stroke-width:4px
+```