@agile-team/mach-table 0.31.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/mach-table",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Enterprise-grade, framework-agnostic TypeScript data grid with virtualization, editing, grouping and extensibility",
   "keywords": [
     "data-grid",
@@ -64,13 +64,80 @@
       }
     },
     "./styles/mach-table.css": {
-      "types": "./styles/mach-table.css.d.ts",
+      "types": "./dist/mach-table.css.d.ts",
       "default": "./dist/mach-table.css"
+    },
+    "./workbench": {
+      "import": {
+        "types": "./dist/workbench.d.ts",
+        "default": "./dist/workbench.js"
+      },
+      "require": {
+        "types": "./dist/workbench.d.cts",
+        "default": "./dist/workbench.cjs"
+      }
+    },
+    "./preferences": {
+      "import": {
+        "types": "./dist/preferences.d.ts",
+        "default": "./dist/preferences.js"
+      },
+      "require": {
+        "types": "./dist/preferences.d.cts",
+        "default": "./dist/preferences.cjs"
+      }
+    },
+    "./ordering": {
+      "import": {
+        "types": "./dist/ordering.d.ts",
+        "default": "./dist/ordering.js"
+      },
+      "require": {
+        "types": "./dist/ordering.d.cts",
+        "default": "./dist/ordering.cjs"
+      }
+    },
+    "./server-side": {
+      "import": {
+        "types": "./dist/server-side.d.ts",
+        "default": "./dist/server-side.js"
+      },
+      "require": {
+        "types": "./dist/server-side.d.cts",
+        "default": "./dist/server-side.cjs"
+      }
+    },
+    "./analysis": {
+      "import": {
+        "types": "./dist/analysis.d.ts",
+        "default": "./dist/analysis.js"
+      },
+      "require": {
+        "types": "./dist/analysis.d.cts",
+        "default": "./dist/analysis.cjs"
+      }
+    },
+    "./multi-range": {
+      "import": {
+        "types": "./dist/multi-range.d.ts",
+        "default": "./dist/multi-range.js"
+      },
+      "require": {
+        "types": "./dist/multi-range.d.cts",
+        "default": "./dist/multi-range.cjs"
+      }
+    },
+    "./styles/workbench.css": {
+      "types": "./dist/workbench.css.d.ts",
+      "default": "./dist/workbench.css"
+    },
+    "./styles/server-side.css": {
+      "types": "./dist/server-side.css.d.ts",
+      "default": "./dist/server-side.css"
     }
   },
   "files": [
-    "dist",
-    "styles/mach-table.css.d.ts"
+    "dist"
   ],
   "sideEffects": [
     "**/*.css"
@@ -81,5 +148,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\nMachTable 0.31.1 的框架无关 TypeScript Core：零运行时依赖，提供行列双虚拟化、领域化 API、单元格/整行编辑、树与分组、随机访问远程数据、区段隔离状态持久化和可诊断扩展系统。本版增加可配置整行颜色、完善主题化行拖拽与键盘排序，并修正树交互与列宽拖动反馈。\n\n```bash\npnpm add @agile-team/mach-table\n```\n\n```ts\nimport { createGrid, indexColumn } from \"@agile-team/mach-table\";\nimport \"@agile-team/mach-table/styles/mach-table.css\";\n\nconst api = createGrid(document.querySelector(\"#grid\")!, {\n  columnDefs: [\n    indexColumn({ headerName: \"序号\" }),\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`persistence.sections` 同时约束进入 store 的数据与恢复范围；异步 store 写入有序，晚到加载不会覆盖加载期间的用户操作。\n\n单元格编辑通过内置对勾/取消控件显式结束，普通鼠标和焦点变化不会误提交；Enter、Escape、Tab 仍提供完整键盘路径。筛选、列设置、上下文菜单和操作菜单会继承所属表格实例的主题变量，不受宿主页面全局样式影响。\n\n`loading: true` 默认展示轻量表格骨架与本地化状态文案，空数据默认展示内置插画；需要品牌化时再通过 `overlayLoadingTemplate`、`overlayNoRowsTemplate` 覆盖，基础页面无需重复实现 loading/empty DOM。\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## 行拖拽与条件整行颜色\n\n```ts\nimport { dragColumn, type GridOptions } from \"@agile-team/mach-table\";\n\ninterface Plan { id: string; name: string; status: string }\nconst options: GridOptions<Plan> = {\n  rowKey: \"id\",\n  columnDefs: [dragColumn(), { field: \"name\" }, { field: \"status\" }],\n  rowStyleRules: [\n    { when: ({ data }) => data.status === \"pending\", tone: \"warning\" },\n    { when: ({ data }) => data.status === \"failed\", tone: \"danger\" },\n    { when: ({ data }) => data.status === \"done\", tone: \"success\" }\n  ]\n};\n```\n\n状态码由应用定义，包内不识别业务状态。颜色规则取第一条命中结果，未命中时沿用默认样式；支持自定义背景/文字颜色、固定列、明暗主题、选择和虚拟行复用。拖拽提供主题手柄、落点线、位置浮层、边缘滚动、Esc 取消和 Alt + ↑/↓ 移动。扁平外部数据设置 `applyRowDrag: false`，由 `onRowDragEnd` 处理持久化；自动模式先完成移动再发出事件，使用 `targetIndex` 读取最终下标。树、分组及排序等自动模式限制见[完整配方](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/row-presentation.md)。\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"
+  "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.32.0 的框架无关 TypeScript Core：零运行时依赖，提供行列双虚拟化、领域化 API、单元格/整行编辑、树与分组、随机访问远程数据、区段隔离状态持久化和可诊断扩展系统。本版增加六个按需高级子入口，完善内部资源所有权、框架生命周期与缓存操作边界。\n\n```bash\npnpm add @agile-team/mach-table\n```\n\n```ts\nimport { createGrid, indexColumn } from \"@agile-team/mach-table\";\nimport \"@agile-team/mach-table/styles/mach-table.css\";\n\nconst api = createGrid(document.querySelector(\"#grid\")!, {\n  columnDefs: [\n    indexColumn({ headerName: \"序号\" }),\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`persistence.sections` 同时约束进入 store 的数据与恢复范围；异步 store 写入有序，晚到加载不会覆盖加载期间的用户操作。\n\n单元格编辑通过内置对勾/取消控件显式结束，普通鼠标和焦点变化不会误提交；Enter、Escape、Tab 仍提供完整键盘路径。筛选、列设置、上下文菜单和操作菜单会继承所属表格实例的主题变量，不受宿主页面全局样式影响。\n\n编辑、粘贴、清空和填充共用已有列校验与整行校验，批量输入按行提交并合并撤销记录，异步校验不会写回已替换的数据。随机块缓存淘汰后，未保存行仍可通过编辑 API 保存或回滚；完整替换数据与重新查询会清理旧作用域的状态。\n\n`loading: true` 默认展示轻量表格骨架与本地化状态文案，空数据默认展示内置插画；需要品牌化时再通过 `overlayLoadingTemplate`、`overlayNoRowsTemplate` 覆盖，基础页面无需重复实现 loading/empty DOM。\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## 行拖拽与条件整行颜色\n\n```ts\nimport { dragColumn, type GridOptions } from \"@agile-team/mach-table\";\n\ninterface Plan { id: string; name: string; status: string }\nconst options: GridOptions<Plan> = {\n  rowKey: \"id\",\n  columnDefs: [dragColumn(), { field: \"name\" }, { field: \"status\" }],\n  rowStyleRules: [\n    { when: ({ data }) => data.status === \"pending\", tone: \"warning\" },\n    { when: ({ data }) => data.status === \"failed\", tone: \"danger\" },\n    { when: ({ data }) => data.status === \"done\", tone: \"success\" }\n  ]\n};\n```\n\n状态码由应用定义，包内不识别业务状态。颜色规则取第一条命中结果，未命中时沿用默认样式；支持自定义背景/文字颜色、固定列、明暗主题、选择和虚拟行复用。拖拽提供主题手柄、落点线、位置浮层、边缘滚动、Esc 取消和 Alt + ↑/↓ 移动。扁平外部数据设置 `applyRowDrag: false`，由 `onRowDragEnd` 处理持久化；自动模式先完成移动再发出事件，使用 `targetIndex` 读取最终下标。树、分组及排序等自动模式限制见[完整配方](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/row-presentation.md)。\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\n## 按需高级入口（0.32）\n\n仍从本包导入，无需另装高级功能包。普通根入口不加载这些实现或附加 CSS。\n\n| 子路径 | 功能 |\n| --- | --- |\n| `/workbench` | 高级过滤草稿与应用、修改差异/部分保存/冲突审阅、手动诊断 |\n| `/preferences` | 复合身份隔离、CAS、有序写入、历史版本及列 ID/类型迁移报告 |\n| `/ordering` | 多行/树移动、防环与业务约束、失败回滚、持久化撤销/重做 |\n| `/server-side` | 服务端分组/聚合、route 分页、缓存/刷新/事务及层级选择 |\n| `/multi-range` | Ctrl/Cmd 追加范围、格式化复制、校验清空及撤销 |\n| `/analysis` | Pivot、安全公式、柱/折线图和数据表回退 |\n\n```ts\nimport { mountAdvancedFilterBuilder } from \"@agile-team/mach-table/workbench\";\nimport \"@agile-team/mach-table/styles/workbench.css\";\n\nconst filters = mountAdvancedFilterBuilder(host, { api });\n// 宿主卸载时调用；表格销毁也会释放工作台。\nfilters.destroy();\n```\n\n服务端分组控件使用 `/styles/server-side.css`，分析与多范围使用 `/styles/workbench.css`。排序、偏好和纯分析计算无需附加 CSS。服务端 Store 按 route 分页，不提供全树任意显示 offset；分析只处理当前已加载数据并显示范围。排序 undo/redo 的 transport 必须一次 CAS 保存 `context.operations` 的完整批次或 `context.plan.after`，只保存首参数无法完整恢复非连续/跨父级位置。\n\n完整示例与限制：[工作台](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/workbench.md) · [排序](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/row-presentation.md) · [企业偏好](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/enterprise-preferences.md) · [服务端 Store](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/server-side-store.md) · [多范围](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/multi-range.md) · [分析](https://github.com/ChenyCHENYU/MachTable/blob/main/docs/recipes/analysis.md)。\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"
 }