feat: force refresh with controller

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+### Added
+- force refreshing suggestions with `SuggestionsController.refresh`
+
 ## 5.1.0 - 2024-01-27
 ### Added
 - Returning null from `suggestionsCallback` hides the box

README.md

@@ -260,6 +260,36 @@ As well as all the usual parameters, such as `suggestionsCallback`, `onSelected`
 The `decorationBuilder` can be used to inject required wrappers like `Material` or `DefaultTextStyle`.
 For more information, see the source code of the `TypeAheadField` widget.
 
+## FAQ
+
+### My suggestions arent changing when I type
+
+You have most likely forgotten to pass the controller and focus node to the `TextField` in the `builder` property.
+This is required for the suggestions box to function. Here is an example:
+
+```dart
+TypeAheadField(
+  // ...
+  controller: myTextEditingController, // your custom controller, or null
+  builder: (context, controller, focusNode) {
+    return TextField(
+      controller: controller, // note how the controller is passed
+      focusNode: focusNode,
+      // ...
+    );
+  },
+);
+```
+
+### My suggestions are not updating when I click on the TextField
+
+The TypeAhead field caches the suggestions to avoid unnecessary calls to the `suggestionsCallback`.
+If you want to force the suggestions to update, you can use the `SuggestionsController` to force a refresh.
+
+```dart
+mySuggestionsController.refresh();
+```
+
 ## Migrations
 
 ### From 4.x to 5.x

lib/src/common/base/suggestions_controller.dart

@@ -52,6 +52,9 @@ class SuggestionsController<T> extends ChangeNotifier {
 
   List<T>? _suggestions;
 
+  /// Resets the suggestions so that they are requested again.
+  void refresh() => suggestions = null;
+
   /// Whether the suggestions box is loading.
   bool get isLoading => _isLoading;
   set isLoading(bool value) {

lib/src/common/search/suggestions_search.dart

@@ -67,26 +67,38 @@ class _SuggestionsSearchState<T> extends State<SuggestionsSearch<T>> {
   bool isQueued = false;
   late String search;
   late bool wasOpen;
+  late bool hadSuggestions;
 
   @override
   void initState() {
     super.initState();
     search = widget.textEditingController.text;
     wasOpen = widget.controller.isOpen;
+    hadSuggestions = widget.controller.suggestions != null;
     WidgetsBinding.instance.addPostFrameCallback((_) {
       if (!mounted) return;
-      if (wasOpen) {
-        load();
-      }
+      if (wasOpen) load();
     });
   }
 
+  void onChange() {
+    if (!mounted) return;
+    onOpenChange();
+    onSuggestionsChange();
+  }
+
   void onOpenChange() {
-    if (wasOpen == widget.controller.isOpen) return;
-    wasOpen = widget.controller.isOpen;
-    if (wasOpen) {
-      load();
-    }
+    bool isOpen = widget.controller.isOpen;
+    if (wasOpen == isOpen) return;
+    wasOpen = isOpen;
+    if (isOpen) load();
+  }
+
+  void onSuggestionsChange() {
+    bool hasSuggestions = widget.controller.suggestions != null;
+    if (hadSuggestions == hasSuggestions) return;
+    hadSuggestions = hasSuggestions;
+    if (!hasSuggestions) load();
   }
 
   /// Loads suggestions if not already loaded.
@@ -143,8 +155,8 @@ class _SuggestionsSearchState<T> extends State<SuggestionsSearch<T>> {
         },
         child: ConnectorWidget(
           value: widget.controller,
-          connect: (value) => value.addListener(onOpenChange),
-          disconnect: (value, key) => value.removeListener(onOpenChange),
+          connect: (value) => value.addListener(onChange),
+          disconnect: (value, key) => value.removeListener(onChange),
           child: widget.child,
         ),
       ),

test/common/base/suggestions_controller_test.dart

@@ -20,6 +20,13 @@ void main() {
       expect(controller.suggestions, equals(['a', 'b', 'c']));
     });
 
+    test('refreshes the suggestions', () {
+      expect(controller.suggestions, isNull);
+      controller.suggestions = ['a', 'b', 'c'];
+      controller.refresh();
+      expect(controller.suggestions, null);
+    });
+
     test('sets loading state', () {
       expect(controller.isLoading, isFalse);
       controller.isLoading = true;

test/common/search/suggestions_search_test.dart

@@ -100,6 +100,34 @@ void main() {
       expect(controller.suggestions, ['new1', 'new2']);
     });
 
+    testWidgets('reloads entries when suggestions are set to null',
+        (WidgetTester tester) async {
+      int count = 0;
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Material(
+            child: SuggestionsSearch<String>(
+              controller: controller,
+              textEditingController: textEditingController,
+              suggestionsCallback: (pattern) async {
+                count++;
+                return [count.toString()];
+              },
+              debounceDuration: debounceDuration,
+              child: const SizedBox(),
+            ),
+          ),
+        ),
+      );
+
+      expect(controller.suggestions, ['1']);
+
+      controller.refresh();
+      await tester.pump();
+
+      expect(controller.suggestions, ['2']);
+    });
+
     testWidgets('loads when controller opens', (WidgetTester tester) async {
       controller.close();