@reopt-ai/opt-ui 1.8.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/COMPONENT_CATALOG.md +222 -34
  2. package/README.md +70 -6
  3. package/dist/core/index.cjs +170 -155
  4. package/dist/core/index.d.cts +3 -2
  5. package/dist/core/index.d.ts +3 -2
  6. package/dist/core/index.js +3 -3
  7. package/dist/docs/02-components/01-core.md +223 -18
  8. package/dist/docs/02-components/02-visuals.md +1 -1
  9. package/dist/docs/02-components/03-shells.md +17 -16
  10. package/dist/docs/02-components/04-surfaces.md +1 -1
  11. package/dist/docs/02-components/index.md +4 -4
  12. package/dist/{field-sidebar-Bqfp6dgg.cjs → field-sidebar-B6Ndr8HE.cjs} +304 -289
  13. package/dist/{field-sidebar-BYD_UIjG.js → field-sidebar-BXjvV7Cz.js} +25 -10
  14. package/dist/{field-sidebar-BYD_UIjG.js.map → field-sidebar-BXjvV7Cz.js.map} +1 -1
  15. package/dist/{field-sidebar-5KYVlpSs.d.ts → field-sidebar-DWfJAJlx.d.ts} +32 -3
  16. package/dist/{field-sidebar-5KYVlpSs.d.ts.map → field-sidebar-DWfJAJlx.d.ts.map} +1 -1
  17. package/dist/{field-sidebar-BP0iWkoV.d.cts → field-sidebar-nwcE9LC4.d.cts} +32 -3
  18. package/dist/{field-sidebar-BP0iWkoV.d.cts.map → field-sidebar-nwcE9LC4.d.cts.map} +1 -1
  19. package/dist/id-registry.cjs +98 -2
  20. package/dist/id-registry.d.cts.map +1 -1
  21. package/dist/id-registry.d.ts.map +1 -1
  22. package/dist/id-registry.js +98 -2
  23. package/dist/id-registry.js.map +1 -1
  24. package/dist/id-registry.json +202 -4
  25. package/dist/index.cjs +664 -643
  26. package/dist/index.d.cts +5 -4
  27. package/dist/index.d.cts.map +1 -1
  28. package/dist/index.d.ts +5 -4
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +10 -4
  31. package/dist/index.js.map +1 -1
  32. package/dist/{shader-surface-BUPZ0P-n.js → key-pad-menu-BQunU20e.js} +727 -19
  33. package/dist/key-pad-menu-BQunU20e.js.map +1 -0
  34. package/dist/{shader-surface-BfTP9c1Q.d.ts → key-pad-menu-BsgJMjD4.d.ts} +415 -3
  35. package/dist/key-pad-menu-BsgJMjD4.d.ts.map +1 -0
  36. package/dist/{shader-surface-Fav5K9UC.cjs → key-pad-menu-D5mQcS5v.cjs} +969 -201
  37. package/dist/{shader-surface-DRrcLrWf.d.cts → key-pad-menu-DfZbeXhG.d.cts} +415 -3
  38. package/dist/key-pad-menu-DfZbeXhG.d.cts.map +1 -0
  39. package/dist/meta.cjs +641 -0
  40. package/dist/meta.d.cts.map +1 -1
  41. package/dist/meta.d.ts.map +1 -1
  42. package/dist/meta.js +641 -0
  43. package/dist/meta.js.map +1 -1
  44. package/dist/shells/index.cjs +1 -1
  45. package/dist/shells/index.d.cts +1 -1
  46. package/dist/shells/index.d.ts +1 -1
  47. package/dist/shells/index.js +1 -1
  48. package/dist/{types-D0FlcYnM.d.ts → text-truncate-BGr7bB_8.d.cts} +110 -2
  49. package/dist/text-truncate-BGr7bB_8.d.cts.map +1 -0
  50. package/dist/{types-D0FlcYnM.d.cts → text-truncate-BGr7bB_8.d.ts} +110 -2
  51. package/dist/text-truncate-BGr7bB_8.d.ts.map +1 -0
  52. package/dist/{pagination-DjfxBcjX.cjs → text-truncate-CxdzAnhS.cjs} +418 -8
  53. package/dist/{pagination-DWbvACuN.js → text-truncate-j6X3z7Pv.js} +392 -12
  54. package/dist/text-truncate-j6X3z7Pv.js.map +1 -0
  55. package/package.json +3 -3
  56. package/dist/pagination-DWbvACuN.js.map +0 -1
  57. package/dist/shader-surface-BUPZ0P-n.js.map +0 -1
  58. package/dist/shader-surface-BfTP9c1Q.d.ts.map +0 -1
  59. package/dist/shader-surface-DRrcLrWf.d.cts.map +0 -1
  60. package/dist/types-D0FlcYnM.d.cts.map +0 -1
  61. package/dist/types-D0FlcYnM.d.ts.map +0 -1
