@vmscloud/moz-ui-grid-react 0.1.19

package/README.md

@@ -0,0 +1,148 @@
+# @vmscloud/moz-ui-grid-react
+
+`@vmscloud/moz-ui-grid-core`의 React 18+ wrapping 라이브러리입니다. Vue 버전(`@vmscloud/moz-ui-grid-vue`)과 외관·동작·API가 동등합니다.
+
+## 설치
+
+```bash
+pnpm add @vmscloud/moz-ui-grid-react react react-dom
+```
+
+npmjs 공개 패키지라 레지스트리 설정이나 토큰 없이 설치됩니다.
+예전에 `.npmrc`에 넣어 둔 `@vmscloud:registry=https://npm.pkg.github.com` 매핑은 제거하세요.
+
+## 문서
+
+전체 API 레퍼런스가 패키지에 **동봉**됩니다 (`node_modules/@vmscloud/moz-ui-grid-react/docs/manual/`):
+
+- **`reference_react.md`** — React 래퍼(신규 `MozGrid`) Props·이벤트·Slot·인스턴스 API
+- **`reference.md`** — 코어(`PureSheet`) Config·타입·이벤트 전체 레퍼런스 (래퍼 문서가 링크로 위임)
+- **`examples.md`** — 코어 사용 예제
+
+> 아래 "기본 사용법"은 legacy 컴포넌트(`MozGridReact`) 기준입니다. `coreConfig` 기반 신규 `MozGrid` API는 `reference_react.md`를 참조하세요.
+
+## 기본 사용법
+
+```tsx
+import { MozGridReact, MozConfigProvider, koKR } from '@vmscloud/moz-ui-grid-react';
+// 그리드 전체 CSS(core+chrome 합본)는 wrapper 패키지가 제공한다 (react/vue 는 wrapper 를 external 화).
+import '@vmscloud/moz-ui-grid-wrapper/style.css';
+
+const fields = [
+  { id: 'name', header: '이름', dataType: 'string' },
+  { id: 'age', header: '나이', dataType: 'number' },
+];
+const data = [
+  { id: 1, name: '홍길동', age: 30 },
+  { id: 2, name: '김철수', age: 25 },
+];
+
+function App() {
+  return (
+    <MozConfigProvider locale={koKR}>
+      <div style={{ height: 600 }}>
+        <MozGridReact fields={fields} data={data} />
+      </div>
+    </MozConfigProvider>
+  );
+}
+```
+
+## 아키텍처
+
+```
+moz-ui-grid-react/
+├── src/
+│   ├── components/grid/          MozGridReact, MozGridReactCore, toolbar/, context-menu/, bulk-editor/
+│   ├── components/common/        Filter, Sort, CustomCell, SearchInput, Footer, ClientExcelUploadPopup, Dragging
+│   ├── components/pivot/         MozPivotReact, ToolBox, OptionModal, FieldPanel, ContextMenu, chart/
+│   ├── ui/                       Radix UI 기반 12 primitives (CheckBox, Toggle, Button, Input, NumberInput,
+│   │                             DateInput, EmptyState, Popup, ContextMenu, Select, MultiSelect)
+│   ├── bridge/                   ReactRenderer (React ↔ DOM), fieldBuilder, templateRegistry
+│   ├── contexts/                 8 React Context (Grid/Renderer/Registry/Filter/Sort/CustomCell/BulkEditor/Container)
+│   ├── hooks/                    15 hook (useGridInstance/Events/Selection/Changes/UndoRedo/Validation/
+│   │                             Columns/Select/SearchHighlight/CellTooltip/Filter/Sort/CustomCell/
+│   │                             BulkEditor/ContextMenu/ClientExcelStore/ClientExcelExport)
+│   ├── contracts/                NotificationContract
+│   ├── icons/                    20개 SVG 아이콘
+│   ├── locale/                   ko/en/zh/ja 사전 + MozConfigProvider + useMozLocale
+│   ├── types/                    props, slots, toolbar, pivot-props
+│   └── utils/                    cn, generateUUID, pxToRem, formatMessage, pickFile, downloadBlob
+```
+
+## Vue 버전과의 차이점
+
+| 항목 | Vue | React |
+|---|---|---|
+| Provider | `<MozConfigProvider :locale="...">` | `<MozConfigProvider locale={...}>` |
+| Composable | `useGridInstance()` → `Ref<PureSheet \| null>` | `useGridInstance()` → `PureSheet \| null` (React 리렌더로 자동 갱신) |
+| v-model | `v-model:visible="..."` | `visible={...} onVisibleChange={...}` |
+| Slots | `<template #default>` | `children` 또는 `xxxSlot` 함수 prop |
+| Refs | `defineExpose` | `forwardRef` + `useImperativeHandle` |
+| `provide/inject` | InjectionKey | React Context |
+| `VueRenderer` | `createApp` per cell | `createRoot` per cell (`ReactRenderer`) |
+| Pinia store | `useExcelStore` 등 | (서버사이드 Excel은 본 패키지에서 제외) |
+
+## 셀 커스터마이즈 (template)
+
+```tsx
+import { useEffect, useContext } from 'react';
+import {
+  MozGridReact,
+  GridTemplateRegistryContext,
+  type CellSlotProps,
+} from '@vmscloud/moz-ui-grid-react';
+
+function StatusCell({ value }: CellSlotProps) {
+  return <span style={{ color: value === 'active' ? '#357e63' : '#dc5a5a' }}>{String(value)}</span>;
+}
+
+function MyGrid() {
+  return (
+    <MozGridReact fields={fields} data={data}>
+      <RegisterStatusCell />
+    </MozGridReact>
+  );
+}
+
+function RegisterStatusCell() {
+  const registry = useContext(GridTemplateRegistryContext);
+  useEffect(() => {
+    if (!registry) return;
+    registry.register({ type: 'cell', fieldId: 'status', component: StatusCell });
+    return () => registry.unregister('cell', 'status');
+  }, [registry]);
+  return null;
+}
+```
+
+## 스타일
+
+- 모든 클래스는 `moz-r-` prefix (Vue `moz-` prefix와 분리)
+- Radix UI primitive + scoped SCSS (Tailwind 미사용)
+- 컬러 토큰: `#4568e0`(accent), `#bac6d4`(border), `#dc5a5a`(error), `#28364e`(text), `#96a5be`(placeholder)
+- 그리드 전체 CSS(core+chrome 합본)는 `import '@vmscloud/moz-ui-grid-wrapper/style.css'` 로 로드 (react/vue 는 wrapper 를 external 화)
+
+## 제한사항 / 향후 보강 항목
+
+- **서버사이드 Excel 미포함**: Vue 측 `useExcelStore`/`useExcelDownloadStore`/`useExcelUploadStore`와 `ExcelGuard`/`ExcelQueueManager`/`ExcelTaskRunner`/`ExcelTimeoutManager`/`ExcelImportUtil`은 본 패키지에 없음. 클라이언트사이드 Excel(`ClientExcelUploadPopup`, `useClientExcelStore`, `runClientExport`, `exportCsv`)만 제공.
+- **DateInput**: 현재는 native `<input type="date">` 기반. Vue의 커스텀 Calendar popup은 추후 보강.
+- **Pivot Field Panel**: 시각 골격만 제공. 드래그-드롭 dnd 통합은 호스트가 콜백으로 처리.
+- **GridFilter/GridSort/GridCustomCell**: hook 연동 골격. 고급 옵션(헤더 필터 UI, drag-resize 행) 추후 보강.
+
+## 빌드
+
+```bash
+pnpm install
+pnpm --filter @vmscloud/moz-ui-grid-react build
+```
+
+산출물:
+- `dist/index.js` (ES module)
+- `dist/index.cjs` (CommonJS)
+- `dist/index.d.ts` (TypeScript)
+- `dist/style.css` (단일 스타일시트, 24.8kB)
+
+## 라이센스
+
+ISC

