sellmate-design-system-react 4.3.1 → 5.0.2

package/AGENTS.md

@@ -396,6 +396,24 @@ SModal.create({ component: OrderModal, componentProps: { orderId } })
   .onDismissed(() => {});
 ```
 
+#### 3-3-5. 닫기 경로 — `persistent` 는 기본이 `true` 다
+
+모달 3종(`SActionModal` · `SConfirmModal` · `SLoadingModal`)과 `SDrawer` 는 **백드롭 클릭·ESC 로 닫히지 않는 것이 기본**이다. 닫기 시도는 흔들림(shake)으로만 반응한다. 작성 중인 내용을 실수로 잃지 않게 하기 위한 것이다.
+
+| | 기본 닫기 경로 | 백드롭·ESC |
+| --- | --- | --- |
+| `SActionModal` · `SConfirmModal` · `SLoadingModal` | X 버튼, 모달 안의 버튼 | 막힘 (흔들림) |
+| `SDrawer` | X 버튼, footer 버튼 | 막힘 (흔들림) |
+| `SPopover` · `STooltip` · `SSelect` 등 floating | 바깥 클릭·ESC | **막지 않는다** — 이 규칙의 대상이 아니다 |
+
+따라서 다음을 지킨다.
+
+- **닫을 수단을 반드시 하나는 둔다.** `SActionModal` 에 `showClose` 도 `button`/`footerLeft` 도 없으면 사용자가 모달을 닫을 방법이 없다. 백드롭이 더 이상 탈출구가 아니다.
+- **`persistent` 를 `true` 로 직접 주지 않는다.** 기본값이므로 중복이다.
+- **`persistent={false}` 는 잃을 입력이 없을 때만.** 단순 알림처럼 임의로 닫혀도 아무것도 사라지지 않는 경우로 한정한다.
+
+작성 중인 내용이 있을 때 닫기를 시도하면 이탈 안내를 띄우는 것은 **소비 앱 몫**이다. 디자인 시스템은 dirty 상태를 알지 못하므로 백드롭·ESC 를 일괄 차단할 뿐이다. 안내가 필요하면 앱이 자체 dirty 판정 후 `SModal.confirm` 으로 띄운다.
+
 ### 3-4. 테이블 컬럼 정렬
 
 **값의 크기를 비교하는 숫자 컬럼은 예외 없이 오른쪽 정렬한다** (`align: 'right'`).

package/README.md

@@ -281,14 +281,14 @@ export default [...sellmate.configs.strict];
 | Atoms       | `SIcon` · `SBadge` · `SCard` · `SDraggableItem` · `SDraggableList` · `SExpansionItem` · `SExpansionList` · `SList` · `SListItem` · `STree` · `SSectionHeaderCard` · `SDivider` · `SScrollArea` · `STag` · `SButton` · `SCallout` · `SLinearProgress` · `SCircleProgress` · `SLoadingContainer` |
 | Control     | `STextLink` · `SDropdownButton` · `SGhostButton` · `SSwitch` · `SToggle`                                                                                                                                                                                                                       |
 | Overlays    | `STooltip` · `SPopover` · `SPortal` · `SPopup` · `SGuide`                                                                                                                                                                                                                                      |
-| Modals      | `SConfirmModal` · `SActionModal` · `SLoadingModal` · `SModal`                                                                                                                                                                                                                                  |
+| Modals      | `SConfirmModal` · `SActionModal` · `SLoadingModal` · `SDrawer` · `SModal`                                                                                                                                                                                                                      |
 | Layout      | `SGnb` · `SLayout` · `SPage`                                                                                                                                                                                                                                                                   |
 | Navigation  | `STabs` · `SPagination` · `SStepper`                                                                                                                                                                                                                                                           |
 | Data        | `STable` · `STableBar` · `SKeyValueTable`                                                                                                                                                                                                                                                      |
 | Feedback    | `SToast`                                                                                                                                                                                                                                                                                       |
 | SField (폼) | `SForm` · `SField` · `SCheckbox` · `SRadio` · `SRadioButton` · `SInput` · `STextarea` · `SSelect` · `SNumberInput` · `SChip` · `SChipInput` · `SBarcodeInput` · `SCalendar` · `SDatePicker` · `SDateRangePicker` · `STimePicker` · `STimeRangePicker` · `SFilePicker`                          |
 
-`SModalContainer` 는 모달 3종의 내부 공통 컨테이너로 **공개 export 가 아닙니다.** 소비자는 `SConfirmModal`/`SActionModal`/`SLoadingModal` 을 사용하세요.
+`SModalContainer` 는 모달 3종의 내부 공통 컨테이너로 **공개 export 가 아닙니다.** `SOverlayHeader` 는 모달·드로어 내부 제목 영역, `SFooter` 는 모달·드로어·팝업 하단 액션 영역 조합용 컴포넌트라 public export 에 포함하지 않습니다. 소비자는 `SConfirmModal`/`SActionModal`/`SLoadingModal`/`SDrawer`/`SPopup` 을 사용하세요.
 
 유틸리티도 함께 export 합니다.
 

package/dist/components/SActionModal/README.md

@@ -9,10 +9,10 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `open?` | `boolean` | — |  |
-| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) |
+| `persistent?` | `boolean` | — | 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** |
 | `modalTitle?` | `string` | `''` |  |
 | `description?` | `ReactNode` | — | 제목 오른쪽에 붙는 보조 설명 (sd-action-modal 의 header-sub-title 슬롯). 문자열이면 서브텍스트 스타일로 렌더하고, 노드를 넘기면 그대로 배치한다. |
-| `button?` | `SActionModalButton` | — | 하단 액션 버튼 (주 액션 1개). 의도적으로 단수다 — 보조 버튼(취소·삭제 등)은 `footerLeft` 슬롯에 직접 배치한다. |
+| `button?` | `SFooterButton` | — | 하단 액션 버튼 (주 액션 1개). 의도적으로 단수다 — 보조 버튼(취소·삭제 등)은 `footerLeft` 슬롯에 직접 배치한다. |
 | `footerLeft?` | `ReactNode` | — | footer 좌측 영역 (sd-action-modal 의 bottom-sub-content 슬롯). 보조 버튼이나 안내 문구를 넣는다. 버튼을 하나 더 쓰고 싶을 때 여기에 SButton 을 넣는다. |
 | `width?` | `number \| string` | — |  |
 | `height?` | `number \| string` | — |  |
@@ -29,14 +29,16 @@
 
 ### Depends on
 
-- [SButton](../SButton)
+- [SFooter](../SFooter)
 - [SModalContainer](../SModalContainer)
+- [SOverlayHeader](../SOverlayHeader)
 
 ### Graph
 
 ```mermaid
 graph TD;
