Fix bug in Autocomplete example (#127219)

This example was incorrectly throwing away results from a query when multiple queries were pending at once.   Thanks to @sun-jiao in https://github.com/flutter/flutter/pull/127019#issuecomment-1552347037 for pointing this out.

I also added a quick  `Text` widget explaining what to do to use the examples.  Since there are only three small possible `options`, it's easy to type into the field and not get any results and wonder what's wrong.

examples/api/lib/material/autocomplete/autocomplete.0.dart

@@ -18,8 +18,14 @@ class AutocompleteExampleApp extends StatelessWidget {
         appBar: AppBar(
           title: const Text('Autocomplete Basic'),
         ),
-        body: const Center(
-          child: AutocompleteBasicExample(),
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              Text('Type below to autocomplete the following possible results: ${AutocompleteBasicExample._kOptions}.'),
+              const AutocompleteBasicExample(),
+            ],
+          ),
         ),
       ),
     );

examples/api/lib/material/autocomplete/autocomplete.1.dart

@@ -18,8 +18,14 @@ class AutocompleteExampleApp extends StatelessWidget {
         appBar: AppBar(
           title: const Text('Autocomplete Basic User'),
         ),
-        body: const Center(
-          child: AutocompleteBasicUserExample(),
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              Text('Type below to autocomplete the following possible results: ${AutocompleteBasicUserExample._userOptions}.'),
+              const AutocompleteBasicUserExample(),
+            ],
+          ),
         ),
       ),
     );

examples/api/lib/material/autocomplete/autocomplete.2.dart

@@ -21,8 +21,14 @@ class AutocompleteExampleApp extends StatelessWidget {
         appBar: AppBar(
           title: const Text('Autocomplete - async'),
         ),
-        body: const Center(
-          child: _AsyncAutocomplete(),
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              Text('Type below to autocomplete the following possible results: ${_FakeAPI._kOptions}.'),
+              const _AsyncAutocomplete(),
+            ],
+          ),
         ),
       ),
     );

examples/api/lib/material/autocomplete/autocomplete.3.dart

@@ -24,8 +24,14 @@ class AutocompleteExampleApp extends StatelessWidget {
         appBar: AppBar(
           title: const Text('Autocomplete - async and debouncing'),
         ),
-        body: const Center(
-          child: _AsyncAutocomplete(),
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              Text('Type below to autocomplete the following possible results: ${_FakeAPI._kOptions}.'),
+              const _AsyncAutocomplete(),
+            ],
+          ),
         ),
       ),
     );
@@ -59,7 +65,6 @@ class _AsyncAutocompleteState extends State<_AsyncAutocomplete > {
 
     // If another search happened after this one, throw away these options.
     if (_currentQuery != query) {
-      _currentQuery = null;
       return null;
     }
     _currentQuery = null;

examples/api/lib/material/autocomplete/autocomplete.4.dart

@@ -25,8 +25,15 @@ class AutocompleteExampleApp extends StatelessWidget {
         appBar: AppBar(
           title: const Text('Autocomplete - async, debouncing, and network errors'),
         ),
-        body: const Center(
-          child: _AsyncAutocomplete(),
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              Text('Type below to autocomplete the following possible results: ${_FakeAPI._kOptions}.'),
+              const SizedBox(height: 32.0),
+              const _AsyncAutocomplete(),
+            ],
+          ),
         ),
       ),
     );

examples/api/test/material/autocomplete/autocomplete.3_test.dart

@@ -77,4 +77,37 @@ void main() {
     expect(find.text('bobcat'), findsNothing);
     expect(find.text('chameleon'), findsOneWidget);
   });
+
+  testWidgets('multiple pending requests', (WidgetTester tester) async {
+    await tester.pumpWidget(const example.AutocompleteExampleApp());
+
+    await tester.enterText(find.byType(TextFormField), 'a');
+
+    // Wait until the debounce duration has expired, but the request is still
+    // pending.
+    await tester.pump(example.debounceDuration);
+
+    expect(find.text('aardvark'), findsNothing);
+    expect(find.text('bobcat'), findsNothing);
+    expect(find.text('chameleon'), findsNothing);
+
+    await tester.enterText(find.byType(TextFormField), 'aa');
+
+    // Wait until the first request has completed.
+    await tester.pump(example.fakeAPIDuration - example.debounceDuration);
+
+    // The results from the first request are thrown away since the query has
+    // changed.
+    expect(find.text('aardvark'), findsNothing);
+    expect(find.text('bobcat'), findsNothing);
+    expect(find.text('chameleon'), findsNothing);
+
+    // Wait until the second request has completed.
+    await tester.pump(example.fakeAPIDuration);
+
+    // The results of the second request are reflected.
+    expect(find.text('aardvark'), findsOneWidget);
+    expect(find.text('bobcat'), findsNothing);
+    expect(find.text('chameleon'), findsNothing);
+  });
 }