[two_dimensional_scrollables] Add TableSpanPadding

[Piinks]

• Waiting on [two_dimensional_scrollables] Fix paint bug when rows/columns are pinned and axes are reversed #5038 first

---

Fixes flutter/flutter#134453
Also related: flutter/flutter#134655

This adds padding to TableSpans with TableSpanPadding. This affords folks a leading and trailing offset to pad rows and columns by.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter. (Unlike the flutter/flutter repo, the flutter/packages repo does use dart format.)
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I listed at least one issue that this PR fixes in the description above.
• I updated pubspec.yaml with an appropriate new version according to the pub versioning philosophy, or this PR is exempt from version changes.
• I updated CHANGELOG.md to add a description of the change, following repository CHANGELOG style.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

[Quijx]

The paddings for the TableSpans are useful for sure the way they are implemented here, but I think having a normal padding on the TableView that only applies to the outer sides of the table in addition would also be useful. For example in the app I showed in flutter/flutter#134453, I have a global padding defined in a theme extension that needs to be applied to every screen filling scrollable on each page. Or I could imagine a case where someone wants to use MediaQuery.paddingOf(context) to make room for system UI while still seeing the cells scroll below it. Integrating such a padding into the TableSpans would be a bit verbose:

@override
  Widget build(BuildContext context) {
    final padding = MediaQuery.paddingOf(context);
    const columnCount = 100;
    const rowCount = 100;
    return TableView.builder(
      cellBuilder: (context, vicinity) {
        return const Text('foo');
      },
      columnCount: columnCount,
      columnBuilder: (int column) => TableSpan(
        extent: const FixedTableSpanExtent(64),
        padding: TableSpanPadding(
          leading: column == 0 ? padding.left : 0.0,
          trailing: column == columnCount - 1 ? padding.right : 0.0,
        ),
      ),
      rowCount: rowCount,
      rowBuilder: (int row) => TableSpan(
        extent: FixedTableSpanExtent(64),
        padding: TableSpanPadding(
          leading: row == 0 ? padding.top : 0.0,
          trailing: row == rowCount - 1 ? padding.bottom : 0.0,
        ),
      ),
    );
  }

---

Also the TableSpanExtent should probably clarify in its doc that the colums/rows width/height that it describes does not include the padding.

[Piinks]

a normal padding on the TableView that only applies to the outer sides of the table in addition would also be useful

That can be achieved here by applying the appropriate padding to the first/last columns/rows. Additionally, you can always wrap the TableView with a padding widget. In general, we avoid enumerating padding properties on widgets when we have a Padding widget itself. :)

I could imagine a case where someone wants to use MediaQuery.paddingOf(context) to make room for system UI while still seeing the cells scroll below it

This sounds like a case for SafeArea!

Also the TableSpanExtent should probably clarify in its doc that the columns/rows width/height that it describes does not include the padding.

Good point! Thanks for the feedback!

[Quijx]

That can be achieved here by applying the appropriate padding to the first/last columns/rows.

Sure. This wouldn't make anything possible that wasn't possible before. It would just be a convenience feature and would make it consistent with other scrollable widgets such as ListView or GridView which also have a padding.

Additionally, you can always wrap the TableView with a padding widget.
This sounds like a case for SafeArea!

But wouldn't both a SafeArea or a wrapping Padding widget behave different from a build in padding the same way it is different in for example a ListView?

Padding widget around ListView:

screen-20231010-211917.2.mp4

padding attribute on ListView:

screen-20231010-212041.2.mp4

[Piinks]

Sure! I think we are talking about different things, I may have misunderstood. :)

[Piinks]

FYI @goderbauer, not ready for review yet.

[Piinks]

I realize I am packing a lot into this single golden file test, but I don't want to add more images to the repo when very soon I will be able to rewrite this into tests that use the mock canvas API when it reaches stable.

[goderbauer]

Assertion sounds dangerous. For me as a developer on my MegaPhone everything my look fine, but when my users run it on their TinyPhone things will be broken for them - and I never saw the assertion during development to warn me about this.

To really fix this, we probably need to do more than just an assertion. What do other implementations do if there isn't enough screen real estate to display all frozen rows/cols? Spreadsheet apps come to mind that we could check for their behavior (both on web and in their native app).

(This is of course not required to be resolved for this PR, having a TODO for this use case seems fine for now.)

[Piinks]

We discussed this offline and agreed we will pursue a non fatal warning here in the same way we do the render overflow error.

[goderbauer]

Just wondering if this could/should be

Suggested change

	TableSpanPadding? padding,
	this.padding = const TableSpanPadding(),

and then remove the padding initializer below?

[Piinks]

I had it this way originally, then when writing the sample code, I found it unfriendly. For example:

// Non-nullable
TableSpan(
  padding: someCondition ? TableSpanPadding(leading: 20) : TableSpanPadding(),
  // ...
)

versus

// Nullable, resolves to non nullable in field member assignment
TableSpan(
  padding: someCondition ? TableSpanPadding(leading: 20) : null,
  // ...
)

[goderbauer]

(I know we cannot do this here (yet) but I really wish this would be an interactive example so I can play with enabling/disabling consumeSpanPadding and see what it does.)

[goderbauer]

Could you explain to me how the padding is taken into account when calculating the start and end (input to this method) cells?

[goderbauer]

_Span.trailingOffset is used to calculate the start and end, which includes the padding. There are even tests for this case. Awesome!

[goderbauer]

LGTM