sellmate-design-system-react 9.0.0-beta.8 → 9.0.0-beta.80

package/dist/components/SChatMessage/SChatMessage.d.ts

@@ -0,0 +1,123 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+/** 메시지가 오는 쪽 — 받은 메시지(incoming)는 왼쪽, 보낸 메시지(outgoing)는 오른쪽에 선다. */
+export declare const CHAT_MESSAGE_DIRECTIONS: readonly ["incoming", "outgoing"];
+export type SChatMessageDirection = (typeof CHAT_MESSAGE_DIRECTIONS)[number];
+/**
+ * 말풍선의 종류.
+ * - `default` 사람이 직접 쓴 메시지
+ * - `template` 미리 등록된 서식으로 보내진 메시지
+ * - `admin` 관리자·시스템이 보낸 메시지
+ *
+ * **보낸 메시지에서만 면이 갈린다.** 셋 다 사업자 쪽이 보내는 것이라 받은 메시지에는
+ * 뜻이 없고, 받은 메시지는 무엇으로 보냈든 같은 면으로 선다.
+ */
+export declare const CHAT_MESSAGE_VARIANTS: readonly ["default", "template", "admin"];
+export type SChatMessageVariant = (typeof CHAT_MESSAGE_VARIANTS)[number];
+/** 상대가 내 메시지를 읽었는지. 시각 왼쪽에 붙는다. */
+export declare const CHAT_MESSAGE_READ_STATUSES: readonly ["read", "unread"];
+export type SChatMessageReadStatus = (typeof CHAT_MESSAGE_READ_STATUSES)[number];
+export interface SChatMessageProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * 받은 메시지(왼쪽)인지 보낸 메시지(오른쪽)인지.
+     *
+     * **아바타와 이름 유무도 여기서 갈린다** — 받은 메시지에만 아바타와 `sender` 가 선다.
+     * 보낸 메시지는 내가 보냈다는 것이 자리로 이미 드러나 얼굴도 이름도 필요 없다.
+     */
+    direction: SChatMessageDirection;
+    /**
+     * 말풍선 위에 붙는 보낸 사람 이름. 없으면 자리째 빠진다.
+     *
+     * **받은 메시지에만 쓰인다** — 보낸 메시지에는 넘겨도 그리지 않는다(`direction` 참고).
+     * 앱이 데이터를 한 번만 매핑해 방향과 무관하게 넘길 수 있도록 막지 않고 무시한다.
+     */
+    sender?: ReactNode;
+    /**
+     * 말풍선 아래에 붙는 시각. 표기는 앱이 정해 문자열로 넘긴다 — 대화 화면의 시각은
+     * `오후 5:52` 처럼 읽는 표기를 쓰므로 카드가 서식을 강제하지 않는다 (AGENTS.md §1-4 예외).
+     */
+    time?: ReactNode;
+    /**
+     * 상대가 읽었는지. 시각 왼쪽에 `읽음`·`안 읽음` 으로 붙고, 주지 않으면 표시하지 않는다.
+     *
+     * **내가 보낸 메시지에만 붙인다** — 받은 메시지에 읽음 표시를 다는 것은 뜻이 없다.
+     */
+    readStatus?: SChatMessageReadStatus;
+    /**
+     * 아바타 이미지 경로. 없으면 사람 아이콘 자리표시가 선다.
+     *
+     * **받은 메시지에만 쓰인다** — 보낸 메시지에는 아바타가 서지 않는다(`direction` 참고).
+     */
+    avatarSrc?: string;
+    /** 아바타 대체 텍스트 */
+    avatarAlt?: string;
+    /**
+     * 같은 사람이 이어서 말한 묶음인지. 켜면 **아바타와 `sender` 를 그리지 않는다** —
+     * 말풍선이 위 묶음과 같은 선에서 시작해 한 사람의 말로 이어 읽힌다.
+     *
+     * 받은 메시지에서는 아바타 자리를 비워 둔 채 남긴다 — 안 남기면 말풍선이 44px 왼쪽으로 밀려
+     * 위 묶음과 어긋난다. 보낸 메시지는 아바타가 없으므로 이름만 숨긴다.
+     *
+     * `time`·`readStatus` 는 그대로 나온다. 시간이 벌어져 묶음을 나눴어도 얼굴은 한 번만 보이면
+     * 되고 시각은 묶음마다 필요하기 때문이다.
+     *
+     * **얼마나 벌어져야 묶음을 나눌지는 앱이 정한다** — 30분이든 하루든 대화의 성격에 달렸으므로
+     * 컴포넌트는 기준을 갖지 않고 스위치만 연다.
+     */
+    continued?: boolean;
+    /**
+     * 말풍선 종류. `template` 은 미리 등록된 서식으로, `admin` 은 관리자·시스템이 보낸
+     * 메시지임을 각각 다른 면으로 드러낸다. 면 색은 토큰이 정하므로 여기서 색을 정하지 않는다.
+     *
+     * **보낸 메시지(`direction="outgoing"`)에만 쓰인다** — 받은 메시지에는 넘겨도 그리지 않는다.
+     * 셋 다 사업자 쪽이 보내는 것이라 받은 쪽에는 뜻이 없다. 앱이 메시지를 한 번만 매핑해
+     * 방향과 무관하게 넘길 수 있도록 막지 않고 무시한다.
+     */
+    variant?: SChatMessageVariant;
+    /**
+     * 시각 아래에 붙는 동작 슬롯. 없으면 그 줄이 통째로 빠진다.
+     *
+     * 「상담원 연결」처럼 **이 메시지에 이어서 할 수 있는 동작**이 오는 자리다. 무엇을 놓을지는
+     * 앱이 정하고, 메시지는 줄로 세우고 방향에 맞춰 정렬하는 것까지만 한다.
+     *
+     * 시각과 같은 선에서 시작한다 — 말풍선 끝에서 한 칸 안이다.
+     */
+    actions?: ReactNode;
+    /**
+     * 말풍선 목록. **한 항목이 말풍선 하나**가 되어 위에서 아래로 쌓인다.
+     *
+     * 한 사람이 연달아 말하면 아바타·이름·시각은 한 번만 서고 말풍선만 늘어난다 —
+     * 그 묶음이 이 컴포넌트 한 개다. 말풍선 안에는 글뿐 아니라 버튼 같은 요소도 올 수 있다.
+     */
+    messages?: ReactNode[];
+    /**
+     * 말풍선 아래에 붙는 파일 목록. **한 항목이 칸 하나**가 되어 위에서 아래로 쌓인다.
+     *
+     * `SChatFile` 을 넣는 자리다 — 말풍선과 달리 면으로 감싸지 않고 넘긴 것을 그대로 세운다.
+     * 파일 칸은 제 면·선·라운드를 이미 갖고 있어 한 번 더 감싸면 칸이 두 겹으로 보인다.
+     *
+     * **`messages` 대신 여기로 넘긴다.** `messages` 로 넘기면 말풍선 면에 감싸여 그렇게 된다.
+     *
+     * 아바타·이름·시각·읽음 표시는 글 메시지와 똑같이 이 컴포넌트가 그린다 — 파일을 보낸 것도
+     * 대화의 한 줄이므로 행 규칙을 따로 갖지 않는다.
+     */
+    attachments?: ReactNode[];
+}
+/**
+ * SChatMessage — 대화 화면에서 한 사람이 한 번에 말한 묶음.
+ *
+ * 아바타·보낸 사람(받은 메시지만)·말풍선·시각을 한 줄로 세운다. **말풍선은 `messages` 항목 수만큼 쌓이고**
+ * 아바타·이름·시각은 그 묶음에 한 번만 붙는다 — 연달아 말한 여러 줄이 한 덩어리로 읽힌다.
+ *
+ * 시각 아래에 동작을 붙여야 하면 `actions` 슬롯에 넣는다 — 시각과 같은 선에서 시작해 방향에
+ * 맞춰 정렬된다.
+ *
+ * 시간이 벌어져 묶음을 나눠야 하는데 말한 사람은 같을 때는 `continued` 를 켠다 — 아바타 자리는
+ * 유지한 채 얼굴과 이름만 빠져, 두 묶음이 한 사람의 말로 이어 읽힌다.
+ `direction` 하나로 받은 메시지(왼쪽)와
+ * 보낸 메시지(오른쪽)가 갈리고, 그에 따라 정렬과 말풍선 색이 함께 뒤집힌다.
+ *
+ * **말풍선 폭은 내용이 정한다** — 짧은 메시지는 글자만큼만 차지하고, 길면 접힌다. 다만 반대편
+ * 끝까지 가지는 않는다: 받은 메시지는 오른쪽, 보낸 메시지는 왼쪽에 여백이 남아 어느 쪽이 말한
+ * 것인지가 폭으로도 읽힌다. 대화 폭을 더 좁히려면 이 컴포넌트가 아니라 담는 쪽을 좁힌다.
+ */
+export declare const SChatMessage: import("react").ForwardRefExoticComponent<SChatMessageProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1 @@
+export { SChatMessage, CHAT_MESSAGE_DIRECTIONS, CHAT_MESSAGE_READ_STATUSES, CHAT_MESSAGE_VARIANTS, type SChatMessageDirection, type SChatMessageReadStatus, type SChatMessageVariant, type SChatMessageProps, } from './SChatMessage';

