[two_dimensional_scrollables] Fix merged cells unmerging behind pinned spans (#11418)

This PR addresses an issue where merged cells in a `TableView` would "unmerge" or break when the first cell of the merge was scrolled into the area overlaid by a pinned row or column.

- Updated `RenderTableViewport` to expand the `_targetLeadingColumnPixel` and `_targetLeadingRowPixel` calculation to include the pinned extent. 
- Strengthened the documentation in `TableView` and `TableViewCell` to explicitly state that the same child and merge information **must** be returned from every vicinity in the merge to avoid unmerging when cells are culled due to lazy loading.

Fixes flutter/flutter#174862

## Pre-Review Checklist

**Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: Piinks

packages/two_dimensional_scrollables/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.4.2
+
+* Fixes an issue where merged cells would unmerge when the first cell was overlaid by a pinned row or column.
+
 ## 0.4.1
 
 * Adds warnings for TableView pinned rows and columns that exceed the viewport dimensions.

packages/two_dimensional_scrollables/lib/src/table_view/table.dart

@@ -28,11 +28,19 @@ import 'table_span.dart';
 /// and columns through merging. The table supports lazy rendering and will only
 /// instantiate those cells that are currently visible in the table's viewport
 /// and those that extend into the [cacheExtent]. Therefore, when merging cells
-/// in a [TableView], the same child must be returned from every vicinity the
-/// merged cell contains. The `build` method will only be called once for a
-/// merged cell, but since the table's children are lazily laid out, returning
-/// the same child ensures the merged cell can be built no matter which part of
-/// it is visible.
+/// in a [TableView], the same child with the same merge information must be
+/// returned from every vicinity the merged cell contains. The `build` method
+/// will only be called once for a merged cell, but since the table's children
+/// are lazily laid out, returning the same child and merge information ensures
+/// the merged cell can be built no matter which part of it is visible.
+///
+/// For example, if a cell is configured to span 3 columns, starting at column 1,
+/// the [cellBuilder] must return a [TableViewCell] with the same [child],
+/// [columnMergeStart] as 1, and [columnMergeSpan] as 3 for all three
+/// [TableVicinity]s (column 1, 2, and 3). If the merge information is only
+/// provided for the first vicinity (column 1), and that vicinity is scrolled
+/// out of the viewport and [cacheExtent], the table will not know the following
+/// vicinities (column 2 and 3) are part of a merge and will "unmerge" them.
 ///
 /// The layout of the table (e.g. how many rows/columns there are and their
 /// extents) as well as the content of the individual cells is defined by
@@ -380,7 +388,7 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
   // Where column layout begins, potentially outside of the visible area.
   double get _targetLeadingColumnPixel {
     return clampDouble(
-      horizontalOffset.pixels - cacheExtent,
+      horizontalOffset.pixels - math.max(_pinnedColumnsExtent, cacheExtent),
       0,
       double.infinity,
     );
@@ -398,7 +406,11 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
   bool get _rowsAreInfinite => delegate.rowCount == null;
   // Where row layout begins, potentially outside of the visible area.
   double get _targetLeadingRowPixel {
-    return clampDouble(verticalOffset.pixels - cacheExtent, 0, double.infinity);
+    return clampDouble(
+      verticalOffset.pixels - math.max(_pinnedRowsExtent, cacheExtent),
+      0,
+      double.infinity,
+    );
   }
 
   // How far rows should be laid out in a given frame.

packages/two_dimensional_scrollables/lib/src/table_view/table_cell.dart

@@ -95,11 +95,21 @@ class TableViewParentData extends TwoDimensionalViewportParentData {
 /// Creates a cell of the [TableView], along with information regarding merged
 /// cells and [RepaintBoundary]s.
 ///
-/// When merging cells in a [TableView], the same child should be returned from
-/// every vicinity the merged cell contains. The `build` method will only be
-/// called once for a merged cell, but since the table's children are lazily
-/// laid out, returning the same child ensures the merged cell can be built no
-/// matter which part of it is visible.
+/// When merging cells in a [TableView], the same child with the same merge
+/// information must be returned from every vicinity the merged cell contains.
+/// The `build` method will only be called once for a merged cell, but since
+/// the table's children are lazily laid out, returning the same child and merge
+/// information ensures the merged cell can be built no matter which part of it
+/// is visible.
+///
+/// For example, if a cell is configured to span 3 columns, starting at column 1,
+/// the `cellBuilder` of the [TableView] must return a [TableViewCell] with the
+/// same [child], [columnMergeStart] as 1, and [columnMergeSpan] as 3 for all
+/// three [TableVicinity]s (column 1, 2, and 3). If the merge information is
+/// only provided for the first vicinity (column 1), and that vicinity is
+/// scrolled out of the viewport and [cacheExtent], the table will not know the
+/// following vicinities (column 2 and 3) are part of a merge and will "unmerge"
+/// them.
 class TableViewCell extends StatelessWidget {
   /// Creates a widget that controls how a child of a [TableView] spans across
   /// multiple rows or columns.

packages/two_dimensional_scrollables/pubspec.yaml

@@ -1,6 +1,6 @@
 name: two_dimensional_scrollables
 description: Widgets that scroll using the two dimensional scrolling foundation.
-version: 0.4.1
+version: 0.4.2
 repository: https://github.com/flutter/packages/tree/main/packages/two_dimensional_scrollables
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+two_dimensional_scrollables%22+
 

packages/two_dimensional_scrollables/test/table_view/table_test.dart

@@ -4176,6 +4176,132 @@ void main() {
     },
   );
 
+  testWidgets(
+    'Merged cells should not unmerge when the first cell is overlaid by a pinned column',
+    (WidgetTester tester) async {
+      // Regression test for https://github.com/flutter/flutter/issues/174862
+      final horizontalController = ScrollController();
+      addTearDown(horizontalController.dispose);
+
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Scaffold(
+            body: SizedBox(
+              width: 400,
+              height: 400,
+              child: TableView.builder(
+                cacheExtent: 0.0,
+                horizontalDetails: ScrollableDetails.horizontal(
+                  controller: horizontalController,
+                ),
+                pinnedColumnCount: 1,
+                columnCount: 10,
+                rowCount: 10,
+                columnBuilder: (int index) => TableSpan(
+                  extent: FixedTableSpanExtent(index == 0 ? 100 : 50),
+                ),
+                rowBuilder: (int index) =>
+                    const TableSpan(extent: FixedTableSpanExtent(50)),
+                cellBuilder: (BuildContext context, TableVicinity vicinity) {
+                  final isColumn1 = vicinity.column == 1;
+                  return TableViewCell(
+                    columnMergeStart: isColumn1 ? 1 : null,
+                    columnMergeSpan: isColumn1 ? 3 : null,
+                    child: Center(
+                      child: Text('Cell ${vicinity.column},${vicinity.row}'),
+                    ),
+                  );
+                },
+              ),
+            ),
+          ),
+        ),
+      );
+
+      // Initially, column 1 is visible next to pinned column 0.
+      expect(find.text('Cell 1,0'), findsOneWidget);
+      // Column 2 and 3 should be part of the merge, so they are not built.
+      expect(find.text('Cell 2,0'), findsNothing);
+      expect(find.text('Cell 3,0'), findsNothing);
+
+      // Scroll horizontally so that column 1 is entirely behind pinned column 0.
+      // Pinned column 0 is 0 to 100.
+      // Unpinned content starts at 100 (Column 1).
+      // Scroll 100 pixels.
+      // Content at 0 (start of column 1) moves to absolute 100 - 100 = 0.
+      // Content at 50 (end of column 1) moves to absolute 100 + (50 - 100) = 50.
+      // So column 1 (0 to 50) is entirely covered by pinned column 0.
+      // Column 2 (50 to 100) is also covered.
+      // Column 3 (100 to 150) is the first visible in unpinned area.
+      horizontalController.jumpTo(100);
+      await tester.pump();
+
+      // With the fix, column 1 is still built because it is under the pinned area.
+      // Since column 1 is built, its merge info is found and applied to columns 2 and 3.
+      expect(find.text('Cell 1,0'), findsOneWidget);
+      expect(find.text('Cell 2,0'), findsNothing);
+      expect(find.text('Cell 3,0'), findsNothing);
+    },
+  );
+
+  testWidgets(
+    'Merged cells should not unmerge when the first cell is overlaid by a pinned row',
+    (WidgetTester tester) async {
+      final verticalController = ScrollController();
+      addTearDown(verticalController.dispose);
+
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Scaffold(
+            body: SizedBox(
+              width: 400,
+              height: 400,
+              child: TableView.builder(
+                cacheExtent: 0.0,
+                verticalDetails: ScrollableDetails.vertical(
+                  controller: verticalController,
+                ),
+                pinnedRowCount: 1,
+                columnCount: 10,
+                rowCount: 10,
+                columnBuilder: (int index) =>
+                    const TableSpan(extent: FixedTableSpanExtent(50)),
+                rowBuilder: (int index) => TableSpan(
+                  extent: FixedTableSpanExtent(index == 0 ? 100 : 50),
+                ),
+                cellBuilder: (BuildContext context, TableVicinity vicinity) {
+                  // Merged cell spanning rows 1, 2, and 3.
+                  final isRow1 = vicinity.row == 1;
+                  return TableViewCell(
+                    rowMergeStart: isRow1 ? 1 : null,
+                    rowMergeSpan: isRow1 ? 3 : null,
+                    child: Center(
+                      child: Text('Cell ${vicinity.column},${vicinity.row}'),
+                    ),
+                  );
+                },
+              ),
+            ),
+          ),
+        ),
+      );
+
+      // Initially, row 1 is visible below pinned row 0.
+      expect(find.text('Cell 0,1'), findsOneWidget);
+      expect(find.text('Cell 0,2'), findsNothing);
+      expect(find.text('Cell 0,3'), findsNothing);
+
+      // Scroll vertically so that row 1 is entirely behind pinned row 0.
+      verticalController.jumpTo(100);
+      await tester.pump();
+
+      // Row 1 should still be built, maintaining the merge.
+      expect(find.text('Cell 0,1'), findsOneWidget);
+      expect(find.text('Cell 0,2'), findsNothing);
+      expect(find.text('Cell 0,3'), findsNothing);
+    },
+  );
+
   testWidgets(
     'Table does not crash when focusing outside of the table while focused text field is not in the view',
     (WidgetTester tester) async {