model: Add TypingNotifier

The debugEnable setup is borrowed from
debugEnableRegisterNotificationToken. This acts as a hook to
temporarily disable typing notices in later widget tests.

The documentation and implementation are based on the web app:

  https://github.com/zulip/zulip/blob/52a9846cdf4abfbe937a94559690d508e95f4065/web/shared/src/typing_status.ts

We do not expose Futures with keystroke/stopComposing.  Because the
caller shouldn't need to wait for the underlying API request to
finish.

Perhaps one nice thing we can do is defining a TypingNotifier mixin
and add that to both PerAccountStore and TypingNotifier, similar to
ChannelStore.  But TypingNotifier is not complicated enough for that
to be worthwhile.

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

lib/model/store.dart

@@ -277,6 +277,13 @@ class PerAccountStore extends ChangeNotifier with EmojiStore, ChannelStore, Mess
       accountId: accountId,
       selfUserId: account.userId,
       userSettings: initialSnapshot.userSettings,
+      typingNotifier: TypingNotifier(
+        connection: connection,
+        typingStoppedWaitPeriod: Duration(
+          milliseconds: initialSnapshot.serverTypingStoppedWaitPeriodMilliseconds),
+        typingStartedWaitPeriod: Duration(
+          milliseconds: initialSnapshot.serverTypingStartedWaitPeriodMilliseconds),
+      ),
       users: Map.fromEntries(
         initialSnapshot.realmUsers
         .followedBy(initialSnapshot.realmNonActiveUsers)
@@ -311,6 +318,7 @@ class PerAccountStore extends ChangeNotifier with EmojiStore, ChannelStore, Mess
     required this.accountId,
     required this.selfUserId,
     required this.userSettings,
+    required this.typingNotifier,
     required this.users,
     required this.typingStatus,
     required ChannelStoreImpl channels,
@@ -413,6 +421,8 @@ class PerAccountStore extends ChangeNotifier with EmojiStore, ChannelStore, Mess
 
   final UserSettings? userSettings; // TODO(server-5)
 
+  final TypingNotifier typingNotifier;
+
   ////////////////////////////////
   // Users and data about them.
 
@@ -493,6 +503,7 @@ class PerAccountStore extends ChangeNotifier with EmojiStore, ChannelStore, Mess
     unreads.dispose();
     _messages.dispose();
     typingStatus.dispose();
+    typingNotifier.dispose();
     updateMachine?.dispose();
     connection.close();
     _disposed = true;

lib/model/typing_status.dart

@@ -2,7 +2,10 @@ import 'dart:async';
 
 import 'package:flutter/foundation.dart';
 
+import '../api/core.dart';
 import '../api/model/events.dart';
+import '../api/route/typing.dart';
+import 'binding.dart';
 import 'narrow.dart';
 
 /// The model for tracking the typing status organized by narrows.
@@ -84,3 +87,148 @@ class TypingStatus extends ChangeNotifier {
     }
   }
 }
+
+/// Sends the self-user's typing-status updates.
+///
+/// See also:
+///  * https://github.com/zulip/zulip/blob/52a9846cdf4abfbe937a94559690d508e95f4065/web/shared/src/typing_status.ts
+///  * https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html
+class TypingNotifier {
+  TypingNotifier({
+    required this.connection,
+    required this.typingStoppedWaitPeriod,
+    required this.typingStartedWaitPeriod,
+  });
+
+  final ApiConnection connection;
+  final Duration typingStoppedWaitPeriod;
+  final Duration typingStartedWaitPeriod;
+
+  SendableNarrow? _currentDestination;
+
+  /// Records time elapsed since the last time we notify the server;
+  /// this is `null` when the user is not actively typing.
+  Stopwatch? _sinceLastPing;
+
+  /// A timer that resets on every [keystroke].
+  ///
+  /// Upon its expiry, the user is considered idle and
+  /// a "typing stopped" notice will be sent.
+  Timer? _idleTimer;
+
+  void dispose() {
+    _idleTimer?.cancel();
+  }
+
+  /// Updates the server, if needed, that a keystroke was made when
+  /// composing a new message to [destination].
+  ///
+  /// To be called on all keystrokes in the composing session.
+  /// Sends "typing started" notices, throttled appropriately,
+  /// for repeated calls to the same [destination].
+  ///
+  /// If [destination] differs from the previous call, such as after a topic
+  /// input change, sends a "typing stopped" notice for the old destination.
+  ///
+  /// Keeps a timer to send a "typing stopped" notice when this and
+  /// [stoppedComposing] haven't been called in some time.
+  void keystroke(SendableNarrow destination) {
+    if (!debugEnable) return;
+
+    if (_currentDestination != null) {
+      if (destination == _currentDestination) {
+        // Nothing has really changed, except we may need
+        // to send a ping to the server and extend out our idle time.
+        if (_sinceLastPing!.elapsed > typingStartedWaitPeriod) {
+          _actuallyPingServer();
+        }
+        _startOrExtendIdleTimer();
+        return;
+      }
+
+      _stopLastNotification();
+    }
+
+    // We just started typing to this destination, so notify the server.
+    _currentDestination = destination;
+    _startOrExtendIdleTimer();
+    _actuallyPingServer();
+  }
+
+  /// Sends the server a "typing stopped" notice for the destination of
+  /// the current composing session, if there is one.
+  ///
+  /// To be called on cues that the user has exited a new-message composing session,
+  /// e.g., send button tapped, compose box unfocused, nav changed, app quit.
+  ///
+  /// If [keystroke] hasn't been called in some time, does nothing.
+  ///
+  /// Otherwise:
+  /// - Users will see our user's typing indicator disappear immediately
+  ///   instead of after [keystroke]'s timer.
+  /// - [keystroke]'s timer is canceled.
+  ///
+  /// (This has no "destination" param because the user can really only compose
+  /// to one destination at a time. This function acts on the current session
+  /// regardless of its destination.)
+  void stoppedComposing() {
+    if (!debugEnable) return;
+
+    if (_currentDestination != null) {
+      _stopLastNotification();
+    }
+  }
+
+  void _startOrExtendIdleTimer() {
+    _idleTimer?.cancel();
+    _idleTimer = Timer(typingStoppedWaitPeriod, _stopLastNotification);
+  }
+
+  void _actuallyPingServer() {
+    // This allows us to use [clock.stopwatch] only when testing.
+    _sinceLastPing = ZulipBinding.instance.stopwatch()..start();
+
+    unawaited(setTypingStatus(
+      connection,
+      op: TypingOp.start,
+      destination: _currentDestination!.destination));
+  }
+
+  void _stopLastNotification() {
+    assert(_currentDestination != null);
+    final destination = _currentDestination!;
+
+    _idleTimer!.cancel();
+    _currentDestination = null;
+    _sinceLastPing = null;
+
+    unawaited(setTypingStatus(
+      connection,
+      op: TypingOp.stop,
+      destination: destination.destination));
+  }
+
+  /// In debug mode, controls whether typing notices should be sent.
+  ///
+  /// Outside of debug mode, this is always true and the setter has no effect.
+  static bool get debugEnable {
+    bool result = true;
+    assert(() {
+      result = _debugEnable;
+      return true;
+    }());
+    return result;
+  }
+  static bool _debugEnable = true;
+  static set debugEnable(bool value) {
+    assert(() {
+      _debugEnable = value;
+      return true;
+    }());
+  }
+
+  @visibleForTesting
+  static void debugReset() {
+    _debugEnable = true;
+  }
+}