sellmate-design-system-react 9.0.0-beta.27 → 9.0.0-beta.29

package/AGENTS.md

@@ -27,7 +27,7 @@
 | 분류 | 컴포넌트 |
 | --- | --- |
 | **버튼·링크** | `SButton` `SGhostButton` `SDropdownButton` `SSystemActionButton` `STextLink` `SSwitch` `SToggle` |
-| **입력 (폼)** | `SForm` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
+| **입력 (폼)** | `SForm` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
 | **날짜·시간** | `SCalendar` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` |
 | **표·목록** | `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
 | **레이아웃** | `SLayout` `SGnb` `SPage`(제목 영역은 `header` prop) `SSectionHeaderCard` `SCard` `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
@@ -152,7 +152,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` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SImage` `SLinearProgress` `SCircleProgress` |
+| **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SDropdownButton` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `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` |
 
@@ -300,6 +300,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 - **라디오는 `SRadioGroup` 을 쓴다.** `direction="horizontal" | "vertical"` 만 주면 간격을 알아서 맞춘다 — 직접 `flex` 로 감싸지 않는다.
 - `SRadioButton` 그룹의 간격은 `-1px`(테두리 겹침 처리)이라 손으로 만들지 않는다.
+- **카드형 라디오는 `SRadioCardGroup` 을 쓴다.** 카드 사이 간격은 수평·수직이 같고 `SRadioGroup` 과 다르므로, 손으로 `flex gap-…` 을 맞추지 말고 `direction` 만 준다.
 - 정확한 값이 필요하면 토큰을 직접 참조해도 된다: `gap-[var(--cmp-checkbox-group-gap-horizontal)]`
 
 #### 섹션·패널 안쪽 여백
@@ -480,6 +481,8 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 목록에서 하나 고르게 한다 | `SSelect` | §3-7-2 |
 | 선택지를 항상 펼쳐 두고 하나 고르게 한다 | `SRadioGroup` | §3-7-2 |
 | 버튼 모양으로 모드를 하나 고르게 한다 | `SRadioButton` | §3-7-2 |
+| 선택지마다 설명이 붙어 한 줄로는 안 된다 | `SRadioCardGroup` | §3-7-2 |
+| 설명이 붙은 선택지 카드 하나를 직접 배치한다 | `SRadioCard` | §3-7-2 |
 | 라디오 하나를 표 셀 등에 직접 배치한다 | `SRadio` | §3-7-2 |
 | 여러 개를 고르게 한다 / 동의를 받는다 | `SCheckbox` | §3-7-3 |
 | 켜는 즉시 반영되는 설정을 준다 | `SSwitch` | §3-7-3 |
