@reopt-ai/opt-ui 1.12.5 → 1.14.0

package/dist/meta.cjs

@@ -1221,6 +1221,10 @@ const coreMetas = [
 				},
 				{
 					name: "setOpen",
+					deprecated: {
+						since: "1.13.0",
+						replacement: "onOpenChange"
+					},
 					type: "(open: boolean) => void",
 					description: "제어 모드: 상태 변경 핸들러"
 				},
@@ -1255,6 +1259,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.",
@@ -1298,6 +1322,10 @@ const coreMetas = [
 				},
 				{
 					name: "setSelectedId",
+					deprecated: {
+						since: "1.13.0",
+						replacement: "onSelectedIdChange"
+					},
 					type: "(id: string | null) => void",
 					description: "제어 모드: 탭 변경 핸들러"
 				}
@@ -1378,6 +1406,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.",
@@ -1466,6 +1499,10 @@ const coreMetas = [
 				},
 				{
 					name: "gutter",
+					deprecated: {
+						since: "1.13.0",
+						replacement: "sideOffset"
+					},
 					type: "number",
 					default: "4",
 					description: "트리거와의 간격 (px)"
@@ -1514,6 +1551,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.",
@@ -1544,6 +1586,10 @@ const coreMetas = [
 				description: "제어 모드: 열림 상태"
 			}, {
 				name: "setOpen",
+				deprecated: {
+					since: "1.13.0",
+					replacement: "onOpenChange"
+				},
 				type: "(open: boolean) => void",
 				description: "제어 모드: 상태 변경 핸들러"
 			}],
