DataGrid

DataGrid - 마이그레이션 플레이북

기존 grid를 한 번에 치환하기보다 row identity, column model, edit pipeline, backend contract 순서로 분리해서 옮기는 방식을 정리합니다.

reopt designUpdated Jun 26, 2026

1. 권장 이행 순서

Step 1

현재 grid 계약 인벤토리

행 식별자, 컬럼 스키마, 편집 정책, selection, clipboard, backend fetch/save 계약을 먼저 문서화합니다.

Step 2

row / column 모델 재정의

도메인 row 타입과 DataGridColumn 배열을 분리하고, getValue/setValue 기준으로 컬럼 책임을 고정합니다.

Step 3

편집 파이프라인 이관

단건 commit, 일괄 편집, paste/delete/fill 정책을 onCellCommit, onCellsEdited, onPaste로 옮깁니다.

Step 4

성능 설정 조정

getRowId, valueCache, rowBufferPx, maxRenderedRows를 기준으로 기존 성능 튜닝 포인트를 다시 매핑합니다.

Step 5

remote datasource 연결

서버 window fetch나 배치 저장이 있으면 migration 막바지에 remote protocol을 붙입니다.

Step 6

점진 rollout

읽기 전용 화면부터 교체하고, 편집형 화면은 rejectedEdits와 rollback 처리까지 검증한 뒤 전환합니다.

2. 개념 매핑 표

기존 개념	opt-datagrid 대응	핵심 포인트
row key / item id	`getRowId(row)`	정렬, reorder, remote refresh 이후에도 stable identity를 유지해야 합니다.
column accessor / valueGetter	`column.getValue(row)`	표시값 계산 로직을 컬럼 객체로 모읍니다.
column setter / onCellEdited	`column.setValue(row, nextValue) + onCellCommit`	도메인 row 변경과 commit side effect를 분리합니다.
selection model	`gridSelection + onGridSelectionChange`	active cell과 range selection을 제어형 상태로 올릴 수 있습니다.
viewport event / infinite loading	`onVisibleRegionChanged 또는 remote datasource`	스크롤 위치 추적과 server fetch 트리거를 구분합니다.
bulk update / clipboard hooks	`onCellsEdited, onPaste, onDelete, onFillPattern`	엑셀형 일괄 편집 정책을 한 레이어에서 다룹니다.

3. 컬럼 모델 전환 예제

migration의 핵심은 기존 grid-specific column 정의를 DataGridColumn<Row>로 재정의하는 것입니다. 아래처럼 값을 읽는 로직과 쓰는 로직을 컬럼 객체에 붙이면 편집 정책을 더 쉽게 테스트할 수 있습니다.

tsx

type OrderRow = {
  id: string;
  customer: string;
  status: "draft" | "confirmed";
};

const columns: DataGridColumn<OrderRow>[] = [
  {
    id: "customer",
    title: "Customer",
    width: 220,
    editable: true,
    getValue: (row) => row.customer,
    setValue: (row, nextValue) => ({ ...row, customer: nextValue }),
  },
  {
    id: "status",
    title: "Status",
    width: 160,
    editable: true,
    getValue: (row) => row.status,
    setValue: (row, nextValue) => ({
      ...row,
      status: nextValue as OrderRow["status"],
    }),
  },
];

<DataGrid
  rows={rows}
  columns={columns}
  getRowId={(row) => row.id}
  onRowsChange={(nextRows) => setRows(Array.from(nextRows))}
  onCellCommit={({ row, columnId, nextValue }) => {
    auditChange(row.id, columnId, nextValue);
  }}
  ariaLabel="Order migration grid"
/>;

4. backend handoff 기준

migration 중 서버 window fetch나 batch save가 필요해지면, 여기서 더 임시 API를 늘리지 말고 원격 연동 계약으로 바로 넘어가서 view session 기반 계약을 맞추는 편이 좋습니다.

정렬, 필터, 대량 편집, 부분 실패가 동시에 존재하면 client-only migration으로 끝내기 어렵습니다. 그 시점부터는 remote datasource 설계를 migration 범위에 포함시키는 편이 낫습니다.

5. rollout 체크리스트

- 모든 row가 문자열 또는 숫자 기반 stable ID를 갖는지 확인합니다.

- 컬럼별 editable 여부와 custom editor 선택 기준을 문서화합니다.

- 성능 테스트 전에 valueCache와 rowBufferPx 기본값을 먼저 잡습니다.

- 기존 grid의 숨겨진 side effect를 onCellCommit 또는 onCellsEdited로 분리합니다.

- remote 저장이 있으면 rejectedEdits와 canonical rows 처리 규칙을 서버와 합의합니다.

- pilot 화면에서 키보드, clipboard, undo/redo, paste failure를 먼저 검증합니다.