@@ -1267,7 +1270,7 @@ const columns: STableColumn[] = [
 
 `SSearchInput` 은 폼 필드가 아니다 — 라벨·힌트·유효성 규칙·에러 메시지를 받지 않고, `SForm` 의 제출 검증 대상에도 들어가지 않는다. 돋보기 아이콘이 항상 앞에 붙어 "여기는 검색"임을 스스로 밝히므로 라벨을 따로 붙이지 않는다. 검색 실행은 `onSearch`(Enter) 로 받고, 값이 바뀔 때마다 좁히는 실시간 필터라면 `onValueChange` 만 쓴다. 반대로 검색어를 **저장하거나 검증해야 한다면** 그것은 폼 값이므로 `SInput` 이다.
 
-#### 3-7-2. 하나를 고르게 하는 다섯 — SSelect vs SRadioGroup vs SRadioButton vs STabs vs SRadio
+#### 3-7-2. 하나를 고르게 하는 여섯 — SSelect vs SRadioGroup vs SRadioCardGroup vs SRadioButton vs STabs vs SRadio
 
 **먼저 "고르면 무엇이 바뀌는가"를 본다.**
 
@@ -1278,10 +1281,14 @@ const columns: STableColumn[] = [
 | --- | --- |
 | 6개 이상, 또는 서버에서 오는 동적 목록 | `SSelect` |
 | 2~5개 고정 + 선택지를 항상 보여야 함 | `SRadioGroup` |
+| 2~5개 고정 + **선택지마다 설명 한 줄이 필요함** | `SRadioCardGroup` |
 | 2~4개 + 짧은 라벨의 배타적 모드 전환 (세그먼트) | `SRadioButton` |
 
 - **`SRadio` 를 직접 나열하지 않는다.** 그룹 간격은 `SRadioGroup` 이 맞춘다 (§2-2). `SRadio` 단독은 `SRadioGroup` 이 만들 수 없는 배치 — 표 셀 안에 행마다 하나씩 놓는 경우 — 에만 쓴다.
 - `SRadioButton` 은 `options` 를 통째로 받는 세그먼트 컨트롤이라 `SRadio` 를 여러 개 넣는 게 아니다.
+- **`SRadioGroup` 과 `SRadioCardGroup` 의 갈림길은 "설명이 필요한가" 하나다.** 라벨만으로 뜻이 통하면 `SRadioGroup`, 고르기 전에 한 줄 설명을 읽어야 하면 `SRadioCardGroup` 이다. 라벨 옆에 설명을 괄호로 덧붙여 늘이지 않는다.
+- `SRadioCard` 단독은 `SRadioCardGroup` 이 만들 수 없는 배치에만 쓴다 — 나열은 그룹이 맡는다 (§2-2).
+- 카드 안에 상태 배지를 넣으려면 `tag` 슬롯에 `STag` 를 준다. 라벨 문자열에 "(추천)" 처럼 섞어 쓰지 않는다.
 
 #### 3-7-3. 켜고 끄는 셋 — SCheckbox vs SSwitch vs SToggle
 

package/dist/components/SChipFilter/README.md

@@ -259,7 +259,10 @@ export interface SChipFilterFieldBase {
   /** 칩에 표시할 레이블 */
   label: string;
   /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
-   *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
+   *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다.
+   *  값이 채워졌다가 다시 비면(예: value를 제어하는 부모가 onReset에서 자기 상태를 비우는 경우)
+   *  기본값이 한 번 더 채워진다 — required 필드가 빈 채로 남으면 onSearch가 막히기 때문이다.
+   *  단 그 값을 부모가 value로 받아 주지 않으면 반복해서 채우지는 않는다 */
   required?: boolean;
   /** 고정 필터. true면 activeKeys와 무관하게 항상 노출되고 "필터 추가" 목록에는 나타나지 않는다.
    *  required도 같은 효과를 낸다 — 처음부터 바에 보이는 것은 fixed이거나 required인 필드뿐이고,

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

@@ -46,7 +46,10 @@ export interface SChipFilterFieldBase {
     /** 칩에 표시할 레이블 */
     label: string;
     /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
-     *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
+     *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다.
+     *  값이 채워졌다가 다시 비면(예: value를 제어하는 부모가 onReset에서 자기 상태를 비우는 경우)
+     *  기본값이 한 번 더 채워진다 — required 필드가 빈 채로 남으면 onSearch가 막히기 때문이다.
+     *  단 그 값을 부모가 value로 받아 주지 않으면 반복해서 채우지는 않는다 */
     required?: boolean;
     /** 고정 필터. true면 activeKeys와 무관하게 항상 노출되고 "필터 추가" 목록에는 나타나지 않는다.
      *  required도 같은 효과를 낸다 — 처음부터 바에 보이는 것은 fixed이거나 required인 필드뿐이고,

package/dist/components/SLinearProgress/README.md

@@ -10,6 +10,7 @@
 |------|------|---------|-------------|
 | `value?` | `number` | `0` | 진행률 (0–100) |
 | `type?` | `SLinearProgressType` | `'primary'` | 색상 타입 |
+| `size?` | `SLinearProgressSize` | `'sm'` | 바 높이. xs 는 바 안에 퍼센트 텍스트를 넣지 않는다 |
 | `indeterminate?` | `boolean` | `false` | 진행률 없이 무한 애니메이션 |
 | `label?` | `string` | — | 하단 레이블 |
 | `className?` | `string` | — |  |
@@ -23,3 +24,9 @@
 export type SLinearProgressType = 'primary' | 'error' | 'complete';
 ```
 
+### SLinearProgressSize
+
+```ts
+export type SLinearProgressSize = 'xs' | 'sm' | 'md';
+```
+

package/dist/components/SLinearProgress/SLinearProgress.d.ts

@@ -1,10 +1,13 @@
 import { type CSSProperties } from 'react';
 export type SLinearProgressType = 'primary' | 'error' | 'complete';
+export type SLinearProgressSize = 'xs' | 'sm' | 'md';
 export interface SLinearProgressProps {
     /** 진행률 (0–100) */
     value?: number;
     /** 색상 타입 */
     type?: SLinearProgressType;
+    /** 바 높이. xs 는 바 안에 퍼센트 텍스트를 넣지 않는다 */
+    size?: SLinearProgressSize;
     /** 진행률 없이 무한 애니메이션 */
     indeterminate?: boolean;
     /** 하단 레이블 */

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

@@ -1 +1 @@
-export { SLinearProgress, type SLinearProgressProps, type SLinearProgressType, } from './SLinearProgress';
+export { SLinearProgress, type SLinearProgressProps, type SLinearProgressType, type SLinearProgressSize, } from './SLinearProgress';

package/dist/components/SRadioButton/README.md

@@ -37,7 +37,7 @@ export interface SRadioButtonOption {
 ### SRadioButtonSize
 
 ```ts
-export type SRadioButtonSize = 'xs' | 'sm';
+export type SRadioButtonSize = 'xs' | 'sm' | 'md';
 ```
 
 ## Dependencies

package/dist/components/SRadioButton/SRadioButton.d.ts

@@ -1,5 +1,5 @@
 import { type CSSProperties } from 'react';
-export type SRadioButtonSize = 'xs' | 'sm';
+export type SRadioButtonSize = 'xs' | 'sm' | 'md';
 export interface SRadioButtonOption {
     value: string | number;
     label: string;

package/dist/components/SRadioCard/README.md

@@ -0,0 +1,78 @@
+# SRadioCard
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SRadioCardGroup
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options?` | `SRadioCardOption[]` | `[]` | 옵션 목록 |
+| `value?` | `SRadioValue \| null` | — | 현재 선택 값 |
+| `direction?` | `'vertical' \| 'horizontal'` | `'vertical'` | 배치 방향 |
+| `disabled?` | `boolean` | `false` | 전체 비활성 |
+| `groupName?` | `string` | — | 라디오 name 속성 (form-agnostic 그룹핑) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(val: SRadioValue) => void` | 선택 변경 (sdUpdate) |
+
+### SRadioCard
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `val` | `SRadioValue` | — | 이 카드의 값 |
+| `value?` | `SRadioValue \| null` | — | 그룹의 현재 선택 값 |
+| `label` | `string` | — | 라벨 (첫 줄) |
+| `subtitle?` | `string` | — | 서브타이틀 (둘째 줄). 라벨 왼쪽 끝에 맞춰 들여쓴다 |
+| `tag?` | `Omit<STagProps, 'size'>` | — | 라벨 오른쪽에 붙일 태그. `STag` 의 props 를 그대로 받되 크기는 `xs` 로 고정된다 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `name?` | `string` | — | native radio name (form-agnostic 그룹핑) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(val: SRadioValue) => void` | 선택 변경 (sdUpdate) — 선택된 val 전달 |
+
+## Types
+
+### SRadioCardOption
+
+```ts
+export interface SRadioCardOption {
+  /** 옵션 값 */
+  value: SRadioValue;
+  /** 라벨 (첫 줄) */
+  label: string;
+  /** 서브타이틀 (둘째 줄) */
+  subtitle?: string;
+  /** 라벨 오른쪽에 붙일 태그 (`STag` props, 크기는 `xs` 고정) */
+  tag?: Omit<STagProps, 'size'>;
+  /** 이 옵션만 비활성 */
+  disabled?: boolean;
+}
+```
+
+## Dependencies
+
+### Depends on
+
+- [STag](../STag)
+
+### Graph
+
+```mermaid
+graph TD;
+  SRadioCard --> STag
+  style SRadioCard fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SRadioCard/SRadioCard.d.ts

@@ -0,0 +1,29 @@
+import { type CSSProperties } from 'react';
+import { type SRadioValue } from '../SRadio';
+import { type STagProps } from '../STag';
+export interface SRadioCardProps {
+    /** 이 카드의 값 */
+    val: SRadioValue;
+    /** 그룹의 현재 선택 값 */
+    value?: SRadioValue | null;
+    /** 라벨 (첫 줄) */
+    label: string;
+    /** 서브타이틀 (둘째 줄). 라벨 왼쪽 끝에 맞춰 들여쓴다 */
+    subtitle?: string;
+    /** 라벨 오른쪽에 붙일 태그. `STag` 의 props 를 그대로 받되 크기는 `xs` 로 고정된다 */
+    tag?: Omit<STagProps, 'size'>;
+    /** 비활성 */
+    disabled?: boolean;
+    /** native radio name (form-agnostic 그룹핑) */
+    name?: string;
+    /** 선택 변경 (sdUpdate) — 선택된 val 전달 */
+    onValueChange?: (val: SRadioValue) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SRadioCard — 라디오 + 라벨 + 서브타이틀을 카드 한 장에 담은 선택지.
+ * 카드 전체가 클릭 영역이며 `value === val` 이면 선택 상태다.
+ * 선택지마다 설명이 붙어 한 줄짜리 `SRadio` 로는 담기 어려울 때 쓴다.
+ */
+export declare function SRadioCard({ val, value, label, subtitle, tag, disabled, name, onValueChange, className, style, }: SRadioCardProps): import("react").JSX.Element;

package/dist/components/SRadioCard/SRadioCardGroup.d.ts

@@ -0,0 +1,36 @@
+import { type CSSProperties } from 'react';
+import { type SRadioValue } from '../SRadio';
+import { type STagProps } from '../STag';
+export interface SRadioCardOption {
+    /** 옵션 값 */
+    value: SRadioValue;
+    /** 라벨 (첫 줄) */
+    label: string;
+    /** 서브타이틀 (둘째 줄) */
+    subtitle?: string;
+    /** 라벨 오른쪽에 붙일 태그 (`STag` props, 크기는 `xs` 고정) */
+    tag?: Omit<STagProps, 'size'>;
+    /** 이 옵션만 비활성 */
+    disabled?: boolean;
+}
+export interface SRadioCardGroupProps {
+    /** 옵션 목록 */
+    options?: SRadioCardOption[];
+    /** 현재 선택 값 */
+    value?: SRadioValue | null;
+    /** 배치 방향 */
+    direction?: 'vertical' | 'horizontal';
+    /** 전체 비활성 */
+    disabled?: boolean;
+    /** 라디오 name 속성 (form-agnostic 그룹핑) */
+    groupName?: string;
+    /** 선택 변경 (sdUpdate) */
+    onValueChange?: (val: SRadioValue) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SRadioCardGroup — `options` 를 SRadioCard 로 렌더하고 카드 사이 간격을 맞춘다.
+ * 카드는 컨테이너 폭을 채우므로 horizontal 이면 카드들이 폭을 균등하게 나눠 갖는다.
+ */
+export declare function SRadioCardGroup({ options, value, direction, disabled, groupName, onValueChange, className, style, }: SRadioCardGroupProps): import("react").JSX.Element;

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

@@ -0,0 +1,2 @@
+export { SRadioCard, type SRadioCardProps } from './SRadioCard';
+export { SRadioCardGroup, type SRadioCardGroupProps, type SRadioCardOption, } from './SRadioCardGroup';

package/dist/components/STag/README.md

@@ -11,6 +11,7 @@
 | `shape?` | `STagShape` | `'square'` | 모양 |
 | `size?` | `STagSize` | `'sm'` | 크기 |
 | `color?` | `STagColor` | `'grey'` | 색상 |
+| `deep?` | `boolean` | `false` | 진한 배경(deep) 버전. 배경에 강조색을 채우고 텍스트·아이콘을 반전색으로 쓴다 |
 | `label?` | `string` | `''` | 레이블 텍스트 |
 | `icon?` | `SIconName` | — | 아이콘명 |
 | `iconLeft?` | `boolean` | `true` | 아이콘을 레이블 왼쪽에 배치 |
@@ -71,6 +72,7 @@ export const TAG_COLORS = [
  - [SConfirmModal](../SConfirmModal)
  - [SGhostButton](../SGhostButton)
  - [SGnb](../SGnb)
+ - [SRadioCard](../SRadioCard)
  - [SSystemActionButton](../SSystemActionButton)
  - [STabs](../STabs)
  - [STextLink](../STextLink)
@@ -88,6 +90,7 @@ graph TD;
   SConfirmModal --> STag
   SGhostButton --> STag
   SGnb --> STag
+  SRadioCard --> STag
   SSystemActionButton --> STag
   STabs --> STag
   STextLink --> STag

package/dist/components/STag/STag.d.ts

@@ -8,6 +8,8 @@ export interface STagProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'
     size?: STagSize;
     /** 색상 */
     color?: STagColor;
+    /** 진한 배경(deep) 버전. 배경에 강조색을 채우고 텍스트·아이콘을 반전색으로 쓴다 */
+    deep?: boolean;
     /** 레이블 텍스트 */
     label?: string;
     /** 아이콘명 */
@@ -20,6 +22,6 @@ export interface STagProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'
 /**
  * STag — sd-tag 포팅.
  * Stencil의 `name`(예: square_sm_grey) 프리셋을 shape/size/color 세 prop으로 분리.
- * 색상은 컴포넌트 토큰 `--cmp-tag-<color>-{bg,content}` 참조.
+ * 색상은 컴포넌트 토큰 `--cmp-tag-<color>-{bg,content}`, deep 은 `--cmp-tag-<color>-deep-*` 참조.
  */
 export declare const STag: import("react").ForwardRefExoticComponent<STagProps & import("react").RefAttributes<HTMLSpanElement>>;