-  SActionModal --> SButton
+  SActionModal --> SFooter
   SActionModal --> SModalContainer
+  SActionModal --> SOverlayHeader
   style SActionModal fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SActionModal/SActionModal.d.ts

@@ -1,20 +1,11 @@
 import { type ReactNode } from 'react';
-import { type SButtonColor, type SButtonSize } from '../SButton';
-export interface SActionModalButton {
-    label?: string;
-    color?: SButtonColor;
-    outline?: boolean;
-    size?: SButtonSize;
-    disabled?: boolean;
-    /** 클릭 핸들러. 모달은 자동으로 닫히지 않으므로 닫는 시점은 onOpenChange 로 직접 제어한다 */
-    onClick?: () => void;
-}
+import { type SFooterButton } from '../SFooter';
 export interface SActionModalProps {
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     /** 닫기(X) 버튼 클릭 (sdClose) */
     onClose?: () => void;
-    /** true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) */
+    /** 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** */
     persistent?: boolean;
     modalTitle?: string;
     /**
@@ -26,7 +17,7 @@ export interface SActionModalProps {
      * 하단 액션 버튼 (주 액션 1개).
      * 의도적으로 단수다 — 보조 버튼(취소·삭제 등)은 `footerLeft` 슬롯에 직접 배치한다.
      */
-    button?: SActionModalButton;
+    button?: SFooterButton;
     /**
      * footer 좌측 영역 (sd-action-modal 의 bottom-sub-content 슬롯).
      * 보조 버튼이나 안내 문구를 넣는다. 버튼을 하나 더 쓰고 싶을 때 여기에 SButton 을 넣는다.

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

@@ -1 +1 @@
-export { SActionModal, type SActionModalProps, type SActionModalButton } from './SActionModal';
+export { SActionModal, type SActionModalProps } from './SActionModal';

package/dist/components/SButton/README.md

@@ -19,14 +19,12 @@
 
 ### Used by
 
- - [SActionModal](../SActionModal)
  - [SConfirmModal](../SConfirmModal)
- - [SDrawer](../SDrawer)
  - [SDropdownButton](../SDropdownButton)
+ - [SFooter](../SFooter)
  - [SKeyValueTable](../SKeyValueTable)
  - [SLoadingModal](../SLoadingModal)
  - [SPopover](../SPopover)
- - [SPopup](../SPopup)
  - [SToast](../SToast)
 
 ### Depends on
@@ -38,14 +36,12 @@
 ```mermaid
 graph TD;
   SButton --> SIcon
-  SActionModal --> SButton
   SConfirmModal --> SButton
-  SDrawer --> SButton
   SDropdownButton --> SButton
+  SFooter --> SButton
   SKeyValueTable --> SButton
   SLoadingModal --> SButton
   SPopover --> SButton
-  SPopup --> SButton
   SToast --> SButton
   style SButton fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SConfirmModal/README.md

@@ -9,7 +9,7 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `open?` | `boolean` | — |  |
-| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) |
+| `persistent?` | `boolean` | — | 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** |
 | `type?` | `SConfirmModalType` | `'positive'` | 타입 (아이콘·메인버튼 색 결정) |
 | `modalTitle?` | `string` | `''` |  |
 | `titleClass?` | `string` | — | 제목 엘리먼트에 추가할 클래스 (sd-confirm-modal titleClass) |

package/dist/components/SConfirmModal/SConfirmModal.d.ts

@@ -6,7 +6,7 @@ export type ConfirmModalMainButton = 'primary_md' | 'primary_outline_md' | 'dang
 export interface SConfirmModalProps {
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
-    /** true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) */
+    /** 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** */
     persistent?: boolean;
     /** 타입 (아이콘·메인버튼 색 결정) */
     type?: SConfirmModalType;

package/dist/components/SDrawer/README.md

@@ -9,9 +9,12 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `open?` | `boolean` | — | 표시 여부 |
-| `persistent?` | `boolean` | `false` | true면 backdrop·ESC로 닫히지 않고 흔들림 효과를 준다. |
+| `persistent?` | `boolean` | `true` | backdrop·ESC로 닫히지 않고 흔들림 효과를 준다. **기본값 true** — Drawer는 내용을 작성·구성하는 곳이라 임의 닫힘을 막는 것이 기본이다. 닫기 경로는 X 버튼과 footer 버튼뿐이다. false로 주면 backdrop·ESC 닫기가 열린다. |
 | `title?` | `string` | `''` | 접근성 제목 및 헤더 제목 |
 | `width?` | `number \| string` | `572` | Drawer 너비. 기본값은 Figma drawer 기준 572px이다. |
+| `resizable?` | `boolean` | `false` | true면 왼쪽 테두리를 드래그해 너비를 조절할 수 있다. |
+| `minWidth?` | `number \| string` | — | 리사이즈 가능한 최소 너비(px, %, vw, vh) |
+| `maxWidth?` | `number \| string` | — | 리사이즈 가능한 최대 너비(px, %, vw, vh) |
 | `footerLeft?` | `ReactNode` | — | footer 좌측 슬롯 |
 | `button?` | `SDrawerButton` | — | 우측 기본 액션 버튼 |
 | `children?` | `ReactNode` | — |  |
@@ -29,14 +32,14 @@
 
 ### Depends on
 
-- [SButton](../SButton)
-- [SGhostButton](../SGhostButton)
+- [SFooter](../SFooter)
+- [SOverlayHeader](../SOverlayHeader)
 
 ### Graph
 
 ```mermaid
 graph TD;
-  SDrawer --> SButton
-  SDrawer --> SGhostButton
+  SDrawer --> SFooter
+  SDrawer --> SOverlayHeader
   style SDrawer fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SDrawer/SDrawer.d.ts

@@ -1,13 +1,6 @@
 import { type CSSProperties, type ReactNode } from 'react';
-import { type SButtonColor, type SButtonSize } from '../SButton';
-export interface SDrawerButton {
-    label?: string;
-    color?: SButtonColor;
-    outline?: boolean;
-    size?: SButtonSize;
-    disabled?: boolean;
-    onClick?: () => void;
-}
+import { type SFooterButton } from '../SFooter';
+export type SDrawerButton = SFooterButton;
 export interface SDrawerProps {
     /** 표시 여부 */
     open?: boolean;
@@ -15,12 +8,22 @@ export interface SDrawerProps {
     onOpenChange?: (open: boolean) => void;
     /** 닫기(X) 버튼 클릭 */
     onClose?: () => void;
-    /** true면 backdrop·ESC로 닫히지 않고 흔들림 효과를 준다. */
+    /**
+     * backdrop·ESC로 닫히지 않고 흔들림 효과를 준다.
+     * **기본값 true** — Drawer는 내용을 작성·구성하는 곳이라 임의 닫힘을 막는 것이 기본이다.
+     * 닫기 경로는 X 버튼과 footer 버튼뿐이다. false로 주면 backdrop·ESC 닫기가 열린다.
+     */
     persistent?: boolean;
     /** 접근성 제목 및 헤더 제목 */
     title?: string;
     /** Drawer 너비. 기본값은 Figma drawer 기준 572px이다. */
     width?: number | string;
+    /** true면 왼쪽 테두리를 드래그해 너비를 조절할 수 있다. */
+    resizable?: boolean;
+    /** 리사이즈 가능한 최소 너비(px, %, vw, vh) */
+    minWidth?: number | string;
+    /** 리사이즈 가능한 최대 너비(px, %, vw, vh) */
+    maxWidth?: number | string;
     /** footer 좌측 슬롯 */
     footerLeft?: ReactNode;
     /** 우측 기본 액션 버튼 */
@@ -36,4 +39,4 @@ export interface SDrawerProps {
  * 모달을 추가로 열면 새 모달이 Drawer 위에 쌓이고, Drawer 내부 floating은 전용 portal
  * container를 통해 Drawer의 backdrop 위에 표시된다.
  */
-export declare function SDrawer({ open, onOpenChange, onClose, persistent, title, width, footerLeft, button, children, className, style, }: SDrawerProps): import("react").JSX.Element;
+export declare function SDrawer({ open, onOpenChange, onClose, persistent, title, width, resizable, minWidth, maxWidth, footerLeft, button, children, className, style, }: SDrawerProps): import("react").JSX.Element;

package/dist/components/SFooter/README.md

@@ -0,0 +1,40 @@
+# SFooter
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SFooter
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `bg?` | `SFooterBg` | `'white'` | 배경색 |
+| `left?` | `ReactNode` | — | footer 좌측 slot |
+| `children?` | `ReactNode` | — | footer 좌측 slot. left와 함께 쓰면 left 뒤에 렌더된다 |
+| `button?` | `SFooterButton` | — | 우측 기본 액션 버튼 |
+| `className?` | `string` | — |  |
+| `leftClassName?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SDrawer](../SDrawer)
+ - [SPopup](../SPopup)
+
+### Depends on
+
+- [SButton](../SButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SFooter --> SButton
+  SActionModal --> SFooter
+  SDrawer --> SFooter
+  SPopup --> SFooter
+  style SFooter fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SFooter/SFooter.d.ts

@@ -0,0 +1,36 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type SButtonColor, type SButtonSize } from '../SButton';
+export type SFooterBg = 'white' | 'grey';
+export interface SFooterButton {
+    label?: string;
+    color?: SButtonColor;
+    outline?: boolean;
+    size?: SButtonSize;
+    disabled?: boolean;
+    onClick?: () => void;
+}
+/**
+ * @internal
+ * 모달·드로어·팝업 하단 영역 공통 props.
+ */
+export interface SFooterProps {
+    /** 배경색 */
+    bg?: SFooterBg;
+    /** footer 좌측 slot */
+    left?: ReactNode;
+    /** footer 좌측 slot. left와 함께 쓰면 left 뒤에 렌더된다 */
+    children?: ReactNode;
+    /** 우측 기본 액션 버튼 */
+    button?: SFooterButton;
+    className?: string;
+    leftClassName?: string;
+    style?: CSSProperties;
+}
+/**
+ * SFooter — overlay 계열 내부 전용 footer.
+ *
+ * @internal
+ * SActionModal/SConfirmModal/SDrawer/SPopup 의 하단 액션 영역만 공통화한다.
+ * 패키지 public export 에 추가하지 말 것.
+ */
+export declare function SFooter({ bg, left, button, children, className, leftClassName, style, }: SFooterProps): import("react").JSX.Element;

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