package/dist/MozGrid.d.ts

@@ -0,0 +1,136 @@
+import { ReactNode, ComponentType } from 'react';
+import { GridChrome, WrapperExtras, MozGridCoreProps, WrapperToolItemsProps } from '@vmscloud/moz-ui-grid-wrapper';
+import { PureSheet, ScrollEndReachedPayload, ScrollPayload } from '@vmscloud/moz-ui-grid-core';
+import { CellSlotProps, HeaderSlotProps, EditorSlotProps } from './types/slots';
+/**
+ * MozGrid — vanilla GridChrome(@vmscloud/moz-ui-grid-wrapper) 위임 React 어댑터.
+ *
+ * props = core(`MozGridCoreProps` = PureSheetConfig 평탄화, controlled) + wrapper 개별 props(`WrapperExtras`)
+ * + React 전용(템플릿/slot ReactNode/이벤트). 마운트 후 변경은 변경된 설정만 코어/크롬에 타깃 반영(전체 재렌더 회피):
+ *  - core 설정 → `chrome.reconcileCoreConfig` (data→loadData, fields→updateFields, theme/group/… 전용 setter).
+ *  - 런타임 setter 없는 키(rowHeight/editable/keyFields/…) → 상태보존 재생성(getConfig→applyConfig).
+ *  - wrapper UI 플래그(useToolBox 등) → `chrome.setUIOptions` (그리드 보존, 크롬만 부분 재조립).
+ */
+export type MozGridProps = WrapperExtras & {
+    /**
+     * core 설정 1덩어리 (`MozGridCoreProps` = PureSheetConfig 평탄형) — **controlled(양방향)**.
+     * 그리드 내부 변경(피벗 패널/옵션 모달·그룹)이 `onCoreConfigChange` 로 역류 → 단방향 prop 클로버 버그 소멸.
+     */
+    coreConfig?: MozGridCoreProps;
+    onCoreConfigChange?: (next: MozGridCoreProps) => void;
+    cellTemplates?: Record<string, ComponentType<CellSlotProps>>;
+    headerTemplates?: Record<string, ComponentType<HeaderSlotProps>>;
+    editorTemplates?: Record<string, ComponentType<EditorSlotProps>>;
+    toolLeft?: ReactNode;
+    /** tool-items 슬롯 — 정적 ReactNode 또는 {disabled,hasItem} 받는 render-prop (Vue 스코프 슬롯 대응). */
+    toolItems?: ReactNode | ((props: WrapperToolItemsProps) => ReactNode);
+    toolBottom?: ReactNode;
+    optionPopup?: ReactNode;
+    notification?: ReactNode;
+    footer?: ReactNode;
+    /** 빈 상태 customState 영역 (Vue `#empty-state` 슬롯 대응) */
+    emptyStateContent?: ReactNode;
+    /**
+     * 그리드 준비 완료. `grid` 는 core 인스턴스, `chrome` 은 wrapper 크롬이다.
+     * 예) 피벗 옵션 바를 처음부터 켜 두기: `(grid, chrome) => chrome.setPivotBarVisible(true)`.
+     */
+    onReady?: (grid: PureSheet, chrome: GridChrome) => void;
+    onDataLoaded?: () => void;
+    onRowClick?: (payload: unknown) => void;
+    onRowDblclick?: (payload: unknown) => void;
+    onRowPinned?: (payload: unknown) => void;
+    onRowUnpinned?: (payload: unknown) => void;
+    onRowReordered?: (payload: unknown) => void;
+    onCellClick?: (payload: unknown) => void;
+    onCellDblclick?: (payload: unknown) => void;
+    onCellChange?: (payload: unknown) => void;
+    onCellBeforeEdit?: (payload: unknown) => void;
+    onCellEditCommitting?: (payload: unknown) => void;
+    onCellEditCommitted?: (payload: unknown) => void;
+    onCellTooltip?: (payload: unknown) => void;
+    onSelectionChanged?: (payload: unknown) => void;
+    onColumnResize?: (payload: unknown) => void;
+    onColumnReorder?: (payload: unknown) => void;
+    onColumnPin?: (payload: unknown) => void;
+    onColumnVisibility?: (payload: unknown) => void;
+    onSortChanged?: (payload: unknown) => void;
+    onHeaderClick?: (payload: unknown) => void;
+    onHeaderSortClick?: (payload: unknown) => void;
+    onHeaderFilterClick?: (payload: unknown) => void;
+    onFilterChanged?: (payload: unknown) => void;
+    onScroll?: (payload: ScrollPayload) => void;
+    onEndReached?: (payload: ScrollEndReachedPayload) => void;
+    onUndoStateChange?: (payload: unknown) => void;
+    onClipboardCopy?: (payload: unknown) => void;
+    onClipboardPaste?: (payload: unknown) => void;
+    onValidationChanged?: (payload: unknown) => void;
+    onColumnGroupToggle?: (payload: unknown) => void;
+    onGroupToggle?: (payload: unknown) => void;
+    onGroupBatchToggle?: (payload: unknown) => void;
+    onContextMenu?: (payload: unknown) => void;
+};
+/**
+ * ref 핸들 — GridChrome 전체 표면 평탄 노출(Vue MozGrid.vue Proxy expose 대응).
+ * `ref.current.grid/filter/sort/pivot/chart/setUIOptions/on...` 직접 접근 + chrome 재생성 자연 반영.
+ */
+export type MozGridHandle = GridChrome & {
+    chrome: GridChrome | null;
+};
+export declare const MozGrid: import('react').ForwardRefExoticComponent<WrapperExtras & {
+    /**
+     * core 설정 1덩어리 (`MozGridCoreProps` = PureSheetConfig 평탄형) — **controlled(양방향)**.
+     * 그리드 내부 변경(피벗 패널/옵션 모달·그룹)이 `onCoreConfigChange` 로 역류 → 단방향 prop 클로버 버그 소멸.
+     */
+    coreConfig?: MozGridCoreProps;
+    onCoreConfigChange?: (next: MozGridCoreProps) => void;
+    cellTemplates?: Record<string, ComponentType<CellSlotProps>>;
+    headerTemplates?: Record<string, ComponentType<HeaderSlotProps>>;
+    editorTemplates?: Record<string, ComponentType<EditorSlotProps>>;
+    toolLeft?: ReactNode;
+    /** tool-items 슬롯 — 정적 ReactNode 또는 {disabled,hasItem} 받는 render-prop (Vue 스코프 슬롯 대응). */
+    toolItems?: ReactNode | ((props: WrapperToolItemsProps) => ReactNode);
+    toolBottom?: ReactNode;
+    optionPopup?: ReactNode;
+    notification?: ReactNode;
+    footer?: ReactNode;
+    /** 빈 상태 customState 영역 (Vue `#empty-state` 슬롯 대응) */
+    emptyStateContent?: ReactNode;
+    /**
+     * 그리드 준비 완료. `grid` 는 core 인스턴스, `chrome` 은 wrapper 크롬이다.
+     * 예) 피벗 옵션 바를 처음부터 켜 두기: `(grid, chrome) => chrome.setPivotBarVisible(true)`.
+     */
+    onReady?: (grid: PureSheet, chrome: GridChrome) => void;
+    onDataLoaded?: () => void;
+    onRowClick?: (payload: unknown) => void;
+    onRowDblclick?: (payload: unknown) => void;
+    onRowPinned?: (payload: unknown) => void;
+    onRowUnpinned?: (payload: unknown) => void;
+    onRowReordered?: (payload: unknown) => void;
+    onCellClick?: (payload: unknown) => void;
+    onCellDblclick?: (payload: unknown) => void;
+    onCellChange?: (payload: unknown) => void;
+    onCellBeforeEdit?: (payload: unknown) => void;
+    onCellEditCommitting?: (payload: unknown) => void;
+    onCellEditCommitted?: (payload: unknown) => void;
+    onCellTooltip?: (payload: unknown) => void;
+    onSelectionChanged?: (payload: unknown) => void;
+    onColumnResize?: (payload: unknown) => void;
+    onColumnReorder?: (payload: unknown) => void;
+    onColumnPin?: (payload: unknown) => void;
+    onColumnVisibility?: (payload: unknown) => void;
+    onSortChanged?: (payload: unknown) => void;
+    onHeaderClick?: (payload: unknown) => void;
+    onHeaderSortClick?: (payload: unknown) => void;
+    onHeaderFilterClick?: (payload: unknown) => void;
+    onFilterChanged?: (payload: unknown) => void;
+    onScroll?: (payload: ScrollPayload) => void;
+    onEndReached?: (payload: ScrollEndReachedPayload) => void;
+    onUndoStateChange?: (payload: unknown) => void;
+    onClipboardCopy?: (payload: unknown) => void;
+    onClipboardPaste?: (payload: unknown) => void;
+    onValidationChanged?: (payload: unknown) => void;
+    onColumnGroupToggle?: (payload: unknown) => void;
+    onGroupToggle?: (payload: unknown) => void;
+    onGroupBatchToggle?: (payload: unknown) => void;
+    onContextMenu?: (payload: unknown) => void;
+} & import('react').RefAttributes<MozGridHandle>>;

