Add Geolocation component

docs/search-ui-react.geolocationprops.handleclick.md

@@ -4,7 +4,7 @@
 
 ## GeolocationProps.handleClick property
 
-A function which is called when the geolocation button is clicked.
+A function which is called when the geolocation button is clicked, after user's position is successfully determined.
 
 <b>Signature:</b>
 

docs/search-ui-react.geolocationprops.md

@@ -19,7 +19,7 @@ export interface GeolocationProps
 |  [customCssClasses?](./search-ui-react.geolocationprops.customcssclasses.md) | [GeolocationCssClasses](./search-ui-react.geolocationcssclasses.md) | <i>(Optional)</i> CSS classes for customizing the component styling. |
 |  [GeolocationIcon?](./search-ui-react.geolocationprops.geolocationicon.md) | React.FunctionComponent | <i>(Optional)</i> Custom icon component to display along with the button. |
 |  [geolocationOptions?](./search-ui-react.geolocationprops.geolocationoptions.md) | PositionOptions | <i>(Optional)</i> Configuration used when collecting the user's location. Definition: [https://w3c.github.io/geolocation-api/\#position\_options\_interface](https://w3c.github.io/geolocation-api/#position_options_interface)<!-- -->. |
-|  [handleClick?](./search-ui-react.geolocationprops.handleclick.md) | (position: GeolocationPosition) =&gt; void | <i>(Optional)</i> A function which is called when the geolocation button is clicked. |
+|  [handleClick?](./search-ui-react.geolocationprops.handleclick.md) | (position: GeolocationPosition) =&gt; void | <i>(Optional)</i> A function which is called when the geolocation button is clicked, after user's position is successfully determined. |
 |  [label?](./search-ui-react.geolocationprops.label.md) | string | <i>(Optional)</i> The label for the button. Defaults to 'Use my location'. |
 |  [radius?](./search-ui-react.geolocationprops.radius.md) | number | <i>(Optional)</i> The radius, in miles, around the user's location to find results. Defaults to 50. If location accuracy is low, a larger radius may be used automatically. |
 

src/components/Geolocation.tsx

@@ -1,10 +1,8 @@
-import { Matcher, SelectableStaticFilter, useSearchActions, useSearchState } from '@yext/search-headless-react';
-import { executeSearch } from '../utils/search-operations';
-import { getUserLocation } from '../utils/location-operations';
 import { useComposedCssClasses } from '../hooks/useComposedCssClasses';
-import { useCallback, useState } from 'react';
+import { useState } from 'react';
 import LoadingIndicator from '../icons/LoadingIndicator';
 import { YextIcon } from '../icons/YextIcon';
+import { useGeolocationHandler } from '../hooks/useGeolocationHandler';
 
 /**
  * The CSS class interface for the Geolocation component.
@@ -43,15 +41,15 @@ export interface GeolocationProps {
   label?: string,
   /** Custom icon component to display along with the button. */
   GeolocationIcon?: React.FunctionComponent,
-  /** A function which is called when the geolocation button is clicked. */
+  /**
+   * A function which is called when the geolocation button is clicked,
+   * after user's position is successfully determined.
+   */
   handleClick?: (position: GeolocationPosition) => void,
   /** CSS classes for customizing the component styling. */
   customCssClasses?: GeolocationCssClasses
 }
 