package/dist/components/SChatSystemMessage/README.md

@@ -0,0 +1,12 @@
+# SChatSystemMessage
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SChatSystemMessage
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message?` | `string[]` | — | 안내 문구. **항목 수만큼 알약이 쌓인다** — 서로 다른 시점에 일어난 사실은 한 알약에 몰아넣지 않고 항목을 나눈다 (`SChatMessage` 의 `messages` 와 같은 규칙). 각 항목은 **인라인 HTML 문자열을 받는다.** `<b>` `<strong>` `<i>` `<em>` `<br>` `<span>` `<a>` 만 살아남고 나머지 태그·속성과 `javascript:` 같은 위험한 스킴은 `sanitizeInlineHtml` 이 제거한다. 그래도 **서버·사용자가 만든 문자열을 그대로 넘기지 않는다** — 살균은 마지막 방어선이지 입력 검증의 대체가 아니다. ```tsx <SChatSystemMessage message={['<b>김상담</b> 상담사가 배정되었습니다.']} /> ``` |
+

package/dist/components/SChatSystemMessage/SChatSystemMessage.d.ts

@@ -0,0 +1,18 @@
+import { type HTMLAttributes } from 'react';
+export interface SChatSystemMessageProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * 안내 문구. **항목 수만큼 알약이 쌓인다** — 서로 다른 시점에 일어난 사실은
+     * 한 알약에 몰아넣지 않고 항목을 나눈다 (`SChatMessage` 의 `messages` 와 같은 규칙).
+     *
+     * 각 항목은 **인라인 HTML 문자열을 받는다.** `<b>` `<strong>` `<i>` `<em>` `<br>`
+     * `<span>` `<a>` 만 살아남고 나머지 태그·속성과 `javascript:` 같은 위험한 스킴은
+     * `sanitizeInlineHtml` 이 제거한다. 그래도 **서버·사용자가 만든 문자열을 그대로 넘기지 않는다** —
+     * 살균은 마지막 방어선이지 입력 검증의 대체가 아니다.
+     *
+     * ```tsx
+     * <SChatSystemMessage message={['<b>김상담</b> 상담사가 배정되었습니다.']} />
+     * ```
+     */
+    message?: string[];
+}
+export declare const SChatSystemMessage: import("react").ForwardRefExoticComponent<SChatSystemMessageProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1 @@
+export { SChatSystemMessage, type SChatSystemMessageProps } from './SChatSystemMessage';

package/dist/components/SCheckbox/README.md

@@ -22,6 +22,14 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: boolean \| unknown[]) => void` | 값 변경 (sdUpdate) |
 
