autocomplete [nfc]: Factor out generic AutocompleteView

The mechanism of query and results is generic to the idea of
autocomplete in general, it's not specific to autocomplete on
@-mentions vs. topics vs. anything else.

Author: Khader-1

lib/model/autocomplete.dart

@@ -8,7 +8,7 @@ import 'narrow.dart';
 import 'store.dart';
 
 extension ComposeContentAutocomplete on ComposeContentController {
-  AutocompleteIntent? autocompleteIntent() {
+  AutocompleteIntent<MentionAutocompleteQuery>? autocompleteIntent() {
     if (!selection.isValid || !selection.isNormalized) {
       // We don't require [isCollapsed] to be true because we've seen that
       // autocorrect and even backspace involve programmatically expanding the
@@ -69,7 +69,7 @@ final RegExp mentionAutocompleteMarkerRegex = (() {
 })();
 
 /// The content controller's recognition that the user might want autocomplete UI.
-class AutocompleteIntent {
+class AutocompleteIntent<Q extends AutocompleteQuery> {
   AutocompleteIntent({
     required this.syntaxStart,
     required this.query,
@@ -91,7 +91,7 @@ class AutocompleteIntent {
   // that use a custom/subclassed [TextEditingValue], so that's not convenient.
   final int syntaxStart;
 
-  final MentionAutocompleteQuery query; // TODO other autocomplete query types
+  final Q query;
 
   /// The [TextEditingValue] whose text [syntaxStart] refers to.
   final TextEditingValue textEditingValue;
@@ -151,83 +151,34 @@ class AutocompleteViewManager {
   // void dispose() { … }
 }
 
-/// A view-model for a mention-autocomplete interaction.
+/// A view-model for an autocomplete interaction.
 ///
 /// The owner of one of these objects must call [dispose] when the object
 /// will no longer be used, in order to free resources on the [PerAccountStore].
 ///
 /// Lifecycle:
-///  * Create with [init].
+///  * Create an instance of a concrete subtype.
 ///  * Add listeners with [addListener].
 ///  * Use the [query] setter to start a search for a query.
 ///  * On reassemble, call [reassemble].
 ///  * When the object will no longer be used, call [dispose] to free
 ///    resources on the [PerAccountStore].
-class MentionAutocompleteView extends ChangeNotifier {
-  MentionAutocompleteView._({
-    required this.store,
-    required this.narrow,
-    required this.sortedUsers,
-  });
+abstract class AutocompleteView<Q extends AutocompleteQuery, R extends AutocompleteResult> extends ChangeNotifier {
 
-  factory MentionAutocompleteView.init({
-    required PerAccountStore store,
-    required Narrow narrow,
-  }) {
-    final view = MentionAutocompleteView._(
-      store: store,
-      narrow: narrow,
-      sortedUsers: _usersByRelevance(store: store, narrow: narrow),
-    );
-    store.autocompleteViewManager.registerMentionAutocomplete(view);
-    return view;
-  }
+  /// This could be used to transform results after they've been
+  /// computed for sorting, filtering etc.
+  final List<R> Function(List<R> results)? resultsFilter;
+  final PerAccountStore store;
 
-  static List<User> _usersByRelevance({
-    required PerAccountStore store,
-    required Narrow narrow,
-  }) {
-    assert(narrow is! CombinedFeedNarrow);
-    return store.users.values.toList()
-      ..sort((userA, userB) => compareByDms(userA, userB, store: store));
-  }
+  AutocompleteView({this.resultsFilter, required this.store});
 
-  /// Determines which of the two users is 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.
-  @visibleForTesting
-  static int compareByDms(User userA, User userB, {required PerAccountStore store}) {
-    final recentDms = store.recentDmConversationsView;
-    final aLatestMessageId = recentDms.latestMessagesByRecipient[userA.userId];
-    final bLatestMessageId = recentDms.latestMessagesByRecipient[userB.userId];
+  Iterable<Object> getDataForQuery(Q query);
 
-    return switch((aLatestMessageId, bLatestMessageId)) {
-      (int a, int b) => -a.compareTo(b),
-      (int(),     _) => -1,
-      (_,     int()) => 1,
-      _              => 0,
-    };
-  }
+  R? testItem(Q query, Object item);
 
-  @override
-  void dispose() {
-    store.autocompleteViewManager.unregisterMentionAutocomplete(this);
-    // 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?)
-    super.dispose();
-  }
-
-  final PerAccountStore store;
-  final Narrow narrow;
-  final List<User> sortedUsers;
-
-  MentionAutocompleteQuery? get query => _query;
-  MentionAutocompleteQuery? _query;
-  set query(MentionAutocompleteQuery? query) {
+  Q? get query => _query;
+  Q? _query;
+  set query(Q? query) {
     _query = query;
     if (query != null) {
       _startSearch(query);
@@ -243,11 +194,22 @@ class MentionAutocompleteView extends ChangeNotifier {
     }
   }
 
-  Iterable<MentionAutocompleteResult> get results => _results;
-  List<MentionAutocompleteResult> _results = [];
+  Iterable<R> get results => _results;
+  List<R> _results = [];
+
+  Future<void> _startSearch(Q query) async {
+    List<R>? newResults;
+
+    while (true) {
+      try {
+        newResults = await _computeResults(query);
+        break;
+      } on ConcurrentModificationError {
+        // Retry
+        // TODO backoff?
+      }
+    }
 
-  Future<void> _startSearch(MentionAutocompleteQuery query) async {
-    final newResults = await _computeResults(query);
     if (newResults == null) {
       // Query was old; new search is in progress. Or, no listeners to notify.
       return;
@@ -257,9 +219,11 @@ class MentionAutocompleteView extends ChangeNotifier {
     notifyListeners();
   }
 
-  Future<List<MentionAutocompleteResult>?> _computeResults(MentionAutocompleteQuery query) async {
-    final List<MentionAutocompleteResult> results = [];
-    final iterator = sortedUsers.iterator;
+  Future<List<R>?> _computeResults(Q query) async {
+    final List<R> results = [];
+    final Iterable<Object> data = getDataForQuery(query);
+
+    final iterator = data.iterator;
     bool isDone = false;
     while (!isDone) {
       // CPU perf: End this task; enqueue a new one for resuming this work
@@ -274,41 +238,89 @@ class MentionAutocompleteView extends ChangeNotifier {
           isDone = true;
           break;
         }
-
-        final User user = iterator.current;
-        if (query.testUser(user, store.autocompleteViewManager.autocompleteDataCache)) {
-          results.add(UserMentionAutocompleteResult(userId: user.userId));
-        }
+        final Object item = iterator.current;
+        final result = testItem(query, item);
+        if (result != null) results.add(result);
       }
     }
-    return results;
+    return resultsFilter?.call(results) ?? results;
   }
 }
 
-class MentionAutocompleteQuery {
-  MentionAutocompleteQuery(this.raw, {this.silent = false})
-    : _lowercaseWords = raw.toLowerCase().split(' ');
+class MentionAutocompleteView extends AutocompleteView<MentionAutocompleteQuery, MentionAutocompleteResult> {
+  final Narrow narrow;
+  final List<User> sortedUsers;
 
-  final String raw;
+  MentionAutocompleteView.init({
+    required super.store,
+    required this.narrow,
+  }) : sortedUsers = _usersByRelevance(store: store, narrow: narrow)
+  {
+    store.autocompleteViewManager.registerMentionAutocomplete(this);
+  }
 
-  /// Whether the user wants a silent mention (@_query, vs. @query).
-  final bool silent;
+  static List<User> _usersByRelevance({
+    required PerAccountStore store,
+    required Narrow narrow,
+  }) {
+    assert(narrow is! CombinedFeedNarrow);
+    return store.users.values.toList()
+      ..sort((userA, userB) => compareByDms(userA, userB, store: store));
+  }
 
-  final List<String> _lowercaseWords;
+  @override
+  Iterable<Object> getDataForQuery(MentionAutocompleteQuery query) {
+    return sortedUsers;
+  }
 
-  bool testUser(User user, AutocompleteDataCache cache) {
-    // TODO(#236) test email too, not just name
+  @override
+  MentionAutocompleteResult? testItem(MentionAutocompleteQuery query, Object item) {
+    if (item is User) {
+      if (query.testUser(item, store.autocompleteViewManager.autocompleteDataCache)) {
+        return UserMentionAutocompleteResult(userId: item.userId);
+      }
+    }
+    return null;
+  }
 
-    if (!user.isActive) return false;
+  /// Determines which of the two users is 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.
+  @visibleForTesting
+  static int compareByDms(User userA, User userB, {required PerAccountStore store}) {
+    final recentDms = store.recentDmConversationsView;
+    final aLatestMessageId = recentDms.latestMessagesByRecipient[userA.userId];
+    final bLatestMessageId = recentDms.latestMessagesByRecipient[userB.userId];
 
-    return _testName(user, cache);
+    return switch((aLatestMessageId, bLatestMessageId)) {
+      (int a, int b) => -a.compareTo(b),
+      (int(),     _) => -1,
+      (_,     int()) => 1,
+      _              => 0,
+    };
   }
 
-  bool _testName(User user, AutocompleteDataCache cache) {
-    // TODO(#237) test with diacritics stripped, where appropriate
+  @override
+  void dispose() {
+    store.autocompleteViewManager.unregisterMentionAutocomplete(this);
+    // 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?)
+    super.dispose();
+  }
+}
 
-    final List<String> nameWords = cache.nameWordsForUser(user);
+abstract class AutocompleteQuery {
+  final String raw;
+  final List<String> _lowercaseWords;
 
+  AutocompleteQuery(this.raw) : _lowercaseWords = raw.toLowerCase().split(' ');
+
+  bool _testContainsQueryWords(List<String> nameWords) {
+    // TODO(#237) test with diacritics stripped, where appropriate
     int nameWordsIndex = 0;
     int queryWordsIndex = 0;
     while (true) {
@@ -326,6 +338,33 @@ class MentionAutocompleteQuery {
     }
   }
 
+  @override
+  String toString() {
+    return '${objectRuntimeType(this, 'AutocompleteQuery')}(raw: $raw})';
+  }
+
+  @override
+  bool operator ==(Object other) {
+    return other is AutocompleteQuery && other.raw == raw;
+  }
+
+  @override
+  int get hashCode => Object.hash('AutocompleteQuery', raw);
+}
+
+class MentionAutocompleteQuery extends AutocompleteQuery {
+  /// Whether the user wants a silent mention (@_query, vs. @query).
+  final bool silent;
+
+  MentionAutocompleteQuery(super.raw, {this.silent = false});
+
+  bool testUser(User user, AutocompleteDataCache cache) {
+    // TODO(#236) test email too, not just name
+    if (!user.isActive) return false;
+
+    return _testContainsQueryWords(cache.nameWordsForUser(user));
+  }
+
   @override
   String toString() {
     return '${objectRuntimeType(this, 'MentionAutocompleteQuery')}(raw: $raw, silent: $silent})';
@@ -352,7 +391,9 @@ class AutocompleteDataCache {
   }
 }
 
-sealed class MentionAutocompleteResult {}
+class AutocompleteResult {}
+
+sealed class MentionAutocompleteResult extends AutocompleteResult {}
 
 class UserMentionAutocompleteResult extends MentionAutocompleteResult {
   UserMentionAutocompleteResult({required this.userId});

test/model/autocomplete_checks.dart

@@ -3,10 +3,10 @@ import 'package:zulip/model/autocomplete.dart';
 import 'package:zulip/widgets/compose_box.dart';
 
 extension ComposeContentControllerChecks on Subject<ComposeContentController> {
-  Subject<AutocompleteIntent?> get autocompleteIntent => has((c) => c.autocompleteIntent(), 'autocompleteIntent');
+  Subject<AutocompleteIntent<MentionAutocompleteQuery>?> get autocompleteIntent => has((c) => c.autocompleteIntent(), 'autocompleteIntent');
 }
 
-extension AutocompleteIntentChecks on Subject<AutocompleteIntent> {
+extension AutocompleteIntentChecks on Subject<AutocompleteIntent<MentionAutocompleteQuery>> {
   Subject<int> get syntaxStart => has((i) => i.syntaxStart, 'syntaxStart');
   Subject<MentionAutocompleteQuery> get query => has((i) => i.query, 'query');
 }

test/widgets/compose_box_checks.dart

@@ -6,7 +6,7 @@ extension ComposeContentControllerChecks on Subject<ComposeContentController> {
   Subject<List<ContentValidationError>> get validationErrors => has((c) => c.validationErrors, 'validationErrors');
 }
 
-extension AutocompleteIntentChecks on Subject<AutocompleteIntent> {
+extension AutocompleteIntentChecks on Subject<AutocompleteIntent<MentionAutocompleteQuery>> {
   Subject<int> get syntaxStart => has((i) => i.syntaxStart, 'syntaxStart');
   Subject<MentionAutocompleteQuery> get query => has((i) => i.query, 'query');
 }