sellmate-design-system-react 9.0.0-beta.3 → 9.0.0-beta.30

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

@@ -1,14 +1,19 @@
 import { type CSSProperties, type ReactNode } from 'react';
 import { type SDateRangeValue } from '../SDateRangePicker';
-export type SChipFilterType = 'single' | 'multi' | 'keyword' | 'date' | 'custom';
+/** 필터가 값을 받는 방식. 각 값에 대응하는 필드 인터페이스가 따로 있다 —
+ *  SChipFilterSelectField·SChipFilterSelectMultiField·SChipFilterKeywordField·
+ *  SChipFilterDatePickerDayField·SChipFilterDatePickerRangeField·
+ *  SChipFilterDatePickerStatisticsField·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일/사용자 지정 등) */
+/** datepicker-range·datepicker-statistics 필드의 프리셋 라디오 항목 (오늘/지난 7일/일별/월별/사용자 지정 등) */
 export interface SChipFilterDatePreset {
     /** 프리셋 식별자 */
     value: string;
@@ -16,7 +21,8 @@ export interface SChipFilterDatePreset {
     label: string;
     /** true면 "사용자 지정" — 선택 시 날짜/기간 피커가 추가로 노출된다. resolve는 무시된다. */
     custom?: boolean;
-    /** custom이 아닐 때 실제 값을 계산한다. 단일 날짜(string) 또는 기간([start,end]) 모두 가능 */
+    /** custom이 아닐 때 실제 값을 계산한다. 단일 날짜(string) 또는 기간([start,end]) 모두 가능 —
+     *  datepicker-range 에서는 'd' 를 그 하루짜리 기간 ['d', 'd'] 와 같은 값으로 본다 */
     resolve?: () => string | SDateRangeValue;
 }
 /** keyword 필드에서 matchModes 활성 시 사용하는 값 형태 — 입력해 추가한 키워드 목록 */
@@ -24,59 +30,132 @@ export interface SChipFilterKeywordValue {
     keywords: string[];
     mode: SChipFilterMatchMode;
 }
+/** datepicker-statistics 필드 값 — 선택 단위(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은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
+     *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다.
+     *  값이 채워졌다가 다시 비면(예: value를 제어하는 부모가 onReset에서 자기 상태를 비우는 경우)
+     *  기본값이 한 번 더 채워진다 — required 필드가 빈 채로 남으면 onSearch가 막히기 때문이다.
+     *  단 그 값을 부모가 value로 받아 주지 않으면 반복해서 채우지는 않는다 */
     required?: boolean;
-    /** 초기값 및 clearable 클릭 시 되돌아갈 값. required 여부와 무관하게 적용된다 — 값이 비어 있으면
-     *  마운트(또는 "필터 추가"로 활성화) 시 이 값이 자동으로 채워진다. required인데 지정하지 않으면
-     *  타입별 내장 기본값(single: 첫 번째 옵션, date: 오늘 날짜)을 대신 쓴다 */
+    /** 고정 필터. true면 항상 노출되고 "필터 추가" 목록에는 나타나지 않으며 칩을 제거할 수 없다.
+     *  required도 같은 효과를 낸다. 나머지 필드는 "필터 추가"에서 골랐거나 value에 값이 들어
+     *  있는 동안 노출된다 — 값으로 떠 있던 칩은 값이 비면 함께 빠지고, "필터 추가"로 꺼낸 칩은
+     *  값이 없어도 세션 동안 자리를 지킨다 */
+    fixed?: boolean;
+    /** 초기값 및 clearable 클릭 시 되돌아갈 값.
+     *
+     *  **`fixed` 또는 `required` 필드에서만 쓴다.** 그 외 필드에 지정하면 무시하고 콘솔에 알린다 —
+     *  뺄 수 있는 필터는 처음에 바에 없는데, 값 맵에는 기본값이 채워져 **보이지도 지울 수도 없는
+     *  조건이 검색에 걸린다.** 칩을 지워 값을 비워도 "검색 초기화"가 그 값을 되돌려 놓아 필터가
+     *  조용히 되살아난다. 처음부터 값이 정해져 있어야 하는 필터라면 그것이 `fixed`·`required` 다.
+     *
+     *  required인데 지정하지 않으면 타입별 내장 기본값(select: 첫 번째 옵션,
+     *  datepicker-day·datepicker-range: 오늘 날짜)을 대신 쓴다. 인라인(radioButton) datepicker-range
+     *  필드는 팝오버 없이 바에 바로 노출되어 빈 상태로 둘 수 없으므로, 이 규칙과 무관하게 언제나
+     *  오늘이 채워진다 */
     defaultValue?: SChipFilterValue;
-    /** 경고 테두리 표시 */
-    warning?: boolean;
-    /** 비활성 상태 */
+    /** 이 필터만 비활성. 바에 남아 있되 팝오버가 열리지 않고 clearable도 눌리지 않는다.
+     *  바 전체를 잠그려면 SChipFilterProps.disabled를 쓴다 — 둘은 OR로 합쳐진다 */
     disabled?: boolean;
-    /** 처음부터 칩으로 노출할지 여부. false면 "필터 추가" 목록에만 나타나고, 거기서 고르기 전까지는
-     *  필터 바에 보이지 않는다. activeKeys를 직접 제어하는 경우엔 초기 activeKeys 구성에만 참고되고
-     *  이후엔 activeKeys가 우선한다 */
-    defaultActive?: boolean;
-    /** keyword 입력 placeholder */
+}
+/** 후보 목록에서 고르는 필터 — select·select-multi·keyword */
+export interface SChipFilterOptionsField extends SChipFilterFieldBase {
+    /** 고를 수 있는 후보 목록 */
+    options?: SChipFilterOption[];
+}
+/** 프리셋으로 기간을 고르는 필터 — datepicker-range·datepicker-statistics */
+export interface SChipFilterPresetsField extends SChipFilterFieldBase {
+    /** 프리셋 라디오 목록. 지정하지 않으면 타입별 기본 목록을 쓴다 —
+     *  datepicker-range: 오늘·지난 7일·지난 30일·사용자 지정,
+     *  datepicker-statistics: 일별·월별·분기별·반기별·연도별·사용자 지정.
+     *  프리셋 라디오 없이 캘린더(datepicker-range) 하나만 두려면 presets: [] 를 명시한다 */
+    presets?: SChipFilterDatePreset[];
+    /** 선택 가능 범위 */
+    selectable?: [string, string];
+    /** "사용자 지정" 프리셋으로 기간을 고를 때의 최대 선택 일수.
+     *  지정하지 않아도 presets에 custom 프리셋이 있으면 기본 90일이 적용된다 — 무제한 기간
+     *  집계·조회로 백엔드에 과도한 요청이 가는 것을 막기 위한 안전장치. 다른 상한이 필요하면
+     *  이 값을 직접 지정한다 */
+    maxRange?: number;
+}
+/** 후보 하나를 고른다 */
+export interface SChipFilterSelectField extends SChipFilterOptionsField {
+    type: 'select';
+}
+/** 후보 여럿을 고른다 */
+export interface SChipFilterSelectMultiField extends SChipFilterOptionsField {
+    type: 'select-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 선택 가능 범위 */
+}
+/** 날짜 하나를 고른다 — 캘린더 트리거 하나만 놓인다. 프리셋으로 고르게 하거나 시작~종료를
+ *  받아야 하면 datepicker-range 다 */
+export interface SChipFilterDatePickerDayField extends SChipFilterFieldBase {
+    type: 'datepicker-day';
+    /** 캘린더 트리거의 placeholder */
+    placeholder?: string;
+    /** 선택 가능 범위 */
     selectable?: [string, string];
-    /** date 프리셋의 "사용자 지정" 기간 선택 시 최대 선택 일수 */
-    maxRange?: number;
-    /** date 필드의 프리셋 라디오 목록. 지정하지 않으면 기존처럼 단일 캘린더 트리거로 동작한다 */
-    presets?: SChipFilterDatePreset[];
-    /** presets 사용 시 UI 형태 — true: 필터 바에 세그먼트 라디오로 인라인 노출(팝오버 없음),
-     *  false(기본): 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
+}
+/** 기간(시작~종료)을 고른다. presets를 주면 프리셋 라디오 목록으로 고르고,
+ *  주지 않으면 기간 피커 하나만 놓인다 */
+export interface SChipFilterDatePickerRangeField extends SChipFilterPresetsField {
+    type: 'datepicker-range';
+    /** presets를 필터 바에 세그먼트 라디오로 펼쳐 놓는다(팝오버 없음).
+     *  기본 false — 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
     radioButton?: boolean;
-    /** type이 'custom'일 때 필터 바에 이 필드 자리에 놓일 노드를 직접 그린다. 칩+팝오버를 거치지 않고
-     *  반환한 노드가 그대로 바에 노출된다 — SSelect를 그대로 놓거나 SInput을 바로 노출하는 식으로
-     *  렌더 방식 자체를 완전히 자유롭게 구성한다. */
+}
+/** 집계 단위(일·월·분기·반기·연)와 그 단위의 값을 함께 고른다 */
+export interface SChipFilterDatePickerStatisticsField extends SChipFilterPresetsField {
+    type: 'datepicker-statistics';
+}
+/** 칩+팝오버를 거치지 않고 바에 놓을 노드를 앱이 직접 그린다 */
+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는 select·select-multi·keyword, presets·maxRange·radioButton은
+ *  datepicker-range·datepicker-statistics, render는 custom 에만 있다 */
+export type SChipFilterField = SChipFilterSelectField | SChipFilterSelectMultiField | SChipFilterDatePickerDayField | SChipFilterDatePickerRangeField | SChipFilterDatePickerStatisticsField | SChipFilterKeywordField | SChipFilterCustomField;
 export interface SChipFilterChangeDetail {
     key: string;
     value: SChipFilterValue;
@@ -92,7 +171,7 @@ export type SChipFilterGroupRule = {
     type: 'requireAny';
     dataGroupName?: string;
 };
-/** 필터를 그룹으로 묶어서 넘길 때의 단위. 그룹이 시작될 때마다 앞에 구분선이 붙는다. */
+/** fields를 이루는 단위. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]` */
 export interface SChipFilterGroup {
     fields: SChipFilterField[];
     /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
@@ -101,21 +180,27 @@ export interface SChipFilterGroup {
     rule?: SChipFilterGroupRule;
     /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
     tooltipMessage?: string;
+    /** 이 그룹 앞에 구분선을 넣을지. 검증(rule)과 구분선은 별개라 — 묶어서 검증만 하고 싶으면
+     *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(label을 지정했다면 그 구분선이
+     *  이미 있다) */
+    divider?: boolean;
 }
 export interface SChipFilterHandle {
     /** 특정 필터 편집 팝오버를 엽니다. */
     open: (key: string) => void;
-    /** 모든 필터 값을 초기화합니다. */
+    /** 바를 처음 상태로 되돌립니다 — 모든 필터 값이 기본값(또는 null)으로 돌아가고, "필터 추가"로
+     *  꺼내 놓은 칩도 함께 빠져 fixed·required 필드만 남습니다. 열려 있던 편집 팝오버는 닫힙니다 */
     reset: () => void;
-    /** fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지
-     *  반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
+    /** 현재 값 기준으로 각 그룹의 rule을 만족하는지, 그리고 required 필드가 모두 비어 있지 않은지
+     *  반환합니다. rule을 준 그룹이 없고 required 필드도 모두 값이 있으면 항상 true.
+     *  경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
      *  이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) */
     validate: () => boolean;
 }
 export interface SChipFilterProps {
-    /** 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에
-     *  구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). */
-    fields?: SChipFilterField[] | SChipFilterGroup[];
+    /** 필터 정의 목록. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]`.
+     *  그룹은 rule로 함께 검증하거나 divider로 갈라 놓을 때 나눈다. */
+    fields?: SChipFilterGroup[];
     /** 필터 값 맵 */
     value?: SChipFilterValueMap;
     /** 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 */
@@ -124,31 +209,25 @@ export interface SChipFilterProps {
     onFilterChange?: (detail: SChipFilterChangeDetail) => void;
     /** 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른
      *  칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom,
-     *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
+     *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도
+     *  그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
      *  실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고
      *  닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
      *  onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상
-     *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) */
+     *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음). required 필드가 비어 있는 동안에도
+     *  마찬가지로 호출되지 않는다 — 정상 설정(내장 기본값 또는 defaultValue)이라면 원래 비워지지
+     *  않지만, defaultValue 없는 select-multi·keyword·custom에 required만 준 오설정에서는 "검색
+     *  초기화"·clearable이 값을 null로 비울 수 있어 이때의 안전장치다 */
     onSearch?: (value: SChipFilterValueMap) => void;
-    /** 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접
-     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별
-     *  defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 */
-    activeKeys?: string[];
-    /** 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다.
-     *  activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 */
-    onActiveKeysChange?: (keys: string[]) => void;
-    /** "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋된 뒤 호출된다 */
+    /** "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋되고 "필터 추가"로 꺼낸 칩이
+     *  바에서 빠진 뒤 호출된다 */
     onReset?: () => void;
-    /** "필터 추가" 목록에서 항목을 골랐을 때 — activeKeys를 직접 제어 중이면 이 콜백에서
-     *  (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다.
-     *  activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 */
+    /** "필터 추가" 목록에서 항목을 골랐을 때 호출된다(알림). 칩 노출은 컴포넌트가 알아서 하므로
+     *  이 콜백에서 따로 해줄 일은 없다 */
     onAddFilter?: (key: string) => void;
-    /** 좌측 태그 텍스트 */
+    /** 좌측 태그 텍스트. 지정하면 태그와 그 뒤 구분선이 함께 노출되고, 지정하지 않으면(undefined)
+     *  둘 다 생략된다 */
     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 SChipFilterCustomValue, type SChipFilterDatePickerDayField, type SChipFilterDatePickerRangeField, type SChipFilterDatePickerStatisticsField, type SChipFilterDatePreset, type SChipFilterField, type SChipFilterFieldBase, type SChipFilterGroup, type SChipFilterGroupRule, type SChipFilterHandle, type SChipFilterKeywordField, type SChipFilterKeywordInput, type SChipFilterKeywordValue, type SChipFilterMatchMode, type SChipFilterOption, type SChipFilterOptionValue, type SChipFilterOptionsField, type SChipFilterPeriodUnit, type SChipFilterPeriodValue, type SChipFilterPresetsField, type SChipFilterProps, type SChipFilterSelectField, type SChipFilterSelectMultiField, 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/SChipInput/index.d.ts

@@ -1 +1 @@
-export { SChipInput, type SChipInputMetaPlacement, type SChipInputProps, type SChipInputSize, } from './SChipInput';
+export { SChipInput, type SChipInputHandle, type SChipInputMetaPlacement, type SChipInputProps, type SChipInputSize, } from './SChipInput';

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

@@ -24,7 +24,7 @@
 | `optionSlot?` | `ReactNode` | — | 콘텐츠 박스에서 태그 오른쪽 커스텀 콘텐츠 (미지정 시 slotLabel 텍스트) |
 | `contentSlot?` | `ReactNode` | — | 콘텐츠 박스 바로 아래에 통으로 들어가는 커스텀 콘텐츠 (전체 폭) |
 | `mainButtonLabel?` | `string` | `'확인'` | 메인 버튼 |
-| `mainButtonName?` | `ConfirmModalMainButton` | — | 확인 버튼 프리셋 (없으면 type에 따라 자동 결정) |
+| `mainButtonName?` | `SConfirmModalMainButton` | — | 확인 버튼 프리셋 (없으면 type에 따라 자동 결정) |
 | `subButtonLabel?` | `string` | — | 서브(취소) 버튼 |
 
 #### Events
@@ -36,6 +36,22 @@
 | `onCancel` | `() => void` |  |
 | `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) |
 
+## Types
+
+### SConfirmModalType
+
+```ts
+export type SConfirmModalType = 'positive' | 'negative' | 'default';
+```
+
+### SConfirmModalMainButton
+
+```ts
+/** 확인 버튼 프리셋 (sd-confirm-modal ConfirmModalMainButton) */
+export type SConfirmModalMainButton =
+  'primary_md' | 'primary_outline_md' | 'danger_md' | 'danger_outline_md' | 'neutral_outline_md';
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SConfirmModal/SConfirmModal.d.ts

@@ -2,7 +2,7 @@ import { type ReactNode } from 'react';
 import { type STagColor, type STagShape, type STagSize } from '../STag';
 export type SConfirmModalType = 'positive' | 'negative' | 'default';
 /** 확인 버튼 프리셋 (sd-confirm-modal ConfirmModalMainButton) */
-export type ConfirmModalMainButton = 'primary_md' | 'primary_outline_md' | 'danger_md' | 'danger_outline_md' | 'neutral_outline_md';
+export type SConfirmModalMainButton = 'primary_md' | 'primary_outline_md' | 'danger_md' | 'danger_outline_md' | 'neutral_outline_md';
 export interface SConfirmModalProps {
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
@@ -34,7 +34,7 @@ export interface SConfirmModalProps {
     /** 메인 버튼 */
     mainButtonLabel?: string;
     /** 확인 버튼 프리셋 (없으면 type에 따라 자동 결정) */
-    mainButtonName?: ConfirmModalMainButton;
+    mainButtonName?: SConfirmModalMainButton;
     /** 서브(취소) 버튼 */
     subButtonLabel?: string;
     /** 확인 버튼 클릭 (sdOk) */

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

@@ -1 +1 @@
-export { SConfirmModal, type SConfirmModalProps, type SConfirmModalType } from './SConfirmModal';
+export { SConfirmModal, type SConfirmModalMainButton, type SConfirmModalProps, type SConfirmModalType, } from './SConfirmModal';

package/dist/components/SDatePicker/README.md

@@ -2,6 +2,25 @@
 
 > 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
 
+### SDatePickerMonthListbox
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 월 (YYYY-MM) |
+| `anchorYear?` | `number` | — | 연도 리스트가 처음 열릴 때 중앙에 둘 연도. 기본값은 올해 |
+| `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` |  |
+| `onMonthSelect` | `(value: string) => void` | 월 컬럼에서 월을 선택했을 때 호출 |
+
 ### SDatePicker
 
 #### Props
@@ -14,7 +33,9 @@
 | `placeholder?` | `string` | — |  |
 | `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] |
 | `disabled?` | `boolean` | `false` |  |
-| `width?` | `number \| string` | — |  |
+| `clearable?` | `boolean` | `false` | 선택값 지우기 버튼. 값이 있을 때만 나타나고, 누르면 `onValueChange` 로 `null` 이 온다. **필수 입력 필드에는 켜지 않는다** — 지우면 다시 고르기 전까지 폼이 통과하지 못한다. `STimePicker` · `STimeRangePicker` · `SSelect` 의 `clearable` 과 같은 규칙이다. |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
+| `maxWidth?` | `SFieldWidth` | — | 컨트롤 최대 너비 — 폭 등급 · 숫자=px · CSS 길이. 지정하지 않으면 값 길이(`YYYY-MM-DD`)에 맞춘 내장 상한(`size='md'` → `lg`, `'sm'` → `md`)이 걸려, `width="100%"` 를 받아도 행 전체로 늘어나지 않는다. 팝오버처럼 폭이 이미 좁게 정해진 자리에서 그 폭을 그대로 채워야 하면 `width="100%"` 와 함께 `maxWidth="100%"` 를 준다. `0` 은 상한을 아예 걸지 않는다 — 부모보다 넓어지는 것까지 허용해야 할 때만 쓴다. |
 | `name?` | `string` | — |  |
 | `rules?` | `Rule[]` | — |  |
 | `status?` | `SFieldStatus` | — |  |
@@ -36,9 +57,41 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onValueChange` | `(value: string) => void` | 선택 변경 (sdUpdate) |
+| `onValueChange` | `(value: string \| null) => void` | 선택 변경 (sdUpdate). `clearable` 로 지우면 `null` 이 온다 |
 | `onViewChange` | `(view: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
 
+### SDatePickerYearListbox
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 연도 (YYYY) |
+| `anchorYear?` | `number` | — | 리스트가 처음 열릴 때 중앙에 둘 연도. 기본값은 올해 |
+| `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(year: string) => void` |  |
+
+## Types
+
+### SDatePickerMode
+
+```ts
+export type SDatePickerMode = 'date' | 'month' | 'year';
+```
+
+### SDatePickerSize
+
+```ts
+export type SDatePickerSize = SFieldSize;
+```
+
 ## Dependencies
 
 ### Used by
@@ -50,6 +103,7 @@
 
 - [SCalendar](../SCalendar)
 - [SField](../SField)
+- [SGhostButton](../SGhostButton)
 - [SIcon](../SIcon)
 
 ### Graph
@@ -58,6 +112,7 @@
 graph TD;
   SDatePicker --> SCalendar
   SDatePicker --> SField
+  SDatePicker --> SGhostButton
   SDatePicker --> SIcon
   SChipFilter --> SDatePicker
   SKeyValueTable --> SDatePicker

package/dist/components/SDatePicker/SDatePicker.d.ts

@@ -4,13 +4,14 @@ 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 SDatePickerSize = SFieldSize;
 export type SDatePickerMode = 'date' | 'month' | 'year';
 export interface SDatePickerProps {
     /** 선택 값 (date: YYYY-MM-DD, month: YYYY-MM, year: YYYY) */
     value?: string | null;
-    /** 선택 변경 (sdUpdate) */
-    onValueChange?: (value: string) => void;
+    /** 선택 변경 (sdUpdate). `clearable` 로 지우면 `null` 이 온다 */
+    onValueChange?: (value: string | null) => void;
     /** 보이는 연·월 변경 (sdViewChange) */
     onViewChange?: (view: {
         year: number;
@@ -23,7 +24,29 @@ export interface SDatePickerProps {
     /** 선택 가능 범위 [시작, 종료] */
     selectable?: [string, string];
     disabled?: boolean;
-    width?: number | string;
+    /**
+     * 선택값 지우기 버튼. 값이 있을 때만 나타나고, 누르면 `onValueChange` 로 `null` 이 온다.
+     *
+     * **필수 입력 필드에는 켜지 않는다** — 지우면 다시 고르기 전까지 폼이 통과하지 못한다.
+     * `STimePicker` · `STimeRangePicker` · `SSelect` 의 `clearable` 과 같은 규칙이다.
+     */
+    clearable?: boolean;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
+    /**
+     * 컨트롤 최대 너비 — 폭 등급 · 숫자=px · CSS 길이. 지정하지 않으면 값 길이(`YYYY-MM-DD`)에 맞춘
+     * 내장 상한(`size='md'` → `lg`, `'sm'` → `md`)이 걸려, `width="100%"` 를 받아도 행 전체로
+     * 늘어나지 않는다.
+     *
+     * 팝오버처럼 폭이 이미 좁게 정해진 자리에서 그 폭을 그대로 채워야 하면 `width="100%"` 와 함께
+     * `maxWidth="100%"` 를 준다. `0` 은 상한을 아예 걸지 않는다 — 부모보다 넓어지는 것까지 허용해야
+     * 할 때만 쓴다.
+     */
+    maxWidth?: SFieldWidth;
     name?: string;
     rules?: Rule[];
     status?: SFieldStatus;
@@ -41,5 +64,35 @@ export interface SDatePickerProps {
     className?: string;
     style?: CSSProperties;
 }
+export interface SDatePickerYearListboxProps {
+    /** 선택 연도 (YYYY) */
+    value?: string | null;
+    /** 리스트가 처음 열릴 때 중앙에 둘 연도. 기본값은 올해 */
+    anchorYear?: number;
+    /** 선택 가능 범위 [시작, 종료] */
+    selectable?: [string, string];
+    onValueChange?: (year: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/** SDatePickerYearListbox — SDatePicker의 연도 선택 listbox 조각.
+ * 자체 트리거/팝오버 없이 연도 리스트만 필요한 커스텀 조합에 재사용한다. */
+export declare function SDatePickerYearListbox({ value, anchorYear, selectable, onValueChange, className, style, }: SDatePickerYearListboxProps): import("react").JSX.Element;
+export interface SDatePickerMonthListboxProps {
+    /** 선택 월 (YYYY-MM) */
+    value?: string | null;
+    /** 연도 리스트가 처음 열릴 때 중앙에 둘 연도. 기본값은 올해 */
+    anchorYear?: number;
+    /** 선택 가능 범위 [시작, 종료] */
+    selectable?: [string, string];
+    onValueChange?: (value: string) => void;
+    /** 월 컬럼에서 월을 선택했을 때 호출 */
+    onMonthSelect?: (value: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/** SDatePickerMonthListbox — SDatePicker의 월 선택 listbox 조각.
+ * 자체 트리거/팝오버 없이 연도+월 리스트만 필요한 커스텀 조합에 재사용한다. */
+export declare function SDatePickerMonthListbox({ value, anchorYear, selectable, onValueChange, onMonthSelect, className, style, }: SDatePickerMonthListboxProps): import("react").JSX.Element;
 /** SDatePicker — sd-date-picker 포팅. SField + SPopover(SCalendar). */
-export declare function SDatePicker({ value, onValueChange, onViewChange, mode, size, placeholder, selectable, disabled, width, name, rules, status, label, labelWidth, icon, iconColor, labelTooltip, labelTooltipProps, addonLabel, addonAlign, hint, error, errorMessage, className, style, }: SDatePickerProps): import("react").JSX.Element;
+export declare function SDatePicker({ value, onValueChange, onViewChange, mode, size, placeholder, selectable, disabled, clearable, width, maxWidth, name, rules, status, label, labelWidth, icon, iconColor, labelTooltip, labelTooltipProps, addonLabel, addonAlign, hint, error, errorMessage, className, style, }: SDatePickerProps): import("react").JSX.Element;

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

@@ -1 +1 @@
-export { SDatePicker, type SDatePickerMode, type SDatePickerProps, type SDatePickerSize, } from './SDatePicker';
+export { SDatePicker, SDatePickerMonthListbox, SDatePickerYearListbox, type SDatePickerMode, type SDatePickerMonthListboxProps, type SDatePickerProps, type SDatePickerSize, type SDatePickerYearListboxProps, } from './SDatePicker';