package/COMPONENT_CATALOG.md CHANGED
@@ -2,17 +2,17 @@
2
2
 
3
3
  <!-- DEPRECATED: Prefer dist/docs/02-components/ for per-layer reference. -->
4
4
  <!-- Auto-generated from ComponentMeta. Do not edit. -->
5
- <!-- Version: 1.7.0 -->
5
+ <!-- Version: 1.9.0 -->
6
6
 
7
7
  ## Quick Stats
8
8
 
9
9
  | Layer | Count |
10
10
  | --------- | ------- |
11
- | Core | 59 |
11
+ | Core | 68 |
12
12
  | Visuals | 0 |
13
13
  | Shells | 80 |
14
14
  | Surfaces | 0 |
15
- | **Total** | **139** |
15
+ | **Total** | **148** |
16
16
 
17
17
  ## Component Selection Guide
18
18
 
@@ -95,7 +95,7 @@
95
95
  | 인사이트/이상탐지 | InsightsPanel | Shell |
96
96
  | 프롬프트 템플릿 | PromptTemplate | Shell |
97
97
 
98
- ## Core Components (59)
98
+ ## Core Components (68)
99
99
 
100
100
  ### Input
101
101
 
@@ -175,21 +175,30 @@
175
175
 
176
176
  ### Other
177
177
 
