@vmscloud/moz-ui-grid-vue 0.2.8 → 0.2.9

package/docs/manual/reference_vue.md

@@ -1,7 +1,7 @@
 # MozGrid Vue 래퍼 레퍼런스 (Props · Emits · Slots · Instance API)
 
 > 패키지: `@vmscloud/moz-ui-grid-vue`
-> 마지막 업데이트: 2026-06-24
+> 검증 기준: `0481bd5` (main 리베이스 후 소스)
 
 > 📋 **이 문서는 프레임워크 래퍼 표면만 다룹니다.** 코어 그리드 설정(`PureSheetConfig` 필드), 코어 타입, 이벤트 페이로드 형태는 코어 레퍼런스에 있습니다 → [reference.md](reference.md)
 > 📋 사용 예제 코드는 [examples.md](examples.md) 참조
@@ -16,8 +16,8 @@ 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" />
+    <MozGrid :core-config="{ enableReferCache: true, fields, data }" />
+    <MozGrid :core-config="{ enableReferCache: true, fields, data, timeZone: 'UTC' }" locale="en" />
   </MozGridConfigProvider>
 </template>
 ```
@@ -38,12 +38,14 @@ const gridConfig = reactive<MozGridConfig>({ locale: 'ko', timeZone: 'Asia/Seoul
 - [빠른 시작](#빠른-시작)
 - [Props](#props)
   - [v-model:coreConfig (코어 설정)](#v-modelcoreconfig-코어-설정)
+  - [초기화·편집·XLSX 설정 전달](#초기화편집xlsx-설정-전달)
   - [WrapperExtras 옵션 (래퍼 전용)](#wrapperextras-옵션-래퍼-전용)
   - [WrapperUIOptions — UI 표시 플래그](#wrapperuioptions--ui-표시-플래그)
   - [contextMenuConfig — IContextMenuConfig](#contextmenuconfig--icontextmenuconfig)
   - [emptyState — EmptyStateConfig](#emptystate--emptystateconfig)
   - [sourceFields — PivotSourceField](#sourcefields--pivotsourcefield)
   - [chartMap — ChartSeriesConfig](#chartmap--chartseriesconfig)
+  - [chartConfig — 내장 피벗 차트 설정](#chartconfig--내장-피벗-차트-설정)
   - [locale](#locale)
 - [Emits](#emits)
 - [Slots](#slots)
@@ -115,27 +117,24 @@ npmjs에 공개 패키지로 게시됩니다. 레지스트리 매핑이나 토
 
 ### 스타일 import
 
-그리드 스타일은 **두 개의 스타일시트**로 나뉩니다. 앱 진입점에서 한 번씩 import하세요.
+Vue 패키지의 스타일시트는 코어 + 크롬 셸 + Vue 어댑터 스타일을 포함합니다. 앱 진입점에서 한 번 import하세요.
 
 ```typescript
