# Map

Links: [Home](../index.md)

An interactive map on [OpenStreetMap](https://www.openstreetmap.org/) data: pins, contours, lines,
circles and rectangles, address search, routing, measurement, track playback and GeoJSON interchange.

This is an **SGApps.IO module on open source**: the module, its API, its vertex editor and its
rate-limited provider layer are ours (Apache-2.0); the rendering is done by the vendored
[Leaflet 1.9.4](../thirdparty/gui/map-leaflet.md) (BSD-2-Clause), and the data and services come from
OpenStreetMap and whatever other providers the host configures.

Nothing Leaflet-shaped crosses the API. Coordinates go in and out as plain numbers, latitude first, so
a host never holds an `L.*` object -- except through the one deliberate escape hatch, `leafletMap()`.

## Loading the Module

```js
Application.require("gadgets/map").then(function (SGMap) {
    // SGMap is a constructor function
});
```

**Dependencies:** `thirdparty/gui/map/leaflet`, `uri-load`. The geometry half is also a module of its
own -- `gadgets/map/geo` -- with no DOM and no Leaflet, so form validation or a worker can require it
without a map.

## What reaches third parties

The map talks to services on the network. Hosts need this for their own privacy notice, so it is also
available at runtime through `dataRecipients()`:

| Service | Default | What it receives |
|---|---|---|
| Tiles | `tile.openstreetmap.org` | the viewer's IP address, the browser's `Referer`, and the tile coordinates of the area being looked at |
| Geocoding | `nominatim.openstreetmap.org` | the viewer's IP address, the browser's `Referer`, and the searched text or the reverse-geocoded coordinates |
| Routing | **none** | nothing, until the host configures a router |

The module is built to keep the [OSMF tile usage policy](https://operations.osmfoundation.org/policies/tiles/)
and the [Nominatim usage policy](https://operations.osmfoundation.org/policies/nominatim/):

- the attribution control is always visible and cannot be emptied through the API;
- nothing is prefetched, no tile is stored, and no cache-busting header is sent;
- geocoding requests are serialised **at module level** -- at least 1.1 s apart across every map on the
  page -- and cached in memory by query text;
- **there is no autocomplete**: a search leaves only on Enter or on the button;
- routing has no default server. `route()` without `providers.route.url` fails with `ERR_NO_ROUTER` and
  sends nothing. The OSRM demo server is not permitted behind a paid product; a host may set it
  explicitly for development.

For a map that touches no service at all -- a demo, a test, an offline host -- use the tile-less
coordinate grid: `providers: { tiles: 'blank' }`.

## The module's own frame

Identifying the application means sending a `Referer`, and **a document loaded from a `blob:` or `data:`
URL sends none**. That is not a corner case: this repository's own playground renders every preview inside
a `blob:` iframe, and [`gadgets/wrapper`](wrapper.md) is a `blob:` sandbox too. A map built directly in
such a document asks OpenStreetMap for tiles with an empty `Referer`, and OSM answers with a blocked
placeholder image -- *"App is not following the tile usage policy"* -- served as **HTTP 200**, so nothing
reports an error and the map simply shows "Access blocked" in every tile.

The module therefore ships its own document, `modules/gadgets/map/frame.html`, loaded through
`module.resourceUrl('../frame.html')`. It is a real URL, so requests made from it carry a real `Referer`
again. `frame.html` pulls in Leaflet and the module stylesheet itself, relative to its own location, and
the map is built inside it.

`frame` decides when that happens:

| Value | Behaviour |
|---|---|
| `'auto'` (default) | the frame is used only when `location.protocol` is `blob:`, `data:` or `about:`, or the document's origin is opaque |
| `true` | always use the frame |
| `false` | never use it, even in a document that cannot identify itself |

On an ordinary page nothing changes: the map is built directly in the host's container, the host's CSS can
style it, and there is no extra document to load.

When the frame **is** used:

- `node()` returns the `<iframe>` -- that is what was appended to the container -- while `mapNode()`
  returns the `.sg-map` root inside it, `frame()` returns the iframe and `mapDocument()` the document the
  map lives in;
- the host's stylesheet does not reach the map, which is isolation when you want it and a limitation when
  you wanted to restyle `.sg-map` from the host page;
- everything else is unchanged: the whole API, every event and the geometry helpers work exactly as they
  do in place.

The frame is same-origin, so if it cannot be loaded or Leaflet is missing inside it, the module falls back
to building in the host document and raises `event:error` with code `ERR_FRAME` -- a map whose tiles may be
refused is still better than an empty box, and the message says why.

## API

### `SGMap([config])`

Create a map. Returns an `ApplicationPrototype` instance.

```js
var map = SGMap({
    container: document.getElementById('map'),
    lat: 47.0105,
    lng: 28.8638,
    zoom: 16,
    mode: 'pick-point',
    locale: 'ro'
});

map.whenLoaded().then(function () {
    map.on('event:point-changed', function (p) {
        console.log(p.lat, p.lng);
    });
});
```

### Configuration

| Option | Default | Description |
|---|---|---|
| `container` | `null` | Element the map is appended to |
| `lat`, `lng` | `47.0105`, `28.8638` | Initial centre |
| `zoom` | `13` | Initial zoom |
| `minZoom`, `maxZoom` | `null` | Limits for the map as a whole; each tile layer also has its own |
| `mode` | `'view'` | `view`, `pick-point`, `edit-polygon`, `edit-line`, `draw-polygon`, `draw-line`, `measure` |
| `readOnly` | `false` | No editing; `mode: 'viewer'` is accepted as a synonym that also sets this |
| `embedded` | `false` | Tighter control spacing for a pinned window |
| `locale` | `'en'` | `en`, `ro`, `ru`, `es`, `fr`, `it`, `de`, `zh`, or anything added with `addLocale()`. `locales()` lists them |
| `providers` | `null` | Provider configuration; see below |
| `cluster` | `false` | `true`, or a number: markers group once there are at least that many |
| `format` | `'flat'` | Coordinate shape returned by getters and carried by events: `flat`, `pairs`, `objects` |
| `snapPixels` | `12` | Snap radius in screen pixels while drawing or dragging; `0` disables it |
| `viewDebounce` | `220` | Debounce for `event:view-changed`, in ms |
| `frame` | `'auto'` | Where the map is built: `'auto'` uses the module's own `frame.html` only when the host document cannot send a `Referer`, `true` always, `false` never. See *The module's own frame* below |
| `showToolbar` | `true` | The whole toolbar |
| `toolbar` | all `true` | Per-group: `search`, `zoom`, `fit`, `locate`, `modes`, `layers`, `measure`, `editing` |
| `markers` | `null` | Markers to place at startup |
| `shapes` | `null` | Shape records to place at startup |
| `geojson` | `null` | A FeatureCollection to load at startup |

### Coordinates

Latitude before longitude, everywhere, as in Leaflet. A list of coordinates is accepted in any of these
shapes and returned in the one the caller asks for:

```js
map.setPolygon('p1', [47.01, 28.86, 47.02, 28.87, 47.03, 28.85]);        // flat
map.setPolygon('p1', [[47.01, 28.86], [47.02, 28.87], [47.03, 28.85]]);  // pairs
map.setPolygon('p1', [{ lat: 47.01, lng: 28.86 }, /* ... */]);           // objects

map.getPolygon('p1');            // flat, the default
map.getPolygon('p1', 'pairs');   // [[lat, lng], ...]
map.getPolygon('p1', 'objects'); // [{lat, lng}, ...]
```

Invalid entries are dropped rather than throwing -- coordinates arrive from forms and from other
people's exports, and one bad row should not cost the whole contour. Contours are **not** closed: the
first point is not repeated at the end.

### Providers

```js
map.setProviders({
    tiles: [
        'osm',                                        // the OSM standard layer
        { url: null, name: 'Grid' },                  // the tile-less graticule
        { url: 'https://tiles.example.com/{z}/{x}/{y}.png', attribution: 'Tiles: Example Inc.' }
    ],
    geocode: { url: 'https://nominatim.example.com', countryCodes: 'md,ro', language: 'ro' },
    route:   { url: 'https://osrm.example.com', profile: 'driving', attribution: 'Routing: OSRM' }
});
```

Shorthands: `'blank'` for the grid only, `{ geocode: false }` to disable search, a bare URL template in
place of a layer object. A layer that names its own `url` never inherits the preset's credit line --
crediting OpenStreetMap for somebody else's tiles would be false attribution -- so set `attribution`
for your own tile service. Switching to a layer with a lower `maxZoom` pulls the view back inside its
range, so no tiles are requested that the service never had.

### Instance Methods

#### View

| Method | Returns | Description |
|---|---|---|
| `node()` | `HTMLElement` | What was appended to the container: the `.sg-map` root, or the `<iframe>` in framed mode |
| `mapNode()` | `HTMLElement` | The `.sg-map` root itself, wherever it lives |
| `frame()` | `HTMLIFrameElement` | The frame, or `null` when the map is built in the host document |
| `mapDocument()` | `Document` | The document the map was built in |
| `whenLoaded()` | `Promise` | Resolves once the map is built |
| `setView(lat, lng [, zoom])` | `app` | Centre the map |
| `getView()` | `object` | `{lat, lng, zoom, bounds: {south, west, north, east}}` |
| `panTo(lat, lng)` | `app` | Pan without changing the zoom |
| `setZoom(z)` / `zoomIn()` / `zoomOut()` / `getZoom()` | -- | Zoom |
| `fitBounds([points [, padding]])` | `app` | Fit a point list, a bbox object, or -- with no argument -- everything on the map |
| `fitAll([padding])` | `app` | Fit everything |
| `redraw()` | `app` | Re-measure the container (`invalidateSize`). Call it from a window manager's `require-redraw` |
| `leafletMap()` | `L.Map` | Escape hatch: the raw Leaflet map |
| `leaflet()` | `L` | Escape hatch: the Leaflet namespace |
| `destroy()` | `app` | Tear everything down and detach the DOM |

#### Markers

| Method | Returns | Description |
|---|---|---|
| `setMarkers(list)` | `number` | Replace every marker; returns how many were accepted |
| `addMarker(marker)` | `id` | Add one, or replace the one with that `id` |
| `updateMarker(id, patch)` | `boolean` | Merge fields into an existing marker |
| `removeMarker(id)` | `boolean` | Remove one |
| `clearMarkers()` | `app` | Remove all |
| `getMarkers()` | `array` | `[{id, lat, lng, label, color, properties}]` |
| `getMarker(id)` | `object` | One of the above, or `null` |
| `openPopup(id)` | `boolean` | Open a marker's popup; `false` if it is currently inside a cluster |

A marker is `{ id, lat, lng, label?, title?, color?, size?, popup?, draggable?, opacity?, properties? }`,
or a bare `[lat, lng]`. Pins are drawn as inline SVG, so no image is fetched. `color` takes any CSS
colour. With `cluster` on, markers that would overlap on the current screen are replaced by a counted
badge; clicking it zooms to what it holds.

#### Picking one point

| Method | Returns | Description |
|---|---|---|
| `pickPoint([{lat, lng, label}])` | `app` | Enter pick mode; a click places or moves the pin, which is also draggable |
| `endPick([keepMarker])` | `app` | Leave pick mode; `false` also removes the pin |
| `getPoint()` | `object` | `{id, lat, lng, label}` or `null` |
| `setPoint(lat, lng [, label])` | `boolean` | Place the pin from code |

In pick mode, choosing an address from the search results also moves the pin.

#### Contours, lines, circles, rectangles

| Method | Returns | Description |
|---|---|---|
| `setPolygon(id, coords [, opts])` | `id` | Place or replace a contour |
| `getPolygon(id [, format])` | `coords` | Its coordinates; also works on a rectangle |
| `setPolyline(id, coords [, opts])` | `id` | Place or replace a line |
| `getPolyline(id [, format])` | `coords` | Its coordinates |
| `setCircle(id, lat, lng, radius_m [, opts])` | `id` | A circle -- a delivery radius, a geofence |
| `setRectangle(id, bounds [, opts])` | `id` | `bounds` is `{south, west, north, east}` or any point list |
| `drawPolygon([id [, opts]])` | `id` | Draw a new contour: a click per point, double-click or **Done** to finish |
| `drawPolyline([id [, opts]])` | `id` | The same for a line |
| `editPolygon(id [, on])` | `boolean` | Show the vertex handles of an existing shape |
| `removeShape(id)` | `boolean` | Remove one |
| `clearShapes()` | `app` | Remove all |
| `getShapes()` | `array` | `[{id, kind, label}]` |
| `getShape(id [, format])` | `object` | Kind-dependent: `coords`, or `lat/lng/radius`, or `bounds` |

Shape options: `color`, `fillColor`, `fillOpacity`, `fill`, `width`, `opacity`, `dashArray`, `label`,
`editable`, and `arrows` for a line.

#### Editing

While a shape is being drawn or edited: drag a vertex to move it, click the half-transparent handle in
the middle of an edge to insert one, right-click a vertex to delete it. A vertex within `snapPixels` of
another shape's vertex snaps onto it exactly, so adjacent parcels share an edge. A contour never drops
below three points, a line never below two.

| Method | Returns | Description |
|---|---|---|
| `undo()` / `redo()` | `boolean` | One step of vertex editing |
| `canUndo()` / `canRedo()` | `boolean` | Whether the buttons should be live |
| `finishDrawing()` | `boolean` | Finish the drawing; `false` while it is still too short |
| `cancelDrawing()` | `boolean` | Abandon it; an unfinished shape is removed |

#### Tracks

| Method | Returns | Description |
|---|---|---|
| `setTrack(id, points [, opts])` | `id` | A line with direction arrows |
| `playTrack(id [, opts])` | `boolean` | Walk a marker along it. `{duration, fps, follow, color, keepMarker}` |
| `pauseTrack()` / `seekTrack(0..1)` / `stopTrack()` | `boolean` | Playback control |

The position is interpolated by **distance**, not by vertex index: a GPS track is dense where the
vehicle was slow, so stepping per vertex would play the fast parts slowly and the slow parts fast.

#### Address search and routing

| Method | Returns | Description |
|---|---|---|
| `geocode(text, cb)` | `app` | `cb(err, [{lat, lng, label, name, type, bbox, address, osm}])` |
| `reverse(lat, lng, cb)` | `app` | `cb(err, {lat, lng, label, address, osm})` |
| `route(points [, opts], cb)` | `app` | `cb(err, {distance_m, duration_s, geometry, legs, waypoints, profile})` |
| `pendingRequests()` | `number` | How many provider requests are queued or in flight |

`route` options: `profile`, `draw` (default `true`, draws the result as a line), `id`, `fit`, `color`,
`width`, `steps`. Errors carry a stable `code` -- `ERR_NO_ROUTER`, `ERR_NO_GEOCODER`, `ERR_NETWORK`,
`ERR_TIMEOUT`, `ERR_PARSE`, `ERR_NO_RESULT`, `ERR_NO_ROUTE`, `ERR_BAD_INPUT`, `ERR_HTTP_<status>`,
`ERR_FRAME` --
so a host can branch on them instead of matching translated text.

#### Geometry and measurement

No service is involved in any of these; they are the `gadgets/map/geo` functions.

| Method | Returns | Description |
|---|---|---|
| `measureDistance(points)` | metres | Length of a path |
| `measureArea(coords)` | m&sup2; | Area of a ring, by spherical excess |
| `distance(a, b)` | metres | Great-circle distance between two points |
| `pointInPolygon(point, coordsOrId)` | `boolean` | Containment; takes a shape id or a coordinate list |
| `centroid(coords [, format])` | point | Area-weighted centroid |
| `bbox(coords)` | `object` | `{south, west, north, east}` |
| `simplify(coords, tolerance_m [, format])` | `coords` | Douglas-Peucker, tolerance in metres |
| `geo()` | `object` | The whole geometry namespace, including `bearing`, `destination`, `formatDistance`, `formatArea` |
| `startMeasure([closed])` / `stopMeasure()` | `boolean` | The on-map measuring tool with its readout |

`pointInPolygon` works on the lat/lng plane. At the scale this module serves -- a yard, a city, a
delivery region -- the error is far below the precision of a hand-drawn contour, but a ring spanning
the antimeridian or a pole is outside what it answers correctly.

#### GeoJSON

| Method | Returns | Description |
|---|---|---|
| `toGeoJSON()` | `object` | Everything on the map as a FeatureCollection |
| `loadGeoJSON(input [, opts])` | `number` | Load one; `{replace: true, fit: true}` |

GeoJSON is `[lng, lat]`; the swap happens inside the module. A circle travels as a `Point` with
`properties.radius_m`, a rectangle as a `Polygon` with `properties.shape = "rectangle"`, and both come
back as what they were. `Multi*` geometries are split into one shape per part, because exports from
QGIS and PostGIS routinely wrap a single shape in a `MultiPolygon`. Polygon holes are **not**
supported: only the outer ring is read.

#### Languages

The map speaks **English, Romanian, Russian, Spanish, French, Italian, German and Chinese**; every label,
hint and error message is translated, and `geo().formatDistance()` / `formatArea()` use the locale's
decimal separator (`1,54 km` in most of Europe, `1.54 km` in English and Chinese).

| Method | Description |
|---|---|
| `locales()` | The codes the map can speak, the ones a host added included |
| `setLocale(code)` / `getLocale()` | Switch; a regional code falls back to its language (`ro-MD` to `ro`) |
| `addLocale(code, dict)` | Register a new language, or **extend an existing one** -- the dictionary is merged, so three labels can be renamed without re-translating the module |
| `i18n()` | The translation namespace itself |

```js
map.addLocale('pt', {
    'search.placeholder': 'Procurar um endereço',
    'mode.point': 'Colocar um ponto'
});                                    // the rest falls back to English
map.setLocale('pt');

map.addLocale('ro', { 'mode.point': 'Pune pinul' });   // just renames one label
```

#### Configuration at runtime

| Method | Returns | Description |
|---|---|---|
| `setProviders(cfg)` / `getProviders()` | -- | Replace or read the provider configuration |
| `dataRecipients()` | `array` | `[{service, host, receives}]` -- for a privacy notice |
| `getTileLayers()` | `array` | `[{index, name, active, tiled}]` |
| `setTileLayer(index)` | `boolean` | Switch layer |
| `setReadOnly(flag)` / `isReadOnly()` | `boolean` | Editing on or off |
| `setMode(mode)` / `getMode()` | -- | See the mode list in the configuration table |
| `setLocale(code)` / `getLocale()` | -- | Switch language; the toolbar is rebuilt |
| `addLocale(code, dict)` | `boolean` | Register or extend a locale; merging, so three labels can be overridden |
| `locate([opts], cb)` | `app` | Browser geolocation. `{setView, zoom, marker, highAccuracy, timeout}` |

### Events

Subscribe with `map.on(name, handler)`.

| Event | Payload | When |
|---|---|---|
| `ready` | `app` | The map is built |
| `event:click` | `{lat, lng}` | The map was clicked |
| `event:point-changed` | `{id, lat, lng}` | The picked point was placed or moved |
| `event:marker-moved` | `{id, lat, lng}` | A draggable marker was dropped |
| `event:marker-click` | `{id, lat, lng, label}` | A marker was clicked |
| `event:cluster-click` | `{count, ids, lat, lng}` | A cluster badge was clicked |
| `event:polygon-changed` | `{id, coords, phase, points, area_m2}` | A contour changed. `phase` is `drawing`, `drag` (live, one per mouse move) or `commit` |
| `event:polyline-changed` | `{id, coords, phase, points, length_m}` | The same for a line |
| `event:shape-finished` | `{id, kind, coords}` | A drawing was finished |
| `event:shape-click` | `{id, lat, lng}` | A shape was clicked |
| `event:view-changed` | `{lat, lng, zoom, bounds}` | The view settled (debounced) |
| `event:mode-changed` | `{mode}` | The mode changed |
| `event:layer-changed` | `{index, name}` | The tile layer was switched |
| `event:search-results` | `{query, results}` | A search answered |
| `event:search-selected` | the result row | A result was chosen |
| `event:measure` | `{points, length_m, area_m2, coords}` | The measuring tool updated |
| `event:route-done` | the route | A route came back |
| `event:track` | `{id, progress, walked_m, total_m, lat, lng, done}` | Track playback advanced |
| `event:locate` | `{lat, lng, accuracy_m}` | Geolocation answered |
| `event:error` | `{code, message, error}` | Anything failed |
| `event:destroyed` | -- | `destroy()` finished |

Every method also raises the framework's `before<Name>` / `on<Name>` / `after<Name>` lifecycle events,
so a host can hook a call without patching the module.

A vertex drag emits `event:polygon-changed` with `phase: 'drag'` once per mouse move. Persist on
`commit`, not on `drag`.

## Use Cases

### Pick a location for a record

```js
var map = SGMap({ container: holder, lat: 47.0105, lng: 28.8638, zoom: 16, mode: 'pick-point' });

map.on('event:point-changed', function (p) {
    form.lat.value = p.lat;
    form.lng.value = p.lng;
});
```

### Draw a contour and read it back

```js
map.setPolygon('yard', form.geo.value, { editable: true, color: '#d93025' });

map.on('event:polygon-changed', function (e) {
    if (e.phase !== 'commit') return;          // 'drag' fires per mouse move
    form.geo.value = JSON.stringify(e.coords); // flat [lat, lng, lat, lng, ...]
    areaLabel.textContent = map.geo().formatArea(e.area_m2, 'ro');
});

// or let the user draw a new one
map.drawPolygon('yard', { color: '#d93025' });
```

### Is this address inside the delivery zone?

```js
map.setPolygon('zone', zoneCoords);
map.setCircle('radius', 47.0105, 28.8638, 5000, { label: '5 km' });

map.geocode('Str. Alba Iulia 75, Chisinau', function (err, hits) {
    if (err || !hits.length) return;
    var inside = map.pointInPolygon([hits[0].lat, hits[0].lng], 'zone');
    var km = (map.distance([47.0105, 28.8638], [hits[0].lat, hits[0].lng]) / 1000).toFixed(1);
    console.log(inside ? 'in the zone' : 'outside', km + ' km from the depot');
});
```

### Replay a vehicle's day

```js
map.setTrack('day', positions, { color: '#1557b0', arrows: true });
map.fitBounds();
map.playTrack('day', { duration: 20000, follow: true });

map.on('event:track', function (p) {
    progress.value = p.progress;
});
```

### A map that touches no service

```js
var map = SGMap({
    container: holder,
    providers: { tiles: 'blank', geocode: false },
    markers: stops
});
```

The coordinate grid replaces the tiles, every vector feature still works, and `dataRecipients()`
returns an empty list.

### Several hundred pins

```js
var map = SGMap({ container: holder, cluster: 20, markers: posList });
map.fitBounds();
map.on('event:cluster-click', function (c) { console.log(c.count, c.ids); });
```

## Notes

- **Containers that change size.** The module watches its own element with a `ResizeObserver`, so a
  pinned window or a form column that changes width needs nothing. A container that is hidden while it
  resizes has no render frames, so call `redraw()` when it becomes visible again.
- **Keyboard.** The map container carries `tabindex="0"` and `role="application"`; once focused, the
  arrow keys pan and `+` / `-` zoom. Every control has an accessible label, and the search result list
  is navigable with the arrow keys and Enter.
- **Narrow containers.** Usable down to 320 px: the search field shrinks, the toolbar wraps and the
  attribution stays visible.
- **Printing.** The controls are hidden, the map and its attribution are not.
- **There is no PNG snapshot.** Compositing the tiles into a canvas would mean reading them again
  through a CORS-enabled provider, which the tile policy does not invite.