@vmscloud/moz-ui-grid-react 0.1.19

package/docs/manual/examples.md

@@ -0,0 +1,2385 @@
+# moz-ui-grid-core 사용 예제
+
+> 본 문서는 [API 레퍼런스(reference.md)](reference.md)의 사용 예제 모음입니다. 타입·시그니처·옵션 표는 [reference.md](reference.md)에서 확인하세요.
+>
+> 패키지: `@vmscloud/moz-ui-grid-core` (클래스명은 호환을 위해 `PureSheet` 유지)
+
+## 목차
+
+- [기본 플랫 그리드](#기본-플랫-그리드)
+- [grid.rows 사용 예제](#gridrows-사용-예제)
+- [grid.columns 사용 예제](#gridcolumns-사용-예제)
+- [grid.changes 사용 예제](#gridchanges-사용-예제)
+- [grid.undoManager 사용 예제](#gridundomanager-사용-예제)
+- [grid.rowGroup 사용 예제](#gridrowgroup-사용-예제)
+- [grid.tree 사용 예제](#gridtree-사용-예제)
+- [트리 드래그 reorder 사용 예제](#트리-드래그-reorder-사용-예제)
+- [grid.pivot 사용 예제](#gridpivot-사용-예제)
+- [grid.masterDetail 사용 예제](#gridmasterdetail-사용-예제)
+- [grid.validation 사용 예제](#gridvalidation-사용-예제)
+- [grid.clipboard 사용 예제](#gridclipboard-사용-예제)
+- [grid.headers 사용 예제](#gridheaders-사용-예제)
+- [grid.io 사용 예제](#gridio-사용-예제)
+- [Reactive API 전체 사용 예제](#reactive-api-전체-사용-예제)
+- [이벤트 전체 사용 예제](#이벤트-전체-사용-예제)
+- [정렬/필터 사용 예제](#정렬필터-사용-예제)
+- [필터 그룹 사용 예제](#필터-그룹-사용-예제)
+- [값 목록 필터 사용 예제 (엑셀식 체크박스)](#값-목록-필터-사용-예제-엑셀식-체크박스)
+- [헤더 아이콘 이벤트 사용 예제](#헤더-아이콘-이벤트-사용-예제)
+- [저장본 마이그레이션 사용 예제](#저장본-마이그레이션-사용-예제)
+- [선택 모드 사용 예제](#선택-모드-사용-예제)
+- [셀 병합 사용 예제](#셀-병합-사용-예제)
+- [동적 행 높이 사용 예제](#동적-행-높이-사용-예제)
+- [데이터 조회 사용 예제](#데이터-조회-사용-예제)
+- [스크롤/네비게이션 사용 예제](#스크롤네비게이션-사용-예제)
+- [국제화 사용 예제](#국제화-사용-예제)
+- [포맷팅 사용 예제](#포맷팅-사용-예제)
+- [헤더/상태바 사용 예제](#헤더상태바-사용-예제)
+- [배치 작업 사용 예제](#배치-작업-사용-예제)
+- [데이터 내보내기 사용 예제](#데이터-내보내기-사용-예제)
+- [스트리밍/로더 사용 예제](#스트리밍로더-사용-예제)
+- [성능 조회 사용 예제](#성능-조회-사용-예제)
+
+---
+
+### 기본 플랫 그리드
+
+```typescript
+const grid = new PureSheet(container, {
+  mode: 'flat',
+  fields: [
+    // id = 컬럼 **식별자**(가리킬 때: 정렬/필터 상태, 폭, 저장 레이아웃).
+    // field = 원본 데이터 **키**(읽을 때: row[field]). 생략하면 id 와 같은 값으로 정규화.
+    { id: 'name', header: '이름', dataType: 'string', width: 200 },
+    { id: 'age', header: '나이', dataType: 'number', width: 100, align: 'right' },
+    { id: 'email', header: '이메일', dataType: 'string', flex: 1 },
+
+    // 같은 원본 컬럼을 두 번 배치 — id 로 구분한다 (ITSM-2026-002188)
+    { id: 'dept_raw',   field: 'dept', header: '부서(원본)', dataType: 'string' },
+    { id: 'dept_short', field: 'dept', header: '부서(약칭)', dataType: 'string' },
+  ],
+  data: employees,
+  rowSelection: { mode: 'multi' },
+  editable: true,
+});
+
+// 초기화 완료 대기
+await grid.waitForReady();
+
+// 데이터 로드
+await grid.loadData(newData);
+
+// 새로고침
+await grid.refresh();
+
+// 리소스 해제
+grid.destroy();
+```
+
+---
+
+### grid.rows 사용 예제
+
+```typescript
+// ── 행 조회 ──
+const row = grid.rows.getById('row-1');       // ID로 단일 행
+const rowByIdx = grid.rows.getByIndex(0);     // sourceIndex로 단일 행 O(1)
+const allRows = grid.rows.all();              // 전체 행
+const filtered = grid.rows.where(             // 조건부
+  (data, state) => data.age > 30 && state !== 'deleted'
+);
+const batch = grid.rows.getByIds([1, 2, 3]); // ID 목록
+const byIndices = grid.rows.getByIndices([0, 1, 2]); // sourceIndex 목록
+
+// ── 반응형 ──
+const reactiveRow = grid.rows.observeById('row-1');     // ID 기반
+const reactiveByIdx = grid.rows.observeByIndex(0);      // sourceIndex 기반
+
+// ── 선택 (행 쓰기) ──
+grid.rows.selectRowsByIds([1, 2, 3]);                 // rowId 배열로 행 선택
+grid.rows.selectRowsByViewIndices([0, 1, 2]);         // viewIndex(화면 물리 순서) 배열로 — 정렬/필터 정확
+grid.rows.selectRowRangeByViewIndex(2, 6);           // 화면상 N~M번째 범위 선택
+grid.rows.selectRowRangeByIds('r2', 'r7');           // rowId 범위 선택(정렬/필터 안정)
+grid.rows.selectAllRows();                             // 전체 선택
+grid.rows.clearRowSelection();                        // 행 선택 해제
+
+// ── 선택 (셀 쓰기) ──
+grid.cells.selectCellsByIds([{ rowId: 5, columnId: 'name' }]);        // rowId+열
+grid.cells.selectCellsByViewIndices([{ viewIndex: 3, columnId: 'name' }]); // viewIndex+열
+grid.cells.selectCellRangeByViewIndex(                 // 셀 사각형 범위 (viewIndex)
+  { viewIndex: 2, columnId: 'name' },
+  { viewIndex: 6, columnId: 'salary' },
+);
+grid.cells.selectCellRangeByIds(                        // 셀 사각형 범위 (rowId, 정렬/필터 안정)
+  { rowId: 'r2', columnId: 'name' },
+  { rowId: 'r7', columnId: 'salary' },
+);
+grid.cells.clearCellSelection();                   // 셀 선택만 해제
+
+// ── 선택 조회 (행 — grid.rows) ──
+const ids = grid.rows.getSelectedRowIds();                     // 선택된 행 rowId
+const srcIdx = await grid.rows.getSelectedRowIndices();        // sourceIndex
+const viewIdx = await grid.rows.getSelectedRowViewIndices();   // viewIndex(화면 물리 순서)
+const dispIdx = await grid.rows.getSelectedRowDisplayedIndices(); // displayedIndex(화면 표시 순서)
+
+// ── 선택 조회 (셀 — grid.cells) ──
+const cells = grid.cells.getSelectedCellIds();               // [{ rowId, columnId }, ...]
+const cellRowIds = grid.cells.getSelectedCellRowIds();       // 걸친 행 rowId (중복 제거)
+const cellCols = grid.cells.getSelectedCellColumnIds();     // 걸친 컬럼 columnId (중복 제거)
+
+// ── 선택 상태 (RowHandle 기반 — grid.selection) ──
+const selRows = grid.selection.getSelectedRows();  // RowHandle[] (viewIndex/sourceIndex 채워짐)
+const activeRow = grid.selection.getActiveRow();   // RowHandle | null (traversal 앵커)
+const selCells = grid.selection.getSelectedCells(); // [{ row: RowHandle, columnId }, ...]
+const activeCell = grid.selection.getActiveCell(); // { row: RowHandle, columnId } | null
+
+
+// ── 다음/이전 이동 (traversal) — Drawer 상세 네비게이션 패턴 ──
+// 현재 선택 앵커에서 displayed 순서로 ±1 이동. 접힌 그룹의 자식은 자동 스킵된다.
+async function move(dir: 1 | -1) {
+  const anchor = grid.selection.getActiveRow();          // 마지막 상호작용 행
+  const cur = anchor ? await grid.rows.getDisplayedIndexById(anchor.id) : -1;
+  const total = grid.rows.displayedCount();
+  for (let i = cur + dir; i >= 0 && i < total; i += dir) {
+    const info = await grid.rows.getByDisplayedIndex(i);
+    if (info?.type === 'data' && info.rowId != null) {
+      grid.rows.selectRowsByIds([info.rowId]);               // 그 행으로 이동·선택
+      return info.rowId;                                  // Drawer에 이 rowId의 detail 표시
+    }
+  }
+  return null; // 경계 도달
+}
+
+// ── 숨은(접힌 그룹 속) 행으로 이동 ──
+// getDisplayedIndexById가 -1이면 조상 그룹을 펼친 뒤 이동
+async function goToRow(rowId: string | number) {
+  if (await grid.rows.getDisplayedIndexById(rowId) < 0) {
+    await grid.rowGroup.expandToRow(rowId);              // 조상 그룹 모두 펼침
+  }
+  grid.rows.selectRowsByIds([rowId]);
+}
+
+
+// ── 집계 ──
+const result = grid.rows.selectionAggregates();
+// → {
+//   columns: [
+//     { columnId: 'salary', header: 'Salary', aggregate: 'sum', value: 325000, formattedValue: '$325,000', count: 5 },
+//   ],
+//   total: { sum: 325000, avg: 65000, count: 5, totalCount: 5, min: 50000, max: 90000 }
+// }
+
+// ── 선택 일괄 ──
+const deletedCount = await grid.rows.deleteSelectedRows();
+const updatedCount = await grid.rows.updateSelectedRows('status', 'approved');
+const discardedCount = await grid.rows.discardSelectedRows();
+
+// ── 데이터 행 고정 ──
+grid.rows.pinTopById('row-1');               // ID로 기존 행을 상단 고정
+grid.rows.pinTopByIndex(0);                  // sourceIndex로 기존 행을 상단 고정
+grid.rows.pinBottomById('row-2');            // ID로 기존 행을 하단 고정
+grid.rows.pinBottomByIndex(1);               // sourceIndex로 기존 행을 하단 고정
+
+// ── 구조적 행 고정 ──
+const pinnedRow = grid.rows.addPinnedTop({ id: 'summary', label: '요약', amount: 9999 });
+grid.rows.addPinnedBottom({ id: 'footer', label: '합계' });
+
+// ── 고정 관리 ──
+grid.rows.unpinById('summary');
+const { top, bottom } = grid.rows.getPinned();
+grid.rows.clearPinned();
+grid.rows.refreshPinned();
+
+// ── 구조적 행 ──
+grid.rows.addGrandTotal([
+  { field: 'amount', aggregate: 'sum' },
+  { field: 'quantity', aggregate: 'avg' },
+]);
+grid.rows.addFilter();
+```
+
+---
+
+### grid.columns 사용 예제
+
+```typescript
+// ── 고정 ──
+grid.columns.pinLeft('name');
+grid.columns.pinRight('total');
+grid.columns.unpin('name');
+
+// ── 너비 ──
+grid.columns.setWidth('name', 300);
+grid.columns.autoFit('name', true);
+grid.columns.autoFitAll();           // 일회성
+grid.columns.autoFitAll(true);       // 영구 적용
+
+// ── 순서 (일반 헤더) ──
+grid.columns.setOrder(['id', 'name', 'email', 'age']);
+
+// ── 순서 (컬럼 그룹) ── 그룹 ID를 포함하여 전달
+grid.columns.setOrder(['personal', 'work', 'age'], {
+  leafOrders: { personal: ['name', 'email'] }  // 그룹 내 리프 순서 지정 (선택)
+});
+
+// ── 단일 컬럼 이동 ──
+grid.columns.move('email', 'name', 'before');  // email을 name 앞으로
+grid.columns.move('email', 'name', 'after');   // email을 name 뒤로
+// 컬럼 그룹에서 lockToGroup=true이면 같은 그룹 내에서만 이동 가능
+
+// ── 그룹 통째로 이동 (같은 레벨 형제 간) ──
+grid.columns.moveGroup('personal', 'work', 'after');  // personal 그룹을 work 뒤로
+
+// ── 가시성 ──
+grid.columns.hide('email');
+grid.columns.show('email');
+grid.columns.setHidden('email', true);
+grid.columns.toggle('email');
+
+// ── 상태 저장/복원 ──
+const json = grid.columns.save();
+grid.columns.load(json);           // JSON에서 복원
+
+// ── 조회 (모두 ColumnInfo[] / ColumnInfo — 동일한 키 집합) ──
+// ColumnInfo = 정적 ColumnDef + 런타임 ColumnState 합본
+// header/type/align/mask/cellAttributes/headerAttributes/aggregate ... + width/pinned/visible/order/offset ...
+const all = grid.columns.getAll();                // 전체, 정의 순서
+const map = grid.columns.getMap();                // getAll 의 별칭 (하위호환)
+const states = grid.columns.getState();           // 전체, state 배열 순서
+const visible = grid.columns.getVisibleColumns(); // 보이는 것만, order 순
+const col = grid.columns.getById('name');         // 단건
+
+// ── 통합 변경: columns.update(colId, partial, options?) ──
+// FieldDef/ColumnDef 키들을 한 번에 부분 갱신. 변경 키별로 적절한 렌더 자동 발화.
+grid.columns.update('amount', {
+  align: 'right',
+  header: '금액',
+  mask: { type: 'numeric', pattern: '#,##0', prefix: '$' },
+  cellAttributes: { class: 'highlight', style: 'background:#fffbe6' },
+});
+
+// updateSnapshot: 변경분을 초기 스냅샷에도 미러 → 이후 reset 시 이 변경을 포함한 새 baseline 으로 복귀
+grid.columns.update('amount', { header: '판매금액' }, { updateSnapshot: true });
+
+// ── 복귀: columns.reset / resetAll ──
+grid.columns.reset('amount');   // 1개 컬럼 — 초기 스냅샷 복귀 (정적 + 런타임 양쪽)
+grid.columns.resetAll();        // 전체 복귀. 컬럼 그룹 없을 때 컬럼 순서도 함께 복원
+
+// ── 이벤트 ──
+grid.on('column:update', ({ columnId, changedKeys }) => {
+  console.log(`${columnId} 변경:`, changedKeys);
+});
+grid.on('column:reset', ({ columnId }) => {
+  // columnId === null 이면 resetAll
+});
+```
+
+---
+
+### grid.changes 사용 예제
+
+```typescript
+// ── CRUD (Dirty State) ──
+const newId = await grid.changes.addRow({ name: '신규', age: 0 });
+await grid.changes.addRow({ name: '삽입', age: 25 }, 3); // 인덱스 3에 삽입
+
+// ById 패턴 (rowId 기반)
+await grid.changes.updateCellById('row-1', 'name', '수정됨');
+await grid.changes.deleteRowById('row-1');
+await grid.changes.undeleteRowById('row-1');
+const restoredCount = await grid.changes.undeleteRowsById([1, 2, 3]);
+
+// 행 객체 패턴 (enableReferCache 필요)
+const row = await grid.getRowById('row-1');
+await grid.changes.updateCell(row, 'name', '수정됨');
+await grid.changes.deleteRow(row);
+await grid.changes.undeleteRow(row);
+
+// ByIndex 패턴 (sourceIndex O(1))
+await grid.changes.updateCellByIndex(0, 'name', '수정됨');
+await grid.changes.deleteRowByIndex(0);
+
+// ── 선택 행 삭제 ──
+const count = await grid.changes.deleteSelectedRows();
+// (RowsAPI 쪽은 `grid.rows.deleteSelectedRows()` — 이름이 다름에 주의)
+
+// ── 변경 취소 ──
+await grid.changes.discardById('row-1');         // ID로 단일 행
+await grid.changes.discard(row);                 // 행 객체로
+await grid.changes.discardByIndex(0);            // sourceIndex로
+const discarded = await grid.changes.discardSelectedRows(); // 선택 행
+await grid.changes.discardImmediateById('row-1'); // undo 스택 미경유, 즉시 반영
+await grid.changes.discardImmediate(row);         // 행 객체로 즉시 반영
+await grid.changes.discardImmediateByIndex(0);    // sourceIndex로 즉시 반영
+await grid.changes.discardAll();                  // 전체
+
+// ── 커밋 ──
+try {
+  await grid.changes.commit();           // invalid 있으면 PS715 throw + 첫 invalid로 자동 점프
+} catch (err) {
+  console.warn(err.message);              // 사용자가 invalid 셀을 확인 가능
+}
+await grid.changes.commit({ allowInvalid: true });  // 검증 무시하고 강제 commit
+
+// ── 조회 ──
+const dirty = grid.changes.hasChanges;
+const summary = grid.changes.getAll();
+// → { added: [...], modified: [...], deleted: [...], reorderedOrder: [...] | null }
+const state = grid.changes.getRowStateById('row-1');
+// → 'pristine' | 'added' | 'modified' | 'deleted'
+const stateByIdx = grid.changes.getRowStateByIndex(0);
+const stateByRow = grid.changes.getRowState(row);
+
+// ── 대량 업데이트 ──
+const updated = await grid.changes.bulkUpdate('status', 'done', 'selected');
+const updatedAll = await grid.changes.bulkUpdate('flag', true, 'all');
+
+// ── 행 재정렬 ──
+await grid.changes.reorderRow(2, 5);  // 인덱스 2→5
+const order = grid.changes.getRowOrder();
+const reordered = grid.changes.isReordered();
+```
+
+---
+
+### grid.undoManager 사용 예제
+
+```typescript
+// ── Undo/Redo ──
+grid.undoManager.undo();
+grid.undoManager.redo();
+console.log(grid.undoManager.canUndo); // true/false
+console.log(grid.undoManager.canRedo); // true/false
+
+// ── 배치 (여러 작업을 하나의 Undo 단위로) ──
+grid.undoManager.beginBatch('대량 수정');
+await grid.changes.updateCellById(1, 'name', 'A');
+await grid.changes.updateCellById(2, 'name', 'B');
+await grid.changes.updateCellById(3, 'name', 'C');
+await grid.undoManager.endBatch();
+// → Undo 1번으로 3개 셀 모두 복원
+
+// ── 콜백 배치 ──
+await grid.undoManager.batch(async () => {
+  await grid.changes.addRow({ name: '행1' });
+  await grid.changes.addRow({ name: '행2' });
+}, { description: '행 2개 추가' });
+
+// ── skipUndo 옵션 ──
+await grid.undoManager.batch(async () => {
+  await grid.changes.updateCellById(1, 'timestamp', Date.now());
+}, { skipUndo: true }); // Undo 스택에 기록하지 않음
+
+// ── undoThrough — 특정 command까지 cascade undo (낙관적 파이프라인 롤백) ──
+// e.commandId는 row:reordered / changes:undone 이벤트가 주는 값 (= BatchCommand.id).
+// target + 그 위(더 최신) 전부를 top→target 순으로 되돌리고, 되돌린 id 배열을 반환.
+grid.on('row:reordered', async (e) => {
+  try {
+    await api.applyReorder(e.patches);          // 낙관적: UI는 이미 반영됨
+  } catch {
+    // 실패한 그 작업 + 그 위에 쌓인 것 전부 롤백 (위치 기반 undo()는 엉뚱한 top을 되돌림)
+    const rolledBack = grid.undoManager.undoThrough(e.commandId);
+    console.log('cascade 롤백:', rolledBack); // [topId, ..., targetId]
+    // 백엔드 롤백은 changes:undone이 cascade 개수만큼 자동 발화 → 별도 핸들러가 처리
+  }
+});
+// 미존재/빈 스택/이미 롤백된 id → [] 반환 (idempotent, throw 없음)
+
+// ── 스택 접근 ──
+const stack = grid.undoManager.getStack();
+```
+
+---
+
+### grid.rowGroup 사용 예제
+
+> 정식 네임스페이스는 `grid.rowGroup`입니다. 구 `grid.group`은 deprecated 별칭으로 계속 동작합니다(다음 major에서 제거 예정).
+
+```typescript
+// ── 그룹화 설정 ──
+await grid.rowGroup.setConfig({
+  columns: ['region', 'category'],
+  aggregates: { amount: 'sum', quantity: 'avg' },
+  defaultCollapsed: false,
+});
+
+// ── 간편 그룹화 ──
+await grid.rowGroup.groupBy(['region', 'category']);
+
+// ── 그룹 설정 조회 ──
+const groupConfig = grid.rowGroup.getConfig();
+
+// ── 그룹 토글/펼침/접힘 ──
+await grid.rowGroup.toggle('region:서울');
+await grid.rowGroup.expand('region:서울');
+await grid.rowGroup.collapse('region:서울');
+console.log(grid.rowGroup.isCollapsed('region:서울')); // true/false
+await grid.rowGroup.expandAll();
+await grid.rowGroup.collapseAll();
+
+// ── 레벨별 펼침/접힘 ──
+await grid.rowGroup.expandToLevel(0);   // 최상위만 펼침 — ⚠️ 이벤트 미발화(알려진 갭)
+await grid.rowGroup.collapseToLevel(0); // 최상위만 남기고 접기 — ⚠️ 이벤트 미발화
+await grid.rowGroup.expandAtLevel(1);   // 정확히 레벨 1 그룹만 펼침 — 다른 레벨 보존
+await grid.rowGroup.collapseAtLevel(1); // 정확히 레벨 1 그룹만 접힘 — 다른 레벨 보존
+
+// ── 그룹 컬럼 추가/제거 ──
+await grid.rowGroup.addColumn('product');
+await grid.rowGroup.removeColumn('category');
+
+// ── 그룹 멤버 rowId 조회 (groupId = "col:val/col:val" 경로 = GroupRowContext.groupId) ──
+// 소스 전체 스캔이라 접힘/필터 무관, 중첩 그룹이면 하위 전체 포함.
+// 메서드명은 getGroupRows 그대로 유지.
+grid.rowGroup.getGroupRows('region:서울');            // 서울 하위 모든 데이터 행 rowId[]
+grid.rowGroup.getGroupRows('region:서울/category:가전'); // 중첩 경로
+// 예: 그룹 단위 일괄 수정
+const ids = grid.rowGroup.getGroupRows('region:서울');
+grid.rows.getByIds(ids).setValue('flag', true);    // enableReferCache: true 필요
+
+// ── 그룹화 해제 ──
+await grid.rowGroup.clear();
+
+// ── 토글 이벤트 구독 (구 onGroupToggle config 콜백 대체) ──
+// 헤더 클릭은 source:'user', 프로그래매틱 API 호출은 source:'api'로 발화.
+grid.on('rowGroup:toggle', (e) => {
+  if (e.source === 'api') return; // 프로그래매틱 재진입 무한루프 방지
+  console.log('single toggle', e.groupId, e.collapsed);
+});
+grid.on('rowGroup:batchToggle', (e) => {
+  // 여러 그룹 일괄 토글. e.scope로 구분 — 화면 밖 포함 전체 groupIds가 1회로 요약 통지됨.
+  switch (e.scope) {
+    case 'level':   // 같은 depth 일괄(Ctrl/Cmd+클릭 또는 expandAtLevel/collapseAtLevel). e.level 존재.
+      console.log('level toggle', e.level, e.groupIds, e.collapsed); break;
+    case 'toLevel': // 특정 depth까지 누적(expandToLevel/collapseToLevel). e.level 존재.
+      console.log('toLevel toggle', e.level, e.groupIds, e.collapsed); break;
+    case 'all':     // 전체(expandAll/collapseAll). e.level은 undefined.
+      console.log('all toggle', e.groupIds, e.collapsed); break;
+  }
+});
+// 그룹 체크박스 cascade (구 group:checkbox 에서 리네임)
+grid.on('rowGroup:checkbox', (e) => console.log(e.groupId, e.checked, e.memberCount));
+```
+
+---
+
+### grid.tree 사용 예제
+
+```typescript
+// ── 트리 설정 (flat 구조 — parentId 기반) ──
+await grid.tree.setConfig({
+  idField: 'id',
+  parentField: 'parentId',
+  treeColumn: 'name',
+  defaultExpandLevel: 1,
+  aggregates: { amount: 'sum' },
+});
+
+// ── 트리 설정 (중첩 구조 — children 배열) ──
+await grid.tree.loadData(nestedData, {
+  idField: 'id',
+  childrenField: 'children',
+  treeColumn: 'name',
+});
+
+// ── 노드 조작 ──
+await grid.tree.toggle('node-1');
+await grid.tree.expand('node-1');
+await grid.tree.collapse('node-1');
+await grid.tree.expandAll();
+await grid.tree.collapseAll();
+await grid.tree.expandToLevel(2);   // 레벨 2까지 펼침
+await grid.tree.collapseToLevel(0); // 루트만 남기고 접기
+await grid.tree.expandAtLevel(1);   // 정확히 레벨 1 노드만 펼침 — 다른 레벨 보존
+await grid.tree.collapseAtLevel(1); // 정확히 레벨 1 노드만 접힘 — 다른 레벨 보존
+console.log(grid.tree.isCollapsed('node-1')); // true/false
+
+// ── 경로 펼치기 (검색 결과 표시용) ──
+await grid.tree.expandPath('deep-node-42'); // 조상 노드를 모두 펼쳐서 대상 노드를 보이게 함
+
+// ── 프로그램 방식 노드 이동 (드래그 없이 코드로) ──
+// moveNode(nodeId, newParentId, newIndex?) — newIndex는 "이동 후 최종 위치".
+// flat 그리드 changes.reorderRow의 tree 대칭 API. 원자 undo 단위 + row:reordered{kind:'tree'} 발화.
+await grid.tree.moveNode('report.pdf', 'work', 0);  // report.pdf를 work 폴더의 첫 자식으로
+await grid.tree.moveNode('work', null, 1);          // work를 root 레벨 index 1로 승격
+await grid.tree.moveNode('leaf', 'archive');        // newIndex 생략 → archive 맨 끝에 append
+// throw: PS401(nodeId 부재) / PS402(부모 부재) / PS403(cycle — 자기 자신·후손으로 이동)
+
+// ── 트래버설 (idField/parentField 값 기준 — 접힘/필터/정렬 무관, 소스 전체 스캔) ──
+grid.tree.getChildren('work');     // 직계 자식 rowId[] (소스 순서)
+grid.tree.getDescendants('work');  // 모든 자손 rowId[] (BFS)
+grid.tree.getParent('report.pdf'); // 부모 rowId | null
+grid.tree.getAncestors('report.pdf'); // 조상 rowId[] (가까운 부모 → root)
+
+// ── 부모↔자손 체크박스 cascade (boolean 컬럼 + editCommitted 트리거) ──
+// enableReferCache: true 필요 (rows.getByIds/getById는 idMap 기반 조회)
+let cascading = false;
+grid.on('cell:editCommitted', (e) => {
+  if (e.columnId !== 'checked' || cascading || e.rowId == null) return;
+  cascading = true;
+  try {
+    const next = !!e.newValue;
+    // ① 하향: 자손 전체를 같은 값으로
+    const descendants = grid.tree.getDescendants(e.rowId);
+    if (descendants.length) grid.rows.getByIds(descendants).setValue('checked', next);
+    // ② 상향: 가까운 조상부터 "자식 전부 체크 = 부모 체크" 재계산
+    const cur = new Map([[String(e.rowId), next], ...descendants.map(d => [String(d), next])]);
+    const valueOf = (id) => cur.has(String(id)) ? cur.get(String(id)) : !!grid.rows.getById(id).data?.checked;
+    for (const anc of grid.tree.getAncestors(e.rowId)) {
+      const all = grid.tree.getChildren(anc).every(valueOf);
+      grid.rows.getById(anc).setValue('checked', all);
+      cur.set(String(anc), all);
+    }
+  } finally { cascading = false; }
+  grid.refresh(); // 값이 안 바뀐 조상까지 재렌더 (부분체크 indeterminate 재계산 등)
+});
+
+// ── 설정 조회 ──
+const config = grid.tree.getConfig();
+```
+
+> **부분 체크 표시(indeterminate)** — boolean 셀은 native `<input>`이 아니라 `.ps-cell-checkbox` span이라
+> `formatRow(type:'data')`에서 `getDescendants` 체크 비율을 계산해 CSS 클래스로 `−`를 그립니다.
+> 전체 동작 데모는 `apps/demo/examples/tree-checkbox-cascade.html` 참조.
+
+---
+
+### 트리 드래그 reorder 사용 예제
+
+```typescript
+// ── 트리 드래그 reorder 활성화 (treeConfig + reorderableRows) ──
+const grid = new PureSheet(container, {
+  treeConfig: { idField: 'id', parentField: 'parentId', treeColumn: 'name' },
+  dragDropConfig: {
+    reorderableRows: true,        // treeConfig와 함께 → 트리 인식 드래그 자동 활성
+    dragTrigger: 'row',           // 행 본문 어디서나 드래그 (파일 탐색기 UX)
+    showDragHandleColumn: false,  // 핸들 컬럼 숨김
+    treeReorder: {
+      allowReparent: true,        // 다른 부모로 재부모화 허용
+      expandOnHover: 700,         // collapsed 부모 위 700ms hover → 자동 펼침
+      // 폴더 위 dwell → drop-onto(자식화), 파일 위 → insert-between(형제 사이)
+      resolveDropMode: (row) => (row.type === 'folder' ? 'drop-onto' : 'insert-between'),
+      isDroppableAsChild: (row) => row.type === 'folder',  // 폴더만 자식 수용
+      dropOntoEdgeThreshold: 2,   // 행 가장자리 2px는 drop-onto여도 형제 삽입으로 fall-back
+    },
+  },
+});
+
+// ── order 필드 자동 관리 + updatedAt 갱신 (flat/tree 공통) ──
+await grid.dragDrop.setConfig({
+  ...grid.dragDrop.getConfig(),
+  rowOrderField: { field: 'order', strategy: 'dense' },  // tree에서도 형제 순서 자동 저장
+  mutateOnDirty: (row, ctx) => {
+    if (ctx.type === 'tree-reorder' || ctx.type === 'reorder') {
+      return { updatedAt: new Date().toISOString() };
+    }
+  },
+});
+
+// ── 완료 통지: row:reordered {kind:'tree'} ──
+grid.on('row:reordered', (e) => {
+  if (e.kind !== 'tree') return;
+  console.log('트리 이동:', e.patches, 'commandId:', e.commandId);
+  // 낙관적 백엔드 sync + 실패 시 undoThrough(e.commandId) → 이벤트 예제 섹션 참조
+});
+
+// ── 드래그 없이 프로그램 방식 이동 ──
+await grid.tree.moveNode('report.pdf', 'work', 0);  // work 폴더 첫 자식으로
+```
+
+> 낙관적 백엔드 동기화(실패 시 `undoThrough` cascade 롤백) + undo/redo 시 `changes:undone`/`changes:redone` 처리 전체 흐름은 [이벤트 전체 사용 예제](#이벤트-전체-사용-예제)와 [grid.undoManager 사용 예제](#gridundomanager-사용-예제)를 참조하세요.
+
+---
+
+### grid.pivot 사용 예제
+
+```typescript
+// ── 모드 관리 ──
+console.log(grid.pivot.getMode()); // 'flat' | 'pivot'
+await grid.pivot.setMode('pivot');
+
+// ── 피벗 설정 ──
+await grid.pivot.setConfig({
+  rowFields: [
+    { field: 'region', header: '지역' },
+    { field: 'category', header: '카테고리' },
+  ],
+  columnFields: [
+    { field: 'quarter', header: '분기' },
+  ],
+  valueFields: [
+    { field: 'sales', header: '매출', aggregate: 'sum', showValueAs: 'none' },
+    { field: 'profit', header: '이익', aggregate: 'sum', showValueAs: 'percentOfGrandTotal' },
+  ],
+  showRowGrandTotals: true,
+  showColumnGrandTotals: true,
+  showRowSubTotals: true,
+  rowSubTotalPosition: 'after',
+});
+
+// ⚠️ 같은 field 를 값 필드로 **여러 번** 넣을 때는 불변 id 를 명시한다 (ITSM-2026-002188).
+//    id 가 없으면 'sales-0' 같은 **순서 기반** 키로 폴백하는데, 값 필드 순서를 바꾸거나
+//    하나를 지우면 인덱스가 밀려 같은 저장본이 다른 필드를 가리킨다(수식 필터·조건부 서식이
+//    조용히 어긋남). 콘솔 경고도 함께 나온다.
+await grid.pivot.setConfig({
+  rowFields: [{ field: 'region', header: '지역' }],
+  valueFields: [
+    { field: 'sales', header: '매출 합계', aggregate: 'sum', id: 'sales_sum' },
+    { field: 'sales', header: '매출 평균', aggregate: 'avg', id: 'sales_avg' },
+  ],
+});
+
+const config = grid.pivot.getConfig(); // 깊은 복사본 반환
+const result = grid.pivot.getResult();
+
+// ── 편의 메서드: 소계/총합계 설정 ──
+await grid.pivot.setSubTotals({
+  showRowSubTotals: true,
+  rowSubTotalFields: ['category'],
+  rowSubTotalPosition: 'after',
+});
+await grid.pivot.setGrandTotals({
+  showRowGrandTotals: true,
+  showColumnGrandTotals: false,
+});
+
+// ── 편의 메서드: 필드 변경 ──
+await grid.pivot.setRowFields([{ field: 'region', header: '지역' }]);
+await grid.pivot.setColumnFields([{ field: 'year', header: '연도' }]);
+await grid.pivot.setValueFields([{ field: 'sales', header: '매출', aggregate: 'sum' }]);
+
+// ── 상태 저장/복원 ──
+const state = grid.pivot.getState();
+// → { config: {...}, collapsedRowNodes: ['region:서울'], collapsedColumnNodes: ['quarter:Q1'] }
+await grid.pivot.setState(state);
+
+// ── 행 노드 네비게이션 ──
+await grid.pivot.toggleRow('region:서울');
+await grid.pivot.expandRow('region:서울');
+await grid.pivot.collapseRow('region:서울');
+await grid.pivot.expandAllRows();
+await grid.pivot.collapseAllRows();
+await grid.pivot.expandRowAtLevel(0);    // 특정 레벨만 펼침
+await grid.pivot.collapseRowAtLevel(1);  // 특정 레벨만 접기
+await grid.pivot.expandRowToLevel(2);    // 레벨 2까지 펼침
+await grid.pivot.collapseRowToLevel(0);  // 레벨 0까지 접기
+console.log(grid.pivot.isRowCollapsed('region:서울'));
+const collapsedRows = grid.pivot.getCollapsedRowNodes();
+
+// ── 피벗 정렬/필터 (viewState 단일 채널 — field-level sort 옵션 없음) ──
+// 라벨 기준 정렬
+await grid.sort([{ id: 'region', direction: 'asc', sequence: 1 }]);
+// 값(집계) 기준 정렬 — byValue 로 집계 값 기준 정렬
+await grid.sort([{ id: 'region', direction: 'desc', sequence: 1, byValue: 'sales' }]);
+
+// 차원(행/열 필드) 필터 → core 가 자동으로 pre(소스 축소 후 재집계)로 분류
+await grid.filter([{ id: 'region', operator: 'eq', filterValue: '서울', sequence: 1 }]);
+// 값(measure) 필터 → 자동으로 post(피벗 값 기준 행 필터). excludeUnmatchedColumns 로 빈 컬럼까지 제거
+await grid.filter([
+  { id: 'sales', operator: 'gte', filterValue: 1000, sequence: 1, excludeUnmatchedColumns: true },
+]);
+// 명시 mode 로 분류 override (예: dimension 필터를 소스 축소 없이 post 로)
+await grid.filter([{ id: 'region', operator: 'eq', filterValue: '서울', sequence: 1, mode: 'post' }]);
+
+// ── 열 노드 네비게이션 (Row 메서드와 대칭) ──
+await grid.pivot.toggleColumn('quarter:Q1');
+await grid.pivot.expandAllColumns();
+await grid.pivot.collapseColumnToLevel(0);
+const collapsedCols = grid.pivot.getCollapsedColumnNodes();
+
+// ── 소스 행 매핑 (trackSourceRows: true 필요) ──
+const cellSources = await grid.pivot.getSourceRowsForCell(0, 'Q1_sales');
+const rowSources = await grid.pivot.getSourceRowsForRow(0);
+const selSources = await grid.pivot.getSourceRowsForSelection();
+
+// ── 메타/차트 ──
+const meta = grid.pivot.getPivotMeta();             // 동기, 경량 스냅샷
+const series = await grid.pivot.getSeriesData();    // 차트용 시리즈
+```
+
+---
+
+### grid.masterDetail 사용 예제
+
+```typescript
+// ── 디테일 설정 ──
+await grid.masterDetail.setConfig({
+  expandColumn: 'name',
+  singleExpand: false,
+  keepExpandedOnDataChange: false,
+  keepMasterDetailRows: true,
+  keepMasterDetailRowsCount: 10,
+  minHeight: 100,
+  maxHeight: 400,
+  isExpandable: (data) => data.hasDetails === true,
+  renderer: (container, parentData, dataIndex) => {
+    // 디테일 패널 렌더링
+    const div = document.createElement('div');
+    div.innerHTML = `<h3>${parentData.name} 상세</h3><p>인덱스: ${dataIndex}</p>`;
+    container.appendChild(div);
+
+    // cleanup 함수 반환 (선택)
+    return () => {
+      div.remove();
+    };
+  },
+});
+
+const config = grid.masterDetail.getConfig();
+
+// ── 디테일 조작 ──
+await grid.masterDetail.toggle(0);   // dataIndex 0 토글
+await grid.masterDetail.expand(3);   // dataIndex 3 펼침
+await grid.masterDetail.collapse(3); // dataIndex 3 접기
+await grid.masterDetail.expandAll();   // 전체 펼침
+await grid.masterDetail.collapseAll(); // 전체 접기
+console.log(grid.masterDetail.isExpanded(0)); // true/false
+
+// ── 설정 제거 ──
+await grid.masterDetail.setConfig(null);
+```
+
+---
+
+### grid.validation 사용 예제
+
+```typescript
+// ── 검증 실행 ──
+const errors = grid.validation.validateAll();            // trigger 기본 'commit' (['blur', 'commit'])
+const blurErrors = grid.validation.validateAll('blur');  // 특정 trigger만
+
+// ── 에러 조회 ──
+const allErrors = grid.validation.getErrors();
+// → [{ rowId: 1, field: 'name', messages: ['필수 입력'] }, ...]
+console.log(grid.validation.hasErrors()); // true/false
+
+// ── 에러 초기화 ──
+await grid.validation.clear();
+
+// ── 셀/행 단위 조회 ──
+const cellErrors = grid.validation.getCellErrors('user-5', 'email');
+// → ['이메일 형식 불일치'] | undefined
+const has = grid.validation.hasCellError('user-5', 'email'); // true/false
+
+const rowErrors = grid.validation.getRowErrors('user-5');
+// → Map { 'email' => ['...'], 'phone' => ['...'] } | undefined
+if (rowErrors) {
+  for (const [field, messages] of rowErrors) {
+    console.log(`${field}: ${messages.join(', ')}`);
+  }
+}
+
+// ── 외부 에러 주입 (백엔드 응답 반영) ──
+// 시나리오: commit 전 사전 검증 후 백엔드에 보냈는데 서버가 reject
+async function saveDirtyChanges() {
+  // 1) 클라이언트 검증 먼저
+  const clientErrors = grid.validation.validateAll();
+  if (clientErrors.length > 0) {
+    grid.validation.nextInvalid({ fromStart: true });
+    return alert(`${clientErrors.length}개 오류를 먼저 수정하세요.`);
+  }
+
+  // 2) 백엔드 전송
+  const dirty = grid.changes.getAll();
+  const response = await fetch('/api/save', {
+    method: 'POST',
+    body: JSON.stringify(dirty),
+  });
+
+  if (response.ok) {
+    // 3-a) 성공 → 검증 skip하고 commit (이미 검증 완료)
+    await grid.changes.commit({ allowInvalid: true });
+  } else {
+    // 3-b) 서버가 field-level 에러 반환
+    const { errors } = await response.json();
+    // errors: [{ rowId, field, messages }, ...]
+    for (const e of errors) {
+      grid.validation.setCellErrors(e.rowId, e.field, e.messages);
+    }
+    // 에러가 있는 첫 셀로 자동 이동
+    grid.validation.nextInvalid({ fromStart: true });
+  }
+}
+
+// ── 특정 행의 모든 에러 제거 (사용자가 해당 행을 다시 편집할 때) ──
+grid.validation.clearRowErrors('user-5');
+
+// ── 개별 셀 에러 제거 (입력 중 실시간으로 특정 제약 해소됨을 감지) ──
+grid.validation.clearCellErrors('user-5', 'email');
+
+// ── Invalid 셀 네비게이션 ──
+// 첫 invalid 셀로 이동 (anchor 무시)
+const first = grid.validation.nextInvalid({ fromStart: true });
+// → { rowId: 'user-5', field: 'email' } | null
+
+// 현재 선택 셀 이후의 다음 invalid
+const next = grid.validation.nextInvalid();
+
+// 이전 invalid
+const prev = grid.validation.prevInvalid();
+
+// wrap 없이 순회 (끝에서 멈춤)
+const lastInRange = grid.validation.nextInvalid({ wrap: false });
+if (lastInRange === null) {
+  console.log('더 이상 뒤에 invalid 셀이 없습니다.');
+}
+
+// ── commit 시 자동 점프 활용 ──
+try {
+  await grid.changes.commit();  // 실패 시 자동으로 첫 invalid로 점프
+} catch (err) {
+  // 에러 메시지 표시. anchor는 이미 첫 invalid 셀로 이동돼 있음.
+  alert(err.message);  // "[PureSheet] PS715 commit: error.PS715"
+}
+
+// ── 검증 무시하고 강제 commit ──
+await grid.changes.commit({ allowInvalid: true });
+
+// ── 커스텀 "Fix all errors" 워크플로우 ──
+async function fixAllErrors() {
+  let current = grid.validation.nextInvalid({ fromStart: true });
+  while (current) {
+    // UI로 사용자에게 수정 요청
+    await promptUserToFix(current);
+    current = grid.validation.nextInvalid({ wrap: false });
+  }
+  if (!grid.validation.hasErrors()) {
+    await grid.changes.commit();
+  }
+}
+```
+
+---
+
+### grid.clipboard 사용 예제
+
+```typescript
+// ── 복사 ──
+// 데이터만 복사
+const text = await grid.clipboard.copy();
+
+// 헤더 포함 복사
+const text = await grid.clipboard.copy({ includeHeaders: true });
+
+// ── 붙여넣기 ──
+const pastedCount = await grid.clipboard.paste();
+// → 6 (붙여넣기된 셀 수)
+```
+
+---
+
+### grid.headers 사용 예제
+
+```typescript
+// ── 컬럼 그룹 조작 ──
+grid.headers.collapse('personal');
+grid.headers.expand('personal');
+grid.headers.toggle('personal');
+console.log(grid.headers.isCollapsed('personal')); // true/false
+
+grid.headers.collapseAll();
+grid.headers.expandAll();
+
+// ── 특정 레벨만 (Ctrl/Cmd+클릭 "같은 depth 일괄" 제스처와 동일) ──
+grid.headers.collapseAtLevel(0);  // level 0 그룹만 접기
+grid.headers.expandAtLevel(0);    // level 0 그룹만 펼치기
+```
+
+---
+
+### grid.io 사용 예제
+
+```typescript
+// ── 1) 기본 export (메모리 Blob) ──
+const blob = await grid.io.toExcel({
+  scope: 'visible',
+  includeHeaders: true,
+  preserveFormatting: true,
+});
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'data.xlsx';
+a.click();
+URL.revokeObjectURL(url);
+
+// ── 2) 디스크 직접 저장 (FSA) + 분할 ──
+const abort = new AbortController();
+const result = await grid.io.saveExcelToFile({
+  suggestedName: 'huge-dataset.xlsx',
+  scope: 'all',
+  sheetSplit: 'auto',          // 1,048,576 행 한계 자동 분할
+  sheetNamePattern: 'Data ({n})',
+  freezeHeader: true,
+  autoFilter: true,
+  useWorker: true,
+  signal: abort.signal,
+  onProgress: (p) => {
+    if (p.currentSheet) {
+      console.log(`Sheet ${p.currentSheet}/${p.totalSheets} ${p.percent}%`);
+    } else {
+      console.log(`${p.phase}: ${p.percent}%`);
+    }
+  },
+});
+console.log(`Saved via ${result.mode}: ${result.fileName}`);
+
+// ── 3) 시트 정보 미리 조회 ──
+const sheets = await grid.io.getSheetInfo(file);
+// → [{ index: 0, name: 'Sheet1', estimatedRowCount: 5_000_000 }]
+
+// ── 4) 미리보기 (처음 20행만) ──
+const preview = await grid.io.previewExcel(file, { rows: 20 });
+console.log(preview.headers, preview.rows);
+
+// ── 5) Import: replace + 수동 검토 후 commit ──
+const importResult = await grid.io.fromExcel(file, {
+  mode: 'replace',
+  autoCommit: false,
+  onProgress: (p) => updateProgressBar(p.percent),
+});
+
+if (importResult.warnings?.includes('LARGE_IMPORT')) {
+  const ok = confirm(
+    `Import 결과 미리보기:\n` +
+    `+ 추가 ${importResult.addedCount}\n` +
+    `~ 수정 ${importResult.updatedCount}\n` +
+    `- 삭제 ${importResult.deletedCount}\n` +
+    `= 동일 ${importResult.unchangedCount}\n\n` +
+    `이대로 commit할까요?`
+  );
+  if (ok) await grid.changes.commit();
+  else await grid.changes.discardAll();
+}
+
+// ── 6) Import: append + skip 전략 ──
+const appendResult = await grid.io.fromExcel(file, {
+  mode: 'append',
+  conflictStrategy: 'skip',
+  autoCommit: true,
+});
+if (appendResult.conflicts?.length) {
+  console.warn(`충돌 ${appendResult.skippedCount}개 건너뜀:`, appendResult.conflicts);
+}
+
+// ── 7) Dry-run으로 변경 요약만 확인 (실제 dirty 반영 없음) ──
+const dry = await grid.io.fromExcel(file, {
+  mode: 'upsert',
+  dryRun: true,
+});
+console.log(`예상 변경: +${dry.addedCount} ~${dry.updatedCount} -${dry.deletedCount}`);
+
+// ── 8) Import 취소 ──
+const abortImport = new AbortController();
+setTimeout(() => abortImport.abort(), 5000);  // 5초 후 취소
+try {
+  await grid.io.fromExcel(file, { signal: abortImport.signal });
+} catch (err) {
+  if (err.name === 'AbortError') console.log('Import 취소됨');
+}
+
+// ── 9) 이벤트 구독 ──
+grid.on('io:import:complete', ({ rowCount, duration }) => {
+  console.log(`Import 완료: ${rowCount}행, ${duration.toFixed(0)}ms`);
+});
+grid.on('io:export:complete', ({ rowCount, fileSize }) => {
+  console.log(`Export 완료: ${rowCount}행, ${(fileSize / 1024 / 1024).toFixed(1)}MB`);
+});
+
+// ── 10) 피벗 모드 export (default) ──
+// 기본값 `pivotExpandCollapsed: true`로 접힘 무시 + 다단계 컬럼 헤더 + rowMergeInfo 병합까지 복원.
+// columnFields 2+level인 경우 `<mergeCells>`로 상위 헤더 colspan 병합됨.
+await grid.io.toExcel({
+  includeHeaders: true,
+  // pivotExpandCollapsed: true,  // default
+});
+
+// ── 11) 피벗 "화면에 보이는 것만" export ──
+// 현재 접힘 상태 그대로 export. row merge는 생략 (v1 안전 가드).
+await grid.io.toExcel({
+  pivotExpandCollapsed: false,
+});
+
+// ── 12) 원본 데이터 export (모든 모드 공통) ──
+// `exportSource: true`는 flat/pivot/tree/grouping 어떤 모드에서든 동작.
+// `sourceColumns` 옵션으로 포함 범위 선택:
+
+// 12-a) 원본의 모든 컬럼 (default) — 피벗에선 rowFields/columnFields 라벨 + 타입 추론 적용
+await grid.io.toExcel({
+  exportSource: true,
+  // sourceColumns: 'all',  // default
+});
+
+// 12-b) 피벗에 참여하는 필드만 — rowFields + columnFields + valueFields 교집합
+// 피벗 차원 + 집계 대상 컬럼만 필요할 때. flat 모드에서는 'all'과 동일.
+await grid.io.toExcel({
+  exportSource: true,
+  sourceColumns: 'used',
+});
+
+// 12-c) 미배치 필드까지 header 라벨로 — sourceFields 카탈로그 주입
+// 피벗 모드는 배치된 필드(rowFields/columnFields)에만 header가 있어, 행/열/값에
+// 안 들어간 원본 필드는 raw id로 새어 나간다. sourceFields로 모든 원본 필드의
+// header/type을 시드하면 미배치 필드도 사람이 읽는 header로 export된다.
+// (피벗 rowFields/columnFields의 header가 카탈로그를 override, valueFields는 제외.
+//  미지정 시 originalConfig.fields로 폴백.)
+await grid.io.toExcel({
+  exportSource: true,
+  sourceColumns: 'all',  // default
+  sourceFields: [
+    { field: 'region', header: '지역', dataType: 'string' },
+    { field: 'amount', header: '매출액', dataType: 'number' },
+    { field: 'memo', header: '비고' },  // 피벗 미배치 필드도 header로
+  ],
+});
+
+// ── 13) 플랫 셀 병합 (MergeStrategy) 보존 ──
+// grid.merge.setConfig({...})로 설정된 병합이 Excel <mergeCells>로 그대로 반영 (default true).
+await grid.io.toExcel({
+  preserveMerges: true,   // default
+});
+// 레거시 동작(평탄 export):
+await grid.io.toExcel({ preserveMerges: false });
+
+// ── 14) 플랫 컬럼 그룹 다단계 헤더 export ──
+// `columnGroups: [{ header: '개인정보', children: [...] }]` 같은 트리가 다단계 행 + merge로 복원.
+// default `preserveColumnGroups: true`이므로 별도 옵션 없이 동작.
+await grid.io.toExcel({});
+
+// ── 15) 플랫 그룹 행 3가지 모드 ──
+// 'include' (default): 접힘 무시, 모든 group header + data
+await grid.io.toExcel({ groupRowMode: 'include' });
+// 'visible': 현재 접힘 상태 반영 (collapsed 자식 제외)
+await grid.io.toExcel({ groupRowMode: 'visible' });
+// 'dataOnly': group header 행 제외, data 행만
+await grid.io.toExcel({ groupRowMode: 'dataOnly' });
+
+// ── 16) 조합: columnGroups + grouping + merge 동시 ──
+// 세 기능은 직교 조합 가능. 헤더는 컬럼 그룹 다단계, 데이터는 group row 섞임,
+// 각 data 행의 cell merge는 스트리밍 감지로 누적.
+await grid.io.toExcel({
+  preserveMerges: true,
+  preserveColumnGroups: true,
+  groupRowMode: 'include',
+});
+
+// ── 17) 트리 그리드 export ──
+// 기본: 모든 노드 + Excel 네이티브 outline (+/- 버튼).
+await grid.io.toExcel({ treeRowMode: 'include', treeOutline: true });
+// 현재 접힘 상태 그대로 (collapsed 자식은 xlsx에 없음).
+await grid.io.toExcel({ treeRowMode: 'visible' });
+// outline 없이 평탄한 트리 행만 내보내고 싶다면:
+await grid.io.toExcel({ treeRowMode: 'include', treeOutline: false });
+// 원본 평탄 데이터(트리 구조 전혀 없이)만 추출:
+await grid.io.toExcel({ exportSource: true });
+
+// ── 18) 그룹 행 + Excel outline ──
+// 기본: 그룹 행 + 데이터 행 + outline(+/- 버튼). groupOutline default true.
+await grid.io.toExcel({ groupRowMode: 'include' });
+// outline 없이 평탄 그룹 행만:
+await grid.io.toExcel({ groupRowMode: 'include', groupOutline: false });
+```
+
+---
+
+### Reactive API 전체 사용 예제
+
+#### grid.select() — GridState 주요 필드
+
+```typescript
+// ── 데이터 & 컬럼 ──
+const columns = grid.select(s => s.columns);
+columns.subscribe(() => console.log('컬럼 정의 변경:', columns.getSnapshot()));
+
+const columnStates = grid.select(s => s.columnStates);
+columnStates.subscribe(() => console.log('컬럼 UI 상태 변경:', columnStates.getSnapshot()));
+
+// ── 행 수 ──
+const totalRowCount = grid.select(s => s.totalRowCount);
+totalRowCount.subscribe(() => console.log('전체 행 수:', totalRowCount.getSnapshot()));
+
+const visibleRowCount = grid.select(s => s.visibleRowCount);
+visibleRowCount.subscribe(() => console.log('표시 행 수:', visibleRowCount.getSnapshot()));
+
+// ── 뷰 상태 ──
+const viewState = grid.select(s => s.viewState);
+viewState.subscribe(() => console.log('뷰 상태 변경:', viewState.getSnapshot()));
+
+// ── Feature 모듈 설정 (반응형 관측 계약) ──
+const pivotConfig = grid.select(s => s.pivotConfig);
+pivotConfig.subscribe(() => console.log('피벗 설정 변경:', pivotConfig.getSnapshot()));
+
+const pivotMode = grid.select(s => s.pivotMode);   // 'flat' | 'pivot'
+const treeConfig = grid.select(s => s.treeConfig);
+const masterDetailConfig = grid.select(s => s.masterDetailConfig);
+const groupConfig = grid.select(s => s.groupConfig);
+const dragDropConfig = grid.select(s => s.dragDropConfig);
+const mergeConfig = grid.select(s => s.mergeConfig);
+
+// ── 변경 추적 ──
+const hasChanges = grid.select(s => s.hasChanges);
+hasChanges.subscribe(() => console.log('변경 여부:', hasChanges.getSnapshot()));
+
+const changeVersion = grid.select(s => s.changeVersion);
+changeVersion.subscribe(() => console.log('변경 버전:', changeVersion.getSnapshot()));
+
+// ── 비동기 상태 ──
+const activity = grid.select(s => s.activity);
+activity.subscribe(() => {
+  const act = activity.getSnapshot();
+  if (act === 'idle') console.log('대기 중');
+  else console.log('작업 중:', act);
+});
+
+const isSearching = grid.select(s => s.isSearching);   // background 검색 진행 여부 (activity와 독립)
+isSearching.subscribe(() => console.log('검색 중:', isSearching.getSnapshot()));
+
+// ── 선택 ──
+const selectedRowCount = grid.select(s => s.selectedRowCount);
+selectedRowCount.subscribe(() => console.log('선택 행 수:', selectedRowCount.getSnapshot()));
+
+const selectedCellCount = grid.select(s => s.selectedCellCount);
+selectedCellCount.subscribe(() => console.log('선택 셀 수:', selectedCellCount.getSnapshot()));
+
+// ── 편집 ──
+const isEditing = grid.select(s => s.isEditing);
+isEditing.subscribe(() => console.log('편집 중:', isEditing.getSnapshot()));
+
+const editingCell = grid.select(s => s.editingCell);
+editingCell.subscribe(() => console.log('편집 셀:', editingCell.getSnapshot()));
+
+// ── Undo/Redo ──
+const canUndo = grid.select(s => s.canUndo);
+canUndo.subscribe(() => console.log('Undo 가능:', canUndo.getSnapshot()));
+
+const canRedo = grid.select(s => s.canRedo);
+canRedo.subscribe(() => console.log('Redo 가능:', canRedo.getSnapshot()));
+
+// ── 검증 ──
+const hasValidationErrors = grid.select(s => s.hasValidationErrors);
+hasValidationErrors.subscribe(() => console.log('검증 에러:', hasValidationErrors.getSnapshot()));
+
+const validationErrorCount = grid.select(s => s.validationErrorCount);
+validationErrorCount.subscribe(() => console.log('에러 수:', validationErrorCount.getSnapshot()));
+
+// ── 스크롤 ──
+const scrollTop = grid.select(s => s.scrollTop);
+scrollTop.subscribe(() => console.log('스크롤:', scrollTop.getSnapshot()));
+
+const visibleStartIndex = grid.select(s => s.visibleStartIndex);
+visibleStartIndex.subscribe(() => console.log('보이는 첫 행:', visibleStartIndex.getSnapshot()));
+
+const visibleEndIndex = grid.select(s => s.visibleEndIndex);
+visibleEndIndex.subscribe(() => console.log('보이는 끝 행:', visibleEndIndex.getSnapshot()));
+```
+
+#### 파생 셀렉터 (복합 상태)
+
+```typescript
+// 여러 상태를 조합한 파생 셀렉터
+const toolbar = grid.select(s => ({
+  canSave: s.hasChanges && !s.hasValidationErrors,
+  canUndo: s.canUndo,
+  canRedo: s.canRedo,
+  isBusy: s.activity !== 'idle',
+  rowCount: s.visibleRowCount,
+  selectedCount: s.selectedRowCount,
+}));
+
+toolbar.subscribe(() => {
+  const state = toolbar.getSnapshot();
+  saveButton.disabled = !state.canSave;
+  undoButton.disabled = !state.canUndo;
+  redoButton.disabled = !state.canRedo;
+  spinner.hidden = !state.isBusy;
+  statusLabel.textContent = `${state.rowCount}건 (${state.selectedCount}건 선택)`;
+});
+```
+
+#### grid.rows.observeById() — ReactiveRow 전체
+
+```typescript
+const row = grid.rows.observeById('row-1');
+
+// ── 구독 ──
+const unsub = row.subscribe(() => {
+  console.log('행 변경됨');
+});
+
+// ── 속성 읽기 (getter) ── 총 11개
+console.log(row.id);             // 'row-1'
+console.log(row.data);           // { id: 'row-1', name: '홍길동', age: 30 }
+console.log(row.exists);         // true
+console.log(row.state);          // 'pristine' | 'added' | 'modified' | 'deleted'
+console.log(row.selected);       // true/false
+console.log(row.readOnly);       // true/false
+console.log(row.visible);        // true/false
+console.log(row.pinned);         // 'top' | 'bottom' | null
+console.log(row.cssClass);       // 'highlight' | null
+console.log(row.height);         // 40 | null
+console.log(row.changedFields);  // ['name', 'age'] | null
+
+// ── Subscribable 인터페이스 ──
+const snapshot = row.getSnapshot(); // Row | undefined
+
+// ── 셀 접근 ──
+const nameCell = row.cell('name');
+```
+
+#### ReactiveCell 전체
+
+```typescript
+const cell = grid.rows.observeById('row-1').cell('amount');
+
+// ── 구독 ──
+const unsub = cell.subscribe(() => {
+  console.log('셀 값 변경:', cell.getSnapshot());
+});
+
+// ── 값 읽기 ──
+const value = cell.getSnapshot(); // CellValue
+
+// ── 값 쓰기 ──
+cell.set(1500);
+cell.set('변경됨');
+cell.set(null);
+```
+
+#### React useSyncExternalStore 통합
+
+```tsx
+import { useSyncExternalStore, useMemo } from 'react';
+
+// GridState 구독 훅
+function useGridState<T>(grid: PureSheet, selector: (state: GridState) => T): T {
+  const subscribable = useMemo(() => grid.select(selector), [grid, selector]);
+  return useSyncExternalStore(subscribable.subscribe, subscribable.getSnapshot);
+}
+
+// 행 구독 훅
+function useRow(grid: PureSheet, rowId: string | number) {
+  const row = useMemo(() => grid.rows.observeById(rowId), [grid, rowId]);
+  return useSyncExternalStore(row.subscribe, row.getSnapshot);
+}
+
+// 셀 구독 훅
+function useCellValue(grid: PureSheet, rowId: string | number, field: string) {
+  const cell = useMemo(() => grid.rows.observeById(rowId).cell(field), [grid, rowId, field]);
+  return useSyncExternalStore(cell.subscribe, cell.getSnapshot);
+}
+
+// 사용 예
+function GridToolbar({ grid }) {
+  const rowCount = useGridState(grid, s => s.visibleRowCount);
+  const hasChanges = useGridState(grid, s => s.hasChanges);
+  const canUndo = useGridState(grid, s => s.canUndo);
+  const canRedo = useGridState(grid, s => s.canRedo);
+  const isBusy = useGridState(grid, s => s.activity !== 'idle');
+  const selectedCount = useGridState(grid, s => s.selectedRowCount);
+  const isEditing = useGridState(grid, s => s.isEditing);
+  const hasErrors = useGridState(grid, s => s.hasValidationErrors);
+  const errorCount = useGridState(grid, s => s.validationErrorCount);
+
+  return (
+    <div>
+      <span>{rowCount}건 ({selectedCount}건 선택)</span>
+      <button disabled={!canUndo} onClick={() => grid.undoManager.undo()}>Undo</button>
+      <button disabled={!canRedo} onClick={() => grid.undoManager.redo()}>Redo</button>
+      <button disabled={!hasChanges || hasErrors} onClick={() => grid.changes.commit()}>저장</button>
+      {isBusy && <Spinner />}
+      {isEditing && <span>편집 중</span>}
+      {hasErrors && <span style={{ color: 'red' }}>{errorCount}개 에러</span>}
+    </div>
+  );
+}
+
+function RowStatus({ grid, rowId }) {
+  const row = useRow(grid, rowId);
+  if (!row) return null;
+  return <span>{row.name} ({row.state})</span>;
+}
+
+function CellDisplay({ grid, rowId, field }) {
+  const value = useCellValue(grid, rowId, field);
+  return <span>{String(value)}</span>;
+}
+```
+
+---
+
+### 이벤트 전체 사용 예제
+
+```typescript
+// ═══════════════════════════════════════════════════
+// 데이터 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('data:loaded', ({ rowCount, columnCount }) => {
+  console.log(`데이터 로드 완료: ${rowCount}행, ${columnCount}열`);
+});
+
+// ═══════════════════════════════════════════════════
+// 행 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('row:click', ({ row, rowIndex, event }) => {
+  console.log(`행 클릭: index=${rowIndex}, id=${row.id}`);
+});
+
+grid.on('row:dblclick', ({ row, rowIndex, event }) => {
+  console.log(`행 더블클릭: index=${rowIndex}`);
+});
+
+grid.on('row:pinned', ({ row, position }) => {
+  console.log(`행 고정: ${row.id} → ${position}`); // 'top' | 'bottom'
+});
+
+grid.on('row:unpinned', ({ rowId, position }) => {
+  console.log(`행 고정 해제: ${rowId}`);
+});
+
+grid.on('row:reordered', (e) => {
+  // discriminated union — flat 그리드 vs 트리 그리드
+  if (e.kind === 'flat') {
+    console.log(`행 재정렬: ${e.fromIndex} → ${e.toIndex}`);
+  } else {
+    // kind === 'tree' — 트리 노드 재정렬
+    console.log(`트리 이동: ${e.patches.length}개, dropMode=${e.dropMode}`);
+  }
+  // e.commandId(= BatchCommand.id)는 undoManager.undoThrough(commandId) 롤백 키
+});
+
+// ═══════════════════════════════════════════════════
+// 셀 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('cell:click', ({ row, columnId, value, event }) => {
+  console.log(`셀 클릭: [${row.id}].${columnId} = ${value}`);
+});
+
+grid.on('cell:dblclick', ({ row, columnId, value, event }) => {
+  console.log(`셀 더블클릭: [${row.id}].${columnId} = ${value}`);
+});
+
+grid.on('cell:change', ({ rowIndex, columnId, oldValue, newValue }) => {
+  console.log(`셀 변경: row[${rowIndex}].${columnId}: ${oldValue} → ${newValue}`);
+});
+
+grid.on('cell:beforeEdit', (payload) => {
+  // 편집 시작 전 — cancel()로 취소 가능
+  if (payload.columnId === 'locked_field') {
+    payload.cancel();
+  }
+});
+
+grid.on('cell:editCommitting', (payload) => {
+  // 편집 커밋 전 — cancel()로 취소 가능
+  if (payload.newValue === '') {
+    payload.cancel(); // 빈 값 커밋 방지
+  }
+});
+
+grid.on('cell:editCommitted', ({ rowIndex, dataIndex, columnId, oldValue, newValue }) => {
+  console.log(`편집 완료: row[${rowIndex}].${columnId}: ${oldValue} → ${newValue}`);
+});
+
+grid.on('cell:tooltip', (payload) => {
+  // 셀·컬럼 헤더 공통 이벤트 — payload.area ('cell' | 'columnHeader') 로 구분.
+  // payload.tooltipText: ColumnDef.headerTooltip/cellTooltip 로 지정한 커스텀 문구(있으면 우선).
+  console.log('툴팁:', payload.area, payload.tooltipText ?? payload.formattedValue);
+});
+
+// ═══════════════════════════════════════════════════
+// 선택 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('selection:changed', ({ selectedRows, selectedCells }) => {
+  console.log(`선택 변경: ${selectedRows.length}행, ${selectedCells.length}셀`);
+});
+
+// ═══════════════════════════════════════════════════
+// 컬럼 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('column:resize', ({ columnId, width }) => {
+  console.log(`컬럼 리사이즈: ${columnId} → ${width}px`);
+});
+
+grid.on('column:reorder', ({ order, source, sourceId }) => {
+  console.log(`컬럼 순서 변경 (${source}):`, order);
+  // source: 'order' | 'column' | 'group' | 'groupOrder'
+  // sourceId: move/moveGroup 시 이동된 컬럼/그룹 ID
+});
+
+grid.on('column:pin', ({ columnId, position }) => {
+  console.log(`컬럼 고정: ${columnId} → ${position}`); // 'left' | 'right' | 'none'
+});
+
+grid.on('column:visibility', ({ columnId, visible }) => {
+  console.log(`컬럼 가시성: ${columnId} → ${visible}`);
+});
+
+// ═══════════════════════════════════════════════════
+// 정렬/필터 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('sort:changed', ({ sorts }) => {
+  console.log('정렬 변경:', sorts);
+  // → [{ id: 'name', direction: 'asc', sequence: 1 }]
+});
+
+grid.on('filter:changed', ({ filters }) => {
+  console.log('필터 변경:', filters);
+  // → [{ id: 'age', operator: 'gte', filterValue: 30, sequence: 1 }]
+});
+
+// 헤더 클릭 = 정렬 정책은 소비처가 소유한다.
+// core는 header:click만 발행하고 자동 정렬하지 않으므로,
+// 클릭-정렬을 원하면 직접 toggleSort()를 호출한다.
+grid.on('header:click', ({ columnId, event }) => {
+  // event는 원본 DOM MouseEvent — 모디파이어를 직접 읽는다.
+  // shift+클릭이면 기존 정렬에 추가(다중 정렬), 아니면 단일 정렬.
+  grid.toggleSort(columnId, { additive: event.shiftKey });
+  // 사이클: none → asc → desc → none (sortable:false 컬럼은 무시)
+});
+
+// 헤더 아이콘 클릭은 셀 본체 클릭과 **분리**된다 (ITSM-2026-002185).
+// 아이콘 클릭은 stopPropagation 되므로 header:click 과 동시에 발생하지 않는다.
+grid.on('header:sortClick', ({ columnId, element }) => {
+  openSortPanel(element, columnId);      // element = 아이콘 DOM (팝오버 앵커)
+});
+grid.on('header:filterClick', ({ columnId, element }) => {
+  openFilterPopover(element, columnId);
+  // 필드에 showFilterIcon:false 면 아이콘 DOM 자체가 없어 이 이벤트도 발생하지 않는다.
+});
+
+// ═══════════════════════════════════════════════════
+// Undo/Redo 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('undo:stateChange', (state) => {
+  console.log('Undo 상태:', state); // { canUndo, canRedo } — 버튼 활성화 토글용
+});
+
+// changes:undone / changes:redone — undo/redo 완료 시 구조화된 변경 payload.
+// ⚠️ row:reordered만 구독하면 undo/redo 시 백엔드와 어긋난다 (row:reordered는 정방향만 발화).
+// ⚠️ 트리/플랫 reorder는 항상 kind:'batch'로 감싸져 오므로, iterateLeafChanges로 평탄화한 뒤 분기.
+import { iterateLeafChanges } from '@solasheet/core';
+
+function syncChange(rootChange, direction) {
+  // children은 이미 direction-ordered → 헬퍼 방출 순서 그대로 순차 적용 (재-reverse 금지)
+  for (const leaf of iterateLeafChanges(rootChange)) {
+    switch (leaf.kind) {
+      case 'cell-edit':
+        api.patch(leaf.rowId, { [leaf.field]: direction === 'undo' ? leaf.oldValue : leaf.newValue });
+        break;
+      case 'tree-reorder':
+        for (const p of leaf.patches) {
+          api.setParent(p.rowId, direction === 'undo' ? p.oldParentId : p.newParentId);
+        }
+        for (const [parentId, order] of leaf.siblingsAfterFinal) api.reorderChildren(parentId, order);
+        break;
+      // 'flat-move' / 'add-row' / 'delete-row' 등도 동일 패턴
+    }
+  }
+}
+grid.on('changes:undone', (e) => syncChange(e.change, 'undo'));
+grid.on('changes:redone', (e) => syncChange(e.change, 'redo'));
+
+// ═══════════════════════════════════════════════════
+// 클립보드 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('clipboard:copy', ({ text, rowCount, colCount }) => {
+  console.log(`복사: ${rowCount}행 × ${colCount}열`);
+});
+
+grid.on('clipboard:paste', ({ cellCount }) => {
+  console.log(`붙여넣기: ${cellCount}셀`);
+});
+
+// ═══════════════════════════════════════════════════
+// 검증 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('validation:changed', (payload) => {
+  console.log('검증 상태 변경:', payload);
+});
+
+// ═══════════════════════════════════════════════════
+// 컬럼 그룹 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('columnGroup:toggle', ({ groupId, collapsed }) => {
+  console.log(`컬럼 그룹: ${groupId} → ${collapsed ? '접힘' : '펼침'}`);
+});
+
+// ═══════════════════════════════════════════════════
+// 컨텍스트 메뉴 이벤트
+// ═══════════════════════════════════════════════════
+
+grid.on('contextmenu', ({
+  area,           // 'cell' | 'header' | 'rowHeader' | 'empty'
+  rowIndex,       // 행 인덱스 (cell 영역)
+  dataIndex,      // 데이터 인덱스
+  rowId,          // 행 ID
+  columnId,       // 컬럼 ID
+  value,          // 셀 값
+  selectedRowIds, // 현재 선택된 행 ID 배열
+  selectedCells,  // 현재 선택된 셀 배열
+  originalEvent,  // 원본 MouseEvent
+}) => {
+  originalEvent.preventDefault();
+  showContextMenu(originalEvent.clientX, originalEvent.clientY, {
+    area, rowId, columnId, value, selectedRowIds, selectedCells,
+  });
+});
+
+// ═══════════════════════════════════════════════════
+// 이벤트 구독 해제
+// ═══════════════════════════════════════════════════
+
+// 방법 1: on() 반환값 사용
+const unsubscribe = grid.on('cell:click', handler);
+unsubscribe();
+
+// 방법 2: off() 사용
+grid.off('cell:click', handler);
+```
+
+---
+
+### 정렬/필터 사용 예제
+
+```typescript
+// ── 정렬 (SortState[] — id/direction/sequence) ──
+await grid.sort([{ id: 'name', direction: 'asc', sequence: 1 }]);
+await grid.sort([
+  { id: 'age', direction: 'desc', sequence: 1 },
+  { id: 'name', direction: 'asc', sequence: 2 },  // 다중 정렬
+]);
+
+// ── 조건식 필터 (FilterState[] — id/operator/filterValue/sequence) ──
+await grid.filter([
+  { id: 'age', operator: 'gte', filterValue: 30, sequence: 1 },
+  { id: 'name', operator: 'contains', filterValue: '김', sequence: 2 },
+]);
+
+// OR 조건 (logical: 'or')
+await grid.filter([
+  { id: 'status', operator: 'eq', filterValue: 'active', sequence: 1 },
+  { id: 'status', operator: 'eq', filterValue: 'pending', sequence: 2, logical: 'or' },
+]);
+
+// ── 값 집합 필터 (엑셀식 체크박스 — filterValue 가 **배열**) ──
+await grid.filter([
+  { id: 'dept', operator: 'in', filterValue: ['영업', '개발'], sequence: 1 },
+]);
+// notIn = 제외 방향 (exclude 모드가 만드는 형태)
+await grid.filter([
+  { id: 'dept', operator: 'notIn', filterValue: ['임시'], sequence: 1 },
+]);
+
+// ── 수식 필터 (행 전체를 식 하나로 판정 — 괄호·컬럼 간 비교 가능) ──
+await grid.filter([{
+  id: '__formula__', sequence: 1, operator: 'formula',
+  expression: '([급여] > 50000 AND [부서] == "Engineering") OR [도시] == "서울"',
+}]);
+
+// ── 뷰 상태 저장/복원 ──
+const viewState = grid.getViewState();   // { sorts, filters, filterGroups }
+await grid.setViewState(viewState);
+```
+
+> ⚠️ `FilterState` 는 `operator` 로 갈라지는 **판별 유니온**입니다. `in`/`notIn` 에 스칼라를 넣거나 `formula` 에 `expression` 을 빠뜨리면 런타임에서 **조용히 전 행 통과**가 됩니다 — 타입이 이를 컴파일 시점에 막습니다. → [reference.md SortState / FilterState](reference.md#sortstate--filterstate)
+
+---
+
+### 필터 그룹 사용 예제
+
+여러 UI(툴바 필터 창, 컬럼 헤더 팝오버)가 **같은 필터 배열을 공유하지 않도록** 소스별로 그룹을 나눕니다.
+
+```typescript
+import type { FilterGroupMap } from '@vmscloud/moz-ui-grid-core';
+
+// 그룹 맵으로 한 번에 적용 — 그룹 간은 항상 AND, 그룹 안은 각 항목의 logical
+const groups: FilterGroupMap = {
+  toolbar: {
+    type: 'conditional', priority: 0, applied: true,
+    states: [{ id: 'dept', operator: 'eq', filterValue: 'Sales', sequence: 0 }],
+  },
+  'headerPopover:name': {
+    type: 'values', priority: 1, applied: true,
+    states: [{ id: 'name', operator: 'in', filterValue: ['강호동', '김태희'], sequence: 0 }],
+  },
+};
+await grid.filter(groups);
+// → (dept = Sales) AND (name ∈ {강호동, 김태희})
+
+// 그룹 하나만 교체 — 다른 그룹은 건드리지 않는다
+await grid.setFilterGroup('headerPopover:name', {
+  type: 'values', priority: 1, applied: true,
+  states: [{ id: 'name', operator: 'in', filterValue: ['강호동'], sequence: 0 }],
+});
+
+// 그룹 삭제 (팝오버에서 "지우기")
+await grid.setFilterGroup('headerPopover:name', null);
+
+// 임시로 끄기 — 상태는 남기고 필터링에만 미참여
+const g = grid.getFilterGroup('toolbar');
+if (g) await grid.setFilterGroup('toolbar', { ...g, applied: false });
+
+// 전체 조회
+const all = grid.getFilterGroups();
+const flat = grid.getViewState().filters;   // 평탄화된 파생값 (엔진이 읽는 형태)
+```
+
+> **그룹 경계 = 괄호.** 평면 배열 하나로 두면 좌→우 fold 가 그룹을 넘나들어, 뒤 그룹의 OR 이 앞 그룹 조건을 통째로 무력화합니다(실측: `dept=Sales` + `name∈{강호동,김태희}` 에서 HR/김태희 누출). 평탄화 시 `groupKey` 가 자동 부착되어 이를 막습니다.
+>
+> 컬럼 간 OR 은 그룹으로 표현할 수 없습니다(그룹 간 AND 고정) — **수식 그룹**(`type: 'formula'`)이 담당합니다.
+
+---
+
+### 값 목록 필터 사용 예제 (엑셀식 체크박스)
+
+```typescript
+import { ValueCheckList, DEFAULT_VALUE_LIST_LIMIT } from '@vmscloud/moz-ui-grid-core';
+
+const GROUP_KEY = 'headerPopover:dept';
+let selectedKeys: string[] = [];
+
+const list = new ValueCheckList(popoverBody, {
+  mode: 'exclude',                                  // 전체 체크로 시작 → notIn 저장
+  onSelectionChange: (keys) => { selectedKeys = keys; },
+  // 검색을 소비처가 소유 — 상한 밖 값은 로컬 필터링으로 못 찾으므로 엔진에 재조회한다
+  onKeywordChange: async (keyword) => {
+    const r = await grid.getFilterValues('dept', { keyword });
+    list.setValues(r.values, selectedKeys, { truncated: r.truncated, rawValues: r.rawValues });
+  },
+});
+
+// 1) 후보 수집 — 자기 컬럼의 값 목록 조건(in/notIn)만 제외한 나머지 필터가 적용된다
+list.setLoading(true);
+const r = await grid.getFilterValues('dept', { limit: DEFAULT_VALUE_LIST_LIMIT });
+list.setValues(r.values, undefined, {
+  truncated: r.truncated,          // true 면 위젯이 "검색으로 좁혀 주세요" 안내
+  limit: DEFAULT_VALUE_LIST_LIMIT,
+  rawValues: r.rawValues,          // 필터에 실을 원본값 (표시값 아님)
+});
+
+// 2) [적용] 클릭 — 선택 항목을 원본값으로 필터에 싣는다
+const picked = list.getSelectedItems();
+await grid.setFilterGroup(GROUP_KEY, {
+  type: 'values', priority: 1, applied: true,
+  states: [{ id: 'dept', operator: 'notIn', sequence: 0,
+             filterValue: picked.map((i) => i.value) }],
+});
+
+// 3) 팝오버를 닫을 때
+list.destroy();
+```
+
+> **표시값과 원본값을 구분하세요.** `values` 는 mask 가 적용된 **표시 라벨**(검색·필터가 표시값 기준이므로 목록도 같아야 합니다), `rawValues` 는 **필터에 실을 원본값**입니다. 표시값으로 필터링하면 5M 행에서 30.6배 느리고 함수형 mask 는 Worker 복제가 안 됩니다.
+>
+> 원본값 하나를 화면 표기로 되돌릴 때는 `grid.formatColumnValue(columnId, raw)` 를 쓰세요 — mask 해석 규칙은 core 가 소유하므로 소비처가 재현하면 어긋납니다.
+>
+> **팝오버 재오픈 시** 저장된 필터에서 "현재 후보 목록에 없는 지목"을 추려 `setValues(..., { offListPicks })` 로 넘겨야, 상한 밖 값이 화면에서 사라지지 않습니다.
+
+---
+
+### 헤더 아이콘 이벤트 사용 예제
+
+헤더의 **셀 본체 / 정렬 아이콘 / 필터 아이콘** 클릭은 서로 배타적인 세 이벤트로 분리됩니다 (ITSM-2026-002185).
+
+```typescript
+// 셀 본체 클릭 = 정렬 토글 (core 는 자동 정렬하지 않는다 — 정책은 소비처 소유)
+grid.on('header:click', ({ columnId, event }) => {
+  grid.toggleSort(columnId, { additive: event.shiftKey });
+});
+
+// 정렬 아이콘 클릭 = 정렬 패널 열기 (element 를 앵커로)
+grid.on('header:sortClick', ({ columnId, element }) => {
+  openSortPanel(element, columnId);
+});
+
+// 필터 아이콘 클릭 = 값 목록 팝오버 열기
+grid.on('header:filterClick', ({ columnId, element }) => {
+  openValueListPopover(element, columnId);
+});
+```
+
+> 아이콘 클릭은 `HeaderCell` 에서 `stopPropagation` 되므로 `header:click` 과 **동시에 발생하지 않습니다**.
+>
+> 필드에 `showFilterIcon: false` 를 주면 아이콘 span 자체가 생성되지 않아 그 컬럼에서는 `header:filterClick` 이 **발생하지 않습니다**. 이것은 표시 축일 뿐이며 툴바 필터 창·수식 등 다른 경로로는 여전히 조건을 걸고 해제할 수 있습니다.
+
+---
+
+### 저장본 마이그레이션 사용 예제
+
+```typescript
+import {
+  GRID_CONFIG_VERSION, compareConfigVersion,
+  migrateFormulaToStorage, conditionFiltersToFormulaState,
+} from '@vmscloud/moz-ui-grid-core';
+
+const grid = new PureSheet(el, {
+  fields,
+  // 옛 저장본을 현재 스키마로 올린다. core 는 호출 시점·순서만 책임지고,
+  // 어떤 버전에서 무엇을 바꿀지는 스키마를 아는 소비처가 정한다.
+  migrateConfig: (cfg, fromVersion) => {
+    let out = cfg;
+    // 0.1 → 0.2: 수식 컬럼 참조를 [라벨] → $id 로
+    if (compareConfigVersion(fromVersion, '0.2') < 0) out = to02(out);
+    // 0.2 → 0.3: 소유자 없는 옛 조건식을 고급 필터 수식 그룹으로
+    if (compareConfigVersion(fromVersion, '0.3') < 0) out = to03(out);
+    return { ...out, version: GRID_CONFIG_VERSION };
+  },
+});
+
+// 저장 — getConfig() 가 항상 현재 버전을 실어 준다
+const saved = grid.getConfig();     // { version: '0.3', current, snapshot }
+localStorage.setItem('layout', JSON.stringify(saved));
+
+// 복원 — version 이 없으면 '0.1' 로 간주하고 체인을 처음부터 태운다
+await grid.applyConfig(JSON.parse(localStorage.getItem('layout')!));
+```
+
+> **마이그레이션은 누적 적용입니다.** `0.1` 저장본이면 `0.1 → 0.2 → 0.3` 을 순서대로 전부 거칩니다. 최신 변환만 돌리면 중간 단계를 건너뛰어 조용히 어긋납니다.
+>
+> 변환 중 예외가 나도 복원 자체는 막지 않고 경고(`PS901`)만 남깁니다 — 옛 저장본이라도 최대한 살립니다.
+
+---
+
+### 선택 모드 사용 예제
+
+moz-ui-grid-core는 행 선택과 셀 선택을 **독립된 두 옵션**(`rowSelection` + `cellSelection`)으로 분리합니다.
+하나의 `selectionMode` 옵션이 아니라 각 도메인을 따로 설정하므로, 행 식별(identity) 모델과
+좌표(position) 모델이 정합성 보호 하에 공존할 수 있습니다.
+
+- **`rowSelection`**: `rowId` 기반 (정렬/필터/dirty 변경에도 같은 식별자 추종)
+- **`cellSelection`**: `viewIndex` 기반 (자리 추종 — Excel 모델)
+
+둘 다 미지정 시 기본은 `cellSelection: { mode: 'range' }` (셀 전용 Excel 스타일).
+
+> 각 옵션의 타입 정의는 [reference.md → RowSelectionConfig/CellSelectionConfig](reference.md#열거형유니온-타입) 참조.
+
+#### `RowSelectionConfig` 필드
+
+| 필드 | 타입 | 기본 | 의미 |
+|---|---|---|---|
+| `mode` | `'none' \| 'single' \| 'multi'` | `'none'` | 행 선택 모드 |
+| `trigger` | `'cellClick' \| 'rowHeader' \| 'checkbox' \| Array<...>` | 자동 결정(아래 표 참조) | 어느 입력 이벤트가 행 선택을 발화시키는지 |
+| `includeInSelectAll` | `boolean` | `false` | **Ctrl+A 시 행도 함께 fill 할지** — 아래 섹션 참조 |
+
+#### `CellSelectionConfig` 필드
+
+| 필드 | 타입 | 기본 | 의미 |
+|---|---|---|---|
+| `mode` | `'none' \| 'single' \| 'range'` | (둘 다 미지정 시 `'range'`) | 셀 선택 모드 |
+
+#### 분리 API 예제
+
+```typescript
+// ── 행 전용 (단순 list 그리드) ──
+new PureSheet(container, {
+  rowSelection: { mode: 'multi' },
+});
+//   trigger 미지정 → 자동 'cellClick' (셀 클릭으로 행 선택)
+
+// ── 셀 전용 (Excel 스타일) ──
+new PureSheet(container, {
+  cellSelection: { mode: 'range' },
+});
+
+// ── 셀+행 분리: 행 헤더 클릭으로 행 선택 (정합성 보호) ──
+new PureSheet(container, {
+  rowSelection: { mode: 'multi' },  // trigger 자동 = 'rowHeader'
+  cellSelection: { mode: 'range' },
+});
+//   _rowHeader 컬럼 자동 주입. 셀 클릭은 셀만 선택 → 행/셀 독립.
+
+// ── 체크박스 트리거 ──
+new PureSheet(container, {
+  rowSelection: { mode: 'multi', trigger: 'checkbox' },
+});
+//   _rowHeader 컬럼 자동 주입 + CSS-only 체크박스 자동 렌더.
+
+// ── 트리거 복수 지정 (행 헤더 + 체크박스) ──
+new PureSheet(container, {
+  rowSelection: { mode: 'multi', trigger: ['rowHeader', 'checkbox'] },
+  cellSelection: { mode: 'range' },
+});
+
+// ── 셀 클릭이 행도 선택 (legacy 'all' 동작) ──
+new PureSheet(container, {
+  rowSelection: { mode: 'multi', trigger: 'cellClick' },  // 명시 지정
+  cellSelection: { mode: 'range' },
+});
+//   셀 mutation이 행 selection을 자동 동기화 (drag/click 한정).
+```
+
+#### `rowSelection.trigger` 자동 결정
+
+| `rowSelection.mode` | `cellSelection.mode` | `trigger` 자동값 | 의미 |
+|---|---|---|---|
+| 활성 | 미지정/`'none'` | `'cellClick'` | 셀 클릭으로 행 선택 (단순 list 그리드) |
+| 활성 | 활성 | `'rowHeader'` | 정합성 보호 — 셀과 행 독립 (수동 명시로 `'cellClick'` 가능) |
+
+#### `rowSelection.includeInSelectAll` — Ctrl+A 동작 제어
+
+`Ctrl+A`(전체 선택) 시점에 활성된 selection 도메인을 어떻게 채울지 제어합니다.
+AG Grid의 `ctrlASelectsRows` 옵션과 같은 의미.
+
+| `cellSelection` | `rowSelection` | `includeInSelectAll` | Ctrl+A 결과 |
+|---|---|---|---|
+| 활성 | 비활성 | (무시) | 모든 셀 |
+| 비활성 | 활성 | (무시) | 모든 행 |
+| 활성 | 활성 | `false` (기본) | 모든 셀만 — 행은 그대로 |
+| 활성 | 활성 | `true` | 모든 셀 + 모든 행 |
+
+```typescript
+// 기본 — 셀만 전체 선택 (AG Grid와 동일)
+new PureSheet(container, {
+  rowSelection: { mode: 'multi' },
+  cellSelection: { mode: 'range' },
+  // rowSelection.includeInSelectAll: false (기본)
+});
+
+// Ctrl+A로 행도 함께 fill
+new PureSheet(container, {
+  rowSelection: { mode: 'multi', includeInSelectAll: true },
+  cellSelection: { mode: 'range' },
+});
+```
+
+> **`trigger: 'cellClick'`과의 분리** — `trigger='cellClick'`은 **마우스 드래그/클릭** 시
+> 셀 mutation이 행을 동반 동기화하는 규칙. Ctrl+A는 별개의 명시적 단축키라서
+> `includeInSelectAll`이 단독으로 제어합니다. 즉 `trigger='cellClick'`이어도
+> `includeInSelectAll: false`(기본)면 Ctrl+A는 셀만 전체 선택합니다.
+
+#### `cellSelectionImpliesRows` — 행 액션 fallback
+
+행 단위 액션(Ctrl+H 행 숨김, 행 삭제, 행 복사 등)이 **셀 선택만 있을 때** 어떻게
+작동할지 결정합니다. `includeInSelectAll`과 별개의 옵션 — 이쪽은 Ctrl+A와 무관하게
+**암묵적으로 셀 → 행을 도출**할지 정합니다.
+
+```typescript
+// 기본 (Policy A — 엄격 분리)
+new PureSheet(container, {
+  rowSelection: { mode: 'multi' },
+  cellSelection: { mode: 'range' },
+  // cellSelectionImpliesRows: false (기본)
+});
+// → cell-only 사용자가 Ctrl+H를 누르면 작동 안 함 (행 선택이 없으므로).
+
+// Policy B — Excel/Google Sheets 동작
+new PureSheet(container, {
+  rowSelection: { mode: 'multi' },
+  cellSelection: { mode: 'range' },
+  cellSelectionImpliesRows: true,
+});
+// → cell-only 사용자가 Ctrl+H를 누르면 셀이 걸친 행들이 숨겨짐.
+//   시각(`ps-selected` 클래스)은 옵션과 무관하게 명시적 행 선택만 표시.
+```
+
+| 정책 | 명시적 행 선택만 있음 | 셀만 선택됨 (행 비어있음) |
+|---|---|---|
+| Policy A (`false`, 기본) | 행 액션 작동 | 행 액션 작동 안 함 |
+| Policy B (`true`) | 행 액션 작동 | 셀의 행 자동 도출 → 행 액션 작동 |
+
+#### 세 옵션 정리 — 어떤 동작이 어떤 옵션에 묶이나
+
+| 시나리오 | 제어 옵션 |
+|---|---|
+| 셀 클릭/드래그 시 행도 함께 선택될지 | `rowSelection.trigger`에 `'cellClick'` 포함 여부 |
+| **Ctrl+A** 시 셀 + 행 둘 다 채울지 | `rowSelection.includeInSelectAll` |
+| 셀만 선택된 상태에서 **행 액션**이 작동할지 | `cellSelectionImpliesRows` |
+
+세 가지가 모두 독립적이므로, 예를 들어:
+- `trigger: 'rowHeader'` + `includeInSelectAll: true` → 평소엔 셀/행 분리지만 Ctrl+A는 둘 다 fill.
+- `trigger: 'cellClick'` + `includeInSelectAll: false` → 평소엔 셀이 행을 끌고가지만 Ctrl+A는 셀만.
+
+#### 그룹 행과 선택
+
+그룹 행(그룹 배너)은 데이터가 없는 구조적 행이라 **선택 대상이 아닙니다**.
+
+- **드래그 range** — 커서를 그룹 경계 너머로 드래그하면 그룹 행을 기점으로 선택이 **분리(split)** 됩니다. 그룹 배너 셀은 range에서 제외되고, 선택 오버레이도 그룹 행 위치에서 끊어 여러 조각으로 그립니다.
+- **Ctrl+A / `selectAll()` / `selectAllCells()`** — 그룹 행을 제외한 **모든 데이터 행**을 덮습니다. 그룹 행이 사이에 끼어 있어도 맨 아래 데이터 행까지 빠짐없이 포함됩니다.
+- 그룹 배너 자체에는 마우스 hover 하이라이트만 표시되고 선택 하이라이트(`ps-selected`)는 붙지 않습니다.
+
+> 트리 노드는 실제 데이터 행이므로 위 규칙과 무관하게 정상적으로 선택됩니다(그룹 배너·소계 같은 구조적 행에만 해당).
+
+#### SelectionManager 직접 조회 API (저수준)
+
+대부분의 사용자는 `grid.rows.getSelectedRowIds()` 같은 RowsAPI를 쓰면 충분. 좌표계 변환이
+필요한 고급 케이스(커스텀 렌더러/집계/익스텐션)에서만 SelectionManager에 직접 접근.
+
+```typescript
+const sm = (grid as any).selectionManager;
+sm.getSelectedRows();            // Set<RowId> — pinned/regular 통합, identity 추종
+sm.getSelectedCells();           // Set<`${rowId}\x1F${col}`> — pinned 셀 통합 (외부 표준)
+sm.getSelectedCellsByView();     // Set<`${viewIndex}\x1F${col}`> — viewIndex 좌표 (자리 추종)
+sm.getSelectedPinnedCells();     // Set<`${top|bottom}:${idx}\x1F${col}`> — pinned 좌표
+sm.getSourceIndex(rowId);        // number | undefined — sourceIndex 캐시 lookup (idMap 회피용)
+sm.getRanges();                  // SelectionRange[] — drag 1회 = 1 range. isAllVisible flag로 Ctrl+A 빠른 판정
+sm.isAllVisibleSelected();       // boolean — ranges에 isAllVisible flag 포함 여부 (5M행 O(1) 판정)
+sm.selectAll();                  // 활성된 도메인 채우기 (includeInSelectAll에 따라 분기)
+sm.selectAllCells();             // 모든 셀만 (isAllVisible 빠른 path)
+sm.clearSelection();             // 전체 선택 해제 (selectedRows + cells + ranges 모두)
+sm.clearCellRanges();            // 셀 range만 해제 (row identity 선택은 보존) — 피벗 collapse 등 view 구조 변경 시
+```
+
+| 메서드 | 키/반환 형식 | 추종 | 주 사용처 |
+|---|---|---|---|
+| `getSelectedRows()` | `Set<RowId>` | identity | 외부 일반 — 행 ID 조회 |
+| `getSelectedCells()` | `Set<rowIdKey>` | identity | 외부 일반 — 셀 (pinned 통합) |
+| `getSelectedCellsByView()` | `Set<viewIndexKey>` | position | 렌더러 / 집계 / 클립보드 (regular 영역) |
+| `getSelectedPinnedCells()` | `Set<pinnedCoordKey>` | position | pinned 영역 paint / 집계 |
+| `getSourceIndex(rowId)` | `number \| undefined` | — | idMap O(N) 회피 캐시 lookup |
+| `getRanges()` | `SelectionRange[]` | position | drag/range 단위 순회 — `isAllVisible` flag로 unbounded full range 판정 |
+| `isAllVisibleSelected()` | `boolean` | — | Ctrl+A 후 ClipboardManager / aggregates 빠른 path 분기 |
+| `clearSelection()` | `void` | — | 전체 선택 해제 |
+| `clearCellRanges()` | `void` | — | 셀 range만 해제, row identity 보존. view 구조가 변하여 viewIndex 기반 range가 stale일 때 (피벗 collapse 등) |
+
+> **identity vs position** — `getSelectedRows`/`getSelectedCells`는 rowId 기반이라
+> 정렬/필터에 안정적. `getSelectedCellsByView`/`getSelectedPinnedCells`는 좌표 기반이라
+> 정렬 시 같은 화면 자리의 셀이 선택된 상태로 유지(Excel 모델).
+
+> **`isAllVisible` 패턴** — Ctrl+A 같은 unbounded full selection은 `selectedCells` Set에
+> 모든 셀을 채우지 않고 ranges에 `isAllVisible: true` flag만 둡니다. 5M 행 × N 컬럼
+> Set.add 회피로 O(1)에 즉시 표시. ag-grid의 unbounded cell range, MUI X DataGrid의
+> exclude model과 동일 패턴.
+
+#### 선택된 행 ID 조회
+
+```typescript
+// 선택된 행 ID 조회
+const selectedRowIds = grid.rows.getSelectedRowIds();
+// 또는 reactive: grid.rows.getSelectedRowsAccessor().rows()
+```
+
+---
+
+### 셀 병합 사용 예제
+
+```typescript
+// content 병합: 인접한 같은 값을 자동 병합 (계층 X)
+grid.setMergeConfig({
+  type: 'content',
+  columns: ['region'],
+});
+
+// hierarchical 병합: 상위 컬럼이 같은 범위 안에서만 하위 컬럼도 병합 (계층 O)
+grid.setMergeConfig({
+  type: 'hierarchical',
+  columns: ['region', 'category'],
+});
+
+// custom 병합(세로): 콜백으로 셀별 병합 범위 직접 결정 (Worker 모드 불가)
+// startCol/endCol 생략 → 현재 컬럼만(세로 전용).
+grid.setMergeConfig({
+  type: 'custom',
+  columns: ['dept', 'team'],
+  getMergedRange: ({ rowIndex, columnId, value, getRowData, totalRowCount }) => {
+    let start = rowIndex, end = rowIndex;
+    while (start > 0 && getRowData(start - 1)?.[columnId] === value) start--;
+    while (end < totalRowCount - 1 && getRowData(end + 1)?.[columnId] === value) end++;
+    return start === end ? null : { startRow: start, endRow: end };
+  },
+});
+
+// custom 병합(가로): startCol/endCol 지정 → 한 행에서 여러 컬럼을 가로 병합.
+// anchor(colIndex 0)에서만 영역을 반환하고, 컬럼 인덱스는 columnsInOrder(렌더 순서) 기준.
+grid.setMergeConfig({
+  type: 'custom',
+  columns: ['q1', 'q2', 'q3', 'q4'],
+  getMergedRange: ({ rowIndex, colIndex, columnsInOrder, getCellValue }) => {
+    if (colIndex !== 0) return null;                        // 첫 참여 컬럼에서만
+    if (getCellValue(rowIndex, 'status') !== 'TOTAL') return null;
+    return {
+      startRow: rowIndex, endRow: rowIndex,                 // 한 행
+      startCol: columnsInOrder.indexOf('q1'),
+      endCol: columnsInOrder.indexOf('q4'),                // q1..q4 가로 병합
+    };
+  },
+});
+
+// custom 병합(2D): 세로(같은 값 연속) × 가로(참여 컬럼) 사각형 블록
+grid.setMergeConfig({
+  type: 'custom',
+  columns: ['region', 'category'],
+  getMergedRange: ({ rowIndex, colIndex, columnId, value, getRowData, totalRowCount, columnsInOrder }) => {
+    if (colIndex !== 0) return null;
+    let start = rowIndex, end = rowIndex;
+    while (start > 0 && getRowData(start - 1)?.[columnId] === value) start--;
+    while (end < totalRowCount - 1 && getRowData(end + 1)?.[columnId] === value) end++;
+    if (start === end) return null;
+    return {
+      startRow: start, endRow: end,
+      startCol: columnsInOrder.indexOf('region'),
+      endCol: columnsInOrder.indexOf('category'),          // region..category 2D 사각형
+    };
+  },
+});
+
+// getMergedRanges(배치) — 여러 셀을 한 번에 처리(성능). getMergedRange보다 우선.
+
+// 병합 해제
+grid.setMergeConfig(null);
+```
+
+자세한 타입은 [reference.md → MergeConfig](reference.md#셀-병합--mergeconfig) 참조.
+
+---
+
+### 동적 행 높이 사용 예제
+
+```typescript
+grid.setDynamicRowHeights(true);
+console.log(grid.isDynamicRowHeightsEnabled()); // true
+grid.setDynamicRowHeights(false);
+```
+
+---
+
+### 데이터 조회 사용 예제
+
+```typescript
+const allData = await grid.getAllData();
+const visibleData = await grid.getVisibleData(); // async — 반드시 await
+const totalCount = grid.getTotalRowCount();
+const visibleCount = grid.getVisibleRowCount();
+const rowById = await grid.getRowById('row-1');
+const rowIndex = await grid.getRowIndexById('row-1');
+const virtualIndex = await grid.getRowVirtualIndexById('row-1');
+// sourceIndex로 단일 행 조회 — 최상위 getRowByIndex는 제거됨. grid.rows.getByIndex(idx) 사용
+const rowByIdx = grid.rows.getByIndex(0).data; // sourceIndex 기반 O(1) (data는 readonly 속성)
+const fields = grid.getFields(); // flat 모드: FieldDef[]
+
+// 피벗 모드에서 필드 조회 (카테고리별)
+const pivotFields = grid.getPivotFields();
+// { rowFields: FieldDef[], columnFields: FieldDef[], valueFields: FieldDef[], filterFields: FieldDef[] }
+
+// 모드 무관하게 flat array로 필드 조회
+const pf = grid.getPivotFields();
+const anyFields = grid.getFields()
+  ?? (pf ? [...pf.rowFields, ...pf.columnFields, ...pf.valueFields, ...pf.filterFields] : null);
+
+// ── 필드 정의 교체 (updateFields) ──
+// 기존 컬럼의 레이아웃(너비, 순서, 가시성, 고정)을 보존하면서 필드 교체.
+// 새 필드는 추가, 삭제된 필드는 제거됨.
+await grid.updateFields([
+  { id: 'name', header: '이름', width: 200 },
+  { id: 'email', header: '이메일', width: 250 },       // 기존 컬럼 — 사용자가 조정한 너비/순서 유지
+  { id: 'phone', header: '전화번호', width: 150 },     // 새 컬럼 — 기본 상태로 추가
+  // 기존에 있던 'address' 필드가 빠짐 — 자동 제거
+]);
+
+// getFields() 가 반환하는 **원본 필드 목록도 함께 갱신**된다(ITSM-2026-002177).
+// 이전에는 갱신되지 않아 "화면에는 있는데 필드 목록에는 없는" 동적 컬럼이 생겼고,
+// getFields().find(id) 로 필드를 찾는 소비처(필터 팝오버·툴바 필터 창·정렬 패널)가
+// 에러 없이 조용히 무시했다(실측: 동적 컬럼의 필터 아이콘 무반응).
+grid.getFields()?.some((f) => f.id === 'phone');   // → true
+```
+
+---
+
+### 스크롤/네비게이션 사용 예제
+
+```typescript
+grid.scrollToRow(0);                          // 인덱스 기반
+grid.ensureCellVisible(5, 'email');            // dataIndex + columnId
+```
+
+---
+
+### 국제화 사용 예제
+
+```typescript
+grid.setLocale('en-US');
+console.log(grid.getLocale()); // 'en-US'
+```
+
+---
+
+### 셀 렌더러 사용 예제
+
+컬럼별 셀 커스텀 렌더링은 `FieldDef.cellRenderer`(및 `rowHeader.cellRenderer`)로 합니다.
+`function.length`(arity)로 **Simple**(1인자)과 **Lifecycle**(2인자)이 자동 구분됩니다.
+
+```typescript
+// Simple (arity 1) — 매 렌더마다 호출, 반환값으로 셀 내용 교체 (vanilla JS)
+const fields = [{
+  id: 'status', header: '상태', dataType: 'string',
+  cellRenderer: ({ value }) => `<span class="badge badge-${value}">${value}</span>`,
+}];
+
+// Lifecycle (arity 2) — mount/update/destroy 훅. React/Vue 등 프레임워크 래핑용.
+const chartField = {
+  id: 'trend', header: '추이', dataType: 'number',
+  cellRenderer: (container, params) => {
+    const inst = mountMyWidget(container, params.value);       // 최초 1회 mount
+    return {
+      // 재사용 셀의 데이터가 바뀔 때. false 반환 → 그리드가 destroy 후 re-mount 강제.
+      update: (p) => { inst.setValue(p.value); return true; },
+      // 셀 풀 반환 / 컬럼 영구 제거 / 그리드 destroy 시 호출 (스크롤 재사용 시점엔 호출 X — dormant 유지).
+      destroy: () => inst.unmount(),
+    };
+  },
+};
+```
+
+`rowHeader.cellRenderer`도 동일 `CellRenderer` 타입이며, params에 `selected`(행 선택 스냅샷)가 추가로 전달됩니다. 실제 `<input>`에 `ps-row-header-checkbox-input` 클래스를 붙이면 built-in 선택 동기화가 `checked`를 자동 갱신합니다.
+
+```typescript
+new PureSheet(el, {
+  fields,
+  rowSelection: { mode: 'multi', trigger: 'checkbox' },
+  rowHeader: {
+    width: 44,
+    cellRenderer: ({ selected }) =>            // built-in 체크박스를 대체
+      `<input type="checkbox" class="ps-row-header-checkbox-input" ${selected ? 'checked' : ''}>`,
+    headerRenderer: () => '☑',                 // 좌상단 코너(TopLeft) 셀
+  },
+});
+```
+
+> 데모: `apps/demo/examples/cell-renderer-lifecycle.html`. 타입 상세는 [reference.md → CellRendererParams / CellRenderer](reference.md) 참조.
+
+---
+
+### 포맷팅 사용 예제
+
+```typescript
+// 행 포맷 핸들러 등록 (네임드 키 + priority)
+grid.formatRow.addHandler('highlight', (info) => {
+  if (info.type === 'data') {
+    const { data, rowElement, cells } = info.ctx;
+    // 조건부 행 스타일
+    if ((data as Record<string, number>).price >= 80000) {
+      rowElement.style.backgroundColor = 'rgba(255, 193, 7, 0.12)';
+    } else {
+      rowElement.style.backgroundColor = '';
+    }
+    // 조건부 셀 스타일
+    const stockCell = cells.stock;
+    if (stockCell && (data as Record<string, number>).stock <= 20) {
+      stockCell.element.style.color = '#d32f2f';
+    }
+  }
+});
+
+// 여러 핸들러를 priority로 순서 제어
+grid.formatRow.addHandler('reset', (info) => {
+  if (info.type !== 'data') return;
+  // 모든 셀 스타일 초기화 (Row 재사용 시 누수 방지)
+  for (const cell of Object.values(info.ctx.cells)) {
+    cell.element.style.backgroundColor = '';
+    cell.element.style.color = '';
+  }
+}, { priority: 0 }); // priority 0 = 가장 먼저 실행
+
+// 핸들러 해제
+grid.formatRow.removeHandler('highlight');
+```
+
+**priority 가이드:**
+
+| 범위 | 용도 |
+|------|------|
+| 0-9 | Core 초기화 (스타일 리셋) |
+| 10-19 | Core 기능 (검색 하이라이트, 커스텀 셀) |
+| 50 | 기본값 (사용자 formatRow) |
+| 90-99 | 최종 오버라이드 |
+
+> `info.ctx`의 전체 형태(DataRowContext/GroupRowContext/SubtotalContext)는 [reference.md → FormatRowInfo](reference.md#formatrow-컨텍스트--formatrowinfo) 참조.
+
+#### 헤더 행 포맷팅 — formatHeader
+
+`formatRow` 의 헤더 카운터파트. 헤더가 (재)렌더될 때만 발화 — 스크롤로는 발화 X.
+
+##### 기본 사용 — config 슬롯
+
+```typescript
+new PureSheet(el, {
+  fields,
+  formatHeader: (ctx) => {
+    // 정렬된 컬럼에 data-* 마커
+    for (const [colId, cell] of Object.entries(ctx.cells)) {
+      cell.element.dataset.sortDir = cell.sortState?.direction ?? '';
+    }
+  },
+});
+```
+
+##### wrapper-managed 사용자 헤더 서식 (완전 패턴)
+
+`devSnap` 보관, `column:update` 이벤트 구독, self-suppress 가드 모두 **불필요**.
+핸들러가 매 invoke 마다 wrapper state 를 직접 읽으므로 자연 일관성.
+
+```typescript
+// 클로저 캡처용 wrapper state
+const userHeaderFmt = new Map<string, { class?: string; style?: string }>();
+
+// (a) 핸들러 1개 등록 — 모든 컬럼을 한 번에 처리
+grid.formatHeader.addHandler('mzc-user-header', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    const fmt = userHeaderFmt.get(colId);
+    // toggle 식 적용 — idempotent (여러 번 호출해도 안전)
+    cell.element.classList.toggle('mzc-user-header', !!fmt);
+    if (fmt?.class) {
+      for (const c of fmt.class.split(/\s+/)) cell.element.classList.add(c);
+    }
+    if (fmt?.style) {
+      // 인라인 style 누적 방지 — 우선 제거 후 재적용
+      cell.element.removeAttribute('style');
+      cell.element.style.cssText = fmt.style;
+    }
+  }
+}, { priority: 80 });
+
+// (b) 사용자 UI 액션 — 노란 배경 적용
+function applyHeaderStyle(colId, style) {
+  userHeaderFmt.set(colId, style);
+  grid.refresh();   // 헤더 재렌더 트리거 → 핸들러 invoke
+}
+
+// (c) 단일 컬럼 해제
+function clearHeaderStyle(colId) {
+  userHeaderFmt.delete(colId);
+  grid.refresh();
+}
+
+// (d) 전체 해제 + 핸들러 제거 (cleanup, e.g. wrapper destroy 시)
+function destroyHeaderFormatter() {
+  userHeaderFmt.clear();
+  grid.formatHeader.removeHandler('mzc-user-header');
+  grid.refresh();   // 잔존 클래스/스타일 정리
+}
+
+// (e) 직렬화 — localStorage 등
+function serializeUserHeader() {
+  return Object.fromEntries(userHeaderFmt);
+}
+function restoreUserHeader(saved) {
+  userHeaderFmt.clear();
+  for (const [colId, fmt] of Object.entries(saved)) userHeaderFmt.set(colId, fmt);
+  grid.refresh();
+}
+```
+
+##### 다중 핸들러 공존 — 검색 하이라이트 / 정렬 강조 / wrapper
+
+```typescript
+// 정렬 순위 뱃지 (priority 50)
+grid.formatHeader.addHandler('sort-rank', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    cell.element.dataset.sortRank = cell.sortState
+      ? String((cell.sortState.index ?? 0) + 1)
+      : '';
+  }
+}, { priority: 50 });
+
+// 검색 매칭 (priority 60)
+const matched = new Set<string>();
+grid.formatHeader.addHandler('search-match', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    cell.element.classList.toggle('search-matched', matched.has(colId));
+  }
+}, { priority: 60 });
+
+// wrapper UI (priority 80) — 위의 mzc-user-header 와 동일
+```
+
+priority 순(50 → 60 → 80)으로 누적 적용. 같은 cell 의 class/style 을 여러 핸들러가 안전하게 누적할 수 있습니다.
+
+##### 발화 시점
+
+- **자동 발화**: 초기 렌더 / 정렬 / 필터 / 핀 / 리사이즈 / 순서 / 가시성 변경 / 컬럼 그룹 토글 / `columns.update`(헤더 영향 키) / 테마·로케일 변경
+- **명시 트리거**: 사용자 state 변경 후엔 `grid.refresh()` 호출 필요 (헤더만 따로 재렌더하는 API 는 미제공)
+- **발화 안 함**: 스크롤, body CRUD, undo/redo 등 헤더 메타가 변하지 않는 액션
+
+> 발화 매트릭스 / priority 가이드 / 직렬화 등 상세는 [reference.md → FormatHeaderContext](reference.md#formatheader-컨텍스트--formatheadercontext) 참조.
+
+---
+
+### 헤더/상태바 사용 예제
+
+```typescript
+grid.setHeaderVisible(false);
+console.log(grid.isHeaderVisible()); // false
+grid.setStatusBarVisible(true);
+grid.updateStatusBarRowCount();
+```
+
+---
+
+### 배치 작업 사용 예제
+
+```typescript
+// 콜백 배치
+await grid.batch(async () => {
+  await grid.changes.addRow({ name: 'A' });
+  await grid.changes.addRow({ name: 'B' });
+  await grid.changes.updateCellById(1, 'status', 'done');
+});
+
+// 명시적 배치
+grid.beginBatch('대량 작업');
+// ... 여러 작업 ...
+await grid.endBatch();
+
+// 트랜잭션
+grid.applyTransaction((tx) => {
+  tx.add({ name: '행1' });
+  tx.add({ name: '행2' });
+  tx.update(1, { status: 'done' });
+});
+
+await grid.applyTransactionAsync(async (tx) => {
+  // 비동기 트랜잭션
+});
+
+// 비동기 트랜잭션 flush
+await grid.flushAsyncTransactions();
+```
+
+---
+
+### 데이터 내보내기 사용 예제
+
+```typescript
+const exportData = grid.getExportData();
+const exportFiltered = grid.getExportData({ includeHidden: false });
+```
+
+---
+
+### 스트리밍/로더 사용 예제
+
+```typescript
+// 스트리밍 설정 (StreamingOptions)
+grid.setStreamingOptions({
+  asyncTransactionWaitMillis: 50,  // 비동기 트랜잭션 배치 간격 (ms, 기본 50)
+  enableCellFlash: true,           // 값 변경 시 셀 플래시 (기본 false)
+  cellFlashDuration: 500,          // 플래시 지속 (ms, 기본 500)
+  cellFadeDuration: 1000,          // 페이드 지속 (ms, 기본 1000)
+});
+
+// 로더 파라미터 업데이트
+grid.updateLoaderParams({ authToken: 'new-token', page: 2 });
+
+// 로더 데이터 새로고침
+await grid.refreshLoaderData();
+```
+
+> DataLoader 클래스 작성법은 [reference.md → DataLoader 클래스](reference.md#dataloader-클래스--워커-기반-커스텀-데이터-로딩) 참조.
+
+---
+
+### 성능 조회 사용 예제
+
+```typescript
+const timings = grid.getTimings();
+console.log(timings);
+// → PerformanceTiming[]: [{ name: 'dataLoad', duration: 150 }, { name: 'render', duration: 30 }, ...]
+```