-// 1) 코어 그리드 본체 + 크롬 셸 — **필수**. 코어 그리드 클래스(.ps-*)는 래퍼 스타일시트에만 있다.
-import '@vmscloud/moz-ui-grid-wrapper/style.css';
-// 2) Vue 어댑터 추가 스타일
 import '@vmscloud/moz-ui-grid-vue/style.css';
 ```
 
-> ⚠️ `@vmscloud/moz-ui-grid-vue/style.css`만 import하면 그리드 **본체가 스타일 없이** 렌더됩니다 — 코어 그리드 스타일(`.ps-*`)은 `@vmscloud/moz-ui-grid-wrapper`의 `style.css`에만 포함되어 있습니다(래퍼는 vue 패키지의 런타임 의존성이라 별도 설치는 불필요).
+wrapper의 `style.css`는 코어 + 셸 통합 스타일이며, 위 Vue 통합 스타일을 사용하면 별도로 중복 import할 필요가 없습니다.
 
 ### 서브패스 exports
 
 | 서브패스 | 내용 |
 |----------|------|
 | `.` | 메인 엔트리 (`MozGrid`, 컨트랙트, 템플릿, compat 등) |
-| `./style.css` | Vue 어댑터 추가 스타일 (코어 그리드 본체 스타일은 `@vmscloud/moz-ui-grid-wrapper/style.css` 필요) |
+| `./style.css` | 코어 + 셸 + Vue 어댑터 통합 스타일 |
 | `./store` | Excel 스토어 (`useExcelStore` / `useExcelDownloadStore` / `useExcelUploadStore`) |
 | `./utils/excel/*` | Excel 유틸 5종 (`ExcelGuard` · `ExcelQueueManager` · `ExcelTaskRunner` · `ExcelTimeoutManager` · `ExcelImportUtil`) |
 
-> 패키지 버전 0.1.40 · `type: module` · `main` `dist/index.cjs` · `module` `dist/index.js` · `types` `dist/index.d.ts`.
+> `type: module` · `main` `dist/index.cjs` · `module` `dist/index.js` · `types` `dist/index.d.ts`.
 
 ### 타입 재노출
 
@@ -156,16 +155,16 @@ Vue 패키지는 소비처가 wrapper/core 를 직접 의존하지 않아도 핸
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { MozGrid } from '@vmscloud/moz-ui-grid-vue';
+import { MozGrid, CellTemplate } from '@vmscloud/moz-ui-grid-vue';
 // `@ready` 핸들러 인자 타입은 vue 패키지가 재노출합니다 — 소비처 package.json 에 wrapper/core
 // 의존성이 없어도 타입을 지정할 수 있습니다(ITSM-2026-002154).
 import type { MozGridCoreProps, GridChrome, PureSheet } from '@vmscloud/moz-ui-grid-vue';
-import '@vmscloud/moz-ui-grid-wrapper/style.css'; // 코어 그리드 본체 + 셸 (필수)
-import '@vmscloud/moz-ui-grid-vue/style.css';     // Vue 어댑터 추가 스타일
+import '@vmscloud/moz-ui-grid-vue/style.css'; // 코어 + 셸 + Vue 어댑터
 
 // 코어 그리드 설정(PureSheetConfig 평탄형). 필드별 의미는 reference.md 참조.
 const coreConfig = ref<MozGridCoreProps>({
   mode: 'flat',
+  keyFields: ['id'], // 업무 키를 명시 (원본 id 필드가 자동 선택되지는 않음)
   fields: [
     // id = 컬럼 식별자(가리킬 때), field = 원본 데이터 키(읽을 때, 생략 시 id).
     { id: 'name', header: '이름', dataType: 'string', width: 200 },
@@ -182,7 +181,7 @@ const gridRef = ref();
 // `@ready` 는 2개 인자를 줍니다: 코어 PureSheet + wrapper GridChrome.
 function onReady(grid: PureSheet, chrome: GridChrome) {
   console.log('grid ready', grid);
-  chrome.setPivotBarVisible(true);   // 피벗 옵션 바를 처음부터 켜 두기
+  chrome.setToolbarVisible(false);   // 툴바를 처음부터 접기(펼치기 토글은 유지)
 }
 </script>
 
@@ -215,7 +214,17 @@ function onReady(grid: PureSheet, chrome: GridChrome) {
 
 ## Props
 
-`MozGrid`의 props는 `withDefaults(defineProps<WrapperExtras & { name?: string }>(), {...})`로 선언됩니다. 즉 props 표면은 **`coreConfig`(별도 v-model)** + **WrapperExtras(래퍼 전용 키)** + **`name`(Vue 전용 프리셋 식별자)** 입니다.
+`MozGrid`의 props는 `withDefaults(defineProps<WrapperExtras & { name?: string; usePreset?: boolean }>(), {...})`로 선언됩니다. 즉 props 표면은 **`coreConfig`(별도 v-model)** + **WrapperExtras(래퍼 전용 키)** + **`name`/`usePreset`(Vue 전용 프리셋 옵션)** 입니다.
+
+| Vue 전용 옵션 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `usePreset` | `boolean` | `true` | 생성 시에만 읽는 프리셋 참여 여부. `false`면 `UserLayoutInstance` 생성, 호스트 등록, 저장된 프리셋 복원을 모두 건너뜁니다. `name`은 그대로 유지됩니다. |
+
+```vue
+<MozGrid name="orders" :use-preset="false" v-model:coreConfig="coreConfig" />
+```
+
+`usePreset` 생략 또는 `true`는 기존 `name` + 호스트 `'user-layout-module'` 동작을 유지합니다. 마운트 후 prop 변경은 활성화/해제/등록 취소를 수행하지 않습니다. 값을 바꾸려면 컴포넌트를 새로 마운트하세요. 이 옵션은 Vue 프리셋 통합에만 적용되며, 코어 설정이나 툴바 표시 옵션이 아닙니다.
 
 ### v-model:coreConfig (코어 설정)
 
@@ -240,11 +249,34 @@ type MozGridCoreProps =
 
 > `coreConfig`의 `fields`는 코어에 전달되기 전에 `cell`/`header`/`editor` 슬롯 템플릿을 `FieldDef` 콜백으로 변환하는 `buildFieldDefs`를 거치며, raw 참조 동일성으로 메모이즈됩니다(큰 배열의 깊은 순회 회피).
 
+### 초기화·편집·XLSX 설정 전달
+
+- **행 식별 설정은 필수**입니다. 업무 키가 있으면 `coreConfig.keyFields`를 명시하고, 키 없이 시작하려면 `coreConfig.enableReferCache: true`를 설정하세요(기본 `false`). 두 설정 모두 생략하거나 `keyFields: []`를 전달하면 초기화할 수 없습니다. 원본 `id` 필드를 자동으로 키로 선택하지 않습니다. 자동 ID 수명과 행 객체 참조 계약은 [코어 Config](reference.md#config-설정)를 참조하세요.
+- 내장 숫자/날짜시간 편집기는 별도 래퍼 prop이 아니라 `coreConfig.fields[].editor`로 전달합니다. 아래 설정을 기존 `coreConfig`에 병합하세요.
+
+```ts
+import type { MozGridCoreProps } from '@vmscloud/moz-ui-grid-vue';
+// coreConfig의 일부 — data/keyFields 등은 기존 설정 유지
+const editingConfig: MozGridCoreProps = {
+  editable: true,
+  timeZone: 'Asia/Seoul',
+  fields: [
+    { id: 'quantity', dataType: 'number', editor: { type: 'number', min: 0, max: 100, step: 0.5 } },
+    { id: 'scheduledAt', dataType: 'date', editor: { type: 'datetime' },
+      mask: { type: 'date', pattern: 'YYYY-MM-DD HH:mm:ss' } },
+  ],
+};
+```
+
+`datetime`은 **에디터 타입**이며 날짜 필드의 `dataType`은 `'date'`입니다. 숫자 경계/step 검증, `Date | null` 커밋, 시간대 처리는 [EditorConfig](reference.md#editorconfig) 및 [날짜 시간대 계약](reference.md#날짜-시간대-계약-timezone)을 따릅니다. 필드 변경은 새 `fields` 배열로 전달하세요.
+
+XLSX 컨텍스트 메뉴는 `contextMenuConfig.clientExportOptions`로 옵션을 전달합니다. 예: `{ clientExportOptions: { preserveFormatting: true } }`. 래퍼 `ExcelController`는 기본 `true`이며, 코어 `grid.io`를 직접 호출할 때 기본은 `false`입니다. 고정 행(`includePinnedRows`)도 같습니다: 컨텍스트 메뉴 XLSX/CSV와 `runClientExport`는 화면에 보이는 고정 행(구조·데이터 고정)을 화면 순서로 포함하고(`true`), 끄려면 `clientExportOptions: { includePinnedRows: false }`, 코어 직접 호출 기본은 `false`입니다. 날짜 Excel 서식은 위와 같은 구조화된 `mask`에서 변환됩니다. **export 옵션 `dateFormat`은 제거**되었으므로 전달하지 마세요(에디터 `dateFormat`과는 별개). 지원 패턴·fallback·원본 날짜 값 계약은 [Excel Import/Export](reference.md#gridio--excel-importexport-api)를 참조하세요.
+
 ### WrapperExtras 옵션 (래퍼 전용)
 
-`WrapperExtras`는 `WrapperUIOptions`를 확장(상속 12개 UI 플래그 + 자체 8개 키 = 20개)합니다. 어댑터가 코어 설정을 만들기 전에 이 키들을 분리(strip)합니다. **코어 `PureSheetConfig`와 겹치는 유일한 키는 `locale`**(둘 다 `string`, 무해하며 의도적으로 분리 대상에서 제외 → 코어·래퍼 양쪽에 전달).
+`WrapperExtras`는 `WrapperUIOptions`를 확장(UI 플래그 + 래퍼 전용 키)합니다. 어댑터가 코어 설정을 만들기 전에 이 키들을 분리(strip)합니다. **코어 `PureSheetConfig`와 겹치는 유일한 키는 `locale`**(둘 다 `string`, 무해하며 의도적으로 분리 대상에서 제외 → 코어·래퍼 양쪽에 전달).
 
-> **기본값 출처 주의** — Vue `withDefaults`는 **10개 키만** 설정합니다: `height` + 8개 항상-on UI 플래그(`useToolBox` · `useToolBoxSetting` · `useExtendFooter` · `useSummaryFooter` · `useSort` · `useCustomCell` · `useContextMenu` · `useBuiltinTooltip`) + `usePivotBar`. 그 외 키는 prop 레이어에서 `undefined`로 남고, 래퍼의 `DEFAULT_UI_OPTIONS`/`resolveUIOptions`(UI 플래그 SSOT) 또는 다운스트림(차트 등)에서 문서화된 기본값으로 해석됩니다. 아래 표의 기본값은 **최종 적용 기본값**입니다.
+> **기본값 출처 주의** — Vue는 미전달 boolean prop을 `false`로 변환합니다. `withDefaults`가 툴박스·푸터·설정 권한·피벗 바 등 기본-on 플래그와 `usePreset: true`를 복원하며, `useSummaryFooter`는 명시적으로 `false`입니다. React의 undefined → `resolveUIOptions` 경로와 구분하세요.
 >
 > ⚠️ `usePivotBar` 가 `withDefaults` 에 있는 이유: **Vue 는 미전달 boolean prop 을 `false` 로 강제**하므로 여기서 복원하지 않으면 prop 을 안 준 소비처에서 바가 통째로 사라집니다(= 피벗 정렬·필터 진입점 상실).
 
@@ -265,22 +297,31 @@ type MozGridCoreProps =
 | `useCustomCell` | `boolean` | `true` | 조건부 서식(커스텀 셀) 활성화 |
 | `useContextMenu` | `boolean` | `true` | 컨텍스트 메뉴 활성화 |
 | `useBuiltinTooltip` | `boolean` | `true` | 내장 셀/헤더 툴팁 렌더러 사용. `false`면 wrapper가 툴팁을 그리지 않음 — 코어 `cell:tooltip` 이벤트는 그대로 발행되므로 소비처가 `@ready`의 `grid.on('cell:tooltip', …)`로 직접 렌더 가능(발행은 `tooltipMode`로 제어) |
+| `toolbarConfig` | `{ filter?: { disabled?: boolean; hidden?: boolean } }` | — | 툴바 **고급 필터 버튼만** 제어. `filter.disabled`: 버튼은 보이되 비활성(실제 비활성 = 필드 없음 || `disabled`). `filter.hidden`: 필터 버튼만 제거, 나머지 버튼 배치 유지. 다른 툴바 버튼·헤더 필터 아이콘(`showFilterIcon`)·컨텍스트 메뉴(`contextMenuConfig.useFilter`)·걸린 필터 조건은 영향 없음. 비활성으로 바뀌어도 열린 고급 필터 창은 닫지 않음. 객체 단위 교체(생략한 키는 `false`). 런타임 변경 지원(툴박스 재조립 없음, reactive 중첩 필드 변경도 추적). 화면 제어 입력이라 프리셋에 저장되지 않음 |
 | `usePivot` | `boolean` | `false` | 피벗 패널 버튼 표시 (Vue withDefaults 미설정 → `DEFAULT_UI_OPTIONS`에서 `false`) |
 | `usePivotBar` | `boolean` | `true` | **피벗 옵션 바(툴박스 아래 행/열/값 한 줄) 사용 여부** — 피벗 모드 전용 (ITSM-2026-002154). Vue `withDefaults` 가 `true` 로 복원 |
 | `useChart` | `boolean` | `false` | 피벗 차트 버튼 표시(피벗 모드 전용). Vue withDefaults 미설정 |
-| `useMultipleChart` | `boolean` | `true` | 피벗 차트 Multiple(행별 미니 차트) 모드. Vue withDefaults 미설정 → 다운스트림에서 `true` 적용(legacy MozPivotVue 패리티) |
+| `useMultipleChart` | `boolean` | `false` (Vue 미전달 시) | Vue boolean prop 변환으로 `false`가 전달됩니다. 공용 wrapper/React의 미지정 기본값 `true`와 다릅니다. Multiple 모드는 `:use-multiple-chart="true"`로 명시하세요. |
 | `chartIncludeGrandTotal` | `boolean` | `false` | 피벗 차트에 총합(Grand Total) 카테고리 포함 |
 | `chartMap` | `Record<string, ChartSeriesConfig>` | `undefined` | 피벗 차트 시리즈별 type/color 설정 → [chartMap](#chartmap--chartseriesconfig) |
+| `chartConfig` | `PivotChartConfig` | `undefined` | 내장 피벗 차트 설정(`transformData`/`xAxisLabelFormatter`/`accumulate`/제외 목록) → [chartConfig](#chartconfig--내장-피벗-차트-설정) |
 | `loading` | `boolean` | `false` | 로딩 오버레이 강제 표시(호스트 비동기 상태). `false`여도 내부 비동기 작업(`activity!=='idle'` && 검색 아님) 중에는 스피너 자동 표시. Vue는 `{ immediate: true }` 전용 watch로 `chrome.setUIOptions({ loading })` 배선 |
 | `locale` | `string` | `'ko'` | UI 언어 → [locale](#locale) |
 | `contextMenuConfig` | `IContextMenuConfig` | `undefined` | 컨텍스트 메뉴 설정 → [contextMenuConfig](#contextmenuconfig--icontextmenuconfig) |
 | `emptyState` | `EmptyStateConfig` | `undefined` | 빈 상태 오버레이 설정 → [emptyState](#emptystate--emptystateconfig) |
 | `sourceFields` | `PivotSourceField[]` | `undefined` | 피벗 배치 후보 필드 카탈로그 → [sourceFields](#sourcefields--pivotsourcefield) |
 
+> **툴바 필터 버튼만 막기** (예: 노드 필터 중에는 고급 필터 진입 차단)
+> ```vue
+> <MozGrid v-model:core-config="cfg" :toolbar-config="{ filter: { disabled: isNodeFiltered } }" />
+> <!-- 버튼 자체를 없애려면 :toolbar-config="{ filter: { hidden: true } }" -->
+> ```
+
+
 > **`usePivotBar` — "지금 보이는가"가 아니라 "이 화면에서 바를 쓰는가" (ITSM-2026-002154)**
 > 표시/숨김은 사용자가 런타임에 바꾸는 **상태**이므로 prop 이 아니라 `GridChrome.setPivotBarVisible()` 이 소유합니다. 초기에 켜 두려면 `@ready` 의 2번째 인자로 오는 chrome 에서 호출하세요:
 > ```vue
-> <MozGrid :usePivotBar="true" @ready="(grid, chrome) => chrome.setPivotBarVisible(true)" />
+> <MozGrid v-model:coreConfig="coreConfig" :usePivotBar="true" @ready="(grid, chrome) => chrome.setPivotBarVisible(true)" />
 > ```
 >
 > 🚨 **`false` 는 바를 숨기는 것이 아니라 피벗의 정렬·필터 진입점을 함께 제거합니다:**
@@ -289,13 +330,13 @@ type MozGridCoreProps =
 >
 > 그래서 기본값이 `true` 이며, `false` 는 "피벗을 읽기 전용 표로만 쓴다"는 선언에 가깝습니다.
 
-> **라이브 토글** — UI 플래그(`useToolBox`/`useToolBoxSetting`/`useExtendFooter`/`useSummaryFooter`/`useSort`/`useCustomCell`/`useContextMenu`/`useBuiltinTooltip`/`usePivot`/`usePivotBar`)는 변경 시 `chrome.setUIOptions`로 런타임 갱신됩니다(`useBuiltinTooltip`은 내장 툴팁 렌더러를 런타임에 생성/파괴). `loading`·`sourceFields`·**`contextMenuConfig`** 는 각자 전용 watch 를 가집니다(`sourceFields`/`contextMenuConfig` 는 래퍼 전용 키라 reconcile 을 거치지 않고 `chrome.setSourceFields`/`chrome.setContextMenuConfig` 로 직접 전파). `useChart`/`useMultipleChart`/`chartIncludeGrandTotal`/`chartMap`은 `GridChromeOptions`로 전달만 됩니다(라이브 watch X). `height`는 순수 어댑터 로컬(`hostStyle`).
+> **라이브 토글** — UI 플래그(`useToolBox`/`useToolBoxSetting`/`useExtendFooter`/`useSummaryFooter`/`useSort`/`useCustomCell`/`useContextMenu`/`useBuiltinTooltip`/`toolbarConfig`/`usePivot`/`usePivotBar` 및 `useRowGroupSettings`/`useFieldSettings`/`useFormatSettings`/`useLayoutSettings`/`useAggregateSettings`)는 변경 시 `chrome.setUIOptions`로 런타임 갱신됩니다(`useBuiltinTooltip`은 내장 툴팁 렌더러를 런타임에 생성/파괴). `loading`·`sourceFields`·**`contextMenuConfig`**·**`chartConfig`** 는 각자 전용 watch 를 가집니다(`sourceFields`/`contextMenuConfig`/`chartConfig` 는 래퍼 전용 키라 reconcile 을 거치지 않고 `chrome.setSourceFields`/`chrome.setContextMenuConfig`/`chrome.setChartConfig` 로 직접 전파). `useChart`/`useMultipleChart`/`chartIncludeGrandTotal`/`chartMap`은 `GridChromeOptions`로 전달만 됩니다(라이브 watch X). `height`는 순수 어댑터 로컬(`hostStyle`).
 >
 > ⚠️ `contextMenuConfig` 는 이전에 `buildChromeOptions` 가 **생성 시 1회만** 읽어, 소비자가 `customMenu` 를 비동기로 채우면(예: 새 탭 열기 대상의 메뉴 이름 lookup 응답 후) 그대로 유실됐습니다. 이제 변경 시 크롬에 전파됩니다.
 
 ### WrapperUIOptions — UI 표시 플래그
 
-`WrapperExtras`가 확장하는 12개 UI 플래그 베이스 인터페이스입니다. `DEFAULT_UI_OPTIONS`(`Required<WrapperUIOptions>`)가 기본값 SSOT이고, `resolveUIOptions`가 `options.X ?? DEFAULT_UI_OPTIONS.X`로 병합합니다(프레임워크 무관 기본값).
+`WrapperExtras`가 확장하는 UI 플래그 베이스 인터페이스입니다. `DEFAULT_UI_OPTIONS`(`Required<WrapperUIOptions>`)가 기본값 SSOT이고, `resolveUIOptions`가 `options.X ?? DEFAULT_UI_OPTIONS.X`로 병합합니다(프레임워크 무관 기본값).
 
 | 플래그 | 기본값 | 플래그 | 기본값 |
 |--------|--------|--------|--------|
@@ -305,8 +346,11 @@ type MozGridCoreProps =
 | `useSummaryFooter` | `false` | `useChart` | `false` (피벗 전용) |
 | `useSort` | `true` | `loading` | `false` |
 | `useCustomCell` | `true` | `useBuiltinTooltip` | `true` |
+| `useRowGroupSettings` | `true` | `useFieldSettings` | `true` |
+| `useFormatSettings` | `true` | `useLayoutSettings` | `true` |
+| `useAggregateSettings` | `true` | — | — |
 
-> `useMultipleChart`/`chartIncludeGrandTotal`/`chartMap`/`height`/`locale`/`sourceFields`/`contextMenuConfig`/`emptyState`는 `WrapperUIOptions`가 아니라 `WrapperExtras`에만 존재합니다.
+> `useMultipleChart`/`chartIncludeGrandTotal`/`chartMap`/`chartConfig`/`height`/`locale`/`sourceFields`/`contextMenuConfig`/`emptyState`는 `WrapperUIOptions`가 아니라 `WrapperExtras`에만 존재합니다.
 
 ### contextMenuConfig — IContextMenuConfig
 
@@ -320,7 +364,7 @@ type MozGridCoreProps =
 | `useSort` | `boolean?` | 정렬 항목 토글 |
 | `useFilter` | `boolean?` | 필터 항목 토글 |
 | `useCustomCell` | `boolean?` | 조건부 서식 항목 토글 |
-| `useBulkEditColumn` | `boolean?` | 컬럼 일괄 편집 항목 토글 |
+| `useBulkEditColumn` | `boolean?` | 컬럼 일괄 편집 항목 토글. 숫자 컬럼의 일괄 편집 입력은 `FieldDef.editor`의 `min`/`max`/`step`(`type: 'number'`)을 따르고, 범위·간격에 맞지 않는 값은 셀 편집과 같이 [확인]이 비활성됩니다(자동 보정 없음, 빈 값은 `null`). `step` 미선언 시 기존 5 단위 |
 | `useDataCopy` | `boolean?` | 데이터 복사 항목 토글 |
 | `useDataWithHeaderCopy` | `boolean?` | 헤더 포함 복사 항목 토글 |
 | `useAutoSizeColumns` | `boolean?` | 컬럼 자동 크기 항목 토글 |
@@ -367,7 +411,7 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 
 `PivotRowField`/`PivotColumnField`/`PivotValueField` 3종의 교집합이므로 모든 row/column/value 필드 props(`field`, `header`, `dataType`, `aggregate`, `formula`, `showValueAs`, `headerAttributes`, `cellAttributes`, `width` 등)를 선언할 수 있습니다. **각 필드 상세는 코어 레퍼런스 참조**(3종 모두 코어 `pivot.types.ts`) → [reference.md 피벗 필드 타입](reference.md#피벗-필드-타입).
 
-> 런타임 갱신: `chrome.setSourceFields(...)`(어댑터가 `sourceFields` prop watch에서 호출). `PivotSourceField`는 래퍼 index에서 재-export되지 않으며 `sourceFields`/`chartMap` 등의 요소 타입으로만 도달합니다.
+> 런타임 갱신: `chrome.setSourceFields(...)`(어댑터가 `sourceFields` prop watch에서 호출). `PivotSourceField`는 `@vmscloud/moz-ui-grid-wrapper`의 controllers 배럴을 통해 export됩니다(Vue 루트에서는 재노출하지 않음).
 
 ### chartMap — ChartSeriesConfig
 
@@ -380,17 +424,181 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 
 > `ChartSeriesConfig`/`ChartType`은 래퍼 index에서 재-export되지 않으며 `chartMap`의 값 타입으로만 도달합니다.
 
+### chartConfig — 내장 피벗 차트 설정
+
+**범위: wrapper 내장 피벗 차트(차트 버튼·컨텍스트 메뉴 '차트 열기'로 여는 차트 패널)만.** 그리드 셀·내보내기·`grid.pivot.getSeriesData()` 직접 호출 결과에는 영향이 없습니다. 이름은 `coreConfig`/`contextMenuConfig` 와 같은 `xxxConfig` 규칙입니다. Prop: `:chart-config`.
+
+```ts
+interface PivotChartConfig {
+  /** getSeriesData 결과를 차트에 덮어쓰기 직전에 한 번 호출. 반환값을 차트 데이터로 사용 */
+  transformData?: (data: PivotSeriesData, ctx: ChartTransformContext) => PivotSeriesData;
+  /** X축 라벨 표시 변환 */
+  xAxisLabelFormatter?: (label: string) => string;
+  /** 레거시 setChartData 대체 — 리프 data 행 × 값 칸마다 호출, add(시리즈명, 값)으로 (범주, X축) 칸에 합산 */
+  accumulate?: (cell: PivotChartCell, add: (seriesName: string, value: number | null) => void) => void;
+  /** Y축 범주 후보에서 제외할 행 필드 id */
+  categoryFieldsExclude?: string[];
+  /** X축 범주 후보에서 제외할 열 필드 id */
+  xAxisFieldsExclude?: string[];
+  /** 값 필드 후보·초기 선택을 이 값 필드 id 로 제한 */
+  valueFields?: string[];
+  /** 차트를 그릴 외부 요소(또는 CSS 선택자). 미지정/null = 그리드 내부 50/50 분할 */
+  container?: HTMLElement | string | null;
+}
+interface PivotChartCell {
+  category: string;                        // getRowHeaderPath(행 필드 값, 현재 범주) — 일반 차트 범주 이름과 같음(중간 단계 범주도 '서울 › 1공장')
+  categoryKey: string;                     // getRowHeaderKey — 경로 값 '|' join('|'·'\' 이스케이프), 범주 합산 기준. 이전 core 면 category
+  categoryPath: string[];                  // 최상위 행 필드 → 범주 필드 값. 이전 core 면 [category]
+  xLabel: string;                          // 열 경로를 현재 X축 레벨까지 잘라 '\n' join — 일반 차트 xLabels 와 같음
+  rowValues: Record<string, CellValue>;    // 행 필드 id → 값 (레거시 rowField)
+  columnValues: Record<string, CellValue>; // 열 필드 id → 열 헤더 키 문자열
+  valueField: string;                      // 값 필드 id
+  value: number | null;                    // 칸 값(숫자가 아니면 null)
+}
+// PivotSeriesData = { xLabels: string[]; categories: { name: string; key: string; path: string[]; series: { name: string; data: (number | null)[] }[] }[] }
+interface ChartTransformContext {
+  categoryField: string;                 // 차트 툴바 'Y축 범주'(행 필드 식별자)
+  columnFieldLevel: number | undefined;  // 'X축 범주' 레벨, '전체'면 undefined
+  valueFields: string[];                 // 선택된 값 필드 식별자
+  includeGrandTotal: boolean;            // chartIncludeGrandTotal
+  rowFields: { id; field; header }[];      // getPivotMeta().rowFields
+  columnFields: { id; field; header }[];   // getPivotMeta().columnFields
+  allValueFields: { id; field; header; aggregate? }[]; // getPivotMeta().valueFields (선택 무관)
+  pivotConfig: PivotConfig | null;       // grid.pivot.getConfig() — 내부 참조, 읽기 전용
+}
+```
+
+`PivotChartConfig`/`ChartTransformContext` 타입은 `@vmscloud/moz-ui-grid-wrapper` 에서 import 합니다.
+
+| 키 | 동작 |
+|----|------|
+| 미지정 | 현재 동작 그대로(변환 없음, 축 옵션 무변경) |
+| `transformData` | 차트 갱신(열기·필터/정렬/데이터 로드·피벗 설정 변경·툴바 선택 변경)마다 `getSeriesData` 직후 1회 호출. 인자 `data` 는 **복사본**이라 변조해도 안전. 예외를 던지거나 형태가 잘못되면(`xLabels`/`categories` 가 배열이 아니거나, 각 `name` 이 문자열·`series[].data` 가 배열이 아님) `console.error` 후 **원본 데이터 사용** |
+| `xAxisLabelFormatter` | X축 라벨 **표시**만 변환(`xLabels` 데이터 불변). 상세(풀사이즈) 차트의 축 라벨·axisPointer 라벨·툴팁 제목에 같은 변환 적용. 라벨 회전·초기 줌 계산은 변환 후 문자열 기준. Multiple 모드 미니 차트는 원래 축 라벨을 표시하지 않음. 예외 시 원본 라벨(`console.error` 는 함수당 1회) |
+| `accumulate` | 지정하면 `getSeriesData` 대신 `grid.pivot.getDataMatrix({ subtotals:'none', grandTotals:'none', excludeStructuralColumns:true })` 의 **리프 data 행 × 선택된 값 필드의 값 칸**마다 1회 호출. `add(시리즈명, 값)` 은 (`cell.category`, `cell.xLabel`) 칸에 합산(null 무시, 더해진 값이 없으면 null). `add` 는 `accumulate` 안에서 **동기로만** 호출. 범주·X축 순서 = 피벗 결과 순서, 시리즈 순서 = add 최초 등장 순(모든 범주가 같은 시리즈 목록). `chartIncludeGrandTotal` 이면 범주별 결과를 합산한 `Grand Total` 범주를 마지막에 붙임. 결과는 `transformData` → 렌더로 이어짐. 예외(또는 `columns` 를 주지 않는 이전 core) 시 `console.error` 후 기본 `getSeriesData` 경로. 범주 이름이 일반 차트와 같아 Detail 모드 셀 클릭 → 범주 전환이 그대로 동작 |
+| `categoryFieldsExclude` | 툴바 'Y축 범주' 후보에서 제외할 **행 필드 id**. 초기·폴백 범주 = 제외 후 첫 후보 |
+| `xAxisFieldsExclude` | 툴바 'X축 범주' 후보에서 제외할 **열 필드 id**. 실제로 제외되는 필드가 있으면 '전체' 후보를 숨기고 남은 첫 레벨이 기본(X축 라벨은 기존처럼 그 레벨까지의 경로) |
+| `container` | 차트를 그릴 **외부 요소**(`HTMLElement`) 또는 CSS 선택자. 미지정·`null` 이면 기존처럼 그리드 내부 50/50 분할. 지정하면 차트를 열 때(툴박스 차트 버튼·컨텍스트 메뉴 '차트 열기' 공통) 그리드 root 를 분할하지 않고(그리드 100%, 리사이저·내부 차트 영역 숨김) 차트 패널 `.mzc-pivot-chart.mzc-pivot-chart--external` 을 그 요소의 **마지막 자식으로 붙이고**, 닫거나 그리드를 destroy 하면 떼어냄(요소의 기존 자식은 그대로). 선택자는 **차트를 열 때** `document.querySelector` 로 찾고, 없으면 내부 분할로 대체하며 `console.warn`. 열린 채 바꾸면 즉시 이동(같은 요소·같은 문자열이면 no-op, `null` 이면 내부 분할로 복귀). 외부 요소의 크기(높이)는 소비자가 정함 — 패널은 `height:100%` |
+| `valueFields` | 툴바 '카테고리'(값 필드) 후보·초기 선택을 이 **값 필드 id** 로 제한. 모르는 id 는 무시 |
+
+- 제외 목록 공통: 현재 선택이 런타임에 제외되면 남은 첫 후보로 이동. 후보가 전부 제외되면 제외를 **무시**(차트가 비지 않게) + `console.warn`(같은 내용 1회). 후보가 1개뿐이면 그 Select 는 숨김(기존 규칙). 배열은 **내용** 비교 — 매 렌더 새 배열 리터럴이어도 같으면 no-op.
+- `accumulate` 를 쓰면 상위 범주(예 품목)를 골라도 하위 구분(kind)별 값이 셀 단위로 오므로, 범주를 바꾸지 않고 구분별 시리즈를 만들 수 있습니다. 시리즈 이름이 값 필드 header 와 다르면 `decimalFormat` 연동이 적용되지 않아 툴팁이 기본 표시가 됩니다(아래 규칙과 같음).
+- 성능: 내장 차트에는 렌더 상한이 없습니다(레거시 Wijmo 차트의 `ALLOWED_RENDERING_MAX = 500` 열 그룹 상한은 옮기지 않음). `accumulate` 는 리프 행 수 × 값 칸 수만큼 호출되므로 큰 피벗에서는 가볍게 유지하세요.
+
+- 변환 뒤 데이터 기준으로 동작하는 것: Multiple 카테고리 목록, Detail 기본 카테고리 선택, `chartMap`(시리즈 이름 키).
+- 시리즈 이름을 바꾸면 피벗 값 필드 `decimalFormat` 연동(키 = 값 필드 header)이 그 시리즈엔 적용되지 않아 툴팁이 기본 표시(원본 소수 보존 + 천단위)가 됩니다. 소수 자릿수를 유지하려면 값 필드 header 와 같은 시리즈 이름을 쓰세요.
+- 카테고리 이름을 바꾸면 Detail 모드에서 피벗 셀 클릭 → 해당 카테고리 전환이 매칭되지 않아 무시됩니다.
+- 셀 단위 합산(legacy `setChartData({ iterator })`)은 `accumulate` 로 옮깁니다. `transformData` 의 데이터 단위는 현재 선택한 Y축 범주의 결과(상위 범주면 하위 구분별 값은 이미 합산됨)입니다.
+- legacy `MozPivotVue` 의 `formatXAxisLabel`/`setChartData` prop 은 인자 형태가 달라 그대로 옮겨지지 않습니다(`chartConfig` 로 재작성 — 아래 대응표).
+
+**외부 차트 영역(`container`)** — 레거시 `ExtendPivotGrid` 의 `teleportChartTo` 처럼 그리드 아래·옆의 별도 영역에 차트를 그립니다. 그리드는 분할되지 않고 전체 높이를 유지합니다. 외부로 나간 패널은 `.mzc-grid-root` 바깥이라 `--mzc-*` 디자인 토큰을 패널 자체(`.mzc-pivot-chart--external`)에 같은 기본값으로 다시 정의합니다(그리드 root 의 토큰을 덮어쓴 경우 이 클래스에도 같이 지정하세요). 차트 크기는 요소 크기를 따르며(echarts autoresize), 이동 직후 한 번 resize 합니다.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+const chartArea = ref<HTMLElement | null>(null);
+</script>
+<template>
+  <div class="res-alloc-info">
+    <MozGrid :core-config="coreConfig" use-pivot use-chart :chart-config="{ container: chartArea }" />
+    <!-- 템플릿 ref 는 마운트 뒤에 채워지며, 바뀌면 watch 로 전파된다. 선택자 문자열('.res-alloc-info-bottom')도 가능 -->
+    <div ref="chartArea" class="res-alloc-info-bottom" style="height: 320px" />
+  </div>
+</template>
+```
+
+**레거시 → 신규 대응표**
+
+| 레거시(Wijmo `ExtendPivotGrid`/`MozPivotVue`) | 신규 `chartConfig` | 차이 |
+|------|------|------|
+| `setChartData({ iterator })` + `iterator(({ accObj, getValue, rowField }) => …)` | `accumulate(cell, add)` | `rowField`(값 배열) → `cell.rowValues`(필드 id → 값), `getValue(값필드 header)` → `cell.valueField`(id) + `cell.value`(칸마다 1회 호출), `accObj[이름] = (accObj[이름]‖0) + v` → `add(이름, v)`. 레거시 총합계 범주는 값 필드별 총합이었으나 신규는 **범주별 accumulate 결과의 합** |
+| `chartRowFieldsException`(헤더 **표시 문자열**) | `categoryFieldsExclude`(행 필드 **id**) | 번역 문자열 대신 필드 id |
+| `chartColumnFieldsException`(헤더 표시 문자열) | `xAxisFieldsExclude`(열 필드 id) | 레거시는 필터 후 인덱스가 밀리는 문제가 있었으나 신규는 원래 레벨 유지 |
+| `chartValueFields`(차트에 그릴 **시리즈 이름** 목록 — setChartData 와 함께 쓰면 accObj 키) | `accumulate` 를 쓰면 **불필요**(add 한 시리즈가 전부 그려짐). 값 필드 후보 제한은 `valueFields`(값 필드 id) | 그릴 시리즈를 더 거르려면 `accumulate` 에서 add 하지 않거나 `transformData` 로 필터 |
+| `formatXAxisLabel` | `xAxisLabelFormatter` | 같음 |
+| `teleportChartTo`(차트를 Teleport 할 선택자) | `container`(요소 또는 선택자) | 레거시처럼 그리드는 분할하지 않음. 선택자를 못 찾으면 내부 분할로 대체(+warn) |
+
+```ts
+// MrpReport 이식 — 행 필드 [item, kind] / 열 필드 [week] / 값 [category_qty].
+// 범주(Y축)=item 그대로, kind 별로 A/B/C 시리즈 합산. 'mrp_category' 등은 범주·X축 후보에서 제외.
+const KIND_SERIES: Record<string, string> = {
+  'A-used_qty': t('text-A-used_qty'),
+  'B-receipt_qty': t('text-B-receipt_qty'),
+  'C-expected_wip_qty': t('text-C-expected_wip_qty'),
+};
+const chartConfig: PivotChartConfig = {
+  accumulate: (cell, add) => {
+    const name = KIND_SERIES[String(cell.rowValues.kind)];
+    if (name && cell.valueField === 'category_qty') add(name, cell.value);
+  },
+  categoryFieldsExclude: ['mrp_category', 'boh_qty', 'total_receipt_qty', 'total_used_qty', 'eoh_qty'],
+  xAxisFieldsExclude: ['mrp_category'],
+  xAxisLabelFormatter: (label) => (label.startsWith('#') ? label.slice(3) : label),
+};
+```
+
+**런타임 변경** — prop 을 deep `watch` 해 `chrome.setChartConfig` 로 전파합니다(reactive 객체의 제외 목록 배열을 제자리 변경해도 전달). 템플릿 객체 리터럴(`:chart-config="{ transformData, xAxisLabelFormatter }"`)처럼 매 렌더 새 객체가 와도 **함수 identity·제외 목록 내용이 같으면 no-op** 이라 재계산이 없습니다. `accumulate`·제외 목록이 바뀌면 차트를 다시 조회합니다. `<script setup>` 에 선언한 함수는 identity 가 안정적입니다(템플릿 안 인라인 화살표 함수는 매 렌더 바뀌므로 피하세요). `transformData` 교체는 `getSeriesData` 를 다시 부르지 않고 캐시된 원본에 재적용하며, 그리드는 재생성되지 않습니다.
+
+```vue
+<script setup lang="ts">
+import type { PivotChartConfig } from '@vmscloud/moz-ui-grid-wrapper';
+
+// MrpReport 형태 — 행 필드 [item_id, kind] 에서 차트 툴바 'Y축 범주'를 leaf(kind)로 두면
+// 카테고리 이름이 "품목 › 구분" 경로로 온다. 구분별 값을 품목 카테고리의 시리즈로 다시 묶는다.
+const KIND_SERIES: Record<string, string> = {
+  'A-used_qty': '소요량',
+  'B-receipt_qty': '입고 예정량',
+  'C-expected_wip_qty': '예상 재고량',
+};
+
+const transformData: NonNullable<PivotChartConfig['transformData']> = (data, ctx) => {
+  if (ctx.categoryField !== 'kind') return data; // 다른 범주 선택 시 기본 동작
+  const byItem = new Map<string, Map<string, (number | null)[]>>();
+  for (const cat of data.categories) {
+    const parts = cat.name.split(' › ');
+    const seriesName = KIND_SERIES[parts[parts.length - 1]!];
+    if (!seriesName) continue;
+    const item = parts.slice(0, -1).join(' › ');
+    const qty = cat.series.find((s) => s.name === '수량')?.data ?? [];
+    const seriesMap = byItem.get(item) ?? new Map();
+    const acc = seriesMap.get(seriesName) ?? data.xLabels.map(() => 0);
+    qty.forEach((v, i) => { acc[i] = (acc[i] ?? 0) + (v ?? 0); });
+    seriesMap.set(seriesName, acc);
+    byItem.set(item, seriesMap);
+  }
+  return {
+    xLabels: data.xLabels,
+    categories: [...byItem].map(([name, m]) => ({
+      name,
+      series: [...m].map(([sName, d]) => ({ name: sName, data: d })),
+    })),
+  };
+};
+
+// '#01' 같은 정렬용 접두어(3글자) 제거 — 표시만 바뀌고 데이터(xLabels)는 그대로.
+const xAxisLabelFormatter = (label: string) => (label.startsWith('#') ? label.slice(3) : label);
+</script>
+
+<template>
+  <MozGrid
+    v-model:coreConfig="coreConfig"
+    :use-chart="true"
+    :chart-config="{ transformData, xAxisLabelFormatter }"
+  />
+</template>
+```
+
 ### locale
 
 | 속성 | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
