@superrouteca/smap 1.1.7 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 1.2.1 — 2026-10-28
+
+- Pins: the number and the count badge are drawn into each pin at every zoom, so where pins overlap the upper pin
+  covers the lower one with its number and badge, as on Superroute's route map. Before, further out than zoom 13
+  numbers and badges were their own layers above every pin. `bakeZoom` (a zoom) keeps the former drawing further out
+  than it; `bakeZoom: false` at every zoom.
+
+## 1.2.0 — 2026-10-28
+
+- Maps without WebGL: where the browser has no WebGL 2 (old computers, remote desktops, graphics acceleration
+  switched off) or refuses a WebGL context, the map is drawn on a 2D canvas instead — sMap's raster tiles of the same
+  scheme, with points, route pins, lines, areas, heat maps, popups, tooltips, custom markers, clusters, drawing and
+  selection working through the same calls — so a page is written once. Such a map does not tilt or turn and has no
+  3D buildings, terrain, hillshade or 3D models; it says so with an `smap.unsupported` event. `renderer: 'webgl'`
+  keeps the WebGL map only, `renderer: 'canvas'` always draws in 2D, and `map.renderer` says which one is in use.
+- Custom markers: `addCustomMarkers(id, data, { render })` puts your own element at each point — any HTML, such as a
+  vehicle with its driver's name, a depot icon or a label — above the drawn layers. Elements are made when a point
+  first comes into view and are not laid out while out of view, so thousands stay smooth. Anchor, offset, class,
+  opacity and z-order per feature, the marker under the pointer brought to the front (`riseOnHover`), clicks and
+  popups as on other layers. `setData` keeps the element of every feature still there and renders it again only when
+  its properties change; `getMarker(id, key)` gives one marker's element.
+- Dragging: points (`addPoints`) and custom markers take `draggable` (for every feature or per feature) with
+  `onDragStart`, `onDrag` and `onDragEnd`. The map does not pan while dragging, the release is not a click, and the
+  layer's data holds the new position afterwards (a copy: the objects you gave are not changed). A dragged point of
+  a large layer costs two data updates, whatever the layer's size.
+- Tooltips: every layer takes `tooltip` (a template or a function) shown while the pointer is over a feature —
+  beside a point or a custom marker, at the pointer on lines and areas — with `direction`, `offset` and `className`.
+- Line labels: `addLines(…, { label: 'name' })` writes a property along each line as a permanent label.
+- Clusters with their own look: `cluster.ring` draws each cluster as its count inside a ring of its points' colours
+  (each colour's share of the points, e.g. the drivers whose stops it holds), and `cluster.html(cluster)` draws each
+  cluster yourself from its count, its properties and its points. A click still zooms in to where it splits
+  (`zoomOnClick: false` turns it off); `maxZoom` is the last zoom with clusters.
+- Controls: a layer switcher (`addTool('layers', 'layers', { options: { base, overlays } })`) chooses one base map at
+  a time — a scheme, a custom style or imagery — and turns overlays on and off, reporting each change. `setBaseImagery`
+  shows satellite or aerial tiles in place of the street map, with or without the street map's labels on top, your
+  layers staying above. `addControl` puts any element or control in a corner without making it a tool. The full
+  screen tool takes `{ container }` to make a page element (the map with its side panels) full screen.
+- Drawing and editing: `drawTool()` draws polygons, rectangles, circles, lines and points and edits them — drag a
+  vertex, drag a midpoint to add one, move a whole shape, delete a vertex or a shape, draw a hole in a polygon — with
+  snapping to other shapes' vertices, undo and redo, keyboard keys and a toolbar whose texts can be translated.
+  Rectangles stay rectangles and circles keep their centre and radius. Every change is reported with the shapes as
+  GeoJSON.
+- Area selection: `selectArea({ mode: 'box' | 'lasso' })` lets the user draw a box or a free shape and answers the
+  features of each layer inside it.
+- Heat maps: `addHeatmap(id, points, { weight, radius, intensity, colors })`.
+- Google base maps: `setGoogleBase({ session, key })` shows Google's road or satellite map read straight from Google
+  with a Map Tiles session your server made with your own Google key, with the Google logo and the copyright of the
+  area in view; `onFail` is called when Google's tiles do not load.
+- 3D models: `addModels(id, points, { model, size, heading })` places a glTF model at each point, turned to its
+  heading, in the map's 3D view (three.js handed over once with `sMap.useThree(THREE, GLTFLoader)`).
+- Terrain: `setTerrain({ tiles, encoding, exaggeration, hillshade })` draws the map over elevation tiles (seen when
+  tilted) with hillshading under the roads; kept across scheme and language changes.
+- Synced maps: `syncWith(other, { offsetZoom })` keeps two maps on the same view, both ways (a picture in picture).
+- Drawn tiles: `addCanvasTiles(id, draw)` shows raster tiles your page paints on a canvas.
+- Geometry helpers: `sMap.geo` — `distance`, `length`, `bounds`, `pointInPolygon` (with holes), `nearestPointOnLine`,
+  `distanceToLine`, `decodePolyline` and `encodePolyline`.
+
 ## 1.1.7 — 2026-10-28
 
 - Plan editor: faster edits through sMap's fast path, with no code change. When your plan editor token answer names a

package/README.md

@@ -65,6 +65,23 @@ SDK does not wrap, and `getEngine()` gives the renderer itself.
 In a server-rendered page (for example Next.js), create the map in an effect or event handler, never while rendering
 on the server: `new Map()` throws outside a browser. Importing the package is fine anywhere.
 
+## Without WebGL
+
+Where the browser has no WebGL 2 (old computers, remote desktops, graphics acceleration switched off) or refuses a
+WebGL context, the map is drawn on a 2D canvas: sMap's raster tiles of the same scheme and language, with your
+points, pins, lines, areas, heat maps, popups, tooltips, custom markers, clusters, drawing and selection drawn by the
+SDK through the same calls. Your page needs nothing of its own.
+
+```js
+const map = new Map({ container: 'map', apiKey: 'smk_…', renderer: 'auto' });   // 'webgl' | 'canvas' to choose
+map.renderer;                                     // 'webgl' or 'canvas'
+map.on('smap.unsupported', (e) => console.info('not without WebGL:', e.feature));
+```
+
+A canvas map does not tilt or turn and has no 3D buildings, terrain, hillshade or 3D models; asking for one of them
+fires `smap.unsupported`. Style layers of your own are drawn when they are raster, fill, line, circle, symbol or
+heatmap layers.
+
 ## Popups
 
 Give a layer a `popup` and a click on one of its features opens it. A map has one popup: opening another closes the
@@ -201,6 +218,52 @@ map.addPoints('stops', stops, {           // {lng, lat, stop_number, status_colo
 Numbers and badges are drawn over all pins of the layer, so where pins overlap a lower pin's number can show through
 an upper pin.
 
+## Custom markers, dragging and tooltips
+
+**Custom markers** put your own element at each point, above the drawn layers. `render` returns an element or
+trusted HTML (inserted as is: escape feature data yourself). An element is made the first time its point comes into
+view and is left out of the page while out of view, so a layer of thousands stays smooth.
+
+```js
+map.addCustomMarkers('vehicles', vehicles, {          // [{ lng, lat, id, name, color, heading }, …]
+  idProperty: 'id',
+  anchor: 'center',                                  // or top, bottom, left, right, top-left, … (default center)
+  render: (p) => `<div class="truck" style="--c:${p.color}">${escapeHtml(p.name)}</div>`,
+  zIndex: { property: 'priority' },                  // per feature: a constant, a function or { property }
+  riseOnHover: true,
+  popup: '<b>{name}</b>',
+  tooltip: '{name}',
+});
+map.setData('vehicles', moved);                      // elements of features still there are kept (and only moved)
+map.getMarker('vehicles', 'v-17');                   // one marker's element
+```
+
+**Dragging**: points and custom markers take `draggable` (true, or per feature) and `onDragStart` / `onDrag` /
+`onDragEnd(feature, { lngLat, point, originalEvent })`. The map does not pan while a feature is dragged, the release
+is not a click, and the layer's data holds the new position afterwards (a copy of your data).
+
+```js
+map.addPoints('stops', stops, {
+  marker: { text: { property: 'stop_number' } },
+  draggable: (p) => !p.done,
+  onDragEnd: (f, e) => save(f.properties.id, e.lngLat),
+});
+```
+
+**Tooltips**: any layer takes `tooltip` — a template (`'{name}'`, each property HTML-escaped) or a function returning
+trusted HTML or a node — shown while the pointer is over a feature: beside a point or custom marker, at the pointer
+on lines and areas. `tooltipOptions`: `direction` (`top` default, `bottom`, `left`, `right`), `offset`, `className`.
+A map shows one tooltip at a time. **Line labels**: `addLines(id, data, { label: 'name' })` writes a property along
+each line (`labelSpacing`, `labelColor`).
+
+**Clusters with their own look**: `cluster.ring` draws each cluster as its count inside a ring of its points' colours
+(each colour's share), `cluster.html(cluster)` draws it yourself (`cluster.count`, `cluster.properties`,
+`await cluster.leaves(limit)`). A click zooms in to where the cluster splits (`zoomOnClick: false` turns it off).
+
+```js
+map.addPoints('stops', stops, { marker: { … }, cluster: { radius: 60, maxZoom: 14, ring: 'route_color' } });
+```
+
 ## Map tools: showing and hiding controls and panels
 
 Register what floats on the map, and the map gets a tools control (one button, the last of the map's toolbar) that
@@ -241,6 +304,61 @@ map.tools(); // [{ id: 'zoom', label: 'Zoom', visible: true }, …]
   like (the page's storage, your server).
 - The tools control joins the map with the first tool; a map without tools is unchanged.
 
+### Layer switcher, imagery and your own controls
+
+```js
+map.addTool('layers', 'layers', { label: 'Layers', options: {
+  base: [
+    { id: 'streets', label: 'Streets', style: 'light' },
+    { id: 'satellite', label: 'Satellite', imagery: { tiles: ['https://imagery.example/{z}/{y}/{x}'], maxzoom: 19, attribution: '© Example' } },
+    { id: 'hybrid', label: 'Hybrid', imagery: { tiles: ['https://imagery.example/{z}/{y}/{x}'], labels: true } },
+  ],
+  overlays: [{ id: 'traffic', label: 'Traffic', layers: ['traffic'], visible: false }],
+  onChange: ({ base, overlays }) => save(base, overlays),
+} });
+map.setBaseImagery({ tiles: […], labels: true });   // or null for the street map
+map.addControl(document.getElementById('legend'), 'bottom-left');   // in a corner, not a tool
+map.addTool('fullscreen', 'fullscreen', { options: { container: document.getElementById('stage') } });
+```
+
+Imagery is drawn over the basemap's land, water and roads and under its labels (kept with `labels: true`); your
+layers stay on top. The scheme already shown is not loaded again when only the imagery changes.
+
+## Drawing, editing and selecting
+
+```js
+const draw = map.drawTool({ features: zones, modes: ['polygon', 'rectangle', 'circle'], labels: { polygon: 'Zone' } });
+draw.on('change', (e) => save(e.features));      // created, edited, deleted: every shape as GeoJSON
+draw.start('polygon');                           // or from the toolbar
+draw.select(zoneId); draw.delete(); draw.undo();
+
+const picked = await map.selectArea({ mode: 'lasso', layers: ['stops'] });
+if (picked) { assign(picked.features.stops); }
+```
+
+Drawing: click to add vertices; a click on the first vertex, a double click or Enter finishes, Backspace removes the
+last vertex, Escape cancels. Rectangles and circles are dragged. A selected shape shows its vertices and midpoints:
+drag a vertex, drag a midpoint to add a vertex, drag the shape to move it, Delete removes the selected vertex or the
+shape, Ctrl/⌘+Z undoes (with Shift redoes). New and moved vertices snap to other shapes' vertices within 10 px.
+
+## Heat maps, terrain, synced maps, drawn tiles and geometry
+
+```js
+map.addHeatmap('density', stops, { weight: { property: 'orders' }, radius: 25, colors: ['#ffffb2', '#fd8d3c', '#bd0026'] });
+map.setTerrain({ tiles: ['https://dem.example/terrarium/{z}/{x}/{y}.png'], encoding: 'terrarium', exaggeration: 1.5 });
+const stop = map.syncWith(overview, { offsetZoom: -4 });          // a picture in picture; stop() ends it
+map.addCanvasTiles('grid', (ctx, z, x, y, { size }) => { ctx.strokeRect(0, 0, size, size); }, { opacity: 0.5 });
+
+map.setGoogleBase({ session, key, type: 'satellite', onFail: () => map.setGoogleBase(null) });   // Google's own tiles
+sMap.useThree(THREE, GLTFLoader);                                  // once, for 3D models
+map.addModels('vans', vehicles, { model: '/models/van.glb', size: 1, heading: { property: 'bearing' } });
+
+sMap.geo.distance([-79.38, 43.65], [-73.57, 45.5]);               // metres
+sMap.geo.pointInPolygon([lng, lat], zone.geometry);               // holes and multi-polygons
+sMap.geo.nearestPointOnLine(route.geometry, [lng, lat]);          // { point, distance, index, along }
+sMap.geo.decodePolyline(shape, 6);                                // [[lng, lat], …]
+```
+
 ## Plan editor: editing routes on the map
 
 `map.planEditor(options)` lets a person edit a plan of routes on the map: drag a stop within its route or onto another

package/dist/SOURCE.json

@@ -1,15 +1,15 @@
 {
-  "sdkVersion": "1.1.7",
+  "sdkVersion": "1.2.1",
   "engine": "maplibre-gl 6.16.0",
   "files": {
-    "smap.js": "1e7ba1266c67f860e74a2956521d55f49ea5771e0b1cfa832014433ea0554d25",
-    "smap.css": "d82adcd1b8e2b5d1a6ebe0ee648bc24eb84471bc956e3c8ac3cc7dc1f447d96f",
-    "smap-client.js": "f845c1d52a6f13bfb7f85cf8690e70320b09278b203b9e6a2cc874eed734eb10",
+    "smap.js": "bbce8821ec3564f5fc7498b0e7973636e98650e956d94a51a2dbd2259b71b89b",
+    "smap.css": "9bc4b14821de97da199e6af4f18541eeaf53a2ae91e5831e7224f57fe6b77660",
+    "smap-client.js": "5c769f3f9e4e82d3e7c25bfbd8b91f85f106161f65328fe6eaf19eab6561e897",
     "smap-client.d.ts": "5f0df11bf60c5a9ced34522a284de81260c27871678ab772f16da9ccf6883f58",
-    "smap.mjs": "ff3859691bfaf62d672ec6991eeda530be3316b22413d85c09a4adb7e11529cb",
-    "smap.cjs": "74c72a1504a0023d1b3d2613aac1527bc20676a7002c909715e60f798182b5c8",
-    "smap-client.cjs": "c1d143a0a9ac8a4cf1abdc7c2c82aec0d063bc51188e3eeb572dc48497475ef3",
-    "smap-client.mjs": "69d3e44f0d3fd39c3edbd8be6e66d4ddb625795f356a583dfeea610025cb7bd5",
+    "smap.mjs": "8edb30186a60969440415b75f6b14b04eea317dc83637dc49e1757ded0c9b0de",
+    "smap.cjs": "5bfc4ff01ed19e861ffde2b908f5509c774912fe4d305c6f8269cb4d9f7eeb69",
+    "smap-client.cjs": "13a379343810b63bdaa060499d63844e133d28c00649811dcfe107b5dfbabb53",
+    "smap-client.mjs": "58f6aa8cb2cec09569606b088247b0e7803cdf225d5ceb733ae3115572a36241",
     "smap-client.d.cts": "e0fe4eb54cd66b831116082f42bd2f7de260f9f12a2741f4004f8cf10c252116",
     "smap-client.d.mts": "96830d316ddb33b4ff8edb8b6f810337479636114f75c4170d95038ffda74103",
     "vendor-licenses.txt": "ee5fc05a0677eaf69601d2c7db0d9ecd6cc27c3abc1d0733bc9ed34707cf8ef2"

package/dist/smap-client.cjs

@@ -1,5 +1,5 @@
 /* Generated by js/build.mjs from js/src (see SOURCE.json). Do not edit. */
-/*! sMap JS client 1.1.7 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.2.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
 /*
  * Runs wherever `fetch` exists: browsers, Node.js 18+, workers; elsewhere (mini programs, older runtimes) pass your
  * own `fetch`. UMD: `window.SMapClient`, `require('smap-client')`, or an AMD module.
@@ -19,7 +19,7 @@
 }(typeof self !== 'undefined' ? self : this, function () {
   'use strict';
 
-  var VERSION = '1.1.7';
+  var VERSION = '1.2.1';
   var NODE_TTL = 3600 * 1000;          // the measured order
   var KNOWN_TTL = 30 * 86400 * 1000;   // the last node list received, used when none can be read
 

package/dist/smap-client.js

@@ -1,4 +1,4 @@
-/*! sMap JS client 1.1.7 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.2.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
 /*
  * Runs wherever `fetch` exists: browsers, Node.js 18+, workers; elsewhere (mini programs, older runtimes) pass your
  * own `fetch`. UMD: `window.SMapClient`, `require('smap-client')`, or an AMD module.
@@ -18,7 +18,7 @@
 }(typeof self !== 'undefined' ? self : this, function () {
   'use strict';
 
-  var VERSION = '1.1.7';
+  var VERSION = '1.2.1';
   var NODE_TTL = 3600 * 1000;          // the measured order
   var KNOWN_TTL = 30 * 86400 * 1000;   // the last node list received, used when none can be read
 

package/dist/smap-client.mjs

@@ -1,7 +1,7 @@
 /* Generated by js/build.mjs from js/src (see SOURCE.json). Do not edit. */
 var smapClientModule = { exports: {} };
 (function (module, exports, define) {
-/*! sMap JS client 1.1.7 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.2.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
 /*
  * Runs wherever `fetch` exists: browsers, Node.js 18+, workers; elsewhere (mini programs, older runtimes) pass your
  * own `fetch`. UMD: `window.SMapClient`, `require('smap-client')`, or an AMD module.
@@ -21,7 +21,7 @@ var smapClientModule = { exports: {} };
 }(typeof self !== 'undefined' ? self : this, function () {
   'use strict';
 
-  var VERSION = '1.1.7';
+  var VERSION = '1.2.1';
   var NODE_TTL = 3600 * 1000;          // the measured order
   var KNOWN_TTL = 30 * 86400 * 1000;   // the last node list received, used when none can be read