sellmate-design-system-react 9.0.0-beta.31 → 9.0.0-beta.32

package/dist/components/SGnb/SGnb.d.ts

@@ -12,6 +12,9 @@ import { type SGnbType, type SGnbHeader, type SGnbColor, type SGnbMenuItem } fro
  * `folded` 는 GNB 의 접힘 상태가 아니라 **그 자리가 접힌 레일인지**다. panel 은 두 곳에 놓이고
  * (메뉴 컬럼 바닥 · 접힘 레일 바닥) 각 자리가 자기 형태를 못 박으므로, 접는 동안 아직 미끄러져
  * 나가는 중인 메뉴 컬럼의 패널이 min 형태로 튀지 않는다.
+ *
+ * 그래서 fix 로 접혀 있는 동안 슬롯 내용은 **두 자리에 함께 마운트된다** — 미끄러져 나간 메뉴
+ * 컬럼(잔상)과 레일 바닥(실물). `active` 가 그 둘을 가른다.
  */
 export interface SGnbSystemContextValue {
     /** GNB 색 */
@@ -20,6 +23,15 @@ export interface SGnbSystemContextValue {
     folded: boolean;
     /** 이 자리가 세로 판인지 전폭 상단바인지 */
     placement: SGnbSystemPlacement;
+    /**
+     * 이 자리가 지금 화면에 살아 있는 자리인가. 접힌 GNB 의 메뉴 컬럼처럼 밖으로 미끄러져 나가
+     * 잔상으로만 남는 자리는 `false` 다.
+     *
+     * 잔상에서도 계정 리스트박스 같은 **떠 있는 층은 함께 숨지 않는다** — SPortal 로 문서 최상단에
+     * 그려져 컬럼의 `visibility: hidden` 이 닿지 않기 때문이다. 그래서 잔상이 된 자리는 열어 둔
+     * 것을 스스로 닫아야 하고, 그 신호가 이 값이다.
+     */
+    active: boolean;
 }
 export declare const SGnbSystemContext: import("react").Context<SGnbSystemContextValue | null>;
 export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {

package/dist/components/SGnbSystem/README.md

@@ -9,9 +9,8 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `color?` | `SGnbSystemColor` | — | 색상(패널 표면). light = 흰 면, dark = 오션블루 면. 미지정 시 자기를 담은 SGnb 의 color 를 따른다(단독으로 쓰면 `'light'`). |
-| `folded?` | `boolean` | — | 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다. 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. `placement="top"` 에서는 뜻이 없다. |
-| `placement?` | `SGnbSystemPlacement` | — | 놓이는 자리: `panel` = GNB 바닥의 세로 판, `top` = 전폭 상단바 위의 가로 한 줄. 미지정 시 자기를 담은 SGnb 가 `header` 로 정해 내려준다(fix → panel, full → top). |
-| `actions?` | `SGnbSystemAction[]` | — | 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외). 판에서는 맨 위에 쌓이고, 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다. 접히면 자리가 없어 렌더되지 않는다. |
+| `folded?` | `boolean` | — | 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다. 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. 상단바 자리에서는 뜻이 없다. |
+| `actions?` | `SGnbSystemAction[]` | — | 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외 · 계정 행은 `account` 로 따로 준다). 판에서는 맨 위에 쌓이고, 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다. 접히면 자리가 없어 렌더되지 않는다. |
 | `domain?` | `string` | — | 도메인 태그 텍스트. 접히면 자리가 없어 렌더되지 않는다 |
 | `alert?` | `SGnbSystemAlert` | — | 알림 버튼. 없으면 렌더하지 않는다. 판에서는 설정과 나란히 서면 남는 폭을 먹고 혼자면 폭을 다 먹는다. 상단바에서는 자리가 넉넉하지 않아 라벨 없이 아이콘+개수만 선다. |
 | `setting?` | `SGnbSystemSetting` | — | 설정 버튼. 없으면 렌더하지 않는다. 판에서는 알림과 나란히 서면 제 폭만 갖고 혼자면 폭을 다 먹고, 상단바에서는 라벨 없이 아이콘만 선다. 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다. |
