sellmate-design-system-react 9.0.0-beta.0 → 9.0.0-beta.3

package/AGENTS.md

@@ -32,7 +32,7 @@
 | **표·목록** | `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
 | **레이아웃** | `SLayout` `SGnb` `SPage`(제목 영역은 `header` prop) `SSectionHeaderCard` `SCard` `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
 | **내비게이션** | `STabs` `SPagination` `SStepper` |
-| **표시·상태** | `STag` `SBadge` `SIcon` `SCallout` `SGuide` |
+| **표시·상태** | `STag` `SBadge` `SIcon` `SImage` `SCallout` `SGuide` |
 | **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
 | **오버레이** | `STooltip` `SPopover` `SPopup` `SDrawer` `SPortal` |
 | **모달** | `SModal.confirm()` `SModal.create()` + `SActionModal` `SConfirmModal` `SModalOutlet`(앱 루트 1회) |
@@ -138,7 +138,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | --- | --- | --- |
 | **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `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` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SLinearProgress` `SCircleProgress` |
+| **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SDropdownButton` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SImage` `SLinearProgress` `SCircleProgress` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
 | **레이어** | 문서 흐름 **밖**에 떠서 그려진다. 어느 층에서 띄우든 레이아웃에 영향이 없다 | `SModal` `SActionModal` `SConfirmModal` `SPopup` `SDrawer` `SPopover` `STooltip` `SPortal` `SToast` `SLoadingModal` `SLoadingContainer` `SGuide` |
 
@@ -442,6 +442,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 상태·분류를 라벨로 찍는다 | `STag` | §3-1 |
 | 색 점만으로 상태를 찍는다 | `SBadge` | §3-1 |
 | 아이콘을 넣는다 | `SIcon` | |
+| 사진·썸네일을 보여준다 (로딩·실패 상태 포함) | `SImage` | §3-7-12 |
 | 문장 안에서 다른 화면으로 보낸다 | `STextLink` | §3-5-6 |
 
 #### C. 동작을 실행시킨다
@@ -1085,6 +1086,23 @@ const columns: STableColumn[] = [
 - 검색 실행 시점이 다르다 — `SKeyValueTable` 필터는 앱이 검색 버튼을 직접 놓지만, `SChipFilter` 는 편집 팝오버가 닫히거나 "검색" 을 누를 때 `onSearch` 가 값 맵과 함께 호출된다. 값이 바뀌지 않았으면 호출되지 않는다.
 - 함께 걸어야 하는 조건(예: 기간 중 하나는 필수)이 있으면 `fields` 를 그룹으로 넘긴다. 규칙을 못 채운 동안 경고 툴팁이 떠 있고 `onSearch` 가 막힌다.
 
+#### 3-7-12. 이미지 — SImage
+
+사진·썸네일은 `<img>` 를 직접 쓰지 않고 `SImage` 를 쓴다. **로딩·실패 상태를 컴포넌트가 이미 처리하기 때문이다.**
+
+- **로딩 스피너와 실패 표시를 앱이 만들지 않는다.** `src` 가 없거나 로드에 실패하면 빈 이미지 아이콘이, 로딩 중에는 스피너가 자동으로 놓인다. 크기는 상자 높이에 비례하므로 썸네일이든 큰 미리보기든 따로 맞출 것이 없다.
+- **크기는 `ratio` 와 너비로 준다.** `ratio` 기본값이 `1`(정사각형)이라 너비만 주면 정사각형이 된다. `className`/`style` 로 높이를 직접 주면 그쪽이 이기고 `ratio` 는 무시된다.
+- 상자를 채우는 방식은 `fit`(기본 `cover`), 붙는 위치는 `position` 이다. 안쪽 `<img>` 에 네이티브 속성이 필요하면 `imgProps` 로 넘긴다 — 목록에서 고스트 드래그를 막는 `imgProps={{ draggable: false }}` 가 대표적이다.
+- 썸네일이 많은 목록에서는 `loadingShowDelay` 를 준다. 캐시된 이미지가 즉시 로드될 때 스피너가 한 프레임 번쩍이는 것을 막는다.
+
+```tsx
+✅ <SImage src={item.thumbnailUrl} alt={item.name} style={{ width: 64 }} />   {/* 정사각 썸네일 */}
+✅ <SImage src={banner} ratio={16 / 9} className="w-full" />                  {/* 가로형 배너 */}
+
+❌ <img src={item.thumbnailUrl} />                                            {/* 로딩·실패 상태가 없다 */}
+❌ {loading ? <SCircleProgress indeterminate /> : <SImage src={url} />}        {/* SImage 가 이미 한다 */}
+```
+
 ---
 
 ## 4. 페이지 레시피 — 표준 골격

package/dist/components/SCircleProgress/README.md

@@ -11,6 +11,7 @@
 | `value?` | `number` | `0` | 진행률 (0–100) |
 | `type?` | `SCircleProgressType` | `'primary'` | 색상 테마 |
 | `indeterminate?` | `boolean` | `false` | 불확정(스피너) 모드 — value 무시 |
+| `size?` | `number \| string` | `DEFAULT_SIZE` | 링의 지름. 숫자는 px 로 해석한다. 부모 크기에 비례시키려면 컨테이너 쿼리 단위(`'45cqh'`)를 쓴다 — 퍼센트는 부모가 inline-flex 라 기준 폭이 정해지지 않아 해석되지 않는다. |
 | `label?` | `string` | — | 하단 레이블 |
 | `innerValue?` | `boolean` | `false` | true면 퍼센트를 원 아래가 아닌 원 가운데에 표시 |
 | `className?` | `string` | — |  |
@@ -20,6 +21,7 @@
 
 ### Used by
 
+ - [SImage](../SImage)
  - [SLoadingContainer](../SLoadingContainer)
  - [SLoadingModal](../SLoadingModal)
  - [STable](../STable)
@@ -28,6 +30,7 @@
 
 ```mermaid
 graph TD;
