@reopt-ai/opt-ui 1.10.0 → 1.12.0

package/dist/meta.cjs

@@ -721,7 +721,7 @@ const coreMetas = [
 			},
 			{
 				name: "variant",
-				type: "\"heading-1\" … \"heading-6\" | \"display-1\" | \"display-2\" | \"display-3\"",
+				type: "\"heading-1\" | \"heading-2\" | \"heading-3\" | \"heading-4\" | \"heading-5\" | \"heading-6\" | \"display-1\" | \"display-2\" | \"display-3\"",
 				description: "시각적 제목 역할"
 			},
 			{
@@ -1050,7 +1050,7 @@ const coreMetas = [
 	{
 		name: "StatCard",
 		category: "core",
-		description: "트렌드 방향과 변화량을 표시하는 통계 카드.",
+		description: "단일 지표를 값·변화량·보조 설명으로 표시하는 통계 카드. 비교 기준이 없으면 변화량 줄을 렌더하지 않는다.",
 		slug: "stat-card",
 		exports: ["StatCard"],
 		props: { StatCard: [
@@ -1069,14 +1069,61 @@ const coreMetas = [
 			{
 				name: "change",
 				type: "string",
-				required: true,
-				description: "변화량 텍스트 (예: '+12.5%')"
+				description: "변화량 텍스트 (예: '+12.5%'). 비교 기준이 없으면 생략 — trend와 함께 있을 때만 렌더된다"
 			},
 			{
 				name: "trend",
 				type: "\"up\" | \"down\" | \"neutral\"",
-				required: true,
-				description: "트렌드 방향. 색상과 아이콘 결정"
+				description: "변화 방향. change와 함께 있을 때만 의미를 갖는다"
+			},
+			{
+				name: "polarity",
+				type: "\"positive\" | \"negative\"",
+				default: "\"positive\"",
+				description: "상승이 좋은 지표인지. 이탈률·에러 수처럼 반대인 지표는 negative로 색을 뒤집는다"
+			},
+			{
+				name: "description",
+				type: "string",
+				description: "값 아래 한 줄 보조 설명 (집계 대상·기간 등)"
+			},
+			{
+				name: "hint",
+				type: "string",
+				description: "산출 근거 등 긴 설명. 툴팁과 aria-describedby로 노출"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "밀도 프리셋. 요약 행에는 sm"
+			},
+			{
+				name: "loading",
+				type: "boolean",
+				default: "false",
+				description: "값 로딩 중 스켈레톤 표시"
+			},
+			{
+				name: "href",
+				type: "string",
+				description: "드릴다운 링크. 지정 시 카드가 앵커로 렌더된다"
+			},
+			{
+				name: "onSelect",
+				type: "() => void",
+				description: "드릴다운 핸들러. 지정 시 카드가 버튼으로 렌더된다"
+			},
+			{
+				name: "selected",
+				type: "boolean",
+				default: "false",
+				description: "선택 가능한 카드 행에서 현재 선택 상태"
+			},
+			{
+				name: "sparklineData",
+				type: "number[]",
+				description: "값 옆에 그릴 미니 추세선 데이터"
 			}
 		] },
 		ariaRole: "presentation",
@@ -2679,10 +2726,19 @@ const store = useFormStore({ defaultValues: { name: "" } });
 				type: "string",
 				description: "스위치 레이블"
 			},
+			{
+				name: "hint",
+				type: "string",
+				description: "레이블 아래 보조 설명 텍스트"
+			},
 			{
 				name: "description",
 				type: "string",
-				description: "레이블 아래 설명 텍스트"
+				description: "레이블 아래 설명 텍스트",
+				deprecated: {
+					since: "1.9.0",
+					replacement: "hint"
+				}
 			},
 			{
 				name: "checked",
@@ -3103,12 +3159,180 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			},
 			{
 				name: "actions",
-				type: "EmptyStateAction[]",
-				description: "액션 버튼 배열. { label, onClick, variant? }"
+				type: "EmptyStateAction[] | ReactNode",
+				description: "액션 버튼 배열 { label, onClick, variant? } 또는 직접 렌더할 노드"
+			},
+			{
+				name: "body",
+				type: "ReactNode",
+				description: "description 대신 넣는 리치 본문 (문단·목록·코드 스니펫)"
+			},
+			{
+				name: "footer",
+				type: "ReactNode",
+				description: "구분선 아래 보조 콘텐츠. 문서 링크·단축키 안내 등"
+			},
+			{
+				name: "layout",
+				type: "\"vertical\" | \"horizontal\"",
+				default: "\"vertical\"",
+				description: "horizontal은 아이콘을 텍스트 옆으로 옮긴다 (전체 페이지용)"
+			},
+			{
+				name: "titleSize",
+				type: "\"sm\" | \"md\" | \"lg\"",
+				default: "\"md\"",
+				description: "제목 시각 크기. headingLevel과 독립"
+			},
+			{
+				name: "hasBorder",
+				type: "boolean",
+				default: "false",
+				description: "테두리 있는 패널로 렌더"
+			},
+			{
+				name: "tone",
+				type: "\"default\" | \"subdued\" | \"error\"",
+				default: "\"default\"",
+				description: "error는 실패를 알리고 role=alert로 렌더. subdued는 아직 데이터가 없음을 뜻한다"
+			},
+			{
+				name: "iconSize",
+				type: "\"sm\" | \"md\" | \"lg\"",
+				default: "\"md\"",
+				description: "아이콘 크기 프리셋"
+			},
+			{
+				name: "headingLevel",
+				type: "\"h2\" | \"h3\" | \"h4\"",
+				default: "\"h3\"",
+				description: "문서 구조상 제목 레벨"
 			}
 		] },
 		testDescribe: "EmptyState"
 	},