+## Types
+
+### SCheckboxValue
+
+```ts
+export type SCheckboxValue = boolean | unknown[] | null;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SChip/README.md

@@ -8,6 +8,7 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `color?` | `SChipColor` | — | 색상. 주지 않으면 기본 회색 칩이다. 색은 기본 상태에만 입힌다 — error·편집 중·disabled 는 상태 토큰이 우선한다. 색상은 컴포넌트 토큰 `--cmp-chip-chip-<color>-{bg,content,border}` 를 참조한다. |
 | `name?` | `string` | — | 폼 연동용 name |
 | `value?` | `string` | `''` | 칩 텍스트 값 |
 | `error?` | `boolean` | — | 에러 상태 |
@@ -35,6 +36,30 @@
 | `focus` | `() => void` | 편집 input에 포커스합니다. |
 | `getNativeElement` | `() => HTMLElement \| null` | 네이티브 편집 엘리먼트를 반환합니다. |
 
+## Types
+
+### SChipColor
+
+```ts
+export type SChipColor = (typeof CHIP_COLORS)[number];
+```
+
+### CHIP_COLORS
+
+```ts
+export const CHIP_COLORS = [
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'blue',
+  'darkblue',
+  'indigo',
+  'purple',
+  'grey',
+] as const;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SChip/SChip.d.ts