+  SImage --> SCircleProgress
   SLoadingContainer --> SCircleProgress
   SLoadingModal --> SCircleProgress
   STable --> SCircleProgress

package/dist/components/SCircleProgress/SCircleProgress.d.ts

@@ -1,5 +1,5 @@
 import { type CSSProperties } from 'react';
-export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete';
+export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete' | 'neutral';
 export interface SCircleProgressProps {
     /** 진행률 (0–100) */
     value?: number;
@@ -7,6 +7,12 @@ export interface SCircleProgressProps {
     type?: SCircleProgressType;
     /** 불확정(스피너) 모드 — value 무시 */
     indeterminate?: boolean;
+    /**
+     * 링의 지름. 숫자는 px 로 해석한다.
+     * 부모 크기에 비례시키려면 컨테이너 쿼리 단위(`'45cqh'`)를 쓴다 — 퍼센트는 부모가
+     * inline-flex 라 기준 폭이 정해지지 않아 해석되지 않는다.
+     */
+    size?: number | string;
     /** 하단 레이블 */
     label?: string;
     /** true면 퍼센트를 원 아래가 아닌 원 가운데에 표시 */

package/dist/components/SDatePicker/README.md

@@ -8,9 +8,10 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value?` | `string \| null` | — | 선택 날짜 (YYYY-MM-DD) |
+| `value?` | `string \| null` | — | 선택 값 (date: YYYY-MM-DD, month: YYYY-MM, year: YYYY) |
+| `mode?` | `SDatePickerMode` | `'date'` | 선택 모드 |
 | `size?` | `SDatePickerSize` | `'sm'` |  |
-| `placeholder?` | `string` | `'YYYY-MM-DD'` |  |
+| `placeholder?` | `string` | — |  |
 | `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] |
 | `disabled?` | `boolean` | `false` |  |
 | `width?` | `number \| string` | — |  |
@@ -35,7 +36,7 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
+| `onValueChange` | `(value: string) => void` | 선택 변경 (sdUpdate) |
 | `onViewChange` | `(view: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
 
 ## Dependencies

package/dist/components/SDatePicker/SDatePicker.d.ts

@@ -5,16 +5,19 @@ import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
 export type SDatePickerSize = SFieldSize;
+export type SDatePickerMode = 'date' | 'month' | 'year';
 export interface SDatePickerProps {
-    /** 선택 날짜 (YYYY-MM-DD) */
+    /** 선택 값 (date: YYYY-MM-DD, month: YYYY-MM, year: YYYY) */
     value?: string | null;
     /** 선택 변경 (sdUpdate) */
-    onValueChange?: (date: string) => void;
+    onValueChange?: (value: string) => void;
     /** 보이는 연·월 변경 (sdViewChange) */
     onViewChange?: (view: {
         year: number;
         month: number;
     }) => void;
+    /** 선택 모드 */
+    mode?: SDatePickerMode;
     size?: SDatePickerSize;
     placeholder?: string;
     /** 선택 가능 범위 [시작, 종료] */
@@ -39,4 +42,4 @@ export interface SDatePickerProps {
     style?: CSSProperties;
 }
 /** SDatePicker — sd-date-picker 포팅. SField + SPopover(SCalendar). */
-export declare function SDatePicker({ value, onValueChange, onViewChange, size, placeholder, selectable, disabled, width, name, rules, status, label, labelWidth, icon, iconColor, labelTooltip, labelTooltipProps, addonLabel, addonAlign, hint, error, errorMessage, className, style, }: SDatePickerProps): import("react").JSX.Element;
+export declare function SDatePicker({ value, onValueChange, onViewChange, mode, size, placeholder, selectable, disabled, width, name, rules, status, label, labelWidth, icon, iconColor, labelTooltip, labelTooltipProps, addonLabel, addonAlign, hint, error, errorMessage, className, style, }: SDatePickerProps): import("react").JSX.Element;

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

@@ -1 +1 @@
-export { SDatePicker, type SDatePickerProps, type SDatePickerSize } from './SDatePicker';
+export { SDatePicker, type SDatePickerMode, type SDatePickerProps, type SDatePickerSize, } from './SDatePicker';

package/dist/components/SIcon/README.md

@@ -36,6 +36,7 @@
  - [SGhostButton](../SGhostButton)
  - [SGnb](../SGnb)
  - [SGuide](../SGuide)
+ - [SImage](../SImage)
  - [SKeyValueTable](../SKeyValueTable)
  - [SListItem](../SListItem)
  - [SLoadingModal](../SLoadingModal)
@@ -73,6 +74,7 @@ graph TD;
   SGhostButton --> SIcon
   SGnb --> SIcon
   SGuide --> SIcon
+  SImage --> SIcon
   SKeyValueTable --> SIcon
   SListItem --> SIcon
   SLoadingModal --> SIcon

package/dist/components/SImage/README.md

@@ -0,0 +1,44 @@
+# SImage
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SImage
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src?` | `string` | — | 이미지 경로. 없으면 빈 이미지 아이콘이 나온다 |
+| `alt?` | `string` | `''` | 대체 텍스트 |
+| `ratio?` | `number` | `1` | 가로세로 비율. 소비자가 높이를 직접 주면 그쪽이 이긴다 |
+| `fit?` | `SImageFit` | `'cover'` | 이미지가 상자를 채우는 방식 (object-fit) |
+| `position?` | `string` | `'50% 50%'` | 이미지 정렬 위치 (object-position) |
+| `loading?` | `'lazy' \| 'eager'` | `'lazy'` | 브라우저 로딩 방식 |
+| `loadingShowDelay?` | `number` | `0` | 스피너를 띄우기까지 기다리는 시간(ms). 이 시간 안에 로드되면 스피너를 아예 그리지 않는다 — 캐시된 이미지에서 스피너가 한 프레임 번쩍이는 것을 막는다. |
+| `noSpinner?` | `boolean` | `false` | 로딩 중에도 스피너를 그리지 않는다 |
+| `loadingSlot?` | `ReactNode` | — | 로딩 중 표시를 직접 지정한다 (기본: 스피너) |
+| `errorSlot?` | `ReactNode` | — | 실패·빈 상태 표시를 직접 지정한다 (기본: 빈 이미지 아이콘) |
+| `imgProps?` | `ImgHTMLAttributes<HTMLImageElement>` | — | 안쪽 `<img>` 로 넘길 네이티브 속성 (srcSet · sizes · crossOrigin · draggable 등) |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onLoad` | `(src: string) => void` | 로드 완료. 로드된 src 를 넘긴다 |
+| `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | 로드 실패 |
+
+## Dependencies
+
+### Depends on
+
+- [SCircleProgress](../SCircleProgress)
+- [SIcon](../SIcon)
+
+### Graph
+
+```mermaid
+graph TD;
+  SImage --> SCircleProgress
+  SImage --> SIcon
+  style SImage fill:#f9f,stroke:#333,stroke-width:4px
+```

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

@@ -0,0 +1,41 @@
+import { type HTMLAttributes, type ImgHTMLAttributes, type ReactNode, type SyntheticEvent } from 'react';
+export declare const IMAGE_FITS: readonly ["cover", "contain", "fill", "none", "scale-down"];
+export type SImageFit = (typeof IMAGE_FITS)[number];
+export interface SImageProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onLoad' | 'onError'> {
+    /** 이미지 경로. 없으면 빈 이미지 아이콘이 나온다 */
+    src?: string;
+    /** 대체 텍스트 */
+    alt?: string;
+    /** 가로세로 비율. 소비자가 높이를 직접 주면 그쪽이 이긴다 */
+    ratio?: number;
+    /** 이미지가 상자를 채우는 방식 (object-fit) */
+    fit?: SImageFit;
+    /** 이미지 정렬 위치 (object-position) */
+    position?: string;
+    /** 브라우저 로딩 방식 */
+    loading?: 'lazy' | 'eager';
+    /**
+     * 스피너를 띄우기까지 기다리는 시간(ms). 이 시간 안에 로드되면 스피너를 아예 그리지 않는다 —
+     * 캐시된 이미지에서 스피너가 한 프레임 번쩍이는 것을 막는다.
+     */
+    loadingShowDelay?: number;
+    /** 로딩 중에도 스피너를 그리지 않는다 */
+    noSpinner?: boolean;
+    /** 로딩 중 표시를 직접 지정한다 (기본: 스피너) */
+    loadingSlot?: ReactNode;
+    /** 실패·빈 상태 표시를 직접 지정한다 (기본: 빈 이미지 아이콘) */
+    errorSlot?: ReactNode;
+    /** 안쪽 `<img>` 로 넘길 네이티브 속성 (srcSet · sizes · crossOrigin · draggable 등) */
+    imgProps?: ImgHTMLAttributes<HTMLImageElement>;
+    /** 로드 완료. 로드된 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/SImage/index.d.ts

@@ -0,0 +1 @@
+export { SImage, IMAGE_FITS, type SImageProps, type SImageFit } from './SImage';

package/dist/components/SToggle/README.md

@@ -11,6 +11,7 @@
 | `value?` | `boolean` | `false` | 선택(on/off) 상태 |
 | `label?` | `string` | `''` | 라벨 |
 | `disabled?` | `boolean` | `false` | 비활성 |
+| `size?` | `SToggleSize` | `'sm'` | 크기 |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 

package/dist/components/SToggle/SToggle.d.ts

@@ -1,4 +1,5 @@
 import { type CSSProperties } from 'react';
+export type SToggleSize = 'xs' | 'sm';
 export interface SToggleProps {
     /** 선택(on/off) 상태 */
     value?: boolean;
@@ -6,6 +7,8 @@ export interface SToggleProps {
     label?: string;
     /** 비활성 */
     disabled?: boolean;
+    /** 크기 */
+    size?: SToggleSize;
     /** 변경 (sdUpdate) */
     onValueChange?: (value: boolean) => void;
     className?: string;
@@ -15,4 +18,4 @@ export interface SToggleProps {
  * SToggle — sd-toggle 포팅. 알약형 토글 버튼.
  * default(흰 배경/회색), hover(파란 채움), select(흰 배경/파란 테두리·글자), disabled.
  */
-export declare function SToggle({ value, label, disabled, onValueChange, className, style, }: SToggleProps): import("react").JSX.Element;
+export declare function SToggle({ value, label, disabled, size, onValueChange, className, style, }: SToggleProps): import("react").JSX.Element;