package/dist/bridge/ReactRenderer.d.ts

@@ -0,0 +1,45 @@
+import { ComponentType, ReactNode } from 'react';
+export type ContextWrapper = (children: ReactNode) => ReactNode;
+export declare class ReactRenderer {
+    private instances;
+    private contextWrapper;
+    /**
+     * lifecycle 셀 renderer 전용: 컨테이너(.ps-cell-content)별 "현재 owner root".
+     * 가상 스크롤/그룹 토글로 CellPool이 같은 DOM 노드를 LIFO로 즉시 재획득할 때
+     * 발생하는 "지연 unmount ↔ 새 mount" 경쟁을 막기 위한 추적용. (mountInstance 참조)
+     */
+    private lifecycleRoots;
+    /** 외부 Provider 트리를 캡처 (MozGridReactCore의 useLayoutEffect에서 호출). */
+    setContextWrapper(wrapper: ContextWrapper | null): void;
+    /**
+     * React 컴포넌트를 DOM 요소에 마운트합니다.
+     *
+     * 동일 key로 재호출 시 props만 업데이트합니다 (root.render 재호출).
+     */
+    mount(key: string, container: HTMLElement, component: ComponentType<any>, props?: Record<string, unknown>): void;
+    /**
+     * 컨테이너 단위 lifecycle 인스턴스 마운트 (키 없음).
+     *
+     * core 의 LifecycleCellRenderer(arity 2: `(container, params) => instance`) 전용.
+     * 전역 키맵을 쓰지 않고 셀 컨테이너마다 독립 root 를 만들며, update(=root.render 재호출)로 갱신,
+     * destroy(=root.unmount)로 정리한다. 가상 스크롤 재사용은 destroy 없이 update 로 처리.
+     * (키 충돌·미재마운트로 셀이 안 그려지던 버그 해소)
+     */
+    mountInstance(container: HTMLElement, component: ComponentType<any>, initialProps: Record<string, unknown>): {
+        update: (props: Record<string, unknown>) => void;
+        destroy: () => void;
+    };
+    /** props 업데이트 (재마운트 없음, root.render 재호출) */
+    updateProps(key: string, props: Record<string, unknown>): void;
+    /** 특정 인스턴스 언마운트 */
+    unmount(key: string): void;
+    /** 접두사 기반 일괄 언마운트 (예: 'cell:' 접두사) */
+    unmountByPrefix(prefix: string): void;
+    /** 전체 인스턴스 언마운트 */
+    unmountAll(): void;
+    /** 현재 마운트된 인스턴스 수 */
+    get size(): number;
+    /** 특정 key의 인스턴스가 존재하는지 확인 */
+    has(key: string): boolean;
+    private render;
+}

