@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.26 → 1.0.28

package/build/components/examples/opsnow-common-coach-mark-examples-data.js

@@ -0,0 +1,91 @@
+// CoachMark 컴포넌트 예제 데이터
+export const CoachMarkExamples = [
+    {
+        title: "storageKey-title-content-placement",
+        code: `<OpsnowCommonCoachMark
+  storageKey="dashboard-filter-guide"
+  title="필터 사용법"
+  content="여기서 기간과 계정을 선택해 비용을 필터링할 수 있어요."
+  placement="bottom"
+>
+  <Button>필터</Button>
+</OpsnowCommonCoachMark>`,
+        description: "기본 가이드 말풍선 예제입니다. storageKey는 가이드마다 고유하게 지정하며(localStorage 키로 사용), X로 닫으면 localStorage에 저장되어 새로고침해도 다시 뜨지 않습니다.",
+    },
+    {
+        title: "content-only",
+        code: `<OpsnowCommonCoachMark
+  storageKey="content-only-guide"
+  content="제목 없이 본문만 표시할 수도 있어요."
+  placement="right"
+>
+  <Button>본문만</Button>
+</OpsnowCommonCoachMark>`,
+        description: "title 없이 content만 넘기면 본문만 표시되는 예제입니다.",
+    },
+    {
+        title: "placement-top",
+        code: `<OpsnowCommonCoachMark
+  storageKey="top-guide"
+  title="위쪽 말풍선"
+  content="대상 요소 위에 표시됩니다."
+  placement="top"
+>
+  <Button>placement top</Button>
+</OpsnowCommonCoachMark>`,
+        description: "placement로 말풍선 위치를 지정하는 예제입니다 (top/bottom/left/right).",
+    },
+    {
+        title: "placement-left",
+        code: `<OpsnowCommonCoachMark
+  storageKey="left-guide"
+  title="왼쪽 말풍선"
+  content="대상 요소 왼쪽에 표시됩니다."
+  placement="left"
+>
+  <Button>placement left</Button>
+</OpsnowCommonCoachMark>`,
+        description: "대상 요소 왼쪽에 표시되는 예제입니다. 공간이 부족하면 MUI가 자동으로 반대쪽으로 flip 됩니다.",
+    },
+    {
+        title: "jsx-content-onClose",
+        code: `<OpsnowCommonCoachMark
+  storageKey="jsx-guide"
+  title="새 기능 안내"
+  content={
+    <>
+      <div>여러 줄로 구성된 안내 문구입니다.</div>
+      <div><b>굵은 텍스트</b>나 링크도 넣을 수 있어요.</div>
+    </>
+  }
+  placement="right"
+  onClose={() => console.log('closed')}
+>
+  <Button>JSX content</Button>
+</OpsnowCommonCoachMark>`,
+        description: "content에 JSX를 넘겨 여러 줄/굵은 글씨/링크 등을 표현하고, onClose로 닫힐 때 콜백을 실행하는 예제입니다.",
+    },
+    {
+        title: "actions-button",
+        code: `<OpsnowCommonCoachMark
+  storageKey="actions-guide"
+  title="새 기능 안내"
+  content="아래 확인 버튼을 누르면 안내가 닫힙니다."
+  placement="bottom"
+  actions={(close) => (
+    <Button size="small" onClick={close}>확인</Button>
+  )}
+>
+  <Button>actions 버튼</Button>
+</OpsnowCommonCoachMark>`,
+        description: "actions에 함수를 주면 close 인자로 '닫기+영구저장' 핸들러를 받아 하단 우측에 액션 버튼을 표시하는 예제입니다.",
+    },
+    {
+        title: "reset-dismissed-guides",
+        code: `Object.keys(window.localStorage)
+  .filter((k) => k.startsWith('opsnow-common-coach-mark:'))
+  .forEach((k) => window.localStorage.removeItem(k));
+window.location.reload();`,
+        description: "닫힘 기록을 초기화하는 예제입니다. localStorage에서 'opsnow-common-coach-mark:' prefix 키를 제거하면 닫았던 가이드가 다시 표시됩니다.",
+    },
+];

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

