# MapOverlay

## Overview

`MapOverlay` anchors React content over the map surface. Nine anchors on one consistent stacking layer, so a legend does not end up underneath a notice on one screen and above it on the next.

---

## Import

```tsx
import { Map, MapOverlay, MapLegend, MapNotice } from 'xertica-ui/ui';
```

---

## Prerequisites

- Import `xertica-ui/style.css` once at the app root.
- Place overlays as children of `<Map>` — that is what gives them a positioned container.

---

## Props

| Prop       | Type                 | Default       | Description                           |
| ---------- | -------------------- | ------------- | ------------------------------------- |
| `position` | `MapOverlayPosition` | `'top-right'` | One of the nine anchors.              |
| `zIndex`   | `number`             | shared layer  | Raises this overlay above the others. |
| `children` | `ReactNode`          | required      | The content to anchor.                |

`MapOverlayPosition` is `'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'`.

---

## Example

```tsx
<Map height="520px" markers={markers} attribution="© IBGE">
  <MapOverlay position="bottom-left">
    <MapLegend variant="overlay" items={bands} />
  </MapOverlay>
  <MapOverlay position="top-right">
    <MapNotice variant="synthetic">Dados demonstrativos</MapNotice>
  </MapOverlay>
</Map>
```

---

## AI Rules

- **Always** place `MapOverlay` as a child of `<Map>`.
- **Always** keep overlays small — they cover the map they annotate.
- **Never** put two overlays at the same anchor; they will stack on top of each other.
- **Never** hand-place the scale bar or the attribution — use `<Map scaleBar>` and `<Map attribution>`, which know where those belong by convention.
- Common mistake: wrapping `<Map>` in a `relative` div and positioning overlays as siblings. That still works, but children of `<Map>` are the supported path.