@superrouteca/smap 1.0.1 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.0.5 — 2026-10-27
+
+- Auto Zoom has a switch: the map option `autoZoom` and `map.setAutoZoom(on)`. In 3D, W / S tilt and A / D turn the view (`keyboard3D`).
+- Auto Zoom, pins piled up under a click: the map zooms in around it so they come apart; close up, or for pins at one spot, a chooser lists them and opens the one picked (`overlap`). Marker `opacity`; a clicked pin stays in front while its popup is open.
+- A pin's popup opens just above the pin at its current size, and the map pans to show it whole (`autoPan`). Overlapping pins: the one under the pointer comes to the front, as on Superroute's route map (`hoverRaise`, on by default).
+- Markers take `scale`: the pin, its number and its badge are sized together, for example smaller at a low zoom.
+- Markers take `textMinzoom` and `badgeMinzoom`: numbers and badges appear only from that zoom on, so an overview of
+  thousands of stops stays readable.
+- Popups made for many markers: one popup per map (opening another closes the one before), a point's popup opens at
+  the point, and only the top feature under a click opens. Nothing runs for a feature until its popup opens.
+- `popupTemplate('<b>{name}</b><br>{address}')` builds a popup from feature properties, HTML-escaped; the fast and
+  safe choice for large layers.
+- A popup may be a promise of HTML or a DOM node: a loading state shows meanwhile (`popupLoading`), an answer that
+  arrives after another popup opened is dropped, and a failure closes the popup and is reported as the map's `error`
+  event.
+- Popup options per layer (`popupOptions`) over map defaults (`popup` when creating the map): `className`, `maxWidth`,
+  `minWidth`, `offset`, `anchor`, `closeButton`, `closeOnClick`, `focusAfterOpen`.
+- Popups are styled with CSS variables (`--smap-popup-bg`, `--smap-popup-color`, `--smap-popup-radius`,
+  `--smap-popup-padding`, `--smap-popup-shadow`, `--smap-popup-font-size`, `--smap-popup-width`); dark colours on the
+  dark and black schemes.
+- `map.openPopup(position, content, options)` and `map.closePopup()`.
+- Route-map pins on the GPU (`marker` on `addPoints`): the pin of Superroute's route map (or a circle) with a fill and
+  a border colour, a number and a red count badge, each set per feature from a property, a constant or an expression.
+  Each distinct pin, number and badge is drawn once, when a feature first shows it, so tens of thousands of stops stay
+  smooth.
+- Route lines like Superroute's route map: a colour per feature, `casing`, `shadow` and direction `arrows`.
+
+## 1.0.2 — 2026-10-27
+
+- A layer takes a bare GeoJSON geometry as well (`addLines('route', { type: 'LineString', coordinates })`, a Polygon, a
+  Point, …): it is drawn as one feature. Before, such a layer stayed empty.
+
 ## 1.0.1 — 2026-10-27
 
 - Every map shows a small sMap badge (the sMap icon and name on a semi-transparent pill that reads on all five colour

package/README.md

@@ -10,7 +10,7 @@ areas drawn on the GPU (hundreds of thousands of points, clustered or not), 3D b
 renew themselves. Also the JS client (no map view) for servers and workers: tokens, the nearest node, styles, tiles
 and raw reads.
 
-- Version 1.0.1, MIT licence (see `LICENSE` at the repository root)
+- Version 1.0.5, MIT licence (see `LICENSE` at the repository root)
 - Works with bundlers (Vite, webpack, Next.js and others): ES module and CommonJS entry points with types
 - Nothing else to install: the map renderer is bundled in the package
 - Importing is safe on a server; a map is created in the browser only
@@ -57,9 +57,6 @@ map.setBuildings3D(true);
 map.fitLayer('stops');
 ```
 
-A `popup` option returns an HTML string, which is inserted as it is and never sanitized (escape any feature data you
-put in it), or a DOM node.
-
 `setStyle()` and `setLanguage()` keep your layers. Other calls: `setData`, `setVisible`, `removeLayer`, `layers`,
 `flyTo`, `setProjection`, `on` / `off` / `once`, `remove`. `map.engine` is the renderer's own map for anything the
 SDK does not wrap, and `getEngine()` gives the renderer itself.
@@ -67,6 +64,141 @@ 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.
 
+## 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
+one before. A point's popup opens at the point, a line's or area's where it was clicked, and only the top feature
+under the click opens.
+
+```js
+import { Map, popupTemplate } from '@superrouteca/smap';   // browser build: sMap.popupTemplate
+
+map.addPoints('stops', stops, {
+  icon: '/img/stop.png',
+  popup: popupTemplate('<b>{name}</b><br>{address}'),
+  popupOptions: { className: 'stop-popup', maxWidth: 280 },
+});
+```
+
+**Templates.** `popupTemplate(template)` replaces every `{name}` with the feature's property of that name,
+HTML-escaped (empty when the feature has none). The template is compiled once, and nothing runs for a feature until
+its popup opens, so a layer of tens of thousands of markers costs nothing extra. It is the recommended popup for
+large layers.
+
+**Your own function.** `popup(properties, feature)` may return:
+
+- an HTML string: inserted as it is and never sanitized, so it must be trusted (escape any feature data you put in
+  it, or use `popupTemplate`);
+- a DOM node, inserted as it is;
+- a promise of either, for content fetched when the popup opens. The loading state shows meanwhile (`popupLoading`,
+  an HTML string or a DOM node; three pulsing dots by default). An answer that arrives after another popup opened is
+  dropped; a failure closes the popup and is reported as the map's `error` event (`map.on('error', …)`);
+- nothing (`null`, `false`, `''`): no popup.
+
+```js
+map.addPoints('orders', orders, {
+  popup: async (p) => {
+    const order = await (await fetch(`/api/orders/${p.id}`)).json();
+    return popupTemplate('<b>{number}</b><br>{status}')(order);
+  },
+});
+```
+
+**Options.** `popupOptions` on a layer is merged over the map's defaults, given as `popup` when the map is created:
+
+| Option | Meaning |
+|---|---|
+| `className` | classes added beside `smap-popup` |
+| `maxWidth`, `minWidth` | pixels or a CSS length (`maxWidth` is 240px by default) |
+| `offset` | distance from the position in pixels (default 12) |
+| `anchor` | the side that points at the position (`top`, `bottom-left`, …); chosen to fit by default |
+| `closeButton` | the close button (default true) |
+| `closeOnClick` | a click on the map closes the popup (default true) |
+| `focusAfterOpen` | focus moves into the popup (default true) |
+
+```js
+const map = new Map({ container: 'map', popup: { maxWidth: 320, closeButton: false }, popupLoading: '<span>…</span>' });
+```
+
+**Styling.** The popup's element has the class `smap-popup` (plus your `className`). Set these CSS variables on the
+popup's class, on the map's element or on the page; nothing else needs overriding:
+
+```css
+.stop-popup {
+  --smap-popup-bg: #0f172a;
+  --smap-popup-color: #f8fafc;
+  --smap-popup-radius: 12px;
+  --smap-popup-padding: 12px 14px;
+  --smap-popup-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  --smap-popup-font-size: 14px;
+  --smap-popup-width: 260px;
+}
+```
+
+The tip follows the background. On the `dark` and `black` schemes the defaults are dark (the map's element carries
+`smap-style-<scheme>`).
+
+**From code.** `map.openPopup([lng, lat], content, options)` opens the map's popup with the same kinds of content
+(and `options.loading`); `map.closePopup()` closes it.
+
+## 3D view from the keyboard
+
+In 3D (3D buildings on, or the map tilted) W / S tilt the view and A / D turn it while the map has focus; Shift
+takes bigger steps. `keyboard3D: false` turns it off.
+
+## Route maps: pins, numbers and route lines
+
+Points can be drawn as the pins of Superroute's route map (`marker`), and lines with a casing, a shadow and direction
+arrows. Everything is drawn on the GPU, so tens of thousands of stops stay smooth: each distinct pin (a colour pair),
+number and badge is drawn once, the first time a feature shows it.
+
+A value that can differ per feature is a constant (`'#e6194b'`), a feature property (`{ property: 'status_color' }`,
+with `default` for features without it) or an engine expression (an array such as `['get', 'color']`).
+
+**`marker`** on `addPoints`:
+
+| Option | Meaning |
+|---|---|
+| `shape` | `'pin'` (default; the tip is at the position) or `'circle'` |
+| `fill` | inside colour (default white) |
+| `border` | border colour (default the layer's `color`) |
+| `borderWidth` | pixels (default 3) |
+| `size` | width in pixels (default 32) |
+| `text` | the text in the pin, e.g. the stop number (none when empty) |
+| `textColor` | default white |
+| `badge` | a red count at the upper right, shown when more than 1 |
+| `opacity` | of the pin, its number and its badge together (e.g. settled stops paler) |
+| `overlap` | Auto Zoom for this layer (map option `autoZoom`, `map.setAutoZoom(on)`, on by default): pins piled up under a click: 4 or more within 12 px zoom the map in by 2; close up (zoom 17) or at one spot a chooser lists them, `label(properties)` names each row; `false` turns it off |
+| `hoverRaise` | the pin under the pointer comes to the front, so overlapping pins can be read and clicked (default `true`) |
+| `scale` | size factor of the pin, its number and its badge together; a number or an expression of the zoom, e.g. `['interpolate', ['linear'], ['zoom'], 9, 0.5, 14, 1]` |
+| `textMinzoom`, `badgeMinzoom` | show numbers / badges only from this zoom on, so an overview of many stops stays readable |
+
+**Lines** on `addLines`: `color` may be per feature; `casing` (`true`: white, 9 px), `shadow` (`true`: black, 7 px,
+opacity 0.3) and `arrows` (`true`: every 80 px, 14 px, in the line's colour; or `{ spacing, size, color, opacity }`)
+are drawn under, between and over the line.
+
+**The route map, as on Superroute** (one layer for all routes, one for all stops):
+
+```js
+map.addLines('routes', routes, {          // features with properties.color
+  color: { property: 'color' }, width: 5, opacity: 0.9,
+  casing: true, shadow: true, arrows: true,
+});
+map.addPoints('stops', stops, {           // {lng, lat, stop_number, status_color, route_color, orders, …}
+  marker: {
+    fill: { property: 'status_color' },
+    border: { property: 'route_color' },
+    text: { property: 'stop_number' },
+    badge: { property: 'orders' },
+  },
+  popup: popupTemplate('<b>{stop_number}</b> {address}'),
+  zIndex: 1,                              // stops over the routes
+});
+```
+
+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.
+
 ## Map keys and tokens
 
 - **Map key** (`apiKey: 'smk_…'`): created in the Superroute developer center, with the sites (and apps) it may be

package/dist/SOURCE.json

@@ -1,15 +1,15 @@
 {
-  "sdkVersion": "1.0.1",
+  "sdkVersion": "1.0.5",
   "engine": "maplibre-gl 6.16.0",
   "files": {
-    "smap.js": "b48a84d65d3937c122f3f67b6cead8b9348913e2447782cca2a3f7a6c5d48ae7",
-    "smap.css": "558e15e5dfb3676e90f4cdfdb277c58f78c3d8de5527c8df1707f6c572241668",
-    "smap-client.js": "8029946bec62ce4806e47e2324f3020b3d049b0a73bb98352cdd307474ae776c",
+    "smap.js": "3b8d6eaa6a2ddd6fb14b1465a9c6ef46a09d550093bb567b613fda3b26fa1fe5",
+    "smap.css": "5e3bdcb00b8fc8805f545b76cdeea5e783c89984f48ec2fee66c4319af4ada0b",
+    "smap-client.js": "1ae5f49b4be515efa69570a110b862ac8f325a6b45a9438a5c8011fa9278f598",
     "smap-client.d.ts": "ad701612630a290b2dc0e49250ae25cea965ecb3a145c016bb462cd30f108cf7",
-    "smap.mjs": "b59530982e07703ce3e3ffeaea328f18a86855e99076e737ee41c4dbd186104d",
-    "smap.cjs": "22f7b7248f40d5436cb1cd4c865f06e1a38ab8f9beed96ec3828abf058549a71",
-    "smap-client.cjs": "9956892bea8d367c1d278de11c3850293ad7d963d74d9692ce7194f6deff6f15",
-    "smap-client.mjs": "176a70faf2b4ecb3f998e5823202097b2a9d1bce546c41f6411f2567e2f7e5ae",
+    "smap.mjs": "7ea12152fa21a7d3e2c235646998cd8e36fded1db808945289123dc19c11424e",
+    "smap.cjs": "668b85f95674a22b7072566ec91f499de3623cddb10afb28aa32c528a39313da",
+    "smap-client.cjs": "6c54aa4a7676c26e7c4569203afb19f6c20233dc96f3e1400087b035f4e7d4f0",
+    "smap-client.mjs": "207bcb78118603359d73aecbea3f422d101b729f5e8462c1bb05225ad886d1f5",
     "smap-client.d.cts": "80b96f5a907caf6295ca073816dc526e8d285f22670c809adaab5242a018e686",
     "smap-client.d.mts": "a66834cab868a6a0eaf943c1b185a236916cb00ecf32a871f972ab3213eddeba",
     "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.0.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.0.5 — 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.0.1';
+  var VERSION = '1.0.5';
   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.0.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.0.5 — 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.0.1';
+  var VERSION = '1.0.5';
   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.0.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.0.5 — 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.0.1';
+  var VERSION = '1.0.5';
   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