@reopt-ai/opt-ui 1.5.0 → 1.7.0

package/COMPONENT_CATALOG.md

@@ -2,7 +2,7 @@
 
 <!-- DEPRECATED: Prefer dist/docs/02-components/ for per-layer reference. -->
 <!-- Auto-generated from ComponentMeta. Do not edit. -->
-<!-- Version: 1.4.1 -->
+<!-- Version: 1.6.0 -->
 
 ## Quick Stats
 
@@ -10,9 +10,9 @@
 | --------- | ------- |
 | Core      | 59      |
 | Visuals   | 0       |
-| Shells    | 75      |
+| Shells    | 80      |
 | Surfaces  | 0       |
-| **Total** | **134** |
+| **Total** | **139** |
 
 ## Component Selection Guide
 
@@ -184,7 +184,7 @@
 | Toggle        | 눌림(pressed) 두 상태 버튼. 단독 사용하거나 ToggleGroup으로 묶어 단일/다중 선택을 만든다.                                                                | `Toggle`, `ToggleGroup`                                                                                                                         |
 | Accordion     | 수직으로 쌓인 펼침/접힘 패널. single(한 개)/multiple(여러 개) 모드와 collapsible 지원.                                                                   | `AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`                                                                        |
 | Meter         | 범위 내 스칼라 측정값 게이지 (디스크 사용량·점수·용량 등). role=meter로 작업 진행률(Progress)과 구분된다.                                                | `Meter`                                                                                                                                         |
-| BlockLayout   | Block 루트 레이아웃. flex + 기본 section spacing 적용, loading prop으로 LoadingOverlay 자동 래핑.                                                        | `BlockLayout`                                                                                                                                   |
+| BlockLayout   | Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다.                         | `BlockLayout`                                                                                                                                   |
 | createBlock   | Block 팩토리 함수. BlockLayout 래핑을 구조적으로 강제하여 loading/className 처리를 자동화합니다.                                                         | `createBlock`                                                                                                                                   |
 | StarRating    | 1~N점 별점을 선택하는 인터랙티브 레이팅 입력. 읽기 전용 표시도 지원.                                                                                     | `StarRating`                                                                                                                                    |
 | ErrorBoundary | React 에러 바운더리. 자식 컴포넌트 렌더 에러를 잡아 fallback UI를 표시합니다.                                                                            | `ErrorBoundary`                                                                                                                                 |
@@ -196,7 +196,7 @@
 | Component | Description | Key Exports |
 | --------- | ----------- | ----------- |
 
-## Shell Components (75)
+## Shell Components (80)
 
 ### Navigation & Layout
 
@@ -328,15 +328,20 @@
 
 ### 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` |
