sellmate-design-system-react 9.0.0-beta.4 → 9.0.0-beta.40

package/dist/components/SGhostButton/README.md

@@ -27,14 +27,29 @@
 |-------|------|-------------|
 | `onClick` | `(e: MouseEvent<HTMLButtonElement>) => void` | 클릭 (sdClick) |
 
+## Types
+
+### SGhostButtonSize
+
+```ts
+export type SGhostButtonSize = 'xxs' | 'xs' | 'sm' | 'md' | 'lg';
+```
+
+### SGhostButtonIntent
+
+```ts
+export type SGhostButtonIntent = 'default' | 'danger' | 'action' | 'subAction' | 'inverse';
+```
+
 ## Dependencies
 
 ### Used by
 
  - [SBarcodeInput](../SBarcodeInput)
  - [SCalendar](../SCalendar)
+ - [SCalendarBoard](../SCalendarBoard)
  - [SChip](../SChip)
- - [SChipFilter](../SChipFilter)
+ - [SDatePicker](../SDatePicker)
  - [SDateRangePicker](../SDateRangePicker)
  - [SFilePicker](../SFilePicker)
  - [SGnb](../SGnb)
@@ -44,7 +59,8 @@
  - [SOverlayHeader](../SOverlayHeader)
  - [SPage](../SPage)
  - [SPopover](../SPopover)
- - [SSelect](../SSelect)
+ - [SSearchInput](../SSearchInput)
+ - [STable](../STable)
  - [STimePicker](../STimePicker)
  - [STimeRangePicker](../STimeRangePicker)
  - [SToast](../SToast)
@@ -64,8 +80,9 @@ graph TD;
   SGhostButton --> STag
   SBarcodeInput --> SGhostButton
   SCalendar --> SGhostButton
+  SCalendarBoard --> SGhostButton
   SChip --> SGhostButton
-  SChipFilter --> SGhostButton
+  SDatePicker --> SGhostButton
   SDateRangePicker --> SGhostButton
   SFilePicker --> SGhostButton
   SGnb --> SGhostButton
@@ -75,7 +92,8 @@ graph TD;
   SOverlayHeader --> SGhostButton
   SPage --> SGhostButton
   SPopover --> SGhostButton
-  SSelect --> SGhostButton
+  SSearchInput --> SGhostButton
+  STable --> SGhostButton
   STimePicker --> SGhostButton
   STimeRangePicker --> SGhostButton
   SToast --> SGhostButton

package/dist/components/SGnb/README.md

@@ -26,6 +26,7 @@
 | `resizable?` | `boolean` | `false` | 메뉴 폭을 드래그로 조절할 수 있게 한다. 레일 폭은 고정이고 **메뉴 컬럼만** 늘고 준다. 조절선은 GNB 컬럼의 오른쪽 경계 전체다 — fix 는 상단바 높이까지, full 은 상단바가 전폭이라 본문 높이까지. 접혀 있거나 깔 메뉴가 없으면(레일 리프가 활성) 조절선이 나오지 않는다. |
 | `menuWidth?` | `number` | — | 메뉴 폭(px). 주면 controlled — onMenuWidthChange 로 직접 갱신해야 움직인다 |
 | `defaultMenuWidth?` | `number` | — | 메뉴 초기 폭(px). uncontrolled |
+| `system?` | `ReactNode` | — | system 슬롯(`SGnbSystem`). 놓이는 자리와 형태는 `header` 가 정한다. - fix : GNB 맨 아래 세로 판. 펼치면 메뉴 컬럼 바닥에, 접히면 `foldedFooter` 아래 레일 바닥에 여백 없이 붙는다. useRail 에서 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 슬롯도 함께 빠진다. - full: 전폭 상단바 오른쪽 끝에 가로 한 줄로 선다. 상단바는 접어도 남으므로 조각들도 늘 남는다. 색·형태는 GNB 가 내려주므로 SGnbSystem 에 다시 넘기지 않아도 된다. |
 | `ariaLabel?` | `string` | `'global navigation'` | 메뉴 landmark(nav) 의 접근성 레이블. 한 화면에 nav 가 여럿일 때 구분한다. |
 
 #### Events
@@ -38,8 +39,57 @@
 | `onLauncherClick` | `() => void` | 앱런처(그리드) 버튼 클릭. 미지정 시 런처 버튼을 렌더하지 않는다. 접힘 레일(fix)에는 폴드 버튼만 남으므로 표시되지 않는다. |
 | `onMenuWidthChange` | `(width: number) => void` | 메뉴 폭이 확정될 때(드래그를 놓거나 방향키 조작). 드래그하는 동안에는 오지 않는다 |
 
