@reopt-ai/opt-ui 1.4.1

package/dist/docs/02-components/03-shells.md

@@ -0,0 +1,1361 @@
+---
+title: "Shell Components"
+description: "75 Shell layer components — props, examples, keyboard shortcuts."
+version: "1.4.1"
+generated: true
+---
+
+# Shell Components (75)
+
+## Navigation & Layout
+
+| Component             | Description                                                                                                           | Key Exports             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| AppMenubar            | 데스크톱 스타일 메뉴바. 체크박스, 라디오 메뉴 항목 지원.                                                              | `AppMenubar`            |
+| MegaMenu              | 메가 메뉴. Popover + CSS grid 멀티컬럼 + 카테고리 헤딩 + footer 슬롯.                                                 | `MegaMenu`              |
+| SidebarNav            | Composite 기반 사이드바 네비게이션. pathname 자동 동기화.                                                             | `SidebarNav`            |
+| Sidebar               | 접기/펼치기를 지원하는 compound 사이드바. Header/Content/Footer 구조 + Group/Item으로 네비게이션 구성. Ctrl+[ 단축키. | `Sidebar`, `useSidebar` |
+| AppShell              | Header + Sidebar + Content + Footer 4영역 페이지 레이아웃 템플릿. Sidebar 컴포넌트와 조합.                            | `AppShell`              |
+| ContentTabs           | 탭 콘텐츠 패널. Tabs primitive 래퍼.                                                                                  | `ContentTabs`           |
+| VerticalTabs          | 세로 탭 레이아웃. 좌측 탭 리스트 + 우측 패널 구성입니다.                                                              | `VerticalTabs`          |
+| FaqAccordion          | FAQ 질문/답변 아코디언. Composite + Disclosure 조합.                                                                  | `FaqAccordion`          |
+| CommandPalette        | Cmd+K 스타일 커맨드 팔레트. Dialog + Combobox + match-sorter 퍼지 검색.                                               | `CommandPalette`        |
+| CommandPaletteTrigger | CommandPalette + Cmd+K 키보드 단축키 자동 바인딩.                                                                     | `CommandPaletteTrigger` |
+| ProjectSwitcher       | 프로젝트 검색 전환기. Combobox + match-sorter 퍼지 검색 지원.                                                         | `ProjectSwitcher`       |
+| EditorToolbar         | 리치 텍스트 에디터 스타일 툴바. Toolbar + Tooltip 조합.                                                               | `EditorToolbar`         |
+| FloatingActionBar     | 플로팅 액션 바. 선택된 항목에 대한 일괄 작업 버튼을 하단에 표시합니다.                                                | `FloatingActionBar`     |
+| TemplatePicker        | 템플릿 선택기. 카테고리별 그리드와 검색을 제공하며 featured/tags 표시를 지원합니다.                                   | `TemplatePicker`        |
+| ThemeSwitcher         | 테마 프리셋 선택기. 프리셋과 light/dark/system 모드 전환.                                                             | `ThemeSwitcher`         |
+
+### AppMenubar
+
+> 데스크톱 스타일 메뉴바. 체크박스, 라디오 메뉴 항목 지원.
+
+**Import:** `import { AppMenubar } from "@reopt-ai/opt-ui"`
+**Dependencies:** menu (core), kbd (core)
+
+| Prop    | Type        | Required | Default | Description                                         |
+| ------- | ----------- | -------- | ------- | --------------------------------------------------- |
+| `menus` | `MenuDef[]` | Yes      |         | 메뉴 정의 배열. { id, label, items: MenuItemDef[] } |
+
+### MegaMenu
+
+> 메가 메뉴. Popover + CSS grid 멀티컬럼 + 카테고리 헤딩 + footer 슬롯.
+
+**Import:** `import { MegaMenu } from "@reopt-ai/opt-ui"`
+**Dependencies:** popover (core)
+
+| Prop           | Type                | Required | Default | Description        |
+| -------------- | ------------------- | -------- | ------- | ------------------ |
+| `menus`        | `MegaMenuSection[]` | Yes      |         | 메뉴 섹션 배열     |
+| `columns`      | `number`            |          | 3       | 그리드 컬럼 수     |
+| `footer`       | `ReactNode`         |          |         | 하단 footer 슬롯   |
+| `triggerLabel` | `string`            |          | "Menu"  | 트리거 버튼 텍스트 |
+| `className`    | `string`            |          |         | 커스텀 CSS 클래스  |
+
+### SidebarNav
+
+> Composite 기반 사이드바 네비게이션. pathname 자동 동기화.
+
+**Import:** `import { SidebarNav } from "@reopt-ai/opt-ui"`
+
+| Prop    | Type           | Required | Default | Description                                                     |
+| ------- | -------------- | -------- | ------- | --------------------------------------------------------------- |
+| `items` | `NavItemDef[]` | Yes      |         | 네비게이션 항목. { id, label, href, separator?, sectionLabel? } |
+
+### Sidebar
+
+> 접기/펼치기를 지원하는 compound 사이드바. Header/Content/Footer 구조 + Group/Item으로 네비게이션 구성. Ctrl+[ 단축키.
+
+**Import:** `import { Sidebar } from "@reopt-ai/opt-ui"`
+**Dependencies:** sidebar-nav (shells)
+
+**Sidebar:**
+
+| Prop                | Type                           | Required | Default    | Description                                               |
+| ------------------- | ------------------------------ | -------- | ---------- | --------------------------------------------------------- |
+| `children`          | `ReactNode`                    | Yes      |            | Sidebar.Header, Sidebar.Content, Sidebar.Footer 자식 요소 |
+| `collapsible`       | `boolean`                      |          | false      | 접기/펼치기 토글 지원                                     |
+| `defaultCollapsed`  | `boolean`                      |          | false      | 초기 접힘 상태                                            |
+| `collapsed`         | `boolean`                      |          |            | 제어 모드: 접힘 상태                                      |
+| `onCollapsedChange` | `(collapsed: boolean) => void` |          |            | 제어 모드: 접힘 상태 변경 핸들러                          |
+| `width`             | `number`                       |          | 280        | 펼침 상태 너비 (px)                                       |
+| `collapsedWidth`    | `number`                       |          | 56         | 접힘 상태 너비 (px)                                       |
+| `side`              | `"left" \| "right"`            |          | "left"     | 사이드바 위치                                             |
+| `label`             | `string`                       |          | "사이드바" | aside aria-label                                          |
+| `className`         | `string`                       |          |            | 커스텀 CSS 클래스                                         |
+
+**Sidebar.Group:**
+
+| Prop        | Type        | Required | Default | Description                        |
+| ----------- | ----------- | -------- | ------- | ---------------------------------- |
+| `children`  | `ReactNode` | Yes      |         | Sidebar.Item 요소들                |
+| `label`     | `string`    |          |         | 그룹 레이블 (접힌 상태에서 숨겨짐) |
+| `className` | `string`    |          |         | 커스텀 CSS 클래스                  |
+
+**Sidebar.Item:**
+
+| Prop        | Type         | Required | Default | Description                                                   |
+| ----------- | ------------ | -------- | ------- | ------------------------------------------------------------- |
+| `children`  | `ReactNode`  | Yes      |         | 항목 레이블 텍스트                                            |
+| `icon`      | `ReactNode`  |          |         | 아이콘 (접힌 상태에서도 표시)                                 |
+| `active`    | `boolean`    |          | false   | 활성 상태 (aria-current=page)                                 |
+| `onClick`   | `() => void` |          |         | 클릭 핸들러                                                   |
+| `href`      | `string`     |          |         | 링크 URL — 설정 시 <a> 태그로 렌더링                          |
+| `tooltip`   | `string`     |          |         | 접힌 상태에서 Tooltip 표시 (미지정 시 children 텍스트)        |
+| `badge`     | `ReactNode`  |          |         | 우측 배지 (숫자/텍스트). 접힌 상태에서 아이콘 위 dot으로 축소 |
+| `className` | `string`     |          |         | 커스텀 CSS 클래스                                             |
+
+### AppShell
+
+> Header + Sidebar + Content + Footer 4영역 페이지 레이아웃 템플릿. Sidebar 컴포넌트와 조합.
+
+**Import:** `import { AppShell } from "@reopt-ai/opt-ui"`
+**Dependencies:** sidebar (shells), page-header (core)
+
+| Prop        | Type        | Required | Default | Description                                                                    |
+| ----------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------ |
+| `children`  | `ReactNode` | Yes      |         | AppShell.Header, AppShell.Sidebar, AppShell.Content, AppShell.Footer 자식 요소 |
+| `className` | `string`    |          |         | 커스텀 CSS 클래스                                                              |
+
+**Examples:**
+
+_앱 레이아웃:_
+
+```tsx
+import { AppShell } from "@reopt-ai/opt-ui";
+
+<AppShell>
+  <AppShell.Header>헤더 영역</AppShell.Header>
+  <AppShell.Sidebar>사이드바 영역</AppShell.Sidebar>
+  <AppShell.Content>메인 콘텐츠</AppShell.Content>
+</AppShell>;
+```
+
+### ContentTabs
+
+> 탭 콘텐츠 패널. Tabs primitive 래퍼.
+
+**Import:** `import { ContentTabs } from "@reopt-ai/opt-ui"`
+**Dependencies:** tabs (core)
+
+| Prop           | Type       | Required | Default | Description                          |
+| -------------- | ---------- | -------- | ------- | ------------------------------------ |
+| `tabs`         | `TabDef[]` | Yes      |         | 탭 정의 배열. { id, label, content } |
+| `defaultTabId` | `string`   |          |         | 초기 선택 탭 ID. 미지정 시 첫 탭     |
+
+### VerticalTabs
+
+> 세로 탭 레이아웃. 좌측 탭 리스트 + 우측 패널 구성입니다.
+
+**Import:** `import { VerticalTabs } from "@reopt-ai/opt-ui"`
+**Dependencies:** tabs (core)
+
+| Prop           | Type       | Required | Default | Description       |
+| -------------- | ---------- | -------- | ------- | ----------------- |
+| `tabs`         | `TabDef[]` | Yes      |         | 탭 정의 배열      |
+| `defaultTabId` | `string`   |          |         | 기본 선택 탭 ID   |
+| `className`    | `string`   |          |         | 커스텀 CSS 클래스 |
+
+### FaqAccordion
+
+> FAQ 질문/답변 아코디언. Composite + Disclosure 조합.
+
+**Import:** `import { FaqAccordion } from "@reopt-ai/opt-ui"`
+**Dependencies:** disclosure (core)
+
+| Prop    | Type        | Required | Default | Description                             |
+| ------- | ----------- | -------- | ------- | --------------------------------------- |
+| `items` | `FaqItem[]` | Yes      |         | FAQ 항목 배열. { id, question, answer } |
+
+### CommandPalette
+
+> Cmd+K 스타일 커맨드 팔레트. Dialog + Combobox + match-sorter 퍼지 검색.
+
+**Import:** `import { CommandPalette } from "@reopt-ai/opt-ui"`
+**Dependencies:** dialog (core), combobox (core), kbd (core)
+
+| Prop            | Type                                         | Required | Default | Description                                           |
+| --------------- | -------------------------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `commands`      | `Omit<Command, "action">[]`                  | Yes      |         | 커맨드 목록. { id, label, group, shortcut? }          |
+| `open`          | `boolean`                                    | Yes      |         | 열림 상태                                             |
+| `onOpenChange`  | `(open: boolean) => void`                    | Yes      |         | 상태 변경 핸들러                                      |
+| `onSelect`      | `(command: Omit<Command, 'action'>) => void` |          |         | 커맨드 선택 핸들러                                    |
+| `inline`        | `boolean`                                    |          | false   | true일 때 풀스크린 Dialog 대신 인라인 팝업으로 렌더링 |
+| `labels`        | `CommandPaletteLabels`                       |          |         | title/description/input/list/empty/escape 문구        |
+| `footer`        | `ReactNode`                                  |          |         | 명령 목록 아래에 표시할 footer slot                   |
+| `empty`         | `ReactNode`                                  |          |         | 결과가 없을 때 표시할 empty slot                      |
+| `inputTrailing` | `ReactNode`                                  |          |         | 검색 입력 우측 보조 콘텐츠                            |
+
+### CommandPaletteTrigger
+
+> CommandPalette + Cmd+K 키보드 단축키 자동 바인딩.
+
+**Import:** `import { CommandPaletteTrigger } from "@reopt-ai/opt-ui"`
+**Dependencies:** command-palette (shells)
+
+| Prop       | Type                                         | Required | Default | Description                                        |
+| ---------- | -------------------------------------------- | -------- | ------- | -------------------------------------------------- |
+| `commands` | `Omit<Command, "action">[]`                  | Yes      |         | 커맨드 목록                                        |
+| `onSelect` | `(command: Omit<Command, 'action'>) => void` |          |         | 커맨드 선택 핸들러                                 |
+| `labels`   | `CommandPaletteTriggerLabels`                |          |         | 내부 CommandPalette에 전달할 title/input/list 문구 |
+
+### ProjectSwitcher
+
+> 프로젝트 검색 전환기. Combobox + match-sorter 퍼지 검색 지원.
+
+**Import:** `import { ProjectSwitcher } from "@reopt-ai/opt-ui"`
+**Dependencies:** combobox (core)
+
+| Prop          | Type                   | Required | Default            | Description                                             |
+| ------------- | ---------------------- | -------- | ------------------ | ------------------------------------------------------- |
+| `projects`    | `ProjectDef[]`         | Yes      |                    | 프로젝트 목록. { id, name, framework, status, domain? } |
+| `value`       | `string`               |          |                    | 제어 모드: 현재 선택된 프로젝트 ID                      |
+| `onChange`    | `(id: string) => void` |          |                    | 프로젝트 선택 핸들러                                    |
+| `placeholder` | `string`               |          | "프로젝트 검색..." | 검색 입력 플레이스홀더                                  |
+
+### EditorToolbar
+
+> 리치 텍스트 에디터 스타일 툴바. Toolbar + Tooltip 조합.
+
+**Import:** `import { EditorToolbar } from "@reopt-ai/opt-ui"`
+**Dependencies:** toolbar (core)
+
+| Prop            | Type                   | Required | Default | Description                                |
+| --------------- | ---------------------- | -------- | ------- | ------------------------------------------ |
+| `buttons`       | `ToolbarButtonDef[]`   | Yes      |         | 버튼 정의. { id, label, icon, separator? } |
+| `onAction`      | `(id: string) => void` |          |         | 버튼 클릭 핸들러                           |
+| `activeButtons` | `string[]`             |          | []      | 활성 상태 버튼 ID 배열                     |
+
+### FloatingActionBar
+
+> 플로팅 액션 바. 선택된 항목에 대한 일괄 작업 버튼을 하단에 표시합니다.
+
+**Import:** `import { FloatingActionBar } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core)
+
+### TemplatePicker
+
+> 템플릿 선택기. 카테고리별 그리드와 검색을 제공하며 featured/tags 표시를 지원합니다.
+
+**Import:** `import { TemplatePicker } from "@reopt-ai/opt-ui"`
+
+| Prop         | Type                           | Required | Default | Description                                                                 |
+| ------------ | ------------------------------ | -------- | ------- | --------------------------------------------------------------------------- |
+| `templates`  | `TemplateDef[]`                | Yes      |         | 템플릿 배열. { id, name, description?, icon?, category?, featured?, tags? } |
+| `selected`   | `string`                       |          |         | 현재 선택된 템플릿 ID                                                       |
+| `onSelect`   | `(templateId: string) => void` | Yes      |         | 템플릿 선택 핸들러                                                          |
+| `showSearch` | `boolean`                      |          | false   | 검색 입력 표시 여부                                                         |
+
+### ThemeSwitcher
+
+> 테마 프리셋 선택기. 프리셋과 light/dark/system 모드 전환.
+
+**Import:** `import { ThemeSwitcher } from "@reopt-ai/opt-ui"`
+
+| Prop     | Type                  | Required | Default | Description            |
+| -------- | --------------------- | -------- | ------- | ---------------------- |
+| `labels` | `ThemeSwitcherLabels` |          |         | i18n용 라벨 오버라이드 |
+
+## Data Display
+
+| Component           | Description                                                                                                                  | Key Exports                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| DataTable           | 제네릭 데이터 테이블. 동적 컬럼, 결측값 안전 정렬, 키보드 컬럼 리사이즈, 보정된 인라인 진행률과 Composite 탐색을 지원합니다. | `DataTable`                                   |
+| InlineEditTable     | 인라인 편집 테이블. 더블클릭으로 셀 편집, Enter 확정, Escape 취소.                                                           | `InlineEditTable`                             |
+| TreeTable           | 계층형 트리 테이블. 재귀 행 렌더링 + 펼침/접기 셰브론.                                                                       | `TreeTable`                                   |
+| DomainTable         | 도메인 테이블. Composite 기반 그리드로 키보드 탐색 지원.                                                                     | `DomainTable`                                 |
+| QueryResultsTable   | 쿼리 결과 테이블. SQL 결과와 스크린 리더에 안내되는 로딩, 에러, 빈 상태를 지원합니다.                                        | `QueryResultsTable`                           |
+| DashboardGrid       | Composite 기반 통계 카드 그리드. 유효한 1–4열 레이아웃과 화살표 키 2D 탐색을 지원합니다.                                     | `DashboardGrid`                               |
+| SummaryRow          | 통계 요약 행. StatCard 그리드 레이아웃을 표준화합니다. loading 시 SkeletonCard 표시.                                         | `SummaryRow`                                  |
+| CodeSnippetViewer   | 코드 스니펫 뷰어. 줄 번호, 복사 버튼, 포커스 가능한 스크롤 영역, syntaxTheme 톤을 지원합니다.                                | `CodeSnippetViewer`                           |
+| CodeDiffViewer      | 코드 비교 뷰어. LCS 알고리즘 기반 unified/split 모드 diff와 포커스 가능한 스크롤 영역을 제공합니다.                          | `CodeDiffViewer`                              |
+| ConnectionIndicator | 연결 상태 표시기. connected, connecting, disconnected, error 상태를 지원합니다.                                              | `ConnectionIndicator`                         |
+| EventIcon           | 이벤트 아이콘. semantic key 또는 ReactNode 아이콘과 배경색을 표시합니다.                                                     | `EventIcon`, `POPULAR_ICONS`, `COLOR_PRESETS` |
+
+### DataTable
+
+> 제네릭 데이터 테이블. 동적 컬럼, 결측값 안전 정렬, 키보드 컬럼 리사이즈, 보정된 인라인 진행률과 Composite 탐색을 지원합니다.
+
+**Import:** `import { DataTable } from "@reopt-ai/opt-ui"`
+**Dependencies:** composite-zone (core), button (core), checkbox (core)
+
+**DataTable:**
+
+| Prop           | Type                 | Required | Default             | Description                                         |
+| -------------- | -------------------- | -------- | ------------------- | --------------------------------------------------- |
+| `data`         | `T[]`                | Yes      |                     | 테이블 데이터 배열                                  |
+| `columns`      | `ColumnDef<T>[]`     | Yes      |                     | 컬럼 정의. { id, header, accessor, width?, align? } |
+| `keyExtractor` | `(row: T) => string` | Yes      |                     | 각 행의 고유 키 추출 함수                           |
+| `title`        | `string`             |          | "데이터 테이블"     | 테이블 제목                                         |
+| `onRowClick`   | `(row: T) => void`   |          |                     | 행 클릭 핸들러                                      |
+| `emptyMessage` | `string`             |          | "데이터가 없습니다" | 데이터 없을 때 표시할 메시지                        |
+
+**ColumnDef:**
+
+| Prop       | Type                 | Required | Default     | Description                                                  |
+| ---------- | -------------------- | -------- | ----------- | ------------------------------------------------------------ |
+| `bar`      | `(row: T) => number` |          |             | 인라인 프로그레스 바 비율(0-1) 계산 함수. 범위 밖/NaN은 보정 |
+| `barColor` | `string`             |          | "bg-accent" | 인라인 바 색상 클래스                                        |
+
+**Examples:**
+
+_기본 테이블:_
+
+```tsx
+import { DataTable } from "@reopt-ai/opt-ui";
+
+const columns = [
+  { id: "name", header: "이름", accessor: (r) => r.name },
+  { id: "email", header: "이메일", accessor: (r) => r.email },
+];
+const data = [
+  { name: "홍길동", email: "hong@example.com" },
+  { name: "김철수", email: "kim@example.com" },
+];
+
+<DataTable columns={columns} data={data} keyExtractor={(r) => r.email} />;
+```
+
+_선택 + 정렬:_
+
+```tsx
+import { DataTable } from "@reopt-ai/opt-ui";
+
+<DataTable
+  columns={columns}
+  data={data}
+  keyExtractor={(r) => r.id}
+  selectable
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+  sortable
+  onSort={(colId, dir) => console.log(colId, dir)}
+/>;
+```
+
+### InlineEditTable
+
+> 인라인 편집 테이블. 더블클릭으로 셀 편집, Enter 확정, Escape 취소.
+
+**Import:** `import { InlineEditTable } from "@reopt-ai/opt-ui"`
+**Dependencies:** data-table (shells)
+
+| Prop           | Type                                                       | Required | Default | Description                      |
+| -------------- | ---------------------------------------------------------- | -------- | ------- | -------------------------------- |
+| `data`         | `T[]`                                                      | Yes      |         | 행 데이터 배열                   |
+| `columns`      | `InlineEditColumnDef<T>[]`                                 | Yes      |         | 컬럼 정의 (editable 플래그 포함) |
+| `keyExtractor` | `(row: T) => string`                                       | Yes      |         | 행 키 추출기                     |
+| `onCellEdit`   | `(rowId: string, columnId: string, value: string) => void` |          |         | 셀 편집 확정 콜백                |
+| `className`    | `string`                                                   |          |         | 커스텀 CSS 클래스                |
+
+### TreeTable
+
+> 계층형 트리 테이블. 재귀 행 렌더링 + 펼침/접기 셰브론.
+
+**Import:** `import { TreeTable } from "@reopt-ai/opt-ui"`
+**Dependencies:** data-table (shells)
+
+| Prop              | Type                 | Required | Default | Description        |
+| ----------------- | -------------------- | -------- | ------- | ------------------ |
+| `data`            | `TreeNode<T>[]`      | Yes      |         | 트리 노드 배열     |
+| `columns`         | `TreeColumnDef<T>[]` | Yes      |         | 컬럼 정의          |
+| `defaultExpanded` | `string[]`           |          | []      | 기본 펼침 노드 ID  |
+| `indentSize`      | `number`             |          | 24      | 들여쓰기 크기 (px) |
+| `className`       | `string`             |          |         | 커스텀 CSS 클래스  |
+
+### DomainTable
+
+> 도메인 테이블. Composite 기반 그리드로 키보드 탐색 지원.
+
+**Import:** `import { DomainTable } from "@reopt-ai/opt-ui"`
+
+| Prop      | Type          | Required | Default  | Description                                               |
+| --------- | ------------- | -------- | -------- | --------------------------------------------------------- |
+| `domains` | `DomainDef[]` | Yes      |          | 도메인 목록. { domain, status, ssl, redirect?, addedAt? } |
+| `title`   | `string`      |          | "도메인" | 테이블 제목                                               |
+
+### QueryResultsTable
+
+> 쿼리 결과 테이블. SQL 결과와 스크린 리더에 안내되는 로딩, 에러, 빈 상태를 지원합니다.
+
+**Import:** `import { QueryResultsTable } from "@reopt-ai/opt-ui"`
+
+| Prop      | Type                             | Required | Default | Description             |
+| --------- | -------------------------------- | -------- | ------- | ----------------------- |
+| `columns` | `string[]`                       | Yes      |         | 컬럼 이름               |
+| `rows`    | `Array<Record<string, unknown>>` | Yes      |         | 결과 행                 |
+| `loading` | `boolean`                        |          |         | polite 로딩 상태        |
+| `error`   | `string`                         |          |         | assertive 오류 상태     |
+| `labels`  | `QueryResultsTableLabels`        |          |         | 로딩/빈 상태/행 수 문구 |
+
+### DashboardGrid
+
+> Composite 기반 통계 카드 그리드. 유효한 1–4열 레이아웃과 화살표 키 2D 탐색을 지원합니다.
+
+**Import:** `import { DashboardGrid } from "@reopt-ai/opt-ui"`
+**Dependencies:** stat-card (core), composite-zone (core)
+
+| Prop      | Type         | Required | Default | Description                                           |
+| --------- | ------------ | -------- | ------- | ----------------------------------------------------- |
+| `stats`   | `StatCard[]` | Yes      |         | 통계 데이터 배열. { id, title, value, change, trend } |
+| `columns` | `number`     |          | 3       | 행당 컬럼 수                                          |
+
+### SummaryRow
+
+> 통계 요약 행. StatCard 그리드 레이아웃을 표준화합니다. loading 시 SkeletonCard 표시.
+
+**Import:** `import { SummaryRow } from "@reopt-ai/opt-ui"`
+**Dependencies:** stat-card (core), skeleton (core)
+
+| Prop                       | Type                             | Required | Default | Description                      |
+| -------------------------- | -------------------------------- | -------- | ------- | -------------------------------- |
+| `stats`                    | `StatCardType[]`                 | Yes      |         | 통계 카드 배열                   |
+| `columns`                  | `2 \| 3 \| 4`                    |          | 4       | 컬럼 수                          |
+| `onStatClick`              | `(stat: StatCardType) => void`   |          |         | 카드 클릭 핸들러                 |
+| `formatValue`              | `(stat: StatCardType) => string` |          |         | 값 표시 커스텀 포맷 함수         |
+| `durationFractionDigits`   | `number`                         |          | 1       | duration 포맷 시 소수점 자리수   |
+| `percentageFractionDigits` | `number`                         |          | 1       | percentage 포맷 시 소수점 자리수 |
+| `loading`                  | `boolean`                        |          | false   | 로딩 시 스켈레톤 표시            |
+
+### CodeSnippetViewer
+
+> 코드 스니펫 뷰어. 줄 번호, 복사 버튼, 포커스 가능한 스크롤 영역, syntaxTheme 톤을 지원합니다.
+
+**Import:** `import { CodeSnippetViewer } from "@reopt-ai/opt-ui"`
+
+| Prop              | Type                                           | Required | Default   | Description                       |
+| ----------------- | ---------------------------------------------- | -------- | --------- | --------------------------------- |
+| `code`            | `string`                                       | Yes      |           | 표시할 코드 문자열                |
+| `language`        | `string`                                       |          | "text"    | 코드 언어 라벨                    |
+| `title`           | `string`                                       |          |           | 헤더에 표시할 제목                |
+| `showLineNumbers` | `boolean`                                      |          | true      | 줄 번호 표시 여부                 |
+| `showCopyButton`  | `boolean`                                      |          | true      | 복사 버튼 표시 여부               |
+| `maxHeight`       | `number`                                       |          | 400       | 스크롤 영역의 최대 높이(px)       |
+| `syntaxTheme`     | `"default" \| "muted" \| "dark" \| "terminal"` |          | "default" | 코드 블록 색상 톤                 |
+| `className`       | `string`                                       |          |           | 커스텀 CSS 클래스                 |
+| `labels`          | `CodeSnippetViewerLabels`                      |          |           | 복사 버튼과 코드 영역 레이블 문구 |
+
+### CodeDiffViewer
+
+> 코드 비교 뷰어. LCS 알고리즘 기반 unified/split 모드 diff와 포커스 가능한 스크롤 영역을 제공합니다.
+
+**Import:** `import { CodeDiffViewer } from "@reopt-ai/opt-ui"`
+
+| Prop              | Type                   | Required | Default   | Description                             |
+| ----------------- | ---------------------- | -------- | --------- | --------------------------------------- |
+| `original`        | `string`               | Yes      |           | 원본 코드                               |
+| `modified`        | `string`               | Yes      |           | 수정된 코드                             |
+| `mode`            | `"split" \| "unified"` |          | "unified" | 뷰 모드                                 |
+| `showLineNumbers` | `boolean`              |          | true      | 줄 번호 표시                            |
+| `scrollLabel`     | `string`               |          |           | 스크롤 가능한 diff 영역의 접근성 레이블 |
+| `className`       | `string`               |          |           | 커스텀 CSS 클래스                       |
+
+### ConnectionIndicator
+
+> 연결 상태 표시기. connected, connecting, disconnected, error 상태를 지원합니다.
+
+**Import:** `import { ConnectionIndicator } from "@reopt-ai/opt-ui"`
+
+### EventIcon
+
+> 이벤트 아이콘. semantic key 또는 ReactNode 아이콘과 배경색을 표시합니다.
+
+**Import:** `import { EventIcon } from "@reopt-ai/opt-ui"`
+
+| Prop    | Type                        | Required | Default      | Description                                                                                             |
+| ------- | --------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| `icon`  | `string \| React.ReactNode` | Yes      |              | semantic icon key, legacy key, 또는 React 노드 (Lucide 등)                                              |
+| `color` | `string`                    |          | theme accent | 사용자 지정 아이콘 색상. 없으면 theme accent 토큰을 사용하고, 전달하면 전경색과 tint 배경에 적용됩니다. |
+| `size`  | `"sm" \| "md" \| "lg"`      |          | "md"         | 아이콘 크기 (sm=20px, md=28px, lg=36px)                                                                 |
+
+## Lists & Feeds
+
+| Component          | Description                                                                         | Key Exports          |
+| ------------------ | ----------------------------------------------------------------------------------- | -------------------- |
+| TaskList           | 작업 목록 관리 컴포넌트. 우선순위, 상태, 담당자, 태그, 하위 작업 지원.              | `TaskList`           |
+| ActivityFeed       | 활동 피드/로그 컴포넌트. 타임라인 스타일, 상대 시간 표시.                           | `ActivityFeed`       |
+| TeamMemberList     | 팀원 목록 컴포넌트. 온라인 상태, 다양한 레이아웃(list, compact, avatars-only) 지원. | `TeamMemberList`     |
+| KanbanBoard        | 칸반 보드. HTML5 DnD로 카드를 컬럼 간 드래그&드롭.                                  | `KanbanBoard`        |
+| AuditLog           | 감사 로그 타임라인. 아바타 + 액션 텍스트 + 메타데이터 배지 레이아웃.                | `AuditLog`           |
+| NotificationCenter | 알림 센터. 벨 아이콘 트리거 + 미읽음 배지 + 스크롤 알림 목록.                       | `NotificationCenter` |
+
+### TaskList
+
+> 작업 목록 관리 컴포넌트. 우선순위, 상태, 담당자, 태그, 하위 작업 지원.
+
+**Import:** `import { TaskList } from "@reopt-ai/opt-ui"`
+**Dependencies:** avatar (core), checkbox (core)
+
+| Prop                 | Type                                          | Required | Default     | Description                                                |
+| -------------------- | --------------------------------------------- | -------- | ----------- | ---------------------------------------------------------- |
+| `tasks`              | `TaskDef[]`                                   | Yes      |             | 작업 배열. { id, title, status, priority, assignee?, ... } |
+| `title`              | `string`                                      |          | "작업 목록" | 섹션 제목                                                  |
+| `onTaskClick`        | `(task: TaskDef) => void`                     |          |             | 작업 클릭 핸들러                                           |
+| `onTaskStatusChange` | `(task: TaskDef, completed: boolean) => void` |          |             | 완료 상태 변경 핸들러                                      |
+| `showSubtasks`       | `boolean`                                     |          | false       | 하위 작업 표시 여부                                        |
+
+### ActivityFeed
+
+> 활동 피드/로그 컴포넌트. 타임라인 스타일, 상대 시간 표시.
+
+**Import:** `import { ActivityFeed } from "@reopt-ai/opt-ui"`
+**Dependencies:** avatar (core)
+
+| Prop              | Type                                   | Required | Default     | Description                                           |
+| ----------------- | -------------------------------------- | -------- | ----------- | ----------------------------------------------------- |
+| `activities`      | `ActivityDef[]`                        | Yes      |             | 활동 배열. { id, type, title, actor, timestamp, ... } |
+| `title`           | `string`                               |          | "활동 피드" | 섹션 제목                                             |
+| `maxItems`        | `number`                               |          |             | 최대 표시 개수                                        |
+| `onActivityClick` | `(activity: ActivityDef) => void`      |          |             | 활동 클릭 핸들러                                      |
+| `layout`          | `"list" \| "compact"`                  |          | "list"      | 시간 표시 레이아웃 모드                               |
+| `renderActions`   | `(activity: ActivityDef) => ReactNode` |          |             | 각 활동 항목 우측 액션 슬롯 렌더 함수                 |
+
+### TeamMemberList
+
+> 팀원 목록 컴포넌트. 온라인 상태, 다양한 레이아웃(list, compact, avatars-only) 지원.
+
+**Import:** `import { TeamMemberList } from "@reopt-ai/opt-ui"`
+**Dependencies:** avatar (core)
+
+| Prop            | Type                                    | Required | Default | Description                                             |
+| --------------- | --------------------------------------- | -------- | ------- | ------------------------------------------------------- |
+| `members`       | `TeamMemberDef[]`                       | Yes      |         | 팀원 배열. { id, name, email, avatar?, role?, status? } |
+| `title`         | `string`                                |          | "팀원"  | 섹션 제목                                               |
+| `layout`        | `"list" \| "compact" \| "avatars-only"` |          | "list"  | 레이아웃 모드                                           |
+| `maxDisplay`    | `number`                                |          |         | 최대 표시 인원                                          |
+| `onMemberClick` | `(member: TeamMemberDef) => void`       |          |         | 팀원 클릭 핸들러                                        |
+
+### KanbanBoard
+
+> 칸반 보드. HTML5 DnD로 카드를 컬럼 간 드래그&드롭.
+
+**Import:** `import { KanbanBoard } from "@reopt-ai/opt-ui"`
+**Dependencies:** scroll-area (core)
+
+| Prop           | Type                                        | Required | Default | Description                      |
+| -------------- | ------------------------------------------- | -------- | ------- | -------------------------------- |
+| `columns`      | `KanbanColumn<T>[]`                         | Yes      |         | 컬럼 목록 (각 컬럼에 items 배열) |
+| `onDragEnd`    | `(itemId, fromCol, toCol, toIndex) => void` | Yes      |         | 드래그 완료 콜백                 |
+| `renderCard`   | `(item: T) => ReactNode`                    | Yes      |         | 카드 렌더링 함수                 |
+| `keyExtractor` | `(item: T) => string`                       | Yes      |         | 항목 키 추출기                   |
+| `className`    | `string`                                    |          |         | 커스텀 CSS 클래스                |
+
+### AuditLog
+
+> 감사 로그 타임라인. 아바타 + 액션 텍스트 + 메타데이터 배지 레이아웃.
+
+**Import:** `import { AuditLog } from "@reopt-ai/opt-ui"`
+**Dependencies:** avatar (core), badge (core)
+
+| Prop         | Type           | Required | Default | Description         |
+| ------------ | -------------- | -------- | ------- | ------------------- |
+| `entries`    | `AuditEntry[]` | Yes      |         | 감사 로그 항목 배열 |
+| `onLoadMore` | `() => void`   |          |         | 더 보기 콜백        |
+| `loading`    | `boolean`      |          | false   | 로딩 상태           |
+| `className`  | `string`       |          |         | 커스텀 CSS 클래스   |
+
+### NotificationCenter
+
+> 알림 센터. 벨 아이콘 트리거 + 미읽음 배지 + 스크롤 알림 목록.
+
+**Import:** `import { NotificationCenter } from "@reopt-ai/opt-ui"`
+**Dependencies:** popover (core), badge (core), scroll-area (core)
+
+| Prop            | Type                   | Required | Default | Description         |
+| --------------- | ---------------------- | -------- | ------- | ------------------- |
+| `notifications` | `NotificationItem[]`   | Yes      |         | 알림 목록           |
+| `onMarkRead`    | `(id: string) => void` | Yes      |         | 읽음 처리 콜백      |
+| `onMarkAllRead` | `() => void`           | Yes      |         | 전체 읽음 처리 콜백 |
+| `onAction`      | `(id: string) => void` |          |         | 알림 액션 콜백      |
+| `className`     | `string`               |          |         | 커스텀 CSS 클래스   |
+
+## Filters & Search
+
+| Component          | Description                                                                                                        | Key Exports          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| SearchCombobox     | match-sorter 기반 퍼지 검색 콤보박스.                                                                              | `SearchCombobox`     |
+| AsyncCombobox      | 비동기 검색 콤보박스. 디바운스 + 로딩 스피너와 stale response 방어를 내장합니다.                                   | `AsyncCombobox`      |
+| StatusSelect       | 색상 인디케이터가 있는 상태 선택 드롭다운.                                                                         | `StatusSelect`       |
+| BranchSelect       | Git 브랜치 선택 드롭다운. Select primitive 래퍼.                                                                   | `BranchSelect`       |
+| FilterBar          | 필터링 바 컴포넌트. 검색, 선택, 다중 선택 필터 지원.                                                               | `FilterBar`          |
+| SavedFilters       | 필터 프리셋 관리. 현재 필터를 저장하고 불러오는 Popover UI.                                                        | `SavedFilters`       |
+| QuickActions       | 빠른 작업 패널. 그리드/리스트 레이아웃, 단축키 표시 지원.                                                          | `QuickActions`       |
+| TimeRangeSelector  | 시간 범위 선택기. Popover + DateRangePicker + 프리셋 버튼 조합. 12개 시계열 Surface에서 사용.                      | `TimeRangeSelector`  |
+| ComparisonSelector | 비교 선택기. 고유 레이블이 연결된 Select × 2 + Swap 버튼 조합. CohortComparison, FunnelAnalysis 등에서 사용합니다. | `ComparisonSelector` |
+| ColumnToggler      | 테이블 컬럼 표시/숨김 토글러. Popover + Checkbox 리스트입니다.                                                     | `ColumnToggler`      |
+| BulkActions        | 일괄 작업 바. 선택 카운트 배지 + DropdownMenu 액션 목록 + 해제 버튼.                                               | `BulkActions`        |
+
+### SearchCombobox
+
+> match-sorter 기반 퍼지 검색 콤보박스.
+
+**Import:** `import { SearchCombobox } from "@reopt-ai/opt-ui"`
+**Dependencies:** combobox (core)
+
+| Prop          | Type                                   | Required | Default   | Description                      |
+| ------------- | -------------------------------------- | -------- | --------- | -------------------------------- |
+| `items`       | `string[]`                             | Yes      |           | 검색 대상 문자열 목록            |
+| `placeholder` | `string`                               |          | "검색..." | 입력 플레이스홀더                |
+| `label`       | `string`                               |          | "검색"    | 입력 레이블                      |
+| `onSelect`    | `(item: string) => void`               |          |           | 항목 선택 핸들러                 |
+| `labels`      | `SearchComboboxLabels`                 |          |           | noResults/loading 문구           |
+| `async`       | `boolean`                              |          | false     | 비동기 검색 모드 활성화          |
+| `onSearch`    | `(query: string) => Promise<string[]>` |          |           | async=true일 때 사용할 검색 콜백 |
+| `debounceMs`  | `number`                               |          | 300       | 비동기 검색 디바운스 ms          |
+
+**Examples:**
+
+_검색 + 선택:_
+
+```tsx
+import { SearchCombobox } from "@reopt-ai/opt-ui";
+
+<SearchCombobox
+  items={["React", "Vue", "Angular", "Svelte"]}
+  placeholder="프레임워크 검색..."
+  onSelect={(item) => console.log(item)}
+/>;
+```
+
+### AsyncCombobox
+
+> 비동기 검색 콤보박스. 디바운스 + 로딩 스피너와 stale response 방어를 내장합니다.
+
+**Import:** `import { AsyncCombobox } from "@reopt-ai/opt-ui"`
+**Dependencies:** combobox (core), spinner (core)
+
+| Prop          | Type                               | Required | Default   | Description                              |
+| ------------- | ---------------------------------- | -------- | --------- | ---------------------------------------- |
+| `onSearch`    | `(q: string) => Promise<string[]>` | Yes      |           | 검색 콜백                                |
+| `debounceMs`  | `number`                           |          | 300       | 디바운스 ms                              |
+| `minChars`    | `number`                           |          | 1         | 최소 검색 글자 수                        |
+| `placeholder` | `string`                           |          | "Search…" | 플레이스홀더                             |
+| `onSelect`    | `(value: string) => void`          |          |           | 선택 콜백                                |
+| `labels`      | `AsyncComboboxLabels`              |          |           | input/loading/noResults/placeholder 문구 |
+| `loadingText` | `string`                           |          |           | 로딩 문구. labels.loading 사용 권장      |
+
+### StatusSelect
+
+> 색상 인디케이터가 있는 상태 선택 드롭다운.
+
+**Import:** `import { StatusSelect } from "@reopt-ai/opt-ui"`
+**Dependencies:** select (core)
+
+| Prop       | Type                      | Required | Default | Description                         |
+| ---------- | ------------------------- | -------- | ------- | ----------------------------------- |
+| `options`  | `SelectOption[]`          | Yes      |         | 옵션 목록. { value, label, color? } |
+| `value`    | `string`                  |          |         | 제어 모드: 현재 선택 값             |
+| `onChange` | `(value: string) => void` |          |         | 제어 모드: 값 변경 핸들러           |
+| `label`    | `string`                  |          | "상태"  | Select 레이블                       |
+
+### BranchSelect
+
+> Git 브랜치 선택 드롭다운. Select primitive 래퍼.
+
+**Import:** `import { BranchSelect } from "@reopt-ai/opt-ui"`
+**Dependencies:** select (core)
+
+| Prop       | Type                     | Required | Default  | Description                                             |
+| ---------- | ------------------------ | -------- | -------- | ------------------------------------------------------- |
+| `branches` | `BranchDef[]`            | Yes      |          | 브랜치 목록. { name, isDefault?, lastCommit?, author? } |
+| `value`    | `string`                 |          |          | 제어 모드: 현재 선택된 브랜치 이름                      |
+| `onChange` | `(name: string) => void` |          |          | 브랜치 선택 핸들러                                      |
+| `label`    | `string`                 |          | "브랜치" | Select 레이블                                           |
+
+### FilterBar
+
+> 필터링 바 컴포넌트. 검색, 선택, 다중 선택 필터 지원.
+
+**Import:** `import { FilterBar } from "@reopt-ai/opt-ui"`
+**Dependencies:** select (core), input (core), button (core), switch (core), checkbox (core), date-range-picker (core)
+
+| Prop             | Type                                                    | Required | Default | Description                                           |
+| ---------------- | ------------------------------------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `filters`        | `FilterGroupDef[]`                                      | Yes      |         | 필터 그룹 배열. { id, label, type, options?, value? } |
+| `onFilterChange` | `(filterId: string, value: string \| string[]) => void` |          |         | 필터 변경 핸들러                                      |
+| `onClearAll`     | `() => void`                                            |          |         | 모든 필터 초기화 핸들러                               |
+
+**Examples:**
+
+_필터 바:_
+
+```tsx
+import { FilterBar } from "@reopt-ai/opt-ui";
+
+const filters = [
+  { id: "status", label: "상태", type: "select", options: ["활성", "비활성"] },
+  { id: "search", label: "검색", type: "search" },
+];
+
+<FilterBar
+  filters={filters}
+  onFilterChange={(id, value) => console.log(id, value)}
+  onClearAll={() => console.log("clear")}
+/>;
+```
+
+### SavedFilters
+
+> 필터 프리셋 관리. 현재 필터를 저장하고 불러오는 Popover UI.
+
+**Import:** `import { SavedFilters } from "@reopt-ai/opt-ui"`
+**Dependencies:** popover (core), input (core)
+
+| Prop             | Type                                                       | Required | Default | Description          |
+| ---------------- | ---------------------------------------------------------- | -------- | ------- | -------------------- |
+| `currentFilters` | `Record<string, unknown>`                                  | Yes      |         | 현재 적용 중인 필터  |
+| `presets`        | `FilterPreset[]`                                           | Yes      |         | 저장된 프리셋 목록   |
+| `onSavePreset`   | `(name: string, filters: Record<string, unknown>) => void` | Yes      |         | 프리셋 저장 콜백     |
+| `onLoadPreset`   | `(preset: FilterPreset) => void`                           | Yes      |         | 프리셋 불러오기 콜백 |
+| `onDeletePreset` | `(presetId: string) => void`                               | Yes      |         | 프리셋 삭제 콜백     |
+| `className`      | `string`                                                   |          |         | 커스텀 CSS 클래스    |
+
+### QuickActions
+
+> 빠른 작업 패널. 그리드/리스트 레이아웃, 단축키 표시 지원.
+
+**Import:** `import { QuickActions } from "@reopt-ai/opt-ui"`
+**Dependencies:** kbd (core)
+
+| Prop      | Type               | Required | Default     | Description                                                       |
+| --------- | ------------------ | -------- | ----------- | ----------------------------------------------------------------- |
+| `actions` | `QuickActionDef[]` | Yes      |             | 작업 배열. { id, label, description?, icon?, shortcut?, onClick } |
+| `title`   | `string`           |          | "빠른 작업" | 섹션 제목                                                         |
+| `layout`  | `"grid" \| "list"` |          | "grid"      | 레이아웃 모드                                                     |
+| `columns` | `2 \| 3 \| 4`      |          | 3           | 그리드 컬럼 수                                                    |
+
+### TimeRangeSelector
+
+> 시간 범위 선택기. Popover + DateRangePicker + 프리셋 버튼 조합. 12개 시계열 Surface에서 사용.
+
+**Import:** `import { TimeRangeSelector } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), popover (core), date-range-picker (core)
+
+| Prop       | Type                         | Required | Default | Description                          |
+| ---------- | ---------------------------- | -------- | ------- | ------------------------------------ |
+| `value`    | `DateRange`                  |          |         | 현재 선택된 날짜 범위                |
+| `onChange` | `(range: DateRange) => void` |          |         | 범위 변경 핸들러                     |
+| `presets`  | `TimePresetDef[]`            |          |         | 빠른 프리셋 목록 (Today, Last 7d 등) |
+| `labels`   | `TimeRangeSelectorLabels`    |          |         | i18n용 라벨 오버라이드               |
+
+### ComparisonSelector
+
+> 비교 선택기. 고유 레이블이 연결된 Select × 2 + Swap 버튼 조합. CohortComparison, FunnelAnalysis 등에서 사용합니다.
+
+**Import:** `import { ComparisonSelector } from "@reopt-ai/opt-ui"`
+**Dependencies:** select (core), button (core)
+
+| Prop        | Type                       | Required | Default | Description               |
+| ----------- | -------------------------- | -------- | ------- | ------------------------- |
+| `segments`  | `ComparisonOption[]`       | Yes      |         | 선택 가능한 세그먼트 목록 |
+| `valueA`    | `string`                   |          |         | Base 선택값               |
+| `valueB`    | `string`                   |          |         | Compare 선택값            |
+| `onChangeA` | `(value: string) => void`  |          |         | Base 변경 핸들러          |
+| `onChangeB` | `(value: string) => void`  |          |         | Compare 변경 핸들러       |
+| `labels`    | `ComparisonSelectorLabels` |          |         | i18n용 라벨 오버라이드    |
+
+### ColumnToggler
+
+> 테이블 컬럼 표시/숨김 토글러. Popover + Checkbox 리스트입니다.
+
+**Import:** `import { ColumnToggler } from "@reopt-ai/opt-ui"`
+**Dependencies:** popover (core), checkbox (core)
+
+| Prop             | Type                                 | Required | Default | Description            |
+| ---------------- | ------------------------------------ | -------- | ------- | ---------------------- |
+| `columns`        | `ColumnTogglerColumn[]`              | Yes      |         | 전체 컬럼 목록         |
+| `visibleColumns` | `string[]`                           | Yes      |         | 표시 중인 컬럼 ID 배열 |
+| `onChange`       | `(visibleColumns: string[]) => void` | Yes      |         | 변경 콜백              |
+
+### BulkActions
+
+> 일괄 작업 바. 선택 카운트 배지 + DropdownMenu 액션 목록 + 해제 버튼.
+
+**Import:** `import { BulkActions } from "@reopt-ai/opt-ui"`
+**Dependencies:** dropdown-menu (core), badge (core)
+
+| Prop            | Type                         | Required | Default | Description                                  |
+| --------------- | ---------------------------- | -------- | ------- | -------------------------------------------- |
+| `selectedCount` | `number`                     | Yes      |         | 선택된 항목 수                               |
+| `actions`       | `BulkActionDef[]`            | Yes      |         | 액션 목록. { id, label, variant?: "danger" } |
+| `onAction`      | `(actionId: string) => void` | Yes      |         | 액션 실행 콜백                               |
+| `onClear`       | `() => void`                 | Yes      |         | 선택 해제 콜백                               |
+| `className`     | `string`                     |          |         | 커스텀 CSS 클래스                            |
+
+## Forms
+
+| Component        | Description                                                                                                            | Key Exports        |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| SettingsForm     | 데이터 기반 설정 폼. 유효성 검증, 라디오, 체크박스 지원.                                                               | `SettingsForm`     |
+| AuthForm         | 로그인/회원가입 모드 전환 가능한 인증 폼. 이메일·비밀번호 검증, FormSwitch로 로그인 상태 유지 옵션 지원.               | `AuthForm`         |
+| DynamicFieldForm | 런타임 필드 추가/제거 폼. 최소/최대 필드 수 제약, 개별 검증, 동적 스토어 업데이트 지원.                                | `DynamicFieldForm` |
+| FileUploadForm   | 파일 선택, 메타데이터 표시, 이미지 미리보기를 포함한 업로드 폼. 파일 크기 제한, 설명 입력 지원.                        | `FileUploadForm`   |
+| WizardForm       | 다단계 순차 입력 폼. FormFieldDef 기반 필드 정의, 단계별 검증, 현재 단계가 연결된 진행 표시기, 리뷰 단계를 지원합니다. | `WizardForm`       |
+| ConfirmDialog    | 확인/취소 대화 상자. danger 변형으로 위험 작업 확인을 지원합니다.                                                      | `ConfirmDialog`    |
+| PromptTemplate   | AI 프롬프트 뷰어/헬퍼. 변수 입력 → 실시간 치환 → 복사 기능.                                                            | `PromptTemplate`   |
+
+### SettingsForm
+
+> 데이터 기반 설정 폼. 유효성 검증, 라디오, 체크박스 지원.
+
+**Import:** `import { SettingsForm } from "@reopt-ai/opt-ui"`
+**Dependencies:** form (core), checkbox (core), radio-group (core), switch (core)
+
+| Prop       | Type                                        | Required | Default | Description       |
+| ---------- | ------------------------------------------- | -------- | ------- | ----------------- |
+| `fields`   | `FormFieldDef[]`                            | Yes      |         | 폼 필드 정의 배열 |
+| `onSubmit` | `(values: Record<string, unknown>) => void` |          |         | 제출 핸들러       |
+
+**Examples:**
+
+_설정 폼:_
+
+```tsx
+import { SettingsForm } from "@reopt-ai/opt-ui";
+
+const fields = [
+  { name: "username", label: "사용자명", type: "text", required: true },
+  { name: "theme", label: "테마", type: "select", options: ["light", "dark"] },
+  { name: "notifications", label: "알림", type: "switch" },
+];
+
+<SettingsForm fields={fields} onSubmit={(values) => console.log(values)} />;
+```
+
+### AuthForm
+
+> 로그인/회원가입 모드 전환 가능한 인증 폼. 이메일·비밀번호 검증, FormSwitch로 로그인 상태 유지 옵션 지원.
+
+**Import:** `import { AuthForm } from "@reopt-ai/opt-ui"`
+**Dependencies:** form (core)
+
+| Prop                | Type                                                                         | Required | Default | Description                                  |
+| ------------------- | ---------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------- |
+| `defaultMode`       | `"login" \| "signup"`                                                        |          | "login" | 초기 모드 (비제어)                           |
+| `mode`              | `"login" \| "signup"`                                                        |          |         | 제어 모드: 현재 모드                         |
+| `onModeChange`      | `(mode: "login" \| "signup") => void`                                        |          |         | 모드 변경 핸들러                             |
+| `showRememberMe`    | `boolean`                                                                    |          | true    | 로그인 모드에서 '로그인 상태 유지' 표시 여부 |
+| `minPasswordLength` | `number`                                                                     |          | 8       | 비밀번호 최소 길이                           |
+| `onSubmit`          | `(values: { email, password, confirmPassword?, rememberMe?, mode }) => void` |          |         | 제출 핸들러                                  |
+| `labels`            | `AuthFormLabels`                                                             |          |         | i18n용 라벨 오버라이드                       |
+
+### DynamicFieldForm
+
+> 런타임 필드 추가/제거 폼. 최소/최대 필드 수 제약, 개별 검증, 동적 스토어 업데이트 지원.
+
+**Import:** `import { DynamicFieldForm } from "@reopt-ai/opt-ui"`
+**Dependencies:** form (core)
+
+| Prop            | Type                                                    | Required | Default | Description            |
+| --------------- | ------------------------------------------------------- | -------- | ------- | ---------------------- |
+| `initialCount`  | `number`                                                |          | 1       | 초기 필드 수           |
+| `minFields`     | `number`                                                |          | 1       | 최소 필드 수           |
+| `maxFields`     | `number`                                                |          |         | 최대 필드 수           |
+| `fieldType`     | `"text" \| "email" \| "url" \| "number"`                |          | "text"  | 필드 입력 타입         |
+| `validateField` | `(value: string, index: number) => string \| undefined` |          |         | 커스텀 필드 검증 함수  |
+| `onSubmit`      | `(values: string[]) => void`                            |          |         | 제출 핸들러            |
+| `labels`        | `DynamicFieldFormLabels`                                |          |         | i18n용 라벨 오버라이드 |
+
+### FileUploadForm
+
+> 파일 선택, 메타데이터 표시, 이미지 미리보기를 포함한 업로드 폼. 파일 크기 제한, 설명 입력 지원.
+
+**Import:** `import { FileUploadForm } from "@reopt-ai/opt-ui"`
+**Dependencies:** form (core)
+
+| Prop              | Type                                             | Required | Default                    | Description                               |
+| ----------------- | ------------------------------------------------ | -------- | -------------------------- | ----------------------------------------- |
+| `accept`          | `string`                                         |          | "image/\*,.pdf,.doc,.docx" | 허용 파일 타입                            |
+| `showPreview`     | `boolean`                                        |          | true                       | 이미지 미리보기 표시                      |
+| `showFileInfo`    | `boolean`                                        |          | true                       | 파일 정보 표시                            |
+| `showDescription` | `boolean`                                        |          | true                       | 설명 텍스트영역 표시                      |
+| `maxFileSize`     | `number`                                         |          |                            | 최대 파일 크기 (bytes)                    |
+| `onSubmit`        | `(values: { title, description, file }) => void` |          |                            | 제출 핸들러                               |
+| `labels`          | `FileUploadFormLabels`                           |          |                            | i18n용 라벨 오버라이드                    |
+| `onPreview`       | `(file: File) => void`                           |          |                            | 파일 선택 후 프리뷰 콜백                  |
+| `columnMapping`   | `ReactNode`                                      |          |                            | CSV 컬럼 매핑 UI 슬롯 (파일 선택 후 표시) |
+
+### WizardForm
+
+> 다단계 순차 입력 폼. FormFieldDef 기반 필드 정의, 단계별 검증, 현재 단계가 연결된 진행 표시기, 리뷰 단계를 지원합니다.
+
+**Import:** `import { WizardForm } from "@reopt-ai/opt-ui"`
+**Dependencies:** form (core), checkbox (core), radio-group (core)
+
+| Prop           | Type                                        | Required | Default | Description                                |
+| -------------- | ------------------------------------------- | -------- | ------- | ------------------------------------------ |
+| `fields`       | `FormFieldDef[]`                            | Yes      |         | 폼 필드 정의 배열                          |
+| `steps`        | `WizardStepDef[]`                           | Yes      |         | 단계 정의. { id, label, fields: string[] } |
+| `showReview`   | `boolean`                                   |          | true    | 마지막 리뷰 단계 표시 여부                 |
+| `onSubmit`     | `(values: Record<string, unknown>) => void` |          |         | 제출 핸들러                                |
+| `onStepChange` | `(stepIndex: number) => void`               |          |         | 단계 변경 핸들러                           |
+| `labels`       | `WizardFormLabels`                          |          |         | i18n용 라벨 오버라이드                     |
+
+### ConfirmDialog
+
+> 확인/취소 대화 상자. danger 변형으로 위험 작업 확인을 지원합니다.
+
+**Import:** `import { ConfirmDialog } from "@reopt-ai/opt-ui"`
+**Dependencies:** dialog (core)
+
+| Prop           | Type                    | Required | Default   | Description      |
+| -------------- | ----------------------- | -------- | --------- | ---------------- |
+| `open`         | `boolean`               | Yes      |           | 열림 상태        |
+| `onConfirm`    | `() => void`            | Yes      |           | 확인 콜백        |
+| `onCancel`     | `() => void`            | Yes      |           | 취소 콜백        |
+| `title`        | `string`                | Yes      |           | 대화 상자 제목   |
+| `description`  | `string`                |          |           | 설명 텍스트      |
+| `confirmLabel` | `string`                |          | "Confirm" | 확인 버튼 텍스트 |
+| `cancelLabel`  | `string`                |          | "Cancel"  | 취소 버튼 텍스트 |
+| `variant`      | `"default" \| "danger"` |          | "default" | 변형             |
+
+### PromptTemplate
+
+> AI 프롬프트 뷰어/헬퍼. 변수 입력 → 실시간 치환 → 복사 기능.
+
+**Import:** `import { PromptTemplate } from "@reopt-ai/opt-ui"`
+**Dependencies:** input (core)
+
+| Prop          | Type                   | Required | Default | Description                                                  |
+| ------------- | ---------------------- | -------- | ------- | ------------------------------------------------------------ |
+| `title`       | `string`               | Yes      |         | 프롬프트 제목                                                |
+| `description` | `string`               |          |         | 프롬프트 설명 (헤더 아래 표시)                               |
+| `template`    | `string`               | Yes      |         | 프롬프트 템플릿. {변수명}으로 치환 가능                      |
+| `variables`   | `PromptVariable[]`     |          |         | 변수 정의 배열. { name, label, placeholder?, defaultValue? } |
+| `labels`      | `PromptTemplateLabels` |          |         | i18n용 라벨 오버라이드                                       |
+
+## Infrastructure
+
+| Component          | Description                                                                 | Key Exports          |
+| ------------------ | --------------------------------------------------------------------------- | -------------------- |
+| DeploymentTimeline | 배포 단계 타임라인. Composite 기반 키보드 탐색 지원.                        | `DeploymentTimeline` |
+| EnvPanel           | 환경변수 패널. Disclosure로 환경별 그룹 접기/펼치기, Composite로 변수 탐색. | `EnvPanel`           |
+| WebhookConfig      | 웹훅 설정 패널. URL 입력 + 이벤트 체크박스 + 재시도 설정 + 테스트 버튼.     | `WebhookConfig`      |
+| FeatureFlagPanel   | 피처 플래그 관리 패널. 플래그 토글 + 환경 배지 + 롤아웃 % 조절.             | `FeatureFlagPanel`   |
+| DataImportWizard   | 데이터 임포트 마법사. 4단계: 업로드 → 컬럼 매핑 → 미리보기 → 확인.          | `DataImportWizard`   |
+
+### DeploymentTimeline
+
+> 배포 단계 타임라인. Composite 기반 키보드 탐색 지원.
+
+**Import:** `import { DeploymentTimeline } from "@reopt-ai/opt-ui"`
+
+| Prop    | Type               | Required | Default         | Description                                              |
+| ------- | ------------------ | -------- | --------------- | -------------------------------------------------------- |
+| `steps` | `DeploymentStep[]` | Yes      |                 | 배포 단계 배열. { id, name, status, duration?, detail? } |
+| `title` | `string`           |          | "배포 타임라인" | 타임라인 제목                                            |
+
+### EnvPanel
+
+> 환경변수 패널. Disclosure로 환경별 그룹 접기/펼치기, Composite로 변수 탐색.
+
+**Import:** `import { EnvPanel } from "@reopt-ai/opt-ui"`
+**Dependencies:** disclosure (core)
+
+| Prop     | Type            | Required | Default | Description                                |
+| -------- | --------------- | -------- | ------- | ------------------------------------------ |
+| `groups` | `EnvGroupDef[]` | Yes      |         | 환경 그룹 배열. { env, vars: EnvVarDef[] } |
+
+### WebhookConfig
+
+> 웹훅 설정 패널. URL 입력 + 이벤트 체크박스 + 재시도 설정 + 테스트 버튼.
+
+**Import:** `import { WebhookConfig } from "@reopt-ai/opt-ui"`
+**Dependencies:** input (core), checkbox (core), number-input (core), button (core)
+
+| Prop              | Type                            | Required | Default | Description             |
+| ----------------- | ------------------------------- | -------- | ------- | ----------------------- |
+| `webhook`         | `WebhookDef`                    | Yes      |         | 웹훅 설정 객체          |
+| `onChange`        | `(webhook: WebhookDef) => void` | Yes      |         | 변경 콜백               |
+| `availableEvents` | `string[]`                      | Yes      |         | 선택 가능한 이벤트 목록 |
+| `onTest`          | `() => void`                    |          |         | 테스트 버튼 콜백        |
+| `className`       | `string`                        |          |         | 커스텀 CSS 클래스       |
+
+### FeatureFlagPanel
+
+> 피처 플래그 관리 패널. 플래그 토글 + 환경 배지 + 롤아웃 % 조절.
+
+**Import:** `import { FeatureFlagPanel } from "@reopt-ai/opt-ui"`
+**Dependencies:** switch (core), badge (core), number-input (core)
+
+| Prop              | Type                                           | Required | Default | Description        |
+| ----------------- | ---------------------------------------------- | -------- | ------- | ------------------ |
+| `flags`           | `FeatureFlag[]`                                | Yes      |         | 피처 플래그 목록   |
+| `onToggle`        | `(flagId: string, enabled: boolean) => void`   | Yes      |         | 토글 콜백          |
+| `onRolloutChange` | `(flagId: string, percentage: number) => void` |          |         | 롤아웃 % 변경 콜백 |
+| `environments`    | `string[]`                                     | Yes      |         | 전체 환경 목록     |
+| `className`       | `string`                                       |          |         | 커스텀 CSS 클래스  |
+
+### DataImportWizard
+
+> 데이터 임포트 마법사. 4단계: 업로드 → 컬럼 매핑 → 미리보기 → 확인.
+
+**Import:** `import { DataImportWizard } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core)
+
+| Prop              | Type                      | Required | Default | Description         |
+| ----------------- | ------------------------- | -------- | ------- | ------------------- |
+| `fields`          | `ImportFieldDef[]`        | Yes      |         | 매핑 대상 필드 목록 |
+| `onImport`        | `(mapping, data) => void` | Yes      |         | 임포트 확정 콜백    |
+| `acceptedFormats` | `string`                  |          | ".csv"  | 허용 파일 형식      |
+| `className`       | `string`                  |          |         | 커스텀 CSS 클래스   |
+
+## Analytics
+
+| Component        | Description                                                                                                      | Key Exports        |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------ |
+| SqlEditor        | SQL 에디터. CodeMirror 기반의 SQL 편집기로 구문 강조와 자동 완성을 지원합니다.                                   | `SqlEditor`        |
+| EventMetaEditor  | 이벤트 메타 에디터. 레이블이 연결된 IconPicker + ColorPicker + TagInput 조합으로 이벤트 메타데이터를 편집합니다. | `EventMetaEditor`  |
+| PropertyExplorer | 프로퍼티 탐색기. 검색 가능한 속성 목록을 그룹별로 표시합니다.                                                    | `PropertyExplorer` |
+| RichTextEditor   | 마크다운 리치 텍스트 에디터. 서식 툴바 + textarea 조합.                                                          | `RichTextEditor`   |
+| ExportButton     | 데이터 내보내기 버튼. CSV/JSON 변환 내장, PDF는 콜백 위임. DropdownMenu 기반.                                    | `ExportButton`     |
+| InsightsPanel    | 이상 탐지 인사이트 패널. severity별 카드, 통계 필터, dismiss 기능, 검출 설정(유형/Z-score/days).                 | `InsightsPanel`    |
+
+### SqlEditor
+
+> SQL 에디터. CodeMirror 기반의 SQL 편집기로 구문 강조와 자동 완성을 지원합니다.
+
+**Import:** `import { SqlEditor } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core)
+
+### EventMetaEditor
+
+> 이벤트 메타 에디터. 레이블이 연결된 IconPicker + ColorPicker + TagInput 조합으로 이벤트 메타데이터를 편집합니다.
+
+**Import:** `import { EventMetaEditor } from "@reopt-ai/opt-ui"`
+**Dependencies:** input (core), icon-picker (core), color-picker (core), tag-input (core)
+
+### PropertyExplorer
+
+> 프로퍼티 탐색기. 검색 가능한 속성 목록을 그룹별로 표시합니다.
+
+**Import:** `import { PropertyExplorer } from "@reopt-ai/opt-ui"`
+**Dependencies:** input (core)
+
+### RichTextEditor
+
+> 마크다운 리치 텍스트 에디터. 서식 툴바 + textarea 조합.
+
+**Import:** `import { RichTextEditor } from "@reopt-ai/opt-ui"`
+
+| Prop          | Type                      | Required | Default                                                  | Description       |
+| ------------- | ------------------------- | -------- | -------------------------------------------------------- | ----------------- |
+| `value`       | `string`                  | Yes      |                                                          | 텍스트 값         |
+| `onChange`    | `(value: string) => void` | Yes      |                                                          | 변경 콜백         |
+| `placeholder` | `string`                  |          | "Write something…"                                       | 플레이스홀더      |
+| `toolbar`     | `ToolbarAction[]`         |          | ["bold","italic","code","link","heading","list","quote"] | 툴바 액션 목록    |
+| `className`   | `string`                  |          |                                                          | 커스텀 CSS 클래스 |
+
+### ExportButton
+
+> 데이터 내보내기 버튼. CSV/JSON 변환 내장, PDF는 콜백 위임. DropdownMenu 기반.
+
+**Import:** `import { ExportButton } from "@reopt-ai/opt-ui"`
+**Dependencies:** dropdown-menu (core), button (core)
+
+| Prop       | Type                             | Required | Default         | Description              |
+| ---------- | -------------------------------- | -------- | --------------- | ------------------------ |
+| `data`     | `Record<string, unknown>[]`      | Yes      |                 | 내보낼 데이터 배열       |
+| `columns`  | `ExportColumn[]`                 |          |                 | 컬럼 매핑 (key → header) |
+| `fileName` | `string`                         |          | "export"        | 파일 이름                |
+| `formats`  | `ExportFormat[]`                 |          | ["csv", "json"] | 지원 포맷                |
+| `onExport` | `(format: ExportFormat) => void` |          |                 | 커스텀 내보내기 핸들러   |
+
+### InsightsPanel
+
+> 이상 탐지 인사이트 패널. severity별 카드, 통계 필터, dismiss 기능, 검출 설정(유형/Z-score/days).
+
+**Import:** `import { InsightsPanel } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), stat-card (core), badge (core)
+
+| Prop                      | Type                                | Required | Default | Description                                        |
+| ------------------------- | ----------------------------------- | -------- | ------- | -------------------------------------------------- |
+| `insights`                | `InsightItem[]`                     | Yes      |         | 인사이트 항목 배열                                 |
+| `stats`                   | `InsightsStat[]`                    |          |         | 통계 필터 카드 배열 (클릭 가능)                    |
+| `detectionTypes`          | `DetectionTypeDef[]`                |          |         | 검출 유형 토글 배열 (volume_anomaly, new_event 등) |
+| `detectionConfig`         | `DetectionConfig`                   |          |         | 검출 파라미터 (days, zScoreThreshold)              |
+| `onDetectionConfigChange` | `(config: DetectionConfig) => void` |          |         | 검출 파라미터 변경 핸들러                          |
+| `onDismiss`               | `(id: string) => void`              |          |         | 인사이트 dismiss 핸들러                            |
+
+## Builders
+
+| Component      | Description                                                                                                        | Key Exports      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------- |
+| AlertBuilder   | 알림 빌더. 명시적으로 연결된 폼 레이블로 메트릭 조건, 빈도, 채널을 구성합니다.                                     | `AlertBuilder`   |
+| SegmentBuilder | 세그먼트 빌더. 각 조건 컨트롤의 접근 가능한 이름을 유지하며 event, property, cohort, custom 세그먼트를 정의합니다. | `SegmentBuilder` |
+| ReportBuilder  | 리포트 빌더. 레이블이 연결된 4단계 위저드 (차트 타입 → 데이터 설정 → 스타일 → 미리보기).                           | `ReportBuilder`  |
+
+### AlertBuilder
+
+> 알림 빌더. 명시적으로 연결된 폼 레이블로 메트릭 조건, 빈도, 채널을 구성합니다.
+
+**Import:** `import { AlertBuilder } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), input (core)
+
+### SegmentBuilder
+
+> 세그먼트 빌더. 각 조건 컨트롤의 접근 가능한 이름을 유지하며 event, property, cohort, custom 세그먼트를 정의합니다.
+
+**Import:** `import { SegmentBuilder } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), input (core)
+
+### ReportBuilder
+
+> 리포트 빌더. 레이블이 연결된 4단계 위저드 (차트 타입 → 데이터 설정 → 스타일 → 미리보기).
+
+**Import:** `import { ReportBuilder } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), input (core)
+
+| Prop          | Type                                                               | Required | Default | Description                         |
+| ------------- | ------------------------------------------------------------------ | -------- | ------- | ----------------------------------- |
+| `chartTypes`  | `ChartTypeDef[]`                                                   |          |         | 차트 타입 그리드 (기본 9종 제공)    |
+| `dataSources` | `DataSourceDef[]`                                                  |          |         | 데이터 소스 드롭다운 옵션           |
+| `configForm`  | `ReactNode`                                                        |          |         | 차트별 데이터 설정 폼 슬롯 (step 2) |
+| `styleForm`   | `ReactNode`                                                        |          |         | 차트별 스타일 설정 폼 슬롯 (step 3) |
+| `preview`     | `ReactNode`                                                        |          |         | 차트 미리보기 슬롯 (step 4)         |
+| `onSave`      | `(report: { name, description, chartType, dataSourceId }) => void` |          |         | 저장 콜백                           |
+| `onCancel`    | `() => void`                                                       |          |         | 취소 콜백                           |
+| `labels`      | `ReportBuilderLabels`                                              |          |         | UI 텍스트 커스터마이징              |
+
+## Widgets & Reports
+
+| Component  | Description                                                                              | Key Exports  |
+| ---------- | ---------------------------------------------------------------------------------------- | ------------ |
+| WidgetGrid | 위젯 그리드. react-grid-layout 래퍼로 드래그/리사이즈 가능한 대시보드 위젯을 배치합니다. | `WidgetGrid` |
+
+### WidgetGrid
+
+> 위젯 그리드. react-grid-layout 래퍼로 드래그/리사이즈 가능한 대시보드 위젯을 배치합니다.
+
+**Import:** `import { WidgetGrid } from "@reopt-ai/opt-ui"`
+
+## Notification
+
+| Component         | Description                                                                                                               | Key Exports                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| NotificationToast | 토스트 알림 시스템. 포인터/키보드 상호작용 중 자동 닫힘을 일시 정지하고, 중요도별 live region으로 전역 알림을 관리합니다. | `ToastProvider`, `useToast`, `NotificationToast`, `toast` |
+
+### NotificationToast
+
+> 토스트 알림 시스템. 포인터/키보드 상호작용 중 자동 닫힘을 일시 정지하고, 중요도별 live region으로 전역 알림을 관리합니다.
+
+**Import:** `import { ToastProvider } from "@reopt-ai/opt-ui"`
+**Dependencies:** alert (core)
+
+**ToastProvider:**
+
+| Prop              | Type                                                           | Required | Default     | Description         |
+| ----------------- | -------------------------------------------------------------- | -------- | ----------- | ------------------- |
+| `children`        | `ReactNode`                                                    | Yes      |             | 앱 컨텐츠           |
+| `position`        | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` |          | "top-right" | 토스트 표시 위치    |
+| `defaultDuration` | `number`                                                       |          | 5000        | 기본 표시 시간 (ms) |
+
+**useToast:**
+
+| Prop      | Type                                | Required | Default | Description              |
+| --------- | ----------------------------------- | -------- | ------- | ------------------------ |
+| `returns` | `{ toasts, addToast, removeToast }` |          |         | 토스트 상태 및 제어 함수 |
+
+**toast:**
+
+| Prop                                     | Type                                    | Required | Default | Description                                                                          |
+| ---------------------------------------- | --------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------ |
+| `toast.success / error / info / warning` | `(message: string, options?) => string` |          |         | 훅 없이 어디서든 호출하는 프로그램매틱 API. toast.dismiss(id) / toast.clear()도 제공 |
+
+**NotificationToast:**
+
+| Prop        | Type           | Required | Default | Description        |
+| ----------- | -------------- | -------- | ------- | ------------------ |
+| `toast`     | `ToastMessage` | Yes      |         | 토스트 메시지 객체 |
+| `onDismiss` | `() => void`   | Yes      |         | 닫기 핸들러        |
+
+## Development
+
+| Component        | Description                                                                                         | Key Exports        |
+| ---------------- | --------------------------------------------------------------------------------------------------- | ------------------ |
+| DesignGuidePanel | 디자인 시스템 참조 패널. 프리미티브 맵, 키보드 패턴, Tailwind 셀렉터, 접근성 속성 등 6개 섹션 제공. | `DesignGuidePanel` |
+
+### DesignGuidePanel
+
+> 디자인 시스템 참조 패널. 프리미티브 맵, 키보드 패턴, Tailwind 셀렉터, 접근성 속성 등 6개 섹션 제공.
+
+**Import:** `import { DesignGuidePanel } from "@reopt-ai/opt-ui"`
+
+| Prop        | Type     | Required | Default | Description     |
+| ----------- | -------- | -------- | ------- | --------------- |
+| `className` | `string` |          |         | 추가 CSS 클래스 |
+
+## Workflow
+
+| Component      | Description                                                                        | Key Exports      |
+| -------------- | ---------------------------------------------------------------------------------- | ---------------- |
+| WorkflowCanvas | 워크플로우 캔버스. 그리드 셀 기반 스텝 배치, SVG 연결선, 키보드 이동을 지원합니다. | `WorkflowCanvas` |
+
+### WorkflowCanvas
+
+> 워크플로우 캔버스. 그리드 셀 기반 스텝 배치, SVG 연결선, 키보드 이동을 지원합니다.
+
+**Import:** `import { WorkflowCanvas } from "@reopt-ai/opt-ui"`
+**Dependencies:** badge (core)
+
+| Prop           | Type                                                 | Required | Default | Description                                 |
+| -------------- | ---------------------------------------------------- | -------- | ------- | ------------------------------------------- |
+| `steps`        | `WorkflowCanvasStep[]`                               | Yes      |         | 스텝 배열. { id, title, row, col, status? } |
+| `connections`  | `WorkflowCanvasConnection[]`                         |          | []      | 연결선 배열. { from, to, label? }           |
+| `onStepMove`   | `(stepId: string, row: number, col: number) => void` |          |         | 화살표 키 이동 핸들러                       |
+| `onSelectStep` | `(step: WorkflowCanvasStep) => void`                 |          |         | 스텝 선택 핸들러                            |
+
+## Other
+
+| Component       | Description                                                                | Key Exports       |
+| --------------- | -------------------------------------------------------------------------- | ----------------- |
+| PageAside       | Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.  | `PageAside`       |
+| FailureList     | 실패 목록 패널. severity별 색상 강조, 그룹핑, 액션 슬롯을 지원합니다.      | `FailureList`     |
+| KeyValueEditor  | 키-값 쌍 편집기. 동적 행 추가/삭제, 비밀값 토글, 유효성 검사를 지원합니다. | `KeyValueEditor`  |
+| AuditTimeline   | 변경 이력 타임라인. 액션별 색상 코딩 + 확장 가능한 diff 뷰.                | `AuditTimeline`   |
+| ChatSidebar     | AI 채팅 사이드바. 대화 목록, 검색, 새 대화 버튼.                           | `ChatSidebar`     |
+| ChatInput       | 채팅 입력 컴포넌트. 자동 리사이즈 textarea, 파일 첨부, 모델/스타일 Select. | `ChatInput`       |
+| ChatMessageList | 채팅 메시지 목록. 역할별 말풍선, 타이핑 인디케이터, 자동 스크롤.           | `ChatMessageList` |
+
+### PageAside
+
+> Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.
+
+**Import:** `import { PageAside } from "@reopt-ai/opt-ui"`
+
+| Prop             | Type        | Required | Default | Description                            |
+| ---------------- | ----------- | -------- | ------- | -------------------------------------- |
+| `header`         | `ReactNode` |          |         | 상단 고정 슬롯 (예: package switcher). |
+| `children`       | `ReactNode` | Yes      |         | 스크롤 가능한 네비게이션 영역.         |
+| `footer`         | `ReactNode` |          |         | 하단 고정 슬롯 (예: version label).    |
+| `widthClassName` | `string`    |          |         | 너비 Tailwind 클래스. 기본값 `w-60`.   |
+| `label`          | `string`    |          |         | `<aside>`의 aria-label.                |
+| `hideOnMobile`   | `boolean`   |          |         | md 아래에서 숨김. 기본값 true.         |
+
+### FailureList
+
+> 실패 목록 패널. severity별 색상 강조, 그룹핑, 액션 슬롯을 지원합니다.
+
+**Import:** `import { FailureList } from "@reopt-ai/opt-ui"`
+**Dependencies:** badge (core)
+
+| Prop             | Type                                  | Required | Default     | Description                                                          |
+| ---------------- | ------------------------------------- | -------- | ----------- | -------------------------------------------------------------------- |
+| `failures`       | `FailureItem[]`                       | Yes      |             | 실패 항목 배열. { id, title, message?, severity, timestamp, group? } |
+| `title`          | `string`                              |          | "최근 실패" | 섹션 제목                                                            |
+| `maxItems`       | `number`                              |          |             | 최대 표시 개수                                                       |
+| `grouped`        | `boolean`                             |          | false       | group 필드 기준으로 그룹핑 표시                                      |
+| `onFailureClick` | `(failure: FailureItem) => void`      |          |             | 실패 항목 클릭 핸들러                                                |
+| `renderActions`  | `(failure: FailureItem) => ReactNode` |          |             | 각 항목 우측 액션 슬롯 렌더 함수                                     |
+
+### KeyValueEditor
+
+> 키-값 쌍 편집기. 동적 행 추가/삭제, 비밀값 토글, 유효성 검사를 지원합니다.
+
+**Import:** `import { KeyValueEditor } from "@reopt-ai/opt-ui"`
+
+| Prop               | Type                                                             | Required | Default | Description                       |
+| ------------------ | ---------------------------------------------------------------- | -------- | ------- | --------------------------------- |
+| `value`            | `KeyValueEntry[]`                                                |          |         | 현재 엔트리 (controlled 모드)     |
+| `defaultValue`     | `KeyValueEntry[]`                                                |          |         | 초기 엔트리 (uncontrolled 모드)   |
+| `onChange`         | `(entries: KeyValueEntry[]) => void`                             |          |         | 엔트리 변경 핸들러                |
+| `showSecretToggle` | `boolean`                                                        |          | false   | 비밀값 표시/숨김 토글 버튼 활성화 |
+| `maxEntries`       | `number`                                                         |          |         | 최대 항목 수 제한                 |
+| `readOnly`         | `boolean`                                                        |          | false   | 읽기 전용 모드                    |
+| `labels`           | `KeyValueEditorLabels`                                           |          |         | i18n 라벨 오버라이드              |
+| `renderActions`    | `(entry: KeyValueEntry, index: number) => ReactNode`             |          |         | 항목별 커스텀 액션 슬롯           |
+| `validateKey`      | `(key: string, entries: KeyValueEntry[]) => string \| undefined` |          |         | 키 유효성 검사 함수               |
+
+### AuditTimeline
+
+> 변경 이력 타임라인. 액션별 색상 코딩 + 확장 가능한 diff 뷰.
+
+**Import:** `import { AuditTimeline } from "@reopt-ai/opt-ui"`
+**Dependencies:** badge (core), button (core), empty-state (core)
+
+| Prop           | Type                          | Required | Default | Description            |
+| -------------- | ----------------------------- | -------- | ------- | ---------------------- |
+| `entries`      | `AuditEntry[]`                | Yes      |         | 변경 이력 항목 배열    |
+| `labels`       | `AuditTimelineLabels`         |          |         | UI 텍스트 커스터마이징 |
+| `onEntryClick` | `(entry: AuditEntry) => void` |          |         | 항목 클릭 콜백         |
+| `className`    | `string`                      |          |         | 커스텀 CSS 클래스      |
+
+### ChatSidebar
+
+> AI 채팅 사이드바. 대화 목록, 검색, 새 대화 버튼.
+
+**Import:** `import { ChatSidebar } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), input (core), scroll-area (core), empty-state (core)
+
+| Prop                   | Type                                          | Required | Default | Description                                                     |
+| ---------------------- | --------------------------------------------- | -------- | ------- | --------------------------------------------------------------- |
+| `conversations`        | `ChatConversationDef[]`                       | Yes      |         | 대화 목록 배열. { id, title, lastMessage?, timestamp, unread? } |
+| `activeConversationId` | `string`                                      |          |         | 현재 활성 대화 ID                                               |
+| `onConversationSelect` | `(conversation: ChatConversationDef) => void` |          |         | 대화 선택 핸들러                                                |
+| `onNewChat`            | `() => void`                                  |          |         | 새 대화 생성 핸들러                                             |
+| `onSearch`             | `(query: string) => void`                     |          |         | 검색 핸들러                                                     |
+| `labels`               | `ChatSidebarLabels`                           |          |         | i18n 라벨 오버라이드                                            |
+
+### ChatInput
+
+> 채팅 입력 컴포넌트. 자동 리사이즈 textarea, 파일 첨부, 모델/스타일 Select.
+
+**Import:** `import { ChatInput } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core), kbd (core), select (core)
+
+| Prop           | Type                        | Required | Default | Description                |
+| -------------- | --------------------------- | -------- | ------- | -------------------------- |
+| `value`        | `string`                    |          |         | 제어 모드: 입력 값         |
+| `onSend`       | `(message: string) => void` |          |         | 메시지 전송 핸들러         |
+| `onFileAttach` | `() => void`                |          |         | 파일 첨부 클릭 핸들러      |
+| `models`       | `ChatModelDef[]`            |          |         | 모델 선택 옵션             |
+| `stylePresets` | `ChatStylePresetDef[]`      |          |         | 스타일 프리셋 옵션         |
+| `maxRows`      | `number`                    |          | 6       | textarea 최대 행 수        |
+| `showHint`     | `boolean`                   |          | true    | Shift+Enter 힌트 표시 여부 |
+| `labels`       | `ChatInputLabels`           |          |         | i18n 라벨 오버라이드       |
+
+**Examples:**
+
+_채팅 입력:_
+
+```tsx
+import { ChatInput } from "@reopt-ai/opt-ui";
+
+<ChatInput
+  placeholder="메시지를 입력하세요..."
+  onSend={(message) => console.log(message)}
+/>;
+```
+
+### ChatMessageList
+
+> 채팅 메시지 목록. 역할별 말풍선, 타이핑 인디케이터, 자동 스크롤.
+
+**Import:** `import { ChatMessageList } from "@reopt-ai/opt-ui"`
+**Dependencies:** scroll-area (core), avatar (core), empty-state (core)
+
+| Prop              | Type                                     | Required | Default | Description                                   |
+| ----------------- | ---------------------------------------- | -------- | ------- | --------------------------------------------- |
+| `messages`        | `ChatMessageDef[]`                       | Yes      |         | 메시지 배열. { id, role, content, timestamp } |
+| `loading`         | `boolean`                                |          | false   | 타이핑 인디케이터 표시                        |
+| `renderContent`   | `(message: ChatMessageDef) => ReactNode` |          |         | 커스텀 메시지 렌더러. 기본: plain text        |
+| `assistantAvatar` | `string`                                 |          |         | 어시스턴트 아바타 이미지 URL                  |
+| `showTimestamps`  | `boolean`                                |          | true    | 타임스탬프 표시 여부                          |
+| `autoScroll`      | `boolean`                                |          | true    | 새 메시지 시 자동 스크롤                      |
+| `labels`          | `ChatMessageListLabels`                  |          |         | i18n 라벨 오버라이드                          |
+
+**Examples:**
+
+_메시지 목록:_
+
+```tsx
+import { ChatMessageList } from "@reopt-ai/opt-ui";
+
+const messages = [
+  { id: "1", role: "user", content: "안녕하세요!", timestamp: new Date() },
+  { id: "2", role: "assistant", content: "반갑습니다.", timestamp: new Date() },
+];
+
+<ChatMessageList messages={messages} loading={false} />;
+```