178
- | Component | Description | Key Exports |
179
- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
180
- | Text | 본문, 레이블, 보조 설명, 코드에 일관된 의미 기반 타이포그래피를 적용합니다. | `Text` |
181
- | Heading | 문서의 의미 계층과 시각적 타이포그래피 계층을 독립적으로 제어합니다. | `Heading` |
182
- | Separator | 콘텐츠를 구분하는 가로/세로 디바이더. 라벨을 넣으면 가운데 정렬 구분선이 된다. | `Separator` |
183
- | OtpField | 일회용 코드(OTP)/PIN 입력. 셀 단위 입력, 붙여넣기 분배, 자동 포커스 이동, 백스페이스 네비게이션과 폼 이름/오류 연결을 지원합니다. | `OtpField` |
184
- | Toggle | 눌림(pressed) 두 상태 버튼. 단독 사용하거나 ToggleGroup으로 묶어 단일/다중 선택을 만든다. | `Toggle`, `ToggleGroup` |
185
- | Accordion | 수직으로 쌓인 펼침/접힘 패널. single(한 개)/multiple(여러 개) 모드와 collapsible 지원. | `AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` |
186
- | Meter | 범위 내 스칼라 측정값 게이지 (디스크 사용량·점수·용량 등). role=meter로 작업 진행률(Progress)과 구분된다. | `Meter` |
187
- | BlockLayout | Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다. | `BlockLayout` |
188
- | createBlock | Block 팩토리 함수. BlockLayout 래핑을 구조적으로 강제하여 loading/className 처리를 자동화합니다. | `createBlock` |
189
- | StarRating | 1~N점 별점을 선택하는 인터랙티브 레이팅 입력. 읽기 전용 표시도 지원. | `StarRating` |
190
- | ErrorBoundary | React 에러 바운더리. 자식 컴포넌트 렌더 에러를 잡아 fallback UI를 표시합니다. | `ErrorBoundary` |
191
- | Command | cmdk 스타일 명령 anatomy. 자동 필터링 + 키보드 내비게이션. 인라인 또는 CommandDialog로 사용. | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut` |
192
- | ShaderSurface | ogl 기반 애니메이션 WebGL 셰이더 배경. 럭셔리 프리셋(메탈릭/실크/유리 등) + 색·파라미터로 배경·카드 배경을 만든다. 정지 프레임·PNG 캡처·WebGL 폴백 지원. | `ShaderSurface` |
178
+ | Component | Description | Key Exports |
179
+ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
180
+ | FieldToken | 필드 타입을 글리프 하나로 표현하는 토큰. 문자열·숫자·날짜·IP·지오 등 분석 스키마 타입마다 고정된 아이콘과 팔레트 슬롯을 부여해 필드 목록·컬럼 헤더·속성 테이블 전역에서 같은 어휘를 쓴다. | `FieldToken`, `FIELD_TYPE_TOKENS`, `resolveFieldType` |
181
+ | Facet | 필드 값 분포를 카운트와 점유율 막대로 보여주고 그 행 자체가 필터가 되는 패싯. 긴 꼬리는 접어 두고 상위 값부터 읽힌다. | `Facet`, `FacetGroup` |
182
+ | Expression | 조건을 폼이 아니라 문장으로 쓰고 그 자리에서 편집하는 표현식 절. 알림 규칙·세그먼트 필터처럼 읽어서 검증해야 하는 조건에 쓴다. | `Expression`, `ExpressionGroup` |
183
+ | TextTruncate | 실제 폰트로 실제 가용 폭을 측정해 문자열의 식별력이 가장 낮은 부분을 잘라내는 생략. CSS가 못 하는 앞·중간·양끝 생략을 지원하고 전체 문자열은 접근성 트리에 남는다. | `TextTruncate` |
184
+ | Highlight | 검색어에 해당하는 구간을 <mark>로 표시. 긴 항목 우선 매칭이라 겹치는 검색어도 조각나지 않는다. | `Highlight` |
185
+ | LiveRegion | 라이브 뷰의 변화를 스크린 리더에 읽어 주는 영역. 스로틀로 폭주를 요약하고 두 노드를 번갈아 써서 같은 문구도 다시 읽힌다. | `LiveRegion` |
186
+ | ColorPalette | 시각화 색 팔레트를 그 팔레트의 모습 그대로 보여 주고 고르게 하는 컴포넌트. 범주형은 블록, 순차·발산형은 그라디언트로 그려 데이터 종류를 그림이 말한다. | `ColorPaletteDisplay`, `ColorPalettePicker`, `THEME_PALETTES` |
187
+ | InlineEdit | 대시보드 제목·지표 이름처럼 읽히는 횟수가 훨씬 많은 값을 그 자리에서 고치는 편집. Enter 확정, Escape 되돌리기, 거절된 저장은 입력을 유지한다. | `InlineEdit` |
188
+ | KeyPadMenu | 이름보다 그림으로 알아보기 쉬운 선택지를 타일로 고르는 메뉴. 내부는 실제 radio·checkbox라 키보드와 스크린 리더가 그대로 동작한다. | `KeyPadMenu` |
189
+ | Text | 본문, 레이블, 보조 설명, 코드에 일관된 의미 기반 타이포그래피를 적용합니다. | `Text` |
190
+ | Heading | 문서의 의미 계층과 시각적 타이포그래피 계층을 독립적으로 제어합니다. | `Heading` |
191
+ | Separator | 콘텐츠를 구분하는 가로/세로 디바이더. 라벨을 넣으면 가운데 정렬 구분선이 된다. | `Separator` |
192
+ | OtpField | 일회용 코드(OTP)/PIN 입력. 셀 단위 입력, 붙여넣기 분배, 자동 포커스 이동, 백스페이스 네비게이션과 폼 이름/오류 연결을 지원합니다. | `OtpField` |
193
+ | Toggle | 눌림(pressed) 두 상태 버튼. 단독 사용하거나 ToggleGroup으로 묶어 단일/다중 선택을 만든다. | `Toggle`, `ToggleGroup` |
194
+ | Accordion | 수직으로 쌓인 펼침/접힘 패널. single(한 개)/multiple(여러 개) 모드와 collapsible 지원. | `AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` |
195
+ | Meter | 범위 내 스칼라 측정값 게이지 (디스크 사용량·점수·용량 등). role=meter로 작업 진행률(Progress)과 구분된다. | `Meter` |
196
+ | BlockLayout | Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다. | `BlockLayout` |
197
+ | createBlock | Block 팩토리 함수. BlockLayout 래핑을 구조적으로 강제하여 loading/className 처리를 자동화합니다. | `createBlock` |
198
+ | StarRating | 1~N점 별점을 선택하는 인터랙티브 레이팅 입력. 읽기 전용 표시도 지원. | `StarRating` |
199
+ | ErrorBoundary | React 에러 바운더리. 자식 컴포넌트 렌더 에러를 잡아 fallback UI를 표시합니다. | `ErrorBoundary` |
200
+ | Command | cmdk 스타일 명령 anatomy. 자동 필터링 + 키보드 내비게이션. 인라인 또는 CommandDialog로 사용. | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut` |
201
+ | ShaderSurface | ogl 기반 애니메이션 WebGL 셰이더 배경. 럭셔리 프리셋(메탈릭/실크/유리 등) + 색·파라미터로 배경·카드 배경을 만든다. 정지 프레임·PNG 캡처·WebGL 폴백 지원. | `ShaderSurface` |
193
202
 
194
203
  ## Visual Components (0)
195
204
 
@@ -352,6 +361,184 @@
352
361
 
353
362
  ### Core Layer
354
363
 
