[two_dimensional_scrollables] Add alignment to TreeView and TableView (#11353)

This PR implements declarative alignment for the content of TableView and TreeView widgets when that content is smaller than the viewport extent. Users can now use the alignment property to center or otherwise position the entire table/tree within the viewport.
Alignment correctly reverts to start for axes that exceed viewport dimensions.

Fixes flutter/flutter#170349 

- TableView
   - Added an alignment property of type AlignmentGeometry (defaults to Alignment.topLeft).
   - Full support for both horizontal and vertical alignment.
   - Supports AlignmentDirectional to correctly handle TextDirection (LTR/RTL).
   - Works with pinned rows and columns, as well as reversed axis directions.

- TreeView
   - Added an alignment property of type AlignmentGeometry (defaults to Alignment.topLeft).
   - Caveat: Currently only supports the vertical component of the alignment. The tree remains
     aligned to the horizontal "start" to maintain consistent indentation logic and avoid layout
     jumps caused by dynamic, lazily-loaded node widths.

## 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.0
+
+* Added `alignment` property to `TableView` and `TreeView` to align content within the viewport when it is smaller than the viewport extent.
+
 ## 0.3.9
 
 * Fixes TableSpan borders being flipped when one or both axis directions are reversed.

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

@@ -116,6 +116,7 @@ class TableView extends TwoDimensionalScrollView {
     super.dragStartBehavior,
     super.keyboardDismissBehavior,
     super.clipBehavior,
+    this.alignment = Alignment.topLeft,
   });
 
   /// Creates a [TableView] of widgets that are created on demand.
@@ -155,6 +156,7 @@ class TableView extends TwoDimensionalScrollView {
     required TableSpanBuilder columnBuilder,
     required TableSpanBuilder rowBuilder,
     required TableViewCellBuilder cellBuilder,
+    this.alignment = Alignment.topLeft,
   }) : assert(pinnedRowCount >= 0),
        assert(rowCount == null || rowCount >= 0),
        assert(rowCount == null || rowCount >= pinnedRowCount),
@@ -199,6 +201,7 @@ class TableView extends TwoDimensionalScrollView {
     required TableSpanBuilder columnBuilder,
     required TableSpanBuilder rowBuilder,
     List<List<TableViewCell>> cells = const <List<TableViewCell>>[],
+    this.alignment = Alignment.topLeft,
   }) : assert(pinnedRowCount >= 0),
        assert(pinnedColumnCount >= 0),
        super(
@@ -211,6 +214,11 @@ class TableView extends TwoDimensionalScrollView {
          ),
        );
 
+  /// The alignment of the table within the viewport when there is extra space.
+  ///
+  /// Defaults to [Alignment.topLeft].
+  final AlignmentGeometry alignment;
+
   @override
   TableViewport buildViewport(
     BuildContext context,
@@ -226,6 +234,7 @@ class TableView extends TwoDimensionalScrollView {
       mainAxis: mainAxis,
       cacheExtent: cacheExtent,
       clipBehavior: clipBehavior,
+      alignment: alignment,
     );
   }
 }
@@ -245,8 +254,12 @@ class TableViewport extends TwoDimensionalViewport {
     required super.mainAxis,
     super.cacheExtent,
     super.clipBehavior,
+    this.alignment = Alignment.topLeft,
   });
 
+  /// The alignment of the table within the viewport when there is extra space.
+  final AlignmentGeometry alignment;
+
   @override
   RenderTwoDimensionalViewport createRenderObject(BuildContext context) {
     return RenderTableViewport(
@@ -259,6 +272,8 @@ class TableViewport extends TwoDimensionalViewport {
       clipBehavior: clipBehavior,
       delegate: delegate as TableCellDelegateMixin,
       childManager: context as TwoDimensionalChildManager,
+      alignment: alignment,
+      textDirection: Directionality.maybeOf(context),
     );
   }
 
@@ -275,7 +290,9 @@ class TableViewport extends TwoDimensionalViewport {
       ..mainAxis = mainAxis
       ..cacheExtent = cacheExtent
       ..clipBehavior = clipBehavior
-      ..delegate = delegate as TableCellDelegateMixin;
+      ..delegate = delegate as TableCellDelegateMixin
+      ..alignment = alignment
+      ..textDirection = Directionality.maybeOf(context);
   }
 }
 
