feat(geo): Rename 'Geocoder' to 'LocationSearch' (#1938)

slaymance · web-flow · commit 344e65f8a535 · 2022-05-19T18:05:15.000-07:00
* Re-alias Geocoder component as LocationSearch

* Refactor examples to use LocationSearch component

* Update Geocoder e2e tests to reflect LocationSearch change

* Update docs to reference LocationSearch instead of Geocoder

* Rename cypress test step files

* Create bright-frogs-remember.md
diff --git a/.changeset/bright-frogs-remember.md b/.changeset/bright-frogs-remember.md
@@ -0,0 +1,5 @@
+---
+"@aws-amplify/ui-react": patch
+---
+
+feat(geo): Rename 'Geocoder' to 'LocationSearch'
diff --git a/docs/src/pages/[platform]/components/geo/fragments/location-search-position.react.mdx b/docs/src/pages/[platform]/components/geo/fragments/location-search-position.react.mdx
@@ -1,16 +1,16 @@
 ```js{12}
-import { MapView, Geocoder } from '@aws-amplify/ui-react';
+import { MapView, LocationSearch } from '@aws-amplify/ui-react';
 import { Amplify } from 'aws-amplify';
 
 import '@aws-amplify/ui-react/styles.css';
 
 import awsExports from './aws-exports';
 
 Amplify.configure(awsExports);
-export default function GeocoderPosition() {
+export default function LocationSearchPosition() {
   return (
     <MapView>
-      <Geocoder position="top-left" />
+      <LocationSearch position="top-left" />
     </MapView>
   );
 }
diff --git a/docs/src/pages/[platform]/components/geo/fragments/location-search-quick-start.react.mdx b/docs/src/pages/[platform]/components/geo/fragments/location-search-quick-start.react.mdx
@@ -1,3 +1,3 @@
-```js{1,4,13} file=../../../../../../../examples/next/pages/ui/components/geo/map-with-geocoder/index.page.tsx
+```js{1,4,13} file=../../../../../../../examples/next/pages/ui/components/geo/map-with-location-search/index.page.tsx
 
 ```
diff --git a/docs/src/pages/[platform]/components/geo/fragments/location-search-standalone.react.mdx b/docs/src/pages/[platform]/components/geo/fragments/location-search-standalone.react.mdx
@@ -1,3 +1,3 @@
-```js{1,4,16} file=../../../../../../../examples/next/pages/ui/components/geo/standalone-geocoder/index.page.tsx
+```js{1,4,16} file=../../../../../../../examples/next/pages/ui/components/geo/standalone-location-search/index.page.tsx
 
 ```
diff --git a/docs/src/pages/[platform]/components/geo/react.mdx b/docs/src/pages/[platform]/components/geo/react.mdx
@@ -61,35 +61,43 @@ when the marker is clicked. The `offset` property can be used to prevent the pop
 _Note: Ensure `originalEvent.stopPropagation()` is called in the marker click handler. This allows the `showPopup`
 state to be handled by the component._
 
-## Geocoder (Location Search)
+## Location Search
 
-`Geocoder` provides location search powered by [Amazon Location Service](https://aws.amazon.com/location/) for the
-`MapView` component, using the viewport as the proximity for generating results. `Geocoder` is used as a child
+_Component can also be imported as `Geocoder`_
+
+`LocationSearch` provides location search powered by [Amazon Location Service](https://aws.amazon.com/location/) for the
+`MapView` component, using the viewport as the proximity for generating results. `LocationSearch` is used as a child
 component of `MapView` for which it renders visual markers and information based on its location search results.
 
-You can import the `Geocoder` component with related styles and use it as a child of `MapView` without any
+You can import the `LocationSearch` component with related styles and use it as a child of `MapView` without any
 additional configuration.
 
 <Fragment platforms={['react']}>
-  {({ platform }) => import(`./fragments/geocoder-quick-start.${platform}.mdx`)}
+  {({ platform }) =>
+    import(`./fragments/location-search-quick-start.${platform}.mdx`)
+  }
 </Fragment>
 
-### Geocoder Position
+### LocationSearch Position
 
-`Geocoder` can be provided a `position` property when used with `MapView`. The property is not reactive, meaning the
+`LocationSearch` can be provided a `position` property when used with `MapView`. The property is not reactive, meaning the
 position is fixed after the component mounts. Valid values are `'top-right'`, `'top-left'`, `'bottom-right'`, and
 `'bottom-left'`. Default value is `'top-right'`.
 
 <Fragment platforms={['react']}>
-  {({ platform }) => import(`./fragments/geocoder-position.${platform}.mdx`)}
+  {({ platform }) =>
+    import(`./fragments/location-search-position.${platform}.mdx`)
+  }
 </Fragment>
 
-### Standalone Geocoder
+### Standalone LocationSearch
 
-`Geocoder` can also be used as a standalone component without `MapView`. As a standalone component, `Geocoder`
+`LocationSearch` can also be used as a standalone component without `MapView`. As a standalone component, `LocationSearch`
 provides search results based on an initial proximity. When used as a standlone component, the `proximity` property
 with provided `latitude` and `longitude` properties is required.
 
 <Fragment platforms={['react']}>
-  {({ platform }) => import(`./fragments/standalone-geocoder.${platform}.mdx`)}
+  {({ platform }) =>
+    import(`./fragments/location-search-standalone.${platform}.mdx`)
+  }
 </Fragment>
diff --git a/examples/next/pages/ui/components/geo/map-with-location-search/aws-exports.js b/examples/next/pages/ui/components/geo/map-with-location-search/aws-exports.js
diff --git a/examples/next/pages/ui/components/geo/map-with-location-search/index.page.tsx b/examples/next/pages/ui/components/geo/map-with-location-search/index.page.tsx
@@ -1,4 +1,4 @@
-import { MapView, Geocoder } from '@aws-amplify/ui-react';
+import { MapView, LocationSearch } from '@aws-amplify/ui-react';
 import { Amplify } from 'aws-amplify';
 
 import '@aws-amplify/ui-react/styles.css';
@@ -7,10 +7,10 @@ import awsExports from './aws-exports';
 
 Amplify.configure(awsExports);
 
-export default function MapWithGeocoder() {
+export default function MapWithLocationSearch() {
   return (
     <MapView>
-      <Geocoder />
+      <LocationSearch />
     </MapView>
   );
 }
diff --git a/examples/next/pages/ui/components/geo/standalone-location-search/aws-exports.js b/examples/next/pages/ui/components/geo/standalone-location-search/aws-exports.js
diff --git a/examples/next/pages/ui/components/geo/standalone-location-search/index.page.tsx b/examples/next/pages/ui/components/geo/standalone-location-search/index.page.tsx
@@ -1,4 +1,4 @@
-import { Geocoder } from '@aws-amplify/ui-react';
+import { LocationSearch } from '@aws-amplify/ui-react';
 import { Amplify } from 'aws-amplify';
 
 import '@aws-amplify/ui-react/styles.css';
@@ -12,6 +12,6 @@ const SAN_FRANCISCO = {
   longitude: -122.431,
 };
 
-export default function StandaloneGeocoder() {
-  return <Geocoder proximity={SAN_FRANCISCO} />;
+export default function StandaloneLocationSearch() {
+  return <LocationSearch proximity={SAN_FRANCISCO} />;
 }
diff --git a/packages/e2e/cypress/integration/ui/components/geo/map-with-location-search/map-with-location-search.steps.ts b/packages/e2e/cypress/integration/ui/components/geo/map-with-location-search/map-with-location-search.steps.ts
diff --git a/packages/e2e/cypress/integration/ui/components/geo/standalone-location-search/standalone-location-search.steps.ts b/packages/e2e/cypress/integration/ui/components/geo/standalone-location-search/standalone-location-search.steps.ts
diff --git a/packages/e2e/features/ui/components/geo/map-with-location-search.feature b/packages/e2e/features/ui/components/geo/map-with-location-search.feature
@@ -1,9 +1,9 @@
-Feature: Map with Geocoder
+Feature: Map with LocationSearch
 
-  Testing map with geocoder.
+  Testing map with LocationSearch.
 
   Background:
-    Given I'm running the example "ui/components/geo/map-with-geocoder"
+    Given I'm running the example "ui/components/geo/map-with-location-search"
     And my default search results is 5
 
   @react
diff --git a/packages/e2e/features/ui/components/geo/standalone-location-search.feature b/packages/e2e/features/ui/components/geo/standalone-location-search.feature
@@ -1,9 +1,9 @@
-Feature: Standalone Geocoder
+Feature: Standalone LocationSearch
 
-  Testing geocoder without an attached map.
+  Testing LocationSearch without an attached map.
 
   Background:
-    Given I'm running the example "ui/components/geo/standalone-geocoder"
+    Given I'm running the example "ui/components/geo/standalone-location-search"
     And my default search results is 5
 
   @react
diff --git a/packages/react/__tests__/exports.ts b/packages/react/__tests__/exports.ts
@@ -1371,6 +1371,7 @@ describe('@aws-amplify/ui-react', () => {
           "Image",
           "Link",
           "Loader",
+          "LocationSearch",
           "MapView",
           "Menu",
           "MenuButton",
diff --git a/packages/react/package.json b/packages/react/package.json
@@ -132,7 +132,7 @@
     {
       "name": "Geo",
       "path": "dist/esm/index.js",
-      "import": "{ MapView, Geocoder }",
+      "import": "{ MapView, LocationSearch }",
       "limit": "300 kB"
     }
   ]
diff --git a/packages/react/src/components/Geo/LocationSearch/index.tsx b/packages/react/src/components/Geo/LocationSearch/index.tsx
@@ -4,104 +4,109 @@ import { useEffect, useRef } from 'react';
 import { useControl, useMap } from 'react-map-gl';
 import type { IControl } from 'react-map-gl';
 
-const GEOCODER_OPTIONS = {
+const LOCATION_SEARCH_OPTIONS = {
   maplibregl,
   marker: { color: '#3FB1CE' },
   popup: true,
   showResultMarkers: { color: '#3FB1CE' },
   showResultsWhileTyping: true,
 };
 
-const GEOCODER_CONTAINER = 'geocoder-container';
+const LOCATION_SEARCH_CONTAINER = 'geocoder-container';
 
-type AmplifyGeocoder = IControl & {
+type AmplifyLocationSearch = IControl & {
   addTo: (container: string) => void;
 };
 
 /**
- * The `<Geocoder>` component provides location search. See https://ui.docs.amplify.aws/components/geo#geocoder.
+ * The `<LocationSearch>` component provides location search. See https://ui.docs.amplify.aws/components/geo#geocoder.
  *
  * @example
  * // Used as a map control:
  * function App() {
  *   return (
  *     <MapView>
- *       <Geocoder />
+ *       <LocationSearch />
  *     </MapView>
  *   );
  * }
  *
  * @example
  * // Used as a standalone component:
  * function App() {
- *   return <Geocoder />;
+ *   return <LocationSearch />;
  * }
  */
-export const Geocoder = (props: GeocoderProps) => {
+export const LocationSearch = (props: LocationSearchProps) => {
   const { current: map } = useMap();
 
   /**
-   * This logic determines whether the Geocoder exists as part of a Map component or if it is a standalone component.
-   * The `useControl` hook inside `GeocoderControl` from `react-map-gl` makes it easy to add a control to a map,
-   * but throws an error if that map doesn't exist. If the map doesn't exist, the Geocoder is mounted to a container
-   * upon rendering inside the `GeocoderStandalone`.
+   * This logic determines whether the LocationSearch exists as part of a Map component or if it is a standalone component.
+   * The `useControl` hook inside `LocationSearchControl` from `react-map-gl` makes it easy to add a control to a map,
+   * but throws an error if that map doesn't exist. If the map doesn't exist, the LocationSearch is mounted to a container
+   * upon rendering inside the `LocationSearchStandalone`.
    */
   if (map) {
-    return <GeocoderControl {...GEOCODER_OPTIONS} {...props} />;
+    return <LocationSearchControl {...LOCATION_SEARCH_OPTIONS} {...props} />;
   }
 
-  return <GeocoderStandalone {...GEOCODER_OPTIONS} {...props} />;
+  return <LocationSearchStandalone {...LOCATION_SEARCH_OPTIONS} {...props} />;
 };
 
-const GeocoderControl = ({
+const LocationSearchControl = ({
   position = 'top-right',
   ...props
-}: GeocoderProps) => {
-  useControl(() => createAmplifyGeocoder(props) as unknown as AmplifyGeocoder, {
-    position,
-  });
+}: LocationSearchProps) => {
+  useControl(
+    () => createAmplifyGeocoder(props) as unknown as AmplifyLocationSearch,
+    {
+      position,
+    }
+  );
 
   return null;
 };
 
-const GeocoderStandalone = (props: GeocoderProps) => {
+const LocationSearchStandalone = (props: LocationSearchProps) => {
   const hasMounted = useRef(false);
 
   useEffect(() => {
     if (!hasMounted.current) {
-      (createAmplifyGeocoder(props) as unknown as AmplifyGeocoder).addTo(
-        `#${GEOCODER_CONTAINER}`
+      (createAmplifyGeocoder(props) as unknown as AmplifyLocationSearch).addTo(
+        `#${LOCATION_SEARCH_CONTAINER}`
       );
 
       hasMounted.current = true;
     }
   }, [props]);
 