364
+ #### FieldToken
365
+
366
+ **Import:** `import { FieldToken } from "@reopt-ai/opt-ui"`
367
+
368
+ | Prop | Type | Required | Default | Description |
369
+ | ------------ | ------------------------------- | -------- | -------- | ------------------------------------------------------- |
370
+ | `type` | `FieldDataType` | Yes | | 필드 타입. 백엔드 원본 타입은 resolveFieldType으로 변환 |
371
+ | `size` | `"xs" \| "sm" \| "md" \| "lg"` | | "sm" | 토큰 크기 |
372
+ | `fill` | `"subtle" \| "solid" \| "none"` | | "subtle" | 배경 채우기 방식 |
373
+ | `shape` | `"square" \| "circle"` | | "square" | 토큰 모양 |
374
+ | `title` | `string` | | | 접근성 이름. 기본값은 타입 이름 |
375
+ | `decorative` | `boolean` | | false | 인접 텍스트가 타입을 이미 말할 때 접근성 트리에서 제외 |
376
+ | `className` | `string` | | | 추가 CSS 클래스 |
377
+
378
+ #### Facet
379
+
380
+ **Import:** `import { Facet } from "@reopt-ai/opt-ui"`
381
+
382
+ **Facet:**
383
+
384
+ | Prop | Type | Required | Default | Description |
385
+ | ---------------- | ---------------------------- | -------- | ---------- | -------------------------------- |
386
+ | `item` | `FacetItem` | Yes | | 표시할 값 |
387
+ | `selected` | `boolean` | | false | 선택 상태 |
388
+ | `onSelect` | `(id: string) => void` | | | 선택 콜백 |
389
+ | `showShare` | `boolean` | | true | 점유율 막대 표시 |
390
+ | `share` | `number` | | | 0–1 점유율. 그룹이 계산해 내려줌 |
391
+ | `countFormatter` | `(count: number) => string` | | | 카운트 포맷터 |
392
+ | `layout` | `"vertical" \| "horizontal"` | | "vertical" | 배치 방향 |
393
+ | `labels` | `FacetGroupLabels` | | | 지역화 문자열 |
394
+ | `className` | `string` | | | 추가 CSS 클래스 |
395
+
396
+ **FacetGroup:**
397
+
398
+ | Prop | Type | Required | Default | Description |
399
+ | ------------------ | ---------------------------------- | -------- | ---------- | ------------------------------ |
400
+ | `items` | `FacetItem[]` | Yes | | 값 목록 |
401
+ | `selected` | `string[]` | | | 선택된 id. 생략 시 비제어 |
402
+ | `onSelectedChange` | `(next: string[]) => void` | | | 선택 변경 콜백 |
403
+ | `selection` | `"single" \| "multiple" \| "none"` | | "multiple" | 선택 모드 |
404
+ | `layout` | `"vertical" \| "horizontal"` | | "vertical" | 배치 방향 |
405
+ | `showShare` | `boolean` | | true | 점유율 막대 표시 |
406
+ | `countFormatter` | `(count: number) => string` | | | 카운트 포맷터 |
407
+ | `max` | `number` | | | 접기 전 표시 행 수 |
408
+ | `total` | `number` | | | 점유율 분모. 생략 시 카운트 합 |
409
+ | `loading` | `boolean` | | false | 로딩 상태 |
410
+ | `emptyState` | `ReactNode` | | | 빈 상태 렌더 |
411
+ | `labels` | `FacetGroupLabels` | | | 지역화 문자열 |
412
+ | `className` | `string` | | | 추가 CSS 클래스 |
413
+ | `aria-label` | `string` | | | 그룹 접근성 이름 |
414
+
415
+ #### Expression
416
+
417
+ **Import:** `import { Expression } from "@reopt-ai/opt-ui"`
418
+
419
+ **Expression:**
420
+
421
+ | Prop | Type | Required | Default | Description |
422
+ | ------------- | ----------------------- | -------- | -------- | -------------------------------- |
423
+ | `description` | `ReactNode` | Yes | | 고정되는 절반 (WHEN, IS ABOVE …) |
424
+ | `value` | `ReactNode` | | | 편집되는 절반 |
425
+ | `tone` | `ExpressionTone` | | "accent" | 의미별 색상 |
426
+ | `active` | `boolean` | | false | 편집기 열림 상태 |
427
+ | `invalid` | `boolean` | | false | 유효하지 않은 절 |
428
+ | `disabled` | `boolean` | | false | 비활성 |
429
+ | `onClick` | `() => void` | | | 편집기 열기 |
430
+ | `display` | `"inline" \| "stacked"` | | "inline" | 문장 흐름 유지 vs 값 아래 배치 |
431
+ | `aria-label` | `string` | | | 접근성 이름 |
432
+ | `className` | `string` | | | 추가 CSS 클래스 |
433
+
434
+ **ExpressionGroup:**
435
+
436
+ | Prop | Type | Required | Default | Description |
437
+ | ------------ | ------------------------- | -------- | ---------- | ---------------------- |
438
+ | `children` | `ReactNode` | Yes | | 절들 |
439
+ | `display` | `"sentence" \| "columns"` | | "sentence" | 문장 배치 vs 컬럼 정렬 |
440
+ | `className` | `string` | | | 추가 CSS 클래스 |
441
+ | `aria-label` | `string` | | | 그룹 접근성 이름 |
442
+
443
+ #### TextTruncate
444
+
445
+ **Import:** `import { TextTruncate } from "@reopt-ai/opt-ui"`
446
+
447
+ | Prop | Type | Required | Default | Description |
448
+ | ------------ | ---------------------------------------- | -------- | ---------- | --------------------------------------------- |
449
+ | `text` | `string` | Yes | | 전체 문자열 |
450
+ | `truncation` | `TruncationSide` | | "startEnd" | 생략 위치: end \| start \| middle \| startEnd |
451
+ | `ellipsis` | `string` | | "…" | 생략 기호 |
452
+ | `width` | `number` | | | 고정 폭(px). 생략 시 컨테이너 측정 |
453
+ | `children` | `(truncated: string) => React.ReactNode` | | | 잘린 문자열을 직접 렌더 |
454
+ | `className` | `string` | | | 추가 CSS 클래스 |
455
+
456
+ #### Highlight
457
+
458
+ **Import:** `import { Highlight } from "@reopt-ai/opt-ui"`
459
+
460
+ | Prop | Type | Required | Default | Description |
461
+ | --------------- | -------------------- | -------- | ------- | ------------------------ |
462
+ | `text` | `string` | Yes | | 전체 텍스트 |
463
+ | `search` | `string \| string[]` | Yes | | 검색어 하나 또는 여러 개 |
464
+ | `caseSensitive` | `boolean` | | false | 대소문자 구분 |
465
+ | `firstOnly` | `boolean` | | false | 첫 일치만 표시 |
466
+ | `className` | `string` | | | 추가 CSS 클래스 |
467
+ | `markClassName` | `string` | | | mark 요소 추가 클래스 |
468
+
469
+ #### LiveRegion
470
+
471
+ **Import:** `import { LiveRegion } from "@reopt-ai/opt-ui"`
472
+
473
+ | Prop | Type | Required | Default | Description |
474
+ | ------------ | ------------------------- | -------- | -------- | -------------------------------------------------- |
475
+ | `message` | `string` | Yes | | 안내할 문구 |
476
+ | `nonce` | `string \| number` | | | 문구가 같아도 다시 읽히게 하는 값 (카운터·배치 id) |
477
+ | `politeness` | `"polite" \| "assertive"` | | "polite" | 끼어들기 여부 |
478
+ | `throttleMs` | `number` | | 0 | 안내 병합 간격(ms) |
479
+ | `muted` | `boolean` | | false | 안내 일시 중단 |
480
+
481
+ #### ColorPalette
482
+
483
+ **Import:** `import { ColorPaletteDisplay } from "@reopt-ai/opt-ui"`
484
+
485
+ **ColorPaletteDisplay:**
486
+
487
+ | Prop | Type | Required | Default | Description |
488
+ | ------------ | ------------------------------ | -------- | ------- | ------------------------------------------------ |
489
+ | `palette` | `ColorPalette` | Yes | | 표시할 팔레트 |
490
+ | `render` | `"stops" \| "gradient"` | | | 블록 vs 그라디언트. 기본은 palette.kind에서 결정 |
491
+ | `size` | `"xs" \| "sm" \| "md" \| "lg"` | | "sm" | 스와치 높이 |
492
+ | `aria-label` | `string` | | | 접근성 이름 |
493
+ | `className` | `string` | | | 추가 CSS 클래스 |
494
+
495
+ **ColorPalettePicker:**
496
+
497
+ | Prop | Type | Required | Default | Description |
498
+ | --------------- | ------------------------------ | -------- | ---------------- | ------------------ |
499
+ | `palettes` | `ColorPalette[]` | Yes | | 선택지 |
500
+ | `value` | `string` | | | 선택된 팔레트 id |
501
+ | `onValueChange` | `(id: string) => void` | | | 선택 콜백 |
502
+ | `label` | `string` | | "Colour palette" | 레이블 |
503
+ | `hideLabel` | `boolean` | | false | 레이블 시각적 숨김 |
504
+ | `size` | `"xs" \| "sm" \| "md" \| "lg"` | | "sm" | 스와치 높이 |
505
+ | `disabled` | `boolean` | | false | 비활성 |
506
+ | `className` | `string` | | | 추가 CSS 클래스 |
507
+
508
+ #### InlineEdit
509
+
510
+ **Import:** `import { InlineEdit } from "@reopt-ai/opt-ui"`
511
+
512
+ | Prop | Type | Required | Default | Description |
513
+ | ------------- | --------------------------------------------------------------- | -------- | ---------- | ------------------------------------------- |
514
+ | `value` | `string` | Yes | | 현재 값 |
515
+ | `onSave` | `(next: string) => boolean \| void \| Promise<boolean \| void>` | Yes | | 저장. false를 반환하면 거절하고 편집을 유지 |
516
+ | `as` | `"span" \| "h1" \| "h2" \| "h3" \| "h4"` | | "span" | 읽기 모드 요소 |
517
+ | `size` | `"sm" \| "md" \| "lg" \| "xl"` | | "md" | 타이포 크기 |
518
+ | `placeholder` | `string` | | | 입력 자리표시자 |
519
+ | `emptyText` | `string` | | "Untitled" | 빈 값 표시 |
520
+ | `disabled` | `boolean` | | false | 편집 불가 |
521
+ | `maxLength` | `number` | | | 최대 길이 |
522
+ | `suffix` | `ReactNode` | | | 읽기 모드 텍스트 뒤 요소 |
523
+ | `labels` | `InlineEditLabels` | | | 지역화 문자열 |
524
+ | `className` | `string` | | | 추가 CSS 클래스 |
525
+
526
+ #### KeyPadMenu
527
+
528
+ **Import:** `import { KeyPadMenu } from "@reopt-ai/opt-ui"`
529
+
530
+ | Prop | Type | Required | Default | Description |
531
+ | --------------- | -------------------------------------------------------- | -------- | -------- | -------------------------------------------- |
532
+ | `items` | `KeyPadItem[]` | Yes | | 타일 목록 |
533
+ | `label` | `string` | Yes | | 그룹 레이블 |
534
+ | `selection` | `"single" \| "multiple"` | | "single" | 선택 모드. value·onValueChange의 형태를 결정 |
535
+ | `value` | `string \| string[]` | | | 선택된 id |
536
+ | `onValueChange` | `((next: string) => void) \| ((next: string[]) => void)` | | | 선택 콜백. value의 형태를 그대로 받는다 |
537
+ | `columns` | `number \| "auto"` | | "auto" | 행당 타일 수 |
538
+ | `size` | `"sm" \| "md"` | | "md" | 타일 크기 |
539
+ | `hideLabel` | `boolean` | | false | 레전드 시각적 숨김 |
540
+ | `className` | `string` | | | 추가 CSS 클래스 |
541
+
355
542
  #### Text
