@agile-team/mach-table 0.23.0 → 0.24.0

package/dist/worker.d.cts

@@ -1 +1,47 @@
-export { ap as FieldDataProcessorOptions, ay as GridDataProcessor, az as GridDataProcessorColumn, aA as GridDataProcessorPayload, aB as GridDataProcessorRequest, aC as GridDataProcessorResult, aD as GridDataProcessorRow, aE as GridDataWorkerScope, aU as GridWorkerCancelMessage, aV as GridWorkerProcessMessage, aW as GridWorkerRequestMessage, aX as GridWorkerResponseMessage, bF as WorkerDataProcessorOptions, bK as createWorkerDataProcessor, bL as installGridDataWorker, bM as processFieldDataRequest } from './worker-DsFc5zec.cjs';
+import { ai as GridDataProcessorRequest, ag as GridDataProcessor, aj as GridDataProcessorResult } from './options-CnUx414l.cjs';
+export { ah as GridDataProcessorColumn, ak as GridDataProcessorRow } from './options-CnUx414l.cjs';
+
+type GridDataProcessorPayload<TData = any> = Omit<GridDataProcessorRequest<TData>, "signal">;
+interface GridWorkerProcessMessage<TData = any> {
+    type: "mach-table:process";
+    requestId: number;
+    payload: GridDataProcessorPayload<TData>;
+}
+interface GridWorkerCancelMessage {
+    type: "mach-table:cancel";
+    requestId: number;
+}
+type GridWorkerRequestMessage<TData = any> = GridWorkerProcessMessage<TData> | GridWorkerCancelMessage;
+type GridWorkerResponseMessage = {
+    type: "mach-table:result";
+    requestId: number;
+    rowIds: readonly string[];
+} | {
+    type: "mach-table:error";
+    requestId: number;
+    message: string;
+};
+interface WorkerDataProcessorOptions {
+    /** Terminate the lazily-created worker when the grid is destroyed. Defaults to true. */
+    terminateOnDestroy?: boolean;
+}
+interface FieldDataProcessorOptions {
+    /** Cooperative cancellation/yield granularity. Defaults to 2,000 rows. */
+    yieldEvery?: number;
+    isCancelled?: () => boolean;
+}
+/** Built-in serializable field-path processor intended to run inside an application Worker. */
+declare function processFieldDataRequest<TData = any>(request: GridDataProcessorPayload<TData>, options?: FieldDataProcessorOptions): Promise<GridDataProcessorResult>;
+interface GridDataWorkerScope {
+    addEventListener(type: "message", listener: (event: MessageEvent<GridWorkerRequestMessage>) => void): void;
+    postMessage(message: GridWorkerResponseMessage): void;
+}
+/** Installs the standard field-path protocol in a dedicated Worker module. */
+declare function installGridDataWorker(scope: GridDataWorkerScope): void;
+/**
+ * Adapts a dedicated Web Worker to GridDataProcessor without Blob URLs or eval.
+ * The host controls the worker URL, keeping CSP and bundler behavior explicit.
+ */
+declare function createWorkerDataProcessor<TData = any>(createWorker: () => Worker, options?: WorkerDataProcessorOptions): GridDataProcessor<TData>;
+
+export { type FieldDataProcessorOptions, GridDataProcessor, type GridDataProcessorPayload, GridDataProcessorRequest, GridDataProcessorResult, type GridDataWorkerScope, type GridWorkerCancelMessage, type GridWorkerProcessMessage, type GridWorkerRequestMessage, type GridWorkerResponseMessage, type WorkerDataProcessorOptions, createWorkerDataProcessor, installGridDataWorker, processFieldDataRequest };

package/dist/worker.d.ts

