@vmscloud/moz-ui-grid-react 0.1.25 → 0.1.27

package/docs/manual/examples.md

@@ -7,6 +7,8 @@
 ## 목차
 
 - [기본 플랫 그리드](#기본-플랫-그리드)
+- [행 식별 정책과 자동 ID](#행-식별-정책과-자동-id)
+- [숫자 제약과 날짜시간 편집기](#숫자-제약과-날짜시간-편집기)
 - [grid.rows 사용 예제](#gridrows-사용-예제)
 - [grid.columns 사용 예제](#gridcolumns-사용-예제)
 - [grid.changes 사용 예제](#gridchanges-사용-예제)
@@ -47,6 +49,7 @@
 ```typescript
 const grid = new PureSheet(container, {
   mode: 'flat',
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   fields: [
     // id = 컬럼 **식별자**(가리킬 때: 정렬/필터 상태, 폭, 저장 레이아웃).
     // field = 원본 데이터 **키**(읽을 때: row[field]). 생략하면 id 와 같은 값으로 정규화.
@@ -78,6 +81,104 @@ grid.destroy();
 
 ---
 
+### 행 식별 정책과 자동 ID
+
+`keyFields`의 암묵적 `['id']` 기본값은 없습니다. 원본에 `id` 속성이 있어도 업무 키로 쓰려면 `keyFields: ['id']`를 명시해야 합니다. 컬럼의 `FieldDef.id`는 컬럼 식별자이지 행 키 설정이 아닙니다.
+
+| 설정 | 동작 |
+|---|---|
+| `keyFields: ['employeeNo']` | 명시한 업무 키로 식별. 잘못된 키를 자동 ID로 대체하지 않음 |
+| `keyFields` 생략 + `enableReferCache: true` | 내부 자동 ID 사용. 업무 데이터에 합성 키 필드를 추가할 필요 없음 |
+| `keyFields` 생략 + 캐시 생략/`false` | 초기화 오류. 키를 명시하거나 캐시를 켜야 함 |
+| `keyFields: []` | 초기화 오류. 자동 ID를 원하면 속성 자체를 생략 |
+
+명시적 업무 키는 캐시 없이 사용할 수 있지만, ID로 행 데이터를 찾는 API 등 참조 캐시가 필요한 경로는 `enableReferCache: true`를 설정해야 합니다. 대용량에서 캐시를 끈다면 업무 키를 명시하고 지원되는 sourceIndex 기반 API를 사용하세요.
+
+```typescript
+// 업무 키가 있는 경우 — employeeNo는 실제 데이터 필드다.
+const keyedGrid = new PureSheet(container, {
+  keyFields: ['employeeNo'],
+  enableReferCache: true,
+  fields: [{ id: 'name', dataType: 'string', header: '이름' }],
+  data: [{ employeeNo: 'E-001', name: '김민수' }],
+});
+await keyedGrid.waitForReady();
+const employeeId = keyedGrid.rows.getByIndex(0).id;
+await keyedGrid.changes.updateCellById(employeeId, 'name', '김민수 수정');
+```
+
+```typescript
+// 업무 키가 없는 경우 — 같은 내용의 행도 서로 다른 행으로 식별한다.
+const grid = new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 자동 ID
+  fields: [
+    { id: 'name', dataType: 'string', header: '이름' },
+    { id: 'quantity', dataType: 'number', header: '수량' },
+  ],
+  data: [{ name: '부품', quantity: 1 }, { name: '부품', quantity: 1 }],
+  editable: true,
+  rowSelection: { mode: 'multi' },
+});
+await grid.waitForReady();
+
+// 원본 객체의 id나 내부 문자열 형식을 추측하지 않고 공개 API의 반환 ID를 사용한다.
+const rowId = grid.rows.getByIndex(1).id;
+grid.rows.selectRowsByIds([rowId]);
+await grid.changes.updateCellById(rowId, 'quantity', 2);
+console.log(grid.rows.getById(rowId).data);
+
+const addedId = await grid.changes.addRow({ name: '신규 부품', quantity: 1 });
+await grid.changes.updateCellById(addedId, 'quantity', 3);
+await grid.changes.commit();
+// commit 후에도 반환 ID로 같은 행을 조작한다.
+await grid.changes.deleteRowById(addedId);
+await grid.changes.undeleteRowById(addedId);
+console.log(grid.rows.getById(addedId).data);
+```
+
+자동 ID는 현재 데이터 수명 안에서 재사용하는 식별자입니다. 정렬·필터·편집·commit·Undo/Redo에 사용하되, `loadData()`로 전체 데이터를 교체한 뒤에는 공개 API에서 다시 얻으세요. 서버의 영속 업무 키나 다음 로드의 ID로 저장하지 마세요. 행 객체 API에는 그리드가 반환한 객체를 사용하고, 동일한 값을 가진 새 객체를 만들어 같은 행이라고 가정하지 마세요.
+
+> 아래 API 목록의 `'row-1'`, `'user-5'`, `1` 등은 **실제로 얻은 rowId를 대신 적은 예시 값**입니다. 자동 ID 모드에서는 반환 ID로 바꿔 사용하세요. 업무 키가 필요한 트리 관계나 Excel upsert/충돌 매칭은 별도로 명시적 키를 구성해야 합니다. 신규 행의 업무 키를 생략한 CRUD 예제는 자동 ID 모드를 전제로 합니다.
+
+---
+
+### 숫자 제약과 날짜시간 편집기
+
+`id`는 컬럼 식별자, `field`는 원본 데이터 키, `dataType`은 데이터 타입, `editor`는 편집 UI 설정입니다. 날짜시간도 `dataType: 'date'`를 쓰며 `datetime`은 **editor 타입**입니다.
+
+```typescript
+import { PureSheet, type FieldDef } from '@vmscloud/moz-ui-grid-core';
+
+const fields: FieldDef[] = [
+  {
+    id: 'quantity', field: 'quantity', header: '수량', dataType: 'number',
+    editor: { type: 'number', min: 0, max: 100, step: 0.5 },
+  },
+  {
+    id: 'scheduledAt', field: 'scheduledAt', header: '예약 시각', dataType: 'date',
+    editor: { type: 'datetime' },
+    mask: { type: 'date', pattern: 'YYYY-MM-DD HH:mm:ss' },
+  },
+];
+const grid = new PureSheet(container, {
+  fields,
+  enableReferCache: true,
+  editable: true,
+  timeZone: 'Asia/Seoul',
+  data: [
+    { quantity: 1.5, scheduledAt: new Date('2026-10-19T00:30:00Z') },
+    { quantity: 0, scheduledAt: null },
+  ],
+});
+await grid.waitForReady();
+```
+
+- 숫자의 `min`/`max`는 경계를 포함하며, `step`은 `min`(생략 시 0)을 기준으로 하는 양수 간격입니다. 생략한 제약은 적용되지 않습니다. 범위/간격을 벗어난 입력은 에디터 커밋에서 오류로 표시되며 자동으로 잘라내거나 반올림하지 않습니다. 빈 입력은 `null`입니다. 이 옵션을 모든 프로그램적 mutation의 검증 규칙으로 간주하지 마세요.
+- `datetime`은 `datetime-local` 입력을 사용하지만 커밋 값은 HTML 문자열이 아닌 **`Date | null`**입니다. 위 예제의 최초 표시/편집 시각은 서울 기준 `2026-10-19 09:30:00`이며, 시간대 설정을 생략하면 브라우저 로컬 시간대를 사용합니다. 서버에서 받은 ISO 문자열을 이 계약으로 쓰려면 데이터 준비 단계에서 `Date`로 변환하세요.
+- 기존 `editor: { type: 'date' }`는 날짜 전용 입력과 **문자열 커밋** 동작을 유지합니다. `editor: { type: 'datepicker', dateFormat: 'yyyy-MM-dd' }`의 `dateFormat`도 유지됩니다. 이는 아래 XLSX export에서 제거된 옵션과 별개이며, `mask.pattern`의 `YYYY-MM-DD` 토큰과 혼동하지 마세요.
+
+---
+
 ### grid.rows 사용 예제
 
 ```typescript
@@ -174,15 +275,20 @@ 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로 기존 행을 하단 고정
+// ── 데이터 행 고정 (본문 행을 고정 영역으로 옮김 — setProps({ pinned })와 동일, 본문에서는 빠짐) ──
+grid.rows.pinTopById('row-1');               // ID로 기존 행을 상단 고정 영역으로 옮김
+grid.rows.pinTopByIndex(0);                  // sourceIndex로 기존 행을 상단 고정 영역으로 옮김
+grid.rows.pinBottomById('row-2');            // ID로 기존 행을 하단 고정 영역으로 옮김
+grid.rows.pinBottomByIndex(1);               // sourceIndex로 기존 행을 하단 고정 영역으로 옮김
+grid.rows.unpinById('row-1');                // 본문 원래 위치로 복귀
 
-// ── 구조적 행 고정 ──
-const pinnedRow = grid.rows.addPinnedTop({ id: 'summary', label: '요약', amount: 9999 });
-grid.rows.addPinnedBottom({ id: 'footer', label: '합계' });
+// ── 구조적 행 고정 (RowConfig: 데이터는 data 안에 지정) ──
+const pinnedRow = grid.rows.addPinnedTop({
+  id: 'summary', structural: true, data: { label: '요약', amount: 9999 },
+});
+grid.rows.addPinnedBottom({
+  id: 'footer', structural: true, data: { label: '합계' },
+});
 
 // ── 고정 관리 ──
 grid.rows.unpinById('summary');
@@ -464,6 +570,8 @@ grid.on('rowGroup:checkbox', (e) => console.log(e.groupId, e.checked, e.memberCo
 
 ### grid.tree 사용 예제
 
+아래 관계/노드 ID 예제는 생성 시 `keyFields: ['id']`, `enableReferCache: true`를 설정하고 실제 `id`/`parentId` 데이터를 로드한 그리드를 전제로 합니다. `treeConfig.idField`만 지정한다고 행 업무 키의 암묵적 기본값이 복원되지는 않습니다.
+
 ```typescript
 // ── 트리 설정 (flat 구조 — parentId 기반) ──
 await grid.tree.setConfig({
@@ -548,6 +656,8 @@ const config = grid.tree.getConfig();
 ```typescript
 // ── 트리 드래그 reorder 활성화 (treeConfig + reorderableRows) ──
 const grid = new PureSheet(container, {
+  keyFields: ['id'], // 트리 관계에 쓰는 업무 키를 명시
+  enableReferCache: true,
   treeConfig: { idField: 'id', parentField: 'parentId', treeColumn: 'name' },
   dragDropConfig: {
     reorderableRows: true,        // treeConfig와 함께 → 트리 인식 드래그 자동 활성
@@ -705,7 +815,7 @@ const series = await grid.pivot.getSeriesData();    // 차트용 시리즈
 await grid.masterDetail.setConfig({
   expandColumn: 'name',
   singleExpand: false,
-  keepExpandedOnDataChange: false,
+  keepExpandedOnDataChange: true,   // 기본값 — 정렬·필터·재조회(같은 keyFields 키) 뒤에도 펼친 채 유지. false 면 모두 접힘
   keepMasterDetailRows: true,
   keepMasterDetailRowsCount: 10,
   minHeight: 100,
@@ -888,6 +998,63 @@ grid.headers.expandAtLevel(0);    // level 0 그룹만 펼치기
 
 ### grid.io 사용 예제
 
+업무 키로 기존 행을 매칭하는 import 예제(`upsert`, append 충돌 처리 등)는 생성 시 `keyFields`를 명시한 그리드를 사용하세요. 자동 ID는 Excel 파일에 담긴 업무 키가 아니므로 재가져오기에서 같은 행을 식별하는 키로 간주하면 안 됩니다.
+
+#### 컬럼별 XLSX 날짜 서식과 구조적 고정 행
+
+공개 `toExcel`/`saveExcelToFile` 옵션의 `dateFormat`은 제거되었습니다. 날짜 표시를 보존하려면 각 `dataType: 'date'` 필드에 구조화된 `mask`를 지정하고 `preserveFormatting: true`를 사용하세요. 날짜 편집기의 `dateFormat`과는 별개입니다.
+
+```typescript
+import { PureSheet, type FieldDef } from '@vmscloud/moz-ui-grid-core';
+
+const fields: FieldDef[] = [
+  { id: 'name', header: '항목', dataType: 'string' },
+  {
+    id: 'day', header: '기준일', dataType: 'date',
+    mask: { type: 'date', pattern: 'YYYY-MM-DD' },
+  },
+  {
+    id: 'recordedAt', header: '기록 시각', dataType: 'date',
+    mask: { type: 'date', pattern: 'YYYY-MM-DD HH:mm:ss' },
+  },
+];
+const grid = new PureSheet(container, {
+  fields,
+  enableReferCache: true,
+  timeZone: 'Asia/Seoul',
+  data: [{
+    name: '입고',
+    day: new Date('2026-10-19T00:00:00+09:00'),
+    recordedAt: new Date('2026-10-19T09:30:45+09:00'),
+  }],
+});
+await grid.waitForReady();
+grid.rows.addPinnedTop({
+  id: 'export-note', structural: true, data: { name: '서울 기준 입고 내역' },
+});
+
+const blob = await grid.io.toExcel({
+  scope: 'all',
+  preserveFormatting: true,
+  structuralPinnedRows: 'include',
+});
+// day → yyyy-mm-dd, recordedAt → yyyy-mm-dd hh:mm:ss (Excel numFmt).
+// blob 다운로드는 아래 기본 export 예제와 동일하다.
+
+// 직접 파일 저장도 같은 컬럼별 서식/고정 행 옵션을 사용한다.
+await grid.io.saveExcelToFile({
+  suggestedName: 'receipts.xlsx',
+  preserveFormatting: true,
+  structuralPinnedRows: 'include',
+});
+```
+
+- `preserveFormatting` 기본값은 `false`입니다. 생략/`false`, 날짜 mask 없음 또는 지원하지 않는 날짜 mask는 기본 Excel 날짜 서식 `yyyy-mm-dd`를 사용합니다. 지원 불가 패턴은 `PS005` 경고를 냅니다. 표시 서식은 날짜 값의 시간 정보를 잘라내는 옵션이 아닙니다.
+- `structuralPinnedRows` 기본값은 `'exclude'`입니다. `'include'`는 **상단 고정 → 본문 → 하단 고정** 순서로 구조적 행의 현재 typed 집계값과 원시 라벨 데이터를 내보냅니다. `scope: 'selected'`에서는 선택된 고정 행만 포함합니다.
+- 이 옵션은 원본(`exportSource: true`)·피벗 export 및 CSV에는 적용되지 않습니다. DOM/`formatRow` 결과나 집계 formatter가 만든 화면 문자열을 직렬화하는 옵션도 아닙니다.
+
+#### 기타 IO 작업
+
 ```typescript
 // ── 1) 기본 export (메모리 Blob) ──
 const blob = await grid.io.toExcel({
@@ -1722,6 +1889,7 @@ import {
 } from '@vmscloud/moz-ui-grid-core';
 
 const grid = new PureSheet(el, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   fields,
   // 옛 저장본을 현재 스키마로 올린다. core 는 호출 시점·순서만 책임지고,
   // 어떤 버전에서 무엇을 바꿀지는 스키마를 아는 소비처가 정한다.
@@ -1781,17 +1949,20 @@ moz-ui-grid-core는 행 선택과 셀 선택을 **독립된 두 옵션**(`rowSel
 ```typescript
 // ── 행 전용 (단순 list 그리드) ──
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi' },
 });
 //   trigger 미지정 → 자동 'cellClick' (셀 클릭으로 행 선택)
 
 // ── 셀 전용 (Excel 스타일) ──
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   cellSelection: { mode: 'range' },
 });
 
 // ── 셀+행 분리: 행 헤더 클릭으로 행 선택 (정합성 보호) ──
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi' },  // trigger 자동 = 'rowHeader'
   cellSelection: { mode: 'range' },
 });
@@ -1799,18 +1970,21 @@ new PureSheet(container, {
 
 // ── 체크박스 트리거 ──
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi', trigger: 'checkbox' },
 });
 //   _rowHeader 컬럼 자동 주입 + CSS-only 체크박스 자동 렌더.
 
 // ── 트리거 복수 지정 (행 헤더 + 체크박스) ──
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi', trigger: ['rowHeader', 'checkbox'] },
   cellSelection: { mode: 'range' },
 });
 
 // ── 셀 클릭이 행도 선택 (legacy 'all' 동작) ──
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi', trigger: 'cellClick' },  // 명시 지정
   cellSelection: { mode: 'range' },
 });
@@ -1839,6 +2013,7 @@ AG Grid의 `ctrlASelectsRows` 옵션과 같은 의미.
 ```typescript
 // 기본 — 셀만 전체 선택 (AG Grid와 동일)
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi' },
   cellSelection: { mode: 'range' },
   // rowSelection.includeInSelectAll: false (기본)
@@ -1846,6 +2021,7 @@ new PureSheet(container, {
 
 // Ctrl+A로 행도 함께 fill
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi', includeInSelectAll: true },
   cellSelection: { mode: 'range' },
 });
@@ -1865,6 +2041,7 @@ new PureSheet(container, {
 ```typescript
 // 기본 (Policy A — 엄격 분리)
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi' },
   cellSelection: { mode: 'range' },
   // cellSelectionImpliesRows: false (기본)
@@ -1873,6 +2050,7 @@ new PureSheet(container, {
 
 // Policy B — Excel/Google Sheets 동작
 new PureSheet(container, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   rowSelection: { mode: 'multi' },
   cellSelection: { mode: 'range' },
   cellSelectionImpliesRows: true,
@@ -2132,6 +2310,7 @@ const chartField = {
 
 ```typescript
 new PureSheet(el, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   fields,
   rowSelection: { mode: 'multi', trigger: 'checkbox' },
   rowHeader: {
@@ -2201,6 +2380,7 @@ grid.formatRow.removeHandler('highlight');
 
 ```typescript
 new PureSheet(el, {
+  enableReferCache: true, // keyFields 생략: 내부 자동 ID 사용
   fields,
   formatHeader: (ctx) => {
     // 정렬된 컬럼에 data-* 마커