356
543
 
357
544
  **Import:** `import { Text } from "@reopt-ai/opt-ui"`
@@ -3327,21 +3514,22 @@ const messages = [
3327
3514
 
3328
3515
  **Import:** `import { LogTable } from "@reopt-ai/opt-ui"`
3329
3516
 
3330
- | Prop | Type | Required | Default | Description |
3331
- | ---------------- | ---------------------------------------- | -------- | -------- | -------------------------------- |
3332
- | `rows` | `Row[]` | Yes | | 표시할 행 |
3333
- | `columns` | `LogColumn<Row>[]` | Yes | | 컬럼 정의 (표시 중인 것만) |
3334
- | `getRowId` | `(row: Row) => string` | Yes | | 행 식별자 |
3335
- | `selectedId` | `string \| null` | | | 선택된 행 |
3336
- | `onSelect` | `(id: string) => void` | | | 행 선택 |
3337
- | `onLoadMore` | `() => void` | | | 다음 페이지 요청 |
3338
- | `prepending` | `boolean` | | false | 상단에 행이 삽입되는 라이브 목록 |
3339
- | `onFollowChange` | `(following: boolean) => void` | | | 최신 행 고정 여부 보고 |
3340
- | `isNew` | `(row: Row) => boolean` | | | 방금 도착한 행 강조 |
3341
- | `sort` | `LogSort \| null` | | | 정렬 상태 |
3342
- | `onSortChange` | `(sort: LogSort) => void` | | | 헤더 클릭 정렬 |
3343
- | `onCellAction` | `(action: LogCellAction) => void` | | | 셀 값 포함/제외 필터 |
3344
- | `density` | `"compact" \| "normal" \| "comfortable"` | | "normal" | 행 높이와 글자 크기 |
3517
+ | Prop | Type | Required | Default | Description |
3518
+ | ---------------- | ---------------------------------------- | -------- | -------- | -------------------------------------------------------- |
3519
+ | `rows` | `Row[]` | Yes | | 표시할 행 |
3520
+ | `columns` | `LogColumn<Row>[]` | Yes | | 컬럼 정의 (표시 중인 것만) |
3521
+ | `getRowId` | `(row: Row) => string` | Yes | | 행 식별자 |
3522
+ | `selectedId` | `string \| null` | | | 선택된 행 |
3523
+ | `onSelect` | `(id: string) => void` | | | 행 선택 |
3524
+ | `onLoadMore` | `() => void` | | | 다음 페이지 요청 |
3525
+ | `prepending` | `boolean` | | false | 상단에 행이 삽입되는 라이브 목록 |
3526
+ | `onFollowChange` | `(following: boolean) => void` | | | 최신 행 고정 여부 보고 |
3527
+ | `isNew` | `(row: Row) => boolean` | | | 방금 도착한 행 강조 |
3528
+ | `sort` | `LogSort \| null` | | | 정렬 상태 |
3529
+ | `onSortChange` | `(sort: LogSort) => void` | | | 헤더 클릭 정렬 |
3530
+ | `onCellAction` | `(action: LogCellAction) => void` | | | 셀 값 포함/제외 필터 |
3531
+ | `highlightTerms` | `string[]` | | | 셀 텍스트에서 표시할 검색어. 쿼리의 자유 텍스트만 넘긴다 |
3532
+ | `density` | `"compact" \| "normal" \| "comfortable"` | | "normal" | 행 높이와 글자 크기 |
3345
3533
 
3346
3534
  #### QueryBar
3347
3535
 
package/README.md CHANGED
@@ -47,13 +47,13 @@ bun add @reopt-ai/opt-ui
47
47
  ## 컴포넌트 계층
48
48
 
49
49
  ```
50
- Core (55) → Shells (79) → Blocks via opt-cli
50
+ Core (59) → Shells (80) → Blocks via opt-cli
51
51
  primitives 비즈니스 조합 페이지 템플릿 설치
52
52
 
53
- opt-charts (21) → 데이터 시각화와 chart-specific shells
53
+ opt-charts (35) → 데이터 시각화와 chart-specific shells
54
54
  ```
55
55
 
56
- ### Core (55개)
56
+ ### Core (59개)
57
57
 
58
58
  접근성 프리미티브 + Tailwind 스타일. 단일 책임 primitive 컴포넌트.
59
59
 
@@ -63,15 +63,17 @@ Button, Badge, Input, Textarea, Switch, Checkbox, CheckboxGroup, RadioGroup, Rad
63
63
 
64
64
  차트 컴포넌트는 `@reopt-ai/opt-charts`에서 직접 import합니다. `@reopt-ai/opt-ui/visuals`는 기존 소비자를 위한 deprecated compatibility re-export입니다.
65
65
 
66
- ChartContainer, ChartTooltip, ChartLegend, LineChart, BarChart, AreaChart, Sparkline, PieChart, ScatterChart, ComparisonChart, GaugeChart, FunnelChart, RetentionHeatmap, SankeyChart
66
+ 대표 컴포넌트:
67
+
68
+ ChartContainer, ChartTooltip, ChartLegend, LineChart, BarChart, AreaChart, Sparkline, PieChart, ScatterChart, ComparisonChart, GaugeChart, FunnelChart, RetentionHeatmap, SankeyChart, TimeSeriesChart, TimeSeriesTooltipContent
67
69
 
68
- ### Shells (79개)
70
+ ### Shells (80개)
69
71
 
70
72
  Core 조합 + 비즈니스 로직.
71
73
 
72
74
  대표 컴포넌트:
73
75
 
74
- CommandPalette, CommandPaletteTrigger, DashboardGrid, SearchCombobox, StatusSelect, AppMenubar, SidebarNav, EditorToolbar, ContentTabs, FaqAccordion, SettingsForm, AuthForm, DynamicFieldForm, FileUploadForm, WizardForm, DeploymentTimeline, ProjectSwitcher, EnvPanel, BranchSelect, DomainTable, DataTable, NotificationToast, TaskList, ActivityFeed, FilterBar, QuickActions, TeamMemberList, EventIcon, ConnectionIndicator, FloatingActionBar, TemplatePicker, CodeSnippetViewer, PropertyExplorer, QueryResultsTable, AlertBuilder, SqlEditor, EventMetaEditor, WidgetGrid, ReportBuilder, SegmentBuilder, InsightsPanel, TimeRangeSelector, ExportButton, LoadingOverlay, SummaryRow, ComparisonSelector, ThemeSwitcher, PromptTemplate, Sidebar, AppShell, DesignGuidePanel
76
+ CommandPalette, CommandPaletteTrigger, DashboardGrid, SearchCombobox, StatusSelect, AppMenubar, SidebarNav, EditorToolbar, ContentTabs, FaqAccordion, SettingsForm, AuthForm, DynamicFieldForm, FileUploadForm, WizardForm, DeploymentTimeline, ProjectSwitcher, EnvPanel, BranchSelect, DomainTable, DataTable, NotificationToast, TaskList, ActivityFeed, FilterBar, QuickActions, TeamMemberList, EventIcon, ConnectionIndicator, FloatingActionBar, TemplatePicker, CodeSnippetViewer, PropertyExplorer, QueryResultsTable, AlertBuilder, SqlEditor, EventMetaEditor, WidgetGrid, ReportBuilder, SegmentBuilder, InsightsPanel, TimeRangeSelector, TimeRangeControl, TimeSeriesPanel, LogTable, QueryBar, FieldSidebar, ExportButton, LoadingOverlay, SummaryRow, ComparisonSelector, ThemeSwitcher, PromptTemplate, Sidebar, AppShell, DesignGuidePanel
75
77
 
76
78
  전체 목록은 `COMPONENT_CATALOG.md` 또는 generated docs의 `02-components/03-shells.md`를 기준으로 확인합니다.
77
79
 
@@ -94,6 +96,10 @@ import { LineChart, BarChart } from "@reopt-ai/opt-charts";
94
96
  import { Button, Badge } from "@reopt-ai/opt-ui/core";
95
97
  import { LineChart, BarChart } from "@reopt-ai/opt-charts/visuals";
96
98
  import { DataTable, FilterBar } from "@reopt-ai/opt-ui/shells";
99
+
100
+ // React가 필요 없는 파서와 시간 계산은 서버 안전 서브패스 사용
101
+ import { parseQuery, matchesQueryObject } from "@reopt-ai/opt-ui/query";
102
+ import { resolveTimeRange } from "@reopt-ai/opt-charts/time";
97
103
  ```
98
104
 
99
105
  ### 기본 예시
@@ -143,6 +149,64 @@ const series = [
143
149
  </ChartContainer>;
144
150
  ```
145
151
 
152
+ ### 로그 탐색: 쿼리를 값으로 유지
153
+
154
+ <code>QueryBar</code>는 문자열을 내부 상태에 숨기지 않고 직렬화 가능한
155
+ <code>Query</code> 값을 입출력합니다. 같은 값으로 서버 요청, 현재 브라우저 행,
156
+ 실시간으로 도착한 행을 동일하게 필터링할 수 있습니다. Route Handler나 서버
157
+ 코드에서는 React client boundary를 끌어오지 않는
158
+ <code>@reopt-ai/opt-ui/query</code>를 사용합니다.
159
+
160
+ ```ts
161
+ import { matchesQueryObject, parseQuery } from "@reopt-ai/opt-ui/query";
162
+
163
+ const query = parseQuery("service:api -status:200 duration>250");
164
+
165
+ const visibleRows = rows.filter((row) =>
166
+ matchesQueryObject(query, row, { nested: "properties" }),
167
+ );
168
+ ```
169
+
170
+ UI에서는 동일한 <code>Query</code>를 <code>QueryBar</code>에 전달하고,
171
+ <code>LogTable</code>의 cell action을 <code>applyCellAction</code>으로 다시
172
+ 쿼리에 합칩니다. <code>FieldSidebar</code>의 값 분포 필터도 같은
173
+ include/exclude 계약을 사용합니다.
174
+
175
+ - [QueryBar Explore](https://design.reopt.ai/explore/shells/query-bar)
176
+ - [LogTable Explore](https://design.reopt.ai/explore/shells/log-table)
177
+ - [FieldSidebar Explore](https://design.reopt.ai/explore/shells/field-sidebar)
178
+
179
+ ### 시간 범위: 표현식을 저장하고 나중에 해석
180
+
181
+ <code>TimeRangeControl</code>은 두 시각을 고정하는 대신
182
+ <code>{ from: "now-7d", to: "now" }</code> 형태의 date-math 표현식을
183
+ 유지합니다. URL이나 저장된 대시보드는 계속 “최근 7일”을 뜻하고, 실제 요청을
184
+ 보낼 때만 기준 시각과 시간대를 넣어 절대 범위로 해석합니다.
185
+
186
+ ```ts
187
+ import { resolveTimeRange } from "@reopt-ai/opt-charts/time";
188
+
189
+ const resolved = resolveTimeRange(
190
+ { from: "now-7d/d", to: "now/d" },
191
+ {
192
+ now: Date.now(),
193
+ timeZone: "Asia/Seoul",
194
+ weekStartsOn: 1,
195
+ },
196
+ );
197
+
198
+ if (!resolved) {
199
+ throw new Error("Invalid time range");
200
+ }
201
+ ```
202
+
203
+ 서버, URL parser, unit test에서는 <code>@reopt-ai/opt-charts/time</code>을
204
+ 사용하고, 클라이언트 화면에서는 <code>TimeRangeControl</code> 또는 차트까지
205
+ 묶은 <code>TimeSeriesPanel</code>을 사용합니다.
206
+
207
+ - [TimeRangeControl Explore](https://design.reopt.ai/explore/shells/time-range-control)
208
+ - [TimeSeriesPanel Explore](https://design.reopt.ai/explore/shells/time-series-panel)
209
+
146
210
  ### Block template 설치
147
211
 
148
212
  ```bash