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

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

@@ -1610,12 +1610,12 @@ const handleDownload = useCallback(() => {
 export const CurrencySwitcherExamples = [
     {
         title: 'header-currency-switcher',
-        code: `// 공통 헤더(header)에서 사용법 — 기본 배선 (opsnow-finops-common-header >= 1.0.20)
+        code: `// 공통 헤더(header)에서 사용법 — 기본 배선
 // 헤더는 통화 상태/환율 데이터를 갖지 않는다 — 앱이 관리해 props로 주입한다
 import OpsnowFinopsCommonHeader from '@opsnow-common/opsnow-finops-common-header'
 
 const [currency, setCurrency] = useState('USD')
-const [historyQuery, setHistoryQuery] = useState({ currency: 'USD', period: 24 })
+const [historyQuery, setHistoryQuery] = useState({ currency: 'USD', period: 6 })
 const historySeries = useMemo(
   () => buildSeries(historyQuery.currency, historyQuery.period), // 실사용: BE 조회
   [historyQuery]
@@ -1665,13 +1665,11 @@ const isCurrencyEnabledPath = CURRENCY_ENABLED_ROUTES.some(
     onHistoryQueryChange: refetchHistory,
 
     nativeCurrency: 'KRW',                          // 무환산(수집) 통화
-    historyMode: 'popup',                           // 히스토리 항상 중앙 팝업
-    simulationTarget: { currency: 'USD', payer: 'Azure' },
   }}
   // 적용 대상 외 메뉴에서 뜨는 안내 문구를 앱 문구로 덮어쓰기
   currencySwitcherDisabledTooltip={t('header.currencyNotSupported')}
 />`,
-        description: "공통 헤더(header)에서 사용법 — 멀티 CSP(수집 통화 혼재) 조합 예제입니다. 'multi-csp-native-currency' 예제와 같은 props(nativeCurrency/historyMode/simulationTarget 포함)를 currencySwitcherProps 안에 그대로 넣으면 되고, 비활성 안내 문구는 currencySwitcherDisabledTooltip으로 앱 번역으로 덮어쓸 수 있습니다. [검색 키워드: 헤더 멀티 CSP, 헤더 통화 전환, 헤더에서 사용법, 수집 통화, currencySwitcherDisabledTooltip]"
+        description: "공통 헤더(header)에서 사용법 — 멀티 CSP(수집 통화 혼재) 조합 예제입니다. 'multi-csp-native-currency' 예제와 같은 props(nativeCurrency 포함)를 currencySwitcherProps 안에 그대로 넣으면 되고, 비활성 안내 문구는 currencySwitcherDisabledTooltip으로 앱 번역으로 덮어쓸 수 있습니다. [검색 키워드: 헤더 멀티 CSP, 헤더 통화 전환, 헤더에서 사용법, 수집 통화, currencySwitcherDisabledTooltip]"
     },
     {
         title: 'standalone-props-reference',
@@ -1688,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 },
     ],
@@ -1704,18 +1702,15 @@ 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: '통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 props 참고용 예제입니다 (⚠️ 실서비스 배치는 header-currency-switcher 예제처럼 공통 헤더로). 환율 데이터는 컴포넌트가 조회하지 않으므로 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',
+        title: 'custom-options-no-history',
         code: `// ⚠️ 단독 배치는 props 참고용 — 실서비스 배치는 header-currency-switcher 예제 사용
 <OpsnowCommonCurrencySwitcher
   value={currency}
@@ -1728,10 +1723,9 @@ const rateInfo = {
   ]}
   baseCurrency="USD"
   size="small"
-  showDetail={false}
   showHistory={false}
 />`,
-        description: '팝오버 통화 목록을 커스텀하고 환율 설정(시뮬레이션)·히스토리 없이 small 크기 트리거로 사용하는 예제입니다.'
+        description: '팝오버 통화 목록을 커스텀하고 하단 히스토리 섹션 없이(showHistory=false, 통화 목록만 노출) small 크기 트리거로 사용하는 예제입니다.'
     },
     {
         title: 'multi-csp-native-currency',
@@ -1755,13 +1749,11 @@ const multiCspRateInfo = {
   value={currency}
   onChange={handleCurrencyChange}
   rateInfo={multiCspRateInfo}
-  historySeries={historySeries}
+  historySeries={historySeries}             // 시리즈에도 currency: 'KRW' 를 담아 행 라벨에 병기
   onHistoryQueryChange={handleHistoryQueryChange}
   nativeCurrency="KRW"                      // 무환산(수집) 통화 — 앵커(baseCurrency=USD)와 분리
-  historyMode="popup"                       // 히스토리 항상 중앙 팝업 (USD 뷰 포함)
-  simulationTarget={{ currency: 'USD', payer: 'Azure' }} // 시뮬레이션 대상을 실제 환산되는 CSP로 고정
 />`,
-        description: "수집 통화 분리 — 멀티 CSP 혼재 예제입니다 (opsnow-common-dropdown >= 1.0.32). 기준 통화(USD)는 환율 앵커로 유지하되 '변환 없음(Default)' 문구는 nativeCurrency='KRW' 행에 붙습니다. USD 행에는 'N개 환율' 배지가 붙고, USD 선택 시 '현재 적용 환율'에 CSP별 환산 환율이 행 단위 통화(KRW)로 나열됩니다. historyMode='popup'이면 선택 통화와 무관하게 히스토리가 항상 중앙 팝업으로 열리고, simulationTarget으로 환율 설정(시뮬레이션) 대상이 실제 환산되는 Payer에 고정됩니다. [검색 키워드: 멀티 CSP, 수집 통화, 무환산, nativeCurrency, historyMode, simulationTarget]"
+        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,30 +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 · nativeCurrency/historyMode/simulationTarget은 >= 1.0.32)
+// 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, currency? }>)로 2건 이상이면 다중 환율 통화로 취급 (없으면 목록에 환율이 '-'로 표시). 수집 통화가 CSP별로 다른 멀티 CSP 케이스는 details를 기준 통화 키(details.USD)에 담고 행마다 currency 필드로 행 단위 통화를 표기 — nativeCurrency와 함께 사용 (예: 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("변환 기준 통화 코드 — 환율이 '1 {base} = X'로 저장되는 앵커. 무환산 표기와는 별개 개념(nativeCurrency 참고) (기본값: 'USD')"),
-    nativeCurrency: z.string().optional().describe("무환산(수집) 통화 코드 — '변환 없음(Default)' 문구가 붙는 행. 수집 통화가 기준 통화와 다른 멀티 CSP 조합(예: Azure/GCP KRW 수집)에서 baseCurrency(환율 앵커)와 분리 지정 (기본값: baseCurrency, dropdown >= 1.0.32)"),
-    defaultTargetCurrency: z.string().optional().describe("기준 통화 선택 중일 때 환율 설정이 다룰 초기 비교 통화 코드"),
-    simulationTarget: z.string().optional().describe("환율 설정(시뮬레이션) 대상 지정 객체 변수명 — { currency, payer?, invoice? } 형태, 기준 통화 뷰에서 실제 환산되는 CSP(Payer)로 고정하며 payer/invoice 일치 행이 사전 선택됨 (예: simulationTarget, dropdown >= 1.0.32)"),
-    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)"),
-    historyMode: z.enum(["auto", "popup"]).optional().describe("히스토리 열림 방식 — 'popup'이면 선택 통화·환율 수와 무관하게 항상 화면 중앙 팝업으로 열고 통화 셀렉트에 기준 통화 포함, 'auto'는 다중 환율=팝업/단일 환율·기준 통화=인라인 분기 (기본값: 'auto', dropdown >= 1.0.32)"),
-    renderChart: z.string().optional().describe("히스토리 팝업 차트 교체 슬롯 함수명 — (series, currency) => ReactNode 형태, 체크된(보이는) 시리즈만 전달 (기본: 내장 SVG 멀티라인 차트)"),
-    labels: z.string().optional().describe("문구 개별 커스텀 객체 변수명 — Partial<CurrencySwitcherLabels>, i18n(ko/en/ja) 번역 위에 항목별로 덮어씀 ({placeholder} 템플릿 치환 지원)"),
+    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() {
@@ -564,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)
@@ -1121,40 +1123,39 @@ export function createFormsComponent() {
         },
         {
             name: "createCurrencySwitcher",
-            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 — ⚠️ 실서비스 배치는 반드시 공통 헤더(OpsnowFinopsCommonHeader)의 currencySwitcherProps로만 (opsnow-common-dropdown >= 1.0.29 · nativeCurrency/historyMode/simulationTarget은 >= 1.0.32)
+            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건 이상이면 다중 환율 통화로 취급
-      - 멀티 CSP(수집 통화 혼재, 예: AWS=USD·Azure/GCP=KRW 수집): details를 기준 통화 키에 담고 행마다 currency 필드로 행 단위 통화 표기 — details: { USD: [{ payer: 'Azure', rate: 1508.8, currency: 'KRW' }, ...] }, nativeCurrency='KRW'와 함께 사용
-      - 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 사용
 
-      **히스토리 동작 분기 규칙:**
+      **히스토리 표기 규칙:**
 
-      | 선택 통화 상태 | 히스토리 동작 | 조회 통화 | 표시 시리즈 |
+      | 상황 | 히스토리 표기 | 조회 통화 | 표시 시리즈 |
       |------|------|------|------|
-      | historyMode='popup' 지정 (선택 통화·환율 수 무관) | 항상 화면 중앙 팝업 — 통화 셀렉트에 기준 통화 포함 | 선택 통화 (기준 통화 포함) | 주입 시리즈 전체 (멀티 CSP 다중 시리즈) |
-      | 'auto' · 다중 환율 통화 선택 (details 2건 이상 — 기준 통화 포함) | 화면 중앙 팝업 (차트/테이블 전환, Payer/Invoice 검색·체크박스 — 팝오버는 열린 채 유지, 닫으면 복귀) | 선택 통화 | Payer/Invoice별 전체 시리즈 |
-      | 'auto' · 단일 환율 통화 선택 (예: JPY, VND) | 팝오버 안에 인라인 차트 펼침/접힘 (팝업 없음) | 선택 통화 | 첫 번째 시리즈(대표 환율)만 |
-      | 'auto' · 기준 통화 선택 중 + details 없음 (예: USD) | 팝오버 안에 인라인 차트 펼침/접힘 (팝업 없음) | 선택 통화(기준 통화) | 첫 번째 시리즈(대표 환율)만 |
+      | 팝오버 열림 (통화·환율 수 무관) | 하단에 히스토리 섹션 상시 노출 — 추가 팝업 없음, 기본 뷰는 테이블 | 선택 통화 | 주입 시리즈 전체 |
+      | 테이블 뷰 (기본) | 연월이 컬럼 헤더, 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, opsnow-finops-common-header >= 1.0.20):**
+      **공통 헤더에서 쓰기 (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'(하위 경로 포함) — 현재 라우트가 여기에 속하는지를 앱에서 판단해 주입하세요
+      - 헤더는 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:
 
@@ -1200,20 +1201,15 @@ export function createFormsComponent() {
                     entries.push(["baseCurrency", `'${args.baseCurrency}'`]);
                 if (args.nativeCurrency)
                     entries.push(["nativeCurrency", `'${args.nativeCurrency}'`]);
-                if (args.defaultTargetCurrency)
-                    entries.push(["defaultTargetCurrency", `'${args.defaultTargetCurrency}'`]);
-                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)]);
+                // [다음 버전 재도입 예정] 환율 설정(직접 입력 · 시뮬레이션) 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)
                     entries.push(["showHistory", String(args.showHistory)]);
-                if (args.historyMode)
-                    entries.push(["historyMode", `'${args.historyMode}'`]);
-                if (args.simulationTarget)
-                    entries.push(["simulationTarget", args.simulationTarget]);
                 if (args.renderChart)
                     entries.push(["renderChart", args.renderChart]);
                 if (args.labels)

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.36",
+  "version": "1.0.37",
   "type": "module",
   "main": "index.js",
   "bin": {