autocomplete [nfc]: Add bucket-sort step in mention-autocomplete

Like we do in emoji autocomplete.

This commit doesn't make any changes to the results ordering;
bucketSort sorts stably, and the input is still just the wildcard
results followed by the user results.

Soon, though, we'd like to rank by match quality and add user-group
results (for #233) interleaved with user results. Bucket sorting
will help us do this without making many intermediate copies of
lists of results; see discussion:
  https://chat.zulip.org/#narrow/channel/48-mobile/topic/user-group.20mentions.20.23F233/near/2216353

Co-authored-by: Greg Price <[email protected]>

Author: chrisbobbe

lib/model/autocomplete.dart

@@ -8,6 +8,7 @@ import '../api/model/model.dart';
 import '../api/route/channels.dart';
 import '../generated/l10n/zulip_localizations.dart';
 import '../widgets/compose_box.dart';
+import 'algorithms.dart';
 import 'compose.dart';
 import 'emoji.dart';
 import 'narrow.dart';
@@ -635,16 +636,18 @@ class MentionAutocompleteView extends AutocompleteView<MentionAutocompleteQuery,
 
   @override
   Future<List<MentionAutocompleteResult>?> computeResults() async {
-    final results = <MentionAutocompleteResult>[];
+    final unsorted = <MentionAutocompleteResult>[];
     // Give priority to wildcard mentions.
-    computeWildcardMentionResults(results: results,
+    computeWildcardMentionResults(results: unsorted,
       isComposingChannelMessage: narrow is ChannelNarrow || narrow is TopicNarrow);
 
     if (await filterCandidates(filter: _testUser,
-        candidates: sortedUsers, results: results)) {
+        candidates: sortedUsers, results: unsorted)) {
       return null;
     }
-    return results;
+
+    return bucketSort(unsorted,
+      (r) => r.rank, numBuckets: MentionAutocompleteQuery._numResultRanks);
   }
 
   MentionAutocompleteResult? _testUser(MentionAutocompleteQuery query, User user) {
@@ -749,7 +752,8 @@ class MentionAutocompleteQuery extends ComposeAutocompleteQuery {
     final matches = wildcardOption.canonicalString.contains(_lowercase)
       || wildcardOption.localizedCanonicalString(localizations).contains(_lowercase);
     if (!matches) return null;
-    return WildcardMentionAutocompleteResult(wildcardOption: wildcardOption);
+    return WildcardMentionAutocompleteResult(
+      wildcardOption: wildcardOption, rank: _rankWildcardResult);
   }
 
   MentionAutocompleteResult? testUser(User user, PerAccountStore store) {
@@ -760,13 +764,30 @@ class MentionAutocompleteQuery extends ComposeAutocompleteQuery {
     // TODO(#236) test email too, not just name
     if (!_testName(user, cache)) return null;
 
-    return UserMentionAutocompleteResult(userId: user.userId);
+    return UserMentionAutocompleteResult(
+      userId: user.userId, rank: _rankUserResult(user));
   }
 
   bool _testName(User user, AutocompleteDataCache cache) {
     return _testContainsQueryWords(cache.nameWordsForUser(user));
   }
 
+  /// A measure of a wildcard result's quality in the context of the query,
+  /// from 0 (best) to one less than [_numResultRanks].
+  ///
+  /// See also [_rankUserResult].
+  static const _rankWildcardResult = 0;
+
+  /// A measure of a user result's quality in the context of the query,
+  /// from 0 (best) to one less than [_numResultRanks].
+  ///
+  /// See also [_rankWildcardResult].
+  static int _rankUserResult(User user) => 1;
+
+  /// The number of possible values returned by
+  /// [_rankWildcardResult] and [_rankUserResult].
+  static const _numResultRanks = 2;
+
   @override
   String toString() {
     return '${objectRuntimeType(this, 'MentionAutocompleteQuery')}(raw: $raw, silent: $silent})';
@@ -853,20 +874,31 @@ class EmojiAutocompleteResult extends ComposeAutocompleteResult {
 /// This is abstract because there are several kinds of result
 /// that can all be offered in the same @-mention autocomplete interaction:
 /// a user, a wildcard, or a user group.
-sealed class MentionAutocompleteResult extends ComposeAutocompleteResult {}
+sealed class MentionAutocompleteResult extends ComposeAutocompleteResult {
+  /// A measure of the result's quality in the context of the query.
+  ///
+  /// Used internally by [MentionAutocompleteView] for ranking the results.
+  int get rank;
+}
 
 /// An autocomplete result for an @-mention of an individual user.
 class UserMentionAutocompleteResult extends MentionAutocompleteResult {
-  UserMentionAutocompleteResult({required this.userId});
+  UserMentionAutocompleteResult({required this.userId, required this.rank});
 
   final int userId;
+
+  @override
+  final int rank;
 }
 
 /// An autocomplete result for an @-mention of all the users in a conversation.
 class WildcardMentionAutocompleteResult extends MentionAutocompleteResult {
-  WildcardMentionAutocompleteResult({required this.wildcardOption});
+  WildcardMentionAutocompleteResult({required this.wildcardOption, required this.rank});
 
   final WildcardMentionOption wildcardOption;
+
+  @override
+  final int rank;
 }
 
 // TODO(#233): // class UserGroupMentionAutocompleteResult extends MentionAutocompleteResult {

test/model/autocomplete_test.dart

@@ -972,6 +972,50 @@ void main() {
     });
   });
 
+  group('MentionAutocompleteQuery ranking', () {
+    // This gets filled lazily, but never reset.
+    // We're counting on this group's tests never doing anything to mutate it.
+    PerAccountStore? store;
+
+    int? rankOf(String queryStr, Object candidate) {
+      final query = MentionAutocompleteQuery(queryStr);
+      final result = switch (candidate) {
+        WildcardMentionOption() => query.testWildcardOption(candidate,
+          localizations: GlobalLocalizations.zulipLocalizations),
+        User() => query.testUser(candidate, (store ??= eg.store())),
+        _ => throw StateError('invalid candidate'),
+      };
+      return result?.rank;
+    }
+
+    void checkPrecedes(String query, Object a, Object b) {
+      check(rankOf(query, a)!).isLessThan(rankOf(query, b)!);
+    }
+
+    void checkSameRank(String query, Object a, Object b) {
+      check(rankOf(query, a)!).equals(rankOf(query, b)!);
+    }
+
+    test('wildcards, then users', () {
+      checkSameRank('', WildcardMentionOption.all, WildcardMentionOption.topic);
+      checkPrecedes('', WildcardMentionOption.topic, eg.user());
+      checkSameRank('', eg.user(), eg.user());
+    });
+
+    test('wildcard-vs-user more significant than match quality', () {
+      // Make the query an exact match for the user's name.
+      final user = eg.user(fullName: 'Ann');
+      checkPrecedes(user.fullName, WildcardMentionOption.channel, user);
+    });
+
+    test('full list of ranks', () {
+      check([
+        rankOf('', WildcardMentionOption.all), // wildcard
+        rankOf('', eg.user()),                 // user
+      ]).deepEquals([0, 1]);
+    });
+  });
+
   group('ComposeTopicAutocomplete.autocompleteIntent', () {
     void doTest(String markedText, TopicAutocompleteQuery? expectedQuery) {
       final parsed = parseMarkedText(markedText);