sellmate-design-system-react 9.0.0-beta.66 → 9.0.0-beta.67

package/AGENTS.md

@@ -579,6 +579,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 아이콘을 넣는다 | `SIcon` | |
 | 셀메이트 로고를 넣는다 | `SLogo` (`SIcon` 과 달리 `size` 가 **높이**이고, 색을 주지 않으면 브랜드색이다) | §3-7-14 |
 | 사진·썸네일을 보여준다 (로딩·실패 상태 포함) | `SImage` | §3-7-12 |
+| 작은 썸네일을 호버해서 크게 확인하게 한다 | `SImage previewOnHover` | 툴팁·팝오버로 직접 만들지 않는다 — 미리보기는 마우스를 통과시키고 원본의 로딩·실패도 스스로 표현한다. §3-7-12 |
 | 문장 안에서 다른 화면으로 보낸다 | `STextLink` | §3-5-6 |
 
 #### C. 동작을 실행시킨다
@@ -650,8 +651,8 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 | 하려는 일 | 컴포넌트 | 갈림 |
 | --- | --- | --- |
-| 화면 전체를 잠그고 기다리게 한다 | `SLoadingModal` (또는 `SModal.loading()`) | §3-2 |
-| 특정 영역만 덮고 기다리게 한다 | `SLoadingContainer` | §3-2 |
+| 화면 전체를 잠그고 기다리게 한다 | `loading.show()` — 진행률·실패 후 재시도 버튼이 필요하면 `SLoadingModal` (`SModal.loading()`) | §3-3-6 |
+| 특정 영역만 덮고 기다리게 한다 | `SLoadingContainer` | §3-3-6 |
 | 진행률을 가로 막대로 보여준다 | `SLinearProgress` | §3-7-9 |
 | 진행률·대기를 원형으로 보여준다 | `SCircleProgress` | §3-7-9 |
 
@@ -681,7 +682,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 작업 결과를 **일시적으로** 알림 | `SToast` (+ 루트에 `SToastContainer`) |
 | 진행 전 **확인/취소**를 받아야 할 때 | `SModal.confirm({...}).onOk(...)` — 무엇을 할지가 모달 밖에서 이미 정해진 경우다 (§3-3-2) |
 | 특정 UI 요소에 대한 **온보딩·기능 안내** | `SGuide` |
-| 로딩 중 화면 잠금 | `SLoadingModal` / 영역 로딩은 `SLoadingContainer` |
+| 로딩 중 화면 잠금 | `loading.show()` (§3-3-6) / 영역 로딩은 `SLoadingContainer` |
 
 **`SCallout` 의 `type` 은 놓이는 면이 정한다.** 안내의 강도가 아니라 배경 대비의 문제다.
 
@@ -713,7 +714,8 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | --- | --- |
 | hover 시 **짧은 보조 설명** (상호작용 없음) | `STooltip` |
 | 클릭 시 **상호작용 가능한** 작은 콘텐츠 (메뉴·미니 폼) | `SPopover` |
-| 로딩 중 화면 잠금 | `SModal.loading(...)` / `SLoadingModal` |
+| 로딩 중 화면 잠금 — 스피너와 메시지만 (기본) | `loading.show(...)` — 3-3-6 |
+| 로딩 중 화면 잠금 — **진행률·실패 후 재시도 버튼**이 필요하다 | `SModal.loading(...)` / `SLoadingModal` |
 | 그 밖에 **흐름을 끊고 띄우는 창** | `SPopup` · `SActionModal` · `SModal.confirm` — 아래 3-3-1 판별 순서로 고른다 |
 
 #### 3-3-1. SPopup vs SActionModal vs SModal.confirm — 판별 순서
@@ -886,6 +888,78 @@ SModal.create({ component: OrderModal, componentProps: { orderId } })
 
 작성 중인 내용이 있을 때 닫기를 시도하면 이탈 안내를 띄우는 것은 **소비 앱 몫**이다. 디자인 시스템은 dirty 상태를 알지 못하므로 백드롭·ESC 를 일괄 차단할 뿐이다. 안내가 필요하면 앱이 자체 dirty 판정 후 `SModal.confirm` 으로 띄운다.
 