-  return <div id={GEOCODER_CONTAINER} />;
+  return <div id={LOCATION_SEARCH_CONTAINER} />;
 };
 
-// `GeocoderProps` is based upon the typing specified by maplibre-gl-geocoder:
+export const Geocoder = LocationSearch;
+
+// `LocationSearchProps` is based upon the typing specified by maplibre-gl-geocoder:
 // https://github.com/maplibre/maplibre-gl-geocoder/blob/main/lib/index.js#L11-L66
 // TODO: formalize this type in the `maplibre-gl-geocoder` library
-export type GeocoderProps = {
+export type LocationSearchProps = {
   /**
    * A bounding box given as an array in the format `[minX, minY, maxX, maxY]`.
    * Search results will be limited to the bounding box.
    */
   bbox?: number[];
   /**
    * Default: false
-   * If `true`, the geocoder control will clear it's contents and blur when user presses the escape key.
+   * If `true`, the LocationSearch control will clear it's contents and blur when user presses the escape key.
    */
   clearAndBlurOnEsc?: boolean;
   /**
    * Default: false
-   * If `true`, the geocoder control will clear its value when the input blurs.
+   * If `true`, the LocationSearch control will clear its value when the input blurs.
    */
   clearOnBlur?: boolean;
   /**
    * Default: false
-   * If `true`, the geocoder control will collapse until hovered or in focus.
+   * If `true`, the LocationSearch control will collapse until hovered or in focus.
    */
   collapsed?: boolean;
   /**
@@ -110,7 +115,7 @@ export type GeocoderProps = {
   countries?: string;
   /**
    * Default: 200
-   * Sets the amount of time, in milliseconds, to wait before querying the server when a user types into the Geocoder
+   * Sets the amount of time, in milliseconds, to wait before querying the server when a user types into the LocationSearch
    * input box. This parameter may be useful for reducing the total number of API calls made for a single query.
    */
   debounceSearch?: number;
@@ -120,7 +125,7 @@ export type GeocoderProps = {
    */
   enableEventLogging?: boolean;
   /**
-   *  A function accepting the query string, current features list, and geocoder options which performs geocoding to
+   *  A function accepting the query string, current features list, and LocationSearch options which performs geocoding to
    * supplement results from the Maplibre Geocoding API. Expected to return a Promise which resolves to an Array of
    * GeoJSON Features in the [Carmen GeoJSON](https://github.com/mapbox/carmen/blob/master/carmen-geojson.md) format.
    */
@@ -195,7 +200,7 @@ export type GeocoderProps = {
   popupRender?: Function;
   /**
    * Default: 'top-right'
-   * Position the geocoder will be rendered on the map. Only relevant when `<Geocoder>` is used with a map.
+   * Position the LocationSearch will be rendered on the map. Only relevant when `<LocationSearch>` is used with a map.
    */
   position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
   /**
@@ -229,13 +234,13 @@ export type GeocoderProps = {
   showResultMarkers?: boolean | object;
   /**
    * Default: true
-   * If `false`, indicates that search will only occur on enter key press. If `true`, indicates that the Geocoder will
+   * If `false`, indicates that search will only occur on enter key press. If `true`, indicates that the LocationSearch will
    * search on the input box being updated above the minLength option.
    */
   showResultsWhileTyping?: boolean;
   /**
    * Default: true
-   * If `true`, the geocoder proximity will automatically update based on the map view.
+   * If `true`, the LocationSearch proximity will automatically update based on the map view.
    */
   trackProximity?: boolean;
   /**
diff --git a/packages/react/src/components/Geo/index.ts b/packages/react/src/components/Geo/index.ts
@@ -1,2 +1,2 @@
 export { MapView } from './MapView';
-export { Geocoder } from './Geocoder';
+export { Geocoder, LocationSearch } from './LocationSearch';

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@aws-amplify/ui-react": patch
 +---
++
 +feat(geo): Rename 'Geocoder' to 'LocationSearch'
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`		-```js{1,4,13} file=../../../../../../../examples/next/pages/ui/components/geo/map-with-geocoder/index.page.tsx
	`1`	+```js{1,4,13} file=../../../../../../../examples/next/pages/ui/components/geo/map-with-location-search/index.page.tsx
`2`	`2`
`3`	`3`	```
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`		-```js{1,4,16} file=../../../../../../../examples/next/pages/ui/components/geo/standalone-geocoder/index.page.tsx
	`1`	+```js{1,4,16} file=../../../../../../../examples/next/pages/ui/components/geo/standalone-location-search/index.page.tsx
`2`	`2`
`3`	`3`	```