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

package/AGENTS.md

@@ -150,7 +150,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 | 층 | 무엇인가 | 컴포넌트 |
 | --- | --- | --- |
-| **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 패널) `SPage`(제목 영역은 `header` prop) |
+| **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 판 · 전폭 상단바 오른쪽 끝) `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` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SImage` `SLinearProgress` `SCircleProgress` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
@@ -534,7 +534,8 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | --- | --- | --- |
 | 앱 셸(상단바 + 내비 + 본문)을 세운다 | `SLayout` | §4-1 |
 | 좌측 내비게이션을 만든다 | `SGnb` | §4-1 |
-| 좌측 내비게이션 맨 아래에 서비스·도메인·알림·설정·계정 묶음을 붙인다 | `SGnbSystem` | §4-1 |
+| 좌측 내비게이션 맨 아래(또는 전폭 상단바 오른쪽 끝)에 서비스·도메인·알림·설정·계정 묶음을 붙인다 | `SGnbSystem` | §4-1 |
+| 앱 상단바 오른쪽 끝에 알림 벨·계정 이름을 둔다 | `SGnbSystem` (`SGnb` 의 `system` 슬롯 — 직접 만들지 않는다) | §4-1 |
 | 페이지 본문을 담는다 (패딩·스크롤) | `SPage` | §4-1 |
 | 페이지 제목(+ 서브 텍스트·뒤로가기·우측 슬롯)을 만든다 | `SPage` 의 `header` prop | §4-1 |
 | 제목 있는 섹션으로 묶는다 | `SSectionHeaderCard` | §3-7-8 |
@@ -1172,7 +1173,7 @@ const columns: STableColumn[] = [
 | `status` | 없음 | 상태 태그(`option.color`·`option.label`) | 화살표 | 라벨 대신 상태 자체가 제목일 때 |
 
 - **`SPage` 본문에 직접 놓지 않는다.** 폭을 가득 채우는 행이라 페이지에 바로 놓으면 표처럼 보인다. GNB system 패널·`SDrawer`·`SPopover` 처럼 **좁은 폭이 정해진 자리**에 쌓는다. 행 사이 간격은 `--cmp-gnb-system-panel-gap` 이다.
-- **GNB 맨 아래에 쌓는 것이라면 이 버튼을 직접 배치하지 말고 `SGnbSystem` 의 `actions` 에 넘긴다** (§4-1). 패널의 배경·구분선·도메인 태그·알림·계정까지 한 벌로 그려주므로, 조각을 손으로 조립할 이유가 없다.
+- **GNB 의 system 자리(맨 아래 판 · 전폭 상단바)에 놓는 것이라면 이 버튼을 직접 배치하지 말고 `SGnbSystem` 의 `actions` 에 넘긴다** (§4-1). 패널의 배경·구분선·도메인 태그·알림·계정까지 한 벌로 그려주므로, 조각을 손으로 조립할 이유가 없다.
 - **`color` 는 놓이는 표면을 따라간다** — 흰 면이면 `light`, 오션블루 면이면 `dark`, 네이비 면이면 `darker`. 배경과 다른 색을 고르면 버튼만 떠 보인다.
 - **상태는 default·hover 둘뿐이다.** 토큰에 selected 가 없으므로 "지금 열려 있는 항목"을 이 버튼으로 표시하지 않는다. 선택 상태가 필요한 자리면 `SGnb` 메뉴나 `SListItem`(§3-7-6) 이다.
 - **선행 아이콘이 비는 행은 없다.** `account` 는 `user` 고정, `status` 는 태그가 자리를 차지하고, 나머지는 `option.icon` 이 필수다.
@@ -1465,6 +1466,7 @@ const [selectedId, setSelectedId] = useState<string>();
 - `SChipFilter` 는 조건을 **칩 한 줄**로 접고, "필터 추가" 로 필요한 것만 꺼내 쓰게 한다. 칩을 누르면 편집 팝오버가 열리고, 날짜는 프리셋(오늘·지난 7일·사용자 지정)으로 고른다. 조건 후보가 많은 목록 화면에서 필터가 화면을 세로로 잡아먹는 것을 막는 용도다.
 - 검색 실행 시점이 다르다 — `SKeyValueTable` 필터는 앱이 검색 버튼을 직접 놓지만, `SChipFilter` 는 편집 팝오버가 닫히거나 "검색" 을 누를 때 `onSearch` 가 값 맵과 함께 호출된다. 값이 바뀌지 않았으면 호출되지 않는다.
 - **노출할 칩을 앱이 계산하지 않는다.** 바에 놓이는 것은 `fixed`·`required` 필드와 **`value` 에 값이 들어 있는 필드**다. 노출 목록을 밖에서 넘기는 prop 은 없다. 쿼리스트링·서버 상태에서 조건을 복원하는 목록 화면도 **`value` 만 넘기면 칩이 함께 살아나고**, 그 조건을 빼면 칩도 함께 빠진다 — 칩과 조회 조건이 어긋날 자리가 없다. "필터 추가" 로 꺼낸 필터는 값을 넣기 전에도 자리를 지키지만, "검색 초기화" 를 누르거나 화면을 다시 그리면 사라진다. 걸린 조건이 없으니 문제되지 않는다.
+- **후보가 하나뿐인 `select`·`select-multi` 는 자동으로 선택된다.** 고를 여지가 없는 목록이라 컴포넌트가 그 값을 채우고, 사용자가 고르지 않아도 `onValueChange` 가 그 값과 함께 호출된다 — 마운트 직후부터 그 조건이 값 맵에 들어 있다고 보고 조회를 짠다. 옵션이 API 응답이라 늦게 도착해도 도착한 시점에 채워지므로, 앱이 따로 채워 넣을 필요가 없다. 사용자가 그 값을 지우면 다시 채우지 않는다.
 - **`fields` 는 항상 그룹 배열이다.** 묶을 것이 없어도 `[{ fields: [...] }]` 로 한 겹 감싼다. 함께 걸어야 하는 조건(예: 기간 중 하나는 필수)이 있으면 그 필드들만 별도 그룹으로 떼어 `rule` 을 준다 — 규칙을 못 채운 동안 경고 툴팁이 떠 있고 `onSearch` 가 막힌다. 그룹 앞 구분선은 `divider` 로 켠다. 검증 단위와 구분선은 별개라, 묶어서 검증만 하고 싶으면 `divider` 를 주지 않는다.
 
 #### 3-7-12. 이미지 — SImage
@@ -1581,9 +1583,10 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 | `header` | 상단바 배치 | 로고 폭 | `topContent` |
 | --- | --- | --- | --- |
 | `"fix"` (기본) | `[런처 · 로고 … 폴드]` — 상단바가 GNB 컬럼 안에 있고 폴드가 컬럼 오른쪽 끝 | 내용 폭 | **렌더되지 않는다** (놓을 자리가 없다) |
-| `"full"` | `[런처 · 폴드 · 로고 · topContent]` — 상단바가 화면 전폭 | **140px 고정** (런처 없으면 172px) | 로고 오른쪽 남는 폭 전체 |
+| `"full"` | `[런처 · 폴드 · 로고 · topContent … system]` — 상단바가 화면 전폭이고 `system` 은 오른쪽 끝 | **140px 고정** (런처 없으면 172px) | 로고 오른쪽 남는 폭 전체 |
 
-- `topContent` 는 상단바 로고 오른쪽 슬롯이다. 전역 검색·계정 메뉴·알림처럼 **모든 페이지에 공통인 것만** 넣는다. 페이지별 액션은 여기가 아니라 §4-2 의 `STableBar` 로 간다.
+- `topContent` 는 상단바 로고 오른쪽 슬롯이다. 전역 검색처럼 **모든 페이지에 공통인 것만** 넣는다. 페이지별 액션은 여기가 아니라 §4-2 의 `STableBar` 로 간다.
+- **계정·알림·설정·도메인·서비스 전환은 `topContent` 에 손으로 만들지 않는다.** `header="full"` 이면 `system` 슬롯의 조각들이 상단바 오른쪽 끝으로 올라오므로, 그것들은 전부 `SGnbSystem` 이 그린다 (바로 아래 절).
 - 슬롯이 남는 폭을 통째로 받으므로 **정렬은 안에서 직접 잡는다** (좌측 정렬 + 우측은 `ml-auto`).
 - `header="full"` 에서 로고 자리는 140px 로 고정된다 — 로고 내용이 바뀌어도 `topContent` 시작점이 흔들리지 않게 하기 위함이다. 로고가 그보다 넓으면 잘리므로 이 폭에 맞춰 준비한다.
 - `onLauncherClick` 을 주지 않으면 런처가 렌더되지 않고, 그 자리(버튼 + 간격)를 로고 슬롯이 이어받아 172px 가 된다. `topContent` 시작점은 런처 유무와 관계없이 같은 자리다.
@@ -1594,12 +1597,14 @@ import { SModalOutlet } from 'sellmate-design-system-react';
     items={MENU} value={current} onValueChange={navigate}
     logo={<Logo />}
     topContent={
-      /* 남는 폭 전체를 받는다 — 왼쪽은 그대로, 오른쪽 끝은 ml-auto */
+      /* 남는 폭 전체를 받는다 — 왼쪽은 그대로, 오른쪽 끝은 ml-auto.
+         계정·알림은 여기 만들지 않는다 — system 슬롯이 상단바 오른쪽 끝에 그린다 */
       <div className="flex w-full items-center gap-sd-8">
         <SSearchInput value={keyword} onValueChange={setKeyword} onSearch={runSearch} placeholder="통합 검색" />
-        <SButton size="sm" color="neutral" outline label="내 계정" className="ml-auto" onClick={openAccount} />
+        <SButton size="sm" color="neutral" outline label="도움말" className="ml-auto" onClick={openHelp} />
       </div>
     }
+    system={<SGnbSystem alert={{ count: unreadCount, onClick: openAlerts }} account={{ label: userName, onClick: openAccount }} />}
   />
   <SPage background="frame">{children}</SPage>
 </SLayout>
@@ -1621,11 +1626,18 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 
 슬롯 안쪽 여백은 **슬롯 내용이 직접 갖는다** — 컴포넌트는 자리만 잡는다(폴드 슬롯만 좁은 폭에 맞춰 가운데 정렬한다). 메뉴 폭은 `resizable` 로 바뀔 수 있으므로 슬롯 내용은 고정 폭 대신 `w-full` 로 따라가게 둔다.
 
-#### GNB 맨 아래의 system 패널
+#### 서비스·도메인·알림·설정·계정 묶음 (system 슬롯)
 
-**서비스 전환·도메인·알림·설정·계정처럼 "지금 어떤 자격으로 보고 있는가" 를 다루는 묶음은 `SGnbSystem` 을 `SGnb` 의 `system` 슬롯에 넣는다.** 이 조각들을 `menuFooter` 에 손으로 조립하지 않는다 — 패널의 배경·위쪽 경계·구분선·행 간격이 전부 토큰으로 정해져 있어 직접 만들면 어긋난다.
+**서비스 전환·도메인·알림·설정·계정처럼 "지금 어떤 자격으로 보고 있는가" 를 다루는 묶음은 `SGnbSystem` 을 `SGnb` 의 `system` 슬롯에 넣는다.** 이 조각들을 `menuFooter` 나 `topContent` 에 손으로 조립하지 않는다 — 배경·경계·구분선·행 간격이 전부 토큰으로 정해져 있어 직접 만들면 어긋난다.
 
-`system` 은 다른 슬롯과 달리 **펼침·접힘 양쪽을 혼자 맡는다** — 펼치면 메뉴 컬럼 바닥에, 접히면(`header="fix"`) `foldedFooter` 아래 레일 바닥에 여백 없이 붙는다. 그래서 `menuFooter`/`foldedFooter` 로 나눠 줄 필요가 없다.
+**놓이는 자리는 `header` 가 정한다. 앱이 넘기는 것은 양쪽 모두 똑같다.**
+
+| `header` | system 이 서는 자리 | 형태 |
+| --- | --- | --- |
+| `"fix"` (기본) | GNB 맨 아래 (접히면 `foldedFooter` 아래 레일 바닥) | 세로 판 — 위에서부터 `actions` · 도메인 · `[알림 \| 설정]` · 계정 |
+| `"full"` | 전폭 상단바 **오른쪽 끝** | 가로 한 줄 — `actions` \| 알림 \| 설정 \| 도메인·계정 |
+
+`system` 은 다른 슬롯과 달리 **펼침·접힘 양쪽을 혼자 맡는다** — `header="fix"` 면 펼쳤을 때 메뉴 컬럼 바닥에, 접혔을 때 레일 바닥에 여백 없이 붙는다. 그래서 `menuFooter`/`foldedFooter` 로 나눠 줄 필요가 없다.
 
 ```tsx
 <SGnb
