import {
  Meta,
  Title,
  Subtitle,
  Description,
  Primary,
  Controls,
  Stories,
} from '@storybook/addon-docs/blocks';
import * as MapLocateControlStories from './map-locate-control.stories';

<Meta of={MapLocateControlStories} />

<Title />
<Subtitle>Centres the map on the device's position, with every failure mode named.</Subtitle>

<Description />

<Primary />

<Controls />

---

## Variations

<Stories />

---

## AI Best Practices

> [!IMPORTANT]
>
> - **Feed the reading into `<Map deviceLocation>`** so the accuracy halo is drawn. A coordinate shown without its accuracy overstates precision.
> - **Handle `onError`.** A denied permission, a timeout and an absent provider are three different situations for the user, and only one of them is worth a retry.
> - **Never treat `mocked === false` as proof** the coordinate is genuine — only some platforms report the flag at all. Deployments that must reject simulated coordinates need server-side corroboration too.
> - When `mocked` is true, `<Map>` renders the marker in a destructive state. That is deliberate: a simulated coordinate has to be visible in the interface, not merely caught by a silent validation.