sellmate-design-system-react 9.0.0-beta.24 → 9.0.0-beta.26

package/AGENTS.md

@@ -26,7 +26,7 @@
 
 | 분류 | 컴포넌트 |
 | --- | --- |
-| **버튼·링크** | `SButton` `SGhostButton` `SDropdownButton` `STextLink` `SSwitch` `SToggle` |
+| **버튼·링크** | `SButton` `SGhostButton` `SDropdownButton` `SSystemActionButton` `STextLink` `SSwitch` `SToggle` |
 | **입력 (폼)** | `SForm` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
 | **날짜·시간** | `SCalendar` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` |
 | **표·목록** | `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
@@ -152,7 +152,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | --- | --- | --- |
 | **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SPage`(제목 영역은 `header` prop) |
 | **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SForm` `SSplitter` `SScrollArea` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `STabs` `SStepper` `SPagination` `SDivider` |
-| **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SDropdownButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SImage` `SLinearProgress` `SCircleProgress` |
+| **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SDropdownButton` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SImage` `SLinearProgress` `SCircleProgress` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
 | **레이어** | 문서 흐름 **밖**에 떠서 그려진다. 어느 층에서 띄우든 레이아웃에 영향이 없다 | `SModal` `SActionModal` `SConfirmModal` `SPopup` `SDrawer` `SPopover` `STooltip` `SPortal` `SToast` `SLoadingModal` `SLoadingContainer` `SGuide` |
 
@@ -523,6 +523,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 라벨이 있는 일반 액션을 준다 | `SButton` | §3-5 |
 | 아이콘 하나로 뜻이 통하는 부가 조작을 준다 | `SGhostButton` | §3-5-5 |
 | 한 버튼에 여러 선택지를 매단다 | `SDropdownButton` | §3-5-4 |
+| GNB system 패널에서 한 줄짜리 행 액션을 준다 | `SSystemActionButton` | §3-5-7 |
 
 #### D. 화면을 담고 나눈다
 
@@ -1012,6 +1013,7 @@ const columns: STableColumn[] = [
 | **아이콘 하나로 뜻이 통하는 부가 조작** | **`SGhostButton`** — 라벨이 없는 아이콘 전용 버튼 (아래 3-5-5) |
 | 본문 속 이동 링크 | `STextLink` |
 | 메인 액션 + 부가 메뉴 | `SDropdownButton` |
+| **GNB system 패널의 한 줄 액션** | **`SSystemActionButton`** — 행 전체가 버튼인 표면형 (아래 3-5-7) |
 
 #### 3-5-1. 채움 버튼은 페이지당 개수 제한이 있다
 
@@ -1144,6 +1146,34 @@ const columns: STableColumn[] = [
 </div>
 ```
 
+#### 3-5-7. `SSystemActionButton` — GNB system 패널의 한 줄 액션
+
+**행 전체가 하나의 버튼**인 표면형 컨트롤이다. 아이콘 프레임 + 라벨 + 우측 액션이 한 줄에 붙고, hover 하면 표면색이 한 단계 바뀐다.
+
+| 상황 | 사용 |
+| --- | --- |
+| 페이지·모달의 일반 액션 | `SButton` — 라벨 폭만큼만 차지한다 |
+| 목록에서 항목 하나를 고르게 한다 | `SListItem` · `STree` (§3-7-6·§3-7-7) |
+| 좌측 내비게이션의 메뉴 | `SGnb` 의 `menus` (§4-1) |
+| **GNB system 패널에서 설정·연결 상태를 한 줄씩 쌓고, 그 줄을 눌러 들어가게 한다** | **`SSystemActionButton`** |
+
+**무엇이 그려지는지는 `type` 이 정한다.** 타입마다 다른 값만 `option` 으로 받으므로, 타입에 맞지 않는 `option` 은 타입 에러가 된다.
+
+| `type` | 선행 아이콘 | 라벨 | 우측 | 언제 |
+| --- | --- | --- | --- | --- |
+| `account` | `user` 고정 | `label` | 없음 | 로그인한 계정을 보여주고 계정 화면으로 보낼 때 |
+| `select` | `option.icon` (필수) | `label` | 화살표 | 눌러서 하위 화면으로 들어갈 때 |
+| `switch` | `option.icon` (필수) | `label` | `option.text` + 새로고침 | 지금 붙어 있는 대상을 갈아 끼울 때 |
+| `subSelect` | `option.icon` (필수) | `label` | `option.text` + 화살표 | 지금 선택돼 있는 값을 함께 보여줄 때 |
+| `status` | 없음 | 상태 태그(`option.color`·`option.label`) | 화살표 | 라벨 대신 상태 자체가 제목일 때 |
+
+- **`SPage` 본문에 직접 놓지 않는다.** 폭을 가득 채우는 행이라 페이지에 바로 놓으면 표처럼 보인다. GNB system 패널·`SDrawer`·`SPopover` 처럼 **좁은 폭이 정해진 자리**에 쌓는다. 행 사이 간격은 `--cmp-gnb-system-panel-gap` 이다.
+- **`color` 는 놓이는 표면을 따라간다** — 흰 면이면 `light`, 오션블루 면이면 `dark`, 네이비 면이면 `darker`. 배경과 다른 색을 고르면 버튼만 떠 보인다.
+- **상태는 default·hover 둘뿐이다.** 토큰에 selected 가 없으므로 "지금 열려 있는 항목"을 이 버튼으로 표시하지 않는다. 선택 상태가 필요한 자리면 `SGnb` 메뉴나 `SListItem`(§3-7-6) 이다.
+- **선행 아이콘이 비는 행은 없다.** `account` 는 `user` 고정, `status` 는 태그가 자리를 차지하고, 나머지는 `option.icon` 이 필수다.
+- **우측 아이콘은 `type` 이 정하므로 밖에서 바꾸지 않는다.** 화살표가 필요한데 문구가 없으면 `select`, 문구가 함께 필요하면 `subSelect` 다.
+- 높이·라운드·아이콘 크기·좌우 여백은 전부 토큰이 넣는다. 직접 주지 않는다.
+
 ### 3-6. 영역 나누기 — SDivider vs SSplitter
 
 | 상황 | 사용 |