+#### 3-3-6. 전역 로딩 오버레이 — `loading`
+
+화면 전체를 잠그고 기다리게 할 때 쓰는 명령형 싱글톤이다. 마운트할 것이 없다 — 첫 `show` 에 오버레이 루트가 `body` 에 자동으로 붙는다.
+
+**표면은 둘뿐이다.**
+
+| 하려는 일 | 사용 |
+| --- | --- |
+| 기다리게 한다 (거의 항상 이것) | `loading.show({ message })` → **핸들**. 부르면 걷고, `.update({ message })` 로 이 오버레이의 메시지만 바꾼다 |
+| 화면 전환·에러 복구로 짝을 더는 맞출 수 없다 | `loading.hideAll()` — 비상구다. 평소에는 쓰지 않는다 |
+
+**걷는 것은 `finally` 에 둔다.** 빠뜨리면 그 즉시 화면이 갇히고, 정상 경로에서는 아무 표시가 없다.
+
+```tsx
+const done = loading.show({ message: '저장 중입니다...' });
+try {
+  const payload = buildPayload(form);
+  done.update({ message: '전송 중입니다...' });   // 이 오버레이의 메시지만 바뀐다
+  await api.submit(payload);
+} finally {
+  done();                                        // 이 오버레이만 걷는다
+}
+```
+
+한 화면에서 같은 모양이 반복되면 **앱이 자기 헬퍼를 둔다.** 디자인 시스템은 원시 도구만 준다.
+
+```tsx
+// 소비 앱 쪽 유틸 — DS 가 가지지 않는다
+export const withLoading = async <T,>(task: Promise<T>, options?: { message?: string }) => {
+  const done = loading.show(options);
+  try {
+    return await task;
+  } finally {
+    done();
+  }
+};
+```
+
+- **반환 핸들을 반드시 잡는다.** 잡지 않으면 그 오버레이를 걷을 방법이 `hideAll()`(= 전부 걷기) 밖에 남지 않는다.
+- **메시지를 바꾸려고 `show()` 를 다시 부르지 않는다.** 하나 더 쌓여 한 번 걷는 것으로는 닫히지 않는다. 핸들의 `update()` 를 쓴다.
+- 겹쳐 부르면 그만큼 쌓이고 **마지막 하나가 걷힐 때** 닫힌다. 목록 재조회와 상세 저장이 겹쳐도 먼저 끝난 쪽이 아직 진행 중인 작업의 화면 잠금을 풀지 않는다. 화면에 그려지는 오버레이는 몇 개를 띄우든 **하나**이고, 표시되는 메시지는 맨 위 것이다.
+
+##### 제거된 API — 올라오면서 바꿀 것
+
+「스택 맨 위를 집는」 **위치 기준 API 를 전부 없앴다.** 호출자가 누구인지 볼 수 없어 겹친 작업끼리 남의 것을 걷거나 덮었고, 화면이 영영 닫히지 않는 사고의 원인이었다.
+
+| 없어진 것 | 무엇이었나 | 무엇으로 바꾸나 |
+| --- | --- | --- |
+| ❌ `loading.hide()` | 맨 위 **하나**를 걷었다 | **거의 전부 `show()` 핸들**을 `finally` 에서 부르는 것으로 바뀐다. `hideAll()` 은 라우트 이탈·에러 복구처럼 **진행 중이던 남의 작업까지 정리하는 것이 의도였던** 소수의 자리에만 |
+| ❌ `loading.update()` | 맨 위 항목의 메시지를 바꿨다 | `show()` 핸들의 `update()` |
+| ❌ `SLoadingViewport` | 뷰포트를 직접 배치하게 했다 | 트리에서 뺀다. 루트는 첫 `show` 에 자동으로 붙으므로 직접 두면 오버레이가 **두 겹**이 되어 딤만 진해졌다 |
+
+⚠️ **`hideAll()` 로 일괄 치환하지 않는다.** `hide()` 가 참조 카운트 이전에는 「전부 걷기」였으므로 그쪽이 맞아 보이지만, 그 시절 호출자의 의도는 **「내가 띄운 걸 닫는다」**였다 — 큐가 있다는 것을 몰랐을 뿐이다. `hideAll()` 로 옮기면 겹친 화면에서 **아직 진행 중인 작업의 잠금까지 풀어** 재클릭·중복 요청이 난다. 기본은 핸들이다.
+
+> **왜 이 실수가 쉬운가** — `show()` 를 몇 번 부르든 **화면에 그려지는 오버레이는 하나**다. 내부 카운트는 화면에 드러나지 않으므로 `hide()` 뒤에 오버레이가 남아도 「안 닫혔다」로만 보이고 「하나 남았다」로는 보이지 않는다. 그래서 위치로 짝을 맞추는 방식은 눈으로 검증할 수 없고, 핸들로 소유권을 명시하는 것이 유일한 방법이다.
+
+⚠️ **`show()` 가 두 번 불리는 경로도 함께 본다.** 같은 변경에서 `show()` 의 의미도 바뀌었다 — 그전에는 다시 부르는 것이 **갱신**이었고 지금은 하나 더 쌓인다. 그래서 아래는 `hide()` 를 안 썼어도 오버레이를 남긴다.
+
+```tsx
+❌ loading.show({ message: '1/2 ...' });
+   loading.show({ message: '2/2 ...' });   // 그때는 갱신, 지금은 하나 더 쌓인다
+   done();                                  // 하나만 걷힌다 → 남는다
+
+✅ const done = loading.show({ message: '1/2 ...' });
+   done.update({ message: '2/2 ...' });
+   done();
+```
+
+> **원본(Quasar `Loading`)과의 차이는 둘뿐이고 둘 다 안전 때문이다.** 원본의 인자 없는 `hide()` 는 「전부 걷기」이므로 이름을 되쓰면 기존 호출의 의미가 컴파일 에러 없이 바뀐다 — 그래서 `hideAll()` 이다. 그리고 원본은 겹친 작업을 앱이 준 `group` 이름으로 가르지만(안 주면 먼저 끝난 쪽이 남의 잠금을 푼다), 여기서는 `show()` 마다 항목이 따로 생겨 앱이 무엇을 빠뜨려도 그 일이 없다.
+
+> **영역만 덮을 때는 `SLoadingContainer` 를 직접 배치한다** (`open` prop 제어). `loading` 은 화면 전체를 잠그는 전역 오버레이 전용이다.
+
 ### 3-4. 테이블 컬럼 — 정렬·너비·헤더
 
 #### 정렬과 너비는 같은 표에서 정한다
