@vmscloud/moz-ui-grid-vue 0.2.16 → 0.2.18

package/dist/types/pivot-props.d.ts

@@ -83,11 +83,14 @@ export interface PivotGridProps {
     loading?: boolean;
     /** 빈 상태 설정 — 객체를 넘겨야 EmptyState가 활성화됨 (레거시 ExtendPivotGrid와 동일한 opt-in) */
     emptyState?: {
+        /** 빈 상태 안내 사용 (기본 true). false 면 0행·필터 0건이어도 안내를 그리지 않음(헤더만 있는 빈 표) */
+        enabled?: boolean;
         /** 커스텀 빈 상태 (customState 슬롯 사용) */
         isCustomState?: boolean;
         headerMsg?: string;
         contentMsg?: string;
-        useImg?: boolean;
+        /** 안내 그림 (기본 true). 'auto' 면 안내 영역 높이가 모자랄 때 그림만 숨기고 문구는 남김(리사이즈 시 재판정) */
+        useImg?: boolean | 'auto';
         /** 빈 상태 이미지 강제 지정 (생략 시 totalRowCount/filteredRowCount로 자동 결정) */
         selectImg?: 'Custom' | 'Result' | 'Data' | 'Search';
     };

package/dist/types/props.d.ts

@@ -72,9 +72,7 @@ export interface MozGridVueCoreProps {
     locale?: string;
     /** 데이터 처리 엔진 (기본: 'native') */
     engine?: 'aq' | 'native';
-    /** Web Worker 사용 여부 */
-    useWorker?: boolean;
-    /** Worker 데이터 로더 설정 (useWorker: true 시 사용) */
+    /** 데이터 로더 설정 — `{ use: DataLoader 클래스 }`(메인 스레드) 또는 `{ worker: () => new Worker(...) }`(Worker) */
     loader?: LoaderConfig;
     /** 키 컬럼 편집 방지 (기본: false) */
     preventKeyEdit?: boolean;
@@ -114,8 +112,6 @@ export interface MozGridVueProps extends MozGridVueCoreProps {
     useToolBoxSetting?: boolean;
     /** 푸터 표시 (기본: true) */
     useExtendFooter?: boolean;
-    /** 집계 푸터 표시 (기본: false) */
-    useSummaryFooter?: boolean;
     /** 정렬 버튼 표시 (기본: true) */
     useSort?: boolean;
     /** 조건부 스타일 버튼 표시 (기본: true) */
@@ -128,11 +124,14 @@ export interface MozGridVueProps extends MozGridVueCoreProps {
     loading?: boolean;
     /** 빈 상태 설정 — 객체를 넘겨야 EmptyState가 활성화됨 (레거시 ExtendFlexGrid와 동일한 opt-in) */
     emptyState?: {
+        /** 빈 상태 안내 사용 (기본 true). false 면 0행·필터 0건이어도 안내를 그리지 않음(헤더만 있는 빈 표) */
+        enabled?: boolean;
         /** 커스텀 빈 상태 (customState 슬롯 사용) */
         isCustomState?: boolean;
         headerMsg?: string;
         contentMsg?: string;
-        useImg?: boolean;
+        /** 안내 그림 (기본 true). 'auto' 면 안내 영역 높이가 모자랄 때 그림만 숨기고 문구는 남김(리사이즈 시 재판정) */
+        useImg?: boolean | 'auto';
         /** 빈 상태 이미지 강제 지정 (생략 시 totalRowCount/filteredRowCount로 자동 결정) */
         selectImg?: 'Custom' | 'Result' | 'Data' | 'Search';
     };
@@ -169,7 +168,7 @@ export interface MozGridVueEmits {
     (e: 'contextmenu', payload: unknown): void;
 }
 /** Props → PureSheetConfig 변환에 사용하는 키 목록 */
-export declare const CONFIG_PROP_KEYS: readonly ["keyFields", "theme", "rowHeight", "headerHeight", "showHeader", "resizableColumns", "reorderableColumns", "showRowHeader", "rowHeader", "rowSelection", "cellSelection", "cellSelectionImpliesRows", "editable", "tooltipMode", "alternatingRows", "autoFitColumns", "dynamicRowHeights", "reorderableRows", "locale", "engine", "useWorker", "loader", "preventKeyEdit", "showStatusBar", "showDragHandleColumn", "undoStack", "formatRow", "translations", "rowStyle", "headerStyle", "rowHeightChangeThreshold"];
+export declare const CONFIG_PROP_KEYS: readonly ["keyFields", "theme", "rowHeight", "headerHeight", "showHeader", "resizableColumns", "reorderableColumns", "showRowHeader", "rowHeader", "rowSelection", "cellSelection", "cellSelectionImpliesRows", "editable", "tooltipMode", "alternatingRows", "autoFitColumns", "dynamicRowHeights", "reorderableRows", "locale", "engine", "loader", "preventKeyEdit", "showStatusBar", "showDragHandleColumn", "undoStack", "formatRow", "translations", "rowStyle", "headerStyle", "rowHeightChangeThreshold"];
 /** flat 모드 전용 Props 키 목록 (pivot 모드에서는 제외) */
 export declare const FLAT_ONLY_PROP_KEYS: readonly ["columnGroups", "rowTemplate"];
 /**

package/dist/types/toolbar.d.ts

@@ -1,10 +1,4 @@
-/**
- * Grid UI 타입 정의
- *
- * moz-wijmo-grid의 types.d.ts에서 포팅.
- * ComparisonOperator, LogicalOperator, IFilterDef, ISortDef, ICustomCellRuleSet 등
- * Wijmo 비의존 타입은 그대로 재사용합니다.
- */
+import { FieldDef } from '@vmscloud/moz-ui-grid-core';
 /** 비교 연산자 */
 export type ComparisonOperator = '=' | '≠' | '%' | '!%' | '>' | '≥' | '<' | '≤' | '∅' | '●';
 /** 논리 연산자 */
@@ -125,6 +119,24 @@ export interface IColumnFormatConfig {
     /** columnId → 사용자 헤더 서식 */
     header: Record<string, IColumnHeaderFormat>;
 }
+/**
+ * 우클릭한 위치 정보 — 컨텍스트 메뉴 항목의 `hidden`/`disabled` 조건 함수와 `handler` 가 받는다.
+ * (wrapper `ContextMenuContext` 와 같은 모양)
+ *
+ * - `area`: 데이터 셀·피벗 행 머리글·빈 영역 = 'cell', 열 머리글 = 'header'.
+ * - 머리글이면 `rowIndex` 는 -1, `cellValue`/`rowData` 는 null.
+ * - 피벗 값 셀: `columnId` = '<열 경로>␞<값 필드>', `field` = 값 필드, `cellValue` = 집계값(빈 칸 null).
+ */
+export interface ContextMenuContext {
+    area?: 'cell' | 'header';
+    rowIndex: number;
+    rowId?: string | number;
+    columnId: string;
+    groupId?: string;
+    field: FieldDef | null;
+    cellValue: unknown;
+    rowData: Record<string, unknown> | null;
+}
 /** 컨텍스트 메뉴 항목 */
 export interface IContextMenuItem {
     /** 메뉴 ID */
@@ -133,14 +145,20 @@ export interface IContextMenuItem {
     label: string;
     /** 아이콘 */
     icon?: string;
-    /** 비활성화 */
-    disabled?: boolean;
+    /** 비활성 조건 — boolean 또는 우클릭마다 계산하는 함수. 예외 시 활성(false). */
+    disabled?: boolean | ((ctx: ContextMenuContext) => boolean);
+    /**
+     * 숨김 조건 — boolean 또는 우클릭마다 계산하는 함수. 미지정 = 항상 보임. 예외 시 보임.
+     * children 에도 적용되고, 자식이 모두 숨으면 부모도 빠진다.
+     * @example hidden: ({ area, cellValue }) => area !== 'cell' || cellValue === 0
+     */
+    hidden?: boolean | ((ctx: ContextMenuContext) => boolean);
     /** 구분선 */
     separator?: boolean;
     /** 하위 메뉴 */
     children?: IContextMenuItem[];
-    /** 클릭 핸들러 */
-    handler?: () => void;
+    /** 클릭 핸들러 — 우클릭한 위치(ctx)를 받는다(인자 없는 기존 핸들러도 동작). */
+    handler?: (ctx: ContextMenuContext) => void;
     /**
      * 메뉴 표시 순서 (낮을수록 위에 표시)
      *
@@ -153,6 +171,8 @@ export interface IContextMenuItem {
 export interface IContextMenuConfig {
     /** 컬럼 선택 UI 표시 여부 (설정 모달 내) */
     useViewSelectColumn?: boolean;
+    /** '첫 번째 열로 보내기' 메뉴 (기본 false, 고정·합성 열·다단 헤더에서는 비활성) */
+    useMoveColumnFirst?: boolean;
     /** 고정 컬럼 메뉴 */
     useFixedColumn?: boolean;
     /** 그룹 메뉴 */

package/docs/manual/examples.md

@@ -9,6 +9,7 @@
 - [기본 플랫 그리드](#기본-플랫-그리드)
 - [행 식별 정책과 자동 ID](#행-식별-정책과-자동-id)
 - [숫자 제약과 날짜시간 편집기](#숫자-제약과-날짜시간-편집기)
+- [객체 값 열·점 표기 필드 사용 예제](#객체-값-열점-표기-필드-사용-예제)
 - [grid.rows 사용 예제](#gridrows-사용-예제)
 - [grid.columns 사용 예제](#gridcolumns-사용-예제)
 - [grid.changes 사용 예제](#gridchanges-사용-예제)
@@ -179,6 +180,133 @@ await grid.waitForReady();
 
 ---
 
+### 객체 값 열·점 표기 필드 사용 예제
+
+서버가 담당자를 객체(`owner: { id, name, team }`)로 주는 경우입니다. 담당자 열은 객체 그대로 두고, 팀은 점 표기 열로, 호칭은 수식 열로 보입니다. 규칙 전체는 [reference.md — 점 표기 필드 경로](reference.md#점-표기-필드-경로-field-ownerteam) · [객체 값 열](reference.md#객체-값-열-datatype-object)을 보세요.
+
+```typescript
+import { PureSheet, type FieldDef } from '@vmscloud/moz-ui-grid-core';
+
+const users = [
+  { id: 'u1', name: '홍길동', team: 'A' },
+  { id: 'u2', name: '김철수', team: 'B' },
+  { id: 'u3', name: '김철수', team: 'C' },   // 동명이인
+  { id: 'u4', name: '이영희', team: 'D' },
+];
+
+/** 아이디 또는 이름으로 찾는다. 동명이인이면 throw, 없으면 undefined. */
+function findUser(text: string) {
+  const byId = users.find(u => u.id === text);
+  if (byId) return byId;
+  const byName = users.filter(u => u.name === text);
+  if (byName.length > 1) throw new Error(`동명이인: ${text} — 아이디로 입력하세요`);
+  return byName[0];
+}
+
+const fields: FieldDef[] = [
+  { id: 'no', header: 'No', dataType: 'number' },
+  {
+    id: 'owner', header: '담당자', dataType: 'object',
+    objectKey: 'id',                               // 묶기·필터·병합·선택 비교 키
+    sortValue: 'name',                             // 이름순 정렬 (생략하면 id 순)
+    mask: { type: 'function', formatter: v => (v as { name?: string } | null)?.name ?? '', parser: findUser },
+  },
+  { id: 'ownerTeam', header: '팀', field: 'owner.team' },                      // 점 표기 = row.owner.team
+  { id: 'label', header: '호칭', dataType: 'string', formula: '[owner.name] & "님"' },
+  { id: 'qty', header: '수량', dataType: 'number' },
+];
+
+const shared = { id: 'u1', name: '홍길동', team: 'A' };
+const grid = new PureSheet(container, {
+  fields,
+  keyFields: ['no'],
+  enableReferCache: true,
+  editable: true,
+  data: [
+    { no: 1, owner: { id: 'u2', name: '김철수', team: 'B' }, qty: 10 },
+    { no: 2, owner: { id: 'u2', name: '김철수', team: 'B' }, qty: 20 },  // 같은 id 의 다른 객체
+    { no: 3, owner: { id: 'u3', name: '김철수', team: 'C' }, qty: 30 },  // 동명이인
+    { no: 4, owner: null, qty: 40 },
+    { no: 5, owner: shared, qty: 50 },                                      // 5·6행이 같은 객체를 공유
+    { no: 6, owner: shared, qty: 60 },
+  ],
+});
+await grid.waitForReady();
+```
+
+화면에 보이는 값:
+
+| no | 담당자 | 팀 | 호칭 |
+|---|---|---|---|
+| 1, 2 | 김철수 | B | 김철수님 |
+| 3 | 김철수 | C | 김철수님 |
+| 4 | (빈 칸) | (빈 칸) | 님 |
+| 5, 6 | 홍길동 | A | 홍길동님 |
+
+- 묶기: 같은 설정에 `rowGroupConfig: { columns: ['owner'] }` 를 더하면 1·2행은 객체 참조가 달라도 id 가 같아 그룹 하나(`owner:u2`), 3행(동명이인)은 따로(`owner:u3`)입니다. 배너 라벨은 둘 다 `김철수` 입니다.
+
+```typescript
+await grid.rowGroup.collapse('owner:u2');   // 1·2행만 접힌다 — 3행은 그대로 보인다
+```
+
+- 값 목록 필터: `김철수` 항목이 둘(u2, u3) 나옵니다. 필터는 키나 객체로 겁니다.
+
+```typescript
+await grid.filter([{ id: 'owner', operator: 'in', filterValue: ['u2'], sequence: 0 }]);  // 1·2행
+```
+
+**텍스트 편집 (`mask.parser`)** — 5행 담당자 칸을 더블클릭하면 `홍길동` 이 입력된 채로 열립니다.
+
+| 입력 → Enter | 결과 |
+|---|---|
+| `이영희` | `owner` = `{ id: 'u4', name: '이영희', team: 'D' }` |
+| `u3` | `owner` = u3 객체 |
+| `김철수` | 편집 유지, 오류 문구 `동명이인: 김철수 — 아이디로 입력하세요` (parser 가 throw) |
+| `없는사람` | 편집 유지, 오류 문구 `값을 찾을 수 없습니다` (parser 가 `undefined`) |
+| (빈 글자) | `owner` = `null` |
+| `홍길동` 그대로 | 변경 없음 |
+
+**선택 편집** — 목록에서 고르게 하려면 `editor` 에 사용자 객체 배열을 그대로 넘깁니다. 라벨은 위 `formatter`(이름), 현재 값 표시와 "같은 값" 판단은 `objectKey`(id)입니다.
+
+```typescript
+const ownerSelect: FieldDef = {
+  ...fields[1]!,
+  editor: { type: 'dropdown', options: users },  // 객체 배열 그대로 (options: EditorOption[] | CellObject[])
+};
+// 목록: 홍길동 / 김철수 / 김철수 / 이영희 — 1행을 열면 2번째(u2)가 선택 표시
+// 같은 u2 를 다시 고르면 변경 없음, 3번째(u3)를 고르면 owner = u3 객체
+```
+
+**점 표기 열 쓰기** — 최상위 객체를 복사해 바꾸므로 공유 객체를 쓰는 다른 행은 그대로입니다.
+
+```typescript
+await grid.changes.updateCellById(5, 'owner.team', 'Z');
+const { modified } = grid.changes.getAll();
+// 5행: fields ['owner'], data.owner = { id: 'u1', name: '홍길동', team: 'Z' }
+// 같은 객체를 공유하던 6행의 owner.team 은 'A' 그대로
+```
+
+**붙여넣기** — 1행 담당자 칸에서 담당자·수량 두 칸에 `이영희\t11\n없는사람\t22` 를 붙이면 1행은 담당자·수량이 모두 바뀌고, 2행은 담당자를 건너뛰고(parser 실패) 수량만 바뀝니다.
+
+> Worker 모드(`loader: { worker }`)에서는 `objectKey`·`sortValue` 를 경로 문자열(`'id'`, `'name'`)이나 등록 함수 참조로 쓰세요. 인라인 함수는 오류입니다.
+
+**JSON 편집기 (래퍼 `jsonEditor`)** — 정해진 모양이 없는 객체(설정·속성 등)는 JSON 으로 고칩니다. Vue/React `MozGrid` 는 `editor`·`mask.parser`·`displayKey` 가 없는 편집 가능한 객체 열에 자동으로 붙이고, 코어를 직접 쓸 때는 wrapper 에서 가져와 지정합니다.
+
+```typescript
+import { jsonEditor } from '@vmscloud/moz-ui-grid-wrapper';   // Vue/React 는 각 패키지에서 import
+
+const fields: FieldDef[] = [
+  { id: 'no', header: 'No', dataType: 'number' },
+  { id: 'meta', header: '속성', dataType: 'object', editor: jsonEditor() },
+];
+// meta = { color: 'red', tags: ['a'] } 인 칸을 더블클릭 → 줄을 나눈 JSON 이 팝업으로 열린다
+// '{"color": "blue"}' 로 고치고 Ctrl+Enter → meta = { color: 'blue' }
+// 내용을 모두 지우고 Ctrl+Enter → meta = null
+// '[1, 2]' 처럼 객체가 아니면 [적용]이 꺼지고, 창 밖을 누르면 원래 값 그대로
+```
+
+---
+
 ### grid.rows 사용 예제
 
 ```typescript
@@ -386,8 +514,9 @@ grid.on('column:reset', ({ columnId }) => {
 
 ```typescript
 // ── CRUD (Dirty State) ──
-const newId = await grid.changes.addRow({ name: '신규', age: 0 });
-await grid.changes.addRow({ name: '삽입', age: 25 }, 3); // 인덱스 3에 삽입
+const newId = await grid.changes.addRow({ name: '신규', age: 0 });          // 맨 끝
+await grid.changes.addRowByIndex({ name: '삽입', age: 25 }, 3);           // 원본 2번 행 바로 뒤
+await grid.changes.addRowAfterSelection({ name: '' }, { startEdit: true }); // 선택 행 아래 + 편집 시작
 
 // ById 패턴 (rowId 기반)
 await grid.changes.updateCellById('row-1', 'name', '수정됨');