@vmscloud/moz-ui-grid-vue 0.2.17 → 0.2.19

package/docs/manual/runtime-contracts.md

@@ -26,28 +26,30 @@ import type { WorkerFunctionRef } from '@vmscloud/moz-ui-grid-core';
 const sumRef: WorkerFunctionRef = { workerFunction: 'app:sum', params: { factor: 1 } };
 ```
 
-`workerFunction`은 정적 등록 ID이며 `params`는 structured-clone 가능해야 합니다. 등록 함수는 기존 callback 인수 **뒤에** params를 받습니다. 계산 함수는 동기 함수여야 하며 Promise 반환은 오류입니다. 중복 등록 ID, 미등록 ID, Worker 계산 경계의 inline 함수는 오류입니다. Main 콜백 왕복이나 Main 계산 fallback으로 우회하지 않습니다.
+`workerFunction`은 정적 등록 ID이며 `params`는 structured-clone 가능해야 합니다. 등록 함수는 기존 callback 인수 **뒤에** params를 받습니다. 계산 함수는 동기 함수여야 하며 Promise 반환은 오류입니다. 중복 등록 ID, 미등록 ID, Worker 계산 경계의 inline 함수는 오류입니다. Main 콜백 왕복이나 Main 계산 fallback으로 우회하지 않습니다. 예외: XLSX export의 inline 함수 서식은 Worker로 함수를 보내지 않고, 위 Main 모드 inline 계약대로 Main이 청크를 보내기 전에 표시 문자열을 계산해 함께 보냅니다(Worker 실패 후 재계산이나 왕복 콜백이 아님 — 아래 표 'XLSX Worker formatter'). 또 하나의 예외: 열 `mask` 의 inline 함수(검색·표시값 필터·값 목록)는 Worker가 그 열의 고유값만 Main으로 보내고 Main이 `formatter(value)` 로 만든 '값 → 표시 글자 대조표'를 청크 단위로 돌려받아 씁니다(함수 본문은 Worker로 가지 않음, 값만으로 표시 글자가 정해진다는 계약 — [reference.md](reference.md) MaskConfig 절 'Worker 그리드의 inline 함수 mask').
 
-다음은 앱에서 빌드할 두 파일의 최소 예입니다. `/worker` entry는 import만으로 설치되지 않으므로 등록 뒤 `installProcessorWorker()`를 호출합니다.
+다음은 앱에서 빌드할 두 파일의 최소 예입니다. `/worker` entry는 import만으로는 아무 일도 하지 않으며, Worker 파일에서 `setupGridWorker()`를 호출해야 그리드 Worker가 됩니다.
 
 ```ts
-// app-grid.worker.ts
-import { DataLoader } from '@vmscloud/moz-ui-grid-core';
+// orders.worker.ts — 파일 이름은 자유
+import { DataLoader, setupGridWorker } from '@vmscloud/moz-ui-grid-core/worker';
 import type { Row } from '@vmscloud/moz-ui-grid-core';
-import { registerWorkerFunctions, installProcessorWorker } from '@vmscloud/moz-ui-grid-core/worker';
 