-| `locale` | `string` (코드: `'ko'` \| `'en'` \| `'ja'` \| `'zh'` 또는 `'en-US'` 같은 접두형) | `'ko'` | UI 언어 |
+| `locale` | `string` (코드: `'ko'` \| `'en'` \| `'ja'` \| `'zh'` 또는 `'en-US'` 같은 접두형) | `'ko'` | UI 언어(우선순위는 공통 설정 Provider 참조) |
 
 - 허용 코드는 `LocaleCode = 'ko' \| 'en' \| 'ja' \| 'zh'`이며 필드 타입은 `string`이라 접두형(`'en-US'`)도 내부 `normalize()`가 정규화합니다. 미설정 시 `'ko'`.
-- **생성 시 1회만 적용**됩니다(`GridChrome` 생성자에서 모듈 함수 `setLocale(options.locale)` 호출). **런타임 전환 미지원** — 공개 `GridChrome.setLocale` 메서드는 존재하지 않습니다(`WrapperExtras.locale` JSDoc 의 "런타임 변경은 `GridChrome.setLocale` 경유" 표현은 stale). `setUIOptions`도 locale을 처리하지 않습니다.
+- 공개 `GridChrome.setLocale`은 없습니다. `locale` prop/Provider 변경은 어댑터가 추적하여 상태 보존 재생성으로 적용합니다(`ready` 재발화). Excel 팝업·토스트 locale도 watch로 갱신됩니다.
 - `locale`은 `WrapperExtras`와 코어 `PureSheetConfig` 양쪽에 있는 유일한 키입니다(둘 다 `string`). 의도적으로 `WRAPPER_EXTRA_KEYS`에서 제외되어 코어 설정과 `options.locale` 양쪽에 흐릅니다. Vue에서도 `coreConfig` 변경 감지에 folding되어 locale 변경은 reinit을 유발합니다.
 
