@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.41 → 1.0.43

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.
@@ -9,7 +9,8 @@ const gridOptionsSchema = z.object({
9
9
  headerCheckbox: z.boolean().optional().describe('헤더 체크박스 사용 여부'),
10
10
  enableSelectionWithoutKeys: z.boolean().optional().describe('키 없이 선택 허용'),
11
11
  }).optional().describe('행 선택 옵션'),
12
- tooltipShowDelay: z.number().optional().describe('툴팁 표시 지연 시간'),
12
+ tooltipShowDelay: z.number().optional().describe('툴팁 표시 지연 시간 (ms, 기본 300)'),
13
+ tooltipShowMode: z.enum(['standard', 'whenTruncated']).optional().describe("툴팁 표시 방식. 지정하지 않으면 그리드가 'whenTruncated'(잘린 셀만 툴팁)를 자동 적용 — 직접 지정하면 자동 말줄임 툴팁·헤더 툴팁이 꺼지므로 보통 지정하지 말 것"),
13
14
  domLayout: z.enum(['autoHeight', 'print']).optional().describe("그리드 레이아웃 방식 — 'autoHeight' 권장(최대 maxGridHeight까지 콘텐츠 맞춤). 고정 높이는 이 키를 빼고 gridHeight. ⚠️ 'normal'은 쓰지 말 것: 컨테이너 높이가 비워져 그리드가 0px로 사라짐(부모 높이와 무관, grid 2.0.7 브라우저 실측)"),
14
15
  suppressCellFocus: z.boolean().optional().describe('셀 포커스 비활성화 (셀 클릭 이벤트 사용 시 필수: true)'),
15
16
  suppressPaginationPanel: z.boolean().optional().describe('페이지네이션 패널 숨김'),