@@ -1643,14 +1655,15 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 />
 ```
 
-- **`color` 와 `folded` 를 주지 않는다.** `system` 슬롯에 있으면 GNB 가 자기 색과 접힘 형태를 내려준다. 두 prop 은 GNB 밖에서 이 패널을 단독으로 쓸 때만 준다.
+- **`color`·`folded`·`placement` 를 주지 않는다.** `system` 슬롯에 있으면 GNB 가 자기 색과 자리·형태를 내려준다. 이 prop 들은 GNB 밖에서 단독으로 쓸 때만 준다.
 - **각 조각은 해당 prop 을 줄 때만 나타난다 — 어떤 조합이어도 그것만으로 판이 성립한다.** 계정만, 알림만, 설정만, 알림+계정 … 서비스가 쓰는 것만 넘긴다. 조각을 빼려고 빈 문자열이나 빈 객체를 넣지 않는다(`setting={{}}` 은 "설정 버튼을 쓴다" 는 뜻이다).
   - 구분선은 **위아래 양쪽에 내용이 있을 때만** 그어진다 — `actions` 만 넘겨도 바닥에 뜻 없는 선이 남지 않는다.
   - 알림·설정은 **혼자 서면 폭을 다 먹고**, 둘이 나란히 서면 알림이 남는 폭을·설정이 제 폭을 갖는다. 어느 쪽이 빠져도 왼쪽 끝은 위아래 행과 맞으므로 앱이 정렬을 맞출 일이 없다.
   - **켜진 조각이 하나도 없으면 아무것도 렌더되지 않는다.** 조건부로 조각이 다 빠지는 화면에서도 GNB 바닥에 빈 판이 남지 않는다.
-- **접히면 알림·계정 아이콘만 남는다** — `actions`·`domain`·`setting` 은 48px 폭에 놓을 자리가 없어 렌더되지 않고, 알림 개수는 점 배지가 된다. **알림도 계정도 안 쓰는 조합이면 접힌 패널은 아예 렌더되지 않는다** — 접힌 상태에서도 반드시 눌러야 하는 것이 그 둘 밖에 있으면 `foldedTop`/`foldedFooter` 로 따로 준다.
+- **`header="fix"` 를 접으면 알림·계정 아이콘만 남는다** — `actions`·`domain`·`setting` 은 48px 폭에 놓을 자리가 없어 렌더되지 않고, 알림 개수는 점 배지가 된다. **알림도 계정도 안 쓰는 조합이면 접힌 패널은 아예 렌더되지 않는다** — 접힌 상태에서도 반드시 눌러야 하는 것이 그 둘 밖에 있으면 `foldedTop`/`foldedFooter` 로 따로 준다.
+- **`header="full"` 은 접어도 상단바가 남으므로 조각들도 그대로 남는다.** 대신 가로로 자리가 넉넉하지 않아 알림·설정이 라벨을 벗고 아이콘(알림은 개수까지)만 남는다 — 이건 컴포넌트가 알아서 하므로 앱이 라벨을 지우지 않는다.
 - **알림 개수는 `alert.count` 하나로 표현한다.** 1 이상이면 벨이 울리는 아이콘과 강조색으로 바뀐다 — 색은 GNB 색이 정하므로 앱이 직접 칠하지 않는다.
-- **`useRail` 에서 하위 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 패널도 함께 빠진다.** 항상 보여야 하는 계정·알림이라면 그런 레일 리프를 두지 않는다.
+- **`header="fix"` + `useRail` 에서 하위 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 패널도 함께 빠진다.** 항상 보여야 하는 계정·알림이라면 그런 레일 리프를 두지 않는다 — 또는 `header="full"` 로 두면 상단바에 남는다(그런 레일 리프가 있으면 GNB 가 `header` 를 `full` 로 강제한다).
 
 ### 4-2. 목록 페이지 (필터 + 테이블)
 

package/dist/components/SChipFilter/README.md

@@ -242,7 +242,14 @@ export type SChipFilterCustomValue = Record<string, unknown>;
 ```ts
 /** 후보 목록에서 고르는 필터 — select·select-multi·keyword */
 export interface SChipFilterOptionsField extends SChipFilterFieldBase {
-  /** 고를 수 있는 후보 목록 */
+  /** 고를 수 있는 후보 목록.
+   *
+   *  **select·select-multi 에서 고를 수 있는 후보가 하나뿐이면 그 값이 자동으로 선택된다** —
+   *  `required` 여부와 무관하고, 사용자가 고르지 않아도 `onValueChange` 로 값이 올라온다
+   *  (select 는 그 값, select-multi 는 그 값 하나짜리 배열). 옵션이 API 응답이라 늦게 도착해도
+   *  도착한 시점에 채워진다. 사용자가 그 값을 지우면 다시 채우지 않는다 —
+   *  다만 "검색 초기화"는 되돌려 놓는다(다른 기본값과 같은 규칙).
+   *  후보가 하나인데 비활성(`disabled`)이면 고를 수 없는 값이므로 채우지 않는다 */
   options?: SChipFilterOption[];
 }
 ```
@@ -275,7 +282,9 @@ export interface SChipFilterFieldBase {
    *  조용히 되살아난다. 처음부터 값이 정해져 있어야 하는 필터라면 그것이 `fixed`·`required` 다.
    *
    *  required인데 지정하지 않으면 타입별 내장 기본값(select: 첫 번째 옵션,
-   *  datepicker-day·datepicker-range: 오늘 날짜)을 대신 쓴다. 인라인(radioButton) datepicker-range
+   *  datepicker-day·datepicker-range: 오늘 날짜)을 대신 쓴다. select·select-multi 는
+   *  후보가 하나뿐일 때 required 가 아니어도 그 값이 기본값이 된다(options 참고) —
+   *  fixed·required 필드에 defaultValue 를 함께 주면 그쪽이 이긴다. 인라인(radioButton) datepicker-range
    *  필드는 팝오버 없이 바에 바로 노출되어 빈 상태로 둘 수 없으므로, 이 규칙과 무관하게 언제나
    *  오늘이 채워진다 */
   defaultValue?: SChipFilterValue;

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: 오늘 날짜)을 대신 쓴다. select·select-multi 는
+     *  후보가 하나뿐일 때 required 가 아니어도 그 값이 기본값이 된다(options 참고) —
+     *  fixed·required 필드에 defaultValue 를 함께 주면 그쪽이 이긴다. 인라인(radioButton) datepicker-range
      *  필드는 팝오버 없이 바에 바로 노출되어 빈 상태로 둘 수 없으므로, 이 규칙과 무관하게 언제나
      *  오늘이 채워진다 */
     defaultValue?: SChipFilterValue;
@@ -74,7 +76,14 @@ export interface SChipFilterFieldBase {
 }
 /** 후보 목록에서 고르는 필터 — select·select-multi·keyword */
 export interface SChipFilterOptionsField extends SChipFilterFieldBase {
-    /** 고를 수 있는 후보 목록 */
+    /** 고를 수 있는 후보 목록.
+     *
+     *  **select·select-multi 에서 고를 수 있는 후보가 하나뿐이면 그 값이 자동으로 선택된다** —
+     *  `required` 여부와 무관하고, 사용자가 고르지 않아도 `onValueChange` 로 값이 올라온다
+     *  (select 는 그 값, select-multi 는 그 값 하나짜리 배열). 옵션이 API 응답이라 늦게 도착해도
+     *  도착한 시점에 채워진다. 사용자가 그 값을 지우면 다시 채우지 않는다 —
+     *  다만 "검색 초기화"는 되돌려 놓는다(다른 기본값과 같은 규칙).
+     *  후보가 하나인데 비활성(`disabled`)이면 고를 수 없는 값이므로 채우지 않는다 */
     options?: SChipFilterOption[];
 }
 /** 프리셋으로 기간을 고르는 필터 — datepicker-range·datepicker-statistics */

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,25 @@
 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 형태로 튀지 않는다.
  */
 export interface SGnbSystemContextValue {
     /** GNB 색 */
     color: SGnbColor;
-    /** 이 자리가 접힌(48px) 레일인지 */
+    /** 이 자리가 접힌(48px) 레일인지. `placement: 'top'` 에서는 뜻이 없다 */
     folded: boolean;
+    /** 이 자리가 세로 판인지 전폭 상단바인지 */
+    placement: SGnbSystemPlacement;
 }
 export declare const SGnbSystemContext: import("react").Context<SGnbSystemContextValue | null>;
 export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
@@ -96,10 +103,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 +122,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,12 @@
 | 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 의 접힘 상태를 따른다. `placement="top"` 에서는 뜻이 없다. |
+| `placement?` | `SGnbSystemPlacement` | — | 놓이는 자리: `panel` = GNB 바닥의 세로 판, `top` = 전폭 상단바 위의 가로 한 줄. 미지정 시 자기를 담은 SGnb 가 `header` 로 정해 내려준다(fix → panel, full → top). |
+| `actions?` | `SGnbSystemAction[]` | — | 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외). 판에서는 맨 위에 쌓이고, 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다. 접히면 자리가 없어 렌더되지 않는다. |
 | `domain?` | `string` | — | 도메인 태그 텍스트. 접히면 자리가 없어 렌더되지 않는다 |
-| `alert?` | `SGnbSystemAlert` | — | 알림 버튼. 없으면 렌더하지 않는다. 설정과 나란히 서면 남는 폭을 먹고, 혼자면 폭을 다 먹는다 |
-| `setting?` | `SGnbSystemSetting` | — | 설정 버튼. 없으면 렌더하지 않는다. 알림과 나란히 서면 제 폭만 갖고, 혼자면 폭을 다 먹는다. 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다. |
+| `alert?` | `SGnbSystemAlert` | — | 알림 버튼. 없으면 렌더하지 않는다. 판에서는 설정과 나란히 서면 남는 폭을 먹고 혼자면 폭을 다 먹는다. 상단바에서는 자리가 넉넉하지 않아 라벨 없이 아이콘+개수만 선다. |
+| `setting?` | `SGnbSystemSetting` | — | 설정 버튼. 없으면 렌더하지 않는다. 판에서는 알림과 나란히 서면 제 폭만 갖고 혼자면 폭을 다 먹고, 상단바에서는 라벨 없이 아이콘만 선다. 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다. |
 | `account?` | `SGnbSystemAccount` | — | 계정 행. 없으면 렌더하지 않는다 |
 
 ## Types
@@ -24,6 +25,12 @@
 export type SGnbSystemColor = (typeof GNB_SYSTEM_COLORS)[number];
 ```
 
