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

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

@@ -64,7 +64,9 @@ export interface SChipFilterFieldBase {
      *  조용히 되살아난다. 처음부터 값이 정해져 있어야 하는 필터라면 그것이 `fixed`·`required` 다.
      *
      *  required인데 지정하지 않으면 타입별 내장 기본값(select: 첫 번째 옵션,
-     *  datepicker-day·datepicker-range: 오늘 날짜)을 대신 쓴다. 인라인(radioButton) datepicker-range
+     *  datepicker-day·datepicker-range: 오늘 날짜)을 대신 쓴다. `fixed`·`required` 인
+     *  select·select-multi 는 후보가 하나뿐일 때 그 값이 기본값이 된다(options 참고) —
+     *  defaultValue 를 함께 주면 그쪽이 이긴다. 인라인(radioButton) datepicker-range
      *  필드는 팝오버 없이 바에 바로 노출되어 빈 상태로 둘 수 없으므로, 이 규칙과 무관하게 언제나
      *  오늘이 채워진다 */
     defaultValue?: SChipFilterValue;
@@ -74,7 +76,18 @@ export interface SChipFilterFieldBase {
 }
 /** 후보 목록에서 고르는 필터 — select·select-multi·keyword */
 export interface SChipFilterOptionsField extends SChipFilterFieldBase {
-    /** 고를 수 있는 후보 목록 */
+    /** 고를 수 있는 후보 목록.
+     *
+     *  **`fixed`·`required` 인 select·select-multi 에서 고를 수 있는 후보가 하나뿐이면 그 값이
+     *  자동으로 선택된다** — 사용자가 고르지 않아도 `onValueChange` 로 값이 올라온다
+     *  (select 는 그 값, select-multi 는 그 값 하나짜리 배열). 옵션이 API 응답이라 늦게 도착해도
+     *  도착한 시점에 채워진다. 사용자가 그 값을 지우면 다시 채우지 않는다 —
+     *  다만 "검색 초기화"는 되돌려 놓는다(다른 기본값과 같은 규칙).
+     *  후보가 하나인데 비활성(`disabled`)이면 고를 수 없는 값이므로 채우지 않는다.
+     *
+     *  뺄 수 있는 필터(= `fixed`·`required` 가 아닌 필드)는 후보가 하나여도 채우지 않는다 —
+     *  처음에 바에 없는 필터라 보이지도 지울 수도 없는 조건이 검색에 걸리기 때문이다.
+     *  후보가 하나뿐인 필터를 반드시 걸어야 한다면 `fixed` 나 `required` 로 준다 */
     options?: SChipFilterOption[];
 }
 /** 프리셋으로 기간을 고르는 필터 — datepicker-range·datepicker-statistics */