package/dist/components/SChipFilter/README.md

@@ -11,8 +11,7 @@
 | `fields?` | `SChipFilterGroup[]` | — | 필터 정의 목록. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]`. 그룹은 rule로 함께 검증하거나 divider로 갈라 놓을 때 나눈다. |
 | `value?` | `SChipFilterValueMap` | — | 필터 값 맵 |
 | `activeKeys?` | `string[]` | — | 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접 넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 fixed·required 필드만 노출된 상태로 시작해 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다. fixed·required 필드는 이 배열에 없어도 항상 노출된다 |
-| `label?` | `string` | `'검색 필터'` | 좌측 태그 텍스트 |
-| `showLabel?` | `boolean` | `false` | 좌측 태그(label)·구분선 표시 여부 |
+| `label?` | `string` | — | 좌측 태그 텍스트. 지정하면 태그와 그 뒤 구분선이 함께 노출되고, 지정하지 않으면(undefined) 둘 다 생략된다 |
 | `showReset?` | `boolean` | `true` | 검색 초기화 링크 표시 여부 |
 | `disabled?` | `boolean` | `false` | 바 비활성 상태 |
 | `className?` | `string` | — |  |
@@ -24,7 +23,7 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: SChipFilterValueMap) => void` | 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 |
 | `onFilterChange` | `(detail: SChipFilterChangeDetail) => void` | 개별 필터 값 변경 |