+| 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`                          |
+| TimeRangeControl | date math(now-7d, now/d) 기반 시간 범위 컨트롤. quick select, 프리셋/최근 사용, 명시적 Update, 자동 갱신, 창 이동·확대/축소 버튼을 제공합니다. | `TimeRangeControl`, `DEFAULT_TIME_PRESETS` |
+| TimeSeriesPanel  | 시간 범위 컨트롤과 시계열 차트를 한 단위로 묶은 패널. 드래그 줌과 줌 히스토리(되돌리기), 범례 토글을 포함합니다.                               | `TimeSeriesPanel`                          |
+| LogTable         | 계속 도착하는 로그용 윈도잉 테이블. 컬럼 정의 기반, 상단 삽입 시 스크롤 위치 보존, follow 상태 보고, 셀 값 즉시 필터, 밀도·정렬을 지원합니다.  | `LogTable`                                 |
+| QueryBar         | 검색과 필터를 한 입력으로 합친 쿼리 바. field:value, -부정, (a or b), 비교 연산, 필드·값 자동완성, 절(clause) 칩을 지원합니다.                 | `QueryBar`                                 |
+| FieldSidebar     | 데이터에 어떤 필드가 있고 각 필드가 무슨 값을 갖는지 보여주는 사이드바. 값 분포 막대, 컬럼으로 승격, 값 기준 포함/제외 필터를 제공합니다.      | `FieldSidebar`                             |
 
 ## Surface Components (0)
 
@@ -373,9 +378,11 @@
 
 **Import:** `import { Kbd } from "@reopt-ai/opt-ui"`
 
-| Prop       | Type        | Required | Default | Description          |
-| ---------- | ----------- | -------- | ------- | -------------------- |
-| `children` | `ReactNode` | Yes      |         | 표시할 단축키 텍스트 |
+| Prop        | Type        | Required | Default | Description                                                                     |
+| ----------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------- |
+| `children`  | `ReactNode` | Yes      |         | 표시할 단축키 텍스트                                                            |
+| `hint`      | `boolean`   |          |         | 인라인 힌트 배지로 표시. `data-shortcut-hints="hidden"`일 때 숨겨진다 (app.css) |
+| `className` | `string`    |          |         | 기본 스타일 오버라이드                                                          |
 
 #### Separator
 
@@ -542,26 +549,31 @@
 
 **TabsRoot:**
 
-| Prop                | Type                           | Required | Default | Description               |
-| ------------------- | ------------------------------ | -------- | ------- | ------------------------- |
-| `defaultSelectedId` | `string`                       |          |         | 초기 선택된 탭 ID         |
-| `selectedId`        | `string \| null`               |          |         | 제어 모드: 선택된 탭 ID   |
-| `setSelectedId`     | `(id: string \| null) => void` |          |         | 제어 모드: 탭 변경 핸들러 |
+| Prop                | Type                           | Required | Default | Description                                                                            |
+| ------------------- | ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `variant`           | `"underline" \| "workspace"`   |          |         | 탭 프레임 형태. workspace는 편집기 탭(문서/쿼리처럼 열고 닫히며 상태를 갖는 작업 단위) |
+| `defaultSelectedId` | `string`                       |          |         | 초기 선택된 탭 ID                                                                      |
+| `selectedId`        | `string \| null`               |          |         | 제어 모드: 선택된 탭 ID                                                                |
+| `setSelectedId`     | `(id: string \| null) => void` |          |         | 제어 모드: 탭 변경 핸들러                                                              |
 
 **TabList:**
 
-| Prop        | Type        | Required | Default | Description            |
-| ----------- | ----------- | -------- | ------- | ---------------------- |
-| `children`  | `ReactNode` | Yes      |         | Tab 요소들             |
-| `className` | `string`    |          |         | 기본 스타일 오버라이드 |
+| Prop        | Type        | Required | Default | Description                                                                            |
+| ----------- | ----------- | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `children`  | `ReactNode` | Yes      |         | Tab 요소들                                                                             |
+| `actions`   | `ReactNode` |          |         | 탭 줄 오른쪽 액션 영역 (새 탭, 닫기 등). tablist 바깥에 렌더돼 탭 순회에 끼어들지 않음 |
+| `className` | `string`    |          |         | 기본 스타일 오버라이드                                                                 |
 
 **Tab:**
 
-| Prop        | Type        | Required | Default | Description                          |
-| ----------- | ----------- | -------- | ------- | ------------------------------------ |
-| `id`        | `string`    | Yes      |         | 탭 고유 ID (TabPanel의 tabId와 매칭) |
-| `children`  | `ReactNode` | Yes      |         | 탭 레이블                            |
-| `className` | `string`    |          |         | 기본 스타일 오버라이드               |
+| Prop          | Type                   | Required | Default | Description                                       |
+| ------------- | ---------------------- | -------- | ------- | ------------------------------------------------- |
+| `id`          | `string`               | Yes      |         | 탭 고유 ID (TabPanel의 tabId와 매칭)              |
+| `children`    | `ReactNode`            | Yes      |         | 탭 레이블                                         |
+| `icon`        | `ReactNode`            |          |         | 탭 이름 앞 아이콘. 활성 탭에서 accent 색으로 전환 |
+| `status`      | `"dirty" \| "running"` |          |         | 저장되지 않은 변경 / 실행 중 인디케이터           |
+| `statusLabel` | `string`               |          |         | status 인디케이터의 접근성 레이블                 |
+| `className`   | `string`               |          |         | 기본 스타일 오버라이드                            |
 
 **TabPanel:**
 
@@ -1877,13 +1889,14 @@ import {
 
 **Import:** `import { BlockLayout } from "@reopt-ai/opt-ui"`
 
-| Prop           | Type                                          | Required | Default   | Description                                                                          |
-| -------------- | --------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------ |
-| `children`     | `ReactNode`                                   | Yes      |           | Block 콘텐츠                                                                         |
-| `loading`      | `boolean`                                     |          |           | 로딩 상태. 설정 시 LoadingOverlay로 자동 래핑                                        |
-| `loadingLabel` | `string`                                      |          |           | LoadingOverlay 접근성 레이블                                                         |
-| `spacing`      | `"section" \| "group" \| "element" \| "none"` |          | "section" | Block 최상위 자식 사이 간격. 데이터 밀도가 높은 Block는 group/element로 낮출 수 있음 |
-| `className`    | `string`                                      |          |           | 기본 스타일 오버라이드                                                               |
+| Prop           | Type                                          | Required | Default   | Description                                                                                          |
+| -------------- | --------------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `children`     | `ReactNode`                                   | Yes      |           | Block 콘텐츠                                                                                         |
+| `loading`      | `boolean`                                     |          |           | 로딩 상태. 설정 시 LoadingOverlay로 자동 래핑                                                        |
+| `loadingLabel` | `string`                                      |          |           | LoadingOverlay 접근성 레이블                                                                         |
+| `spacing`      | `"section" \| "group" \| "element" \| "none"` |          | "section" | Block 최상위 자식 사이 간격. 데이터 밀도가 높은 Block는 group/element로 낮출 수 있음                 |
+| `inset`        | `"section" \| "group" \| "element" \| "none"` |          |           | Block 안쪽 여백. 페이지 콘텐츠 경계에는 section을 사용하고, 이미 여백을 제공하는 Shell 안에서는 생략 |
+| `className`    | `string`                                      |          |           | 기본 스타일 오버라이드                                                                               |
 
 **Examples:**
 
@@ -1892,7 +1905,7 @@ _Block 루트:_
 ```tsx
 import { BlockLayout, PageHeader } from "@reopt-ai/opt-ui";
 