+## Types
+
+### SGnbType
+
+```ts
+/** 메뉴 스타일: box = 라운드/좁은 들여쓰기, belt = 풀폭 행/넓은 들여쓰기 */
+export type SGnbType = 'box' | 'belt';
+```
+
+### SGnbHeader
+
+```ts
+/** 상단바 구조: fix = GNB 폭에 고정, full = 레이아웃 전폭 */
+export type SGnbHeader = 'fix' | 'full';
+```
+
+### SGnbColor
+
+```ts
+/** 색상(테마): light / dark */
+export type SGnbColor = 'light' | 'dark';
+```
+
+### SGnbMenuItem
+
+```ts
+/** GNB 메뉴 아이템 (재귀 트리). depth1 → depth2 → depth3. */
+export interface SGnbMenuItem {
+  /** 표시 텍스트 */
+  label: string;
+  /** 고유 식별값 (선택 상태 비교 기준) */
+  value: string;
+  /** depth1 전용 아이콘명 */
+  icon?: SIconName;
+  /** 우측 Tag 뱃지 텍스트 */
+  tag?: string;
+  /** 뱃지 색. 미지정 시 blue. */
+  tagColor?: STagColor;
+  /** 비활성 여부 */
+  disabled?: boolean;
+  /** 하위 아이템 (있으면 펼침/접힘 대상) */
+  children?: SGnbMenuItem[];
+}
+```
+
 ## Dependencies
 
+### Used by
+
+ - [SGnbSystem](../SGnbSystem)
+
 ### Depends on
 
 - [SGhostButton](../SGhostButton)
@@ -55,5 +105,6 @@ graph TD;
   SGnb --> SIcon
   SGnb --> SLayout
   SGnb --> STag
+  SGnbSystem --> SGnb
   style SGnb fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -1,5 +1,45 @@
 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 에 맞춘다 — 앱이 같은 값을 두 번 넘기지 않게 한다.
+ *
+ * 슬롯이 어디에 놓이는지는 header 가 정한다.
+ * - fix : 메뉴 컬럼 바닥 · 접힘 레일 바닥 → `placement: 'panel'` (세로 판)
+ * - full: 전폭 상단바 오른쪽 끝 → `placement: 'top'` (판 없이 가로 한 줄)
+ *
+ * `folded` 는 GNB 의 접힘 상태가 아니라 **그 자리가 접힌 레일인지**다. panel 은 두 곳에 놓이고
+ * (메뉴 컬럼 바닥 · 접힘 레일 바닥) 각 자리가 자기 형태를 못 박으므로, 접는 동안 아직 미끄러져
+ * 나가는 중인 메뉴 컬럼의 패널이 min 형태로 튀지 않는다.
+ *
+ * 그래서 fix 로 접혀 있는 동안 슬롯 내용은 **두 자리에 함께 마운트된다** — 미끄러져 나간 메뉴
+ * 컬럼(잔상)과 레일 바닥(실물). `active` 가 그 둘을 가른다.
+ */
+export interface SGnbSystemContextValue {
+    /** GNB 색 */
+    color: SGnbColor;
+    /** 이 자리가 접힌(48px) 레일인지. `placement: 'top'` 에서는 뜻이 없다 */
+    folded: boolean;
+    /** 이 자리가 세로 판인지 전폭 상단바인지 */
+    placement: SGnbSystemPlacement;
+    /**
+     * 이 자리가 지금 화면에 살아 있는 자리인가. 접힌 GNB 의 메뉴 컬럼처럼 밖으로 미끄러져 나가
+     * 잔상으로만 남는 자리는 `false` 다.
+     *
+     * 잔상에서도 계정 리스트박스 같은 **떠 있는 층은 함께 숨지 않는다** — SPortal 로 문서 최상단에
+     * 그려져 컬럼의 `visibility: hidden` 이 닿지 않기 때문이다. 그래서 잔상이 된 자리는 열어 둔
+     * 것을 스스로 닫아야 하고, 그 신호가 이 값이다.
+     */
+    active: boolean;
+    /**
+     * 이 자리가 메뉴 기본 폭(GNB_MENU_WIDTH)보다 좁은가 — `resizable` 로 줄인 메뉴 컬럼이 그렇다.
+     * 좁아진 판에서는 알림 개수를 적을 가로가 모자라 개수 대신 점 배지가 붙는다.
+     * 없으면 좁지 않은 것으로 본다(접힘 레일·상단바는 자기 규칙을 따르므로 이 값과 무관하다).
+     */
+    narrow?: boolean;
+}
+export declare const SGnbSystemContext: import("react").Context<SGnbSystemContextValue | null>;
 export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
     /** 메뉴 스타일: box(라운드) / belt(풀폭 행). 미지정 시 SLayout 의 type 을 따른다. */
     type?: SGnbType;
