@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.39 → 1.0.40

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

@@ -2476,4 +2476,262 @@ export const DataGridExamples = [
           langCd={i18n.getLocale()}
         />`
     },
+    {
+        title: '셀 단위 로딩 (Partial Loading — refreshCells) + 컬럼 전체 / 실패·재시도',
+        description: '"이 셀만 갱신 중" 같은 부분 로딩 예제입니다. status={GRID_STATUS.LOADING}은 그리드 전체를 가리므로 부분 로딩에 쓸 수 없습니다 — status는 DATA_EXISTS로 두고, 로딩 중인 셀 키를 useRef(Set)에 담은 뒤 ref API refreshCells({ rowNodes, columns, force: true })로 해당 셀만 다시 그립니다. 값이 그대로라 force: true가 필수입니다. rowNodes를 생략하면 그 컬럼의 모든 셀이 대상(컬럼 단위)이며, 실패도 같은 패턴(별도 Set)으로 처리해 인라인 "재시도" 링크를 띄웁니다. 인디케이터로 셀 콘텐츠를 치환하지 말고 visibility: hidden으로 남기고 겹쳐야(CellProgress) autoHeight 행 높이가 유지됩니다.',
+        code_props_usage: `
+      import { useCallback, useMemo, useRef, useState } from 'react'
+      import Box from '@mui/material/Box'
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      // 원래 콘텐츠를 hidden 으로 남겨 행 높이를 유지하고 인디케이터를 겹친다 (모듈 최상위에 둘 것)
+      const CellProgress = ({ children }) => {
+        const { OpsnowCommonLoading } = useCommonComponents()
+        return (
+          <Box sx={{ position: 'relative', display: 'inline-flex', alignItems: 'center', minWidth: '18px', minHeight: '20px' }}>
+            <Box aria-hidden sx={{ visibility: 'hidden' }}>{children}</Box>
+            <Box sx={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center' }}>
+              <OpsnowCommonLoading size={18} />
+            </Box>
+          </Box>
+        )
+      }
+
+      const formatCost = (value) => '$' + Number(value).toLocaleString()
+      const fakeApi = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+      const { OpsnowCommonDataGrid, OpsnowCommonButton, OpsnowCommonLink } = useCommonComponents()
+      const { CommonConst } = useGlobalContext()
+      const gridRef = useRef(null)
+
+      const [rowData] = useState([
+        { id: 'r1', account: 'opsnow-prod', service: 'Amazon EC2', cost: 12480 },
+        { id: 'r2', account: 'opsnow-dev', service: 'Amazon S3', cost: 3120 },
+        { id: 'r3', account: 'opsnow-stg', service: 'Amazon RDS', cost: 8640 },
+      ])
+      const status = CommonConst.GRID_STATUS.DATA_EXISTS
+
+      // state 가 아니라 ref — state 면 그리드 전체 리렌더로 스크롤이 튄다
+      const loadingCellsRef = useRef(new Set())
+      const errorCellsRef = useRef(new Set())
+
+      const refreshCostCells = useCallback((nodes) => {
+        gridRef.current?.refreshCells({
+          rowNodes: nodes,
+          columns: ['cost'],
+          force: true,   // 값이 그대로라 필수
+        })
+      }, [])
+
+      const fetchCost = useCallback(async (node) => {
+        const key = node.data.id + ':cost'
+        loadingCellsRef.current.add(key)
+        errorCellsRef.current.delete(key)
+        refreshCostCells([node])
+        try {
+          await fakeApi(1200)
+          if (node.data.id === 'r3' && !node.data.retried) {   // 데모: 첫 시도만 실패
+            node.data.retried = true
+            throw new Error('cost fetch failed')
+          }
+          node.setDataValue('cost', Math.round(node.data.cost * (0.9 + Math.random() * 0.3)))
+        } catch {
+          errorCellsRef.current.add(key)
+        } finally {
+          loadingCellsRef.current.delete(key)
+          refreshCostCells([node])
+        }
+      }, [refreshCostCells])
+
+      const refreshCostColumn = useCallback(async () => {
+        const nodes = []
+        gridRef.current?.forEachNode((node) => nodes.push(node))
+        nodes.forEach((node) => loadingCellsRef.current.add(node.data.id + ':cost'))
+        gridRef.current?.refreshCells({ columns: ['cost'], force: true })   // rowNodes 생략 = 컬럼 단위
+        await Promise.all(nodes.map((node) => fetchCost(node)))
+      }, [fetchCost])
+
+      const CostCell = useCallback((params) => {
+        const value = <span>{formatCost(params.value)}</span>
+        const key = params.data.id + ':' + params.colDef.field
+        if (loadingCellsRef.current.has(key)) return <CellProgress>{value}</CellProgress>
+        if (errorCellsRef.current.has(key)) {
+          // 버튼을 넣으면 행 높이가 바뀜 — 인라인 링크로
+          return (
+            <Box component="span" sx={(theme) => ({ display: 'inline-flex', alignItems: 'center', gap: '6px', color: theme.palette.error.main })}>
+              불러오기 실패
+              <OpsnowCommonLink color="primary" sx={{ cursor: 'pointer' }} onClick={() => fetchCost(params.node)}>재시도</OpsnowCommonLink>
+            </Box>
+          )
+        }
+        return value
+      }, [fetchCost])
+
+      const RecalcButtonCell = useCallback((params) => (
+        <OpsnowCommonButton label="재계산" size="small" variant="outlined" color="secondary" onClick={() => fetchCost(params.node)} />
+      ), [fetchCost])
+
+      // useMemo 로 고정 — 매 렌더마다 새로 만들면 그리드가 통째로 다시 그려진다
+      const columnDefs = useMemo(() => [
+        { headerName: '계정', field: 'account', flex: 1, minWidth: 140 },
+        { headerName: '서비스', field: 'service', flex: 1, minWidth: 160 },
+        { headerName: '비용', field: 'cost', flex: 1, minWidth: 200, cellRenderer: CostCell },
+        { headerName: '', colId: 'action', width: 110, sortable: false, cellRenderer: RecalcButtonCell },
+      ], [CostCell, RecalcButtonCell])
+
+      const gridOptions = useMemo(() => ({
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+        animateRows: true,
+      }), [])
+    `,
+        code: `<>
+          <div style={{ marginBottom: '16px' }}>
+            <OpsnowCommonButton label="비용 컬럼 새로고침 (컬럼 전체)" size="large" variant="outlined" color="secondary" onClick={refreshCostColumn} />
+          </div>
+          <OpsnowCommonDataGrid
+            ref={gridRef}
+            langCd={i18n.getLocale()}
+            columnDefs={columnDefs}
+            rowData={rowData}
+            status={status}
+            gridOptions={gridOptions}
+          />
+        </>`
+    },
+    {
+        title: '행 단위 로딩 (Partial Loading — rowClassRules + redrawRows) + 선택 행 일괄 로딩',
+        description: '"이 행만 동기화 중" 같은 행 단위 부분 로딩 예제입니다. 로딩 중인 행 id를 useRef(Set)에 담고, gridOptions.rowClassRules로 그 행에 클래스를 붙여 dim + 클릭 차단하며, ref API redrawRows({ rowNodes })로 해당 행만 다시 그리면 rowClassRules가 재평가됩니다. 인디케이터는 컬럼 렌더러를 감싸 행 전체 컬럼(버튼 컬럼 포함)에 적용해야 로딩 중 행 높이가 유지됩니다. 여러 행(체크박스 선택)을 켤 때는 rowNodes 배열로 묶어 redrawRows를 한 번만 호출하고, 끌 때는 응답이 온 행부터 개별 해제합니다. 선택 노드는 forEachNode + node.isSelected()로 수집하고(getSelectedNodes는 ref API에 없음), onSelectionChanged는 gridOptions가 아니라 top-level prop으로 넘겨야 호출됩니다(인자 = 선택된 노드 배열).',
+        code_props_usage: `
+      import { useCallback, useMemo, useRef, useState } from 'react'
+      import Box from '@mui/material/Box'
+      import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader'
+      import i18n from '@opsnow-common/opsnow-finops-common-i18n'
+
+      // '셀 단위 로딩' 예제와 동일
+      const CellProgress = ({ children }) => {
+        const { OpsnowCommonLoading } = useCommonComponents()
+        return (
+          <Box sx={{ position: 'relative', display: 'inline-flex', alignItems: 'center', minWidth: '18px', minHeight: '20px' }}>
+            <Box aria-hidden sx={{ visibility: 'hidden' }}>{children}</Box>
+            <Box sx={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center' }}>
+              <OpsnowCommonLoading size={18} />
+            </Box>
+          </Box>
+        )
+      }
+
+      const fakeApi = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+      const nowLabel = () => new Date().toLocaleTimeString()
+
+      const { OpsnowCommonDataGrid, OpsnowCommonButton } = useCommonComponents()
+      const { CommonConst } = useGlobalContext()
+      const gridRef = useRef(null)
+
+      const [rowData] = useState([
+        { id: 'r1', account: 'opsnow-prod', service: 'Amazon EC2', status: '동기화 완료' },
+        { id: 'r2', account: 'opsnow-dev', service: 'Amazon S3', status: '동기화 완료' },
+        { id: 'r3', account: 'opsnow-stg', service: 'Amazon RDS', status: '동기화 완료' },
+      ])
+      const status = CommonConst.GRID_STATUS.DATA_EXISTS
+
+      const loadingRowsRef = useRef(new Set())
+      const [selectedCount, setSelectedCount] = useState(0)
+      const [running, setRunning] = useState(false)
+
+      const setRowLoading = useCallback((node, loading) => {
+        if (loading) loadingRowsRef.current.add(node.data.id)
+        else loadingRowsRef.current.delete(node.data.id)
+        gridRef.current?.redrawRows({ rowNodes: [node] })   // rowClassRules 재평가
+      }, [])
+
+      const refreshRow = useCallback(async (node) => {
+        setRowLoading(node, true)
+        try {
+          await fakeApi(1800)
+          node.setDataValue('status', '동기화 ' + nowLabel())
+        } finally {
+          setRowLoading(node, false)
+        }
+      }, [setRowLoading])
+
+      const syncSelectedRows = useCallback(async () => {
+        const nodes = []
+        gridRef.current?.forEachNode((node) => { if (node.isSelected()) nodes.push(node) })   // getSelectedNodes 없음
+        if (nodes.length === 0) return
+        setRunning(true)
+        nodes.forEach((node) => loadingRowsRef.current.add(node.data.id))
+        gridRef.current?.redrawRows({ rowNodes: nodes })   // 묶어서 한 번만
+        await Promise.all(nodes.map(async (node, index) => {
+          await fakeApi(1000 + index * 600)
+          node.setDataValue('status', '동기화 ' + nowLabel())
+          loadingRowsRef.current.delete(node.data.id)
+          gridRef.current?.redrawRows({ rowNodes: [node] })
+        }))
+        setRunning(false)
+      }, [])
+
+      // defaultColDef 는 마운트 시점에 굳으므로 컬럼 렌더러를 감싼다
+      const withRowLoading = useCallback((Renderer) => {
+        const Wrapped = (params) => {
+          const content = Renderer ? <Renderer {...params} /> : <span>{params.value}</span>
+          return loadingRowsRef.current.has(params.data?.id) ? <CellProgress>{content}</CellProgress> : content
+        }
+        return Wrapped
+      }, [])
+
+      const RefreshButtonCell = useCallback((params) => (
+        <OpsnowCommonButton label="행 새로고침" size="small" variant="outlined" color="secondary" onClick={() => refreshRow(params.node)} />
+      ), [refreshRow])
+
+      // 감싼 렌더러는 useMemo 안에서 한 번만 만든다
+      const columnDefs = useMemo(() => {
+        const valueCell = withRowLoading()
+        return [
+          { headerName: '계정', field: 'account', flex: 1, minWidth: 140, cellRenderer: valueCell },
+          { headerName: '서비스', field: 'service', flex: 1, minWidth: 160, cellRenderer: valueCell },
+          { headerName: '상태', field: 'status', flex: 1, minWidth: 180, cellRenderer: valueCell },
+          // 버튼 컬럼도 감싸야 행 높이가 유지된다
+          { headerName: '', colId: 'action', width: 140, sortable: false, cellRenderer: withRowLoading(RefreshButtonCell) },
+        ]
+      }, [withRowLoading, RefreshButtonCell])
+
+      const gridOptions = useMemo(() => ({
+        domLayout: 'autoHeight',
+        suppressCellFocus: true,
+        animateRows: true,
+        rowSelection: { mode: 'multiRow', checkboxes: true, headerCheckbox: true, enableClickSelection: false },
+        rowClassRules: {
+          'row-loading': (params) => loadingRowsRef.current.has(params.data?.id),
+        },
+      }), [])
+
+      // gridOptions 가 아니라 top-level prop — 인자는 선택된 노드 배열
+      const handleSelectionChanged = useCallback((selectedNodes) => {
+        setSelectedCount(selectedNodes.length)
+      }, [])
+    `,
+        code: `<Box sx={{ '& .ag-row.row-loading': { opacity: 0.45, pointerEvents: 'none' } }}>
+          <div style={{ marginBottom: '16px' }}>
+            <OpsnowCommonButton
+              label={'선택 행 동기화 (' + selectedCount + ')'}
+              size="large"
+              variant="outlined"
+              color="secondary"
+              disabled={selectedCount === 0 || running}
+              onClick={syncSelectedRows}
+            />
+          </div>
+          <OpsnowCommonDataGrid
+            ref={gridRef}
+            langCd={i18n.getLocale()}
+            columnDefs={columnDefs}
+            rowData={rowData}
+            status={status}
+            gridOptions={gridOptions}
+            onSelectionChanged={handleSelectionChanged}
+          />
+        </Box>`
+    },
 ];

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

@@ -30,6 +30,7 @@ const gridOptionsSchema = z.object({
     serverSideSortAllLevels: z.boolean().optional().describe('서버사이드 전체 레벨 정렬'),
     getRowId: z.string().optional().describe('행 ID 반환 함수(stringified)'),
     suppressMenuHide: z.boolean().optional().describe('메뉴 숨김 억제'),
+    rowClassRules: z.record(z.string()).optional().describe('행 클래스 규칙 { 클래스명: (params) => boolean (stringified) }. redrawRows({ rowNodes }) 호출 시 재평가됨 — 행 단위 로딩(dim/클릭 차단) 표현에 사용. \'셀·행 단위 로딩\' 예제 참고'),
 });
 const columnDefsSchema = z.lazy(() => z.object({
     headerName: z.string().optional().describe('컬럼 헤더명'),
@@ -131,6 +132,8 @@ export const DataGridSchema = z.object({
     rowData: z.array(z.record(z.any())).optional().describe('그리드에 표시할 데이터'),
     status: z.number().describe(`그리드 상태값: GRID.STATUS.LOADING(0), GRID.STATUS.DATA_EXISTS(1), GRID.STATUS.ERROR(9) 중 하나를 사용해야 합니다.
 
+    ⚠️ LOADING은 그리드 **전체**를 가리는 로딩입니다. "이 셀만/이 행만 갱신 중" 같은 부분 로딩은 status로 표현할 수 없습니다 — status는 DATA_EXISTS로 두고, ref API(refreshCells/redrawRows) + 로딩 키 Set(useRef) 조합으로 구현합니다. '셀 단위 로딩' / '행 단위 로딩' 예제 참고.
+
     **필수 구현 패턴:**
     반드시 useState로 상태를 관리하고, useEffect 등을 사용하여 데이터 로딩 로직을 구현해야 합니다.
     사용자는 이 상태 제어 코드 안에 실제 비즈니스 로직(API 호출, 데이터 처리 등)을 추가할 수 있습니다.
@@ -190,7 +193,7 @@ export const DataGridSchema = z.object({
     onGridReady: z.string().optional().describe('그리드 준비 이벤트 핸들러(stringified)'),
     onFirstDataRendered: z.string().optional().describe('첫 데이터 렌더링 이벤트 핸들러(stringified)'),
     onGridSizeChanged: z.string().optional().describe('그리드 크기 변경 이벤트 핸들러(stringified)'),
-    onSelectionChanged: z.string().optional().describe('선택 변경 이벤트 핸들러(stringified)'),
+    onSelectionChanged: z.string().optional().describe('선택 변경 이벤트 핸들러(stringified). 반드시 gridOptions가 아니라 이 top-level prop으로 넘겨야 호출됨 (래퍼가 AG Grid 이벤트를 내부에서 잡고 이 prop을 부름). 인자는 이벤트 객체가 아니라 선택된 노드 배열: (selectedNodes) => setCount(selectedNodes.length)'),
     onCellClick: z.string().optional().describe('셀 클릭 이벤트 핸들러(stringified)'),
     onFilterChanged: z.string().optional().describe('필터 변경 이벤트 핸들러(stringified)'),
     onUpdateFilter: z.string().optional().describe('필터 업데이트 이벤트 핸들러(stringified)'),
@@ -252,6 +255,18 @@ export function createDataGridComponent() {
       // 10행 초과 시에만 고정 높이 부여 (autoHeight 셀은 가변이라 픽셀 고정값 사용)
       <OpsnowCommonDataGrid gridOptions={gridOptions} gridHeight={isScroll ? 600 : undefined} />
 
+      **셀·행 단위 부분 로딩 (Partial Loading) — status로 하지 말 것**
+      status={GRID_STATUS.LOADING}은 그리드 전체를 가립니다. "이 셀만 재계산 중", "선택한 행만 동기화 중" 같은 부분 로딩은
+      status는 DATA_EXISTS로 유지하고 아래 조합으로 앱에서 구현합니다 ('셀 단위 로딩' / '행 단위 로딩' 예제 전문 참고):
+      1. 로딩 중인 키는 useState가 아니라 useRef(new Set()) 에 담는다 — state로 두면 그리드 전체 리렌더로 스크롤이 튄다
+      2. 셀 단위: gridRef.current.refreshCells({ rowNodes, columns, force: true }) — 값이 그대로라 force: true 필수. rowNodes 생략 시 컬럼 전체
+      3. 행 단위: gridOptions.rowClassRules + gridRef.current.redrawRows({ rowNodes }) — redrawRows 시 rowClassRules 재평가. 여러 행은 rowNodes 배열로 묶어 한 번만 호출
+      4. 인디케이터로 셀 콘텐츠를 치환하지 말고, 원래 콘텐츠를 visibility: hidden 으로 남기고 인디케이터를 position: absolute 로 겹친다 (autoHeight라 치환하면 행 높이가 바뀜)
+      5. columnDefs/셀 렌더러는 useMemo/useCallback 으로 고정 — 매 렌더마다 새로 만들면 그리드가 통째로 다시 그려진다
+      6. 선택 노드 수집: forEachNode + node.isSelected() (getSelectedNodes는 ref API에 없음). onSelectionChanged는 top-level prop (인자 = 선택 노드 배열)
+      ref API 요약: refreshCells / redrawRows / forEachNode / node.setDataValue(field, value) / downloadExcel / downloadCsv
+      rowModelType: 'serverSide' 그리드는 AG Grid 내장 loadingCellRenderer를 쓰는 것이 맞습니다.
+
       **import:**
       \`\`\`javascript
       import { useCommonComponents, useGlobalContext } from '@opsnow-common/opsnow-finops-common-ui-loader';

package/package.json

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