autocomplete [nfc]: Factor out generic AutocompleteView

The mechanism of query and results, is tricky. It's also generic to
the idea of autocomplete in general, is 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,38 +151,115 @@ 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;
+
+  AutocompleteView({this.resultsFilter, required this.store});
+
+  Iterable<Object> getDataForQuery(Q query);
+
+  R? testItem(Q query, Object item);
+
+  Q? get query => _query;
+  Q? _query;
+  set query(Q? query) {
+    _query = query;
+    if (query != null) {
+      _startSearch(query);
+    }
+  }
+
+  /// Called when the app is reassembled during debugging, e.g. for hot reload.
+  ///
+  /// This will redo the search from scratch for the current query, if any.
+  void reassemble() {
+    if (_query != null) {
+      _startSearch(_query!);
+    }
+  }
+
+  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?
+      }
+    }
+
+    if (newResults == null) {
+      // Query was old; new search is in progress. Or, no listeners to notify.
+      return;
+    }
+
+    _results = newResults;
+    notifyListeners();
+  }
+
+  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
+      await Future(() {});
+
+      if (query != _query || !hasListeners) { // false if [dispose] has been called.
+        return null;
+      }
+
+      for (int i = 0; i < 1000; i++) {
+        if (!iterator.moveNext()) {
+          isDone = true;
+          break;
+        }
+        final Object item = iterator.current;
+        final result = testItem(query, item);
+        if (result != null) results.add(result);
+      }
+    }
+    return resultsFilter?.call(results) ?? results;
+  }
+}
+
+class MentionAutocompleteView extends AutocompleteView<MentionAutocompleteQuery, MentionAutocompleteResult> {
+  final Narrow narrow;
+
+  MentionAutocompleteView.init({
+    required super.store,
+    required this.narrow,
+  }) : sortedUsers = _usersByRelevance(store: store, narrow: narrow)
+  {
+    store.autocompleteViewManager.registerMentionAutocomplete(this);
   }
 
+  final List<User> sortedUsers;
+
   static List<User> _usersByRelevance({
     required PerAccountStore store,
     required Narrow narrow,
@@ -192,6 +269,21 @@ class MentionAutocompleteView extends ChangeNotifier {
       ..sort((userA, userB) => compareByDms(userA, userB, store: store));
   }
 
+  @override
+  Iterable<Object> getDataForQuery(MentionAutocompleteQuery query) {
+    return sortedUsers;
+  }
+
+  @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;
+  }
+
   /// Determines which of the two users is more recent in DM conversations.
   ///
   /// Returns a negative number if [userA] is more recent than [userB],
@@ -221,76 +313,39 @@ class MentionAutocompleteView extends ChangeNotifier {
     super.dispose();
   }
 
-  final PerAccountStore store;
-  final Narrow narrow;
-  final List<User> sortedUsers;
-
-  MentionAutocompleteQuery? get query => _query;
-  MentionAutocompleteQuery? _query;
-  set query(MentionAutocompleteQuery? query) {
-    _query = query;
-    if (query != null) {
-      _startSearch(query);
-    }
-  }
-
-  /// Called when the app is reassembled during debugging, e.g. for hot reload.
+  /// Recompute user results for the current query, if any.
   ///
-  /// This will redo the search from scratch for the current query, if any.
-  void reassemble() {
+  /// Called in particular when we get a [RealmUserEvent].
+  void refreshStaleUserResults() {
     if (_query != null) {
       _startSearch(_query!);
     }
   }
+}
 
-  Iterable<MentionAutocompleteResult> get results => _results;
-  List<MentionAutocompleteResult> _results = [];
+abstract class AutocompleteQuery {
+  AutocompleteQuery(this.raw);
 
-  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;
-    }
+  final String raw;
 
-    _results = newResults;
-    notifyListeners();
+  @override
+  String toString() {
+    return '${objectRuntimeType(this, 'AutocompleteQuery')}(raw: $raw})';
   }
 
-  Future<List<MentionAutocompleteResult>?> _computeResults(MentionAutocompleteQuery query) async {
-    final List<MentionAutocompleteResult> results = [];
-    final iterator = sortedUsers.iterator;
-    bool isDone = false;
-    while (!isDone) {
-      // CPU perf: End this task; enqueue a new one for resuming this work
-      await Future(() {});
-
-      if (query != _query || !hasListeners) { // false if [dispose] has been called.
-        return null;
-      }
-
-      for (int i = 0; i < 1000; i++) {
-        if (!iterator.moveNext()) {
-          isDone = true;
-          break;
-        }
-
-        final User user = iterator.current;
-        if (query.testUser(user, store.autocompleteViewManager.autocompleteDataCache)) {
-          results.add(UserMentionAutocompleteResult(userId: user.userId));
-        }
-      }
-    }
-    return results;
+  @override
+  bool operator ==(Object other) {
+    return other is AutocompleteQuery && other.raw == raw;
   }
+
+  @override
+  int get hashCode => Object.hash('AutocompleteQuery', raw);
 }
 
-class MentionAutocompleteQuery {
-  MentionAutocompleteQuery(this.raw, {this.silent = false})
+class MentionAutocompleteQuery extends AutocompleteQuery {
+  MentionAutocompleteQuery(super.raw, {this.silent = false})
     : _lowercaseWords = raw.toLowerCase().split(' ');
 
-  final String raw;
-
   /// Whether the user wants a silent mention (@_query, vs. @query).
   final bool silent;
 
@@ -352,7 +407,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');
 }