@reopt-ai/opt-ui 1.11.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: "시각적 제목 역할"
 			},
 			{
@@ -2726,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",
@@ -3403,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",
@@ -3540,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",
@@ -3614,7 +3641,7 @@ const store = useFormStore({ defaultValues: { name: "" } });
 			},
 			{
 				name: "onComparisonChange",
-				type: "(comparison: boolean, mode: ComparisonMode) => void",
+				type: "(mode: ComparisonMode | null) => void",
 				description: "비교 모드 변경 콜백"
 			},
 			{
@@ -4302,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",
@@ -4949,6 +4981,189 @@ const MyDashboard = createBlock<MyDashboardProps>(
 			}
 		] },
 		testDescribe: "ShaderSurface"
+	},
+	{
+		name: "Callout",
+		category: "core",
+		description: "페이지에 머무는 인페이지 고지. Alert와 달리 dismiss가 없고, 조건이 참인 동안 레이아웃의 일부로 남습니다.",
+		slug: "callout",
+		exports: ["Callout"],
+		props: { Callout: [
+			{
+				name: "tone",
+				type: "\"info\" | \"success\" | \"warning\" | \"danger\" | \"neutral\"",
+				default: "\"info\"",
+				description: "고지의 성격"
+			},
+			{
+				name: "title",
+				type: "ReactNode",
+				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",
+				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: "size",
+				type: "\"sm\" | \"md\"",
+				default: "\"md\"",
+				description: "점과 글자 크기"
+			},
+			{
+				name: "children",
+				type: "ReactNode",
+				required: true,
+				description: "상태 라벨. 필수 — 색은 상태가 아닙니다"
+			},
+			{
+				name: "hint",
+				type: "string",
+				description: "판정 기준 툴팁"
+			}
+		] },
+		usage: {
+			bestPractices: ["표의 상태 컬럼처럼 행마다 반복되는 자리에 씁니다. 점은 장식이고 의미는 텍스트가 담습니다."],
+			avoid: ["사람이 붙인 라벨(태그, 카테고리)에는 Badge를 씁니다. StatusDot은 관측된 상태용입니다."]
+		},
+		testDescribe: "StatusDot"
+	},
+	{
+		name: "CopyButton",
+		category: "core",
+		description: "값을 클립보드에 올리고 성공 여부를 알립니다. 클립보드 거부를 삼키지 않습니다.",
+		slug: "copy-button",
+		exports: ["CopyButton"],
+		props: { CopyButton: [
+			{
+				name: "value",
+				type: "string",
+				required: true,
+				description: "복사할 텍스트"
+			},
+			{
+				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: "CopyButton"
+	},
+	{
+		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
@@ -4968,6 +5183,14 @@ const shellMetas = [
 			required: true,
 			description: "FAQ 항목 배열. { id, question, answer }"
 		}] },
+		ariaRole: "region",
+		keyboardShortcuts: [{
+			keys: "↑ ↓",
+			action: "질문 사이 포커스 이동"
+		}, {
+			keys: "Enter / Space",
+			action: "답변 펼치기 또는 접기"
+		}],
 		dependencies: [{
 			slug: "disclosure",
 			category: "core"
@@ -5289,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"
 	},
 	{
@@ -5300,7 +5542,7 @@ const fields = [
 		props: { CommandPalette: [
 			{
 				name: "commands",
-				type: "Omit<Command, \"action\">[]",
+				type: "Omit<CommandDef, \"action\">[]",
 				required: true,
 				description: "커맨드 목록. { id, label, group, shortcut? }"
 			},
@@ -5318,7 +5560,7 @@ const fields = [
 			},
 			{
 				name: "onSelect",
-				type: "(command: Omit<Command, 'action'>) => void",
+				type: "(command: Omit<CommandDef, \"action\">) => void",
 				description: "커맨드 선택 핸들러"
 			},
 			{
@@ -5373,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: "커맨드 선택 핸들러"
 			},
 			{
@@ -5854,7 +6096,7 @@ const data = [
 			},
 			{
 				name: "onFilterChange",
-				type: "(filterId: string, value: string | string[]) => void",
+				type: "(filterId: string, value: string | string[] | boolean) => void",
 				description: "필터 변경 핸들러"
 			},
 			{
@@ -6045,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: "제출 핸들러"
 			},
 			{
@@ -6210,7 +6452,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { title, description, file }) => void",
+				type: "(values: { title: string; description: string; file: File | null }) => void",
 				description: "제출 핸들러"
 			},
 			{
@@ -6807,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: "저장 콜백"
 			},
 			{
@@ -7665,7 +7907,7 @@ const filters = [
 		props: { AsyncCombobox: [
 			{
 				name: "onSearch",
-				type: "(q: string) => Promise<string[]>",
+				type: "(query: string) => Promise<string[]>",
 				required: true,
 				description: "검색 콜백"
 			},
@@ -7685,7 +7927,11 @@ const filters = [
 				name: "placeholder",
 				type: "string",
 				default: "\"Search…\"",
-				description: "플레이스홀더"
+				description: "플레이스홀더",
+				deprecated: {
+					since: "1.9.0",
+					replacement: "labels.placeholder"
+				}
 			},
 			{
 				name: "onSelect",
@@ -7700,7 +7946,11 @@ const filters = [
 			{
 				name: "loadingText",
 				type: "string",
-				description: "로딩 문구. labels.loading 사용 권장"
+				description: "로딩 문구",
+				deprecated: {
+					since: "1.9.0",
+					replacement: "labels.loading"
+				}
 			}
 		] },
 		dependencies: [{
@@ -7736,6 +7986,14 @@ const filters = [
 				description: "커스텀 CSS 클래스"
 			}
 		] },
+		ariaRole: "tablist",
+		keyboardShortcuts: [{
+			keys: "↑ ↓",
+			action: "세로 탭 사이 이동 및 선택"
+		}, {
+			keys: "Home / End",
+			action: "첫 번째 또는 마지막 탭으로 이동"
+		}],
 		dependencies: [{
 			slug: "tabs",
 			category: "core"
@@ -7808,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"
@@ -7877,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: "드래그 완료 콜백"
 			},
@@ -8113,7 +8389,7 @@ const filters = [
 			},
 			{
 				name: "onImport",
-				type: "(mapping, data) => void",
+				type: "(mapping: Record<string, string>, data: string[][]) => void",
 				required: true,
 				description: "임포트 확정 콜백"
 			},
@@ -8165,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"
@@ -8767,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[]",
@@ -8813,6 +9119,11 @@ const messages = [
 				type: "number",
 				default: "280",
 				description: "차트 높이"
+			},
+			{
+				name: "aria-label",
+				type: "string",
+				description: "제목 대신 사용할 패널 region의 접근 가능한 이름"
 			}
 		] },
 		ariaRole: "region",
@@ -8996,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