From 69b23734270e8754a518790620872dc1f4136cc7 Mon Sep 17 00:00:00 2001 From: Martin Schuhfuss Date: Thu, 15 Feb 2024 12:10:14 +0100 Subject: [PATCH] refactor!: remove obsolete hooks (#219) BREAKING-CHANGE: removed the `useStreetViewPanorama()` and `useDirectionsService()` hooks. --- .../hooks/use-api-loading-status.md | 2 +- .../hooks/use-directions-service.md | 61 --------- .../hooks/use-streetview-panorama.md | 86 ------------- .../interacting-with-google-maps-api.md | 6 - docs/table-of-contents.json | 5 +- .../__tests__/directions-service.test.tsx | 30 ----- .../__tests__/street-view-panorama.test.tsx | 34 ----- src/hooks/directions-service.ts | 118 ------------------ src/hooks/street-view-panorama.ts | 58 --------- src/index.ts | 2 - 10 files changed, 3 insertions(+), 399 deletions(-) delete mode 100644 docs/api-reference/hooks/use-directions-service.md delete mode 100644 docs/api-reference/hooks/use-streetview-panorama.md delete mode 100644 src/hooks/__tests__/directions-service.test.tsx delete mode 100644 src/hooks/__tests__/street-view-panorama.test.tsx delete mode 100644 src/hooks/directions-service.ts delete mode 100644 src/hooks/street-view-panorama.ts diff --git a/docs/api-reference/hooks/use-api-loading-status.md b/docs/api-reference/hooks/use-api-loading-status.md index cc036cb0..955bfd91 100644 --- a/docs/api-reference/hooks/use-api-loading-status.md +++ b/docs/api-reference/hooks/use-api-loading-status.md @@ -1,4 +1,4 @@ -# `useApiIsLoaded` Hook +# `useApiLoadingStatus` Hook React hook to get the current status of the API Loader. This can be used to react to loading-errors. diff --git a/docs/api-reference/hooks/use-directions-service.md b/docs/api-reference/hooks/use-directions-service.md deleted file mode 100644 index e1b3fc5c..00000000 --- a/docs/api-reference/hooks/use-directions-service.md +++ /dev/null @@ -1,61 +0,0 @@ -# `useDirectionsService` Hook - -React hook to use the Google Maps Platform [Directions Service](https://developers.google.com/maps/documentation/javascript/reference/directions) in any component. - -## Usage - -```tsx -import React from 'react'; -import {useDirectionsService} from '@vis.gl/react-google-maps-hooks'; - -const MyComponent = () => { - const { - directionsService, - directionsRenderer, - renderRoute, - setRenderedRouteIndex - } = useDirectionsService(directionsOptions); - - // Do something with the directions - - return (...); -}; -``` - -## Parameters - -### DirectionsProps - -Pass in whether to render on a Google Maps Platform map or not and the -[DirectionsRendererOptions](https://developers.google.com/maps/documentation/javascript/reference/directions#DirectionsRendererOptions). - -```TypeScript -export interface DirectionsServiceHookOptions { - mapId?: string; - renderOnMap?: boolean; - renderOptions?: google.maps.DirectionsRendererOptions; -} -``` - -The `mapId` needs to be applied when multiple `Map` components are used. - -## Return value - -Returns an object with the following elements: - -- [`directionsService`](https://developers.google.com/maps/documentation/javascript/reference/directions#DirectionsService) instance -- [`directionsRenderer`](https://developers.google.com/maps/documentation/javascript/reference/directions#DirectionsRenderer) instance -- `renderRoute` retrieve directions and render them on the map, will return the route result (`google.maps.DirectionsResult`). -- `setRenderedRouteIndex` select which of multiple routes from the `google.maps.DirectionsResult` should be rendered - -```TypeScript -interface DirectionsServiceHookReturns { - directionsService: google.maps.DirectionsService | null; - directionsRenderer: google.maps.DirectionsRenderer | null; - renderRoute: ((request: google.maps.DirectionsRequest) => Promise) | null; - setRenderedRouteIndex : ((index: number) => void) | null; -} -``` - -**NOTE**: -renderRoute and setRenderedRouteIndex are only returned when `renderRoute` is set to true diff --git a/docs/api-reference/hooks/use-streetview-panorama.md b/docs/api-reference/hooks/use-streetview-panorama.md deleted file mode 100644 index 994c0c8f..00000000 --- a/docs/api-reference/hooks/use-streetview-panorama.md +++ /dev/null @@ -1,86 +0,0 @@ -# `useStreetViewPanorama` Hook - -React hook to use the Google Maps Platform [Street View Panorama](https://developers.google.com/maps/documentation/javascript/streetview) in -any component. - -## Usage - -The `StreetViewPanorama` can either be used within a DOM element, like a `
` element: - -```tsx -import React, {useEffect} from 'react'; -import { - useMap, - useStreetViewPanorama -} from '@vis.gl/react-google-maps-hooks'; - -const MyComponent = () => { - const [divContainer, setDivContainer] = useState(null); - - const divRef = useCallback( - (node: React.SetStateAction) => { - node && setDivContainer(node); - }, - [] - ); - - const map = useMap(); - - const position = /** google.maps.LatLng */; - const pov = /** google.maps.StreetViewPov */; - - const panorama = useStreetViewPanorama({ - divElement: divContainer, - position, - pov - }); - - return
; -}; -``` - -or can be created on its own to be used by the map: - -```tsx -import React, {useEffect} from 'react'; -import { - useMap, - useStreetViewPanorama -} from '@vis.gl/react-google-maps-hooks'; - -const MyComponent = () => { - const position = /** google.maps.LatLng */; - const pov = /** google.maps.StreetViewPov */; - - useStreetViewPanorama({ - position, - pov - }); - - return null; -}; -``` - -## Return value - -Returns a [`StreetViewPanorama`](https://developers.google.com/maps/documentation/javascript/reference/street-view#StreetViewPanorama) -instance to use directly. - -## Parameters - -### StreetViewPanoramaProps - -Optional options that can be passed to display a street view -location: [Street View Locations and Point-of-View (POV)](https://developers.google.com/maps/documentation/javascript/streetview#StreetViewLocation). - -```TypeScript -interface StreetViewPanoramaProps { - mapId?: string; - divElement?: HTMLElement | null; - position?: google.maps.LatLng | google.maps.LatLngLiteral; - pov?: google.maps.StreetViewPov; - zoom?: number; -} -``` - -The `mapId` needs to be applied when multiple `Map` components are used. diff --git a/docs/guides/interacting-with-google-maps-api.md b/docs/guides/interacting-with-google-maps-api.md index 3f874567..437643b1 100644 --- a/docs/guides/interacting-with-google-maps-api.md +++ b/docs/guides/interacting-with-google-maps-api.md @@ -46,12 +46,6 @@ const App = () => ( ); ``` -Other hooks provide access to different Google Maps API services: - -- [useDirectionsService](../api-reference/hooks/use-directions-service.md) - for the [Directions Service](https://developers.google.com/maps/documentation/javascript/directions) -- [useStreetViewPanorama](../api-reference/hooks/use-streetview-panorama.md) for the [Streetview Service](https://developers.google.com/maps/documentation/javascript/streetview) - The [useMapsLibrary](../api-reference/hooks/use-maps-library.md) hook can be utilized to load other parts of the Google Maps API that are not loaded by default. For example, the Places Service or the Geocoding Service. diff --git a/docs/table-of-contents.json b/docs/table-of-contents.json index b3d2887b..6c2cd4b9 100644 --- a/docs/table-of-contents.json +++ b/docs/table-of-contents.json @@ -49,10 +49,9 @@ "items": [ "api-reference/hooks/use-map", - "api-reference/hooks/use-api-is-loaded", "api-reference/hooks/use-maps-library", - "api-reference/hooks/use-directions-service", - "api-reference/hooks/use-streetview-panorama" + "api-reference/hooks/use-api-is-loaded", + "api-reference/hooks/use-api-loading-status" ] } ] diff --git a/src/hooks/__tests__/directions-service.test.tsx b/src/hooks/__tests__/directions-service.test.tsx deleted file mode 100644 index 42b1bff7..00000000 --- a/src/hooks/__tests__/directions-service.test.tsx +++ /dev/null @@ -1,30 +0,0 @@ -import React from 'react'; -import {renderHook} from '@testing-library/react'; -import {initialize, DirectionsService} from '@googlemaps/jest-mocks'; - -import {APIProvider} from '../../components/api-provider'; -import {useDirectionsService} from '../directions-service'; - -import {waitForMockInstance} from './__utils__/wait-for-mock-instance'; - -jest.mock('../../libraries/google-maps-api-loader'); - -let wrapper: ({children}: {children: React.ReactNode}) => JSX.Element | null; - -beforeEach(() => { - initialize(); - - wrapper = ({children}: {children: React.ReactNode}) => ( - {children} - ); -}); - -test('directions service is initialized', async () => { - const {result} = renderHook(() => useDirectionsService(), {wrapper}); - - const service = await waitForMockInstance(DirectionsService); - - expect(service).toBeDefined(); - expect(result.current.directionsService).toBe(service); - expect(service).toBeInstanceOf(google.maps.DirectionsService); -}); diff --git a/src/hooks/__tests__/street-view-panorama.test.tsx b/src/hooks/__tests__/street-view-panorama.test.tsx deleted file mode 100644 index 411d4346..00000000 --- a/src/hooks/__tests__/street-view-panorama.test.tsx +++ /dev/null @@ -1,34 +0,0 @@ -import React from 'react'; -import {renderHook} from '@testing-library/react'; -import {initialize, StreetViewPanorama} from '@googlemaps/jest-mocks'; - -import {APIProvider} from '../../components/api-provider'; -import {useStreetViewPanorama} from '../street-view-panorama'; - -import {waitForMockInstance} from './__utils__/wait-for-mock-instance'; - -jest.mock('../../libraries/google-maps-api-loader'); - -let wrapper: ({children}: {children: React.ReactNode}) => JSX.Element | null; -let divElement: HTMLDivElement; - -beforeEach(() => { - initialize(); - - divElement = document.createElement('div'); - - wrapper = ({children}: {children: React.ReactNode}) => ( - {children} - ); -}); - -test('it should initialize a street view panorama', async () => { - const {result} = renderHook(() => useStreetViewPanorama({divElement}), { - wrapper - }); - - const service = await waitForMockInstance(StreetViewPanorama); - - expect(result.current).toBe(service); - expect(service).toBeInstanceOf(google.maps.StreetViewPanorama); -}); diff --git a/src/hooks/directions-service.ts b/src/hooks/directions-service.ts deleted file mode 100644 index 5b91e524..00000000 --- a/src/hooks/directions-service.ts +++ /dev/null @@ -1,118 +0,0 @@ -import {useMemo, useEffect, useCallback} from 'react'; - -import {useApiIsLoaded} from './use-api-is-loaded'; -import {useMap} from './use-map'; -import {assertNotNull} from '../libraries/assert-not-null'; - -export interface DirectionsServiceHookOptions { - mapId?: string; - renderOnMap?: boolean; - renderOptions?: google.maps.DirectionsRendererOptions; -} - -interface DirectionsServiceHookReturns { - directionsService: google.maps.DirectionsService | null; - directionsRenderer: google.maps.DirectionsRenderer | null; - renderRoute: - | (( - request: google.maps.DirectionsRequest - ) => Promise) - | null; - setRenderedRouteIndex: ((index: number) => void) | null; -} - -const useDirectionsRenderer = ( - mapId: string | null, - renderOnMap?: boolean, - renderOptions?: google.maps.DirectionsRendererOptions -) => { - const map = useMap(mapId); - - // create the renderer instance - const directionsRenderer = useMemo( - () => { - if (!map || !renderOnMap) return null; - - const renderer = new google.maps.DirectionsRenderer(renderOptions); - renderer.setMap(map); - - return renderer; - }, - // note: no dependency on renderOptions since those are handled in the - // next effect. - // eslint-disable-next-line react-hooks/exhaustive-deps - [map, renderOnMap] - ); - - useEffect( - () => { - if (!directionsRenderer) return; - - directionsRenderer.setOptions(renderOptions || {}); - }, - // note: directionsRenderer dependency isn't needed since the - // renderOptions will be set on initialization when creating the renderer. - // eslint-disable-next-line react-hooks/exhaustive-deps - [renderOptions] - ); - - return directionsRenderer; -}; - -/** - * Hook to get Google Maps Places Directions Service instance - */ -export const useDirectionsService = ( - props: DirectionsServiceHookOptions = {} -): DirectionsServiceHookReturns => { - const {mapId = null, renderOnMap, renderOptions} = props; - const isApiLoaded = useApiIsLoaded(); - - // Creates a Directions Service instance - const directionsService = useMemo(() => { - // Wait for Google Maps API to be loaded - if (!isApiLoaded) return null; - - return new google.maps.DirectionsService(); - }, [isApiLoaded]); - - // create the renderer instance - const directionsRenderer = useDirectionsRenderer( - mapId, - renderOnMap, - renderOptions - ); - - // Custom Directions route request followed by directions rendering - const renderRoute = useCallback( - async ( - request: google.maps.DirectionsRequest - ): Promise => { - // findAndRenderRoute() isn't callable when either directions - // service or renderer aren't ready - assertNotNull(directionsService); - assertNotNull(directionsRenderer); - - const result = await directionsService.route(request); - directionsRenderer.setDirections(result); - - return result; - }, - [directionsService, directionsRenderer] - ); - - // Renders directions route of given index - const setRenderedRouteIndex = (index: number) => { - assertNotNull(directionsRenderer); - - directionsRenderer.setRouteIndex(index); - }; - - return { - directionsService, - directionsRenderer, - renderRoute: directionsService && directionsRenderer ? renderRoute : null, - setRenderedRouteIndex: - directionsService && directionsRenderer ? setRenderedRouteIndex : null - }; -}; diff --git a/src/hooks/street-view-panorama.ts b/src/hooks/street-view-panorama.ts deleted file mode 100644 index 5dea3163..00000000 --- a/src/hooks/street-view-panorama.ts +++ /dev/null @@ -1,58 +0,0 @@ -/* eslint-disable complexity */ -import {useEffect, useState} from 'react'; -import {useApiIsLoaded} from './use-api-is-loaded'; -import {useMap} from './use-map'; - -export interface StreetViewPanoramaProps { - mapId?: string; - divElement?: HTMLElement | null; - position?: google.maps.LatLng | google.maps.LatLngLiteral; - pov?: google.maps.StreetViewPov; - zoom?: number; -} - -/** - * Hook to get Street View Panorama - */ -export const useStreetViewPanorama = ( - props: StreetViewPanoramaProps = {} -): google.maps.StreetViewPanorama | null => { - const {mapId, divElement, position, pov, zoom} = props; - const googleMapsAPIIsLoaded = useApiIsLoaded(); - const map = useMap(mapId); - - const [streetViewPanorama, setStreetViewPanorama] = - useState(null); - - // Creates a Street View instance - useEffect( - () => { - if (!googleMapsAPIIsLoaded) return; - - let pano: google.maps.StreetViewPanorama | null = null; - if (divElement) { - pano = new google.maps.StreetViewPanorama(divElement); - } else if (map) { - pano = map.getStreetView(); - } - - setStreetViewPanorama(pano); - - if (!pano) return; - if (pov) pano.setPov(pov); - if (position) pano.setPosition(position); - if (zoom || zoom === 0) pano.setZoom(zoom); - - return (): void => { - setStreetViewPanorama(null); - - if (map) map.setStreetView(null); - }; - }, - // fixme: implement extra hook to update FOV when props change - // eslint-disable-next-line react-hooks/exhaustive-deps - [googleMapsAPIIsLoaded, map, divElement] - ); - - return streetViewPanorama; -}; diff --git a/src/index.ts b/src/index.ts index 269ccbb4..5c622ff1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -9,8 +9,6 @@ export * from './hooks/use-api-loading-status'; export * from './hooks/use-api-is-loaded'; export * from './hooks/use-maps-library'; export * from './hooks/use-map'; -export * from './hooks/directions-service'; -export * from './hooks/street-view-panorama'; export {limitTiltRange} from './libraries/limit-tilt-range'; export * from './libraries/lat-lng-utils';