# Map

## Overview

`Map` renders an interactive Google Map with advanced markers, optional rich info windows, circles, polygons, and native overlay layers. It uses the built-in Xertica Google Maps loader and renders a safe configuration state when no API key is available.

---

## Import

```tsx
import {
  Map,
  GoogleMapsLoaderProvider,
  useGoogleMapsLoader,
  useMapLayers,
  GOOGLE_MAPS_ID,
  GOOGLE_MAPS_LIBRARIES,
  type MapLayersConfig,
} from 'xertica-ui/ui';
```

---

## Prerequisites

- Import `xertica-ui/style.css` once at the app root.
- Provide a Google Maps JavaScript API key through `apiKey`, `VITE_GOOGLE_MAPS_API_KEY`, storage, or `<XerticaProvider googleMapsApiKey="...">`.
- If no key is configured, the component renders a non-crashing setup prompt.

---

## Props

| Prop        | Type                             | Default   | Description                                               |
| ----------- | -------------------------------- | --------- | --------------------------------------------------------- |
| `center`    | `{ lat: number; lng: number }`   | Sao Paulo | Initial map center coordinates.                           |
| `zoom`      | `number`                         | `12`      | Initial zoom level.                                       |
| `markers`   | `MapMarker[]`                    | `[]`      | Markers to display.                                       |
| `circle`    | `object`                         | -         | Optional circle overlay.                                  |
| `polygon`   | `object`                         | -         | Optional polygon overlay.                                 |
| `layers`    | `MapLayersConfig`                | `{}`      | Native layer toggles for traffic, transit, and bicycling. |
| `height`    | `string`                         | `"400px"` | Container height.                                         |
| `apiKey`    | `string`                         | -         | Per-component Google Maps API key override.               |
| `onMapLoad` | `(map: google.maps.Map) => void` | -         | Receives the underlying map instance.                     |

---

## Public Utilities

`useMapLayers(map, layers)` is public for advanced integrations that already own a `google.maps.Map` instance.

`GOOGLE_MAPS_ID` and `GOOGLE_MAPS_LIBRARIES` are public constants for integrations that need to inspect or align with the built-in loader.

---

## Example

```tsx
import { Map } from 'xertica-ui/ui';

<Map
  center={{ lat: -23.5505, lng: -46.6333 }}
  zoom={12}
  height="420px"
  markers={[
    {
      position: { lat: -23.5505, lng: -46.6333 },
      title: 'Xertica',
      info: 'Main office',
    },
  ]}
  layers={{ traffic: true }}
/>;
```

---

## AI Rules

- Always set visible height through `height` or layout constraints.
- Do not install another Google Maps script loader; use `GoogleMapsLoaderProvider` or `XerticaProvider`.
- Use `{ lat, lng }` coordinates, never `{ latitude, longitude }`.
- For standalone usage, pass `apiKey` directly or rely on `VITE_GOOGLE_MAPS_API_KEY`.