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

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

@@ -1614,21 +1614,21 @@ export const CurrencySwitcherExamples = [
 
 const [currency, setCurrency] = useState('USD')
 const [appliedRate, setAppliedRate] = useState(1)
+const [historySeries, setHistorySeries] = useState([])
 
 // BE 환율 API 응답을 그대로 주입 (컴포넌트는 API를 호출하지 않음)
 const rateInfo = {
   baseDate: '2026-07-08',            // 적용 환율 기준일
   source: '한국수출입은행',            // 출처 (선택)
-  rates: { USD: 1, KRW: 1450, JPY: 156.58, VND: 25508, AED: 3.67 }, // 기준 통화(USD) 1단위당 환율
+  rates: { USD: 1, KRW: 1450, JPY: 156.58, VND: 25508, AED: 3.67 }, // 기준 통화(USD) 1단위당 대표 환율
+  details: {                         // (선택) 통화별 Payer/Invoice 상세 환율
+    KRW: [                           // 2건 이상이면 '다중 환율' — 배지 · 현재 적용 환율 목록 · 히스토리 팝업
+      { payer: 'Payer 1234', invoice: 'Invoice 0000', rate: 1450 },
+      { payer: 'Payer 5678', invoice: 'Invoice 9999', rate: 1462 },
+    ],
+  },
 }
 
-// 환율 상세 보기 차트용 월별(또는 일별) 추이 — 과거 → 현재 순, 마지막 값 = 현재 환율
-const history = [
-  { label: '25.07', rate: 1495.3 },
-  { label: '26.06', rate: 1462.1 },
-  { label: '26.07', rate: 1450 },
-]
-
 <OpsnowCommonCurrencySwitcher
   value={currency}
   onChange={(code, rate) => {
@@ -1636,9 +1636,17 @@ const history = [
     setAppliedRate(rate) // 금액 표시 변환은 소비 측에서 rate로 처리
   }}
   rateInfo={rateInfo}
-  history={history}
+  historySeries={historySeries}
+  onHistoryQueryChange={(code, months) => {
+    // 히스토리 열림/팝업 통화·기간 셀렉트 변경 시 통지 → BE 재조회 후 주입
+    // historySeries: [{ name, label?, current?, points: [{ label, rate }, ...] }, ...]
+    fetchHistory(code, months).then(setHistorySeries)
+  }}
+  onCustomRateChange={(rate, context) => {
+    // what-if 시뮬레이션 값 (저장되지 않음, onChange 미호출)
+  }}
 />`,
-        description: '통화 전환 드롭다운 + 환율 팝오버 기본 예제입니다. 환율 데이터는 컴포넌트가 조회하지 않으므로 BE 환율 API 응답을 rateInfo/history props로 주입합니다. [검색 키워드: 통화 전환, 환율, 환율 필터, 통화 필터, 통화 변환, currency, exchange rate]'
+        description: '통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리 기본 예제입니다. 환율 데이터는 컴포넌트가 조회하지 않으므로 BE 환율 API 응답을 rateInfo/historySeries props로 주입하고, onHistoryQueryChange(currency, months)로 조회 조건을 통지받아 재조회합니다. rateInfo.details가 2건 이상인 통화는 다중 환율로 취급되어 히스토리가 화면 중앙 팝업(차트/테이블)으로 열리고, 단일 환율·기준 통화는 팝오버 안 인라인 차트로 열립니다. [검색 키워드: 통화 전환, 환율, 환율 필터, 통화 필터, 통화 변환, 환율 히스토리, 다중 환율, currency, exchange rate]'
     },
     {
         title: 'custom-options-no-detail',
@@ -1654,8 +1662,9 @@ const history = [
   baseCurrency="USD"
   size="small"
   showDetail={false}
+  showHistory={false}
 />`,
-        description: '팝오버 통화 목록을 커스텀하고 환율 상세 보기 드릴다운 없이 small 크기 트리거로 사용하는 예제입니다.'
+        description: '팝오버 통화 목록을 커스텀하고 환율 설정(시뮬레이션)·히스토리 없이 small 크기 트리거로 사용하는 예제입니다.'
     }
 ];
 export const ToggleButtonExamples = [

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

@@ -290,19 +290,23 @@ export const InsightContentSchema = z.object({
     emptyMessage: z.string().optional().describe("insightText가 없을 때 표시할 빈 메시지"),
     sx: z.string().optional().describe("MUI sx 스타일 객체(JSX/문자열)"),
 });
-// CurrencySwitcher 컴포넌트 관련 스키마 정의 (통화 전환 드롭다운 + 환율 팝오버, opsnow-common-forms >= 1.0.19)
+// CurrencySwitcher 컴포넌트 관련 스키마 정의 (통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리, opsnow-common-dropdown >= 1.0.29)
 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 } 형태로 BE 환율 API 응답을 주입 (없으면 목록에 환율이 '-'로 표시, 예: rateInfo)"),
-    history: z.string().optional().describe("환율 상세 보기 추이 차트 데이터 배열 변수명 — Array<{ label, rate }>, 과거 → 현재 순이며 마지막 값 = 현재 환율 (예: history)"),
+    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)"),
     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("기준 통화 선택 중일 때 상세 보기가 다룰 초기 비교 통화 코드"),
+    defaultTargetCurrency: z.string().optional().describe("기준 통화 선택 중일 때 환율 설정이 다룰 초기 비교 통화 코드"),
     customRate: z.string().optional().describe("직접 입력 시뮬레이션 환율 상태 변수명 (number | null, controlled 모드 — 미지정 시 내부 관리)"),