-const LOCATION_FIELD_ID = 'builtin.location';
-const METERS_PER_MILE = 1609.344;
-
 /**
  * A React Component which collects location information to create a
  * location filter and perform a new search.
@@ -70,46 +68,15 @@ export function Geolocation({
   handleClick,
   customCssClasses,
 }: GeolocationProps): JSX.Element | null {
-  const searchActions = useSearchActions();
-  const staticFilters = useSearchState(s => s.filters.static || []);
   const [isFetchingLocation, setIsFetchingLocation] = useState<boolean>(false);
   const cssClasses = useComposedCssClasses(builtInCssClasses, customCssClasses);
 
-  const handleGeolocationClick = useCallback(async () => {
-    setIsFetchingLocation(true);
-    try {
-      const position = await getUserLocation(geolocationOptions);
-      if (handleClick) {
-        handleClick(position);
-        return;
-      }
-      const { latitude, longitude, accuracy } = position.coords;
-      const locationFilter: SelectableStaticFilter = {
-        displayName: 'Current Location',
-        selected: true,
-        filter: {
-          kind: 'fieldValue',
-          fieldId: LOCATION_FIELD_ID,
-          matcher: Matcher.Near,
-          value: {
-            lat: latitude,
-            lng: longitude,
-            radius: Math.max(accuracy, radius * METERS_PER_MILE)
-          },
-        }
-      };
-      const nonLocationFilters = staticFilters.filter(filter => {
-        return !(filter.filter.kind === 'fieldValue'
-          && filter.filter.fieldId === LOCATION_FIELD_ID);
-      });
-      searchActions.setStaticFilters([...nonLocationFilters, locationFilter]);
-      executeSearch(searchActions);
-    } catch (e) {
-      console.warn(e);
-    } finally {
-      setIsFetchingLocation(false);
-    }
-  }, [geolocationOptions, handleClick, radius, searchActions, staticFilters]);
+  const handleGeolocationClick = useGeolocationHandler({
+    setIsFetchingLocation,
+    geolocationOptions,
+    radius,
+    handleUserPosition: handleClick
+  });
 
   return (
     <div className={cssClasses.geolocationContainer}>
@@ -121,4 +88,4 @@ export function Geolocation({
       </div>
     </div>
   );
-}
+}

src/hooks/useGeolocationHandler.ts

@@ -0,0 +1,82 @@
+
+import { Matcher, SelectableStaticFilter, useSearchActions, useSearchState } from '@yext/search-headless-react';
+import { executeSearch } from '../utils/search-operations';
+import { getUserLocation } from '../utils/location-operations';
+import { useCallback } from 'react';
+
+const LOCATION_FIELD_ID = 'builtin.location';
+const METERS_PER_MILE = 1609.344;
+
+/**
+ * The props for {@link useGeolocationHandler} hook.
+ *
+ * @internal
+ */
+interface GeolocationhandlerProps {
+  /** A React dispatch function use to update the status of fetching user's location. */
+  setIsFetchingLocation: React.Dispatch<React.SetStateAction<boolean>>,
+  /** Configuration used when collecting the user's location. */
+  geolocationOptions?: PositionOptions,
+  /**
+   * The radius, in miles, around the user's location to find results. Defaults to 50.
+   * If location accuracy is low, a larger radius may be used automatically.
+   */
+  radius?: number,
+  /** Custom handler function to call after user's position is successfully determined. */
+  handleUserPosition?: (position: GeolocationPosition) => void
+}
+
+/**
+ * Returns a function that will collect user's geolocation and, by default, will set
+ * a built-in location filter and execute a search.
+ *
+ * @internal
+ *
+ * @param props - {@link GeolocationProps}
+ * @returns A function to collect and process user's geolocation
+ */
+export function useGeolocationHandler({
+  setIsFetchingLocation,
+  geolocationOptions,
+  radius = 50,
+  handleUserPosition
+}: GeolocationhandlerProps): () => Promise<void> {
+  const searchActions = useSearchActions();
+  const staticFilters = useSearchState(s => s.filters.static || []);
+
+  const defaultHandleUserPosition = useCallback((position: GeolocationPosition) => {
+    const { latitude, longitude, accuracy } = position.coords;
+    const locationFilter: SelectableStaticFilter = {
+      displayName: 'Current Location',
+      selected: true,
+      filter: {
+        kind: 'fieldValue',
+        fieldId: LOCATION_FIELD_ID,
+        matcher: Matcher.Near,
+        value: {
+          lat: latitude,
+          lng: longitude,
+          radius: Math.max(accuracy, radius * METERS_PER_MILE)
+        },
+      }
+    };
+    const nonLocationFilters = staticFilters.filter(filter => {
+      return !(filter.filter.kind === 'fieldValue'
+        && filter.filter.fieldId === LOCATION_FIELD_ID);
+    });
+    searchActions.setStaticFilters([...nonLocationFilters, locationFilter]);
+    executeSearch(searchActions);
+  }, [radius, searchActions, staticFilters]);
+
+  return useCallback(async () => {
+    setIsFetchingLocation(true);
+    try {
+      const position = await getUserLocation(geolocationOptions);
+      (handleUserPosition ?? defaultHandleUserPosition)(position);
+    } catch (e) {
+      console.warn(e);
+    } finally {
+      setIsFetchingLocation(false);
+    }
+  }, [setIsFetchingLocation, geolocationOptions, handleUserPosition, defaultHandleUserPosition]);
+}

