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

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` | — |  |
@@ -25,7 +24,7 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: SChipFilterValueMap) => void` | 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 |
 | `onFilterChange` | `(detail: SChipFilterChangeDetail) => void` | 개별 필터 값 변경 |
-| `onSearch` | `(value: SChipFilterValueMap) => void` | 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른 칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom, clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. dirty 체크가 기본 적용되어 있어 — 마지막으로 실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고 닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔 onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상 실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) |
+| `onSearch` | `(value: SChipFilterValueMap) => void` | 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른 칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom, clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도 그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. dirty 체크가 기본 적용되어 있어 — 마지막으로 실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고 닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔 onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상 실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) |
 | `onActiveKeysChange` | `(keys: string[]) => void` | 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다. activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 |
 | `onReset` | `() => void` | "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋된 뒤 호출된다 |
 | `onAddFilter` | `(key: string) => void` | "필터 추가" 목록에서 항목을 골랐을 때 — activeKeys를 직접 제어 중이면 이 콜백에서 (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다. activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 |
@@ -36,7 +35,291 @@
 |--------|------|-------------|
 | `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;
+  /** 입력 방식. 기본 'tag' — Enter 로 하나씩 추가한다.
+   *  'csv' 는 쉼표도 구분자로 인정해, 쉼표를 치거나 쉼표가 섞인 텍스트를 붙여넣으면 그 자리에서
+   *  여러 개로 쪼개져 목록에 쌓인다(엑셀에서 복사한 코드 목록을 한 번에 넣는 용도).
+   *  쌓이는 목록도 값 형태도 'tag' 와 같다 — 구분자만 늘어난다. */
+  input?: SChipFilterKeywordInput;
+  /** 검색조건(포함/일치) 토글 표시 여부 */
+  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;
+    /** 속한 그룹이 rule을 위반하는 동안 true — 직접 그린 노드에도 경고 표시를 맞추라는 신호다 */
+    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[];
+}
+```
+
+### SChipFilterKeywordInput
+
+```ts
+/** keyword 필드의 입력 방식 — 무엇을 키워드 하나의 끝으로 볼지 */
+export type SChipFilterKeywordInput = 'tag' | 'csv';
+```
+
+### 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;
+  /** 이 필터만 비활성. 바에 남아 있되 팝오버가 열리지 않고 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,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,59 +28,107 @@ 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;
-    /** 경고 테두리 표시 */
-    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';
+}
+/** keyword 필드의 입력 방식 — 무엇을 키워드 하나의 끝으로 볼지 */
+export type SChipFilterKeywordInput = 'tag' | 'csv';
+/** 키워드를 입력해 누적한다. options는 입력 중 후보로만 뜬다 */
+export interface SChipFilterKeywordField extends SChipFilterOptionsField {
+    type: 'keyword';
+    /** 입력 placeholder */
     placeholder?: string;
-    /** keyword 필드에 검색조건(포함/일치) 토글 표시 여부 */
+    /** 입력 방식. 기본 'tag' — Enter 로 하나씩 추가한다.
+     *  'csv' 는 쉼표도 구분자로 인정해, 쉼표를 치거나 쉼표가 섞인 텍스트를 붙여넣으면 그 자리에서
+     *  여러 개로 쪼개져 목록에 쌓인다(엑셀에서 복사한 코드 목록을 한 번에 넣는 용도).
+     *  쌓이는 목록도 값 형태도 'tag' 와 같다 — 구분자만 늘어난다. */
+    input?: SChipFilterKeywordInput;
+    /** 검색조건(포함/일치) 토글 표시 여부 */
     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;
+        /** 속한 그룹이 rule을 위반하는 동안 true — 직접 그린 노드에도 경고 표시를 맞추라는 신호다 */
         warning?: boolean;
         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 +144,7 @@ export type SChipFilterGroupRule = {
     type: 'requireAny';
     dataGroupName?: string;
 };
-/** 필터를 그룹으로 묶어서 넘길 때의 단위. 그룹이 시작될 때마다 앞에 구분선이 붙는다. */
+/** fields를 이루는 단위. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]` */
 export interface SChipFilterGroup {
     fields: SChipFilterField[];
     /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
@@ -101,21 +153,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를 쓴다 */
@@ -124,15 +179,17 @@ export interface SChipFilterProps {
     onFilterChange?: (detail: SChipFilterChangeDetail) => void;
     /** 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른
      *  칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom,
-     *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
+     *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도
+     *  그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
      *  실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고
      *  닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
      *  onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상
      *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) */
     onSearch?: (value: SChipFilterValueMap) => void;
     /** 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접
-     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별
-     *  defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 */
+     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면
+     *  fixed·required 필드만 노출된 상태로 시작해 컴포넌트가 내부 상태로 관리하는 비제어 방식으로
+     *  동작한다. fixed·required 필드는 이 배열에 없어도 항상 노출된다 */
     activeKeys?: string[];
     /** 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다.
      *  activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 */
@@ -147,8 +204,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 SChipFilterKeywordInput, 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

@@ -30,7 +30,7 @@
 | `labelWidth?` | `number \| string` | — |  |
 | `hint?` | `string` | — |  |
 | `errorMessage?` | `string` | — |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `status?` | `SFieldStatus` | — |  |
 | `icon?` | `SIconName` | — |  |
 | `iconColor?` | `SColor` | — |  |
@@ -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/SChipInput/SChipInput.d.ts

@@ -4,6 +4,7 @@ import { type SIconName } from '../SIcon';
 import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
+import { type SFieldWidth } from '../../lib/field-width';
 export type SChipInputSize = SFieldSize;
 export type SChipInputMetaPlacement = 'end' | 'inline';
 /** ref로 노출되는 UX 메서드 (sd-chip-input @Method sdFocus 대응) */
@@ -50,7 +51,12 @@ export interface SChipInputProps {
     labelWidth?: number | string;
     hint?: string;
     errorMessage?: string;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     status?: SFieldStatus;
     icon?: SIconName;
     iconColor?: SColor;

package/dist/components/SCircleProgress/README.md

@@ -17,6 +17,14 @@
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
+## Types
+
+### SCircleProgressType
+
+```ts
+export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete' | 'neutral';
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SConfirmModal/README.md

@@ -36,6 +36,22 @@
 | `onCancel` | `() => void` |  |
 | `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) |
 
+## Types
+
+### SConfirmModalType
+
+```ts
+export type SConfirmModalType = 'positive' | 'negative' | 'default';
+```
+
+### ConfirmModalMainButton
+
+```ts
+/** 확인 버튼 프리셋 (sd-confirm-modal ConfirmModalMainButton) */
+export type ConfirmModalMainButton =
+  'primary_md' | 'primary_outline_md' | 'danger_md' | 'danger_outline_md' | 'neutral_outline_md';
+```
+
 ## Dependencies
 
 ### Used by