+	{
+		name: "DescriptionList",
+		category: "core",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"detail",
+			"definition",
+			"key-value",
+			"metadata",
+			"dl"
+		],
+		description: "한 대상의 라벨 있는 사실들을 시맨틱 <dl>로 표시한다. 상세 패널의 필드 나열을 표준화하고 식별자 복사를 제공한다.",
+		slug: "description-list",
+		exports: ["DescriptionList"],
+		props: { DescriptionList: [
+			{
+				name: "items",
+				type: "DescriptionListItem[]",
+				required: true,
+				description: "term/description 쌍 배열. { id, term, description, copyValue?, hint?, wrap? }"
+			},
+			{
+				name: "layout",
+				type: "\"grid\" | \"stack\" | \"inline\"",
+				default: "\"grid\"",
+				description: "grid는 각 쌍을 박스로 감싼다(필드가 많은 상세 패널). stack은 평범한 정의 목록, inline은 헤더 스트립용 한 줄 배치"
+			},
+			{
+				name: "columns",
+				type: "1 | 2 | 3 | 4",
+				default: "2",
+				description: "grid/stack 레이아웃의 컬럼 수"
+			},
+			{
+				name: "compressed",
+				type: "boolean",
+				default: "false",
+				description: "밀도 축소"
+			},
+			{
+				name: "labels",
+				type: "DescriptionListLabels",
+				description: "복사/복사됨/빈 값 문구"
+			}
+		] },
+		usage: {
+			bestPractices: ["세션 ID·프로필 ID처럼 다른 화면에 붙여넣게 되는 값에는 copyValue를 준다.", "값이 비면 빈 셀 대신 labels.empty가 렌더되므로 로딩 중과 구분된다."],
+			avoid: ["표 형태로 비교해야 하는 다건 데이터에는 쓰지 않는다 — 그건 DataTable의 일이다."]
+		},
+		testDescribe: "DescriptionList"
+	},
+	{
+		name: "Identity",
+		category: "core",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"user",
+			"profile",
+			"avatar",
+			"person",
+			"anonymous"
+		],
+		description: "사람(또는 익명 디바이스)을 목록 셀 한 칸으로 표현한다. 이름→이메일→ID 폴백과 익명 표식을 한 곳에서 처리한다.",
+		slug: "identity",
+		exports: ["Identity"],
+		props: { Identity: [
+			{
+				name: "name",
+				type: "string | null",
+				description: "표시 이름. 없으면 secondary, 그다음 id로 폴백한다"
+			},
+			{
+				name: "secondary",
+				type: "string | null",
+				description: "보통 이메일. 이름이 없으면 주 라벨로 승격된다"
+			},
+			{
+				name: "id",
+				type: "string",
+				description: "최후 폴백 라벨이자 hover 시 title"
+			},
+			{
+				name: "avatarSrc",
+				type: "string | null",
+				description: "아바타 이미지 URL"
+			},
+			{
+				name: "state",
+				type: "\"identified\" | \"anonymous\"",
+				description: "익명 여부. 디바이스를 사람으로 오독하지 않게 배지로 표시한다"
+			},
+			{
+				name: "badge",
+				type: "ReactNode",
+				description: "state 배지 대신 표시할 내용 (라이프사이클 단계 등)"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "밀도 프리셋"
+			},
+			{
+				name: "hideAvatar",
+				type: "boolean",
+				default: "false",
+				description: "이미 밀도가 높은 행에서 아바타 제거"
+			},
+			{
+				name: "labels",
+				type: "{ identified?: string; anonymous?: string }",
+				description: "식별/익명 배지 문구"
+			}
+		] },
+		usage: {
+			bestPractices: ["사용자·세션·이벤트 표에서 주체를 나타내는 컬럼에 일관되게 사용한다."],
+			avoid: ["아바타만 필요하면 Avatar를 직접 쓴다."]
+		},
+		testDescribe: "Identity"
+	},
 	{
 		name: "Card",
 		category: "core",
@@ -3188,10 +3412,19 @@ const store = useFormStore({ defaultValues: { name: "" } });
 					type: "string",
 					description: "체크박스 레이블"
 				},
+				{
+					name: "hint",
+					type: "string",
+					description: "레이블 아래 보조 설명 텍스트"
+				},
 				{
 					name: "description",
 					type: "string",
-					description: "레이블 아래 설명 텍스트"
+					description: "레이블 아래 설명 텍스트",
+					deprecated: {
+						since: "1.9.0",
+						replacement: "hint"
+					}
 				},
 				{
 					name: "checked",
@@ -3325,10 +3558,19 @@ const store = useFormStore({ defaultValues: { name: "" } });
 					type: "string",
 					description: "라디오 레이블"
 				},
+				{
+					name: "hint",
+					type: "string",
+					description: "레이블 아래 보조 설명 텍스트"
+				},
 				{
 					name: "description",
 					type: "string",
-					description: "레이블 아래 설명 텍스트"
+					description: "레이블 아래 설명 텍스트",
+					deprecated: {
+						since: "1.9.0",
+						replacement: "hint"
+					}
 				},
 				{
 					name: "size",
@@ -3399,7 +3641,7 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			},
 			{
 				name: "onComparisonChange",
-				type: "(comparison: boolean, mode: ComparisonMode) => void",
+				type: "(mode: ComparisonMode | null) => void",
 				description: "비교 모드 변경 콜백"
 			},
 			{
@@ -4087,7 +4329,12 @@ const store = useFormStore({ defaultValues: { name: "" } });
 				{
 					name: "autoSaveId",
 					type: "string",
-					description: "id의 deprecated 별칭"
+					description: "id의 deprecated 별칭",
+					deprecated: {
+						since: "1.6.0",
+						replacement: "id",
+						reason: "id + defaultLayout + onLayoutChanged 조합으로 대체되었습니다."
+					}
 				},
 				{
 					name: "className",
@@ -4734,82 +4981,273 @@ const MyDashboard = createBlock<MyDashboardProps>(
 			}
 		] },
 		testDescribe: "ShaderSurface"
