Merge branch 'develop' into chore/workflows

Author: plumdumpling

README.md

@@ -16,6 +16,7 @@ This is a JavaScript library to easily implement a Google Maps map into your Rea
   - [useDirections](#usedirections)
   - [useGeocoder](#usegeocoder)
   - [usePlacesService](#useplacesservice)
+  - [useDistanceMatrix](#usedistancematrix)
 - [Publish](#publish)
 
 ## Requirements
@@ -479,6 +480,35 @@ Returns the [`PlacesService`](google.maps.places.PlacesService) class to use dir
 google.maps.places.PlacesService
 ```
 
+### useDistanceMatrix
+
+React hook to use the [Google Maps Distance Matrix Service](https://developers.google.com/maps/documentation/javascript/distancematrix) in any component.
+
+#### Usage
+
+```jsx
+import React from 'react';
+import { useDistanceMatrix } from '@ubilabs/google-maps-react-hooks';
+
+const MyComponent = () => {
+  const service = useDistanceMatrix();
+
+  service.getDistanceMatrix(request, response => {
+    // Do something with the response
+  }
+
+  return (...);
+};
+```
+
+#### Return value
+
+Returns the [`DistanceMatrixService`](google.maps.DistanceMatrixService) class to use directly.
+
+```TypeScript
+google.maps.DistanceMatrixService
+```
+
 ## Publish (only for maintainers)
 
 `npm publish --access public`

examples/package.json

@@ -8,7 +8,9 @@
     "clean-examples": "rm -rf public .parcel-cache",
     "start:map": "PARCEL_AUTOINSTALL=false parcel serve ./basic-google-map/index.html --dist-dir public --port 1234",
     "start:map-markers": "PARCEL_AUTOINSTALL=false parcel serve ./google-map-with-markers/index.html --dist-dir public --port 1234",
-    "start:geocoding": "PARCEL_AUTOINSTALL=false parcel serve ./geocoding/index.html --dist-dir public --port 1234"
+    "start:geocoding": "PARCEL_AUTOINSTALL=false parcel serve ./geocoding/index.html --dist-dir public --port 1234",
+    "start:places": "PARCEL_AUTOINSTALL=false parcel serve ./places/index.html --dist-dir public --port 1234",
+    "start:autocomplete": "PARCEL_AUTOINSTALL=false parcel serve ./places-autocomplete/index.html --dist-dir public --port 1234"
   },
   "license": "MIT",
   "dependencies": {

examples/places-autocomplete/README.md

@@ -0,0 +1,36 @@
+# Basic Google Maps Setup Example
+
+This is an example setup of a **Map with a Places Autocomplete Search** to show the usage of the **useAutocomplete hook** with the Google Maps React Hooks library.
+
+## Instructions
+
+To run this project, clone the Google Maps React Hooks repository locally.
+
+First go to the root of the repository and run:
+
+```shell
+npm install
+````
+
+once to install all dependencies.
+
+Then start this example locally with
+
+```shell
+npm run start:autocomplete-example
+```
+
+**NOTE**:
+To see the examples it is needed to add an `.env` file with a [Google Maps API key](https://developers.google.com/maps/documentation/embed/get-api-key#:~:text=Go%20to%20the%20Google%20Maps%20Platform%20%3E%20Credentials%20page.&text=On%20the%20Credentials%20page%2C%20click,Click%20Close.) in the following format:
+
+`GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"`
+
+An example can be found in `.env.example`.
+
+## Output
+
+The project will start at [localhost:1234](http://localhost:1234) and show a map with an input field and an autocomplete functionality.
+
+![image](https://user-images.githubusercontent.com/39244966/196221028-34d47ae1-b612-4886-bd51-f736ffb77197.png)
+
+![image](https://user-images.githubusercontent.com/39244966/196220079-22405c58-c364-48bf-b70c-dc828e4bd635.png)

examples/places-autocomplete/app.tsx

@@ -0,0 +1,46 @@
+import React, {FunctionComponent, useState, useCallback} from 'react';
+import {GoogleMapProvider} from '@ubilabs/google-maps-react-hooks';
+
+import MapCanvas from './components/map-canvas/map-canvas';
+import PlacesSearch from './components/places-search/places-search';
+
+import {GOOGLE_MAPS_API_KEY} from '../constants';
+
+import './main.module.css';
+
+const mapOptions = {
+  center: {lat: 53.5582447, lng: 9.647645},
+  zoom: 6,
+  disableDefaultUI: true,
+  zoomControl: true
+};
+
+const App: FunctionComponent<Record<string, unknown>> = () => {
+  const [mapContainer, setMapContainer] = useState<HTMLDivElement | null>(null);
+
+  const mapRef = useCallback(
+    (node: React.SetStateAction<HTMLDivElement | null>) => {
+      node && setMapContainer(node);
+    },
+    []
+  );
+
+  return (
+    <React.StrictMode>
+      <GoogleMapProvider
+        googleMapsAPIKey={GOOGLE_MAPS_API_KEY}
+        mapContainer={mapContainer}
+        options={mapOptions}
+        // Add the places library
+        libraries={['places']}
+      >
+        <div id="container">
+          <MapCanvas ref={mapRef} />
+          <PlacesSearch />
+        </div>
+      </GoogleMapProvider>
+    </React.StrictMode>
+  );
+};
+
+export default App;

examples/places-autocomplete/components/map-canvas/map-canvas.module.css

@@ -0,0 +1,4 @@
+.map {
+  width: 100%;
+  height: 100%;
+}

examples/places-autocomplete/components/map-canvas/map-canvas.tsx

@@ -0,0 +1,9 @@
+import React, {forwardRef} from 'react';
+
+import styles from './map-canvas.module.css';
+
+const MapCanvas = forwardRef<HTMLDivElement, Record<string, unknown>>(
+  (_, ref) => <div ref={ref} className={styles.map} />
+);
+
+export default MapCanvas;

examples/places-autocomplete/components/places-search/places-search.module.css

@@ -0,0 +1,8 @@
+.searchInput {
+  position: absolute;
+  top: 1rem;
+  right: 1rem;
+  width: 20rem;
+  height: 2rem;
+  padding-left: 0.5rem;
+}

examples/places-autocomplete/components/places-search/places-search.tsx

@@ -0,0 +1,68 @@
+import React, {useEffect, useRef, useState} from 'react';
+import {useAutocomplete, useGoogleMap} from '@ubilabs/google-maps-react-hooks';
+
+import styles from './places-search.module.css';
+
+const PlacesSearch = () => {
+  const {map} = useGoogleMap();
+
+  // Use the input ref to pass an input field to the useAutocomplete hook below
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  const [inputValue, setInputValue] = useState('');
+  const [selectedPlace, setSelectedPlace] =
+    useState<google.maps.places.PlaceResult | null>(null);
+
+  const [marker, setMarker] = useState<google.maps.Marker | null>(null);
+
+  const onPlaceChanged = (place: google.maps.places.PlaceResult) => {
+    if (place) {
+      setSelectedPlace(place);
+      setInputValue(place.formatted_address || place.name);
+
+      // Keep focus on input element
+      inputRef.current?.focus();
+    }
+  };
+
+  // Use the useAutocomplete hook and pass the input field ref and the onPlaceChanged function to it
+  useAutocomplete({
+    inputField: inputRef && inputRef.current,
+    onPlaceChanged
+  });
+
+  const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setInputValue(event.target.value);
+  };
+
+  useEffect(() => {
+    if (map && selectedPlace) {
+      if (marker) {
+        marker.setMap(null);
+      }
+
+      const markerOptions: google.maps.MarkerOptions = {
+        map,
+        position: selectedPlace?.geometry?.location,
+        title: selectedPlace.name,
+        clickable: false
+      };
+
+      // Add a marker whenever a place was selected
+      const newMarker = new google.maps.Marker(markerOptions);
+
+      setMarker(newMarker);
+    }
+  }, [map, selectedPlace]);
+
+  return (
+    <input
+      className={styles.searchInput}
+      ref={inputRef}
+      value={inputValue}
+      onChange={handleInputChange}
+    />
+  );
+};
+
+export default PlacesSearch;

examples/places-autocomplete/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="de-DE">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
+    <title>
+      Example Google Map with a places search to show the usage of the
+      useAutocomplete hook of the Google Maps React Hooks.
+    </title>
+    <meta
+      name="description"
+      content="Example Google Map with a places search to show the usage of the useAutocomplete hook of the Google Maps React Hooks."
+    />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./index.tsx"></script>
+  </body>
+</html>

examples/places-autocomplete/index.tsx

@@ -0,0 +1,6 @@
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+import App from './app';
+
+ReactDOM.render(<App />, document.getElementById('app'));