-> **참고 — `WRAPPER_EXTRA_KEYS`**: 어댑터가 코어 설정을 만들기 전 분리하는 래퍼 전용 키 18개(`height`, `contextMenuConfig`, `emptyState`, `sourceFields`, `useToolBox`, `useToolBoxSetting`, `useExtendFooter`, `useSummaryFooter`, `useSort`, `useCustomCell`, `useContextMenu`, `useBuiltinTooltip`, `usePivot`, `useChart`, `useMultipleChart`, `chartIncludeGrandTotal`, `loading`, `chartMap`). `locale`은 위 사유로 **제외**. (`@vmscloud/moz-ui-grid-wrapper`에서 export)
+> `WRAPPER_EXTRA_KEYS`는 compat 등에서 평탄 props를 분리할 때 사용하는 공용 키 목록입니다. `locale`은 코어·래퍼 양쪽에 필요하므로 제외됩니다. 새 `MozGrid`에는 코어 옵션을 `coreConfig`, 래퍼 옵션을 개별 prop으로 전달하세요.
 
 ---
 
@@ -406,9 +614,9 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 - 핸들러는 인스턴스별이므로 직접 등록은 각 `@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`는 전용 구독).
+`MozGrid`는 아래 이벤트와 `defineModel`의 암시적 `update:coreConfig`를 emit합니다. 인터랙션 이벤트는 `FORWARD_EVENTS`로 포워딩하고 `ready`/`data:loaded`는 별도 배선합니다. React의 `onEndReached`와 달리 Vue는 `scroll:endReached`를 직접 emit하지 않습니다. 필요하면 `@ready`에서 `chrome.on('scroll:endReached', handler)`로 구독하세요.
 
