@vmscloud/moz-ui-grid-react 0.1.19

package/docs/manual/reference_react.md

@@ -0,0 +1,720 @@
+# MozGrid React 레퍼런스 (Props · 이벤트 · Slot · 인스턴스 API)
+
+> 패키지: `@vmscloud/moz-ui-grid-react`
+> 마지막 업데이트: 2026-06-24
+
+> 📋 이 문서는 **React 래퍼 표면만** 다룹니다. 그리드 본체(코어) 설정·타입·이벤트 페이로드는 [reference.md](reference.md)를 참조하세요.
+> 📋 사용 예제 코드는 [examples.md](examples.md)를 참조하세요.
+
+## 목차
+
+- [개요](#개요)
+- [설치](#설치)
+- [빠른 시작](#빠른-시작)
+  - [타입 재노출](#타입-재노출)
+- [Props](#props)
+  - [coreConfig (controlled core 설정)](#coreconfig-controlled-core-설정)
+  - [WrapperExtras (래퍼 전용 옵션)](#wrapperextras-래퍼-전용-옵션)
+  - [템플릿 맵 (cellTemplates / headerTemplates / editorTemplates)](#템플릿-맵-celltemplates--headertemplates--editortemplates)
+- [이벤트 콜백 props](#이벤트-콜백-props)
+- [Slot props (ReactNode)](#slot-props-reactnode)
+- [인스턴스 API (MozGridHandle ref)](#인스턴스-api-mozgridhandle-ref)
+- [coreConfig 역류 (onCoreConfigChange)](#coreconfig-역류-oncoreconfigchange)
+- [Vue와의 비대칭 (주의)](#vue와의-비대칭-주의)
+- [템플릿 컴포넌트 props 타입](#템플릿-컴포넌트-props-타입)
+- [부가 타입 레퍼런스](#부가-타입-레퍼런스)
+  - [IContextMenuConfig (contextMenuConfig)](#icontextmenuconfig-contextmenuconfig)
+  - [EmptyStateConfig (emptyState)](#emptystateconfig-emptystate)
+  - [PivotSourceField (sourceFields)](#pivotsourcefield-sourcefields)
+  - [chartMap / ChartSeriesConfig](#chartmap--chartseriesconfig)
+  - [locale](#locale)
+- [Legacy exports](#legacy-exports)
+- [관련 문서](#관련-문서)
+
+---
+
+## 개요
+
+`@vmscloud/moz-ui-grid-react`는 moz-ui-grid의 **React 래퍼**입니다.
+
+> **아키텍처**: `MozGrid`는 프레임워크 비의존 vanilla `GridChrome`(`@vmscloud/moz-ui-grid-wrapper`) 위에 올린 **얇은 React 어댑터**입니다. 그리드 동작·UI 셸(툴박스/푸터/패널/컨텍스트 메뉴)은 모두 GridChrome이 소유하고, 이 컴포넌트는 props → GridChrome 옵션/코어 설정 변환과 React 렌더링 통합(템플릿·슬롯·ref)만 담당합니다.
+
+- 본체 그리드(데이터 로드, 정렬, 필터, 피벗, 선택 등)는 **코어 PureSheet**가 담당합니다 — 코어 API는 [reference.md](reference.md)를 참조하세요.
+- `coreConfig` prop은 코어 설정(`PureSheetConfig`)을 평탄화한 객체이며, 본 문서에서는 필드별 상세를 다루지 않고 **[reference.md](reference.md)로 위임**합니다.
+- 본 문서는 **래퍼 표면**(래퍼 전용 옵션, 템플릿, 슬롯, 이벤트 콜백, 인스턴스 핸들)만 문서화합니다.
+
+패키지 진입점(`src/index.ts`)은 `MozGrid` 관련 3개의 신규 심볼과, `./legacy`의 전체 재노출(비파괴)로 구성됩니다.
+
+```ts
+export { MozGrid, type MozGridProps, type MozGridHandle } from './MozGrid';
+export * from './legacy';
+```
+
+> ⚠️ `MozGridCoreProps` / `WrapperExtras` 같은 래퍼 타입은 **이 패키지에서 재노출되지 않습니다.** 필요하면 `@vmscloud/moz-ui-grid-wrapper`에서 직접 import 하세요(아래 코드 참조).
+
+---
+
+## 설치
+
+```bash
+pnpm add @vmscloud/moz-ui-grid-react react react-dom
+```
+
+패키지는 npmjs에 공개로 게시됩니다. 레지스트리 매핑이나 토큰 없이 설치되며,
+예전에 `.npmrc`에 넣어 둔 `@vmscloud:registry=https://npm.pkg.github.com` 매핑은 제거하세요.
+
+### peerDependencies
+
+| 패키지 | 버전 | 필수 |
+|--------|------|------|
+| `react` | `>=18.2.0` | ✅ 필수 |
+| `react-dom` | `>=18.2.0` | ✅ 필수 |
+| `dayjs` | `>=1.11.0` | 선택 (optional) |
+| `file-saver` | `>=2.0.0` | 선택 (optional) |
+
+### CSS import
+
+전체 그리드 스타일(코어 + 셸)은 **래퍼 패키지의 스타일시트**를 import 합니다(React는 래퍼를 externalize).
+
+```ts
+import '@vmscloud/moz-ui-grid-wrapper/style.css';
+```
+
+> ⚠️ 코어 그리드 본체 스타일(`.ps-*` 클래스)은 **래퍼 패키지의 `style.css`에만** 포함됩니다 — 새 `MozGrid`는 바닐라 `GridChrome`을 마운트하고 호스트 스타일은 inline이라, **위 한 줄이면 충분**합니다(래퍼는 react 패키지의 런타임 의존성).
+>
+> 참고: `@vmscloud/moz-ui-grid-react/style.css` 서브패스도 존재하지만 이는 주로 **legacy React 컴포넌트**(radix 기반)용입니다. 새 `MozGrid`만 쓴다면 import하지 않아도 됩니다.
+
+### 모듈 포맷
+
+- ESM-first (`type: module`), 듀얼 ESM/CJS 빌드 (`module=dist/index.js`, `main=dist/index.cjs`, `types=dist/index.d.ts`).
+- exports map: `.`(types/import/require), `./style.css`, `./package.json`.
+
+---
+
+## 빠른 시작
+
+```tsx
+import { useRef, useState } from 'react';
+import { MozGrid, type MozGridHandle } from '@vmscloud/moz-ui-grid-react';
+// onReady 인자 타입은 react 패키지가 재노출한다 — 소비처가 wrapper/core 를 직접
+// 의존하지 않아도 핸들러를 타입 지정할 수 있다(ITSM-2026-002154).
+import type { GridChrome, PureSheet } from '@vmscloud/moz-ui-grid-react';
+// MozGridCoreProps 는 래퍼 패키지에서 가져온다 (react 패키지는 재노출하지 않음).
+import type { MozGridCoreProps } from '@vmscloud/moz-ui-grid-wrapper';
+import '@vmscloud/moz-ui-grid-wrapper/style.css';
+
+function Example() {
+  const gridRef = useRef<MozGridHandle>(null);
+
+  // coreConfig는 controlled — 내부 변경(피벗/그룹/옵션 모달)이 onCoreConfigChange로 역류한다
+  const [coreConfig, setCoreConfig] = useState<MozGridCoreProps>({
+    mode: 'flat',
+    fields: [
+      // id = 컬럼 식별자(가리킬 때), field = 원본 데이터 키(읽을 때, 생략 시 id).
+      { id: 'name', header: '이름', dataType: 'string', width: 200 },
+      { id: 'age', header: '나이', dataType: 'number', width: 100, showFilterIcon: false },
+    ],
+    data: [
+      { id: 1, name: '홍길동', age: 30 },
+      { id: 2, name: '김철수', age: 25 },
+    ],
+  });
+
+  return (
+    <MozGrid
+      ref={gridRef}
+      height={480}
+      locale="ko"
+      coreConfig={coreConfig}
+      onCoreConfigChange={setCoreConfig}
+      useToolBox
+      useContextMenu
+      onReady={(grid: PureSheet, chrome: GridChrome) => {
+        // grid === 코어 PureSheet (reference.md), chrome === wrapper GridChrome
+        chrome.setPivotBarVisible(true);   // 피벗 옵션 바를 처음부터 켜 두기
+      }}
+      onRowClick={(payload) => console.log('row:click', payload)}
+      onHeaderFilterClick={(payload) => console.log('필터 아이콘 클릭', payload)}
+    />
+  );
+}
+```
+
+### 타입 재노출
+
+React 패키지는 소비처가 wrapper/core 를 직접 의존하지 않아도 `onReady` 핸들러를 타입 지정할 수 있도록 아래 타입을 재노출합니다 (ITSM-2026-002154).
+
+| 타입 | 원 출처 | 용도 |
+|------|---------|------|
+| `GridChrome` | `@vmscloud/moz-ui-grid-wrapper` | `onReady` 2번째 인자 · `ref.current` 표면 |
+| `PureSheet` | `@vmscloud/moz-ui-grid-core` | `onReady` 1번째 인자 · `ref.current.grid` |
+
+> 재노출하지 않으면 소비처가 `onReady` 를 `any` 로 받게 되고, 그러면 **크롬 API 변경이 소비처에 전혀 드러나지 않습니다**. `MozGridCoreProps`/`WrapperExtras` 는 여전히 래퍼 패키지에서 가져옵니다(Vue 패키지는 `MozGridCoreProps` 도 재노출 — 두 어댑터의 비대칭).
+
+`MozGrid`는 `forwardRef<MozGridHandle, MozGridProps>`로 선언되며, 단일 호스트 `div`(`className="moz-grid-chrome"`)를 렌더링합니다. 호스트 높이는 `height` prop으로만 결정됩니다(`width: 100%`, `overflow: hidden` 고정).
+
+---
+
+## Props
+
+`MozGridProps`는 다음 묶음의 교집합입니다.
+
+```ts
+type MozGridProps = WrapperExtras & {
+  coreConfig?: MozGridCoreProps;
+  onCoreConfigChange?: (next: MozGridCoreProps) => void;
+  cellTemplates?: Record<string, ComponentType<CellSlotProps>>;
+  headerTemplates?: Record<string, ComponentType<HeaderSlotProps>>;
+  editorTemplates?: Record<string, ComponentType<EditorSlotProps>>;
+  // 7개 ReactNode 슬롯 props + 34개 on* 이벤트 콜백 props (아래 표 참조)
+};
+```
+
+`MozGridProps`만 react 패키지에서 export 되며, 교집합의 좌변인 `WrapperExtras`·`MozGridCoreProps` 는 `@vmscloud/moz-ui-grid-wrapper` 에서 가져옵니다.
+
+### coreConfig (controlled core 설정)
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `coreConfig` | `MozGridCoreProps` | `undefined` (내부적으로 `?? {}`) | 코어 그리드 설정을 평탄화한 단일 객체. **controlled / 양방향** — 그리드 내부 변경(피벗 패널, 옵션 모달의 값필드 형식, 그룹 변경)이 `onCoreConfigChange`로 역류합니다. `data`/`fields`/`pivot`/`group`/`theme` 등 모든 flat·pivot 키를 담습니다. |
+| `onCoreConfigChange` | `(next: MozGridCoreProps) => void` | `undefined` | 코어 설정의 내부 변경이 발생할 때 호출되는 역류 콜백. controlled `coreConfig`를 가능하게 합니다. 자세한 내용은 [coreConfig 역류](#coreconfig-역류-oncoreconfigchange) 참조. |
+
+`MozGridCoreProps`는 코어 `PureSheetConfig`(= `FlatModeConfig | PivotModeConfig` 판별 유니온)를 단일 객체로 **평탄화**한 타입입니다. (`@vmscloud/moz-ui-grid-wrapper` 에 정의 — react 패키지는 재노출하지 않으므로 직접 타이핑이 필요하면 래퍼에서 import.)
+
+```ts
+type MozGridCoreProps =
+  & Partial<Omit<FlatModeConfig, 'mode'>>
+  & Partial<Omit<PivotModeConfig, 'mode'>>
+  & { mode?: 'flat' | 'pivot' };
+```
+
+- 모든 flat·pivot 키가 optional로 노출되지만 정확한 타입은 보존됩니다.
+- **필드별 상세(data / fields / pivot / group / theme / treeConfig / masterDetailConfig / dragDropConfig 등)는 코어 문서가 정본입니다 → [reference.md의 Config](reference.md#config-설정) 참조.**
+- 어댑터 특이사항:
+  - 셀/헤더/에디터 React 템플릿은 `coreConfig.fields`에 병합됩니다(아래 [템플릿 맵](#템플릿-맵-celltemplates--headertemplates--editortemplates) 참조). 이 병합은 **raw `fields` 참조가 변경될 때만** 수행됩니다(불필요한 `updateFields` 방지).
+  - `locale`(래퍼 prop)은 생성 시점에 코어 설정에도 접혀 들어갑니다(코어 PureSheet 생성 시 필요).
+
+### WrapperExtras (래퍼 전용 옵션)
+
+`WrapperExtras`는 그리드가 런타임에 변경하지 않는 **래퍼 전용 입력**으로, `coreConfig`에 흡수되지 않고 **개별(uncontrolled) props**로 전달됩니다. `WrapperExtras`는 `WrapperUIOptions`(12개 UI 플래그)를 상속합니다.
+
+> 미설정 UI 플래그는 React가 `undefined`로 전달하며, 래퍼 `resolveUIOptions`가 `DEFAULT_UI_OPTIONS`를 적용합니다(Vue와 달리 React는 미설정 boolean을 `false`로 강제 변환하지 않음 — 그래서 Vue 의 `withDefaults` 같은 복원이 필요 없습니다).
+
+#### UI 플래그 (WrapperUIOptions 상속)
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `useToolBox` | `boolean` | `true` | 툴박스 표시 |
+| `useToolBoxSetting` | `boolean` | `true` | 툴박스 설정(기어) 버튼 표시 |
+| `useExtendFooter` | `boolean` | `true` | 확장 푸터 표시 |
+| `useSummaryFooter` | `boolean` | `false` | 푸터 집계(요약) 표시 |
+| `useSort` | `boolean` | `true` | 정렬 기능 활성화 |
+| `useCustomCell` | `boolean` | `true` | 조건부 서식(커스텀 셀) 활성화 |
+| `useContextMenu` | `boolean` | `true` | 컨텍스트 메뉴 활성화 |
+| `useBuiltinTooltip` | `boolean` | `true` | 내장 셀/헤더 툴팁 렌더러 사용. `false`면 wrapper가 툴팁을 그리지 않음 — 코어 `cell:tooltip` 이벤트는 그대로 발행되므로 소비처가 `onReady`의 `grid.on('cell:tooltip', …)`로 직접 렌더 가능(발행은 `tooltipMode`로 제어) |
+| `usePivot` | `boolean` | `false` | 피벗 패널 버튼 표시 |
+| `usePivotBar` | `boolean` | `true` | **피벗 옵션 바(툴박스 아래 행/열/값 한 줄) 사용 여부** — 피벗 모드 전용 (ITSM-2026-002154). 아래 주석 참조 |
+| `useChart` | `boolean` | `false` | 피벗 차트 버튼 표시 (피벗 모드 전용). 생성 시에만 전달되며 **런타임 변경 경로 없음** |
+| `loading` | `boolean` | `false` | 로딩 오버레이 강제 표시(호스트 비동기 상태). `false`라도 내부 비동기 작업(`activity !== 'idle'` 이며 검색 아님) 중에는 스피너가 자동 표시됨 |
+
+> **`usePivotBar` — "지금 보이는가"가 아니라 "이 화면에서 바를 쓰는가" (ITSM-2026-002154)**
+> 표시/숨김은 사용자가 런타임에 바꾸는 **상태**이므로 prop 이 아니라 `GridChrome.setPivotBarVisible()` 이 소유합니다. 초기에 켜 두려면 `onReady` 의 2번째 인자로 오는 chrome 에서 호출하세요:
+> ```tsx
+> <MozGrid usePivotBar onReady={(grid, chrome) => chrome.setPivotBarVisible(true)} />
+> ```
+>
+> 🚨 **`false` 는 바를 숨기는 것이 아니라 피벗의 정렬·필터 진입점을 함께 제거합니다:** 피벗은 헤더 클릭으로 정렬하지 않고(헤더 클릭이 바를 켜서 정렬 지점을 안내), 피벗 헤더에는 필터 아이콘이 없어 값 목록 필터의 앵커가 바 아이템의 아이콘뿐입니다. 그래서 기본값이 `true` 이며 `false` 는 "피벗을 읽기 전용 표로만 쓴다"는 선언에 가깝습니다.
+
+#### 래퍼 추가 옵션
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `height` | `string \| number` | `'100%'` | 호스트 컨테이너 높이. `number`→`${h}px`, `string`→그대로. **어댑터 스타일 전용** — 코어/셸 옵션에 전달되지 않음 |
+| `locale` | `string` | `'ko'` | UI 언어. `'ko' \| 'en' \| 'ja' \| 'zh'` 또는 접두 형식(`'en-US'` 등). **생성 시 1회만 적용 — 런타임 전환 미지원**. 코어 설정과 래퍼 옵션 양쪽에 전달됨. [locale](#locale) 참조 |
+| `sourceFields` | `PivotSourceField[]` | `undefined` | 피벗 배치 후보 필드 카탈로그(래퍼 전용, 코어 미전달). [PivotSourceField](#pivotsourcefield-sourcefields) 참조 |
+| `contextMenuConfig` | `IContextMenuConfig` | `undefined` | 컨텍스트 메뉴 설정(빌트인 항목 토글 + customMenu 커스텀 항목). [IContextMenuConfig](#icontextmenuconfig-contextmenuconfig) 참조 |
+| `emptyState` | `EmptyStateConfig` | `undefined` (미설정 시 i18n 기본 적용) | 빈 상태 오버레이 설정. `empty-state` 슬롯과 조합 가능. [EmptyStateConfig](#emptystateconfig-emptystate) 참조 |
+| `useMultipleChart` | `boolean` | `true` | 피벗 차트: Multiple(행별 미니 차트) 모드 |
+| `chartIncludeGrandTotal` | `boolean` | `false` | 피벗 차트: 총합(Grand Total) 카테고리 포함 |
+| `chartMap` | `Record<string, ChartSeriesConfig>` | `undefined` | 피벗 차트: 시리즈별 type/color 설정. [chartMap](#chartmap--chartseriesconfig) 참조 |
+
+> `WrapperExtras`에는 `detail`/디테일-템플릿 키가 **없습니다**(코어/래퍼 어디에도 해당 필드 없음).
+> UI 플래그는 생성 시 `buildChromeOptions`로, 런타임 변경 시 `setUIOptions`로 GridChrome에 전달됩니다(`setUIOptions` 가 처리하는 플래그는 useToolBox·useToolBoxSetting·useExtendFooter·useSummaryFooter·useSort·useCustomCell·useContextMenu·useBuiltinTooltip·usePivot·**usePivotBar**·loading 11종). `useChart`/`sourceFields`/`useMultipleChart`/`chartIncludeGrandTotal`/`chartMap`/`emptyState` 는 런타임 변경 경로 없음 — 생성 시에만 적용.
+>
+> ⚠️ **`contextMenuConfig` 는 이제 런타임 전파됩니다** (ITSM-2026-002154). 이전에는 생성 시 스냅샷만 남아, 소비자가 `customMenu`/`exportFileName` 을 비동기로 확정하는 경우(메뉴 이름 lookup 응답 후 등) 그대로 유실됐습니다. 어댑터가 전용 `useEffect` 로 `chrome.setContextMenuConfig(props.contextMenuConfig)` 를 호출합니다.
+
+### 템플릿 맵 (cellTemplates / headerTemplates / editorTemplates)
+
+`fieldId → React 컴포넌트` 매핑 3종으로, React 컴포넌트를 코어 `FieldDef`의 렌더 콜백으로 변환합니다. 키는 `fieldId` 문자열, 값은 타입별 props를 받는 `ComponentType`입니다.
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `cellTemplates` | `Record<string, ComponentType<CellSlotProps>>` | `undefined` (`{}` 취급) | `fieldId → 셀 렌더 컴포넌트`. `type:'cell'`로 등록 후 `buildFieldDefs`로 적용 |
+| `headerTemplates` | `Record<string, ComponentType<HeaderSlotProps>>` | `undefined` (`{}` 취급) | `fieldId → 헤더 렌더 컴포넌트`. `type:'header'` |
+| `editorTemplates` | `Record<string, ComponentType<EditorSlotProps>>` | `undefined` (`{}` 취급) | `fieldId → 에디터 컴포넌트`(`onCommit`/`onCancel` 콜백). `type:'editor'` |
+
+내부적으로 어댑터는 매번 새 `templateRegistry`(`createTemplateRegistry`)를 만들어 각 엔트리를 `{ type, fieldId, component }`로 등록하고 `buildFieldDefs(rawFields, registry, renderer)`를 실행합니다. 이 변환은 **raw `fields` 참조가 변경될 때만** 수행됩니다(메모이즈). 템플릿 컴포넌트가 받는 props 타입은 [템플릿 컴포넌트 props 타입](#템플릿-컴포넌트-props-타입)을 참조하세요.
+
+```tsx
+function StatusCell({ value, rowData, columnId, rowId }: CellSlotProps) {
+  return <span className={`badge badge-${value}`}>{String(value)}</span>;
+}
+
+<MozGrid
+  coreConfig={coreConfig}
+  cellTemplates={{ status: StatusCell }}
+/>;
+```
+
+---
+
+## 이벤트 콜백 props
+
+모든 상호작용 콜백은 `on*` props입니다. `onReady`/`onDataLoaded`를 제외한 **32개**는 코어 PureSheet 이벤트를 `EVENT_CALLBACKS` 표를 통해 `chrome.on(event, ...)`으로 일반 포워딩합니다(총 **34개 이벤트 콜백** props). `onDataLoaded` 는 `chrome.on('data:loaded', …)` 로 별도 배선되고, `onReady` 는 어댑터가 직접 호출합니다.
+
+> **페이로드 형태는 모두 코어 이벤트 페이로드입니다 — [reference.md 이벤트](reference.md#이벤트) 참조.** props 시그니처상 `(payload: unknown) => void`로 노출되지만 실제 페이로드는 해당 코어 이벤트의 형태를 따릅니다.
+
+| 콜백 prop | 시그니처 | 대응 코어 이벤트 | 설명 |
+|-----------|----------|------------------|------|
+| `onReady` | `(grid: PureSheet, chrome: GridChrome) => void` | — (직접 호출) | `chrome.ready()` 완료(및 reinit 상태 복원) 후. 1번째 인자는 코어 `PureSheet`, **2번째 인자는 wrapper 크롬**(ITSM-2026-002154). reinit 마다 다시 호출되므로 여러 번 받을 수 있음 |
+| `onDataLoaded` | `() => void` | `data:loaded` | 데이터 로드 완료(페이로드 없음) |
+| `onRowClick` | `(payload: unknown) => void` | `row:click` | 행 클릭 |
+| `onRowDblclick` | `(payload: unknown) => void` | `row:dblclick` | 행 더블클릭 |
+| `onRowPinned` | `(payload: unknown) => void` | `row:pinned` | 행 고정 |
+| `onRowUnpinned` | `(payload: unknown) => void` | `row:unpinned` | 행 고정 해제 |
+| `onRowReordered` | `(payload: unknown) => void` | `row:reordered` | 행 순서 변경 |
+| `onCellClick` | `(payload: unknown) => void` | `cell:click` | 셀 클릭 |
+| `onCellDblclick` | `(payload: unknown) => void` | `cell:dblclick` | 셀 더블클릭 |
+| `onCellChange` | `(payload: unknown) => void` | `cell:change` | 셀 값 변경 |
+| `onCellBeforeEdit` | `(payload: unknown) => void` | `cell:beforeEdit` | 셀 편집 시작 전 |
+| `onCellEditCommitting` | `(payload: unknown) => void` | `cell:editCommitting` | 셀 편집 커밋 중 |
+| `onCellEditCommitted` | `(payload: unknown) => void` | `cell:editCommitted` | 셀 편집 커밋 완료 |
+| `onCellTooltip` | `(payload: unknown) => void` | `cell:tooltip` | 셀 툴팁 |
+| `onSelectionChanged` | `(payload: unknown) => void` | `selection:changed` | 선택 변경 |
+| `onColumnResize` | `(payload: unknown) => void` | `column:resize` | 컬럼 리사이즈 |
+| `onColumnReorder` | `(payload: unknown) => void` | `column:reorder` | 컬럼 순서 변경 |
+| `onColumnPin` | `(payload: unknown) => void` | `column:pin` | 컬럼 고정 |
+| `onColumnVisibility` | `(payload: unknown) => void` | `column:visibility` | 컬럼 표시/숨김 |
+| `onSortChanged` | `(payload: unknown) => void` | `sort:changed` | 정렬 변경 |
+| `onHeaderClick` | `(payload: unknown) => void` | `header:click` | 헤더 **셀 본체** 클릭 |
+| `onHeaderSortClick` | `(payload: unknown) => void` | `header:sortClick` | 헤더 **정렬 아이콘** 클릭 (ITSM-2026-002185). 페이로드에 앵커용 `element` 포함 |
+| `onHeaderFilterClick` | `(payload: unknown) => void` | `header:filterClick` | 헤더 **필터 아이콘** 클릭 (ITSM-2026-002185). 페이로드에 앵커용 `element` 포함. 필드에 `showFilterIcon: false` 면 아이콘 DOM 자체가 없어 **발생하지 않음** |
+| `onFilterChanged` | `(payload: unknown) => void` | `filter:changed` | 필터 변경 |
+| `onScroll` | `(payload: ScrollPayload) => void` | `scroll` | 스크롤 range 변경 |
+| `onEndReached` | `(payload: ScrollEndReachedPayload) => void` | `scroll:endReached` | 끝/near-end 도달(경계별 1회) |
+| `onUndoStateChange` | `(payload: unknown) => void` | `undo:stateChange` | Undo/Redo 상태 변경 |
+| `onClipboardCopy` | `(payload: unknown) => void` | `clipboard:copy` | 클립보드 복사 |
+| `onClipboardPaste` | `(payload: unknown) => void` | `clipboard:paste` | 클립보드 붙여넣기 |
+| `onValidationChanged` | `(payload: unknown) => void` | `validation:changed` | 검증 상태 변경 |
+| `onColumnGroupToggle` | `(payload: unknown) => void` | `columnGroup:toggle` | 컬럼 그룹 토글 (구 `onHeaderGroupToggle`/`headerGroup:toggle`) |
+| `onGroupToggle` | `(payload: unknown) => void` | `rowGroup:toggle` | 단일 로우 그룹 토글 (헤더 클릭 `source:'user'` / 프로그래매틱 `source:'api'`) |
+| `onGroupBatchToggle` | `(payload: unknown) => void` | `rowGroup:batchToggle` | 여러 그룹 일괄 토글. `scope`로 구분 — `'level'`(같은 depth 일괄, Ctrl/Cmd+클릭 또는 `expandAtLevel`/`collapseAtLevel`), `'toLevel'`(특정 depth까지 누적, `expandToLevel`/`collapseToLevel`), `'all'`(전체, `expandAll`/`collapseAll`). 영향 그룹 전체를 1회로 요약 통지 |
+| `onContextMenu` | `(payload: unknown) => void` | `contextmenu` | 컨텍스트 메뉴 |
+
+> 콜백은 `propsRef.current`를 통해 항상 최신 핸들러로 호출되므로, 콜백 props가 매 렌더마다 새로 생성되어도 재구독이 발생하지 않습니다.
+
+---
+
+## Slot props (ReactNode)
+
+React에는 명명 슬롯이 없으므로, GridChrome의 7개 셸 슬롯 지점을 **`ReactNode` props**로 노출합니다(Vue 명명 슬롯과 1:1). 각 슬롯은 코어 DOM 컨테이너 안에 React 컴포넌트를 마운트하고 언마운트 정리 함수를 반환합니다.
+
+| 슬롯 prop | 타입 | 대응 슬롯명 | 설명 |
+|-----------|------|-------------|------|
+| `toolLeft` | `ReactNode` | `tool-left` | 툴박스 좌측 영역 |
+| `toolItems` | `ReactNode \| ((props: WrapperToolItemsProps) => ReactNode)` | `tool-items` | 툴박스 우측 커스텀 항목. 정적 노드 **또는** `{ disabled, hasItem }`를 받는 **render-prop**. tool-items props 변경 시 구독을 통해 재렌더 |
+| `toolBottom` | `ReactNode` | `tool-bottom` | 툴박스 하단(그룹 패널 영역) |
+| `optionPopup` | `ReactNode` | `option-popup` | 설정 모달 |
+| `notification` | `ReactNode` | `notification` | 툴바와 본문 사이 영역. **수동 영역일 뿐, React에는 뒤에 동작하는 excel/notification contract 없음**([Vue와의 비대칭](#vue와의-비대칭-주의) 참조) |
+| `footer` | `ReactNode` | `footer` | 푸터 커스텀 영역 |
+| `emptyStateContent` | `ReactNode` | `empty-state` | 빈 상태 customState 영역(Vue `#empty-state`) |
+
+`tool-items` 슬롯은 Vue scoped slot과 동일하게 동적 props를 받는 **render-prop**을 지원합니다.
+
+```tsx
+interface WrapperToolItemsProps {
+  disabled: boolean; // 표시 가능한 행이 0일 때 (그리드 비활성)
+  hasItem: boolean;  // 적용된 항목(필터 등)이 있을 때
+}
+
+<MozGrid
+  coreConfig={coreConfig}
+  toolLeft={<button onClick={refresh}>새로고침</button>}
+  toolItems={({ disabled, hasItem }) => (
+    <button disabled={disabled}>{hasItem ? '필터 해제' : '내보내기'}</button>
+  )}
+  emptyStateContent={<div>데이터가 없습니다.</div>}
+/>;
+```
+
+---
+
+## 인스턴스 API (MozGridHandle ref)
+
+`ref`로 전달받는 핸들은 **GridChrome 표면 전체**입니다. core `PureSheet`는 `ref.current.grid`로 노출되므로, displayed 좌표계 API도 `ref.current?.grid.getDisplayedData()` / `.getDisplayedRowIds()`(배열), `ref.current?.grid.rows.displayedCount()` / `.getByDisplayedIndex(i)` / `.getDisplayedIndexById(id)`(traversal 인덱싱)로 바로 호출합니다. 자세한 계약은 core 레퍼런스(reference.md)를 참조하세요.
+
+```ts
+type MozGridHandle = GridChrome & { chrome: GridChrome | null };
+```
+
+`useImperativeHandle`은 **Proxy**(한 번만 생성)를 반환합니다. get 트랩이 매 접근마다 `chromeRef.current`를 읽으므로, Tier-C 상태보존 재초기화로 GridChrome 인스턴스가 재생성되어도 자연스럽게 반영됩니다. 모든 함수 멤버는 chrome 인스턴스에 자동 바인딩됩니다(`this` 사용 메서드 대응). 리터럴 키 `chrome`은 raw 현재 인스턴스(또는 마운트 전 `null`)를 반환합니다.
+
+따라서 `ref.current.grid` / `.filter` / `.sort` / `.pivot` / `.chart` / `.setUIOptions(...)` / `.on(...)` 등이 직접 동작하며, back-compat용 `ref.current.chrome`도 사용 가능합니다.
+
+### 주요 public 메서드
+
+| 메서드 | 시그니처 | 설명 |
+|--------|----------|------|
+| `ready` | `async ready(): Promise<void>` | 코어 `waitForReady` 대기 후 데이터 로드 표시, 카운트/푸터/빈상태 갱신. 생성 직후 1회 호출(어댑터가 자동 호출) |
+| `on` | `on(event, handler): Unsubscribe` | 코어 PureSheet 이벤트 구독 + 구독 추적(destroy 시 자동 정리). 반환된 `Unsubscribe`로 해제 |
+| `reconcileCoreConfig` | `reconcileCoreConfig(next): { reinitRequired: boolean }` | 변경된 코어 설정 키만 타겟 세터로 적용. 세터 없는 키 변경 시 `{ reinitRequired: true }` 반환(상태보존 재초기화 필요) |
+| `getCoreConfig` | `getCoreConfig(base?): PureSheetConfig` | 현재 코어 설정을 입력(PureSheetConfig) 형태로 반환(`update:coreConfig` 역류용). `fields`/`data` 참조 보존, sorts/filters view-state 미포함 |
+| `onConfigChange` | `onConfigChange(cb): Unsubscribe` | 내부 코어 변경(pivotConfig + groupConfig.columns) 구독 → 어댑터가 역류. UI 옵션/차트/커스텀셀은 미포함 |
+| `syncAppliedConfig` | `syncAppliedConfig(next): void` | reconcile 기준선(appliedConfig)을 강제 동기화 — 직후 prop-back reconcile을 no-op으로 만들어 중복 피벗 재계산 방지 |
+| `setSourceFields` | `setSourceFields(sources?): void` | 피벗 배치 후보 카탈로그 런타임 갱신(`sourceFields`는 reconcile을 거치지 않으므로 직접 호출) |
+| `setContextMenuConfig` | `setContextMenuConfig(config?): void` | **컨텍스트 메뉴 설정 런타임 갱신** (ITSM-2026-002154). `sourceFields` 와 같은 래퍼 전용 키라 reconcile 우회 — 어댑터가 전용 `useEffect` 로 호출하므로 `customMenu` 를 비동기로 확정해도 유실되지 않음 |
+| `setUIOptions` | `setUIOptions(partial): void` | 래퍼 UI 플래그 런타임 변경 — PureSheet는 건드리지 않고 영향받는 셸(툴박스/푸터/컨텍스트 메뉴/피벗 바/로딩)만 부분 재구성 |
+| `captureReinitState` | `captureReinitState(): GridChromeReinitState` | 재초기화 스냅샷(코어 getConfig + 래퍼 전용 customCell + columnFormat) 캡처 |
+| `restoreReinitState` | `async restoreReinitState(state): Promise<void>` | 새 인스턴스에서 스냅샷 복원(코어 → columnFormat → customCell 순). 절대 reject 하지 않음(부분 복원 허용) |
+| `getToolItemsProps` | `getToolItemsProps(): WrapperToolItemsProps` | tool-items 슬롯의 동적 props `{ disabled, hasItem }` |
+| `setPivotBarVisible` | `setPivotBarVisible(visible: boolean): void` | **피벗 옵션 바 표시/숨김** — 표시 여부는 prop(`usePivotBar`)이 아니라 이 메서드가 소유. 초기에 켜 두려면 `onReady` 2번째 인자로 호출 |
+| `isPivotBarVisible` | `isPivotBarVisible(): boolean` | 피벗 옵션 바 표시 상태 조회 |
+| `setGroupPanelVisible` | `setGroupPanelVisible(visible: boolean): void` | 그룹 패널 표시/숨김 |
+| `getViewOptions` | `getViewOptions(): WrapperViewOptions` | 뷰 상태 `{ toolbarVisible, footerVisible, groupPanelVisible }` |
+| `destroy` | `destroy(): void` | 모든 셸/컨트롤러/구독/슬롯/코어 그리드 해제 및 root DOM 제거(멱등). 어댑터가 unmount 시 자동 호출 |
+
+> ⚠️ `usePivotBar` 를 `setUIOptions` 로 껐다 다시 켜면 `PivotBar` 가 새로 생성되므로 **표시 상태는 기본값(숨김)으로 돌아갑니다.** 표시 여부의 소유자는 `setPivotBarVisible` 이므로, 켠 뒤 보이게 하려면 소비처가 그 메서드를 다시 호출해야 합니다.
+
+> GridChrome에는 public `off` 메서드가 **없습니다**. `on`/`onConfigChange`가 반환한 `Unsubscribe`를 호출하거나, `destroy()`가 추적된 모든 구독을 정리합니다.
+
+### 주요 public 컨트롤러/필드
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `grid` | `PureSheet` | **코어 본체 그리드.** `loadData`/`updateFields`/`select`/`on`/`columns`/`rows`/`filter`/`sort`/`group`/`tree`/`masterDetail`/`dragDrop`/`pivot`/`getConfig`/`applyConfig`/`waitForReady`/`destroy` 등 — **전체 API는 [reference.md](reference.md) 참조** |
+| `slots` | `SlotHost` | 슬롯 호스트 레지스트리 |
+| `ui` | `Required<WrapperUIOptions>` | 현재 적용된 UI 옵션(직접 수정 금지, `setUIOptions` 사용) |
+| `filter` | `FilterController` | 필터 UI 상태/로직 |
+| `sort` | `SortController` | 정렬 UI 상태/로직 |
+| `customCell` | `CustomCellController` | 조건부 서식(커스텀 셀) |
+| `bulkEditor` | `BulkEditorController` | 일괄 편집 |
+| `columnSettings` | `ColumnSettingsController` | 컬럼 표시/순서 설정 |
+| `group` | `GroupController` | 그룹화 |
+| `excel` | `ExcelController` | Excel/CSV import/export |
+| `pivot` | `PivotController` | 피벗 필드 패널 |
+| `search` | `SearchController` | 검색(키워드 + 하이라이트) |
+| `columnFormat` | `ColumnFormatController` | 컬럼 단위 셀/헤더 서식(조건부 서식의 base 레이어) |
+| `contextMenu` | `ContextMenuController` | 컨텍스트 메뉴 |
+| `chart` | `ChartController \| null` | 피벗 차트 — **피벗 모드에서만 non-null**(flat 모드는 `null`이므로 null 체크 필요) |
+| `hosts` | `Readonly<Omit<ChromeShell, 'root'>>` (getter) | 내부 DOM 호스트 요소 읽기 전용 접근자 |
+
+```tsx
+const gridRef = useRef<MozGridHandle>(null);
+
+// 코어 본체 직접 조작
+gridRef.current?.grid.rows.deleteSelectedRows();
+
+// 래퍼 컨트롤러
+gridRef.current?.filter.clearFilter();
+gridRef.current?.chart?.setVisible(true); // null 체크
+
+// 이벤트 구독 (반환 Unsubscribe로 해제)
+const off = gridRef.current?.on('cell:change', (p) => console.log(p));
+```
+
+> `.grid`는 코어 PureSheet이므로 본 문서에서 메서드를 나열하지 않습니다. **[reference.md](reference.md)** 를 참조하세요.
+
+---
+
+## coreConfig 역류 (onCoreConfigChange)
+
+`coreConfig`는 controlled 양방향 prop입니다. 그리드 내부에서 발생하는 코어 설정 변경(피벗 패널 조작, 옵션 모달의 값필드 형식, 그룹 변경)은 `onCoreConfigChange`로 역류하여 단방향 prop-clobber 버그를 제거합니다.
+
+역류 배선:
+
+1. 어댑터가 `chrome.onConfigChange(...)`로 내부 변경(pivotConfig + groupConfig.columns)을 구독합니다.
+2. 변경 시 `onCoreConfigChange(chrome.getCoreConfig(base))`를 호출합니다.
+3. `getCoreConfig`는 라이브 런타임 설정(mode, group, pivot 키)만 base에 오버레이하고 `fields`/`data` 참조는 보존하며, sorts/filters 같은 view-state는 포함하지 않습니다.
+
+```tsx
+// MozGridCoreProps 는 @vmscloud/moz-ui-grid-wrapper 에서 import.
+const [coreConfig, setCoreConfig] = useState<MozGridCoreProps>({ mode: 'flat', fields, data });
+
+<MozGrid
+  coreConfig={coreConfig}
+  onCoreConfigChange={setCoreConfig} // 피벗/그룹 변경이 상태로 역류
+/>;
+```
+
+> 역류 대상은 `pivotConfig`와 `groupConfig.columns`입니다. UI 옵션/차트/커스텀셀 변경은 `onConfigChange`에 포함되지 않습니다.
+
+---
+
+## Vue와의 비대칭 (주의)
+
+React 어댑터는 Vue 어댑터와 다음 표면이 **다릅니다**. 마이그레이션 시 유의하세요.
+
+| 항목 | Vue | React |
+|------|-----|-------|
+| **Excel 라이프사이클(excelHooks)** | `excelHooks`를 완전 배선 — export start/progress/complete/error/cancel, import complete/error를 notification store에 자동 push | **미배선.** `buildChromeOptions`가 `excelHooks` 없이 옵션을 구성하며, `ExcelLifecycleHooks`를 import하지 않음(능력은 GridChromeOptions에 존재하나 React가 미사용) |
+| **notification store contract** | `provideGridNotification` / `useGridNotificationStore`로 host 주입 store를 읽어 excel 토스트 자동화 | `notification`은 **수동 ReactNode 슬롯**일 뿐. `MozGrid.tsx`에 `useGridNotificationStore` import 없음(legacy contract 파일은 존재하나 새 컴포넌트가 사용 안 함) |
+| **userLayout contract** | 제공 | **미제공** |
+| **useGridPreset (프리셋/레이아웃 직렬화 훅)** | 제공 | **미제공** |
+
+**실무적 결론**: React에서는 Excel import/export 진행/오류 토스트가 host notification store로 자동 push되지 **않습니다**. 필요 시 `notification` ReactNode 슬롯 + 인스턴스 핸들/이벤트로 직접 배선해야 합니다. Vue에서는 notification store만 제공하면 excel 라이프사이클 토스트가 자동화됩니다.
+
+> 참고: React에서 host-주입 가능한 contract는 **notification contract**(legacy)뿐이며, 이는 `MozGrid` 신규 컴포넌트가 아니라 [Legacy exports](#legacy-exports)의 일부입니다. locale은 contract가 아니라 Context(`MozConfigProvider`/`useMozLocale`)로 제공됩니다.
+
+---
+
+## 템플릿 컴포넌트 props 타입
+
+[템플릿 맵](#템플릿-맵-celltemplates--headertemplates--editortemplates)에 등록한 컴포넌트가 React props로 받는 타입입니다(`src/types/slots.ts`). 이 타입들은 `./legacy`를 통해 패키지 루트에서도 재노출됩니다.
+
+### CellSlotProps
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `value` | `unknown` | 셀 값 |
+| `rowData` | `Record<string, unknown>` | 행 데이터 |
+| `columnId` | `string` | 컬럼 ID |
+| `rowId` | `string \| number` (optional) | 행 ID |
+
+### HeaderSlotProps
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `columnId` | `string` | 컬럼 ID |
+| `header` | `string` | 헤더 텍스트 |
+
+### EditorSlotProps
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `value` | `unknown` | 현재 값 |
+| `rowData` | `Record<string, unknown>` | 행 데이터 |
+| `columnId` | `string` | 컬럼 ID |
+| `onCommit` | `(newValue: unknown) => void` | 편집 커밋 콜백 |
+| `onCancel` | `() => void` | 편집 취소 콜백 |
+
+### DetailSlotProps / GroupSlotProps (참고)
+
+`MozGrid`에는 detail/group 템플릿 **맵 prop이 없습니다**. 두 타입은 타입으로 재노출되며, legacy 흐름에서 레지스트리 `type:'detail'`/`type:'group'`로 사용됩니다.
+
+| 타입 | 필드 |
+|------|------|
+| `DetailSlotProps` | `{ parentData: Record<string, unknown>; dataIndex: number }` |
+| `GroupSlotProps` | `{ groupKey: string; groupValue: unknown; level: number; count: number; isExpanded: boolean }` |
+
+### 레지스트리 타입 (고급)
+
+| 타입 | 설명 |
+|------|------|
+| `TemplateEntry` | `{ type: 'cell'\|'header'\|'editor'\|'detail'\|'group'; fieldId?: string; component?: ComponentType<any>; props?: Record<string, unknown> }` |
+| `TemplateRegistry` | `register(entry)` / `unregister(type, fieldId?)` / `get(type, fieldId?)` / `getAll(type)`. **비반응형** — register/unregister 후 PureSheet 재빌드 필요(그리드 `fields` prop 참조 변경 시 자동) |
+
+브릿지 유틸(고급 용도, legacy 재노출): `ReactRenderer`(+`ContextWrapper` 타입), `createTemplateRegistry`, `buildFieldDefs`.
+
+---
+
+## 부가 타입 레퍼런스
+
+### IContextMenuConfig (contextMenuConfig)
+
+컨텍스트 메뉴 빌트인 항목 토글 + excel 콜백 + customMenu 커스텀 항목. 모든 필드 optional.
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `useViewSelectColumn` | `boolean?` | 컬럼 표시 선택 항목 토글 |
+| `useFixedColumn` | `boolean?` | 컬럼 고정 항목 |
+| `useGroupColumn` | `boolean?` | 컬럼 그룹화 항목 |
+| `useContextMenu` | `boolean?` | 컨텍스트 메뉴 마스터 토글 (`WrapperUIOptions.useContextMenu`와는 별개) |
+| `useSort` | `boolean?` | 정렬 항목 |
+| `useFilter` | `boolean?` | 필터 항목 |
+| `useCustomCell` | `boolean?` | 조건부 서식 항목 |
+| `useBulkEditColumn` | `boolean?` | 컬럼 일괄 편집 항목 |
+| `useDataCopy` | `boolean?` | 데이터 복사 항목 |
+| `useDataWithHeaderCopy` | `boolean?` | 헤더 포함 복사 항목 |
+| `useAutoSizeColumns` | `boolean?` | 컬럼 자동 크기 항목 |
+| `useExportCsv` | `boolean?` | CSV 내보내기 항목 |
+| `useRowPinning` | `boolean?` | 행 고정 항목 |
+| `useExportImport` | `boolean?` | 내보내기/가져오기 그룹 |
+| `useExportExcel` | `boolean?` | Excel 내보내기 항목 |
+| `onImportExcel` | `(ctx: IContextMenuExcelEventArgs) => void` | Excel 가져오기 콜백. `IContextMenuExcelEventArgs = { grid: unknown; field?: unknown }` |
+| `onImportExcelAppend` | `(ctx: IContextMenuExcelEventArgs) => void` | Excel 가져오기(append) 콜백 |
+| `onExportOriginalData` | `(format: 'excel' \| 'csv') => void` | 원본(집계 전) 데이터 내보내기 콜백 |
+| `useClientExcelImport` | `boolean?` | 클라이언트 Excel 가져오기 활성화 |
+| `useClientExcelExport` | `boolean?` | 클라이언트 Excel 내보내기 활성화 |
+| `useExportOriginal` | `boolean?` | 원본(집계 전) XLSX 내보내기 — 피벗/그룹/병합 무시, 코어 source 행 내보내기 (`saveExcelToFile({ exportSource: true })`). 피벗 모드에서 raw 데이터가 필요할 때 |
+| `clientImportOptions` | `Record<string, unknown>?` | 클라이언트 가져오기 옵션 |
+| `clientExportOptions` | `Record<string, unknown>?` | 클라이언트 내보내기 옵션 |
+| `exportFileName` | `string?` | 내보내기 파일명의 base. 실제 제안명은 `${base}_${YYYYMMDD}.xlsx`(원본 export는 `${base}_source_${YYYYMMDD}.xlsx`, CSV는 `.csv`), 미지정 시 `'export'` |
+| `onClientImportComplete` | `(result: unknown) => void` | 클라이언트 가져오기 완료 콜백 |
+| `onClientExportComplete` | `(result: SaveExcelToFileResult) => void` | 클라이언트 내보내기 완료 콜백(FSA 스트리밍/폴백 다운로드 결과) |
+| `customMenu` | `IContextMenuItem[]` | 커스텀 메뉴 항목 |
+
+`IContextMenuItem = { id: string; label: string; icon?: string; disabled?: boolean; separator?: boolean; children?: IContextMenuItem[]; handler?: () => void; order?: number (기본 50); aggregate?: { header: string; aggLabel: string; value: string }; compact?: boolean }`
+
+### EmptyStateConfig (emptyState)
+
+빈 상태 오버레이 설정(legacy `MozGridVue emptyState` prop 1:1). 미설정 시 i18n 기본 텍스트/이미지가 자동 적용됩니다. 모든 필드 optional.
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `isCustomState` | `boolean?` | 커스텀 빈 상태 강제(custom_empty 이미지) |
+| `headerMsg` | `string?` | 헤더 텍스트 override(미설정 시 뷰 타입별 i18n 기본) |
+| `contentMsg` | `string?` | 내용 텍스트 override(`unsafeHTML`로 렌더, 미설정 시 i18n 기본) |
+| `useImg` | `boolean?` | 빈 상태 이미지 표시(내부 기본 `true`) |
+| `selectImg` | `EmptyStateImg?` | 명시적 이미지 선택. `'Custom' \| 'Result' \| 'Data' \| 'Search'`. 총/필터 행 수가 0일 때 자동 뷰 타입을 override |
+
+> `empty-state` 슬롯(`emptyStateContent` prop)으로 customState 영역을 주입할 수 있습니다.
+
+### PivotSourceField (sourceFields)
+
+피벗 배치 후보 카탈로그 요소(래퍼 SSOT — 코어는 후보 풀을 노출하지 않음).
+
+```ts
+type PivotSourceField = PivotRowField & PivotColumnField & PivotValueField;
+```
+
+세 코어 피벗 필드 타입의 **교집합**이므로 모든 row/column/value 필드 속성(`field`, `header`, `dataType`, `aggregate`, `formula`, `showValueAs`, `headerAttributes`, `cellAttributes`, `width` 등)을 선언할 수 있습니다. 풀의 필드를 row/col/value로 드래그하면 선언된 속성이 `PivotConfig`로 전달됩니다.
+
+> 세 component 타입(`PivotRowField`/`PivotColumnField`/`PivotValueField`)의 **필드별 상세는 코어 문서가 정본입니다 → [reference.md의 피벗 필드 타입](reference.md#피벗-필드-타입) 참조.**
+> `PivotSourceField` 타입은 **이 react 패키지에서 재노출되지 않습니다.** 직접 타이핑이 필요하면 `@vmscloud/moz-ui-grid-wrapper` 에서 import 하세요(래퍼 main index 가 `controllers` 배럴을 통해 export). 대부분의 소비처는 `sourceFields`/`chartMap` props 의 요소/값 타입으로 추론되므로 별도 import 없이 사용 가능합니다.
+
+런타임 갱신: 인스턴스 핸들의 `setSourceFields(sources)` 사용.
+
+### chartMap / ChartSeriesConfig
+
+피벗 차트의 시리즈 키 → 설정 매핑(legacy `MozPivotVue chartMap` 1:1).
+
+```ts
+type chartMap = Record<string, ChartSeriesConfig>;
+interface ChartSeriesConfig {
+  type?: 'bar' | 'line' | 'lineSymbols' | 'area';
+  color?: string;
+}
+```
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `type` | `'bar' \| 'line' \| 'lineSymbols' \| 'area'` (optional) | 시리즈별 차트 타입 |
+| `color` | `string?` | 시리즈별 색상(미설정 시 팔레트 기본) |
+
+> `ChartSeriesConfig`/`ChartType`은 **래퍼 main index에서는 재노출되지 않으며**(차트 유틸 모듈 내부에 정의) `chartMap`의 값 타입으로만 도달 가능합니다. 단, react 패키지의 **legacy 배럴에서는 두 타입을 모두 재노출**합니다(`export { type ChartType, type ChartSeriesConfig } from '.../chartUtils'`).
+
+### locale
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `locale` | `string` (`'ko' \| 'en' \| 'ja' \| 'zh'` 또는 `'en-US'` 같은 접두 형식) | `'ko'` | UI 언어 |
+
+- **생성 시 1회만 적용 — 런타임 전환 미지원.** public `GridChrome.setLocale` 메서드는 존재하지 않습니다(`setLocale`은 내부 i18n 모듈 함수로 GridChrome 생성자에서만 호출). `setUIOptions`도 locale을 처리하지 않습니다. (래퍼 `WrapperExtras.locale` 의 JSDoc 이 `GridChrome.setLocale` 을 언급하나, 이는 stale 한 주석일 뿐 실제 public API 가 아닙니다.)
+- `locale`은 `WrapperExtras`와 코어 `PureSheetConfig` 양쪽에 존재하는 유일한 키이며(둘 다 `string`), 의도적으로 strip되지 않아 코어 설정과 래퍼 옵션(`options.locale`) 양쪽에 전달됩니다(`WRAPPER_EXTRA_KEYS` 에서 `locale` 제외).
+
+---
+
+## Legacy exports
+
+아래 항목은 모두 **legacy(이전 React API)** 로, 패키지 루트의 `export * from './legacy'`를 통해 재노출됩니다. 신규 코드는 위의 `MozGrid` 컴포넌트를 사용하세요. 여기서는 그대로(비파괴) 재노출됩니다.
+
+> ⚠️ **legacy 표기**: 아래 모든 심볼은 호환을 위해 유지되는 이전 API입니다.
+
+### 컴포넌트 (legacy)
+
+| 심볼 | 종류 | 설명 |
+|------|------|------|
+| `MozGridReact` | 컴포넌트 | (legacy) 이전 React 그리드 컴포넌트. README의 사용 예제가 이를 사용 |
+| `MozGridReactCore` / `MozGridReactCoreHandle` | 컴포넌트 / 타입 | (legacy) 저수준 코어 그리드 컴포넌트 + ref 핸들 |
+| `CellTemplate`, `HeaderTemplate`, `CellEditor`, `DetailTemplate`, `GroupTemplate` | 컴포넌트 | (legacy) 선언형 템플릿 등록 child 컴포넌트 |
+| `GridToolBox`, `GridOptionModal`, `ColumnPicker`, `GridBulkEditor`, `GridContextMenu` (+`GridContextMenuHandle`) | 컴포넌트 / 타입 | (legacy) 그리드 UI 서브 컴포넌트 |
+| `GridSearchInput`, `GridFilter`, `GridSort`, `GridCustomCell`, `GridFooter`, `Dragging`, `draggingEventBus` | 컴포넌트 / 값 | (legacy) 공용 UI 컴포넌트 (`draggingEventBus`는 런타임 값) |
+| `MozPivotReact`, `PivotToolBox`, `PivotOptionModal`, `PivotFieldPanel`, `PivotContextMenu` | 컴포넌트 | (legacy) 피벗 컴포넌트 |
+| `PivotGrid` | 컴포넌트 | (legacy, `@deprecated`) `MozPivotReact`의 옛 이름 alias |
+| `MozPivotChart` (+`MozPivotChartHandle`/`MozPivotChartProps`), `PivotChartDetail`, `PivotChartMini`, `PivotChartMultiple`, `PivotChartToolbar`, `EChart` (+`EChartHandle`/`EChartProps`) | 컴포넌트 / 타입 | (legacy) 피벗 차트 컴포넌트(echarts 기반) |
+| `ClientExcelUploadPopup` | 컴포넌트 | (legacy) 클라이언트 Excel 팝업 |
+| UI 프리미티브 (Radix 기반): `CheckBox`, `Toggle`, `Button`, `Input`, `NumberInput`, `DateInput`, `EmptyState`, `Popup`, `ContextMenu`, `Select`, `MultiSelect` (+ 각 Props/Handle 타입) | 컴포넌트 / 타입 | (legacy) UI 프리미티브 11종 |
+| 아이콘 20종 (`IconAdd`, `IconArrowDownWithTail`, …, `IconToastWarning`) | 컴포넌트 | (legacy) |
+
+### 함수 / 유틸 (legacy)
+
+| 심볼 | 종류 | 설명 |
+|------|------|------|
+| `toEChartsOption`, `CHART_TYPE_OPTIONS` | 함수 / const | (legacy) 차트 유틸 + 옵션 |
+| `pickFile`, `downloadBlob` | 함수 | (legacy) 파일 유틸 |
+| `cn`, `generateUUID`, `pxToRem`, `uniqueId`, `shallowEqual`, `formatMessage` | 함수 | (legacy) 공용 유틸 |
+| `runClientExport`, `exportCsv`, `generateSessionId` | 함수 | (legacy) 클라이언트 내보내기 헬퍼 |
+
+### i18n (legacy)
+
+| 심볼 | 종류 | 설명 |
+|------|------|------|
+| `MozConfigProvider`, `MozLocaleContext`, `useMozLocale`, `koKR`, `enUS`, `zhCN`, `jaJP` (+`MozConfigProviderProps`, `MozLocaleMessages`), `useMozContextWrapper`, `MozContextWrapperContext` (+`ContextWrapper`) | 컴포넌트 / Context / 훅 / 사전 / 타입 | (legacy) i18n. `useMozLocale()`는 `MozLocaleMessages` 객체를 직접 반환(Ref 아님, 재렌더 시 자동 갱신). locale은 Context이며 contract가 아님. **`MozConfigProvider contextWrapper`** 로 소비자 Provider 트리를 넘기면 셀·헤더·에디터 템플릿과 slot 의 독립 root 가 그 트리로 감싸져 소비자 context 를 되찾는다(`@vmscloud/moz-ui-components-react` 와 같은 계약, 신규 `MozGrid`·legacy `MozGridReact` 공통). 참조 동일성 유지 필요 |
+
+### Notification contract (legacy — React 유일의 host 주입 contract)
+
+| 심볼 | 종류 | 설명 |
+|------|------|------|
+| `GridNotificationProvider`, `GridNotificationContext`, `GridNotificationKey`, `useGridNotificationStore`, `provideGridNotification` (+`GridNotificationContract`, `NotificationItem`, `SSENotificationType`, `ExcelNotificationOperationType`) | Provider / Context / Symbol / 훅 / 함수 / 타입 | (legacy) React에서 host-주입 가능한 유일한 contract |
+
+```ts
+interface GridNotificationContract {
+  show: (item: Omit<NotificationItem, 'id' | 'createdAt'>) => string;
+  update: (id: string, patch: Partial<NotificationItem>) => void;
+  remove: (id: string) => void;
+  list: NotificationItem[];
+}
+// NotificationItem = { id; type: SSENotificationType; operation?: ExcelNotificationOperationType;
+//                      title; message?; progress?; createdAt }
+// SSENotificationType = 'INFO' | 'WARNING' | 'ERROR' | 'SUCCESS'
+// ExcelNotificationOperationType = 'IMPORT' | 'EXPORT' | 'EXPORT_CSV'
+```
+
+> ⚠️ 이 contract는 신규 `MozGrid` 컴포넌트가 사용하지 **않습니다**([Vue와의 비대칭](#vue와의-비대칭-주의) 참조). `GridNotificationProvider`(= `GridNotificationContext.Provider`)로 주입하고 `useGridNotificationStore()`(contract 또는 `null` 반환)로 소비합니다. `provideGridNotification(contract)`는 contract를 그대로 반환합니다(Provider 권장).
+
+### Contexts (legacy)
+
+`GridInstanceContext`, `GridContainerContext`, `GridRendererContext`, `GridTemplateRegistryContext`, `GridFilterModuleContext`, `GridSortModuleContext`, `GridCustomCellModuleContext`, `GridBulkEditorModuleContext` — (legacy) 내부이지만 public한 React Context 8종. 템플릿 등록에는 `GridTemplateRegistryContext`를 사용합니다.
+
+### 훅 (legacy)
+
+| 훅 | 시그니처 | 설명 |
+|----|----------|------|
+| `useGridInstance` | `(): PureSheet \| null` | 현재 PureSheet(초기화 전 `null`). Vue와 달리 인스턴스를 직접 반환 |
+| `useGridEvents` | `(handlers: Partial<Record<PureSheetEventType, (payload: unknown) => void>>): void` | 그리드 이벤트 선언형 구독(자동 등록/해제) |
+| `useGridSelection` / `useGridSelect` | `() => ...` | 선택 상태/헬퍼(별개 2종) |
+| `useGridChanges` | `() => ...` | 변경 추적 |
+| `useGridUndoRedo` | `(): UseGridUndoRedoReturn` | Undo/Redo 컨트롤러 |
+| `useGridValidation` | `(): UseGridValidationReturn` | 검증 상태 |
+| `useGridColumns` | `(): UseGridColumnsReturn` | 컬럼 상태/표시 |
+| `useSearchHighlight` | `() => ...` | 검색 하이라이트 부수효과 |
+| `useCellTooltip` | `() => ...` | 셀 툴팁 동작 |
+| `useGridFilter` | `(): UseGridFilterReturn` | 필터 모듈 |
+| `useGridSort` | `(): UseGridSortReturn` | 정렬 모듈 |
+| `useGridCustomCell` | `(): UseGridCustomCellReturn` | 커스텀 셀(조건부 서식) 모듈 |
+| `useGridBulkEditor` | `(): UseGridBulkEditorReturn` | 일괄 편집 컨트롤러 |
+| `useContextMenu` | `(): UseContextMenuReturn` | 컨텍스트 메뉴 컨트롤러 |
+| `useClientExcelStore` | `(): UseClientExcelStoreReturn` | 클라이언트 Excel store |
+| `useMozLocale` | `(): MozLocaleMessages` | locale 메시지 객체 직접 반환 |
+| `useGridNotificationStore` | `(): GridNotificationContract \| null` | host 주입 notification contract 조회 |
+
+> ⚠️ React 전용으로 제공되지 않는 항목: **`useGridPreset` / userLayout 훅은 없습니다**(Vue 전용).
+
+### 타입 재노출 (legacy)
+
+- 피벗 prop/config 타입: `PivotGridProps`, `PivotFieldItem`, `AvailableField`, `PivotFieldPanelConfig`, `PivotGridSettings`
+- legacy 컴포넌트 props 타입: `MozGridReactCoreProps`, `MozGridReactProps`
+- 슬롯/레지스트리 타입: `CellSlotProps`, `HeaderSlotProps`, `EditorSlotProps`, `DetailSlotProps`, `GroupSlotProps`, `TemplateRegistry`, `TemplateEntry`
+- 차트 타입: `ChartType`, `ChartSeriesConfig`, `EChartsConfig`
+- 클라이언트 Excel 타입: `UseClientExcelStoreReturn`, `ClientExcelExportConfig`, `BulkEditorState`, 및 각 훅 반환 타입(`UseGridUndoRedoReturn`/`UseGridValidationReturn`/`UseGridColumnsReturn`/`UseGridFilterReturn`/`UseGridSortReturn`/`UseGridCustomCellReturn`/`UseGridBulkEditorReturn`/`UseContextMenuReturn`)
+- 툴바 config 타입: `ComparisonOperator`, `LogicalOperator`, `IFilterDef`, `ISortDef`, `ICustomCellDef`, `ICustomCellRuleSet`, `ICustomCellConfig`, `IContextMenuItem`, `IContextMenuConfig`, `IContextMenuExcelEventArgs`, `AggregateType`, `IAggregateValues`
+- 코어 타입 pass-through(`@vmscloud/moz-ui-grid-core` 재노출, type-only): `PureSheetConfig`, `FieldDef`, `PureSheetEventType`, `SortState`, `FilterState`, `FilterOperator`, `Row`, `ColumnDef`, `ColumnState`, `EditorConfig`, `GridState`, `GridActivity`, `ViewState`, `RowSelectionMode`, `CellSelectionMode`, `RowSelectionTrigger`, `RowSelectionConfig`, `CellSelectionConfig`, `DataType`, `AggregateFunc`, `RowState`, `ValidationRule`, `ValidationError`, `ValidationTrigger`, `GroupConfig`, `GroupingConfig`, `TreeConfig`, `MasterDetailConfig`, `HeaderGroupDef`, `FormatRowCallback`, `PartialTranslationMap`, `IPivotAPI`, `PivotState`, `PivotConfig`, `PivotRowField`, `PivotColumnField`, `PivotValueField`, `PivotResult`, `PivotHeaderNode`, `PivotRow`, `ShowValueAs`, `IRowsAPI`, `IColumnsAPI`, `IChangesAPI`, `IUndoManagerAPI`, `IGroupAPI`, `ITreeAPI`, `IMasterDetailAPI`, `IValidationAPI`, `IClipboardAPI`, `IHeadersAPI` — 및 런타임 값 `UndoStack`
+
+> ⚠️ 서버사이드 Excel은 이 패키지에 의도적으로 포함되지 않습니다 — 클라이언트사이드 Excel만 존재합니다.
+
+---
+
+## 관련 문서
+
+- [reference.md](reference.md) — 코어 그리드(PureSheet) Config · 타입 · API · **이벤트 페이로드** 정본
+- [examples.md](examples.md) — 사용 예제 (Sub-API별 사용, Reactive React 통합, 이벤트, 선택 모드, Excel I/O 등)