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

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.
@@ -18,12 +18,8 @@ export const XyMultiChartSchema = z.object({
18
18
  "xAxis": {
19
19
  "type": "date", // 축 타입: 'date' | 'category'
20
20
  "valueField": "date", // X축 값 필드
21
- "dateFormats": [ // xAxis type이 'date'일 때 사용
22
- {
23
- "type": "day", // 날짜 단위: 'day' | 'week' | 'month' | 'year'
24
- "dateFormat": "MM/dd" // amCharts5에서 지원하는 날짜 형식
25
- }
26
- ],
21
+ // ⚠️ "dateFormats"는 넣지 말 것 — X축 날짜는 표기 표준이 기본 적용됨 (축: 분·시 HH:mm / 일 MM-dd / 월 yyyy-MM / 년 yyyy, 툴팁: yyyy-MM-dd(HH:mm) / yyyy-MM).
22
+ // dateFormats를 지정하면 축·기간변경·툴팁 포맷이 모두 그 값으로 덮어써져 표준이 깨짐 ('MM/dd' 같은 값 금지)
27
23
  "baseInterval": { // xAxis type이 'date'일 때 사용
28
24
  "timeUnit": "day", // 시간 단위: 'day' | 'week' | 'month' | 'year'
29
25
  "count": 1 // 간격 수(1로 고정이며 변경 불가)
@@ -236,7 +232,7 @@ export const XyMultiChartSchema = z.object({
236
232
  // 범례 설정
237
233
  "legend": {
238
234
  "clickTarget": "none", // 범례 클릭 대상: "none" | "" (기본값: "none")
239
- "useExtension": true // 범례 확장 사용 여부 (기본값: true — 끄려면 false). 켜져 있으면 범례 전체 선택 체크박스 사용 가능
235
+ "useExtension": false // 범례 확장 사용 여부 (기본값: false — true를 명시해야 켜짐). 켜면 범례 펼치기/접기 + 전체 선택 체크박스 사용 가능. 범례가 많아 접어야 할 때만 true
240
236
  }
241
237
  }
242
238
  `),
@@ -402,6 +398,7 @@ export const XyMultiChartSchema = z.object({
402
398
  useOpsnowUs: z.boolean().optional().describe("OpsNow US 기본(basic) 색상 팔레트 사용 여부 (boolean, 기본값 true). false면 mix 팔레트를 사용합니다. chartCategoryColorByVendor가 지정되면 그 설정이 우선합니다."),
403
399
  chartNoRowsText: z.string().optional().describe("차트 데이터가 없을 때 표시할 텍스트 (string, 기본값 없음)"),
404
400
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
401
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
405
402
  });
406
403
  // opsnow-common-stack-chart
407
404
  export const StackChartSchema = z.object({
@@ -423,12 +420,8 @@ export const StackChartSchema = z.object({
423
420
  "xAxis": {
424
421
  "type": "date", // 축 타입: 'date' | 'value' | 'category' (바형 차트일 경우는 value 사용)
425
422
  "valueField": "date", // X축 값 필드 (컬럼형 차트일 경우 필수, 바형 차트일 경우 절대 생성하면 안됨)
426
- "dateFormats": [ // xAxis type이 'date'일 때 사용
427
- {
428
- "type": "day", // 날짜 단위: 'day' | 'week' | 'month' | 'year'
429
- "dateFormat": "MM/dd" // amCharts5에서 지원하는 날짜 형식
430
- }
431
- ],
423
+ // ⚠️ "dateFormats"는 넣지 말 것 — X축 날짜는 표기 표준이 기본 적용됨 (축: 분·시 HH:mm / 일 MM-dd / 월 yyyy-MM / 년 yyyy, 툴팁: yyyy-MM-dd(HH:mm) / yyyy-MM).
424
+ // dateFormats를 지정하면 축·기간변경·툴팁 포맷이 모두 그 값으로 덮어써져 표준이 깨짐 ('MM/dd' 같은 값 금지)
432
425
  "baseInterval": { // xAxis type이 'date'일 때 사용
433
426
  "timeUnit": "day", // 시간 단위: 'day' | 'week' | 'month' | 'year'
434
427
  "count": 1 // 간격 수(1로 고정이며 변경 불가)
@@ -537,7 +530,7 @@ export const StackChartSchema = z.object({
537
530
  // 범례 설정
538
531
  "legend": {
539
532
  "clickTarget": "none", // 범례 클릭 대상: "none" | "" (기본값: "none")
540
- "useExtension": true // 범례 확장 사용 여부 (기본값: true — 끄려면 false). 켜져 있으면 범례 전체 선택 체크박스 사용 가능
533
+ "useExtension": false // 범례 확장 사용 여부 (기본값: false — true를 명시해야 켜짐). 켜면 범례 펼치기/접기 + 전체 선택 체크박스 사용 가능. 범례가 많아 접어야 할 때만 true
541
534
  }
542
535
  }
543
536
  `),
@@ -739,6 +732,7 @@ export const StackChartSchema = z.object({
739
732
  .optional()
740
733
  .describe("차트 데이터가 없을 때 표시할 텍스트 (string, 기본값 없음)"),
741
734
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
735
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
742
736
  });
743
737
  // opsnow-common-bar-chart
744
738
  export const BarChartSchema = z.object({
@@ -760,12 +754,8 @@ export const BarChartSchema = z.object({
760
754
  "xAxis": {
761
755
  "type": "date", // 축 타입: 'date' | 'value' | 'category' (바형 차트일 경우는 value 사용)
762
756
  "valueField": "date", // X축 값 필드 (컬럼형 차트일 경우 필수, 바형 차트일 경우 절대 생성하면 안됨)
763
- "dateFormats": [ // xAxis type이 'date'일 때 사용
764
- {
765
- "type": "day", // 날짜 단위: 'day' | 'week' | 'month' | 'year'
766
- "dateFormat": "MM/dd" // amCharts5에서 지원하는 날짜 형식
767
- }
768
- ],
757
+ // ⚠️ "dateFormats"는 넣지 말 것 — X축 날짜는 표기 표준이 기본 적용됨 (축: 분·시 HH:mm / 일 MM-dd / 월 yyyy-MM / 년 yyyy, 툴팁: yyyy-MM-dd(HH:mm) / yyyy-MM).
758
+ // dateFormats를 지정하면 축·기간변경·툴팁 포맷이 모두 그 값으로 덮어써져 표준이 깨짐 ('MM/dd' 같은 값 금지)
769
759
  "baseInterval": { // xAxis type이 'date'일 때 사용
770
760
  "timeUnit": "day", // 시간 단위: 'day' | 'week' | 'month' | 'year'
771
761
  "count": 1 // 간격 수(1로 고정이며 변경 불가)
@@ -874,7 +864,7 @@ export const BarChartSchema = z.object({
874
864
  // 범례 설정
875
865
  "legend": {
876
866
  "clickTarget": "none", // 범례 클릭 대상: "none" | "" (기본값: "none")
877
- "useExtension": true // 범례 확장 사용 여부 (기본값: true — 끄려면 false). 켜져 있으면 범례 전체 선택 체크박스 사용 가능
867
+ "useExtension": false // 범례 확장 사용 여부 (기본값: false — true를 명시해야 켜짐). 켜면 범례 펼치기/접기 + 전체 선택 체크박스 사용 가능. 범례가 많아 접어야 할 때만 true
878
868
  }
879
869
  }
880
870
  `),
@@ -1068,6 +1058,7 @@ export const BarChartSchema = z.object({
1068
1058
  .optional()
1069
1059
  .describe("차트 데이터가 없을 때 표시할 텍스트 (string, 기본값 없음)"),
1070
1060
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
1061
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
1071
1062
  });
1072
1063
  // opsnow-common-line-chart
1073
1064
  export const LineChartSchema = z.object({
@@ -1089,12 +1080,8 @@ export const LineChartSchema = z.object({
1089
1080
  "xAxis": {
1090
1081
  "type": "category", // 축 타입: 'date' | 'value' | 'category'
1091
1082
  "valueField": "date", // X축 값 필드
1092
- "dateFormats": [ // xAxis type이 'date'일 때 사용
1093
- {
1094
- "type": "day", // 날짜 단위: 'day' | 'week' | 'month' | 'year'
1095
- "dateFormat": "MM/dd" // amCharts5에서 지원하는 날짜 형식
1096
- }
1097
- ],
1083
+ // ⚠️ "dateFormats"는 넣지 말 것 — X축 날짜는 표기 표준이 기본 적용됨 (축: 분·시 HH:mm / 일 MM-dd / 월 yyyy-MM / 년 yyyy, 툴팁: yyyy-MM-dd(HH:mm) / yyyy-MM).
1084
+ // dateFormats를 지정하면 축·기간변경·툴팁 포맷이 모두 그 값으로 덮어써져 표준이 깨짐 ('MM/dd' 같은 값 금지)
1098
1085
  "baseInterval": { // xAxis type이 'date'일 때 사용
1099
1086
  "timeUnit": "day", // 시간 단위: 'day' | 'week' | 'month' | 'year'
1100
1087
  "count": 1 // 간격 수(1로 고정이며 변경 불가)
@@ -1205,7 +1192,7 @@ export const LineChartSchema = z.object({
1205
1192
  // 범례 설정
1206
1193
  "legend": {
1207
1194
  "clickTarget": "none", // 범례 클릭 대상: "none" | "" (기본값: "none")
1208
- "useExtension": true // 범례 확장 사용 여부 (기본값: true — 끄려면 false). 켜져 있으면 범례 전체 선택 체크박스 사용 가능
1195
+ "useExtension": false // 범례 확장 사용 여부 (기본값: false — true를 명시해야 켜짐). 켜면 범례 펼치기/접기 + 전체 선택 체크박스 사용 가능. 범례가 많아 접어야 할 때만 true
1209
1196
  }
1210
1197
  }
1211
1198
  `),
@@ -1384,6 +1371,7 @@ export const LineChartSchema = z.object({
1384
1371
  .optional()
1385
1372
  .describe("OpsNow US 기본(basic) 색상 팔레트 사용 여부 (boolean, 기본값 true). false면 mix 팔레트를 사용합니다. chartCategoryColorByVendor가 지정되면 그 설정이 우선합니다."),
1386
1373
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
1374
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
1387
1375
  chartNoRowsText: z.string().optional().describe("차트 데이터가 없을 때 표시할 텍스트 (string, 기본값 없음)"),
1388
1376
  });
1389
1377
  // opsnow-common-pie-chart
@@ -1521,6 +1509,7 @@ export const PieChartSchema = z.object({
1521
1509
  ]`),
1522
1510
  useOpsnowUs: z.boolean().optional().describe("OpsNow US 기본(basic) 색상 팔레트 사용 여부 (boolean, 기본값 true). false면 mix 팔레트를 사용합니다. chartCategoryColorByVendor가 지정되면 그 설정이 우선합니다."),
1523
1511
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
1512
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
1524
1513
  chartNoRowsText: z.string().optional().describe("차트 데이터가 없을 때 표시할 텍스트 (string, 기본값 없음)"),
1525
1514
  chartLocaleMessage: z.array(z.object({
1526
1515
  name: z.string().describe("차트에서 사용하는 필드의 값 전체 또는 일부"),
@@ -1619,6 +1608,7 @@ export const GaugeChartSchema = z.object({
1619
1608
  { name: '사용량', locale: $t('usage') }
1620
1609
  ]`),
1621
1610
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
1611
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
1622
1612
  });
1623
1613
  // opsnow-common-heatmap-chart
1624
1614
  export const HeatmapChartSchema = z.object({
@@ -1782,6 +1772,7 @@ export const HeatmapChartSchema = z.object({
1782
1772
  ]`),
1783
1773
  langCd: z.enum(['ko', 'en', 'ja', 'zh', 'ar']).optional().describe("언어 코드"),
1784
1774
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부"),
1775
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
1785
1776
  onChartClick: z.string().optional().describe('셀 클릭 시 호출되는 콜백 함수(stringified). 클릭 시 { xField, yField, valueField, from: "heatmap" } 객체를 전달합니다.'),
1786
1777
  // 샘플(스켈레톤) 차트 설정 — chartProps 없이 chartSample* 계열만 전달하면 실데이터 로딩 전 미리보기(스켈레톤) 차트가 렌더링됩니다.
1787
1778
  chartSampleProps: z.object({}).optional().describe("샘플(스켈레톤) 차트 속성 (object, 기본값 없음). chartProps와 동일한 구조의 JSON입니다. chartProps 없이 chartSampleProps만 전달하면 차트가 샘플(미리보기/스켈레톤) 모드로 렌더링됩니다."),
@@ -1898,6 +1889,7 @@ export const BubbleChartSchema = z.object({
1898
1889
  locale: z.string()
1899
1890
  })).optional().describe("샘플 차트 데이터 다국어 적용 목록 (object[], 기본값 없음). chartLocaleData와 동일한 구조이며 샘플(스켈레톤) 모드에서 사용됩니다."),
1900
1891
  isDarkMode: z.boolean().optional().describe("다크 모드 활성화 여부 (boolean, 기본값 없음 — 미지정 시 MUI 테마의 palette.mode를 따릅니다)"),
1892
+ useSafeResolution: z.boolean().optional().describe("iOS 캔버스 메모리 제한 회피용 — true면 해상도 1(devicePixelRatio 무시)로 렌더링 (boolean, 기본값 false). iPhone/iPad 사파리에서 차트가 하얗게 비거나 깨질 때, 또는 한 화면에 차트가 많을 때 사용. 화질이 약간 흐려지므로 필요한 화면에만"),
1901
1893
  chartNoRowsText: z.string().optional().describe("차트 데이터가 없을 때 표시할 텍스트 (string, 기본값 없음)"),
1902
1894
  chartTooltipDetailText: z.string().optional().describe("툴팁에서 보여주는 상세 텍스트"),
1903
1895
  chartLocaleData: z.array(z.object({
@@ -1940,6 +1932,8 @@ export function createChartComponent() {
1940
1932
  props.push(`chartLocaleMessage={${JSON.stringify(args.chartLocaleMessage)}}`);
1941
1933
  if (args.isDarkMode !== undefined)
1942
1934
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
1935
+ if (args.useSafeResolution !== undefined)
1936
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
1943
1937
  const code = `<OpsnowCommonGaugeChart ${props.join(' ')} />`;
1944
1938
  return {
1945
1939
  content: [
@@ -2002,6 +1996,8 @@ export function createChartComponent() {
2002
1996
  props.push(`chartUserDefinedFunc={${jsxExpr(args.chartUserDefinedFunc)}}`);
2003
1997
  if (args.isDarkMode !== undefined)
2004
1998
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
1999
+ if (args.useSafeResolution !== undefined)
2000
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2005
2001
  if (args.chartNoRowsText)
2006
2002
  props.push(`chartNoRowsText="${args.chartNoRowsText}"`);
2007
2003
  if (args.chartLocaleMessage)
@@ -2089,6 +2085,8 @@ export function createChartComponent() {
2089
2085
  props.push(`langCd="${args.langCd}"`);
2090
2086
  if (args.isDarkMode !== undefined)
2091
2087
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
2088
+ if (args.useSafeResolution !== undefined)
2089
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2092
2090
  if (args.chartNoRowsText)
2093
2091
  props.push(`chartNoRowsText="${args.chartNoRowsText}"`);
2094
2092
  const code = `<OpsnowCommonLineChart ${props.join(' ')} />`;
@@ -2177,6 +2175,8 @@ export function createChartComponent() {
2177
2175
  props.push(`onTopNPopupDetailClick={${jsxExpr(args.onTopNPopupDetailClick)}}`);
2178
2176
  if (args.isDarkMode !== undefined)
2179
2177
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
2178
+ if (args.useSafeResolution !== undefined)
2179
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2180
2180
  const code = `<OpsnowCommonBarChart ${props.join(' ')} />`;
2181
2181
  return {
2182
2182
  content: [
@@ -2264,6 +2264,8 @@ export function createChartComponent() {
2264
2264
  props.push(`onTopNPopupDetailClick={${jsxExpr(args.onTopNPopupDetailClick)}}`);
2265
2265
  if (args.isDarkMode !== undefined)
2266
2266
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
2267
+ if (args.useSafeResolution !== undefined)
2268
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2267
2269
  const code = `<OpsnowCommonStackChart ${props.join(' ')} />`;
2268
2270
  return {
2269
2271
  content: [
@@ -2354,6 +2356,8 @@ export function createChartComponent() {
2354
2356
  props.push(`chartFoldLegend="${args.chartFoldLegend}"`);
2355
2357
  if (args.isDarkMode !== undefined)
2356
2358
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
2359
+ if (args.useSafeResolution !== undefined)
2360
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2357
2361
  const code = `<OpsnowCommonXyMultiChart ${props.join(' ')} />`;
2358
2362
  return {
2359
2363
  content: [
@@ -2401,6 +2405,8 @@ export function createChartComponent() {
2401
2405
  props.push(`langCd="${args.langCd}"`);
2402
2406
  if (args.isDarkMode !== undefined)
2403
2407
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
2408
+ if (args.useSafeResolution !== undefined)
2409
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2404
2410
  if (args.onChartClick)
2405
2411
  props.push(`onChartClick={${jsxExpr(args.onChartClick)}}`);
2406
2412
  if (args.chartSampleProps)
@@ -2472,6 +2478,8 @@ export function createChartComponent() {
2472
2478
  props.push(`chartSampleLocaleData={${jsxExpr(args.chartSampleLocaleData)}}`);
2473
2479
  if (args.isDarkMode !== undefined)
2474
2480
  props.push(`isDarkMode={${jsxExpr(args.isDarkMode)}}`);
2481
+ if (args.useSafeResolution !== undefined)
2482
+ props.push(`useSafeResolution={${jsxExpr(args.useSafeResolution)}}`);
2475
2483
  if (args.chartNoRowsText)
2476
2484
  props.push(`chartNoRowsText="${args.chartNoRowsText}"`);
2477
2485
  if (args.chartTooltipDetailText)
@@ -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.42",
4
4
  "type": "module",
5
5
  "main": "index.js",
6
6
  "bin": {