@reopt-ai/opt-ui 1.13.0 → 1.14.0

package/dist/meta.js

@@ -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",
@@ -2220,7 +2250,7 @@ const coreMetas = [
 				{
 					name: "gutter",
 					deprecated: {
-						since: "1.12.5",
+						since: "1.13.0",
 						replacement: "sideOffset"
 					},
 					type: "number",
@@ -2545,6 +2575,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 +2633,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 +2682,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 +2707,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 +2755,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 +2825,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 +2896,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 +2976,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 +3030,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 +3103,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 +3565,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 +4084,11 @@ const store = useFormStore({ defaultValues: { name: "" } });
 				type: "number",
 				description: "매치 카운트 표시 (toLocaleString 포맷)"
 			},
+			{
+				name: "labels",
+				type: "ConditionBuilderLabels",
+				description: "미리보기 문구 오버라이드 (previewSuffix, formatPreview). 기본은 영어 \"matches\""
+			},
 			{
 				name: "addNestedGroupLabel",
 				type: "string",
@@ -3961,6 +4099,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 +4128,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 +4165,7 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			DropdownContent: [{
 				name: "gutter",
 				deprecated: {
-					since: "1.12.5",
+					since: "1.13.0",
 					replacement: "sideOffset"
 				},
 				type: "number",
@@ -4776,6 +4916,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 라이브 영역으로 콘텐츠 위 로딩 상태를 표시합니다.",
@@ -5821,6 +5971,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 +6121,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 +6326,10 @@ const data = [
 		testDescribe: "ActivityFeed"
 	},
 	{
+		usage: {
+			bestPractices: ["filters의 id를 안정적으로 유지하고 onFilterChange에서 해당 필터의 value를 갱신합니다. onClearAll에서는 적용된 값과 조회 조건을 함께 초기화합니다."],
+			avoid: ["필터 UI 변경만으로 서버 데이터까지 자동 조회된다고 가정하지 않습니다. 비동기 조회와 오류 처리는 호출자가 연결합니다."]
+		},
 		name: "FilterBar",
 		category: "shell",
 		description: "필터링 바 컴포넌트. 검색, 선택, 다중 선택 필터 지원.",
@@ -7375,6 +7544,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 +7815,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 +7919,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 +11094,6 @@ const messages = [
 				category: "core"
 			}
 		],
-		ariaRole: "dialog",
 		testDescribe: "SaveQueryDialog"
 	},
 	{

package/dist/shells/index.cjs

@@ -1,7 +1,7 @@
 "use client";
 "use client";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_field_sidebar = require("../field-sidebar-CxxSK4JO.cjs");
+const require_field_sidebar = require("../field-sidebar-ePqFX6MN.cjs");
 let _reopt_ai_opt_charts = require("@reopt-ai/opt-charts");
 exports.AppMenubar = require_field_sidebar.AppMenubar;
 exports.BranchSelect = require_field_sidebar.BranchSelect;