@@ -299,7 +316,10 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
     required super.childManager,
     super.cacheExtent,
     super.clipBehavior,
-  });
+    AlignmentGeometry alignment = Alignment.topLeft,
+    TextDirection? textDirection,
+  }) : _alignment = alignment,
+       _textDirection = textDirection;
 
   @override
   TableCellDelegateMixin get delegate =>
@@ -309,6 +329,31 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
     super.delegate = value;
   }
 
+  /// The alignment of the table within the viewport when there is extra space.
+  AlignmentGeometry get alignment => _alignment;
+  AlignmentGeometry _alignment;
+  set alignment(AlignmentGeometry value) {
+    if (_alignment == value) {
+      return;
+    }
+    _alignment = value;
+    markNeedsLayout();
+  }
+
+  /// The text direction with which to resolve [alignment].
+  TextDirection? get textDirection => _textDirection;
+  TextDirection? _textDirection;
+  set textDirection(TextDirection? value) {
+    if (_textDirection == value) {
+      return;
+    }
+    _textDirection = value;
+    markNeedsLayout();
+  }
+
+  double _hAlignmentOffset = 0.0;
+  double _vAlignmentOffset = 0.0;
+
   // Skipped vicinities for the current frame based on merged cells.
   // This prevents multiple build calls for the same cell that spans multiple
   // vicinities.
@@ -852,6 +897,33 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
       _updateFirstAndLastVisibleCell();
     }
 
