@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.9 → 1.0.10

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

@@ -1978,7 +1978,11 @@ export const DataGridExamples = [
           usedSearch={true}
           pagination={true}
           paginationPageSize={5}
-          pageSizeList={[5, 10]}
+          pageSizeList={[
+              { label: '5', value: 5 },
+              { label: '10', value: 10 },
+              { label: '20', value: 20 },
+          ]}
           langCd={i18n.getLocale()}
         />`
     },
@@ -2083,4 +2087,130 @@ export const DataGridExamples = [
           langCd={i18n.getLocale()}
         />`
     },
+    {
+        title: 'Error Status',
+        description: 'Error Status 예제입니다.',
+        code_props_usage: `
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      // 컬럼 정의
+      const columnDefs = [
+        { headerName: 'Make', field: 'make' },
+        { headerName: 'Model', field: 'model' },
+        { headerName: 'Price', field: 'price' },
+      ]
+
+      const gridOptions = {
+        animateRows: true,
+        rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+        tooltipShowDelay: 100,
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+      }
+
+      const { OpsnowCommonDataGrid } = useCommonComponents();
+      const { CommonConst } = useGlobalContext()
+      // errorStatus 상태를 관리
+      const [errorStatus, setErrorStatus] = useState(CommonConst.GRID_STATUS.LOADING)
+
+      // 에러 상태 시뮬레이션을 위한 useEffect
+      useEffect(() => {
+        // 1초 후에 에러 상태로 설정
+        const timeoutId = setTimeout(() => {
+          setErrorStatus(CommonConst.GRID_STATUS.ERROR)
+        }, 1000)
+
+        // 컴포넌트 언마운트 시 타임아웃 클리어
+        return () => {
+          clearTimeout(timeoutId)
+        }
+      }, [])
+    `,
+        code: `<OpsnowCommonDataGrid
+          columnDefs={columnDefs}
+          rowData={[]}
+          status={errorStatus}
+          gridOptions={gridOptions}
+          textErrorTitle="데이터 로드 실패"
+          textErrorDescription="데이터를 불러오는 중 오류가 발생했습니다."
+          langCd={i18n.getLocale()}
+        />`
+    },
+    {
+        title: 'Long Text with autoHeight',
+        description: 'Long Text with autoHeight (긴 텍스트 자동 높이 조절) 예제입니다.',
+        code_props_usage: `
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      // Long Text용 컬럼 정의
+      const columnDefs = [
+        {
+          headerName: 'ID',
+          field: 'id',
+          flex: 1,
+          minWidth: 80
+        },
+        {
+          headerName: 'Description',
+          field: 'description',
+          flex: 3,  // 가장 넓은 비율
+          minWidth: 300,
+          suppressSizeToFit: true,  // 자동 리사이즈 방지
+          cellStyle: {
+            'align-items': 'center'  // autoHeight 작동을 위해 필수
+          }
+        },
+        {
+          headerName: 'Status',
+          field: 'status',
+          flex: 1,
+          minWidth: 120
+        },
+      ]
+
+      // Long Text용 행 데이터
+      const rowData = [
+        {
+          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. This demonstrates the autoHeight feature.',
+          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. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.',
+          status: 'Pending'
+        },
+        {
+          id: 4,
+          description: 'Another example of long text content that needs multiple lines',
+          status: 'Active'
+        },
+      ]
+
+      const gridOptions = {
+        animateRows: true,
+        rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+        tooltipShowDelay: 100,
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+      }
+
+      const { OpsnowCommonDataGrid } = useCommonComponents();
+      const { CommonConst } = useGlobalContext()
+    `,
+        code: `<OpsnowCommonDataGrid
+          columnDefs={columnDefs}
+          rowData={rowData}
+          status={CommonConst.GRID_STATUS.DATA_EXISTS}
+          gridOptions={gridOptions}
+          langCd={i18n.getLocale()}
+        />`
+    },
 ];

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

