sellmate-design-system-react 3.0.0 → 3.1.0

package/dist/components/SIcon/README.md

@@ -0,0 +1,91 @@
+# SIcon
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SIcon
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `SIconName` | — | 아이콘명 |
+| `size?` | `number \| string` | `24` | 아이콘 크기(px 또는 CSS 길이) |
+| `color?` | `SColor` | — | 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상. 미지정 시 currentColor 상속 |
+| `rotate?` | `0 \| 90 \| 180 \| 270` | — | 회전 각도 |
+| `label?` | `string` | — | 접근성 라벨. 없으면 aria-hidden 처리 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Used by
+
+ - [SButton](../SButton)
+ - [SCallout](../SCallout)
+ - [SCheckbox](../SCheckbox)
+ - [SChipInput](../SChipInput)
+ - [SConfirmModal](../SConfirmModal)
+ - [SDatePicker](../SDatePicker)
+ - [SDateRangePicker](../SDateRangePicker)
+ - [SDraggableItem](../SDraggableItem)
+ - [SDropdownButton](../SDropdownButton)
+ - [SExpansionItem](../SExpansionItem)
+ - [SField](../SField)
+ - [SFilePicker](../SFilePicker)
+ - [SGhostButton](../SGhostButton)
+ - [SGnb](../SGnb)
+ - [SGuide](../SGuide)
+ - [SKeyValueTable](../SKeyValueTable)
+ - [SList](../SList)
+ - [SLoadingModal](../SLoadingModal)
+ - [SNumberInput](../SNumberInput)
+ - [SPagination](../SPagination)
+ - [SPopover](../SPopover)
+ - [SSectionHeaderCard](../SSectionHeaderCard)
+ - [SSelect](../SSelect)
+ - [SStepper](../SStepper)
+ - [STable](../STable)
+ - [STag](../STag)
+ - [STextLink](../STextLink)
+ - [STimePicker](../STimePicker)
+ - [STimeRangePicker](../STimeRangePicker)
+ - [SToast](../SToast)
+ - [STooltip](../STooltip)
+
+### Graph
+
+```mermaid
+graph TD;
+  SButton --> SIcon
+  SCallout --> SIcon
+  SCheckbox --> SIcon
+  SChipInput --> SIcon
+  SConfirmModal --> SIcon
+  SDatePicker --> SIcon
+  SDateRangePicker --> SIcon
+  SDraggableItem --> SIcon
+  SDropdownButton --> SIcon
+  SExpansionItem --> SIcon
+  SField --> SIcon
+  SFilePicker --> SIcon
+  SGhostButton --> SIcon
+  SGnb --> SIcon
+  SGuide --> SIcon
+  SKeyValueTable --> SIcon
+  SList --> SIcon
+  SLoadingModal --> SIcon
+  SNumberInput --> SIcon
+  SPagination --> SIcon
+  SPopover --> SIcon
+  SSectionHeaderCard --> SIcon
+  SSelect --> SIcon
+  SStepper --> SIcon
+  STable --> SIcon
+  STag --> SIcon
+  STextLink --> SIcon
+  STimePicker --> SIcon
+  STimeRangePicker --> SIcon
+  SToast --> SIcon
+  STooltip --> SIcon
+  style SIcon fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SInput/README.md

@@ -0,0 +1,66 @@
+# SInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| number` | — | 값 (제어) |
+| `type?` | `'text' \| 'password' \| 'email' \| 'number' \| 'tel' \| 'search' \| 'url'` | `'text'` | 입력 타입 |
+| `size?` | `SFieldSize` | `'sm'` | 크기 |
+| `icon?` | `SIconName` | — | 좌측 아이콘명 |
+| `iconColor?` | `SColor` | — | 좌측 아이콘 색상 |
+| `prefix?` | `ReactNode` | — | 입력 앞(좌측) 커스텀 노드 — 원본 slot="prefix" |
+| `suffix?` | `ReactNode` | — | 입력 뒤(우측) 커스텀 노드 — 원본 slot="suffix" |
+| `clearable?` | `boolean` | `false` | 지우기 버튼 |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 자동 검증 |
+| `status?` | `SFieldStatus` | — | 필드 상태 ('default' | 'pass' | 'error') |
+| `focused?` | `boolean` | — | 포커스 상태 (제어/반영) |
+| `hovered?` | `boolean` | — | 호버 상태 (제어/반영) |
+| `inputClass?` | `string` | — | 내부 input 요소 className |
+| `inputStyle?` | `CSSProperties` | — | 내부 input 요소 style |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `labelTooltip?` | `string` | — | 레이블 툴팁 텍스트 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — | 어드온 정렬 |
+| `width?` | `number \| string` | — |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 값 변경 (sdUpdate) — 문자열 전달 |
+| `onChange` | `InputHTMLAttributes<HTMLInputElement>['onChange']` | 네이티브 onChange (form-agnostic 연동용, RHF 등) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SInput --> SField
+  SInput --> SGhostButton
+  SKeyValueTable --> SInput
+  style SInput fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SKeyValueTable/README.md