@@ -53,7 +54,11 @@ const columnDefsSchema = z.lazy(() => z.object({
53
54
  'ratioBar',
54
55
  'dataBar',
55
56
  'date'
56
- ])).optional().describe(`컬럼 타입.
57
+ ])).optional().describe(`컬럼 타입. 숫자·날짜 표기 표준은 type이 처리하므로 valueFormatter/cellStyle로 직접 만들지 말 것.
58
+ - cost·ratio·integer·number·mixFormat: 헤더·셀 오른쪽 정렬 자동
59
+ - ratio(mixFormat 퍼센트 포함): 소수 1자리 (85.3%, 0.0%)
60
+ - cost: 0.01 미만은 <$0.01, 실제 0은 $0.00. 증감 부호는 typeParams.showSign
61
+ - date: 셀 YYYY-MM-DD HH:mm(24시간제, 입력값을 UTC로 보고 브라우저 시간대로 표시), 헤더에 시간대 자동 표기(예: (UTC+9)) — headerName에 '(UTC'가 있으면 생략
57
62
  - ratioBar: 여러 색상/세그먼트로 구성 비율을 보여주는 스택 차트 스타일 바. 여러 필드의 비율을 시각화할 때 사용 (예: Cost Composition by Type). 'Ratio Bar' 예제 참고.
58
63
  - dataBar: 단일 색상으로 셀 배경을 값에 비례하여 채우는 Excel 스타일 바. 단일 값의 크기를 시각화할 때 사용 (예: 월별 비용 트렌드). 'Data Bar' 예제 참고.`),
59
64
  cellRenderer: z.any().optional().describe('셀 렌더러'),
@@ -65,6 +70,7 @@ const columnDefsSchema = z.lazy(() => z.object({
65
70
  isPercent: z.boolean().optional().describe('퍼센트 표시 여부'),
66
71
  vendor: z.string().optional().describe('cost 타입: 벤더별 통화·포맷 (예: \'aws\')'),
67
72
  isNegative: z.boolean().optional().describe('cost 타입: 음수 표시 처리'),
73
+ showSign: z.boolean().optional().describe('증감 부호 항상 표기 (+12.5%, -3.2%, 0은 부호 없음). ratio·cost·mixFormat 타입. 전월 대비 같은 증감 컬럼에 사용'),
68
74
  fields: z.array(z.string()).optional().describe('비율바 등에서 여러 필드'),
69
75
  label: z.object({
70
76
  postfix: z.string().optional().describe('라벨 접미사'),
@@ -92,8 +98,10 @@ const columnDefsSchema = z.lazy(() => z.object({
92
98
  }).catchall(z.any()).optional().describe('헤더 컴포넌트 파라미터'),
93
99
  sortable: z.boolean().optional().describe('정렬 가능 여부'),
94
100
  resizable: z.boolean().optional().describe('크기 조절 가능 여부'),
95
- wrapText: z.boolean().optional().describe('텍스트 줄바꿈'),
96
- autoHeight: z.boolean().optional().describe('자동 높이'),
101
+ wrapText: z.boolean().optional().describe('텍스트 줄바꿈 (기본 false = 한 줄 + 말줄임 + 잘리면 툴팁). 줄바꿈이 꼭 필요한 컬럼에만 true'),
102
+ autoHeight: z.boolean().optional().describe('자동 높이 (그리드 기본값 true — 지정 불필요)'),
103
+ tooltipField: z.string().optional().describe('툴팁에 표시할 필드명. ⚠️ 하나라도 지정하면 그리드 전체의 자동 말줄임 툴팁이 꺼짐 — 보통 지정하지 말 것'),
104
+ headerTooltip: z.string().optional().describe('헤더 툴팁 문구. ⚠️ 지정하면 자동 말줄임 툴팁이 꺼짐 — 긴 헤더는 기본으로 2줄 + 말줄임 + 전체 명칭 툴팁이 나오므로 보통 불필요'),
97
105
  suppressMenu: z.boolean().optional().describe('메뉴 숨김'),
98
106
  unSortIcon: z.boolean().optional().describe('정렬 해제 아이콘 표시'),
99
107
  rowDrag: z.boolean().optional().describe('행 드래그 사용'),
@@ -114,8 +122,8 @@ const columnDefsSchema = z.lazy(() => z.object({
114
122
  children: z.array(z.lazy(() => columnDefsSchema)).optional().describe('하위 컬럼 정의 배열 (컬럼 그룹화)'),
115
123
  }));
116
124
  const defaultColDefSchema = z.object({
117
- wrapText: z.boolean().optional().describe('텍스트 줄바꿈'),
118
- autoHeight: z.boolean().optional().describe('자동 높이'),
125
+ wrapText: z.boolean().optional().describe('⚠️ defaultColDef에는 넣지 말 것 — 모든 컬럼이 줄바꿈되어 표기 표준(한 줄 + 말줄임) 위반. 필요한 컬럼의 colDef에만 지정'),
126
+ autoHeight: z.boolean().optional().describe('자동 높이 (그리드 기본값 true — 지정 불필요)'),
119
127
  suppressMenu: z.boolean().optional().describe('메뉴 숨김'),
120
128
  unSortIcon: z.boolean().optional().describe('정렬 해제 아이콘 표시'),
121
129
  sortable: z.boolean().optional().describe('정렬 가능 여부'),
@@ -161,13 +169,14 @@ export const DataGridSchema = z.object({
161
169
  setClass: z.string().optional().describe('그리드 클래스명'),
162
170
  pagination: z.boolean().optional().describe('페이지네이션 사용 여부 (true로 설정 시 내부적으로 opsnow-common-pagination 컴포넌트 사용)'),
163
171
  paginationPageSize: z.number().optional().describe('페이지당 행 수 (기본값: 10)'),
164
- textNoData: z.string().optional().describe('데이터 없음 텍스트'),
172
+ textNoData: z.string().optional().describe('데이터 없음 문구 — 생략 시 langCd 표준 문구(ko: 표시할 데이터가 없습니다.). 화면 고유 문구가 필요할 때만'),
165
173
  noDataDescription: z.string().optional().describe('데이터 없음 설명'),
166
- textLoading: z.string().optional().describe('로딩 중 텍스트'),
167
- textErrorTitle: z.string().optional().describe('에러 타이틀'),
168
- textErrorDescription: z.string().optional().describe('에러 설명'),
174
+ textLoading: z.string().optional().describe('로딩 문구 — 생략 시 표준 문구(ko: 데이터를 불러오는 중입니다.)'),
175
+ textErrorTitle: z.string().optional().describe('오류 타이틀 — 생략 시 표준 문구(ko: 오류). 보통 생략'),
176
+ textErrorDescription: z.string().optional().describe('오류 설명 — 생략 시 표준 문구(ko: 데이터를 불러오지 못했습니다. 잠시 후 다시 시도해 주세요.). 보통 생략'),
177
+ onRetry: z.string().optional().describe('오류 상태의 [다시 시도] 버튼 클릭 핸들러(stringified). 넘기면 버튼이 표시됨 — 보통 조회 함수를 그대로 전달: onRetry={fetchData}'),
169
178
  filterSearchText: z.string().optional().describe('필터 검색 텍스트'),
170
- searchTextNoData: z.string().optional().describe('검색 결과 없음 텍스트'),
179
+ searchTextNoData: z.string().optional().describe('검색 결과 없음 문구 — 생략 시 표준 문구'),
171
180
  searchTextNoDataDescription: z.string().optional().describe('검색 결과 없음 설명'),
172
181
  pageSizeList: z.array(z.object({
173
182
  label: z.string().describe('페이지 사이즈 라벨'),
@@ -219,36 +228,30 @@ export function createDataGridComponent() {
219
228
  **이 데이터 그리드 컴포넌트는 ag-grid를 기반으로 구현되었습니다.**
220
229
  **데이터 그리드 데이터, 컬럼 정의 등의 데이터가 제공되지 않을 경우 목업 데이터를 사용하세요.**
221
230
 
222
- **CRITICAL: Auto Row Height - 다음 경우 반드시 적용**
223
- 1. 긴 텍스트가 들어올 수 있는 컬럼이 있는 경우 (설명, 메시지, 항목, 이름, 제목, 코멘트, 비고, 등)
224
- 2. 컬럼이 resizable인 경우 - 사용자가 폭을 줄여도 텍스트가 잘리지 않고 여러 줄로 정상 표시되어야 함 (ellipsis로 자르면 안됨)
231
+ **CRITICAL: 셀 표기 표준 — 기본은 한 줄 + 말줄임 (wrapText 강제 금지)**
232
+ 그리드 기본 colDef가 이미 { autoHeight: true, wrapText: false, wrapHeaderText: true, autoHeaderHeight: true }이고,
233
+ 잘린 셀에만 툴팁을 띄우는 tooltipShowMode: 'whenTruncated'를 자동 적용합니다. 긴 텍스트(설명·메시지·ARN 등) 컬럼도 기본은 아무 설정 없이 둡니다.
234
+ 1. ❌ defaultColDef에 wrapText: true / autoHeight: true 넣지 말 것 — 모든 컬럼이 줄바꿈되어 표기 표준 위반
235
+ 2. ✅ 줄바꿈이 꼭 필요한 컬럼에만 colDef에 wrapText: true (행 높이는 기본 autoHeight라 자동으로 늘어남)
236
+ 3. ⚠️ 컬럼 하나라도 tooltipField / tooltipValueGetter / tooltipComponent / headerTooltip / headerTooltipValueGetter를 지정하거나
237
+ defaultColDef·gridOptions(tooltipShowMode)에 툴팁 설정을 넣으면, 자동 말줄임 툴팁·헤더 툴팁이 그리드 전체에서 꺼짐 — 정말 커스텀 툴팁이 필요할 때만
238
+ 4. 헤더: 긴 헤더명은 2줄까지 표시, 넘치면 말줄임 + 호버 시 전체 명칭 툴팁 (HeaderFilter·HeaderInfoTooltip 커스텀 헤더도 동일) — 헤더명을 줄이거나 headerTooltip을 따로 달 필요 없음
225
239
 
226
- [필수] defaultColDef에 반드시 포함:
227
- const defaultColDef = {
228
- // ... 다른 설정들
229
- wrapText: true, // 필수 - 텍스트 줄바꿈
230
- autoHeight: true, // 필수 - 행 높이 자동 조절
231
- };
232
-
233
- [필수] gridOptions에 반드시 포함:
234
- const gridOptions = {
235
- // ... 다른 설정들
236
- domLayout: 'autoHeight', // 필수
237
- };
238
-
239
- [필수] 텍스트 컬럼에 반드시 포함:
240
- {
241
- headerName: '설명',
242
- field: 'description',
243
- flex: 2, // 필수 - flex 사용
244
- minWidth: 200,
245
- wrapText: true, // 필수 - 텍스트 줄바꿈
246
- autoHeight: true, // 필수 - 행 높이 자동 조절
247
- suppressSizeToFit: true, // 필수
248
- cellStyle: { alignItems: 'center' } // 필수 (flex-start도 가능)
249
- }
240
+ const columnDefs = [
241
+ { headerName: 'Description', field: 'description', flex: 2, minWidth: 220 }, // 한 줄 + 말줄임 + 잘리면 툴팁
242
+ { headerName: 'Memo', field: 'memo', flex: 2, minWidth: 220, wrapText: true }, // 이 컬럼만 줄바꿈
243
+ ];
244
+ '긴 텍스트 컬럼 (한 줄 + 말줄임 툴팁 / 줄바꿈 선택)' 예제 참고.
250
245
 
251
- ⚠️ defaultColDef에 wrapText, autoHeight가 없으면 텍스트가 넘칩니다!
246
+ **숫자·날짜 표기 표준 — type만 지정, valueFormatter/cellStyle로 다시 만들지 말 것**
247
+ - cost·ratio·integer·number·mixFormat 타입: 헤더·셀 자동 오른쪽 정렬
248
+ - ratio (mixFormat 퍼센트 포함): 소수 1자리 (85.3%, 0.0%). digits로 변경 가능
249
+ - cost: 0.01 미만 금액은 <$0.01 (음수는 >-$0.01), 실제 0은 $0.00
250
+ - 증감 컬럼: cellRendererParams: { typeParams: { showSign: true } } → +12.5% / -3.2% (0은 부호 없음, ratio·cost·mixFormat)
251
+ - date: 셀 YYYY-MM-DD HH:mm (24시간제, 언어 무관). 입력값을 UTC로 보고 브라우저 시간대로 변환하므로 rowData에는 UTC 값을 그대로 넣음.
252
+ 시간대는 헤더에 한 번 자동으로 붙음 (예: 'Updated At' → 'Updated At (UTC+9)'). headerName에 이미 '(UTC'가 있으면 다시 붙이지 않음 — 셀/헤더에 시간대를 직접 붙이지 말 것
253
+ 그리드 밖(카드·요약 텍스트·파일명 등)의 날짜는 useGlobalContext()의 finOpsDateUtils(formatDate/formatPeriod/formatDateTime/getTimeZoneLabel/formatFileNameDate)로 — 서버 UTC 값은 formatDateTime(v, { inputUtc: true })
254
+ '표기 표준 (숫자·날짜·2줄 헤더)' 예제 참고.
252
255
 
253
256
  **그리드 높이 정책 (grid ≥2.0.6) — 행 수로 분기하지 말 것**
254
257
  - 기본: gridOptions.domLayout: 'autoHeight' 하나만. 행이 적으면 콘텐츠 높이에 맞추고,
@@ -298,7 +301,8 @@ export function createDataGridComponent() {
298
301
  3. useEffect를 반드시 사용하여 데이터 로딩 시뮬레이션
299
302
  4. .then()으로 성공 처리 → CommonConst.GRID_STATUS.DATA_EXISTS로 변경
300
303
  5. .catch()로 에러 처리 → CommonConst.GRID_STATUS.ERROR로 변경
301
- 6. OpsnowCommonDataGrid에 textErrorTitle, textErrorDescription 속성 반드시 포함
304
+ 6. 상태 문구(로딩·오류·데이터 없음·검색 결과 없음)는 그리드가 langCd(ko/en/ja) 표준 문구로 표시 — textLoading/textErrorTitle/textErrorDescription/textNoData 등은 넘기지 않는 것이 기본 (화면 고유 문구가 꼭 필요할 때만)
305
+ 7. 조회 함수를 onRetry로 넘겨 오류 상태에 [다시 시도] 버튼을 제공 (재조회 시 status를 LOADING으로 되돌리는 것까지 조회 함수에서 처리)
302
306
 
303
307
  사용자는 생성된 코드의 useEffect 내부에 실제 비즈니스 로직(API 호출, 데이터 변환 등)을 추가할 수 있습니다.
304
308
 
@@ -308,10 +312,10 @@ export function createDataGridComponent() {
308
312
  const [status, setStatus] = useState(CommonConst.GRID_STATUS.LOADING);
309
313
  const [rowData, setRowData] = useState([]);
310
314
 
311
- // ✅ 올바른 방법: useEffect에서 데이터 로딩
312
- useEffect(() => {
313
- // 사용자가 여기에 실제 API 호출 등 비즈니스 로직을 추가합니다
314
- const fetchData = async () => {
315
+ // ✅ 올바른 방법: 조회 함수를 만들고 useEffect + onRetry 양쪽에서 사용
316
+ const fetchData = useCallback(async () => {
317
+ setStatus(CommonConst.GRID_STATUS.LOADING);
318
+ // 사용자가 여기에 실제 API 호출 등 비즈니스 로직을 추가합니다
315
319
  try {
316
320
  // 실제로는 여기에 API 호출을 넣습니다
317
321
  // 예: const response = await fetch('/api/data');
@@ -331,21 +335,21 @@ export function createDataGridComponent() {
331
335
  console.error('Error loading data:', error);
332
336
  setStatus(CommonConst.GRID_STATUS.ERROR);
333
337
  }
334
- };
338
+ }, []);
335
339
 
340
+ useEffect(() => {
336
341
  fetchData();
337
- }, []);
342
+ }, [fetchData]);
338
343
 
339
344
  // gridOptions 정의 (권장)
340
345
  const gridOptions = {
341
346
  animateRows: true,
342
347
  rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
343
- tooltipShowDelay: 100,
344
348
  domLayout: 'autoHeight',
345
349
  suppressCellFocus: true,
346
350
  };
347
351
 
348
- // ✅ 올바른 방법: 에러 관련 속성 포함
352
+ // ✅ 올바른 방법: onRetry로 [다시 시도] 제공, 상태 문구는 표준 문구 사용 (text* prop 생략)
349
353
  <OpsnowCommonDataGrid
350
354
  columnDefs={columnDefs}
351
355
  rowData={rowData}
@@ -358,8 +362,7 @@ export function createDataGridComponent() {
358
362
  { label: '10', value: 10 },
359
363
  { label: '20', value: 20 }
360
364
  ]}
361
- textErrorTitle="데이터 로드 실패"
362
- textErrorDescription="데이터를 불러오는 중 오류가 발생했습니다."
365
+ onRetry={fetchData}
363
366
  langCd={i18n.getLocale()}
364
367
  />
365
368
  \`\`\``,
@@ -4,7 +4,8 @@ export const SelectSchema = z.object({
4
4
  items: z.array(z.object({
5
5
  value: z.union([z.string(), z.number()]),
6
6
  label: z.any(), // string | JSX 가능
7
- })).describe("셀렉트 옵션 목록 [{ value, label }] — 항목별 disabled는 지원하지 않음(무시됨)."),
7
+ copilotLabel: z.string().optional().describe("코파일럿에만 보이는 옵션 이름 — 화면 표시명은 그대로 두고 코파일럿 선택지 라벨만 바꿈. 화면 label이 겹쳐 코파일럿이 구분할 수 없을 때 구분 정보를 붙여 지정 (예: 같은 이름 보고서 → 'GDPR Report (2026-10-01 09:00)'). copilotId가 있을 때만 의미 있음, 컴포넌트는 그리지 않음"),
8
+ })).describe("셀렉트 옵션 목록 [{ value, label, copilotLabel? }] — 항목별 disabled는 지원하지 않음(무시됨). TS 타입: import type { OpsnowCommonSelectItem } from '@opsnow-common/opsnow-finops-common-ui-loader' (컴포넌트가 아니라 items 원소 타입 — JSX로 쓰지 말 것)"),
8
9
  value: z.any().optional().describe("선택된 값(단일/다중)"),