@@ -0,0 +1 @@
+export { SFooter, type SFooterBg, type SFooterButton, type SFooterProps } from './SFooter';

package/dist/components/SGhostButton/README.md

@@ -35,12 +35,12 @@
  - [SCalendar](../SCalendar)
  - [SChip](../SChip)
  - [SDateRangePicker](../SDateRangePicker)
- - [SDrawer](../SDrawer)
  - [SFilePicker](../SFilePicker)
  - [SGnb](../SGnb)
  - [SGuide](../SGuide)
  - [SInput](../SInput)
  - [SModalContainer](../SModalContainer)
+ - [SOverlayHeader](../SOverlayHeader)
  - [SPopover](../SPopover)
  - [SSelect](../SSelect)
  - [STimePicker](../STimePicker)
@@ -64,12 +64,12 @@ graph TD;
   SCalendar --> SGhostButton
   SChip --> SGhostButton
   SDateRangePicker --> SGhostButton
-  SDrawer --> SGhostButton
   SFilePicker --> SGhostButton
   SGnb --> SGhostButton
   SGuide --> SGhostButton
   SInput --> SGhostButton
   SModalContainer --> SGhostButton
+  SOverlayHeader --> SGhostButton
   SPopover --> SGhostButton
   SSelect --> SGhostButton
   STimePicker --> SGhostButton