@@ -0,0 +1,59 @@
+# SKeyValueTable
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SKeyValueTable
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields?` | `SKeyValueField[][]` | `[]` | 2차원 배열. row → [th|td] 필드들 |
+| `values?` | `Record<string, unknown>` | `{}` | field name을 key로 하는 값 객체 (`{ [name]: value }`). 지정 시 해당 field의 값으로 사용되며, field별 `options.value`보다 우선합니다. `onChange`의 `detail.values`와 함께 controlled 패턴으로 사용합니다. |
+| `search?` | `boolean` | `false` | 우측 검색 패널 |
+| `radius?` | `'default' \| 'useTop' \| 'full'` | `'default'` | border-radius 제어 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onChange` | `(detail: SKeyValueChangeDetail) => void` | 값 변경 (sdChange) |
+| `onSearch` | `() => void` | 검색 클릭 (sdSearch) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SCheckbox](../SCheckbox)
+- [SDatePicker](../SDatePicker)
+- [SDateRangePicker](../SDateRangePicker)
+- [SFilePicker](../SFilePicker)
+- [SIcon](../SIcon)
+- [SInput](../SInput)
+- [SNumberInput](../SNumberInput)
+- [SRadio](../SRadio)
+- [SSelect](../SSelect)
+- [STextarea](../STextarea)
+- [STooltip](../STooltip)
+
+### Graph
+
+```mermaid
+graph TD;
+  SKeyValueTable --> SButton
+  SKeyValueTable --> SCheckbox
+  SKeyValueTable --> SDatePicker
+  SKeyValueTable --> SDateRangePicker
+  SKeyValueTable --> SFilePicker
+  SKeyValueTable --> SIcon
+  SKeyValueTable --> SInput
+  SKeyValueTable --> SNumberInput
+  SKeyValueTable --> SRadio
+  SKeyValueTable --> SSelect
+  SKeyValueTable --> STextarea
+  SKeyValueTable --> STooltip
+  style SKeyValueTable fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SLayout/README.md

@@ -0,0 +1,42 @@
+# SLayout
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLayout
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SLayoutType` | `'box'` | 메뉴 스타일: box(라운드) / belt(풀폭 행). 자식 SGnb 가 이 값을 따른다. |
+| `header?` | `SLayoutHeader` | `'fix'` | 레이아웃 구조: fix(가로 분할) / full(풀폭 상단바). 자식 SGnb·SPage 가 이 값을 따른다. |
+| `useRail?` | `boolean` | `false` | GNB 좌측 레일 사용 여부. 자식 SGnb 가 이 값을 따르고, full 의 메뉴 열 폭도 레일만큼 넓어진다. 레일에 children 없는 아이템이 있으면 SGnb 가 header 를 full 로 강제하고, 이 레이아웃도 그에 맞춰 full 그리드로 선다. |
+| `folded?` | `boolean` | — | GNB 접힘 상태 (controlled) |
+| `defaultFolded?` | `boolean` | `false` | GNB 초기 접힘 상태 (uncontrolled) |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onFoldedChange` | `(folded: boolean) => void` | 접힘 상태 변경 |
+
+## Dependencies
+
+### Used by
+
+ - [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/SLinearProgress/README.md

@@ -0,0 +1,17 @@
+# SLinearProgress
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLinearProgress
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `number` | `0` | 진행률 (0–100) |
+| `type?` | `SLinearProgressType` | `'primary'` | 색상 타입 |
+| `indeterminate?` | `boolean` | `false` | 진행률 없이 무한 애니메이션 |
+| `label?` | `string` | — | 하단 레이블 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+

package/dist/components/SList/README.md

@@ -0,0 +1,14 @@
+# SList
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SList
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | `ReactNode` | — | 리스트 컨테이너 내부에 렌더링할 내용 |
+| `useGap?` | `boolean` | `false` | 리스트 아이템 사이 gap 토큰 적용 여부 |
+| `usePadding?` | `boolean` | `false` | 리스트 컨테이너 padding 토큰 적용 여부 |
+

package/dist/components/SListItem/README.md

@@ -0,0 +1,19 @@
+# SListItem
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SListItem
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `SListItemSlot` | — | 리스트 아이템 제목 |
+| `depth?` | `1 \| 2 \| 3` | `1` | 중첩 단계. Figma 기준 1~3단계 |
+| `leading?` | `SListItemSlot` | — | 타이틀 앞에 표시할 아이콘/콘텐츠 |
+| `trailing?` | `SListItemSlot` | — | 타이틀 뒤에 표시할 태그/콘텐츠 |
+| `bordered?` | `boolean` | `false` | 외곽 테두리 사용 여부 |
+| `accentStripe?` | `boolean` | `false` | 아이템 왼쪽 accent stripe 표시 여부 |
+| `dense?` | `boolean` | `false` | 조밀한 높이 사용 여부 |
+| `disabled?` | `boolean` | `false` | 비활성 상태 여부 |
+

package/dist/components/SLoadingContainer/README.md

@@ -0,0 +1,29 @@
+# SLoadingContainer
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLoadingContainer
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | `false` | 오버레이 표시 여부 (Stencil의 show()/hide() 명령형 API → 제어 prop으로 대체) |
+| `message?` | `string` | — | 스피너 하단 메시지 |
+| `zIndex?` | `number` | `1200` | z-index. 기본값(1200)은 토스트(1100)·모달(1000/1001) 위 — 전체 화면을 막는 최상단 블로킹 오버레이 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Depends on
+
+- [SCircleProgress](../SCircleProgress)
+
+### Graph
+
+```mermaid
+graph TD;
+  SLoadingContainer --> SCircleProgress
+  style SLoadingContainer fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SLoadingModal/README.md