@@ -37,7 +37,7 @@ const columnDefsSchema = z.lazy(() => z.object({
     colId: z.string().optional().describe('컬럼 고유 ID'),
     groupId: z.string().optional().describe('컬럼 그룹 고유 ID'),
     width: z.number().optional().describe('컬럼 너비'),
-    minWidth: z.number().optional().describe('컬럼 최소 너비'),
+    minWidth: z.number().describe('컬럼 최소 너비'),
     maxWidth: z.number().optional().describe('컬럼 최대 너비'),
     pinned: z.enum(['left', 'right']).optional().describe('컬럼 고정 위치'),
     type: z.array(z.enum([
@@ -126,7 +126,27 @@ export const DataGridSchema = z.object({
     columnDefs: z.array(columnDefsSchema).describe("ag-grid 컬럼 정의").min(1),
     defaultColDef: defaultColDefSchema.optional().describe('ag-grid 기본 컬럼 옵션'),
     rowData: z.array(z.record(z.any())).optional().describe('그리드에 표시할 데이터'),
-    status: z.number().describe('그리드 상태값: 0-로딩, 1-데이터 있음, 9-에러'),
+    status: z.number().describe(`그리드 상태값: GRID.STATUS.LOADING(0), GRID.STATUS.DATA_EXISTS(1), GRID.STATUS.ERROR(9) 중 하나를 사용해야 합니다.
+
+    **필수 구현 패턴:**
+    반드시 useState로 상태를 관리하고, useEffect 등을 사용하여 데이터 로딩 로직을 구현해야 합니다.
+    사용자는 이 상태 제어 코드 안에 실제 비즈니스 로직(API 호출, 데이터 처리 등)을 추가할 수 있습니다.
+
+    예제:
+    const [status, setStatus] = useState(CommonConst.GRID_STATUS.LOADING)
+    const [rowData, setRowData] = useState([])
+
+    useEffect(() => {
+      // 여기에 실제 비즈니스 로직을 추가합니다 (예: API 호출)
+      fetchData()
+        .then(data => {
+          setRowData(data)
+          setStatus(CommonConst.GRID_STATUS.DATA_EXISTS)
+        })
+        .catch(error => {
+          setStatus(CommonConst.GRID_STATUS.ERROR)
+        })
+    }, [])`),
     gridHeight: z.number().optional().describe('그리드 높이'),
     setClass: z.string().optional().describe('그리드 클래스명'),
     localRowClass: z.string().optional().describe('로컬 행 클래스명'),
@@ -141,7 +161,10 @@ export const DataGridSchema = z.object({
     searchTextNoData: z.string().optional().describe('검색 결과 없음 텍스트'),
     searchTextNoDataDescription: z.string().optional().describe('검색 결과 없음 설명'),
     pagingFromServer: z.boolean().optional().describe('서버 페이징 사용 여부'),
-    pageSizeList: z.array(z.number()).optional().describe('페이지 사이즈 리스트'),
+    pageSizeList: z.array(z.object({
+        label: z.string().describe('페이지 사이즈 라벨'),
+        value: z.number().describe('페이지 사이즈 값')
+    })).optional().describe('페이지 사이즈 리스트 (예: [{ label: "5", value: 5 }, { label: "10", value: 10 }])'),
     placeholderText: z.string().optional().describe('플레이스홀더 텍스트'),
     usedRowClass: z.boolean().optional().describe('행 클래스 사용 여부 (셀 클릭 이벤트 사용 시 필수: true)'),
     usedSearch: z.boolean().optional().describe('검색창 사용 여부'),
@@ -182,20 +205,112 @@ export function createDataGridComponent() {
       **이 데이터 그리드 컴포넌트는 ag-grid를 기반으로 구현되었습니다.**
       **데이터 그리드 데이터, 컬럼 정의 등의 데이터가 제공되지 않을 경우 목업 데이터를 사용하세요.**
 
-      **페이지네이션 사용법:**
-      - 이 그리드는 내장 페이지네이션 기능을 제공합니다.
-      - 별도의 Pagination 컴포넌트를 추가할 필요가 없습니다.
-      - 페이지네이션을 사용하려면 다음 props를 설정하세요:
-        pagination={true} - 페이지네이션 활성화
-        paginationPageSize={10} - 페이지당 행 수
-        pageSizeList={[5, 10, 20, 50]} - 페이지 크기 선택 옵션
-      - 서버 사이드 페이징은 pagingFromServer={true}와 serverSideTotalPageSize를 사용하세요.
+      **중요: 긴 텍스트 컬럼 처리 (필수)**
+      컬럼 값이 길어서 줄바꿈이 필요한 경우, 반드시 다음을 따라야 합니다:
+      1. 모든 컬럼에 flex 속성 필수 (비율로 너비 분배, 예: flex: 1, flex: 3)
+      2. 긴 텍스트 컬럼에 suppressSizeToFit: true 필수
+      3. 긴 텍스트 컬럼에 cellStyle: { 'align-items': 'center' } 필수
+      4. gridOptions에 domLayout: 'autoHeight' 설정
+
+      예시:
+      const columnDefs = [
+        { headerName: 'ID', field: 'id', flex: 1, minWidth: 80 },
+        {
+          headerName: 'Description',
+          field: 'description',
+          flex: 3,
+          minWidth: 300,
+          suppressSizeToFit: true,
+          cellStyle: { 'align-items': 'center' }
+        },
+        { headerName: 'Status', field: 'status', flex: 1, minWidth: 120 }
+      ];
 
       **import:**
       \`\`\`javascript
       import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader';
       const { OpsnowCommonDataGrid } = useCommonComponents();
-      const { CommonConst } = useGlobalContext()
+      const { CommonConst } = useGlobalContext();
+      \`\`\`
+
+      **중요: 상태 관리 패턴 (필수 구현)**
+      데이터 그리드를 구현할 때는 반드시 아래의 세 가지 상태(LOADING, DATA_EXISTS, ERROR)를 모두 처리하는 코드를 포함해야 합니다.
+
+      **절대 하지 말아야 할 것:**
+      - useState에 직접 데이터를 넣지 마세요: const [rowData] = useState([{...}]) ❌
+      - status를 바로 DATA_EXISTS로 설정하지 마세요: const [status] = useState(CommonConst.GRID_STATUS.DATA_EXISTS) ❌
+      - useEffect 없이 구현하지 마세요 ❌
+
+      **반드시 따라야 할 구현 패턴:**
+      1. status는 반드시 CommonConst.GRID_STATUS.LOADING으로 시작
+      2. rowData는 반드시 빈 배열 []로 시작
+      3. useEffect를 반드시 사용하여 데이터 로딩 시뮬레이션
+      4. .then()으로 성공 처리 → CommonConst.GRID_STATUS.DATA_EXISTS로 변경
+      5. .catch()로 에러 처리 → CommonConst.GRID_STATUS.ERROR로 변경
+      6. OpsnowCommonDataGrid에 textErrorTitle, textErrorDescription 속성 반드시 포함
+
+      사용자는 생성된 코드의 useEffect 내부에 실제 비즈니스 로직(API 호출, 데이터 변환 등)을 추가할 수 있습니다.
+
+      **기본 패턴 예제 (정확히 이 구조를 따라야 함):**
+      \`\`\`javascript
+      // ✅ 올바른 방법: LOADING으로 시작, 빈 배열로 시작
+      const [status, setStatus] = useState(CommonConst.GRID_STATUS.LOADING);
+      const [rowData, setRowData] = useState([]);
+
+      // ✅ 올바른 방법: useEffect에서 데이터 로딩
+      useEffect(() => {
+        // 사용자가 여기에 실제 API 호출 등 비즈니스 로직을 추가합니다
+        const fetchData = async () => {
+          try {
+            // 실제로는 여기에 API 호출을 넣습니다
+            // 예: const response = await fetch('/api/data');
+            // const data = await response.json();
+
+            // 데모를 위한 시뮬레이션
+            await new Promise(resolve => setTimeout(resolve, 1000));
+
+            const mockData = [
+              { make: 'Toyota', model: 'Celica', price: 35000 },
+              { make: 'Ford', model: 'Mondeo', price: 32000 }
+            ];
+
+            setRowData(mockData);
+            setStatus(CommonConst.GRID_STATUS.DATA_EXISTS);
+          } catch (error) {
+            console.error('Error loading data:', error);
+            setStatus(CommonConst.GRID_STATUS.ERROR);
+          }
+        };
+
+        fetchData();
+      }, []);
+
+      // gridOptions 정의 (권장)
+      const gridOptions = {
+        animateRows: true,
+        rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+        tooltipShowDelay: 100,
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+      };
+
+      // ✅ 올바른 방법: 에러 관련 속성 포함
+      <OpsnowCommonDataGrid
+        columnDefs={columnDefs}
+        rowData={rowData}
+        status={status}
+        gridOptions={gridOptions}
+        pagination={true}
+        paginationPageSize={5}
+        pageSizeList={[
+          { label: '5', value: 5 },
+          { label: '10', value: 10 },
+          { label: '20', value: 20 }
+        ]}
+        textErrorTitle="데이터 로드 실패"
+        textErrorDescription="데이터를 불러오는 중 오류가 발생했습니다."
+        langCd={i18n.getLocale()}
+      />
       \`\`\``,
             parameters: DataGridSchema,
             handler: async (args) => {

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

@@ -51,13 +51,6 @@ export function createPaginationComponent() {
             name: "createPagination",
             description: `페이지네이션 컴포넌트 - 페이지 이동 및 크기 조절
 
-      **중요: OpsnowCommonDataGrid(데이터 그리드)와 함께 사용하는 경우**
-      - OpsnowCommonDataGrid는 내장 페이지네이션 기능을 제공합니다.
-      - 데이터 그리드에서 페이지네이션을 사용하려면 이 툴을 사용하지 말고 createDataGrid 툴을 사용하세요.
-
-      **이 툴을 사용해야 하는 경우**
-      - 데이터 그리드가 아닌 일반 목록이나 카드 뷰에서 페이지네이션이 필요한 경우에만 사용하세요.
-
       **import**:
       \`\`\`jsx
       import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader'

package/build/index.js

@@ -26,6 +26,56 @@ import { createCommonExamplesComponent } from "./components/opsnow-common-exampl
 const server = new McpServer({
     name: "opsnow-mcp-common-ui-server",
     version: "1.0.0"
+}, {
+    instructions: `OpsNow UI Components Usage Guidelines:
+
+IMPORTANT: All components require React 18.x or higher environment.
+Always include required import statements and i18n configuration when needed.
+
+**CRITICAL: OpsnowCommonDataGrid Usage Rules**
+
+Before implementing OpsnowCommonDataGrid, you MUST use getUIExamples tool with 'DataGrid' parameter first!
+
+1. Grid Top Search/Button Area - You MUST use children or searchAddon slots:
+
+   [CORRECT] Using children slot:
+   <OpsnowCommonDataGrid usedSearch={true}>
+     <OpsnowCommonButton label="Add" iconName="Plus" />
+   </OpsnowCommonDataGrid>
+
+   [CORRECT] Using searchAddon slot:
+   <OpsnowCommonDataGrid
+     usedSearch={true}
+     searchAddon={<OpsnowCommonDatePicker />}
+   />
+
+   [FORBIDDEN] DO NOT create separate Stack/Box outside the grid:
+   <Stack direction="row">  <- DO NOT DO THIS!
+     <OpsnowCommonButton label="Add" />
+   </Stack>
+   <OpsnowCommonDataGrid usedSearch={true} />
+
+   Reference example: "Insert Button Inside the Common Grid Search Section"
+
+2. Grid Bottom Pagination - You MUST use built-in pagination prop:
+
+   [CORRECT] Using built-in pagination:
+   <OpsnowCommonDataGrid
+     pagination={true}
+     paginationPageSize={10}
+     pageSizeList={[
+       { label: '10', value: 10 },
+       { label: '20', value: 20 }
+     ]}
+   />
+
+   [FORBIDDEN] DO NOT use OpsnowCommonPagination component separately:
+   <OpsnowCommonDataGrid />
+   <OpsnowCommonPagination />  <- DO NOT DO THIS!
+
+   Reference example: "Search + Pagination"
+
+WARNING: Violating these rules will cause the UI to malfunction.`
 });
 // 컴포넌트들 등록
 const componentFactories = [

package/package.json

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