+    final Alignment resolvedAlignment = alignment.resolve(textDirection);
+    _hAlignmentOffset = 0.0;
+    if (!_columnsAreInfinite && _columnMetrics.isNotEmpty) {
+      final double totalWidth =
+          _pinnedColumnsExtent +
+          _columnMetrics[delegate.columnCount! - 1]!.trailingOffset;
+      if (totalWidth < viewportDimension.width) {
+        _hAlignmentOffset =
+            (viewportDimension.width - totalWidth) *
+            (resolvedAlignment.x + 1.0) /
+            2.0;
+      }
+    }
+
+    _vAlignmentOffset = 0.0;
+    if (!_rowsAreInfinite && _rowMetrics.isNotEmpty) {
+      final double totalHeight =
+          _pinnedRowsExtent +
+          _rowMetrics[delegate.rowCount! - 1]!.trailingOffset;
+      if (totalHeight < viewportDimension.height) {
+        _vAlignmentOffset =
+            (viewportDimension.height - totalHeight) *
+            (resolvedAlignment.y + 1.0) /
+            2.0;
+      }
+    }
+
     if (_firstNonPinnedCell == null &&
         _lastPinnedRow == null &&
         _lastPinnedColumn == null) {
@@ -862,19 +934,21 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
     final double? offsetIntoColumn = _firstNonPinnedColumn != null
         ? horizontalOffset.pixels -
               _columnMetrics[_firstNonPinnedColumn]!.leadingOffset -
-              _pinnedColumnsExtent
+              _pinnedColumnsExtent -
+              _hAlignmentOffset
         : null;
     final double? offsetIntoRow = _firstNonPinnedRow != null
         ? verticalOffset.pixels -
               _rowMetrics[_firstNonPinnedRow]!.leadingOffset -
-              _pinnedRowsExtent
+              _pinnedRowsExtent -
+              _vAlignmentOffset
         : null;
     if (_lastPinnedRow != null && _lastPinnedColumn != null) {
       // Layout cells that are contained in both pinned rows and columns
       _layoutCells(
         start: TableVicinity.zero,
         end: TableVicinity(column: _lastPinnedColumn!, row: _lastPinnedRow!),
-        offset: Offset.zero,
+        offset: Offset(-_hAlignmentOffset, -_vAlignmentOffset),
       );
     }
 
@@ -886,7 +960,7 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
       _layoutCells(
         start: TableVicinity(column: _firstNonPinnedColumn!, row: 0),
         end: TableVicinity(column: _lastNonPinnedColumn!, row: _lastPinnedRow!),
-        offset: Offset(offsetIntoColumn!, 0),
+        offset: Offset(offsetIntoColumn!, -_vAlignmentOffset),
       );
     }
     if (_lastPinnedColumn != null && _firstNonPinnedRow != null) {
@@ -897,7 +971,7 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
       _layoutCells(
         start: TableVicinity(column: 0, row: _firstNonPinnedRow!),
         end: TableVicinity(column: _lastPinnedColumn!, row: _lastNonPinnedRow!),
-        offset: Offset(0, offsetIntoRow!),
+        offset: Offset(-_hAlignmentOffset, offsetIntoRow!),
       );
     }
     if (_firstNonPinnedCell != null) {
@@ -1176,19 +1250,20 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
     // follows row or column major ordering. Here is slightly different
     // as we break the cells up into 4 main paint passes to clip for overlap.
 
+    final bool reversedH = axisDirectionIsReversed(horizontalAxisDirection);
+    final bool reversedV = axisDirectionIsReversed(verticalAxisDirection);
+
     if (_firstNonPinnedCell != null) {
       // Paint all visible un-pinned cells
       assert(_lastNonPinnedCell != null);
       _clipCellsHandle.layer = context.pushClipRect(
         needsCompositing,
         offset,
         Rect.fromLTWH(
-          axisDirectionIsReversed(horizontalAxisDirection)
-              ? 0.0
-              : _pinnedColumnsExtent,
-          axisDirectionIsReversed(verticalAxisDirection)
-              ? 0.0
-              : _pinnedRowsExtent,
+          (reversedH ? 0.0 : _pinnedColumnsExtent) +
+              (reversedH ? -_hAlignmentOffset : _hAlignmentOffset),
+          (reversedV ? 0.0 : _pinnedRowsExtent) +
+              (reversedV ? -_vAlignmentOffset : _vAlignmentOffset),
           viewportDimension.width - _pinnedColumnsExtent,
           viewportDimension.height - _pinnedRowsExtent,
         ),
@@ -1214,12 +1289,13 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
         needsCompositing,
         offset,
         Rect.fromLTWH(
-          axisDirectionIsReversed(horizontalAxisDirection)
-              ? viewportDimension.width - _pinnedColumnsExtent
-              : 0.0,
-          axisDirectionIsReversed(verticalAxisDirection)
-              ? 0.0
-              : _pinnedRowsExtent,
+          reversedH
+              ? viewportDimension.width -
+                    _pinnedColumnsExtent -
+                    _hAlignmentOffset
+              : _hAlignmentOffset,
+          (reversedV ? 0.0 : _pinnedRowsExtent) +
+              (reversedV ? -_vAlignmentOffset : _vAlignmentOffset),
           _pinnedColumnsExtent,
           viewportDimension.height - _pinnedRowsExtent,
         ),
@@ -1248,12 +1324,11 @@ class RenderTableViewport extends RenderTwoDimensionalViewport {
         needsCompositing,
         offset,
         Rect.fromLTWH(
-          axisDirectionIsReversed(horizontalAxisDirection)
-              ? 0.0
-              : _pinnedColumnsExtent,
-          axisDirectionIsReversed(verticalAxisDirection)
-              ? viewportDimension.height - _pinnedRowsExtent
-              : 0.0,
+          (reversedH ? 0.0 : _pinnedColumnsExtent) +
+              (reversedH ? -_hAlignmentOffset : _hAlignmentOffset),
+          reversedV
+              ? viewportDimension.height - _pinnedRowsExtent - _vAlignmentOffset
+              : _vAlignmentOffset,
           viewportDimension.width - _pinnedColumnsExtent,
           _pinnedRowsExtent,
         ),

packages/two_dimensional_scrollables/lib/src/tree_view/render_tree.dart

@@ -38,9 +38,13 @@ class RenderTreeViewport extends RenderTwoDimensionalViewport {
     required super.childManager,
     super.cacheExtent,
     super.clipBehavior,
+    AlignmentGeometry alignment = Alignment.topLeft,
+    TextDirection? textDirection,
   }) : _activeAnimations = activeAnimations,
        _rowDepths = rowDepths,
        _indentation = indentation,
+       _alignment = alignment,
+       _textDirection = textDirection,
        assert(indentation >= 0),
        assert(
          verticalAxisDirection == AxisDirection.down &&
@@ -56,6 +60,30 @@ class RenderTreeViewport extends RenderTwoDimensionalViewport {
     super.delegate = value;
   }
 
+  /// The alignment of the tree within the viewport when there is extra space.
+  AlignmentGeometry get alignment => _alignment;
+  AlignmentGeometry _alignment;
+  set alignment(AlignmentGeometry value) {
+    if (_alignment == value) {
+      return;
+    }
+    _alignment = value;
+    markNeedsLayout();
+  }
+
+  /// The text direction with which to resolve [alignment].
+  TextDirection? get textDirection => _textDirection;
+  TextDirection? _textDirection;
+  set textDirection(TextDirection? value) {
+    if (_textDirection == value) {
+      return;
+    }
+    _textDirection = value;
+    markNeedsLayout();
+  }
+
+  double _vAlignmentOffset = 0.0;
+
   /// The currently active [TreeViewNode] animations.
   ///
   /// Since the index of animating nodes can change at any time, the unique key
@@ -348,6 +376,19 @@ class RenderTreeViewport extends RenderTwoDimensionalViewport {
       _updateFirstAndLastVisibleRow();
     }
 
+    final Alignment resolvedAlignment = alignment.resolve(textDirection);
+    _vAlignmentOffset = 0.0;
+    if (_rowMetrics.isNotEmpty) {
+      final double totalHeight =
+          _rowMetrics[_rowMetrics.length - 1]!.trailingOffset;
+      if (totalHeight < viewportDimension.height) {
+        _vAlignmentOffset =
+            (viewportDimension.height - totalHeight) *
+            (resolvedAlignment.y + 1.0) /
+            2.0;
+      }
+    }
+
     if (_firstRow == null) {
       assert(_lastRow == null);
       return;
@@ -356,7 +397,9 @@ class RenderTreeViewport extends RenderTwoDimensionalViewport {
 
     _Span rowSpan;
     double rowOffset =
-        -verticalOffset.pixels + _rowMetrics[_firstRow!]!.leadingOffset;
+        -verticalOffset.pixels +
+        _rowMetrics[_firstRow!]!.leadingOffset +
+        _vAlignmentOffset;
     for (int row = _firstRow!; row <= _lastRow!; row++) {
       rowSpan = _rowMetrics[row]!;
       final double rowHeight = rowSpan.extent;
@@ -489,11 +532,11 @@ class RenderTreeViewport extends RenderTwoDimensionalViewport {
       final double trailingOffset =
           _rowMetrics[segment.trailingIndex]!.trailingOffset;
       final rect = Rect.fromPoints(
-        Offset(0.0, leadingOffset - verticalOffset.pixels),
+        Offset(0.0, leadingOffset - verticalOffset.pixels + _vAlignmentOffset),
         Offset(
           viewportDimension.width,
           math.min(
-            trailingOffset - verticalOffset.pixels,
+            trailingOffset - verticalOffset.pixels + _vAlignmentOffset,
             viewportDimension.height,
           ),
         ),