@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.35 → 1.0.37

package/build/components/examples/opsnow-common-forms-examples-data.js

@@ -1609,8 +1609,72 @@ const handleDownload = useCallback(() => {
 ];
 export const CurrencySwitcherExamples = [
     {
-        title: 'basic-currency-switcher',
-        code: `const { OpsnowCommonCurrencySwitcher } = useCommonComponents()
+        title: 'header-currency-switcher',
+        code: `// 공통 헤더(header)에서 사용법 — 기본 배선
+// 헤더는 통화 상태/환율 데이터를 갖지 않는다 — 앱이 관리해 props로 주입한다
+import OpsnowFinopsCommonHeader from '@opsnow-common/opsnow-finops-common-header'
+
+const [currency, setCurrency] = useState('USD')
+const [historyQuery, setHistoryQuery] = useState({ currency: 'USD', period: 6 })
+const historySeries = useMemo(
+  () => buildSeries(historyQuery.currency, historyQuery.period), // 실사용: BE 조회
+  [historyQuery]
+)
+
+// 통화 전환 적용 대상: 개요(OverView) · 비용 분석(Analytics) · 청구 내역(Billing Invoice) · 비용 배분(Cost Allocation)
+// 그 외 메뉴에서는 currencySwitcherEnabled={false} → 버튼 disabled + 호버 시 안내 툴팁
+const CURRENCY_ENABLED_ROUTES = [
+  '/overview',                      // 개요
+  '/cost/analytics/usage-charges',  // 비용 분석
+  '/cost/billing-invoice',          // 청구 내역
+  '/settings/cost-allocation',      // 비용 배분 (하위 경로 포함)
+]
+const isCurrencyEnabledPath = CURRENCY_ENABLED_ROUTES.some(
+  (route) => location.pathname === route || location.pathname.startsWith(route + '/')
+)
+
+<OpsnowFinopsCommonHeader
+  menuList={headerMenuList}
+  /* …로고 · 도움말 · 언어 · 테마 토글 등 다른 헤더 props는 기존 코드 유지… */
+
+  showCurrencySwitcher                              // 헤더에 스위처 노출
+  currencySwitcherEnabled={isCurrencyEnabledPath}   // 적용 대상 메뉴 여부
+  currencySwitcherProps={{                          // dropdown 컴포넌트로 그대로 전달
+    value: currency,
+    onChange: code => setCurrency(code),
+    rateInfo,                                       // BE 환율 API 응답
+    historySeries,
+    onHistoryQueryChange: (code, months) => {
+      setHistoryQuery({ currency: code, period: months })
+    },
+  }}
+/>`,
+        description: "공통 헤더(header)에서 사용법 — 기본 배선 예제입니다. 선택 통화·히스토리 조회 조건은 앱 상태로 관리하고, 적용 대상 메뉴 여부는 currencySwitcherEnabled로 넘깁니다. 통화 변경은 '개요(OverView)'·'비용 분석(Analytics)'·'청구 내역(Billing Invoice)'·'비용 배분(Cost Allocation)' 4개 메뉴에서만 활성화하고, 그 외 메뉴에서는 currencySwitcherEnabled={false}로 버튼을 disabled 처리해 호버 시 안내 툴팁이 뜨게 합니다. 헤더는 AI 버튼~알림 벨 사이 자리만 제공하고 상태·환율 데이터를 갖지 않으므로, 앱이 currencySwitcherProps로 주입한 값이 내부 OpsnowCommonCurrencySwitcher에 그대로 전달됩니다(단독 사용 시 props 규칙 동일 적용). 주의: 이 MCP는 헤더 props 중 통화 전환 관련 4개(showCurrencySwitcher/currencySwitcherEnabled/currencySwitcherProps/currencySwitcherDisabledTooltip)만 안내하며, menuList·로고·도움말·언어·테마 토글 등 헤더의 다른 props는 제공하지 않습니다 — 프로젝트의 기존 헤더 코드를 유지한 채 통화 관련 props만 추가하세요. [검색 키워드: 헤더 통화 전환, 공통 헤더, header currency, 헤더에서 사용법, GNB 통화, showCurrencySwitcher]"
+    },
+    {
+        title: 'header-multi-csp-currency-switcher',
+        code: `// 공통 헤더(header)에서 사용법 — 멀티 CSP(수집 통화 혼재) 조합
+// 'multi-csp-native-currency' 예제와 같은 props를 currencySwitcherProps 안에 그대로 넣으면 된다
+<OpsnowFinopsCommonHeader
+  showCurrencySwitcher
+  currencySwitcherProps={{
+    value: currency,
+    onChange: setCurrency,
+    rateInfo: multiCspRateInfo,                     // details.USD 에 CSP 별 환산 환율
+    historySeries,
+    onHistoryQueryChange: refetchHistory,
+
+    nativeCurrency: 'KRW',                          // 무환산(수집) 통화
+  }}
+  // 적용 대상 외 메뉴에서 뜨는 안내 문구를 앱 문구로 덮어쓰기
+  currencySwitcherDisabledTooltip={t('header.currencyNotSupported')}
+/>`,
+        description: "공통 헤더(header)에서 사용법 — 멀티 CSP(수집 통화 혼재) 조합 예제입니다. 'multi-csp-native-currency' 예제와 같은 props(nativeCurrency 포함)를 currencySwitcherProps 안에 그대로 넣으면 되고, 비활성 안내 문구는 currencySwitcherDisabledTooltip으로 앱 번역으로 덮어쓸 수 있습니다. [검색 키워드: 헤더 멀티 CSP, 헤더 통화 전환, 헤더에서 사용법, 수집 통화, currencySwitcherDisabledTooltip]"
+    },
+    {
+        title: 'standalone-props-reference',
+        code: `// ⚠️ 단독 배치는 props 참고용 — 실서비스 배치는 header-currency-switcher 예제 사용
+const { OpsnowCommonCurrencySwitcher } = useCommonComponents()
 
 const [currency, setCurrency] = useState('USD')
 const [appliedRate, setAppliedRate] = useState(1)
@@ -1622,7 +1686,7 @@ const rateInfo = {
   source: '한국수출입은행',            // 출처 (선택)
   rates: { USD: 1, KRW: 1450, JPY: 156.58, VND: 25508, AED: 3.67 }, // 기준 통화(USD) 1단위당 대표 환율
   details: {                         // (선택) 통화별 Payer/Invoice 상세 환율
-    KRW: [                           // 2건 이상이면 '다중 환율' — 배지 · 현재 적용 환율 목록 · 히스토리 팝업
+    KRW: [                           // 2건 이상이면 '다중 환율' — 'N개 환율' 배지 · 히스토리 다중 시리즈
       { payer: 'Payer 1234', invoice: 'Invoice 0000', rate: 1450 },
       { payer: 'Payer 5678', invoice: 'Invoice 9999', rate: 1462 },
     ],
@@ -1638,19 +1702,17 @@ const rateInfo = {
   rateInfo={rateInfo}
   historySeries={historySeries}
   onHistoryQueryChange={(code, months) => {
-    // 히스토리 열림/팝업 통화·기간 셀렉트 변경 시 통지 → BE 재조회 후 주입
-    // historySeries: [{ name, label?, current?, points: [{ label, rate }, ...] }, ...]
+    // 팝오버 열림·통화 선택·기간 셀렉트 변경 시 통지 → BE 재조회 후 주입
+    // historySeries: [{ name, label?, currency?, points: [{ label, rate }, ...] }, ...]
     fetchHistory(code, months).then(setHistorySeries)
   }}
-  onCustomRateChange={(rate, context) => {
-    // what-if 시뮬레이션 값 (저장되지 않음, onChange 미호출)
-  }}
 />`,
-        description: '통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 기본 예제입니다. 환율 데이터는 컴포넌트가 조회하지 않으므로 BE 환율 API 응답을 rateInfo/historySeries props로 주입하고, onHistoryQueryChange(currency, months)로 조회 조건을 통지받아 재조회합니다. rateInfo.details가 2건 이상인 통화는 다중 환율로 취급되어 히스토리가 화면 중앙 팝업(차트/테이블)으로 열리고, 단일 환율·기준 통화는 팝오버 안 인라인 차트로 열립니다. [검색 키워드: 통화 전환, 환율, 환율 필터, 통화 필터, 통화 변환, 환율 히스토리, 다중 환율, currency, exchange rate]'
+        description: '통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 props 참고용 예제입니다 (⚠️ 실서비스 배치는 header-currency-switcher 예제처럼 공통 헤더로). 환율 데이터는 컴포넌트가 조회하지 않으므로 BE 환율 API 응답을 rateInfo/historySeries props로 주입하고, onHistoryQueryChange(currency, months)로 조회 조건을 통지받아 재조회합니다. 히스토리는 팝오버 하단에 상시 인라인으로 노출되며(추가 팝업 없음) 기본은 최근 6개월 테이블(연월=컬럼, Payer/Invoice=행), 차트 뷰로 전환하면 범례 클릭으로 시리즈를 필터링합니다. [검색 키워드: 통화 전환, 환율, 환율 필터, 통화 필터, 통화 변환, 환율 히스토리, 다중 환율, currency, exchange rate]'
     },
     {
-        title: 'custom-options-no-detail',
-        code: `<OpsnowCommonCurrencySwitcher
+        title: 'custom-options-no-history',
+        code: `// ⚠️ 단독 배치는 props 참고용 — 실서비스 배치는 header-currency-switcher 예제 사용
+<OpsnowCommonCurrencySwitcher
   value={currency}
   onChange={handleCurrencyChange}
   rateInfo={rateInfo}
@@ -1661,11 +1723,38 @@ const rateInfo = {
   ]}
   baseCurrency="USD"
   size="small"
-  showDetail={false}
   showHistory={false}
 />`,
-        description: '팝오버 통화 목록을 커스텀하고 환율 설정(시뮬레이션)·히스토리 없이 small 크기 트리거로 사용하는 예제입니다.'
-    }
+        description: '팝오버 통화 목록을 커스텀하고 하단 히스토리 섹션 없이(showHistory=false, 통화 목록만 노출) small 크기 트리거로 사용하는 예제입니다.'
+    },
+    {
+        title: 'multi-csp-native-currency',
+        code: `// ⚠️ 단독 배치는 props 참고용 — 실서비스 배치는 header-multi-csp-currency-switcher 예제 사용
+// 수집 통화가 CSP별로 다른 회사 (AWS=USD, Azure/GCP=KRW 수집)
+// USD로 '보는' 것 자체가 KRW 환율로 나누는 환산이므로 details를 기준 통화 키(USD)에 담고
+// 행마다 currency 필드로 행 단위 통화를 표기, 무환산 문구는 nativeCurrency='KRW' 행에 붙음
+const multiCspRateInfo = {
+  baseDate: '2026-07-08',
+  source: '한국수출입은행',
+  rates: { USD: 1, KRW: 1508.8, JPY: 156.58 },
+  details: {
+    USD: [
+      { payer: 'Azure', invoice: 'Invoice 1111', rate: 1508.8, currency: 'KRW' },
+      { payer: 'GCP', invoice: 'Invoice 2222', rate: 1512.3, currency: 'KRW' },
+    ],
+  },
+}
+
+<OpsnowCommonCurrencySwitcher
+  value={currency}
+  onChange={handleCurrencyChange}
+  rateInfo={multiCspRateInfo}
+  historySeries={historySeries}             // 시리즈에도 currency: 'KRW' 를 담아 행 라벨에 병기
+  onHistoryQueryChange={handleHistoryQueryChange}
+  nativeCurrency="KRW"                      // 무환산(수집) 통화 — 앵커(baseCurrency=USD)와 분리
+/>`,
+        description: "수집 통화 분리 — 멀티 CSP 혼재 예제입니다. 기준 통화(USD)는 환율 앵커로 유지하되 '변환 없음(Default)' 문구는 nativeCurrency='KRW' 행에 붙습니다. USD 행에는 'N개 환율' 배지가 붙고, 히스토리 테이블 행 라벨에는 실제 환산 통화가 'Azure · Invoice 1111 (KRW)'처럼 병기됩니다 — USD로 보는 것 자체가 KRW 환율로 나누는 환산이기 때문입니다. 시리즈에도 currency 필드를 담아 주입하세요. [검색 키워드: 멀티 CSP, 수집 통화, 무환산, nativeCurrency, 행 단위 통화]"
+    },
 ];
 export const ToggleButtonExamples = [
     {

package/build/components/opsnow-common-forms.js

@@ -290,26 +290,32 @@ export const InsightContentSchema = z.object({
     emptyMessage: z.string().optional().describe("insightText가 없을 때 표시할 빈 메시지"),
     sx: z.string().optional().describe("MUI sx 스타일 객체(JSX/문자열)"),
 });
-// CurrencySwitcher 컴포넌트 관련 스키마 정의 (통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리, opsnow-common-dropdown >= 1.0.29)
+// CurrencySwitcher 컴포넌트 관련 스키마 정의 (통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 — 히스토리는 팝오버 하단 인라인)
+// 공통 헤더(OpsnowFinopsCommonHeader) 배선은 헤더의 props(showCurrencySwitcher 등)라 이 스키마에 없음 — createCurrencySwitcher description·헤더 예제 참고
 export const CurrencySwitcherSchema = z.object({
     value: z.string().describe("현재 표시 통화 코드 상태 변수명 (controlled, 예: currency)"),
     onChange: z.string().describe("통화 선택 시 호출되는 핸들러 함수명 — (currency, rate) => void 형태, rate는 기준 통화 1단위당 대표 환율 (예: handleCurrencyChange)"),
-    rateInfo: z.string().optional().describe("기준일 환율 정보 객체 변수명 — { baseDate, source?, rates, details? } 형태로 BE 환율 API 응답을 주입. details는 통화별 Payer/Invoice 상세 환율(Array<{ payer, invoice?, rate }>)로 2건 이상이면 다중 환율 통화로 취급 (없으면 목록에 환율이 '-'로 표시, 예: rateInfo)"),
-    historySeries: z.string().optional().describe("환율 히스토리 시리즈 배열 변수명 (controlled) — Array<{ name, label?, current?, points: Array<{ label, rate }> }>, onHistoryQueryChange로 통지받은 조건 기준으로 BE 재조회 후 주입. 인라인 차트는 첫 번째 시리즈(대표 환율)만 사용 (예: historySeries)"),
-    onHistoryQueryChange: z.string().optional().describe("히스토리 조회 조건 통지 핸들러 함수명 — (currency, months) => void 형태, 히스토리 열림/팝업 통화·기간 셀렉트 변경 시 호출 → 소비 측이 BE 재조회 후 historySeries 갱신 (예: handleHistoryQueryChange)"),
-    historyPeriodOptions: z.string().optional().describe("히스토리 팝업 기간 옵션 배열 변수명 — number[] (기본값: [6, 12, 24])"),
-    defaultHistoryPeriod: z.number().optional().describe("히스토리 기본 조회 기간(개월, 기본값: 24)"),
+    rateInfo: z.string().optional().describe("기준일 환율 정보 객체 변수명 — { baseDate, source?, rates, details? } 형태로 BE 환율 API 응답을 주입. details는 통화별 Payer/Invoice 상세 환율(Array<{ payer, invoice?, rate, currency? }>)로 2건 이상이면 다중 환율 통화로 취급('N개 환율' 배지, 없으면 목록에 환율이 '-'로 표시). 수집 통화가 CSP별로 다른 멀티 CSP 케이스는 details를 기준 통화 키(details.USD)에 담고 행마다 currency 필드로 행 단위 통화를 표기 — nativeCurrency와 함께 사용 (예: rateInfo)"),
+    historySeries: z.string().optional().describe("환율 히스토리 시리즈 배열 변수명 (controlled) — Array<{ name, label?, currency?, points: Array<{ label, rate }> }>, onHistoryQueryChange로 통지받은 조건 기준으로 BE 재조회 후 주입. 테이블 뷰는 전체 시리즈를 행으로, 차트 뷰는 범례에서 선택된 시리즈만 표시. 시리즈 순서가 곧 테이블 행 순서·색상 순서이므로 대표 환율을 첫 번째로 정렬 (예: historySeries)"),
+    onHistoryQueryChange: z.string().optional().describe("히스토리 조회 조건 통지 핸들러 함수명 — (currency, months) => void 형태, 팝오버 열림·통화 선택·기간 셀렉트 변경 시 호출 → 소비 측이 BE 재조회 후 historySeries 갱신 (예: handleHistoryQueryChange)"),
+    historyPeriodOptions: z.string().optional().describe("히스토리 기간 옵션 배열 변수명 — number[] (기본값: [6, 12, 24])"),
+    defaultHistoryPeriod: z.number().optional().describe("히스토리 기본 조회 기간(개월, 기본값: 6)"),
     currencyOptions: z.string().optional().describe("팝오버 통화 목록 배열 변수명 — Array<{ code, symbol, digits? }> (기본: USD/KRW/JPY/VND/AED)"),
-    baseCurrency: z.string().optional().describe("변환 기준 통화 코드 (기본값: 'USD')"),
-    defaultTargetCurrency: z.string().optional().describe("기준 통화 선택 중일 때 환율 설정이 다룰 초기 비교 통화 코드"),
-    customRate: z.string().optional().describe("직접 입력 시뮬레이션 환율 상태 변수명 (number | null, controlled 모드 — 미지정 시 내부 관리)"),
-    onCustomRateChange: z.string().optional().describe("직접 입력 환율 변경 핸들러 함수명 — (rate, context) => void 형태, 저장되지 않는 what-if 값 통지 (onChange는 호출되지 않음)"),
-    showDetail: z.boolean().optional().describe("환율 설정(직접 입력 시뮬레이션) 섹션 노출 여부 (기본값: true)"),
-    showHistory: z.boolean().optional().describe("월별 환율 히스토리 링크·인라인 차트·팝업 노출 여부 (기본값: true)"),
-    renderChart: z.string().optional().describe("히스토리 팝업 차트 교체 슬롯 함수명 — (series, currency) => ReactNode 형태, 체크된(보이는) 시리즈만 전달 (기본: 내장 SVG 멀티라인 차트)"),
-    labels: z.string().optional().describe("문구 개별 커스텀 객체 변수명 — Partial<CurrencySwitcherLabels>, i18n(ko/en/ja) 번역 위에 항목별로 덮어씀 ({placeholder} 템플릿 치환 지원)"),
+    baseCurrency: z.string().optional().describe("변환 기준 통화 코드 — 환율이 '1 {base} = X'로 저장되는 앵커. 무환산 표기와는 별개 개념(nativeCurrency 참고) (기본값: 'USD')"),
+    nativeCurrency: z.string().optional().describe("무환산(수집) 통화 코드 — '변환 없음(Default)' 문구가 붙는 행. 수집 통화가 기준 통화와 다른 멀티 CSP 조합(예: Azure/GCP KRW 수집)에서 baseCurrency(환율 앵커)와 분리 지정 (기본값: baseCurrency)"),
+    showHistory: z.boolean().optional().describe("팝오버 하단 히스토리 섹션 노출 여부 (기본값: true)"),
+    renderChart: z.string().optional().describe("히스토리 차트 뷰 교체 슬롯 함수명 — (series, currency) => ReactNode 형태, 범례에서 선택된(보이는) 시리즈만 전달 (기본: 내장 SVG 멀티라인 차트)"),
+    labels: z.string().optional().describe("문구 개별 커스텀 객체 변수명 — Partial<CurrencySwitcherLabels>, 우선순위 labels > 앱 i18n 리소스(common.currency_switcher.*) > 패키지 내장 ko/en/ja ({placeholder} 템플릿 치환 지원). 기준 통화 행 문구는 baseCurrencyDescription, 히스토리 테이블 첫 컬럼 머리는 payerColumnLabel 키로 교체"),
     size: z.enum(["small", "medium"]).optional().describe("트리거 크기"),
     disabled: z.boolean().optional().describe("비활성화 여부"),
+    // [다음 버전 재도입 예정] 환율 설정(직접 입력 · 시뮬레이션) 영역 props — dropdown 컴포넌트 쪽
+    // '[다음 버전 재도입 예정]' 주석 블록이 되살아나면 아래 주석 해제 (핸들러 쪽 주석 블록도 함께)
+    // defaultTargetCurrency: z.string().optional().describe("기준 통화 선택 중일 때 환율 설정이 다룰 초기 비교 통화 코드"),
+    // simulationTarget: z.string().optional().describe("환율 설정(시뮬레이션) 대상 지정 객체 변수명 — { currency, payer?, invoice? } 형태, 기준 통화 뷰에서 실제 환산되는 CSP(Payer)로 고정하며 payer/invoice 일치 행이 사전 선택됨 (예: simulationTarget)"),
+    // customRate: z.string().optional().describe("직접 입력 시뮬레이션 환율 상태 변수명 (number | null, controlled 모드 — 미지정 시 내부 관리)"),
+    // onCustomRateChange: z.string().optional().describe("직접 입력 환율 변경 핸들러 함수명 — (rate, context) => void 형태, 저장되지 않는 what-if 값 통지 (onChange는 호출되지 않음)"),
+    // showDetail: z.boolean().optional().describe("환율 설정(직접 입력 시뮬레이션) 섹션 노출 여부 (기본값: true)"),
+    // historyMode: z.enum(["auto", "popup"]).optional().describe("히스토리 열림 방식 — 'popup'이면 항상 화면 중앙 팝업, 'auto'는 다중 환율=팝업/단일 환율·기준 통화=인라인 분기 (기본값: 'auto')"),
 });
 // Forms 컴포넌트 함수 - 배열 반환
 export function createFormsComponent() {
@@ -560,7 +566,7 @@ export function createFormsComponent() {
                     props.push(`adornmentIconName=\"${args.adornmentIconName}\"`);
                 if (args.adornmentPosition)
                     props.push(`adornmentPosition=\"${args.adornmentPosition}\"`);
-                // readOnly는 톱레벨 prop이 아니라 inputProps 경로로만 동작 (MUI 7: rest prop은 FormControl로 가서 input에 미도달)
+                // readOnly는 톱레벨 prop이 아니라 inputProps 경로로만 동작 (MUI: rest prop은 FormControl로 가서 input에 미도달)
                 if (args.readOnly && !args.inputProps)
                     props.push(`inputProps={{ readOnly: true }}`);
                 if (args.adornmentLabelColor)
@@ -1117,73 +1123,109 @@ export function createFormsComponent() {
         },
         {
             name: "createCurrencySwitcher",
-            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리, 환율/통화 필터로 사용 (opsnow-common-dropdown >= 1.0.29)
+            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 — ⚠️ 실서비스 배치는 반드시 공통 헤더(OpsnowFinopsCommonHeader)의 currencySwitcherProps로만
+
+      ⚠️ **배치 규칙: 실서비스에서는 반드시 OpsnowFinopsCommonHeader의 currencySwitcherProps로만 배치합니다. 단독 \`<OpsnowCommonCurrencySwitcher>\` 사용은 props 참고용 데모에 한합니다.**
 
       트리거에 현재 선택된 통화가 표시되고, 클릭하면 팝오버에서 적용 환율 기준일 안내와
       통화 목록(클릭 시 즉시 적용)을 제공합니다. Payer/Invoice별 환율이 여러 개인 통화는
-      'N개 환율' 배지와 '현재 적용 환율' 목록이 표시되고, 환율 설정에서 Payer를 골라
-      what-if 시뮬레이션을 입력할 수 있습니다.
+      'N개 환율' 배지가 표시됩니다. 팝오버 하단에 월별 환율 히스토리가 상시 인라인으로
+      노출되며(추가 팝업 없음), 기본은 최근 6개월 테이블(연월=컬럼, Payer/Invoice=행)이고
+      차트 뷰로 전환하면 하단 범례 클릭으로 시리즈를 필터링할 수 있습니다.
 
       **데이터 주입 규칙 (중요):**
       - 환율 데이터는 컴포넌트가 조회하지 않습니다 — BE 환율 API 응답을 rateInfo / historySeries props로 주입하고, 조회 조건이 바뀌면 onHistoryQueryChange(currency, months)로 통지받아 재조회하세요.
       - rateInfo: { baseDate: 'YYYY-MM-DD', source?: '출처', rates: { USD: 1, KRW: 1450, ... }, details?: { KRW: [{ payer, invoice?, rate }, ...] } } — 기준 통화 1단위당 환율, details의 통화별 배열이 2건 이상이면 다중 환율 통화로 취급
-      - historySeries: [{ name, label?, current?, points: [{ label, rate }, ...] }, ...] — 모든 시리즈는 같은 월 구간으로 정렬, 대표 환율이 첫 번째 시리즈가 되도록 정렬 (인라인 차트는 첫 번째 시리즈만 사용)
+      - 멀티 CSP(수집 통화 혼재, 예: AWS=USD·Azure/GCP=KRW 수집): details를 기준 통화 키에 담고 행마다 currency 필드로 행 단위 통화 표기 — details: { USD: [{ payer: 'Azure', rate: 1508.8, currency: 'KRW' }, ...] }, nativeCurrency='KRW'와 함께 사용. 히스토리 시리즈에도 currency: 'KRW'를 담으면 테이블 행 라벨에 'Azure · Invoice 1111 (KRW)'처럼 병기됩니다
+      - historySeries: [{ name, label?, currency?, points: [{ label, rate }, ...] }, ...] — 모든 시리즈는 같은 월 구간으로 정렬(테이블 컬럼은 가장 긴 시리즈의 연월 기준), 시리즈 순서가 곧 테이블 행 순서·색상 순서이므로 대표 환율이 첫 번째가 되도록 정렬
       - BE API 호출 시 axios 직접 import 금지 — getAxios() 공통 axios 사용
 
-      **히스토리 동작 분기 규칙:**
-      - 다중 환율 통화(details 2건 이상): 화면 중앙 팝업(차트/테이블 전환, Payer/Invoice 검색·체크박스) — Payer/Invoice별 전체 시리즈 표시
-      - 단일 환율 통화·기준 통화: 팝오버 안 인라인 차트 펼침/접힘(팝업 없음) — 첫 번째 시리즈(대표 환율)만 표시
+      **히스토리 표기 규칙:**
+
+      | 상황 | 히스토리 표기 | 조회 통화 | 표시 시리즈 |
+      |------|------|------|------|
+      | 팝오버 열림 (통화·환율 수 무관) | 하단에 히스토리 섹션 상시 노출 — 추가 팝업 없음, 기본 뷰는 테이블 | 선택 통화 | 주입 시리즈 전체 |
+      | 테이블 뷰 (기본) | 연월이 컬럼 헤더, Payer/Invoice가 행. 첫 컬럼은 고정되고 12/24개월은 가로 스크롤 | 선택 통화 | 주입 시리즈 전체 (범례 필터 영향 없음) |
+      | 차트 뷰 | 멀티라인 차트 + 하단 범례. 범례 클릭 시 해당 시리즈가 차트에서 빠짐 (필터링) | 선택 통화 | 범례에서 선택된 시리즈만 |
+      | 통화 변경 · 기간 변경 | onHistoryQueryChange(통화, 개월) 통지 → 소비자가 historySeries 갱신. 통화가 바뀌면 범례 필터 초기화 | 새 선택 통화 | 재조회 결과 |
 
       **동작 규칙:**
       - 통화 선택 시 onChange(currency, rate)가 호출됩니다 — 금액 표시 변환은 소비 프로젝트에서 rate로 처리
-      - 직접 입력 환율은 저장되지 않는 what-if 시뮬레이션 값으로 onCustomRateChange(rate, context)로만 통지되며, onChange(실제 적용)는 호출되지 않습니다
-      - 문구는 i18n 현재 언어(ko/en/ja)를 자동으로 따르고, labels prop으로 항목별 커스텀 가능
+      - 문구는 i18n 현재 언어(ko/en/ja)를 자동으로 따르고, labels prop으로 항목별 커스텀 가능 (우선순위: labels > 앱 i18n 리소스 common.currency_switcher.* > 패키지 내장 문구. 기준 통화 행 문구는 baseCurrencyDescription, 히스토리 테이블 첫 컬럼 머리는 payerColumnLabel 키)
+
+      **공통 헤더에서 쓰기 (OpsnowFinopsCommonHeader):**
+      - 실서비스 배치는 **무조건 공통 헤더를 통해서** 합니다 — 페이지 본문에 단독 배치하지 마세요 (단독 예제는 props 사용법 참고용)
+      - 헤더는 AI 버튼~알림 벨 사이 자리만 제공하고 상태·환율 데이터를 갖지 않습니다 — 앱이 관리하는 값을 currencySwitcherProps로 주입하면 내부 OpsnowCommonCurrencySwitcher에 그대로 전달됩니다 (위 props 규칙 동일 적용)      - **활성/비활성 정책**: 통화 변경은 '개요(OverView)' · '비용 분석(Analytics)' · '청구 내역(Billing Invoice)' · '비용 배분(Cost Allocation)' 4개 메뉴에서만 허용됩니다 — 그 외 메뉴 진입 시 currencySwitcherEnabled={false}로 넘겨 버튼을 disabled 상태로 노출하고, 호버 시 안내 툴팁이 표시됩니다 (문구는 내장 ko/en/ja 기본, currencySwitcherDisabledTooltip으로 덮어쓰기 가능). 적용 라우트: '/overview' · '/cost/analytics/usage-charges' · '/cost/billing-invoice' · '/settings/cost-allocation'(하위 경로 포함) — 현재 라우트가 여기에 속하는지를 앱에서 판단해 주입하세요
+
+      헤더 전용 Props:
+
+      | 이름 | 타입 | 기본값 | 설명 |
+      |------|------|--------|------|
+      | showCurrencySwitcher | boolean | false | 헤더에 통화 전환 노출 여부. props를 주입해 둔 채로 메뉴에 따라 아예 숨겨야 할 때도 false로 준다 (비활성+툴팁은 currencySwitcherEnabled 사용) |
+      | currencySwitcherProps | OpsnowCommonCurrencySwitcherProps | — | 위 Props 표의 값이 그대로 전달된다. 주입하지 않으면 showCurrencySwitcher가 true여도 렌더되지 않음 |
+      | currencySwitcherEnabled | boolean | true | 현재 메뉴가 통화 전환 적용 대상인지. false면 트리거를 비활성화하고 호버 시 안내 툴팁 표시 |
+      | currencySwitcherDisabledTooltip | string | 내장 ko/en/ja 문구 | 비활성 안내 툴팁 문구 덮어쓰기 (미지정 시 헤더 locale을 따르는 기본 문구) |
+
+      - ⚠️ 위 4개는 CurrencySwitcher가 아니라 **헤더(OpsnowFinopsCommonHeader)의 props**입니다 — 이 도구의 파라미터/스키마에 없으며 OpsnowCommonCurrencySwitcher에 직접 붙이면 안 됩니다. 배선 코드는 header-currency-switcher / header-multi-csp-currency-switcher 예제(getUIExamples) 참고
+      - ⚠️ 이 MCP는 헤더 props 중 통화 전환 관련 위 4개만 안내합니다 — menuList·로고·도움말·언어·테마 토글 등 헤더의 다른 props는 제공하지 않으므로, 프로젝트의 기존 헤더 코드는 그대로 두고 통화 관련 props만 추가하세요
 
       **import:**
       \`\`\`javascript
+      // 단독 사용
       import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
       const { OpsnowCommonCurrencySwitcher } = useCommonComponents();
+
+      // 공통 헤더에서 사용 (헤더 배선 시에만)
+      import OpsnowFinopsCommonHeader from '@opsnow-common/opsnow-finops-common-header';
       \`\`\``,
             parameters: CurrencySwitcherSchema,
             handler: async (args) => {
-                const props = [];
+                const entries = [];
                 if (args.value)
-                    props.push(`value={${args.value}}`);
+                    entries.push(["value", args.value]);
                 if (args.onChange)
-                    props.push(`onChange={${args.onChange}}`);
+                    entries.push(["onChange", args.onChange]);
                 if (args.rateInfo)
-                    props.push(`rateInfo={${args.rateInfo}}`);
+                    entries.push(["rateInfo", args.rateInfo]);
                 if (args.historySeries)
-                    props.push(`historySeries={${args.historySeries}}`);
+                    entries.push(["historySeries", args.historySeries]);
                 if (args.onHistoryQueryChange)
-                    props.push(`onHistoryQueryChange={${args.onHistoryQueryChange}}`);
+                    entries.push(["onHistoryQueryChange", args.onHistoryQueryChange]);
                 if (args.historyPeriodOptions)
-                    props.push(`historyPeriodOptions={${args.historyPeriodOptions}}`);
+                    entries.push(["historyPeriodOptions", args.historyPeriodOptions]);
                 if (args.defaultHistoryPeriod !== undefined)
-                    props.push(`defaultHistoryPeriod={${args.defaultHistoryPeriod}}`);
+                    entries.push(["defaultHistoryPeriod", String(args.defaultHistoryPeriod)]);
                 if (args.currencyOptions)
-                    props.push(`currencyOptions={${args.currencyOptions}}`);
+                    entries.push(["currencyOptions", args.currencyOptions]);
                 if (args.baseCurrency)
-                    props.push(`baseCurrency="${args.baseCurrency}"`);
-                if (args.defaultTargetCurrency)
-                    props.push(`defaultTargetCurrency="${args.defaultTargetCurrency}"`);
-                if (args.customRate)
-                    props.push(`customRate={${args.customRate}}`);
-                if (args.onCustomRateChange)
-                    props.push(`onCustomRateChange={${args.onCustomRateChange}}`);
-                if (args.showDetail !== undefined)
-                    props.push(`showDetail={${args.showDetail}}`);
+                    entries.push(["baseCurrency", `'${args.baseCurrency}'`]);
+                if (args.nativeCurrency)
+                    entries.push(["nativeCurrency", `'${args.nativeCurrency}'`]);
+                // [다음 버전 재도입 예정] 환율 설정(직접 입력 · 시뮬레이션) props — 스키마 주석 블록과 함께 주석 해제
+                // if (args.defaultTargetCurrency) entries.push(["defaultTargetCurrency", `'${args.defaultTargetCurrency}'`]);
+                // if (args.simulationTarget) entries.push(["simulationTarget", args.simulationTarget]);
+                // if (args.customRate) entries.push(["customRate", args.customRate]);
+                // if (args.onCustomRateChange) entries.push(["onCustomRateChange", args.onCustomRateChange]);
+                // if (args.showDetail !== undefined) entries.push(["showDetail", String(args.showDetail)]);
+                // if (args.historyMode) entries.push(["historyMode", `'${args.historyMode}'`]);
                 if (args.showHistory !== undefined)
-                    props.push(`showHistory={${args.showHistory}}`);
+                    entries.push(["showHistory", String(args.showHistory)]);
                 if (args.renderChart)
-                    props.push(`renderChart={${args.renderChart}}`);
+                    entries.push(["renderChart", args.renderChart]);
                 if (args.labels)
-                    props.push(`labels={${args.labels}}`);
+                    entries.push(["labels", args.labels]);
                 if (args.size)
-                    props.push(`size="${args.size}"`);
+                    entries.push(["size", `'${args.size}'`]);
                 if (args.disabled)
-                    props.push(`disabled`);
-                const code = `<OpsnowCommonCurrencySwitcher\n  ${props.join('\n  ')}\n/>`;
+                    entries.push(["disabled", "true"]);
+                // 'USD' 같은 문자열 리터럴은 JSX에서 attr="USD" 형태로 렌더
+                const toJsxAttr = ([k, v]) => {
+                    if (v === "true")
+                        return k;
+                    const literal = v.match(/^'([^']*)'$/);
+                    return literal ? `${k}="${literal[1]}"` : `${k}={${v}}`;
+                };
+                const code = `<OpsnowCommonCurrencySwitcher\n  ${entries.map(toJsxAttr).join('\n  ')}\n/>`;
                 return {
                     content: [
                         {

package/build/index.js

@@ -28,6 +28,22 @@ const server = new McpServer({
 
 IMPORTANT: All components require React 18.x or higher environment.
 Always include required import statements and i18n configuration when needed.
+
+**CRITICAL: 공통 패키지 버전 규칙**
+
+- @opsnow-common/* 공통 패키지는 반드시 메이저 버전 2.x대를 사용합니다.
+- MUI(@mui/*)는 반드시 9.x대를 사용합니다 — 공통 패키지 2.x가 MUI 9 기반이라 프로젝트의 MUI 버전도 맞춰야 합니다.
+- 이 MCP의 스펙/예제는 모두 2.x + MUI 9 기준이라 그 이전 버전에서는 UI·동작이 다르게 나올 수 있습니다.
+- 작업 전 package.json에서 @opsnow-common/*이 2.x인지, @mui/*가 9.x인지 확인하고, 아니면 업그레이드를 먼저 안내하세요.
+
+**CRITICAL: MUI 9 코드 작성 규칙 (옛 MUI 문법 금지)**
+
+1. system props 금지 — Box/Stack/Typography/Grid/Link에 mt/mb/px/color 등을 직접 prop으로 주면 동작하지 않습니다. 반드시 sx로: <Box sx={{ mt: 2 }}> (O), <Box mt={2}> (X)
+2. Grid는 size prop 사용 — item prop 삭제, xs/sm/md/lg/xl prop 삭제: <Grid size={6}> / <Grid size={{ xs: 12, md: 6 }}> (O), <Grid item xs={6}> (X). 세로 배치(direction="column")도 삭제 — Stack 사용
+3. slots/slotProps로 통일 — InputProps/inputProps/componentsProps/TransitionComponent 등 legacy prop 삭제: slotProps.input / slotProps.htmlInput / slots.transition 사용
+4. Dialog/Modal의 disableEscapeKeyDown 삭제 — onClose의 reason 인자('escapeKeyDown' | 'backdropClick')로 분기 처리
+
+위 규칙은 raw MUI 컴포넌트(Box/Stack/Grid 등 직접 사용)에 적용됩니다. OpsnowCommon* 래퍼 컴포넌트는 각 컴포넌트 스펙(getComponentSpec)이 우선입니다 — 예: OpsnowCommonTextField는 inputProps/InputProps를 자체 props로 지원하며 내부에서 slotProps로 매핑하므로 스펙대로 사용하세요.
 ${toolFlowInstructions}
 
 **CRITICAL: API 호출 규칙**
@@ -87,7 +103,7 @@ Before implementing OpsnowCommonDataGrid, you MUST use getUIExamples tool with '
 **CRITICAL: Spacing Tokens (theme.commonSpacing) — DO NOT hardcode px**
 
 Just like color tokens (theme.palette.commonPalette), all layout spacing uses the semantic token theme.commonSpacing
-(requires @opsnow-common/opsnow-common-style 1.0.11+, type-augmented → autocompletes, light/dark 공통):
+(@opsnow-common/opsnow-common-style 제공, type-augmented → autocompletes, light/dark 공통):
 
    filterGap      24px        - gap between filters (filter row gap)
    filterLabelGap 8px         - gap between label and its filter
@@ -122,7 +138,7 @@ When placing multiple filters in one row, the gap values are MANDATORY:
    - Label and its filter: theme.commonSpacing.filterLabelGap (8px) — wrap label+filter in one Stack
    - A labeled group counts as ONE filter — still filterGap from the previous filter
    - Pure CSS (no theme context): use var(--opsnow-spacing-filter-gap) / var(--opsnow-spacing-filter-label-gap)
-   - Requires @opsnow-common/opsnow-common-style 1.0.11+ (theme.commonSpacing is type-augmented → autocompletes)
+   - theme.commonSpacing is provided by @opsnow-common/opsnow-common-style (type-augmented → autocompletes)
 
 WARNING: Violating these rules will cause the UI to malfunction.`
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsnow-mcp/opsnow-mcp-common-ui-server",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "type": "module",
   "main": "index.js",
   "bin": {