# RouteMap

## Overview

A specialized Google Maps component that calculates and renders a route between an origin and destination point, with support for intermediate waypoints and multiple travel modes. The route is drawn on the map using the Google Directions Service, and optionally returns the calculated distance and duration.

Use `<Map>` for general-purpose map rendering. Use `<RouteMap>` specifically when you need to display a navigable route.

---

## When to Use

- Displaying the route between two locations (delivery tracking, field service, logistics)
- Showing estimated travel time and distance
- Multi-stop itinerary visualization

## When NOT to Use

- General-purpose map without route — use `<Map>` instead.
- Static location marker display — use `<Map markers={...}>` instead.

---

## Prerequisites

- A Google Maps JavaScript API key with the **Directions API** enabled.
- The key must be provided to `<XerticaProvider googleMapsApiKey="YOUR_KEY">`, OR passed directly as the `apiKey` prop.

---

## Props

| Prop                | Type                                                 | Default     | Required | Description                                                         |
| ------------------- | ---------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------- |
| `origin`            | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route start point                                                   |
| `destination`       | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route end point                                                     |
| `waypoints`         | `{ lat: number; lng: number }[]`                     | `[]`        | No       | Intermediate stops                                                  |
| `travelMode`        | `'DRIVING' \| 'WALKING' \| 'BICYCLING' \| 'TRANSIT'` | `'DRIVING'` | No       | Mode of transport                                                   |
| `height`            | `string`                                             | `'450px'`   | No       | CSS height of the map container                                     |
| `mapId`             | `string`                                             | —           | No       | Google Maps Map ID for custom styling                               |
| `apiKey`            | `string`                                             | —           | No       | Overrides provider API key                                          |
| `onRouteCalculated` | `(distance: string, duration: string) => void`       | —           | No       | Called with formatted distance and duration after route is computed |
| `disableDefaultUI`  | `boolean`                                            | `false`     | No       | Hides all default map UI controls                                   |
| `zoomControl`       | `boolean`                                            | `true`      | No       | Shows/hides zoom control                                            |
| `streetViewControl` | `boolean`                                            | `false`     | No       | Shows/hides Street View control                                     |
| `mapTypeControl`    | `boolean`                                            | `false`     | No       | Shows/hides map type switcher                                       |
| `fullscreenControl` | `boolean`                                            | `true`      | No       | Shows/hides fullscreen button                                       |
| `className`         | `string`                                             | —           | No       | Additional CSS classes for the wrapper div                          |

---

## Examples

### Basic Route

```tsx
import { RouteMap } from 'xertica-ui';

<RouteMap
  origin={{ lat: -12.971, lng: -38.501 }}
  destination={{ lat: -13.025, lng: -38.478 }}
  height="400px"
/>;
```

### With Waypoints and Distance Callback

```tsx
const [routeInfo, setRouteInfo] = useState<{ distance: string; duration: string }>();

<RouteMap
  origin={{ lat: -12.971, lng: -38.501 }}
  destination={{ lat: -13.025, lng: -38.478 }}
  waypoints={[{ lat: -12.99, lng: -38.49 }]}
  travelMode="DRIVING"
  height="500px"
  onRouteCalculated={(distance, duration) => setRouteInfo({ distance, duration })}
/>;

{
  routeInfo && (
    <p className="text-sm text-muted-foreground mt-2">
      {routeInfo.distance} · {routeInfo.duration}
    </p>
  );
}
```

### Walking Mode

```tsx
<RouteMap
  origin={{ lat: -12.971, lng: -38.501 }}
  destination={{ lat: -12.98, lng: -38.51 }}
  travelMode="WALKING"
  height="300px"
/>
```

---

## Return Values from `onRouteCalculated`

| Parameter  | Format                   | Example                    |
| ---------- | ------------------------ | -------------------------- |
| `distance` | `"X.X km"`               | `"12.4 km"`                |
| `duration` | `"Xh Ymin"` or `"Y min"` | `"1h 23min"` or `"45 min"` |

---

## AI Rules

- **Always** set an explicit `height` — without it the map renders with 0 height.
- `origin` and `destination` use `{ lat, lng }` format — **not** `{ latitude, longitude }`.
- The API key requires the **Directions API** enabled, in addition to the Maps JavaScript API. Plain Maps API keys will fail route calculation.
- `onRouteCalculated` receives pre-formatted strings (`"12.4 km"`, `"23 min"`) — not raw numeric values.
- If `waypoints` is empty, simply omit the prop — do not pass an empty array explicitly.

---

## Related Components

- [`Map`](./map.md) — General-purpose map without route
- [Maps Pattern](../patterns/analytics.md) — Location-based analytics usage