@@ -210,9 +223,14 @@ export interface SChipFilterProps {
     /** 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른
      *  칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom,
      *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도
-     *  그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
+     *  그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다.
+     *  keyword 입력창에 Enter 없이 텍스트를 남긴 채 팝오버를 닫으면 그 텍스트도 키워드로 확정한 뒤
+     *  호출된다(input: 'csv'면 콤마로 쪼개는 규칙도 그대로 적용) — 사용자가 검색어를 넣고 "검색"을 누른
+     *  조작이 입력 확정 여부 때문에 사라지지 않게 한다. dirty 체크가 기본 적용되어 있어 — 마지막으로
      *  실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고
-     *  닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
+     *  닫는 경우) 호출되지 않는다. 단 마운트 후 첫 호출은 비교할 기준이 없어 값이 처음 그대로여도 나간다 —
+     *  마운트 시 자동 조회하지 않는 화면(다이얼로그 등)에서 사용자의 첫 "검색"이 막히지 않게 하기 위함이다.
+     *  fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
      *  onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상
      *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음). required 필드가 비어 있는 동안에도
      *  마찬가지로 호출되지 않는다 — 정상 설정(내장 기본값 또는 defaultValue)이라면 원래 비워지지

package/dist/components/SGnb/README.md

@@ -26,7 +26,7 @@
 | `resizable?` | `boolean` | `false` | 메뉴 폭을 드래그로 조절할 수 있게 한다. 레일 폭은 고정이고 **메뉴 컬럼만** 늘고 준다. 조절선은 GNB 컬럼의 오른쪽 경계 전체다 — fix 는 상단바 높이까지, full 은 상단바가 전폭이라 본문 높이까지. 접혀 있거나 깔 메뉴가 없으면(레일 리프가 활성) 조절선이 나오지 않는다. |
 | `menuWidth?` | `number` | — | 메뉴 폭(px). 주면 controlled — onMenuWidthChange 로 직접 갱신해야 움직인다 |
 | `defaultMenuWidth?` | `number` | — | 메뉴 초기 폭(px). uncontrolled |
-| `system?` | `ReactNode` | — | GNB 맨 아래에 붙는 system 패널(`SGnbSystem`) 슬롯. 펼치면 메뉴 컬럼 바닥에, 접히면(header="fix" 레일) `foldedFooter` 아래 레일 바닥에 여백 없이 붙는다. 색·형태(펼침/접힘)는 GNB 가 내려주므로 SGnbSystem 에 다시 넘기지 않아도 된다. useRail 에서 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 슬롯도 함께 빠진다. |
+| `system?` | `ReactNode` | — | system 슬롯(`SGnbSystem`). 놓이는 자리와 형태는 `header` 가 정한다. - fix : GNB 맨 아래 세로 판. 펼치면 메뉴 컬럼 바닥에, 접히면 `foldedFooter` 아래 레일 바닥에 여백 없이 붙는다. useRail 에서 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 슬롯도 함께 빠진다. - full: 전폭 상단바 오른쪽 끝에 가로 한 줄로 선다. 상단바는 접어도 남으므로 조각들도 늘 남는다. 색·형태는 GNB 가 내려주므로 SGnbSystem 에 다시 넘기지 않아도 된다. |
 | `ariaLabel?` | `string` | `'global navigation'` | 메뉴 landmark(nav) 의 접근성 레이블. 한 화면에 nav 가 여럿일 때 구분한다. |
 
 #### Events

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

@@ -1,18 +1,37 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+import type { SGnbSystemPlacement } from '../SGnbSystem/gnbSystem.config';
 import { type SGnbType, type SGnbHeader, type SGnbColor, type SGnbMenuItem } from './gnb.config';
 /**
  * SGnb 가 `system` 슬롯에 내려주는 값. 슬롯에 놓인 SGnbSystem 이 이걸 읽어
- * 색과 형태(펼침/접힘)를 GNB 에 맞춘다 — 앱이 같은 값을 두 번 넘기지 않게 한다.
+ * 색과 형태(가로/세로 · 펼침/접힘)를 GNB 에 맞춘다 — 앱이 같은 값을 두 번 넘기지 않게 한다.
  *
- * `folded` 는 GNB 의 접힘 상태가 아니라 **그 자리가 접힌 레일인지**다. 슬롯은 두 곳에 놓이고
+ * 슬롯이 어디에 놓이는지는 header 가 정한다.
+ * - fix : 메뉴 컬럼 바닥 · 접힘 레일 바닥 → `placement: 'panel'` (세로 판)
+ * - full: 전폭 상단바 오른쪽 끝 → `placement: 'top'` (판 없이 가로 한 줄)
+ *
+ * `folded` 는 GNB 의 접힘 상태가 아니라 **그 자리가 접힌 레일인지**다. panel 은 두 곳에 놓이고
  * (메뉴 컬럼 바닥 · 접힘 레일 바닥) 각 자리가 자기 형태를 못 박으므로, 접는 동안 아직 미끄러져
  * 나가는 중인 메뉴 컬럼의 패널이 min 형태로 튀지 않는다.
+ *
+ * 그래서 fix 로 접혀 있는 동안 슬롯 내용은 **두 자리에 함께 마운트된다** — 미끄러져 나간 메뉴
+ * 컬럼(잔상)과 레일 바닥(실물). `active` 가 그 둘을 가른다.
  */
 export interface SGnbSystemContextValue {
     /** GNB 색 */
     color: SGnbColor;
-    /** 이 자리가 접힌(48px) 레일인지 */
+    /** 이 자리가 접힌(48px) 레일인지. `placement: 'top'` 에서는 뜻이 없다 */
     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'> {
@@ -96,10 +115,12 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
     /** 메뉴 폭이 확정될 때(드래그를 놓거나 방향키 조작). 드래그하는 동안에는 오지 않는다 */
     onMenuWidthChange?: (width: number) => void;
     /**
-     * GNB 맨 아래에 붙는 system 패널(`SGnbSystem`) 슬롯. 펼치면 메뉴 컬럼 바닥에,
-     * 접히면(header="fix" 레일) `foldedFooter` 아래 레일 바닥에 여백 없이 붙는다.
-     * 색·형태(펼침/접힘)는 GNB 가 내려주므로 SGnbSystem 에 다시 넘기지 않아도 된다.
-     * useRail 에서 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 슬롯도 함께 빠진다.
+     * system 슬롯(`SGnbSystem`). 놓이는 자리와 형태는 `header` 가 정한다.
+     * - fix : GNB 맨 아래 세로 판. 펼치면 메뉴 컬럼 바닥에, 접히면 `foldedFooter` 아래 레일 바닥에
+     *   여백 없이 붙는다. useRail 에서 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로
+     *   이 슬롯도 함께 빠진다.
+     * - full: 전폭 상단바 오른쪽 끝에 가로 한 줄로 선다. 상단바는 접어도 남으므로 조각들도 늘 남는다.
+     * 색·형태는 GNB 가 내려주므로 SGnbSystem 에 다시 넘기지 않아도 된다.
      */
     system?: ReactNode;
     /** 메뉴 landmark(nav) 의 접근성 레이블. 한 화면에 nav 가 여럿일 때 구분한다. */
@@ -113,6 +134,7 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
  * header 가 배치와 접힘 형태를 정한다:
  * - fix: 상단바가 GNB 컬럼(메뉴 폭) 안에 있다. 접으면 48px 세로 레일로 좁혀지고 상단바에는 폴드 버튼만 남는다.
  * - full: 상단바가 레이아웃 전폭을 가로지르고 그 아래 [메뉴 | 페이지]. 접으면 메뉴만 사라진다.
+ *   system 조각들도 메뉴 바닥이 아니라 이 상단바 오른쪽 끝으로 올라온다.
  *
  * useRail 이면 items 의 첫 depth 가 좌측 레일(아이콘+라벨 68px)로 서고, 선택된 레일 아이템의
  * children 이 메뉴 패널의 depth1 이 된다 — 트리는 그대로 두고 어디부터 그릴지만 바뀐다.

package/dist/components/SGnbSystem/README.md

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

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

@@ -1,4 +1,5 @@
 import { type HTMLAttributes } from 'react';
+import { type SAccountListBoxContent } from '../SAccountListBox';
 import { type SSystemActionButtonProps } from '../SSystemActionButton';
 import { type SGnbSystemColor } from './gnbSystem.config';
 /** 유니온을 유지한 채 키를 걷어낸다 — 그냥 Omit 하면 판별 유니온이 한 덩어리로 뭉개진다. */
@@ -6,8 +7,14 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K>
 /**
  * 패널 상단에 쌓이는 행 하나. `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,20 +66,26 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
     color?: SGnbSystemColor;
     /**
      * 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다.
-     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다.
+     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. 상단바 자리에서는 뜻이 없다.
      */
     folded?: boolean;
     /**
-     * 패널 상단에 쌓는 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외).
-     * 아래에 다른 조각이 있으면 그 사이에 구분선이 그어진다. 접히면 자리가 없어 렌더되지 않는다.
+     * 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외 · 계정 행은 `account` 로
+     * 따로 준다). 판에서는 맨 위에 쌓이고,
+     * 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다.
+     * 접히면 자리가 없어 렌더되지 않는다.
      */
     actions?: SGnbSystemAction[];
     /** 도메인 태그 텍스트. 접히면 자리가 없어 렌더되지 않는다 */
     domain?: string;
-    /** 알림 버튼. 없으면 렌더하지 않는다. 설정과 나란히 서면 남는 폭을 먹고, 혼자면 폭을 다 먹는다 */
+    /**
+     * 알림 버튼. 없으면 렌더하지 않는다. 판에서는 설정과 나란히 서면 남는 폭을 먹고 혼자면 폭을 다 먹는다.
+     * 상단바에서는 자리가 넉넉하지 않아 라벨 없이 아이콘+개수만 선다.
+     */
     alert?: SGnbSystemAlert;
     /**
-     * 설정 버튼. 없으면 렌더하지 않는다. 알림과 나란히 서면 제 폭만 갖고, 혼자면 폭을 다 먹는다.
+     * 설정 버튼. 없으면 렌더하지 않는다. 판에서는 알림과 나란히 서면 제 폭만 갖고 혼자면 폭을 다 먹고,
+     * 상단바에서는 라벨 없이 아이콘만 선다.
      * 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다.
      */
     setting?: SGnbSystemSetting;
@@ -66,28 +93,41 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
     account?: SGnbSystemAccount;
 }
 /**
- * SGnbSystem — GNB 맨 아래에 붙는 system 패널.
+ * SGnbSystem — GNB 의 system 조각들(액션 · 도메인 · 알림 · 설정 · 계정).
+ *
+ * 어디에 놓이느냐로 두 형태가 있고, 그 자리는 담은 SGnb 의 `header` 가 정해 내려준다(앱이 고르지 않는다).
+ * - `panel` (header="fix") — GNB 바닥에 깔리는 세로 판. 위에서부터 [행 목록(`actions`)] · 구분선 ·
+ *   [도메인 태그] · [알림 | 설정] · [계정] 을 쌓는다.
+ * - `top` (header="full") — 레이아웃 전폭 상단바의 오른쪽 끝에 서는 가로 한 줄.
+ *   [행 목록] | [알림] | [설정] | [도메인 계정] 순으로 서고 조각 사이에 세로 구분선이 놓인다
+ *   (도메인·계정은 한 덩어리라 그 사이만 선 없이 붙는다).
  *
- * 위에서부터 [행 목록(`actions`)] · 구분선 · [도메인 태그] · [알림 | 설정] · [계정] 을 쌓는다.
  * 각 조각은 해당 prop 을 줄 때만 나타나므로, 서비스마다 필요한 만큼만 켜서 쓴다 — 계정만, 알림만,
  * 설정만, 알림+계정 … 어떤 부분집합이어도 그 조합만으로 판이 성립하도록 다음을 지킨다.
  *
- * - **구분선은 위아래 양쪽에 내용이 있을 때만** 긋는다. `actions` 만 주면 바닥에 뜻 없는 선이 남지 않는다.
- * - **알림·설정은 혼자 서면 폭을 다 먹는다.** 둘이 나란히 서면 알림이 남는 폭을, 설정이 제 폭을 갖고
- *   사이에 세로선이 놓인다. 어느 쪽이 빠져도 왼쪽 끝은 위아래 행과 맞는다.
+ * - **구분선은 양쪽에 내용이 있을 때만** 긋는다. `actions` 만 주면 뜻 없는 선이 남지 않는다.
+ * - **판에서 알림·설정은 혼자 서면 폭을 다 먹는다.** 둘이 나란히 서면 알림이 남는 폭을, 설정이 제 폭을
+ *   갖고 사이에 세로선이 놓인다. 어느 쪽이 빠져도 왼쪽 끝은 위아래 행과 맞는다.
  * - **켜진 조각이 하나도 없으면 아무것도 렌더하지 않는다** — 빈 판은 GNB 바닥에 정체 모를 경계선만 남긴다.
  *
- * 알림·설정·계정은 늘 함께 붙어 다니는 한 덩어리라 사이를 띄우지 않고, 그 위 조각들만 간격을 갖는다.
+ * 판에서 알림·설정·계정은 늘 함께 붙어 다니는 한 덩어리라 사이를 띄우지 않고, 그 위 조각들만 간격을 갖는다.
+ * 상단바에서는 자리가 가로로 넉넉하지 않아 알림·설정이 라벨을 벗고 아이콘(+개수)만 남는다.
  *
  * `folded` 면 48px 레일 폭에 맞춘 min 형태가 된다 — **알림·계정 아이콘만** 남고 라벨·태그·행 목록·설정은
  * 빠진다(시안). 알림 개수는 적을 자리가 없어 점 배지로 바뀐다. 둘 다 없는 조합(설정만 쓰는 앱 등)이면
  * 접힌 패널은 렌더되지 않으므로, 접힌 상태에서도 닿아야 하는 것은 SGnb 의 `foldedTop`·`foldedFooter` 에 둔다.
+ * 상단바는 접어도 남으므로 `top` 에는 접힘 형태가 없다.
+ *
+ * `alert.count` 가 1 이상이면 벨이 울리는 아이콘(`bellRinging`)과 강조색으로 바뀐다 — light 는 파랑,
+ * 어두운 면은 노랑(토큰이 정한다). 0 이거나 없으면 조용한 벨(`bell`)에 기본 색이다.
  *
- * `alert.count` 가 1 이상이면 벨이 울리는 아이콘(`alert`)과 강조색으로 바뀐다 — light 는 파랑,
- * dark 는 노랑(토큰이 정한다). 0 이거나 없으면 조용한 벨(`bell`)에 기본 색이다.
+ * 색은 놓인 면을 따른다: 판 위는 `light`/`dark`(오션블루 판), 판 없이 상단바 면에 바로 얹는 `top` 의
+ * dark 는 한 단계 어두운 `darker`(네이비) 색표다 — GNB_SYSTEM_TOP_COLOR_CONFIG 가 그 대응을 쥔다.
  *
- * SGnb 의 `system` 슬롯에 넣으면 `color` 와 `folded` 를 GNB 에서 받아오므로 앱이 다시 넘길 필요가 없다.
- * 단독으로 쓰면 두 prop 을 직접 준다. 폭은 늘 부모를 가득 채운다 — 좁은 GNB 컬럼에 놓이는 패널이다.
+ * **놓이는 자리(`placement`)는 prop 이 아니다** — 자기를 담은 SGnb 가 `header` 로 정해 내려준다.
+ * 앱이 고르면 세로 판 자리에 가로 한 줄이 서는 조합이 만들어지고, 그것을 고를 이유가 있는 화면은 없다.
+ * `color`·`folded` 도 슬롯 안에서는 GNB 가 내려주므로 다시 넘기지 않는다.
+ * 판은 폭이 늘 부모를 가득 채우고, 상단바 줄은 내용 폭만 갖는다.
  */
 export declare const SGnbSystem: import("react").ForwardRefExoticComponent<SGnbSystemProps & import("react").RefAttributes<HTMLDivElement>>;
 export {};

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

@@ -18,10 +18,18 @@ import type { SSystemActionButtonColor } from '../SSystemActionButton';
 /** 색상(표면). light = 흰 면, dark = 오션블루 면. GNB 의 color 를 그대로 따라간다 */
 export declare const GNB_SYSTEM_COLORS: readonly ["light", "dark"];
 export type SGnbSystemColor = (typeof GNB_SYSTEM_COLORS)[number];
+/**
+ * 조각들이 놓이는 자리. GNB 의 `header` 가 정하므로 앱이 고르지 않는다.
+ * - `panel` — GNB 바닥에 깔리는 세로 판 (header="fix"). 접히면 48px 레일용 min 형태가 된다.
+ * - `top`   — 레이아웃 전폭 상단바 위 (header="full"). 판을 깔지 않고 가로 한 줄로 선다.
+ */
+export declare const GNB_SYSTEM_PLACEMENTS: readonly ["panel", "top"];
+export type SGnbSystemPlacement = (typeof GNB_SYSTEM_PLACEMENTS)[number];
 /**
  * 패널 색이 곧 행 색이다 — 행(아이콘 프레임·라벨·hover)은 SSystemActionButton 과 같은
  * `--cmp-gnb-system-item-*` 토큰을 쓰므로, 그 색표를 그대로 빌려 두 컴포넌트가 어긋나지 않게 한다.
- * `darker`(패널 없이 어두운 GNB 면에 바로 얹는 색)는 패널에 대응 토큰이 없어 노출하지 않는다.
+ * `darker`(판 없이 어두운 GNB 면에 바로 얹는 색)는 판을 깔지 않는 `top` 자리가 쓴다
+ * → GNB_SYSTEM_TOP_COLOR_CONFIG.
  */
 export type GnbSystemItemColor = SSystemActionButtonColor;
 export interface GnbSystemColorTokens {
@@ -46,6 +54,31 @@ export interface GnbSystemColorTokens {
     alertHoverBg?: string;
 }
 export declare const GNB_SYSTEM_COLOR_CONFIG: Record<SGnbSystemColor, GnbSystemColorTokens>;
+/**
+ * `top` 자리(전폭 상단바)의 색.
+ *
+ * 상단바에는 판을 깔지 않고 조각을 GNB 면에 바로 얹는다 — 그래서 행 색이 패널과 한 단계 다르다.
+ * dark 는 패널의 오션블루(`dark`)가 아니라 GNB 네이비 면용 `darker` 를 쓰고, 구분선·도메인 태그도
+ * 그에 맞춘 `*-darker-*` 토큰을 쓴다. 알림 강조색은 darker 대응 토큰이 없어 dark 값을 그대로 쓴다
+ * (두 면 모두 어두운 면이라 같은 노랑이 맞는다).
+ */
+export interface GnbSystemTopColorTokens {
+    /** 조각(액션·알림·설정·계정)이 쓰는 행 색 */
+    item: GnbSystemItemColor;
+    /** 조각 사이 세로 구분선 */
+    divider: string;
+    /** 도메인 태그 배경 */
+    domainBg: string;
+    /** 도메인 태그 글자색 */
+    domainText: string;
+    /** 알림이 있을 때의 벨 글리프색 */
+    alertIcon: string;
+    /** 알림 개수 색 */
+    alertCount: string;
+    /** 알림이 있을 때의 hover 배경. 없으면 행 기본 hover 를 쓴다 */
+    alertHoverBg?: string;
+}
+export declare const GNB_SYSTEM_TOP_COLOR_CONFIG: Record<SGnbSystemColor, GnbSystemTopColorTokens>;
 /** 치수 — 전부 토큰 참조 */
 export declare const GNB_SYSTEM_LAYOUT: {
     /** 펼친 패널의 안쪽 여백 */

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

@@ -1,2 +1,2 @@
 export { SGnbSystem, type SGnbSystemProps, type SGnbSystemAction, type SGnbSystemAlert, type SGnbSystemSetting, type SGnbSystemAccount, } from './SGnbSystem';
-export { GNB_SYSTEM_COLORS, GNB_SYSTEM_COLOR_CONFIG, GNB_SYSTEM_LAYOUT, type SGnbSystemColor, type GnbSystemColorTokens, } from './gnbSystem.config';
+export { GNB_SYSTEM_COLORS, GNB_SYSTEM_COLOR_CONFIG, GNB_SYSTEM_LAYOUT, GNB_SYSTEM_PLACEMENTS, GNB_SYSTEM_TOP_COLOR_CONFIG, type SGnbSystemColor, type SGnbSystemPlacement, type GnbSystemColorTokens, type GnbSystemTopColorTokens, } from './gnbSystem.config';

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