@@ -1 +1,47 @@
-export { ap as FieldDataProcessorOptions, ay as GridDataProcessor, az as GridDataProcessorColumn, aA as GridDataProcessorPayload, aB as GridDataProcessorRequest, aC as GridDataProcessorResult, aD as GridDataProcessorRow, aE as GridDataWorkerScope, aU as GridWorkerCancelMessage, aV as GridWorkerProcessMessage, aW as GridWorkerRequestMessage, aX as GridWorkerResponseMessage, bF as WorkerDataProcessorOptions, bK as createWorkerDataProcessor, bL as installGridDataWorker, bM as processFieldDataRequest } from './worker-DsFc5zec.js';
+import { ai as GridDataProcessorRequest, ag as GridDataProcessor, aj as GridDataProcessorResult } from './options-CnUx414l.js';
+export { ah as GridDataProcessorColumn, ak as GridDataProcessorRow } from './options-CnUx414l.js';
+
+type GridDataProcessorPayload<TData = any> = Omit<GridDataProcessorRequest<TData>, "signal">;
+interface GridWorkerProcessMessage<TData = any> {
+    type: "mach-table:process";
+    requestId: number;
+    payload: GridDataProcessorPayload<TData>;
+}
+interface GridWorkerCancelMessage {
+    type: "mach-table:cancel";
+    requestId: number;
+}
+type GridWorkerRequestMessage<TData = any> = GridWorkerProcessMessage<TData> | GridWorkerCancelMessage;
+type GridWorkerResponseMessage = {
+    type: "mach-table:result";
+    requestId: number;
+    rowIds: readonly string[];
+} | {
+    type: "mach-table:error";
+    requestId: number;
+    message: string;
+};
+interface WorkerDataProcessorOptions {
+    /** Terminate the lazily-created worker when the grid is destroyed. Defaults to true. */
+    terminateOnDestroy?: boolean;
+}
+interface FieldDataProcessorOptions {
+    /** Cooperative cancellation/yield granularity. Defaults to 2,000 rows. */
+    yieldEvery?: number;
+    isCancelled?: () => boolean;
+}
+/** Built-in serializable field-path processor intended to run inside an application Worker. */
+declare function processFieldDataRequest<TData = any>(request: GridDataProcessorPayload<TData>, options?: FieldDataProcessorOptions): Promise<GridDataProcessorResult>;
+interface GridDataWorkerScope {
+    addEventListener(type: "message", listener: (event: MessageEvent<GridWorkerRequestMessage>) => void): void;
+    postMessage(message: GridWorkerResponseMessage): void;
+}
+/** Installs the standard field-path protocol in a dedicated Worker module. */
+declare function installGridDataWorker(scope: GridDataWorkerScope): void;
+/**
+ * Adapts a dedicated Web Worker to GridDataProcessor without Blob URLs or eval.
+ * The host controls the worker URL, keeping CSP and bundler behavior explicit.
+ */
+declare function createWorkerDataProcessor<TData = any>(createWorker: () => Worker, options?: WorkerDataProcessorOptions): GridDataProcessor<TData>;
+
+export { type FieldDataProcessorOptions, GridDataProcessor, type GridDataProcessorPayload, GridDataProcessorRequest, GridDataProcessorResult, type GridDataWorkerScope, type GridWorkerCancelMessage, type GridWorkerProcessMessage, type GridWorkerRequestMessage, type GridWorkerResponseMessage, type WorkerDataProcessorOptions, createWorkerDataProcessor, installGridDataWorker, processFieldDataRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/mach-table",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Enterprise-grade, framework-agnostic TypeScript data grid with virtualization, editing, grouping and extensibility",
   "keywords": [
     "data-grid",
@@ -43,6 +43,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./adapter": {
+      "import": {
+        "types": "./dist/adapter.d.ts",
+        "default": "./dist/adapter.js"
+      },
+      "require": {
+        "types": "./dist/adapter.d.cts",
+        "default": "./dist/adapter.cjs"
+      }
+    },
     "./worker": {
       "import": {
         "types": "./dist/worker.d.ts",
@@ -71,5 +81,5 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage"
   },
-  "readme": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/ChenyCHENYU/MachTable/main/assets/mach-table-logo.svg\" alt=\"MachTable\" width=\"760\" />\n</p>\n\n# @agile-team/mach-table\n\nEnterprise-grade, framework-independent TypeScript data grid. Zero runtime dependencies, virtualized rows and columns, polished cell/full-row editing, async validation, action columns, change tracking, versioned state and resilient infinite loading.\n\n```bash\npnpm add @agile-team/mach-table\n```\n\n```ts\nimport { createGrid } from \"@agile-team/mach-table\";\nimport \"@agile-team/mach-table/styles/mach-table.css\";\n\nconst api = createGrid(document.querySelector(\"#grid\")!, {\n  columnDefs: [\n    { field: \"id\", headerName: \"ID\", width: 120 },\n    { field: \"name\", headerName: \"Name\", flex: 1, editable: true }\n  ],\n  rowData: [{ id: \"1\", name: \"MachTable\" }],\n  rowKey: \"id\",\n  enableColumnResize: true,\n  stateKey: \"customer-list\"\n});\n\n// Required for native integrations when the host is removed.\napi.destroy();\n```\n\nComplex business workflows use first-class APIs instead of adapter-specific glue:\n\n```ts\nconst state = api.getState();\nawait api.saveChanges((changes) => orderApi.save(changes));\napi.rollbackChanges();\nconsole.info(api.getDiagnostics());\n\nawait api.applyTransactionAsync({ update: realtimeRows });\napi.applyState(state);\n```\n\n0.23 adds governed domain APIs, incremental update invalidation and bounded remote-resource scheduling without removing the flat 0.x API:\n\n```ts\napi.batch((grid) => {\n  grid.rows.apply({ update: changedRows });\n  grid.columns.setVisible(\"internalNote\", false);\n  grid.refreshCells({ rowIds: changedIds, columns: [\"status\"] });\n});\n\nconsole.info(api.diagnostics.get().updates);\n```\n\nFor very large remote datasets, opt into random-access blocks. Sequential infinite loading remains the compatibility default:\n\n```ts\nconst options = {\n  datasource,\n  datasourceMode: \"block\" as const,\n  datasourceRowCount: 1_000_000,\n  blockSize: 200,\n  maxBlocksInCache: 12,\n  blockPrefetch: 1\n};\n\nawait api.rows.ensureLoaded(40_000, 40_200, { signal });\nconsole.info(api.rows.getCacheSnapshot());\n```\n\nWorker runtime helpers are intentionally split from the default entry:\n\n```ts\nimport { createWorkerDataProcessor, installGridDataWorker } from \"@agile-team/mach-table/worker\";\n```\n\n0.18 added governed runtime APIs, nested filters, named views, conflict-aware saves and performance evidence:\n\n```ts\nconst views = createGridViewManager(api, { scope: \"tenant:user:orders\" });\nawait views.save(\"My pending orders\");\n\nconst result = await api.saveChangesDetailed(orderApi.saveChanges);\nconsole.table(result.failures);\nconsole.table(result.conflicts);\nconsole.info(api.getDiagnostics().performance);\n```\n\n`GridState` v1 inputs migrate to v2 automatically. `GridFeature` manifests can declare `version`, `requires` and `conflicts`; invalid graphs are isolated before setup side effects run. JavaScript/JSON option patches are sanitized from the same metadata registry used by Core and framework adapters.\n\n0.13 added a built-in/headless column workbench and cancellable lazy trees:\n\n```ts\napi.openColumnWorkbench();\nconst columns = api.getColumnWorkbenchItems();\n\nconst treeOptions = {\n  treeData: true,\n  isTreeRowExpandable: ({ data }) => data.hasChildren,\n  loadTreeChildren: ({ data, signal }) => catalogApi.children(data.id, { signal })\n};\n```\n\nXLSX stays outside Core; install `@agile-team/mach-table-xlsx` only on Excel routes.\n\nPolished editing and row actions are built in rather than adapter-specific:\n\n```ts\nimport { rowActionsColumn } from \"@agile-team/mach-table\";\n\nconst options = {\n  editType: \"fullRow\" as const,\n  columnDefs: [\n    { field: \"name\", editable: true },\n    { field: \"age\", editable: true, cellEditor: \"number\" },\n    rowActionsColumn({ onView, onDelete, overflow: \"drawer\" })\n  ]\n};\n```\n\nCell mode remains the default and renders a subtle pencil plus inline confirm/cancel controls. Use `editableIndicator: \"always\" | \"hover\" | \"none\"` to match the page density.\n\n0.14 removes common page glue with automatic GridState persistence, an explicit error overlay, compact row keys and framework-neutral toolbar commands:\n\n```ts\nimport { createMachTableCommands } from \"@agile-team/mach-table\";\n\nconst commands = createMachTableCommands({ getApi: () => api });\ncommands.search(\"pending\");\nawait commands.refresh();\n\napi.setOverlay(\"error\", () => \"Request failed. Please retry.\");\n```\n\n`rowKey: \"id\"` is shorthand for a stable field path; `getRowId` remains available for derived IDs and wins when both are present. `domLayout: \"autoHeight\"` is intended only for small client-side tables—normal virtual layout remains the large-data default.\n\nColumn resizing is deliberately opt-in. Set `enableColumnResize: true`; add `stateKey` to remember the complete workspace, or `columnStateKey` to remember only widths/order/visibility/pinning/sort. Pointer cancellation rolls back, completed drags persist once, and untouched automatic/flex columns remain responsive.\n\nFor framework applications use the official adapters:\n\n- Vue 3: [`@agile-team/mach-table-vue`](https://www.npmjs.com/package/@agile-team/mach-table-vue)\n- React 18+: [`@agile-team/mach-table-react`](https://www.npmjs.com/package/@agile-team/mach-table-react)\n\nDocumentation: [Quick start](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/getting-started.md) · [Enterprise integration](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/enterprise-integration.md) · [API](https://github.com/ChenyCHENYU/MachTable/tree/main/docs/api)\n\n> Overlay strings render as text by default. Prefer HTMLElement factories for rich content; enable `allowUnsafeOverlayHtml` only for fully trusted static markup.\n\nSource-available © ChenyCHENYU (Agile Team). Any use requires prior written authorization. See the [license](https://github.com/ChenyCHENYU/MachTable/blob/main/LICENSE) and [authorization process](https://github.com/ChenyCHENYU/MachTable/blob/main/LICENSING.md).\n"
+  "readme": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/ChenyCHENYU/MachTable/main/assets/mach-table-logo.svg\" alt=\"MachTable\" width=\"760\" />\n</p>\n\n# @agile-team/mach-table\n\nMachTable 0.24 的框架无关 TypeScript Core：零运行时依赖，提供行列双虚拟化、领域化 API、单元格/整行编辑、树与分组、随机访问远程数据、状态持久化和可诊断扩展系统。\n\n```bash\npnpm add @agile-team/mach-table\n```\n\n```ts\nimport { createGrid } from \"@agile-team/mach-table\";\nimport \"@agile-team/mach-table/styles/mach-table.css\";\n\nconst api = createGrid(document.querySelector(\"#grid\")!, {\n  columnDefs: [\n    { field: \"id\", headerName: \"ID\", width: 120 },\n    { field: \"name\", headerName: \"名称\", flex: 1, editable: true }\n  ],\n  rowData: [{ id: \"1\", name: \"MachTable\" }],\n  rowKey: \"id\",\n  enableColumnResize: true,\n  persistence: { key: \"tenant:user:customers\", sections: [\"columns\"] }\n});\n\napi.batch((grid) => {\n  grid.rows.transact({ update: [{ id: \"1\", name: \"Updated\" }] });\n  grid.columns.setVisible(\"internalNote\", false);\n  grid.view.refreshCells({ rowIds: [\"1\"] });\n});\n\nconst saved = await api.editing.save(orderApi.saveChanges);\nconsole.table(saved.conflicts);\nconsole.info(api.diagnostics.get());\n\n// 原生宿主卸载时必须销毁；Vue/React 适配器会自动处理。\napi.destroy();\n```\n\n公共命令按 `rows`、`columns`、`selection`、`editing`、`filtering`、`sorting`、`pagination`、`hierarchy`、`view`、`state`、`io`、`diagnostics` 划分。完整签名见 [GridApi](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/api/grid-api.md)。\n\n大型本地数据 Worker 使用独立入口：\n\n```ts\nimport { createWorkerDataProcessor } from \"@agile-team/mach-table/worker\";\n```\n\nVue/React 项目请只安装对应适配包，它会自动安装并重导出 Core：\n\n- [@agile-team/mach-table-vue](https://www.npmjs.com/package/@agile-team/mach-table-vue)\n- [@agile-team/mach-table-react](https://www.npmjs.com/package/@agile-team/mach-table-react)\n\n文档：[快速开始](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/getting-started.md) · [企业接入](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/guide/enterprise-integration.md) · [API](https://github.com/ChenyCHENYU/MachTable/tree/main/docs/api)\n\nSource-available © ChenyCHENYU (Agile Team). 任何使用均须事先取得书面授权。详见 [LICENSE](https://github.com/ChenyCHENYU/MachTable/blob/main/LICENSE) 与[授权流程](https://github.com/ChenyCHENYU/MachTable/blob/main/LICENSING.md)。\n"
 }