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 it was
"Cancel". That's particularly helpful when the confirmation dialog
belongs 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 == SuggestedActionDialogResult.doAction) {
+                  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 == SuggestedActionDialogResult.doAction) {
+        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 == SuggestedActionDialogResult.doAction) {
+          unawaited(AppSettings.openAppSettings());
+        }
       } else {
         showErrorDialog(context: context,
           title: zulipLocalizations.errorDialogTitle,

lib/widgets/dialog.dart

@@ -19,13 +19,22 @@ Widget _dialogActionText(String text) {
 
 /// Tracks the status of a dialog, in being still open or already closed.
 ///
+/// For dialog interactions with multiple possible outcomes,
+/// pass for [T] an enum representing the possible outcomes
+/// (e.g., [SuggestedActionDialogResult]).
+///
 /// 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 the dialog interaction has multiple possible outcomes,
+  /// resolves with a [T] value representing the outcome of the interaction.
+  ///
+  /// See, e.g., [showSuggestedActionDialog] and [SuggestedActionDialogResult].
+  final Future<T> closed;
 }
 
 /// Displays an [AlertDialog] with a dismiss button
@@ -37,7 +46,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 +70,41 @@ DialogStatus showErrorDialog({
   return DialogStatus(future);
 }
 
-void showSuggestedActionDialog({
+DialogStatus<SuggestedActionDialogResult> 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<SuggestedActionDialogResult>(
     context: context,
     builder: (BuildContext context) => AlertDialog(
       title: Text(title),
       content: SingleChildScrollView(child: Text(message)),
       actions: [
         TextButton(
-          onPressed: () => Navigator.pop(context),
+          onPressed: () => Navigator.pop<SuggestedActionDialogResult>(context,
+            SuggestedActionDialogResult.cancel),
           child: _dialogActionText(zulipLocalizations.dialogCancel)),
         TextButton(
-          onPressed: () {
-            onActionButtonPress();
-            Navigator.pop(context);
-          },
+          onPressed: () => Navigator.pop<SuggestedActionDialogResult>(context,
+            SuggestedActionDialogResult.doAction),
           child: _dialogActionText(actionButtonText ?? zulipLocalizations.dialogContinue)),
       ]));
+  return DialogStatus(_wrapFutureExpectingNonNull(future));
+}
+
+enum SuggestedActionDialogResult {
+  cancel,
+  doAction,
+}
+
+Future<T> _wrapFutureExpectingNonNull<T>(Future<T?> future) {
+  return future.then((value) {
+    if (value == null) {
+      throw StateError('future unexpectedly completed with null');
+    }
+    return value;
+  });
 }

test/widgets/dialog_test.dart

@@ -26,4 +26,38 @@ 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(SuggestedActionDialogResult.doAction));
+    });
+
+    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(SuggestedActionDialogResult.cancel));
+    });
+  });
 }