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: #228

Author: sm-sayedi

lib/model/algorithms.dart

@@ -116,3 +116,46 @@ QueueList<int> setUnion(Iterable<int> xs, Iterable<int> ys) {
   }
   return result;
 }
+
+extension PossibleIndex<T extends num> on List<T> {
+  /// The index of [element] in this sorted list.
+  ///
+  /// Uses binary search to find the index, so the list must be sorted,
+  /// otherwise the result is unpredictable.
+  ///
+  /// If [element] is found, returns its index (0-based).
+  ///
+  /// ```dart
+  /// final somePrimes = [11, 13, 17, 23, 27];
+  /// final index = somePrimes.possibleIndexOf(17); // 2
+  /// ```
+  /// If [element] is not found, returns the possible index (1-based)
+  /// with a negative sign, where if the [element] is inserted,
+  /// the order of the list is maintained.
+  ///
+  /// ```dart
+  /// final somePrimes = [11, 13, 17, 23, 27];
+  /// int index = somePrimes.possibleIndexOf(7); // -1
+  /// index = somePrimes.possibleIndexOf(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 possibleIndexOf(T element) {
+    int low = 0;
+    int high = length - 1;
+
+    while (high >= low) {
+      int mid = (low + high) ~/ 2;
+      if (element == this[mid]) {
+        return mid;
+      } else if (element < this[mid]) {
+        high = mid - 1;
+      } else {
+        low = mid + 1;
+      }
+    }
+    return -low - 1;
+  }
+}

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,89 @@ 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
+      .lowercasedNameForUserName(userA.fullName);
+    final userBName = store.autocompleteViewManager.autocompleteDataCache
+      .lowercasedNameForUserName(userB.fullName);
+    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);
+  }
+
   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;
     bool isDone = false;
     while (!isDone) {
       // CPU perf: End this task; enqueue a new one for resuming this work
@@ -270,7 +350,7 @@ class MentionAutocompleteView extends ChangeNotifier {
         }
       }
     }
-    return results; // TODO(#228) sort for most relevant first
+    return results;
   }
 }
 
@@ -339,6 +419,12 @@ class AutocompleteDataCache {
   void invalidateUser(int userId) {
     _nameWordsByUser.remove(userId);
   }
+
+  final Map<String, String> _lowercasedNamesByUserName = {};
+
+  String lowercasedNameForUserName(String name) {
+    return _lowercasedNamesByUserName[name] ??= name.toLowerCase();
+  }
 }
 
 sealed class MentionAutocompleteResult {}

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,

lib/model/recent_senders.dart

@@ -0,0 +1,138 @@
+import '../api/model/model.dart';
+import 'algorithms.dart';
+
+class MessageIdTracker {
+  final List<int> _ids = [];
+
+  void add(int id) {
+    if (_ids.isEmpty) {
+      _ids.add(id);
+    } else {
+      int i = _ids.possibleIndexOf(id);
+      if (i >= 0) { // the [id] already exists, so do not add it.
+        return;
+      }
+      i = -i - 1; // change the index back to 0-based for readability.
+      if (i == _ids.length) { // the [id] should be added to the end of the list.
+        _ids.add(id);
+      } else {
+        _ids.insert(i, id);
+      }
+    }
+  }
+
+  // TODO: remove
+
+  /// The maximum id in the tracker list.
+  ///
+  /// Returns -1 if the tracker list is empty.
+  int get maxId => _ids.isNotEmpty ? _ids.last : -1;
+
+  @override
+  String toString() => _ids.toString();
+}
+
+/// A data structure to keep track of stream and topic messages.
+///
+/// The owner should call [clear] in order to free resources.
+class RecentSenders {
+  // streamSenders[streamId][senderId] = IdTracker
+  final Map<int, Map<int, MessageIdTracker>> _streamSenders = {};
+
+  // topicSenders[streamId][topic][senderId] = IdTracker
+  final Map<int, Map<String, Map<int, MessageIdTracker>>> _topicSenders = {};
+
+  void clear() {
+    _streamSenders.clear();
+    _topicSenders.clear();
+  }
+
+  int _latestMessageIdOfSenderInStream({required int streamId, required int senderId}) {
+    return _streamSenders[streamId]?[senderId]?.maxId ?? -1;
+  }
+
+  int _latestMessageIdOfSenderInTopic({
+    required int streamId,
+    required String topic,
+    required int senderId,
+  }) {
+    return _topicSenders[streamId]?[topic]?[senderId]?.maxId ?? -1;
+  }
+
+  void _addMessageInStream({
+    required int streamId,
+    required int senderId,
+    required messageId,
+  }) {
+    final senderMap = _streamSenders[streamId] ?? {};
+    final idTracker = senderMap[senderId] ?? MessageIdTracker();
+    _streamSenders[streamId] = senderMap;
+    senderMap[senderId] = idTracker;
+    idTracker.add(messageId);
+  }
+
+  void _addMessageInTopic({
+    required int streamId,
+    required String topic,
+    required int senderId,
+    required messageId,
+  }) {
+    final topicMap = _topicSenders[streamId] ?? {};
+    final senderMap = topicMap[topic] ?? {};
+    final idTracker = senderMap[senderId] ?? MessageIdTracker();
+    _topicSenders[streamId] = topicMap;
+    topicMap[topic] = senderMap;
+    senderMap[senderId] = idTracker;
+    idTracker.add(messageId);
+  }
+
+  /// Extracts and keeps track of the necessary data from a [message] only
+  /// if it is a stream message.
+  void processAsStreamMessage(Message message) {
+    if (message is! StreamMessage) {
+      return;
+    }
+
+    final streamId = message.streamId;
+    final topic = message.subject;
+    final senderId = message.senderId;
+    final messageId = message.id;
+
+    _addMessageInStream(
+      streamId: streamId, senderId: senderId, messageId: messageId);
+    _addMessageInTopic(
+      streamId: streamId,
+      topic: topic,
+      senderId: senderId,
+      messageId: messageId);
+  }
+
+  // TODO: removeMessageInTopic
+
+  int compareByRecency({
+    required User userA,
+    required User userB,
+    required int streamId,
+    required String? topic,
+  }) {
+    int aMessageId, bMessageId;
+
+    if (topic != null) {
+      aMessageId = _latestMessageIdOfSenderInTopic(
+        streamId: streamId, topic: topic, senderId: userA.userId);
+      bMessageId = _latestMessageIdOfSenderInTopic(
+        streamId: streamId, topic: topic, senderId: userB.userId);
+
+      if (aMessageId != bMessageId) {
+        return bMessageId - aMessageId;
+      }
+    }
+
+    aMessageId =
+      _latestMessageIdOfSenderInStream(streamId: streamId, senderId: userA.userId);
+    bMessageId =
+      _latestMessageIdOfSenderInStream(streamId: streamId, senderId: userB.userId);
+
+    return bMessageId - aMessageId;
+  }
+}