@@ -1667,6 +1713,10 @@ const coreMetas = [
 		props: {
 			ComboboxRoot: [{
 				name: "setValue",
+				deprecated: {
+					since: "1.13.0",
+					replacement: "onValueChange"
+				},
 				type: "(value: string) => void",
 				description: "입력값 변경 핸들러"
 			}, {
@@ -1708,6 +1758,10 @@ const coreMetas = [
 				},
 				{
 					name: "gutter",
+					deprecated: {
+						since: "1.13.0",
+						replacement: "sideOffset"
+					},
 					type: "number",
 					default: "4",
 					description: "입력과의 간격 (px)"
@@ -1839,6 +1893,10 @@ const coreMetas = [
 				},
 				{
 					name: "gutter",
+					deprecated: {
+						since: "1.13.0",
+						replacement: "sideOffset"
+					},
 					type: "number",
 					default: "8",
 					description: "트리거와의 간격 (px)"
@@ -2192,6 +2250,10 @@ const coreMetas = [
 				},
 				{
 					name: "gutter",
+					deprecated: {
+						since: "1.13.0",
+						replacement: "sideOffset"
+					},
 					type: "number",
 					default: "4",
 					description: "트리거와의 간격 (px)"
@@ -2514,6 +2576,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 상태를 지원합니다.",
@@ -2568,6 +2634,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) 옵션 지원.",
@@ -2607,6 +2683,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 모드를 지원합니다.",
@@ -2622,6 +2708,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), 제목/본문/닫기 버튼 지원.",
@@ -2660,6 +2756,10 @@ const store = useFormStore({
 		testDescribe: "Alert"
 	},
 	{
+		usage: {
+			bestPractices: ["label로 입력 목적을, hint로 형식을 안내합니다. error는 오류 문자열이며 표시될 때 hint보다 우선합니다.", "제어 값은 문자열로 유지하고 onChange의 event.target.value를 저장합니다. FormControl 조합에서는 레이블을 중복하지 않습니다."],
+			avoid: ["placeholder를 유일한 레이블로 사용하거나 제어/비제어 상태를 렌더 중 전환하지 않습니다."]
+		},
 		name: "Input",
 		category: "core",
 		description: "독립적인 텍스트 입력 컴포넌트. 레이블, 에러, 힌트, 아이콘 지원.",
@@ -2726,6 +2826,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가지 크기와 레이블/설명의 명시적 접근성 연결을 지원합니다.",
@@ -2782,6 +2897,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 변형. 프리셋 컴포넌트 포함.",
@@ -2852,6 +2977,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).",
@@ -2896,6 +3031,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: "사용자 아바타. 이미지, 이니셜 자동 생성, 스크린 리더에 노출되는 상태 인디케이터, 그룹을 지원합니다.",
@@ -2959,6 +3104,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 값을 지원합니다.",
@@ -3411,6 +3566,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 상태를 지원합니다.",
@@ -3920,6 +4085,11 @@ const store = useFormStore({ defaultValues: { name: "" } });
 				type: "number",
 				description: "매치 카운트 표시 (toLocaleString 포맷)"
 			},
+			{
+				name: "labels",
+				type: "ConditionBuilderLabels",
+				description: "미리보기 문구 오버라이드 (previewSuffix, formatPreview). 기본은 영어 \"matches\""
+			},
 			{
 				name: "addNestedGroupLabel",
 				type: "string",
@@ -3930,6 +4100,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 프리미티브 래퍼. 트리거 요소에 연결된 플로팅 콘텐츠를 표시합니다.",
@@ -3948,11 +4129,6 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			action: "트리거 활성화"
 		}],
 		props: { PopoverContent: [{
-			name: "gutter",
-			type: "number",
-			default: "8",
-			description: "트리거와의 간격 (px)"
-		}, {
 			name: "className",
 			type: "string",
 			description: "커스텀 CSS 클래스"
@@ -3989,6 +4165,10 @@ const store = useFormStore({ defaultValues: { name: "" } });
 		props: {
 			DropdownContent: [{
 				name: "gutter",
+				deprecated: {
+					since: "1.13.0",
+					replacement: "sideOffset"
+				},
 				type: "number",
 				default: "4",
 				description: "트리거와의 간격 (px)"
@@ -4737,6 +4917,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 라이브 영역으로 콘텐츠 위 로딩 상태를 표시합니다.",
@@ -4999,6 +5189,7 @@ const MyDashboard = createBlock<MyDashboardProps>(
 		description: "페이지에 머무는 인페이지 고지. Alert와 달리 dismiss가 없고, 조건이 참인 동안 레이아웃의 일부로 남습니다.",
 		slug: "callout",
 		exports: ["Callout"],
+		ariaRole: "status",
 		props: { Callout: [
 			{
 				name: "tone",
@@ -5781,6 +5972,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 탐색을 지원합니다.",
@@ -5927,6 +6122,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으로 전역 알림을 관리합니다.",
@@ -6121,6 +6327,10 @@ const data = [
 		testDescribe: "ActivityFeed"
 	},
 	{
+		usage: {
+			bestPractices: ["filters의 id를 안정적으로 유지하고 onFilterChange에서 해당 필터의 value를 갱신합니다. onClearAll에서는 적용된 값과 조회 조건을 함께 초기화합니다."],
+			avoid: ["필터 UI 변경만으로 서버 데이터까지 자동 조회된다고 가정하지 않습니다. 비동기 조회와 오류 처리는 호출자가 연결합니다."]
+		},
 		name: "FilterBar",
 		category: "shell",
 		description: "필터링 바 컴포넌트. 검색, 선택, 다중 선택 필터 지원.",
@@ -6940,15 +7150,26 @@ const filters = [
 	{
 		name: "QueryResultsTable",
 		category: "shell",
-		description: "쿼리 결과 테이블. SQL 결과와 스크린 리더에 안내되는 로딩, 에러, 빈 상태를 지원합니다.",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"query",
+			"results",
+			"grid",
+			"table",
+			"virtualized"
+		],
+		description: "쿼리 결과 테이블. 타입이 표시되는 헤더, 로컬 정렬, 컬럼 리사이즈, 행 상세 패널을 갖추고 행을 윈도잉해 만 행도 스크롤로 다룹니다. NULL·불리언·객체를 빈칸 대신 글자로 씁니다.",
 		slug: "query-results-table",
 		exports: ["QueryResultsTable"],
+		domlessExports: ["formatQueryCell"],
 		props: { QueryResultsTable: [
 			{
 				name: "columns",
-				type: "string[]",
+				type: "Array<string | QueryResultColumn>",
 				required: true,
-				description: "컬럼 이름"
+				description: "컬럼 이름, 또는 타입을 포함한 컬럼 정의"
 			},
 			{
 				name: "rows",
@@ -6956,6 +7177,12 @@ const filters = [
 				required: true,
 				description: "결과 행"
 			},
+			{
+				name: "maxHeight",
+				type: "number | \"fill\"",
+				default: "400",
+				description: "스크롤 높이(px). fill이면 부모 높이를 채움"
+			},
 			{
 				name: "loading",
 				type: "boolean",
@@ -6966,12 +7193,59 @@ const filters = [
 				type: "string",
 				description: "assertive 오류 상태"
 			},
+			{
+				name: "sortable",
+				type: "boolean",
+				default: "true",
+				description: "헤더 클릭 정렬"
+			},
+			{
+				name: "sort",
+				type: "QueryResultSort | null",
+				description: "제어형 정렬 상태"
+			},
+			{
+				name: "onSortChange",
+				type: "(sort: QueryResultSort | null) => void",
+				description: "정렬 변경"
+			},
+			{
+				name: "rowHeight",
+				type: "number",
+				default: "32",
+				description: "행 높이(px). 윈도잉의 기준"
+			},
+			{
+				name: "rowDetails",
+				type: "boolean",
+				default: "true",
+				description: "행을 상세 패널로 열기"
+			},
+			{
+				name: "footer",
+				type: "ReactNode",
+				description: "행 수 뒤에 붙는 푸터 내용 — 경과 시간, 읽은 바이트"
+			},
 			{
 				name: "labels",
 				type: "QueryResultsTableLabels",
-				description: "로딩/빈 상태/행 수 문구"
+				description: "로딩/빈 상태/행 수/정렬/상세 문구"
 			}
 		] },
+		dependencies: [
+			{
+				slug: "field-token",
+				category: "core"
+			},
+			{
+				slug: "flyout",
+				category: "shell"
+			},
+			{
+				slug: "description-list",
+				category: "core"
+			}
+		],
 		testDescribe: "QueryResultsTable"
 	},
 	{
@@ -7011,12 +7285,12 @@ const filters = [
 			},
 			{
 				name: "onRun",
-				type: "(sql: string) => void",
-				description: "Mod+Enter 실행 핸들러"
+				type: "(sql: string, context: SqlEditorRunContext) => void",
+				description: "Mod+Enter 실행 핸들러. 두 번째 인자로 선택 영역과 커서 위치"
 			},
 			{
 				name: "onRunAndAdvance",
-				type: "(sql: string) => void",
+				type: "(sql: string, context: SqlEditorRunContext) => void",
 				description: "Shift+Enter — 실행 후 다음 셀/탭으로 이동"
 			},
 			{
@@ -7069,6 +7343,18 @@ const filters = [
 				type: "boolean",
 				description: "실행 힌트/버튼 표시. 기본값은 onRun이 있을 때 표시"
 			},
+			{
+				name: "lineNumbers",
+				type: "boolean",
+				default: "true",
+				description: "줄 번호 거터"
+			},
+			{
+				name: "theme",
+				type: "SqlEditorTheme",
+				default: "\"auto\"",
+				description: "편집기 색상. auto는 OptThemeProvider의 resolved mode를 따름"
+			},
 			{
 				name: "labels",
 				type: "SqlEditorLabels",
@@ -7259,6 +7545,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",
@@ -7315,6 +7816,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에서 사용.",
@@ -7404,6 +7920,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 표시.",
@@ -9881,6 +10410,777 @@ const messages = [
 			avoid: ["선택 초기화를 호출자에게 맡기지 않습니다 — 보이지 않는 행에 일괄 작업이 적용됩니다."]
 		},
 		testDescribe: "CatalogFrame"
+	},
+	{
+		name: "SchemaTree",
+		category: "shell",
+		functionalCategory: "navigation",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"schema",
+			"tables",
+			"columns",
+			"tree",
+			"autocomplete"
+		],
+		description: "쿼리할 수 있는 테이블과 컬럼을 타입 글리프와 함께 보여주는 트리. 테이블·컬럼을 함께 검색하고, 이름을 커서에 삽입하거나 테이블을 미리보기합니다.",
+		slug: "schema-tree",
+		exports: ["SchemaTree"],
+		props: { SchemaTree: [
+			{
+				name: "tables",
+				type: "SchemaTreeTable[]",
+				required: true,
+				description: "테이블과 컬럼"
+			},
+			{
+				name: "loading",
+				type: "boolean",
+				description: "스키마 조회 중"
+			},
+			{
+				name: "defaultExpanded",
+				type: "string[]",
+				description: "처음에 펼칠 테이블. 생략 시 첫 테이블"
+			},
+			{
+				name: "onInsert",
+				type: "(name: string, kind: \"table\" | \"column\", table: string) => void",
+				description: "이름을 편집기 커서에 삽입"
+			},
+			{
+				name: "onPreview",
+				type: "(table: string) => void",
+				description: "테이블 미리보기 실행. SQL은 호출자가 작성"
+			},
+			{
+				name: "header",
+				type: "ReactNode",
+				description: "검색창 위 내용"
+			},
+			{
+				name: "labels",
+				type: "SchemaTreeLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [{
+			slug: "field-token",
+			category: "core"
+		}, {
+			slug: "highlight",
+			category: "core"
+		}],
+		ariaRole: "complementary",
+		testDescribe: "SchemaTree"
+	},
+	{
+		name: "QueryToolbar",
+		category: "shell",
+		functionalCategory: "action",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"run",
+			"cancel",
+			"toolbar",
+			"shortcut"
+		],
+		description: "실행 버튼 하나가 상태를 말하는 쿼리 툴바. 변경됨/현재/실행 중을 색과 문구로 구분하고, 실행 중이면 취소로 바뀌며, 선택 영역·전체 실행은 분할 버튼 뒤에 둡니다.",
+		slug: "query-toolbar",
+		exports: ["QueryToolbar"],
+		props: { QueryToolbar: [
+			{
+				name: "onRun",
+				type: "() => void",
+				required: true,
+				description: "커서 위치의 문장 실행"
+			},
+			{
+				name: "onCancel",
+				type: "() => void",
+				description: "실행 중 취소. 있으면 버튼이 Cancel로 전환"
+			},
+			{
+				name: "running",
+				type: "boolean",
+				description: "실행 중"
+			},
+			{
+				name: "runState",
+				type: "QueryRunState",
+				default: "\"idle\"",
+				description: "마지막 실행 대비 변경 여부"
+			},
+			{
+				name: "runDisabledReason",
+				type: "string",
+				description: "실행 불가 사유. 툴팁으로 표시"
+			},
+			{
+				name: "onRunSelection",
+				type: "() => void",
+				description: "선택 영역만 실행"
+			},
+			{
+				name: "hasSelection",
+				type: "boolean",
+				description: "선택 영역이 있는지. 없으면 항목 비활성"
+			},
+			{
+				name: "onRunAll",
+				type: "() => void",
+				description: "전체 문장 실행"
+			},
+			{
+				name: "multiStatement",
+				type: "boolean",
+				description: "문장이 둘 이상인지. 아니면 전체 실행을 숨김"
+			},
+			{
+				name: "onSave",
+				type: "() => void",
+				description: "저장 다이얼로그 열기"
+			},
+			{
+				name: "saveDisabled",
+				type: "boolean",
+				description: "저장 비활성"
+			},
+			{
+				name: "children",
+				type: "ReactNode",
+				description: "실행 그룹 뒤의 컨트롤 — 필터, 변수"
+			},
+			{
+				name: "trailing",
+				type: "ReactNode",
+				description: "끝쪽 컨트롤"
+			},
+			{
+				name: "modifierKey",
+				type: "string",
+				description: "단축키 힌트의 수정자 글리프. 기본은 플랫폼 감지"
+			},
+			{
+				name: "labels",
+				type: "QueryToolbarLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [
+			{
+				slug: "button",
+				category: "core"
+			},
+			{
+				slug: "kbd",
+				category: "core"
+			},
+			{
+				slug: "dropdown-menu",
+				category: "core"
+			}
+		],
+		ariaRole: "toolbar",
+		testDescribe: "QueryToolbar"
+	},
+	{
+		name: "QueryOutputPane",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"results",
+			"chart",
+			"split",
+			"status bar"
+		],
+		description: "쿼리 결과가 놓이는 출력 패널. 대기·실행 중·오류·취소·완료 상태를 그리고, 완료는 표·차트·좌우 분할로 전환하며, 상태바에 행 수·경과·읽은 바이트·절단 여부를 남깁니다.",
+		slug: "query-output-pane",
+		exports: ["QueryOutputPane"],
+		props: { QueryOutputPane: [
+			{
+				name: "view",
+				type: "QueryOutputView",
+				required: true,
+				description: "표 / 차트 / 분할"
+			},
+			{
+				name: "onViewChange",
+				type: "(view: QueryOutputView) => void",
+				required: true,
+				description: "뷰 전환"
+			},
+			{
+				name: "results",
+				type: "ReactNode",
+				required: true,
+				description: "결과 테이블"
+			},
+			{
+				name: "chart",
+				type: "ReactNode",
+				description: "차트 빌더. 없으면 차트 뷰를 숨김"
+			},
+			{
+				name: "status",
+				type: "\"idle\" | \"running\" | \"success\" | \"error\" | \"cancelled\"",
+				required: true,
+				description: "실행 수명주기"
+			},
+			{
+				name: "error",
+				type: "string",
+				description: "백엔드 오류 원문"
+			},
+			{
+				name: "runningSeconds",
+				type: "number",
+				description: "실행 경과 초. 로딩 상태에 표시"
+			},
+			{
+				name: "onCancel",
+				type: "() => void",
+				description: "실행 취소"
+			},
+			{
+				name: "stats",
+				type: "QueryRunStats",
+				description: "행 수, 경과, 읽은 바이트, 절단 여부"
+			},
+			{
+				name: "actions",
+				type: "ReactNode",
+				description: "뷰 전환 오른쪽 컨트롤"
+			},
+			{
+				name: "statusExtra",
+				type: "ReactNode",
+				description: "상태바 추가 내용"
+			},
+			{
+				name: "banner",
+				type: "ReactNode",
+				description: "출력 위 알림"
+			},
+			{
+				name: "onRetry",
+				type: "() => void",
+				description: "오류 상태 닫기"
+			},
+			{
+				name: "labels",
+				type: "QueryOutputPaneLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [
+			{
+				slug: "segmented-control",
+				category: "core"
+			},
+			{
+				slug: "empty-state",
+				category: "core"
+			},
+			{
+				slug: "resizable",
+				category: "core"
+			}
+		],
+		ariaRole: "region",
+		testDescribe: "QueryOutputPane"
+	},
+	{
+		name: "QueryResultChart",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"chart",
+			"visualization",
+			"line",
+			"bar",
+			"pie",
+			"number"
+		],
+		description: "결과 행을 차트로 그리는 빌더. 첫 문자·날짜 컬럼을 축으로, 숫자 컬럼을 값으로 고르고, 한 행 한 숫자면 큰 숫자로 보여줍니다. 설정은 호출자가 들고 있어 저장 쿼리와 함께 보관됩니다.",
+		slug: "query-result-chart",
+		exports: ["QueryResultChart"],
+		domlessExports: ["defaultQueryChartConfig", "numericResultColumns"],
+		props: { QueryResultChart: [
+			{
+				name: "columns",
+				type: "QueryResultColumn[]",
+				required: true,
+				description: "결과 컬럼"
+			},
+			{
+				name: "rows",
+				type: "Array<Record<string, unknown>>",
+				required: true,
+				description: "결과 행"
+			},
+			{
+				name: "config",
+				type: "QueryChartConfig",
+				required: true,
+				description: "차트 종류, 축, 값 컬럼"
+			},
+			{
+				name: "onConfigChange",
+				type: "(config: QueryChartConfig) => void",
+				required: true,
+				description: "설정 변경"
+			},
+			{
+				name: "showControls",
+				type: "boolean",
+				default: "true",
+				description: "컨트롤 표시. 임베드 카드에서는 끔"
+			},
+			{
+				name: "height",
+				type: "number",
+				description: "차트 높이(px). 기본은 부모 채움"
+			},
+			{
+				name: "maxPoints",
+				type: "number",
+				default: "1000",
+				description: "차트에 그릴 최대 행 수"
+			},
+			{
+				name: "labels",
+				type: "QueryResultChartLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [
+			{
+				slug: "line-chart",
+				category: "visuals"
+			},
+			{
+				slug: "bar-chart",
+				category: "visuals"
+			},
+			{
+				slug: "area-chart",
+				category: "visuals"
+			},
+			{
+				slug: "pie-chart",
+				category: "visuals"
+			},
+			{
+				slug: "segmented-control",
+				category: "core"
+			},
+			{
+				slug: "select",
+				category: "core"
+			}
+		],
+		testDescribe: "QueryResultChart"
+	},
+	{
+		name: "QueryFiltersMenu",
+		category: "shell",
+		functionalCategory: "input",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"filters",
+			"date range",
+			"placeholder",
+			"where"
+		],
+		description: "기간과 속성 조건을 데이터로 들고 {filters} 플레이스홀더로 SQL에 전달하는 메뉴. 플레이스홀더가 없으면 조건이 적용되지 않는다고 경고하고 삽입 버튼을 제공합니다.",
+		slug: "query-filters-menu",
+		exports: ["QueryFiltersMenu"],
+		domlessExports: [
+			"EMPTY_QUERY_FILTERS",
+			"VALUELESS_OPERATORS",
+			"hasActiveQueryFilters",
+			"countActiveQueryFilters"
+		],
+		props: { QueryFiltersMenu: [
+			{
+				name: "value",
+				type: "QueryFilters",
+				required: true,
+				description: "기간과 속성 필터"
+			},
+			{
+				name: "onChange",
+				type: "(filters: QueryFilters) => void",
+				required: true,
+				description: "필터 변경"
+			},
+			{
+				name: "fields",
+				type: "QueryFilterField[]",
+				required: true,
+				description: "필드 선택지"
+			},
+			{
+				name: "placeholderPresent",
+				type: "boolean",
+				description: "SQL에 {filters}가 있는지"
+			},
+			{
+				name: "onInsertPlaceholder",
+				type: "() => void",
+				description: "{filters}를 커서에 삽입"
+			},
+			{
+				name: "onLoadValues",
+				type: "(field: string) => Promise<string[]>",
+				description: "필드의 알려진 값. 값 입력란의 제안으로 쓰이며 자유 입력도 허용"
+			},
+			{
+				name: "presets",
+				type: "DateRangePreset[]",
+				description: "기간 프리셋"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				description: "비활성"
+			},
+			{
+				name: "labels",
+				type: "QueryFiltersMenuLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [
+			{
+				slug: "popover",
+				category: "core"
+			},
+			{
+				slug: "date-range-picker",
+				category: "core"
+			},
+			{
+				slug: "select",
+				category: "core"
+			},
+			{
+				slug: "combobox",
+				category: "core"
+			},
+			{
+				slug: "callout",
+				category: "core"
+			}
+		],
+		testDescribe: "QueryFiltersMenu"
+	},
+	{
+		name: "QueryVariablesMenu",
+		category: "shell",
+		functionalCategory: "input",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"variables",
+			"parameters",
+			"placeholder"
+		],
+		description: "실행마다 바뀌는 값을 이름 붙여 두는 변수 메뉴. SQL은 {variables.name}으로 참조하고 치환은 호출자가 합니다.",
+		slug: "query-variables-menu",
+		exports: ["QueryVariablesMenu"],
+		domlessExports: ["isValidQueryVariableName"],
+		props: { QueryVariablesMenu: [
+			{
+				name: "value",
+				type: "QueryVariable[]",
+				required: true,
+				description: "변수 목록"
+			},
+			{
+				name: "onChange",
+				type: "(variables: QueryVariable[]) => void",
+				required: true,
+				description: "변수 변경"
+			},
+			{
+				name: "onInsert",
+				type: "(name: string) => void",
+				description: "{variables.name}을 커서에 삽입"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				description: "비활성"
+			},
+			{
+				name: "disabledReason",
+				type: "string",
+				description: "비활성 사유. 툴팁으로 표시"
+			},
+			{
+				name: "labels",
+				type: "QueryVariablesMenuLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [{
+			slug: "popover",
+			category: "core"
+		}, {
+			slug: "input",
+			category: "core"
+		}],
+		testDescribe: "QueryVariablesMenu"
+	},
+	{
+		name: "QueryHistoryList",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"history",
+			"recent",
+			"rerun"
+		],
+		description: "실행 이력 목록. 각 실행의 성공/실패, 시각, 행 수, 경과를 보여주고 편집기로 되돌리거나 다시 실행합니다.",
+		slug: "query-history-list",
+		exports: ["QueryHistoryList"],
+		props: { QueryHistoryList: [
+			{
+				name: "items",
+				type: "QueryHistoryItem[]",
+				required: true,
+				description: "최근 실행부터"
+			},
+			{
+				name: "loading",
+				type: "boolean",
+				description: "이력 조회 중"
+			},
+			{
+				name: "onLoad",
+				type: "(item: QueryHistoryItem) => void",
+				description: "쿼리를 편집기로"
+			},
+			{
+				name: "onRerun",
+				type: "(item: QueryHistoryItem) => void",
+				description: "그대로 다시 실행"
+			},
+			{
+				name: "onClear",
+				type: "() => void",
+				description: "이력 비우기"
+			},
+			{
+				name: "header",
+				type: "ReactNode",
+				description: "목록 위 내용"
+			},
+			{
+				name: "labels",
+				type: "QueryHistoryListLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [{
+			slug: "button",
+			category: "core"
+		}],
+		ariaRole: "region",
+		testDescribe: "QueryHistoryList"
+	},
+	{
+		name: "SaveQueryDialog",
+		category: "shell",
+		functionalCategory: "overlay",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"save",
+			"dialog",
+			"saved query"
+		],
+		description: "쿼리에 이름·설명·공개 여부를 붙여 저장하는 다이얼로그. 편집기에 문장이 여럿이면 어느 문장을 저장할지 넘겨 보며 고릅니다.",
+		slug: "save-query-dialog",
+		exports: ["SaveQueryDialog"],
+		props: { SaveQueryDialog: [
+			{
+				name: "open",
+				type: "boolean",
+				required: true,
+				description: "열림"
+			},
+			{
+				name: "onOpenChange",
+				type: "(open: boolean) => void",
+				required: true,
+				description: "열림 상태 변경"
+			},
+			{
+				name: "onSubmit",
+				type: "(values: SaveQueryValues) => void | Promise<void>",
+				required: true,
+				description: "저장"
+			},
+			{
+				name: "candidates",
+				type: "string[]",
+				required: true,
+				description: "저장할 SQL 후보. 문장이 여럿이면 여러 개"
+			},
+			{
+				name: "initialCandidate",
+				type: "number",
+				default: "0",
+				description: "처음 보여줄 후보"
+			},
+			{
+				name: "candidateIsSelection",
+				type: "boolean",
+				description: "후보가 선택 영역인지"
+			},
+			{
+				name: "initialValues",
+				type: "Partial<Omit<SaveQueryValues, \"sql\">>",
+				description: "기존 저장 쿼리를 수정할 때의 초기값"
+			},
+			{
+				name: "mode",
+				type: "\"create\" | \"update\"",
+				default: "\"create\"",
+				description: "새로 저장 / 수정"
+			},
+			{
+				name: "saving",
+				type: "boolean",
+				description: "저장 중"
+			},
+			{
+				name: "error",
+				type: "string",
+				description: "저장 실패 메시지"
+			},
+			{
+				name: "labels",
+				type: "SaveQueryDialogLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [
+			{
+				slug: "dialog",
+				category: "core"
+			},
+			{
+				slug: "input",
+				category: "core"
+			},
+			{
+				slug: "textarea",
+				category: "core"
+			},
+			{
+				slug: "switch",
+				category: "core"
+			}
+		],
+		testDescribe: "SaveQueryDialog"
+	},
+	{
+		name: "QueryWorkspace",
+		category: "shell",
+		functionalCategory: "layout",
+		maturity: "stable",
+		keywords: [
+			"sql",
+			"workspace",
+			"layout",
+			"resizable",
+			"sidebar"
+		],
+		description: "스키마·편집기·출력의 3-pane 쿼리 워크스페이스. 패널은 리사이즈되고 사이드바는 접히며, storageKey로 레이아웃을 기억합니다. 툴바·편집기·출력은 슬롯입니다.",
+		slug: "query-workspace",
+		exports: ["QueryWorkspace"],
+		props: { QueryWorkspace: [
+			{
+				name: "sidebar",
+				type: "ReactNode",
+				description: "왼쪽 패널 내용"
+			},
+			{
+				name: "sidebarOpen",
+				type: "boolean",
+				description: "제어형 사이드바 열림"
+			},
+			{
+				name: "onSidebarOpenChange",
+				type: "(open: boolean) => void",
+				description: "사이드바 열림 변경"
+			},
+			{
+				name: "header",
+				type: "ReactNode",
+				description: "툴바 위 — 탭이나 페이지 헤더"
+			},
+			{
+				name: "toolbar",
+				type: "ReactNode",
+				description: "툴바"
+			},
+			{
+				name: "editor",
+				type: "ReactNode",
+				required: true,
+				description: "편집기"
+			},
+			{
+				name: "output",
+				type: "ReactNode",
+				required: true,
+				description: "출력"
+			},
+			{
+				name: "storageKey",
+				type: "string",
+				description: "패널 크기를 localStorage에 기억할 키"
+			},
+			{
+				name: "defaultSidebarSize",
+				type: "number",
+				default: "22",
+				description: "사이드바 폭(%)"
+			},
+			{
+				name: "defaultEditorSize",
+				type: "number",
+				default: "40",
+				description: "편집기 높이(%)"
+			},
+			{
+				name: "labels",
+				type: "QueryWorkspaceLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		dependencies: [{
+			slug: "resizable",
+			category: "core"
+		}, {
+			slug: "button",
+			category: "core"
+		}],
+		testDescribe: "QueryWorkspace"
 	}
 ];
 //#endregion