# MapLayers / useMapLayers

A hook for managing Google Maps native overlay layers (traffic, transit, bicycling) on a map instance. Used internally by the `Map` component via its `layers` prop.

---

## Import

```tsx
import { useMapLayers } from 'xertica-ui/ui';
// or
import { useMapLayers, MapLayersConfig } from 'xertica-ui';
```

---

## `useMapLayers`

A React hook that attaches and detaches Google Maps overlay layers reactively based on a configuration object.

### Signature

```tsx
function useMapLayers(map: google.maps.Map | null, layers: MapLayersConfig): void;
```

### Parameters

| Parameter | Type                      | Description                                                                                  |
| --------- | ------------------------- | -------------------------------------------------------------------------------------------- |
| `map`     | `google.maps.Map \| null` | The Google Maps instance to attach layers to. Pass `null` to skip (layers are not rendered). |
| `layers`  | `MapLayersConfig`         | Configuration object specifying which layers to display                                      |

### `MapLayersConfig`

```tsx
interface MapLayersConfig {
  traffic?: boolean; // Real-time traffic overlay
  transit?: boolean; // Public transit routes overlay
  bicycling?: boolean; // Bicycle route overlay
}
```

---

## Available Layers

| Layer     | Key         | Description                                                 |
| --------- | ----------- | ----------------------------------------------------------- |
| Traffic   | `traffic`   | Real-time traffic conditions with color-coded road segments |
| Transit   | `transit`   | Public transit routes (bus, metro, train)                   |
| Bicycling | `bicycling` | Dedicated bicycle lanes and paths                           |

---

## Usage

### Standalone Hook

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

function MapWithLayers() {
  const [mapInstance, setMapInstance] = useState<google.maps.Map | null>(null);
  const [showTraffic, setShowTraffic] = useState(false);
  const [showTransit, setShowTransit] = useState(false);

  useMapLayers(mapInstance, {
    traffic: showTraffic,
    transit: showTransit,
  });

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={showTraffic}
          onChange={e => setShowTraffic(e.target.checked)}
        />
        Traffic
      </label>
      {/* map container */}
    </div>
  );
}
```

### Via `Map` Component (Recommended)

The `Map` component accepts a `layers` prop that internally uses `useMapLayers`:

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

<Map
  center={{ lat: -23.5505, lng: -46.6333 }}
  zoom={12}
  layers={{
    traffic: true,
    transit: false,
    bicycling: false,
  }}
/>;
```

---

## Behavior

- **Reactive**: Layers are added or removed automatically when the `layers` config changes.
- **Cleanup**: Each layer is removed from the map on component unmount (via `useEffect` cleanup).
- **Null-safe**: If `map` is `null`, the hook does nothing. This is safe to use before the map instance is ready.
- **Singleton layers**: Each layer type is created once and reused (stored in refs). Toggling a layer on/off does not create new instances.

---

## Prerequisites

The Google Maps JavaScript API must be loaded before using this hook. Use `GoogleMapsLoader` or `XerticaProvider` with a `googleMapsApiKey`:

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

<XerticaProvider googleMapsApiKey="YOUR_API_KEY">
  <App />
</XerticaProvider>;
```

---

## AI Rules

> [!IMPORTANT]
>
> - **Use via `Map` component when possible**: The `Map` component's `layers` prop is the recommended way to enable overlays. Use `useMapLayers` directly only when building a custom map integration.
> - **Requires Google Maps API**: This hook uses `google.maps.TrafficLayer`, `google.maps.TransitLayer`, and `google.maps.BicyclingLayer`. These are only available after the Maps JavaScript API is loaded.
> - **Pass `null` safely**: If the map instance is not yet available, pass `null` as the first argument. The hook will skip all operations until a valid map is provided.