@reopt-ai/opt-ui 1.10.0 → 1.11.0

package/dist/core/index.js

@@ -1,4 +1,4 @@
 "use client";
-import { $ as ToolbarButton, $t as Alert, A as FormSelectItem, At as DialogHeading, B as useFormStore, Bt as TabPanel, C as FormPush, Ct as AlertDialogPanel, D as FormReset, Dt as DialogDismiss, E as FormRemove, Et as DialogDisclosure, F as FormSwitch, Ft as SelectPopover, Gt as Composite, H as DateRangePicker, Ht as DisclosureContent, It as SelectRoot, J as PopoverContent, Jt as CompositeRow, K as ColorPicker, Kt as CompositeItem, L as FormTextarea, Lt as SelectTrigger, Mt as DialogRoot, Nt as SelectItem, O as FormRoot, Ot as DialogFooter, P as FormSubmit, Pt as SelectLabel, Q as NumberInput, Rt as Tab, S as FormProvider, St as ComboboxRoot, T as FormRadioGroup, Tt as DialogDescription, U as TagInput, Ut as DisclosureRoot, V as DEFAULT_PRESETS, Vt as TabsRoot, W as IconPicker, Wt as DisclosureTrigger, X as PopoverTrigger, Y as PopoverRoot, Yt as CompositeZone, Z as Slider, Zt as Input, _ as FormGroupLabel, _t as ComboboxGroup, a as resolveFieldType, at as TooltipProvider, b as FormLabel, bt as ComboboxItem, c as CheckboxGroup, ct as MenuItemCheckbox, d as FormControl, dt as MenuRoot, en as Spinner, et as ToolbarContainer, ft as MenuSeparator, g as FormGroup, gt as ComboboxEmpty, h as FormField, ht as MenubarRoot, i as FieldToken, it as TooltipAnchor, j as FormSelectPopover, jt as DialogPanel, k as FormSelect, kt as DialogHeader, l as FormCheckbox, lt as MenuItemRadio, m as FormError, mt as MenubarContainer, n as Highlight, nn as EmptyState, nt as ToolbarSeparator, o as Pagination, ot as MenuButtonArrow, p as FormDescription, pt as MenuTrigger, q as PopoverClose, qn as Kbd, qt as CompositeProvider, r as FIELD_TYPE_TOKENS, rn as Button, rt as Tooltip, s as Checkbox, sn as StatCard, st as MenuItem, t as TextTruncate, tn as Badge, tt as ToolbarRoot, ut as MenuPopover, vt as ComboboxGroupLabel, w as FormRadio, wt as DialogBody, xt as ComboboxPopover, y as FormInput, yt as ComboboxInput, z as useFormContext, zt as TabList } from "../text-truncate-j6X3z7Pv.js";
-import { $ as Skeleton, A as PageHeader, B as DropdownTrigger, C as Logo, D as Section, E as ResizablePanelGroup, F as RadioGroup, I as DropdownContent, J as CircularProgress, K as StepBuilder, L as DropdownItem, M as BlockLayout, O as Container, P as Radio, Q as Textarea, R as DropdownMenu, S as DrawerRoot, T as ResizablePanel, V as ConditionBuilder, X as Avatar, Y as Progress, Z as AvatarGroup, _ as getShaderFragment, _t as ToggleGroup, a as THEME_PALETTES, at as Card, b as DrawerClose, bt as Heading, c as ExpressionGroup, ct as CardFooter, d as ShaderSurface, dt as Breadcrumb, et as SkeletonAvatar, f as SHADER_OVERLAY_PARAM_KEYS, ft as AccordionContent, g as SHADER_PRESET_IDS, gt as Toggle, h as SHADER_PRESETS, ht as AccordionTrigger, i as ColorPalettePicker, it as Switch, j as createBlock, k as ScrollArea, l as Facet, lt as CardHeader, m as SHADER_PARAM_KEYS, mt as AccordionRoot, n as InlineEdit, nt as SkeletonTable, o as LiveRegion, ot as CardContent, p as SHADER_PARAM_FALLBACK, pt as AccordionItem, q as Meter, r as ColorPaletteDisplay, rt as SkeletonText, s as Expression, st as CardDescription, t as KeyPadMenu, tt as SkeletonCard, u as FacetGroup, ut as CardTitle, v as getShaderPreset, vt as OtpField, w as ResizableHandle, x as DrawerPanel, xt as Text, y as VirtualList, yt as Separator, z as DropdownSeparator } from "../key-pad-menu-BQunU20e.js";
-export { AccordionContent, AccordionItem, AccordionRoot, AccordionTrigger, Alert, AlertDialogPanel, Avatar, AvatarGroup, Badge, BlockLayout, BlockLayout as SurfaceLayout, Breadcrumb, Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, CheckboxGroup, CircularProgress, ColorPaletteDisplay, ColorPalettePicker, ColorPicker, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxPopover, ComboboxRoot, Composite, CompositeItem, CompositeProvider, CompositeRow, CompositeZone, ConditionBuilder, Container, DEFAULT_PRESETS, DateRangePicker, DialogBody, DialogDescription, DialogDisclosure, DialogDismiss, DialogFooter, DialogHeader, DialogHeading, DialogPanel, DialogRoot, DisclosureContent, DisclosureRoot, DisclosureTrigger, DrawerClose, DrawerPanel, DrawerRoot, DropdownContent, DropdownItem, DropdownMenu, DropdownSeparator, DropdownTrigger, EmptyState, Expression, ExpressionGroup, FIELD_TYPE_TOKENS, Facet, FacetGroup, FieldToken, FormCheckbox, FormControl, FormDescription, FormError, FormField, FormGroup, FormGroupLabel, FormInput, FormLabel, FormProvider, FormPush, FormRadio, FormRadioGroup, FormRemove, FormReset, FormRoot, FormSelect, FormSelectItem, FormSelectPopover, FormSubmit, FormSwitch, FormTextarea, Heading, Highlight, IconPicker, InlineEdit, Input, Kbd, KeyPadMenu, LiveRegion, Logo, MenuButtonArrow, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuRoot, MenuSeparator, MenuTrigger, MenubarContainer, MenubarRoot, Meter, NumberInput, OtpField, PageHeader, Pagination, PopoverClose, PopoverContent, PopoverRoot, PopoverTrigger, Progress, Radio, RadioGroup, ResizableHandle, ResizablePanel, ResizablePanelGroup, SHADER_OVERLAY_PARAM_KEYS, SHADER_PARAM_FALLBACK, SHADER_PARAM_KEYS, SHADER_PRESETS, SHADER_PRESET_IDS, ScrollArea, Section, SelectItem, SelectLabel, SelectPopover, SelectRoot, SelectTrigger, Separator, ShaderSurface, Skeleton, SkeletonAvatar, SkeletonCard, SkeletonTable, SkeletonText, Slider, Spinner, StatCard, StepBuilder, Switch, THEME_PALETTES, Tab, TabList, TabPanel, TabsRoot, TagInput, Text, TextTruncate, Textarea, Toggle, ToggleGroup, ToolbarButton, ToolbarContainer, ToolbarRoot, ToolbarSeparator, Tooltip, TooltipAnchor, TooltipProvider, VirtualList, createBlock, createBlock as createSurface, getShaderFragment, getShaderPreset, resolveFieldType, useFormContext, useFormStore };
+import { $ as PopoverContent, $t as CompositeRow, A as FormRadioGroup, At as DialogDescription, B as FormSwitch, Bt as SelectPopover, Ct as ComboboxGroupLabel, D as FormProvider, Dt as ComboboxRoot, Et as ComboboxPopover, F as FormSelectItem, Ft as DialogHeading, G as useFormStore, Gt as TabPanel, H as FormTextarea, Ht as SelectTrigger, I as FormSelectPopover, It as DialogPanel, J as TagInput, Jt as DisclosureRoot, K as DEFAULT_PRESETS, Kt as TabsRoot, Lt as DialogRoot, M as FormReset, Mt as DialogDismiss, N as FormRoot, Nt as DialogFooter, O as FormPush, Ot as AlertDialogPanel, P as FormSelect, Pt as DialogHeader, Q as PopoverClose, Qt as CompositeProvider, Rt as SelectItem, S as FormGroupLabel, St as ComboboxGroup, T as FormLabel, Tt as ComboboxItem, Ut as Tab, Vt as SelectRoot, W as useFormContext, Wt as TabList, Xt as Composite, Y as IconPicker, Yt as DisclosureTrigger, Z as ColorPicker, Zt as CompositeItem, _n as SkeletonTable, _t as MenuSeparator, a as resolveFieldType, an as Alert, ar as Kbd, at as ToolbarContainer, b as FormField, bt as MenubarRoot, c as CheckboxGroup, cn as EmptyState, ct as Tooltip, dt as MenuButtonArrow, en as CompositeZone, et as PopoverRoot, ft as MenuItem, g as FormControl, gn as SkeletonCard, gt as MenuRoot, hn as SkeletonAvatar, ht as MenuPopover, i as FieldToken, it as ToolbarButton, j as FormRemove, jt as DialogDisclosure, k as FormRadio, kt as DialogBody, ln as Button, lt as TooltipAnchor, m as FormCheckbox, mn as Skeleton, mt as MenuItemRadio, n as Highlight, nt as Slider, o as Pagination, on as Spinner, ot as ToolbarRoot, pn as StatCard, pt as MenuItemCheckbox, q as DateRangePicker, qt as DisclosureContent, r as FIELD_TYPE_TOKENS, rn as Input, rt as NumberInput, s as Checkbox, sn as Badge, st as ToolbarSeparator, t as TextTruncate, tn as Meter, tt as PopoverTrigger, ut as TooltipProvider, v as FormDescription, vn as SkeletonText, vt as MenuTrigger, w as FormInput, wt as ComboboxInput, x as FormGroup, xt as ComboboxEmpty, y as FormError, yt as MenubarContainer, z as FormSubmit, zt as SelectLabel } from "../text-truncate-C17HHCR-.js";
+import { $ as Identity, A as PageHeader, B as DropdownTrigger, C as Logo, D as Section, E as ResizablePanelGroup, F as RadioGroup, G as Textarea, H as StepBuilder, I as DropdownContent, J as CardContent, K as Switch, L as DropdownItem, M as BlockLayout, O as Container, P as Radio, Q as CardTitle, R as DropdownMenu, S as DrawerRoot, T as ResizablePanel, U as CircularProgress, V as ConditionBuilder, W as Progress, X as CardFooter, Y as CardDescription, Z as CardHeader, _ as getShaderFragment, a as THEME_PALETTES, at as AccordionItem, b as DrawerClose, c as ExpressionGroup, ct as Toggle, d as ShaderSurface, dt as Separator, et as Avatar, f as SHADER_OVERLAY_PARAM_KEYS, ft as Heading, g as SHADER_PRESET_IDS, h as SHADER_PRESETS, i as ColorPalettePicker, it as AccordionContent, j as createBlock, k as ScrollArea, l as Facet, lt as ToggleGroup, m as SHADER_PARAM_KEYS, n as InlineEdit, nt as DescriptionList, o as LiveRegion, ot as AccordionRoot, p as SHADER_PARAM_FALLBACK, pt as Text, q as Card, r as ColorPaletteDisplay, rt as Breadcrumb, s as Expression, st as AccordionTrigger, t as KeyPadMenu, tt as AvatarGroup, u as FacetGroup, ut as OtpField, v as getShaderPreset, w as ResizableHandle, x as DrawerPanel, y as VirtualList, z as DropdownSeparator } from "../key-pad-menu-wXkWn1I1.js";
+export { AccordionContent, AccordionItem, AccordionRoot, AccordionTrigger, Alert, AlertDialogPanel, Avatar, AvatarGroup, Badge, BlockLayout, BlockLayout as SurfaceLayout, Breadcrumb, Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, CheckboxGroup, CircularProgress, ColorPaletteDisplay, ColorPalettePicker, ColorPicker, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxPopover, ComboboxRoot, Composite, CompositeItem, CompositeProvider, CompositeRow, CompositeZone, ConditionBuilder, Container, DEFAULT_PRESETS, DateRangePicker, DescriptionList, DialogBody, DialogDescription, DialogDisclosure, DialogDismiss, DialogFooter, DialogHeader, DialogHeading, DialogPanel, DialogRoot, DisclosureContent, DisclosureRoot, DisclosureTrigger, DrawerClose, DrawerPanel, DrawerRoot, DropdownContent, DropdownItem, DropdownMenu, DropdownSeparator, DropdownTrigger, EmptyState, Expression, ExpressionGroup, FIELD_TYPE_TOKENS, Facet, FacetGroup, FieldToken, FormCheckbox, FormControl, FormDescription, FormError, FormField, FormGroup, FormGroupLabel, FormInput, FormLabel, FormProvider, FormPush, FormRadio, FormRadioGroup, FormRemove, FormReset, FormRoot, FormSelect, FormSelectItem, FormSelectPopover, FormSubmit, FormSwitch, FormTextarea, Heading, Highlight, IconPicker, Identity, InlineEdit, Input, Kbd, KeyPadMenu, LiveRegion, Logo, MenuButtonArrow, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuRoot, MenuSeparator, MenuTrigger, MenubarContainer, MenubarRoot, Meter, NumberInput, OtpField, PageHeader, Pagination, PopoverClose, PopoverContent, PopoverRoot, PopoverTrigger, Progress, Radio, RadioGroup, ResizableHandle, ResizablePanel, ResizablePanelGroup, SHADER_OVERLAY_PARAM_KEYS, SHADER_PARAM_FALLBACK, SHADER_PARAM_KEYS, SHADER_PRESETS, SHADER_PRESET_IDS, ScrollArea, Section, SelectItem, SelectLabel, SelectPopover, SelectRoot, SelectTrigger, Separator, ShaderSurface, Skeleton, SkeletonAvatar, SkeletonCard, SkeletonTable, SkeletonText, Slider, Spinner, StatCard, StepBuilder, Switch, THEME_PALETTES, Tab, TabList, TabPanel, TabsRoot, TagInput, Text, TextTruncate, Textarea, Toggle, ToggleGroup, ToolbarButton, ToolbarContainer, ToolbarRoot, ToolbarSeparator, Tooltip, TooltipAnchor, TooltipProvider, VirtualList, createBlock, createBlock as createSurface, getShaderFragment, getShaderPreset, resolveFieldType, useFormContext, useFormStore };

