feat: support grouped grand totals by dimension

docs/assets/demo/en/data-analysis/pivot-analysis-total.md

@@ -9,7 +9,7 @@ option: PivotTable#dataConfig.totals
 
 # Pivot Analysis - Subtotal Total
 
-To summarize table data in pivot analysis, configure totals in dataConfig to set the total subtotal of the row and column dimensions.This example summary is always displayed to the bottom, and can also be displayed to the top through total.showGrandTotalsOnTop. [Configuration reference](../../option/PivotTable#dataConfig.totals)
+Configure `dataConfig.totals` to display subtotals and grand totals for row and column dimensions. In this example, row totals retain the original behavior, while `grandTotalDimensions: ['Segment']` groups the column grand total by `Segment` and appends an overall subtotal containing all groups. Row grand totals appear at the bottom by default and can be moved to the top with `showGrandTotalsOnTop`; column grand totals appear on the right and can be moved to the left with `showGrandTotalsOnLeft`. [Configuration reference](../../option/PivotTable#dataConfig.totals)
 
 ## Key Configurations
 
@@ -178,6 +178,7 @@ fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American
             showGrandTotals: true,
             showSubTotals: true,
             subTotalsDimensions: ['Region'],
+            grandTotalDimensions: ['Segment'],
             grandTotalLabel: 'Column Totals',
             subTotalLabel: 'Sub Totals'
           }

docs/assets/demo/zh/data-analysis/pivot-analysis-total.md

@@ -9,7 +9,7 @@ option: PivotTable#dataConfig.totals
 
 # 透视分析——小计总计
 
-透视分析表格数据汇总，dataConfig 中配置 totals 来设置行列维度的小计总计。该示例汇总总显示到底部，也可以通过 total.showGrandTotalsOnTop 来显示到顶部。[配置参考](../../option/PivotTable#dataConfig.totals)
+透视分析表格通过 `dataConfig.totals` 配置行列维度的小计和总计。本示例中，行方向保持原有的小计和总计效果；列方向通过 `grandTotalDimensions: ['Segment']`，让列总计在 `Segment` 维度下分组展示，并追加一个包含全部分组的整体小计。行总计默认显示在底部，可通过 `showGrandTotalsOnTop` 调整到顶部；列总计默认显示在右侧，可通过 `showGrandTotalsOnLeft` 调整到左侧。[配置参考](../../option/PivotTable#dataConfig.totals)
 
 ## 关键配置
 
@@ -178,6 +178,7 @@ fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American
             showGrandTotals: true,
             showSubTotals: true,
             subTotalsDimensions: ['Region'],
+            grandTotalDimensions: ['Segment'],
             grandTotalLabel: 'Column Totals',
             subTotalLabel: 'Sub Totals'
           }

docs/assets/guide/en/data_analysis/pivot_table_dataAnalysis.md

@@ -82,6 +82,7 @@ dataConfig: {
           showGrandTotals: true,
           showSubTotals: true,
           subTotalsDimensions: ['province'],
+          grandTotalDimensions: ['province'], // Group the grand total by province and append an overall subtotal
           grandTotalLabel: 'row total',
           subTotalLabel: 'Subtotal',
           showGrandTotalsOnTop: true, //totals show on top
@@ -99,6 +100,8 @@ dataConfig: {
     },
 ```
 
+`grandTotalDimensions` retains lower-level dimensions in the grand total area. For example, with the row dimensions `['region', 'province']` shown above, setting `grandTotalDimensions: ['province']` displays a total for each province under "row total" and appends an overall "Subtotal" row. The same option is available for column totals. Only dimensions after the first dimension on the current axis are supported. When omitted, VTable keeps the original single grand total.
+
 Online demo：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-total
 
 #### Custom summary data

docs/assets/guide/zh/data_analysis/pivot_table_dataAnalysis.md

@@ -82,6 +82,7 @@ dataConfig: {
           showGrandTotals: true,
           showSubTotals: true,
           subTotalsDimensions: ['province'],
+          grandTotalDimensions: ['province'], // 总计区域继续按 province 分组，并追加整体小计
           grandTotalLabel: '行总计',
           subTotalLabel: '小计',
           showGrandTotalsOnTop: true, //汇总值显示在上
@@ -99,6 +100,8 @@ dataConfig: {
     },
 ```
 
+`grandTotalDimensions` 用于在总计区域中保留下级维度。比如上述行维度为 `['region', 'province']` 时，将行总计配置为 `grandTotalDimensions: ['province']`，会在“行总计”下按省份分别显示汇总值，并追加一行整体“小计”。该配置也可用于列总计，只支持当前行或列方向首层之后的维度；不配置时仍显示原有的单一总计。
+
 具体示例：https://visactor.io/vtable/demo/data-analysis/pivot-analysis-total
 
 #### 自定义汇总数据

docs/assets/option/en/table/pivotChart.md

@@ -49,6 +49,10 @@ The currently supported data formats are, taking the sales of large supermarkets
 ]
 ```
 
+## dataConfig(IPivotTableDataConfig)
+
+PivotChart supports the PivotTable data analysis configuration. When totals are configured, use `totals.row.grandTotalDimensions` or `totals.column.grandTotalDimensions` to create grouped grand totals by retained lower-level dimensions.
+
 ## columnTree(Array)
 
 List header tree, type:`(IDimensionHeaderNode|IIndicatorHeaderNode)[]`. Among them, IDimensionHeaderNode refers to the dimension value node of the dimension non-indicator, and IIndicatorHeaderNode refers to the indicator name node.
@@ -240,4 +244,4 @@ chartDimensionLinkage: {
     }
   }
 }
-```
+```

docs/assets/option/en/table/pivotTable.md

@@ -225,6 +225,8 @@ export interface Total {
   showSubTotals: boolean;
   // Subtotal summary dimension definition
   subTotalsDimensions?: string[];
+  // Lower-level dimensions retained in the grand total area for grouped totals. Only dimensions after the first dimension on the current axis are supported.
+  grandTotalDimensions?: string[];
   //Default 'total'
   grandTotalLabel?: string;
   //Default 'Subtotal'

docs/assets/option/zh/table/pivotChart.md

@@ -49,6 +49,10 @@
 ]
 ```
 
+## dataConfig(IPivotTableDataConfig)
+
+透视图支持复用透视表的数据分析配置。配置总计时可使用 `totals.row.grandTotalDimensions` 或 `totals.column.grandTotalDimensions`，按保留的下级维度生成分组总计。
+
 ## columnTree(Array)
 
 列表头树，类型为:`(IDimensionHeaderNode|IIndicatorHeaderNode)[]`。其中 IDimensionHeaderNode 指的是维度非指标的维度值节点，IIndicatorHeaderNode 指的是指标名称节点。
@@ -247,4 +251,4 @@ chartDimensionLinkage: {
     }
   }
 }