-<BlockLayout loading={isLoading} spacing="section">
+<BlockLayout loading={isLoading} spacing="section" inset="section">
   <PageHeader title="대시보드" description="프로젝트 현황" />
   <section>콘텐츠 영역</section>
 </BlockLayout>;
@@ -2605,17 +2618,17 @@ const filters = [
 **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 슬롯 (파일 선택 후 표시) |
 
 #### EventIcon
 
@@ -2627,6 +2640,19 @@ const filters = [
 | `color` | `string`                    |          | theme accent | 사용자 지정 아이콘 색상. 없으면 theme accent 토큰을 사용하고, 전달하면 전경색과 tint 배경에 적용됩니다. |
 | `size`  | `"sm" \| "md" \| "lg"`      |          | "md"         | 아이콘 크기 (sm=20px, md=28px, lg=36px)                                                                 |
 
+#### ConnectionIndicator
+
+**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`                                                    |          |         | 기본 스타일 오버라이드                                                |
+
 #### TemplatePicker
 
 **Import:** `import { TemplatePicker } from "@reopt-ai/opt-ui"`
@@ -2728,6 +2754,30 @@ const filters = [
 | `error`   | `string`                         |          |         | assertive 오류 상태     |
 | `labels`  | `QueryResultsTableLabels`        |          |         | 로딩/빈 상태/행 수 문구 |
 
+#### SqlEditor
+
+**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`                      |          |         | 기본 스타일 오버라이드                                                           |
+
 #### ReportBuilder
 
 **Import:** `import { ReportBuilder } from "@reopt-ai/opt-ui"`
@@ -3242,4 +3292,82 @@ const messages = [
 <ChatMessageList messages={messages} loading={false} />;
 ```
 
+#### TimeRangeControl
+
+**Import:** `import { TimeRangeControl } from "@reopt-ai/opt-ui"`
+
+| Prop                | Type                             | Required | Default | Description                              |
+| ------------------- | -------------------------------- | -------- | ------- | ---------------------------------------- |
+| `value`             | `TimeRange`                      | Yes      |         | { from, to } — date math 문자열 또는 ISO |
+| `onChange`          | `(range: TimeRange) => void`     | Yes      |         | 범위가 커밋되었을 때 호출                |
+| `presets`           | `TimeRangePreset[]`              |          |         | 자주 쓰는 범위 목록                      |
+| `recentRanges`      | `TimeRangePreset[]`              |          |         | 최근 사용한 범위 (호출자 소유)           |
+| `timeZone`          | `string`                         |          |         | 라운딩·표시에 쓸 IANA 타임존             |
+| `showUpdateButton`  | `boolean`                        |          | true    | 편집을 명시적으로 커밋                   |
+| `showWindowButtons` | `boolean`                        |          | true    | 이전/다음 창, 확대/축소 버튼             |
+| `refresh`           | `RefreshSetting`                 |          |         | { interval, paused } 자동 갱신 설정      |
+| `onRefresh`         | `() => void \| Promise<unknown>` |          |         | 갱신 요청 — 프라미스가 끝난 뒤 다음 tick |
+
+#### TimeSeriesPanel
+
+**Import:** `import { TimeSeriesPanel } from "@reopt-ai/opt-ui"`
+
+| Prop               | Type                         | Required | Default | Description                                   |
+| ------------------ | ---------------------------- | -------- | ------- | --------------------------------------------- |
+| `data`             | `TimeSeriesPoint[]`          | Yes      |         | 시계열 데이터                                 |
+| `series`           | `TimeSeriesDef[]`            | Yes      |         | 시리즈 정의                                   |
+| `range`            | `TimeRange`                  | Yes      |         | 조회 구간 — 차트 축도 여기에 고정됩니다       |
+| `onRangeChange`    | `(range: TimeRange) => void` | Yes      |         | 드래그 줌·컨트롤 변경으로 구간이 바뀔 때 호출 |
+| `showRangeControl` | `boolean`                    |          | true    | 헤더에 TimeRangeControl 렌더                  |
+| `toggleableLegend` | `boolean`                    |          | false   | 범례 클릭으로 시리즈 숨김                     |
+| `annotations`      | `TimeSeriesAnnotation[]`     |          |         | 시간축 마커/구간                              |
+| `height`           | `number`                     |          | 280     | 차트 높이                                     |
+
+#### LogTable
+
+**Import:** `import { LogTable } from "@reopt-ai/opt-ui"`
+
+| Prop             | Type                                     | Required | Default  | Description                      |
+| ---------------- | ---------------------------------------- | -------- | -------- | -------------------------------- |
+| `rows`           | `Row[]`                                  | Yes      |          | 표시할 행                        |
+| `columns`        | `LogColumn<Row>[]`                       | Yes      |          | 컬럼 정의 (표시 중인 것만)       |
+| `getRowId`       | `(row: Row) => string`                   | Yes      |          | 행 식별자                        |
+| `selectedId`     | `string \| null`                         |          |          | 선택된 행                        |
+| `onSelect`       | `(id: string) => void`                   |          |          | 행 선택                          |
+| `onLoadMore`     | `() => void`                             |          |          | 다음 페이지 요청                 |
+| `prepending`     | `boolean`                                |          | false    | 상단에 행이 삽입되는 라이브 목록 |
+| `onFollowChange` | `(following: boolean) => void`           |          |          | 최신 행 고정 여부 보고           |
+| `isNew`          | `(row: Row) => boolean`                  |          |          | 방금 도착한 행 강조              |
+| `sort`           | `LogSort \| null`                        |          |          | 정렬 상태                        |
+| `onSortChange`   | `(sort: LogSort) => void`                |          |          | 헤더 클릭 정렬                   |
+| `onCellAction`   | `(action: LogCellAction) => void`        |          |          | 셀 값 포함/제외 필터             |
+| `density`        | `"compact" \| "normal" \| "comfortable"` |          | "normal" | 행 높이와 글자 크기              |
+
+#### QueryBar
+
+**Import:** `import { QueryBar } from "@reopt-ai/opt-ui"`
+
+| Prop          | Type                     | Required | Default | Description                  |
+| ------------- | ------------------------ | -------- | ------- | ---------------------------- |
+| `value`       | `Query`                  | Yes      |         | 파싱된 쿼리                  |
+| `onChange`    | `(query: Query) => void` | Yes      |         | 커밋 시 호출 (Enter·blur)    |
+| `fields`      | `QueryField[]`           |          |         | 자동완성할 필드와 알려진 값  |
+| `showClauses` | `boolean`                |          | false   | 절을 제거 가능한 칩으로 표시 |
+| `live`        | `boolean`                |          | false   | 키 입력마다 커밋             |
+
+#### FieldSidebar
+
+**Import:** `import { FieldSidebar } from "@reopt-ai/opt-ui"`
+
+| Prop                    | Type                                                                     | Required | Default | Description                    |
+| ----------------------- | ------------------------------------------------------------------------ | -------- | ------- | ------------------------------ |
+| `fields`                | `FieldSummary[]`                                                         | Yes      |         | 필드 목록                      |
+| `expandedField`         | `string \| null`                                                         |          |         | 값을 펼친 필드                 |
+| `onExpandedFieldChange` | `(field: string \| null) => void`                                        |          |         | 펼침 전환 — 호출자가 값을 조회 |
+| `values`                | `FieldValueCount[]`                                                      |          |         | 펼친 필드의 상위 값            |
+| `valuesLoading`         | `boolean`                                                                |          | false   | 값 조회 중                     |
+| `sampledRows`           | `number`                                                                 |          |         | 집계 대상 행 수 (분모)         |
+| `onToggleColumn`        | `(field: string, next: boolean) => void`                                 |          |         | 컬럼 추가/제거                 |
+| `onFilter`              | `(field: string, value: string, intent: "include" \| "exclude") => void` |          |         | 값 기준 필터                   |
+
 ### Surface Layer

package/README.md

@@ -2,6 +2,25 @@
 
 접근성 우선 UI 컴포넌트 라이브러리. opt-ui-primitives 기반 Core, 비즈니스 Shells, Surface/block layout primitives를 제공합니다. 페이지 템플릿 Surface는 `@reopt-ai/opt-cli` registry로 설치하며, 차트와 데이터 시각화 컴포넌트는 `@reopt-ai/opt-charts`로 분리되었습니다.
 
+## 에이전트 스킬로 설정하기 (권장)
+
+소비자 프로젝트 루트에서 전용 스킬을 설치합니다.
+
+```bash
+npx skills add reopt-ai/reopt-skills/opt-ui-install
+```
+
+설치 후 에이전트에게
+`opt-ui-install 스킬로 이 프로젝트에 @reopt-ai/opt-ui를 설정하고 검증해줘`라고
+요청하세요. 스킬은 신규 설치와 업그레이드를 구분하고, `AGENTS.md`(없으면
+`CLAUDE.md`)의 reopt marker 블록, Tailwind v4, `OptThemeProvider`, `opt
+doctor`, Surface 흐름을 멱등하게 설정합니다. 스킬 소스는
+[`reopt-ai/reopt-skills`](https://github.com/reopt-ai/reopt-skills/tree/main/skills/opt-ui-install)가
+단일 기준입니다.
+
+아래 설치 명령은 스킬을 사용할 수 없거나 모든 단계를 직접 통제할 때의 수동
+대안입니다.
+
 ## 설치
 
 ```bash
@@ -170,13 +189,15 @@ CSS 변수 기반 시맨틱 토큰 — `dark:` 프리픽스 없이 자동 전환
 
 ### 시맨틱 스페이싱
 
-| CSS 변수              | Tailwind      | 값            |
-| --------------------- | ------------- | ------------- |
-| `--opt-space-section` | `gap-section` | 1.5rem (24px) |
-| `--opt-space-group`   | `gap-group`   | 1rem (16px)   |
-| `--opt-space-element` | `gap-element` | 0.5rem (8px)  |
+| CSS 변수              | Tailwind                   | 값            |
+| --------------------- | -------------------------- | ------------- |
+| `--opt-space-section` | `gap-section`, `p-section` | 1.5rem (24px) |
+| `--opt-space-group`   | `gap-group`, `p-group`     | 1rem (16px)   |
+| `--opt-space-element` | `gap-element`, `p-element` | 0.5rem (8px)  |
 
-Surface 루트는 반드시 `SurfaceLayout`을 사용하여 일관된 스페이싱을 유지합니다.
+Block 루트는 반드시 `BlockLayout`을 사용합니다. 페이지 콘텐츠 경계를 Block이 직접 맡을 때는
+`inset="section"`을 지정하고, 카드나 Shell이 이미 여백을 제공하는 embedded Block에서는 inset을
+생략합니다. `PageHeader`는 재사용 가능한 콘텐츠 헤더이므로 바깥 여백을 소유하지 않습니다.
 
 ## 접근성
 
@@ -229,7 +250,7 @@ bun run test:coverage
 ## Design Decisions
 
 - **Layer metaphor**: Core → Shells는 opt-ui가 맡고, 페이지 템플릿 Surface는 opt-cli block registry로 설치
-- **SurfaceLayout 강제**: block template은 반드시 `SurfaceLayout` 또는 `createSurface`를 사용하여 구조적 일관성 보장
+- **BlockLayout 강제**: block template은 반드시 `BlockLayout` 또는 `createBlock`을 사용하고, 페이지 경계는 `inset="section"`으로 명시
 - **Subpath exports**: `./core`, `./visuals`, `./shells` — 필요한 계층만 import 가능
 - **Dual format**: ESM + CJS — 모든 번들러/런타임 호환
 - **Source maps**: 디버깅을 위한 소스맵 포함

package/dist/app.css

@@ -0,0 +1,170 @@
+/*
+ * @reopt-ai/opt-ui — Application base layer (optional)
+ *
+ * `tailwind.css`가 토큰과 유틸리티를 준다면, 이 파일은 **앱 셸이 매번 다시 쓰는
+ * 규칙**을 준다. 실제 소비 프로젝트를 감사했을 때 아래 다섯 가지가 앱마다
+ * 손으로 재작성돼 있었고, 매번 조금씩 달랐다 — 커서 정책, opt-ui 밖 요소의
+ * 포커스 링, 사용자 모션 설정, 글자 크기 설정, 스킵 링크.
+ *
+ * Usage (consumer globals.css):
+ *
+ *   @import "tailwindcss";
+ *   @import "@reopt-ai/opt-ui/tailwind.css";
+ *   @import "@reopt-ai/opt-ui/app.css";
+ *
+ * 선택 사항이다. 앱이 자기 규칙을 갖고 있다면 안 써도 되고, 여기 규칙은 전부
+ * `:where()`로 특이도 0이라 유틸리티 클래스가 항상 이긴다.
+ */
+
+@layer base {
+  /* ── Cursor ──
+   *
+   * 브라우저 기본값은 button에 `default`를 준다. 디자인 시스템을 쓰는 앱은
+   * 예외 없이 이걸 pointer로 되돌리는데, 그 목록을 손으로 관리하면 role 기반
+   * 요소(`[role="option"]`, `[role="treeitem"]`)가 빠지기 쉽다.
+   *
+   * opt-ui 컴포넌트는 자체 클래스로 커서를 지정하므로 여기 규칙과 무관하다.
+   * 이건 앱이 직접 쓰는 raw 요소를 위한 것이다. */
+  :where(
+    button:not(:disabled),
+    summary,
+    label[for],
+    select:not(:disabled),
+    a[href],
+    input:is(
+      [type="button"],
+      [type="submit"],
+      [type="reset"],
+      [type="checkbox"],
+      [type="radio"],
+      [type="file"],
+      [type="range"]
+    ):not(:disabled),
+    [role="button"]:not([aria-disabled="true"]),
+    [role="tab"]:not([aria-disabled="true"]),
+    [role="menuitem"]:not([aria-disabled="true"]),
+    [role="menuitemcheckbox"]:not([aria-disabled="true"]),
+    [role="menuitemradio"]:not([aria-disabled="true"]),
+    [role="option"]:not([aria-disabled="true"]),
+    [role="switch"]:not([aria-disabled="true"]),
+    [role="checkbox"]:not([aria-disabled="true"]),
+    [role="radio"]:not([aria-disabled="true"]),
+    [role="treeitem"]:not([aria-disabled="true"])
+  ) {
+    cursor: pointer;
+  }
+
+  :where(
+    button:disabled,
+    input:disabled,
+    select:disabled,
+    textarea:disabled,
+    [aria-disabled="true"]
+  ) {
+    cursor: not-allowed;
+  }
+
+  /* ── Focus ──
+   *
+   * opt-ui 컴포넌트는 `data-opt-id`를 달고 자체 포커스 링을 갖는다. 앱이 직접
+   * 쓰는 raw button/link/summary에는 아무것도 없어서, 키보드 사용자가 앱 고유
+   * 영역에 들어가는 순간 포커스가 사라지곤 한다. 같은 링을 기본값으로 준다. */
+  :where(
+    button:not([data-opt-id]),
+    a[href]:not([data-opt-id]),
+    summary:not([data-opt-id]),
+    [tabindex]:not([tabindex="-1"]):not([data-opt-id])
+  ):focus-visible {
+    outline: 2px solid var(--opt-ring);
+    outline-offset: 2px;
+  }
+
+  /* ── User preference: text scale ──
+   *
+   * `<html data-text-scale="small|large">`로 루트 글자 크기를 조절한다. rem
+   * 기반 토큰이 전부 따라 움직이므로 레이아웃이 함께 확대/축소된다. */
+  html[data-text-scale="small"] {
+    font-size: 93.75%;
+  }
+
+  html[data-text-scale="large"] {
+    font-size: 112.5%;
+  }
+
+  /* ── User preference: motion ──
+   *
+   * `tailwind.css`가 시스템 `prefers-reduced-motion`을 이미 존중한다. 이건 앱
+   * 설정에서 사용자가 **시스템과 무관하게** 끈 경우를 위한 명시적 스코프다.
+   * `<html data-motion="reduced">` 또는 앱 셸 루트에 붙인다. */
+  [data-motion="reduced"],
+  [data-motion="reduced"] :where(*, *::before, *::after) {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+@layer components {
+  /* ── Shortcut hints ──
+   *
+   * `<Kbd hint>`가 붙이는 클래스. 메뉴 항목 옆에 붙는 "⌘K" 같은 광고성 배지를
+   * 가리키며, 단축키 도움말 자체는 대상이 아니다.
+   *
+   * `<html data-shortcut-hints="hidden">`이면 사라진다 — 설정 값을 모든 호출
+   * 지점에 내려보내지 않고 "키보드 힌트 숨기기"를 구현하는 경로다.
+   * opt-shell의 `shortcutHints` 정책이 그 속성을 쓴다. */
+  [data-shortcut-hints="hidden"] .opt-shortcut-hint {
+    display: none;
+  }
+
+  /* ── Skip link ──
+   *
+   * 키보드 사용자가 사이드바 전체를 Tab으로 통과하지 않고 본문으로 건너뛰는
+   * 링크. 포커스 전에는 화면 밖에 있다가 포커스되면 나타난다.
+   *
+   *   <a class="opt-skip-link" href="#main">본문으로 건너뛰기</a>
+   */
+  .opt-skip-link {
+    position: fixed;
+    z-index: 100;
+    top: var(--opt-space-element);
+    left: var(--opt-space-element);
+    padding: var(--opt-space-element) var(--opt-space-group);
+    border: 1px solid var(--opt-ring);
+    border-radius: var(--opt-radius-md);
+    color: var(--opt-text);
+    background: var(--opt-surface-overlay);
+    box-shadow: var(--opt-shadow-md);
+    text-decoration: none;
+    transform: translateY(calc(-100% - var(--opt-space-section)));
+  }
+
+  .opt-skip-link:focus {
+    transform: translateY(0);
+  }
+}
+
+/*
+ * A row that just arrived over a live connection fades its highlight out once.
+ * The eye catches what is new without the list turning into a light show —
+ * and readers who asked for less motion get the row without the flash.
+ */
+@keyframes opt-log-row-enter {
+  from {
+    background-color: var(--opt-accent-subtle, rgb(59 130 246 / 0.18));
+  }
+  to {
+    background-color: transparent;
+  }
+}
+
+.opt-log-row-enter {
+  animation: opt-log-row-enter 1.5s ease-out 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .opt-log-row-enter {
+    animation: none;
+  }
+}