-class AppLoader extends DataLoader {
-  async fetchData(): Promise<Row[]> {
+class OrderLoader extends DataLoader {
+  async fetchAll(): Promise<Row[]> {
     const response = await fetch(String(this.params.url));
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     return response.json();
   }
 }
-registerWorkerFunctions({
-  'app:sum': (values: unknown[], _ctx: unknown, params: { factor: number }) =>
-    values.reduce<number>((sum, value) => sum + Number(value), 0) * params.factor,
+
+setupGridWorker({
+  loader: OrderLoader,
+  functions: {
+    'app:sum': (values: unknown[], _ctx: unknown, params: { factor: number }) =>
+      values.reduce<number>((sum, value) => sum + Number(value), 0) * params.factor,
+  },
 });
-installProcessorWorker({ loaders: { 'app:data': AppLoader } });
 ```
 
 ```ts
@@ -55,9 +57,10 @@ installProcessorWorker({ loaders: { 'app:data': AppLoader } });
 import { PureSheet } from '@vmscloud/moz-ui-grid-core';
 const grid = new PureSheet(container, {
   keyFields: ['id'],
-  useWorker: true,
-  workerFactory: () => new Worker(new URL('./app-grid.worker.ts', import.meta.url), { type: 'module' }),
-  loader: { module: 'app:data', params: { url: '/api/inventory' } },
+  loader: {
+    worker: () => new Worker(new URL('./orders.worker.ts', import.meta.url), { type: 'module' }),
+    params: { url: '/api/inventory' },
+  },
   fields: [{ id: 'id' }, { id: 'qty', dataType: 'number' }],
 });
 await grid.waitForReady();
@@ -68,7 +71,10 @@ grid.rows.addPinnedBottom({
 await grid.refresh();
 ```
 
-`LoaderConfig.module`의 타입은 `URL | string`이지만 현재 실행 경로는 그 문자열을 `loaders` map에서 찾습니다. 임의 URL을 동적으로 import하지 않습니다. URL을 쓴다면 등록 키가 그 문자열 표현과 정확히 같아야 합니다. loader 생성자는 `new () => DataLoader`이며 정적으로 import한 클래스를 map에 넣습니다. `workerFactory`는 PureSheet → GridCore → ProcessorFactory로 전달됩니다. Worker에서 직접 데이터를 로드하는 경계를 유지하세요.
+- `setupGridWorker({ loader, functions?, xlsxWorkerFactory? })`: Worker 파일 하나에 loader 클래스 하나를 지정합니다. `functions`의 키가 config의 `{ workerFunction: '키' }`가 가리키는 이름입니다. 여러 파일의 함수 묶음은 `{ ...common, ...orders }`처럼 펼쳐 넘깁니다(같은 키는 뒤 값이 덮어씁니다).
+- `loader.worker`: Worker를 만드는 함수입니다. 라이브러리는 앱의 Worker 파일을 알 수 없고, 번들러(Vite 등)는 앱 코드의 `new Worker(new URL(...), { type: 'module' })` 형태를 보고 Worker 번들을 만듭니다. `{ type: 'module' }`은 Worker 안에서 ES `import`를 쓰기 위한 옵션입니다.
+- 그리드 하나가 Worker 하나를 띄웁니다. `loader.worker`가 있으면 `data`/`loadData()`는 쓸 수 없고(PS502) 데이터는 Worker 안 loader가 공급합니다.
+- 메인 스레드에서 같은 loader를 쓰려면 `loader: { use: OrderLoader, params }`로 지정합니다. 이때 계산 함수는 config에 inline 함수로 그대로 씁니다.
 
 ### 지원 범위와 미지원
 
@@ -78,9 +84,9 @@ await grid.refresh();
 | 컬럼 `aggregate`, `rowGroupConfig.aggregates[].func`, pinned `aggregates[].func` | Worker 내부 집계. 등록 그룹 함수는 실제 멤버 values와 ctx를 받음. pinned 결과는 Main에서 재계산하지 않음 |
 | custom merge `getMergedRange` / `getMergedRanges` | 등록 참조 지원. pinned merge는 비동기 Worker 결과를 렌더/export 경로에서 사용 |
 | pivot 계산·집계·정렬 | 대응 callback 위치의 등록 참조 지원. 모든 callback property 이름이 동일한 것은 아니므로 각 타입을 따름 |
-| Worker 검색·컬럼 값 수집의 mask formatter | 등록 참조 실행 지원. 내장 mask는 recipe로 전달 |
+| Worker 검색·컬럼 값 수집의 mask formatter | 등록 참조 실행 지원. 내장 mask는 recipe로 전달. inline 함수 mask(필터에 주입된 열 mask 포함)는 Main이 만든 '값 → 표시 글자 대조표'로 처리(고유값만, 청크 5,000·Main 8ms 양보, (formatter, 열, 데이터 버전) 캐시) |
 | UI 표시 mask | 등록 formatter는 비동기 표시 coordinator를 통해 해석합니다. 표시 결과를 원본 데이터에 쓰지 않습니다. 편집 parser와 표시 formatter의 계약은 구분합니다. |
-| XLSX Worker formatter | processor XLSX session/transport를 통해 등록 함수를 실행합니다. Worker 실행 실패를 Main 계산으로 숨기지 않습니다. |
+| XLSX Worker formatter | 등록 참조는 processor XLSX session/transport를 통해 XLSX Worker 안에서 실행합니다. inline 함수 서식(일반 Main 모드 inline 계약)은 Main이 청크를 보내기 직전에 표시 문자열로 미리 계산해 청크와 함께 보내고, Worker는 글자만 씁니다(함수는 Worker로 보내지 않음, 결과는 `useWorker: false`와 같음). Worker→Main 왕복 콜백은 없습니다. Worker 실행 실패를 Main 계산으로 숨기지 않습니다. |
 
 DOM renderer와 일반 UI callback을 Worker 함수로 모두 치환하는 API가 아닙니다. 일반 Main inline 콜백은 유지됩니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmscloud/moz-ui-grid-vue",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "MozGrid - Vue 3 wrapping library for @vmscloud/moz-ui-grid-core",
   "license": "ISC",
   "type": "module",
@@ -65,6 +65,7 @@
     "directory": "components/frontend/moz-ui-grid/moz-ui-grid-vue"
   },
   "scripts": {
+    "setup": "bun install --cwd ../../.. --frozen-lockfile --filter @vmscloud/moz-ui-grid-core --filter @vmscloud/moz-ui-grid-wrapper --filter @vmscloud/moz-ui-grid-vue && bun run --cwd ../moz-ui-grid-core build && bun run --cwd ../moz-ui-grid-wrapper build:lib",
     "build": "vue-tsc --noEmit && vite build --config vite.config.lib.ts && node scripts/copy-docs.mjs",
     "build:lib": "vite build --config vite.config.lib.ts && node scripts/copy-docs.mjs",
     "docs:bundle": "node scripts/copy-docs.mjs",
@@ -76,7 +77,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "vue-tsc --noEmit",
-    "storybook": "bunx rimraf node_modules/.cache/storybook && storybook dev -p 6008",
+    "storybook": "node -e \"require('fs').rmSync('node_modules/.cache/storybook',{recursive:true,force:true})\" && storybook dev -p 6008",
     "build-storybook": "storybook build"
   },
   "dependencies": {