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

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

@@ -1607,6 +1607,66 @@ const handleDownload = useCallback(() => {
         description: '팝업에서 텍스트 콘텐츠를 표시하고 RTF 파일로 다운로드하는 예제입니다. downloadInsightAsRtf 유틸리티를 사용하면 어떤 텍스트든 RTF 문서로 내보낼 수 있습니다. [검색 키워드: RTF 다운로드, 콘텐츠 내보내기, 문서 저장, 텍스트 내보내기, 리포트 다운로드]'
     }
 ];
+export const CurrencySwitcherExamples = [
+    {
+        title: 'basic-currency-switcher',
+        code: `const { OpsnowCommonCurrencySwitcher } = useCommonComponents()
+
+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단위당 대표 환율
+  details: {                         // (선택) 통화별 Payer/Invoice 상세 환율
+    KRW: [                           // 2건 이상이면 '다중 환율' — 배지 · 현재 적용 환율 목록 · 히스토리 팝업
+      { payer: 'Payer 1234', invoice: 'Invoice 0000', rate: 1450 },
+      { payer: 'Payer 5678', invoice: 'Invoice 9999', rate: 1462 },
+    ],
+  },
+}
+
+<OpsnowCommonCurrencySwitcher
+  value={currency}
+  onChange={(code, rate) => {
+    setCurrency(code)
+    setAppliedRate(rate) // 금액 표시 변환은 소비 측에서 rate로 처리
+  }}
+  rateInfo={rateInfo}
+  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/historySeries props로 주입하고, onHistoryQueryChange(currency, months)로 조회 조건을 통지받아 재조회합니다. rateInfo.details가 2건 이상인 통화는 다중 환율로 취급되어 히스토리가 화면 중앙 팝업(차트/테이블)으로 열리고, 단일 환율·기준 통화는 팝오버 안 인라인 차트로 열립니다. [검색 키워드: 통화 전환, 환율, 환율 필터, 통화 필터, 통화 변환, 환율 히스토리, 다중 환율, currency, exchange rate]'
+    },
+    {
+        title: 'custom-options-no-detail',
+        code: `<OpsnowCommonCurrencySwitcher
+  value={currency}
+  onChange={handleCurrencyChange}
+  rateInfo={rateInfo}
+  currencyOptions={[
+    { code: 'USD', symbol: '$' },
+    { code: 'KRW', symbol: '₩', digits: 0 },
+    { code: 'JPY', symbol: '¥' },
+  ]}
+  baseCurrency="USD"
+  size="small"
+  showDetail={false}
+  showHistory={false}
+/>`,
+        description: '팝오버 통화 목록을 커스텀하고 환율 설정(시뮬레이션)·히스토리 없이 small 크기 트리거로 사용하는 예제입니다.'
+    }
+];
 export const ToggleButtonExamples = [
     {
         title: 'large-toggle-group',

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

@@ -1,4 +1,4 @@
-import { ButtonExamples, BadgeExamples, TextareaExamples, SwitchExamples, ChipExamples, TextFieldExamples, AvatarExamples, CheckboxExamples, RadioGroupExamples, CollapseExamples, SliderExamples, LinkExamples, TreeViewExamples, InsightCardExamples, InsightContentExamples, ToggleButtonExamples } from "./examples/opsnow-common-forms-examples-data.js";
+import { ButtonExamples, BadgeExamples, TextareaExamples, SwitchExamples, ChipExamples, TextFieldExamples, AvatarExamples, CheckboxExamples, RadioGroupExamples, CollapseExamples, SliderExamples, LinkExamples, TreeViewExamples, InsightCardExamples, InsightContentExamples, CurrencySwitcherExamples, ToggleButtonExamples } from "./examples/opsnow-common-forms-examples-data.js";
 import { IconExamples, MuiIconExamples } from "./examples/opsnow-common-icons-examples-data.js";
 import { CalendarExamples } from "./examples/opsnow-common-calendar-examples-data.js";
 import { GaugeChartExamples, PieChartExamples, BarChartExamples, LineChartExamples, StackChartExamples, XyMultiChartExamples, HeatmapChartExamples, BubbleChartExamples } from "./examples/opsnow-common-chart-examples-data.js";
@@ -36,6 +36,7 @@ export const EXAMPLES_MAP = {
     TreeView: TreeViewExamples,
     InsightCard: InsightCardExamples,
     InsightContent: InsightContentExamples,
+    CurrencySwitcher: CurrencySwitcherExamples,
     ToggleButtonGroup: ToggleButtonExamples,
     Icon: IconExamples,
     MuiIcon: MuiIconExamples,

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

@@ -290,6 +290,27 @@ 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)
+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)"),
+    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} 템플릿 치환 지원)"),
+    size: z.enum(["small", "medium"]).optional().describe("트리거 크기"),
+    disabled: z.boolean().optional().describe("비활성화 여부"),
+});
 // Forms 컴포넌트 함수 - 배열 반환
 export function createFormsComponent() {
     return [
@@ -1093,6 +1114,85 @@ export function createFormsComponent() {
                     ]
                 };
             }
+        },
+        {
+            name: "createCurrencySwitcher",
+            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버 + 환율 히스토리, 환율/통화 필터로 사용 (opsnow-common-dropdown >= 1.0.29)
+
+      트리거에 현재 선택된 통화가 표시되고, 클릭하면 팝오버에서 적용 환율 기준일 안내와
+      통화 목록(클릭 시 즉시 적용)을 제공합니다. Payer/Invoice별 환율이 여러 개인 통화는
+      'N개 환율' 배지와 '현재 적용 환율' 목록이 표시되고, 환율 설정에서 Payer를 골라
+      what-if 시뮬레이션을 입력할 수 있습니다.
+
+      **데이터 주입 규칙 (중요):**
+      - 환율 데이터는 컴포넌트가 조회하지 않습니다 — 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(currency, rate)가 호출됩니다 — 금액 표시 변환은 소비 프로젝트에서 rate로 처리
+      - 직접 입력 환율은 저장되지 않는 what-if 시뮬레이션 값으로 onCustomRateChange(rate, context)로만 통지되며, onChange(실제 적용)는 호출되지 않습니다
+      - 문구는 i18n 현재 언어(ko/en/ja)를 자동으로 따르고, labels prop으로 항목별 커스텀 가능
+
+      **import:**
+      \`\`\`javascript
+      import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
+      const { OpsnowCommonCurrencySwitcher } = useCommonComponents();
+      \`\`\``,
+            parameters: CurrencySwitcherSchema,
+            handler: async (args) => {
+                const props = [];
+                if (args.value)
+                    props.push(`value={${args.value}}`);
+                if (args.onChange)
+                    props.push(`onChange={${args.onChange}}`);
+                if (args.rateInfo)
+                    props.push(`rateInfo={${args.rateInfo}}`);
+                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)
+                    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}}`);
+                if (args.showHistory !== undefined)
+                    props.push(`showHistory={${args.showHistory}}`);
+                if (args.renderChart)
+                    props.push(`renderChart={${args.renderChart}}`);
+                if (args.labels)
+                    props.push(`labels={${args.labels}}`);
+                if (args.size)
+                    props.push(`size="${args.size}"`);
+                if (args.disabled)
+                    props.push(`disabled`);
+                const code = `<OpsnowCommonCurrencySwitcher\n  ${props.join('\n  ')}\n/>`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `\`\`\`jsx\n${code}\n\`\`\``
+                        }
+                    ]
+                };
+            }
         }
     ];
 }

package/package.json

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