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

package/dist/components/SCalendar/README.md

@@ -22,6 +22,19 @@
 | `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
 | `onViewChange` | `(v: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
 
+## Types
+
+### SCalendarEventGroup
+
+```ts
+export interface SCalendarEventGroup {
+  /** 도트 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
+  color: SColor;
+  label: string;
+  dates: string[];
+}
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SCallout/README.md

@@ -14,6 +14,21 @@
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
+## Types
+
+### SCalloutType
+
+```ts
+export type SCalloutType = 'default' | 'danger';
+```
+
+### SCalloutMessage
+
+```ts
+/** 중첩 메시지: 문자열 또는 (한 단계 더 들어간) 문자열 배열 */
+export type SCalloutMessage = string | SCalloutMessage[];
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SCheckbox/README.md

@@ -22,6 +22,14 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: boolean \| unknown[]) => void` | 값 변경 (sdUpdate) |
 
+## Types
+
+### SCheckboxValue
+
+```ts
+export type SCheckboxValue = boolean | unknown[] | null;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SChipFilter/README.md

@@ -8,12 +8,11 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `fields?` | `SChipFilterField[] \| SChipFilterGroup[]` | — | 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에 구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). |
+| `fields?` | `SChipFilterGroup[]` | — | 필터 정의 목록. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]`. 그룹은 rule로 함께 검증하거나 divider로 갈라 놓을 때 나눈다. |
 | `value?` | `SChipFilterValueMap` | — | 필터 값 맵 |
-| `activeKeys?` | `string[]` | — | 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접 넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별 defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 |
+| `activeKeys?` | `string[]` | — | 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접 넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 fixed·required 필드만 노출된 상태로 시작해 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다. fixed·required 필드는 이 배열에 없어도 항상 노출된다 |
 | `label?` | `string` | `'검색 필터'` | 좌측 태그 텍스트 |
 | `showLabel?` | `boolean` | `false` | 좌측 태그(label)·구분선 표시 여부 |
-| `showAddButton?` | `boolean` | `true` | 필터 추가 버튼 표시 여부 |
 | `showReset?` | `boolean` | `true` | 검색 초기화 링크 표시 여부 |
 | `disabled?` | `boolean` | `false` | 바 비활성 상태 |
 | `className?` | `string` | — |  |
@@ -36,7 +35,280 @@
 |--------|------|-------------|
 | `open` | `(key: string) => void` | 특정 필터 편집 팝오버를 엽니다. |
 | `reset` | `() => void` | 모든 필터 값을 초기화합니다. |
-| `validate` | `() => boolean` | fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
+| `validate` | `() => boolean` | 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. rule을 준 그룹이 없으면 항상 true. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
+
+## Types
+
+### SChipFilterGroup
+
+```ts
+/** fields를 이루는 단위. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]` */
+export interface SChipFilterGroup {
+  fields: SChipFilterField[];
+  /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
+   *  그룹이 rule을 만족하지 못하면 검색 시도 여부와 무관하게 그 즉시 그룹 중앙에 경고 툴팁이 뜬다.
+   *  지정 안 하면 검증하지 않는다. */
+  rule?: SChipFilterGroupRule;
+  /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
+  tooltipMessage?: string;
+  /** 이 그룹 앞에 구분선을 넣을지. 검증(rule)과 구분선은 별개라 — 묶어서 검증만 하고 싶으면
+   *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(showLabel의 구분선이 이미 있다) */
+  divider?: boolean;
+}
+```
+
+### SChipFilterValueMap
+
+```ts
+export type SChipFilterValueMap = Record<string, SChipFilterValue>;
+```
+
+### SChipFilterChangeDetail
+
+```ts
+export interface SChipFilterChangeDetail {
+  key: string;
+  value: SChipFilterValue;
+  values: SChipFilterValueMap;
+}
+```
+
+### SChipFilterField
+
+```ts
+/** 필터 하나의 정의. type에 따라 쓸 수 있는 속성이 달라진다 —
+ *  options는 single·multi·keyword, presets·selectable·maxRange는 date·period,
+ *  render는 custom 에만 있다 */
+export type SChipFilterField =
+  | SChipFilterSingleField
+  | SChipFilterMultiField
+  | SChipFilterKeywordField
+  | SChipFilterDateField
+  | SChipFilterPeriodField
+  | SChipFilterCustomField;
+```
+
+### SChipFilterGroupRule
+
+```ts
+/** 필터 그룹 검증 규칙 */
+export type SChipFilterGroupRule =
+  | { type: 'requireKey'; key: string }
+  | { type: 'requireAll' }
+  | { type: 'requireAny'; dataGroupName?: string };
+```
+
+### SChipFilterValue
+
+```ts
+export type SChipFilterValue =
+  | SChipFilterOptionValue
+  | SChipFilterOptionValue[]
+  | SDateRangeValue
+  | SChipFilterKeywordValue
+  | SChipFilterPeriodValue
+  | SChipFilterCustomValue
+  | null
+  | undefined;
+```
+
+### SChipFilterSingleField
+
+```ts
+/** 후보 하나를 고른다 */
+export interface SChipFilterSingleField extends SChipFilterOptionsField {
+  type: 'single';
+}
+```
+
+### SChipFilterMultiField
+
+```ts
+/** 후보 여럿을 고른다 */
+export interface SChipFilterMultiField extends SChipFilterOptionsField {
+  type: 'multi';
+}
+```
+
+### SChipFilterKeywordField
+
+```ts
+/** 키워드를 입력해 누적한다. options는 입력 중 후보로만 뜬다 */
+export interface SChipFilterKeywordField extends SChipFilterOptionsField {
+  type: 'keyword';
+  /** 입력 placeholder */
+  placeholder?: string;
+  /** 검색조건(포함/일치) 토글 표시 여부 */
+  matchModes?: boolean;
+  /** matchModes 활성 시 "미포함"까지 포함해 3개(포함/일치/미포함)로 노출할지.
+   *  기본 false — 2개(포함/일치)만 */
+  excludeMode?: boolean;
+}
+```
+
+### SChipFilterDateField
+
+```ts
+/** 날짜 하나 또는 기간을 고른다 */
+export interface SChipFilterDateField extends SChipFilterPresetsField {
+  type: 'date';
+  /** presets 없이 단일 캘린더 트리거로 동작할 때의 placeholder */
+  placeholder?: string;
+  /** presets를 필터 바에 세그먼트 라디오로 펼쳐 놓는다(팝오버 없음).
+   *  기본 false — 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
+  radioButton?: boolean;
+}
+```
+
+### SChipFilterPeriodField
+
+```ts
+/** 집계 단위(일·월·분기·반기·연)와 그 단위의 값을 함께 고른다 */
+export interface SChipFilterPeriodField extends SChipFilterPresetsField {
+  type: 'period';
+}
+```
+
+### SChipFilterCustomField
+
+```ts
+/** 칩+팝오버를 거치지 않고 바에 놓을 노드를 앱이 직접 그린다 */
+export interface SChipFilterCustomField extends SChipFilterFieldBase {
+  type: 'custom';
+  /** 필터 바의 이 필드 자리에 놓일 노드를 직접 그린다. 반환한 노드가 그대로 바에 노출된다 —
+   *  SSelect를 그대로 놓거나 SInput을 바로 노출하는 식으로 렌더 방식을 자유롭게 구성한다. */
+  render?: (ctx: {
+    value: SChipFilterValue;
+    disabled?: boolean;
+    warning?: boolean;
+    onValueChange: (value: SChipFilterValue) => void;
+  }) => ReactNode;
+}
+```
+
+### SChipFilterOptionValue
+
+```ts
+export type SChipFilterOptionValue = string | number;
+```
+
+### SChipFilterKeywordValue
+
+```ts
+/** keyword 필드에서 matchModes 활성 시 사용하는 값 형태 — 입력해 추가한 키워드 목록 */
+export interface SChipFilterKeywordValue {
+  keywords: string[];
+  mode: SChipFilterMatchMode;
+}
+```
+
+### SChipFilterPeriodValue
+
+```ts
+/** period 필드 값 — 선택 단위(unit)와 그 단위의 입력값(value)을 함께 보관한다 */
+export interface SChipFilterPeriodValue {
+  unit: SChipFilterPeriodUnit;
+  value?: string | number | SDateRangeValue | null;
+}
+```
+
+### SChipFilterCustomValue
+
+```ts
+/** custom 필드가 자유롭게 담는 값. 형태를 강제하지 않는다 — render에서 직접 정의한 그대로 읽고 쓴다 */
+export type SChipFilterCustomValue = Record<string, unknown>;
+```
+
+### SChipFilterOptionsField
+
+```ts
+/** 후보 목록에서 고르는 필터 — single·multi·keyword */
+export interface SChipFilterOptionsField extends SChipFilterFieldBase {
+  /** 고를 수 있는 후보 목록 */
+  options?: SChipFilterOption[];
+}
+```
+
+### SChipFilterPresetsField
+
+```ts
+/** 프리셋으로 기간을 고르는 필터 — date·period */
+export interface SChipFilterPresetsField extends SChipFilterFieldBase {
+  /** 프리셋 라디오 목록. date에서 지정하지 않으면 단일 캘린더 트리거로 동작하고,
+   *  period에서 지정하지 않으면 일별·월별·분기별·반기별·연도별·사용자 지정 기본 목록을 쓴다 */
+  presets?: SChipFilterDatePreset[];
+  /** 선택 가능 범위 */
+  selectable?: [string, string];
+  /** "사용자 지정" 프리셋으로 기간을 고를 때의 최대 선택 일수 */
+  maxRange?: number;
+}
+```
+
+### SChipFilterFieldBase
+
+```ts
+/** 타입과 무관하게 모든 필터가 갖는 속성 */
+export interface SChipFilterFieldBase {
+  /** 필터 식별자 */
+  key: string;
+  /** 칩에 표시할 레이블 */
+  label: string;
+  /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
+   *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
+  required?: boolean;
+  /** 고정 필터. true면 activeKeys와 무관하게 항상 노출되고 "필터 추가" 목록에는 나타나지 않는다.
+   *  required도 같은 효과를 낸다 — 처음부터 바에 보이는 것은 fixed이거나 required인 필드뿐이고,
+   *  나머지는 전부 "필터 추가"에서 골라야 나타난다 */
+  fixed?: boolean;
+  /** 초기값 및 clearable 클릭 시 되돌아갈 값. required 여부와 무관하게 적용된다 — 값이 비어 있으면
+   *  마운트(또는 "필터 추가"로 활성화) 시 이 값이 자동으로 채워진다. required인데 지정하지 않으면
+   *  타입별 내장 기본값(single: 첫 번째 옵션, date: 오늘 날짜)을 대신 쓴다 */
+  defaultValue?: SChipFilterValue;
+  /** 경고 테두리 표시. 바 전체를 잠그는 SChipFilterProps.disabled와 달리 이 필터에만 적용된다 */
+  warning?: boolean;
+  /** 이 필터만 비활성. 바에 남아 있되 팝오버가 열리지 않고 clearable도 눌리지 않는다.
+   *  바 전체를 잠그려면 SChipFilterProps.disabled를 쓴다 — 둘은 OR로 합쳐진다 */
+  disabled?: boolean;
+}
+```
+
+### SChipFilterMatchMode
+
+```ts
+export type SChipFilterMatchMode = 'contains' | 'exact' | 'excludes';
+```
+
+### SChipFilterPeriodUnit
+
+```ts
+export type SChipFilterPeriodUnit = 'day' | 'month' | 'quarter' | 'half' | 'year' | 'custom';
+```
+
+### SChipFilterOption
+
+```ts
+export interface SChipFilterOption {
+  value: SChipFilterOptionValue;
+  label: string;
+  disabled?: boolean;
+}
+```
+
+### SChipFilterDatePreset
+
+```ts
+/** date/period 필드의 프리셋 라디오 항목 (오늘/지난 7일/일별/월별/사용자 지정 등) */
+export interface SChipFilterDatePreset {
+  /** 프리셋 식별자 */
+  value: string;
+  /** 라벨 */
+  label: string;
+  /** true면 "사용자 지정" — 선택 시 날짜/기간 피커가 추가로 노출된다. resolve는 무시된다. */
+  custom?: boolean;
+  /** custom이 아닐 때 실제 값을 계산한다. 단일 날짜(string) 또는 기간([start,end]) 모두 가능 */
+  resolve?: () => string | SDateRangeValue;
+}
+```
 
 ## Dependencies
 
@@ -48,6 +320,7 @@
 - [SIcon](../SIcon)
 - [SRadio](../SRadio)
 - [SRadioButton](../SRadioButton)
+- [SSelect](../SSelect)
 - [STag](../STag)
 - [STextLink](../STextLink)
 - [STooltip](../STooltip)
@@ -62,6 +335,7 @@ graph TD;
   SChipFilter --> SIcon
   SChipFilter --> SRadio
   SChipFilter --> SRadioButton
+  SChipFilter --> SSelect
   SChipFilter --> STag
   SChipFilter --> STextLink
   SChipFilter --> STooltip

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

@@ -1,14 +1,18 @@
 import { type CSSProperties, type ReactNode } from 'react';
 import { type SDateRangeValue } from '../SDateRangePicker';
-export type SChipFilterType = 'single' | 'multi' | 'keyword' | 'date' | 'custom';
+/** 필터가 값을 받는 방식. 각 값에 대응하는 필드 인터페이스가 따로 있다 —
+ *  SChipFilterSingleField·SChipFilterMultiField·SChipFilterKeywordField·
+ *  SChipFilterDateField·SChipFilterPeriodField·SChipFilterCustomField */
+export type SChipFilterType = SChipFilterField['type'];
 export type SChipFilterOptionValue = string | number;
 export type SChipFilterMatchMode = 'contains' | 'exact' | 'excludes';
+export type SChipFilterPeriodUnit = 'day' | 'month' | 'quarter' | 'half' | 'year' | 'custom';
 export interface SChipFilterOption {
     value: SChipFilterOptionValue;
     label: string;
     disabled?: boolean;
 }
-/** date 필드의 프리셋 라디오 항목 (오늘/지난 7일/사용자 지정 등) */
+/** date/period 필드의 프리셋 라디오 항목 (오늘/지난 7일/일별/월별/사용자 지정 등) */
 export interface SChipFilterDatePreset {
     /** 프리셋 식별자 */
     value: string;
@@ -24,52 +28,90 @@ export interface SChipFilterKeywordValue {
     keywords: string[];
     mode: SChipFilterMatchMode;
 }
+/** period 필드 값 — 선택 단위(unit)와 그 단위의 입력값(value)을 함께 보관한다 */
+export interface SChipFilterPeriodValue {
+    unit: SChipFilterPeriodUnit;
+    value?: string | number | SDateRangeValue | null;
+}
 /** custom 필드가 자유롭게 담는 값. 형태를 강제하지 않는다 — render에서 직접 정의한 그대로 읽고 쓴다 */
 export type SChipFilterCustomValue = Record<string, unknown>;
-export type SChipFilterValue = SChipFilterOptionValue | SChipFilterOptionValue[] | SDateRangeValue | SChipFilterKeywordValue | SChipFilterCustomValue | null | undefined;
+export type SChipFilterValue = SChipFilterOptionValue | SChipFilterOptionValue[] | SDateRangeValue | SChipFilterKeywordValue | SChipFilterPeriodValue | SChipFilterCustomValue | null | undefined;
 export type SChipFilterValueMap = Record<string, SChipFilterValue>;
-export interface SChipFilterField {
+/** 타입과 무관하게 모든 필터가 갖는 속성 */
+export interface SChipFilterFieldBase {
     /** 필터 식별자 */
     key: string;
     /** 칩에 표시할 레이블 */
     label: string;
-    /** 필터 타입 */
-    type: SChipFilterType;
-    /** single/multi/keyword 후보 목록 */
-    options?: SChipFilterOption[];
     /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
      *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
     required?: boolean;
+    /** 고정 필터. true면 activeKeys와 무관하게 항상 노출되고 "필터 추가" 목록에는 나타나지 않는다.
+     *  required도 같은 효과를 낸다 — 처음부터 바에 보이는 것은 fixed이거나 required인 필드뿐이고,
+     *  나머지는 전부 "필터 추가"에서 골라야 나타난다 */
+    fixed?: boolean;
     /** 초기값 및 clearable 클릭 시 되돌아갈 값. required 여부와 무관하게 적용된다 — 값이 비어 있으면
      *  마운트(또는 "필터 추가"로 활성화) 시 이 값이 자동으로 채워진다. required인데 지정하지 않으면
      *  타입별 내장 기본값(single: 첫 번째 옵션, date: 오늘 날짜)을 대신 쓴다 */
     defaultValue?: SChipFilterValue;
-    /** 경고 테두리 표시 */
+    /** 경고 테두리 표시. 바 전체를 잠그는 SChipFilterProps.disabled와 달리 이 필터에만 적용된다 */
     warning?: boolean;
-    /** 비활성 상태 */
+    /** 이 필터만 비활성. 바에 남아 있되 팝오버가 열리지 않고 clearable도 눌리지 않는다.
+     *  바 전체를 잠그려면 SChipFilterProps.disabled를 쓴다 — 둘은 OR로 합쳐진다 */
     disabled?: boolean;
-    /** 처음부터 칩으로 노출할지 여부. false면 "필터 추가" 목록에만 나타나고, 거기서 고르기 전까지는
-     *  필터 바에 보이지 않는다. activeKeys를 직접 제어하는 경우엔 초기 activeKeys 구성에만 참고되고
-     *  이후엔 activeKeys가 우선한다 */
-    defaultActive?: boolean;
-    /** keyword 입력 placeholder */
+}
+/** 후보 목록에서 고르는 필터 — single·multi·keyword */
+export interface SChipFilterOptionsField extends SChipFilterFieldBase {
+    /** 고를 수 있는 후보 목록 */
+    options?: SChipFilterOption[];
+}
+/** 프리셋으로 기간을 고르는 필터 — date·period */
+export interface SChipFilterPresetsField extends SChipFilterFieldBase {
+    /** 프리셋 라디오 목록. date에서 지정하지 않으면 단일 캘린더 트리거로 동작하고,
+     *  period에서 지정하지 않으면 일별·월별·분기별·반기별·연도별·사용자 지정 기본 목록을 쓴다 */
+    presets?: SChipFilterDatePreset[];
+    /** 선택 가능 범위 */
+    selectable?: [string, string];
+    /** "사용자 지정" 프리셋으로 기간을 고를 때의 최대 선택 일수 */
+    maxRange?: number;
+}
+/** 후보 하나를 고른다 */
+export interface SChipFilterSingleField extends SChipFilterOptionsField {
+    type: 'single';
+}
+/** 후보 여럿을 고른다 */
+export interface SChipFilterMultiField extends SChipFilterOptionsField {
+    type: 'multi';
+}
+/** 키워드를 입력해 누적한다. options는 입력 중 후보로만 뜬다 */
+export interface SChipFilterKeywordField extends SChipFilterOptionsField {
+    type: 'keyword';
+    /** 입력 placeholder */
     placeholder?: string;
-    /** keyword 필드에 검색조건(포함/일치) 토글 표시 여부 */
+    /** 검색조건(포함/일치) 토글 표시 여부 */
     matchModes?: boolean;
-    /** matchModes 활성 시 "미포함"까지 포함해 3개(포함/일치/미포함)로 노출할지. 기본 false — 기존처럼 2개(포함/일치)만 */
+    /** matchModes 활성 시 "미포함"까지 포함해 3개(포함/일치/미포함)로 노출할지.
+     *  기본 false — 2개(포함/일치)만 */
     excludeMode?: boolean;
-    /** date 선택 가능 범위 */
-    selectable?: [string, string];
-    /** date 프리셋의 "사용자 지정" 기간 선택 시 최대 선택 일수 */
-    maxRange?: number;
-    /** date 필드의 프리셋 라디오 목록. 지정하지 않으면 기존처럼 단일 캘린더 트리거로 동작한다 */
-    presets?: SChipFilterDatePreset[];
-    /** presets 사용 시 UI 형태 — true: 필터 바에 세그먼트 라디오로 인라인 노출(팝오버 없음),
-     *  false(기본): 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
+}
+/** 날짜 하나 또는 기간을 고른다 */
+export interface SChipFilterDateField extends SChipFilterPresetsField {
+    type: 'date';
+    /** presets 없이 단일 캘린더 트리거로 동작할 때의 placeholder */
+    placeholder?: string;
+    /** presets를 필터 바에 세그먼트 라디오로 펼쳐 놓는다(팝오버 없음).
+     *  기본 false — 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
     radioButton?: boolean;
-    /** type이 'custom'일 때 필터 바에 이 필드 자리에 놓일 노드를 직접 그린다. 칩+팝오버를 거치지 않고
-     *  반환한 노드가 그대로 바에 노출된다 — SSelect를 그대로 놓거나 SInput을 바로 노출하는 식으로
-     *  렌더 방식 자체를 완전히 자유롭게 구성한다. */
+}
+/** 집계 단위(일·월·분기·반기·연)와 그 단위의 값을 함께 고른다 */
+export interface SChipFilterPeriodField extends SChipFilterPresetsField {
+    type: 'period';
+}
+/** 칩+팝오버를 거치지 않고 바에 놓을 노드를 앱이 직접 그린다 */
+export interface SChipFilterCustomField extends SChipFilterFieldBase {
+    type: 'custom';
+    /** 필터 바의 이 필드 자리에 놓일 노드를 직접 그린다. 반환한 노드가 그대로 바에 노출된다 —
+     *  SSelect를 그대로 놓거나 SInput을 바로 노출하는 식으로 렌더 방식을 자유롭게 구성한다. */
     render?: (ctx: {
         value: SChipFilterValue;
         disabled?: boolean;
@@ -77,6 +119,10 @@ export interface SChipFilterField {
         onValueChange: (value: SChipFilterValue) => void;
     }) => ReactNode;
 }
+/** 필터 하나의 정의. type에 따라 쓸 수 있는 속성이 달라진다 —
+ *  options는 single·multi·keyword, presets·selectable·maxRange는 date·period,
+ *  render는 custom 에만 있다 */
+export type SChipFilterField = SChipFilterSingleField | SChipFilterMultiField | SChipFilterKeywordField | SChipFilterDateField | SChipFilterPeriodField | SChipFilterCustomField;
 export interface SChipFilterChangeDetail {
     key: string;
     value: SChipFilterValue;
@@ -92,7 +138,7 @@ export type SChipFilterGroupRule = {
     type: 'requireAny';
     dataGroupName?: string;
 };
-/** 필터를 그룹으로 묶어서 넘길 때의 단위. 그룹이 시작될 때마다 앞에 구분선이 붙는다. */
+/** fields를 이루는 단위. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]` */
 export interface SChipFilterGroup {
     fields: SChipFilterField[];
     /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
@@ -101,21 +147,24 @@ export interface SChipFilterGroup {
     rule?: SChipFilterGroupRule;
     /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
     tooltipMessage?: string;
+    /** 이 그룹 앞에 구분선을 넣을지. 검증(rule)과 구분선은 별개라 — 묶어서 검증만 하고 싶으면
+     *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(showLabel의 구분선이 이미 있다) */
+    divider?: boolean;
 }
 export interface SChipFilterHandle {
     /** 특정 필터 편집 팝오버를 엽니다. */
     open: (key: string) => void;
     /** 모든 필터 값을 초기화합니다. */
     reset: () => void;
-    /** fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지
-     *  반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
+    /** 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. rule을 준 그룹이 없으면 항상 true.
+     *  경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
      *  이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) */
     validate: () => boolean;
 }
 export interface SChipFilterProps {
-    /** 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에
-     *  구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). */
-    fields?: SChipFilterField[] | SChipFilterGroup[];
+    /** 필터 정의 목록. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]`.
+     *  그룹은 rule로 함께 검증하거나 divider로 갈라 놓을 때 나눈다. */
+    fields?: SChipFilterGroup[];
     /** 필터 값 맵 */
     value?: SChipFilterValueMap;
     /** 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 */
@@ -131,8 +180,9 @@ export interface SChipFilterProps {
      *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) */
     onSearch?: (value: SChipFilterValueMap) => void;
     /** 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접
-     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별
-     *  defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 */
+     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면
+     *  fixed·required 필드만 노출된 상태로 시작해 컴포넌트가 내부 상태로 관리하는 비제어 방식으로
+     *  동작한다. fixed·required 필드는 이 배열에 없어도 항상 노출된다 */
     activeKeys?: string[];
     /** 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다.
      *  activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 */
@@ -147,8 +197,6 @@ export interface SChipFilterProps {
     label?: string;
     /** 좌측 태그(label)·구분선 표시 여부 */
     showLabel?: boolean;
-    /** 필터 추가 버튼 표시 여부 */
-    showAddButton?: boolean;
     /** 검색 초기화 링크 표시 여부 */
     showReset?: boolean;
     /** 바 비활성 상태 */

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

@@ -1 +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';
+export { SChipFilter, type SChipFilterChangeDetail, type SChipFilterCustomField, type SChipFilterDateField, type SChipFilterDatePreset, type SChipFilterField, type SChipFilterFieldBase, type SChipFilterGroup, type SChipFilterGroupRule, type SChipFilterHandle, type SChipFilterKeywordField, type SChipFilterKeywordValue, type SChipFilterMatchMode, type SChipFilterMultiField, type SChipFilterOption, type SChipFilterOptionValue, type SChipFilterOptionsField, type SChipFilterPeriodField, type SChipFilterPresetsField, type SChipFilterProps, type SChipFilterSingleField, type SChipFilterType, type SChipFilterValue, type SChipFilterValueMap, } from './SChipFilter';

package/dist/components/SChipInput/README.md

@@ -54,6 +54,20 @@
 |--------|------|-------------|
 | `focus` | `() => void` | 입력 필드에 포커스를 이동합니다. |
 
+## Types
+
+### SChipInputSize
+
+```ts
+export type SChipInputSize = SFieldSize;
+```
+
+### SChipInputMetaPlacement
+
+```ts
+export type SChipInputMetaPlacement = 'end' | 'inline';
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SCircleProgress/README.md

@@ -11,15 +11,25 @@
 | `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` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
+## Types
+
+### SCircleProgressType
+
+```ts
+export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete' | 'neutral';
+```
+
 ## Dependencies
 
 ### Used by
 
+ - [SImage](../SImage)
  - [SLoadingContainer](../SLoadingContainer)
  - [SLoadingModal](../SLoadingModal)
  - [STable](../STable)
@@ -28,6 +38,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면 퍼센트를 원 아래가 아닌 원 가운데에 표시 */