@@ -2325,6 +2325,96 @@ export const DataGridExamples = [
           langCd={i18n.getLocale()}
         />`
     },
+    {
+        title: 'Auto Row Height (행 수 분기 + 스크롤)',
+        description: 'autoHeight는 모든 행을 펼쳐 그리드가 무한정 길어집니다. 행 수가 가변적이거나 많아질 수 있는 경우(목록/검색 결과 등) 행 수 기준으로 분기해야 합니다: 10행 이하면 autoHeight로 콘텐츠에 맞게 확장하고, 10행 초과면 고정 높이 + 내부 스크롤로 전환합니다. autoHeight 셀은 행마다 높이가 달라 정확한 "10행 높이"를 픽셀로 맞출 수 없으므로 고정 픽셀값(예: 600)을 사용합니다.',
+        code_props_usage: `
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      const ROW_LIMIT = 10           // 이 행 수를 넘으면 고정 높이 + 스크롤
+      const SCROLL_HEIGHT = 600      // 초과 시 고정 높이(px)
+
+      const columnDefs = [
+        { headerName: 'ID', field: 'id', flex: 1, minWidth: 80 },
+        {
+          headerName: 'Description',
+          field: 'description',
+          flex: 3,
+          minWidth: 300,
+          wrapText: true,            // 텍스트 줄바꿈 - 필수
+          autoHeight: true,          // 행 높이 자동 조절 - 필수
+          suppressSizeToFit: true,
+          cellStyle: { alignItems: 'center' }  // autoHeight 작동을 위해 필수
+        },
+        { headerName: 'Status', field: 'status', flex: 1, minWidth: 120 },
+      ]
+
+      const defaultColDef = {
+        wrapText: true,      // 텍스트 줄바꿈 활성화
+        autoHeight: true,    // 셀 높이 자동 조절
+      }
+
+      const { OpsnowCommonDataGrid } = useCommonComponents()
+      const { CommonConst } = useGlobalContext()
+
+      // 4행 데이터 (10행 이하 → autoHeight, 스크롤 없음)
+      const fewRowData = [
+        { id: 1, description: 'This is a very long description text that will wrap to multiple lines when the column width is not sufficient to display all content in a single line.', status: 'Active' },
+        { id: 2, description: 'Short text', status: 'Inactive' },
+        { id: 3, description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', status: 'Pending' },
+        { id: 4, description: 'Another example of long text content that needs multiple lines', status: 'Active' },
+      ]
+
+      // 12행 데이터 (10행 초과 → 고정 높이 600px + 내부 스크롤)
+      const manyRowData = Array.from({ length: 12 }, (_, i) => ({
+        id: i + 1,
+        description: 'Row ' + (i + 1) + ': long description text that wraps to multiple lines when the column is narrow, demonstrating autoHeight with scroll.',
+        status: i % 2 === 0 ? 'Active' : 'Inactive',
+      }))
+
+      const [rowData, setRowData] = useState([])
+      const [status, setStatus] = useState(CommonConst.GRID_STATUS.LOADING)
+
+      useEffect(() => {
+        const fetchData = async () => {
+          try {
+            await new Promise(resolve => setTimeout(resolve, 500))
+            setRowData(fewRowData)   // 실제로는 API 응답 데이터
+            setStatus(CommonConst.GRID_STATUS.DATA_EXISTS)
+          } catch (error) {
+            setStatus(CommonConst.GRID_STATUS.ERROR)
+          }
+        }
+        fetchData()
+      }, [])
+
+      // 행 수 기준 분기 - 핵심
+      const isScroll = rowData.length > ROW_LIMIT
+      const gridOptions = {
+        animateRows: true,
+        rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+        tooltipShowDelay: 100,
+        domLayout: isScroll ? 'normal' : 'autoHeight',  // 10행 이하: 콘텐츠 맞춤 / 초과: 고정+스크롤
+        suppressCellFocus: true,
+      }
+    `,
+        code: `<>
+          <div style={{ marginBottom: '8px', display: 'flex', gap: '8px' }}>
+            <OpsnowCommonButton label="4행 (스크롤 X)" size="large" variant="outlined" color="secondary" onClick={() => setRowData(fewRowData)} />
+            <OpsnowCommonButton label="12행 (스크롤 O)" size="large" variant="outlined" color="secondary" onClick={() => setRowData(manyRowData)} />
+          </div>
+          <OpsnowCommonDataGrid
+            columnDefs={columnDefs}
+            defaultColDef={defaultColDef}
+            rowData={rowData}
+            status={status}
+            gridOptions={gridOptions}
+            gridHeight={isScroll ? SCROLL_HEIGHT : undefined}
+            langCd={i18n.getLocale()}
+          />
+        </>`
+    },
     {
         title: 'API 데이터 로딩 (getAxios 사용)',
         description: 'API에서 데이터를 가져와 그리드에 표시하는 예제입니다. axios 직접 사용 대신 반드시 getAxios를 사용해야 합니다.',

package/build/components/opsnow-common-coach-mark.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+// CoachMark 컴포넌트 관련 스키마 정의
+export const CoachMarkSchema = z.object({
+    storageKey: z.string().describe("가이드마다 고유하게 지정하는 localStorage 키 (내부적으로 'opsnow-common-coach-mark:' prefix가 붙음) - X로 닫으면 localStorage에 저장되어 새로고침해도 다시 표시되지 않음"),
+    title: z.string().optional().describe("가이드 말풍선 제목 - 생략 시 본문만 표시"),
+    content: z.string().describe("가이드 말풍선 본문 - 문자열 또는 JSX 사용 가능 (여러 줄/굵은 글씨/링크 등 표현 시 JSX)"),
+    isJsxContent: z.boolean().optional().describe("content를 JSX로 렌더링할지 여부 - true면 content를 JSX 표현식으로 출력"),
+    placement: z.enum(["top", "bottom", "left", "right"]).optional().describe("말풍선 표시 위치 (top/bottom/left/right) - 공간이 부족하면 MUI가 자동으로 반대쪽으로 flip"),
+    onClose: z.string().optional().describe("말풍선이 닫힐 때 실행할 콜백 함수명"),
+    actionLabel: z.string().optional().describe("하단 우측 액션 버튼 라벨 - 지정 시 actions={(close) => <Button onClick={close}>라벨</Button>} 형태로 렌더링 (close는 '닫기+영구저장' 핸들러)"),
+});
+// CoachMark 컴포넌트 함수 - 배열 반환
+export function createCoachMarkComponent() {
+    return [
+        {
+            name: "createCoachMark",
+            description: `코치마크(가이드 말풍선) 컴포넌트 - 신규 기능/사용법 안내용 말풍선을 대상 요소에 표시
+      X로 닫으면 localStorage('opsnow-common-coach-mark:' + storageKey)에 저장되어 새로고침해도 다시 표시되지 않음
+      **import 예시:**
+      \`\`\`javascript
+      import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
+      const { OpsnowCommonCoachMark } = useCommonComponents();
+      \`\`\`
+      `,
+            parameters: CoachMarkSchema,
+            handler: async (args) => {
+                const props = [];
+                props.push(`storageKey="${args.storageKey}"`);
+                if (args.title)
+                    props.push(`title="${args.title}"`);
+                if (args.isJsxContent) {
+                    props.push(`content={${args.content}}`);
+                }
+                else {
+                    props.push(`content="${args.content}"`);
+                }
+                if (args.placement)
+                    props.push(`placement="${args.placement}"`);
+                if (args.onClose)
+                    props.push(`onClose={${args.onClose}}`);
+                if (args.actionLabel) {
+                    props.push(`actions={(close) => (<Button size="small" variant="contained" onClick={close}>${args.actionLabel}</Button>)}`);
+                }
+                const code = `
+        <OpsnowCommonCoachMark
+          ${props.join("\n          ")}
+        >
+          // 가이드 대상 요소 필요(Mui Button or OpsnowCommonButton 등)
+        </OpsnowCommonCoachMark>
+        `;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `\`\`\`jsx\n${code}\n\`\`\``,
+                        },
+                    ],
+                };
+            },
+        },
+    ];
+}

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