-```
+```

docs/assets/option/zh/table/pivotTable.md

@@ -229,6 +229,8 @@ export interface Total {
   showSubTotals: boolean;
   // 小计汇总维度定义
   subTotalsDimensions?: string[];
+  // 总计中保留的下级维度，用于在总计区域内继续按维度分组；仅支持当前行/列方向首层之后的维度
+  grandTotalDimensions?: string[];
   // 默认'总计'
   grandTotalLabel?: string;
   // 默认'小计'

packages/vtable/__tests__/layout/get-data-cell-path.test.ts

@@ -7184,4 +7184,49 @@ describe('get-data-cell-path test', () => {
       cellLocation: 'body'
     });
   });
+
+  test('get-data-cell-path returns the grouped grand total path', () => {
+    const data = { organization: '公司一', type: '银票', balance: 100 };
+    const path = getDataCellPath(
+      {
+        rows: ['organization', 'type'],
+        columns: [],
+        indicators: [
+          {
+            indicatorKey: 'balance',
+            cellType: 'chart',
+            chartModule: 'vchart',
+            chartSpec: {
+              type: 'bar',
+              data: {
+                id: 'data'
+              },
+              xField: 'type',
+              yField: 'balance'
+            }
+          }
+        ],
+        indicatorsAsCol: false,
+        records: [data],
+        dataConfig: {
+          totals: {
+            row: {
+              showGrandTotals: true,
+              showGrandTotalsOnTop: true,
+              grandTotalDimensions: ['type'],
+              grandTotalLabel: '合计',
+              subTotalLabel: '小计'
+            }
+          }
+        }
+      },
+      data
+    );
+
+    expect(path?.rowHeaderPaths[0]).toMatchObject({
+      dimensionKey: 'organization',
+      value: '合计'
+    });
+    expect(path?.rowHeaderPaths[0].dataValue).toContain('grouped_grand_total');
+  });
 });

packages/vtable/__tests__/pivotChart.test.ts

@@ -9249,6 +9249,66 @@ function createTable(containerDom) {
   const tableInstance = new VTable.PivotChart(option);
   return tableInstance;
 }
+
+describe('pivotChart grouped grand total collected values', () => {
+  test('collects chart ranges under grouped grand total paths while ignoring external total records', () => {
+    const containerDom: HTMLElement = createDiv();
+    containerDom.style.position = 'relative';
+    containerDom.style.width = '500px';
+    containerDom.style.height = '500px';
+    const pivotChart = new VTable.PivotChart({
+      container: containerDom,
+      rows: ['organization', 'type'],
+      columns: [],
+      indicators: [
+        {
+          indicatorKey: 'balance',
+          cellType: 'chart',
+          chartModule: 'vchart',
+          chartSpec: {
+            type: 'bar',
+            data: {
+              id: 'data'
+            },
+            xField: 'type',
+            yField: 'balance'
+          }
+        }
+      ],
+      indicatorsAsCol: false,
+      records: [
+        { organization: '公司一', type: '银票', balance: 100 },
+        { organization: '公司二', type: '银票', balance: 300 },
+        { type: '银票', balance: 999 }
+      ],
+      dataConfig: {
+        totals: {
+          row: {
+            showGrandTotals: true,
+            grandTotalDimensions: ['type'],
+            grandTotalLabel: '合计',
+            subTotalLabel: '小计'
+          }
+        }
+      }
+    });
+    const groupedKey = `${String.fromCharCode(1)}vtable_grouped_grand_total${pivotChart.dataset.stringJoinChar}银票`;
+    const groupedSubtotalKey = `${String.fromCharCode(1)}vtable_grouped_grand_total${
+      pivotChart.dataset.stringJoinChar
+    }${String.fromCharCode(1)}vtable_grouped_grand_total_subtotal`;
+
+    expect(pivotChart.dataset.collectedValues.balance[groupedKey]).toMatchObject({
+      min: 400,
+      max: 400
+    });
+    expect(pivotChart.dataset.collectedValues.balance[groupedSubtotalKey]).toMatchObject({
+      min: 400,
+      max: 400
+    });
+    pivotChart.release();
+  });
+});
+
 describe('pivotChart init test', () => {
   const containerDom: HTMLElement = createDiv();
   containerDom.style.position = 'relative';