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

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

@@ -1885,4 +1885,332 @@ export const DataGridExamples = [
             <button onClick={setCheckBox}>set check box</button>
           </OpsnowCommonDataGrid>`
     },
+    {
+        title: 'Column Group - Basic',
+        description: 'children 속성을 사용한 기본 컬럼 그룹 예제입니다.',
+        code_props_usage: `
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      // 컬럼 그룹 정의 - children을 사용한 예제
+      const columnDefs = [
+        {
+          groupId: 'vehicleGroup',
+          headerName: 'Vehicle Info',
+          children: [
+            { headerName: 'Make', field: 'make' },
+            { headerName: 'Model', field: 'model' },
+          ],
+        },
+        {
+          groupId: 'financialGroup',
+          headerName: 'Financial Info',
+          children: [
+            {
+              headerName: 'Price',
+              field: 'price',
+              valueFormatter: params => params.value ? \`$\${params.value.toLocaleString()}\` : ''
+            },
+            {
+              headerName: 'Tax',
+              field: 'tax',
+              valueFormatter: params => params.value ? \`$\${params.value.toLocaleString()}\` : ''
+            },
+          ],
+        },
+        {
+          groupId: 'salesGroup',
+          headerName: 'Sales Info',
+          children: [
+            { headerName: 'Year', field: 'year' },
+            { headerName: 'Country', field: 'country' },
+          ],
+        },
+      ]
+
+      // 초기 행 데이터
+      const initialRowData = [
+        { make: 'Toyota', model: 'Celica', price: 35000, tax: 3500, year: 2020, country: 'Japan' },
+        { make: 'Ford', model: 'Mondeo', price: 32000, tax: 3200, year: 2019, country: 'USA' },
+        { make: 'Porsche', model: 'Boxter', price: 72000, tax: 7200, year: 2021, country: 'Germany' },
+        { make: 'BMW', model: 'M3', price: 65000, tax: 6500, year: 2020, country: 'Germany' },
+        { make: 'Honda', model: 'Civic', price: 28000, tax: 2800, year: 2019, country: 'Japan' },
+        { make: 'Tesla', model: 'Model S', price: 95000, tax: 9500, year: 2022, country: 'USA' },
+        { make: 'Audi', model: 'A4', price: 45000, tax: 4500, year: 2020, country: 'Germany' },
+        { make: 'Mercedes', model: 'C-Class', price: 55000, tax: 5500, year: 2021, country: 'Germany' },
+        { make: 'Nissan', model: 'Altima', price: 30000, tax: 3000, year: 2019, country: 'Japan' },
+        { make: 'Chevrolet', model: 'Malibu', price: 33000, tax: 3300, year: 2020, country: 'USA' },
+      ]
+
+      const gridOptions = {
+        animateRows: true,
+        rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+        tooltipShowDelay: 100,
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+      }
+
+      const { OpsnowCommonDataGrid } = useCommonComponents();
+      const { CommonConst } = useGlobalContext()
+      // rowData와 status 상태를 관리
+      const [rowData, setRowData] = useState([]) // 초기에는 빈 배열로 설정
+      const [status, setStatus] = useState(CommonConst.GRID_STATUS.LOADING) // 초기에는 LOADING 상태
+
+      // 데이터 지연 설정을 위한 useEffect
+      useEffect(() => {
+        // 1초 후에 데이터를 설정
+        const timeoutId = setTimeout(() => {
+          setRowData(initialRowData)
+          setStatus(CommonConst.GRID_STATUS.DATA_EXISTS)
+        }, 1000)
+
+        // 컴포넌트 언마운트 시 타임아웃 클리어
+        return () => {
+          clearTimeout(timeoutId)
+        }
+      }, [])
+    `,
+        code: `<OpsnowCommonDataGrid
+          columnDefs={columnDefs}
+          rowData={rowData}
+          status={status}
+          gridOptions={gridOptions}
+          usedSearch={true}
+          pagination={true}
+          paginationPageSize={5}
+          pageSizeList={[
+              { label: '5', value: 5 },
+              { label: '10', value: 10 },
+              { label: '20', value: 20 },
+          ]}
+          langCd={i18n.getLocale()}
+        />`
+    },
+    {
+        title: 'Column Group - Nested',
+        description: '다층 구조의 중첩된 컬럼 그룹 예제입니다.',
+        code_props_usage: `
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      // 중첩된 컬럼 그룹 정의
+      const nestedColumnDefs = [
+        {
+          groupId: 'vehicleMainGroup',
+          headerName: 'Vehicle',
+          children: [
+            {
+              groupId: 'vehicleBasicGroup',
+              headerName: 'Basic Info',
+              children: [
+                { headerName: 'Make', field: 'make' },
+                { headerName: 'Model', field: 'model' },
+              ],
+            },
+            {
+              groupId: 'vehicleDetailsGroup',
+              headerName: 'Details',
+              children: [
+                { headerName: 'Year', field: 'year' },
+                { headerName: 'Country', field: 'country' },
+              ],
+            },
+          ],
+        },
+        {
+          groupId: 'financialMainGroup',
+          headerName: 'Financial',
+          children: [
+            {
+              headerName: 'Price',
+              field: 'price',
+              valueFormatter: params => params.value ? \`$\${params.value.toLocaleString()}\` : ''
+            },
+            {
+              headerName: 'Tax',
+              field: 'tax',
+              valueFormatter: params => params.value ? \`$\${params.value.toLocaleString()}\` : ''
+            },
+          ],
+        },
+      ]
+
+      // 초기 행 데이터
+      const initialRowData = [
+        { make: 'Toyota', model: 'Celica', price: 35000, tax: 3500, year: 2020, country: 'Japan' },
+        { make: 'Ford', model: 'Mondeo', price: 32000, tax: 3200, year: 2019, country: 'USA' },
+        { make: 'Porsche', model: 'Boxter', price: 72000, tax: 7200, year: 2021, country: 'Germany' },
+        { make: 'BMW', model: 'M3', price: 65000, tax: 6500, year: 2020, country: 'Germany' },
+        { make: 'Honda', model: 'Civic', price: 28000, tax: 2800, year: 2019, country: 'Japan' },
+        { make: 'Tesla', model: 'Model S', price: 95000, tax: 9500, year: 2022, country: 'USA' },
+        { make: 'Audi', model: 'A4', price: 45000, tax: 4500, year: 2020, country: 'Germany' },
+        { make: 'Mercedes', model: 'C-Class', price: 55000, tax: 5500, year: 2021, country: 'Germany' },
+        { make: 'Nissan', model: 'Altima', price: 30000, tax: 3000, year: 2019, country: 'Japan' },
+        { make: 'Chevrolet', model: 'Malibu', price: 33000, tax: 3300, year: 2020, country: 'USA' },
+      ]
+
+      const gridOptions = {
+        animateRows: true,
+        rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+        tooltipShowDelay: 100,
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+      }
+
+      const { OpsnowCommonDataGrid } = useCommonComponents();
+      const { CommonConst } = useGlobalContext()
+      // rowData와 status 상태를 관리
+      const [rowData, setRowData] = useState([]) // 초기에는 빈 배열로 설정
+      const [status, setStatus] = useState(CommonConst.GRID_STATUS.LOADING) // 초기에는 LOADING 상태
+
+      // 데이터 지연 설정을 위한 useEffect
+      useEffect(() => {
+        // 1초 후에 데이터를 설정
+        const timeoutId = setTimeout(() => {
+          setRowData(initialRowData)
+          setStatus(CommonConst.GRID_STATUS.DATA_EXISTS)
+        }, 1000)
+
+        // 컴포넌트 언마운트 시 타임아웃 클리어
+        return () => {
+          clearTimeout(timeoutId)
+        }
+      }, [])
+    `,
+        code: `<OpsnowCommonDataGrid
+          key={status}
+          columnDefs={nestedColumnDefs}
+          rowData={rowData}
+          status={status}
+          gridOptions={gridOptions}
+          usedSearch={true}
+          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

@@ -31,12 +31,13 @@ const gridOptionsSchema = z.object({
     getRowId: z.string().optional().describe('행 ID 반환 함수(stringified)'),
     suppressMenuHide: z.boolean().optional().describe('메뉴 숨김 억제'),
 });
-const columnDefsSchema = z.object({
+const columnDefsSchema = z.lazy(() => z.object({
     headerName: z.string().optional().describe('컬럼 헤더명'),
     field: z.string().optional().describe('컬럼 데이터 필드명'),
     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([
@@ -101,7 +102,8 @@ const columnDefsSchema = z.object({
     filterParams: z.any().optional().describe('필터 파라미터'),
     cellRendererSelector: z.string().optional().describe('셀 렌더러 선택 함수(stringified)'),
     colSpan: z.string().optional().describe('컬럼 병합 함수(stringified)'),
-});
+    children: z.array(z.lazy(() => columnDefsSchema)).optional().describe('하위 컬럼 정의 배열 (컬럼 그룹화)'),
+}));
 const defaultColDefSchema = z.object({
     wrapText: z.boolean().optional().describe('텍스트 줄바꿈'),
     autoHeight: z.boolean().optional().describe('자동 높이'),
@@ -124,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('로컬 행 클래스명'),
@@ -139,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('검색창 사용 여부'),
@@ -179,12 +204,113 @@ export function createDataGridComponent() {
 
       **이 데이터 그리드 컴포넌트는 ag-grid를 기반으로 구현되었습니다.**
       **데이터 그리드 데이터, 컬럼 정의 등의 데이터가 제공되지 않을 경우 목업 데이터를 사용하세요.**
-      
+
+      **중요: 긴 텍스트 컬럼 처리 (필수)**
+      컬럼 값이 길어서 줄바꿈이 필요한 경우, 반드시 다음을 따라야 합니다:
+      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

@@ -50,6 +50,7 @@ export function createPaginationComponent() {
         {
             name: "createPagination",
             description: `페이지네이션 컴포넌트 - 페이지 이동 및 크기 조절
+
       **import**:
       \`\`\`jsx
       import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader'

package/build/index.js

@@ -25,8 +25,57 @@ import { createCommonExamplesComponent } from "./components/opsnow-common-exampl
 // MCP 서버 생성
 const server = new McpServer({
     name: "opsnow-mcp-common-ui-server",
-    version: "1.0.0",
-    description: "이 도구 서버는 MUI(Material-UI) 기반의 UI 컴포넌트를 제공합니다. 이 컴포넌트들을 사용하는 코드를 생성할 때는, 일관된 디자인을 위해 화면 레이아웃과 스타일링에 MUI의 컴포넌트와 스타일링 유틸리티(예: '@mui/material', '@mui/system' 등)를 적극적으로 활용해야 합니다.",
+    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.8",
+  "version": "1.0.10",
   "type": "module",
   "main": "index.js",
   "bin": {