Merge pull request #52 from ubilabs/feat/update-properties-readme

refactor(readme): update and sort properties section

Author: BiniCodes

README.md

@@ -98,39 +98,198 @@ Component to wrap around the code where the map should be available.
 
 ### Properties
 
+Properties that can be passed to the `GoogleMapsProvider` that are either the container to hold the map instance or [Maps JavaScript API URL Parameters](https://developers.google.com/maps/documentation/javascript/url-params).
+
 ```TypeScript
 interface GoogleMapProviderProps {
-  children: React.ReactElement;
+  googleMapsAPIKey: string;
+  mapContainer?: HTMLElement | null;
+  options?: google.maps.MapOptions;
+  libraries?: string[];
+  language?: string;
+  region?: string;
+  version?: string;
+  authReferrerPolicy?: string;
+  onLoad?: (map: google.maps.Map) => void;
+}
+```
+- - - -
+__googleMapsAPIKey__ (_compulsary property_)
 
-  // The Google Maps API Key
+  The Google Maps JavaScript API Key.
+  ```Typescript
   googleMapsAPIKey: string;
+  ```
 
-  // A reference to the component that displays the map
-  mapContainer?: HTMLElement | null;
+See: [Use API Key](https://developers.google.com/maps/documentation/embed/get-api-key)
 
-  // The Google Maps MapOptions, see: https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions
-  options?: google.maps.MapOptions;
+- - - -
 
-  // Additional Google Maps libraries to load ('drawing', 'geometry', 'places' or 'visualization'), see: https://developers.google.com/maps/documentation/javascript/libraries
-  libraries?: string[];
+__mapContainer__ (_optional property_)
 
-  // By default Google Maps will use the preferred language from the browser setting. This is the property to set it manually, see: https://developers.google.com/maps/documentation/javascript/localization
-  language?: string;
+A reference to the HTML element that displays the map.
+Without the mapContainer provided, no visual map will be displayed.
 
-  // By default Google Maps will use the preferred region from the browser setting. This is the property to set it manually, see: https://developers.google.com/maps/documentation/javascript/localization
-  region?: string;
+```Typescript
+mapContainer?: HTMLElement | null;
+```
 
-  // Use this parameter to specify a version, see: https://developers.google.com/maps/documentation/javascript/versions
-  version?: string;
+_Example:_
 
-  // Use this parameter to set auth_referrer_policy=origin when an URL on the same origin uses the API Key, to limit the amount of data sent when authorizing requests, see "auth_referrer_policy": https://developers.google.com/maps/documentation/javascript/url-params  
-  authReferrerPolicy?: string;
+The mapContainer will be passed to the `mapProvider` and `mapCanvas component` in the following way:
 
-  // A callback function that is called, when the map is loaded.
-  onLoad?: (map: google.maps.Map) => void;
+```TypeScript
+function App() {
+  const [mapContainer, setMapContainer] = useState(null);
+  
+  const mapRef = useCallback((node) => {
+    node && setMapContainer(node);
+  }, []);
+
+  return (
+    <GoogleMapProvider
+      googleMapsAPIKey="my Google Maps API key"
+      mapContainer={mapContainer}
+    >
+      <React.StrictMode>
+        <MapCanvas ref={mapRef} />
+      </React.StrictMode>
+    </GoogleMapProvider>
+  );
 }
 ```
 
+See: [Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/overview)
+
+- - - -
+
+__options__ (_optional property_)
+
+The Google Maps MapOptions.
+
+```Typescript
+options?: google.maps.MapOptions;
+```
+
+_Example:_
+
+```Typescript
+const mapOptions = {
+  center: {lat: 53.5582447, lng: 9.647645},
+  zoom: 6,
+  disableDefaultUI: true,
+};
+```
+
+See: [MapOptions](https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions)
+
+**NOTE**: If the `mapOptions` are not provided here, the map will not be displayed until they are set.
+
+_Example:_ 
+
+MapOptions can be set later in another component in the following way:
+
+```Typescript
+import {useGoogleMap} from '@ubilabs/google-maps-react-hooks';
+
+const mapOptions = {
+  center: {lat: 53.5582447, lng: 9.647645},
+  zoom: 6,
+  disableDefaultUI: true,
+  zoomControl: true,
+  zoomControlOptions: {
+    position: 3 // Right top
+  }
+};
+
+const {map} = useGoogleMap();
+
+map?.setOptions(mapOptions);
+```
+
+- - - -
+
+__libraries__ (_optional property_)
+
+Additional Google Maps libraries to load ('drawing', 'geometry', 'places' or 'visualization').
+
+```Typescript
+libraries?: string[];
+```
+
+See: [Libraries](https://developers.google.com/maps/documentation/javascript/libraries)
+
+- - - -
+
+__languages__ (_optional property_)
+
+By default Google Maps will use the preferred region from the browser setting. This is the property to set it manually.
+
+```Typescript
+language?: string;
+```
+
+See: [Localization](https://developers.google.com/maps/documentation/javascript/localization)
+
+- - - -
+
+__region__ (_optional property_)
+
+By default Google Maps will use the preferred region from the browser setting. This is the property to set it manually.
+
+```Typescript
+region?: string;
+```
+
+See: [Localization](https://developers.google.com/maps/documentation/javascript/localization)
+
+- - - -
+
+__version__ (_optional property_)
+
+Use this parameter to specify a version.
+
+```Typescript
+version?: string;
+```
+
+See: [Versions](https://developers.google.com/maps/documentation/javascript/versions)
+
+- - - -
+
+__authReferrerPolicy__ (_optional property_)
+
+Use this parameter to set auth_referrer_policy=origin when an URL on the same origin uses the API Key, to limit the amount of data sent when authorizing requests.
+
+```Typescript
+authReferrerPolicy?: string;
+```
+
+See: [auth_referrer_policy](https://developers.google.com/maps/documentation/javascript/url-params)
+
+- - - -
+
+__onLoad__ (_optional property_)
+
+A callback function that is called, when the map is loaded.
+
+```Typescript
+onLoad?: (map: google.maps.Map) => void;
+```
+
+_Example:_
+
+```Typescript
+<GoogleMapProvider
+  googleMapsAPIKey="my Google Maps API key"
+  onLoad={(map) => map.setZoom(4)}
+>
+  ...
+</GoogleMapProvider>
+```
+
+- - - -
+
 ## Hooks
 
 ### useGoogleMap