@@ -1,6 +1,14 @@
 import { type CSSProperties } from 'react';
 import { type Rule } from '../../lib/form';
+export declare const CHIP_COLORS: readonly ["red", "orange", "yellow", "green", "blue", "darkblue", "indigo", "purple", "grey"];
+export type SChipColor = (typeof CHIP_COLORS)[number];
 export interface SChipProps {
+    /**
+     * 색상. 주지 않으면 기본 회색 칩이다.
+     * 색은 기본 상태에만 입힌다 — error·편집 중·disabled 는 상태 토큰이 우선한다.
+     * 색상은 컴포넌트 토큰 `--cmp-chip-chip-<color>-{bg,content,border}` 를 참조한다.
+     */
+    color?: SChipColor;
     /** 폼 연동용 name */
     name?: string;
     /** 칩 텍스트 값 */

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

@@ -1 +1 @@
-export { SChip, type SChipHandle, type SChipProps } from './SChip';
+export { SChip, CHIP_COLORS, type SChipColor, type SChipHandle, type SChipProps } from './SChip';

package/dist/components/SChipFilter/README.md

@@ -8,11 +8,9 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `fields?` | `SChipFilterField[] \| SChipFilterGroup[]` | — | 필터 정의 목록. 그룹으로 묶으려면 SChipFilterGroup[]을 넘긴다 — 그룹이 시작될 때마다 앞에 구분선이 자동으로 붙는다(showLabel·인접 그룹·인라인 date 필터와 중첩되지 않도록 처리됨). |
+| `fields?` | `SChipFilterGroup[]` | — | 필터 정의 목록. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]`. 그룹은 rule로 함께 검증하거나 divider로 갈라 놓을 때 나눈다. |
 | `value?` | `SChipFilterValueMap` | — | 필터 값 맵 |
-| `activeKeys?` | `string[]` | — | 노출 필터 key 목록. 지정하면 제어 컴포넌트로 동작 — "필터 추가"로 고른 필드를 이 배열에 직접 넣어줘야 칩이 나타난다(onActiveKeysChange에서 받은 keys로 갱신). 지정하지 않으면 필드별 defaultActive 값을 기준으로 컴포넌트가 내부 상태로 관리하는 비제어 방식으로 동작한다 |
-| `label?` | `string` | `'검색 필터'` | 좌측 태그 텍스트 |
-| `showLabel?` | `boolean` | `false` | 좌측 태그(label)·구분선 표시 여부 |
+| `label?` | `string` | — | 좌측 태그 텍스트. 지정하면 태그와 그 뒤 구분선이 함께 노출되고, 지정하지 않으면(undefined) 둘 다 생략된다 |
 | `showReset?` | `boolean` | `true` | 검색 초기화 링크 표시 여부 |
 | `disabled?` | `boolean` | `false` | 바 비활성 상태 |
 | `className?` | `string` | — |  |
@@ -24,18 +22,377 @@
 |-------|------|-------------|
 | `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를 넘기지 않았다면(비제어) 별도 처리 없이도 컴포넌트가 알아서 칩을 노출한다 |
