autocomplete: Add "recent DM conversations" criterion

In @-mention autocomplete, users are suggested based on:
  1. Recent DM conversations.

Fixes part of: #228

Author: sm-sayedi

lib/model/autocomplete.dart

@@ -267,13 +267,48 @@ class MentionAutocompleteView extends ChangeNotifier {
 
   List<User>? _sortedUsers;
 
-  List<User> sortByRelevance({required List<User> users}) {
+  /// Determines which of the two users are more recent in DM conversations.
+  ///
+  /// Returns a negative number if [userA] is more recent than [userB],
+  /// returns a positive number if [userB] is more recent than [userA],
+  /// and returns `0` if both [userA] and [userB] are equally recent
+  /// or there is no DM exchanged with them whatsoever.
+  int compareByDms(User userA, User userB) {
+    final recentDms = store.recentDmConversationsView;
+    final aLatestMessageId = recentDms.latestMessagesByRecipient[userA.userId] ?? -1;
+    final bLatestMessageId = recentDms.latestMessagesByRecipient[userB.userId] ?? -1;
+
+    return bLatestMessageId.compareTo(aLatestMessageId);
+  }
+
+  int compareByRelevance({
+    required User userA,
+    required User userB,
+  }) {
+    final dmPrecedence = compareByDms(userA, userB);
+    return dmPrecedence;
+  }
+
+  List<User> sortByRelevance({
+    required List<User> users,
+    required Narrow narrow,
+  }) {
+    switch (narrow) {
+      case StreamNarrow():
+      case TopicNarrow():
+      case DmNarrow():
+        users.sort((userA, userB) => compareByRelevance(
+          userA: userA,
+          userB: userB));
+      case AllMessagesNarrow():
+        // do nothing in this case for now
+    }
     return users;
   }
 
   void _sortUsers() {
     final users = store.users.values.toList();
-    _sortedUsers = sortByRelevance(users: users);
+    _sortedUsers = sortByRelevance(users: users, narrow: narrow);
   }
 
   Future<List<MentionAutocompleteResult>?> _computeResults(MentionAutocompleteQuery query) async {

test/model/autocomplete_test.dart

@@ -5,9 +5,11 @@ import 'package:checks/checks.dart';
 import 'package:fake_async/fake_async.dart';
 import 'package:flutter/cupertino.dart';
 import 'package:test/scaffolding.dart';
+import 'package:zulip/api/model/initial_snapshot.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/model/autocomplete.dart';
 import 'package:zulip/model/narrow.dart';
+import 'package:zulip/model/store.dart';
 import 'package:zulip/widgets/compose_box.dart';
 
 import '../example_data.dart' as eg;
@@ -349,4 +351,85 @@ void main() {
       doCheck('Four F', eg.user(fullName: 'Full Name Four Words'), false);
     });
   });
+
+  group('MentionAutocompleteView users results', () {
+    late PerAccountStore store;
+    late MentionAutocompleteView view;
+
+    void prepare({
+      required List<User> users,
+      required List<RecentDmConversation> dmConversations,
+      required Narrow narrow,
+    }) {
+      store = eg.store(
+        initialSnapshot: eg.initialSnapshot(
+          recentPrivateConversations: dmConversations
+      ));
+      for (final user in users) {
+        store.addUser(user);
+      }
+      view = MentionAutocompleteView.init(store: store, narrow: narrow);
+    }
+
+    test('compareByDms gives priority to user with DM exchanged more recently', () {
+      prepare(
+        users: [],
+        dmConversations: [
+          RecentDmConversation(userIds: [1],    maxMessageId: 200),
+          RecentDmConversation(userIds: [1, 2], maxMessageId: 100),
+        ],
+        narrow: const AllMessagesNarrow(),
+      );
+
+      final userA = eg.user(userId: 1);
+      final userB = eg.user(userId: 2);
+      final compareAB = view.compareByDms(userA, userB);
+      check(compareAB).isNegative();
+    });
+
+    test('autocomplete suggests relevant users in the following order: '
+      '1. Users most recent in the DM conversations', () async {
+      final users = [
+        eg.user(userId: 1),
+        eg.user(userId: 2),
+        eg.user(userId: 3),
+        eg.user(userId: 4),
+        eg.user(userId: 5),
+      ];
+
+      final dmConversations = [
+        RecentDmConversation(userIds: [4],    maxMessageId: 300),
+        RecentDmConversation(userIds: [1],    maxMessageId: 200),
+        RecentDmConversation(userIds: [1, 2], maxMessageId: 100),
+      ];
+
+      Future<void> checkResultsIn(Narrow narrow, {required List<int> expected}) async {
+        prepare(users: users, dmConversations: dmConversations, narrow: narrow);
+
+        bool done = false;
+        view.addListener(() { done = true; });
+        view.query = MentionAutocompleteQuery('');
+        await Future(() {});
+        check(done).isTrue();
+        final results = view.results
+          .map((e) => (e as UserMentionAutocompleteResult).userId)
+          .toList();
+        check(results).deepEquals(expected);
+      }
+
+      const streamNarrow = StreamNarrow(1);
+      await checkResultsIn(streamNarrow, expected: [4, 1, 2, 3, 5]);
+
+      const topicNarrow = TopicNarrow(1, 'topic');
+      await checkResultsIn(topicNarrow, expected: [4, 1, 2, 3, 5]);
+
+      final dmNarrow = DmNarrow(allRecipientIds: [eg.selfUser.userId], selfUserId: eg.selfUser.userId);
+      await checkResultsIn(dmNarrow, expected: [4, 1, 2, 3, 5]);
+
+      const allMessagesNarrow = AllMessagesNarrow();
+      // Results are in the original order as we do not sort them for
+      // [AllMessagesNarrow] because we can not access autocomplete for now.
+      await checkResultsIn(allMessagesNarrow, expected: [1, 2, 3, 4, 5]);
+    });
+  });
 }