react-bing-map 1.0.7 → 1.0.8

package/README.md

@@ -1,176 +1,339 @@
-## React - Bing Map
+# React Bing Map
 
-## Prerequisites
+A React + TypeScript wrapper for Bing Maps with pushpins, infoboxes, route navigation, device GPS support, route distance, route duration, and a ready-to-use route selection panel.
 
-To fully utilize this component, you need a Bing Maps API key, which can be obtained from the [Bing Maps Dev Center](https://www.bingmapsportal.com).
+## Features
 
-## Installation
+- Render Bing Maps in React applications.
+- Add multiple pushpins with custom icons and infobox content.
+- Draw routes between a `source` and `destination`.
+- Use the browser/device current location as the route source.
+- Receive route distance and duration with `onRouteCalculated`.
+- Use `RouteSelectionWithGPS` for a built-in route form and map layout.
+- Position the route drawer on the `left`, `right`, `top`, or `bottom`.
+- Supports React `16`, `17`, `18`, and `19`.
 
-```
-yarn add react-bing-map
+## Prerequisites
 
-OR
+You need a Bing Maps API key from the [Bing Maps Dev Center](https://www.bingmapsportal.com).
 
-npm i react-bing-map
-```
+GPS/current-location features require a secure browser context:
 
-## Usage
+- `localhost` during development
+- `https://` in production
 
-#### Import the BingMapsReact component.
+The browser user must also allow location permission.
 
-Import the Bing Maps component
+## Installation
 
-```js
-import { BingMaps } from "react-bing-map";
+```sh
+npm install react-bing-map
 ```
 
-#### Customized Example:
-
-```js
-<BingMaps
-  mapType="grayscale"
-  bingKey="key"
-  centerLocation={[28.6448, 77.216721]}
-  language="en-IN"
-  zoom={0}
-  pushPins={[]}
-  mapPosition={ north: 49.234, south: 24.175, east: -65.573, west: -125.778 }
-  infoBoxStyle={ maxWidth: 490, maxHeight: 600 }
-  pushPinIcon=""
-  showScalebar={true}
-  showCopyright={true}
-  showLogo={true}
-  disableZooming={false}
-  showBreadcrumb={true}
-  showLocateMeButton={true}
-  showZoomButtons={true}
-  showMapTypeSelector={true}
-
-/>
+```sh
+yarn add react-bing-map
 ```
 
-##### Props Details
-
-#### 1. mapType
+## Basic Usage
 
-Following options are available to use based on requirements
+```tsx
+import { BingMaps } from "react-bing-map";
 
-```js
-[
-  "aerial",
-  "canvasDark",
-  "canvasLight",
-  "birdseye",
-  "grayscale",
-  "mercator",
-  "ordnanceSurvey",
-  "road",
-  "streetside",
-];
+export const App = () => {
+  return (
+    <div style={{ width: "100%", height: "500px", position: "relative" }}>
+      <BingMaps
+        bingKey="YOUR_BING_MAPS_KEY"
+        mapType="grayscale"
+        centerLocation={[28.6448, 77.216721]}
+        zoom={6}
+      />
+    </div>
+  );
+}
 ```
 
-#### 2. bingKey
+The parent container should have a height and `position: "relative"` because the map fills its parent.
 
-Get the keys from the Bing Maps Dev Portal and use them.
+## Pushpins and Infoboxes
 
-#### 3. centerLocation
+```tsx
+import { BingMaps } from "react-bing-map";
 
-It is used to set the map position at the center of the browser screen like the output image.
+const pushPins = [
+  {
+    icon: "",
+    location: {
+      latitude: 28.6448,
+      longitude: 77.216721,
+    },
+    content: {
+      title: "Delhi",
+      description: "Simple text or HTML content",
+    },
+  },
+];
 
-```js
-centerLocation={[28.6448, 77.216721]}
+export const MapWithPins = () => {
+  return (
+    <div style={{ width: "100%", height: "500px", position: "relative" }}>
+      <BingMaps
+        bingKey="YOUR_BING_MAPS_KEY"
+        mapType="road"
+        centerLocation={[28.6448, 77.216721]}
+        zoom={8}
+        pushPins={pushPins}
+        pushPinIcon=""
+        infoBoxStyle={{ maxWidth: 490, maxHeight: 600 }}
+      />
+    </div>
+  );
+}
 ```
 
-#### 4. language
+## Route Navigation
 
-It is used to define the map language based on specific needs.
+Use `source`, `destination`, and `showRoute` to draw a route between two coordinates.
 
-```js
-language = "en-IN";
-```
+```tsx
+import { BingMaps } from "react-bing-map";
 
-#### 5. zoom
+const source = { latitude: 13.0827, longitude: 80.2707 }; // Chennai
+const destination = { latitude: 12.9716, longitude: 77.5946 }; // Bangalore
+
+export function RouteMap() {
+  return (
+    <div style={{ width: "100%", height: "500px", position: "relative" }}>
+      <BingMaps
+        bingKey="YOUR_BING_MAPS_KEY"
+        mapType="road"
+        source={source}
+        destination={destination}
+        showRoute={true}
+        routeMode="driving"
+        zoom={6}
+        onRouteCalculated={(routeInfo) => {
+          console.log("Distance:", routeInfo.distance, routeInfo.distanceUnit);
+          console.log("Duration in seconds:", routeInfo.duration);
+        }}
+      />
+    </div>
+  );
+}
+```
 
-We can customize the zoom level of the map and support min 1 and max 19
+Route modes:
 
-```js
-  zoom={0}
+```ts
+type TRouteMode = "driving" | "walking" | "transit";
 ```
 
-#### 6. pushPins
+## Use Current Location as Source
 
-It is a list of array objects, and the structure should be as follows
+Set `useGPS={true}` with a `destination`. The component gets the browser/device location and uses it as the route source.
 
-```json
-{
-  "icon": "",
-  "location": {
-    "latitude": 13.067439,
-    "longitude": 80.237617
-  },
-  "content": {
-    "title": "Chennai",
-    "description": `html or simple text`
-  }
+```tsx
+import { BingMaps } from "react-bing-map";
+
+const destination = { latitude: 12.9716, longitude: 77.5946 }; // Bangalore
+
+export function CurrentLocationRoute() {
+  return (
+    <div style={{ width: "100%", height: "500px", position: "relative" }}>
+      <BingMaps
+        bingKey="YOUR_BING_MAPS_KEY"
+        mapType="road"
+        destination={destination}
+        showRoute={true}
+        useGPS={true}
+        routeMode="driving"
+        onGPSLocationFound={(location) => {
+          console.log("Device location:", location);
+        }}
+        onGPSError={(error) => {
+          console.error(error);
+        }}
+        onRouteCalculated={(routeInfo) => {
+          console.log(`${routeInfo.distance.toFixed(2)} km`);
+        }}
+      />
+    </div>
+  );
 }
 ```
 
-##### 1. icon
-
-This icon used to show the category based pushpin we can use it or else set empty sting and use the `pushPinIon`key for global icon.
-
-The content of the description should be like the inner HTML content below
+If GPS is unavailable or permission is denied, `onGPSError` is called. If `source` is also provided, the component can fall back to routing from `source` to `destination`.
 
-##### 2. content
+## Route Selection Component
 
-The content structure looks like the one below
+`RouteSelectionWithGPS` is a ready-made map + route form component. It includes source selection, destination selection, a `Current Location` source option, GPS checkbox, route mode selector, route summary, distance, duration, and drawer positioning.
 
-```json
+```tsx
+import { RouteSelectionWithGPS } from "react-bing-map";
 
- "content": {
-    "title": "Chennai",
-    "description": `
-      <div class="pin-detail">
-        <section>
-          <div class="name">Partner:</div>
-          <div class="value">
-            1067207 <span id="copy_42" class="copy-section"></span>
-          </div>
-        </section>
-      </div>
-    `
-  }
+export function RoutePlanner() {
+  return (
+    <RouteSelectionWithGPS
+      bingKey="YOUR_BING_MAPS_KEY"
+      drawerPosition="right"
+      mapType="grayscale"
+      zoom={5}
+    />
+  );
+}
+```
 
+### Custom Locations
+
+```tsx
+import { RouteSelectionWithGPS } from "react-bing-map";
+
+const locations = {
+  chennai: { latitude: 13.0827, longitude: 80.2707 },
+  bangalore: { latitude: 12.9716, longitude: 77.5946 },
+  hyderabad: { latitude: 17.385, longitude: 78.4867 },
+};
+
+export function CustomRoutePlanner() {
+  return (
+    <RouteSelectionWithGPS
+      bingKey="YOUR_BING_MAPS_KEY"
+      locations={locations}
+      initialSourceKey="chennai"
+      initialDestinationKey="bangalore"
+      drawerPosition="bottom"
+      mapType="road"
+    />
+  );
+}
 ```
 
-or else use this simple description
+### Drawer Positions
 
-```js
- "content": {
-    "title": "Chennai",
-    "description": "Description"
-  }
+```tsx
+<RouteSelectionWithGPS drawerPosition="left" />
+<RouteSelectionWithGPS drawerPosition="right" />
+<RouteSelectionWithGPS drawerPosition="top" />
+<RouteSelectionWithGPS drawerPosition="bottom" />
 ```
 
-#### 7. pushPinIcon
+## `BingMaps` Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bingKey` | `string` | `""` | Bing Maps API key. Required for map and route features. |
+| `mapType` | `string` | `"grayscale"` | Bing Maps map type. |
+| `centerLocation` | `[number, number]` | `[0, 0]` | Initial map center as `[latitude, longitude]`. |
+| `language` | `string` | `"en-IN"` | Bing Maps script language. |
+| `zoom` | `number` | `0` | Initial map zoom level. |
+| `pushPins` | `TPushPin[]` | `[]` | List of pushpins to render. |
+| `pushPinIcon` | `string` | `""` | Global pushpin icon used when an item has no icon. |
+| `mapPosition` | `TMapPosition` | US bounds | Initial map bounds. |
+| `infoBoxStyle` | `TInfoBoxStyle` | `{ maxWidth: 600, maxHeight: 450 }` | Infobox sizing options. |
+| `showScalebar` | `boolean` | `true` | Show or hide scale bar. |
+| `showCopyright` | `boolean` | `true` | Show or hide copyright text. |
+| `showLogo` | `boolean` | `true` | Show or hide Bing logo. |
+| `disableZooming` | `boolean` | `false` | Disable user zoom interaction. |
+| `showBreadcrumb` | `boolean` | `true` | Show or hide breadcrumb control. |
+| `showLocateMeButton` | `boolean` | `true` | Show or hide locate me button. |
+| `showZoomButtons` | `boolean` | `true` | Show or hide zoom buttons. |
+| `showMapTypeSelector` | `boolean` | `true` | Show or hide map type selector. |
+| `source` | `TLocation` | `undefined` | Route source coordinate. |
+| `destination` | `TLocation` | `undefined` | Route destination coordinate. |
+| `showRoute` | `boolean` | `false` | Draw route when `source`/GPS and `destination` are available. |
+| `routeMode` | `"driving" \| "walking" \| "transit"` | `"driving"` | Route travel mode. |
+| `useGPS` | `boolean` | `false` | Use browser/device current location as route source. |
+| `onGPSLocationFound` | `(location: TLocation) => void` | `undefined` | Called when GPS location is found. |
+| `onGPSError` | `(error: string) => void` | `undefined` | Called when GPS or route calculation fails. |
+| `onRouteCalculated` | `(routeInfo: TRouteInfo) => void` | `undefined` | Called with route distance and duration. |
+
+## `RouteSelectionWithGPS` Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bingKey` | `string` | `""` | Bing Maps API key. |
+| `drawerPosition` | `"left" \| "right" \| "top" \| "bottom"` | `"right"` | Position of the route configuration panel. |
+| `locations` | `Record<string, TLocation>` | Built-in India city list | Source/destination options shown in the form. |
+| `initialSourceKey` | `string` | `"delhi"` | Initial source key from `locations`. |
+| `initialDestinationKey` | `string` | `"mumbai"` | Initial destination key from `locations`. |
+| `mapType` | `string` | `"grayscale"` | Map type passed to `BingMaps`. |
+| `language` | `string` | `"en-IN"` | Map language passed to `BingMaps`. |
+| `zoom` | `number` | `5` | Initial map zoom. |
+| `disableZooming` | `boolean` | `false` | Disable map zooming. |
+| `showScalebar` | `boolean` | `true` | Show scale bar. |
+| `showCopyright` | `boolean` | `true` | Show copyright text. |
+| `showLogo` | `boolean` | `true` | Show Bing logo. |
+| `showBreadcrumb` | `boolean` | `true` | Show breadcrumb control. |
+| `showLocateMeButton` | `boolean` | `true` | Show locate me button. |
+| `showZoomButtons` | `boolean` | `true` | Show zoom buttons. |
+| `showMapTypeSelector` | `boolean` | `true` | Show map type selector. |
+
+## Types
+
+```ts
+type TLocation = {
+  latitude: number;
+  longitude: number;
+};
+
+type TMapPosition = {
+  north: number;
+  south: number;
+  east: number;
+  west: number;
+};
+
+type TPushPin = {
+  icon: string | any;
+  location: TLocation;
+  content: {
+    title: string;
+    description: HTMLElement | string;
+  };
+};
+
+type TRouteInfo = {
+  source: TLocation;
+  destination: TLocation;
+  distance: number;
+  distanceUnit: "kilometers";
+  duration?: number;
+  isFallback?: boolean;
+};
+```
 
-It is used for global pushpin icon
+## Map Type Options
 
-```js
-pushPinIcon = "url";
+```ts
+[
+  "aerial",
+  "canvasDark",
+  "canvasLight",
+  "birdseye",
+  "grayscale",
+  "mercator",
+  "ordnanceSurvey",
+  "road",
+  "streetside",
+]
 ```
 
-#### 8. mapPosition
+## Development
 
-#### 9. infoBoxStyle
+```sh
+npm install
+npm run storybook
+npm run build
+```
 
-It is used to customize the infoBox maxWidth and maxHeight
+## Troubleshooting
 
-```js
-  infoBoxStyle={ maxWidth: 490, maxHeight: 600 }
-```
-![alt text](<infoBox.png>)
+- Make sure `bingKey` is valid and created for a web application.
+- Routes require reachable source and destination coordinates.
+- GPS requires `localhost` or HTTPS and browser location permission.
+- The map fills its parent; always give the parent container a height.
+- If route calculation fails, `onRouteCalculated` may return `isFallback: true` with straight-line distance.
 
-#### Output:
+## License
 
-![screenshot](/output.png)
+MIT