From 5edec61f0e6db790bd10416e8691adf795959a37 Mon Sep 17 00:00:00 2001
From: Tong Mu <dkwingsmt@users.noreply.github.com>
Date: Thu, 1 Aug 2024 10:46:40 -0700
Subject: [PATCH] [CupertinoActionSheet & AlertDialog] Improve documentation
 and type for `scrollController` parameters (#152647)

This PR:
* Improves doc for `scrollController` parameters, replacing the unclear "typically unneeded" with better reasons.
* Makes `scrollController` non-nullable on private classes, since they're always provided by their parents.
* Remove a redundant parameter from a private class.
---
 .../flutter/lib/src/cupertino/dialog.dart     | 34 +++++++------------
 1 file changed, 13 insertions(+), 21 deletions(-)

diff --git a/packages/flutter/lib/src/cupertino/dialog.dart b/packages/flutter/lib/src/cupertino/dialog.dart
index 3c42b786cf..e3e754ba1e 100644
--- a/packages/flutter/lib/src/cupertino/dialog.dart
+++ b/packages/flutter/lib/src/cupertino/dialog.dart
@@ -260,8 +260,8 @@ class CupertinoAlertDialog extends StatefulWidget {
   /// A scroll controller that can be used to control the scrolling of the
   /// [content] in the dialog.
   ///
-  /// Defaults to null, and is typically not needed, since most alert messages
-  /// are short.
+  /// Defaults to null, which means the [CupertinoDialogAction] will create a
+  /// scroll controller internally.
   ///
   /// See also:
   ///
@@ -272,7 +272,8 @@ class CupertinoAlertDialog extends StatefulWidget {
   /// A scroll controller that can be used to control the scrolling of the
   /// actions in the dialog.
   ///
-  /// Defaults to null, and is typically not needed.
+  /// Defaults to null, which means the [CupertinoDialogAction] will create an
+  /// action scroll controller internally.
   ///
   /// See also:
   ///
@@ -397,7 +398,6 @@ class _CupertinoAlertDialogState extends State<CupertinoAlertDialog> {
                 );
           }
           final Widget scrolledActionsSection = _OverscrollBackground(
-            scrollController: _effectiveActionScrollController,
             color: backgroundColor,
             child: actionsSection,
           );
@@ -928,14 +928,15 @@ class CupertinoActionSheet extends StatefulWidget {
   /// A scroll controller that can be used to control the scrolling of the
   /// [message] in the action sheet.
   ///
-  /// This attribute is typically not needed, as alert messages should be
-  /// short.
+  /// Defaults to null, which means the [CupertinoActionSheet] will create a
+  /// scroll controller internally.
   final ScrollController? messageScrollController;
 
   /// A scroll controller that can be used to control the scrolling of the
   /// [actions] in the action sheet.
   ///
-  /// This attribute is typically not needed.
+  /// Defaults to null, which means the [CupertinoActionSheet] will create an
+  /// action scroll controller internally.
   final ScrollController? actionScrollController;
 
   /// The optional cancel button that is grouped separately from the other
@@ -1479,7 +1480,6 @@ class _Divider extends StatelessWidget {
 class _OverscrollBackground extends StatefulWidget {
   const _OverscrollBackground({
     required this.color,
-    required this.scrollController,
     required this.child,
   });
 
@@ -1488,7 +1488,6 @@ class _OverscrollBackground extends StatefulWidget {
   // This value must be a resolved color instead of, for example, a
   // CupertinoDynamicColor.
   final Color color;
-  final ScrollController? scrollController;
   final Widget child;
 
   @override
@@ -1571,7 +1570,7 @@ class _ActionSheetActionSection extends StatelessWidget {
   final int? pressedIndex;
   final Color dividerColor;
   final Color backgroundColor;
-  final ScrollController? scrollController;
+  final ScrollController scrollController;
 
   @override
   Widget build(BuildContext context) {
@@ -1624,7 +1623,7 @@ class _ActionSheetMainSheet extends StatelessWidget {
 
   final int? pressedIndex;
   final _PressedUpdateHandler onPressedUpdate;
-  final ScrollController? scrollController;
+  final ScrollController scrollController;
   final List<Widget> actions;
   final Widget? contentSection;
   final Color dividerColor;
@@ -1632,7 +1631,6 @@ class _ActionSheetMainSheet extends StatelessWidget {
   Widget _scrolledActionsSection(BuildContext context) {
     final Color backgroundColor = CupertinoDynamicColor.resolve(_kActionSheetBackgroundColor, context);
     return _OverscrollBackground(
-      scrollController: scrollController,
       color: backgroundColor,
       child: _ActionSheetActionSection(
         actions: actions,
@@ -1693,7 +1691,7 @@ class _CupertinoAlertContentSection extends StatelessWidget {
   const _CupertinoAlertContentSection({
     this.title,
     this.message,
-    this.scrollController,
+    required this.scrollController,
     this.titlePadding,
     this.messagePadding,
     this.titleTextStyle,
@@ -1716,10 +1714,7 @@ class _CupertinoAlertContentSection extends StatelessWidget {
 
   // A scroll controller that can be used to control the scrolling of the
   // content in the dialog.
-  //
-  // Defaults to null, and is typically not needed, since most alert contents
-  // are short.
-  final ScrollController? scrollController;
+  final ScrollController scrollController;
 
   // Paddings used around title and message.
   // CupertinoAlertDialog and CupertinoActionSheet have different paddings.
@@ -1805,10 +1800,7 @@ class _CupertinoAlertActionSection extends StatelessWidget {
 
   // A scroll controller that can be used to control the scrolling of the
   // actions in the dialog.
-  //
-  // Defaults to null, and is typically not needed, since most alert dialogs
-  // don't have many actions.
-  final ScrollController? scrollController;
+  final ScrollController scrollController;
 
   @override
   Widget build(BuildContext context) {