@@ -0,0 +1,52 @@
+# SLoadingModal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLoadingModal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — |  |
+| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). 로딩 중 닫힘 방지에 유용 |
+| `state?` | `LoadingModalState` | `'loading'` | 상태 (loading: 스피너, error: 경고 아이콘) |
+| `progress?` | `number` | — | 진행률 (0–100) — 지정 시 determinate 스피너 |
+| `message?` | `string \| string[]` | — | 메시지 (없으면 state 기본값) |
+| `useButton?` | `boolean` | `false` | 하단 버튼 표시 |
+| `buttonLabel?` | `string` | — | 버튼 레이블 (없으면 state 기본값) |
+| `width?` | `number \| string` | `520` |  |
+| `height?` | `number \| string` | `320` |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` |  |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) — error 상태에서만 노출 |
+| `onButtonClick` | `() => void` | 버튼 클릭 (sdClick) |
+
+## Dependencies
+
+### Used by
+
+ - [SModal](../SModal)
+
+### Depends on
+
+- [SButton](../SButton)
+- [SCircleProgress](../SCircleProgress)
+- [SIcon](../SIcon)
+- [SModalContainer](../SModalContainer)
+
+### Graph
+
+```mermaid
+graph TD;
+  SLoadingModal --> SButton
+  SLoadingModal --> SCircleProgress
+  SLoadingModal --> SIcon
+  SLoadingModal --> SModalContainer
+  SModal --> SLoadingModal
+  style SLoadingModal fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SModal/README.md

