# MapScaleBar

## Overview

`MapScaleBar` renders a graphic scale bar, recalculated on every zoom change. Reports and dossiers circulate off screen, and a static map with no scale cannot support a claim about distance.

---

## Import

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

---

## Prerequisites

- Prefer `<Map scaleBar />` — the map computes `metersPerPixel` from its own zoom and latitude.
- Mount `MapScaleBar` directly only when driving it from a map instance you own.

---

## Props

| Prop             | Type                     | Default          | Description                       |
| ---------------- | ------------------------ | ---------------- | --------------------------------- |
| `metersPerPixel` | `number`                 | required         | Ground distance one pixel covers. |
| `units`          | `'metric' \| 'imperial'` | `'metric'`       | Unit system.                      |
| `maxWidthPx`     | `number`                 | `120`            | Longest the bar may be drawn.     |
| `position`       | `MapOverlayPosition`     | `'bottom-right'` | Anchor for `layout="overlay"`.    |
| `layout`         | `'overlay' \| 'inline'`  | `'overlay'`      | `inline` flows in normal layout.  |

On `<Map>`: `scaleBar={true}` or `scaleBar={{ units, position }}`.

---

## Public Utilities

`niceScaleDistance(metersPerPixel, maxWidthPx, units)` returns the chosen round distance, its pixel width and its label — useful when composing a scale into an exported image.

---

## Example

```tsx
<Map height="520px" markers={markers} scaleBar={{ units: 'metric', position: 'bottom-right' }} />
```

---

## AI Rules

- **Always** include a scale bar on any map that will be printed, exported, or attached to a report.
- **Always** prefer `<Map scaleBar>` over mounting the component by hand.
- **Never** label the bar with a raw computed distance. It deliberately snaps to 1, 2 or 5 times a power of ten so the reader can halve or triple it by eye.
- Common mistake: assuming the scale is constant across the map. It is computed at the current centre latitude; Mercator stretches with distance from the equator.