feat: suggestions API and UI feature

[TreTuna]

Adds This PR brings functionality for a suggestions API.

• Adds getSuggestions API function to geocoderApi object
  • By default, if getSuggestions api is available, showResultsWhileTyping will default to true and show both geocode and suggestion results
  • This was done as to not break backwards compatibility for current users of this flag for showing geocode results while typing.
  • For v2, it would be suggested to rethink these flags as we now have multiple types of results, we looked at this, but since it would have been a breaking change to rename that, we did not proceed there.
• Adds suggestionsOnlyWhileTyping flag - Combined with the previous, this allows the state where a developer only wants to see suggestions
• Adds processResutls function to the options object that is used to filter, sort, combine, and limit results of forwardGeocode/reverseGeocode and getSuggestions
  • Default processResults function:
  • Filters suggestions strings that are duplicated in geocode results, compared with geocode feature.label
  • Sorts filteredSuggestions first, followed by search results
  • Automatically divides results up to options.limit evenly between the two
    • if options.limit is an odd number, show 1 more geocode result than suggestion
    • if there are not enough suggestions or geocode results to fill to limit, then add more of the other until limit is reached

AutoSuggest with Geocode on typing:

AutoSuggest only on typing:

• [x] briefly describe the changes in this PR
• [x] write tests for all new functionality
• [x] run npm run docs and commit changes to API.md
• [x] update CHANGELOG.md with changes under master heading before merging

[wipfli]

Thanks for sharing this new feature. Is there an easy way to test this locally?

[TreTuna]

Thanks for sharing this new feature. Is there an easy way to test this locally?

Sure! If you have a sample app using the geocoder, you just need to add a fake getSuggestions API function into your geocodeApi object that's passed in. It doesn't need to call an API, just needs to return an array of strings that would be added to the results box.

You can see an example of how we're integrating it with our Amplify plugin here: https://github.com/aws-amplify/maplibre-gl-js-amplify/blob/main/src/AmplifyMapLibreGeocoder.ts