tests/components/Geolocation.test.tsx

@@ -113,98 +113,114 @@ it('renders custom icon when provided', () => {
   expect(LocationIcon).toBeDefined();
 });
 
-it('executes handleClick when provided', async () => {
-  const mockedHandleClickFn = jest.fn();
-  const actions = spyOnActions();
-  render(<Geolocation handleClick={mockedHandleClickFn} />);
-  clickUpdateLocation();
-  await waitFor(() => {
-    expect(mockedHandleClickFn).toHaveBeenCalledWith(newGeoPosition);
+describe('custom click handler', () => {
+  it('executes handleClick when user\'s location is successfully determined', async () => {
+    const mockedHandleClickFn = jest.fn();
+    const actions = spyOnActions();
+    render(<Geolocation handleClick={mockedHandleClickFn} />);
+    clickUpdateLocation();
+    await waitFor(() => {
+      expect(mockedHandleClickFn).toHaveBeenCalledWith(newGeoPosition);
+    });
+    expect(actions.executeVerticalQuery).not.toBeCalled();
+  });
+
+  it('does not execute handleClick when error occurs from collecting user\'s location', async () => {
+    const consoleWarnSpy = jest.spyOn(global.console, 'warn').mockImplementation();
+    jest.spyOn(locationOperations, 'getUserLocation').mockRejectedValue('mocked error!');
+    const mockedHandleClickFn = jest.fn();
+    render(<Geolocation handleClick={mockedHandleClickFn} />);
+    clickUpdateLocation();
+    await waitFor(() => {
+      expect(consoleWarnSpy).toBeCalledWith('mocked error!');
+    });
+    expect(mockedHandleClickFn).not.toBeCalled();
   });
-  expect(actions.executeVerticalQuery).not.toBeCalled();
 });
 
-it('sets a location filter with user\'s coordinates in static filters state when clicked', async () => {
-  const actions = spyOnActions();
-  render(<Geolocation />);
-  clickUpdateLocation();
+describe('default click handler', () => {
+  it('sets a location filter using provided radius', async () => {
+    const actions = spyOnActions();
+    render(<Geolocation radius={10}/>);
+    clickUpdateLocation();
 
-  const expectedLocationFilter: SelectableStaticFilter = createLocationFilter();
-  expect(locationOperations.getUserLocation).toBeCalled();
-  await waitFor(() => {
-    expect(actions.setStaticFilters).toBeCalledWith([expectedLocationFilter]);
+    const expectedLocationFilter: SelectableStaticFilter = createLocationFilter(10 * 1609.344);
+    await waitFor(() => {
+      expect(actions.setStaticFilters).toBeCalledWith([expectedLocationFilter]);
+    });
   });
-});
 
-it('sets a location filter using provided radius', async () => {
-  const actions = spyOnActions();
-  render(<Geolocation radius={10}/>);
-  clickUpdateLocation();
+  it('sets a location filter with user\'s coordinates in static filters state when clicked', async () => {
+    const actions = spyOnActions();
+    render(<Geolocation />);
+    clickUpdateLocation();
 
-  const expectedLocationFilter: SelectableStaticFilter = createLocationFilter(10 * 1609.344);
-  await waitFor(() => {
-    expect(actions.setStaticFilters).toBeCalledWith([expectedLocationFilter]);
+    const expectedLocationFilter: SelectableStaticFilter = createLocationFilter();
+    expect(locationOperations.getUserLocation).toBeCalled();
+    await waitFor(() => {
+      expect(actions.setStaticFilters).toBeCalledWith([expectedLocationFilter]);
+    });
   });
-});
 
-it('sets a location filter using a larger radius than provided value due to low accuracy of user coordinate', async () => {
-  jest.spyOn(locationOperations, 'getUserLocation').mockResolvedValue(newGeoPositionWithLowAccuracy);
-  const actions = spyOnActions();
-  render(<Geolocation radius={10}/>);
-  clickUpdateLocation();
+  it('replace existing location filters with a new location filter in static filters state', async () => {
+    mockAnswersState(mockedStateWithFilters);
+    const actions = spyOnActions();
+    render(<Geolocation />);
+    clickUpdateLocation();
 
-  const accuracy = newGeoPositionWithLowAccuracy.coords.accuracy;
-  const expectedLocationFilter: SelectableStaticFilter = createLocationFilter(accuracy);
-  await waitFor(() => {
-    expect(actions.setStaticFilters).toBeCalledWith([expectedLocationFilter]);
+    const expectedStaticFilters = [
+      {
+        displayName: 'My name',
+        selected: true,
+        filter: {
+          kind: 'fieldValue',
+          fieldId: 'employeeName',
+          matcher: Matcher.Equals,
+          value: 'Bob',
+        }
+      },
+      createLocationFilter()
+    ];
+    await waitFor(() => {
+      expect(actions.setStaticFilters).toBeCalledWith(expectedStaticFilters);
+    });
   });
-});
 
-it('replace existing location filters with a new location filter in static filters state', async () => {
-  mockAnswersState(mockedStateWithFilters);
-  const actions = spyOnActions();
-  render(<Geolocation />);
-  clickUpdateLocation();
-
-  const expectedStaticFilters = [
-    {
-      displayName: 'My name',
-      selected: true,
-      filter: {
-        kind: 'fieldValue',
-        fieldId: 'employeeName',
-        matcher: Matcher.Equals,
-        value: 'Bob',
-      }
-    },
-    createLocationFilter()
-  ];
-  await waitFor(() => {
-    expect(actions.setStaticFilters).toBeCalledWith(expectedStaticFilters);
+  it('sets a location filter using a larger radius than provided value due to low accuracy of user coordinate', async () => {
+    jest.spyOn(locationOperations, 'getUserLocation').mockResolvedValue(newGeoPositionWithLowAccuracy);
+    const actions = spyOnActions();
+    render(<Geolocation radius={10}/>);
+    clickUpdateLocation();
+
+    const accuracy = newGeoPositionWithLowAccuracy.coords.accuracy;
+    const expectedLocationFilter: SelectableStaticFilter = createLocationFilter(accuracy);
+    await waitFor(() => {
+      expect(actions.setStaticFilters).toBeCalledWith([expectedLocationFilter]);
+    });
   });
-});
 
-it('executes a new search when clicked', async () => {
-  const actions = spyOnActions();
-  render(<Geolocation />);
-  clickUpdateLocation();
+  it('executes a new search when clicked', async () => {
+    const actions = spyOnActions();
+    render(<Geolocation />);
+    clickUpdateLocation();
 
-  await waitFor(() => {
-    expect(actions.executeVerticalQuery).toBeCalled();
+    await waitFor(() => {
+      expect(actions.executeVerticalQuery).toBeCalled();
+    });
   });
-});
 
-it('handles error when collecting user\'s location', async () => {
-  const consoleWarnSpy = jest.spyOn(global.console, 'warn').mockImplementation();
-  jest.spyOn(locationOperations, 'getUserLocation').mockRejectedValue('mocked error!');
-  const actions = spyOnActions();
-  render(<Geolocation />);
-  clickUpdateLocation();
-  await waitFor(() => {
-    expect(consoleWarnSpy).toBeCalledWith('mocked error!');
+  it('does not execute default handleClick when error occurs from collecting user\'s location', async () => {
+    const consoleWarnSpy = jest.spyOn(global.console, 'warn').mockImplementation();
+    jest.spyOn(locationOperations, 'getUserLocation').mockRejectedValue('mocked error!');
+    const actions = spyOnActions();
+    render(<Geolocation />);
+    clickUpdateLocation();
+    await waitFor(() => {
+      expect(consoleWarnSpy).toBeCalledWith('mocked error!');
+    });
+    expect(actions.setStaticFilters).not.toBeCalled();
+    expect(actions.executeVerticalQuery).not.toBeCalled();
   });
-  expect(actions.setStaticFilters).not.toBeCalled();
-  expect(actions.executeVerticalQuery).not.toBeCalled();
 });
 
 function clickUpdateLocation() {