autocomplete: Sort user-mention autocomplete results

The @-mention autocomplete shows relevant results in the following order
of priority:
  * Recent conversation users
  * Recent DM users
  * Alphabetical order

Fixes: zulip#228

Author: sm-sayedi

lib/model/algorithms.dart

@@ -1,6 +1,47 @@
 
 import 'package:collection/collection.dart';
 
+  /// The index of [value] in [sortedList].
+  ///
+  /// Uses binary search to find the index, so the list must be sorted,
+  /// otherwise the result is unpredictable.
+  ///
+  /// If [value] is found, returns its index (0-based).
+  ///
+  /// ```dart
+  /// final somePrimes = [11, 13, 17, 23, 27];
+  /// final index = possibleIndexIn(somePrimes, 17); // 2
+  /// ```
+  /// If [value] is not found, returns the possible index (1-based)
+  /// with a negative sign, where if the [value] is inserted,
+  /// the order of the list is maintained.
+  ///
+  /// ```dart
+  /// final somePrimes = [11, 13, 17, 23, 27];
+  /// int index = possibleIndexIn(somePrimes, 7); // -1
+  /// index = possibleIndexIn(somePrimes, 19); // -4
+  /// ```
+  ///
+  /// Note: Using a negative 1-based index will differentiate between the case where
+  /// the element is found at index 0 and the case where the element is not
+  /// found, but should be placed at the very start of the list (index -1).
+int possibleIndexIn<E extends Comparable>(List<E> sortedList, E value) {
+  int min = 0;
+  int max = sortedList.length - 1;
+  while (min <= max) {
+    final mid = min + ((max - min) >> 1);
+    final midElement = sortedList[mid];
+    final comp = midElement.compareTo(value);
+    if (comp == 0) return mid;
+    if (comp < 0) {
+      min = mid + 1;
+    } else {
+      max = mid - 1;
+    }
+  }
+  return -(min + 1);
+}
+
 /// Returns the index in [sortedList] of an element matching the given [key],
 /// if there is one.
 ///

lib/model/autocomplete.dart

