sellmate-design-system-react 8.1.0 → 9.0.0-beta.2

package/dist/components/SChipFilter/SChipFilter.d.ts

@@ -0,0 +1,160 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type SDateRangeValue } from '../SDateRangePicker';
+export type SChipFilterType = 'single' | 'multi' | 'keyword' | 'date' | 'custom';
+export type SChipFilterOptionValue = string | number;
+export type SChipFilterMatchMode = 'contains' | 'exact' | 'excludes';
+export interface SChipFilterOption {
+    value: SChipFilterOptionValue;
+    label: string;
+    disabled?: boolean;
+}
+/** date 필드의 프리셋 라디오 항목 (오늘/지난 7일/사용자 지정 등) */
+export interface SChipFilterDatePreset {
+    /** 프리셋 식별자 */
+    value: string;
+    /** 라벨 */
+    label: string;
+    /** true면 "사용자 지정" — 선택 시 날짜/기간 피커가 추가로 노출된다. resolve는 무시된다. */
+    custom?: boolean;
+    /** custom이 아닐 때 실제 값을 계산한다. 단일 날짜(string) 또는 기간([start,end]) 모두 가능 */
+    resolve?: () => string | SDateRangeValue;
+}
+/** keyword 필드에서 matchModes 활성 시 사용하는 값 형태 — 입력해 추가한 키워드 목록 */
+export interface SChipFilterKeywordValue {
+    keywords: string[];
+    mode: SChipFilterMatchMode;
+}
+/** custom 필드가 자유롭게 담는 값. 형태를 강제하지 않는다 — render에서 직접 정의한 그대로 읽고 쓴다 */
+export type SChipFilterCustomValue = Record<string, unknown>;
+export type SChipFilterValue = SChipFilterOptionValue | SChipFilterOptionValue[] | SDateRangeValue | SChipFilterKeywordValue | SChipFilterCustomValue | null | undefined;
+export type SChipFilterValueMap = Record<string, SChipFilterValue>;
+export interface SChipFilterField {
+    /** 필터 식별자 */
+    key: string;
+    /** 칩에 표시할 레이블 */
+    label: string;
+    /** 필터 타입 */
+    type: SChipFilterType;
+    /** single/multi/keyword 후보 목록 */
+    options?: SChipFilterOption[];
+    /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
+     *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
+    required?: boolean;
+    /** 초기값 및 clearable 클릭 시 되돌아갈 값. required 여부와 무관하게 적용된다 — 값이 비어 있으면
+     *  마운트(또는 "필터 추가"로 활성화) 시 이 값이 자동으로 채워진다. required인데 지정하지 않으면
+     *  타입별 내장 기본값(single: 첫 번째 옵션, date: 오늘 날짜)을 대신 쓴다 */
+    defaultValue?: SChipFilterValue;
+    /** 경고 테두리 표시 */
+    warning?: boolean;
+    /** 비활성 상태 */
+    disabled?: boolean;
+    /** 처음부터 칩으로 노출할지 여부. false면 "필터 추가" 목록에만 나타나고, 거기서 고르기 전까지는
+     *  필터 바에 보이지 않는다. activeKeys를 직접 제어하는 경우엔 초기 activeKeys 구성에만 참고되고
+     *  이후엔 activeKeys가 우선한다 */
+    defaultActive?: boolean;
+    /** keyword 입력 placeholder */
+    placeholder?: string;
+    /** keyword 필드에 검색조건(포함/일치) 토글 표시 여부 */
+    matchModes?: boolean;
+    /** matchModes 활성 시 "미포함"까지 포함해 3개(포함/일치/미포함)로 노출할지. 기본 false — 기존처럼 2개(포함/일치)만 */
+    excludeMode?: boolean;
+    /** date 선택 가능 범위 */
+    selectable?: [string, string];
+    /** date 프리셋의 "사용자 지정" 기간 선택 시 최대 선택 일수 */
+    maxRange?: number;
+    /** date 필드의 프리셋 라디오 목록. 지정하지 않으면 기존처럼 단일 캘린더 트리거로 동작한다 */
+    presets?: SChipFilterDatePreset[];
+    /** presets 사용 시 UI 형태 — true: 필터 바에 세그먼트 라디오로 인라인 노출(팝오버 없음),
+     *  false(기본): 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
+    radioButton?: boolean;
+    /** type이 'custom'일 때 필터 바에 이 필드 자리에 놓일 노드를 직접 그린다. 칩+팝오버를 거치지 않고
+     *  반환한 노드가 그대로 바에 노출된다 — SSelect를 그대로 놓거나 SInput을 바로 노출하는 식으로
+     *  렌더 방식 자체를 완전히 자유롭게 구성한다. */
+    render?: (ctx: {
+        value: SChipFilterValue;
+        disabled?: boolean;
+        warning?: boolean;
+        onValueChange: (value: SChipFilterValue) => void;
+    }) => ReactNode;
+}
+export interface SChipFilterChangeDetail {
+    key: string;
+    value: SChipFilterValue;
+    values: SChipFilterValueMap;
+}
+/** 필터 그룹 검증 규칙 */
+export type SChipFilterGroupRule = {
+    type: 'requireKey';
+    key: string;
+} | {
+    type: 'requireAll';
+} | {
+    type: 'requireAny';
+    dataGroupName?: string;
+};
+/** 필터를 그룹으로 묶어서 넘길 때의 단위. 그룹이 시작될 때마다 앞에 구분선이 붙는다. */
+export interface SChipFilterGroup {
+    fields: SChipFilterField[];
+    /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
+     *  그룹이 rule을 만족하지 못하면 검색 시도 여부와 무관하게 그 즉시 그룹 중앙에 경고 툴팁이 뜬다.
+     *  지정 안 하면 검증하지 않는다. */
+    rule?: SChipFilterGroupRule;
+    /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
+    tooltipMessage?: string;
+}
+export interface SChipFilterHandle {
+    /** 특정 필터 편집 팝오버를 엽니다. */
+    open: (key: string) => void;
+    /** 모든 필터 값을 초기화합니다. */
+    reset: () => void;
+    /** fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지
+     *  반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
+     *  이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) */
+    validate: () => boolean;
+}
+export interface SChipFilterProps {
+    /** 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에
+     *  구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). */
+    fields?: SChipFilterField[] | SChipFilterGroup[];
+    /** 필터 값 맵 */
+    value?: SChipFilterValueMap;
+    /** 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 */
+    onValueChange?: (value: SChipFilterValueMap) => void;
+    /** 개별 필터 값 변경 */
+    onFilterChange?: (detail: SChipFilterChangeDetail) => void;
+    /** 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른
+     *  칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom,
+     *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
+     *  실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고
+     *  닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
+     *  onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상
+     *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) */
+    onSearch?: (value: SChipFilterValueMap) => void;
+    /** 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접
+     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별
+     *  defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 */
+    activeKeys?: string[];
+    /** 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다.
+     *  activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 */
+    onActiveKeysChange?: (keys: string[]) => void;
+    /** "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋된 뒤 호출된다 */
+    onReset?: () => void;
+    /** "필터 추가" 목록에서 항목을 골랐을 때 — activeKeys를 직접 제어 중이면 이 콜백에서
+     *  (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다.
+     *  activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 */
+    onAddFilter?: (key: string) => void;
+    /** 좌측 태그 텍스트 */
+    label?: string;
+    /** 좌측 태그(label)·구분선 표시 여부 */
+    showLabel?: boolean;
+    /** 필터 추가 버튼 표시 여부 */
+    showAddButton?: boolean;
+    /** 검색 초기화 링크 표시 여부 */
+    showReset?: boolean;
+    /** 바 비활성 상태 */
+    disabled?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** SChipFilter — 검색 필터를 칩 바 형태로 구성하는 컴포넌트. */
+export declare const SChipFilter: import("react").ForwardRefExoticComponent<SChipFilterProps & import("react").RefAttributes<SChipFilterHandle>>;

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

@@ -0,0 +1 @@
+export { SChipFilter, type SChipFilterChangeDetail, type SChipFilterDatePreset, type SChipFilterField, type SChipFilterGroup, type SChipFilterGroupRule, type SChipFilterHandle, type SChipFilterKeywordValue, type SChipFilterMatchMode, type SChipFilterOption, type SChipFilterOptionValue, type SChipFilterProps, type SChipFilterType, type SChipFilterValue, type SChipFilterValueMap, } from './SChipFilter';

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

@@ -42,6 +42,7 @@
 
 ### Used by
 
+ - [SChipFilter](../SChipFilter)
  - [SKeyValueTable](../SKeyValueTable)
 
 ### Depends on
@@ -57,6 +58,7 @@ graph TD;
   SDatePicker --> SCalendar
   SDatePicker --> SField
   SDatePicker --> SIcon
+  SChipFilter --> SDatePicker
   SKeyValueTable --> SDatePicker
   style SDatePicker fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SDateRangePicker/README.md

@@ -40,10 +40,30 @@
 | `onValueChange` | `(range: SDateRangeValue) => void` | 선택 변경 (sdUpdate) — [start, end] |
 | `onViewChange` | `(view: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
 
+### SRangeCalendar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `SDateRangeValue` | — |  |
+| `selectable?` | `[string, string]` | — |  |
+| `maxRange?` | `number` | — |  |
+| `useTimePicker?` | `boolean` | `false` |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onSelect` | `(r: [string, string]) => void` |  |
+| `onPendingStartChange` | `(start: string \| null) => void` | 시작일만 선택된(종료일 대기) 상태를 상위로 전달 — 트리거에 `start ~` 프리뷰 표시용 |
+| `onViewChange` | `(view: { year: number; month: number }) => void` |  |
+
 ## Dependencies
 
 ### Used by
 
+ - [SChipFilter](../SChipFilter)
  - [SKeyValueTable](../SKeyValueTable)
 
 ### Depends on
@@ -61,6 +81,7 @@ graph TD;
   SDateRangePicker --> SField
   SDateRangePicker --> SGhostButton
   SDateRangePicker --> SIcon
+  SChipFilter --> SDateRangePicker
   SKeyValueTable --> SDateRangePicker
   style SDateRangePicker fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SDateRangePicker/SDateRangePicker.d.ts

@@ -44,5 +44,21 @@ export interface SDateRangePickerProps {
     className?: string;
     style?: CSSProperties;
 }
+export interface SRangeCalendarProps {
+    value: SDateRangeValue;
+    selectable?: [string, string];
+    maxRange?: number;
+    useTimePicker?: boolean;
+    onSelect: (r: [string, string]) => void;
+    /** 시작일만 선택된(종료일 대기) 상태를 상위로 전달 — 트리거에 `start ~` 프리뷰 표시용 */
+    onPendingStartChange?: (start: string | null) => void;
+    onViewChange?: (view: {
+        year: number;
+        month: number;
+    }) => void;
+}
+/** RangeCalendar — SDateRangePicker의 캘린더 부분만 떼어낸 조각. 자체 트리거/팝오버 없이
+ *  캘린더 그리드만 필요한 커스텀 조합(예: 다른 트리거에 팝오버로 얹는 경우)에 재사용한다. */
+export declare function RangeCalendar({ value, selectable, maxRange, useTimePicker, onSelect, onPendingStartChange, onViewChange, }: SRangeCalendarProps): import("react").JSX.Element;
 /** SDateRangePicker — sd-date-range-picker 포팅. SField + SPopover(범위 캘린더). */
 export declare function SDateRangePicker({ value, onValueChange, onViewChange, size, placeholder, selectable, maxRange, useTimePicker, disabled, width, name, rules, status, label, labelWidth, icon, iconColor, labelTooltip, labelTooltipProps, addonLabel, addonAlign, hint, error, errorMessage, className, style, }: SDateRangePickerProps): import("react").JSX.Element;

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

@@ -1 +1 @@
-export { SDateRangePicker, type SDateRangePickerProps, type SDateRangePickerSize, type SDateRangeValue, } from './SDateRangePicker';
+export { RangeCalendar, SDateRangePicker, type SDateRangePickerProps, type SDateRangePickerSize, type SDateRangeValue, type SRangeCalendarProps, } from './SDateRangePicker';

package/dist/components/SGhostButton/README.md

@@ -34,6 +34,7 @@
  - [SBarcodeInput](../SBarcodeInput)
  - [SCalendar](../SCalendar)
  - [SChip](../SChip)
+ - [SChipFilter](../SChipFilter)
  - [SDateRangePicker](../SDateRangePicker)
  - [SFilePicker](../SFilePicker)
  - [SGnb](../SGnb)
@@ -41,6 +42,7 @@
  - [SInput](../SInput)
  - [SModalContainer](../SModalContainer)
  - [SOverlayHeader](../SOverlayHeader)
+ - [SPage](../SPage)
  - [SPopover](../SPopover)
  - [SSelect](../SSelect)
  - [STimePicker](../STimePicker)
@@ -63,6 +65,7 @@ graph TD;
   SBarcodeInput --> SGhostButton
   SCalendar --> SGhostButton
   SChip --> SGhostButton
+  SChipFilter --> SGhostButton
   SDateRangePicker --> SGhostButton
   SFilePicker --> SGhostButton
   SGnb --> SGhostButton
@@ -70,6 +73,7 @@ graph TD;
   SInput --> SGhostButton
   SModalContainer --> SGhostButton
   SOverlayHeader --> SGhostButton
+  SPage --> SGhostButton
   SPopover --> SGhostButton
   SSelect --> SGhostButton
   STimePicker --> SGhostButton

package/dist/components/SGuide/README.md

@@ -13,7 +13,7 @@
 | `message?` | `SGuideMessage` | `''` | 팝업 메시지 (배열이면 리스트, 중첩 배열이면 depth 표현) |
 | `url?` | `string` | `''` | notion 타입 클릭 시 이동 URL |
 | `popupTitle?` | `string` | `''` | 팝업 제목 (없으면 type 기본값) |
-| `popupWidth?` | `number` | — | 팝업 너비 (px, 기본 426) |
+| `popupWidth?` | `number` | — | 팝업 너비 (px, 기본 426). 창보다 넓게 줘도 창 폭까지만 벌어진다. |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 

package/dist/components/SGuide/SGuide.d.ts

@@ -13,7 +13,7 @@ export interface SGuideProps {
     url?: string;
     /** 팝업 제목 (없으면 type 기본값) */
     popupTitle?: string;
-    /** 팝업 너비 (px, 기본 426) */
+    /** 팝업 너비 (px, 기본 426). 창보다 넓게 줘도 창 폭까지만 벌어진다. */
     popupWidth?: number;
     className?: string;
     style?: CSSProperties;

package/dist/components/SIcon/README.md

@@ -23,6 +23,7 @@
  - [SButton](../SButton)
  - [SCallout](../SCallout)
  - [SCheckbox](../SCheckbox)
+ - [SChipFilter](../SChipFilter)
  - [SChipInput](../SChipInput)
  - [SConfirmModal](../SConfirmModal)
  - [SDatePicker](../SDatePicker)
@@ -35,6 +36,7 @@
  - [SGhostButton](../SGhostButton)
  - [SGnb](../SGnb)
  - [SGuide](../SGuide)
+ - [SImage](../SImage)
  - [SKeyValueTable](../SKeyValueTable)
  - [SListItem](../SListItem)
  - [SLoadingModal](../SLoadingModal)
@@ -59,6 +61,7 @@ graph TD;
   SButton --> SIcon
   SCallout --> SIcon
   SCheckbox --> SIcon
+  SChipFilter --> SIcon
   SChipInput --> SIcon
   SConfirmModal --> SIcon
   SDatePicker --> SIcon
@@ -71,6 +74,7 @@ graph TD;
   SGhostButton --> SIcon
   SGnb --> SIcon
   SGuide --> SIcon
+  SImage --> SIcon
   SKeyValueTable --> SIcon
   SListItem --> SIcon
   SLoadingModal --> SIcon

package/dist/components/SIcon/icons.gen.d.ts

@@ -83,6 +83,7 @@ export declare const ICONS: {
     readonly settingOutline: (p: IconRenderProps) => import("react").JSX.Element;
     readonly shield: (p: IconRenderProps) => import("react").JSX.Element;
     readonly sidebar: (p: IconRenderProps) => import("react").JSX.Element;
+    readonly star: (p: IconRenderProps) => import("react").JSX.Element;
     readonly store: (p: IconRenderProps) => import("react").JSX.Element;
     readonly synchronize: (p: IconRenderProps) => import("react").JSX.Element;
     readonly thumbsDown: (p: IconRenderProps) => import("react").JSX.Element;

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/SList/README.md

@@ -11,6 +11,7 @@
 | `children?` | `ReactNode` | — | 리스트 컨테이너 내부에 렌더링할 내용 |
 | `useGap?` | `boolean` | `false` | 리스트 아이템 사이 gap 토큰 적용 여부 |
 | `usePadding?` | `boolean` | `false` | 리스트 컨테이너 padding 토큰 적용 여부 |
+| `separator?` | `boolean` | `false` | 아이템 하단 구분선 표시 여부. 테두리를 가진 아이템(`bordered`)에는 쓰지 않는다 |
 
 ## Dependencies
 

package/dist/components/SList/SList.d.ts

@@ -6,5 +6,7 @@ export interface SListProps extends HTMLAttributes<HTMLDivElement> {
     useGap?: boolean;
     /** 리스트 컨테이너 padding 토큰 적용 여부 */
     usePadding?: boolean;
+    /** 아이템 하단 구분선 표시 여부. 테두리를 가진 아이템(`bordered`)에는 쓰지 않는다 */
+    separator?: boolean;
 }
 export declare const SList: import("react").ForwardRefExoticComponent<SListProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SListItem/README.md

@@ -15,8 +15,8 @@
 | `leading?` | `SListItemSlot` | — | 타이틀 앞에 표시할 아이콘/콘텐츠 |
 | `trailing?` | `SListItemSlot` | — | 타이틀 뒤에 표시할 태그/콘텐츠 |
 | `bordered?` | `boolean` | `false` | 외곽 테두리 사용 여부 |
-| `selected?` | `boolean` | `false` | 선택 상태 여부 |
-| `clickable?` | `boolean` | `true` | 클릭 가능 상태 여부 |
+| `selected?` | `boolean` | `false` | 선택 상태 여부. `clickable` 이 false 면 무시된다 |
+| `clickable?` | `boolean` | `false` | 클릭 가능 상태 여부. hover·selected·chevron 등 인터랙션 표현이 여기에 딸린다 |
 | `interaction?` | `SListItemInteraction` | — | hover/selected 상태에서 적용할 인터랙션 preset |
 | `accentStripe?` | `boolean` | `false` | 아이템 왼쪽 accent stripe 표시 여부 |
 | `dense?` | `boolean` | `false` | 조밀한 높이 사용 여부 |

package/dist/components/SListItem/SListItem.d.ts

@@ -23,9 +23,9 @@ export interface SListItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'ch
     trailing?: SListItemSlot;
     /** 외곽 테두리 사용 여부 */
     bordered?: boolean;
-    /** 선택 상태 여부 */
+    /** 선택 상태 여부. `clickable` 이 false 면 무시된다 */
     selected?: boolean;
-    /** 클릭 가능 상태 여부 */
+    /** 클릭 가능 상태 여부. hover·selected·chevron 등 인터랙션 표현이 여기에 딸린다 */
     clickable?: boolean;
     /** hover/selected 상태에서 적용할 인터랙션 preset */
     interaction?: SListItemInteraction;

package/dist/components/SPage/README.md

@@ -2,6 +2,24 @@
 
 > 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
 
+### SPageHeader
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | 타이틀 (필수) |
+| `subText?` | `string` | — | 서브 텍스트. fix=true 면 타이틀 오른쪽에, fix=false(기본) 면 타이틀 아래에 놓인다. |
+| `fix?` | `boolean` | `false` | true: 높이 56 고정 + 흰 배경 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄. false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 투명 배경, 서브 텍스트가 타이틀 아래로 내려간다. |
+| `slot?` | `ReactNode` | — | 오른쪽 끝 커스텀 슬롯. 가이드 링크·액션 버튼 등 페이지마다 다른 것이 온다. |
+| `scrolled?` | `boolean` | `false` | `<SPage>` 가 스크롤 여부를 보고 자동으로 넣어준다 — 직접 주지 않는다. fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 그대로 페이지 배경을 따라간다 — 배경을 바꾸는 건 scrolled 가 아니라 fix 다. |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onBack` | `() => void` | 뒤로가기 클릭 핸들러. 지정하면 왼쪽에 뒤로가기 버튼이 나타난다. |
+
 ### SPage
 
 #### Props
@@ -10,17 +28,20 @@
 |------|------|---------|-------------|
 | `background?` | `SPageBackground` | `'frame'` | 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕. 스크롤바 처리도 여기 묶여 있다 — 셋 다 구분선+트랙 배경이고, 트랙 색만 neutral 에서 흰색이 된다. |
 | `scrollEndSpacing?` | `boolean` | `true` | 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다. 기본으로 켜져 있고, 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 끈다(목록 페이지). |
+| `header?` | `SPageHeaderProps` | — | 페이지 타이틀 영역(pageHeader 포팅). 주면 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다. `children` 은 항상 본문이다 — header 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다. |
 
 ## Dependencies
 
 ### Depends on
 
+- [SGhostButton](../SGhostButton)
 - [SLayout](../SLayout)
 
 ### Graph
 
 ```mermaid
 graph TD;
+  SPage --> SGhostButton
   SPage --> SLayout
   style SPage fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SPage/SPage.d.ts

@@ -1,5 +1,6 @@
 import { type HTMLAttributes } from 'react';
 import type { SPageBackground } from './page.config';
+import { type SPageHeaderProps } from './SPageHeader';
 export interface SPageProps extends HTMLAttributes<HTMLElement> {
     /**
      * 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕.
@@ -11,6 +12,11 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
      * 기본으로 켜져 있고, 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 끈다(목록 페이지).
      */
     scrollEndSpacing?: boolean;
+    /**
+     * 페이지 타이틀 영역(pageHeader 포팅). 주면 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다.
+     * `children` 은 항상 본문이다 — header 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다.
+     */
+    header?: SPageHeaderProps;
 }
 /**
  * SPage — SLayout 안에서 남은 공간을 채우는 스크롤 콘텐츠 영역.
@@ -21,5 +27,9 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
  * - header="fix": flex 자식으로 남은 가로 공간을 채운다.
  * - header="full": SLayout 이 깐 grid 의 "page" 영역 = 상단바 아래·메뉴 오른쪽 자리를 차지한다.
  *   좌표가 아니라 이름으로 잡으므로 프레임의 열·행 구성이 바뀌어도 여기는 그대로다.
+ *
+ * **`header` prop 을 주면** 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다(fix 베리에이션이
+ * 늘 보이는 높이 56 바가 되도록). 주지 않으면 이전과 동일하게 동작한다 — ref·className·style·
+ * 나머지 속성이 전부 스크롤 영역 자체(`<main>`)에 그대로 붙는다.
  */
 export declare const SPage: import("react").ForwardRefExoticComponent<SPageProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/SPage/SPageHeader.d.ts

@@ -0,0 +1,32 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface SPageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'slot' | 'title'> {
+    /** 타이틀 (필수) */
+    title: string;
+    /** 서브 텍스트. fix=true 면 타이틀 오른쪽에, fix=false(기본) 면 타이틀 아래에 놓인다. */
+    subText?: string;
+    /**
+     * true: 높이 56 고정 + 흰 배경 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄.
+     * false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 투명 배경,
+     * 서브 텍스트가 타이틀 아래로 내려간다.
+     */
+    fix?: boolean;
+    /** 뒤로가기 클릭 핸들러. 지정하면 왼쪽에 뒤로가기 버튼이 나타난다. */
+    onBack?: () => void;
+    /** 오른쪽 끝 커스텀 슬롯. 가이드 링크·액션 버튼 등 페이지마다 다른 것이 온다. */
+    slot?: ReactNode;
+    /**
+     * `<SPage>` 가 스크롤 여부를 보고 자동으로 넣어준다 — 직접 주지 않는다.
+     * fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는
+     * 콘텐츠 위에 뜬 것처럼 보인다. 배경은 그대로 페이지 배경을 따라간다 — 배경을 바꾸는 건
+     * scrolled 가 아니라 fix 다.
+     * @nodemo SPage 가 스크롤 이벤트로 넣어준다 — 사용자가 직접 시연할 값이 아니다.
+     */
+    scrolled?: boolean;
+}
+/**
+ * SPage 위에 얹는 페이지 타이틀 영역(pageHeader 포팅). `SPage` 가 `header` prop 값으로
+ * 내부적으로만 렌더한다 — 직접 임포트해 쓰지 않는다 (SPage.tsx 참고).
+ * fix 로 bar(높이 고정·흰 배경) / plain(투명·최소 높이) 두 베리에이션을 고른다.
+ * 뒤로가기 버튼은 onBack 유무로 나타나며, 없을 때는 타이틀 쪽에 4px 여백이 대신 들어간다.
+ */
+export declare const SPageHeader: import("react").ForwardRefExoticComponent<SPageHeaderProps & import("react").RefAttributes<HTMLElement>>;

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

@@ -1,2 +1,3 @@
 export { SPage, type SPageProps } from './SPage';
 export { PAGE_BACKGROUNDS, type SPageBackground } from './page.config';
+export { type SPageHeaderProps } from './SPageHeader';

package/dist/components/SPortal/README.md

@@ -18,7 +18,7 @@
 | `maxHeight?` | `number` | — | 콘텐츠 최대 높이 px. 넘치면 세로 스크롤. |
 | `autoClose?` | `boolean` | `false` | 콘텐츠 내부를 클릭하면 자동으로 닫는다. |
 | `persistent?` | `boolean` | `false` | 외부 클릭 · ESC 로 닫히지 않게 한다. |
-| `viewportPadding?` | `number` | `0` | 뷰포트 경계 여백 px (충돌 회피 패딩). |
+| `viewportPadding?` | `number` | `0` | 뷰포트 경계 여백 px (충돌 회피 패딩). 콘텐츠 폭은 항상 `창 폭 - viewportPadding*2` 를 넘지 않게 잘린다. |
 | `children?` | `ReactNode` | — | 본문 내용 (콘텐츠 자유). |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |