@reopt-ai/opt-ui 1.14.0 → 1.15.0

package/dist/meta.js

@@ -531,7 +531,7 @@ const coreMetas = [
 				name: "onSave",
 				type: "(next: string) => boolean | void | Promise<boolean | void>",
 				required: true,
-				description: "저장. false를 반환하면 거절하고 편집을 유지"
+				description: "저장. false 반환 또는 Promise 실패 시 입력을 유지하고 오류를 알림"
 			},
 			{
 				name: "as",
@@ -575,7 +575,7 @@ const coreMetas = [
 			{
 				name: "labels",
 				type: "InlineEditLabels",
-				description: "지역화 문자열"
+				description: "입력 이름(input), 편집·저장·취소·오류 안내 문자열"
 			},
 			{
 				name: "className",
@@ -2211,6 +2211,21 @@ export function Example() {
 				}
 			],
 			FormSelect: [
+				{
+					name: "id",
+					type: "string",
+					description: "트리거 ID. 외부 FormLabel의 htmlFor와 연결"
+				},
+				{
+					name: "aria-label",
+					type: "string",
+					description: "입력의 접근 가능한 이름"
+				},
+				{
+					name: "aria-describedby",
+					type: "string",
+					description: "설명·오류 요소의 ID 목록"
+				},
 				{
 					name: "name",
 					type: "string",
@@ -4302,6 +4317,11 @@ export function Example() { return <PopoverRoot><PopoverTrigger>공유 안내</P
 				type: "(value: number) => void",
 				description: "값 변경 핸들러"
 			},
+			{
+				name: "onValueCommit",
+				type: "(value: number) => void",
+				description: "포인터·키보드 편집 완료 시 한 번 호출. 취소와 외부 값 갱신은 제외"
+			},
 			{
 				name: "min",
 				type: "number",
@@ -5664,7 +5684,7 @@ const shellMetas = [
 			description: "폼 필드 정의 배열"
 		}, {
 			name: "onSubmit",
-			type: "(values: Record<string, unknown>) => void",
+			type: "(values: Record<string, unknown>) => void | Promise<void>",
 			description: "제출 핸들러"
 		}] },
 		dependencies: [
@@ -6535,7 +6555,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { email: string; password: string; confirmPassword?: string; rememberMe?: boolean; mode: \"login\" | \"signup\" }) => void",
+				type: "(values: { email: string; password: string; confirmPassword?: string; rememberMe?: boolean; mode: \"login\" | \"signup\" }) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -6578,7 +6598,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: Record<string, unknown>) => void",
+				type: "(values: Record<string, unknown>) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -6646,7 +6666,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: string[]) => void",
+				type: "(values: string[]) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -6700,7 +6720,7 @@ const filters = [
 			},
 			{
 				name: "onSubmit",
-				type: "(values: { title: string; description: string; file: File | null }) => void",
+				type: "(values: { title: string; description: string; file: File | null }) => void | Promise<void>",
 				description: "제출 핸들러"
 			},
 			{
@@ -11180,6 +11200,426 @@ const messages = [
 			category: "core"
 		}],
 		testDescribe: "QueryWorkspace"
+	},
+	{
+		name: "ReplayScrubber",
+		category: "shell",
+		functionalCategory: "data-display",
+		maturity: "beta",
+		keywords: [
+			"replay",
+			"scrubber",
+			"seekbar",
+			"timeline",
+			"session recording",
+			"playhead"
+		],
+		description: "세션 리플레이의 탐색 트랙. 활동/비활성/미로딩 구간, 활동 밀도, 이벤트 마커를 한 플레이헤드 아래에 겹쳐 그리고, 드래그·키보드 탐색이 끝났을 때만 seek을 커밋한다.",
+		slug: "replay-scrubber",
+		exports: ["ReplayScrubber", "groupReplayMarkers"],
+		props: { ReplayScrubber: [
+			{
+				name: "start",
+				type: "number",
+				required: true,
+				description: "재생 가능한 첫 시각(절대값, 보통 epoch ms)"
+			},
+			{
+				name: "end",
+				type: "number",
+				required: true,
+				description: "재생 가능한 마지막 시각"
+			},
+			{
+				name: "position",
+				type: "number",
+				required: true,
+				description: "현재 플레이헤드. [start, end]로 클램프"
+			},
+			{
+				name: "segments",
+				type: "ReplayScrubberSegment[]",
+				description: "활동 분류 구간. active/inactive/gap/buffer"
+			},
+			{
+				name: "buffered",
+				type: "Array<{ start: number; end: number }>",
+				description: "이미 로드된 범위"
+			},
+			{
+				name: "activity",
+				type: "number[]",
+				description: "0..1로 정규화한 활동 밀도 버킷. 로그 스케일 영역으로 그린다"
+			},
+			{
+				name: "markers",
+				type: "ReplayScrubberMarker[]",
+				description: "트랙 위 관심 지점. 가까운 마커는 하나로 합쳐진다"
+			},
+			{
+				name: "onSeek",
+				type: "(time: number) => void",
+				required: true,
+				description: "포인터·키보드 조작이 끝났을 때 한 번 호출"
+			},
+			{
+				name: "onPreview",
+				type: "(time: number | null) => void",
+				description: "드래그·호버 중 미리보기 시각. 비싼 seek에 쓰지 않는다"
+			},
+			{
+				name: "onMarkerSelect",
+				type: "(marker: ReplayScrubberMarker) => void",
+				description: "마커 선택. 생략하면 해당 시각으로 seek"
+			},
+			{
+				name: "formatTime",
+				type: "(time: number) => string",
+				description: "배지와 aria-valuetext 포맷. 기본 start 기준 m:ss"
+			},
+			{
+				name: "stepMs",
+				type: "number",
+				default: "5000",
+				description: "화살표 키 이동량"
+			},
+			{
+				name: "largeStepMs",
+				type: "number",
+				default: "30000",
+				description: "PageUp/PageDown·Shift+화살표 이동량"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "모든 조작을 비활성화"
+			},
+			{
+				name: "labels",
+				type: "ReplayScrubberLabels",
+				description: "접근성 문구 오버라이드"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "추가 클래스"
+			}
+		] },
+		usage: {
+			bestPractices: ["onSeek에만 실제 seek을 연결한다. onPreview는 시각 표시용이다.", "segments의 buffer는 '아직 안 옴'이고 gap은 '없음'이다. 플레이어가 기다릴지 건너뛸지가 갈린다."],
+			avoid: ["마커를 수천 개 넘기지 않는다. 우선순위로 100개 안팎으로 추려서 넘긴다."]
+		},
+		testDescribe: "ReplayScrubber",
+		examples: [{
+			title: "구간·마커가 있는 탐색 트랙",
+			code: `import { ReplayScrubber } from "@reopt-ai/opt-ui";
+
+<ReplayScrubber
+  start={recording.start}
+  end={recording.end}
+  position={playhead}
+  segments={[
+    { start: recording.start, end: recording.start + 60_000, kind: "active" },
+    { start: recording.start + 60_000, end: recording.end, kind: "inactive" },
+  ]}
+  markers={[{ id: "err", time: errorAt, label: "TypeError", tone: "danger" }]}
+  onSeek={(time) => player.seek(time)}
+  labels={{ track: "녹화 탐색" }}
+/>`
+		}]
+	},
+	{
+		name: "ReplayTransport",
+		category: "shell",
+		functionalCategory: "actions",
+		maturity: "beta",
+		keywords: [
+			"replay",
+			"transport",
+			"play",
+			"pause",
+			"speed",
+			"skip inactivity",
+			"session recording"
+		],
+		description: "세션 리플레이 재생 컨트롤. 재생/일시정지, 앞뒤 점프, 배속 메뉴, 비활성 건너뛰기 토글, 전체화면, 경과/시계 타임코드 전환을 제공하며 재생 상태는 호스트가 소유한다.",
+		slug: "replay-transport",
+		exports: ["ReplayTransport", "formatReplayElapsed"],
+		props: { ReplayTransport: [
+			{
+				name: "playing",
+				type: "boolean",
+				required: true,
+				description: "재생 중 여부"
+			},
+			{
+				name: "ended",
+				type: "boolean",
+				default: "false",
+				description: "끝에 도달. 재생 버튼이 다시 시작을 제안"
+			},
+			{
+				name: "position",
+				type: "number",
+				required: true,
+				description: "절대 플레이헤드 시각"
+			},
+			{
+				name: "start",
+				type: "number",
+				required: true,
+				description: "녹화 시작 시각(절대값)"
+			},
+			{
+				name: "end",
+				type: "number",
+				required: true,
+				description: "녹화 종료 시각(절대값)"
+			},
+			{
+				name: "onTogglePlay",
+				type: "() => void",
+				required: true,
+				description: "재생/일시정지 토글. ended면 처음부터 다시 시작"
+			},
+			{
+				name: "onSkip",
+				type: "(deltaMs: number) => void",
+				required: true,
+				description: "부호 있는 시간만큼 이동"
+			},
+			{
+				name: "onSkipToStart",
+				type: "() => void",
+				description: "처음으로. 생략하면 버튼 숨김"
+			},
+			{
+				name: "jumpMs",
+				type: "number",
+				default: "10000",
+				description: "앞뒤 점프 버튼 이동량(ms)"
+			},
+			{
+				name: "speed",
+				type: "number",
+				required: true,
+				description: "현재 배속"
+			},
+			{
+				name: "speeds",
+				type: "readonly number[]",
+				default: "[0.5, 1, 1.5, 2, 3, 4, 8, 16]",
+				description: "선택 가능한 배속 목록"
+			},
+			{
+				name: "onSpeedChange",
+				type: "(speed: number) => void",
+				required: true,
+				description: "배속 변경 콜백"
+			},
+			{
+				name: "skipInactive",
+				type: "boolean",
+				required: true,
+				description: "비활성 구간 건너뛰기 여부"
+			},
+			{
+				name: "onSkipInactiveChange",
+				type: "(skip: boolean) => void",
+				required: true,
+				description: "건너뛰기 토글 콜백"
+			},
+			{
+				name: "fullscreen",
+				type: "boolean",
+				description: "전체화면 상태(호스트 소유)"
+			},
+			{
+				name: "onFullscreenChange",
+				type: "(fullscreen: boolean) => void",
+				description: "있으면 전체화면 버튼 표시"
+			},
+			{
+				name: "timecode",
+				type: "\"elapsed\" | \"clock\"",
+				default: "\"elapsed\"",
+				description: "경과 시간 또는 실제 시각 표시 모드"
+			},
+			{
+				name: "onTimecodeChange",
+				type: "(mode: \"elapsed\" | \"clock\") => void",
+				description: "있으면 타임코드를 클릭해 전환"
+			},
+			{
+				name: "formatClock",
+				type: "(time: number) => string",
+				description: "clock 모드 포맷"
+			},
+			{
+				name: "disabled",
+				type: "boolean",
+				default: "false",
+				description: "모든 조작을 비활성화"
+			},
+			{
+				name: "children",
+				type: "ReactNode",
+				description: "오른쪽에 추가 컨트롤"
+			},
+			{
+				name: "labels",
+				type: "ReplayTransportLabels",
+				description: "문구 오버라이드"
+			},
+			{
+				name: "shortcuts",
+				type: "ReplayTransportShortcuts",
+				description: "툴팁에 표시할 단축키"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "추가 클래스"
+			}
+		] },
+		usage: {
+			bestPractices: ["단축키는 ReplayPlayerLayout의 shortcuts로 묶고, 여기엔 표시용 문자열만 넘긴다.", "clock 타임코드는 로그와 대조할 때 필요하다. 세션의 실제 시각을 넘긴다."],
+			avoid: ["재생 상태를 컴포넌트 안에 두지 않는다. 플레이어 엔진이 단일 소스다."]
+		},
+		testDescribe: "ReplayTransport",
+		examples: [{
+			title: "호스트가 재생 상태를 소유하는 트랜스포트",
+			code: `import { ReplayTransport } from "@reopt-ai/opt-ui";
+
+<ReplayTransport
+  playing={playing}
+  position={playhead}
+  start={recording.start}
+  end={recording.end}
+  onTogglePlay={() => (playing ? player.pause() : player.play())}
+  onSkip={(delta) => player.seek(playhead + delta)}
+  speed={speed}
+  onSpeedChange={setSpeed}
+  skipInactive={skipInactive}
+  onSkipInactiveChange={setSkipInactive}
+  labels={{ play: "재생", pause: "일시정지" }}
+/>`
+		}]
+	},
+	{
+		name: "ReplayPlayerLayout",
+		category: "shell",
+		functionalCategory: "layout",
+		maturity: "beta",
+		keywords: [
+			"replay",
+			"player",
+			"layout",
+			"inspector",
+			"fullscreen",
+			"shortcuts",
+			"session recording"
+		],
+		description: "세션 리플레이 플레이어의 프레임. 스테이지·메타 바·컨트롤·리사이즈 가능한 인스펙터를 배치하고, 플레이어 전체의 전체화면과 입력 필드를 피하는 키보드 단축키 범위를 소유한다.",
+		slug: "replay-player-layout",
+		exports: ["ReplayPlayerLayout", "replayShortcutKey"],
+		props: { ReplayPlayerLayout: [
+			{
+				name: "stage",
+				type: "ReactNode",
+				required: true,
+				description: "녹화가 렌더되는 영역(iframe 호스트)"
+			},
+			{
+				name: "meta",
+				type: "ReactNode",
+				description: "스테이지 위 얇은 바: URL, 창, 기기"
+			},
+			{
+				name: "controls",
+				type: "ReactNode",
+				description: "스테이지 아래 트랜스포트와 스크러버"
+			},
+			{
+				name: "inspector",
+				type: "ReactNode",
+				description: "측면 패널. 생략하면 패널 없음"
+			},
+			{
+				name: "inspectorOpen",
+				type: "boolean",
+				default: "true",
+				description: "인스펙터 표시 여부(제어됨)"
+			},
+			{
+				name: "onInspectorOpenChange",
+				type: "(open: boolean) => void",
+				description: "있으면 토글 버튼 표시"
+			},
+			{
+				name: "inspectorSize",
+				type: "number",
+				default: "34",
+				description: "인스펙터 초기 폭(%)"
+			},
+			{
+				name: "layoutId",
+				type: "string",
+				description: "리사이즈 레이아웃 영속 id"
+			},
+			{
+				name: "fullscreen",
+				type: "boolean",
+				default: "false",
+				description: "전체화면 상태(호스트 소유)"
+			},
+			{
+				name: "onFullscreenChange",
+				type: "(fullscreen: boolean) => void",
+				description: "전체화면 변경 콜백. 브라우저가 스스로 나가도 호출된다"
+			},
+			{
+				name: "shortcuts",
+				type: "ReplayShortcutMap",
+				description: "포커스가 안에 있고 입력 필드가 아닐 때만 동작. false를 반환하면 전파"
+			},
+			{
+				name: "overlay",
+				type: "ReactNode",
+				description: "스테이지 위 오버레이: 로딩, 오류, 건너뛰는 중"
+			},
+			{
+				name: "labels",
+				type: "ReplayPlayerLayoutLabels",
+				description: "문구 오버라이드"
+			},
+			{
+				name: "className",
+				type: "string",
+				description: "추가 클래스"
+			}
+		] },
+		usage: {
+			bestPractices: ["단축키 키 이름은 replayShortcutKey가 만든다: space, arrowleft, shift+arrowright, mod+arrowleft, f.", "전체화면 상태는 호스트가 들고, 브라우저가 스스로 나가면 onFullscreenChange(false)로 통지된다."],
+			avoid: ["스테이지 iframe에 직접 requestFullscreen하지 않는다. 컨트롤이 함께 보여야 한다."]
+		},
+		testDescribe: "ReplayPlayerLayout",
+		examples: [{
+			title: "스테이지·컨트롤·인스펙터 배치와 단축키",
+			code: `import { ReplayPlayerLayout } from "@reopt-ai/opt-ui";
+
+<ReplayPlayerLayout
+  layoutId="replay-player"
+  meta={<span>{currentPath}</span>}
+  stage={<div ref={stageRef} />}
+  controls={<>{scrubber}{transport}</>}
+  inspector={<EventList onSelect={(e) => player.seek(e.time)} />}
+  inspectorOpen={inspectorOpen}
+  onInspectorOpenChange={setInspectorOpen}
+  shortcuts={{ space: togglePlay, arrowleft: () => skip(-10_000), arrowright: () => skip(10_000) }}
+/>`
+		}]
 	}
 ];
 //#endregion