-> **페이로드 형태** — 인터랙션 이벤트 페이로드는 Vue 선언상 `[payload: unknown]`이지만 런타임에는 **코어 이벤트 페이로드**를 그대로 운반합니다. 실제 형태는 [reference.md 이벤트](reference.md#이벤트) 참조.
+> **페이로드 형태** — `data:changed` 외 인터랙션 이벤트 페이로드는 Vue 선언상 `[payload: unknown]`이지만 런타임에는 **코어 이벤트 페이로드**를 그대로 운반합니다. 실제 형태는 [reference.md 이벤트](reference.md#이벤트) 참조.
 
 | 이벤트 | 페이로드 | 설명 |
 |--------|----------|------|
@@ -448,7 +656,7 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 | `contextmenu` | `[payload: unknown]` | 코어 이벤트 포워딩 |
 | `update:coreConfig` | `[value: MozGridCoreProps]` | **암시적**(`defineModel('coreConfig')`). 어댑터가 `coreConfig.value`를 할당할 때마다 발화(내부 변경 역류). → [coreConfig 역류](#coreconfig-역류-updatecoreconfig) |
 
-> 인터랙션 27개(`row:click`~`contextmenu`)는 `FORWARD_EVENTS` 배열로 `c.on(ev, (p) => fwd(ev, p))`로 일괄 배선됩니다(legacy `MozGridVue` `BRIDGED_EVENTS` 1:1). `data:loaded`는 `FORWARD_EVENTS`에 없고 전용 `c.on('data:loaded', …)` 구독으로 별도 배선됩니다.
+> `data:loaded`는 `FORWARD_EVENTS`에 없으며 전용 구독으로 전달됩니다. `data:changed`는 `DataMutationEvent` 타입이며, 다른 인터랙션 이벤트는 주로 `unknown`으로 선언됩니다.
 
 ---
 
@@ -460,7 +668,7 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 
 ### Chrome 네임드 슬롯
 
-7개 chrome 네임드 슬롯(legacy `MozGridVue` passthrough 지점 1:1). 제공된 슬롯만 `SlotRenderer`로 매핑되어 chrome 컨테이너에 마운트됩니다. **`tool-items`만 scoped 슬롯**입니다.
+8개 chrome 네임드 슬롯(legacy `MozGridVue` passthrough 지점 7개 + 보기 설정 메뉴 항목 `option-menu-items`). 제공된 슬롯만 `SlotRenderer`로 매핑되어 chrome 컨테이너에 마운트됩니다. **scoped 슬롯은 `tool-items`와 `option-menu-items`** 두 개입니다.
 
 | 슬롯 | scoped | 설명 |
 |------|--------|------|
@@ -471,6 +679,7 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 | `notification` | — | 툴박스와 본문 사이 알림 영역 |
 | `footer` | — | 커스텀 푸터 영역 |
 | `empty-state` | — | 커스텀 빈 상태 콘텐츠 (legacy `#customState`) |
+| `option-menu-items` | ✅ `{ close, mode }` | 보기 설정(톱니바퀴) 메뉴 Main 화면 끝(마지막 구분선 아래)에 넣는 소비처 항목 (legacy Wijmo `#custom-options`). scoped props = `WrapperOptionMenuItemsProps` |
 
 **`tool-items` scoped props (`WrapperToolItemsProps`)**:
 
@@ -489,6 +698,36 @@ type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
 </template>
 ```
 
+**`option-menu-items` scoped props (`WrapperOptionMenuItemsProps`)**:
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `close` | `() => void` | 보기 설정 메뉴를 **동기로** 닫는다. 직후 `nextTick`에서 다른 팝업을 열어도 메뉴가 다시 열리지 않는다 |
+| `mode` | `'flat' \| 'pivot'` | 플랫 '보기 설정'이면 `'flat'`, 피벗 '보기 설정'이면 `'pivot'` |
+
+- 플랫·피벗 공통. 피벗의 하위 화면(레이아웃/값 필드 설정)에서는 숨겨지고 Main으로 돌아오면 다시 보입니다.
+- 톱니바퀴가 있을 때만 마운트됩니다(`useToolBox`·`useToolBoxSetting`이 true). 슬롯을 주지 않으면 메뉴 DOM은 바뀌지 않습니다.
+- 슬롯 컴포넌트는 **한 번 마운트되어 상주**합니다. 메뉴를 닫았다 열어도 같은 인스턴스(선택 상태 등)가 유지됩니다. 툴박스 재조립(`useToolBox`/`useSort`/`useCustomCell`/`useToolBoxSetting`/`usePivot` 변경) 때는 정리 후 다시 마운트됩니다.
+- 슬롯 안 클릭은 메뉴를 닫지 않습니다. body로 portal되는 드롭다운은 **슬롯 안 트리거가 `aria-controls`/`aria-owns`로 그 목록의 `id`를 가리킬 때만** 안쪽으로 판정합니다(moz-ui-components `MultiSelect`는 해당). 이 연결이 없는 portal을 클릭하면 메뉴가 닫힙니다.
+- 기본 항목과 같은 모양을 원하면 `class="mzc-pvo__item"`을 쓰세요.
+
+```vue
+<!-- PSI: 메뉴를 닫고 다음 tick 에 컬럼 선택 팝업 열기 -->
+<template #option-menu-items="{ close }">
+  <div class="mzc-pvo__item" @click="() => { close(); nextTick(() => { columnPickerVisible = true; }); }">
+    {{ t('text-column_picker') }}
+  </div>
+</template>
+
+<!-- PA: 메뉴 안에서 KPI MultiSelect -->
+<template #option-menu-items>
+  <div class="kpi-setting-container">
+    <span>{{ t('text-kpi_setting') }}</span>
+    <MultiSelect :width="150" :itemsSource="kpiItemSource" v-model="kpiItems" key-prop="value" display-prop="label" :use-select-all="false" />
+  </div>
+</template>
+```
+
 ---
 
 ## 인스턴스 API (ref / defineExpose)
@@ -540,7 +779,7 @@ g.chrome                            // 원시 GridChrome | null (legacy 호환)
 
 ### 공개 메서드
 
-생성자를 제외한 공개 메서드는 정확히 다음 17개입니다(`off` 메서드 없음 — `on`/`onConfigChange`가 반환하는 `Unsubscribe`를 호출하거나 `destroy()`에 일임).
+공개 메서드는 아래 표를 참조하세요(`off` 메서드 없음 — `on`/`onConfigChange`가 반환하는 `Unsubscribe`를 호출하거나 `destroy()`에 일임).
 
 | 메서드 | 시그니처 | 설명 |
 |--------|----------|------|
@@ -558,11 +797,15 @@ g.chrome                            // 원시 GridChrome | null (legacy 호환)
 | `getToolItemsProps` | `getToolItemsProps(): WrapperToolItemsProps` | `tool-items` 슬롯 props `{ disabled, hasItem }` |
 | `setPivotBarVisible` | `setPivotBarVisible(visible: boolean): void` | **피벗 옵션 바 표시/숨김** — 사용자가 런타임에 바꾸는 *상태*이므로 prop(`usePivotBar`)이 아니라 이 메서드가 소유. 초기에 켜 두려면 `@ready` 2번째 인자로 호출 |
 | `isPivotBarVisible` | `isPivotBarVisible(): boolean` | 피벗 옵션 바 표시 상태 조회 |
+| `setToolbarVisible` | `setToolbarVisible(visible: boolean): void` | 툴바 내용 접기/펼치기. 펼치기 토글은 유지. `useToolBox: false`이면 no-op |
+| `isToolbarVisible` | `isToolbarVisible(): boolean` | 툴바 펼침 상태 조회. 툴박스가 없으면 `false` |
 | `setGroupPanelVisible` | `setGroupPanelVisible(visible: boolean): void` | 그룹 패널 표시/숨김 |
 | `getViewOptions` | `getViewOptions(): WrapperViewOptions` | 뷰 상태 `{ toolbarVisible, footerVisible, groupPanelVisible }` |
 | `destroy` | `destroy(): void` | chrome 인스턴스/구독/슬롯 호스트/코어 그리드/루트 DOM 모두 해제. 멱등(`disposed` 가드) |
 
-> `hosts`는 메서드가 아니라 `get hosts()` 게터(`Readonly<Omit<ChromeShell, 'root'>>` 반환)라 위 17개에 포함되지 않습니다.
+> 초기 접기는 `@ready="(_grid, chrome) => chrome.setToolbarVisible(false)"`로 설정합니다. 기본은 펼침입니다. 접기는 하단 슬롯·그룹 패널·피벗 바를 일시 숨기지만 펼치기 토글은 남깁니다. 동일 값 재설정은 중복 통지하지 않으며, 다른 UI 플래그에 따른 툴바 재조립은 현재 상태를 유지합니다. `useToolBox: false`는 툴박스 제거이며 setter는 no-op입니다. 제거 후 다시 생성하면 기본 펼침 상태이며, GridChrome 전체 재생성 시에는 각 `ready`에서 초기 접기를 다시 적용하세요.
+
+> `hosts`는 메서드가 아니라 `get hosts()` 게터(`Readonly<Omit<ChromeShell, 'root'>>` 반환)라 위 메서드 표에 포함되지 않습니다.
 
 > 어댑터의 양방향 바인딩 4중주: `reconcileCoreConfig`(props → core), `getCoreConfig`(core → `update:coreConfig`), `onConfigChange`(내부 변경 구독), `syncAppliedConfig`(에코 억제). reinit 쌍: `captureReinitState`/`restoreReinitState`(`reconcileCoreConfig`가 `{ reinitRequired: true }` 반환 시 구동).
 
@@ -594,7 +837,7 @@ import { ref, watch } from 'vue';
 import { MozGrid } from '@vmscloud/moz-ui-grid-vue';
 import type { MozGridCoreProps } from '@vmscloud/moz-ui-grid-vue';
 
-const coreConfig = ref<MozGridCoreProps>({ mode: 'pivot', /* ... */ });
+const coreConfig = ref<MozGridCoreProps>({ mode: 'pivot', enableReferCache: true, rowFields: [], columnFields: [], valueFields: [], data: [] });
 
 // 사용자가 피벗 패널에서 필드를 옮기면 coreConfig.value 의 피벗 키가 자동 역류됨
 watch(coreConfig, (cfg) => {
@@ -619,14 +862,15 @@ watch(coreConfig, (cfg) => {
 
 | 컴포넌트 | props | default 슬롯 scoped props |
 |----------|-------|---------------------------|
-| `CellTemplate` | `{ field: string (필수) }` | `CellSlotProps = { value: unknown; rowData: Record<string,unknown>; columnId: string; rowId?: string\|number }` |
+| `CellTemplate` | `{ field: string (필수) }` | `CellSlotProps = { value: unknown; rowData: Record<string,unknown>; columnId: string; rowId?: string\|number }` — `rowId`는 업무 행 ID(`grid.rows.getById`로 해석, `cell:click`의 `rowId`와 같음, 그룹행엔 없음). 행 헤더(`_rowHeader`)는 템플릿 대상이 아니며 `rowHeader.cellRenderer`(+그룹행 `includeGroupRows: true`)에 코어 렌더러 함수를 직접 넘깁니다(→ 코어 [RowHeaderConfig](reference.md#rowheaderconfig)) |
 | `HeaderTemplate` | `{ field: string (필수) }` | `HeaderSlotProps = { columnId: string; header: string }` |
 | `CellEditor` | `{ field: string (필수) }` | `EditorSlotProps = { value: unknown; rowData: Record<string,unknown>; columnId: string; onCommit: (newValue: unknown) => void; onCancel: () => void }` |
 | `DetailTemplate` | `{ minHeight?: number=100; maxHeight?: number; singleExpand?: boolean=false; keepDetailRows?: boolean=true }` | `DetailSlotProps = { parentData: Record<string,unknown>; dataIndex: number }` |
 | `GroupTemplate` | (없음) | `GroupSlotProps = { groupKey: string; groupValue: unknown; level: number; count: number; isExpanded: boolean }` |
 
 - `DetailTemplate`: 마운트 시 `grid.masterDetail.setConfig`로 props 매핑(`keepDetailRows` → 코어 `keepMasterDetailRows`), 디테일 행마다 `detail:${dataIndex}` 키로 슬롯 렌더. 언마운트 시 `renderer.unmountByPrefix('detail:')`.
-- `GroupTemplate`: `_groupTemplate` 이름의 `formatRow` 핸들러를 등록하여 group-header 행에 `group:${ctx.viewIndex}` 키로 슬롯 마운트. 언마운트 시 `unmountByPrefix('group:')` 후 `formatRow.removeHandler('_groupTemplate')`.
+- `GroupTemplate`: `_groupTemplate` 이름(래퍼 예약 키)의 `formatRow` 핸들러를 등록한다. 코어는 이 핸들러에만 그룹행 대신 **보이는 그룹 배너 안의 호스트**(`span.ps-group-label.ps-group-template-host`)를 `ctx.element`로 넘기므로, 슬롯이 배너의 라벨·건수·집계 자리를 대체한다(펼침/접힘 토글 버튼은 코어가 유지, 배너 본문 클릭은 그룹 토글 — `rowGroupConfig.selectable: true`면 본문 클릭은 그룹 선택이고 토글은 ▾ 버튼만). 슬롯 요소의 이벤트(툴팁 등)는 슬롯이 그대로 받는다. 배너가 생기지 않는 컬럼 구성(가운데 컬럼이 모두 `unmergeOnGroupRow`)에서는 예전처럼 그룹행 요소에 마운트된다.
+  - 호스트별로 인스턴스 1개(`renderer.mountInstance`)를 유지하고, 접기/펼치기·건수 변화는 props 갱신으로 반영한다. 배너가 스크롤/그룹 해제/데이터 갱신으로 사라지면 코어가 호스트에 보내는 내부 이벤트로 인스턴스를 정리한다. 그리드 준비 전에 마운트돼도 그리드 인스턴스가 준비되면 등록되고, 언마운트 시 `formatRow.removeHandler('_groupTemplate')` 후 남은 인스턴스를 정리한다.
 
 ```vue
 <MozGrid v-model:coreConfig="coreConfig">
@@ -642,8 +886,8 @@ watch(coreConfig, (cfg) => {
     <OrderDetail :order="parentData" />
   </DetailTemplate>
 
-  <GroupTemplate #default="{ groupValue, count, isExpanded }">
-    {{ groupValue }} ({{ count }}) {{ isExpanded ? '▼' : '▶' }}
+  <GroupTemplate #default="{ groupValue, count }">
+    <strong>{{ groupValue }}</strong> ({{ count }})
   </GroupTemplate>
 </MozGrid>
 ```
@@ -656,9 +900,38 @@ watch(coreConfig, (cfg) => {
 
 > `useGridPreset`은 **패키지 export 표면이 아닙니다**(`src/index.ts`/`legacy`에서 재-export 안 됨). `MozGrid`가 내부에서만 소비합니다. 소비처는 `MozGrid` + `name` prop + 호스트의 `'user-layout-module'` 제공으로 그 동작을 암묵적으로 얻습니다.
 
-사용자 레이아웃 프리셋을 저장/복원합니다. `exportDef`(= `grid.getConfig()` + `customCellConfig`(`getCustomCellState() ?? null`) + `columnFormatConfig`(`getColumnFormatState() ?? null`))와 `importDef`(async; `grid.applyConfig()`; preset이 null이면 캡처된 default 스냅샷 적용 + customCell/columnFormat 복원)로 `UserLayoutInstance`를 구성하고, `useUserLayoutModule().register`로 등록합니다. 등록은 `options.gridInstance` watch 안에서 **그리드 인스턴스 존재 + `options.name.value` 비어있지 않음** 조건의 첫 `data:loaded`에서, `layoutInstance.setDefaultToCurrent()` 후 `nextTick`에서 수행됩니다(Wijmo ExtendFlexGrid 패턴 — 동적 컬럼까지 default 스냅샷에 포착). 호스트가 모듈을 제공하지 않으면 register는 no-op.
+사용자 레이아웃 프리셋을 저장/복원합니다. 등록은 `options.gridInstance` watch 안에서 **그리드 인스턴스 존재 + `options.name.value` 비어있지 않음** 조건의 첫 `data:loaded`에서, `layoutInstance.setDefaultToCurrent()` 후 `nextTick`에서 수행됩니다(Wijmo ExtendFlexGrid 패턴 — 동적 컬럼까지 default 스냅샷에 포착). 호스트가 모듈을 제공하지 않으면 register는 no-op.
+
+**exportDef 저장 항목**
+
+| 키 | 출처 | 소유 | 복원 |
+|---|---|---|---|
+| `version` | `stampPresetVersion` — 최소 `'0.5'` | wrapper | 빠진 항목 정책 판정 |
+| `current` (모드·컬럼 너비/고정/숨김/순서/집계·정렬·필터·행 그룹·트리/디테일·피벗 축·테마·`summaryRow` 등) | `grid.getConfig()` | core | `grid.applyConfig(config, { missing })` |
+| `current` 의 UI 옵션(`rowHeight`·`headerHeight`·`editable`·`tooltipMode`·`alternatingRows`·`showHeader`·`showStatusBar`·선택 모드 등) | `grid.getConfig()` | core(앱 선언값) | **core applyConfig 가 복원하지 않음**(F02, core 범위). `showStatusBar` 는 wrapper 가 항상 false 강제(자체 Footer) |
+| `snapshot` | `grid.getConfig()` | core | 컬럼 reset baseline |
+| `customCellConfig` | `getCustomCellState() ?? null` | wrapper | `setCustomCellState` |
+| `columnFormatConfig` | `getColumnFormatState() ?? null` | wrapper | `setColumnFormatState` |
+| `viewOptionsConfig` | `getViewOptionsState()` = `GridChrome.getPresetViewState()` (툴바 펼침·푸터·그룹 패널·피벗 바) | wrapper | `setViewOptionsState` = `GridChrome.setPresetViewState` |
+
+`height`·`useToolBox` 등 `WrapperExtras` props 는 화면(앱) 선언이라 저장하지 않습니다. 차트 선택 상태(범주/값 필드·표시)도 저장하지 않습니다.
+
+**importDef** 는 wrapper `migrateGridPreset(preset ?? layoutInstance.default, { grid, getSourceFields, baseline: layoutInstance.default })` 하나로 전처리하고(필드 카탈로그 수집·Wijmo 변환·extras 결정·`missing` 판정 — `moz-ui-grid-wrapper/src/config/presetMigration.ts`), 결과를 적용만 합니다: `applyPresetCoreConfig(grid, config, missing)` → `columnFormat` → `customCell` → 보기 상태.
+
+| 저장본 | 빠진 항목 (`missing`) | extras: 값 | extras: `null` | extras: 키 없음 |
+|---|---|---|---|---|
+| `version >= 0.5` (현재 exportDef) | `'reset'` — 기본값/baseline 으로 초기화 | 교체 | 빈 상태 | 기본 보기 캡처값으로 초기화 |
+| `version <= 0.4`, 버전 없음, 초기 envelope | `'keep'` — 현재 상태 유지 | 교체 | 빈 상태 | 유지 |
+| Wijmo 변환본 | `'keep'` | customCell = 변환 결과(없으면 빈 규칙) | — | columnFormat 은 빈 상태, 보기 상태 유지 |
+| 기본 보기(`importDef(null)`) | `'reset'` | 캡처값 | 빈 상태 | 빈 상태. 기본값 자체가 없으면 core 미적용 + extras 비움 |
+
+`missing` 은 core `applyConfig(config, { missing })` 계약으로 전달합니다(옵션 객체는 `toCoreApplyOptions` 한 곳에서 생성). 이 옵션을 모르는 이전 core 는 무시하므로 core 상태의 snapshot 초기화는 core 지원 후에 동작합니다.
+
+연속 호출은 **마지막 요청 우선**입니다: 요청은 직렬로 실행되고(core 적용이 겹치지 않음), 차례가 왔을 때 더 새 요청이 있으면 건너뜁니다. 실패(변환 오류·core 오류)는 reject 하지 않고 `console.error('[Grid preset] import failed', error)` 로 알립니다 — 변환 오류는 적용 전에 거절되어 상태가 바뀌지 않습니다. `UserLayoutInstance` 의 `setApplied(true)` 타이밍은 바뀌지 않습니다(완료 전 표시).
+
+`UseGridPresetOptions`: `usePreset?: boolean`(기본 `true`, 호출 시 `false`면 인스턴스 생성·watch·등록·복원 없이 즉시 반환), `name: Ref<string>`(필수), `type: 'mozFlatGrid' | 'mozPivotGrid'`(필수), `gridInstance: Ref<PureSheet | null>`(필수), `getCustomCellState`/`setCustomCellState`/`getColumnFormatState`/`setColumnFormatState`/`getViewOptionsState`/`setViewOptionsState`(선택 — setter 의 `null` = 빈 상태), `getSourceFields`/`onImportDiagnostics`(내부 호환성 옵션). `MozGrid` 의 `getSourceFields` 는 피벗 카탈로그의 `field` 를 선언 `fields` 의 실제 `id` 로 되찾아 넘깁니다(id≠field 그리드).
 
-`UseGridPresetOptions`: `name: Ref<string>`(필수), `type: 'mozFlatGrid' | 'mozPivotGrid'`(필수), `gridInstance: Ref<PureSheet | null>`(필수), `getCustomCellState`/`setCustomCellState`/`getColumnFormatState`/`setColumnFormatState`(선택).
+Wijmo `columnLayout`/`viewDefinition` 저장본은 import callback에서 검증·변환한 후 `applyConfig`에 전달합니다. 지원 매핑, 진단, 명시적 미지원 범위와 재현 테스트는 [Wijmo preset compatibility](wijmo-preset-compatibility.md)를 참조하세요. 기존 core 문제나 비동기 public setter 완료 보장은 이 변환기의 범위가 아닙니다.
 
 ### Notification Contract
 
@@ -700,7 +973,7 @@ provideGridNotification(myNotificationStore); // GridNotificationContract 구현
 
 ## compat 래퍼 (MozGridVue / MozPivotVue)
 
-> ⛔ **DEPRECATED.** `MozGridVue`/`MozPivotVue`(compat)는 레거시 컴포넌트의 정확한 공개 표면(props/emits/slots/defineExpose)을 보존하는 **얇은 하위 호환 어댑터**입니다. 신규 코드는 `MozGrid`(피벗은 `mode="pivot"`)를 사용하세요. 두 컴포넌트는 `src/compat/` 에 있으며 옛 `legacy` 배럴은 0.2.0 에서 제거되었습니다.
+> ⛔ **DEPRECATED.** `MozGridVue`/`MozPivotVue`(compat)는 레거시 컴포넌트의 정확한 공개 표면(props/emits/slots/defineExpose)을 보존하는 **얇은 하위 호환 어댑터**입니다. 신규 코드는 `MozGrid`(피벗은 `coreConfig.mode: 'pivot'`)를 사용하세요. 두 컴포넌트는 `src/compat/` 에 있으며 옛 `legacy` 배럴은 0.2.0 에서 제거되었습니다.
 
 두 compat 파일은 그리드 로직을 소유하지 않고 `<MozGrid>`를 얇게 감쌉니다. props를 `coreConfig` computed(WRAPPER_EXTRA_KEYS + name + locale 분리)와 `wrapperConfig` computed(WRAPPER_EXTRA_KEYS + locale만)로 분리하여 `coreConfig` + `v-bind="wrapperConfig"` + `:name`을 `MozGrid`에 바인딩합니다.
 
@@ -715,7 +988,7 @@ provideGridNotification(myNotificationStore); // GridNotificationContract 구현
 
 ## 추가 익스포트 (엑셀·locale·타입·Injection 키)
 
-0.2.0 에서 옛 `legacy` 배럴(pre-`MozGrid` Vue 컴포넌트 21종, `useGrid*` composable 17종, 아이콘 20종)을 **제거**했습니다. 같은 기능은 `MozGrid` 가 GridChrome(`@vmscloud/moz-ui-grid-wrapper`)으로 제공합니다. 아래는 패키지 엔트리(`src/index.ts`)가 `MozGrid`·템플릿·compat·계약 외에 추가로 내보내는 표면입니다. 패키지 엔트리는 코어 CSS(`default.css`)를 side-effect 로 import 합니다.
+0.2.0 에서 옛 `legacy` 배럴(pre-`MozGrid` Vue 컴포넌트 21종, `useGrid*` composable 17종, 아이콘 20종)을 **제거**했습니다. 같은 기능은 `MozGrid` 가 GridChrome(`@vmscloud/moz-ui-grid-wrapper`)으로 제공합니다. 아래는 패키지 엔트리(`src/index.ts`)가 `MozGrid`·템플릿·compat·계약 외에 추가로 내보내는 표면입니다. 패키지 엔트리는 wrapper 통합 CSS(코어 + 셸)를 side-effect로 import합니다.
 
 | 분류 | 익스포트 |
 |------|----------|
@@ -727,7 +1000,7 @@ provideGridNotification(myNotificationStore); // GridNotificationContract 구현
 | Bridge | `VueRenderer`, `UndoStack`, `getRowHeaderCell`, `getCornerCell`, `ROW_HEADER_COLUMN_ID` |
 | 타입 | `MozGridVueCoreProps`, `MozGridVueProps`, `MozGridVueEmits`, `CellSlotProps`, `HeaderSlotProps`, `EditorSlotProps`, `DetailSlotProps`, `GroupSlotProps`, `TemplateRegistry`, `TemplateEntry`, `ComparisonOperator`, `LogicalOperator`, `IFilterDef`, `ISortDef`, `ICustomCellDef`, `ICustomCellRuleSet`, `ICustomCellConfig`, `IContextMenuItem`, `IContextMenuConfig`, `IContextMenuExcelEventArgs`, `AggregateType`, `IAggregateValues`, `IColumnCellFormat`, `IColumnHeaderFormat`, `IColumnFormatConfig`, `PivotGridProps`, `PivotFieldItem`, `AvailableField`, `PivotFieldPanelConfig`, `PivotGridSettings`, `UseGridFilterReturn`, `UseGridSortReturn`, `UseGridCustomCellReturn`(모듈 계약 — 옛 useGrid* 반환 타입을 독립 인터페이스로 유지), `GridModuleContract` |
 | Injection 키 (7/8) | `GRID_INSTANCE_KEY`, `GRID_RENDERER_KEY`, `GRID_TEMPLATE_REGISTRY_KEY`, `GRID_FILTER_MODULE_KEY`, `GRID_SORT_MODULE_KEY`, `GRID_CUSTOM_CELL_MODULE_KEY`, `GRID_BULK_EDITOR_MODULE_KEY` (`GRID_CONTAINER_KEY` 제외). 필터·정렬·조건부 스타일 키의 값 타입은 각각 `UseGridFilterReturn`/`UseGridSortReturn`/`UseGridCustomCellReturn`, 일괄 편집 키는 `GridModuleContract`(호스트 임의 모듈) |
-| 코어 타입 재-export | `PureSheetConfig`, `FieldDef`, `SortState`, `FilterState`, `Row`, `ColumnDef`, `GroupConfig`, `TreeConfig`, `MasterDetailConfig`, `PivotConfig`, `PivotRowField`, `PivotColumnField`, `PivotValueField`, `PivotResult`, `IPivotAPI`, `IRowsAPI` 외 다수(편의 패스스루), `FormatHeaderRowCallback`/`FormatHeaderRowContext`(구명 alias) → 의미는 [reference.md](reference.md) |
+| 코어 타입 재-export | `PureSheetConfig`, `FieldDef`, `SortState`, `FilterState`, `Row`, `ColumnDef`, `RowGroupConfig`, `TreeConfig`, `MasterDetailConfig`, `PivotConfig`, `PivotRowField`, `PivotColumnField`, `PivotValueField`, `PivotResult`, `IPivotAPI`, `IRowsAPI` 외 다수(편의 패스스루), `FormatHeaderRowCallback`/`FormatHeaderRowContext`(구명 alias) → 의미는 [reference.md](reference.md) |
 
 > Injection 키 8종은 모두 `Symbol('moz-grid-…')`(번들 로컬, `Symbol.for` 아님)로 생성됩니다. `MozGrid`는 그중 4개(`GRID_INSTANCE_KEY`/`GRID_RENDERER_KEY`/`GRID_TEMPLATE_REGISTRY_KEY`/`GRID_CONTAINER_KEY`)를 provide합니다.