@reopt-ai/opt-ui 1.4.1 → 1.6.0

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

@@ -1,7 +1,7 @@
 ---
 title: "Shell Components"
 description: "75 Shell layer components — props, examples, keyboard shortcuts."
-version: "1.4.1"
+version: "1.6.0"
 generated: true
 ---
 
@@ -9,23 +9,23 @@ generated: true
 
 ## 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`         |
+| 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영역 페이지 레이아웃 템플릿. AppShell.Sidebar는 모든 viewport에서 기본 표시되며 반응형 숨김/Drawer 전환은 소비자가 제어합니다. | `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
 
@@ -106,9 +106,17 @@ generated: true
 | `badge`     | `ReactNode`  |          |         | 우측 배지 (숫자/텍스트). 접힌 상태에서 아이콘 위 dot으로 축소 |
 | `className` | `string`     |          |         | 커스텀 CSS 클래스                                             |
 
+**Keyboard Shortcuts:**
+
+| Keys         | Action                                |
+| ------------ | ------------------------------------- |
+| `Ctrl+[`     | 사이드바 접기/펼치기 토글             |
+| `↑ ↓`        | 사이드바 항목 간 이동                 |
+| `Home / End` | 첫 번째/마지막 사이드바 항목으로 이동 |
+
 ### AppShell
 
-> Header + Sidebar + Content + Footer 4영역 페이지 레이아웃 템플릿. Sidebar 컴포넌트와 조합.
+> Header + Sidebar + Content + Footer 4영역 페이지 레이아웃 템플릿. AppShell.Sidebar는 모든 viewport에서 기본 표시되며 반응형 숨김/Drawer 전환은 소비자가 제어합니다.
 
 **Import:** `import { AppShell } from "@reopt-ai/opt-ui"`
 **Dependencies:** sidebar (shells), page-header (core)
@@ -298,6 +306,17 @@ import { AppShell } from "@reopt-ai/opt-ui";
 | `bar`      | `(row: T) => number` |          |             | 인라인 프로그레스 바 비율(0-1) 계산 함수. 범위 밖/NaN은 보정 |
 | `barColor` | `string`             |          | "bg-accent" | 인라인 바 색상 클래스                                        |
 
+**Keyboard Shortcuts:**
+
+| Keys                             | Action                             |
+| -------------------------------- | ---------------------------------- |
+| `↑ ↓`                            | 행 탐색                            |
+| `← →`                            | 셀 탐색                            |
+| `Enter / Space`                  | 정렬 가능한 헤더 또는 행 활성화    |
+| `리사이즈 핸들: ← →`             | 컬럼 너비를 10px 단위로 조절       |
+| `리사이즈 핸들: Shift+← Shift+→` | 컬럼 너비를 40px 단위로 조절       |
+| `리사이즈 핸들: Home / End`      | 컬럼 너비를 최솟값/최댓값으로 이동 |
+
 **Examples:**
 
 _기본 테이블:_
@@ -401,6 +420,13 @@ import { DataTable } from "@reopt-ai/opt-ui";
 | `stats`   | `StatCard[]` | Yes      |         | 통계 데이터 배열. { id, title, value, change, trend } |
 | `columns` | `number`     |          | 3       | 행당 컬럼 수                                          |
 
+**Keyboard Shortcuts:**
+
+| Keys      | Action             |
+| --------- | ------------------ |
+| `↑ ↓ ← →` | 카드 간 2D 탐색    |
+| `Tab`     | 다음 섹션으로 이동 |
+
 ### SummaryRow
 
 > 통계 요약 행. StatCard 그리드 레이아웃을 표준화합니다. loading 시 SkeletonCard 표시.
@@ -457,6 +483,15 @@ import { DataTable } from "@reopt-ai/opt-ui";
 
 **Import:** `import { ConnectionIndicator } from "@reopt-ai/opt-ui"`
 
+| Prop        | Type                                                        | Required | Default | Description                                                           |
+| ----------- | ----------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------- |
+| `status`    | `"connected" \| "connecting" \| "disconnected" \| "error"`  |          |         | 연결 상태 프리셋. tone과 pulse의 기본값을 정함                        |
+| `tone`      | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` |          |         | status로 표현되지 않는 도메인 상태의 색을 직접 지정 (status보다 우선) |
+| `label`     | `string`                                                    |          |         | 상태 문구                                                             |
+| `showLabel` | `boolean`                                                   |          |         | 문구 표시 여부                                                        |
+| `pulse`     | `boolean`                                                   |          |         | 점 애니메이션. 생략하면 status 프리셋을 따름                          |
+| `className` | `string`                                                    |          |         | 기본 스타일 오버라이드                                                |
+
 ### EventIcon
 
 > 이벤트 아이콘. semantic key 또는 ReactNode 아이콘과 배경색을 표시합니다.
@@ -495,6 +530,14 @@ import { DataTable } from "@reopt-ai/opt-ui";
 | `onTaskStatusChange` | `(task: TaskDef, completed: boolean) => void` |          |             | 완료 상태 변경 핸들러                                      |
 | `showSubtasks`       | `boolean`                                     |          | false       | 하위 작업 표시 여부                                        |
 
+**Keyboard Shortcuts:**
+
+| Keys    | Action       |
+| ------- | ------------ |
+| `↑ ↓`   | 작업 간 이동 |
+| `Enter` | 작업 선택    |
+| `Space` | 완료 토글    |
+
 ### ActivityFeed
 
 > 활동 피드/로그 컴포넌트. 타임라인 스타일, 상대 시간 표시.
@@ -511,6 +554,13 @@ import { DataTable } from "@reopt-ai/opt-ui";
 | `layout`          | `"list" \| "compact"`                  |          | "list"      | 시간 표시 레이아웃 모드                               |
 | `renderActions`   | `(activity: ActivityDef) => ReactNode` |          |             | 각 활동 항목 우측 액션 슬롯 렌더 함수                 |
 
+**Keyboard Shortcuts:**
+
+| Keys    | Action       |
+| ------- | ------------ |
+| `↑ ↓`   | 활동 간 이동 |
+| `Enter` | 활동 선택    |
+
 ### TeamMemberList
 
 > 팀원 목록 컴포넌트. 온라인 상태, 다양한 레이아웃(list, compact, avatars-only) 지원.
@@ -526,6 +576,13 @@ import { DataTable } from "@reopt-ai/opt-ui";
 | `maxDisplay`    | `number`                                |          |         | 최대 표시 인원                                          |
 | `onMemberClick` | `(member: TeamMemberDef) => void`       |          |         | 팀원 클릭 핸들러                                        |
 
+**Keyboard Shortcuts:**
+
+| Keys    | Action       |
+| ------- | ------------ |
+| `↑ ↓`   | 팀원 간 이동 |
+| `Enter` | 팀원 선택    |
+
 ### KanbanBoard
 
 > 칸반 보드. HTML5 DnD로 카드를 컬럼 간 드래그&드롭.
@@ -579,7 +636,7 @@ import { DataTable } from "@reopt-ai/opt-ui";
 | StatusSelect       | 색상 인디케이터가 있는 상태 선택 드롭다운.                                                                         | `StatusSelect`       |
 | BranchSelect       | Git 브랜치 선택 드롭다운. Select primitive 래퍼.                                                                   | `BranchSelect`       |
 | FilterBar          | 필터링 바 컴포넌트. 검색, 선택, 다중 선택 필터 지원.                                                               | `FilterBar`          |
-| SavedFilters       | 필터 프리셋 관리. 현재 필터를 저장하고 불러오는 Popover UI.                                                        | `SavedFilters`       |
+| SavedFilters       | 필터 프리셋 관리. 키보드 목록 탐색, 현재 필터 저장, 안전한 삭제 확인 흐름을 제공하는 Popover UI.                   | `SavedFilters`       |
 | QuickActions       | 빠른 작업 패널. 그리드/리스트 레이아웃, 단축키 표시 지원.                                                          | `QuickActions`       |
 | TimeRangeSelector  | 시간 범위 선택기. Popover + DateRangePicker + 프리셋 버튼 조합. 12개 시계열 Surface에서 사용.                      | `TimeRangeSelector`  |
 | ComparisonSelector | 비교 선택기. 고유 레이블이 연결된 Select × 2 + Swap 버튼 조합. CohortComparison, FunnelAnalysis 등에서 사용합니다. | `ComparisonSelector` |
@@ -697,19 +754,43 @@ const filters = [
 
 ### SavedFilters
 
-> 필터 프리셋 관리. 현재 필터를 저장하고 불러오는 Popover UI.
+> 필터 프리셋 관리. 키보드 목록 탐색, 현재 필터 저장, 안전한 삭제 확인 흐름을 제공하는 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 클래스    |
+**Dependencies:** popover (core), input (core), button (core)
+
+**SavedFilters:**
+
+| 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      |         | 프리셋 삭제 콜백                                   |
+| `labels`         | `SavedFiltersLabels`                                       |          |         | 트리거, 빈 상태, 저장 및 삭제 확인 문구 오버라이드 |
+| `className`      | `string`                                                   |          |         | 커스텀 CSS 클래스                                  |
+
+**SavedFiltersLabels:**
+
+| Prop                 | Type                        | Required | Default            | Description                             |
+| -------------------- | --------------------------- | -------- | ------------------ | --------------------------------------- |
+| `triggerLabel`       | `(count: number) => string` |          |                    | 저장된 프리셋 수를 포함한 트리거 레이블 |
+| `emptyMessage`       | `string`                    |          | "No saved filters" | 프리셋이 없을 때 표시할 메시지          |
+| `deleteLabel`        | `(name: string) => string`  |          |                    | 프리셋 삭제 버튼의 접근 가능한 이름     |
+| `namePlaceholder`    | `string`                    |          | "Filter name…"     | 새 프리셋 이름 입력 안내                |
+| `saveLabel`          | `string`                    |          | "Save"             | 새 프리셋 저장 버튼 레이블              |
+| `confirmDeleteLabel` | `string`                    |          | "Confirm"          | 삭제 확인 버튼 레이블                   |
+| `cancelDeleteLabel`  | `string`                    |          | "Cancel"           | 삭제 취소 버튼 레이블                   |
+
+**Keyboard Shortcuts:**
+
+| Keys         | Action                                      |
+| ------------ | ------------------------------------------- |
+| `↑ ↓`        | 저장된 프리셋 간 이동                       |
+| `Home / End` | 첫 번째/마지막 프리셋으로 이동              |
+| `Enter`      | 프리셋 불러오기 또는 새 프리셋 저장         |
+| `Escape`     | 삭제 확인 취소 후 삭제 버튼으로 포커스 복귀 |
 
 ### QuickActions
 
@@ -725,6 +806,14 @@ const filters = [
 | `layout`  | `"grid" \| "list"` |          | "grid"      | 레이아웃 모드                                                     |
 | `columns` | `2 \| 3 \| 4`      |          | 3           | 그리드 컬럼 수                                                    |
 
+**Keyboard Shortcuts:**
+
+| Keys      | Action                |
+| --------- | --------------------- |
+| `↑ ↓ ← →` | 그리드에서 4방향 탐색 |
+| `↑ ↓`     | 리스트에서 수직 탐색  |
+| `Enter`   | 작업 실행             |
+
 ### TimeRangeSelector
 
 > 시간 범위 선택기. Popover + DateRangePicker + 프리셋 버튼 조합. 12개 시계열 Surface에서 사용.
@@ -864,17 +953,17 @@ const fields = [
 **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 슬롯 (파일 선택 후 표시) |
+| 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
 
@@ -1019,6 +1108,25 @@ const fields = [
 **Import:** `import { SqlEditor } from "@reopt-ai/opt-ui"`
 **Dependencies:** button (core)
 
+| Prop                | Type                          | Required | Default | Description                                                                      |
+| ------------------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------- |
+| `value`             | `string`                      | Yes      |         | 편집 중인 SQL                                                                    |
+| `onChange`          | `(sql: string) => void`       | Yes      |         | 본문 변경 핸들러                                                                 |
+| `onRun`             | `(sql: string) => void`       |          |         | Mod+Enter 실행 핸들러                                                            |
+| `onRunAndAdvance`   | `(sql: string) => void`       |          |         | Shift+Enter — 실행 후 다음 셀/탭으로 이동                                        |
+| `schema`            | `SqlEditorSchema`             |          |         | 테이블/컬럼 자동완성 스키마. 변경 시 에디터를 다시 만들지 않고 자동완성만 재구성 |
+| `completionSources` | `SqlEditorCompletionSource[]` |          |         | 스키마 자동완성에 더할 완성 소스 (함수 시그니처, 스니펫)                         |
+| `keymap`            | `SqlEditorKeyBinding[]`       |          |         | 추가 키 바인딩. 내장 실행 바인딩보다 먼저 평가                                   |
+| `extensions`        | `SqlEditorExtension[]`        |          |         | 임의의 CodeMirror 확장. 내장 확장 뒤에 붙어 우선권을 가짐                        |
+| `height`            | `number \| "fill"`            |          |         | px 고정 높이. fill이면 부모가 정한 높이를 채움                                   |
+| `placeholder`       | `string`                      |          |         | 빈 편집기 안내 문구                                                              |
+| `readOnly`          | `boolean`                     |          |         | 편집 잠금                                                                        |
+| `ariaLabel`         | `string`                      |          |         | 편집 영역 접근성 레이블                                                          |
+| `autoFocus`         | `boolean`                     |          |         | 마운트 시 포커스                                                                 |
+| `showFooter`        | `boolean`                     |          |         | 실행 힌트/버튼 표시. 기본값은 onRun이 있을 때 표시                               |
+| `labels`            | `SqlEditorLabels`             |          |         | 문구 오버라이드                                                                  |
+| `className`         | `string`                      |          |         | 기본 스타일 오버라이드                                                           |
+
 ### EventMetaEditor
 
 > 이벤트 메타 에디터. 레이블이 연결된 IconPicker + ColorPicker + TagInput 조합으로 이벤트 메타데이터를 편집합니다.
@@ -1206,6 +1314,13 @@ const fields = [
 | `onStepMove`   | `(stepId: string, row: number, col: number) => void` |          |         | 화살표 키 이동 핸들러                       |
 | `onSelectStep` | `(step: WorkflowCanvasStep) => void`                 |          |         | 스텝 선택 핸들러                            |
 
+**Keyboard Shortcuts:**
+
+| Keys      | Action                              |
+| --------- | ----------------------------------- |
+| `↑ ↓ ← →` | 선택 스텝 이동 (onStepMove 제공 시) |
+| `Enter`   | 스텝 선택                           |
+
 ## Other
 
 | Component       | Description                                                                | Key Exports       |
@@ -1249,6 +1364,13 @@ const fields = [
 | `onFailureClick` | `(failure: FailureItem) => void`      |          |             | 실패 항목 클릭 핸들러                                                |
 | `renderActions`  | `(failure: FailureItem) => ReactNode` |          |             | 각 항목 우측 액션 슬롯 렌더 함수                                     |
 
+**Keyboard Shortcuts:**
+
+| Keys    | Action            |
+| ------- | ----------------- |
+| `↑ ↓`   | 실패 항목 간 이동 |
+| `Enter` | 실패 항목 선택    |
+
 ### KeyValueEditor
 
 > 키-값 쌍 편집기. 동적 행 추가/삭제, 비밀값 토글, 유효성 검사를 지원합니다.
@@ -1267,6 +1389,12 @@ const fields = [
 | `renderActions`    | `(entry: KeyValueEntry, index: number) => ReactNode`             |          |         | 항목별 커스텀 액션 슬롯           |
 | `validateKey`      | `(key: string, entries: KeyValueEntry[]) => string \| undefined` |          |         | 키 유효성 검사 함수               |
 
+**Keyboard Shortcuts:**
+
+| Keys  | Action             |
+| ----- | ------------------ |
+| `Tab` | 키/값 필드 간 이동 |
+
 ### AuditTimeline
 
 > 변경 이력 타임라인. 액션별 색상 코딩 + 확장 가능한 diff 뷰.
@@ -1315,6 +1443,13 @@ const fields = [
 | `showHint`     | `boolean`                   |          | true    | Shift+Enter 힌트 표시 여부 |
 | `labels`       | `ChatInputLabels`           |          |         | i18n 라벨 오버라이드       |
 
+**Keyboard Shortcuts:**
+
+| Keys            | Action      |
+| --------------- | ----------- |
+| `Enter`         | 메시지 전송 |
+| `Shift + Enter` | 줄바꿈      |
+
 **Examples:**
 
 _채팅 입력:_

package/dist/docs/02-components/04-surfaces.md

@@ -1,7 +1,7 @@
 ---
 title: "Surface Components"
 description: "0 Surface layer components — props, examples, keyboard shortcuts."
-version: "1.4.1"
+version: "1.6.0"
 generated: true
 ---
 

package/dist/docs/02-components/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Component Reference"
 description: "Complete reference for 134 @reopt-ai/opt-ui components across 4 layers."
-version: "1.4.1"
+version: "1.6.0"
 generated: true
 ---
 

package/dist/docs/03-recipes/03-layouts.md

@@ -7,7 +7,7 @@ related:
     - ../02-components/03-shells.md
 ---
 
-<!-- AI agent hint: Surface/페이지 루트에 직접 space-y-* 사용 금지. 반드시 SurfaceLayout 또는 createSurface 사용. -->
+<!-- AI agent hint: Block/페이지 루트에 직접 space-y-* 사용 금지. 반드시 BlockLayout 또는 createBlock 사용. 페이지 경계를 직접 맡으면 inset="section"을 지정. -->
 
 # Layout Recipes
 
@@ -18,6 +18,10 @@ All imports from `@reopt-ai/opt-ui`.
 
 Full application chrome: header, collapsible sidebar, main content area.
 
+`AppShell.Sidebar` stays mounted and visible at every viewport size. Apply a
+responsive `className` such as `hidden xl:block`, or replace it with a mobile
+drawer, when the product should hide navigation on smaller screens.
+
 ```tsx
 "use client";
 
@@ -107,14 +111,14 @@ export function AppLayout({ children }: { children: React.ReactNode }) {
 
 ## 2. Data Explorer Page
 
-FilterBar + DataTable + Pagination in a SurfaceLayout.
+FilterBar + DataTable + Pagination in a BlockLayout.
 
 ```tsx
 "use client";
 
 import { useState, useMemo } from "react";
 import {
-  SurfaceLayout,
+  BlockLayout,
   PageHeader,
   FilterBar,
   DataTable,
@@ -217,7 +221,7 @@ export function UserExplorerPage() {
   };
 
   return (
-    <SurfaceLayout>
+    <BlockLayout inset="section">
       <PageHeader
         title="사용자 관리"
         description={`총 ${filtered.length}명`}
@@ -249,20 +253,20 @@ export function UserExplorerPage() {
         currentPage={page}
         onPageChange={setPage}
       />
-    </SurfaceLayout>
+    </BlockLayout>
   );
 }
 ```
 
 ## 3. Settings Page with Vertical Tabs
 
-SurfaceLayout with VerticalTabs for section navigation and SettingsForm for each tab.
+BlockLayout with VerticalTabs for section navigation and SettingsForm for each tab.
 
 ```tsx
 "use client";
 
 import {
-  SurfaceLayout,
+  BlockLayout,
   PageHeader,
   VerticalTabs,
   SettingsForm,
@@ -387,7 +391,7 @@ const tabs: TabDef[] = [
 
 export function SettingsPage() {
   return (
-    <SurfaceLayout>
+    <BlockLayout inset="section">
       <PageHeader title="설정" description="프로젝트 설정을 관리합니다" />
 
       <VerticalTabs
@@ -395,7 +399,7 @@ export function SettingsPage() {
         defaultTabId="general"
         labels={{ ariaLabel: "설정 카테고리" }}
       />
-    </SurfaceLayout>
+    </BlockLayout>
   );
 }
 ```
@@ -404,14 +408,14 @@ export function SettingsPage() {
 
 | Element        | Approach                                                                  |
 | -------------- | ------------------------------------------------------------------------- |
-| Page root      | `SurfaceLayout` (provides `gap-section` between children)                 |
+| Page root      | `BlockLayout inset="section"` (page inset + `gap-section`)                |
 | App chrome     | `AppShell` + `AppShell.Header/Sidebar/Content/Footer`                     |
 | Sidebar nav    | `Sidebar` with `Sidebar.Header/Content/Footer` sub-components             |
-| Page title     | `PageHeader` with optional `description` and `actions` slot               |
+| Page title     | `PageHeader` with optional slots; outer inset belongs to the page root    |
 | Section grids  | `gap-group` between columns, `gap-element` for tight spacing              |
 | Tab navigation | `VerticalTabs` for left-side tabs, `ContentTabs` for horizontal           |
 | Pagination     | `Pagination` below `DataTable` with `totalItems`/`pageSize`/`currentPage` |
-| Loading state  | `SurfaceLayout loading={true}` wraps content with `LoadingOverlay`        |
+| Loading state  | `BlockLayout loading={true}` wraps content with `LoadingOverlay`          |
 
 ### Semantic Spacing Quick Reference
 
@@ -419,6 +423,10 @@ export function SettingsPage() {
 gap-section  ->  24px  (between major sections)
 gap-group    ->  16px  (between related items)
 gap-element  ->   8px  (between tightly coupled elements)
+p-section    ->  24px  (inside a page-owned content boundary)
 ```
 
 CSS variables: `--opt-space-section`, `--opt-space-group`, `--opt-space-element`.
+
+`BlockLayout`의 inset 기본값은 없음입니다. 재사용 Block이 카드나 Shell 안에 들어갈 때 이중
+여백이 생기지 않게 하고, 페이지 콘텐츠 경계를 맡는 호출부만 `inset="section"`을 명시합니다.

package/dist/docs/04-theming.md

@@ -186,7 +186,9 @@ Dark mode uses the `[data-theme="preset-dark"]` selector. The compound theme sys
 
 /* Dark mode */
 [data-theme="default-dark"] {
-  --opt-surface: hsl(204 4% 16%);
+  --opt-surface: hsl(204 5% 7%);
+  --opt-surface-raised: hsl(204 5% 9%);
+  --opt-surface-overlay: hsl(204 5% 12%);
   --opt-text: hsl(0 0% 82%);
 }
 ```

package/dist/docs/05-migration/01-breaking-changes.md

@@ -25,6 +25,34 @@ description: "opt-ui 버전별 Breaking/Deprecated 변경사항 레지스트리"
 
 ---
 
+## Version 1.5.0
+
+### Breaking
+
+- version: "1.5.0"
+  level: B
+  component: "Surface runtime exports"
+  change: "런타임 Surface export 제거 — opt-cli 블록 registry로 이관"
+  detail: "ChatAssistant, DataExplorer, DeploymentCenter 등 런타임 Surface와 createSurface가 @reopt-ai/opt-ui에서 더 이상 export되지 않습니다. 페이지 템플릿은 opt-cli 블록 registry(copy-paste)로 소비합니다."
+  scan: "ChatAssistant\\|DataExplorer\\|DeploymentCenter\\|createSurface"
+  fix:
+  type: manual
+  from: 'import { ChatAssistant } from "@reopt-ai/opt-ui"'
+  to: "npx @reopt-ai/opt-cli surface add <slug>"
+
+### Deprecated
+
+- version: "1.5.0"
+  level: D
+  component: "SurfaceLayout"
+  change: "SurfaceLayout deprecated → BlockLayout / createBlock"
+  detail: "SurfaceLayout이 deprecated 되었습니다. 페이지 간격·레이아웃은 BlockLayout 또는 createBlock을 사용하세요."
+  scan: "SurfaceLayout"
+  fix:
+  type: rename
+  from: "<SurfaceLayout>"
+  to: "<BlockLayout>"
+
 ## Version 1.2.0
 
 ### Breaking