sellmate-design-system-react 9.0.0-beta.10 → 9.0.0-beta.12

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 > **대상**: 이 패키지로 화면을 만드는 소비 앱의 개발자와 AI 코딩 에이전트(Claude 등).
 > 이 문서는 "무엇을 언제 쓰고, 무엇을 쓰면 안 되는지"의 단일 기준이다.
-> 개별 컴포넌트의 상세 Props/Events는 `node_modules/sellmate-design-system-react/dist/components/<이름>/README.md` 를 참조한다.
+> 개별 컴포넌트의 상세 Props/Events와 그 Props 가 쓰는 타입 정의(Types)는 `node_modules/sellmate-design-system-react/dist/components/<이름>/README.md` 를 참조한다.
 
 ## 0. 최우선 원칙 — 디자인 시스템 컴포넌트가 먼저다
 
@@ -20,7 +20,7 @@
 
 ### 0-1. 전체 컴포넌트 인덱스
 
-무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props 는 `dist/components/<이름>/README.md` 참조.
+무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props·Types 는 `dist/components/<이름>/README.md` 참조.
 
 **이 표에서 어느 것을 골라야 할지 모르겠으면 §3-0 "의도 → 컴포넌트 라우팅" 으로 간다.** 하려는 일을 문장으로 찾으면 답이 하나 나온다 — 여기 인덱스는 "무엇이 있는지", §3-0 은 "언제 그걸 쓰는지" 를 담당한다.
 