@@ -80,6 +120,15 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
     defaultMenuWidth?: number;
     /** 메뉴 폭이 확정될 때(드래그를 놓거나 방향키 조작). 드래그하는 동안에는 오지 않는다 */
     onMenuWidthChange?: (width: number) => void;
+    /**
+     * system 슬롯(`SGnbSystem`). 놓이는 자리와 형태는 `header` 가 정한다.
+     * - fix : GNB 맨 아래 세로 판. 펼치면 메뉴 컬럼 바닥에, 접히면 `foldedFooter` 아래 레일 바닥에
+     *   여백 없이 붙는다. useRail 에서 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로
+     *   이 슬롯도 함께 빠진다.
+     * - full: 전폭 상단바 오른쪽 끝에 가로 한 줄로 선다. 상단바는 접어도 남으므로 조각들도 늘 남는다.
+     * 색·형태는 GNB 가 내려주므로 SGnbSystem 에 다시 넘기지 않아도 된다.
+     */
+    system?: ReactNode;
     /** 메뉴 landmark(nav) 의 접근성 레이블. 한 화면에 nav 가 여럿일 때 구분한다. */
     ariaLabel?: string;
 }
@@ -91,6 +140,7 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
  * header 가 배치와 접힘 형태를 정한다:
  * - fix: 상단바가 GNB 컬럼(메뉴 폭) 안에 있다. 접으면 48px 세로 레일로 좁혀지고 상단바에는 폴드 버튼만 남는다.
  * - full: 상단바가 레이아웃 전폭을 가로지르고 그 아래 [메뉴 | 페이지]. 접으면 메뉴만 사라진다.
+ *   system 조각들도 메뉴 바닥이 아니라 이 상단바 오른쪽 끝으로 올라온다.
  *
  * useRail 이면 items 의 첫 depth 가 좌측 레일(아이콘+라벨 68px)로 서고, 선택된 레일 아이템의
  * children 이 메뉴 패널의 depth1 이 된다 — 트리는 그대로 두고 어디부터 그릴지만 바뀐다.

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

@@ -48,6 +48,8 @@ export declare const GNB_MENU: Record<SGnbType, {
     depth1FontWeight: number;
     itemFontSize: number;
     itemLineHeight: number;
+    itemFontWeight: number;
+    itemFontWeightSelected: number;
 }>;
 /**
  * 색상(color 축). light → --cmp-gnb-light-* 색, dark → --cmp-gnb-dark-* 색
@@ -114,13 +116,13 @@ export declare const GNB_EXPAND_MS = 200;
  * 메뉴 고정 폭. 두 header 모두 메뉴는 이 폭으로 좌측에 붙는다(토큰 없음 → 상수).
  * header="full" 에서 SLayout 이 "메뉴 오른쪽 = 페이지" 영역을 잡을 때도 이 값을 쓴다.
  */
-export declare const GNB_MENU_WIDTH = 240;
+export declare const GNB_MENU_WIDTH = 214;
 /**
  * resizable 일 때 메뉴 폭이 움직일 수 있는 범위(px). 레일 폭은 고정이고 메뉴 컬럼만 늘고 준다.
- * 디자인이 아직 확정한 값이 아니라 임시다 — 확정되면 토큰으로 내려온다.
+ * 기본 폭(GNB_MENU_WIDTH)이 이 범위 안에 있다. 대응 토큰이 없어 상수로 둔다.
  */
 export declare const GNB_MENU_MIN_WIDTH = 200;