@@ -0,0 +1,192 @@
+# SModal
+
+> 수작성 문서 — SModal 은 컴포넌트가 아니라 **명령형 모달 서비스**라 `docs:gen`(Props/Events 표) 대상이 아니다.
+
+버튼 핸들러에서 바로 호출해 모달을 띄우는 명령형 API. 선언형 `<SConfirmModal open>` / `<SLoadingModal open>` 을 **대체하지 않고 추가로** 제공한다. (원본 디자인 시스템 `sdModal` 파리티)
+
+호출 시마다 `document.body` 에 컨테이너를 만들어 모달을 렌더하고, 닫힘 애니메이션이 끝나면 자동으로 언마운트한다. 모든 메서드는 체이닝 핸들 [`SModalRef`](#smodalref) 를 반환한다.
+
+| 메서드 | 띄우는 모달 | 용도 | 주요 콜백/제어 |
+|---|---|---|---|
+| [`SModal.confirm(options)`](#smodalconfirm) | `SConfirmModal` | 확인/취소 | `onOk` / `onCancel` / `onClose` |
+| [`SModal.loading(options?)`](#smodalloading) | `SLoadingModal` | 로딩·에러 (persistent 기본 true) | `onClick` / `update` |
+| [`SModal.create({ component })`](#smodalcreate) | `SActionModal` | 액션 모달 | `modalRef` 주입 → `ok/cancel/close/submit` |
+
+> **띄울 수 있는 모달은 `SActionModal` / `SConfirmModal` / `SLoadingModal` 세 가지뿐이고, 위 메서드가 1:1 로 대응한다.** 그 밖의 스타일로 모달을 띄우는 경로는 제공하지 않는다. `create` 는 컨테이너를 덧씌우지 않고 `component` 를 **그대로** 렌더하므로, `component` 는 루트에 `SActionModal` 을 렌더해야 한다 — 그러지 않으면 딤·카드 없이 콘텐츠만 뜨며, 개발 모드에서 `console.warn` 으로 경고한다.
+
+```ts
+import { SModal } from 'sellmate-design-system-react';
+```
+
+---
+
+## SModal.confirm
+
+아이콘 + 제목 + 메시지 + 확인/취소 버튼. `type` 에 따라 아이콘·메인 버튼 색이 결정된다.
+
+```tsx
+SModal.confirm({
+  type: 'negative',                 // 'positive' | 'negative' | 'default'
+  modalTitle: '삭제하시겠습니까?',
+  topMessage: ['이 작업은 되돌릴 수 없습니다.'],
+  mainButtonLabel: '삭제',
+  subButtonLabel: '취소',
+})
+  .onOk(() => deleteItem())
+  .onCancel(() => {});
+```
+
+**옵션 (`SConfirmOptions`)** — 선언형 `SConfirmModalProps` 에서 제어 흐름 props(`open`/`onOpenChange`/`onOk`/`onCancel`/`onClose`)를 제외한 전부. 주요 키: `type`, `modalTitle`, `topMessage`/`bottomMessage`, `mainButtonLabel`/`mainButtonName`, `subButtonLabel`, `tagSlot`/`optionSlot`, `persistent`.
+
+---
+
+## SModal.loading
+
+스피너/에러 모달. 로딩 중 임의 닫힘을 막기 위해 **`persistent` 기본값이 `true`** 다(백드롭·ESC로 안 닫힘). "띄우고 → 작업 → 결과 반영" 흐름을 `update()` / `close()` 로 제어한다.
+
+```tsx
+const ref = SModal.loading({ message: '업로드 중...' });
+try {
+  await upload();
+  ref.close();
+} catch {
+  ref.update({ state: 'error', message: '업로드 실패' })  // 표시 중 상태 갱신
+     .onClick(() => retry());                             // 「다시 시도」 버튼
+}
+```
+
+진행률:
+
+```tsx
+const ref = SModal.loading({ progress: 0, message: '파일 업로드 중...' });
+ref.update({ progress: 60 });          // 0–100
+ref.update({ progress: 100 });
+ref.close();
+```
+
+> **버튼 클릭은 자동 닫힘이 아니다.** error 상태의 버튼(기본 "다시 시도")은 `onClick` 만 발화하고 모달은 유지된다. consumer 가 `update()`(다시 로딩) / `close()` 로 후속 동작을 결정한다.
+
+**옵션 (`SLoadingOptions`)** — `state`('loading' | 'error'), `progress`(0–100), `message`(string | string[]), `useButton`, `buttonLabel`, `width`/`height`, `persistent`.
+
+---
+
+## SModal.create
+
+**`SActionModal` 을 루트로 렌더하는 컴포넌트**를 띄운다. `create` 는 컨테이너를 덧씌우지 않고 `component` 를 **그대로** 렌더하며, 표시 제어(`open` / `onOpenChange` / `onClose`)와 [`modalRef`](#smodalref) 를 주입하고 닫힘 애니메이션 종료 후 언마운트를 담당한다.
+
+컴포넌트는 주입받은 `open` / `onOpenChange` / `onClose` 를 **SActionModal 에 그대로 전달**해야 한다. 전달하지 않으면 모달이 열리지도, 닫히지도 않는다.
+
+```tsx
+import { SModal, SActionModal, type SModalCreateComponentProps } from 'sellmate-design-system-react';
+
+// componentProps 로 넘긴 값 + 주입 prop 을 함께 받는다
+interface OrderModalProps extends SModalCreateComponentProps {
+  orderId: string;
+}
+
+function OrderModal({ open, onOpenChange, onClose, modalRef, orderId }: OrderModalProps) {
+  return (
+    <SActionModal
+      open={open}
+      onOpenChange={onOpenChange}
+      onClose={onClose}
+      modalTitle="주문 처리"
+      button={{ label: '처리', onClick: () => modalRef.ok() }}
+    >
+      <p>주문번호 {orderId} 를 접수합니다.</p>
+    </SActionModal>
+  );
+}
+
+SModal.create({ component: OrderModal, componentProps: { orderId: 'ORD-001' } })
+  .onOk(() => toast('저장 완료'))
+  .onDismissed(() => cleanup());
+```
+
+**옵션 (`SCreateOptions<P>`)**
+
+| 키 | 타입 | 설명 |
+|---|---|---|
+| `component` | `ComponentType<P & SModalCreateComponentProps>` | 루트에 `SActionModal` 을 렌더하는 컴포넌트 |
+| `componentProps?` | `P` | 컴포넌트에 전달할 추가 props |
+
+**주입되는 prop (`SModalCreateComponentProps`)**
+
+| 키 | 타입 | 설명 |
+|---|---|---|
+| `open` | `boolean` | SActionModal 의 `open` 에 그대로 전달 |
+| `onOpenChange` | `(open: boolean) => void` | SActionModal 의 `onOpenChange` 에 그대로 전달 |
+| `onClose` | `() => void` | SActionModal 의 `onClose` 에 그대로 전달 |
+| `modalRef` | `SModalRef` | `ok()`/`cancel()`/`close()`/`submit()` 으로 자기 모달 제어 |
+
+### 비동기 제출 — 응답 보고 닫기
+
+SActionModal `button` 의 푸터 버튼은 클릭 시 **즉시 닫힌다**. 저장 API 응답에 따라 닫힘 여부를 정해야 하면 푸터 버튼 대신 **본문에 버튼을 두고** `modalRef` 로 닫힘 시점을 직접 제어한다.
+
+```tsx
+function OrderModal({ open, onOpenChange, onClose, modalRef, orderId }: OrderModalProps) {
+  const [error, setError] = useState('');
+  const handleSubmit = async () => {
+    try {
+      await save(orderId);
+      modalRef.ok();          // 성공 → onOk + 닫기
+    } catch {
+      setError('저장 실패');   // 실패 → 모달 유지
+    }
+  };
+  return (
+    // button 을 주지 않으면 푸터가 렌더되지 않는다
+    <SActionModal open={open} onOpenChange={onOpenChange} onClose={onClose} persistent modalTitle="주문 처리">
+      {error && <p>{error}</p>}
+      <SButton label="저장" onClick={handleSubmit} />
+      <SButton label="취소" onClick={() => modalRef.cancel()} />
+    </SActionModal>
+  );
+}
+```
+
+---
+
+## SModalRef
+
+모든 `SModal.*` 호출이 반환하고, `create` 에서는 컴포넌트 prop 으로도 주입되는 제어 핸들. 콜백 등록(체이닝)과 트리거/갱신 메서드를 함께 제공한다. 모달 종류에 따라 관련 있는 메서드만 실제로 발화한다.
+
+### 콜백 등록 (체이닝)
+
+| 메서드 | 발화 시점 |
+|---|---|
+| `onOk(fn)` | 확인 버튼(confirm) 또는 `ok()` |
+| `onCancel(fn)` | 취소 버튼(confirm) 또는 `cancel()` |
+| `onClose(fn)` | 닫기(X) 버튼 또는 `close()` |
+| `onClick(fn)` | 단일 버튼 모달(loading error)의 버튼 클릭 — **닫힘 없음** |
+| `onSubmit(fn)` | create 커스텀 모달의 `submit()` — **닫힘 없음** |
+| `onDismissed(fn)` | 사유 무관 완전히 닫혀 언마운트된 뒤(백드롭·ESC 포함) |
+
+### 트리거 / 제어
+
+| 메서드 | 동작 |
+|---|---|
+| `ok()` | `onOk` 발화 + 닫기 (저장/처리 성공) |
+| `cancel()` | `onCancel` 발화 + 닫기 (작업 취소) |
+| `close()` | `onClose` 발화 + 닫기 (중립적 닫기) |
+| `submit()` | `onSubmit` 발화 (닫힘 없음) |
+| `update(patch)` | 표시 중 옵션 갱신 (loading→error, progress 등). create 는 미지원. |
+
+모든 닫힘은 애니메이션 종료 후 `onDismissed` 로 수렴한다. 이미 닫힘이 시작된 뒤의 중복 트리거는 무시된다.
+
+---
+
+## 주의사항
+
+- **선언형과 공존**: 서비스는 추가 API다. open 상태가 앱 상태/라우트에 묶인 경우엔 선언형 `<SConfirmModal open>` / `<SLoadingModal open>` 이 더 적합하다.
+- **백드롭·ESC = 중립적 닫힘**: 특정 콜백(onClose 등) 없이 `onDismissed` 만 발화한다. 명시적 버튼·메서드만 onOk/onCancel/onClose 를 발화한다.
+- **Context 미상속**: `create` 의 커스텀 컴포넌트는 새 React 트리(createRoot)에서 렌더되어 부모의 Context Provider(Theme·Store 등)를 상속하지 않는다. 필요하면 컴포넌트 내부에서 직접 Provider 로 감싸라. (confirm/loading 은 토큰이 `:root` CSS 변수라 무관)
+- **`create` 의 `component` 는 SActionModal 을 루트로**: `create` 는 컨테이너를 덧씌우지 않으므로, 본문만 렌더하는 컴포넌트를 넘기면 딤·카드 없이 콘텐츠가 그대로 화면에 붙는다. TypeScript 는 이를 막지 못한다(`component` 타입이 아무 컴포넌트나 허용). 개발 모드에서는 마운트 직후 렌더 결과로 이를 감지해 `console.warn` 으로 경고한다 — 세 모달은 모두 Portal 로 `body` 에 렌더되므로 `create` 가 만든 host 는 비어 있어야 하는데, host 에 엘리먼트가 남아 있으면 모달이 아닌 것으로 판정한다.
+
+## Dependencies
+
+### Depends on
+
+- [SActionModal](../SActionModal)
+- [SConfirmModal](../SConfirmModal)
+- [SLoadingModal](../SLoadingModal)

package/dist/components/SModalContainer/README.md

@@ -0,0 +1,49 @@
+# SModalContainer
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SModalContainer
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — | 표시 여부 (제어) |
+| `ariaTitle?` | `string` | `'모달'` | 접근성 제목 (스크린리더용). 시각 제목은 children이 담당 |
+| `showClose?` | `boolean` | `false` | 우측 상단 닫기 버튼 |
+| `persistent?` | `boolean` | `false` | true면 백드롭 클릭·ESC로 닫히지 않고 흔들림(shake) 애니메이션 (sd-modal-container persistent) |
+| `width?` | `number \| string` | — | 너비/높이 |
+| `height?` | `number \| string` | — |  |
+| `children?` | `ReactNode` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` | 표시 상태 변경 |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 시 발생 (sd-modal-container 닫기 버튼 대응) |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SConfirmModal](../SConfirmModal)
+ - [SLoadingModal](../SLoadingModal)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SModalContainer --> SGhostButton
+  SActionModal --> SModalContainer
+  SConfirmModal --> SModalContainer
+  SLoadingModal --> SModalContainer
+  style SModalContainer fill:#f9f,stroke:#333,stroke-width:4px
+```