dialog [nfc]: showSuggestedActionDialog returns DialogStatus with result

With this API, we can use showSuggestedActionDialog in an "early
return" style -- await the user's choice, and early return if they
chose to dismiss the dialog. That's particularly helpful when the
confirmation dialog is opened in an `if` block.

We'll use this for the upcoming "edit message" feature (zulip#126), where
we plan to offer a confirmation dialog before entering an
edit-message session, but only if the compose box has text for a new
message in it (which would be discarded if the user wants to go
ahead).

Author: chrisbobbe

lib/widgets/app.dart

@@ -308,16 +308,17 @@ class ChooseAccountPage extends StatelessWidget {
         trailing: MenuAnchor(
           menuChildren: [
             MenuItemButton(
-              onPressed: () {
-                showSuggestedActionDialog(context: context,
+              onPressed: () async {
+                final dialog = showSuggestedActionDialog(context: context,
                   title: zulipLocalizations.logOutConfirmationDialogTitle,
                   message: zulipLocalizations.logOutConfirmationDialogMessage,
                   // TODO(#1032) "destructive" style for action button
-                  actionButtonText: zulipLocalizations.logOutConfirmationDialogConfirmButton,
-                  onActionButtonPress: () {
-                    // TODO error handling if db write fails?
-                    logOutAccount(GlobalStoreWidget.of(context), accountId);
-                  });
+                  actionButtonText: zulipLocalizations.logOutConfirmationDialogConfirmButton);
+                if (await dialog.closed == true) {
+                  if (!context.mounted) return;
+                  // TODO error handling if db write fails?
+                  unawaited(logOutAccount(GlobalStoreWidget.of(context), accountId));
+                }
               },
               child: Text(zulipLocalizations.chooseAccountPageLogOutButton)),
           ],

lib/widgets/compose_box.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:math';
 
 import 'package:app_settings/app_settings.dart';
@@ -907,13 +908,13 @@ Future<Iterable<_File>> _getFilePickerFiles(BuildContext context, FileType type)
       // If the user hasn't checked "Don't ask again", they can always dismiss
       // our prompt and retry, and the permissions request will reappear,
       // letting them grant permissions and complete the upload.
-      showSuggestedActionDialog(context: context,
+      final dialog = showSuggestedActionDialog(context: context,
         title: zulipLocalizations.permissionsNeededTitle,
         message: zulipLocalizations.permissionsDeniedReadExternalStorage,
-        actionButtonText: zulipLocalizations.permissionsNeededOpenSettings,
-        onActionButtonPress: () {
-          AppSettings.openAppSettings();
-        });
+        actionButtonText: zulipLocalizations.permissionsNeededOpenSettings);
+      if (await dialog.closed == true) {
+        unawaited(AppSettings.openAppSettings());
+      }
     } else {
       showErrorDialog(context: context,
         title: zulipLocalizations.errorDialogTitle,
@@ -1008,13 +1009,13 @@ class _AttachFromCameraButton extends _AttachUploadsButton {
         // permission-request alert once, the first time the app wants to
         // use a protected resource. After that, the only way the user can
         // grant it is in Settings.
-        showSuggestedActionDialog(context: context,
+        final dialog = showSuggestedActionDialog(context: context,
           title: zulipLocalizations.permissionsNeededTitle,
           message: zulipLocalizations.permissionsDeniedCameraAccess,
-          actionButtonText: zulipLocalizations.permissionsNeededOpenSettings,
-          onActionButtonPress: () {
-            AppSettings.openAppSettings();
-          });
+          actionButtonText: zulipLocalizations.permissionsNeededOpenSettings);
+        if (await dialog.closed == true) {
+          unawaited(AppSettings.openAppSettings());
+        }
       } else {
         showErrorDialog(context: context,
           title: zulipLocalizations.errorDialogTitle,

lib/widgets/dialog.dart

@@ -19,13 +19,29 @@ Widget _dialogActionText(String text) {
 
 /// Tracks the status of a dialog, in being still open or already closed.
 ///
+/// Use [T] to identify the outcome of the interaction:
+/// - Pass `void` for an informational dialog with just the option to dismiss.
+/// - For confirmation dialogs with an option to dismiss
+///   plus an option to proceed with an action, pass `bool`.
+///   The action button should pass true for Navigator.pop's `result` argument.
+/// - For dialogs with an option to dismiss plus multiple other options,
+///   pass a custom enum.
+/// For the latter two cases, a cancel button should call Navigator.pop
+/// with null for the `result` argument, to match what Flutter does
+/// when you dismiss the dialog by tapping outside its area.
+///
 /// See also:
 ///  * [showDialog], whose return value this class is intended to wrap.
-class DialogStatus {
+class DialogStatus<T> {
   const DialogStatus(this.closed);
 
   /// Resolves when the dialog is closed.
-  final Future<void> closed;
+  ///
+  /// If this completes with null, the dialog was dismissed.
+  /// Otherwise, completes with a [T] identifying the interaction's outcome.
+  ///
+  /// See, e.g., [showSuggestedActionDialog] and [SuggestedActionDialogResult].
+  final Future<T?> closed;
 }
 
 /// Displays an [AlertDialog] with a dismiss button
@@ -37,7 +53,7 @@ class DialogStatus {
 // [showDialog]'s return value, a [Future], inside [DialogStatus]
 // whose documentation can be accessed.  This helps avoid confusion when
 // intepreting the meaning of the [Future].
-DialogStatus showErrorDialog({
+DialogStatus<void> showErrorDialog({
   required BuildContext context,
   required String title,
   String? message,
@@ -61,28 +77,31 @@ DialogStatus showErrorDialog({
   return DialogStatus(future);
 }
 
-void showSuggestedActionDialog({
+/// Displays an alert dialog with a cancel button and an action button.
+///
+/// The [DialogStatus.closed] Future gives true if the action button was tapped.
+/// If the dialog was canceled,
+/// either with the cancel button or by tapping outside the dialog's area,
+/// it completes with null.
+DialogStatus<bool> showSuggestedActionDialog({
   required BuildContext context,
   required String title,
   required String message,
   required String? actionButtonText,
-  required VoidCallback onActionButtonPress,
 }) {
   final zulipLocalizations = ZulipLocalizations.of(context);
-  showDialog<void>(
+  final future = showDialog<bool>(
     context: context,
     builder: (BuildContext context) => AlertDialog(
       title: Text(title),
       content: SingleChildScrollView(child: Text(message)),
       actions: [
         TextButton(
-          onPressed: () => Navigator.pop(context),
+          onPressed: () => Navigator.pop<bool?>(context, null),
           child: _dialogActionText(zulipLocalizations.dialogCancel)),
         TextButton(
-          onPressed: () {
-            onActionButtonPress();
-            Navigator.pop(context);
-          },
+          onPressed: () => Navigator.pop<bool?>(context, true),
           child: _dialogActionText(actionButtonText ?? zulipLocalizations.dialogContinue)),
       ]));
+  return DialogStatus(future);
 }

test/widgets/dialog_test.dart

@@ -26,4 +26,51 @@ void main() {
         mode: LaunchMode.inAppBrowserView));
     });
   });
+
+  group('showSuggestedActionDialog', () {
+    testWidgets('tap action button', (tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(TestZulipApp());
+      await tester.pump();
+      final element = tester.element(find.byType(Placeholder));
+
+      final dialog = showSuggestedActionDialog(context: element,
+        title: 'Continue?',
+        message: 'Do the thing?',
+        actionButtonText: 'Sure');
+      await tester.pump();
+      await tester.tap(find.text('Sure'));
+      await check(dialog.closed).completes((it) => it.equals(true));
+    });
+
+    testWidgets('tap cancel', (tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(TestZulipApp());
+      await tester.pump();
+      final element = tester.element(find.byType(Placeholder));
+
+      final dialog = showSuggestedActionDialog(context: element,
+        title: 'Continue?',
+        message: 'Do the thing?',
+        actionButtonText: 'Sure');
+      await tester.pump();
+      await tester.tap(find.text('Cancel'));
+      await check(dialog.closed).completes((it) => it.equals(null));
+    });
+
+    testWidgets('tap outside dialog area', (tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(TestZulipApp());
+      await tester.pump();
+      final element = tester.element(find.byType(Placeholder));
+
+      final dialog = showSuggestedActionDialog(context: element,
+        title: 'Continue?',
+        message: 'Do the thing?',
+        actionButtonText: 'Sure');
+      await tester.pump();
+      await tester.tapAt(tester.getTopLeft(find.byType(TestZulipApp)));
+      await check(dialog.closed).completes((it) => it.equals(null));
+    });
+  });
 }