@@ -183,6 +183,7 @@ class MentionAutocompleteView extends ChangeNotifier {
   @override
   void dispose() {
     store.autocompleteViewManager.unregisterMentionAutocomplete(this);
+    _sortedUsers = null;
     // We cancel in-progress computations by checking [hasListeners] between tasks.
     // After [super.dispose] is called, [hasListeners] returns false.
     // TODO test that logic (may involve detecting an unhandled Future rejection; how?)
@@ -206,6 +207,7 @@ class MentionAutocompleteView extends ChangeNotifier {
   /// Called in particular when we get a [RealmUserEvent].
   void refreshStaleUserResults() {
     if (_query != null) {
+      _sortedUsers = null;
       _startSearch(_query!);
     }
   }
@@ -244,11 +246,95 @@ class MentionAutocompleteView extends ChangeNotifier {
     notifyListeners();
   }
 
+  List<User>? _sortedUsers;
+
+  int compareByRelevance({
+    required User userA,
+    required User userB,
+    required int? streamId,
+    required String? topic,
+  }) {
+    // TODO(#234): give preference to "all", "everyone" or "stream".
+
+    // TODO(#618): give preference to subscribed users first.
+
+    if (streamId != null) {
+      final conversationPrecedence = store.recentSenders.compareByRecency(
+        userA: userA,
+        userB: userB,
+        streamId: streamId,
+        topic: topic);
+      if (conversationPrecedence != 0) {
+        return conversationPrecedence;
+      }
+    }
+
+    final dmPrecedence = store.recentDmConversationsView.compareByDms(userA, userB);
+    if (dmPrecedence != 0) {
+      return dmPrecedence;
+    }
+
+    if (!userA.isBot && userB.isBot) {
+      return -1;
+    } else if (userA.isBot && !userB.isBot) {
+      return 1;
+    }
+
+    final userAName = store.autocompleteViewManager.autocompleteDataCache
+      .nameForUser(userA);
+    final userBName = store.autocompleteViewManager.autocompleteDataCache
+      .nameForUser(userB);
+    return userAName.compareTo(userBName);
+  }
+
+  List<User> sortByRelevance({
+    required List<User> users,
+    required Narrow narrow,
+  }) {
+    switch (narrow) {
+      case StreamNarrow():
+        users.sort((userA, userB) => compareByRelevance(
+          userA: userA,
+          userB: userB,
+          streamId: narrow.streamId,
+          topic: null));
+      case TopicNarrow():
+        users.sort((userA, userB) => compareByRelevance(
+          userA: userA,
+          userB: userB,
+          streamId: narrow.streamId,
+          topic: narrow.topic));
+      case DmNarrow():
+        users.sort((userA, userB) => compareByRelevance(
+          userA: userA,
+          userB: userB,
+          streamId: null,
+          topic: null));
+      case AllMessagesNarrow():
+        // do nothing in this case for now
+    }
+    return users;
+  }
+
+  void _sortUsers() {
+    final users = store.users.values.toList();
+    _sortedUsers = sortByRelevance(users: users, narrow: narrow);
+  }
+
+  bool _areUsersModified = false;
+  void _usersModified() {
+    _areUsersModified = true;
+  }
+
   Future<List<MentionAutocompleteResult>?> _computeResults(MentionAutocompleteQuery query) async {
     final List<MentionAutocompleteResult> results = [];
-    final Iterable<User> users = store.users.values;
 
-    final iterator = users.iterator;
+    if (_sortedUsers == null) {
+      _sortUsers();
+    }
+
+    final iterator = _sortedUsers!.iterator;
+    store.users.addListener(_usersModified);
     bool isDone = false;
     while (!isDone) {
       // CPU perf: End this task; enqueue a new one for resuming this work
@@ -259,6 +345,11 @@ class MentionAutocompleteView extends ChangeNotifier {
       }
 
       for (int i = 0; i < 1000; i++) {
+        if (_areUsersModified) {
+          _areUsersModified = false;
+          _sortedUsers = null;
+          throw ConcurrentModificationError();
+        }
         if (!iterator.moveNext()) { // Can throw ConcurrentModificationError
           isDone = true;
           break;
@@ -270,7 +361,8 @@ class MentionAutocompleteView extends ChangeNotifier {
         }
       }
     }
-    return results; // TODO(#228) sort for most relevant first
+    store.users.removeListener(_usersModified);
+    return results;
   }
 }
 
@@ -330,13 +422,25 @@ class MentionAutocompleteQuery {
 }
 
 class AutocompleteDataCache {
+  final Map<int, String> _namesByUser = {};
+
+  /// The lowercase `fullName` of [user].
+  String nameForUser(User user) {
+    return _namesByUser[user.userId] ??= user.fullName.toLowerCase();
+  }
+
   final Map<int, List<String>> _nameWordsByUser = {};
 
   List<String> nameWordsForUser(User user) {
-    return _nameWordsByUser[user.userId] ??= user.fullName.toLowerCase().split(' ');
+    final nameWords = _nameWordsByUser[user.userId];
+    if (nameWords != null) return nameWords;
+
+    final name = _namesByUser[user.userId] ??= user.fullName.toLowerCase();
+    return _nameWordsByUser[user.userId] = name.split(' ');
   }
 
   void invalidateUser(int userId) {
+    _namesByUser.remove(userId);
     _nameWordsByUser.remove(userId);
   }
 }

lib/model/message_list.dart

@@ -381,6 +381,7 @@ class MessageListView with ChangeNotifier, _MessageSequence {
     for (final message in result.messages) {
       if (_messageVisible(message)) {
         _addMessage(message);
+        store.recentSenders.processAsStreamMessage(message);
       }
     }
     _fetched = true;

lib/model/recent_dm_conversations.dart

@@ -30,7 +30,9 @@ class RecentDmConversationsView extends ChangeNotifier {
     required this.map,
     required this.sorted,
     required this.selfUserId,
-  });
+  }) {
+    _computeLatestMessagesWithUsers();
+  }
 
   /// The latest message ID in each conversation.
   final Map<DmNarrow, int> map;
@@ -40,6 +42,32 @@ class RecentDmConversationsView extends ChangeNotifier {
 
   final int selfUserId;
 
+  /// Map from user ID to the latest message ID in any conversation with the user.
+  ///
+  /// Both 1:1 and group DM conversations are considered.
+  /// The self-user ID is excluded even if there is a self-DM conversation.
+  ///
+  /// (The identified message was not necessarily sent by the identified user;
+  /// it might have been sent by anyone in its conversation.)
+  final Map<int, int> _latestMessageByRecipient = {};
+
+  void _computeLatestMessagesWithUsers() {
+    for (final dmNarrow in sorted) {
+      for (final userId in dmNarrow.otherRecipientIds) {
+        if (!_latestMessageByRecipient.containsKey(userId)) {
+          _latestMessageByRecipient[userId] = map[dmNarrow]!;
+        }
+      }
+    }
+  }
+
+  int compareByDms(User userA, User userB) {
+    final aLatestMessageId = _latestMessageByRecipient[userA.userId] ?? -1;
+    final bLatestMessageId = _latestMessageByRecipient[userB.userId] ?? -1;
+
+    return bLatestMessageId - aLatestMessageId;
+  }
+
   /// Insert the key at the proper place in [sorted].
   ///
   /// Optimized, taking O(1) time, for the case where that place is the start,