log: Support reportErrorToUser* helpers.

The imports in `lib/log.dart` are for the code references in
the reportErrorToUser* helpers' dart doc.

The motivation of having these set of helpers, rather than using
showErrorDialog and showSnackBar directly, is that we make displaying
errors more accessible in non-widget code.

Author: gnprice

lib/log.dart

@@ -1,3 +1,6 @@
+import 'package:flutter/material.dart';
+
+import 'widgets/app.dart';
 
 /// Whether [debugLog] should do anything.
 ///
@@ -30,3 +33,43 @@ bool debugLog(String message) {
   }());
   return true;
 }
+
+/// Display an error message in a [SnackBar].
+///
+/// This shows a [SnackBar] containing the message after [ZulipApp] becomes ready,
+/// otherwise logs it to the console.
+// This gets set in [ZulipApp].
+void Function(String message) get reportErrorToUserInSnackBar => (message) {
+  _debugLastReportedError = message;
+  _reportErrorToUserInSnackBar(message);
+};
+void Function(String message) _reportErrorToUserInSnackBar = _defaultReportErrorToUser;
+set reportErrorToUserInSnackBar(void Function(String message) value) => _reportErrorToUserInSnackBar = value;
+
+/// Display an error message in a dialog.
+///
+/// This shows a dialog containing the message after [ZulipApp] becomes ready,
+/// otherwise logs it to the console.
+// This gets set in [ZulipApp].
+void Function(String message) get reportErrorToUserInDialog => (message) {
+  _debugLastReportedError = message;
+  _reportErrorToUserInDialog(message);
+};
+void Function(String message) _reportErrorToUserInDialog = _defaultReportErrorToUser;
+set reportErrorToUserInDialog(void Function(String message) value) => _reportErrorToUserInDialog = value;
+
+String? get debugLastReportedError => _debugLastReportedError;
+String? _debugLastReportedError;
+String? debugTakeLastReportedError() {
+  final result = _debugLastReportedError;
+  _debugLastReportedError = null;
+  return result;
+}
+
+void _defaultReportErrorToUser(String message) {
+  // If this callback is still in place, then the app's widget tree
+  // hasn't mounted yet even as far as the [Navigator].
+  // So there's not much we can do to tell the user;
+  // just log, in case the user is actually a developer watching the console.
+  assert(debugLog(message));
+}

lib/widgets/app.dart

@@ -5,10 +5,12 @@ import 'package:flutter/material.dart';
 import 'package:flutter/scheduler.dart';
 import 'package:flutter_gen/gen_l10n/zulip_localizations.dart';
 
+import '../log.dart';
 import '../model/localizations.dart';
 import '../model/narrow.dart';
 import 'about_zulip.dart';
 import 'app_bar.dart';
+import 'dialog.dart';
 import 'inbox.dart';
 import 'login.dart';
 import 'message_list.dart';
@@ -92,9 +94,21 @@ class ZulipApp extends StatefulWidget {
   /// Useful in tests.
   final List<NavigatorObserver>? navigatorObservers;
 
+  static void _reportErrorToUserInSnackBar(String message) {
+    scaffoldMessenger?.showSnackBar(SnackBar(content: Text(message)));
+  }
+
+  static void _reportErrorToUserInDialog(String message) {
+    final context = navigatorKey.currentContext;
+    if (context == null) return;
+    showErrorDialog(context: context, title: 'Error', message: message);
+  }
+
   void _declareReady() {
     assert(navigatorKey.currentContext != null);
     _ready.value = true;
+    reportErrorToUserInSnackBar = _reportErrorToUserInSnackBar;
+    reportErrorToUserInDialog = _reportErrorToUserInDialog;
   }
 
   @override

test/widgets/app_test.dart

@@ -1,6 +1,7 @@
 import 'package:checks/checks.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:zulip/log.dart';
 import 'package:zulip/model/database.dart';
 import 'package:zulip/widgets/app.dart';
 import 'package:zulip/widgets/inbox.dart';
@@ -10,6 +11,7 @@ import '../example_data.dart' as eg;
 import '../flutter_checks.dart';
 import '../model/binding.dart';
 import '../test_navigation.dart';
+import 'dialog_checks.dart';
 import 'page_checks.dart';
 import 'test_app.dart';
 
@@ -169,5 +171,52 @@ void main() {
       check(ZulipApp.scaffoldMessenger).isNotNull();
       check(ZulipApp.ready).value.isTrue();
     });
+
+    testWidgets('reportErrorToUserBriefly shows snack bar', (tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(const ZulipApp());
+
+      final finder = find.descendant(
+        of: find.byType(SnackBar),
+        matching: find.text('test error message'));
+
+      // Prior to app startup, reportErrorToUserBriefly only logs.
+      reportErrorToUserInSnackBar('test error message');
+      check(ZulipApp.ready).value.isFalse();
+      await tester.pump();
+      check(debugTakeLastReportedError()).equals('test error message');
+      check(finder.evaluate()).isEmpty();
+
+      check(ZulipApp.ready).value.isTrue();
+      // After app startup, reportErrorToUserBriefly displays a snack bar.
+      reportErrorToUserInSnackBar('test error message');
+      await tester.pump();
+      check(finder.evaluate()).single;
+    });
+
+    testWidgets('reportErrorToUserInDialog shows dialog', (tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(const ZulipApp());
+
+      final finder = find.descendant(
+        of: find.byType(AlertDialog),
+        matching: find.text('test error message'));
+
+      // Prior to app startup, reportErrorToUserInDialog only logs.
+      reportErrorToUserInDialog('test error message');
+      check(ZulipApp.ready).value.isFalse();
+      await tester.pump();
+      check(debugTakeLastReportedError()).equals('test error message');
+      check(finder.evaluate()).isEmpty();
+
+      check(ZulipApp.ready).value.isTrue();
+      // After app startup, reportErrorToUserInDialog displays a dialog.
+      reportErrorToUserInDialog('test error message');
+      await tester.pump();
+      check(finder.evaluate()).single;
+      // Check the title too.
+      checkErrorDialog(tester,
+        expectedTitle: 'Error', expectedMessage: 'test error message');
+    });
   });
 }