Merge branch develop into feat/filter-plugin-for-business

Author: skie1997

CLAUDE.md

@@ -64,6 +64,13 @@ git commit -m "type: description"
 - **packages/vtable-search**: Search capabilities
 - **packages/vtable-calendar**: Calendar component
 - **packages/vtable-sheet**: Spreadsheet functionality (current development branch)
+  - **项目特性**: 电子表格组件，支持多sheet tab页签管理
+  - **核心架构**:
+    - `workSheetInstances`: 管理所有sheet tab实例的核心容器
+    - `work-sheet`: 单个sheet页签的实现，包含对应vtable实例
+  - **依赖关系**: 依赖vtable核心插件系统，需先安装vtable插件
+  - **当前开发重点**: 跨sheet tab公式计算支持
+  - **技术实现**: 基于VTable核心库扩展，每个sheet对应独立的VTable实例
 - **packages/react-vtable**: React wrapper
 - **packages/vue-vtable**: Vue wrapper
 - **packages/openinula-vtable**: OpenInula wrapper
@@ -107,5 +114,95 @@ The library is built on a canvas-based rendering system using VRender:
 - Current branch: `feat/vtable-sheet` (spreadsheet functionality)
 - Main branches: `main`, `develop`
 - Node.js versions supported: 14.15.0+, 16.13.0+, 18.15.0+
-- to memorize
-- to memorize
+
+## vtable-sheet 项目详细信息
+
+### 项目路径
+`/Users/bytedance/VisActor/VTable/packages/vtable-sheet`
+
+### 核心功能需求
+- **跨sheet tab公式计算支持**: 实现不同sheet页签间的公式引用和计算
+- **多页签管理**: 支持创建、切换、删除sheet页签
+- **数据同步**: 确保跨sheet数据引用的实时更新
+
+### 技术架构
+- **核心入口**: vtable-sheet文件是整个组件的入口点
+- **实例管理**: workSheetInstances负责管理所有sheet实例
+- **单sheet实现**: 每个work-sheet包含独立的VTable实例
+- **插件依赖**: 依赖VTable核心插件系统提供基础功能
+
+### 跨Sheet公式功能实现
+
+#### 新增核心组件
+1. **CrossSheetFormulaManager** (`src/formula/cross-sheet-formula-manager.ts`)
+   - 管理跨Sheet公式引用关系
+   - 处理依赖关系映射和缓存
+   - 支持公式验证和错误处理
+
+2. **CrossSheetDataSynchronizer** (`src/formula/cross-sheet-data-synchronizer.ts`)
+   - 处理跨Sheet数据同步
+   - 支持批量数据更新
+   - 提供实时更新通知机制
+
+3. **CrossSheetFormulaValidator** (`src/formula/cross-sheet-formula-validator.ts`)
+   - 验证跨Sheet公式语法
+   - 检测循环依赖
+   - 提供详细的错误信息
+
+4. **CrossSheetFormulaHandler** (`src/formula/cross-sheet-formula-handler.ts`)
+   - 统一的跨Sheet公式处理接口
+   - 集成缓存、验证、同步功能
+   - 提供高性能的计算引擎
+
+#### 支持的公式类型
+- **基本引用**: `=Sheet1!A1`, `=Sheet2!B2:C4`
+- **函数计算**: `=SUM(Sheet1!A1:A10)`, `=AVERAGE(Sheet1!B1:B10)`
+- **跨表运算**: `=Sheet1!A1 + Sheet2!B1`
+- **条件判断**: `=IF(Sheet1!A1>100, "达标", "未达标")`
+- **复杂嵌套**: `=IF(AVERAGE(Sheet1!A1:A10)>50, SUM(Sheet1!B1:B10)*1.1, SUM(Sheet1!B1:B10))`
+
+#### 核心功能特性
+- ✅ **实时计算**: 源数据变化时自动更新依赖公式
+- ✅ **智能缓存**: 1秒TTL缓存机制，平衡性能与实时性
+- ✅ **错误处理**: 完善的错误检测和提示机制
+- ✅ **依赖管理**: 自动识别和管理跨Sheet依赖关系
+- ✅ **批量处理**: 支持批量公式计算和数据更新
+- ✅ **性能优化**: 异步处理，避免阻塞UI
+
+#### 使用示例
+```typescript
+// 设置跨Sheet公式
+const cell = { sheet: 'Summary', row: 1, col: 1 };
+const formula = '=SUM(SalesData!B2:E4)';
+await formulaManager.setCrossSheetFormula(cell, formula);
+
+// 获取计算结果
+const result = await formulaManager.getCrossSheetValue(cell);
+console.log(result.value); // 计算结果
+console.log(result.calculationTime); // 计算耗时
+
+// 验证公式
+const validation = formulaManager.validateCrossSheetFormula(cell);
+console.log(validation.valid); // 是否有效
+
+// 获取依赖关系
+const dependencies = formulaManager.getCrossSheetDependencies();
+```
+
+#### 测试覆盖
+- **单元测试**: `__tests__/cross-sheet-formula-simple.test.ts`
+- **集成测试**: `__tests__/integration/cross-sheet-integration.test.ts`
+- **演示页面**: `examples/cross-sheet-demo.html`
+- **使用文档**: `docs/cross-sheet-formula-guide.md`
+
+#### 性能指标
+- 100个跨Sheet公式计算 < 5秒
+- 20个公式批量重新计算 < 2秒
+- 缓存命中率 > 80%
+- 内存使用优化，支持大规模数据
+
+
+#### 使用限制
+- 跨Sheet公式目前主要用于读取操作，写入操作仍在原Sheet中进行
+- 复杂的跨Sheet引用可能需要异步处理以获得最佳性能
+- 循环依赖检测基于静态分析，运行时循环依赖需要额外的错误处理