package/dist/docs/02-components/01-core.md

@@ -1,11 +1,11 @@
 ---
 title: "Core Components"
-description: "68 Core layer components — props, examples, keyboard shortcuts."
-version: "1.9.0"
+description: "70 Core layer components — props, examples, keyboard shortcuts."
+version: "1.10.0"
 generated: true
 ---
 
-# Core Components (68)
+# Core Components (70)
 
 ## Input
 
@@ -736,7 +736,7 @@ const store = useFormStore({
 | Card           | 범용 카드 컨테이너. Header, Title, Description, Content, Footer 하위 컴포넌트 포함.                                         | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` |
 | Breadcrumb     | 현재 위치를 표시하고 계층 탐색을 제공하는 컴포넌트.                                                                         | `Breadcrumb`                                                                      |
 | EmptyState     | 데이터가 없을 때 표시하는 빈 상태 컴포넌트. 아이콘, 제목, 설명, 액션 버튼 지원.                                             | `EmptyState`                                                                      |
-| StatCard       | 트렌드 방향과 변화량을 표시하는 통계 카드.                                                                                  | `StatCard`                                                                        |
+| StatCard       | 단일 지표를 값·변화량·보조 설명으로 표시하는 통계 카드. 비교 기준이 없으면 변화량 줄을 렌더하지 않는다.                     | `StatCard`                                                                        |
 | Logo           | 아이콘+텍스트 조합, 이미지, 링크 래핑을 지원하는 로고 컴포넌트. Sidebar 등에서 활용.                                        | `Logo`                                                                            |
 
 ### Kbd
@@ -1006,25 +1006,42 @@ import {
 
 **Import:** `import { EmptyState } from "@reopt-ai/opt-ui"`
 
-| Prop          | Type                 | Required | Default | Description                                  |
-| ------------- | -------------------- | -------- | ------- | -------------------------------------------- |
-| `title`       | `string`             | Yes      |         | 빈 상태 제목                                 |
-| `description` | `string`             |          |         | 빈 상태 설명                                 |
-| `icon`        | `ReactNode`          |          |         | 표시할 아이콘                                |
-| `actions`     | `EmptyStateAction[]` |          |         | 액션 버튼 배열. { label, onClick, variant? } |
+| Prop           | Type                                | Required | Default    | Description                                                                    |
+| -------------- | ----------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------ |
+| `title`        | `string`                            | Yes      |            | 빈 상태 제목                                                                   |
+| `description`  | `string`                            |          |            | 빈 상태 설명                                                                   |
+| `icon`         | `ReactNode`                         |          |            | 표시할 아이콘                                                                  |
+| `actions`      | `EmptyStateAction[] \| ReactNode`   |          |            | 액션 버튼 배열 { label, onClick, variant? } 또는 직접 렌더할 노드              |
+| `body`         | `ReactNode`                         |          |            | description 대신 넣는 리치 본문 (문단·목록·코드 스니펫)                        |
+| `footer`       | `ReactNode`                         |          |            | 구분선 아래 보조 콘텐츠. 문서 링크·단축키 안내 등                              |
+| `layout`       | `"vertical" \| "horizontal"`        |          | "vertical" | horizontal은 아이콘을 텍스트 옆으로 옮긴다 (전체 페이지용)                     |
+| `titleSize`    | `"sm" \| "md" \| "lg"`              |          | "md"       | 제목 시각 크기. headingLevel과 독립                                            |
+| `hasBorder`    | `boolean`                           |          | false      | 테두리 있는 패널로 렌더                                                        |
+| `tone`         | `"default" \| "subdued" \| "error"` |          | "default"  | error는 실패를 알리고 role=alert로 렌더. subdued는 아직 데이터가 없음을 뜻한다 |
+| `iconSize`     | `"sm" \| "md" \| "lg"`              |          | "md"       | 아이콘 크기 프리셋                                                             |
+| `headingLevel` | `"h2" \| "h3" \| "h4"`              |          | "h3"       | 문서 구조상 제목 레벨                                                          |
 
 ### StatCard
 
-> 트렌드 방향과 변화량을 표시하는 통계 카드.
+> 단일 지표를 값·변화량·보조 설명으로 표시하는 통계 카드. 비교 기준이 없으면 변화량 줄을 렌더하지 않는다.
 
 **Import:** `import { StatCard } from "@reopt-ai/opt-ui"`
 
-| Prop     | Type                          | Required | Default | Description                     |
-| -------- | ----------------------------- | -------- | ------- | ------------------------------- |
-| `title`  | `string`                      | Yes      |         | 통계 제목                       |
-| `value`  | `string`                      | Yes      |         | 통계 값                         |
-| `change` | `string`                      | Yes      |         | 변화량 텍스트 (예: '+12.5%')    |
-| `trend`  | `"up" \| "down" \| "neutral"` | Yes      |         | 트렌드 방향. 색상과 아이콘 결정 |
+| Prop            | Type                          | Required | Default    | Description                                                                             |
+| --------------- | ----------------------------- | -------- | ---------- | --------------------------------------------------------------------------------------- |
+| `title`         | `string`                      | Yes      |            | 통계 제목                                                                               |
+| `value`         | `string`                      | Yes      |            | 통계 값                                                                                 |
+| `change`        | `string`                      |          |            | 변화량 텍스트 (예: '+12.5%'). 비교 기준이 없으면 생략 — trend와 함께 있을 때만 렌더된다 |
+| `trend`         | `"up" \| "down" \| "neutral"` |          |            | 변화 방향. change와 함께 있을 때만 의미를 갖는다                                        |
+| `polarity`      | `"positive" \| "negative"`    |          | "positive" | 상승이 좋은 지표인지. 이탈률·에러 수처럼 반대인 지표는 negative로 색을 뒤집는다         |
+| `description`   | `string`                      |          |            | 값 아래 한 줄 보조 설명 (집계 대상·기간 등)                                             |
+| `hint`          | `string`                      |          |            | 산출 근거 등 긴 설명. 툴팁과 aria-describedby로 노출                                    |
+| `size`          | `"sm" \| "md"`                |          | "md"       | 밀도 프리셋. 요약 행에는 sm                                                             |
+| `loading`       | `boolean`                     |          | false      | 값 로딩 중 스켈레톤 표시                                                                |
+| `href`          | `string`                      |          |            | 드릴다운 링크. 지정 시 카드가 앵커로 렌더된다                                           |
+| `onSelect`      | `() => void`                  |          |            | 드릴다운 핸들러. 지정 시 카드가 버튼으로 렌더된다                                       |
+| `selected`      | `boolean`                     |          | false      | 선택 가능한 카드 행에서 현재 선택 상태                                                  |
+| `sparklineData` | `number[]`                    |          |            | 값 옆에 그릴 미니 추세선 데이터                                                         |
 
 ### Logo
 
@@ -1662,30 +1679,32 @@ import {
 
 ## Other
 
-| Component     | Description                                                                                                                                                                               | Key Exports                                                                                                                                     |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| FieldToken    | 필드 타입을 글리프 하나로 표현하는 토큰. 문자열·숫자·날짜·IP·지오 등 분석 스키마 타입마다 고정된 아이콘과 팔레트 슬롯을 부여해 필드 목록·컬럼 헤더·속성 테이블 전역에서 같은 어휘를 쓴다. | `FieldToken`, `FIELD_TYPE_TOKENS`, `resolveFieldType`                                                                                           |
-| Facet         | 필드 값 분포를 카운트와 점유율 막대로 보여주고 그 행 자체가 필터가 되는 패싯. 긴 꼬리는 접어 두고 상위 값부터 읽힌다.                                                                     | `Facet`, `FacetGroup`                                                                                                                           |
-| Expression    | 조건을 폼이 아니라 문장으로 쓰고 그 자리에서 편집하는 표현식 절. 알림 규칙·세그먼트 필터처럼 읽어서 검증해야 하는 조건에 쓴다.                                                            | `Expression`, `ExpressionGroup`                                                                                                                 |
-| TextTruncate  | 실제 폰트로 실제 가용 폭을 측정해 문자열의 식별력이 가장 낮은 부분을 잘라내는 생략. CSS가 못 하는 앞·중간·양끝 생략을 지원하고 전체 문자열은 접근성 트리에 남는다.                        | `TextTruncate`                                                                                                                                  |
-| Highlight     | 검색어에 해당하는 구간을 <mark>로 표시. 긴 항목 우선 매칭이라 겹치는 검색어도 조각나지 않는다.                                                                                            | `Highlight`                                                                                                                                     |
-| LiveRegion    | 라이브 뷰의 변화를 스크린 리더에 읽어 주는 영역. 스로틀로 폭주를 요약하고 두 노드를 번갈아 써서 같은 문구도 다시 읽힌다.                                                                  | `LiveRegion`                                                                                                                                    |
-| ColorPalette  | 시각화 색 팔레트를 그 팔레트의 모습 그대로 보여 주고 고르게 하는 컴포넌트. 범주형은 블록, 순차·발산형은 그라디언트로 그려 데이터 종류를 그림이 말한다.                                    | `ColorPaletteDisplay`, `ColorPalettePicker`, `THEME_PALETTES`                                                                                   |
-| InlineEdit    | 대시보드 제목·지표 이름처럼 읽히는 횟수가 훨씬 많은 값을 그 자리에서 고치는 편집. Enter 확정, Escape 되돌리기, 거절된 저장은 입력을 유지한다.                                             | `InlineEdit`                                                                                                                                    |
-| KeyPadMenu    | 이름보다 그림으로 알아보기 쉬운 선택지를 타일로 고르는 메뉴. 내부는 실제 radio·checkbox라 키보드와 스크린 리더가 그대로 동작한다.                                                         | `KeyPadMenu`                                                                                                                                    |
-| Text          | 본문, 레이블, 보조 설명, 코드에 일관된 의미 기반 타이포그래피를 적용합니다.                                                                                                               | `Text`                                                                                                                                          |
-| Heading       | 문서의 의미 계층과 시각적 타이포그래피 계층을 독립적으로 제어합니다.                                                                                                                      | `Heading`                                                                                                                                       |
-| Separator     | 콘텐츠를 구분하는 가로/세로 디바이더. 라벨을 넣으면 가운데 정렬 구분선이 된다.                                                                                                            | `Separator`                                                                                                                                     |
-| OtpField      | 일회용 코드(OTP)/PIN 입력. 셀 단위 입력, 붙여넣기 분배, 자동 포커스 이동, 백스페이스 네비게이션과 폼 이름/오류 연결을 지원합니다.                                                         | `OtpField`                                                                                                                                      |
-| Toggle        | 눌림(pressed) 두 상태 버튼. 단독 사용하거나 ToggleGroup으로 묶어 단일/다중 선택을 만든다.                                                                                                 | `Toggle`, `ToggleGroup`                                                                                                                         |
-| Accordion     | 수직으로 쌓인 펼침/접힘 패널. single(한 개)/multiple(여러 개) 모드와 collapsible 지원.                                                                                                    | `AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`                                                                        |
-| Meter         | 범위 내 스칼라 측정값 게이지 (디스크 사용량·점수·용량 등). role=meter로 작업 진행률(Progress)과 구분된다.                                                                                 | `Meter`                                                                                                                                         |
-| BlockLayout   | Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다.                                                          | `BlockLayout`                                                                                                                                   |
-| createBlock   | Block 팩토리 함수. BlockLayout 래핑을 구조적으로 강제하여 loading/className 처리를 자동화합니다.                                                                                          | `createBlock`                                                                                                                                   |
-| StarRating    | 1~N점 별점을 선택하는 인터랙티브 레이팅 입력. 읽기 전용 표시도 지원.                                                                                                                      | `StarRating`                                                                                                                                    |
-| ErrorBoundary | React 에러 바운더리. 자식 컴포넌트 렌더 에러를 잡아 fallback UI를 표시합니다.                                                                                                             | `ErrorBoundary`                                                                                                                                 |
-| Command       | cmdk 스타일 명령 anatomy. 자동 필터링 + 키보드 내비게이션. 인라인 또는 CommandDialog로 사용.                                                                                              | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut` |
-| ShaderSurface | ogl 기반 애니메이션 WebGL 셰이더 배경. 럭셔리 프리셋(메탈릭/실크/유리 등) + 색·파라미터로 배경·카드 배경을 만든다. 정지 프레임·PNG 캡처·WebGL 폴백 지원.                                  | `ShaderSurface`                                                                                                                                 |
+| Component       | Description                                                                                                                                                                               | Key Exports                                                                                                                                     |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| FieldToken      | 필드 타입을 글리프 하나로 표현하는 토큰. 문자열·숫자·날짜·IP·지오 등 분석 스키마 타입마다 고정된 아이콘과 팔레트 슬롯을 부여해 필드 목록·컬럼 헤더·속성 테이블 전역에서 같은 어휘를 쓴다. | `FieldToken`, `FIELD_TYPE_TOKENS`, `resolveFieldType`                                                                                           |
+| Facet           | 필드 값 분포를 카운트와 점유율 막대로 보여주고 그 행 자체가 필터가 되는 패싯. 긴 꼬리는 접어 두고 상위 값부터 읽힌다.                                                                     | `Facet`, `FacetGroup`                                                                                                                           |
+| Expression      | 조건을 폼이 아니라 문장으로 쓰고 그 자리에서 편집하는 표현식 절. 알림 규칙·세그먼트 필터처럼 읽어서 검증해야 하는 조건에 쓴다.                                                            | `Expression`, `ExpressionGroup`                                                                                                                 |
+| TextTruncate    | 실제 폰트로 실제 가용 폭을 측정해 문자열의 식별력이 가장 낮은 부분을 잘라내는 생략. CSS가 못 하는 앞·중간·양끝 생략을 지원하고 전체 문자열은 접근성 트리에 남는다.                        | `TextTruncate`                                                                                                                                  |
+| Highlight       | 검색어에 해당하는 구간을 <mark>로 표시. 긴 항목 우선 매칭이라 겹치는 검색어도 조각나지 않는다.                                                                                            | `Highlight`                                                                                                                                     |
+| LiveRegion      | 라이브 뷰의 변화를 스크린 리더에 읽어 주는 영역. 스로틀로 폭주를 요약하고 두 노드를 번갈아 써서 같은 문구도 다시 읽힌다.                                                                  | `LiveRegion`                                                                                                                                    |
+| ColorPalette    | 시각화 색 팔레트를 그 팔레트의 모습 그대로 보여 주고 고르게 하는 컴포넌트. 범주형은 블록, 순차·발산형은 그라디언트로 그려 데이터 종류를 그림이 말한다.                                    | `ColorPaletteDisplay`, `ColorPalettePicker`, `THEME_PALETTES`                                                                                   |
+| InlineEdit      | 대시보드 제목·지표 이름처럼 읽히는 횟수가 훨씬 많은 값을 그 자리에서 고치는 편집. Enter 확정, Escape 되돌리기, 거절된 저장은 입력을 유지한다.                                             | `InlineEdit`                                                                                                                                    |
+| KeyPadMenu      | 이름보다 그림으로 알아보기 쉬운 선택지를 타일로 고르는 메뉴. 내부는 실제 radio·checkbox라 키보드와 스크린 리더가 그대로 동작한다.                                                         | `KeyPadMenu`                                                                                                                                    |
+| Text            | 본문, 레이블, 보조 설명, 코드에 일관된 의미 기반 타이포그래피를 적용합니다.                                                                                                               | `Text`                                                                                                                                          |
+| Heading         | 문서의 의미 계층과 시각적 타이포그래피 계층을 독립적으로 제어합니다.                                                                                                                      | `Heading`                                                                                                                                       |
+| Separator       | 콘텐츠를 구분하는 가로/세로 디바이더. 라벨을 넣으면 가운데 정렬 구분선이 된다.                                                                                                            | `Separator`                                                                                                                                     |
+| OtpField        | 일회용 코드(OTP)/PIN 입력. 셀 단위 입력, 붙여넣기 분배, 자동 포커스 이동, 백스페이스 네비게이션과 폼 이름/오류 연결을 지원합니다.                                                         | `OtpField`                                                                                                                                      |
+| Toggle          | 눌림(pressed) 두 상태 버튼. 단독 사용하거나 ToggleGroup으로 묶어 단일/다중 선택을 만든다.                                                                                                 | `Toggle`, `ToggleGroup`                                                                                                                         |
+| Accordion       | 수직으로 쌓인 펼침/접힘 패널. single(한 개)/multiple(여러 개) 모드와 collapsible 지원.                                                                                                    | `AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`                                                                        |
+| Meter           | 범위 내 스칼라 측정값 게이지 (디스크 사용량·점수·용량 등). role=meter로 작업 진행률(Progress)과 구분된다.                                                                                 | `Meter`                                                                                                                                         |
+| DescriptionList | 한 대상의 라벨 있는 사실들을 시맨틱 <dl>로 표시한다. 상세 패널의 필드 나열을 표준화하고 식별자 복사를 제공한다.                                                                           | `DescriptionList`                                                                                                                               |
+| Identity        | 사람(또는 익명 디바이스)을 목록 셀 한 칸으로 표현한다. 이름→이메일→ID 폴백과 익명 표식을 한 곳에서 처리한다.                                                                              | `Identity`                                                                                                                                      |
+| BlockLayout     | Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다.                                                          | `BlockLayout`                                                                                                                                   |
+| createBlock     | Block 팩토리 함수. BlockLayout 래핑을 구조적으로 강제하여 loading/className 처리를 자동화합니다.                                                                                          | `createBlock`                                                                                                                                   |
+| StarRating      | 1~N점 별점을 선택하는 인터랙티브 레이팅 입력. 읽기 전용 표시도 지원.                                                                                                                      | `StarRating`                                                                                                                                    |
+| ErrorBoundary   | React 에러 바운더리. 자식 컴포넌트 렌더 에러를 잡아 fallback UI를 표시합니다.                                                                                                             | `ErrorBoundary`                                                                                                                                 |
+| Command         | cmdk 스타일 명령 anatomy. 자동 필터링 + 키보드 내비게이션. 인라인 또는 CommandDialog로 사용.                                                                                              | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut` |
+| ShaderSurface   | ogl 기반 애니메이션 WebGL 셰이더 배경. 럭셔리 프리셋(메탈릭/실크/유리 등) + 색·파라미터로 배경·카드 배경을 만든다. 정지 프레임·PNG 캡처·WebGL 폴백 지원.                                  | `ShaderSurface`                                                                                                                                 |
 
 ### FieldToken
 
@@ -2028,6 +2047,38 @@ import {
 | `showValue` | `boolean`                                        |          | false     | 퍼센트 표시   |
 | `label`     | `string`                                         |          |           | 레이블 텍스트 |
 
+### DescriptionList
+
+> 한 대상의 라벨 있는 사실들을 시맨틱 <dl>로 표시한다. 상세 패널의 필드 나열을 표준화하고 식별자 복사를 제공한다.
+
+**Import:** `import { DescriptionList } from "@reopt-ai/opt-ui"`
+
+| Prop         | Type                            | Required | Default | Description                                                                                                      |
+| ------------ | ------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| `items`      | `DescriptionListItem[]`         | Yes      |         | term/description 쌍 배열. { id, term, description, copyValue?, hint?, wrap? }                                    |
+| `layout`     | `"grid" \| "stack" \| "inline"` |          | "grid"  | grid는 각 쌍을 박스로 감싼다(필드가 많은 상세 패널). stack은 평범한 정의 목록, inline은 헤더 스트립용 한 줄 배치 |
+| `columns`    | `1 \| 2 \| 3 \| 4`              |          | 2       | grid/stack 레이아웃의 컬럼 수                                                                                    |
+| `compressed` | `boolean`                       |          | false   | 밀도 축소                                                                                                        |
+| `labels`     | `DescriptionListLabels`         |          |         | 복사/복사됨/빈 값 문구                                                                                           |
+
+### Identity
+
+> 사람(또는 익명 디바이스)을 목록 셀 한 칸으로 표현한다. 이름→이메일→ID 폴백과 익명 표식을 한 곳에서 처리한다.
+
+**Import:** `import { Identity } from "@reopt-ai/opt-ui"`
+
+| Prop         | Type                                          | Required | Default | Description                                                  |
+| ------------ | --------------------------------------------- | -------- | ------- | ------------------------------------------------------------ |
+| `name`       | `string \| null`                              |          |         | 표시 이름. 없으면 secondary, 그다음 id로 폴백한다            |
+| `secondary`  | `string \| null`                              |          |         | 보통 이메일. 이름이 없으면 주 라벨로 승격된다                |
+| `id`         | `string`                                      |          |         | 최후 폴백 라벨이자 hover 시 title                            |
+| `avatarSrc`  | `string \| null`                              |          |         | 아바타 이미지 URL                                            |
+| `state`      | `"identified" \| "anonymous"`                 |          |         | 익명 여부. 디바이스를 사람으로 오독하지 않게 배지로 표시한다 |
+| `badge`      | `ReactNode`                                   |          |         | state 배지 대신 표시할 내용 (라이프사이클 단계 등)           |
+| `size`       | `"sm" \| "md"`                                |          | "md"    | 밀도 프리셋                                                  |
+| `hideAvatar` | `boolean`                                     |          | false   | 이미 밀도가 높은 행에서 아바타 제거                          |
+| `labels`     | `{ identified?: string; anonymous?: string }` |          |         | 식별/익명 배지 문구                                          |
+
 ### BlockLayout
 
 > Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다.

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

@@ -1,7 +1,7 @@
 ---
 title: "Visual Components"
 description: "0 Visual layer components — props, examples, keyboard shortcuts."
-version: "1.9.0"
+version: "1.10.0"
 generated: true
 ---
 

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

@@ -1,11 +1,11 @@
 ---
 title: "Shell Components"
-description: "80 Shell layer components — props, examples, keyboard shortcuts."
-version: "1.9.0"
+description: "83 Shell layer components — props, examples, keyboard shortcuts."
+version: "1.10.0"
 generated: true
 ---
 
-# Shell Components (80)
+# Shell Components (83)
 
 ## Navigation & Layout
 
@@ -434,15 +434,17 @@ import { DataTable } from "@reopt-ai/opt-ui";
 **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   | 로딩 시 스켈레톤 표시            |
+| Prop                       | Type                             | Required | Default | Description                                             |
+| -------------------------- | -------------------------------- | -------- | ------- | ------------------------------------------------------- |
+| `stats`                    | `StatCardType[]`                 | Yes      |         | 통계 카드 배열                                          |
+| `columns`                  | `2 \| 3 \| 4 \| 5 \| 6`          |          | 4       | 컬럼 수                                                 |
+| `onStatClick`              | `(stat: StatCardType) => void`   |          |         | 카드 클릭 핸들러. 지정 시 카드 자체가 버튼으로 렌더된다 |
+| `selectedStatId`           | `string`                         |          |         | 선택 가능한 행에서 현재 뷰를 이끄는 카드 id             |
+| `size`                     | `"sm" \| "md"`                   |          | "md"    | 카드 밀도. 표 위 헤더 스트립에는 sm                     |
+| `formatValue`              | `(stat: StatCardType) => string` |          |         | 값 표시 커스텀 포맷 함수                                |
+| `durationFractionDigits`   | `number`                         |          | 1       | duration 포맷 시 소수점 자리수                          |
+| `percentageFractionDigits` | `number`                         |          | 1       | percentage 포맷 시 소수점 자리수                        |
+| `loading`                  | `boolean`                        |          | false   | 로딩 시 스켈레톤 표시                                   |
 
 ### CodeSnippetViewer
 
@@ -1323,20 +1325,23 @@ const fields = [
 
 ## 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`                          |
-| 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`                             |
+| Component        | Description                                                                                                                                      | Key Exports                                |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| PageAside        | Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.                                                                        | `PageAside`                                |
+| FailureList      | 실패 목록 패널. severity별 색상 강조, 그룹핑, 액션 슬롯을 지원합니다.                                                                            | `FailureList`                              |
+| KeyValueEditor   | 키-값 쌍 편집기. 동적 행 추가/삭제, 비밀값 토글, 유효성 검사를 지원합니다.                                                                       | `KeyValueEditor`                           |
+| EventTimeline    | 이벤트를 순서로 읽히게 하는 타임라인. 인접 이벤트 사이의 경과 시간을 라벨링하고, 속성 페이로드를 제자리에서 펼치며, 세션 단위 그룹핑을 지원한다. | `EventTimeline`                            |
+| ScoreBreakdown   | 합성 점수를 축별로 분해해 보여준다. 총점과 함께 각 축의 값·가중치·의미를 노출해 '43'을 판정이 아니라 발견으로 만든다.                            | `ScoreBreakdown`                           |
+| Flyout           | 목록을 화면에 둔 채 레코드를 옆에서 보여주는 상세 패널. 모달이 아니다 — 포커스 트랩·aria-modal·inert 없이 Escape로 닫고 포커스를 되돌린다.       | `Flyout`                                   |
+| 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`                             |
 
 ### PageAside
 
@@ -1400,6 +1405,71 @@ const fields = [
 | ----- | ------------------ |
 | `Tab` | 키/값 필드 간 이동 |
 
+### EventTimeline
+
+> 이벤트를 순서로 읽히게 하는 타임라인. 인접 이벤트 사이의 경과 시간을 라벨링하고, 속성 페이로드를 제자리에서 펼치며, 세션 단위 그룹핑을 지원한다.
+
+**Import:** `import { EventTimeline } from "@reopt-ai/opt-ui"`
+
+| Prop           | Type                                | Required | Default | Description                                                                   |
+| -------------- | ----------------------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
+| `items`        | `EventTimelineItem[]`               |          |         | 평면 목록. groups가 있으면 무시된다                                           |
+| `groups`       | `EventTimelineGroup[]`              |          |         | 그룹(주로 세션) 단위 목록. 접기/펼치기와 그룹 요약을 제공                     |
+| `showGaps`     | `boolean`                           |          | true    | 인접 이벤트 사이 경과 시간 표시. 체크아웃 직전 4분 정지 같은 것이 발견이 된다 |
+| `order`        | `"desc" \| "asc"`                   |          | "desc"  | 전달된 items의 정렬 방향. 경과 시간 계산 기준                                 |
+| `minGapMs`     | `number`                            |          | 1000    | 이 값 미만의 간격은 라벨을 생략                                               |
+| `loading`      | `boolean`                           |          | false   | 스켈레톤 표시                                                                 |
+| `hasMore`      | `boolean`                           |          | false   | 더 불러올 항목 존재                                                           |
+| `onLoadMore`   | `() => void`                        |          |         | 더 보기 핸들러                                                                |
+| `onItemSelect` | `(item: EventTimelineItem) => void` |          |         | 이벤트 헤드라인 클릭 핸들러                                                   |
+| `locale`       | `string`                            |          |         | 경과 시간 포맷 로케일                                                         |
+| `labels`       | `EventTimelineLabels`               |          |         | 문구 오버라이드                                                               |
+
+### ScoreBreakdown
+
+> 합성 점수를 축별로 분해해 보여준다. 총점과 함께 각 축의 값·가중치·의미를 노출해 '43'을 판정이 아니라 발견으로 만든다.
+
+**Import:** `import { ScoreBreakdown } from "@reopt-ai/opt-ui"`
+
+| Prop      | Type                   | Required | Default | Description                                        |
+| --------- | ---------------------- | -------- | ------- | -------------------------------------------------- |
+| `score`   | `number`               | Yes      |         | 총점                                               |
+| `max`     | `number`               |          | 100     | 총점 상한                                          |
+| `axes`    | `ScoreAxis[]`          | Yes      |         | 기여 축 배열. { id, label, value, hint?, weight? } |
+| `bands`   | `ScoreBand[]`          |          |         | 점수 구간 이름과 색. { min, label, tone? }         |
+| `formula` | `ReactNode`            |          |         | 총점 산출식 설명 한 줄                             |
+| `loading` | `boolean`              |          | false   | 스켈레톤 표시                                      |
+| `labels`  | `ScoreBreakdownLabels` |          |         | 문구 오버라이드                                    |
+
+### Flyout
+
+> 목록을 화면에 둔 채 레코드를 옆에서 보여주는 상세 패널. 모달이 아니다 — 포커스 트랩·aria-modal·inert 없이 Escape로 닫고 포커스를 되돌린다.
+
+**Import:** `import { Flyout } from "@reopt-ai/opt-ui"`
+
+| Prop                  | Type                    | Required | Default   | Description                                                                         |
+| --------------------- | ----------------------- | -------- | --------- | ----------------------------------------------------------------------------------- |
+| `open`                | `boolean`               | Yes      |           | 열림 상태                                                                           |
+| `onClose`             | `() => void`            | Yes      |           | 닫기 핸들러                                                                         |
+| `title`               | `ReactNode`             |          |           | 패널 제목                                                                           |
+| `description`         | `ReactNode`             |          |           | 제목 아래 한 줄 설명                                                                |
+| `type`                | `"overlay" \| "inline"` |          | "overlay" | overlay는 페이지 위에 띄우고, inline은 aside로 렌더해 배치를 부모 레이아웃에 맡긴다 |
+| `side`                | `"right" \| "left"`     |          | "right"   | overlay일 때 붙는 방향                                                              |
+| `size`                | `"sm" \| "md" \| "lg"`  |          | "md"      | 패널 너비                                                                           |
+| `actions`             | `ReactNode`             |          |           | 닫기 버튼 앞 컨트롤                                                                 |
+| `footer`              | `ReactNode`             |          |           | 하단 고정 영역                                                                      |
+| `scrim`               | `boolean`               |          | false     | 뒤 페이지를 어둡게. 기본 off — 목록이 계속 읽혀야 한다                              |
+| `closeOnOutsideClick` | `boolean`               |          | true      | 바깥 클릭 시 닫기 (overlay 전용)                                                    |
+| `hideCloseButton`     | `boolean`               |          | false     | 닫기 버튼 숨김                                                                      |
+| `labels`              | `FlyoutLabels`          |          |           | 문구 오버라이드                                                                     |
+| `children`            | `ReactNode`             | Yes      |           | 패널 본문                                                                           |
+
+**Keyboard Shortcuts:**
+
+| Keys     | Action                              |
+| -------- | ----------------------------------- |
+| `Escape` | 패널 닫고 여는 컨트롤로 포커스 복귀 |
+
 ### AuditTimeline
 
 > 변경 이력 타임라인. 액션별 색상 코딩 + 확장 가능한 diff 뷰.

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.9.0"
+version: "1.10.0"
 generated: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 title: "Component Reference"
-description: "Complete reference for 148 @reopt-ai/opt-ui components across 4 layers."
-version: "1.9.0"
+description: "Complete reference for 153 @reopt-ai/opt-ui components across 4 layers."
+version: "1.10.0"
 generated: true
 ---
 
@@ -11,11 +11,11 @@ generated: true
 
 | Layer     | Count   |
 | --------- | ------- |
-| Core      | 68      |
+| Core      | 70      |
 | Visuals   | 0       |
-| Shells    | 80      |
+| Shells    | 83      |
 | Surfaces  | 0       |
-| **Total** | **148** |
+| **Total** | **153** |
 
 ## Component Selection Guide