-    onCustomRateChange: z.string().optional().describe("직접 입력 환율 변경 핸들러 함수명 — (rate) => void 형태"),
-    showDetail: z.boolean().optional().describe("환율 상세 보기 드릴다운 노출 여부 (기본값: true)"),
-    renderChart: z.string().optional().describe("추이 차트 교체 슬롯 함수명 — (history, currency) => ReactNode 형태 (기본: 내장 SVG 스파크라인)"),
+    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} 템플릿 치환 지원)"),
     size: z.enum(["small", "medium"]).optional().describe("트리거 크기"),
     disabled: z.boolean().optional().describe("비활성화 여부"),
@@ -1113,21 +1117,26 @@ export function createFormsComponent() {
         },
         {
             name: "createCurrencySwitcher",
-            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버, 환율/통화 필터로 사용 (opsnow-common-forms >= 1.0.19)
+            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리, 환율/통화 필터로 사용 (opsnow-common-dropdown >= 1.0.29)
 
       트리거에 현재 선택된 통화가 표시되고, 클릭하면 팝오버에서 적용 환율 기준일 안내와
-      통화 목록(클릭 시 즉시 적용)을 제공합니다. "환율 상세 보기" 드릴다운에서 직접 입력
-      시뮬레이션, 현재/최고/최저/변동 스탯, 환율 추이 차트를 확인할 수 있습니다.
+      통화 목록(클릭 시 즉시 적용)을 제공합니다. Payer/Invoice별 환율이 여러 개인 통화는
+      'N개 환율' 배지와 '현재 적용 환율' 목록이 표시되고, 환율 설정에서 Payer를 골라
+      what-if 시뮬레이션을 입력할 수 있습니다.
 
       **데이터 주입 규칙 (중요):**
-      - 환율 데이터는 컴포넌트가 조회하지 않습니다 — BE 환율 API 응답을 rateInfo / history props로 주입하세요.
-      - rateInfo: { baseDate: 'YYYY-MM-DD', source?: '출처', rates: { USD: 1, KRW: 1450, ... } } — 기준 통화 1단위당 환율
-      - history: [{ label: '25.07', rate: 1495.3 }, ...] — 과거 → 현재 순, 마지막 값 = 현재 환율
+      - 환율 데이터는 컴포넌트가 조회하지 않습니다 — 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 }, ...] }, ...] — 모든 시리즈는 같은 월 구간으로 정렬, 대표 환율이 첫 번째 시리즈가 되도록 정렬 (인라인 차트는 첫 번째 시리즈만 사용)
       - BE API 호출 시 axios 직접 import 금지 — getAxios() 공통 axios 사용
 
+      **히스토리 동작 분기 규칙:**
+      - 다중 환율 통화(details 2건 이상): 화면 중앙 팝업(차트/테이블 전환, Payer/Invoice 검색·체크박스) — Payer/Invoice별 전체 시리즈 표시
+      - 단일 환율 통화·기준 통화: 팝오버 안 인라인 차트 펼침/접힘(팝업 없음) — 첫 번째 시리즈(대표 환율)만 표시
+
       **동작 규칙:**
-      - 선택/직접 입력 시 onChange(code, rate)가 호출됩니다 — 금액 표시 변환은 소비 프로젝트에서 rate로 처리
-      - 직접 입력 환율은 시뮬레이션 용도이며 저장되지 않습니다
+      - 통화 선택 시 onChange(currency, rate)가 호출됩니다 — 금액 표시 변환은 소비 프로젝트에서 rate로 처리
+      - 직접 입력 환율은 저장되지 않는 what-if 시뮬레이션 값으로 onCustomRateChange(rate, context)로만 통지되며, onChange(실제 적용)는 호출되지 않습니다
       - 문구는 i18n 현재 언어(ko/en/ja)를 자동으로 따르고, labels prop으로 항목별 커스텀 가능
 
       **import:**
@@ -1144,8 +1153,14 @@ export function createFormsComponent() {
                     props.push(`onChange={${args.onChange}}`);
                 if (args.rateInfo)
                     props.push(`rateInfo={${args.rateInfo}}`);
-                if (args.history)
-                    props.push(`history={${args.history}}`);
+                if (args.historySeries)
+                    props.push(`historySeries={${args.historySeries}}`);
+                if (args.onHistoryQueryChange)
+                    props.push(`onHistoryQueryChange={${args.onHistoryQueryChange}}`);
+                if (args.historyPeriodOptions)
+                    props.push(`historyPeriodOptions={${args.historyPeriodOptions}}`);
+                if (args.defaultHistoryPeriod !== undefined)
+                    props.push(`defaultHistoryPeriod={${args.defaultHistoryPeriod}}`);
                 if (args.currencyOptions)
                     props.push(`currencyOptions={${args.currencyOptions}}`);
                 if (args.baseCurrency)
@@ -1158,6 +1173,8 @@ export function createFormsComponent() {
                     props.push(`onCustomRateChange={${args.onCustomRateChange}}`);
                 if (args.showDetail !== undefined)
                     props.push(`showDetail={${args.showDetail}}`);
+                if (args.showHistory !== undefined)
+                    props.push(`showHistory={${args.showHistory}}`);
                 if (args.renderChart)
                     props.push(`renderChart={${args.renderChart}}`);
                 if (args.labels)

package/package.json

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