+### SGnbSystemPlacement
+
+```ts
+export type SGnbSystemPlacement = (typeof GNB_SYSTEM_PLACEMENTS)[number];
+```
+
 ### SGnbSystemAction
 
 ```ts
@@ -102,6 +109,17 @@ 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

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

@@ -1,6 +1,6 @@
 import { type HTMLAttributes } from 'react';
 import { type SSystemActionButtonProps } from '../SSystemActionButton';
-import { type SGnbSystemColor } from './gnbSystem.config';
+import { type SGnbSystemColor, type SGnbSystemPlacement } from './gnbSystem.config';
 /** 유니온을 유지한 채 키를 걷어낸다 — 그냥 Omit 하면 판별 유니온이 한 덩어리로 뭉개진다. */
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 /**
@@ -45,20 +45,30 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
     color?: SGnbSystemColor;
     /**
      * 접힌(min) 형태 — 48px 레일 폭에 맞춰 알림·계정 아이콘만 남는다.
-     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다.
+     * 미지정 시 자기를 담은 SGnb 의 접힘 상태를 따른다. `placement="top"` 에서는 뜻이 없다.
      */
     folded?: boolean;
     /**
-     * 패널 상단에 쌓는 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외).
-     * 아래에 다른 조각이 있으면 그 사이에 구분선이 그어진다. 접히면 자리가 없어 렌더되지 않는다.
+     * 놓이는 자리: `panel` = GNB 바닥의 세로 판, `top` = 전폭 상단바 위의 가로 한 줄.
+     * 미지정 시 자기를 담은 SGnb 가 `header` 로 정해 내려준다(fix → panel, full → top).
+     */
+    placement?: SGnbSystemPlacement;
+    /**
+     * 행 목록. 각 원소는 `SSystemActionButton` 의 props 다(`color` 제외). 판에서는 맨 위에 쌓이고,
+     * 상단바에서는 맨 왼쪽에 선다. 옆(아래)에 다른 조각이 있으면 그 사이에 구분선이 그어진다.
+     * 접히면 자리가 없어 렌더되지 않는다.
      */
     actions?: SGnbSystemAction[];
     /** 도메인 태그 텍스트. 접히면 자리가 없어 렌더되지 않는다 */
     domain?: string;
-    /** 알림 버튼. 없으면 렌더하지 않는다. 설정과 나란히 서면 남는 폭을 먹고, 혼자면 폭을 다 먹는다 */
+    /**
+     * 알림 버튼. 없으면 렌더하지 않는다. 판에서는 설정과 나란히 서면 남는 폭을 먹고 혼자면 폭을 다 먹는다.
+     * 상단바에서는 자리가 넉넉하지 않아 라벨 없이 아이콘+개수만 선다.
+     */
     alert?: SGnbSystemAlert;
     /**
-     * 설정 버튼. 없으면 렌더하지 않는다. 알림과 나란히 서면 제 폭만 갖고, 혼자면 폭을 다 먹는다.
+     * 설정 버튼. 없으면 렌더하지 않는다. 판에서는 알림과 나란히 서면 제 폭만 갖고 혼자면 폭을 다 먹고,
+     * 상단바에서는 라벨 없이 아이콘만 선다.
      * 접히면 자리가 없어 렌더되지 않는다 — 접힌 상태에서도 닿아야 하면 SGnb 의 `foldedFooter` 에 둔다.
      */
     setting?: SGnbSystemSetting;
@@ -66,28 +76,39 @@ export interface SGnbSystemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'c
     account?: SGnbSystemAccount;
 }
 /**
- * SGnbSystem — GNB 맨 아래에 붙는 system 패널.
+ * SGnbSystem — GNB 의 system 조각들(액션 · 도메인 · 알림 · 설정 · 계정).
+ *
+ * 어디에 놓이느냐(`placement`)로 두 형태가 있고, 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 이상이면 벨이 울리는 아이콘(`alert`)과 강조색으로 바뀐다 — light 는 파랑,
- * dark 는 노랑(토큰이 정한다). 0 이거나 없으면 조용한 벨(`bell`)에 기본 색이다.
+ * 어두운 면은 노랑(토큰이 정한다). 0 이거나 없으면 조용한 벨(`bell`)에 기본 색이다.
+ *
+ * 색은 놓인 면을 따른다: 판 위는 `light`/`dark`(오션블루 판), 판 없이 상단바 면에 바로 얹는 `top` 의
+ * dark 는 한 단계 어두운 `darker`(네이비) 색표다 — GNB_SYSTEM_TOP_COLOR_CONFIG 가 그 대응을 쥔다.
  *
- * SGnb 의 `system` 슬롯에 넣으면 `color` 와 `folded` 를 GNB 에서 받아오므로 앱이 다시 넘길 필요가 없다.
- * 단독으로 쓰면 두 prop 을 직접 준다. 폭은 늘 부모를 가득 채운다 — 좁은 GNB 컬럼에 놓이는 패널이다.
+ * SGnb 의 `system` 슬롯에 넣으면 `color`·`folded`·`placement` 를 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';