@@ -1910,13 +1984,23 @@ const [selectedId, setSelectedId] = useState<string>();
 - **크기는 `ratio` 와 너비로 준다.** `ratio` 기본값이 `1`(정사각형)이라 너비만 주면 정사각형이 된다. `className`/`style` 로 높이를 직접 주면 그쪽이 이기고 `ratio` 는 무시된다.
 - 상자를 채우는 방식은 `fit`(기본 `cover`), 붙는 위치는 `position` 이다. 안쪽 `<img>` 에 네이티브 속성이 필요하면 `imgProps` 로 넘긴다 — 목록에서 고스트 드래그를 막는 `imgProps={{ draggable: false }}` 가 대표적이다.
 - 썸네일이 많은 목록에서는 `loadingShowDelay` 를 준다. 캐시된 이미지가 즉시 로드될 때 스피너가 한 프레임 번쩍이는 것을 막는다.
+- **썸네일이 작아 내용을 알아볼 수 없으면 `previewOnHover` 를 켠다.** 호버하면 큰 이미지가 포털로 뜬다 — 상품 목록에서 사진을 확인하려고 상세 화면까지 들어가는 일을 없앤다. **툴팁이나 팝오버로 직접 만들지 않는다**: 미리보기는 마우스를 통과시켜 아래 행의 클릭을 가로채지 않고, 원본의 로딩·실패도 스스로 표현한다.
+  - 목록 썸네일과 원본 URL 이 다르면 원본을 `previewSrc` 로 준다. 주지 않으면 썸네일을 그대로 확대해서 흐릿하다.
+  - **뜨는 자리를 앱이 정하지 않는다.** 미리보기는 썸네일 한가운데에서 오른쪽 아래로 펼쳐지고, 창 밖으로 넘치면 넘친 만큼만 왼쪽·위로 밀린다(반대편으로 뒤집히지 않는다). 방향을 고르는 prop 은 없다.
+  - 크기는 `previewSize` 로 줄일 수 있고 **상한은 200px** 이다. 그보다 큰 값을 줘도 200 으로 잘린다 — 미리보기가 화면을 덮지 않게 하는 규격이다.
+  - 미리보기 상자는 정사각형이고 이미지는 `contain` 으로 들어간다 — 세로로 긴 이미지도 잘리지 않는다. `ratio`·`fit` 은 썸네일 쪽에만 적용된다.
 
 ```tsx
 ✅ <SImage src={item.thumbnailUrl} alt={item.name} style={{ width: 64 }} />   {/* 정사각 썸네일 */}
 ✅ <SImage src={banner} ratio={16 / 9} className="w-full" />                  {/* 가로형 배너 */}
+✅ <SImage src={item.thumbnailUrl} previewOnHover previewSrc={item.imageUrl}  {/* 호버로 원본 확인 */}
+     alt={item.name} style={{ width: 64 }} />
 
 ❌ <img src={item.thumbnailUrl} />                                            {/* 로딩·실패 상태가 없다 */}
 ❌ {loading ? <SCircleProgress indeterminate /> : <SImage src={url} />}        {/* SImage 가 이미 한다 */}
+❌ <STooltip content={<img src={item.imageUrl} />}>                           {/* previewOnHover 를 쓴다 */}
+     <SImage src={item.thumbnailUrl} />
+   </STooltip>
 ```
 
 #### 3-7-14. 로고 — SLogo