-| `onSearch` | `(value: SChipFilterValueMap) => void` | 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른 칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom, clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도 그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. dirty 체크가 기본 적용되어 있어 — 마지막으로 실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고 닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔 onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상 실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) |
+| `onSearch` | `(value: SChipFilterValueMap) => void` | 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른 칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom, clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도 그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. dirty 체크가 기본 적용되어 있어 — 마지막으로 실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고 닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔 onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상 실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음). required 필드가 비어 있는 동안에도 마찬가지로 호출되지 않는다 — 정상 설정(내장 기본값 또는 defaultValue)이라면 원래 비워지지 않지만, defaultValue 없는 select-multi·keyword·custom에 required만 준 오설정에서는 "검색 초기화"·clearable이 값을 null로 비울 수 있어 이때의 안전장치다 |
 | `onActiveKeysChange` | `(keys: string[]) => void` | 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다. activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 |
 | `onReset` | `() => void` | "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋된 뒤 호출된다 |
 | `onAddFilter` | `(key: string) => void` | "필터 추가" 목록에서 항목을 골랐을 때 — activeKeys를 직접 제어 중이면 이 콜백에서 (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다. activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 |
@@ -35,7 +34,7 @@
 |--------|------|-------------|
 | `open` | `(key: string) => void` | 특정 필터 편집 팝오버를 엽니다. |
 | `reset` | `() => void` | 모든 필터 값을 초기화합니다. |
-| `validate` | `() => boolean` | 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. rule을 준 그룹이 없으면 항상 true. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
+| `validate` | `() => boolean` | 현재 값 기준으로 각 그룹의 rule을 만족하는지, 그리고 required 필드가 모두 비어 있지 않은지 반환합니다. rule을 준 그룹이 없고 required 필드도 모두 값이 있으면 항상 true. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
 
 ## Types
 
@@ -52,7 +51,8 @@ export interface SChipFilterGroup {
   /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
   tooltipMessage?: string;
   /** 이 그룹 앞에 구분선을 넣을지. 검증(rule)과 구분선은 별개라 — 묶어서 검증만 하고 싶으면
-   *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(showLabel의 구분선이 이미 있다) */
+   *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(label을 지정했다면 그 구분선이
+   *  이미 있다) */
   divider?: boolean;
 }
 ```

package/dist/components/SChipFilter/SChipFilter.d.ts

@@ -172,7 +172,8 @@ export interface SChipFilterGroup {
     /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
     tooltipMessage?: string;
     /** 이 그룹 앞에 구분선을 넣을지. 검증(rule)과 구분선은 별개라 — 묶어서 검증만 하고 싶으면
-     *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(showLabel의 구분선이 이미 있다) */
+     *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(label을 지정했다면 그 구분선이
+     *  이미 있다) */
     divider?: boolean;
 }
 export interface SChipFilterHandle {
@@ -180,7 +181,8 @@ export interface SChipFilterHandle {
     open: (key: string) => void;
     /** 모든 필터 값을 초기화합니다. */
     reset: () => void;
-    /** 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. rule을 준 그룹이 없으면 항상 true.
+    /** 현재 값 기준으로 각 그룹의 rule을 만족하는지, 그리고 required 필드가 모두 비어 있지 않은지
+     *  반환합니다. rule을 준 그룹이 없고 required 필드도 모두 값이 있으면 항상 true.
      *  경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
      *  이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) */
     validate: () => boolean;
@@ -202,7 +204,10 @@ export interface SChipFilterProps {
      *  실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고
      *  닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
      *  onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상
-     *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) */
+     *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음). required 필드가 비어 있는 동안에도
+     *  마찬가지로 호출되지 않는다 — 정상 설정(내장 기본값 또는 defaultValue)이라면 원래 비워지지
+     *  않지만, defaultValue 없는 select-multi·keyword·custom에 required만 준 오설정에서는 "검색
+     *  초기화"·clearable이 값을 null로 비울 수 있어 이때의 안전장치다 */
     onSearch?: (value: SChipFilterValueMap) => void;
     /** 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접
      *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면
@@ -218,10 +223,9 @@ export interface SChipFilterProps {
      *  (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다.
      *  activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 */
     onAddFilter?: (key: string) => void;
-    /** 좌측 태그 텍스트 */
+    /** 좌측 태그 텍스트. 지정하면 태그와 그 뒤 구분선이 함께 노출되고, 지정하지 않으면(undefined)
+     *  둘 다 생략된다 */
     label?: string;
-    /** 좌측 태그(label)·구분선 표시 여부 */
-    showLabel?: boolean;
     /** 검색 초기화 링크 표시 여부 */
     showReset?: boolean;
     /** 바 비활성 상태 */

package/dist/components/SIcon/README.md

@@ -48,6 +48,7 @@
  - [SSectionHeaderCard](../SSectionHeaderCard)
  - [SSelect](../SSelect)
  - [SStepper](../SStepper)
+ - [SSystemActionButton](../SSystemActionButton)
  - [STable](../STable)
  - [STag](../STag)
  - [STextLink](../STextLink)
@@ -88,6 +89,7 @@ graph TD;
   SSectionHeaderCard --> SIcon
   SSelect --> SIcon
   SStepper --> SIcon
+  SSystemActionButton --> SIcon
   STable --> SIcon
   STag --> SIcon
   STextLink --> SIcon

package/dist/components/SSystemActionButton/README.md

@@ -0,0 +1,129 @@
+# 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
+
+### Depends on
+
+- [SIcon](../SIcon)
+- [STag](../STag)
+
+### Graph
+
+```mermaid
+graph TD;
+  SSystemActionButton --> SIcon
+  SSystemActionButton --> STag
+  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,6 +9,7 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `columns?` | `STableColumn[]` | `[]` |  |
+| `headerGroups?` | `STableHeaderGroup[]` | — | 상위 그룹 헤더. 지정하면 기존 컬럼 헤더가 두 번째 행에 렌더링된다. |
 | `rows?` | `SRow[]` | `[]` |  |
 | `rowKey?` | `string` | `'id'` | 행 식별 필드 |
 | `selectable?` | `boolean` | `false` | 행 선택 체크박스 |
@@ -78,6 +79,21 @@ export type STableColumn = STableColumnBase &
   );
 ```
 
+### 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

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

@@ -147,6 +147,16 @@ export interface STableSort {
     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 {
     /** 행 선택 여부 */
@@ -171,6 +181,8 @@ export interface STableHandle {
 }
 export interface STableProps {
     columns?: STableColumn[];
+    /** 상위 그룹 헤더. 지정하면 기존 컬럼 헤더가 두 번째 행에 렌더링된다. */
+    headerGroups?: STableHeaderGroup[];
     rows?: SRow[];
     /** 행 식별 필드 */
     rowKey?: string;

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

@@ -1 +1 @@
-export { STable, type STableProps, type STableColumn, type STableColumnField, type STableSort, 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';

package/dist/components/STag/README.md

@@ -71,6 +71,7 @@ export const TAG_COLORS = [
  - [SConfirmModal](../SConfirmModal)
  - [SGhostButton](../SGhostButton)
  - [SGnb](../SGnb)
+ - [SSystemActionButton](../SSystemActionButton)
  - [STabs](../STabs)
  - [STextLink](../STextLink)
 
@@ -87,6 +88,7 @@ graph TD;
   SConfirmModal --> STag
   SGhostButton --> STag
   SGnb --> STag
+  SSystemActionButton --> STag
   STabs --> STag
   STextLink --> STag
   style STag fill:#f9f,stroke:#333,stroke-width:4px