@reopt-ai/opt-ui 1.10.0 → 1.11.0

package/dist/meta.cjs

@@ -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",
@@ -3103,12 +3150,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",
@@ -6790,14 +7005,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",
@@ -6832,6 +7058,257 @@ const filters = [
 		}],
 		testDescribe: "SummaryRow"
 	},
+	{
+		name: "EventTimeline",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"timeline",
+			"events",
+			"session",
+			"activity",
+			"sequence"
+		],
+		description: "이벤트를 순서로 읽히게 하는 타임라인. 인접 이벤트 사이의 경과 시간을 라벨링하고, 속성 페이로드를 제자리에서 펼치며, 세션 단위 그룹핑을 지원한다.",
+		slug: "event-timeline",
+		exports: ["EventTimeline"],
+		props: { EventTimeline: [
+			{
+				name: "items",
+				type: "EventTimelineItem[]",
+				description: "평면 목록. groups가 있으면 무시된다"
+			},
+			{
+				name: "groups",
+				type: "EventTimelineGroup[]",
+				description: "그룹(주로 세션) 단위 목록. 접기/펼치기와 그룹 요약을 제공"
+			},
+			{
+				name: "showGaps",
+				type: "boolean",
+				default: "true",
+				description: "인접 이벤트 사이 경과 시간 표시. 체크아웃 직전 4분 정지 같은 것이 발견이 된다"
+			},
+			{
+				name: "order",
+				type: "\"desc\" | \"asc\"",
+				default: "\"desc\"",
+				description: "전달된 items의 정렬 방향. 경과 시간 계산 기준"
+			},
+			{
+				name: "minGapMs",
+				type: "number",
+				default: "1000",
+				description: "이 값 미만의 간격은 라벨을 생략"
+			},
+			{
+				name: "loading",
+				type: "boolean",
+				default: "false",
+				description: "스켈레톤 표시"
+			},
+			{
+				name: "hasMore",
+				type: "boolean",
+				default: "false",
+				description: "더 불러올 항목 존재"
+			},
+			{
+				name: "onLoadMore",
+				type: "() => void",
+				description: "더 보기 핸들러"
+			},
+			{
+				name: "onItemSelect",
+				type: "(item: EventTimelineItem) => void",
+				description: "이벤트 헤드라인 클릭 핸들러"
+			},
+			{
+				name: "locale",
+				type: "string",
+				description: "경과 시간 포맷 로케일"
+			},
+			{
+				name: "labels",
+				type: "EventTimelineLabels",
+				description: "문구 오버라이드"
+			}
+		] },
+		usage: {
+			bestPractices: ["사용자 히스토리는 세션으로 그룹핑한다 — 세션 경계가 없으면 히스토리를 읽을 수 없다.", "이벤트 속성은 properties로 넘겨 제자리에서 펼치게 한다."],
+			avoid: ["수천 건을 한 번에 넘기지 않는다. 페이지네이션이나 onLoadMore로 나눈다."]
+		},
+		testDescribe: "EventTimeline"
+	},
+	{
+		name: "ScoreBreakdown",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "stable",
+		keywords: [
+			"score",
+			"engagement",
+			"health",
+			"rubric",
+			"breakdown"
+		],
+		description: "합성 점수를 축별로 분해해 보여준다. 총점과 함께 각 축의 값·가중치·의미를 노출해 '43'을 판정이 아니라 발견으로 만든다.",
+		slug: "score-breakdown",
+		exports: ["ScoreBreakdown"],
+		props: { ScoreBreakdown: [
+			{
+				name: "score",
+				type: "number",
+				required: true,
+				description: "총점"
+			},
+			{
+				name: "max",
+				type: "number",
+				default: "100",
+				description: "총점 상한"
+			},
+			{
+				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",

package/dist/meta.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.cts","names":[],"sources":["../src/core/_meta.ts","../src/visuals/_meta.ts","../src/shells/_meta.ts"],"mappings":";;cA65Ia,WAAS;;;;cC15IT,aAAa;;;cC6gHb,YAAU"}
+{"version":3,"file":"meta.d.cts","names":[],"sources":["../src/core/_meta.ts","../src/visuals/_meta.ts","../src/shells/_meta.ts"],"mappings":";;cAsnJa,WAAS;;;;cCnnJT,aAAa;;;cCmtHb,YAAU"}

package/dist/meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","names":[],"sources":["../src/core/_meta.ts","../src/visuals/_meta.ts","../src/shells/_meta.ts"],"mappings":";;cA65Ia,WAAS;;;;cC15IT,aAAa;;;cC6gHb,YAAU"}
+{"version":3,"file":"meta.d.ts","names":[],"sources":["../src/core/_meta.ts","../src/visuals/_meta.ts","../src/shells/_meta.ts"],"mappings":";;cAsnJa,WAAS;;;;cCnnJT,aAAa;;;cCmtHb,YAAU"}