@reopt-ai/opt-ui 1.13.0 → 1.15.0

package/dist/meta.js

@@ -531,7 +531,7 @@ const coreMetas = [
 				name: "onSave",
 				type: "(next: string) => boolean | void | Promise<boolean | void>",
 				required: true,
-				description: "저장. false를 반환하면 거절하고 편집을 유지"
+				description: "저장. false 반환 또는 Promise 실패 시 입력을 유지하고 오류를 알림"
 			},
 			{
 				name: "as",
@@ -575,7 +575,7 @@ const coreMetas = [
 			{
 				name: "labels",
 				type: "InlineEditLabels",
-				description: "지역화 문자열"
+				description: "입력 이름(input), 편집·저장·취소·오류 안내 문자열"
 			},
 			{
 				name: "className",
@@ -1221,7 +1221,7 @@ const coreMetas = [
 				{
 					name: "setOpen",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "onOpenChange"
 					},
 					type: "(open: boolean) => void",
@@ -1258,6 +1258,26 @@ const coreMetas = [
 		testDescribe: "Disclosure"
 	},
 	{
+		usage: {
+			anatomy: ["TabsRoot 안에 TabList와 TabPanel을 두고 Tab.id와 TabPanel.tabId를 맞춥니다."],
+			bestPractices: ["TabList에 접근 가능한 이름을 지정하고, 제어 모드는 selectedId와 onSelectedIdChange를 함께 연결합니다."],
+			avoid: ["다른 URL로 이동하는 주 내비게이션을 탭 패널로 구현하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "이름 있는 두 패널",
+			code: `import { TabsRoot, TabList, Tab, TabPanel } from "@reopt-ai/opt-ui";
+
+export function Example() {
+  return <TabsRoot defaultSelectedId="overview">
+    <TabList aria-label="프로젝트 정보">
+      <Tab id="overview">개요</Tab><Tab id="activity">활동</Tab>
+    </TabList>
+    <TabPanel tabId="overview">프로젝트 요약</TabPanel>
+    <TabPanel tabId="activity">최근 활동</TabPanel>
+  </TabsRoot>;
+}`
+		}],
 		name: "Tabs",
 		category: "core",
 		description: "탭 패널 시스템. 4-part anatomy: Root, TabList, Tab, TabPanel.",
@@ -1302,7 +1322,7 @@ const coreMetas = [
 				{
 					name: "setSelectedId",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "onSelectedIdChange"
 					},
 					type: "(id: string | null) => void",
@@ -1385,6 +1405,11 @@ const coreMetas = [
 		testDescribe: "Tabs"
 	},
 	{
+		usage: {
+			anatomy: ["SelectRoot 안에 Label, Trigger, Popover, Item을 조합합니다."],
+			bestPractices: ["옵션 value는 표시 문구와 분리된 안정적인 키로 유지합니다. multiple 모드에서는 배열 값을 사용합니다."],
+			avoid: ["선택 목록에 명령 실행 버튼을 섞지 않습니다. 명령은 DropdownMenu로 분리합니다."]
+		},
 		name: "Select",
 		category: "core",
 		description: "드롭다운 선택 컴포넌트. 5-part anatomy: Root, Label, Trigger, Popover, Item.",
@@ -1474,7 +1499,7 @@ const coreMetas = [
 				{
 					name: "gutter",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "sideOffset"
 					},
 					type: "number",
@@ -1525,6 +1550,11 @@ const coreMetas = [
 		}]
 	},
 	{
+		usage: {
+			anatomy: ["DialogRoot에서 Disclosure와 Panel을 연결하고 Panel 안에 Heading과 Description을 둡니다."],
+			bestPractices: ["열림을 제어할 때 open과 onOpenChange를 함께 제공합니다. 닫기 동작은 DialogDismiss로 노출합니다."],
+			avoid: ["제목 없는 모달이나 종료 방법 없는 모달을 만들지 않습니다. 파괴적 확인은 AlertDialogPanel의 계약을 사용합니다."]
+		},
 		name: "Dialog",
 		category: "core",
 		description: "모달 다이얼로그. 9-part anatomy: Root, Disclosure, Panel, Heading, Description, Dismiss, Header, Body, Footer.",
@@ -1556,7 +1586,7 @@ const coreMetas = [
 			}, {
 				name: "setOpen",
 				deprecated: {
-					since: "1.12.5",
+					since: "1.13.0",
 					replacement: "onOpenChange"
 				},
 				type: "(open: boolean) => void",
@@ -1683,7 +1713,7 @@ const coreMetas = [
 			ComboboxRoot: [{
 				name: "setValue",
 				deprecated: {
-					since: "1.12.5",
+					since: "1.13.0",
 					replacement: "onValueChange"
 				},
 				type: "(value: string) => void",
@@ -1728,7 +1758,7 @@ const coreMetas = [
 				{
 					name: "gutter",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "sideOffset"
 					},
 					type: "number",
@@ -1863,7 +1893,7 @@ const coreMetas = [
 				{
 					name: "gutter",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "sideOffset"
 					},
 					type: "number",
@@ -2181,6 +2211,21 @@ const coreMetas = [
 				}
 			],
 			FormSelect: [
+				{
+					name: "id",
+					type: "string",
+					description: "트리거 ID. 외부 FormLabel의 htmlFor와 연결"
+				},
+				{
+					name: "aria-label",
+					type: "string",
+					description: "입력의 접근 가능한 이름"
+				},
+				{
+					name: "aria-describedby",
+					type: "string",
+					description: "설명·오류 요소의 ID 목록"
+				},
 				{
 					name: "name",
 					type: "string",
@@ -2220,7 +2265,7 @@ const coreMetas = [
 				{
 					name: "gutter",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "sideOffset"
 					},
 					type: "number",
@@ -2545,6 +2590,10 @@ const store = useFormStore({
 		]
 	},
 	{
+		usage: {
+			bestPractices: ["주요 실행에는 primary, 파괴적 실행에는 danger를 사용하고 동작을 설명하는 텍스트를 유지합니다.", "폼 제출은 type=submit을 명시합니다. loading은 버튼을 비활성화하고 aria-busy를 설정합니다."],
+			avoid: ["페이지 이동을 버튼 클릭으로만 구현하지 않습니다. 아이콘만 표시할 때 접근 가능한 이름을 생략하지 않습니다."]
+		},
 		name: "Button",
 		category: "core",
 		description: "접근성 버튼 컴포넌트. 4가지 변형(primary, secondary, ghost, danger), 3가지 크기, 로딩/아이콘과 aria-busy 상태를 지원합니다.",
@@ -2599,6 +2648,16 @@ const store = useFormStore({
 		}]
 	},
 	{
+		usage: {
+			bestPractices: ["variant 색상과 함께 상태를 설명하는 텍스트를 표시합니다. progress를 지정하면 dot 대신 진행률 링이 표시됩니다."],
+			avoid: ["Badge를 클릭 가능한 버튼처럼 사용하거나 색상만으로 성공·실패를 구분하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "텍스트가 있는 상태",
+			code: `import { Badge } from "@reopt-ai/opt-ui";
+export function Example() { return <Badge variant="success" dot>동기화 완료</Badge>; }`
+		}],
 		name: "Badge",
 		category: "core",
 		description: "인라인 상태 뱃지. 5가지 색상 변형, 상태 점(dot) 옵션 지원.",
@@ -2638,6 +2697,16 @@ const store = useFormStore({
 		testDescribe: "Badge"
 	},
 	{
+		usage: {
+			bestPractices: ["단독 로딩 표시는 aria-label로 작업을 설명합니다. 주변 status가 이미 상태를 읽으면 aria-hidden으로 중복 낭독을 막습니다."],
+			avoid: ["Spinner 자체가 요청 진행 상태나 오류 처리를 관리한다고 가정하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "이름 있는 로딩 표시",
+			code: `import { Spinner } from "@reopt-ai/opt-ui";
+export function Example() { return <Spinner size="sm" aria-label="검색 결과 불러오는 중" />; }`
+		}],
 		name: "Spinner",
 		category: "core",
 		description: "로딩 상태 표시 스피너. 3가지 크기와 장식용 aria-hidden 모드를 지원합니다.",
@@ -2653,6 +2722,16 @@ const store = useFormStore({
 		testDescribe: "Spinner"
 	},
 	{
+		usage: {
+			bestPractices: ["title에는 문제 요약을, 본문에는 사용자가 할 수 있는 다음 행동을 적습니다. 닫을 수 있다면 onDismiss로 상태를 갱신합니다."],
+			avoid: ["일반 설명 문구를 모두 긴급 알림으로 노출하거나 오류 원인을 색상으로만 전달하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "재시도 가능한 오류 안내",
+			code: `import { Alert } from "@reopt-ai/opt-ui";
+export function Example() { return <Alert variant="error" title="저장하지 못했습니다">연결 상태를 확인한 뒤 다시 저장하세요.</Alert>; }`
+		}],
 		name: "Alert",
 		category: "core",
 		description: "알림 메시지 컴포넌트. 4가지 변형(info, success, warning, error), 제목/본문/닫기 버튼 지원.",
@@ -2691,6 +2770,10 @@ const store = useFormStore({
 		testDescribe: "Alert"
 	},
 	{
+		usage: {
+			bestPractices: ["label로 입력 목적을, hint로 형식을 안내합니다. error는 오류 문자열이며 표시될 때 hint보다 우선합니다.", "제어 값은 문자열로 유지하고 onChange의 event.target.value를 저장합니다. FormControl 조합에서는 레이블을 중복하지 않습니다."],
+			avoid: ["placeholder를 유일한 레이블로 사용하거나 제어/비제어 상태를 렌더 중 전환하지 않습니다."]
+		},
 		name: "Input",
 		category: "core",
 		description: "독립적인 텍스트 입력 컴포넌트. 레이블, 에러, 힌트, 아이콘 지원.",
@@ -2757,6 +2840,21 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		}]
 	},
 	{
+		usage: {
+			bestPractices: ["즉시 적용되는 켜짐/꺼짐 설정에 사용합니다. onChange는 DOM 이벤트가 아니라 boolean을 전달합니다."],
+			avoid: ["제출 시 한꺼번에 적용되는 동의 목록을 즉시 적용 스위치로 표현하지 않습니다. label을 상태마다 바꾸지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "제어되는 알림 설정",
+			code: `"use client";
+import { useState } from "react";
+import { Switch } from "@reopt-ai/opt-ui";
+export function Example() {
+  const [enabled, setEnabled] = useState(false);
+  return <Switch label="이메일 알림" hint="새 댓글을 이메일로 받습니다" checked={enabled} onChange={setEnabled} />;
+}`
+		}],
 		name: "Switch",
 		category: "core",
 		description: "토글 스위치 컴포넌트. 3가지 크기와 레이블/설명의 명시적 접근성 연결을 지원합니다.",
@@ -2813,6 +2911,16 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		testDescribe: "Switch"
 	},
 	{
+		usage: {
+			bestPractices: ["로드될 콘텐츠와 비슷한 크기·행 수를 사용해 레이아웃 이동을 줄입니다. 컨테이너에서 로딩 상태를 설명합니다."],
+			avoid: ["빈 결과나 요청 오류를 끝나지 않는 스켈레톤으로 대신하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "목록 로딩 자리 확보",
+			code: `import { SkeletonTable } from "@reopt-ai/opt-ui";
+export function Example() { return <section aria-label="목록 불러오는 중" aria-busy="true"><SkeletonTable rows={3} columns={4} /></section>; }`
+		}],
 		name: "Skeleton",
 		category: "core",
 		description: "로딩 플레이스홀더. text/circular/rectangular 변형. 프리셋 컴포넌트 포함.",
@@ -2883,6 +2991,16 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		testDescribe: "Skeleton"
 	},
 	{
+		usage: {
+			bestPractices: ["여러 줄의 자유 입력에 사용하고 label과 hint로 목적·분량을 안내합니다. rows로 초기 높이를 정합니다."],
+			avoid: ["짧은 단일 값 입력에 과도한 편집 영역을 쓰거나 사용자의 세로 크기 조절을 불필요하게 막지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "설명 입력",
+			code: `import { Textarea } from "@reopt-ai/opt-ui";
+export function Example() { return <Textarea label="변경 이유" name="reason" hint="검토자가 알아야 할 내용을 적어주세요" rows={4} resize="vertical" />; }`
+		}],
 		name: "Textarea",
 		category: "core",
 		description: "멀티라인 텍스트 입력. Input과 동일한 API (label, error, hint).",
@@ -2927,6 +3045,16 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		testDescribe: "Textarea"
 	},
 	{
+		usage: {
+			bestPractices: ["name으로 이미지 실패 시 이니셜을 제공하고, alt는 이미지의 실제 의미를 설명합니다. AvatarGroup의 max로 표시 개수를 제한합니다."],
+			avoid: ["이미지나 온라인 상태 점만으로 사용자 신원·상태를 전달하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "이미지 없이 사용자 표시",
+			code: `import { Avatar, AvatarGroup } from "@reopt-ai/opt-ui";
+export function Example() { return <AvatarGroup max={3}><Avatar name="김민수" /><Avatar name="이지수" /></AvatarGroup>; }`
+		}],
 		name: "Avatar",
 		category: "core",
 		description: "사용자 아바타. 이미지, 이니셜 자동 생성, 스크린 리더에 노출되는 상태 인디케이터, 그룹을 지원합니다.",
@@ -2990,6 +3118,16 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		testDescribe: "Avatar"
 	},
 	{
+		usage: {
+			bestPractices: ["완료량을 알면 value와 max를 같은 단위로 제공합니다. 진행률에 작업을 설명하는 접근 가능한 이름을 붙입니다."],
+			avoid: ["측정할 수 없는 진행률을 임의 숫자로 표시하지 않습니다. 완료·실패 후에도 진행 중 표시를 남기지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "업로드 진행률",
+			code: `import { Progress } from "@reopt-ai/opt-ui";
+export function Example() { return <Progress value={35} max={100} aria-label="파일 업로드" />; }`
+		}],
 		name: "Progress",
 		category: "core",
 		description: "진행률 표시. Linear/Circular, determinate/indeterminate 변형과 안전하게 보정된 ARIA 값을 지원합니다.",
@@ -3442,6 +3580,16 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		testDescribe: "Card"
 	},
 	{
+		usage: {
+			bestPractices: ["CheckboxGroup에는 각 Checkbox의 고유 value를 제공합니다. 단일 onChange는 boolean, 그룹 onChange는 문자열 배열을 전달합니다.", "일부 항목만 선택한 전체 선택 컨트롤에는 indeterminate를 사용합니다."],
+			avoid: ["서로 배타적인 선택지를 체크박스로 구성하거나 label 없이 체크 상태만 노출하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "복수 선택 그룹",
+			code: `import { Checkbox, CheckboxGroup } from "@reopt-ai/opt-ui";
+export function Example() { return <CheckboxGroup label="알림 채널" defaultValue={["email"]}><Checkbox value="email" label="이메일" /><Checkbox value="push" label="푸시" /></CheckboxGroup>; }`
+		}],
 		name: "Checkbox",
 		category: "core",
 		description: "독립적인 체크박스 컴포넌트. 레이블, 설명, 그룹과 DOM property까지 동기화되는 indeterminate 상태를 지원합니다.",
@@ -3951,6 +4099,11 @@ const store = useFormStore({ defaultValues: { name: "" } });
 				type: "number",
 				description: "매치 카운트 표시 (toLocaleString 포맷)"
 			},
+			{
+				name: "labels",
+				type: "ConditionBuilderLabels",
+				description: "미리보기 문구 오버라이드 (previewSuffix, formatPreview). 기본은 영어 \"matches\""
+			},
 			{
 				name: "addNestedGroupLabel",
 				type: "string",
@@ -3961,6 +4114,17 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		testDescribe: "ConditionBuilder"
 	},
 	{
+		usage: {
+			anatomy: ["PopoverRoot 안에 Trigger와 Content를 두고 Content 안에 Close를 제공할 수 있습니다."],
+			bestPractices: ["트리거와 관련된 짧은 보조 작업을 배치합니다. 위치는 PopoverRoot의 placement로 지정합니다."],
+			avoid: ["복잡한 필수 입력 작업을 작은 팝오버에 가두거나 트리거의 접근 가능한 이름을 생략하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "보조 설명 열고 닫기",
+			code: `import { PopoverRoot, PopoverTrigger, PopoverContent, PopoverClose } from "@reopt-ai/opt-ui";
+export function Example() { return <PopoverRoot><PopoverTrigger>공유 안내</PopoverTrigger><PopoverContent><p>초대받은 사용자만 문서를 볼 수 있습니다.</p><PopoverClose>닫기</PopoverClose></PopoverContent></PopoverRoot>; }`
+		}],
 		name: "Popover",
 		category: "core",
 		description: "Popover 프리미티브 래퍼. 트리거 요소에 연결된 플로팅 콘텐츠를 표시합니다.",
@@ -3979,15 +4143,6 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			action: "트리거 활성화"
 		}],
 		props: { PopoverContent: [{
-			name: "gutter",
-			deprecated: {
-				since: "1.12.5",
-				replacement: "sideOffset"
-			},
-			type: "number",
-			default: "8",
-			description: "트리거와의 간격 (px)"
-		}, {
 			name: "className",
 			type: "string",
 			description: "커스텀 CSS 클래스"
@@ -4025,7 +4180,7 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			DropdownContent: [{
 				name: "gutter",
 				deprecated: {
-					since: "1.12.5",
+					since: "1.13.0",
 					replacement: "sideOffset"
 				},
 				type: "number",
@@ -4162,6 +4317,11 @@ const store = useFormStore({ defaultValues: { name: "" } });
 				type: "(value: number) => void",
 				description: "값 변경 핸들러"
 			},
+			{
+				name: "onValueCommit",
+				type: "(value: number) => void",
+				description: "포인터·키보드 편집 완료 시 한 번 호출. 취소와 외부 값 갱신은 제외"
+			},
 			{
 				name: "min",
 				type: "number",
@@ -4776,6 +4936,16 @@ const MyDashboard = createBlock<MyDashboardProps>(
 		testDescribe: "VirtualList"
 	},
 	{
+		usage: {
+			bestPractices: ["기존 콘텐츠를 유지한 채 갱신할 때 loading을 연결하고 label로 진행 중인 작업을 설명합니다."],
+			avoid: ["오버레이가 키보드 접근까지 차단한다고 가정하지 않습니다. 중복 실행 방지가 필요하면 내부 컨트롤도 비활성화합니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "기존 결과를 유지하는 갱신 표시",
+			code: `import { LoadingOverlay } from "@reopt-ai/opt-ui";
+export function Example() { return <LoadingOverlay loading label="목록 새로고침 중"><p>이전 조회 결과</p></LoadingOverlay>; }`
+		}],
 		name: "LoadingOverlay",
 		category: "core",
 		description: "로딩 오버레이. 중복 status 없이 하나의 aria-busy 라이브 영역으로 콘텐츠 위 로딩 상태를 표시합니다.",
@@ -5514,7 +5684,7 @@ const shellMetas = [
 			description: "폼 필드 정의 배열"
 		}, {
 			name: "onSubmit",
-			type: "(values: Record<string, unknown>) => void",
+			type: "(values: Record<string, unknown>) => void | Promise<void>",
 			description: "제출 핸들러"
 		}] },
 		dependencies: [
@@ -5821,6 +5991,10 @@ const fields = [
 		testDescribe: "DomainTable"
 	},
 	{
+		usage: {
+			bestPractices: ["keyExtractor에는 정렬·필터 후에도 유지되는 행 ID를 사용합니다. 보이는 title이 없으면 ariaLabel로 grid 이름을 지정합니다.", "컬럼 accessor는 행 타입에 맞춰 선언하고, 서버 조회·편집·대규모 가상화가 필요하면 opt-datagrid의 계약을 검토합니다."],
+			avoid: ["배열 인덱스를 행 식별자로 사용하거나 비어 있는 헤더로 액션 컬럼을 익명화하지 않습니다. headerHidden을 사용합니다."]
+		},
 		name: "DataTable",
 		category: "shell",
 		description: "제네릭 데이터 테이블. 제목은 opt-in이고 ariaLabel로 grid를 이름 붙이며, 동적 컬럼·안전 정렬·키보드 리사이즈·Composite 탐색을 지원합니다.",
@@ -5967,6 +6141,17 @@ const data = [
 		}]
 	},
 	{
+		usage: {
+			bestPractices: ["앱 경계에 ToastProvider를 한 번 마운트한 뒤 이벤트 핸들러에서 toast를 호출합니다. message는 결과를, action은 다음 행동을 설명합니다."],
+			avoid: ["렌더 함수에서 toast를 호출하거나 반드시 읽어야 하는 오류·동의를 자동으로 사라지는 토스트에만 표시하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "사용자 동작의 결과 알림",
+			code: `"use client";
+import { Button, ToastProvider, toast } from "@reopt-ai/opt-ui";
+export function Example() { return <ToastProvider><Button onClick={() => toast.success("알림 동작을 확인했습니다")}>알림 테스트</Button></ToastProvider>; }`
+		}],
 		name: "NotificationToast",
 		category: "shell",
 		description: "토스트 알림 시스템. 포인터/키보드 상호작용 중 자동 닫힘을 일시 정지하고, 중요도별 live region으로 전역 알림을 관리합니다.",
@@ -6161,6 +6346,10 @@ const data = [
 		testDescribe: "ActivityFeed"
 	},
 	{
+		usage: {
+			bestPractices: ["filters의 id를 안정적으로 유지하고 onFilterChange에서 해당 필터의 value를 갱신합니다. onClearAll에서는 적용된 값과 조회 조건을 함께 초기화합니다."],
+			avoid: ["필터 UI 변경만으로 서버 데이터까지 자동 조회된다고 가정하지 않습니다. 비동기 조회와 오류 처리는 호출자가 연결합니다."]
+		},
 		name: "FilterBar",
 		category: "shell",
 		description: "필터링 바 컴포넌트. 검색, 선택, 다중 선택 필터 지원.",
@@ -6366,7 +6555,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { email: string; password: string; confirmPassword?: string; rememberMe?: boolean; mode: \"login\" | \"signup\" }) => void",
+				type: "(values: { email: string; password: string; confirmPassword?: string; rememberMe?: boolean; mode: \"login\" | \"signup\" }) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -6409,7 +6598,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: Record<string, unknown>) => void",
+				type: "(values: Record<string, unknown>) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -6477,7 +6666,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: string[]) => void",
+				type: "(values: string[]) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -6531,7 +6720,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { title: string; description: string; file: File | null }) => void",
+				type: "(values: { title: string; description: string; file: File | null }) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -7375,6 +7564,221 @@ const filters = [
 		}],
 		testDescribe: "SegmentBuilder"
 	},
+	{
+		name: "CriteriaBuilder",
+		category: "shell",
+		description: "도메인 무관 2단계 조건 트리 편집기. 그룹 AND/OR, 순서·복제·부정·오류를 셸이 맡고 조건 문장은 소비자가 Expression 칩으로 렌더링합니다.",
+		slug: "criteria-builder",
+		exports: [
+			"CriteriaBuilder",
+			"criteriaBuilderMove",
+			"criteriaBuilderDuplicate",
+			"criteriaBuilderRemove",
+			"criteriaBuilderInsert",
+			"criteriaBuilderRemoveGroup",
+			"criteriaBuilderDuplicateGroup",
+			"criteriaGroupLetter"
+		],
+		props: { CriteriaBuilder: [
+			{
+				name: "value",
+				type: "CriteriaBuilderValue<TCriterion>",
+				required: true,
+				description: "조건 트리. { logic, groups: [{ id, logic, criteria }] }"
+			},
+			{
+				name: "onChange",
+				type: "(next: CriteriaBuilderValue<TCriterion>) => void",
+				required: true,
+				description: "트리 변경 핸들러"
+			},
+			{
+				name: "kinds",
+				type: "CriteriaBuilderKindOption[]",
+				required: true,
+				description: "조건 추가 메뉴 항목. group으로 섹션을 나누고 negatedLabel이 있으면 부정 항목을 따로 냅니다"
+			},
+			{
+				name: "createCriterion",
+				type: "(kind: string, negate: boolean) => TCriterion",
+				required: true,
+				description: "메뉴 선택으로 만들 초기 조건. 고유 id를 돌려줘야 합니다"
+			},
+			{
+				name: "renderCriterion",
+				type: "(criterion: TCriterion, api: CriteriaRenderApi<TCriterion>) => React.ReactNode",
+				required: true,
+				description: "조건 한 줄의 편집 가능한 문장 렌더러"
+			},
+			{
+				name: "cloneCriterion",
+				type: "(criterion: TCriterion) => TCriterion",
+				description: "복제 시 만들 사본. 기본은 새 id를 붙인 얕은 복사"
+			},
+			{
+				name: "createGroupId",
+				type: "() => string",
+				description: "셸이 만드는 그룹의 id. 기본 group-N"
+			},
+			{
+				name: "errors",
+				type: "Record<string, string>",
+				description: "조건 id 또는 그룹 id별 오류 메시지"
+			},
+			{
+				name: "maxGroups",
+				type: "number",
+				default: "10",
+				description: "그룹 최대 수"
+			},
+			{
+				name: "maxCriteriaPerGroup",
+				type: "number",
+				default: "20",
+				description: "그룹당 조건 최대 수"
+			},
+			{
+				name: "allowNegation",
+				type: "boolean",
+				default: "true",
+				description: "조건별 부정 토글 표시"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "전체 비활성화"
+			},
+			{
+				name: "aside",
+				type: "React.ReactNode",
+				description: "넓은 화면에서 트리 옆, 좁은 화면에서 아래에 놓이는 미리보기 슬롯"
+			},
+			{
+				name: "labels",
+				type: "CriteriaBuilderLabels",
+				description: "i18n용 라벨 오버라이드 (기본 한국어)"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "루트 CSS 클래스"
+			},
+			{
+				name: "aria-label",
+				type: "string",
+				description: "빌더 접근성 이름"
+			}
+		] },
+		ariaRole: "group",
+		keyboardShortcuts: [{
+			keys: "A",
+			action: "포커스된 그룹에 조건 추가 메뉴 열기"
+		}, {
+			keys: "G",
+			action: "그룹 추가"
+		}],
+		dependencies: [
+			{
+				slug: "segmented-control",
+				category: "core"
+			},
+			{
+				slug: "dropdown-menu",
+				category: "core"
+			},
+			{
+				slug: "button",
+				category: "core"
+			},
+			{
+				slug: "callout",
+				category: "core"
+			},
+			{
+				slug: "empty-state",
+				category: "core"
+			},
+			{
+				slug: "kbd",
+				category: "core"
+			}
+		],
+		testDescribe: "CriteriaBuilder",
+		usage: {
+			bestPractices: [
+				"조건 데이터 타입과 각 조건의 문장은 소비자가 소유합니다. renderCriterion에서 Expression 칩을 조합하고, 값 편집은 Popover로 여세요.",
+				"createCriterion은 kind와 negate만 받아 초기 조건을 만듭니다. id는 여기서 고유하게 발급하세요.",
+				"errors는 조건 id·그룹 id로 키를 잡습니다. 검증은 소비자가 하고 셸은 표시와 aria 연결만 맡습니다.",
+				"aside에 라이브 카운트(StatCard)를 두면 넓은 화면에서 트리 옆에, 좁은 화면에서 아래에 놓입니다."
+			],
+			anatomy: ["루트 AND/OR 세그먼트 컨트롤 → 그룹 패널(레터마크 + 그룹 AND/OR + 복제/제거) → 조건 행(부정 토글 + 문장 + 이동/복제/제거) → 조건 추가 메뉴 → 그룹 추가 버튼"],
+			avoid: ["kinds에 없는 kind를 다른 kind의 필드로 대체 렌더링하지 마세요. 셸은 이를 경고 행으로 보여 주고 바꾸기/제거만 허용합니다.", "SegmentBuilder처럼 고정 select 조합이 충분하다면 이 셸은 과합니다. 문장형 편집과 그룹 논리가 필요할 때 쓰세요."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "이벤트 조건 세그먼트",
+			code: `"use client";
+import { useState } from "react";
+import {
+  CriteriaBuilder,
+  Expression,
+  ExpressionGroup,
+  type CriteriaBuilderValue,
+} from "@reopt-ai/opt-ui";
+
+interface Criterion {
+  id: string;
+  kind: string;
+  negate?: boolean;
+  event: string;
+}
+
+let seq = 0;
+
+export function Example() {
+  const [value, setValue] = useState<CriteriaBuilderValue<Criterion>>({
+    logic: "and",
+    groups: [
+      {
+        id: "g1",
+        logic: "and",
+        criteria: [{ id: "c1", kind: "performed", event: "purchase" }],
+      },
+    ],
+  });
+  return (
+    <CriteriaBuilder
+      value={value}
+      onChange={setValue}
+      kinds={[
+        {
+          kind: "performed",
+          label: "이벤트를 수행함",
+          negatedLabel: "이벤트를 수행하지 않음",
+        },
+      ]}
+      createCriterion={(kind, negate) => ({
+        id: \`c\${++seq}\`,
+        kind,
+        negate,
+        event: "",
+      })}
+      renderCriterion={(criterion, api) => (
+        <ExpressionGroup>
+          <Expression
+            description={criterion.negate ? "수행하지 않음" : "수행함"}
+            value={criterion.event || "이벤트 선택"}
+            invalid={api.invalid || criterion.event === ""}
+            onClick={() => api.update({ event: "purchase" })}
+          />
+        </ExpressionGroup>
+      )}
+    />
+  );
+}`
+		}]
+	},
 	{
 		name: "InsightsPanel",
 		category: "shell",
@@ -7431,6 +7835,21 @@ const filters = [
 		testDescribe: "InsightsPanel"
 	},
 	{
+		usage: {
+			bestPractices: ["제어 모드에서는 value와 onChange를 함께 연결합니다. labels와 presets의 label은 제품 언어로 제공합니다.", "프리셋은 로컬 날짜의 자정을 기준으로 계산하므로 API의 시간대·종료일 포함 여부를 조회 계층에서 명시적으로 변환합니다."],
+			avoid: ["날짜 선택만으로 서버 집계가 갱신된다고 가정하거나 null 날짜를 유효한 조회 범위로 전송하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "제어되는 조회 기간",
+			code: `"use client";
+import { useState } from "react";
+import { TimeRangeSelector, type DateRange } from "@reopt-ai/opt-ui";
+export function Example() {
+  const [range, setRange] = useState<DateRange>({ start: null, end: null });
+  return <TimeRangeSelector value={range} onChange={setRange} labels={{ title: "조회 기간", placeholder: "기간 선택" }} presets={[{ label: "최근 7일", days: 7 }]} />;
+}`
+		}],
 		name: "TimeRangeSelector",
 		category: "shell",
 		description: "시간 범위 선택기. Popover + DateRangePicker + 프리셋 버튼 조합. 12개 시계열 Surface에서 사용.",
@@ -7520,6 +7939,19 @@ const filters = [
 		testDescribe: "ExportButton"
 	},
 	{
+		usage: {
+			bestPractices: ["stats에는 안정적인 id와 표시 value를 제공합니다. 감소가 좋은 지표는 polarity=negative로 비교 의미를 명시합니다.", "선택 가능한 카드에서는 onStatClick과 selectedStatId를 같은 조회 상태에 연결합니다. 빈 목록 문구는 labels로 제공합니다."],
+			avoid: ["loading 중 빈 결과를 확정적으로 표시하거나 모든 상승 추세를 좋은 결과로 해석하지 않습니다."]
+		},
+		examples: [{
+			validation: "typechecked",
+			title: "의미가 다른 통계 비교",
+			code: `import { SummaryRow } from "@reopt-ai/opt-ui";
+export function Example() { return <SummaryRow columns={2} stats={[
+  { id: "orders", title: "주문", value: "120", change: "+10%", trend: "up" },
+  { id: "errors", title: "오류", value: "2", change: "-50%", trend: "down", polarity: "negative" },
+]} />; }`
+		}],
 		name: "SummaryRow",
 		category: "shell",
 		description: "통계 요약 행. StatCard 그리드 레이아웃을 표준화합니다. loading 시 SkeletonCard 표시.",
@@ -10682,7 +11114,6 @@ const messages = [
 				category: "core"
 			}
 		],
-		ariaRole: "dialog",
 		testDescribe: "SaveQueryDialog"
 	},
 	{
@@ -10769,6 +11200,426 @@ const messages = [
 			category: "core"
 		}],
 		testDescribe: "QueryWorkspace"
+	},
+	{
+		name: "ReplayScrubber",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "beta",
+		keywords: [
+			"replay",
+			"scrubber",
+			"seekbar",
+			"timeline",
+			"session recording",
+			"playhead"
+		],
+		description: "세션 리플레이의 탐색 트랙. 활동/비활성/미로딩 구간, 활동 밀도, 이벤트 마커를 한 플레이헤드 아래에 겹쳐 그리고, 드래그·키보드 탐색이 끝났을 때만 seek을 커밋한다.",
+		slug: "replay-scrubber",
+		exports: ["ReplayScrubber", "groupReplayMarkers"],
+		props: { ReplayScrubber: [
+			{
+				name: "start",
+				type: "number",
+				required: true,
+				description: "재생 가능한 첫 시각(절대값, 보통 epoch ms)"
+			},
+			{
+				name: "end",
+				type: "number",
+				required: true,
+				description: "재생 가능한 마지막 시각"
+			},
+			{
+				name: "position",
+				type: "number",
+				required: true,
+				description: "현재 플레이헤드. [start, end]로 클램프"
+			},
+			{
+				name: "segments",
+				type: "ReplayScrubberSegment[]",
+				description: "활동 분류 구간. active/inactive/gap/buffer"
+			},
+			{
+				name: "buffered",
+				type: "Array<{ start: number; end: number }>",
+				description: "이미 로드된 범위"
+			},
+			{
+				name: "activity",
+				type: "number[]",
+				description: "0..1로 정규화한 활동 밀도 버킷. 로그 스케일 영역으로 그린다"
+			},
+			{
+				name: "markers",
+				type: "ReplayScrubberMarker[]",
+				description: "트랙 위 관심 지점. 가까운 마커는 하나로 합쳐진다"
+			},
+			{
+				name: "onSeek",
+				type: "(time: number) => void",
+				required: true,
+				description: "포인터·키보드 조작이 끝났을 때 한 번 호출"
+			},
+			{
+				name: "onPreview",
+				type: "(time: number | null) => void",
+				description: "드래그·호버 중 미리보기 시각. 비싼 seek에 쓰지 않는다"
+			},
+			{
+				name: "onMarkerSelect",
+				type: "(marker: ReplayScrubberMarker) => void",
+				description: "마커 선택. 생략하면 해당 시각으로 seek"
+			},
+			{
+				name: "formatTime",
+				type: "(time: number) => string",
+				description: "배지와 aria-valuetext 포맷. 기본 start 기준 m:ss"
+			},
+			{
+				name: "stepMs",
+				type: "number",
+				default: "5000",
+				description: "화살표 키 이동량"
+			},
+			{
+				name: "largeStepMs",
+				type: "number",
+				default: "30000",
+				description: "PageUp/PageDown·Shift+화살표 이동량"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "모든 조작을 비활성화"
+			},
+			{
+				name: "labels",
+				type: "ReplayScrubberLabels",
+				description: "접근성 문구 오버라이드"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "추가 클래스"
+			}
+		] },
+		usage: {
+			bestPractices: ["onSeek에만 실제 seek을 연결한다. onPreview는 시각 표시용이다.", "segments의 buffer는 '아직 안 옴'이고 gap은 '없음'이다. 플레이어가 기다릴지 건너뛸지가 갈린다."],
+			avoid: ["마커를 수천 개 넘기지 않는다. 우선순위로 100개 안팎으로 추려서 넘긴다."]
+		},
+		testDescribe: "ReplayScrubber",
+		examples: [{
+			title: "구간·마커가 있는 탐색 트랙",
+			code: `import { ReplayScrubber } from "@reopt-ai/opt-ui";
+
+<ReplayScrubber
+  start={recording.start}
+  end={recording.end}
+  position={playhead}
+  segments={[
+    { start: recording.start, end: recording.start + 60_000, kind: "active" },
+    { start: recording.start + 60_000, end: recording.end, kind: "inactive" },
+  ]}
+  markers={[{ id: "err", time: errorAt, label: "TypeError", tone: "danger" }]}
+  onSeek={(time) => player.seek(time)}
+  labels={{ track: "녹화 탐색" }}
+/>`
+		}]
+	},
+	{
+		name: "ReplayTransport",
+		category: "shell",
+		functionalCategory: "actions",
+		maturity: "beta",
+		keywords: [
+			"replay",
+			"transport",
+			"play",
+			"pause",
+			"speed",
+			"skip inactivity",
+			"session recording"
+		],
+		description: "세션 리플레이 재생 컨트롤. 재생/일시정지, 앞뒤 점프, 배속 메뉴, 비활성 건너뛰기 토글, 전체화면, 경과/시계 타임코드 전환을 제공하며 재생 상태는 호스트가 소유한다.",
+		slug: "replay-transport",
+		exports: ["ReplayTransport", "formatReplayElapsed"],
+		props: { ReplayTransport: [
+			{
+				name: "playing",
+				type: "boolean",
+				required: true,
+				description: "재생 중 여부"
+			},
+			{
+				name: "ended",
+				type: "boolean",
+				default: "false",
+				description: "끝에 도달. 재생 버튼이 다시 시작을 제안"
+			},
+			{
+				name: "position",
+				type: "number",
+				required: true,
+				description: "절대 플레이헤드 시각"
+			},
+			{
+				name: "start",
+				type: "number",
+				required: true,
+				description: "녹화 시작 시각(절대값)"
+			},
+			{
+				name: "end",
+				type: "number",
+				required: true,
+				description: "녹화 종료 시각(절대값)"
+			},
+			{
+				name: "onTogglePlay",
+				type: "() => void",
+				required: true,
+				description: "재생/일시정지 토글. ended면 처음부터 다시 시작"
+			},
+			{
+				name: "onSkip",
+				type: "(deltaMs: number) => void",
+				required: true,
+				description: "부호 있는 시간만큼 이동"
+			},
+			{
+				name: "onSkipToStart",
+				type: "() => void",
+				description: "처음으로. 생략하면 버튼 숨김"
+			},
+			{
+				name: "jumpMs",
+				type: "number",
+				default: "10000",
+				description: "앞뒤 점프 버튼 이동량(ms)"
+			},
+			{
+				name: "speed",
+				type: "number",
+				required: true,
+				description: "현재 배속"
+			},
+			{
+				name: "speeds",
+				type: "readonly number[]",
+				default: "[0.5, 1, 1.5, 2, 3, 4, 8, 16]",
+				description: "선택 가능한 배속 목록"
+			},
+			{
+				name: "onSpeedChange",
+				type: "(speed: number) => void",
+				required: true,
+				description: "배속 변경 콜백"
+			},
+			{
+				name: "skipInactive",
+				type: "boolean",
+				required: true,
+				description: "비활성 구간 건너뛰기 여부"
+			},
+			{
+				name: "onSkipInactiveChange",
+				type: "(skip: boolean) => void",
+				required: true,
+				description: "건너뛰기 토글 콜백"
+			},
+			{
+				name: "fullscreen",
+				type: "boolean",
+				description: "전체화면 상태(호스트 소유)"
+			},
+			{
+				name: "onFullscreenChange",
+				type: "(fullscreen: boolean) => void",
+				description: "있으면 전체화면 버튼 표시"
+			},
+			{
+				name: "timecode",
+				type: "\"elapsed\" | \"clock\"",
+				default: "\"elapsed\"",
+				description: "경과 시간 또는 실제 시각 표시 모드"
+			},
+			{
+				name: "onTimecodeChange",
+				type: "(mode: \"elapsed\" | \"clock\") => void",
+				description: "있으면 타임코드를 클릭해 전환"
+			},
+			{
+				name: "formatClock",
+				type: "(time: number) => string",
+				description: "clock 모드 포맷"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "모든 조작을 비활성화"
+			},
+			{
+				name: "children",
+				type: "ReactNode",
+				description: "오른쪽에 추가 컨트롤"
+			},
+			{
+				name: "labels",
+				type: "ReplayTransportLabels",
+				description: "문구 오버라이드"
+			},
+			{
+				name: "shortcuts",
+				type: "ReplayTransportShortcuts",
+				description: "툴팁에 표시할 단축키"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "추가 클래스"
+			}
+		] },
+		usage: {
+			bestPractices: ["단축키는 ReplayPlayerLayout의 shortcuts로 묶고, 여기엔 표시용 문자열만 넘긴다.", "clock 타임코드는 로그와 대조할 때 필요하다. 세션의 실제 시각을 넘긴다."],
+			avoid: ["재생 상태를 컴포넌트 안에 두지 않는다. 플레이어 엔진이 단일 소스다."]
+		},
+		testDescribe: "ReplayTransport",
+		examples: [{
+			title: "호스트가 재생 상태를 소유하는 트랜스포트",
+			code: `import { ReplayTransport } from "@reopt-ai/opt-ui";
+
+<ReplayTransport
+  playing={playing}
+  position={playhead}
+  start={recording.start}
+  end={recording.end}
+  onTogglePlay={() => (playing ? player.pause() : player.play())}
+  onSkip={(delta) => player.seek(playhead + delta)}
+  speed={speed}
+  onSpeedChange={setSpeed}
+  skipInactive={skipInactive}
+  onSkipInactiveChange={setSkipInactive}
+  labels={{ play: "재생", pause: "일시정지" }}
+/>`
+		}]
+	},
+	{
+		name: "ReplayPlayerLayout",
+		category: "shell",
+		functionalCategory: "layout",
+		maturity: "beta",
+		keywords: [
+			"replay",
+			"player",
+			"layout",
+			"inspector",
+			"fullscreen",
+			"shortcuts",
+			"session recording"
+		],
+		description: "세션 리플레이 플레이어의 프레임. 스테이지·메타 바·컨트롤·리사이즈 가능한 인스펙터를 배치하고, 플레이어 전체의 전체화면과 입력 필드를 피하는 키보드 단축키 범위를 소유한다.",
+		slug: "replay-player-layout",
+		exports: ["ReplayPlayerLayout", "replayShortcutKey"],
+		props: { ReplayPlayerLayout: [
+			{
+				name: "stage",
+				type: "ReactNode",
+				required: true,
+				description: "녹화가 렌더되는 영역(iframe 호스트)"
+			},
+			{
+				name: "meta",
+				type: "ReactNode",
+				description: "스테이지 위 얇은 바: URL, 창, 기기"
+			},
+			{
+				name: "controls",
+				type: "ReactNode",
+				description: "스테이지 아래 트랜스포트와 스크러버"
+			},
+			{
+				name: "inspector",
+				type: "ReactNode",
+				description: "측면 패널. 생략하면 패널 없음"
+			},
+			{
+				name: "inspectorOpen",
+				type: "boolean",
+				default: "true",
+				description: "인스펙터 표시 여부(제어됨)"
+			},
+			{
+				name: "onInspectorOpenChange",
+				type: "(open: boolean) => void",
+				description: "있으면 토글 버튼 표시"
+			},
+			{
+				name: "inspectorSize",
+				type: "number",
+				default: "34",
+				description: "인스펙터 초기 폭(%)"
+			},
+			{
+				name: "layoutId",
+				type: "string",
+				description: "리사이즈 레이아웃 영속 id"
+			},
+			{
+				name: "fullscreen",
+				type: "boolean",
+				default: "false",
+				description: "전체화면 상태(호스트 소유)"
+			},
+			{
+				name: "onFullscreenChange",
+				type: "(fullscreen: boolean) => void",
+				description: "전체화면 변경 콜백. 브라우저가 스스로 나가도 호출된다"
+			},
+			{
+				name: "shortcuts",
+				type: "ReplayShortcutMap",
+				description: "포커스가 안에 있고 입력 필드가 아닐 때만 동작. false를 반환하면 전파"
+			},
+			{
+				name: "overlay",
+				type: "ReactNode",
+				description: "스테이지 위 오버레이: 로딩, 오류, 건너뛰는 중"
+			},
+			{
+				name: "labels",
+				type: "ReplayPlayerLayoutLabels",
+				description: "문구 오버라이드"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "추가 클래스"
+			}
+		] },
+		usage: {
+			bestPractices: ["단축키 키 이름은 replayShortcutKey가 만든다: space, arrowleft, shift+arrowright, mod+arrowleft, f.", "전체화면 상태는 호스트가 들고, 브라우저가 스스로 나가면 onFullscreenChange(false)로 통지된다."],
+			avoid: ["스테이지 iframe에 직접 requestFullscreen하지 않는다. 컨트롤이 함께 보여야 한다."]
+		},
+		testDescribe: "ReplayPlayerLayout",
+		examples: [{
+			title: "스테이지·컨트롤·인스펙터 배치와 단축키",
+			code: `import { ReplayPlayerLayout } from "@reopt-ai/opt-ui";
+
+<ReplayPlayerLayout
+  layoutId="replay-player"
+  meta={<span>{currentPath}</span>}
+  stage={<div ref={stageRef} />}
+  controls={<>{scrubber}{transport}</>}
+  inspector={<EventList onSelect={(e) => player.seek(e.time)} />}
+  inspectorOpen={inspectorOpen}
+  onInspectorOpenChange={setInspectorOpen}
+  shortcuts={{ space: togglePlay, arrowleft: () => skip(-10_000), arrowright: () => skip(10_000) }}
+/>`
+		}]
 	}
 ];
 //#endregion