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

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
 ```
 
@@ -317,25 +320,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,69 @@
+# 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)·구분선 표시 여부 |
+| `showAddButton?` | `boolean` | `true` | 필터 추가 버튼 표시 여부 |
+| `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)
+- [STag](../STag)
+- [STextLink](../STextLink)
+- [STooltip](../STooltip)
+
+### Graph
+
+```mermaid
+graph TD;
+  SChipFilter --> SDatePicker
+  SChipFilter --> SDateRangePicker
+  SChipFilter --> SGhostButton
+  SChipFilter --> SIcon
+  SChipFilter --> SRadio
+  SChipFilter --> SRadioButton
+  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,160 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type SDateRangeValue } from '../SDateRangePicker';
+export type SChipFilterType = 'single' | 'multi' | 'keyword' | 'date' | 'custom';
+export type SChipFilterOptionValue = string | number;
+export type SChipFilterMatchMode = 'contains' | 'exact' | 'excludes';
+export interface SChipFilterOption {
+    value: SChipFilterOptionValue;
+    label: string;
+    disabled?: boolean;
+}
+/** date 필드의 프리셋 라디오 항목 (오늘/지난 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;
+}
+/** custom 필드가 자유롭게 담는 값. 형태를 강제하지 않는다 — render에서 직접 정의한 그대로 읽고 쓴다 */
+export type SChipFilterCustomValue = Record<string, unknown>;
+export type SChipFilterValue = SChipFilterOptionValue | SChipFilterOptionValue[] | SDateRangeValue | SChipFilterKeywordValue | 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;
+    /** 초기값 및 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 필드의 프리셋 라디오 목록. 지정하지 않으면 기존처럼 단일 캘린더 트리거로 동작한다 */
+    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;
+    /** 필터 추가 버튼 표시 여부 */
+    showAddButton?: 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/SDatePicker/README.md

@@ -42,6 +42,7 @@
 
 ### Used by
 
+ - [SChipFilter](../SChipFilter)
  - [SKeyValueTable](../SKeyValueTable)
 
 ### Depends on
@@ -57,6 +58,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/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';

package/dist/components/SDraggableItem/README.md

@@ -17,6 +17,7 @@
 | `selected?` | `boolean` | `false` | 선택 상태 여부 |
 | `dragging?` | `boolean` | `false` | 드래그 중인 스타일을 고정해서 표시할지 여부 |
 | `dense?` | `boolean` | `false` | 조밀한 높이 사용 여부 |
+| `size?` | `SDraggableItemSize` | `'sm'` | 타이포그래피·세로 패딩 크기 |
 | `disabled?` | `boolean` | `false` | 비활성 상태 여부 |
 | `dragOverlay?` | `boolean` | `true` | 드래그 시 마우스를 따라가는 overlay 표시 여부 |
 | `dragOverlayOpacity?` | `number` | `0.75` | 드래그 overlay 투명도 |

package/dist/components/SDraggableItem/SDraggableItem.d.ts

@@ -7,6 +7,7 @@ export interface SDraggableItemRenderState {
 export type SDraggableItemRenderProp = (state: SDraggableItemRenderState) => ReactNode;
 export type SDraggableItemSlot = ReactNode | SDraggableItemRenderProp;
 export type SDraggableItemSupportingTextPosition = 'right' | 'bottom';
+export type SDraggableItemSize = 'sm' | 'md';
 export interface SDraggableItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {
     /** 드래그 아이템 제목 */
     title: SDraggableItemSlot;
@@ -26,6 +27,8 @@ export interface SDraggableItemProps extends Omit<HTMLAttributes<HTMLDivElement>
     dragging?: boolean;
     /** 조밀한 높이 사용 여부 */
     dense?: boolean;
+    /** 타이포그래피·세로 패딩 크기 */
+    size?: SDraggableItemSize;
     /** 비활성 상태 여부 */
     disabled?: boolean;
     /** 드래그 시 마우스를 따라가는 overlay 표시 여부 */

package/dist/components/SDrawer/README.md

@@ -11,10 +11,10 @@
 | `open?` | `boolean` | — | 표시 여부 |
 | `persistent?` | `boolean` | `true` | backdrop·ESC로 닫히지 않고 흔들림 효과를 준다. **기본값 true** — Drawer는 내용을 작성·구성하는 곳이라 임의 닫힘을 막는 것이 기본이다. 닫기 경로는 X 버튼과 footer 버튼뿐이다. false로 주면 backdrop·ESC 닫기가 열린다. |
 | `title?` | `string` | `''` | 접근성 제목 및 헤더 제목 |
-| `width?` | `number \| string` | `572` | Drawer 너비. 기본값은 Figma drawer 기준 572px이다. |
-| `resizable?` | `boolean` | `false` | true면 왼쪽 테두리를 드래그해 너비를 조절할 수 있다. |
-| `minWidth?` | `number \| string` | — | 리사이즈 가능한 최소 너비(px, %, vw, vh) |
-| `maxWidth?` | `number \| string` | — | 리사이즈 가능한 최대 너비(px, %, vw, vh) |
+| `width?` | `number \| string` | `572` | Drawer 너비. 기본값은 Figma drawer 기준 572px이다. 창이 이보다 좁으면 창 폭까지만 넓어진다 — 드로어가 화면 밖으로 나가지 않는다. `resizable` 로 조절한 폭은 이 값이 바뀔 때 되돌아간다 — 앱이 폭을 저장해 두었다가 다시 열 때 넘겨주면 그 폭으로 열린다. |
+| `resizable?` | `boolean` | `false` | 왼쪽 테두리를 끌어 너비를 조절할 수 있게 한다. 조절선은 패널 왼쪽 경계 전체이며 평소엔 보이지 않다가 hover·포커스·조절 중에만 드러난다(SSplitter·SGnb 와 같은 선). 포커스를 받아 방향키(Shift 는 크게)·Home·End 로도 조절된다. |
+| `minWidth?` | `number \| string` | — | 리사이즈 가능한 최소 너비(px, %, vw, vh). % 는 viewport 기준이며, 창 폭보다 클 수 없다 |
+| `maxWidth?` | `number \| string` | — | 리사이즈 가능한 최대 너비(px, %, vw, vh). % 는 viewport 기준이며, 주지 않으면 창 폭이 상한이다 |
 | `footerLeft?` | `ReactNode` | — | footer 좌측 슬롯 |
 | `button?` | `SDrawerButton` | — | 우측 기본 액션 버튼 |
 | `children?` | `ReactNode` | — |  |
@@ -27,6 +27,7 @@
 |-------|------|-------------|
 | `onOpenChange` | `(open: boolean) => void` | 표시 상태 변경 |
 | `onClose` | `() => void` | 닫기(X) 버튼 클릭 |
+| `onWidthChange` | `(width: number) => void` | 너비가 확정될 때(드래그를 놓거나 방향키 조작). 드래그하는 동안에는 오지 않는다 |
 
 ## Dependencies
 

package/dist/components/SDrawer/SDrawer.d.ts

@@ -16,14 +16,25 @@ export interface SDrawerProps {
     persistent?: boolean;
     /** 접근성 제목 및 헤더 제목 */
     title?: string;
-    /** Drawer 너비. 기본값은 Figma drawer 기준 572px이다. */
+    /**
+     * Drawer 너비. 기본값은 Figma drawer 기준 572px이다.
+     * 창이 이보다 좁으면 창 폭까지만 넓어진다 — 드로어가 화면 밖으로 나가지 않는다.
+     * `resizable` 로 조절한 폭은 이 값이 바뀔 때 되돌아간다 — 앱이 폭을 저장해 두었다가
+     * 다시 열 때 넘겨주면 그 폭으로 열린다.
+     */
     width?: number | string;
-    /** true면 왼쪽 테두리를 드래그해 너비를 조절할 수 있다. */
+    /**
+     * 왼쪽 테두리를 끌어 너비를 조절할 수 있게 한다. 조절선은 패널 왼쪽 경계 전체이며
+     * 평소엔 보이지 않다가 hover·포커스·조절 중에만 드러난다(SSplitter·SGnb 와 같은 선).
+     * 포커스를 받아 방향키(Shift 는 크게)·Home·End 로도 조절된다.
+     */
     resizable?: boolean;
-    /** 리사이즈 가능한 최소 너비(px, %, vw, vh) */
+    /** 리사이즈 가능한 최소 너비(px, %, vw, vh). % 는 viewport 기준이며, 창 폭보다 클 수 없다 */
     minWidth?: number | string;
-    /** 리사이즈 가능한 최대 너비(px, %, vw, vh) */
+    /** 리사이즈 가능한 최대 너비(px, %, vw, vh). % 는 viewport 기준이며, 주지 않으면 창 폭이 상한이다 */
     maxWidth?: number | string;
+    /** 너비가 확정될 때(드래그를 놓거나 방향키 조작). 드래그하는 동안에는 오지 않는다 */
+    onWidthChange?: (width: number) => void;
     /** footer 좌측 슬롯 */
     footerLeft?: ReactNode;
     /** 우측 기본 액션 버튼 */
@@ -39,4 +50,4 @@ export interface SDrawerProps {
  * 모달을 추가로 열면 새 모달이 Drawer 위에 쌓이고, Drawer 내부 floating은 전용 portal
  * container를 통해 Drawer의 backdrop 위에 표시된다.
  */
-export declare function SDrawer({ open, onOpenChange, onClose, persistent, title, width, resizable, minWidth, maxWidth, footerLeft, button, children, className, style, }: SDrawerProps): import("react").JSX.Element;
+export declare function SDrawer({ open, onOpenChange, onClose, persistent, title, width, resizable, minWidth, maxWidth, onWidthChange, footerLeft, button, children, className, style, }: SDrawerProps): import("react").JSX.Element;

package/dist/components/SExpansionItem/README.md

@@ -22,6 +22,7 @@
 | `interaction?` | `SExpansionItemInteraction` | — | hover/selected 상태에서 적용할 인터랙션 preset |
 | `accentStripe?` | `boolean` | `false` | 아이템 왼쪽 accent stripe 표시 여부 |
 | `dense?` | `boolean` | `false` |  |
+| `size?` | `SExpansionItemSize` | `'sm'` | 타이포그래피 크기 |
 | `disabled?` | `boolean` | `false` |  |
 
 #### Events

package/dist/components/SExpansionItem/SExpansionItem.d.ts

@@ -7,6 +7,7 @@ export interface SExpansionItemRenderState {
 export type SExpansionItemRenderProp = (state: SExpansionItemRenderState) => ReactNode;
 export type SExpansionItemInteraction = 'chevron';
 export type SExpansionItemSupportingTextPosition = 'right' | 'bottom';
+export type SExpansionItemSize = 'sm' | 'md';
 export interface SExpansionItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onToggle' | 'title'> {
     title: ReactNode;
     /** 제목을 보조하는 텍스트 */
@@ -31,6 +32,8 @@ export interface SExpansionItemProps extends Omit<HTMLAttributes<HTMLDivElement>
     /** 아이템 왼쪽 accent stripe 표시 여부 */
     accentStripe?: boolean;
     dense?: boolean;
+    /** 타이포그래피 크기 */
+    size?: SExpansionItemSize;
     disabled?: boolean;
     onToggle?: (expanded: boolean, event: MouseEvent<HTMLButtonElement>) => void;
 }

package/dist/components/SGhostButton/README.md

@@ -34,6 +34,7 @@
  - [SBarcodeInput](../SBarcodeInput)
  - [SCalendar](../SCalendar)
  - [SChip](../SChip)
+ - [SChipFilter](../SChipFilter)
  - [SDateRangePicker](../SDateRangePicker)
  - [SFilePicker](../SFilePicker)
  - [SGnb](../SGnb)
@@ -41,6 +42,7 @@
  - [SInput](../SInput)
  - [SModalContainer](../SModalContainer)
  - [SOverlayHeader](../SOverlayHeader)
+ - [SPage](../SPage)
  - [SPopover](../SPopover)
  - [SSelect](../SSelect)
  - [STimePicker](../STimePicker)
@@ -63,6 +65,7 @@ graph TD;
   SBarcodeInput --> SGhostButton
   SCalendar --> SGhostButton
   SChip --> SGhostButton
+  SChipFilter --> SGhostButton
   SDateRangePicker --> SGhostButton
   SFilePicker --> SGhostButton
   SGnb --> SGhostButton
@@ -70,6 +73,7 @@ graph TD;
   SInput --> SGhostButton
   SModalContainer --> SGhostButton
   SOverlayHeader --> SGhostButton
+  SPage --> SGhostButton
   SPopover --> SGhostButton
   SSelect --> SGhostButton
   STimePicker --> SGhostButton

package/dist/components/SGnb/README.md

@@ -17,8 +17,11 @@
 | `folded?` | `boolean` | — | 접힘(레일) 상태. 미지정 시 SLayout 의 folded 를 따른다. |
 | `logo?` | `ReactNode` | — | 상단바 로고 영역 (slot). header="full" 이면 폭이 140px 로 고정된다. |
 | `topContent?` | `ReactNode` | — | 상단바 로고 오른쪽 슬롯 (검색·액션 등). 로고와 16px 띄고 남는 폭을 모두 차지하므로 안에서 자유롭게 정렬한다. 상단바가 전폭인 header="full" 에서만 렌더된다 (fix 는 상단바가 좁은 GNB 컬럼 안이라 놓을 자리가 없다). |
+| `railTop?` | `ReactNode` | — | 레일 상단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고 이 슬롯은 레일 상단(상단바 바로 아래)에 붙어 고정된다. useRail 일 때만 렌더된다. |
 | `railFooter?` | `ReactNode` | — | 레일 하단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고 이 슬롯은 레일 하단에 붙어 고정된다. useRail 일 때만 렌더된다. |
+| `menuTop?` | `ReactNode` | — | 메뉴 상단 고정 슬롯. 메뉴 아이템이 많아 넘치면 메뉴 목록(ul)만 스크롤되고 이 슬롯은 메뉴 상단에 붙어 고정된다. 메뉴가 렌더될 때만(showMenu) 나타난다. |
 | `menuFooter?` | `ReactNode` | — | 메뉴 하단 고정 슬롯. 메뉴 아이템이 많아 넘치면 메뉴 목록(ul)만 스크롤되고 이 슬롯은 메뉴 하단에 붙어 고정된다. 메뉴가 렌더될 때만(showMenu) 나타난다. |
+| `foldedTop?` | `ReactNode` | — | 접힘(fix 레일) 상단 고정 슬롯. 접으면 본문이 빠져나가며 rail/menu top 도 사라지므로, 48px 폴드 레일 상단(상단바 바로 아래)에 붙는 별도 슬롯이다. header="fix" 로 접혔을 때만 나타난다. |
 | `foldedFooter?` | `ReactNode` | — | 접힘(fix 레일) 하단 고정 슬롯. 접으면 본문이 빠져나가며 rail/menu footer 도 사라지므로, 48px 폴드 레일 바닥에 붙는 별도 슬롯이다. header="fix" 로 접혔을 때만 나타난다. |
 | `resizable?` | `boolean` | `false` | 메뉴 폭을 드래그로 조절할 수 있게 한다. 레일 폭은 고정이고 **메뉴 컬럼만** 늘고 준다. 조절선은 GNB 컬럼의 오른쪽 경계 전체다 — fix 는 상단바 높이까지, full 은 상단바가 전폭이라 본문 높이까지. 접혀 있거나 깔 메뉴가 없으면(레일 리프가 활성) 조절선이 나오지 않는다. |
 | `menuWidth?` | `number` | — | 메뉴 폭(px). 주면 controlled — onMenuWidthChange 로 직접 갱신해야 움직인다 |

package/dist/components/SGnb/SGnb.d.ts

@@ -38,16 +38,31 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
      * (fix 는 상단바가 좁은 GNB 컬럼 안이라 놓을 자리가 없다).
      */
     topContent?: ReactNode;
+    /**
+     * 레일 상단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고
+     * 이 슬롯은 레일 상단(상단바 바로 아래)에 붙어 고정된다. useRail 일 때만 렌더된다.
+     */
+    railTop?: ReactNode;
     /**
      * 레일 하단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고
      * 이 슬롯은 레일 하단에 붙어 고정된다. useRail 일 때만 렌더된다.
      */
     railFooter?: ReactNode;
+    /**
+     * 메뉴 상단 고정 슬롯. 메뉴 아이템이 많아 넘치면 메뉴 목록(ul)만 스크롤되고
+     * 이 슬롯은 메뉴 상단에 붙어 고정된다. 메뉴가 렌더될 때만(showMenu) 나타난다.
+     */
+    menuTop?: ReactNode;
     /**
      * 메뉴 하단 고정 슬롯. 메뉴 아이템이 많아 넘치면 메뉴 목록(ul)만 스크롤되고
      * 이 슬롯은 메뉴 하단에 붙어 고정된다. 메뉴가 렌더될 때만(showMenu) 나타난다.
      */
     menuFooter?: ReactNode;
+    /**
+     * 접힘(fix 레일) 상단 고정 슬롯. 접으면 본문이 빠져나가며 rail/menu top 도 사라지므로,
+     * 48px 폴드 레일 상단(상단바 바로 아래)에 붙는 별도 슬롯이다. header="fix" 로 접혔을 때만 나타난다.
+     */
+    foldedTop?: ReactNode;
     /**
      * 접힘(fix 레일) 하단 고정 슬롯. 접으면 본문이 빠져나가며 rail/menu footer 도 사라지므로,
      * 48px 폴드 레일 바닥에 붙는 별도 슬롯이다. header="fix" 로 접혔을 때만 나타난다.

package/dist/components/SGuide/README.md

@@ -13,7 +13,7 @@
 | `message?` | `SGuideMessage` | `''` | 팝업 메시지 (배열이면 리스트, 중첩 배열이면 depth 표현) |
 | `url?` | `string` | `''` | notion 타입 클릭 시 이동 URL |
 | `popupTitle?` | `string` | `''` | 팝업 제목 (없으면 type 기본값) |
-| `popupWidth?` | `number` | — | 팝업 너비 (px, 기본 426) |
+| `popupWidth?` | `number` | — | 팝업 너비 (px, 기본 426). 창보다 넓게 줘도 창 폭까지만 벌어진다. |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 

package/dist/components/SGuide/SGuide.d.ts

@@ -13,7 +13,7 @@ export interface SGuideProps {
     url?: string;
     /** 팝업 제목 (없으면 type 기본값) */
     popupTitle?: string;
-    /** 팝업 너비 (px, 기본 426) */
+    /** 팝업 너비 (px, 기본 426). 창보다 넓게 줘도 창 폭까지만 벌어진다. */
     popupWidth?: number;
     className?: string;
     style?: CSSProperties;

package/dist/components/SIcon/README.md

@@ -23,6 +23,7 @@
  - [SButton](../SButton)
  - [SCallout](../SCallout)
  - [SCheckbox](../SCheckbox)
+ - [SChipFilter](../SChipFilter)
  - [SChipInput](../SChipInput)
  - [SConfirmModal](../SConfirmModal)
  - [SDatePicker](../SDatePicker)
@@ -59,6 +60,7 @@ graph TD;
   SButton --> SIcon
   SCallout --> SIcon
   SCheckbox --> SIcon
+  SChipFilter --> SIcon
   SChipInput --> SIcon
   SConfirmModal --> SIcon
   SDatePicker --> SIcon

package/dist/components/SIcon/icons.gen.d.ts

@@ -83,6 +83,7 @@ export declare const ICONS: {
     readonly settingOutline: (p: IconRenderProps) => import("react").JSX.Element;
     readonly shield: (p: IconRenderProps) => import("react").JSX.Element;
     readonly sidebar: (p: IconRenderProps) => import("react").JSX.Element;
+    readonly star: (p: IconRenderProps) => import("react").JSX.Element;
     readonly store: (p: IconRenderProps) => import("react").JSX.Element;
     readonly synchronize: (p: IconRenderProps) => import("react").JSX.Element;
     readonly thumbsDown: (p: IconRenderProps) => import("react").JSX.Element;