@@ -1163,7 +1163,7 @@ const columns: STableColumn[] = [
 - **기본은 `SKeyValueTable` 이다** (§4-2). 조건이 대여섯 개 이하로 고정이면 표로 펼쳐 두는 편이 한눈에 읽힌다.
 - `SChipFilter` 는 조건을 **칩 한 줄**로 접고, "필터 추가" 로 필요한 것만 꺼내 쓰게 한다. 칩을 누르면 편집 팝오버가 열리고, 날짜는 프리셋(오늘·지난 7일·사용자 지정)으로 고른다. 조건 후보가 많은 목록 화면에서 필터가 화면을 세로로 잡아먹는 것을 막는 용도다.
 - 검색 실행 시점이 다르다 — `SKeyValueTable` 필터는 앱이 검색 버튼을 직접 놓지만, `SChipFilter` 는 편집 팝오버가 닫히거나 "검색" 을 누를 때 `onSearch` 가 값 맵과 함께 호출된다. 값이 바뀌지 않았으면 호출되지 않는다.
-- 함께 걸어야 하는 조건(예: 기간 중 하나는 필수)이 있으면 `fields` 를 그룹으로 넘긴다. 규칙을 못 채운 동안 경고 툴팁이 떠 있고 `onSearch` 가 막힌다.
+- **`fields` 는 항상 그룹 배열이다.** 묶을 것이 없어도 `[{ fields: [...] }]` 로 한 겹 감싼다. 함께 걸어야 하는 조건(예: 기간 중 하나는 필수)이 있으면 그 필드들만 별도 그룹으로 떼어 `rule` 을 준다 — 규칙을 못 채운 동안 경고 툴팁이 떠 있고 `onSearch` 가 막힌다. 그룹 앞 구분선은 `divider` 로 켠다. 검증 단위와 구분선은 별개라, 묶어서 검증만 하고 싶으면 `divider` 를 주지 않는다.
 
 #### 3-7-12. 이미지 — SImage
 

package/dist/components/SBadge/README.md

@@ -10,6 +10,30 @@
 |------|------|---------|-------------|
 | `color?` | `SBadgeColor` | `'blue'` | 뱃지 색상 |
 
+## Types
+
+### SBadgeColor
+
+```ts
+export type SBadgeColor = (typeof BADGE_COLORS)[number];
+```
+
+### BADGE_COLORS
+
+```ts
+export const BADGE_COLORS = [
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'lightblue',
+  'blue',
+  'darkblue',
+  'indigo',
+  'grey',
+] as const;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SBadge/SBadge.d.ts

@@ -1,5 +1,5 @@
 import { type HTMLAttributes } from 'react';
-export declare const BADGE_COLORS: readonly ["red", "orange", "yellow", "green", "blue", "darkblue", "indigo", "grey"];
+export declare const BADGE_COLORS: readonly ["red", "orange", "yellow", "green", "lightblue", "blue", "darkblue", "indigo", "grey"];
 export type SBadgeColor = (typeof BADGE_COLORS)[number];
 export interface SBadgeProps extends HTMLAttributes<HTMLSpanElement> {
     /** 뱃지 색상 */

package/dist/components/SBarcodeInput/README.md

@@ -47,6 +47,14 @@
 | `onFocus` | `() => void` |  |
 | `onBlur` | `() => void` |  |
 
+## Types
+
+### SBarcodeInputSize
+
+```ts
+export type SBarcodeInputSize = SFieldSize;
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SButton/README.md

@@ -15,6 +15,40 @@
 | `rightIcon?` | `SIconName` | — | 레이블 오른쪽 아이콘 |
 | `label?` | `string` | — | 버튼 텍스트 (문자열만 — 아이콘은 icon/rightIcon 사용) |
 
+## Types
+
+### SButtonColor
+
+```ts
+export type SButtonColor = (typeof BUTTON_COLORS)[number];
+```
+
+### SButtonSize
+
+```ts
+export type SButtonSize = (typeof BUTTON_SIZES)[number];
+```
+
+### BUTTON_COLORS
+
+```ts
+/**
+ * SButton 색상/사이즈 설정 — sd-button(component.button 토큰) 충실 포팅.
+ * Stencil `name`(예: primary_sm)의 preset을 color + outline(boolean) + size 로 분리.
+ *  - primary / danger : solid·outline 모두 지원
+ *  - secondary        : solid 전용 (outline 스타일 없음 → outline 무시)
+ *  - neutral          : 흰 배경 고정, outline 은 회색 테두리만 추가(solid = 테두리 없는 흰 버튼)
+ * 색상은 theme.css의 `--cmp-button-*` CSS 변수를 참조한다.
+ */
+export const BUTTON_COLORS = ['primary', 'secondary', 'neutral', 'danger'] as const;
+```
+
+### BUTTON_SIZES
+
+```ts
+export const BUTTON_SIZES = ['xs', 'sm', 'md', 'lg'] as const;
+```
+
 ## Dependencies
 
 ### Used by

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,9 +8,9 @@
 
 | 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)·구분선 표시 여부 |
 | `showReset?` | `boolean` | `true` | 검색 초기화 링크 표시 여부 |
@@ -35,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
 

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

@@ -1,6 +1,9 @@
 import { type CSSProperties, type ReactNode } from 'react';
 import { type SDateRangeValue } from '../SDateRangePicker';
-export type SChipFilterType = 'single' | 'multi' | 'keyword' | 'date' | 'period' | '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';
@@ -34,51 +37,81 @@ export interface SChipFilterPeriodValue {
 export type SChipFilterCustomValue = Record<string, unknown>;
 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/defaultActive와 무관하게 항상 노출되고 "필터 추가" 목록에는 나타나지 않는다 */
-    fix?: 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/period 필드의 프리셋 라디오 목록. date에서 지정하지 않으면 기존처럼 단일 캘린더 트리거로 동작하고,
-     *  period에서 지정하지 않으면 일별·월별·분기별·반기별·연도별·사용자 지정 기본 목록을 쓴다 */
-    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;
@@ -86,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;
@@ -101,7 +138,7 @@ export type SChipFilterGroupRule = {
     type: 'requireAny';
     dataGroupName?: string;
 };
-/** 필터를 그룹으로 묶어서 넘길 때의 단위. 그룹이 시작될 때마다 앞에 구분선이 붙는다. */
+/** fields를 이루는 단위. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]` */
 export interface SChipFilterGroup {
     fields: SChipFilterField[];
     /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
@@ -110,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를 쓴다 */
@@ -140,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에 반영해야 한다 */