From 9670bee734e6aab6237ea5a934ea9488d04ea99b Mon Sep 17 00:00:00 2001
From: biubiukam <biukam.w@gmail.com>
Date: Mon, 6 Jul 2026 22:01:09 +0800
Subject: [PATCH] fix: render group title for single-column lists

---
 ...-group-single-column_2026-07-06-13-55.json | 11 +++++
 .../listTable-group-single-column.test.ts     | 49 +++++++++++++++++++
 .../scenegraph/group-creater/cell-helper.ts   |  7 +--
 .../scenegraph/group-creater/column-helper.ts |  6 +--
 4 files changed, 67 insertions(+), 6 deletions(-)
 create mode 100644 common/changes/@visactor/vtable/fix-issue-5014-group-single-column_2026-07-06-13-55.json
 create mode 100644 packages/vtable/__tests__/layout/listTable-group-single-column.test.ts

diff --git a/common/changes/@visactor/vtable/fix-issue-5014-group-single-column_2026-07-06-13-55.json b/common/changes/@visactor/vtable/fix-issue-5014-group-single-column_2026-07-06-13-55.json
new file mode 100644
index 0000000000..0850a0da73
--- /dev/null
+++ b/common/changes/@visactor/vtable/fix-issue-5014-group-single-column_2026-07-06-13-55.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Render group title for single-column list tables.",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "biukam.w@gmail.com"
+}
diff --git a/packages/vtable/__tests__/layout/listTable-group-single-column.test.ts b/packages/vtable/__tests__/layout/listTable-group-single-column.test.ts
new file mode 100644
index 0000000000..e540c9be9a
--- /dev/null
+++ b/packages/vtable/__tests__/layout/listTable-group-single-column.test.ts
@@ -0,0 +1,49 @@
+// @ts-nocheck
+import { ListTable } from '../../src';
+import { createDiv } from '../dom';
+
+global.__VERSION__ = 'none';
+
+function collectText(graphic: any): string[] {
+  const result: string[] = [];
+  const children = graphic?.children ?? [];
+
+  for (const child of children) {
+    if (child.type === 'text') {
+      result.push(child.attribute?.text);
+    }
+    result.push(...collectText(child));
+  }
+
+  return result;
+}
+
+describe('listTable group single column', () => {
+  test('renders parent group title when there is only one data column', () => {
+    const containerDom: HTMLElement = createDiv();
+    containerDom.style.position = 'relative';
+    containerDom.style.width = '500px';
+    containerDom.style.height = '360px';
+
+    const table = new ListTable(containerDom, {
+      records: [
+        { category: 'Furniture', subCategory: 'Bookcases', value: 'Bookcase' },
+        { category: 'Furniture', subCategory: 'Chairs', value: 'Chair' }
+      ],
+      columns: [{ field: 'value', title: 'Value', width: 180 }],
+      widthMode: 'standard',
+      groupConfig: {
+        groupBy: ['category', 'subCategory'],
+        titleFieldFormat: record => `${record.vtableMergeName}(${record.children.length})`
+      }
+    });
+
+    const groupRecord = table.getCellRawRecord(0, 1);
+    expect(groupRecord.vtableMerge).toBe(true);
+
+    const text = collectText(table.scenegraph.getCell(0, 1, true));
+    expect(text).toContain('Furniture(2)');
+
+    table.release();
+  });
+});
diff --git a/packages/vtable/src/scenegraph/group-creater/cell-helper.ts b/packages/vtable/src/scenegraph/group-creater/cell-helper.ts
index 4268b776d6..b443c0b3c3 100644
--- a/packages/vtable/src/scenegraph/group-creater/cell-helper.ts
+++ b/packages/vtable/src/scenegraph/group-creater/cell-helper.ts
@@ -666,12 +666,12 @@ export function updateCell(
     isMerge = range.start.col !== range.end.col || range.start.row !== range.end.row;
   }
   let isVtableMerge = false;
-  if (table.internalProps.enableTreeNodeMerge && isMerge) {
+  if (table.internalProps.enableTreeNodeMerge && range) {
     const rawRecord = table.getCellRawRecord(range.start.col, range.start.row);
     const { vtableMergeName, vtableMerge } = rawRecord ?? {};
 
-    isVtableMerge = vtableMerge;
-    if (vtableMerge) {
+    isVtableMerge = vtableMerge && (isMerge || !table.isSeriesNumberInBody(col, row));
+    if (isVtableMerge) {
       mayHaveIcon = true;
       if ((table.internalProps as ListTableProtected).groupTitleCustomLayout) {
         customResult = dealWithCustom(
@@ -712,6 +712,7 @@ export function updateCell(
   if (
     !addNew &&
     !isMerge &&
+    !isVtableMerge &&
     !(define?.customLayout || define?.customRender || define?.headerCustomLayout || define?.headerCustomRender) &&
     (forceFastUpdate || canUseFastUpdate(col, row, oldCellGroup, autoWrapText, mayHaveIcon, table))
   ) {
diff --git a/packages/vtable/src/scenegraph/group-creater/column-helper.ts b/packages/vtable/src/scenegraph/group-creater/column-helper.ts
index 772d5b31ae..9896dd5fc1 100644
--- a/packages/vtable/src/scenegraph/group-creater/column-helper.ts
+++ b/packages/vtable/src/scenegraph/group-creater/column-helper.ts
@@ -169,12 +169,12 @@ export function createComplexColumn(
       }
     }
     let isVtableMerge = false;
-    if (table.internalProps.enableTreeNodeMerge && isMerge) {
+    if (table.internalProps.enableTreeNodeMerge && range) {
       const rawRecord = table.getCellRawRecord(range.start.col, range.start.row);
       const { vtableMergeName, vtableMerge } = rawRecord ?? {};
 
-      isVtableMerge = vtableMerge;
-      if (vtableMerge) {
+      isVtableMerge = vtableMerge && (isMerge || !table.isSeriesNumberInBody(col, row));
+      if (isVtableMerge) {
         mayHaveIcon = true;
         if ((table.internalProps as ListTableProtected).groupTitleCustomLayout) {
           customResult = dealWithCustom(