@vmscloud/moz-ui-grid-vue 0.2.6 → 0.2.7

package/docs/manual/reference.md

@@ -6,6 +6,23 @@
 
 > 📋 **사용 예제 코드는 별도 파일**: [examples.md](examples.md) — Sub-API별 사용, Reactive React 통합, 이벤트, 선택 모드, Excel I/O 등 약 30개 시나리오
 
+## 날짜 시간대 계약 (`timeZone`)
+
+```ts
+const grid = new PureSheet(container, { fields, data, timeZone: 'Asia/Seoul' });
+await grid.io.saveExcelToFile({ suggestedName: 'seoul.xlsx' });
+await grid.io.fromExcel(legacyFile, { timeZone: 'UTC' });
+```
+
+- 미지정: 기존 브라우저 로컬 날짜 표시와 UTC Excel serial IO를 유지합니다. `locale`로 시간대를 추론하지 않습니다.
+- 명시: 내장 날짜 mask와 날짜 기본 표시, XLSX serial export/import/preview가 같은 IANA 시간대를 사용합니다. 브라우저/OS 시간대와 무관합니다. 사용자 함수 mask/커스텀 렌더러의 출력은 변경하지 않습니다.
+- `Date`, 숫자 timestamp, `Z` 또는 offset이 있는 ISO 문자열은 **절대 시각**입니다. Offset 없는 ISO 날짜/시각(`2026-09-01 00:00:00`, `2026-09-01T00:00:00`), 날짜만(`2026-09-01`), compact 문자열(`20260901`, `20260901000000`)은 **설정 시간대의 벽시계 값**입니다. 호스트 로컬 `new Date(string)`로 먼저 해석하지 않습니다.
+- Excel은 시간대 정보를 저장하지 않습니다. 같은 파일을 왕복하려면 같은 zone을 사용해야 합니다. `2026-08-31T15:00:00Z`는 Seoul에서 `2026-09-01 00:00:00`, serial `46266`입니다. 미지정/UTC export는 기존 `46265.625`입니다.
+- 날짜만 표시하는 mask는 **시간 값을 자르지 않습니다**. XLSX 소수부에 시·분·초·밀리초가 유지됩니다. 임의의 날짜 문자열은 호스트 의존 파싱을 하지 않고 원문으로 남깁니다.
+- DST 해석은 Temporal `compatible`: 중복 시각은 **더 이른 instant**, 존재하지 않는 시각은 **gap 길이만큼 앞으로** 이동합니다. 따라서 DST 중복 시각의 두 instant를 Excel serial만으로 구분할 수 없습니다. 필요하면 UTC IO override를 사용하세요.
+- 잘못된 zone(빈 문자열 포함)은 `RangeError`입니다. UTC나 브라우저 zone으로 조용히 폴백하지 않습니다.
+- 코어에서는 생성 설정입니다. React/Vue provider 및 `coreConfig.timeZone` 변경은 기존 상태보존 재생성 경로로 반영됩니다.
+
 ## 목차
 
 - [개요](#개요)
@@ -221,6 +238,7 @@ grid.on('row:click', ({ rowIndex }) => {
 | `undoStack` | `UndoStack` | — | 외부 UndoStack 주입 |
 | **국제화** | | | |
 | `locale` | `string` | 자동 감지 | 로케일 (예: `'ko-KR'`) |
+| `timeZone` | `string` | 미지정 | IANA 시간대(예: `'Asia/Seoul'`). 날짜 표시와 XLSX import/export에 공통 적용. 미지정은 기존 로컬 표시·UTC IO 유지 |
 | `translations` | `PartialTranslationMap` | — | 번역 오버라이드 |
 | **포맷팅** | | | |
 | `formatRow` | `FormatRowCallback` | — | 행 포맷팅 콜백 (config에서 설정 시 `_config` 키로 자동 등록) |
@@ -858,7 +876,7 @@ PureSheet 인스턴스는 기능별 Sub-API 네임스페이스를 제공합니
 
 ### grid.cells — 셀 선택 API
 
-셀 = 행(rowId/viewIndex) + 열(columnId)의 교차점. 쓰기(select)와 조회(selected)를 제공한다.
+셀 = 행(rowId/viewIndex) + 열(columnId)의 교차점. 쓰기(select*)와 조회(getSelected*)를 제공한다.
 
 #### 선택 (셀 — 쓰기)
 
@@ -874,7 +892,9 @@ PureSheet 인스턴스는 기능별 Sub-API 네임스페이스를 제공합니
 
 | 메서드 | 반환 | 설명 |
 |--------|------|------|
-| `selected()` | `{rowId, columnId}[]` | 선택된 셀 목록 |
+| `getSelectedCellIds()` | `{rowId, columnId}[]` | 선택된 셀 목록 (셀 API 에는 `selected()` 가 없다 — 행 API `grid.rows.selected()` 와 다름) |
+| `getSelectedCells()` | `SelectedCell[]` | 선택된 셀 상세 (행 핸들·값 포함) |
+| `getActiveCell()` | `SelectedCell \| null` | 현재 활성 셀 |
 | `getSelectedCellRowIds()` | `string[]` | 선택된 셀이 걸친 행 rowId 목록(중복 제거) |
 | `getSelectedCellColumnIds()` | `string[]` | 선택된 셀이 걸친 컬럼 columnId 목록(중복 제거) |
 | `getSelectedCellIndices()` | `number[]` | 선택된 셀이 걸친 행 sourceIndex 목록(중복 제거) |
@@ -1274,8 +1294,13 @@ await grid.rowGroup.setConfig({
 저장본 0.4 → 0.5 마이그레이션은 옛 그룹 정렬 `column`/객체 `by`를 새 모델로 변환하고,
 피벗 `SortState.byValue`는 동일한 scalar 값 그대로 `by`로 개명합니다. 피벗 집계/정렬 의미는 변하지 않습니다.
 
-그룹 내부 데이터 행의 일반 정렬은 별도로 유지됩니다. null/undefined는 기존 정렬 규약대로
-오름차순에서는 뒤, 내림차순에서는 앞에 위치합니다. wrapper 정렬 패널의 **그룹 정렬 → 정렬 기준**에서도
+그룹 내부 데이터 행의 일반 정렬은 별도로 유지됩니다. 일반·계산 필드·그룹·트리·피벗 정렬에서
+null/undefined는 **오름차순(ASC)에서는 앞, 내림차순(DESC)에서는 뒤**에 위치합니다.
+두 값이 모두 null/undefined이면 동률이며, 다음 정렬 키를 비교하고 모든 키가 같으면 기존 순서를 유지합니다.
+빈 문자열(`''`), 공백 문자열, `0`, `false`는 null/undefined로 취급하지 않습니다.
+`sortKey`가 있으면 원본 값이 아닌 변환된 키를 비교합니다.
+이는 이전 ASC 뒤/DESC 앞 기본정책의 변경이며, 저장된 정렬 방향에도 새 기본정책이 적용됩니다.
+wrapper 정렬 패널의 **그룹 정렬 → 정렬 기준**에서도
 ‘그룹 이름’을 선택할 수 있습니다. 정렬 규칙이 없을 때와 새 규칙을 추가할 때 모두
 **그룹 이름 오름차순**이 기본입니다. 기존에 저장한 하위 행 개수·집계 정렬은 그대로 유지됩니다.
 
@@ -1626,6 +1651,8 @@ interface InvalidCell {
 
 #### Export 옵션 — `ExcelExportOptions`
 
+`timeZone?: string`은 해당 작업만 코어 시간대보다 우선합니다. `saveExcelToFile`과 Worker 경로에도 적용됩니다.
+
 | 필드 | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
 | `scope` | `'all' \| 'visible' \| 'selected'` | `'all'` | 데이터 범위 |
@@ -1699,6 +1726,8 @@ interface InvalidCell {
 
 #### Import 옵션 — `ExcelImportOptions`
 
+`timeZone?: string`은 해당 파일의 날짜 serial 해석 시간대를 재정의합니다. 예전 UTC 파일은 `{ timeZone: 'UTC' }`로 가져오세요. `previewExcel(file, { timeZone })`도 같은 옵션을 지원합니다.
+
 ##### 기본 옵션
 
 | 필드 | 타입 | 기본값 | 설명 |
@@ -2244,12 +2273,37 @@ grid.off('cell:click', handler);
 |--------|---------|------|
 | `cell:click` | `{ row, columnId, value, event }` | 셀 클릭 |
 | `cell:dblclick` | `{ row, columnId, value, event }` | 셀 더블클릭 |
-| `cell:change` | `{ rowIndex, rowId, columnId, oldValue, newValue }` | 셀 값 변경. `rowId`는 정렬/필터 무관 안정 식별자(정규화된 문자열) — cascade 등 rowId 기반 로직의 트리거로 사용 |
+| `cell:change` | `{ rowIndex, rowId, columnId, oldValue, newValue }` | 에디터 편집에 따른 셀 값 변경. API·붙여넣기·undo/redo를 모두 관찰하는 이벤트가 아님. `rowId`는 정렬/필터 무관 안정 식별자 |
+| `data:changed` | `DataMutationEvent` | ChangeTracker에 반영된 셀 데이터 변경. 에디터 생명주기와 독립적인 추가 이벤트 (아래 계약 참조) |
+| `changes:changed` | `{ hasChanges, addedCount, deletedCount }` | 기존 dirty 상태 요약. 신규 행 셀 수정도 발행하며 상세 값은 `data:changed`로 구독 |
 | `cell:beforeEdit` | `{ ..., cancel() }` | 편집 시작 전 (취소 가능) |
 | `cell:editCommitting` | `{ ..., cancel() }` | 편집 커밋 전 (취소 가능) |
 | `cell:editCommitted` | `{ rowIndex, rowId, dataIndex, columnId, oldValue, newValue }` | 편집 커밋 완료. `rowId` 포함 (위와 동일) — boolean 셀 즉시 토글도 이 이벤트로 발화되어 체크박스 cascade 트리거로 쓰인다 |
 | `cell:tooltip` | `CellTooltipPayload` (아래 참조) | 셀·컬럼 헤더 호버 시 툴팁 표시 요청 (`tooltipMode` 로 발행 제어) |
 
+**`DataMutationEvent` — 셀 데이터 변경 계약**
+
+```ts
+interface DataMutationEvent {
+  source: 'api' | 'edit' | 'paste' | 'undo' | 'redo' | 'import';
+  changes: Array<{
+    rowId: string | number;
+    field: string;
+    oldValue: CellValue;
+    newValue: CellValue;
+    sourceIndex?: number;
+  }>;
+}
+```
+
+- `oldValue`는 최초 원본이 아니라 **바로 이전 유효 값**, `newValue`는 이번 작업이 반영한 값입니다. Undo는 이전 값으로 되돌아가는 방향으로 전달합니다.
+- `field`는 데이터 바인딩 필드입니다. 표시 컬럼 ID·행 view index와 혼동하지 마세요. `sourceIndex`는 호출자가 아는 경우만 포함합니다.
+- 일반 셀 명령은 변경 1개를 발행합니다. Undo batch는 하나의 undo 단위이지만 셀 이벤트를 하나로 합치지는 않습니다. `beginBulkImport`/`endBulkImport` 구간은 실제 변경 순서를 유지한 `source: 'import'` 변경 묶음을 종료 시 한 번 발행합니다.
+- 현재 값과 `Object.is`로 같은 쓰기는 이벤트·dirty 버전·undo 기록을 만들지 않습니다. 삭제 예정 행에 대한 쓰기도 데이터 이벤트를 만들지 않습니다.
+- 이 이벤트는 **셀 값 쓰기** 계약이며 행 추가/삭제/재정렬, commit/discard, 데이터 전체 교체를 설명하는 이벤트가 아닙니다. 해당 상태는 기존 행 이벤트·`changes:changed`·undo/redo 이벤트로 구독합니다.
+- 신규 행의 임시 식별자는 key 필드를 수정해도 유지됩니다. 기존 행 검증은 설정된 단일/복합 key resolver를 사용하며, 다른 행 데이터·잘못된 originalData·partial seed는 여전히 거부합니다.
+- 알림은 ChangeTracker 반영 시점입니다. **processor 동기화보다 먼저 동기적으로 발행될 수 있으므로**, 핸들러에서는 payload의 `oldValue`/`newValue`를 사용하세요. API 호출의 완료 후 상태가 필요하면 해당 mutation API의 Promise를 기다리세요. 엔진 재조회·비동기 렌더 완료 신호가 아니며 취소할 수 없습니다. `cell:beforeEdit`/`cell:editCommitting`/`cell:editCommitted`의 의미는 바뀌지 않습니다.
+
 **`CellTooltipPayload`** (26cd68a 커밋에서 validation 정보 통합)
 
 | 필드 | 타입 | 설명 |
@@ -4011,7 +4065,7 @@ const grid = new PureSheet(el, {
 
 | 요소 | 표기 |
 |---|---|
-| 컬럼 참조 | `[컬럼헤더]`(표시) / `$id`(저장) — 공백·한글 헤더 지원 |
+| 컬럼 참조 | `[컬럼헤더]`(표시) / `$id` 또는 `$["변동 상태"]`(저장) — 공백·특수문자 ID 지원 |
 | 논리 | `AND` / `OR` / `NOT` 또는 `&&` / `\|\|` / `!` |
 | 비교 | `==` `!=` `>` `>=` `<` `<=` |
 | 문자열 | `CONTAINS` `NOT_CONTAINS` `STARTS_WITH` `ENDS_WITH` `LIKE` `IS_EMPTY` `IS_NOT_EMPTY` |
@@ -4043,6 +4097,16 @@ const grid = new PureSheet(el, {
 
 > 라벨이 바뀌어도(다국어·헤더 편집) **같은 저장본이 늘 현재 라벨로 보입니다.** 필터 평가는 저장 표기(`$id`)를 그대로 쓰므로 라벨 변경이 조건을 깨뜨리지 않습니다.
 
+**공백·특수문자 ID (ITSM-2026-002900)**
+
+- 기존 영문·숫자·한글·밑줄 ID는 `$simple_id`를 유지합니다. 그 외 ID는 `$[JSON 문자열]`로 저장합니다. ID 자체를 trim/치환/정규화하지 않습니다.
+- 예: ID가 `변동 상태`면 `$["변동 상태"] CONTAINS "증가"`, ID가 `a"b]c`면 `$["a\"b]c"] IS_NOT_EMPTY`입니다. JSON 큰따옴표와 이스케이프 규칙을 쓰며 빈 ID는 허용하지 않습니다.
+- Lexer/검증/평가와 `astToFormula`는 같은 바인딩 AST를 사용합니다. 문자열 리터럴 안의 `$`나 `[]`는 변환하지 않습니다. `$a-$b`는 계속 두 컬럼의 뺄셈입니다.
+- 현재 라벨이 중복이거나 `]`/앞뒤 공백/빈 문자열 때문에 라벨 표기로 왕복할 수 없으면 화면에도 명시적 ID 표기를 유지합니다.
+- `FormulaRefIssue.reason`은 `unknown`, `ambiguous`, `syntax`입니다. 토큰화 실패는 원문과 `syntax` 이슈를 반환합니다. 변환 성공 여부만으로 수식 유효성을 판단하지 말고 **변환 후 `validateFormula`**도 확인하세요.
+- 기존의 잘못된 저장본 `$변동 상태 …`는 자동으로 추측 복구하지 않습니다. 원문을 보존하고 편집기에서 오류를 표시합니다. 사용자가 컬럼을 다시 선택하거나 `$["변동 상태"]`로 명시적으로 고쳐야 합니다. 조건부 서식에서 오류가 있으면 규칙 전체 적용을 막고 이전 적용본을 유지합니다.
+- 새 표기를 읽지 못하는 구버전 Core로 되돌리면 해당 수식은 동작하지 않습니다. Core와 공용 wrapper를 함께 배포하고, 소비처 업그레이드 전에는 새 저장본을 공유하지 마세요.
+
 ---
 
 ### 값 목록 위젯 — ValueCheckList

package/docs/manual/reference_vue.md

@@ -6,6 +6,30 @@
 > 📋 **이 문서는 프레임워크 래퍼 표면만 다룹니다.** 코어 그리드 설정(`PureSheetConfig` 필드), 코어 타입, 이벤트 페이로드 형태는 코어 레퍼런스에 있습니다 → [reference.md](reference.md)
 > 📋 사용 예제 코드는 [examples.md](examples.md) 참조
 
+## 공통 설정 Provider
+
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue';
+import { MozGrid, MozGridConfigProvider, type MozGridConfig } from '@vmscloud/moz-ui-grid-vue';
+const gridConfig = reactive<MozGridConfig>({ locale: 'ko', timeZone: 'Asia/Seoul' });
+</script>
+<template>
+  <MozGridConfigProvider :config="gridConfig">
+    <MozGrid :core-config="{ fields, data }" />
+    <MozGrid :core-config="{ fields, data, timeZone: 'UTC' }" locale="en" />
+  </MozGridConfigProvider>
+</template>
+```
+
+`MozGridConfig`는 `{ locale?: string; timeZone?: string }`입니다. `useMozGridConfig()`는 병합 설정의 reactive `Ref<MozGridConfig>`를 반환합니다. `MOZ_GRID_CONFIG_KEY`도 공개 export입니다.
+
+시간대는 **개별 `coreConfig.timeZone` > provider > 미지정 기본값**, 언어는 **개별 `locale` prop > `coreConfig.locale` > provider > 기존 기본값**입니다. 중첩 provider의 undefined 필드는 상위에서 상속합니다. Config 객체 교체와 reactive 필드 변경 모두 반영되며, 명시된 개별 설정은 유지됩니다.
+
+`MozGridLocaleProvider`는 deprecated 호환 API입니다. 기존 `locale` prop 및 `useMozGridLocale`/`MOZ_GRID_LOCALE_KEY`는 유지되며 새 provider와 혼용할 수 있습니다. 신규 코드는 `MozGridConfigProvider :config="{ locale, timeZone }"`를 사용하세요.
+
+미지정은 기존 로컬 표시/UTC IO이며, 명시는 같은 zone으로 날짜 표시와 XLSX IO를 맞춥니다. Offsetless 문자열·DST·IO override 계약은 [코어 날짜 시간대 계약](reference.md#날짜-시간대-계약-timezone)을 참고하세요.
+
 ## 목차
 
 - [개요](#개요)
@@ -372,6 +396,16 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 
 ## Emits
 
+### 준비 완료·재생성·서식 콜백
+
+- `@ready(grid, chrome)`는 현재 인스턴스의 코어 초기화와 reinit 상태 복원 뒤에 발생합니다. unmount나 다음 reinit으로 폐기된 인스턴스의 대기 작업은 복원·emit을 이어서 실행하지 않습니다. 현재 인스턴스의 초기화 실패는 콘솔 오류로 보고하고 `ready`를 발생시키지 않습니다.
+- 설정 watch는 mount 훅 안에서 **동기 등록**됩니다. 첫 `ready`를 기다리는 동안의 prop 변경도 반영하며, unmount 시 Vue의 컴포넌트 scope와 함께 해제됩니다.
+- `ready()`는 `waitForReady()`의 초기화 완료를 뜻하며 `coreConfig.data`로 시작된 모든 비동기 데이터 로딩 완료를 보장하지 않습니다. 데이터 완료는 `@data:loaded` 또는 직접 호출한 `await grid.loadData(rows)`로 확인하세요.
+- `coreConfig.formatRow` / `formatHeader`는 첫 렌더 전에 등록됩니다. 함수 참조 교체·추가·제거는 재생성 없이 `_config` 핸들러만 갱신하고 `grid.refresh()`를 요청합니다. 다른 네임드 핸들러는 유지됩니다.
+- `@ready`에서 `grid.formatRow.addHandler('my-format', handler)`로 직접 등록하면 다음 렌더부터 적용됩니다. 기존 행에도 바로 적용하려면 등록 뒤 `await grid.refresh()`를 호출하세요. 등록 자체는 자동 repaint를 하지 않습니다. `formatHeader`도 동일하며 스크롤만으로 헤더가 다시 그려지지는 않습니다.
+- 핸들러는 인스턴스별이므로 직접 등록은 각 `@ready`에서 반복하세요. 제거는 이후 호출만 멈추며 임의 DOM 변경을 역으로 복원하지 않습니다. 상태에 따라 스타일을 적용/해제하는 대칭적인 콜백을 사용하세요.
+
+
 `MozGrid`는 총 **32개** 이벤트를 emit합니다: `defineEmits`가 선언하는 **31개**(고유 emit 2개 `ready`·`data:loaded` + 코어 인터랙션 이벤트 29개) + `defineModel`이 만드는 암시적 `update:coreConfig` 1개. 인터랙션 이벤트 29개(`row:click` … `contextmenu`)는 `defineEmits`에 선언됨과 동시에 `FORWARD_EVENTS` 배열로 코어에서 일괄 포워딩됩니다(`header:click`/`header:sortClick`/`header:filterClick` 포함 — 별도 배선이 아니라 같은 29개). `ready`/`data:loaded`는 어댑터가 직접 배선(`ready`는 `mountChrome`/`reinitChrome`에서, `data:loaded`는 전용 구독).
 
 > **페이로드 형태** — 인터랙션 이벤트 페이로드는 Vue 선언상 `[payload: unknown]`이지만 런타임에는 **코어 이벤트 페이로드**를 그대로 운반합니다. 실제 형태는 [reference.md 이벤트](reference.md#이벤트) 참조.
@@ -387,7 +421,8 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 | `row:reordered` | `[payload: unknown]` | 코어 이벤트 포워딩 |
 | `cell:click` | `[payload: unknown]` | 코어 이벤트 포워딩 |
 | `cell:dblclick` | `[payload: unknown]` | 코어 이벤트 포워딩 |
-| `cell:change` | `[payload: unknown]` | 코어 이벤트 포워딩 |
+| `cell:change` | `[payload: unknown]` | 에디터 셀 변경 이벤트 포워딩 |
+| `data:changed` | `[payload: DataMutationEvent]` | API·편집·붙여넣기·undo/redo의 실제 셀 변경. ChangeTracker 반영 시점이며 processor 동기화/렌더 완료 신호가 아님 |
 | `cell:beforeEdit` | `[payload: unknown]` | 코어 이벤트 포워딩 |
 | `cell:editCommitting` | `[payload: unknown]` | 코어 이벤트 포워딩 |
 | `cell:editCommitted` | `[payload: unknown]` | 코어 이벤트 포워딩 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmscloud/moz-ui-grid-vue",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "MozGrid - Vue 3 wrapping library for @vmscloud/moz-ui-grid-core",
   "license": "ISC",
   "type": "module",
@@ -80,7 +80,7 @@
   },
   "dependencies": {
     "@vmscloud/moz-ui-grid-core": "^0.1.46",
-    "@vmscloud/moz-ui-grid-wrapper": "^0.1.18",
+    "@vmscloud/moz-ui-grid-wrapper": "^0.1.20",
     "bytebuffer": "^5.0.1",
     "crypto-js": "^4.2.0",
     "echarts": "^5.5.0",