-	}
-];
-//#endregion
-//#region src/visuals/_meta.ts
-/** @deprecated Chart metadata moved to `@reopt-ai/opt-charts/meta`. */
-const visualMetas = [];
-const shellMetas = [
-	{
-		name: "FaqAccordion",
-		category: "shell",
-		description: "FAQ 질문/답변 아코디언. Composite + Disclosure 조합.",
-		slug: "faq-accordion",
-		exports: ["FaqAccordion"],
-		props: { FaqAccordion: [{
-			name: "items",
-			type: "FaqItem[]",
-			required: true,
-			description: "FAQ 항목 배열. { id, question, answer }"
-		}] },
-		dependencies: [{
-			slug: "disclosure",
-			category: "core"
-		}],
-		testDescribe: "FaqAccordion"
 	},
 	{
-		name: "PageAside",
-		category: "shell",
-		description: "Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.",
-		slug: "page-aside",
-		exports: ["PageAside"],
-		props: { PageAside: [
+		name: "Callout",
+		category: "core",
+		description: "페이지에 머무는 인페이지 고지. Alert와 달리 dismiss가 없고, 조건이 참인 동안 레이아웃의 일부로 남습니다.",
+		slug: "callout",
+		exports: ["Callout"],
+		props: { Callout: [
 			{
-				name: "header",
+				name: "tone",
+				type: "\"info\" | \"success\" | \"warning\" | \"danger\" | \"neutral\"",
+				default: "\"info\"",
+				description: "고지의 성격"
+			},
+			{
+				name: "title",
 				type: "ReactNode",
-				description: "상단 고정 슬롯 (예: package switcher)."
+				description: "한 줄 제목"
+			},
+			{
+				name: "icon",
+				type: "ReactNode",
+				description: "tone 기본 글리프 대체. null이면 글리프 없음"
+			},
+			{
+				name: "action",
+				type: "ReactNode",
+				description: "다음 한 걸음. 둘 이상이면 고지가 아니라 폼"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "밀도"
 			},
 			{
 				name: "children",
 				type: "ReactNode",
-				required: true,
-				description: "스크롤 가능한 네비게이션 영역."
+				description: "본문"
+			}
+		] },
+		usage: {
+			bestPractices: ["조건이 참인 동안 계속 보여야 하는 안내에 사용합니다 (정리할 신규 N개, 표본 기반 수치)."],
+			avoid: ["방금 일어난 일을 알릴 때는 Alert를 씁니다. Callout에는 dismiss가 없습니다."]
+		},
+		testDescribe: "Callout"
+	},
+	{
+		name: "StatusDot",
+		category: "core",
+		description: "점 + 텍스트로 상태를 표현합니다. 라벨이 필수라 색만으로 상태를 말할 수 없습니다.",
+		slug: "status-dot",
+		exports: ["StatusDot"],
+		props: { StatusDot: [
+			{
+				name: "tone",
+				type: "\"neutral\" | \"muted\" | \"info\" | \"success\" | \"warning\" | \"danger\"",
+				default: "\"neutral\"",
+				description: "점 색상"
 			},
 			{
-				name: "footer",
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "점과 글자 크기"
+			},
+			{
+				name: "children",
 				type: "ReactNode",
-				description: "하단 고정 슬롯 (예: version label)."
+				required: true,
+				description: "상태 라벨. 필수 — 색은 상태가 아닙니다"
 			},
 			{
-				name: "widthClassName",
+				name: "hint",
 				type: "string",
-				description: "너비 Tailwind 클래스. 기본값 `w-60`."
-			},
+				description: "판정 기준 툴팁"
+			}
+		] },
+		usage: {
+			bestPractices: ["표의 상태 컬럼처럼 행마다 반복되는 자리에 씁니다. 점은 장식이고 의미는 텍스트가 담습니다."],
+			avoid: ["사람이 붙인 라벨(태그, 카테고리)에는 Badge를 씁니다. StatusDot은 관측된 상태용입니다."]
+		},
+		testDescribe: "StatusDot"
+	},
+	{
+		name: "CopyButton",
+		category: "core",
+		description: "값을 클립보드에 올리고 성공 여부를 알립니다. 클립보드 거부를 삼키지 않습니다.",
+		slug: "copy-button",
+		exports: ["CopyButton"],
+		props: { CopyButton: [
 			{
-				name: "label",
+				name: "value",
 				type: "string",
-				description: "`<aside>`의 aria-label."
+				required: true,
+				description: "복사할 텍스트"
 			},
 			{
-				name: "hideOnMobile",
-				type: "boolean",
-				description: "md 아래에서 숨김. 기본값 true."
+				name: "variant",
+				type: "\"icon\" | \"text\"",
+				default: "\"icon\"",
+				description: "글리프만 / 글리프 + 라벨"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "버튼 크기"
+			},
+			{
+				name: "feedbackDuration",
+				type: "number",
+				default: "1500",
+				description: "확인 상태 유지 시간 (ms)"
+			},
+			{
+				name: "onCopy",
+				type: "(ok: boolean) => void",
+				description: "실제로 복사됐는지 — 비보안 컨텍스트·권한 거부에서 false"
+			},
+			{
+				name: "labels",
+				type: "CopyButtonLabels",
+				description: "copy / copied / failed 문구"
 			}
 		] },
-		testDescribe: "PageAside"
+		testDescribe: "CopyButton"
 	},
 	{
-		name: "ContentTabs",
-		category: "shell",
-		description: "탭 콘텐츠 패널. Tabs primitive 래퍼.",
-		slug: "content-tabs",
-		exports: ["ContentTabs"],
-		props: { ContentTabs: [{
-			name: "tabs",
-			type: "TabDef[]",
-			required: true,
+		name: "SegmentedControl",
+		category: "core",
+		description: "선택지를 모두 보여주는 단일 선택 컨트롤. radio-group 프리미티브 위에 올려 화살표 키가 동작합니다.",
+		slug: "segmented-control",
+		exports: ["SegmentedControl"],
+		props: { SegmentedControl: [
+			{
+				name: "options",
+				type: "SegmentedControlOption<T>[]",
+				required: true,
+				description: "세그먼트 목록 (value / label / icon / badge / disabled)"
+			},
+			{
+				name: "value",
+				type: "T",
+				required: true,
+				description: "선택된 값"
+			},
+			{
+				name: "onChange",
+				type: "(value: T) => void",
+				required: true,
+				description: "선택 변경"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "컨트롤 크기"
+			},
+			{
+				name: "fullWidth",
+				type: "boolean",
+				default: "false",
+				description: "컨테이너를 균등 분할"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "전체 비활성"
+			},
+			{
+				name: "aria-label",
+				type: "string",
+				required: true,
+				description: "radiogroup 이름. 필수"
+			}
+		] },
+		usage: {
+			bestPractices: ["정확히 하나가 참이고 선택지가 적을 때 씁니다 (이벤트 | 속성)."],
+			avoid: ["여러 개를 동시에 켤 수 있으면 ToggleGroup을 씁니다.", "선택지가 많으면 Select를 씁니다."]
+		},
+		testDescribe: "SegmentedControl"
+	}
+];
+//#endregion
+//#region src/visuals/_meta.ts
+/** @deprecated Chart metadata moved to `@reopt-ai/opt-charts/meta`. */
+const visualMetas = [];
+const shellMetas = [
+	{
+		name: "FaqAccordion",
+		category: "shell",
+		description: "FAQ 질문/답변 아코디언. Composite + Disclosure 조합.",
+		slug: "faq-accordion",
+		exports: ["FaqAccordion"],
+		props: { FaqAccordion: [{
+			name: "items",
+			type: "FaqItem[]",
+			required: true,
+			description: "FAQ 항목 배열. { id, question, answer }"
+		}] },
+		ariaRole: "region",
+		keyboardShortcuts: [{
+			keys: "↑ ↓",
+			action: "질문 사이 포커스 이동"
+		}, {
+			keys: "Enter / Space",
+			action: "답변 펼치기 또는 접기"
+		}],
+		dependencies: [{
+			slug: "disclosure",
+			category: "core"
+		}],
+		testDescribe: "FaqAccordion"
+	},
+	{
+		name: "PageAside",
+		category: "shell",
+		description: "Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.",
+		slug: "page-aside",
+		exports: ["PageAside"],
+		props: { PageAside: [
+			{
+				name: "header",
+				type: "ReactNode",
+				description: "상단 고정 슬롯 (예: package switcher)."
+			},
+			{
+				name: "children",
+				type: "ReactNode",
+				required: true,
+				description: "스크롤 가능한 네비게이션 영역."
+			},
+			{
+				name: "footer",
+				type: "ReactNode",
+				description: "하단 고정 슬롯 (예: version label)."
+			},
+			{
+				name: "widthClassName",
+				type: "string",
+				description: "너비 Tailwind 클래스. 기본값 `w-60`."
+			},
+			{
+				name: "label",
+				type: "string",
+				description: "`<aside>`의 aria-label."
+			},
+			{
+				name: "hideOnMobile",
+				type: "boolean",
+				description: "md 아래에서 숨김. 기본값 true."
+			}
+		] },
+		testDescribe: "PageAside"
+	},
+	{
+		name: "ContentTabs",
+		category: "shell",
+		description: "탭 콘텐츠 패널. Tabs primitive 래퍼.",
+		slug: "content-tabs",
+		exports: ["ContentTabs"],
+		props: { ContentTabs: [{
+			name: "tabs",
+			type: "TabDef[]",
+			required: true,
 			description: "탭 정의 배열. { id, label, content }"
 		}, {
 			name: "defaultTabId",
@@ -5074,6 +5512,25 @@ const fields = [
 			slug: "kbd",
 			category: "core"
 		}],
+		ariaRole: "menubar",
+		keyboardShortcuts: [
+			{
+				keys: "← →",
+				action: "상위 메뉴 사이 포커스 이동"
+			},
+			{
+				keys: "Enter / Space / ↓",
+				action: "메뉴 열기"
+			},
+			{
+				keys: "↑ ↓",
+				action: "열린 메뉴 항목 이동"
+			},
+			{
+				keys: "Escape",
+				action: "메뉴 닫고 트리거로 복귀"
+			}
+		],
 		testDescribe: "AppMenubar"
 	},
 	{
@@ -5085,7 +5542,7 @@ const fields = [
 		props: { CommandPalette: [
 			{
 				name: "commands",
-				type: "Omit<Command, \"action\">[]",
+				type: "Omit<CommandDef, \"action\">[]",
 				required: true,
 				description: "커맨드 목록. { id, label, group, shortcut? }"
 			},
@@ -5103,7 +5560,7 @@ const fields = [
 			},
 			{
 				name: "onSelect",
-				type: "(command: Omit<Command, 'action'>) => void",
+				type: "(command: Omit<CommandDef, \"action\">) => void",
 				description: "커맨드 선택 핸들러"
 			},
 			{
@@ -5158,13 +5615,13 @@ const fields = [
 		props: { CommandPaletteTrigger: [
 			{
 				name: "commands",
-				type: "Omit<Command, \"action\">[]",
+				type: "Omit<CommandDef, \"action\">[]",
 				required: true,
 				description: "커맨드 목록"
 			},
 			{
 				name: "onSelect",
-				type: "(command: Omit<Command, 'action'>) => void",
+				type: "(command: Omit<CommandDef, \"action\">) => void",
 				description: "커맨드 선택 핸들러"
 			},
 			{
@@ -5639,7 +6096,7 @@ const data = [
 			},
 			{
 				name: "onFilterChange",
-				type: "(filterId: string, value: string | string[]) => void",
+				type: "(filterId: string, value: string | string[] | boolean) => void",
 				description: "필터 변경 핸들러"
 			},
 			{
@@ -5830,7 +6287,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { email, password, confirmPassword?, rememberMe?, mode }) => void",
+				type: "(values: { email: string; password: string; confirmPassword?: string; rememberMe?: boolean; mode: \"login\" | \"signup\" }) => void",
 				description: "제출 핸들러"
 			},
 			{
@@ -5995,7 +6452,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { title, description, file }) => void",
+				type: "(values: { title: string; description: string; file: File | null }) => void",
 				description: "제출 핸들러"
 			},
 			{
@@ -6592,7 +7049,7 @@ const filters = [
 			},
 			{
 				name: "onSave",
-				type: "(report: { name, description, chartType, dataSourceId }) => void",
+				type: "(report: { name: string; description: string; chartType: ReportBuilderChartType; dataSourceId: string }) => void",
 				description: "저장 콜백"
 			},
 			{
@@ -6790,14 +7247,25 @@ const filters = [
 			},
 			{
 				name: "columns",
-				type: "2 | 3 | 4",
+				type: "2 | 3 | 4 | 5 | 6",
 				default: "4",
 				description: "컬럼 수"
 			},
 			{
 				name: "onStatClick",
 				type: "(stat: StatCardType) => void",
-				description: "카드 클릭 핸들러"
+				description: "카드 클릭 핸들러. 지정 시 카드 자체가 버튼으로 렌더된다"
+			},
+			{
+				name: "selectedStatId",
+				type: "string",
+				description: "선택 가능한 행에서 현재 뷰를 이끄는 카드 id"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "카드 밀도. 표 위 헤더 스트립에는 sm"
 			},
 			{
 				name: "formatValue",
@@ -6833,124 +7301,375 @@ const filters = [
 		testDescribe: "SummaryRow"
 	},
 	{
-		name: "ComparisonSelector",
+		name: "EventTimeline",
 		category: "shell",
-		description: "비교 선택기. 고유 레이블이 연결된 Select × 2 + Swap 버튼 조합. CohortComparison, FunnelAnalysis 등에서 사용합니다.",
-		slug: "comparison-selector",
-		exports: ["ComparisonSelector"],
-		props: { ComparisonSelector: [
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"timeline",
+			"events",
+			"session",
+			"activity",
+			"sequence"
+		],
+		description: "이벤트를 순서로 읽히게 하는 타임라인. 인접 이벤트 사이의 경과 시간을 라벨링하고, 속성 페이로드를 제자리에서 펼치며, 세션 단위 그룹핑을 지원한다.",
+		slug: "event-timeline",
+		exports: ["EventTimeline"],
+		props: { EventTimeline: [
 			{
-				name: "segments",
-				type: "ComparisonOption[]",
-				required: true,
-				description: "선택 가능한 세그먼트 목록"
+				name: "items",
+				type: "EventTimelineItem[]",
+				description: "평면 목록. groups가 있으면 무시된다"
 			},
 			{
-				name: "valueA",
-				type: "string",
-				description: "Base 선택값"
+				name: "groups",
+				type: "EventTimelineGroup[]",
+				description: "그룹(주로 세션) 단위 목록. 접기/펼치기와 그룹 요약을 제공"
 			},
 			{
-				name: "valueB",
-				type: "string",
-				description: "Compare 선택값"
+				name: "showGaps",
+				type: "boolean",
+				default: "true",
+				description: "인접 이벤트 사이 경과 시간 표시. 체크아웃 직전 4분 정지 같은 것이 발견이 된다"
 			},
 			{
-				name: "onChangeA",
-				type: "(value: string) => void",
-				description: "Base 변경 핸들러"
+				name: "order",
+				type: "\"desc\" | \"asc\"",
+				default: "\"desc\"",
+				description: "전달된 items의 정렬 방향. 경과 시간 계산 기준"
 			},
 			{
-				name: "onChangeB",
-				type: "(value: string) => void",
-				description: "Compare 변경 핸들러"
+				name: "minGapMs",
+				type: "number",
+				default: "1000",
+				description: "이 값 미만의 간격은 라벨을 생략"
 			},
 			{
-				name: "labels",
-				type: "ComparisonSelectorLabels",
-				description: "i18n용 라벨 오버라이드"
-			}
-		] },
-		dependencies: [{
-			slug: "select",
-			category: "core"
-		}, {
-			slug: "button",
-			category: "core"
-		}],
-		testDescribe: "ComparisonSelector"
-	},
-	{
-		name: "ThemeSwitcher",
-		category: "shell",
-		description: "테마 프리셋 선택기. 프리셋과 light/dark/system 모드 전환.",
-		slug: "theme-switcher",
-		exports: ["ThemeSwitcher"],
-		props: { ThemeSwitcher: [{
-			name: "labels",
-			type: "ThemeSwitcherLabels",
-			description: "i18n용 라벨 오버라이드"
-		}] },
-		testDescribe: "ThemeSwitcher"
-	},
-	{
-		name: "PromptTemplate",
-		category: "shell",
-		description: "AI 프롬프트 뷰어/헬퍼. 변수 입력 → 실시간 치환 → 복사 기능.",
-		slug: "prompt-template",
-		exports: ["PromptTemplate"],
-		props: { PromptTemplate: [
+				name: "loading",
+				type: "boolean",
+				default: "false",
+				description: "스켈레톤 표시"
+			},
 			{
-				name: "title",
-				type: "string",
-				required: true,
-				description: "프롬프트 제목"
+				name: "hasMore",
+				type: "boolean",
+				default: "false",
+				description: "더 불러올 항목 존재"
 			},
 			{
-				name: "description",
-				type: "string",
-				description: "프롬프트 설명 (헤더 아래 표시)"
+				name: "onLoadMore",
+				type: "() => void",
+				description: "더 보기 핸들러"
 			},
 			{
-				name: "template",
-				type: "string",
-				required: true,
-				description: "프롬프트 템플릿. {변수명}으로 치환 가능"
+				name: "onItemSelect",
+				type: "(item: EventTimelineItem) => void",
+				description: "이벤트 헤드라인 클릭 핸들러"
 			},
 			{
-				name: "variables",
-				type: "PromptVariable[]",
-				description: "변수 정의 배열. { name, label, placeholder?, defaultValue? }"
+				name: "locale",
+				type: "string",
+				description: "경과 시간 포맷 로케일"
 			},
 			{
 				name: "labels",
-				type: "PromptTemplateLabels",
-				description: "i18n용 라벨 오버라이드"
+				type: "EventTimelineLabels",
+				description: "문구 오버라이드"
 			}
 		] },
-		dependencies: [{
-			slug: "input",
-			category: "core"
-		}],
-		testDescribe: "PromptTemplate"
+		usage: {
+			bestPractices: ["사용자 히스토리는 세션으로 그룹핑한다 — 세션 경계가 없으면 히스토리를 읽을 수 없다.", "이벤트 속성은 properties로 넘겨 제자리에서 펼치게 한다."],
+			avoid: ["수천 건을 한 번에 넘기지 않는다. 페이지네이션이나 onLoadMore로 나눈다."]
+		},
+		testDescribe: "EventTimeline"
 	},
 	{
-		name: "Sidebar",
+		name: "ScoreBreakdown",
 		category: "shell",
-		description: "접기/펼치기를 지원하는 compound 사이드바. Header/Content/Footer 구조 + Group/Item으로 네비게이션 구성. Ctrl+[ 단축키.",
-		slug: "sidebar",
-		exports: ["Sidebar", "useSidebar"],
-		keyboardShortcuts: [
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"score",
+			"engagement",
+			"health",
+			"rubric",
+			"breakdown"
+		],
+		description: "합성 점수를 축별로 분해해 보여준다. 총점과 함께 각 축의 값·가중치·의미를 노출해 '43'을 판정이 아니라 발견으로 만든다.",
+		slug: "score-breakdown",
+		exports: ["ScoreBreakdown"],
+		props: { ScoreBreakdown: [
 			{
-				keys: "Ctrl+[",
-				action: "사이드바 접기/펼치기 토글"
+				name: "score",
+				type: "number",
+				required: true,
+				description: "총점"
 			},
 			{
-				keys: "↑ ↓",
-				action: "사이드바 항목 간 이동"
+				name: "max",
+				type: "number",
+				default: "100",
+				description: "총점 상한"
 			},
 			{
-				keys: "Home / End",
+				name: "axes",
+				type: "ScoreAxis[]",
+				required: true,
+				description: "기여 축 배열. { id, label, value, hint?, weight? }"
+			},
+			{
+				name: "bands",
+				type: "ScoreBand[]",
+				description: "점수 구간 이름과 색. { min, label, tone? }"
+			},
+			{
+				name: "formula",
+				type: "ReactNode",
+				description: "총점 산출식 설명 한 줄"
+			},
+			{
+				name: "loading",
+				type: "boolean",
+				default: "false",
+				description: "스켈레톤 표시"
+			},
+			{
+				name: "labels",
+				type: "ScoreBreakdownLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		usage: {
+			bestPractices: ["축의 weight 합이 1이 되도록 넘겨 총점이 검산 가능하게 한다.", "각 축에 hint를 붙여 낮은 값이 무엇을 뜻하는지 설명한다."],
+			avoid: ["축 없이 총점만 넘기지 않는다 — 그건 StatCard의 일이다."]
+		},
+		testDescribe: "ScoreBreakdown"
+	},
+	{
+		name: "Flyout",
+		category: "shell",
+		functionalCategory: "overlay",
+		maturity: "stable",
+		keywords: [
+			"panel",
+			"detail",
+			"preview",
+			"side-panel",
+			"inspector"
+		],
+		description: "목록을 화면에 둔 채 레코드를 옆에서 보여주는 상세 패널. 모달이 아니다 — 포커스 트랩·aria-modal·inert 없이 Escape로 닫고 포커스를 되돌린다.",
+		slug: "flyout",
+		exports: ["Flyout"],
+		props: { Flyout: [
+			{
+				name: "open",
+				type: "boolean",
+				required: true,
+				description: "열림 상태"
+			},
+			{
+				name: "onClose",
+				type: "() => void",
+				required: true,
+				description: "닫기 핸들러"
+			},
+			{
+				name: "title",
+				type: "ReactNode",
+				description: "패널 제목"
+			},
+			{
+				name: "description",
+				type: "ReactNode",
+				description: "제목 아래 한 줄 설명"
+			},
+			{
+				name: "type",
+				type: "\"overlay\" | \"inline\"",
+				default: "\"overlay\"",
+				description: "overlay는 페이지 위에 띄우고, inline은 aside로 렌더해 배치를 부모 레이아웃에 맡긴다"
+			},
+			{
+				name: "side",
+				type: "\"right\" | \"left\"",
+				default: "\"right\"",
+				description: "overlay일 때 붙는 방향"
+			},
+			{
+				name: "size",
+				type: "\"sm\" | \"md\" | \"lg\"",
+				default: "\"md\"",
+				description: "패널 너비"
+			},
+			{
+				name: "actions",
+				type: "ReactNode",
+				description: "닫기 버튼 앞 컨트롤"
+			},
+			{
+				name: "footer",
+				type: "ReactNode",
+				description: "하단 고정 영역"
+			},
+			{
+				name: "scrim",
+				type: "boolean",
+				default: "false",
+				description: "뒤 페이지를 어둡게. 기본 off — 목록이 계속 읽혀야 한다"
+			},
+			{
+				name: "closeOnOutsideClick",
+				type: "boolean",
+				default: "true",
+				description: "바깥 클릭 시 닫기 (overlay 전용)"
+			},
+			{
+				name: "hideCloseButton",
+				type: "boolean",
+				default: "false",
+				description: "닫기 버튼 숨김"
+			},
+			{
+				name: "labels",
+				type: "FlyoutLabels",
+				description: "문구 오버라이드"
+			},
+			{
+				name: "children",
+				type: "ReactNode",
+				required: true,
+				description: "패널 본문"
+			}
+		] },
+		keyboardShortcuts: [{
+			keys: "Escape",
+			action: "패널 닫고 여는 컨트롤로 포커스 복귀"
+		}],
+		usage: {
+			bestPractices: ["목록에서 행을 미리 볼 때 쓴다. 딥링크가 필요한 상세는 별도 페이지를 함께 유지한다.", "넓은 화면에서는 type=\"inline\"으로 목록 옆에 나란히 둔다."],
+			avoid: ["확인이 필요한 파괴적 작업에는 쓰지 않는다 — 그건 Dialog다."]
+		},
+		testDescribe: "Flyout"
+	},
+	{
+		name: "ComparisonSelector",
+		category: "shell",
+		description: "비교 선택기. 고유 레이블이 연결된 Select × 2 + Swap 버튼 조합. CohortComparison, FunnelAnalysis 등에서 사용합니다.",
+		slug: "comparison-selector",
+		exports: ["ComparisonSelector"],
+		props: { ComparisonSelector: [
+			{
+				name: "segments",
+				type: "ComparisonOption[]",
+				required: true,
+				description: "선택 가능한 세그먼트 목록"
+			},
+			{
+				name: "valueA",
+				type: "string",
+				description: "Base 선택값"
+			},
+			{
+				name: "valueB",
+				type: "string",
+				description: "Compare 선택값"
+			},
+			{
+				name: "onChangeA",
+				type: "(value: string) => void",
+				description: "Base 변경 핸들러"
+			},
+			{
+				name: "onChangeB",
+				type: "(value: string) => void",
+				description: "Compare 변경 핸들러"
+			},
+			{
+				name: "labels",
+				type: "ComparisonSelectorLabels",
+				description: "i18n용 라벨 오버라이드"
+			}
+		] },
+		dependencies: [{
+			slug: "select",
+			category: "core"
+		}, {
+			slug: "button",
+			category: "core"
+		}],
+		testDescribe: "ComparisonSelector"
+	},
+	{
+		name: "ThemeSwitcher",
+		category: "shell",
+		description: "테마 프리셋 선택기. 프리셋과 light/dark/system 모드 전환.",
+		slug: "theme-switcher",
+		exports: ["ThemeSwitcher"],
+		props: { ThemeSwitcher: [{
+			name: "labels",
+			type: "ThemeSwitcherLabels",
+			description: "i18n용 라벨 오버라이드"
+		}] },
+		testDescribe: "ThemeSwitcher"
+	},
+	{
+		name: "PromptTemplate",
+		category: "shell",
+		description: "AI 프롬프트 뷰어/헬퍼. 변수 입력 → 실시간 치환 → 복사 기능.",
+		slug: "prompt-template",
+		exports: ["PromptTemplate"],
+		props: { PromptTemplate: [
+			{
+				name: "title",
+				type: "string",
+				required: true,
+				description: "프롬프트 제목"
+			},
+			{
+				name: "description",
+				type: "string",
+				description: "프롬프트 설명 (헤더 아래 표시)"
+			},
+			{
+				name: "template",
+				type: "string",
+				required: true,
+				description: "프롬프트 템플릿. {변수명}으로 치환 가능"
+			},
+			{
+				name: "variables",
+				type: "PromptVariable[]",
+				description: "변수 정의 배열. { name, label, placeholder?, defaultValue? }"
+			},
+			{
+				name: "labels",
+				type: "PromptTemplateLabels",
+				description: "i18n용 라벨 오버라이드"
+			}
+		] },
+		dependencies: [{
+			slug: "input",
+			category: "core"
+		}],
+		testDescribe: "PromptTemplate"
+	},
+	{
+		name: "Sidebar",
+		category: "shell",
+		description: "접기/펼치기를 지원하는 compound 사이드바. Header/Content/Footer 구조 + Group/Item으로 네비게이션 구성. Ctrl+[ 단축키.",
+		slug: "sidebar",
+		exports: ["Sidebar", "useSidebar"],
+		keyboardShortcuts: [
+			{
+				keys: "Ctrl+[",
+				action: "사이드바 접기/펼치기 토글"
+			},
+			{
+				keys: "↑ ↓",
+				action: "사이드바 항목 간 이동"
+			},
+			{
+				keys: "Home / End",
 				action: "첫 번째/마지막 사이드바 항목으로 이동"
 			}
 		],
@@ -7188,7 +7907,7 @@ const filters = [
 		props: { AsyncCombobox: [
 			{
 				name: "onSearch",
-				type: "(q: string) => Promise<string[]>",
+				type: "(query: string) => Promise<string[]>",
 				required: true,
 				description: "검색 콜백"
 			},
@@ -7208,7 +7927,11 @@ const filters = [
 				name: "placeholder",
 				type: "string",
 				default: "\"Search…\"",
-				description: "플레이스홀더"
+				description: "플레이스홀더",
+				deprecated: {
+					since: "1.9.0",
+					replacement: "labels.placeholder"
+				}
 			},
 			{
 				name: "onSelect",
@@ -7223,7 +7946,11 @@ const filters = [
 			{
 				name: "loadingText",
 				type: "string",
-				description: "로딩 문구. labels.loading 사용 권장"
+				description: "로딩 문구",
+				deprecated: {
+					since: "1.9.0",
+					replacement: "labels.loading"
+				}
 			}
 		] },
 		dependencies: [{
@@ -7259,6 +7986,14 @@ const filters = [
 				description: "커스텀 CSS 클래스"
 			}
 		] },
+		ariaRole: "tablist",
+		keyboardShortcuts: [{
+			keys: "↑ ↓",
+			action: "세로 탭 사이 이동 및 선택"
+		}, {
+			keys: "Home / End",
+			action: "첫 번째 또는 마지막 탭으로 이동"
+		}],
 		dependencies: [{
 			slug: "tabs",
 			category: "core"
@@ -7331,12 +8066,30 @@ const filters = [
 				default: "24",
 				description: "들여쓰기 크기 (px)"
 			},
+			{
+				name: "getRowLabel",
+				type: "(node: TreeNode<T>) => string",
+				description: "행별 펼침/접기 컨트롤의 접근 가능한 이름 생성기"
+			},
+			{
+				name: "aria-label",
+				type: "string",
+				description: "표의 접근 가능한 이름"
+			},
 			{
 				name: "className",
 				type: "string",
 				description: "커스텀 CSS 클래스"
 			}
 		] },
+		ariaRole: "table",
+		keyboardShortcuts: [{
+			keys: "Tab",
+			action: "펼침/접기 컨트롤 사이 이동"
+		}, {
+			keys: "Enter / Space",
+			action: "하위 행 펼치기 또는 접기"
+		}],
 		dependencies: [{
 			slug: "data-table",
 			category: "shells"
@@ -7400,7 +8153,7 @@ const filters = [
 			},
 			{
 				name: "onDragEnd",
-				type: "(itemId, fromCol, toCol, toIndex) => void",
+				type: "(itemId: string, fromColumnId: string, toColumnId: string, toIndex: number) => void",
 				required: true,
 				description: "드래그 완료 콜백"
 			},
@@ -7636,7 +8389,7 @@ const filters = [
 			},
 			{
 				name: "onImport",
-				type: "(mapping, data) => void",
+				type: "(mapping: Record<string, string>, data: string[][]) => void",
 				required: true,
 				description: "임포트 확정 콜백"
 			},
@@ -7688,12 +8441,32 @@ const filters = [
 				default: "\"Menu\"",
 				description: "트리거 버튼 텍스트"
 			},
+			{
+				name: "aria-label",
+				type: "string",
+				description: "열린 메가 메뉴 탐색 영역의 접근 가능한 이름"
+			},
 			{
 				name: "className",
 				type: "string",
 				description: "커스텀 CSS 클래스"
 			}
 		] },
+		ariaRole: "navigation",
+		keyboardShortcuts: [
+			{
+				keys: "Enter / Space",
+				action: "메가 메뉴 열기"
+			},
+			{
+				keys: "Tab",
+				action: "메뉴 링크와 액션 사이 이동"
+			},
+			{
+				keys: "Escape",
+				action: "메가 메뉴 닫기"
+			}
+		],
 		dependencies: [{
 			slug: "popover",
 			category: "core"
@@ -8290,6 +9063,16 @@ const messages = [
 		slug: "time-series-panel",
 		exports: ["TimeSeriesPanel"],
 		props: { TimeSeriesPanel: [
+			{
+				name: "title",
+				type: "ReactNode",
+				description: "패널 제목. aria-label이 없으면 region 이름으로 연결됩니다"
+			},
+			{
+				name: "description",
+				type: "ReactNode",
+				description: "패널 보조 설명"
+			},
 			{
 				name: "data",
 				type: "TimeSeriesPoint[]",
@@ -8336,6 +9119,11 @@ const messages = [
 				type: "number",
 				default: "280",
 				description: "차트 높이"
+			},
+			{
+				name: "aria-label",
+				type: "string",
+				description: "제목 대신 사용할 패널 region의 접근 가능한 이름"
 			}
 		] },
 		ariaRole: "region",
@@ -8519,6 +9307,354 @@ const messages = [
 		] },
 		ariaRole: "complementary",
 		testDescribe: "FieldSidebar"
+	},
+	{
+		name: "InspectorLayout",
+		category: "shells",
+		description: "목록과 인스펙터의 2-pane 레이아웃. 넓으면 밀어내고(push) 좁으면 덮으며(overlay), 닫을 때 포커스를 열었던 자리로 되돌립니다.",
+		slug: "inspector-layout",
+		exports: ["InspectorLayout"],
+		props: { InspectorLayout: [
+			{
+				name: "children",
+				type: "ReactNode",
+				required: true,
+				description: "목록. 인스펙터가 열려도 마운트와 스크롤을 유지"
+			},
+			{
+				name: "inspector",
+				type: "ReactNode",
+				description: "인스펙터 내용. 닫혀 있으면 렌더하지 않음"
+			},
+			{
+				name: "open",
+				type: "boolean",
+				required: true,
+				description: "열림"
+			},
+			{
+				name: "onClose",
+				type: "() => void",
+				required: true,
+				description: "닫기"
+			},
+			{
+				name: "title",
+				type: "ReactNode",
+				description: "인스펙터 제목"
+			},
+			{
+				name: "description",
+				type: "ReactNode",
+				description: "제목 아래 한 줄"
+			},
+			{
+				name: "actions",
+				type: "ReactNode",
+				description: "닫기 버튼 옆 컨트롤"
+			},
+			{
+				name: "footer",
+				type: "ReactNode",
+				description: "인스펙터 하단"
+			},
+			{
+				name: "breakpoint",
+				type: "\"lg\" | \"xl\" | \"2xl\"",
+				default: "\"xl\"",
+				description: "이 폭 이상이면 push"
+			},
+			{
+				name: "width",
+				type: "\"sm\" | \"md\" | \"lg\"",
+				default: "\"md\"",
+				description: "push 레이아웃에서의 인스펙터 폭"
+			}
+		] },
+		usage: {
+			bestPractices: ["목록 → 상세 → 목록 왕복이 잦은 화면에 씁니다. 다이얼로그는 목록을 가져가 버립니다."],
+			avoid: ["확인이 필요한 파괴적 작업에는 ConfirmDialog를 씁니다.", "포커스 복귀를 직접 다루지 않습니다. Flyout이 소유하며, 부모가 겹쳐 잡으면 패널을 열었던 요소로 오인합니다."]
+		},
+		testDescribe: "InspectorLayout"
+	},
+	{
+		name: "QueryFilterBar",
+		category: "shells",
+		description: "QueryBar와 필터 버튼이 하나의 Query를 공유합니다. 버튼은 상태를 갖지 않고 Query를 읽어 활성 여부를 계산합니다.",
+		slug: "query-filter-bar",
+		exports: ["QueryFilterBar", "hasActiveQuery"],
+		props: { QueryFilterBar: [
+			{
+				name: "value",
+				type: "Query",
+				required: true,
+				description: "필터 상태 전부"
+			},
+			{
+				name: "onChange",
+				type: "(query: Query) => void",
+				required: true,
+				description: "Query 변경"
+			},
+			{
+				name: "filters",
+				type: "QueryFilterDef[]",
+				required: true,
+				description: "필터 컨트롤 정의 (is / field_value_selection / field_value_toggle)"
+			},
+			{
+				name: "fields",
+				type: "QueryField[]",
+				description: "텍스트 입력 자동완성"
+			},
+			{
+				name: "actions",
+				type: "ReactNode",
+				description: "필터 행 끝 슬롯"
+			},
+			{
+				name: "showClauses",
+				type: "boolean",
+				default: "true",
+				description: "절을 제거 가능한 칩으로 표시"
+			},
+			{
+				name: "live",
+				type: "boolean",
+				default: "false",
+				description: "매 입력마다 커밋"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "전체 비활성"
+			},
+			{
+				name: "queryBarLabels",
+				type: "QueryBarLabels",
+				description: "QueryBar로 통과되는 나머지 문구. placeholder/ariaLabel은 labels가 이깁니다"
+			}
+		] },
+		usage: {
+			bestPractices: ["URL에 Query 한 줄만 실어 필터 상태 전체를 공유 가능하게 만듭니다."],
+			avoid: ["필터 버튼이 자체 상태를 갖게 하지 않습니다. 진실 원천이 둘로 갈라집니다."]
+		},
+		testDescribe: "QueryFilterBar"
+	},
+	{
+		name: "CatalogFrame",
+		category: "shells",
+		description: "카탈로그 목록의 공통 뼈대. 헤더·통계·고지·필터·인스펙터·페이지네이션·일괄 작업과 빈/에러 상태를 담고, 필터나 페이지가 바뀌면 선택을 비웁니다.",
+		slug: "catalog-frame",
+		exports: [
+			"CatalogFrame",
+			"CatalogRowActions",
+			"CatalogCellControls"
+		],
+		props: {
+			CatalogFrame: [
+				{
+					name: "children",
+					type: "ReactNode",
+					required: true,
+					description: "테이블. 빈/에러 상태에서는 대체됨"
+				},
+				{
+					name: "isEmpty",
+					type: "boolean",
+					required: true,
+					description: "테이블이 0행인지"
+				},
+				{
+					name: "query",
+					type: "Query",
+					required: true,
+					description: "필터 상태"
+				},
+				{
+					name: "onQueryChange",
+					type: "(query: Query) => void",
+					required: true,
+					description: "Query 변경"
+				},
+				{
+					name: "filters",
+					type: "QueryFilterDef[]",
+					description: "필터 정의"
+				},
+				{
+					name: "stats",
+					type: "StatCardType[]",
+					description: "통계 카드"
+				},
+				{
+					name: "onStatClick",
+					type: "(stat: StatCardType) => void",
+					description: "카드 클릭 = 필터"
+				},
+				{
+					name: "notice",
+					type: "ReactNode",
+					description: "목록 위 고지"
+				},
+				{
+					name: "emptyActions",
+					type: "ReactNode",
+					description: "필터 없는 빈 상태의 다음 행동 (필터된 빈 상태는 필터 지우기 유지)"
+				},
+				{
+					name: "header",
+					type: "ReactNode",
+					description: "헤더 슬롯"
+				},
+				{
+					name: "actions",
+					type: "ReactNode",
+					description: "액션 슬롯"
+				},
+				{
+					name: "toolbar",
+					type: "ReactNode",
+					description: "통계와 필터 사이 컨트롤 (스코프 세그먼트 등)"
+				},
+				{
+					name: "inspector",
+					type: "ReactNode",
+					description: "인스펙터 내용"
+				},
+				{
+					name: "inspectorOpen",
+					type: "boolean",
+					required: true,
+					description: "인스펙터 열림"
+				},
+				{
+					name: "onInspectorClose",
+					type: "() => void",
+					required: true,
+					description: "인스펙터 닫기"
+				},
+				{
+					name: "inspectorTitle",
+					type: "ReactNode",
+					description: "인스펙터 제목"
+				},
+				{
+					name: "inspectorDescription",
+					type: "ReactNode",
+					description: "인스펙터 설명"
+				},
+				{
+					name: "inspectorActions",
+					type: "ReactNode",
+					description: "인스펙터 헤더 컨트롤"
+				},
+				{
+					name: "inspectorFooter",
+					type: "ReactNode",
+					description: "인스펙터 하단"
+				},
+				{
+					name: "inspectorWidth",
+					type: "\"sm\" | \"md\" | \"lg\"",
+					description: "push 레이아웃 폭"
+				},
+				{
+					name: "page",
+					type: "number",
+					default: "1",
+					description: "현재 페이지"
+				},
+				{
+					name: "pageSize",
+					type: "number",
+					default: "50",
+					description: "페이지 크기"
+				},
+				{
+					name: "totalCount",
+					type: "number",
+					description: "필터 반영 총 개수"
+				},
+				{
+					name: "onPageChange",
+					type: "(page: number) => void",
+					description: "페이지 변경"
+				},
+				{
+					name: "selectedKeys",
+					type: "string[]",
+					description: "선택된 행"
+				},
+				{
+					name: "onSelectionChange",
+					type: "(keys: string[]) => void",
+					description: "선택 변경. 필터·페이지가 바뀌면 프레임이 비웁니다"
+				},
+				{
+					name: "bulkActions",
+					type: "FloatingAction[]",
+					description: "일괄 작업"
+				},
+				{
+					name: "onBulkAction",
+					type: "(actionId: string) => void",
+					description: "일괄 작업 실행"
+				},
+				{
+					name: "error",
+					type: "ReactNode",
+					description: "읽기 실패. 빈 목록과 다른 답"
+				},
+				{
+					name: "onRetry",
+					type: "() => void",
+					description: "재시도"
+				},
+				{
+					name: "labels",
+					type: "CatalogFrameLabels",
+					description: "빈/필터된 빈/에러 문구"
+				}
+			],
+			CatalogRowActions: [
+				{
+					name: "item",
+					type: "T",
+					required: true,
+					description: "이 행의 항목"
+				},
+				{
+					name: "actions",
+					type: "CatalogRowAction<T>[]",
+					required: true,
+					description: "행 액션"
+				},
+				{
+					name: "visibleCount",
+					type: "number",
+					default: "2",
+					description: "오버플로 전에 노출할 개수. available 필터링 후에 적용됨"
+				},
+				{
+					name: "labels",
+					type: "CatalogRowActionsLabels",
+					description: "그룹·오버플로 라벨"
+				}
+			],
+			CatalogCellControls: [{
+				name: "children",
+				type: "ReactNode",
+				required: true,
+				description: "행 클릭으로 새면 안 되는 셀 컨트롤"
+			}]
+		},
+		usage: {
+			bestPractices: ["카탈로그 성격의 목록 화면은 이 프레임 위에 컬럼 정의와 labels만 얹습니다."],
+			avoid: ["선택 초기화를 호출자에게 맡기지 않습니다 — 보이지 않는 행에 일괄 작업이 적용됩니다."]
+		},
+		testDescribe: "CatalogFrame"
 	}
 ];
 //#endregion