@@ -3,6 +3,7 @@ import { IconExamples, MuiIconExamples } from "./examples/opsnow-common-icons-ex
 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";
 import { TooltipExamples } from "./examples/opsnow-common-tooltip-examples-data.js";
+import { CoachMarkExamples } from "./examples/opsnow-common-coach-mark-examples-data.js";
 import { DataGridExamples } from "./examples/opsnow-common-grid-examples-data.js";
 import { PopupExamples } from "./examples/opsnow-common-popup-examples-data.js";
 import { StepperExamples } from "./examples/opsnow-common-stepper-examples-data.js";
@@ -47,6 +48,7 @@ const EXAMPLES_MAP = {
     HeatmapChart: HeatmapChartExamples,
     BubbleChart: BubbleChartExamples,
     Tooltip: TooltipExamples,
+    CoachMark: CoachMarkExamples,
     DataGrid: DataGridExamples,
     Popup: PopupExamples,
     Stepper: StepperExamples,

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

@@ -239,6 +239,19 @@ export function createDataGridComponent() {
 
       ⚠️ defaultColDef에 wrapText, autoHeight가 없으면 텍스트가 넘칩니다!
 
+      **CRITICAL: 행 수가 많을 수 있으면 - 높이 분기 필수**
+      autoHeight(domLayout:'autoHeight')는 모든 행을 펼쳐서 그리드가 무한정 길어짐.
+      행 수가 가변적이거나 많아질 수 있으면 행 수 기준으로 분기:
+
+      const ROW_LIMIT = 10;
+      const isScroll = rowData.length > ROW_LIMIT;
+      const gridOptions = {
+        // ... 다른 설정들
+        domLayout: isScroll ? 'normal' : 'autoHeight',  // 10행 이하: 콘텐츠 맞춤 / 초과: 고정+스크롤
+      };
+      // 10행 초과 시에만 고정 높이 부여 (autoHeight 셀은 가변이라 픽셀 고정값 사용)
+      <OpsnowCommonDataGrid gridOptions={gridOptions} gridHeight={isScroll ? 600 : undefined} />
+
       **import:**
       \`\`\`javascript
       import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader';

package/build/index.js

@@ -15,6 +15,7 @@ import { createTabComponent } from "./components/opsnow-common-tab.js";
 import { createGridLayoutComponent } from "./components/opsnow-common-layout.js";
 import { createTypographyComponent } from "./components/opsnow-common-typography.js";
 import { createTooltipComponent } from "./components/opsnow-common-tooltip.js";
+import { createCoachMarkComponent } from "./components/opsnow-common-coach-mark.js";
 import { createSelectComponent } from "./components/opsnow-common-select.js";
 import { createPopupComponent } from "./components/opsnow-common-popup.js";
 import { createStepperComponent } from "./components/opsnow-common-stepper.js";
@@ -103,6 +104,7 @@ const componentFactories = [
     createGridLayoutComponent,
     createTypographyComponent,
     createTooltipComponent,
+    createCoachMarkComponent,
     createSelectComponent,
     createPopupComponent,
     createStepperComponent,

package/package.json

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