Add sortIconBuilder to DataTable, PaginatedDataTable, and DataTableThemeData

[puneetkukreja98]

Description

This PR introduces a sortIconBuilder callback parameter to DataTable, PaginatedDataTable, and DataTableThemeData to allow full customization of the column sorting indicator icon and its visibility/orientation states.

Key Changes

• DataTableSortIconBuilder Typedef: Added typedef DataTableSortIconBuilder = Widget Function(BuildContext context, bool visible, bool ascending);.
• DataTable: Added sortIconBuilder property to DataTable. When provided, it overrides the default _SortArrow widget in table header cells.
• PaginatedDataTable: Added sortIconBuilder property and forwarded it down to the underlying DataTable.
• DataTableThemeData: Added sortIconBuilder property to allow setting a default custom sort icon builder globally across the app's theme. Theme fallback chain: DataTable.sortIconBuilder -> DataTableThemeData.sortIconBuilder -> default _SortArrow.

Fixes #91801

Usage Example

import 'package:flutter/material.dart';

void main() => runApp(const MaterialApp(home: DataTableSortDemo()));

class DataTableSortDemo extends StatefulWidget {
  const DataTableSortDemo({super.key});

  @override
  State<DataTableSortDemo> createState() => _DataTableSortDemoState();
}

class _DataTableSortDemoState extends State<DataTableSortDemo> {
  // Initially sorted by Column 0 (Name), Ascending
  int? _sortColumnIndex = 0;
  bool _sortAscending = true;

  // Pre-sorted list by Name
  final List<Map<String, dynamic>> _desserts = <Map<String, dynamic>>[
    <String, dynamic>{'name': 'Cupcake', 'calories': 305},
    <String, dynamic>{'name': 'Eclair', 'calories': 262},
    <String, dynamic>{'name': 'Frozen Yogurt', 'calories': 159},
    <String, dynamic>{'name': 'Ice Cream Sandwich', 'calories': 237},
  ];

  void _onSort(int columnIndex, bool ascending) {
    setState(() {
      _sortColumnIndex = columnIndex;
      _sortAscending = ascending;

      _desserts.sort((Map<String, dynamic> a, Map<String, dynamic> b) {
        final Comparable<dynamic> aValue = columnIndex == 0
            ? a['name']
            : a['calories'];
        final Comparable<dynamic> bValue = columnIndex == 0
            ? b['name']
            : b['calories'];
        return ascending
            ? Comparable.compare(aValue, bValue)
            : Comparable.compare(bValue, aValue);
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Initially Sorted DataTable')),
      body: Center(
        child: DataTable(
          sortColumnIndex: _sortColumnIndex,
          sortAscending: _sortAscending,
          sortIconBuilder:
              (BuildContext context, bool visible, bool ascending) {
                return Icon(
                  ascending ? Icons.arrow_upward : Icons.arrow_downward,
                  color: visible ? Colors.blue : Colors.grey,
                );
              },
          columns: <DataColumn>[
            DataColumn(label: const Text('Name'), onSort: _onSort),
            DataColumn(
              label: const Text('Calories'),
              numeric: true,
              onSort: _onSort,
            ),
          ],
          rows: _desserts.map<DataRow>((Map<String, dynamic> item) {
            return DataRow(
              cells: <DataCell>[
                DataCell(Text(item['name'].toString())),
                DataCell(Text(item['calories'].toString())),
              ],
            );
          }).toList(),
        ),
      ),
    );
  }
}

Working screen-shot:

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• 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.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

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

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. 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.

[gemini-code-assist]

Code Review

This pull request introduces a sortIconWidget property to DataTable and its internal _SortArrow widget, allowing developers to customize the sorting indicator icon in the table's header cells. It also adds corresponding tests to verify the behavior of the custom icon widget under different configurations. The reviewer suggests updating the documentation of sortIconWidget to clarify that custom widgets will undergo default animations and offsets, and recommends exposing this property in PaginatedDataTable for consistency.

[Piinks]

Once we settle on an API here, we should consider not only applying this to DataTable but also DataTableThemeData and PaginatedDataTable. :)

[puneetkukreja98]

Hi @Piinks, I have updated the PR as requested.

Summary of Updates:

• Added sortIconBuilder property to PaginatedDataTable and forwarded it to the underlying DataTable.
• Added sortIconBuilder property to DataTableThemeData to support global theme configuration.
• Added corresponding unit tests in paginated_data_table_test.dart and data_table_theme_test.dart.
• Updated the PR title and description to reflect the expanded scope.

This PR is ready for your re-review. Thank you!

[puneetkukreja98]

Hi @Piinks, I've pushed the latest updates. Please take a look when you get a chance.

Thanks!

[Piinks]

LGTM

[Piinks]

This PR is now ready to move over to flutter/packages!

See #188444 for guidance and git commands to help move the PR over. Thank you!

[puneetkukreja98]

@Piinks I've ported the changes to flutter/packages#12645. Please take a look.