+| `onSearch` | `(value: SChipFilterValueMap) => void` | 실제 검색을 실행할 시점 — 편집 팝오버의 "검색" 버튼을 누르거나 팝오버가 닫힐 때(바깥 클릭·Esc·다른 칩으로 전환 포함) 그 시점의 전체 값 맵과 함께 호출된다. 팝오버가 없는 필드(인라인 date 프리셋·custom, clearable ×, 검색 초기화)는 값이 바뀌는 즉시 호출된다. keyword 필터에서 Enter 로 키워드를 추가할 때도 그 즉시 호출된다 — 팝오버는 열린 채라 키워드를 이어서 더 넣을 수 있고, 넣을 때마다 조회가 갱신된다. keyword 입력창에 Enter 없이 텍스트를 남긴 채 팝오버를 닫으면 그 텍스트도 키워드로 확정한 뒤 호출된다(input: 'csv'면 콤마로 쪼개는 규칙도 그대로 적용) — 사용자가 검색어를 넣고 "검색"을 누른 조작이 입력 확정 여부 때문에 사라지지 않게 한다. dirty 체크가 기본 적용되어 있어 — 마지막으로 실제 검색이 실행된 값 맵과 비교해 하나라도 달라진 게 없으면(예: 팝오버를 열었다 아무것도 안 바꾸고 닫는 경우) 호출되지 않는다. 단 마운트 후 첫 호출은 비교할 기준이 없어 값이 처음 그대로여도 나간다 — 마운트 시 자동 조회하지 않는 화면(다이얼로그 등)에서 사용자의 첫 "검색"이 막히지 않게 하기 위함이다. fields를 그룹으로 넘겼다면 rule을 만족하지 못한 그룹이 있는 동안엔 onSearch가 호출되지 않는다 — 해당 그룹의 경고 툴팁은 이 시점과 무관하게 값이 비어 있는 동안 항상 실시간으로 떠 있다(별도로 validate()를 호출할 필요 없음). required 필드가 비어 있는 동안에도 마찬가지로 호출되지 않는다 — 정상 설정(내장 기본값 또는 defaultValue)이라면 원래 비워지지 않지만, defaultValue 없는 select-multi·keyword·custom에 required만 준 오설정에서는 "검색 초기화"·clearable이 값을 null로 비울 수 있어 이때의 안전장치다 |
+| `onReset` | `() => void` | "검색 초기화" 클릭 — 모든 필드가 기본값(또는 null)으로 리셋되고 "필터 추가"로 꺼낸 칩이 바에서 빠진 뒤 호출된다 |
+| `onAddFilter` | `(key: string) => void` | "필터 추가" 목록에서 항목을 골랐을 때 호출된다(알림). 칩 노출은 컴포넌트가 알아서 하므로 이 콜백에서 따로 해줄 일은 없다 |
 
 #### Methods (ref)
 
 | Method | Type | Description |
 |--------|------|-------------|
 | `open` | `(key: string) => void` | 특정 필터 편집 팝오버를 엽니다. |
