# Map Editor

Interactive map editor on OpenStreetMap data: markers, polygons, polylines, circles, rectangles and tracks, with vertex editing, snap, undo/redo, free-text notes, address search, measurement, and round-trip import/export in **GeoJSON**, **KML** and **GPX**.

Built on top of the [`gadgets/map`](https://cdn.sgapps.io/components/application-prototype-thirdparty/docs/#/gadgets/map.md) module (OpenStreetMap tiles via Leaflet, in-house editing + provider layer). The editor adds a save/export toolbar, a per-feature note panel, and the `/online/webapp/map-editor` window-manager wrapper so the whole thing drops into an iframe or an in-page custom element with one line.

## Live Demo

<iframe id="me-demo" src="/online/webapp/map-editor" width="100%" height="520" frameborder="0" style="border:1px solid #ccc; border-radius:4px;"></iframe>

<script>window._wsConnect('me-demo', 'meSocket');</script>

## Embed

```html
<iframe src="https://sgapps.io/online/webapp/map-editor"
    width="100%" height="600" frameborder="0"></iframe>
```

### Open with a file

The editor opens whatever file-manager path is passed as the first argument. The file extension picks the parser:

| Extension | Format | Round-trip |
|---|---|---|
| `.geojson`, `.json` (GeoJSON content) | RFC 7946 FeatureCollection | ✅ full — circles survive as `Point + properties.radius_m`, rectangles as `Polygon + properties.shape = "rectangle"` |
| `.kml` | OGC KML 2.2 Placemarks | ✅ points, lines, polygons; circles / rectangles kept via `<ExtendedData>` hints |
| `.gpx` | GPX 1.1 (waypoints / tracks / routes) | points → `<wpt>`, lines → `<trk>`, polygons → `<rte>` (ring, lossy on area semantics) |

```html
<iframe src="https://sgapps.io/online/webapp/map-editor?args=%2Fhome%2Fguest%2Fzones.geojson"
    width="100%" height="600" frameborder="0"></iframe>
```

### In-page (no iframe)

The CDN-registered wrapper `b2b.editor.map-editor` creates an in-page custom element and connects to the window-manager app behind the scenes.

```html
<script src="https://cdn.sgapps.io/scripts/modules-webapp/exporter.js"></script>
<sgapps-map-editor--tool id="map"></sgapps-map-editor--tool>
<script>
Application.require("b2b.editor.map-editor").then(function (factory) {
    var app = factory();
    document.getElementById("map").replaceWith(app.node());
    app.editor().then(function (ed) {
        ed.visible(true);
        // ed.client is a WindowSocket client ready for fire(…)
    });
});
</script>
```

---

## Events Reference

Everything below is sent through the standard webapp socket:

```js
var socket = new WindowSocket(iframe.contentWindow);
socket.start();
socket.fire("webapp::instance::request", eventName, ...args, callback);
```

The map also emits events upward through `api-event::instance:*`; see the full list under **Map events (upstream)** below.

---

### `toGeoJSON` -- Export the current map

Returns everything on the map as an RFC 7946 FeatureCollection. Circles become `Point + properties.radius_m`; rectangles become `Polygon + properties.shape = "rectangle"`; notes are serialised as `properties.note`.

```js
socket.fire("webapp::instance::request", "toGeoJSON",
    function (err, fc) { console.log(fc.features.length, "features"); });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','toGeoJSON',function(e,fc){if(e)return alert('Error: '+e.message);alert(fc.features.length+' features\n\nFirst 400 chars:\n'+JSON.stringify(fc,null,2).substring(0,400))})">Try: Export current map</button>

---

### `loadGeoJSON` -- Replace or merge features

Loads a FeatureCollection into the map. Options: `{ replace: true, fit: true }`.

| Arg | Type |
|---|---|
| `fc` | FeatureCollection |
| `opts` | `{replace?, fit?}` |
| `callback` | `(err, acceptedCount)` |

```js
socket.fire("webapp::instance::request", "loadGeoJSON", fc, { replace: true, fit: true },
    function (err, n) { console.log("loaded", n); });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','loadGeoJSON',{type:'FeatureCollection',features:[{type:'Feature',geometry:{type:'Point',coordinates:[28.8638,47.0105]},properties:{id:'demo-a',label:'Demo A',note:'Loaded from docs'}},{type:'Feature',geometry:{type:'Point',coordinates:[28.868,47.012]},properties:{id:'demo-b',label:'Demo B'}},{type:'Feature',geometry:{type:'LineString',coordinates:[[28.8638,47.0105],[28.868,47.012]]},properties:{id:'demo-line'}}]},{replace:true,fit:true},function(e,n){if(e)return alert('Error: '+e.message);alert('Loaded '+n+' features')})">Try: Load sample FeatureCollection</button>

---

### `exportAs` -- Serialise to a format string

| Arg | Type |
|---|---|
| `format` | `"geojson"` \| `"kml"` \| `"gpx"` |
| `callback` | `(err, text: string)` |

```js
socket.fire("webapp::instance::request", "exportAs", "kml",
    function (err, kmlText) {
        var blob = new Blob([kmlText], { type: "application/vnd.google-earth.kml+xml" });
        var a = document.createElement("a");
        a.href = URL.createObjectURL(blob); a.download = "map.kml"; a.click();
    });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','exportAs','kml',function(e,t){if(e)return alert('Error: '+e.message);var b=new Blob([t],{type:'application/vnd.google-earth.kml+xml'});var a=document.createElement('a');a.href=URL.createObjectURL(b);a.download='map.kml';a.click();})">Try: Download as KML</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','exportAs','gpx',function(e,t){if(e)return alert('Error: '+e.message);var b=new Blob([t],{type:'application/gpx+xml'});var a=document.createElement('a');a.href=URL.createObjectURL(b);a.download='map.gpx';a.click();})">Try: Download as GPX</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','exportAs','geojson',function(e,t){if(e)return alert('Error: '+e.message);var b=new Blob([t],{type:'application/geo+json'});var a=document.createElement('a');a.href=URL.createObjectURL(b);a.download='map.geojson';a.click();})">Try: Download as GeoJSON</button>

---

### `addMarker`, `removeMarker`, `clearMarkers`

```js
socket.fire("webapp::instance::request", "addMarker",
    { id: "pos-1", lat: 47.0105, lng: 28.8638, label: "HQ", color: "#d93025" },
    function (err, id) { /* id = "pos-1" */ });
```

Marker shape: `{ id, lat, lng, label?, title?, color?, size?, popup?, draggable?, opacity?, properties? }`.

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','addMarker',{id:'docs-hq',lat:47.0105,lng:28.8638,label:'HQ Chișinău',title:'Added from docs',color:'#d93025',draggable:true},function(e){if(e)return alert('Error: '+e.message);})">Try: Add red marker (HQ)</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','addMarker',{id:'docs-client-'+Date.now(),lat:47.0105+(Math.random()-0.5)*0.03,lng:28.8638+(Math.random()-0.5)*0.03,label:'Random pin',color:'#188038',draggable:true},function(e){if(e)return alert('Error: '+e.message);})">Try: Add random green pin</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','removeMarker','docs-hq',function(e,ok){if(e)return alert('Error: '+e.message);alert(ok?'Removed HQ':'HQ not found')})">Try: Remove HQ</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','clearMarkers',function(e){if(e)return alert('Error: '+e.message);})">Try: Clear all markers</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','updateMarker','docs-hq',{color:'#1557b0',label:'HQ (recoloured)'},function(e,ok){if(e)return alert('Error: '+e.message);alert(ok?'HQ updated':'HQ not found; add it first')})">Try: Update HQ (blue + new label)</button>

---

### `drawPolygon`, `drawPolyline`

Enter drawing mode: a click per vertex, double-click or **Done** to finish.

```js
socket.fire("webapp::instance::request", "drawPolygon",
    "zone-a", { editable: true, color: "#d93025" },
    function (err, id) { /* id when drawing starts */ });
```

Finished shapes emit `event:shape-finished` upward.

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','drawPolygon',null,{color:'#d93025'},function(e){if(e)return alert('Error: '+e.message);})">Try: Draw a polygon</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','drawPolyline',null,{color:'#1557b0',arrows:true},function(e){if(e)return alert('Error: '+e.message);})">Try: Draw a line</button>

Click on the map to place vertices, then double-click (or press **Done** in the map toolbar) to finish.

---

### `setPolygon`, `setPolyline`, `setCircle`, `setRectangle`

Place or replace a shape from code. Coordinates are latitude first.

```js
socket.fire("webapp::instance::request", "setPolygon",
    "yard", [[47.01, 28.86], [47.02, 28.87], [47.03, 28.85]],
    { editable: true, color: "#d93025" }, function (err, id) {});

socket.fire("webapp::instance::request", "setCircle",
    "radius", 47.0105, 28.8638, 5000,
    { label: "5 km", color: "#188038" }, function (err, id) {});

socket.fire("webapp::instance::request", "setRectangle",
    "bbox", { south: 46.9, west: 28.7, north: 47.1, east: 29.0 },
    {}, function (err, id) {});
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setPolygon','docs-yard',[[47.009,28.858],[47.014,28.86],[47.013,28.868],[47.008,28.866]],{color:'#d93025'},function(e){if(e)return alert('Error: '+e.message);})">Try: Place a polygon</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setCircle','docs-coverage',47.0105,28.8638,1500,{label:'1.5 km',color:'#188038'},function(e){if(e)return alert('Error: '+e.message);})">Try: Place a 1.5 km circle</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setRectangle','docs-bbox',{south:47.005,west:28.855,north:47.015,east:28.875},{label:'bbox',color:'#f29900'},function(e){if(e)return alert('Error: '+e.message);})">Try: Place a rectangle</button>

---

### `getShapes`, `getShape`, `removeShape`, `clearShapes`

```js
socket.fire("webapp::instance::request", "getShapes",
    function (err, list) { /* [{id, kind, label}] */ });

socket.fire("webapp::instance::request", "getShape", "yard", "pairs",
    function (err, data) { /* {coords: [[lat,lng],...]} or {lat,lng,radius} or {bounds} */ });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','getShapes',function(e,l){if(e)return alert('Error: '+e.message);alert(l.length+' shapes:\n\n'+l.map(function(s){return'['+s.kind+'] '+s.id+(s.label?' -- '+s.label:'')}).join('\n'))})">Try: List shapes</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','clearShapes',function(e){if(e)return alert('Error: '+e.message);})">Try: Clear all shapes</button>

---

### `setView`, `getView`, `fitAll`

```js
socket.fire("webapp::instance::request", "setView", 47.0105, 28.8638, 15,
    function (err) {});

socket.fire("webapp::instance::request", "getView",
    function (err, v) { /* {lat, lng, zoom, bounds: {south, west, north, east}} */ });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setView',47.0105,28.8638,16,function(e){if(e)return alert('Error: '+e.message);})">Try: Centre on Chișinău (zoom 16)</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setView',44.4268,26.1025,13,function(e){if(e)return alert('Error: '+e.message);})">Try: Centre on București (zoom 13)</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','fitAll',null,function(e){if(e)return alert('Error: '+e.message);})">Try: Fit all features</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','getView',function(e,v){if(e)return alert('Error: '+e.message);alert('lat: '+v.lat.toFixed(5)+'\nlng: '+v.lng.toFixed(5)+'\nzoom: '+v.zoom+'\nbounds: '+JSON.stringify(v.bounds))})">Try: Get current view</button>