@@ -25,20 +24,21 @@
 export type SGnbSystemColor = (typeof GNB_SYSTEM_COLORS)[number];
 ```
 
-### SGnbSystemPlacement
-
-```ts
-export type SGnbSystemPlacement = (typeof GNB_SYSTEM_PLACEMENTS)[number];
-```
-
 ### SGnbSystemAction
 
 ```ts
 /**
  * 패널 상단에 쌓이는 행 하나. `SSystemActionButton` 의 props 를 그대로 받는다 —
  * 단 `color` 는 패널이 정하므로 받지 않고, 목록 key 로 쓸 `value` 만 더한다.
+ *
+ * `type: 'account'` 는 받지 않는다. 계정 행은 이 패널에 **하나뿐**이고 서는 자리도 맨 아래로
+ * 정해져 있어(§3-5-8) `account` prop 이 따로 있다 — 여기로도 받으면 계정 행이 둘인 패널이
+ * 만들어지고, 그중 하나는 자리가 틀린다.
  */
-export type SGnbSystemAction = DistributiveOmit<SSystemActionButtonProps, 'color'> & {
+export type SGnbSystemAction = DistributiveOmit<
+  Exclude<SSystemActionButtonProps, { type: 'account' }>,
+  'color'
+> & {
   /** 목록 key. 없으면 순서를 key 로 쓴다 */
   value?: string;
 };
@@ -80,8 +80,22 @@ export interface SGnbSystemSetting {
 export interface SGnbSystemAccount {
   /** 계정 이름 */
   label?: string;
-  /** 클릭 */
+  /** 클릭. 패널은 어차피 열리므로, 여는 것 말고 따로 할 일이 있을 때만 준다 */
   onClick?: () => void;
+  /**
+   * 계정 리스트박스가 열리고 닫힐 때. 여닫는 것은 계정 행이 스스로 하므로 **그 사실을 알아야 할
+   * 때만** 준다 — 열려 있는 동안 다른 층을 접어 두거나, 연 것을 기록하는 화면이 그렇다.
+   *
+   * 앱이 누르지 않은 닫힘도 온다: `header="fix"` 에서 GNB 를 접거나 펴면 계정 행이 다른 자리로
+   * 옮겨 서므로 패널이 닫히고 `false` 가 온다.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 누르면 뜨는 계정 리스트박스(`SAccountListBox`) 내용. **필수다** — 계정 행은 늘 이 패널의
+   * 트리거이고, 눌러도 아무것도 뜨지 않는 계정 행은 없다.
+   * 뜨는 방향은 패널이 놓인 자리가 정하므로 앱이 넘기지 않는다.
+   */
+  listBox: SAccountListBoxContent;
 }
 ```
 
@@ -109,21 +123,11 @@ export interface SGnbSystemAccount {
 export const GNB_SYSTEM_COLORS = ['light', 'dark'] as const;
 ```
 
-### GNB_SYSTEM_PLACEMENTS
-
-```ts
-/**
- * 조각들이 놓이는 자리. GNB 의 `header` 가 정하므로 앱이 고르지 않는다.
- * - `panel` — GNB 바닥에 깔리는 세로 판 (header="fix"). 접히면 48px 레일용 min 형태가 된다.
- * - `top`   — 레이아웃 전폭 상단바 위 (header="full"). 판을 깔지 않고 가로 한 줄로 선다.
- */
-export const GNB_SYSTEM_PLACEMENTS = ['panel', 'top'] as const;
-```
-
 ## Dependencies
 
 ### Depends on
 
+- [SAccountListBox](../SAccountListBox)
 - [SGnb](../SGnb)
 - [SIcon](../SIcon)
 - [SSystemActionButton](../SSystemActionButton)
@@ -132,6 +136,7 @@ export const GNB_SYSTEM_PLACEMENTS = ['panel', 'top'] as const;
 
 ```mermaid
 graph TD;
+  SGnbSystem --> SAccountListBox
   SGnbSystem --> SGnb
   SGnbSystem --> SIcon
   SGnbSystem --> SSystemActionButton

package/dist/components/SGnbSystem/SGnbSystem.d.ts

@@ -1,13 +1,20 @@
 import { type HTMLAttributes } from 'react';
+import { type SAccountListBoxContent } from '../SAccountListBox';
 import { type SSystemActionButtonProps } from '../SSystemActionButton';
-import { type SGnbSystemColor, type SGnbSystemPlacement } from './gnbSystem.config';
+import { type SGnbSystemColor } from './gnbSystem.config';
 /** 유니온을 유지한 채 키를 걷어낸다 — 그냥 Omit 하면 판별 유니온이 한 덩어리로 뭉개진다. */
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 /**
  * 패널 상단에 쌓이는 행 하나. `SSystemActionButton` 의 props 를 그대로 받는다 —
  * 단 `color` 는 패널이 정하므로 받지 않고, 목록 key 로 쓸 `value` 만 더한다.
+ *
+ * `type: 'account'` 는 받지 않는다. 계정 행은 이 패널에 **하나뿐**이고 서는 자리도 맨 아래로
+ * 정해져 있어(§3-5-8) `account` prop 이 따로 있다 — 여기로도 받으면 계정 행이 둘인 패널이
+ * 만들어지고, 그중 하나는 자리가 틀린다.
  */
-export type SGnbSystemAction = DistributiveOmit<SSystemActionButtonProps, 'color'> & {
+export type SGnbSystemAction = DistributiveOmit<Exclude<SSystemActionButtonProps, {
+    type: 'account';
+}>, 'color'> & {
     /** 목록 key. 없으면 순서를 key 로 쓴다 */
     value?: string;
 };
@@ -34,8 +41,22 @@ export interface SGnbSystemSetting {
 export interface SGnbSystemAccount {
     /** 계정 이름 */
     label?: string;
-    /** 클릭 */
+    /** 클릭. 패널은 어차피 열리므로, 여는 것 말고 따로 할 일이 있을 때만 준다 */
     onClick?: () => void;
+    /**
+     * 계정 리스트박스가 열리고 닫힐 때. 여닫는 것은 계정 행이 스스로 하므로 **그 사실을 알아야 할
+     * 때만** 준다 — 열려 있는 동안 다른 층을 접어 두거나, 연 것을 기록하는 화면이 그렇다.
+     *
+     * 앱이 누르지 않은 닫힘도 온다: `header="fix"` 에서 GNB 를 접거나 펴면 계정 행이 다른 자리로
+     * 옮겨 서므로 패널이 닫히고 `false` 가 온다.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * 누르면 뜨는 계정 리스트박스(`SAccountListBox`) 내용. **필수다** — 계정 행은 늘 이 패널의
+     * 트리거이고, 눌러도 아무것도 뜨지 않는 계정 행은 없다.
+     * 뜨는 방향은 패널이 놓인 자리가 정하므로 앱이 넘기지 않는다.
+     */
+    listBox: SAccountListBoxContent;
 }
 export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
     /**
@@ -45,16 +66,12 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
     color?: SGnbSystemColor;
     /**
      * 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다.
-     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. `placement="top"` 에서는 뜻이 없다.
+     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. 상단바 자리에서는 뜻이 없다.
      */
     folded?: boolean;
     /**
-     * 놓이는 자리: `panel` = GNB 바닥의 세로 판, `top` = 전폭 상단바 위의 가로 한 줄.
-     * 미지정 시 자기를 담은 SGnb 가 `header` 로 정해 내려준다(fix → panel, full → top).
-     */
-    placement?: SGnbSystemPlacement;
-    /**
-     * 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외). 판에서는 맨 위에 쌓이고,
+     * 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외 · 계정 행은 `account` 로
+     * 따로 준다). 판에서는 맨 위에 쌓이고,
      * 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다.
      * 접히면 자리가 없어 렌더되지 않는다.
      */
@@ -78,7 +95,7 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
 /**
  * SGnbSystem — GNB 의 system 조각들(액션 · 도메인 · 알림 · 설정 · 계정).
  *
- * 어디에 놓이느냐(`placement`)로 두 형태가 있고, SGnb 안에서는 그 값을 `header` 가 정해 내려준다.
+ * 어디에 놓이느냐로 두 형태가 있고, 그 자리는 담은 SGnb 의 `header` 가 정해 내려준다(앱이 고르지 않는다).
  * - `panel` (header="fix") — GNB 바닥에 깔리는 세로 판. 위에서부터 [행 목록(`actions`)] · 구분선 ·
  *   [도메인 태그] · [알림 | 설정] · [계정] 을 쌓는다.
  * - `top` (header="full") — 레이아웃 전폭 상단바의 오른쪽 끝에 서는 가로 한 줄.
@@ -101,14 +118,16 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
  * 접힌 패널은 렌더되지 않으므로, 접힌 상태에서도 닿아야 하는 것은 SGnb 의 `foldedTop`·`foldedFooter` 에 둔다.
  * 상단바는 접어도 남으므로 `top` 에는 접힘 형태가 없다.
  *
- * `alert.count` 가 1 이상이면 벨이 울리는 아이콘(`alert`)과 강조색으로 바뀐다 — light 는 파랑,
+ * `alert.count` 가 1 이상이면 벨이 울리는 아이콘(`bellRinging`)과 강조색으로 바뀐다 — light 는 파랑,
  * 어두운 면은 노랑(토큰이 정한다). 0 이거나 없으면 조용한 벨(`bell`)에 기본 색이다.
  *
  * 색은 놓인 면을 따른다: 판 위는 `light`/`dark`(오션블루 판), 판 없이 상단바 면에 바로 얹는 `top` 의
  * dark 는 한 단계 어두운 `darker`(네이비) 색표다 — GNB_SYSTEM_TOP_COLOR_CONFIG 가 그 대응을 쥔다.
  *
- * SGnb 의 `system` 슬롯에 넣으면 `color`·`folded`·`placement` 를 GNB 에서 받아오므로 앱이 다시 넘길
- * 필요가 없다. 단독으로 쓰면 직접 준다. 판은 폭이 늘 부모를 가득 채우고, 상단바 줄은 내용 폭만 갖는다.
+ * **놓이는 자리(`placement`)는 prop 이 아니다** — 자기를 담은 SGnb 가 `header` 로 정해 내려준다.
+ * 앱이 고르면 세로 판 자리에 가로 한 줄이 서는 조합이 만들어지고, 그것을 고를 이유가 있는 화면은 없다.
+ * `color`·`folded` 도 슬롯 안에서는 GNB 가 내려주므로 다시 넘기지 않는다.
+ * 판은 폭이 늘 부모를 가득 채우고, 상단바 줄은 내용 폭만 갖는다.
  */
 export declare const SGnbSystem: import("react").ForwardRefExoticComponent<SGnbSystemProps & import("react").RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/SIcon/README.md

@@ -20,6 +20,7 @@
 
 ### Used by
 
+ - [SAccountListBox](../SAccountListBox)
  - [SButton](../SButton)
  - [SCallout](../SCallout)
  - [SCheckbox](../SCheckbox)
@@ -62,6 +63,7 @@
 
 ```mermaid
 graph TD;
+  SAccountListBox --> SIcon
   SButton --> SIcon
   SCallout --> SIcon
   SCheckbox --> SIcon

package/dist/components/SIcon/icons.gen.d.ts

@@ -3,6 +3,7 @@ export type IconRenderProps = {
     size?: number | string;
 } & SVGProps<SVGSVGElement>;
 export declare const ICONS: {
+    readonly account: (p: IconRenderProps) => import("react").JSX.Element;
     readonly add: (p: IconRenderProps) => import("react").JSX.Element;
     readonly alert: (p: IconRenderProps) => import("react").JSX.Element;
     readonly alignKorean: (p: IconRenderProps) => import("react").JSX.Element;
@@ -15,6 +16,7 @@ export declare const ICONS: {
     readonly attachFile: (p: IconRenderProps) => import("react").JSX.Element;
     readonly barcode: (p: IconRenderProps) => import("react").JSX.Element;
     readonly bell: (p: IconRenderProps) => import("react").JSX.Element;
+    readonly bellRinging: (p: IconRenderProps) => import("react").JSX.Element;
     readonly bill: (p: IconRenderProps) => import("react").JSX.Element;
     readonly board: (p: IconRenderProps) => import("react").JSX.Element;
     readonly box: (p: IconRenderProps) => import("react").JSX.Element;

package/dist/components/SPortal/README.md

@@ -52,6 +52,7 @@ export type SPortalAlign = 'start' | 'center' | 'end';
 
 ### Used by
 
+ - [SAccountListBox](../SAccountListBox)
  - [SChipInput](../SChipInput)
  - [SSelect](../SSelect)
 
@@ -59,6 +60,7 @@ export type SPortalAlign = 'start' | 'center' | 'end';
 
 ```mermaid
 graph TD;
+  SAccountListBox --> SPortal
   SChipInput --> SPortal
   SSelect --> SPortal
   style SPortal fill:#f9f,stroke:#333,stroke-width:4px

package/dist/components/SSystemActionButton/README.md

@@ -10,7 +10,7 @@
 |------|------|---------|-------------|
 | `type` | `'account'` | — | 계정 행 |
 | `label?` | `string` | — | 라벨 텍스트 |
-| `option?` | `never` | — | 아이콘이 `user` 로 고정이라 받을 것이 없다 |
+| `option` | `SSystemActionButtonAccountOption` | — | 누르면 뜨는 계정 리스트박스. **필수다** — 계정 행은 늘 이 패널의 트리거이고, 눌러도 아무것도 뜨지 않는 계정 행은 없다. 아이콘은 `user` 로 고정이라 여기서 받지 않는다. |
 
 ### SSystemActionButtonBase
 
@@ -39,20 +39,53 @@
 |------|------|---------|-------------|
 | `type` | `'status'` | — | 라벨 자리에 상태 태그가 들어가는 행 |
 | `label?` | `never` | — | 태그가 라벨 자리를 차지하므로 받지 않는다 |
-| `option?` | `SSystemActionButtonStatusOption` | — | 상태 태그 |
+| `option` | `SSystemActionButtonStatusOption` | — | 상태 태그 + 고를 목록. **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거다. |
 
-### SSystemActionButtonText
+### SSystemActionButtonSubSelect
 
 #### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `type` | `'switch' \| 'subSelect'` | — | 우측에 문구가 붙는 행. switch = 보조 조작 문구, subSelect = 지금 선택된 값 |
+| `type` | `'subSelect'` | — | 우측에 지금 선택된 값이 붙는 행 |
+| `label?` | `string` | — | 라벨 텍스트 |
+| `option` | `SSystemActionButtonSubSelectOption` | — | 선행 아이콘 + 우측 값 + 고를 목록 |
+
+### SSystemActionButtonSwitch
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'switch'` | — | 우측에 보조 조작 문구가 붙는 행 |
 | `label?` | `string` | — | 라벨 텍스트 |
 | `option` | `SSystemActionButtonTextOption` | — | 선행 아이콘 + 우측 액션 텍스트 |
 
 ## Types
 
+### SSystemActionButtonAccountOption
+
+```ts
+/**
+ * `account` 타입의 option — 행을 눌렀을 때 뜨는 계정 리스트박스.
+ * 내용(이메일·이름·권한·행들)은 `SAccountListBox` 와 같다.
+ *
+ * **뜨는 자리는 받지 않는다.** 계정 행이 놓인 자리가 정한다 — 판이면 행 위로 · 왼쪽 끝에 맞춰,
+ * 전폭 상단바면 행 아래로 · 오른쪽 끝에 맞춰 펼친다(시안). 화면마다 고를 값이 아니라,
+ * prop 으로 열면 같은 계정 행이 앱마다 다른 방향으로 뜬다.
+ */
+export interface SSystemActionButtonAccountOption extends SAccountListBoxContent {
+  /**
+   * 리스트박스 열림 상태를 밖에서 쥔다(controlled). 주지 않으면 버튼이 스스로 여닫는다.
+   * 행을 담은 쪽이 닫아야 하는 자리가 있어 열어 둔 통로다 — 리스트박스는 SPortal 로 떠 있어
+   * 트리거가 화면에서 빠져도(GNB 를 접으면 메뉴 컬럼이 미끄러져 나간다) 따라 사라지지 않는다.
+   */
+  open?: boolean;
+  /** 리스트박스 열림/닫힘 변경 */
+  onOpenChange?: (open: boolean) => void;
+}
+```
+
 ### SSystemActionButtonColor
 
 ```ts
@@ -72,12 +105,42 @@ export interface SSystemActionButtonIconOption {
 ### SSystemActionButtonStatusOption
 
 ```ts
-/** `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 */
+/**
+ * `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 + 고를 목록.
+ *
+ * `options` 는 **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거이고, 지금 상태(`value`)에
+ * 해당하는 칸의 색·이름이 곧 태그가 된다. 보여주기만 하는 상태 줄이 필요하면 이 버튼이 아니라
+ * `STag` 를 쓴다.
+ */
 export interface SSystemActionButtonStatusOption {
-  /** 상태 태그 색 */
-  color?: STagColor;
-  /** 상태 태그 텍스트 */
-  label?: string;
+  /** 지금 상태. `options` 에서 같은 `value` 를 찾아 그 색·이름으로 태그를 그린다 */
+  value?: string;
+  /** 고를 수 있는 상태. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+  options: SSystemActionButtonStatusMenuOption[];
+  /** 메뉴에서 상태를 고름. 고르면 메뉴가 닫힌다 */
+  onChange?: (value: string) => void;
+}
+```
+
+### SSystemActionButtonSubSelectOption
+
+```ts
+/**
+ * `subSelect` 타입의 option — 지금 값 + 고를 목록.
+ *
+ * `options` 는 **필수다** — `subSelect` 는 "지금 값이 적혀 있고 눌러서 바꾸는 행"이라, 눌러도
+ * 아무것도 뜨지 않으면 그것은 `select`(눌러 들어가는 행)이지 `subSelect` 가 아니다.
+ */
+export interface SSystemActionButtonSubSelectOption extends SSystemActionButtonIconOption {
+  /**
+   * 지금 값. `options` 에서 같은 `value` 를 찾아 우측에 그 `label` 로 적는다
+   * (못 찾으면 `value` 가 그대로 남는다).
+   */
+  value?: string;
+  /** 고를 수 있는 값. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+  options: SSystemActionButtonMenuOption[];
+  /** 메뉴에서 값을 고름. 고르면 메뉴가 닫힌다 */
+  onChange?: (value: string) => void;
 }
 ```
 
@@ -112,6 +175,28 @@ export interface SSystemActionButtonTextOption extends SSystemActionButtonIconOp
 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
@@ -120,6 +205,7 @@ export const SYSTEM_ACTION_BUTTON_COLORS = ['light', 'dark', 'darker'] as const;
 
 ### Depends on
 
+- [SAccountListBox](../SAccountListBox)
 - [SIcon](../SIcon)
 - [STag](../STag)
 
@@ -127,6 +213,7 @@ export const SYSTEM_ACTION_BUTTON_COLORS = ['light', 'dark', 'darker'] as const;
 
 ```mermaid
 graph TD;
+  SSystemActionButton --> SAccountListBox
   SSystemActionButton --> SIcon
   SSystemActionButton --> STag
   SGnbSystem --> SSystemActionButton

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

@@ -1,4 +1,5 @@
 import { type ButtonHTMLAttributes } from 'react';
+import { type SAccountListBoxContent } from '../SAccountListBox';
 import { type SIconName } from '../SIcon';
 import { type STagColor } from '../STag';
 import { type SSystemActionButtonColor } from './systemActionButton.config';
@@ -12,12 +13,49 @@ export interface SSystemActionButtonTextOption extends SSystemActionButtonIconOp
     /** 우측 액션 텍스트 */
     text?: string;
 }
-/** `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 */
-export interface SSystemActionButtonStatusOption {
-    /** 상태 태그 색 */
+/** 값 고르기 메뉴의 한 칸 */
+export interface SSystemActionButtonMenuOption {
+    /** 값. `option.value` 와 맞춰 지금 값을 가린다 */
+    value: string;
+    /** 화면에 적히는 이름 */
+    label: string;
+}
+/**
+ * `subSelect` 타입의 option — 지금 값 + 고를 목록.
+ *
+ * `options` 는 **필수다** — `subSelect` 는 "지금 값이 적혀 있고 눌러서 바꾸는 행"이라, 눌러도
+ * 아무것도 뜨지 않으면 그것은 `select`(눌러 들어가는 행)이지 `subSelect` 가 아니다.
+ */
+export interface SSystemActionButtonSubSelectOption extends SSystemActionButtonIconOption {
+    /**
+     * 지금 값. `options` 에서 같은 `value` 를 찾아 우측에 그 `label` 로 적는다
+     * (못 찾으면 `value` 가 그대로 남는다).
+     */
+    value?: string;
+    /** 고를 수 있는 값. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+    options: SSystemActionButtonMenuOption[];
+    /** 메뉴에서 값을 고름. 고르면 메뉴가 닫힌다 */
+    onChange?: (value: string) => void;
+}
+/** 상태 메뉴의 한 칸 — 점과 글자가 그 상태의 색으로 함께 물든다 */
+export interface SSystemActionButtonStatusMenuOption extends SSystemActionButtonMenuOption {
+    /** 상태 색. 기본 `'blue'` */
     color?: STagColor;
-    /** 상태 태그 텍스트 */
-    label?: string;
+}
+/**
+ * `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 + 고를 목록.
+ *
+ * `options` 는 **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거이고, 지금 상태(`value`)에
+ * 해당하는 칸의 색·이름이 곧 태그가 된다. 보여주기만 하는 상태 줄이 필요하면 이 버튼이 아니라
+ * `STag` 를 쓴다.
+ */
+export interface SSystemActionButtonStatusOption {
+    /** 지금 상태. `options` 에서 같은 `value` 를 찾아 그 색·이름으로 태그를 그린다 */
+    value?: string;
+    /** 고를 수 있는 상태. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+    options: SSystemActionButtonStatusMenuOption[];
+    /** 메뉴에서 상태를 고름. 고르면 메뉴가 닫힌다 */
+    onChange?: (value: string) => void;
 }
 /** 모든 타입이 공통으로 받는 props */
 export interface SSystemActionButtonBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'type' | 'children'> {
@@ -26,14 +64,35 @@ export interface SSystemActionButtonBaseProps extends Omit<ButtonHTMLAttributes<
     /** 비활성 여부. 기본 `false` */
     disabled?: boolean;
 }
+/**
+ * `account` 타입의 option — 행을 눌렀을 때 뜨는 계정 리스트박스.
+ * 내용(이메일·이름·권한·행들)은 `SAccountListBox` 와 같다.
+ *
+ * **뜨는 자리는 받지 않는다.** 계정 행이 놓인 자리가 정한다 — 판이면 행 위로 · 왼쪽 끝에 맞춰,
+ * 전폭 상단바면 행 아래로 · 오른쪽 끝에 맞춰 펼친다(시안). 화면마다 고를 값이 아니라,
+ * prop 으로 열면 같은 계정 행이 앱마다 다른 방향으로 뜬다.
+ */
+export interface SSystemActionButtonAccountOption extends SAccountListBoxContent {
+    /**
+     * 리스트박스 열림 상태를 밖에서 쥔다(controlled). 주지 않으면 버튼이 스스로 여닫는다.
+     * 행을 담은 쪽이 닫아야 하는 자리가 있어 열어 둔 통로다 — 리스트박스는 SPortal 로 떠 있어
+     * 트리거가 화면에서 빠져도(GNB 를 접으면 메뉴 컬럼이 미끄러져 나간다) 따라 사라지지 않는다.
+     */
+    open?: boolean;
+    /** 리스트박스 열림/닫힘 변경 */
+    onOpenChange?: (open: boolean) => void;
+}
 /** 계정 행 — 아이콘이 `user` 로 고정이고 우측 액션이 없다 */
 export interface SSystemActionButtonAccountProps extends SSystemActionButtonBaseProps {
     /** 계정 행 */
     type: 'account';
     /** 라벨 텍스트 */
     label?: string;
-    /** 아이콘이 `user` 로 고정이라 받을 것이 없다 */
-    option?: never;
+    /**
+     * 누르면 뜨는 계정 리스트박스. **필수다** — 계정 행은 늘 이 패널의 트리거이고, 눌러도 아무것도
+     * 뜨지 않는 계정 행은 없다. 아이콘은 `user` 로 고정이라 여기서 받지 않는다.
+     */
+    option: SSystemActionButtonAccountOption;
 }
 /** 화살표만 붙는 행 — 눌러 들어간다는 뜻 */
 export interface SSystemActionButtonSelectProps extends SSystemActionButtonBaseProps {
@@ -44,26 +103,39 @@ export interface SSystemActionButtonSelectProps extends SSystemActionButtonBaseP
     /** 선행 아이콘 */
     option: SSystemActionButtonIconOption;
 }
-/** 우측에 문구가 붙는 행 — `switch` 는 보조 조작 문구, `subSelect` 는 지금 선택된 값 */
-export interface SSystemActionButtonTextProps extends SSystemActionButtonBaseProps {
-    /** 우측에 문구가 붙는 행. switch = 보조 조작 문구, subSelect = 지금 선택된 값 */
-    type: 'switch' | 'subSelect';
+/** 우측에 보조 조작 문구가 붙는 행 — 지금 붙어 있는 대상을 갈아 끼운다 */
+export interface SSystemActionButtonSwitchProps extends SSystemActionButtonBaseProps {
+    /** 우측에 보조 조작 문구가 붙는 행 */
+    type: 'switch';
     /** 라벨 텍스트 */
     label?: string;
     /** 선행 아이콘 + 우측 액션 텍스트 */
     option: SSystemActionButtonTextOption;
 }
-/** 라벨 자리에 상태 태그가 들어가는 행 */
+/** 우측에 지금 선택된 값이 붙는 행 — `options` 를 주면 행 오른쪽으로 메뉴가 펼쳐진다 */
+export interface SSystemActionButtonSubSelectProps extends SSystemActionButtonBaseProps {
+    /** 우측에 지금 선택된 값이 붙는 행 */
+    type: 'subSelect';
+    /** 라벨 텍스트 */
+    label?: string;
+    /** 선행 아이콘 + 우측 값 + 고를 목록 */
+    option: SSystemActionButtonSubSelectOption;
+}
+/** 우측에 문구가 붙는 두 타입을 함께 가리킨다 — `switch` · `subSelect` */
+export type SSystemActionButtonTextProps = SSystemActionButtonSwitchProps | SSystemActionButtonSubSelectProps;
+/** 라벨 자리에 상태 태그가 들어가는 행 — `options` 를 주면 행 오른쪽으로 메뉴가 펼쳐진다 */
 export interface SSystemActionButtonStatusProps extends SSystemActionButtonBaseProps {
     /** 라벨 자리에 상태 태그가 들어가는 행 */
     type: 'status';
     /** 태그가 라벨 자리를 차지하므로 받지 않는다 */
     label?: never;
-    /** 상태 태그 */
-    option?: SSystemActionButtonStatusOption;
+    /**
+     * 상태 태그 + 고를 목록. **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거다.
+     */
+    option: SSystemActionButtonStatusOption;
 }
 /** `type` 으로 갈리는 판별 유니온. 타입에 맞지 않는 option 은 컴파일 단계에서 막힌다. */
-export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystemActionButtonSelectProps | SSystemActionButtonTextProps | SSystemActionButtonStatusProps;
+export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystemActionButtonSelectProps | SSystemActionButtonSwitchProps | SSystemActionButtonSubSelectProps | SSystemActionButtonStatusProps;
 /**
  * SSystemActionButton — GNB system 패널의 한 줄짜리 액션 버튼.
  *
@@ -72,6 +144,16 @@ export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystem
  * `option` 으로 받는다. 선행 아이콘은 항상 있다 — `account` 는 `user` 고정, `status` 는 태그가
  * 자리를 차지해 아이콘이 없고, 나머지는 `option.icon` 이 필수다.
  *
+ * `account` 는 **언제나 계정 리스트박스(`SAccountListBox`)의 트리거**다 — 눌러도 아무것도 뜨지
+ * 않는 계정 행은 없으므로 `option` 이 필수이고, 누르면 이메일·이름·권한과 계정 설정·언어 변경·
+ * 로그아웃을 보여주고 행을 고르면 닫힌다. 뜨는 자리는 받지 않고 놓인 자리가 정한다
+ * (판이면 행 위로 · 왼쪽 끝, 전폭 상단바면 행 아래로 · 오른쪽 끝).
+ *
+ * `subSelect` · `status` 는 **언제나 값 고르기 메뉴의 트리거**다 — 지금 값이 적혀 있는 행이라
+ * 누르면 그 값을 바꾸는 메뉴가 뜬다. 그래서 `option.options` 가 필수이고, 메뉴는 행 오른쪽으로
+ * (행 위쪽 끝에 맞춰) 펼쳐지며 고르면 `option.onChange(value)` 가 돌고 닫힌다.
+ * 눌러서 값 고르는 화면으로 보낼 것이면 `select`, 보여주기만 할 것이면 `STag` 다.
+ *
  * hover 하면 표면색이 한 단계 바뀌고, 어두운 색에서는 아이콘 프레임이 흰색으로 떠오른다.
  * 상태는 default·hover 둘뿐이다 — 토큰에 selected 가 없다.
  * 토큰은 `--cmp-gnb-system-item-*` · `--cmp-gnb-system-actionButton-*`.

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

@@ -1,2 +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 { SSystemActionButton, type SSystemActionButtonProps, type SSystemActionButtonBaseProps, type SSystemActionButtonAccountProps, type SSystemActionButtonAccountOption, type SSystemActionButtonSelectProps, type SSystemActionButtonTextProps, type SSystemActionButtonSwitchProps, type SSystemActionButtonSubSelectProps, type SSystemActionButtonStatusProps, type SSystemActionButtonIconOption, type SSystemActionButtonTextOption, type SSystemActionButtonSubSelectOption, type SSystemActionButtonMenuOption, type SSystemActionButtonStatusOption, type SSystemActionButtonStatusMenuOption, } 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';