package/dist/bridge/fieldBuilder.d.ts

@@ -0,0 +1,9 @@
+import { FieldDef } from '@vmscloud/moz-ui-grid-core';
+import { TemplateRegistry } from '../types/slots';
+import { ReactRenderer } from './ReactRenderer';
+/**
+ * 사용자 FieldDef + 등록된 React 컴포넌트 → cellRenderer/headerRenderer/editor 주입.
+ *
+ * Vue 측 fieldBuilder.ts의 React 대응.
+ */
+export declare function buildFieldDefs(fields: FieldDef[], registry: TemplateRegistry, renderer: ReactRenderer): FieldDef[];

package/dist/bridge/templateRegistry.d.ts

@@ -0,0 +1,11 @@
+import { TemplateRegistry } from '../types/slots';
+/**
+ * 템플릿 레지스트리 생성.
+ *
+ * CellTemplate, HeaderTemplate, CellEditor, DetailTemplate, GroupTemplate React
+ * 컴포넌트가 mount 시 register하고, unmount 시 unregister합니다.
+ *
+ * Vue 버전과 달리 reactive하지 않습니다. 등록 후 PureSheet가 다시 빌드되어야 반영됩니다
+ * (그리드의 fields prop 변경 시 자동으로 rebuildFields가 호출됨).
+ */
+export declare function createTemplateRegistry(): TemplateRegistry;