@@ -3110,6 +3194,7 @@ export default function ExcelFilePopupPage() {
 - [ ] 모달·드로어의 하단 버튼을 본문이 아니라 `button` · `footerLeft` prop 으로 넘겼는가 (§3-3-4), 카드 안에서 닫히는 액션도 같은 prop 으로 넘겼는가 (§3-7-8)
 - [ ] 아래에 버튼이 있는 자리(모달·드로어·카드)의 `STextarea autogrow` 에 `maxRows` 를 함께 줬는가 (§3-7-1 — 없으면 긴 글이 버튼을 화면 밖으로 밀어낸다)
 - [ ] 앱 부트스트랩의 Provider 안쪽에 `<SModalOutlet />` 이 한 번 렌더되어 있는가 (§4-1 — 없으면 모달 안에서 앱 훅이 죽는다), 그 대신으로 모달 컴포넌트를 Provider 로 다시 감싸지 않았는가
+- [ ] 전역 로딩의 `loading.show()` 반환 핸들을 잡아 `finally` 에서 그것만 불렀는가, 메시지를 바꾸려고 `show()` 를 두 번 부르지는 않았는가 (§3-3-6 — 걷기를 빠뜨리면 화면이 갇히고, 두 번 부르면 하나 더 쌓여 오버레이가 남는다)
 - [ ] 고른 컴포넌트를 §2-0 의 제 층에 놓았는가 (요소를 `SPage` 에 직접 놓지 않았는가, 블록을 `div` 로 감싸지 않았는가)
 - [ ] §2-0 포함 규칙을 지켰는가 (카드 안 카드 ❌, 표 셀 안 블록 ❌)
 - [ ] 블록 순서가 §2-0 순서와 맞는가 (제목 → 안내 → 필터 → 툴바 → 본문 → 페이지네이션 → 하단 액션)

package/dist/components/SBarChart/barChart.config.d.ts

@@ -51,14 +51,6 @@ export declare const BAR_DATA_LABEL_COLOR = "var(--cmp-chart-dataLabel-color-def
  */
 export declare const BAR_DATA_LABEL_TYPO = "typo-body-sm-medium";
 export declare const BAR_DATA_LABEL_TYPO_HOVER = "typo-body-md-bold";
-/**
- * 흐려지고 또렷해지는 전환 — 막대와 값 라벨에 같이 건다.
- *
- * 둘의 속도가 다르면 막대는 이미 물러났는데 숫자만 뒤늦게 따라와 어긋나 보인다.
- * 전환 대상은 불투명도뿐이다. 짚은 항목의 라벨이 커지는 것(`typo-*` 교체)은
- * 글자가 늘어나는 중간 상태가 오히려 읽기 나빠 즉시 바꾼다.
- */
-export declare const BAR_HOVER_TRANSITION = "transition-opacity duration-200 ease-out motion-reduce:transition-none";
 export interface BandLayout {
     /** 카테고리 하나가 차지하는 폭(px) */
     band: number;

package/dist/components/SImage/README.md

@@ -19,6 +19,9 @@
 | `loadingSlot?` | `ReactNode` | — | 로딩 중 표시를 직접 지정한다 (기본: 스피너) |
 | `errorSlot?` | `ReactNode` | — | 실패·빈 상태 표시를 직접 지정한다 (기본: 빈 이미지 아이콘) |
 | `imgProps?` | `ImgHTMLAttributes<HTMLImageElement>` | — | 안쪽 `<img>` 로 넘길 네이티브 속성 (srcSet · sizes · crossOrigin · draggable 등) |
+| `previewOnHover?` | `boolean` | `false` | 호버하면 큰 이미지를 포털로 띄운다. 썸네일이 작아 내용을 알아볼 수 없는 자리에 쓴다 |
+| `previewSrc?` | `string` | — | 미리보기에 띄울 경로. 원본 URL 이 썸네일과 다를 때 준다 (기본: `src` 와 같은 경로) |
+| `previewSize?` | `number` | `PREVIEW_MAX_SIZE` | 미리보기 상자의 한 변(px). 상자는 정사각형이고 이미지는 `contain` 으로 들어간다. **200px 이 상한이라 더 큰 값을 줘도 200 으로 잘린다** — 미리보기가 화면을 덮지 않게 하는 규격이다. |
 
 #### Events
 

package/dist/components/SImage/SImage.d.ts

@@ -27,15 +27,18 @@ export interface SImageProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onLoa
     errorSlot?: ReactNode;
     /** 안쪽 `<img>` 로 넘길 네이티브 속성 (srcSet · sizes · crossOrigin · draggable 등) */
     imgProps?: ImgHTMLAttributes<HTMLImageElement>;
+    /** 호버하면 큰 이미지를 포털로 띄운다. 썸네일이 작아 내용을 알아볼 수 없는 자리에 쓴다 */
+    previewOnHover?: boolean;
+    /** 미리보기에 띄울 경로. 원본 URL 이 썸네일과 다를 때 준다 (기본: `src` 와 같은 경로) */
+    previewSrc?: string;
+    /**
+     * 미리보기 상자의 한 변(px). 상자는 정사각형이고 이미지는 `contain` 으로 들어간다.
+     * **200px 이 상한이라 더 큰 값을 줘도 200 으로 잘린다** — 미리보기가 화면을 덮지 않게 하는 규격이다.
+     */
+    previewSize?: number;
     /** 로드 완료. 로드된 src 를 넘긴다 */
     onLoad?: (src: string) => void;
     /** 로드 실패 */
     onError?: (event: SyntheticEvent<HTMLImageElement>) => void;
 }
-/**
- * SImage — 이미지 로딩·실패 상태를 스스로 표현하는 이미지 상자.
- *
- * 로딩 중에는 스피너, `src` 가 없거나 로드에 실패하면 빈 이미지 아이콘을 컨테이너 높이에
- * 비례한 크기로 가운데에 그린다.
- */
 export declare const SImage: import("react").ForwardRefExoticComponent<SImageProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -1,2 +1,2 @@
 export { SLoadingContainer, type SLoadingContainerProps } from './SLoadingContainer';
-export { loading, SLoadingViewport } from './loading';
+export { loading, type SLoadingHandle } from './loading';

package/dist/components/SLoadingContainer/loading.d.ts

@@ -1,26 +1,45 @@
-/** 오버레이 뷰포트 — 스토어를 구독해 SLoadingContainer 를 렌더한다. 직접 배치도 가능. */
-export declare function SLoadingViewport(): import("react").JSX.Element;
+/**
+ * `show()` 가 돌려주는 핸들 — **이 호출 하나**만 걷고 갱신한다.
+ * 부르면 걷고, `update()` 로 이 호출의 메시지만 바꾼다. 둘 다 id 기준이라 겹친 다른 작업의
+ * 항목은 건드리지 않는다. (Quasar `Loading.show()` 가 돌려주는 그룹 함수와 같은 자리다.)
+ */
+export interface SLoadingHandle {
+    (): void;
+    update(options: {
+        message?: string;
+    }): void;
+}
 export declare const loading: {
     /**
      * 로딩 오버레이 표시. 겹쳐 부르면 그만큼 쌓이고 **마지막 하나가 걷힐 때** 닫힌다.
-     * 반환값은 이 호출 하나만 걷는 함수다(두 번 불러도 한 번만 걷힌다) — `hide()` 대신 이것을
-     * 쓰면 짝이 어긋나지 않는다.
+     * 반환값은 이 호출 하나를 걷고 갱신하는 핸들이다(두 번 걷어도 한 번만 걷힌다).
+     *
+     * **걷는 것은 `finally` 에 둔다.** 빠뜨리면 그 즉시 화면이 갇히고, 정상 경로에서는 아무
+     * 표시가 없다.
      *
-     * ⚠️ 메시지만 바꾸려면 `update()` 를 쓴다. `show()` 를 다시 부르면 하나 더 쌓여
-     * `hide()` 한 번으로는 닫히지 않는다.
+     * ```ts
+     * const done = loading.show({ message: '1/2 ...' });
+     * try {
+     *   done.update({ message: '2/2 ...' });   // 이 호출의 메시지만 바뀐다
+     *   await api.submit(payload);
+     * } finally {
+     *   done();                                // 이 호출만 걷는다
+     * }
+     * ```
+     *
+     * ⚠️ **메시지를 바꾸려고 `show()` 를 다시 부르지 않는다.** 하나 더 쌓여 한 번 걷는 것으로는
+     * 닫히지 않는다. 핸들의 `update()` 를 쓴다. (참조 카운트 이전에는 `show()` 를 다시 부르는
+     * 것이 갱신이었다 — Quasar 도 같은 그룹에 다시 show 하면 갱신이다. 그 시절 관행대로 쓰인
+     * 코드는 지금 오버레이를 하나 남긴다.)
      */
     show(options?: {
         message?: string;
-    }): () => void;
-    /** 표시 중인 메시지 갱신 — 쌓인 수는 그대로다 */
-    update(options: {
-        message?: string;
-    }): void;
-    /** 가장 나중의 show 하나를 걷는다. 남은 것이 없을 때만 오버레이가 닫힌다 */
-    hide(): void;
+    }): SLoadingHandle;
     /**
-     * 쌓인 것을 모두 걷고 즉시 닫는다. 화면 전환·에러 복구처럼 진행 중이던 작업의 짝을 더는
-     * 맞출 수 없을 때만 쓴다 — 평소에는 `hide()` 나 `show()` 가 준 함수로 하나씩 걷는다.
+     * 쌓인 것을 모두 걷고 즉시 닫는다. **원본(Quasar)의 인자 없는 `hide()` 가 이것이다.**
+     * 화면 전환·에러 복구처럼 진행 중이던 작업의 짝을 더는 맞출 수 없을 때만 쓴다 — 평소에는
+     * `show()` 가 준 핸들로 걷는다.
+     * 이걸로 걷힌 항목의 주인이 뒤늦게 자기 핸들을 불러도 아무 일도 일어나지 않는다.
      */
     hideAll(): void;
 };