package/dist/components/SGnb/README.md

@@ -33,10 +33,6 @@
 
 ## Dependencies
 
-### Used by
-
- - [SLayout](../SLayout)
-
 ### Depends on
 
 - [SGhostButton](../SGhostButton)
@@ -52,6 +48,5 @@ graph TD;
   SGnb --> SIcon
   SGnb --> SLayout
   SGnb --> STag
-  SLayout --> SGnb
   style SGnb fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -73,7 +73,11 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
  * 접힘/펼침은 GNB_FOLD_MS 동안의 슬라이드다 — 레일·메뉴가 함께 왼쪽으로 빠져나가고 펼치면 오른쪽에서 들어온다.
  * 페이지 쪽 폭은 fix 면 이 컴포넌트의 폭 전환이, full 이면 SLayout 의 메뉴 열 전환이 같은 길이로 맞춘다.
  *
- * SLayout 안에서 쓰면 type·header·folded 를 context 에서 읽어 앱이 중복으로 넘길 필요가 없다.
- * SLayout 없이 단독으로도 동작한다(prop 또는 기본값 사용).
+ * SLayout 안에서 쓰면 type·header·folded 를 context 에서 읽어 앱이 중복으로 넘길 필요가 없고,
+ * 자기 치수(컬럼 폭·상단바 높이·전환 길이)를 registerNav 로 되올려 프레임이 그 값으로 그리드를 깐다.
+ *
+ * SLayout 없이 단독으로도 동작한다(prop 또는 기본값 사용). 단 full 을 **페이지와 나란히** 놓으려면
+ * SLayout 이 필요하다 — 그 안에서만 루트를 display:contents 로 지워 상단바·본문을 프레임 그리드의
+ * header/nav 셀에 앉힌다. 단독일 때는 루트가 전폭 세로 상자로 남아 [상단바 / 본문] 을 스스로 쌓는다.
  */
 export declare const SGnb: import("react").ForwardRefExoticComponent<SGnbProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -143,5 +143,7 @@ export declare const GNB_FULL_LOGO_WIDTH_NO_LAUNCHER: number;
  * value 자체가 레일 아이템이면 그 값을, 어디에도 없으면 undefined 를 반환한다.
  */
 export declare function findGnbRailValue(items: SGnbMenuItem[], value: string): string | undefined;