---

### `setMode`, `getMode`

Modes: `view`, `pick-point`, `edit-polygon`, `edit-line`, `draw-polygon`, `draw-line`, `measure`.

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setMode','measure',function(e){if(e)return alert('Error: '+e.message);})">Try: Enter measure mode</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setMode','view',function(e){if(e)return alert('Error: '+e.message);})">Try: Back to view mode</button>

---

### `geocode`, `reverse`

Address search against the configured Nominatim provider (OSM default). Serialised at module level (≥ 1.1 s apart across every map on the page).

```js
socket.fire("webapp::instance::request", "geocode", "Str. Alba Iulia 75, Chisinau",
    function (err, hits) { /* [{lat, lng, label, name, type, bbox, address, osm}] */ });

socket.fire("webapp::instance::request", "reverse", 47.0105, 28.8638,
    function (err, hit) { /* {lat, lng, label, address, osm} */ });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','geocode','Str. Alba Iulia 75, Chișinău',function(e,h){if(e)return alert('Error: '+(e.code||e.message));if(!h.length)return alert('No results');var top=h[0];alert('Top result:\n'+top.label+'\n\nlat: '+top.lat+'\nlng: '+top.lng);window.meSocket.fire('webapp::instance::request','setView',top.lat,top.lng,17,function(){});})">Try: Geocode address + fly there</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','reverse',47.0105,28.8638,function(e,h){if(e)return alert('Error: '+(e.code||e.message));alert('Reverse geocoded:\n'+h.label)})">Try: Reverse geocode city centre</button>

Error codes to branch on: `ERR_NO_GEOCODER`, `ERR_NETWORK`, `ERR_TIMEOUT`, `ERR_PARSE`, `ERR_NO_RESULT`, `ERR_HTTP_<status>`.

---

### `setProviders` -- swap tile / geocoding / routing endpoints

```js
socket.fire("webapp::instance::request", "setProviders", {
    tiles: ["osm", { url: "https://tiles.example.com/{z}/{x}/{y}.png", attribution: "© Example" }],
    geocode: { url: "https://nominatim.example.com", countryCodes: "md,ro", language: "ro" },
    route: { url: "https://osrm.example.com", profile: "driving", attribution: "Routing: OSRM" }
}, function (err) {});
```

Shorthand `{ tiles: "blank" }` renders the tile-less coordinate graticule (no network traffic).

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setProviders',{tiles:'blank'},function(e){if(e)return alert('Error: '+e.message);})">Try: Blank-grid tiles (no OSM)</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setProviders',{tiles:['osm']},function(e){if(e)return alert('Error: '+e.message);})">Try: Restore OSM tiles</button>

---

### `undo`, `redo`

One step of vertex editing. Returns a boolean.

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','undo',function(e,ok){if(e)return alert('Error: '+e.message);})">Try: Undo</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','redo',function(e,ok){if(e)return alert('Error: '+e.message);})">Try: Redo</button>

---

### `setNote`, `getNote`

Attach a free-text description to any marker or shape (`properties.note` in the GeoJSON export).

```js
socket.fire("webapp::instance::request", "setNote", "pos-1", "Main warehouse — gate 2",
    function (err) {});