README.md

@@ -192,7 +192,15 @@ $ rush update
 
 # ⭐️ Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=visactor/vtable&type=Date)](https://star-history.com/#visactor/vtable&Date)
+## Star History
+
+<a href="https://gitdata.xuanhun520.com/#visactor/vtable&Date">
+<picture >
+
+  <img style="width: 800px; height: 533px;" alt="Star History Chart" src="https://gitdata.xuanhun520.com/api/starimg?repos=visactor/vtable&type=Date&theme=dark" />
+</picture>
+</a>
+
 
 # 🤝 Contribution
 

common/changes/@visactor/vtable/4815-bug-pivotTable-tree-subTotal_2025-12-11-10-35.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: when pivot table set grid-tree subTotal value not show #4815\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

common/changes/@visactor/vtable/feat-cross-tab-formula_2025-12-12-03-16.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: vtable-sheet support cross sheet calculate formula\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

common/changes/@visactor/vtable/fix-delete_exit_edit_2025-12-16-10-58.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: delete key down should not complete edit cell\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

docs/assets/guide/en/cell_type/cellType.md

@@ -253,3 +253,72 @@ The following shows an example of `cellType: ()=>{}`: (Please refer to [Example]
     keepAspectRatio:true,
   }
 ```
+
+## Extension: Custom Column Types (TypeScript)
+
+In real-world applications, in addition to VTable’s built-in `cellType` values (such as `text`, `link`, `image`, `video`, `progressbar`, `sparkline`, and `chart`), it is often necessary to attach **business-specific configurations** to column definitions, for example:
+
+- Permission or visibility control: `permissionKey`
+- Tracking and analytics metadata: `trackId` / `trackParams`
+- Unified rendering strategy flags: `highlightOnNegative` / `useTagStyle`
+- DSL fields used by higher-level wrapper components: `renderAs` / `variant`
+
+These fields are usually **not consumed directly by VTable itself**. Instead, they are read and handled by business-layer abstractions, such as a unified `cellRender`, custom hooks, or column factory utilities.
+
+To support this use case, VTable provides a **type-level extension mechanism** that allows developers to extend `ColumnDefine` via TypeScript _module augmentation_. This enables defining custom column types with full type inference, validation, and IDE autocomplete support.
+
+### 1) Define a custom column type
+
+```ts
+import type { HeaderDefine } from '@visactor/vtable';
+
+// Custom column body definition (example: a customized button column)
+export interface IColoredButtonColumnBody {
+  cellType: 'button';
+  field: string;
+
+  /** Business-specific extension field: highlight when the value is negative */
+  highlightOnNegative?: boolean;
+
+  text?: string;
+  style?: any;
+}
+
+// Full column definition (Header + Body)
+export type ColoredButtonColumnDefine = IColoredButtonColumnBody & HeaderDefine;
+```
+
+### 2) Register the type via module augmentation
+
+```ts
+declare module '@visactor/vtable/es/ts-types' {
+  interface CustomColumnBodyDefineMap {
+    coloredButton: IColoredButtonColumnBody;
+  }
+
+  interface CustomColumnDefineMap {
+    coloredButtonColumn: ColoredButtonColumnDefine;
+  }
+}
+```
+
+### 3) Use the custom column type in `columns`
+
+```ts
+import type { ColumnsDefine } from '@visactor/vtable';
+
+const columns: ColumnsDefine = [
+  {
+    field: 'value',
+    title: 'Custom Button Column',
+    cellType: 'button',
+    text: 'check',
+    highlightOnNegative: true // ✅ extended field from CustomColumnDefineMap
+  }
+];
+```
+
+> **Note:**
+> The example above demonstrates a **type-level extension** only.
+> Whether fields such as `highlightOnNegative` produce actual visual or behavioral effects depends on business-side rendering logic (e.g., custom `cellRender`, hooks, or column factories).
+> VTable itself does not interpret or handle these fields automatically.

docs/assets/guide/zh/cell_type/cellType.md

@@ -254,4 +254,70 @@ VTable 所支持的数据类型共有 7 种，分别为：
     width:'auto',
     keepAspectRatio:true,
   }
-```
+```
+## 扩展：自定义列类型（TypeScript）
+
+在实际业务中，除了 VTable 内置的 `cellType`（text/link/image/video/progressbar/sparkline/chart 等），我们常常还需要在列定义里附加一些 **业务侧专用配置**，例如：
+
+- 权限/可见性控制：`permissionKey`
+- 埋点信息：`trackId` / `trackParams`
+- 统一渲染策略开关：`highlightOnNegative` / `useTagStyle`
+- 上层封装组件的 DSL 字段：`renderAs` / `variant`
+
+这些字段通常不会被 VTable 内部直接消费，而是由业务侧封装层（如统一的 `cellRender`、hook、列工厂函数等）读取并实现对应行为。
+
+为此，VTable 提供了一个 **类型扩展入口**，允许开发者通过 TypeScript 的 module augmentation（模块扩展）为 `ColumnDefine` 增加自定义列类型定义，从而获得完整的类型提示与校验能力。
+
+### 1）定义自定义列类型
+
+```ts
+import type { HeaderDefine } from '@visactor/vtable';
+
+// 自定义列 body 配置（示例：自定义按钮列）
+export interface IColoredButtonColumnBody {
+  cellType: 'button';
+  field: string;
+
+  /** 业务侧扩展字段：当值为负数时高亮 */
+  highlightOnNegative?: boolean;
+
+  text?: string;
+  style?: any;
+}
+
+// 完整列定义（Header + Body）
+export type ColoredButtonColumnDefine = IColoredButtonColumnBody & HeaderDefine;
+```
+
+### 2）通过模块扩展注册类型
+
+```ts
+declare module '@visactor/vtable/es/ts-types' {
+  interface CustomColumnBodyDefineMap {
+    coloredButton: IColoredButtonColumnBody;
+  }
+
+  interface CustomColumnDefineMap {
+    coloredButtonColumn: ColoredButtonColumnDefine;
+  }
+}
+```
+
+### 3）在 columns 中使用
+
+```ts
+import type { ColumnsDefine } from '@visactor/vtable';
+
+const columns: ColumnsDefine = [
+  {
+    field: 'value',
+    title: '自定义按钮列',
+    cellType: 'button',
+    text: 'check',
+    highlightOnNegative: true // ✅ 来自 CustomColumnDefineMap 的扩展字段
+  }
+];
+```
+
+> 注意：以上示例展示的是 **类型系统层面的扩展能力**。
+> `highlightOnNegative` 这类字段是否产生实际效果，需要由业务侧封装的渲染逻辑（例如自定义 `cellRender`、hook 或列工厂）去读取并执行。VTable 本身不会自动解析该字段。

packages/vtable-plugins/src/excel-edit-cell-keyboard.ts

@@ -75,7 +75,12 @@ export class ExcelEditCellKeyboardPlugin implements pluginsDefinition.IVTablePlu
       //判断是键盘触发编辑单元格的情况下，那么在编辑状态中切换方向需要选中下一个继续编辑
       if (this.table.editorManager.editingEditor && this.table.editorManager.beginTriggerEditCellMode === 'keydown') {
         const { col, row } = this.table.editorManager.editCell;
-        this.table.editorManager.completeEdit();
+        if (eventKey !== ExcelEditCellKeyboardResponse.BACKSPACE && eventKey !== ExcelEditCellKeyboardResponse.DELETE) {
+          this.table.editorManager.completeEdit();
+        } else {
+          //如果输入了删除或退格键，应正常删除输入框内容
+          return;
+        }
         this.table.getElement().focus();
         if (!event.shiftKey && !event.ctrlKey && !event.metaKey) {
           //有这些配合键，则不进行选中下一个单元格的行为 执行vtable内部逻辑

packages/vtable-plugins/src/table-series-number.ts

@@ -489,6 +489,10 @@ export class TableSeriesNumber implements pluginsDefinition.IVTablePlugin {
 
   syncRowHeightToComponent() {
     // console.log('syncRowHeightToComponent adjust', adjustStartRowIndex, adjustEndRowIndex);
+    const rowRange = this.table.getBodyVisibleRowRange();
+    if (!rowRange) {
+      return;
+    }
     const { rowStart, rowEnd } = this.table.getBodyVisibleRowRange();
     const adjustStartRowIndex = Math.max(rowStart - 2, this.table.frozenRowCount);
     const adjustEndRowIndex = Math.min(rowEnd + 2, this.table.rowCount - 1);