9
10
  multiple: z.boolean().optional().default(false).describe("다중 선택 가능 여부"),
10
11
  placeholder: z.string().optional().describe("플레이스홀더 텍스트"),
@@ -22,8 +23,9 @@ export const AutocompleteSelectSchema = z.object({
22
23
  label: z.string(),
23
24
  group: z.string().optional(),
24
25
  iconName: z.string().optional(),
25
- disabled: z.boolean().optional().default(false)
26
- })).describe("오토컴플리트 옵션 목록"),
26
+ disabled: z.boolean().optional().default(false),
27
+ copilotLabel: z.string().optional().describe("코파일럿에만 보이는 옵션 이름 — 화면 표시명은 그대로 두고 코파일럿 선택지 라벨만 바꿈. 화면 label이 겹쳐 코파일럿이 구분할 수 없을 때 구분 정보를 붙여 지정 (예: 같은 이름 보고서 → 'GDPR Report (2026-10-01 09:00)'). copilotId가 있을 때만 의미 있음, 컴포넌트는 그리지 않음"),
28
+ })).describe("오토컴플리트 옵션 목록 [{ value, label, group?, iconName?, disabled?, copilotLabel? }]. TS 타입: import type { OpsnowCommonAutocompleteItem } from '@opsnow-common/opsnow-finops-common-ui-loader' (컴포넌트가 아니라 items 원소 타입 — JSX로 쓰지 말 것)"),
27
29
  value: z.any().optional().describe("선택된 값/값들 (단일/다중)"),
