[RFC] removing hooks from the library for the 1.0 release

[usefulthink]

In recent discussions we came to the conclusion that it would probably make sense to remove some of the hooks from the library for the first major release in order to limit the API surface and consolidate what we have before possibly reintroducing them if needed.

The hooks that are definitely going to stay:

• useMap()
• useApiIsLoaded() / useApiLoadingStatus()
• useMapsLibrary() (with the pending change to return the library as returned by google.maps.importLibrary)

Trivial hooks that aren't really needed and will be removed (all of their use-cases can be replaced with a combination of useMapsLibrary() with useState() / useEffect()):

• useAutocompleteService()
• useDistanceMatrixService()
• useElevationService()
• useGeocodingService()
• useMaxZoomService()
• usePlacesService() (the only thing that differs from the other hooks here is that the places-service needs an element to render attribution information to, but that is something that is going to change in future versions of the google maps API).

Finally there are the more complex hooks. Considering those, I started to think that the approach to provide all the functionality of the Maps JavaScript API as is via react-hooks is not the best choice here and we should focus on providing useful abstractions solving specific common use-cases instead.

• useAutocomplete():
  providing a good autocomplete solution is a lot more complicated than can properly be implemented in a simple hook. As such, there would probably only be a very limited number of users this implementation would actually be useful for. The current implementation of google.maps.places.Autocomplete is also problematic in a react-context due to it creating DOM Elements outside of the scope of the map or the autocomplete input-element. Given the new focus on Web Components in the Maps JavaScript API, it is also likely that google will provide a WC based implementation of the autocomplete input in the future that could possibly solve most of these issues and be used instead.

• useDirectionsService(): this seems to fit well with the Idea to solve a common and specific use-case (rendering directions-results on the map). This should probably be refactored a bit to support a wider range of use-cases.

• useStreetViewPanorama(): the StreetView functionality is a unique feature of the Google Maps API and definitely shouldn't be missing from this library. We should think about refactoring this to fit the common use-cases and possibly provide an alternative component-version to just render StreetView imagery.

[usefulthink]

CC @wangela, @BiniCodes, @plumdumpling

[voltuer]

so how do we use autocomplete?

[frascavone]

I'll share my implementation made by following this guide on the docs:

https://developers.google.com/maps/documentation/javascript/place-autocomplete#add-autocomplete

import { ChangeEvent, KeyboardEvent, useEffect, useRef, useState } from "react";
import { useMapsLibrary } from "@vis.gl/react-google-maps";

export const AutoComplete = () => {
	const inputRef = useRef<HTMLInputElement>(null);
	const [inputValue, setInputValue] = useState<string>("");
	const [success, setSuccess] = useState<boolean>(false);

	const handleInputChange = (event: ChangeEvent<HTMLInputElement>) => {
		setInputValue(event.target.value);
	};

	// prevent submit if used in a form
	const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
		if (event.key === "Enter") {
			event.preventDefault();
		}
	};

	const onPlaceChanged = (place: google.maps.places.PlaceResult) => {
		if (place && place.formatted_address && place.name && place.opening_hours && place.opening_hours.periods) {
			setInputValue(place.formatted_address || place.name);

			console.log("Selected Place => ", place);

			setSuccess(true);
		}
		// Keep focus on input element
		inputRef.current && inputRef.current.focus();
	};

	const placesLibrary = useMapsLibrary("places");
	useEffect(() => {
		if (!placesLibrary || !inputRef || !inputRef.current) return;
		const autocomplete = new placesLibrary.Autocomplete(inputRef.current, {
			types: ["establishment"], // filter result to show establishment type only
			componentRestrictions: { country: ["IT"] }, // optional
			fields: ["name", "formatted_address", "opening_hours"], // you pay only for the requested data
		});
		const listener = autocomplete.addListener("place_changed", () => {
			const place = autocomplete.getPlace();
			onPlaceChanged(place);
		});
		// cleanup
		return () => {
			listener.remove();
		};
	}, [placesLibrary, inputRef]);

	return (
		<div>
			<div>
				<input
					id="pac"
					ref={inputRef}
					defaultValue={inputValue}
					onChange={handleInputChange}
					placeholder={"Find-address"}
					onKeyDown={handleKeyDown}
				/>
				<label>{"Import data from Google"}</label>
			</div>
			{success && <p> {"Data Imported successfully!"}</p>}
		</div>
	);
};

[usefulthink]

@sebolio Thanks for taking part in this discussion!

The comprehensive answer to that question would be "it depends", and there are at least three different ways to do it depending on what you need in terms of flexibility, theming and structure, etc.

using google.maps.places.PlaceAutocompleteElement

This is the new (currently in alpha) version that seems to avoid some of the problems with the older google.maps.places.Autocomplete and google.maps.places.SearchBox classes. I haven't played around with it yet, but according to the docs here an implementation would be something like this:

const Autocomplete = () => {
  const [containerEl, setContainerEl] = useState(null);
  const containerRef = useCallback(el => setContainerEl(el));
  const places = useMapsLibrary('places');

  useEffect(() => {
    if (!places || !containerEl) return;

    const input = document.createElement('input');
    const pac = new places.PlaceAutocompleteElement({ inputElement: input });

    containerEl.appendChild(pac.element);
    const listener = pac.addListener('gmp-placeselect', ({place}) => {
      // handle selected place...
    });

    return () => {
      pac.element.remove();
      listener.remove();
    }
  }, [places, containerEl])

  return <div ref={containerRef}></div>;
}

I'm still hoping for a proper web-component based solution, where the simplest solution would become something along the lines of:

const Autocomplete = () => {
  return (
    <gmp-autocomplete onGmpPlaceselect={...}></gmp-autocomplete>
  );
}

using google.maps.places.Autocomplete or google.maps.places.SearchBox

These would follow the same pattern, except that you will be responsible for the input-element.

But I would generally discourage using them since these will create their own DOM-elements at some other place in the document (I think it does something like appending them to be body where the <script> tag loading the maps API is found), which doesn't mesh very well with the way react applications usually work (although chances are that they will be outside the application root).

using google.maps.places.AutocompleteService

If you want to control it to the last bit, use the google.maps.places.AutocompleteService and your own components to render the input, result-list and connect it to the autocomplete service, that would be something like

const Autocomplete = (props) => {
  const placesLibrary = useMapsLibrary('places');
  const [service, setService] = useState(null);
  const [results, setResults] = useState([]);
  const [inputValue, setInputValue] = useState(null);

  // create autocompleteService once available
  useEffect(() => {
    if (placesLibrary)
      setService(new placesLibrary.AutocompleteService());

    return () => setService(null);
  }, [placesLibrary]);

  const updateResults = useCallback(async (inputValue) => {
    if (!service) {
      setResults([]);
      return;
    }

    const request = {input: inputValue};
    const res = await service.getQueryPredictions(request);

    setResults(res);
  });

  const onInputChange = useCallback(ev => {
    const value = ev.target.value;
    setInputValue(value);
    updateResults(value);
  });

  if (!service) return null;

  return (
    <div>
        {/* render input */}
        <input value={inputValue} onChange={onInputChange} />
        {/* render result-list */}
        {results.length > 0 && (
          <ul>
            {results.map(r => (
              <li>...</li>
            ))}
          </ul>
        )}
      </div>
  );
};

(note: this is off the top of my head and untested, I might have missed something and it's certainly not feature-complete, but the basic idea should be clear)

Finally, there are also other react-components around that are directly using the places-autocomplete API and provide better customise-ability than the builtin options (not researching them now, but I can probably provide a list of compatible ones at some point).