+/** value 를 가진 아이템의 형제(같은 부모의 나머지 아이템) value 목록을 반환 → 아코디언 펼침용 */
+export declare function findGnbSiblingValues(items: SGnbMenuItem[], value: string): string[];
 /** value 로 선택된 아이템의 조상 value 목록(자기 자신 제외)을 반환 → 자동 펼침용 */
 export declare function findGnbAncestors(items: SGnbMenuItem[], value: string): string[];

package/dist/components/SLayout/README.md

@@ -10,7 +10,7 @@
 |------|------|---------|-------------|
 | `type?` | `SLayoutType` | `'box'` | 메뉴 스타일: box(라운드) / belt(풀폭 행). 자식 SGnb 가 이 값을 따른다. |
 | `header?` | `SLayoutHeader` | `'fix'` | 레이아웃 구조: fix(가로 분할) / full(풀폭 상단바). 자식 SGnb·SPage 가 이 값을 따른다. |
-| `useRail?` | `boolean` | `false` | GNB 좌측 레일 사용 여부. 자식 SGnb 가 이 값을 따르고, full 의 메뉴 열 폭도 레일만큼 넓어진다. 레일에 children 없는 아이템이 있으면 SGnb 가 header 를 full 로 강제하고, 이 레이아웃도 그에 맞춰 full 그리드로 선다. |
+| `useRail?` | `boolean` | `false` | GNB 좌측 레일 사용 여부. 자식 SGnb 가 이 값을 따르고, 그만큼 넓어진 컬럼 폭을 되올린다. 레일에 children 없는 아이템이 있으면 SGnb 가 full 상단바를 요구하고, 이 레이아웃도 그에 맞춰 full 그리드로 선다. |
 | `folded?` | `boolean` | — | GNB 접힘 상태 (controlled) |
 | `defaultFolded?` | `boolean` | `false` | GNB 초기 접힘 상태 (uncontrolled) |
 
