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

package/README.md

@@ -11,8 +11,11 @@ Sellmate 디자인 시스템의 React 컴포넌트 라이브러리 (React + Type
 
 ## 설치
 
+> ⚠️ **이 패키지는 현재 베타입니다.** `beta` dist-tag 로만 배포되므로 태그를 붙여 설치해야 합니다.
+> 태그 없이 설치하면 마지막 정식 버전(8.x)이 잡힙니다. 자세한 정책은 [버전 정책](#버전-정책) 참조.
+
 ```bash
-npm install sellmate-design-system-react
+npm install sellmate-design-system-react@beta
 npx sellmate-ds init
 ```
 
@@ -183,6 +186,7 @@ export default [
 | `sellmate/component-group-gap`   | warn      | 같은 컴포넌트를 나열할 때의 그룹 간격 — 배열 방향에 따라 값이 다르다(체크박스 가로 24 / 세로 8)                                                                                                         |
 | `sellmate/table-numeric-align`   | warn      | 수량 컬럼(금액·수량 등)에 `align: 'right'` 누락 — **`--fix` 로 자동 교정**                                                                                                                              |
 | `sellmate/require-locale-number` | warn      | 수량 컬럼의 `toLocaleString()` 누락 — 세 자리 콤마                                                                                                                                                      |
+| `sellmate/field-width-grade`     | warn      | 필드 폭이 `maxLength`(스키마 상한)와 어긋남 — 등급 미지정 · 등급 밖 폭 · 상한 대비 과부족                                                                                                               |
 | `sellmate/no-arbitrary-class`    | **off**   | 토큰이 있는 속성(색·타이포·간격·모서리)의 임의 값 — `text-[14px]`, `bg-[#eee]`. 앱 고유 화면에는 정당한 사용이 많아 기본값은 끕니다                                                                     |
 
 `className` 뿐 아니라 `cn()`/`clsx()` 인자, 템플릿 리터럴, 객체 키 안까지 검사합니다.
@@ -234,6 +238,68 @@ export default [
 'sellmate/table-numeric-align': ['error', { allow: ['rank'] }],
 ```
 
+### 필드 폭 등급 (`field-width-grade`)
+
+필드 너비는 **`maxLength`(= 스키마 상한)로 정합니다.** 상한이 등급 안에 들어오면 그 등급으로 고정하고,
+등급 상한(`xl`)을 넘거나 상한이 아예 없으면 행 전체(`width="100%"` 또는 생략)로 둡니다.
+
+| 등급 | 폭    |                          |
+| ---- | ----- | ------------------------ |
+| `xs` | 80px  | 숫자 필드 전용           |
+| `sm` | 120px |                          |
+| `md` | 160px |                          |
+| `lg` | 240px |                          |
+| `xl` | 480px | 정책상 상한              |
+
+```tsx
+// 상한이 등급 안에 들어온다 → 그 등급으로 고정
+<SInput name="code" label="코드" maxLength={10} width={160} />
+
+// 상한이 xl 로도 안 담긴다 → 행 전체
+<SInput name="desc" label="설명" maxLength={100} width="100%" />
+
+// 숫자 필드의 상한은 maxLength 가 아니라 max 다 (천단위 콤마도 폭을 먹는다)
+<SNumberInput name="qty" label="수량" max={99} width={80} />
+```
+
+대상은 `SInput` · `SNumberInput` · `SBarcodeInput` 입니다. `STextarea` 는 여러 줄로 접혀 상한이 폭을
+정하지 않고, 셀렉트 계열은 상한 개념이 없어 목록 최장값으로 폭을 정하며, 날짜·시간 계열은 컴포넌트가
+자체 상한을 갖습니다.
+
+**상한도 폭도 변수로 넘기면 검사하지 않습니다.** 정적으로 알 수 없는 것을 위반으로 보고하지 않습니다.
+
+```tsx
+<SInput maxLength={LIMIT} width={fieldWidth} />   // 통과
+<SInput maxLength={10} {...rest} />               // 통과 (spread 안에 width 가 있을 수 있다)
+```
+
+#### 글자수 환산
+
+등급이 몇 글자를 담는지는 토큰 값(글꼴 크기 · 좌우 패딩 · 테두리 · 스테퍼)에서 계산합니다.
+한글은 전각이라 영숫자의 약 두 배를 먹으므로 **두 기준 사이에는 아무것도 보고하지 않습니다** —
+영숫자로 채워도 넘칠 때만 "좁다", 한글로 채워도 남을 때만 "넓다" 로 판정합니다.
+
+| 등급 | `SInput` (sm) | `SInput` (md) | `SNumberInput` (sm) | `SNumberInput` (sm, `useButton`) |
+| ---- | ------------- | ------------- | ------------------- | -------------------------------- |
+| `xs` | —             | —             | 영숫자 8            | 영숫자 2                         |
+| `sm` | 영숫자 14 / 한글 7  | 영숫자 11 / 한글 6  | 영숫자 14           | 영숫자 8                         |
+| `md` | 영숫자 20 / 한글 11 | 영숫자 16 / 한글 9  | 영숫자 20           | 영숫자 14                        |
+| `lg` | 영숫자 32 / 한글 17 | 영숫자 26 / 한글 14 | 영숫자 32           | 영숫자 26                        |
+| `xl` | 영숫자 68 / 한글 37 | 영숫자 57 / 한글 31 | 영숫자 68           | 영숫자 62                        |
+
+`SNumberInput` 은 `useButton` 여부로 글자 자리가 크게 갈립니다 — 스테퍼가 없으면 좌우 패딩이
+두 배가 되고(기본값), 있으면 버튼 두 개와 간격이 폭을 먹습니다. 규칙은 JSX 의 `useButton` 을 읽어
+둘을 구분합니다.
+
+값이 팀 기준과 다르면 옵션으로 덮습니다.
+
+```js
+'sellmate/field-width-grade': ['warn', {
+  grades: { sm: 120, md: 160, lg: 240, xl: 480 },
+  charRatio: { narrow: 0.55, wide: 1 },
+}],
+```
+
 ### 더 엄격하게 / 더 느슨하게
 
 `configs.strict` 는 전 규칙을 error 로 올리고, `<ul>` `<ol>` `<li>` `<svg>` `<label>` 까지 검사하며, 간격 유틸리티에 `sd-` 접두를 강제합니다(`requirePrefix`). 디자인 시스템 규칙을 처음부터 전면 적용하는 신규 프로젝트용입니다.
@@ -317,25 +383,52 @@ export default [...sellmate.configs.strict];
 - **단일 라이트 테마** — 다크모드는 지원하지 않습니다.
 - **타입 포함** — 모든 컴포넌트에 TypeScript 타입 정의(`.d.ts`)가 함께 제공됩니다.
 
+## 버전 정책
+
+**현재 베타 단계입니다.** 컴포넌트 API 가 아직 자리를 잡는 중이라 `9.0.0-beta.N` 으로 나가고, `beta` dist-tag 로만 배포합니다.
+
+- 베타 기간에는 breaking 이 또 나와도 `beta.N` 만 올라갑니다. 아직 아무도 `9.0.0` 을 받지 않았으므로 major 를 올릴 이유가 없습니다.
+- 프리릴리스는 `^8` 같은 캐럿 범위에 절대 걸리지 않습니다. 기존 소비 앱이 조용히 깨지지 않습니다.
+- 소비 앱은 `sellmate-design-system-react@beta` 로 명시적으로 받아야 합니다.
+
+### 정식 9.0.0 으로 언제 전환하나
+
+날짜가 아니라 상태로 판단합니다. 셋을 모두 만족할 때 전환합니다.
+
+1. **2주 연속 BREAKING 커밋 0** — 지금 major 를 만드는 건 전부 컴포넌트 API 재설계입니다. 이게 멎은 것이 API 가 자리 잡았다는 유일한 실증입니다.
+2. **소비 앱이 이 패키지만으로 프로덕션 화면을 다 그릴 수 있을 때** — `AGENTS.md` §0-1 인덱스에 없어서 소비 앱이 직접 만든 컴포넌트가 남아 있으면, 그게 나중에 들어오면서 또 API 를 흔듭니다.
+3. **토큰 스킴이 값만 바뀌는 단계일 때** — 토큰 JSON 의 키 구조가 바뀌는 동안은 `theme.css` 재생성이 breaking 을 계속 만듭니다.
+
+전환할 때 할 일은 두 가지입니다. `npm run version:stable -- --release-as 9.0.0` 으로 꼬리를 떼고, **`package.json` 의 `publishConfig.tag` 를 지웁니다**(= `latest`). 둘 중 하나만 하면 `prepublishOnly` 가드가 배포를 막습니다.
+
+정식 전환 후 major 인플레를 막는 실제 레버는 번호 체계가 아니라 **릴리스 묶음**입니다. breaking 을 나올 때마다 즉시 내지 말고 정해진 주기(격주·월 1회)에 모아서 내면 같은 변경량이 major 한 번으로 압축됩니다.
+
 ## 버전 업 / 릴리스
 
 Stencil 쪽 `lerna version` 과 동일하게 **Conventional Commits 기반**으로 버전을 올리고 `CHANGELOG.md` 를 누적합니다. 이 패키지는 lerna 관리 대상이 아니라 전용 스크립트를 씁니다.
 
 ```bash
-# 마지막 릴리스 이후 커밋으로 상승 폭을 자동 추론 → package.json/CHANGELOG 갱신 + 릴리스 커밋
-npm run version
+# 베타 이어가기 — 상승 폭 자동 추론 → package.json/CHANGELOG 갱신 + 릴리스 커밋
+npm run version           # 9.0.0-beta.0 → 9.0.0-beta.1
 
 # 실제로 바꾸지 않고 결과만 미리보기
 npm run version:dry
 
-# 루트에서도 실행 가능
-npm run version:rn        # (design-system 루트)
+# 정식 채널용 (베타 졸업 후에 씁니다)
+npm run version:stable
+npm run version:stable:dry
+
+# 루트에서도 실행 가능 (design-system 루트)
+npm run version:rn
+npm run version:rn:stable
 ```
 
 - 마지막 `chore(release): react-native <ver>` 커밋 이후 `react-native/` 를 건드린 커밋을 모읍니다.
-- `BREAKING CHANGE → major`, `feat → minor`, 그 외(`fix` 등) `→ patch` 로 버전을 올립니다.
-- 주요 옵션: `--bump <major|minor|patch>` · `--release-as <x.y.z>` · `--pre-major`(0.x 유지) · `--tag` · `--no-commit` · `--dry-run` · `--force` (`node scripts/version.mjs --help`).
-- push 는 하지 않습니다. 커밋/태그 확인 후 직접 push 하세요.
+- `BREAKING CHANGE → major`, `feat → minor`, 그 외(`fix` 등) `→ patch` 로 버전을 올립니다. `--prerelease` 를 주면 이 상승 폭은 **정식 버전이 아직 없을 때만** core 에 반영됩니다(8.1.0 → 9.0.0-beta.0). 이미 프리릴리스면 `beta.N` 만 올라갑니다.
+- 현재 버전이 프리릴리스인데 `--prerelease` 도 `--release-as` 도 없으면 스크립트가 막습니다 — 베타를 실수로 정식으로 올리는 사고 방지입니다.
+- **git 태그(`sellmate-design-system-react@<ver>`)는 npm scripts 가 `--tag` 를 기본으로 주므로 자동으로 붙습니다.** 건너뛰려면 `npm run version -- --no-tag`.
+- 주요 옵션: `--bump <major|minor|patch>` · `--release-as <x.y.z>`(프리릴리스 꼬리 허용) · `--prerelease [id]` · `--pre-major`(0.x 유지) · `--tag` / `--no-tag` · `--no-commit` · `--dry-run` · `--force` (`node scripts/version.mjs --help`).
+- push 는 하지 않습니다. 커밋/태그 확인 후 직접 push 하세요 — 태그는 `git push origin <태그명>` 으로 따로 올려야 합니다.
 
 ## 라이선스
 

package/dist/components/SChipFilter/README.md

@@ -0,0 +1,70 @@
+# SChipFilter
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SChipFilter
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields?` | `SChipFilterField[] \| SChipFilterGroup[]` | — | 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에 구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). |
+| `value?` | `SChipFilterValueMap` | — | 필터 값 맵 |
+| `activeKeys?` | `string[]` | — | 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접 넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별 defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 |
+| `label?` | `string` | `'검색 필터'` | 좌측 태그 텍스트 |
+| `showLabel?` | `boolean` | `false` | 좌측 태그(label)·구분선 표시 여부 |
+| `showReset?` | `boolean` | `true` | 검색 초기화 링크 표시 여부 |
+| `disabled?` | `boolean` | `false` | 바 비활성 상태 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: SChipFilterValueMap) => void` | 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 |
+| `onFilterChange` | `(detail: SChipFilterChangeDetail) => void` | 개별 필터 값 변경 |
+| `onSearch` | `(value: SChipFilterValueMap) => void` | 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른 칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom, clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. dirty 체크가 기본 적용되어 있어 — 마지막으로 실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고 닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔 onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상 실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) |
+| `onActiveKeysChange` | `(keys: string[]) => void` | 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다. activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 |
+| `onReset` | `() => void` | "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋된 뒤 호출된다 |
+| `onAddFilter` | `(key: string) => void` | "필터 추가" 목록에서 항목을 골랐을 때 — activeKeys를 직접 제어 중이면 이 콜백에서 (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다. activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `open` | `(key: string) => void` | 특정 필터 편집 팝오버를 엽니다. |
+| `reset` | `() => void` | 모든 필터 값을 초기화합니다. |
+| `validate` | `() => boolean` | fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
+
+## Dependencies
+
+### Depends on
+
+- [SDatePicker](../SDatePicker)
+- [SDateRangePicker](../SDateRangePicker)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+- [SRadio](../SRadio)
+- [SRadioButton](../SRadioButton)
+- [SSelect](../SSelect)
+- [STag](../STag)
+- [STextLink](../STextLink)
+- [STooltip](../STooltip)
+
+### Graph
+
+```mermaid
+graph TD;
+  SChipFilter --> SDatePicker
+  SChipFilter --> SDateRangePicker
+  SChipFilter --> SGhostButton
+  SChipFilter --> SIcon
+  SChipFilter --> SRadio
+  SChipFilter --> SRadioButton
+  SChipFilter --> SSelect
+  SChipFilter --> STag
+  SChipFilter --> STextLink
+  SChipFilter --> STooltip
+  style SChipFilter fill:#f9f,stroke:#333,stroke-width:4px
+```

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

@@ -0,0 +1,167 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type SDateRangeValue } from '../SDateRangePicker';
+export type SChipFilterType = 'single' | 'multi' | 'keyword' | 'date' | 'period' | 'custom';
+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/period 필드의 프리셋 라디오 항목 (오늘/지난 7일/일별/월별/사용자 지정 등) */
+export interface SChipFilterDatePreset {
+    /** 프리셋 식별자 */
+    value: string;
+    /** 라벨 */
+    label: string;
+    /** true면 "사용자 지정" — 선택 시 날짜/기간 피커가 추가로 노출된다. resolve는 무시된다. */
+    custom?: boolean;
+    /** custom이 아닐 때 실제 값을 계산한다. 단일 날짜(string) 또는 기간([start,end]) 모두 가능 */
+    resolve?: () => string | SDateRangeValue;
+}
+/** keyword 필드에서 matchModes 활성 시 사용하는 값 형태 — 입력해 추가한 키워드 목록 */
+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 | SChipFilterPeriodValue | SChipFilterCustomValue | null | undefined;
+export type SChipFilterValueMap = Record<string, SChipFilterValue>;
+export interface SChipFilterField {
+    /** 필터 식별자 */
+    key: string;
+    /** 칩에 표시할 레이블 */
+    label: string;
+    /** 필터 타입 */
+    type: SChipFilterType;
+    /** single/multi/keyword 후보 목록 */
+    options?: SChipFilterOption[];
+    /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
+     *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다 */
+    required?: boolean;
+    /** 고정 필터. true면 activeKeys/defaultActive와 무관하게 항상 노출되고 "필터 추가" 목록에는 나타나지 않는다 */
+    fix?: boolean;
+    /** 초기값 및 clearable 클릭 시 되돌아갈 값. required 여부와 무관하게 적용된다 — 값이 비어 있으면
+     *  마운트(또는 "필터 추가"로 활성화) 시 이 값이 자동으로 채워진다. required인데 지정하지 않으면
+     *  타입별 내장 기본값(single: 첫 번째 옵션, date: 오늘 날짜)을 대신 쓴다 */
+    defaultValue?: SChipFilterValue;
+    /** 경고 테두리 표시 */
+    warning?: boolean;
+    /** 비활성 상태 */
+    disabled?: boolean;
+    /** 처음부터 칩으로 노출할지 여부. false면 "필터 추가" 목록에만 나타나고, 거기서 고르기 전까지는
+     *  필터 바에 보이지 않는다. activeKeys를 직접 제어하는 경우엔 초기 activeKeys 구성에만 참고되고
+     *  이후엔 activeKeys가 우선한다 */
+    defaultActive?: boolean;
+    /** keyword 입력 placeholder */
+    placeholder?: string;
+    /** keyword 필드에 검색조건(포함/일치) 토글 표시 여부 */
+    matchModes?: boolean;
+    /** matchModes 활성 시 "미포함"까지 포함해 3개(포함/일치/미포함)로 노출할지. 기본 false — 기존처럼 2개(포함/일치)만 */
+    excludeMode?: boolean;
+    /** date 선택 가능 범위 */
+    selectable?: [string, string];
+    /** date 프리셋의 "사용자 지정" 기간 선택 시 최대 선택 일수 */
+    maxRange?: number;
+    /** date/period 필드의 프리셋 라디오 목록. date에서 지정하지 않으면 기존처럼 단일 캘린더 트리거로 동작하고,
+     *  period에서 지정하지 않으면 일별·월별·분기별·반기별·연도별·사용자 지정 기본 목록을 쓴다 */
+    presets?: SChipFilterDatePreset[];
+    /** presets 사용 시 UI 형태 — true: 필터 바에 세그먼트 라디오로 인라인 노출(팝오버 없음),
+     *  false(기본): 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
+    radioButton?: boolean;
+    /** type이 'custom'일 때 필터 바에 이 필드 자리에 놓일 노드를 직접 그린다. 칩+팝오버를 거치지 않고
+     *  반환한 노드가 그대로 바에 노출된다 — SSelect를 그대로 놓거나 SInput을 바로 노출하는 식으로
+     *  렌더 방식 자체를 완전히 자유롭게 구성한다. */
+    render?: (ctx: {
+        value: SChipFilterValue;
+        disabled?: boolean;
+        warning?: boolean;
+        onValueChange: (value: SChipFilterValue) => void;
+    }) => ReactNode;
+}
+export interface SChipFilterChangeDetail {
+    key: string;
+    value: SChipFilterValue;
+    values: SChipFilterValueMap;
+}
+/** 필터 그룹 검증 규칙 */
+export type SChipFilterGroupRule = {
+    type: 'requireKey';
+    key: string;
+} | {
+    type: 'requireAll';
+} | {
+    type: 'requireAny';
+    dataGroupName?: string;
+};
+/** 필터를 그룹으로 묶어서 넘길 때의 단위. 그룹이 시작될 때마다 앞에 구분선이 붙는다. */
+export interface SChipFilterGroup {
+    fields: SChipFilterField[];
+    /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
+     *  그룹이 rule을 만족하지 못하면 검색 시도 여부와 무관하게 그 즉시 그룹 중앙에 경고 툴팁이 뜬다.
+     *  지정 안 하면 검증하지 않는다. */
+    rule?: SChipFilterGroupRule;
+    /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
+    tooltipMessage?: string;
+}
+export interface SChipFilterHandle {
+    /** 특정 필터 편집 팝오버를 엽니다. */
+    open: (key: string) => void;
+    /** 모든 필터 값을 초기화합니다. */
+    reset: () => void;
+    /** fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지
+     *  반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로,
+     *  이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) */
+    validate: () => boolean;
+}
+export interface SChipFilterProps {
+    /** 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에
+     *  구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). */
+    fields?: SChipFilterField[] | SChipFilterGroup[];
+    /** 필터 값 맵 */
+    value?: SChipFilterValueMap;
+    /** 전체 값 변경 — 편집 중인 값이 바뀔 때마다(선택할 때마다) 호출된다. 실제 검색 실행은 onSearch를 쓴다 */
+    onValueChange?: (value: SChipFilterValueMap) => void;
+    /** 개별 필터 값 변경 */
+    onFilterChange?: (detail: SChipFilterChangeDetail) => void;
+    /** 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른
+     *  칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom,
+     *  clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. dirty 체크가 기본 적용되어 있어 — 마지막으로
+     *  실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고
+     *  닫는 경우) 호출되지 않는다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔
+     *  onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상
+     *  실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음) */
+    onSearch?: (value: SChipFilterValueMap) => void;
+    /** 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접
+     *  넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별
+     *  defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 */
+    activeKeys?: string[];
+    /** 노출 필터 key 변경(칩 추가·제거) — 비제어 방식에서도 참고용으로 호출된다.
+     *  activeKeys를 직접 제어할 때는 이 값을 그대로 activeKeys에 반영해야 한다 */
+    onActiveKeysChange?: (keys: string[]) => void;
+    /** "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋된 뒤 호출된다 */
+    onReset?: () => void;
+    /** "필터 추가" 목록에서 항목을 골랐을 때 — activeKeys를 직접 제어 중이면 이 콜백에서
+     *  (또는 onActiveKeysChange에서) key를 activeKeys에 추가해줘야 칩이 실제로 나타난다.
+     *  activeKeys를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 */
+    onAddFilter?: (key: string) => void;
+    /** 좌측 태그 텍스트 */
+    label?: string;
+    /** 좌측 태그(label)·구분선 표시 여부 */
+    showLabel?: boolean;
+    /** 검색 초기화 링크 표시 여부 */
+    showReset?: boolean;
+    /** 바 비활성 상태 */
+    disabled?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** SChipFilter — 검색 필터를 칩 바 형태로 구성하는 컴포넌트. */
+export declare const SChipFilter: import("react").ForwardRefExoticComponent<SChipFilterProps & import("react").RefAttributes<SChipFilterHandle>>;

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

@@ -0,0 +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';

package/dist/components/SCircleProgress/README.md

@@ -11,6 +11,7 @@
 | `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` | — |  |
@@ -20,6 +21,7 @@
 
 ### Used by
 
+ - [SImage](../SImage)
  - [SLoadingContainer](../SLoadingContainer)
  - [SLoadingModal](../SLoadingModal)
  - [STable](../STable)
@@ -28,6 +30,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면 퍼센트를 원 아래가 아닌 원 가운데에 표시 */

package/dist/components/SDatePicker/README.md

@@ -2,15 +2,35 @@
 
 > 자동 생성 문서 — `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
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value?` | `string \| null` | — | 선택 날짜 (YYYY-MM-DD) |
+| `value?` | `string \| null` | — | 선택 값 (date: YYYY-MM-DD, month: YYYY-MM, year: YYYY) |
+| `mode?` | `SDatePickerMode` | `'date'` | 선택 모드 |
 | `size?` | `SDatePickerSize` | `'sm'` |  |
-| `placeholder?` | `string` | `'YYYY-MM-DD'` |  |
+| `placeholder?` | `string` | — |  |
 | `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] |
 | `disabled?` | `boolean` | `false` |  |
 | `width?` | `number \| string` | — |  |
@@ -35,13 +55,32 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
+| `onValueChange` | `(value: string) => void` | 선택 변경 (sdUpdate) |
 | `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` |  |
+
 ## Dependencies
 
 ### Used by
 
+ - [SChipFilter](../SChipFilter)
  - [SKeyValueTable](../SKeyValueTable)
 
 ### Depends on
@@ -57,6 +96,7 @@ graph TD;
   SDatePicker --> SCalendar
   SDatePicker --> SField
   SDatePicker --> SIcon
+  SChipFilter --> SDatePicker
   SKeyValueTable --> SDatePicker
   style SDatePicker fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -5,16 +5,19 @@ import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
 export type SDatePickerSize = SFieldSize;
+export type SDatePickerMode = 'date' | 'month' | 'year';
 export interface SDatePickerProps {
-    /** 선택 날짜 (YYYY-MM-DD) */
+    /** 선택 값 (date: YYYY-MM-DD, month: YYYY-MM, year: YYYY) */
     value?: string | null;
     /** 선택 변경 (sdUpdate) */
-    onValueChange?: (date: string) => void;
+    onValueChange?: (value: string) => void;
     /** 보이는 연·월 변경 (sdViewChange) */
     onViewChange?: (view: {
         year: number;
         month: number;
     }) => void;
+    /** 선택 모드 */
+    mode?: SDatePickerMode;
     size?: SDatePickerSize;
     placeholder?: string;
     /** 선택 가능 범위 [시작, 종료] */
@@ -38,5 +41,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, 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, width, 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 SDatePickerProps, type SDatePickerSize } from './SDatePicker';
+export { SDatePicker, SDatePickerMonthListbox, SDatePickerYearListbox, type SDatePickerMode, type SDatePickerMonthListboxProps, type SDatePickerProps, type SDatePickerSize, type SDatePickerYearListboxProps, } from './SDatePicker';

package/dist/components/SDateRangePicker/README.md

@@ -40,10 +40,30 @@
 | `onValueChange` | `(range: SDateRangeValue) => void` | 선택 변경 (sdUpdate) — [start, end] |
 | `onViewChange` | `(view: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
 
+### SRangeCalendar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `SDateRangeValue` | — |  |
+| `selectable?` | `[string, string]` | — |  |
+| `maxRange?` | `number` | — |  |
+| `useTimePicker?` | `boolean` | `false` |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onSelect` | `(r: [string, string]) => void` |  |
+| `onPendingStartChange` | `(start: string \| null) => void` | 시작일만 선택된(종료일 대기) 상태를 상위로 전달 — 트리거에 `start ~` 프리뷰 표시용 |
+| `onViewChange` | `(view: { year: number; month: number }) => void` |  |
+
 ## Dependencies
 
 ### Used by
 
+ - [SChipFilter](../SChipFilter)
  - [SKeyValueTable](../SKeyValueTable)
 
 ### Depends on
@@ -61,6 +81,7 @@ graph TD;
   SDateRangePicker --> SField
   SDateRangePicker --> SGhostButton
   SDateRangePicker --> SIcon
+  SChipFilter --> SDateRangePicker
   SKeyValueTable --> SDateRangePicker
   style SDateRangePicker fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SDateRangePicker/SDateRangePicker.d.ts

@@ -44,5 +44,21 @@ export interface SDateRangePickerProps {
     className?: string;
     style?: CSSProperties;
 }
+export interface SRangeCalendarProps {
+    value: SDateRangeValue;
+    selectable?: [string, string];
+    maxRange?: number;
+    useTimePicker?: boolean;
+    onSelect: (r: [string, string]) => void;
+    /** 시작일만 선택된(종료일 대기) 상태를 상위로 전달 — 트리거에 `start ~` 프리뷰 표시용 */
+    onPendingStartChange?: (start: string | null) => void;
+    onViewChange?: (view: {
+        year: number;
+        month: number;
+    }) => void;
+}
+/** RangeCalendar — SDateRangePicker의 캘린더 부분만 떼어낸 조각. 자체 트리거/팝오버 없이
+ *  캘린더 그리드만 필요한 커스텀 조합(예: 다른 트리거에 팝오버로 얹는 경우)에 재사용한다. */
+export declare function RangeCalendar({ value, selectable, maxRange, useTimePicker, onSelect, onPendingStartChange, onViewChange, }: SRangeCalendarProps): import("react").JSX.Element;
 /** SDateRangePicker — sd-date-range-picker 포팅. SField + SPopover(범위 캘린더). */
 export declare function SDateRangePicker({ value, onValueChange, onViewChange, size, placeholder, selectable, maxRange, useTimePicker, disabled, width, name, rules, status, label, labelWidth, icon, iconColor, labelTooltip, labelTooltipProps, addonLabel, addonAlign, hint, error, errorMessage, className, style, }: SDateRangePickerProps): import("react").JSX.Element;

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

@@ -1 +1 @@
-export { SDateRangePicker, type SDateRangePickerProps, type SDateRangePickerSize, type SDateRangeValue, } from './SDateRangePicker';
+export { RangeCalendar, SDateRangePicker, type SDateRangePickerProps, type SDateRangePickerSize, type SDateRangeValue, type SRangeCalendarProps, } from './SDateRangePicker';