28
30
  multiple: z.boolean().optional().default(false).describe("다중 선택 가능 여부 (실제 컴포넌트에선 필수 prop — 단일 선택도 multiple={false} 명시)"),
29
31
  useCheckboxOption: z.boolean().optional().default(false).describe("체크박스 옵션 사용 여부"),
@@ -42,6 +42,27 @@ export function createTabComponent() {
42
42
  import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
43
43
  const { OpsnowCommonTab } = useCommonComponents();
44
44
  \`\`\`
45
+
46
+ **페이지 탭은 URL 해시와 동기화 (useHashTab) — 페이지 단위 탭이면 useState 대신 이것을 사용**
47
+ 새로고침·링크 공유·뒤로가기 시 같은 탭이 열리도록 탭 id를 URL 해시(#tab=<id>, 2단 탭은 &sub=<id>)에 싣습니다.
48
+ useHashTab이 { value, onChange, copilotTabIds }를 만들어 주므로 value/onChange/copilotTabIds를 직접 쓰지 말고 {...tab.props}로 펼칩니다.
49
+ \`\`\`javascript
50
+ import { useCommonComponents, useHashTab, buildTabUrl, readHashTab } from '@opsnow-common/opsnow-finops-common-ui-loader';
51
+
52
+ const TAB_IDS = ['overview', 'history', 'settings']; // items와 같은 순서의 의미 id
53
+ const tab = useHashTab(TAB_IDS); // tab.id: 현재 탭 id, tab.value: 인덱스, tab.setId('history')
54
+ const sub = useHashTab(['daily', 'monthly'], { key: 'sub' }); // 2단 탭
55
+
56
+ <OpsnowCommonTab copilotId="my-page-tab" items={tabItems} {...tab.props} />
57
+ {tab.id === 'history' && <OpsnowCommonTab depth={2} items={subItems} {...sub.props} />}
58
+ \`\`\`
59
+ - 옵션: key(기본 'tab', 2단 탭 'sub'), defaultId(없거나 ids에 없으면 ids[0]), resetKeys(이 탭이 바뀔 때 함께 지울 쿼리·해시 키 — 예: ['sub']), ready(false면 해시를 고치지 않음 — 권한·벤더 조회 전이라 ids가 확정되지 않았을 때 링크의 탭 id를 잃지 않도록)
60
+ - 다른 화면의 특정 탭으로 가는 링크: buildTabUrl(path, id?, query?, { sub? })
61
+ buildTabUrl('/cost/anomalies', 'alert-rule') // '/cost/anomalies#tab=alert-rule'
62
+ buildTabUrl('/optimize/my-commitments', 'coverage', { vendor: 'aws' }, { sub: 'all' }) // '/optimize/my-commitments?vendor=aws#tab=coverage&sub=all'
63
+ path는 basename 없는 라우터 경로. 기본 탭이면 id 생략 가능. ❌ 'path?tab=x' 쿼리 문자열을 직접 조립하지 말 것
64
+ - 훅을 못 쓰는 곳(리다이렉트·헤더 등)에서 현재 탭 판정: readHashTab(location, key?) — 해시 우선, 없으면 예전 ?tab= 쿼리
65
+ - 패널 안 내용만 바꾸는 작은 탭(카드 내부 토글 등)은 기존처럼 useState 인덱스로 충분
45
66
  `,
46
67
  parameters: TabSchema,
47
68
  handler: async (args) => {
package/build/index.js CHANGED
@@ -57,6 +57,47 @@ import axios from 'axios';
57
57
  import { getAxios } from '@opsnow-common/opsnow-finops-common-axios';
58
58
  const response = await getAxios().get('/api/endpoint');
59
59
 
60
+ 공통 오류 팝업 (initializeCommonAxios가 기본 등록): 401·404·500·502·503·504 + network(응답 없이 끝난 요청 — 네트워크 끊김·타임아웃·CORS 헤더 없는 504 등, 요청 취소는 제외)에 공통 오류 팝업이 자동으로 뜹니다.
61
+ - 화면에서 같은 오류에 대해 별도 오류 팝업/토스트를 또 띄우지 마세요 (이중 표시). catch에서는 화면 상태(예: 그리드 status=ERROR)만 바꿉니다.
62
+ - userErrorHandlingCallbackObject를 넘기면 기본 콜백 전체가 대체됩니다(병합 아님) — 커스텀할 때는 network 키까지 포함하세요: { 401: fn, 500: fn, default: fn, network: fn }
63
+ - 재시도 대상 오류는 재시도가 모두 끝난 뒤 한 번만 콜백이 호출되고, 504·응답 없는 오류는 재시도하지 않습니다.
64
+
65
+ **앱 초기화 / 테마 (@opsnow-common/opsnow-finops-common-ui-loader)** — 새 앱 부트스트랩·테마 토글을 만들 때만 해당
66
+ - main.jsx (렌더 전 1회): initializeCommonAxios({ timeout, requestHeaders, retryTimeInterval, userErrorHandlingCallbackObject? }) — getAxios()는 이 호출 뒤에만 동작. 공통 오류 팝업도 여기서 등록됨
67
+ - initialize(routes, { useO360Keycloak, platformApiPrefix }) — 공통 라우트(404·Unauthorized) 등 공통 설정
68
+ - commonInitialize({ useGTM, gtmId, loginUser, useClarity, clarityId, ... }) — 로그인 사용자 확정 후 GTM·Clarity 등 분석 도구 초기화 (한 번만)
69
+ - 테마: <GlobalProvider themeName={currentTheme}> 에 THEME_NAMES.OPSNOW_COMMON_THEME | THEME_NAMES.OPSNOW_DARK_THEME 를 넘깁니다.
70
+ 테마는 쿠키(THEME_COOKIE_NAME='opsnowTheme', 상위 도메인)로 서브도메인 앱 간 동기화됩니다 — 로더가 import 시 쿠키→localStorage를 자동 화해하고 GlobalProvider가 themeName 변경 시 쿠키를 기록하므로 쿠키를 직접 쓰지 마세요.
71
+ 저장은 commonUILocalStorage.setItem(THEME_STORAGE_KEY, theme) (THEME_STORAGE_KEY='currentTheme'). 첫 렌더 전 복원은 localStorage 'opsnow-common-storage.currentTheme'(JSON 문자열)을 읽습니다.
72
+ - 컴포넌트 밖(유틸·상수)에서 현재 MUI 테마 객체가 필요하면 getCurrentTheme() — 컴포넌트 안에서는 useTheme()
73
+ - OpsnowCommonSelectItem · OpsnowCommonAutocompleteItem 은 컴포넌트가 아니라 items 원소 TS 타입입니다 (import type { OpsnowCommonSelectItem } from '@opsnow-common/opsnow-finops-common-ui-loader')
74
+
75
+ **CRITICAL: 날짜 표기 표준 — finOpsDateUtils 사용 (dayjs/moment/toLocaleString으로 직접 포맷 금지)**
76
+ 화면에 날짜·기간·일시·시간대를 표시할 때는 반드시 공통 utils의 표기 표준 함수를 씁니다 (@opsnow-common/opsnow-finops-common-utils ≥1.0.3 — package.json 확인).
77
+ DataGrid의 date 타입 컬럼·차트 X축은 이미 표준 포맷이 적용되므로 그 안에서는 쓰지 않습니다 (그리드 밖 텍스트·카드·필터 요약·파일명 등에 사용).
78
+
79
+ const { finOpsDateUtils } = useGlobalContext(); // import { useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
80
+
81
+ formatDate(v) → '2026-10-01' (값 없음/잘못된 값 → '-')
82
+ formatMonth(v) → '2026-10'
83
+ formatPeriod(start, end) → '2026-10-01 ~ 2026-10-07' (한쪽만 없으면 '- ~ 2026-10-13')
84
+ formatPeriod(start, end, { unit: 'month' }) → '2026-08 ~ 2026-10'
85
+ formatDateTime(v) → '2026-10-07 14:00 (UTC+9)' (시간대 기본 표시, 24시간제)
86
+ 옵션: seconds(초 표시) · inputUtc(입력값을 UTC로 해석 → 브라우저 시간대로 변환) · displayUtc(UTC로 표시) · showTimeZone(false면 시간대 생략)
87
+ getTimeZoneLabel() → '(UTC+9)' / getTimeZoneLabel({ displayUtc: true }) → '(UTC)' — 그리드 밖 표/카드 헤더에 시간대 한 번 표기
88
+ formatFileNameDate(v = 지금) → '20261016' — 다운로드 파일명 날짜
89
+
90
+ ⚠️ formatDateTime은 기본 inputUtc: false (입력값을 브라우저 시간으로 봄). 서버가 UTC로 주는 일시는 반드시 { inputUtc: true } — 그리드 date 컬럼(자동 UTC 해석)과 다르니 주의
91
+ ⚠️ 시간대를 표시했으면 같은 화면의 각 셀에는 showTimeZone: false로 생략하고 헤더에만 getTimeZoneLabel()을 붙입니다
92
+ ❌ 신규 코드 금지 (언어별로 포맷이 달라져 표기 표준 아님): getLocaleDate, getYyyyMmDdFormatDate, getLocaleNowDateForFileNameSuffix
93
+
94
+ **공통 헤더 (OpsnowFinopsCommonHeader, @opsnow-common/opsnow-finops-common-header)** — 앱 레이아웃에 헤더를 배치할 때만 해당
95
+ - noticeTypeLabels: 알림 팝업의 공지 타입 배지 라벨을 앱이 현재 언어로 번역해 주입합니다. 키는 noticeType 대문자:
96
+ noticeTypeLabels={{ NOTICE: '공지', RELEASE: '신규 소식', SERVICE_OUTAGE: '장애', EVENT: '이벤트', MAINTENANCE: '점검' }} // 실제로는 t('...') 결과
97
+ 주입하지 않은 키는 영어 기본값(Notice/Release/Service Outage/Event/Maintenance)으로 표시. 언어 전환 시 값도 바뀌도록 현재 locale 기준으로 넘기세요
98
+ - 공지 아이콘·팝업은 데스크톱 헤더에만 있습니다 (모바일 메뉴에는 공지 아이콘이 없음 — 모바일 전용 공지 진입점을 따로 만들지 마세요). 공지 자체를 끄려면 showNotice={false}
99
+ - 통화 전환은 헤더의 showCurrencySwitcher/currencySwitcherProps로 — getComponentSpec({ component: "CurrencySwitcher" }) 참고
100
+
60
101
  **CRITICAL: OpsnowCommonDataGrid Usage Rules**
61
102
 
62
103
  Before implementing OpsnowCommonDataGrid, you MUST use getUIExamples tool with 'DataGrid' parameter first!
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opsnow-mcp/opsnow-mcp-common-ui-server",
3
- "version": "1.0.41",
3
+ "version": "1.0.43",
4
4
  "type": "module",
5
5
  "main": "index.js",
6
6
  "bin": {