-| `reset` | `() => void` | 모든 필터 값을 초기화합니다. |
-| `validate` | `() => boolean` | fields를 그룹(SChipFilterGroup[])으로 넘겼을 때, 현재 값 기준으로 각 그룹의 rule을 만족하는지 반환합니다. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
+| `reset` | `() => void` | 바를 처음 상태로 되돌립니다 — 모든 필터 값이 기본값(또는 null)으로 돌아가고, "필터 추가"로 꺼내 놓은 칩도 함께 빠져 fixed·required 필드만 남습니다. 열려 있던 편집 팝오버는 닫힙니다 |
+| `validate` | `() => boolean` | 현재 값 기준으로 각 그룹의 rule을 만족하는지, 그리고 required 필드가 모두 비어 있지 않은지 반환합니다. rule을 준 그룹이 없고 required 필드도 모두 값이 있으면 항상 true. 경고 툴팁은 이 호출과 무관하게 rule 위반 상태인 동안 항상 실시간으로 떠 있으므로, 이 메서드는 그 상태를 그대로 읽어오는 용도다(예: 검색 버튼을 눌러도 되는지 사전 확인) |
+
+## Types
+
+### SChipFilterGroup
+
+```ts
+/** fields를 이루는 단위. 묶을 것이 없어도 한 그룹으로 감싸 넘긴다 — `[{ fields: [...] }]` */
+export interface SChipFilterGroup {
+  fields: SChipFilterField[];
+  /** 지정하면 이 규칙으로 그룹을 검증한다. values가 바뀔 때마다 즉시 재평가되는 실시간 검증이라 —
+   *  그룹이 rule을 만족하지 못하면 검색 시도 여부와 무관하게 그 즉시 그룹 중앙에 경고 툴팁이 뜬다.
+   *  지정 안 하면 검증하지 않는다. */
+  rule?: SChipFilterGroupRule;
+  /** rule을 만족하지 않을 때 그룹 중앙에 띄울 툴팁 메시지. 지정 안 하면 rule 종류에 따른 기본 문구를 쓴다 */
+  tooltipMessage?: string;
+  /** 이 그룹 앞에 구분선을 넣을지. 검증(rule)과 구분선은 별개라 — 묶어서 검증만 하고 싶으면
+   *  주지 않는다. 첫 그룹에는 앞에 가를 것이 없으므로 무시된다(label을 지정했다면 그 구분선이
+   *  이미 있다) */
+  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는 select 계열·keyword, presets·maxRange·radioButton은
+ *  datepicker-range·datepicker-statistics, render는 custom 에만 있다 */
+export type SChipFilterField =
+  | SChipFilterSelectField
+  | SChipFilterSelectMultiField
+  | SChipFilterSelectDepthField
+  | SChipFilterSelectMultiDepthField
+  | SChipFilterDatePickerDayField
+  | SChipFilterDatePickerRangeField
+  | SChipFilterDatePickerStatisticsField
+  | SChipFilterKeywordField
+  | 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;
+```
+
+### SChipFilterSelectField
+
+```ts
+/** 후보 하나를 고른다 */
+export interface SChipFilterSelectField extends SChipFilterOptionsField {
+  type: 'select';
+}
+```
+
+### SChipFilterSelectMultiField
+
+```ts
+/** 후보 여럿을 고른다 */
+export interface SChipFilterSelectMultiField extends SChipFilterOptionsField {
+  type: 'select-multi';
+}
+```
+
+### SChipFilterSelectDepthField
+
+```ts
+/** 계층 목록에서 후보 하나를 고른다. `children` 을 가진 항목은 라벨 전용 헤더라 고를 수 없다 —
+ *  값으로 올라오는 것은 리프뿐이다. 계층이 없다면 select 를 쓴다 */
+export interface SChipFilterSelectDepthField extends SChipFilterOptionsField {
+  type: 'select-depth';
+}
+```
+
+### SChipFilterSelectMultiDepthField
+
+```ts
+/** 계층 목록에서 후보 여럿을 고른다. `children` 을 가진 항목은 체크박스를 달고 그 아래 리프를
+ *  한 번에 토글한다(일부만 골랐으면 부분 선택으로 표시) — 값에는 리프만 담긴다 */
+export interface SChipFilterSelectMultiDepthField extends SChipFilterOptionsField {
+  type: 'select-multi-depth';
+}
+```
+
+### SChipFilterDatePickerDayField
+
+```ts
+/** 날짜 하나를 고른다 — 캘린더 트리거 하나만 놓인다. 프리셋으로 고르게 하거나 시작~종료를
+ *  받아야 하면 datepicker-range 다 */
+export interface SChipFilterDatePickerDayField extends SChipFilterFieldBase {
+  type: 'datepicker-day';
+  /** 캘린더 트리거의 placeholder */
+  placeholder?: string;
+  /** 선택 가능 범위 */
+  selectable?: [string, string];
+}
+```
+
+### SChipFilterDatePickerRangeField
+
+```ts
+/** 기간(시작~종료)을 고른다. presets를 주면 프리셋 라디오 목록으로 고르고,
+ *  주지 않으면 기간 피커 하나만 놓인다 */
+export interface SChipFilterDatePickerRangeField extends SChipFilterPresetsField {
+  type: 'datepicker-range';
+  /** presets를 필터 바에 세그먼트 라디오로 펼쳐 놓는다(팝오버 없음).
+   *  기본 false — 칩 클릭 시 팝오버 안에 세로 라디오 목록(+사용자 지정 선택 시 기간 피커) */
+  radioButton?: boolean;
+}
+```
+
+### SChipFilterDatePickerStatisticsField
+
+```ts
+/** 집계 단위(일·월·분기·반기·연)와 그 단위의 값을 함께 고른다 */
+export interface SChipFilterDatePickerStatisticsField extends SChipFilterPresetsField {
+  type: 'datepicker-statistics';
+}
+```
+
+### 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;
+}
+```
+
+### 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
+/** datepicker-statistics 필드 값 — 선택 단위(unit)와 그 단위의 입력값(value)을 함께 보관한다 */
+export interface SChipFilterPeriodValue {
+  unit: SChipFilterPeriodUnit;
+  value?: string | number | SDateRangeValue | null;
+}
+```
+
+### SChipFilterCustomValue
+
+```ts
+/** custom 필드가 자유롭게 담는 값. 형태를 강제하지 않는다 — render에서 직접 정의한 그대로 읽고 쓴다 */
+export type SChipFilterCustomValue = Record<string, unknown>;
+```
+
+### SChipFilterOptionsField
+
+```ts
+/** 후보 목록에서 고르는 필터 — select·select-multi·select-depth·select-multi-depth·keyword */
+export interface SChipFilterOptionsField extends SChipFilterFieldBase {
+  /** 고를 수 있는 후보 목록. select-depth·select-multi-depth 는 `children` 으로 계층을 만든다.
+   *
+   *  **`fixed`·`required` 인 select 계열에서 고를 수 있는 후보가 하나뿐이면 그 값이
+   *  자동으로 선택된다** — 사용자가 고르지 않아도 `onValueChange` 로 값이 올라온다
+   *  (select 는 그 값, select-multi 는 그 값 하나짜리 배열). 옵션이 API 응답이라 늦게 도착해도
+   *  도착한 시점에 채워진다. 사용자가 그 값을 지우면 다시 채우지 않는다 —
+   *  다만 "검색 초기화"는 되돌려 놓는다(다른 기본값과 같은 규칙).
+   *  후보가 하나인데 비활성(`disabled`)이면 고를 수 없는 값이므로 채우지 않는다.
+   *
+   *  뺄 수 있는 필터(= `fixed`·`required` 가 아닌 필드)는 후보가 하나여도 채우지 않는다 —
+   *  처음에 바에 없는 필터라 보이지도 지울 수도 없는 조건이 검색에 걸리기 때문이다.
+   *  후보가 하나뿐인 필터를 반드시 걸어야 한다면 `fixed` 나 `required` 로 준다 */
+  options?: SChipFilterOption[];
+}
+```
+
+### SChipFilterFieldBase
+
+```ts
+/** 타입과 무관하게 모든 필터가 갖는 속성 */
+export interface SChipFilterFieldBase {
+  /** 필터 식별자 */
+  key: string;
+  /** 칩에 표시할 레이블 */
+  label: string;
+  /** 필수 필터 표시. true면 값이 비어 있을 때 기본값(defaultValue 또는 타입별 내장 기본값)이
+   *  자동으로 채워지고, clearable은 현재 값이 기본값과 같을 땐 숨겨지며 클릭 시 기본값으로 되돌아간다.
+   *  값이 채워졌다가 다시 비면(예: value를 제어하는 부모가 onReset에서 자기 상태를 비우는 경우)
+   *  기본값이 한 번 더 채워진다 — required 필드가 빈 채로 남으면 onSearch가 막히기 때문이다.
+   *  단 그 값을 부모가 value로 받아 주지 않으면 반복해서 채우지는 않는다 */
+  required?: boolean;
+  /** 고정 필터. true면 항상 노출되고 "필터 추가" 목록에는 나타나지 않으며 칩을 제거할 수 없다.
+   *  required도 같은 효과를 낸다. 나머지 필드는 "필터 추가"에서 골랐거나 value에 값이 들어
+   *  있는 동안 노출된다 — 값으로 떠 있던 칩은 값이 비면 함께 빠지고, "필터 추가"로 꺼낸 칩은
+   *  값이 없어도 세션 동안 자리를 지킨다 */
+  fixed?: boolean;
+  /** 초기값 및 clearable 클릭 시 되돌아갈 값.
+   *
+   *  **`fixed` 또는 `required` 필드에서만 쓴다.** 그 외 필드에 지정하면 무시하고 콘솔에 알린다 —
+   *  뺄 수 있는 필터는 처음에 바에 없는데, 값 맵에는 기본값이 채워져 **보이지도 지울 수도 없는
+   *  조건이 검색에 걸린다.** 칩을 지워 값을 비워도 "검색 초기화"가 그 값을 되돌려 놓아 필터가
+   *  조용히 되살아난다. 처음부터 값이 정해져 있어야 하는 필터라면 그것이 `fixed`·`required` 다.
+   *
+   *  required인데 지정하지 않으면 타입별 내장 기본값(select: 첫 번째 옵션,
+   *  datepicker-day·datepicker-range: 오늘 날짜)을 대신 쓴다. `fixed`·`required` 인
+   *  select·select-multi 는 후보가 하나뿐일 때 그 값이 기본값이 된다(options 참고) —
+   *  defaultValue 를 함께 주면 그쪽이 이긴다. 인라인(radioButton) datepicker-range
+   *  필드는 팝오버 없이 바에 바로 노출되어 빈 상태로 둘 수 없으므로, 이 규칙과 무관하게 언제나
+   *  오늘이 채워진다 */
+  defaultValue?: SChipFilterValue;
+  /** 이 필터만 비활성. 바에 남아 있되 팝오버가 열리지 않고 clearable도 눌리지 않는다.
+   *  바 전체를 잠그려면 SChipFilterProps.disabled를 쓴다 — 둘은 OR로 합쳐진다 */
+  disabled?: boolean;
+}
+```
+
+### SChipFilterPresetsField
+
+```ts
+/** 프리셋으로 기간을 고르는 필터 — 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;
+}
+```
+
+### SChipFilterKeywordInput
+
+```ts
+/** keyword 필드의 입력 방식 — 무엇을 키워드 하나의 끝으로 볼지 */
+export type SChipFilterKeywordInput = 'tag' | 'csv';
+```
+
+### 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;
+  /** 하위 옵션. children 을 가진 항목은 **고를 수 없는 그룹 헤더**이고, 값으로 올라오는 것은
+   *  언제나 리프(children 없는 항목)의 value 뿐이다. 단일 타입에서 헤더는 라벨만, 다중 타입에서는
+   *  체크박스를 달고 그 아래 전체를 한 번에 토글한다.
+   *
+   *  **계층을 담은 필드는 `select-depth`·`select-multi-depth` 로 선언한다.** 목록은 타입 이름이
+   *  아니라 children 유무를 보고 그리므로 `select`·`select-multi` 에 줘도 계층으로 그려지지만,
+   *  그러면 그 필드가 계층이라는 사실이 코드 어디에도 남지 않는다 */
+  children?: SChipFilterOption[];
+}
+```
+
+### SChipFilterDatePreset
+
+```ts
+/** datepicker-range·datepicker-statistics 필드의 프리셋 라디오 항목 (오늘/지난 7일/일별/월별/사용자 지정 등) */
+export interface SChipFilterDatePreset {
+  /** 프리셋 식별자 */
+  value: string;
+  /** 라벨 */
+  label: string;
+  /** true면 "사용자 지정" — 선택 시 날짜/기간 피커가 추가로 노출된다. resolve는 무시된다. */
+  custom?: boolean;
+  /** custom이 아닐 때 실제 값을 계산한다. 단일 날짜(string) 또는 기간([start,end]) 모두 가능 —
+   *  datepicker-range 에서는 'd' 를 그 하루짜리 기간 ['d', 'd'] 와 같은 값으로 본다 */
+  resolve?: () => string | SDateRangeValue;
+}
+```
 
 ## Dependencies
 
@@ -43,11 +400,10 @@
 
 - [SDatePicker](../SDatePicker)
 - [SDateRangePicker](../SDateRangePicker)
-- [SGhostButton](../SGhostButton)
 - [SIcon](../SIcon)
 - [SRadio](../SRadio)
 - [SRadioButton](../SRadioButton)
-- [SSelect](../SSelect)
+- [SSearchInput](../SSearchInput)
 - [STag](../STag)
 - [STextLink](../STextLink)
 - [STooltip](../STooltip)
@@ -58,11 +414,10 @@
 graph TD;
   SChipFilter --> SDatePicker
   SChipFilter --> SDateRangePicker
-  SChipFilter --> SGhostButton
   SChipFilter --> SIcon
   SChipFilter --> SRadio
   SChipFilter --> SRadioButton
-  SChipFilter --> SSelect
+  SChipFilter --> SSearchInput
   SChipFilter --> STag
   SChipFilter --> STextLink
   SChipFilter --> STooltip