socket.fire("webapp::instance::request", "getNote", "pos-1",
    function (err, note) { /* string or null */ });
```

<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','setNote','docs-hq','Main warehouse -- gate 2',function(e){if(e)return alert('Error: '+e.message);alert('Note set on docs-hq. Add the HQ marker first with the button above if you have not already.')})">Try: Attach note to docs-hq</button>
<button onclick="window._ws('meSocket')&&window.meSocket.fire('webapp::instance::request','getNote','docs-hq',function(e,n){if(e)return alert('Error: '+e.message);alert(n==null?'(no note)':n)})">Try: Read note from docs-hq</button>

The in-app **Note…** button opens a picker over the current markers and shapes.

---

### `save`, `saveAs`

Writes the current map back to the file the editor was opened with (via `app.fs()`):

```js
socket.fire("webapp::instance::request", "save", function (err) {});
```

Save-As asks for a filename via `file-selector`:

```js
socket.fire("webapp::instance::request", "saveAs", "kml", null, function (err) {});
```

Or save directly to a known path:

```js
socket.fire("webapp::instance::request", "saveAs", "gpx", "/home/me/trail.gpx", function (err) {});
```

---

## Map events (upstream)

These are forwarded through `api-event::instance:*` and arrive on the socket as:

```js
socket.on("api-event::instance:event:polygon-changed", function (e) {
    if (e.phase !== "commit") return;         // 'drag' fires per mouse move
    console.log("polygon", e.id, e.area_m2);
});
```

| Event | Payload |
|---|---|
| `ready` | `app` |
| `event:click` | `{lat, lng}` |
| `event:point-changed` | `{id, lat, lng}` |
| `event:marker-moved` | `{id, lat, lng}` |
| `event:marker-click` | `{id, lat, lng, label}` |
| `event:polygon-changed` | `{id, coords, phase, points, area_m2}` -- `phase` is `drawing`, `drag` (live) or `commit` |
| `event:polyline-changed` | `{id, coords, phase, points, length_m}` |
| `event:shape-finished` | `{id, kind, coords}` |
| `event:shape-click` | `{id, lat, lng}` |
| `event:view-changed` | `{lat, lng, zoom, bounds}` (debounced) |
| `event:mode-changed` | `{mode}` |
| `event:layer-changed` | `{index, name}` |
| `event:search-results` | `{query, results}` |
| `event:search-selected` | the result row |
| `event:measure` | `{points, length_m, area_m2, coords}` |
| `event:route-done` | the route |
| `event:track` | `{id, progress, walked_m, total_m, lat, lng, done}` |
| `event:locate` | `{lat, lng, accuracy_m}` |
| `event:error` | `{code, message, error}` |

**Persist on `commit`, not on `drag`:** a vertex drag emits `polygon-changed` with `phase: "drag"` once per mouse move; wait for `phase: "commit"` before writing to a database.

---

## Use Cases

### Delivery zone editor

```js
socket.fire("webapp::instance::request", "setPolygon",
    "zone", existingCoords, { editable: true, color: "#d93025" });
