Document an autocomplete use-case

[Zverik]

First documented in #4066.

Imagine a search field with autocompletion. The value in the field is stored in a state variable. It is then passed to a FutureProvider.family, which requests a list of results. Alas, when a search string changes, it builds a new provider, which has its loading state. Resulting in a loading screen after every keypress.

Given this might be a pretty common case for a family provider, I think it might need to be explicitly documented, like for debouncing, so that other people don't fall into the trap of the loading state.

Here is a sample code:

final autocompleteProvider = FutureProvider.autoDispose
    .family<AutocompleteResults?, String>((ref, value) async {
  if (value.length < 2) {
    return null;
  }

  bool stop = false;
  ref.onDispose(() {
    stop = true;
  });

  await Future.delayed(Duration(milliseconds: 500));
  if (stop) return null;

  return await SomeClass.fetchData(value);
}

class _PageState extends ConsumerState<Page> {
  String _lookingFor = '';

  @override
  Widget build(BuildContext context) {
    final found = ref.watch(autocompleteProvider(_lookingFor));

    return Column(
          children: [
            Expanded(child: found.valueOrNull == null ? EmptyPage() : ResultsPage(found.value!)),
            WordSearchBar(
              onUpdateWord: (value) {
                setState(() {
                  _lookingFor = value;
                });
              },
            ),
          ],
        );
  }
}

There are ways to circumvent this: abandon the provider altogether, use a non-family provider with a side effect, create a new family provider for the page, not for the search, or cache search results in the page state. Each of those has their drawbacks, the main being, they don't feel very "riverpod".

So, it might need to be solved in the library, or a circumvention method documented.