@@ -27,15 +27,10 @@
  - [SGnb](../SGnb)
  - [SPage](../SPage)
 
-### Depends on
-
-- [SGnb](../SGnb)
-
 ### Graph
 
 ```mermaid
 graph TD;
-  SLayout --> SGnb
   SGnb --> SLayout
   SPage --> SLayout
   style SLayout fill:#f9f,stroke:#333,stroke-width:4px

package/dist/components/SLayout/SLayout.d.ts

@@ -1,32 +1,51 @@
 import { type HTMLAttributes } from 'react';
-import { type SGnbHeader, type SGnbType } from '../SGnb/gnb.config';
+import type { SGnbHeader, SGnbType } from '../SGnb/gnb.config';
 /** 메뉴 스타일: box(라운드) / belt(풀폭 행) — 자식 SGnb 의 메뉴 모양 */
 export type SLayoutType = SGnbType;
 /** 레이아웃 구조: fix(좌측 GNB + 페이지 가로 분할) / full(풀폭 상단바 + 아래에 메뉴|페이지) */
 export type SLayoutHeader = SGnbHeader;
+/**
+ * 자식 GNB 가 SLayout 에 올리는 자기 치수·요구사항.
+ *
+ * SLayout 은 GNB 의 내부 상수(레일·메뉴 폭, 상단바 높이, 전환 길이)도 items·activeRail 도 모른다 —
+ * 치수를 아는 쪽이 올리고 프레임은 받아 쓰기만 한다. GNB 내부 치수가 바뀌어도 프레임은 따라온다.
+ */
+export interface SLayoutNavState {
+    /**
+     * 펼친 GNB 컬럼 폭(px). 레일·메뉴 유무를 반영한 합이다.
+     * 접힘은 SLayout 이 folded 로 따로 접으므로 여기엔 펼친 폭만 담는다.
+     */
+    columnWidth: number;
+    /** 상단바 높이(CSS 길이) — header="full" 그리드의 1행 높이가 된다. */
+    topHeight: string;
+    /** 접힘 전환 길이(ms) — 페이지 열이 메뉴와 같은 길이로 미끄러지도록 맞춘다. */
+    foldMs: number;
+    /**
+     * 상단바가 레이아웃 전폭이어야 하는지.
+     * 레일에 리프 아이템이 있으면 메뉴 폭이 출렁여 fix 상단바가 함께 흔들리므로 GNB 가 true 로 올린다.
+     * true 면 header prop 과 무관하게 full 로 선다.
+     */
+    requireFullHeader: boolean;
+}
 export interface SLayoutContextValue {
     /** 메뉴 스타일 — 자식 SGnb 가 스타일을 맞추는 기준 */
     type: SLayoutType;
     /**
      * 상단바 구조 — 자식 SGnb·SPage 가 배치를 맞추는 기준(유효 header).
-     * 레일에 children 없는 아이템이 있어 SGnb 가 full 을 강제하면 여기에도 full 로 반영된다.
+     * 등록된 GNB 가 requireFullHeader 를 올리면 여기에도 full 로 반영된다.
      */
     header: SLayoutHeader;
-    /** GNB 좌측 레일 사용 여부 — 자식 SGnb 가 따르고, header="full" 의 메뉴 열 폭도 이 값을 반영한다 */
+    /** GNB 좌측 레일 사용 여부 — 자식 SGnb 가 따른다 */
     useRail: boolean;
     /** GNB 접힘 상태 */
     folded: boolean;
     /** 접힘 상태 변경 */
     setFolded: (folded: boolean) => void;
     /**
-     * 자식 SGnb 가 런타임 배치 상태를 알린다(SLayout 은 items·activeRail 을 모른다).
-     * - forceFull: 레일에 리프(children 없는) 아이템이 있어 header 를 full 로 강제했는지 → 프레임을 grid 로 맞춘다.
-     * - menuVisible: 활성 레일에 메뉴 패널이 깔렸는지 → false 면 메뉴 열을 빼 레일 폭만 예약한다(빈틈 방지).
+     * 자식 GNB 가 자기 치수·요구사항을 등록한다. 언마운트하거나 SLayout 밖으로 나가면 null 로 해제한다.
+     * 페인트 전에 반영돼야 하므로 GNB 쪽에서 layout effect 로 호출한다.
      */
-    reportGnbState: (state: {
-        forceFull: boolean;
-        menuVisible: boolean;
-    }) => void;
+    registerNav: (nav: SLayoutNavState | null) => void;
 }
 export declare const SLayoutContext: import("react").Context<SLayoutContextValue | null>;
 /**
@@ -40,8 +59,8 @@ export interface SLayoutProps extends HTMLAttributes<HTMLDivElement> {
     /** 레이아웃 구조: fix(가로 분할) / full(풀폭 상단바). 자식 SGnb·SPage 가 이 값을 따른다. */
     header?: SLayoutHeader;
     /**
-     * GNB 좌측 레일 사용 여부. 자식 SGnb 가 이 값을 따르고, full 의 메뉴 열 폭도 레일만큼 넓어진다.
-     * 레일에 children 없는 아이템이 있으면 SGnb 가 header 를 full 로 강제하고, 이 레이아웃도 그에 맞춰 full 그리드로 선다.
+     * GNB 좌측 레일 사용 여부. 자식 SGnb 가 이 값을 따르고, 그만큼 넓어진 컬럼 폭을 되올린다.
+     * 레일에 children 없는 아이템이 있으면 SGnb 가 full 상단바를 요구하고, 이 레이아웃도 그에 맞춰 full 그리드로 선다.
      */
     useRail?: boolean;
     /** GNB 접힘 상태 (controlled) */
@@ -57,10 +76,13 @@ export interface SLayoutProps extends HTMLAttributes<HTMLDivElement> {
  * 자식 SGnb·SPage 는 context 에서 type·header·folded 를 읽으므로 앱은 이 값들을 여기 한 곳에만 쓴다.
  * 높이는 기본 100%(부모를 채움) — 앱 루트로 쓸 땐 부모를 뷰포트 높이로 잡는다.
  *
- * - header="fix": [GNB(자기 폭 소유) | 페이지] 가로 flex.
- * - header="full": 상단바가 풀폭이고 그 아래에 [메뉴 | 페이지] 가 나란히 서야 하는데, SGnb 가 상단바와
- *   메뉴를 한 엘리먼트로 갖고 있어 사이에 끼워넣을 수 없다. 그래서 grid 로 깔고
- *   SGnb 를 전 셀에 겹친 뒤(root 는 투명) SPage 가 (2행,2열) = "메뉴 오른쪽 투명 영역" 을 차지한다.
- *   접으면 메뉴가 사라지므로 1열을 0 으로 접어 페이지가 전폭을 쓴다.
+ * 치수는 자식이 소유한다: GNB 가 registerNav 로 컬럼 폭·상단바 높이·전환 길이를 올리고
+ * 이 프레임은 그 값으로 그리드를 깐다(SLayout 은 GNB 내부 상수를 import 하지 않는다).
+ *
+ * - header="fix": [GNB(자기 폭 소유) | 페이지] 가로 flex. 프레임이 폭에 관여하지 않는다.
+ * - header="full": 이름 있는 영역으로 깐 그리드다.
+ *     "header header"  ← 전폭 상단바 (1행, 높이 = 등록된 topHeight)
+ *     "nav    page"    ← 메뉴 열(등록된 columnWidth) | 페이지
+ *   접으면 nav 열을 0 으로 접어 페이지가 전폭을 쓴다.
  */
 export declare const SLayout: import("react").ForwardRefExoticComponent<SLayoutProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SLoadingModal/README.md

@@ -9,7 +9,7 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `open?` | `boolean` | — |  |
-| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). 로딩 중 닫힘 방지에 유용 |
+| `persistent?` | `boolean` | — | 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** |
 | `state?` | `LoadingModalState` | `'loading'` | 상태 (loading: 스피너, error: 경고 아이콘) |
 | `progress?` | `number` | — | 진행률 (0–100) — 지정 시 determinate 스피너 |
 | `message?` | `string \| string[]` | — | 메시지 (없으면 state 기본값) |

package/dist/components/SLoadingModal/SLoadingModal.d.ts

@@ -4,7 +4,7 @@ export interface SLoadingModalProps {
     onOpenChange?: (open: boolean) => void;
     /** 닫기(X) 버튼 클릭 (sdClose) — error 상태에서만 노출 */
     onClose?: () => void;
-    /** true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). 로딩 중 닫힘 방지에 유용 */
+    /** 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** */
     persistent?: boolean;
     /** 상태 (loading: 스피너, error: 경고 아이콘) */
     state?: LoadingModalState;

package/dist/components/SModalContainer/README.md

@@ -11,7 +11,7 @@
 | `open?` | `boolean` | — | 표시 여부 (제어) |
 | `ariaTitle?` | `string` | `'모달'` | 접근성 제목 (스크린리더용). 시각 제목은 children이 담당 |
 | `showClose?` | `boolean` | `false` | 우측 상단 닫기 버튼 |
-| `persistent?` | `boolean` | `false` | true면 백드롭 클릭·ESC로 닫히지 않고 흔들림(shake) 애니메이션 (sd-modal-container persistent) |
+| `persistent?` | `boolean` | `true` | 백드롭 클릭·ESC로 닫히지 않고 흔들림(shake) 애니메이션 (sd-modal-container persistent). **기본값 true** — 모달은 작성 중인 내용을 잃지 않도록 임의 닫힘을 막는 것이 기본이다. 닫기 경로는 X 버튼과 모달 안의 버튼뿐이다. false로 주면 백드롭·ESC 닫기가 열린다. |
 | `width?` | `number \| string` | — | 너비/높이 |
 | `height?` | `number \| string` | — |  |
 | `children?` | `ReactNode` | — |  |

package/dist/components/SModalContainer/SModalContainer.d.ts

@@ -15,7 +15,11 @@ export interface SModalContainerProps {
     showClose?: boolean;
     /** 닫기(X) 버튼 클릭 시 발생 (sd-modal-container 닫기 버튼 대응) */
     onClose?: () => void;
-    /** true면 백드롭 클릭·ESC로 닫히지 않고 흔들림(shake) 애니메이션 (sd-modal-container persistent) */
+    /**
+     * 백드롭 클릭·ESC로 닫히지 않고 흔들림(shake) 애니메이션 (sd-modal-container persistent).
+     * **기본값 true** — 모달은 작성 중인 내용을 잃지 않도록 임의 닫힘을 막는 것이 기본이다.
+     * 닫기 경로는 X 버튼과 모달 안의 버튼뿐이다. false로 주면 백드롭·ESC 닫기가 열린다.
+     */
     persistent?: boolean;
     /** 너비/높이 */
     width?: number | string;
@@ -27,7 +31,7 @@ export interface SModalContainerProps {
 /**
  * SModalContainer — sd-modal-container 포팅 (Radix Dialog 기반).
  * 모든 모달(Confirm/Action/Loading)의 공통 컨테이너. 딤 오버레이 + 중앙 흰 카드.
- * persistent=true면 백드롭/ESC 닫기를 막고 흔들림 애니메이션을 준다.
+ * persistent(기본 true)면 백드롭/ESC 닫기를 막고 흔들림 애니메이션을 준다.
  *
  * @internal
  * 내부 전용 컴포넌트다. 패키지 public export(src/index.ts)에서 의도적으로 제외돼 있어

package/dist/components/SOverlayHeader/README.md

@@ -0,0 +1,45 @@
+# SOverlayHeader
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SOverlayHeader
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title?` | `ReactNode` | — | 시각 제목 |
+| `description?` | `ReactNode` | — | 제목 오른쪽 보조 설명 |
+| `showClose?` | `boolean` | `false` | 닫기 버튼 표시 |
+| `reserveCloseSpace?` | `boolean` | `false` | 외부 absolute 닫기 버튼 공간 확보 |
+| `className?` | `string` | — |  |
+| `titleClassName?` | `string` | — |  |
+| `descriptionClassName?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onClose` | `() => void` | 닫기 버튼 클릭 |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SDrawer](../SDrawer)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SOverlayHeader --> SGhostButton
+  SActionModal --> SOverlayHeader
+  SDrawer --> SOverlayHeader
+  style SOverlayHeader fill:#f9f,stroke:#333,stroke-width:4px
+```