socket.on("api-event::instance:event:polygon-changed", function (e) {
    if (e.phase === "commit") form.zoneGeoJson.value = JSON.stringify(e.coords);
});
```

### Geofence check against a drawn zone

Load the GeoJSON that comes back from `toGeoJSON()` into any point-in-polygon helper on the server, or (if the host also has `gadgets/map/geo`) run the check client-side with the same semantics the module uses.

### Store locator + address search

```js
socket.fire("webapp::instance::request", "geocode", userInput, function (err, hits) {
    if (hits.length) {
        socket.fire("webapp::instance::request", "setView",
            hits[0].lat, hits[0].lng, 16, function () {});
    }
});
```

### Blank-canvas map (no OSM tiles)

```js
socket.fire("webapp::instance::request", "setProviders", { tiles: "blank" }, function () {});
```

The coordinate grid replaces the tiles, every vector feature still works, and no requests are sent to any third party. Useful for air-gapped demos and for review builds that must not contact OSM.

---

## Privacy / what reaches third parties

By default the editor uses the standard OpenStreetMap tiles (`tile.openstreetmap.org`) and Nominatim geocoding (`nominatim.openstreetmap.org`). Each receives the viewer's IP, the browser's `Referer`, and the tile coordinates or searched text. There is no autocomplete, no prefetch, no cache. Routing has no default provider -- `route()` without a configured server fails with `ERR_NO_ROUTER` and sends nothing. To disable OSM entirely use the `blank` tiles shorthand above.

See [`gadgets/map` docs §What reaches third parties](https://cdn.sgapps.io/components/application-prototype-thirdparty/docs/#/gadgets/map.md) for the full policy summary.