-export declare const GNB_MENU_MAX_WIDTH = 300;
+export declare const GNB_MENU_MAX_WIDTH = 240;
 /** 메뉴 폭 조절에서 방향키 한 번에 움직이는 양(px). Shift 를 함께 누르면 large. */
 export declare const GNB_MENU_RESIZE_KEY_STEP: {
     normal: number;
@@ -160,3 +162,8 @@ export declare function findGnbRailValue(items: SGnbMenuItem[], value: string):
 export declare function findGnbSiblingValues(items: SGnbMenuItem[], value: string): string[];
 /** value 로 선택된 아이템의 조상 value 목록(자기 자신 제외)을 반환 → 자동 펼침용 */
 export declare function findGnbAncestors(items: SGnbMenuItem[], value: string): string[];
+/**
+ * value 를 가진 아이템 아래의 **하위 가지**(children 을 가진 자손) value 목록을 반환.
+ * 부모를 펼칠 때 그 아래 가지도 전부 함께 펼치는 용도 — 리프는 펼침 대상이 아니라 제외한다.
+ */
+export declare function findGnbDescendantBranchValues(items: SGnbMenuItem[], value: string): string[];

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

@@ -1,2 +1,2 @@
-export { SGnb, type SGnbProps } from './SGnb';
+export { SGnb, SGnbSystemContext, type SGnbProps, type SGnbSystemContextValue } from './SGnb';
 export { GNB_HEADER, GNB_MENU, GNB_COLORS, GNB_COMMON, GNB_FOLD_MS, GNB_FULL_LOGO_WIDTH, GNB_MENU_WIDTH, GNB_RAIL, GNB_RAIL_WIDTH, findGnbAncestors, findGnbRailValue, type SGnbType, type SGnbHeader, type SGnbColor, type SGnbMenuItem, } from './gnb.config';

package/dist/components/SGnbSystem/README.md

@@ -0,0 +1,186 @@
+# SGnbSystem
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SGnbSystem
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SGnbSystemColor` | — | 색상(패널 표면). light = 흰 면, dark = 오션블루 면. 미지정 시 자기를 담은 SGnb 의 color 를 따른다(단독으로 쓰면 `'light'`). |
+| `folded?` | `boolean` | — | 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다. 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. 상단바 자리에서는 뜻이 없다. |
+| `actions?` | `SGnbSystemAction[]` | — | 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외 · 계정 행은 `account` 로 따로 준다). 판에서는 맨 위에 쌓이고, 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다. 접히면 자리가 없어 렌더되지 않는다. |
+| `domain?` | `string` | — | 도메인 태그 텍스트. 접히면 자리가 없어 렌더되지 않는다 |
+| `alert?` | `SGnbSystemAlert` | — | 알림 버튼. 없으면 렌더하지 않는다. 판에서는 설정과 나란히 서면 남는 폭을 먹고 혼자면 폭을 다 먹는다. 상단바에서는 자리가 넉넉하지 않아 라벨 없이 아이콘+개수만 선다. |
+| `setting?` | `SGnbSystemSetting` | — | 설정 버튼. 없으면 렌더하지 않는다. 판에서는 알림과 나란히 서면 제 폭만 갖고 혼자면 폭을 다 먹고, 상단바에서는 라벨 없이 아이콘만 선다. 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다. |
+| `account?` | `SGnbSystemAccount` | — | 계정 행. 없으면 렌더하지 않는다 |
+
+## Types
+
+### SGnbSystemColor
+
+```ts
+export type SGnbSystemColor = (typeof GNB_SYSTEM_COLORS)[number];
+```
+
+### SGnbSystemAction
+
+```ts
+/**
+ * 패널 상단에 쌓이는 행 하나. `SSystemActionButton` 의 props 를 그대로 받는다 —
+ * 단 `color` 는 패널이 정하므로 받지 않고, 목록 key 로 쓸 `value` 만 더한다.
+ *
+ * `type: 'account'` 는 받지 않는다. 계정 행은 이 패널에 **하나뿐**이고 서는 자리도 맨 아래로
+ * 정해져 있어(§3-5-8) `account` prop 이 따로 있다 — 여기로도 받으면 계정 행이 둘인 패널이
+ * 만들어지고, 그중 하나는 자리가 틀린다.
+ */
+export type SGnbSystemAction = DistributiveOmit<
+  Exclude<SSystemActionButtonProps, { type: 'account' }>,
+  'color'
+> & {
+  /** 목록 key. 없으면 순서를 key 로 쓴다 */
+  value?: string;
+};
+```
+
+### SGnbSystemAlert
+
+```ts
+/** 알림 버튼 */
+export interface SGnbSystemAlert {
+  /** 라벨 텍스트. 기본 `'알림'` */
+  label?: string;
+  /**
+   * 읽지 않은 알림 개수. 1 이상이면 벨이 울리는 아이콘·강조색으로 바뀌고 개수가 붙는다.
+   * 개수를 적을 가로가 모자란 자리(접힌 레일 · 기본 폭보다 좁게 줄인 판)에서는 점 배지로 바뀐다.
+   * 표기는 컴포넌트가 맡는다 — 세 자리마다 콤마를 넣어 그리므로 앱이 포맷한 문자열을 넘기지 않는다.
+   */
+  count?: number;
+  /** 클릭 */
+  onClick?: () => void;
+  /**
+   * 알림 버튼에 붙는 안내 툴팁의 문구(한 줄이 한 항목). 주면 뜬다 — **문구만 앱이 정하고**
+   * 색·방향·여닫힘은 컴포넌트가 쥔다: 색은 판이 light 면 기본, 그 밖(dark·상단바)이면 강조색이고
+   * 방향은 자리가 정한다(판·접힌 레일이면 오른쪽, 상단바면 아래).
+   *
+   * 스스로 사라지지 않는다 — **알림 버튼을 누르거나, 버튼에 얹었다 커서를 뺄 때** 닫히고,
+   * 같은 값을 계속 넘기는 동안에는 다시 뜨지 않는다.
+   *
+   * **다시 띄우려면 비웠다가 다시 넘긴다**(`undefined` → 문구). 문구가 같아도 상관없다 —
+   * 컴포넌트는 닫았다는 사실만 기억하고 문구 내용은 기억하지 않으므로, 새 알림마다 같은 안내를
+   * 다시 띄우는 화면도 막히지 않는다.
+   */
+  tooltip?: string[];
+  /**
+   * 알림을 누르면 뜨는 목록의 **내용**. 주면 컴포넌트가 알림 버튼에 붙여 띄운다 —
+   * 목록에 무엇을 쌓을지는 서비스마다 다르지만 **뜨는 자리는 늘 같아야 하므로**, 방향·앵커·
+   * 여닫힘(바깥 클릭·ESC 포함)과 배경·라운드·그림자는 컴포넌트가 쥐고 앱은 안에 담을 것만 준다.
+   * 방향은 자리가 정한다 — 판·접힌 레일이면 버튼 오른쪽, 상단바면 아래.
+   */
+  listBox?: ReactNode;
+  /**
+   * 알림 목록이 열리고 닫힐 때. 여닫는 것은 알림 버튼이 스스로 하므로 **그 사실을 알아야 할
+   * 때만** 준다(연 김에 읽음 처리하거나, 열려 있는 동안 다른 층을 접어 두는 화면).
+   *
+   * 앱이 누르지 않은 닫힘도 온다: GNB 를 접거나 펴면 알림 버튼이 다른 자리로 옮겨 서므로
+   * 목록이 닫히고 `false` 가 온다(계정 행과 같다).
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 안내 툴팁이 닫힐 때. 받아서 `tooltip` 을 비워 두는 것이 기본 사용법이다 — 그러면 앱이
+   * 다음에 넘기는 문구가 곧 다음 안내가 된다.
+   *
+   * 컴포넌트가 아는 "다시 뜨지 않는다" 는 **이 자리가 서 있는 동안**뿐이라(새로고침하거나
+   * GNB 를 접어 알림이 다른 자리로 옮겨 서면 새로 마운트된다), 그 사용자에게 두 번 다시 보이지
+   * 않아야 하면 앱이 이 신호를 저장해 두고 `tooltip` 을 그만 넘긴다.
+   */
+  onTooltipDismiss?: () => void;
+}
+```
+
+### SGnbSystemSetting
+
+```ts
+/** 설정 버튼 */
+export interface SGnbSystemSetting {
+  /** 라벨 텍스트. 기본 `'설정'` */
+  label?: string;
+  /** 클릭 */
+  onClick?: () => void;
+}
+```
+
+### SGnbSystemAccount
+
+```ts
+/** 계정 행 */
+export interface SGnbSystemAccount {
+  /** 계정 이름 */
+  label?: string;
+  /** 클릭. 패널은 어차피 열리므로, 여는 것 말고 따로 할 일이 있을 때만 준다 */
+  onClick?: () => void;
+  /**
+   * 계정 리스트박스가 열리고 닫힐 때. 여닫는 것은 계정 행이 스스로 하므로 **그 사실을 알아야 할
+   * 때만** 준다 — 열려 있는 동안 다른 층을 접어 두거나, 연 것을 기록하는 화면이 그렇다.
+   *
+   * 앱이 누르지 않은 닫힘도 온다: `header="fix"` 에서 GNB 를 접거나 펴면 계정 행이 다른 자리로
+   * 옮겨 서므로 패널이 닫히고 `false` 가 온다.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 누르면 뜨는 계정 리스트박스(`SAccountListBox`) 내용. **필수다** — 계정 행은 늘 이 패널의
+   * 트리거이고, 눌러도 아무것도 뜨지 않는 계정 행은 없다.
+   * 뜨는 방향은 패널이 놓인 자리가 정하므로 앱이 넘기지 않는다.
+   */
+  listBox: SAccountListBoxContent;
+}
+```
+
+### GNB_SYSTEM_COLORS
+
+```ts
+/**
+ * SGnbSystem 설정.
+ *
+ * 토큰은 GNB system 패널 한 벌(`--cmp-gnb-system-*`)이다.
+ *   패널(배경·경계·구분선·간격)      → --cmp-gnb-system-panel-*
+ *   도메인 태그                       → --cmp-gnb-system-domainTag-*
+ *   행 공통(높이·라운드·아이콘 프레임) → --cmp-gnb-system-item-*        (SSystemActionButton 과 공유)
+ *   알림 버튼                         → --cmp-gnb-system-alertButton-*
+ *   설정 버튼                         → --cmp-gnb-system-setting-*
+ *   펼침·접힘 패널 여백                → --cmp-gnb-system-project-padding · --cmp-gnb-system-min-padding
+ *
+ * 타이포그래피는 CSS 변수가 아니라 `.typo-*` 프리셋으로 나온다.
+ *   domainTag.typography      → typo-body-sm-medium   (12/500/20)
+ *   item.label.typography     → typo-body-sm-semibold (12/600/20)
+ *   alertButton.count         → typo-body-md-bold     (13/700/22)
+ */
+
+/** 색상(표면). light = 흰 면, dark = 오션블루 면. GNB 의 color 를 그대로 따라간다 */
+export const GNB_SYSTEM_COLORS = ['light', 'dark'] as const;
+```
+
+## Dependencies
+
+### Depends on
+
+- [SAccountListBox](../SAccountListBox)
+- [SGnb](../SGnb)
+- [SIcon](../SIcon)
+- [SPortal](../SPortal)
+- [SSystemActionButton](../SSystemActionButton)
+- [STooltip](../STooltip)
+
+### Graph
+
+```mermaid
+graph TD;
+  SGnbSystem --> SAccountListBox
+  SGnbSystem --> SGnb
+  SGnbSystem --> SIcon
+  SGnbSystem --> SPortal
+  SGnbSystem --> SSystemActionButton
+  SGnbSystem --> STooltip
+  style SGnbSystem fill:#f9f,stroke:#333,stroke-width:4px
+```

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

@@ -0,0 +1,179 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type SAccountListBoxContent } from '../SAccountListBox';
+import { type SSystemActionButtonProps } from '../SSystemActionButton';
+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<Exclude<SSystemActionButtonProps, {
+    type: 'account';
+}>, 'color'> & {
+    /** 목록 key. 없으면 순서를 key 로 쓴다 */
+    value?: string;
+};
+/** 알림 버튼 */
+export interface SGnbSystemAlert {
+    /** 라벨 텍스트. 기본 `'알림'` */
+    label?: string;
+    /**
+     * 읽지 않은 알림 개수. 1 이상이면 벨이 울리는 아이콘·강조색으로 바뀌고 개수가 붙는다.
+     * 개수를 적을 가로가 모자란 자리(접힌 레일 · 기본 폭보다 좁게 줄인 판)에서는 점 배지로 바뀐다.
+     * 표기는 컴포넌트가 맡는다 — 세 자리마다 콤마를 넣어 그리므로 앱이 포맷한 문자열을 넘기지 않는다.
+     */
+    count?: number;
+    /** 클릭 */
+    onClick?: () => void;
+    /**
+     * 알림 버튼에 붙는 안내 툴팁의 문구(한 줄이 한 항목). 주면 뜬다 — **문구만 앱이 정하고**
+     * 색·방향·여닫힘은 컴포넌트가 쥔다: 색은 판이 light 면 기본, 그 밖(dark·상단바)이면 강조색이고
+     * 방향은 자리가 정한다(판·접힌 레일이면 오른쪽, 상단바면 아래).
+     *
+     * 스스로 사라지지 않는다 — **알림 버튼을 누르거나, 버튼에 얹었다 커서를 뺄 때** 닫히고,
+     * 같은 값을 계속 넘기는 동안에는 다시 뜨지 않는다.
+     *
+     * **다시 띄우려면 비웠다가 다시 넘긴다**(`undefined` → 문구). 문구가 같아도 상관없다 —
+     * 컴포넌트는 닫았다는 사실만 기억하고 문구 내용은 기억하지 않으므로, 새 알림마다 같은 안내를
+     * 다시 띄우는 화면도 막히지 않는다.
+     */
+    tooltip?: string[];
+    /**
+     * 알림을 누르면 뜨는 목록의 **내용**. 주면 컴포넌트가 알림 버튼에 붙여 띄운다 —
+     * 목록에 무엇을 쌓을지는 서비스마다 다르지만 **뜨는 자리는 늘 같아야 하므로**, 방향·앵커·
+     * 여닫힘(바깥 클릭·ESC 포함)과 배경·라운드·그림자는 컴포넌트가 쥐고 앱은 안에 담을 것만 준다.
+     * 방향은 자리가 정한다 — 판·접힌 레일이면 버튼 오른쪽, 상단바면 아래.
+     */
+    listBox?: ReactNode;
+    /**
+     * 알림 목록이 열리고 닫힐 때. 여닫는 것은 알림 버튼이 스스로 하므로 **그 사실을 알아야 할
+     * 때만** 준다(연 김에 읽음 처리하거나, 열려 있는 동안 다른 층을 접어 두는 화면).
+     *
+     * 앱이 누르지 않은 닫힘도 온다: GNB 를 접거나 펴면 알림 버튼이 다른 자리로 옮겨 서므로
+     * 목록이 닫히고 `false` 가 온다(계정 행과 같다).
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * 안내 툴팁이 닫힐 때. 받아서 `tooltip` 을 비워 두는 것이 기본 사용법이다 — 그러면 앱이
+     * 다음에 넘기는 문구가 곧 다음 안내가 된다.
+     *
+     * 컴포넌트가 아는 "다시 뜨지 않는다" 는 **이 자리가 서 있는 동안**뿐이라(새로고침하거나
+     * GNB 를 접어 알림이 다른 자리로 옮겨 서면 새로 마운트된다), 그 사용자에게 두 번 다시 보이지
+     * 않아야 하면 앱이 이 신호를 저장해 두고 `tooltip` 을 그만 넘긴다.
+     */
+    onTooltipDismiss?: () => void;
+}
+/** 설정 버튼 */
+export interface SGnbSystemSetting {
+    /** 라벨 텍스트. 기본 `'설정'` */
+    label?: string;
+    /** 클릭 */
+    onClick?: () => void;
+}
+/** 계정 행 */
+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'> {
+    /**
+     * 색상(패널 표면). light = 흰 면, dark = 오션블루 면.
+     * 미지정 시 자기를 담은 SGnb 의 color 를 따른다(단독으로 쓰면 `'light'`).
+     */
+    color?: SGnbSystemColor;
+    /**
+     * 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다.
+     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. 상단바 자리에서는 뜻이 없다.
+     */
+    folded?: boolean;
+    /**
+     * 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외 · 계정 행은 `account` 로
+     * 따로 준다). 판에서는 맨 위에 쌓이고,
+     * 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다.
+     * 접히면 자리가 없어 렌더되지 않는다.
+     */
+    actions?: SGnbSystemAction[];
+    /** 도메인 태그 텍스트. 접히면 자리가 없어 렌더되지 않는다 */
+    domain?: string;
+    /**
+     * 알림 버튼. 없으면 렌더하지 않는다. 판에서는 설정과 나란히 서면 남는 폭을 먹고 혼자면 폭을 다 먹는다.
+     * 상단바에서는 자리가 넉넉하지 않아 라벨 없이 아이콘+개수만 선다.
+     */
+    alert?: SGnbSystemAlert;
+    /**
+     * 설정 버튼. 없으면 렌더하지 않는다. 판에서는 알림과 나란히 서면 제 폭만 갖고 혼자면 폭을 다 먹고,
+     * 상단바에서는 라벨 없이 아이콘만 선다.
+     * 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다.
+     */
+    setting?: SGnbSystemSetting;
+    /** 계정 행. 없으면 렌더하지 않는다 */
+    account?: SGnbSystemAccount;
+}
+/**
+ * SGnbSystem — GNB 의 system 조각들(액션 · 도메인 · 알림 · 설정 · 계정).
+ *
+ * 어디에 놓이느냐로 두 형태가 있고, 그 자리는 담은 SGnb 의 `header` 가 정해 내려준다(앱이 고르지 않는다).
+ * - `panel` (header="fix") — GNB 바닥에 깔리는 세로 판. 위에서부터 [행 목록(`actions`)] · 구분선 ·
+ *   [도메인 태그] · [알림 | 설정] · [계정] 을 쌓는다.
+ * - `top` (header="full") — 레이아웃 전폭 상단바의 오른쪽 끝에 서는 가로 한 줄.
+ *   [행 목록] | [알림] | [설정] | [도메인 계정] 순으로 서고 조각 사이에 세로 구분선이 놓인다
+ *   (도메인·계정은 한 덩어리라 그 사이만 선 없이 붙는다).
+ *
+ * 각 조각은 해당 prop 을 줄 때만 나타나므로, 서비스마다 필요한 만큼만 켜서 쓴다 — 계정만, 알림만,
+ * 설정만, 알림+계정 … 어떤 부분집합이어도 그 조합만으로 판이 성립하도록 다음을 지킨다.
+ *
+ * - **구분선은 양쪽에 내용이 있을 때만** 긋는다. `actions` 만 주면 뜻 없는 선이 남지 않는다.
+ * - **판에서 알림·설정은 혼자 서면 폭을 다 먹는다.** 둘이 나란히 서면 알림이 남는 폭을, 설정이 제 폭을
+ *   갖고 사이에 세로선이 놓인다. 어느 쪽이 빠져도 왼쪽 끝은 위아래 행과 맞는다.
+ * - **켜진 조각이 하나도 없으면 아무것도 렌더하지 않는다** — 빈 판은 GNB 바닥에 정체 모를 경계선만 남긴다.
+ *
+ * 판에서 알림·설정·계정은 늘 함께 붙어 다니는 한 덩어리라 사이를 띄우지 않고, 그 위 조각들만 간격을 갖는다.
+ * 상단바에서는 자리가 가로로 넉넉하지 않아 알림·설정이 라벨을 벗고 아이콘(+개수)만 남는다.
+ *
+ * `folded` 면 48px 레일 폭에 맞춘 min 형태가 된다 — **알림·계정 아이콘만** 남고 라벨·태그·행 목록·설정은
+ * 빠진다(시안). 알림 개수는 적을 자리가 없어 점 배지로 바뀐다. 둘 다 없는 조합(설정만 쓰는 앱 등)이면
+ * 접힌 패널은 렌더되지 않으므로, 접힌 상태에서도 닿아야 하는 것은 SGnb 의 `foldedTop`·`foldedFooter` 에 둔다.
+ * 상단바는 접어도 남으므로 `top` 에는 접힘 형태가 없다.
+ *
+ * `alert.count` 가 1 이상이면 벨이 울리는 아이콘(`bellRinging`)과 강조색으로 바뀐다 — light 는 파랑,
+ * 어두운 면은 노랑(토큰이 정한다). 0 이거나 없으면 조용한 벨(`bell`)에 기본 색이다.
+ *
+ * 안내 툴팁(`alert.tooltip`)은 문구를 받은 동안 떠 있다가 알림을 누르거나 커서를 빼면 닫힌다.
+ * 다시 띄우는 신호는 문구가 **없음 → 있음** 으로 바뀌는 것이라, 같은 문구도 비웠다 다시 넘기면
+ * 새 안내로 뜬다.
+ *
+ * 판이 **메뉴 기본 폭보다 좁으면**(GNB 의 `resizable` 로 줄인 컬럼) 알림 개수를 적을 가로가
+ * 모자라 접힘과 같은 점 배지로 바뀐다 — 숫자가 설정 버튼을 밀어내거나 잘리는 대신, 알림이
+ * 있다는 사실만 남긴다. 좁은지는 담은 SGnb 가 내려주므로 앱이 고르는 prop 이 없다.
+ *
+ * 색은 놓인 면을 따른다: 판 위는 `light`/`dark`(오션블루 판), 판 없이 상단바 면에 바로 얹는 `top` 의
+ * dark 는 한 단계 어두운 `darker`(네이비) 색표다 — GNB_SYSTEM_TOP_COLOR_CONFIG 가 그 대응을 쥔다.
+ *
+ * **놓이는 자리(`placement`)는 prop 이 아니다** — 자기를 담은 SGnb 가 `header` 로 정해 내려준다.
+ * 앱이 고르면 세로 판 자리에 가로 한 줄이 서는 조합이 만들어지고, 그것을 고를 이유가 있는 화면은 없다.
+ * `color`·`folded` 도 슬롯 안에서는 GNB 가 내려주므로 다시 넘기지 않는다.
+ * 판은 폭이 늘 부모를 가득 채우고, 상단바 줄은 내용 폭만 갖는다.
+ */
+export declare const SGnbSystem: import("react").ForwardRefExoticComponent<SGnbSystemProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};