@superrouteca/smap 1.1.2 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.1.5 — 2026-10-28
+
+- Map tools: the controls and panels floating on a map can be shown and hidden one by one or all at once. Register
+  each with `addTool` — a page element (an orders list, a legend, a search box), an engine control, or a zoom, locate,
+  full screen or scale control the SDK makes — and switch them with `setToolVisible` and `setToolsVisible`. A tools
+  control (one button, top right by default) lists every tool with *Show all* and *Hide all*. A hidden tool keeps its
+  state and comes back as it was. The map data credit and the sMap badge always stay. The starting state is given in
+  `tools.hidden` and every change is reported to `onToolsChange`, so the page decides whether and where to keep it.
+  A map without tools is unchanged.
+
 ## 1.1.2 — 2026-10-27
 
 - The version follows the shared 1.1.2 release; no change of its own.

package/README.md

@@ -201,6 +201,36 @@ 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.
 
+## Map tools: showing and hiding controls and panels
+
+Register what floats on the map, and the map gets a tools control (one button, top right) that shows or hides each
+tool, plus *Show all* and *Hide all*:
+
+```js
+const map = new sMap.Map({ container: 'map', style: 'light', tools: { hidden: saved.hidden } });
+map.addTool('zoom', 'navigation', { options: { showCompass: false } });   // made by the SDK
+map.addTool('fullscreen', 'fullscreen');
+map.addTool('legend', document.getElementById('legend'), { label: 'Legend', position: 'bottom-left' });
+map.addTool('orders', document.getElementById('orders'), { label: 'Orders list', position: 'none' }); // stays in the page
+map.onToolsChange((e) => save({ hidden: e.hidden }));
+
+map.setToolVisible('legend', false);
+map.setToolsVisible(true);
+map.tools(); // [{ id: 'zoom', label: 'Zoom', visible: true }, …]
+```
+
+- A tool is a page element, an engine control (`onAdd` / `onRemove`), or a kind the SDK makes: `navigation`,
+  `geolocate`, `fullscreen`, `scale`, and the mobile SDKs' names `zoom` (zoom buttons only), `compass` and `locate`. `position` is a corner, or `'none'` for an element that stays where the page put
+  it. Ids are 1–64 letters, digits, `-`, `_` or `.`; adding an id again replaces the first.
+- A hidden tool is not drawn and keeps its state (an open list stays open, typed text stays). Hiding a switch does not
+  turn off what it switches.
+- The map data credit, the sMap badge and the tools control are never tools: *Hide all* leaves them.
+- `tools.control: false` leaves the tools control out (make your own buttons with the calls above);
+  `tools.labels: { button, showAll, hideAll }` translates it.
+- The SDK keeps no state: give the starting state in `tools.hidden` and keep `onToolsChange`'s `hidden` where you
+  like (the page's storage, your server).
+- The tools control joins the map with the first tool; a map without tools is unchanged.
+
 ## Style layers and sources
 
 Sources and layers of the Style Specification v8 are passed to the map as they are, so a layer copied from Mapbox

package/dist/SOURCE.json

@@ -1,15 +1,15 @@
 {
-  "sdkVersion": "1.1.2",
+  "sdkVersion": "1.1.5",
   "engine": "maplibre-gl 6.16.0",
   "files": {
-    "smap.js": "78b2a10a4b7d5843c427d23d68f935a3917faadd62749a25f42f523274774a7b",
-    "smap.css": "5e3bdcb00b8fc8805f545b76cdeea5e783c89984f48ec2fee66c4319af4ada0b",
-    "smap-client.js": "02f6359fa4d359f205ce45e597f32f068fdb04448a2200274b166b228cd4eba8",
+    "smap.js": "d8658ace857ab90b2f2f3dc0af163104d3231e11c119af4a12a0d88b66f6ecae",
+    "smap.css": "acb9e11dca261a1f827e1d073e47e13b112b986ee744a712107ff83276d327e7",
+    "smap-client.js": "d101ab143691d1973399fb7b45fe396178dc96471048923077e57ce76b413a4a",
     "smap-client.d.ts": "5f0df11bf60c5a9ced34522a284de81260c27871678ab772f16da9ccf6883f58",
-    "smap.mjs": "54a194d152497fd5730dfb55c2588610690d218d98a4c9ee47e065b4f709d612",
-    "smap.cjs": "9d29085aebf24e10e701574e56459afa4758bcc4f04ea2ff99e4fecc2adc8a5b",
-    "smap-client.cjs": "603d5603bce2e7d5912123d65c51ec83cd6b4db266a8c6b47a68b4a893621a6a",
-    "smap-client.mjs": "6d4707ed18d301c24913f3b1d49c88401ff20da5425464b619b94aee42107cbf",
+    "smap.mjs": "db3e14cce3abb2f2dfdd17578de122ed7a633f8f885e1f5765dfbb92cf862e87",
+    "smap.cjs": "34ec49173c1e97b88510ffcfdf1b2db30fcfe28ccef5aa1e8e311e52f459b994",
+    "smap-client.cjs": "45d68a640f686d93e10c98468ed0c384bbc696da51193253217f6476d19ac6ed",
+    "smap-client.mjs": "45b241183a128671d0422c3684f5987cc1d1e1223fc1d95bcba16ba955c58862",
     "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.2 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.1.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.1.2';
+  var VERSION = '1.1.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.1.2 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.1.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.1.2';
+  var VERSION = '1.1.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.1.2 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*! sMap JS client 1.1.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.1.2';
+  var VERSION = '1.1.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.cjs

@@ -1,6 +1,6 @@
 /* Generated by js/build.mjs from js/src (see SOURCE.json). Do not edit. */
 'use strict';
-/*! sMap Web SDK 1.1.2. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
+/*! sMap Web SDK 1.1.5. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
 
 var smapCore = null;
 function smapCreateEngine() {
@@ -28353,7 +28353,7 @@ function smapCreateSdk(engine, interop) {
 })(typeof self !== 'undefined' ? self : this, function (engine, interop) {
   'use strict';
 
-  var VERSION = '1.1.2';
+  var VERSION = '1.1.5';
   var FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
   var BASEMAP_SOURCE = 'basemap';
   var BUILDINGS_LAYER = 'smap-buildings-3d';
@@ -28806,11 +28806,20 @@ function smapCreateSdk(engine, interop) {
     // True between a style's load and the next style change. The engine's own isStyleLoaded() turns false while any
     // source is loading data, which would leave layers added meanwhile waiting for a load that never comes.
     this._styleReady = false;
+    // Map tools (M49-M57): the controls and panels floating on the map that the caller registered, in the order added.
+    var toolOptions = options.tools || {};
+    this._tools = [];
+    this._toolsHidden = {};
+    (toolOptions.hidden || []).forEach(function (id) { this._toolsHidden[id] = true; }, this);
+    this._toolsControlAt = toolOptions.control === undefined ? 'top-right' : toolOptions.control;
+    this._toolsLabels = toolOptions.labels || {};
+    this._toolsControl = null;
+    this._toolHandlers = [];
 
     var self = this;
     var engineOptions = {};
     for (var k in options) {
-      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D'].indexOf(k) < 0) {
+      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D', 'tools'].indexOf(k) < 0) {
         engineOptions[k] = options[k];
       }
     }
@@ -28843,6 +28852,7 @@ function smapCreateSdk(engine, interop) {
         self.engine.addControl(badge, 'bottom-right');
         badge._place();
       }
+      self._mountTools();
       self.engine.on('style.load', function () { self._styleReady = true; self._restore(); });
       self._keyboard3D();
       // One click handler for every layer's popup: the engine's hit test over those layers, the top feature opens.
@@ -29326,6 +29336,249 @@ function smapCreateSdk(engine, interop) {
   SMap.prototype.flyTo = function (o) { this.engine.flyTo(o); return this; };
   SMap.prototype.remove = function () { clearTimeout(this._refreshTimer); if (this.engine) { this.engine.remove(); } };
 
+  // ------------------------------------------------------------------ map tools (M49-M57)
+
+  var TOOL_ID = /^[A-Za-z0-9._-]{1,64}$/;
+  var TOOL_CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+  // The tools the SDK makes by name: the engine control, its English label (the caller may give another) and corner.
+  var TOOL_KINDS = {
+    navigation: { control: 'NavigationControl', label: 'Zoom', position: 'top-left' },
+    geolocate: { control: 'GeolocateControl', label: 'Locate', position: 'top-left' },
+    fullscreen: { control: 'FullscreenControl', label: 'Full screen', position: 'top-left' },
+    scale: { control: 'ScaleControl', label: 'Scale', position: 'bottom-left' },
+    // The mobile SDKs' names for the same controls, so one tool list serves every platform.
+    zoom: { control: 'NavigationControl', label: 'Zoom', position: 'top-left', options: { showCompass: false } },
+    compass: { control: 'NavigationControl', label: 'Compass', position: 'top-left', options: { showZoom: false } },
+    locate: { control: 'GeolocateControl', label: 'Locate', position: 'top-left' },
+  };
+  var TOOLS_ICON = '<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true" focusable="false" fill="none" ' +
+    'stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 7h10M18 7h2M4 17h2M10 17h10"/>' +
+    '<circle cx="16" cy="7" r="2"/><circle cx="8" cy="17" r="2"/></svg>';
+  var TOOLS_TEXT = { button: 'Map tools', showAll: 'Show all', hideAll: 'Hide all' };
+
+  function isElement(v) { return !!v && typeof v === 'object' && v.nodeType === 1; }
+
+  // An engine control whose element the SDK can find again to show or hide it: the control's own onAdd, its element kept.
+  function toolControl(tool, inner) {
+    return {
+      onAdd: function (m) { tool.el = inner.onAdd(m); return tool.el; },
+      onRemove: function (m) { if (inner.onRemove) { inner.onRemove(m); } else if (tool.el && tool.el.parentNode) { tool.el.parentNode.removeChild(tool.el); } tool.el = null; },
+      getDefaultPosition: function () { return tool.position; },
+    };
+  }
+
+  // A page element placed in a corner of the map: it moves into the corner and back where it was when removed.
+  function elementControl(tool, element) {
+    var home = null;
+    var next = null;
+    return {
+      onAdd: function () {
+        home = element.parentNode;
+        next = element.nextSibling;
+        element.classList.add('maplibregl-ctrl', 'smap-tool');
+        tool.el = element;
+        return element;
+      },
+      onRemove: function () {
+        element.classList.remove('maplibregl-ctrl', 'smap-tool');
+        if (home) { home.insertBefore(element, next && next.parentNode === home ? next : null); } else if (element.parentNode) { element.parentNode.removeChild(element); }
+        tool.el = null;
+      },
+      getDefaultPosition: function () { return tool.position; },
+    };
+  }
+
+  /**
+   * Registers a tool floating on the map, shown or hidden by setToolVisible / setToolsVisible and the tools control.
+   *   map.addTool('legend', document.getElementById('legend'), { label: 'Legend', position: 'bottom-left' })
+   *   map.addTool('zoom', 'navigation', { options: { showCompass: false } })
+   * @param {string} id  1-64 letters, digits, '-', '_', '.'; adding an id again replaces the first
+   * @param {Element|Object|string} target  a page element, an engine control (onAdd / onRemove), or a kind the SDK
+   *        makes: 'navigation', 'geolocate', 'fullscreen', 'scale', or the mobile SDKs' 'zoom' (navigation without the
+   *        compass), 'compass' (without the zoom buttons) and 'locate' (geolocate)
+   * @param {Object} [o]  label (shown on its button), position ('top-left', 'top-right', 'bottom-left', 'bottom-right',
+   *        or 'none': an element stays where the page put it), options (of a kind's engine control)
+   */
+  SMap.prototype.addTool = function (id, target, o) {
+    o = o || {};
+    if (typeof id !== 'string' || !TOOL_ID.test(id)) { throw new Error('sMap: a tool id is 1-64 letters, digits, "-", "_" or "."'); }
+    var kind = typeof target === 'string' ? TOOL_KINDS[target] : null;
+    if (typeof target === 'string') {
+      if (!kind) { throw new Error('sMap: unknown tool kind "' + target + '"'); }
+      if (!engine[kind.control]) { throw new Error('sMap: the rendering engine has no ' + kind.control); }
+    } else if (!isElement(target) && !(target && typeof target.onAdd === 'function')) {
+      throw new Error('sMap: a tool is an element, an engine control or a tool kind');
+    }
+    var position = o.position || (kind ? kind.position : (isElement(target) ? (target.parentNode ? 'none' : 'top-left') : 'top-right'));
+    if (position !== 'none' && TOOL_CORNERS.indexOf(position) < 0) { throw new Error('sMap: unknown tool position "' + position + '"'); }
+    if (position === 'none' && !isElement(target)) { throw new Error('sMap: only an element may stay out of the map\'s corners'); }
+    if (this._toolIndex(id) >= 0) { this.removeTool(id); }
+    var tool = { id: id, label: String(o.label || (kind ? kind.label : id)), position: position, el: null, control: null };
+    if (kind) { tool.control = toolControl(tool, new engine[kind.control](o.options || kind.options)); }
+    else if (!isElement(target)) { tool.control = toolControl(tool, target); }
+    else if (position !== 'none') { tool.control = elementControl(tool, target); }
+    else { tool.el = target; }
+    this._tools.push(tool);
+    if (this.engine) { this._mountTool(tool); }
+    this._renderToolsControl();
+    return this;
+  };
+
+  /** Removes a tool: an engine control leaves the map, a page element is shown again where the page put it. */
+  SMap.prototype.removeTool = function (id) {
+    var i = this._toolIndex(id);
+    if (i < 0) { return this; }
+    var tool = this._tools[i];
+    this._tools.splice(i, 1);
+    if (tool.el) { tool.el.classList.remove('smap-tool-hidden'); }
+    if (tool.control && this.engine && tool.mounted) { this.engine.removeControl(tool.control); }
+    this._renderToolsControl();
+    return this;
+  };
+
+  /** Shows or hides one tool. A hidden tool keeps its state and shows again as it was (M57). */
+  SMap.prototype.setToolVisible = function (id, visible) {
+    var tool = this._tools[this._toolIndex(id)];
+    if (!tool || this._toolVisible(tool) === !!visible) { return this; }
+    this._setHidden(tool, !visible);
+    this._renderToolsControl();
+    this._toolsChanged(id);
+    return this;
+  };
+
+  /** Shows or hides every tool. The map data credit, the sMap badge and the tools control always stay (M51). */
+  SMap.prototype.setToolsVisible = function (visible) {
+    var changed = false;
+    this._tools.forEach(function (tool) {
+      if (this._toolVisible(tool) !== !!visible) { this._setHidden(tool, !visible); changed = true; }
+    }, this);
+    if (changed) { this._renderToolsControl(); this._toolsChanged(null); }
+    return this;
+  };
+
+  /** The tools in the order added: [{ id, label, visible }]. */
+  SMap.prototype.tools = function () {
+    return this._tools.map(function (tool) { return { id: tool.id, label: tool.label, visible: this._toolVisible(tool) }; }, this);
+  };
+
+  /** Calls handler({ hidden: [ids], changed: id | null }) after every change; the SDK keeps no state itself (M53). */
+  SMap.prototype.onToolsChange = function (handler) { this._toolHandlers.push(handler); return this; };
+  SMap.prototype.offToolsChange = function (handler) {
+    this._toolHandlers = this._toolHandlers.filter(function (h) { return h !== handler; });
+    return this;
+  };
+
+  SMap.prototype._toolIndex = function (id) {
+    for (var i = 0; i < this._tools.length; i++) { if (this._tools[i].id === id) { return i; } }
+    return -1;
+  };
+  SMap.prototype._toolVisible = function (tool) { return !this._toolsHidden[tool.id]; };
+  SMap.prototype._setHidden = function (tool, hidden) {
+    if (hidden) { this._toolsHidden[tool.id] = true; } else { delete this._toolsHidden[tool.id]; }
+    if (tool.el) { tool.el.classList.toggle('smap-tool-hidden', hidden); }
+  };
+  SMap.prototype._toolsChanged = function (id) {
+    var hidden = this._tools.filter(function (t) { return !this._toolVisible(t); }, this).map(function (t) { return t.id; });
+    this._toolHandlers.slice().forEach(function (h) { h({ hidden: hidden, changed: id }); });
+  };
+
+  SMap.prototype._mountTool = function (tool) {
+    // The tools control joins the map with its first tool, so a map without tools is exactly as before.
+    if (this._toolsControlAt && !this._toolsControl && this.engine.addControl) {
+      this._toolsControl = toolsControl(this);
+      this.engine.addControl(this._toolsControl, this._toolsControlAt);
+    }
+    if (tool.control && this.engine.addControl) { this.engine.addControl(tool.control, tool.position); tool.mounted = true; }
+    if (tool.el) { tool.el.classList.toggle('smap-tool-hidden', !this._toolVisible(tool)); }
+  };
+
+  // Called once the engine exists: every tool registered before it.
+  SMap.prototype._mountTools = function () {
+    this._tools.forEach(function (tool) { this._mountTool(tool); }, this);
+    this._renderToolsControl();
+  };
+  SMap.prototype._renderToolsControl = function () { if (this._toolsControl) { this._toolsControl._render(); } };
+
+  // The tools control: one button that opens a panel with one toggle per tool (pressed = shown), Show all and Hide all.
+  // It is not a tool and is never hidden; it joins the map with the first tool and is not drawn while none is left.
+  function toolsControl(map) {
+    var el = null;
+    var button = null;
+    var panel = null;
+    var drawn = null;
+    var text = {};
+    Object.keys(TOOLS_TEXT).forEach(function (k) { text[k] = map._toolsLabels[k] || TOOLS_TEXT[k]; });
+    function open(on) {
+      panel.hidden = !on;
+      button.setAttribute('aria-expanded', on ? 'true' : 'false');
+    }
+    function close() { if (panel && !panel.hidden) { open(false); } }
+    function key(e) { if (e.key === 'Escape' && !panel.hidden) { open(false); button.focus(); } }
+    function make(doc, tag, className, label) {
+      var b = doc.createElement(tag);
+      b.className = className;
+      if (tag === 'button') { b.type = 'button'; }
+      if (label !== undefined) { b.textContent = label; }
+      return b;
+    }
+    var control = {
+      onAdd: function (m) {
+        var doc = m.getContainer().ownerDocument;
+        el = make(doc, 'div', 'maplibregl-ctrl maplibregl-ctrl-group smap-tools');
+        button = make(doc, 'button', 'smap-tools-button');
+        button.innerHTML = TOOLS_ICON;
+        button.title = text.button;
+        button.setAttribute('aria-label', text.button);
+        button.setAttribute('aria-haspopup', 'true');
+        button.addEventListener('click', function () { open(panel.hidden); });
+        panel = make(doc, 'div', 'smap-tools-panel');
+        panel.setAttribute('role', 'group');
+        panel.setAttribute('aria-label', text.button);
+        el.appendChild(button);
+        el.appendChild(panel);
+        el.addEventListener('keydown', key);
+        open(false);
+        m.on('click', close);
+        return el;
+      },
+      onRemove: function (m) {
+        m.off('click', close);
+        if (el && el.parentNode) { el.parentNode.removeChild(el); }
+        el = null;
+        drawn = null;
+      },
+      _render: function () {
+        if (!el) { return; }
+        var doc = el.ownerDocument;
+        el.classList.toggle('smap-tools-empty', map._tools.length === 0);
+        // The same tools as last time: only the pressed states change, so a toggle keeps the keyboard focus.
+        var signature = JSON.stringify(map._tools.map(function (t) { return [t.id, t.label]; }));
+        if (signature === drawn) {
+          map._tools.forEach(function (tool, i) { panel.children[i].setAttribute('aria-pressed', map._toolVisible(tool) ? 'true' : 'false'); });
+          return;
+        }
+        drawn = signature;
+        while (panel.firstChild) { panel.removeChild(panel.firstChild); }
+        map._tools.forEach(function (tool) {
+          var item = make(doc, 'button', 'smap-tools-item', tool.label);
+          item.setAttribute('aria-pressed', map._toolVisible(tool) ? 'true' : 'false');
+          item.setAttribute('data-tool', tool.id);
+          item.addEventListener('click', function () { map.setToolVisible(tool.id, !map._toolVisible(tool)); });
+          panel.appendChild(item);
+        });
+        var all = make(doc, 'div', 'smap-tools-all');
+        var show = make(doc, 'button', 'smap-tools-show-all', text.showAll);
+        show.addEventListener('click', function () { map.setToolsVisible(true); });
+        var hide = make(doc, 'button', 'smap-tools-hide-all', text.hideAll);
+        hide.addEventListener('click', function () { map.setToolsVisible(false); });
+        all.appendChild(show);
+        all.appendChild(hide);
+        panel.appendChild(all);
+      },
+    };
+    return control;
+  }
+
   // ------------------------------------------------------------------ Style Specification sources and layers (M24)
 
   function clone(v) { return v === undefined ? undefined : JSON.parse(JSON.stringify(v)); }
@@ -30294,7 +30547,7 @@ function SMapMap(options) {
   SMapMap.prototype = core.Map.prototype;
   return new core.Map(options);
 }
-var smapVersion = "1.1.2";
+var smapVersion = "1.1.5";
 var smapStyles = ['light', 'white', 'grayscale', 'dark', 'black'];
 /** The bundled rendering engine, for anything the SDK does not wrap (loaded on the first call). */
 function smapGetEngine() { return smapLoad().engine; }

package/dist/smap.css

@@ -76,3 +76,32 @@
   padding: 0 4px; box-sizing: border-box; border: 2px solid; border-radius: 11px; color: #fff; font-size: 10px; font-weight: 700;
   text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); }
 .smap-chooser-label { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* Map tools (M49-M57). A hidden tool is not drawn; its corner closes up. */
+.smap-tool-hidden { display: none !important; }
+.maplibregl-ctrl.smap-tools.smap-tools-empty { display: none; }
+.smap-tools { position: relative; }
+.smap-tools .smap-tools-button { display: flex; align-items: center; justify-content: center; color: #1e293b; }
+.smap-tools .smap-tools-button[aria-expanded="true"] { color: #2563eb; }
+.smap-tools-panel {
+  position: absolute; top: 0; z-index: 3; display: flex; flex-direction: column; gap: 4px;
+  min-width: 170px; max-height: 60vmin; overflow-y: auto; padding: 8px; box-sizing: border-box;
+  border-radius: 8px; background: #ffffff; color: #1e293b; box-shadow: 0 2px 10px rgba(15, 23, 42, 0.18);
+  font: 12px/1.3 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+.smap-tools-panel[hidden] { display: none; }
+.maplibregl-ctrl-top-right .smap-tools-panel, .maplibregl-ctrl-bottom-right .smap-tools-panel { right: 36px; }
+.maplibregl-ctrl-top-left .smap-tools-panel, .maplibregl-ctrl-bottom-left .smap-tools-panel { left: 36px; }
+.maplibregl-ctrl-bottom-right .smap-tools-panel, .maplibregl-ctrl-bottom-left .smap-tools-panel { top: auto; bottom: 0; }
+.maplibregl-ctrl-group .smap-tools-panel button {
+  display: flex; align-items: center; width: 100%; height: auto; min-height: 28px; padding: 4px 8px; box-sizing: border-box;
+  border: 1px solid rgba(15, 23, 42, 0.15); border-radius: 6px; background: #ffffff; color: inherit;
+  font: inherit; text-align: left; white-space: nowrap; cursor: pointer;
+}
+.maplibregl-ctrl-group .smap-tools-panel button + button { border-top: 1px solid rgba(15, 23, 42, 0.15); }
+.maplibregl-ctrl-group .smap-tools-panel .smap-tools-item[aria-pressed="true"] { border-color: #2563eb; background: #2563eb; color: #ffffff; }
+.maplibregl-ctrl-group .smap-tools-panel button:focus-visible { outline: 2px solid #2563eb; outline-offset: 1px; }
+.smap-tools-all { display: flex; gap: 4px; margin-top: 4px; padding-top: 6px; border-top: 1px solid rgba(15, 23, 42, 0.12); }
+.maplibregl-ctrl-group .smap-tools-all button { justify-content: center; text-align: center; }
+.smap-style-dark .smap-tools-panel, .smap-style-black .smap-tools-panel { background: #1f2430; color: #e5e7eb; }
+.smap-style-dark .smap-tools-panel button, .smap-style-black .smap-tools-panel button { background: #1f2430; border-color: rgba(229, 231, 235, 0.2); }

package/dist/smap.js

@@ -1,4 +1,4 @@
-/*! sMap Web SDK 1.1.2. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
+/*! sMap Web SDK 1.1.5. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
 (function () {
 function smapCreateEngine() {
   var SMAP_BASE_URL = (typeof document !== 'undefined' && document.baseURI) || (typeof location !== 'undefined' && location.href) || 'about:blank';
@@ -28350,7 +28350,7 @@ function smapCreateSdk(engine, interop) {
 })(typeof self !== 'undefined' ? self : this, function (engine, interop) {
   'use strict';
 
-  var VERSION = '1.1.2';
+  var VERSION = '1.1.5';
   var FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
   var BASEMAP_SOURCE = 'basemap';
   var BUILDINGS_LAYER = 'smap-buildings-3d';
@@ -28803,11 +28803,20 @@ function smapCreateSdk(engine, interop) {
     // True between a style's load and the next style change. The engine's own isStyleLoaded() turns false while any
     // source is loading data, which would leave layers added meanwhile waiting for a load that never comes.
     this._styleReady = false;
+    // Map tools (M49-M57): the controls and panels floating on the map that the caller registered, in the order added.
+    var toolOptions = options.tools || {};
+    this._tools = [];
+    this._toolsHidden = {};
+    (toolOptions.hidden || []).forEach(function (id) { this._toolsHidden[id] = true; }, this);
+    this._toolsControlAt = toolOptions.control === undefined ? 'top-right' : toolOptions.control;
+    this._toolsLabels = toolOptions.labels || {};
+    this._toolsControl = null;
+    this._toolHandlers = [];
 
     var self = this;
     var engineOptions = {};
     for (var k in options) {
-      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D'].indexOf(k) < 0) {
+      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D', 'tools'].indexOf(k) < 0) {
         engineOptions[k] = options[k];
       }
     }
@@ -28840,6 +28849,7 @@ function smapCreateSdk(engine, interop) {
         self.engine.addControl(badge, 'bottom-right');
         badge._place();
       }
+      self._mountTools();
       self.engine.on('style.load', function () { self._styleReady = true; self._restore(); });
       self._keyboard3D();
       // One click handler for every layer's popup: the engine's hit test over those layers, the top feature opens.
@@ -29323,6 +29333,249 @@ function smapCreateSdk(engine, interop) {
   SMap.prototype.flyTo = function (o) { this.engine.flyTo(o); return this; };
   SMap.prototype.remove = function () { clearTimeout(this._refreshTimer); if (this.engine) { this.engine.remove(); } };
 
+  // ------------------------------------------------------------------ map tools (M49-M57)
+
+  var TOOL_ID = /^[A-Za-z0-9._-]{1,64}$/;
+  var TOOL_CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+  // The tools the SDK makes by name: the engine control, its English label (the caller may give another) and corner.
+  var TOOL_KINDS = {
+    navigation: { control: 'NavigationControl', label: 'Zoom', position: 'top-left' },
+    geolocate: { control: 'GeolocateControl', label: 'Locate', position: 'top-left' },
+    fullscreen: { control: 'FullscreenControl', label: 'Full screen', position: 'top-left' },
+    scale: { control: 'ScaleControl', label: 'Scale', position: 'bottom-left' },
+    // The mobile SDKs' names for the same controls, so one tool list serves every platform.
+    zoom: { control: 'NavigationControl', label: 'Zoom', position: 'top-left', options: { showCompass: false } },
+    compass: { control: 'NavigationControl', label: 'Compass', position: 'top-left', options: { showZoom: false } },
+    locate: { control: 'GeolocateControl', label: 'Locate', position: 'top-left' },
+  };
+  var TOOLS_ICON = '<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true" focusable="false" fill="none" ' +
+    'stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 7h10M18 7h2M4 17h2M10 17h10"/>' +
+    '<circle cx="16" cy="7" r="2"/><circle cx="8" cy="17" r="2"/></svg>';
+  var TOOLS_TEXT = { button: 'Map tools', showAll: 'Show all', hideAll: 'Hide all' };
+
+  function isElement(v) { return !!v && typeof v === 'object' && v.nodeType === 1; }
+
+  // An engine control whose element the SDK can find again to show or hide it: the control's own onAdd, its element kept.
+  function toolControl(tool, inner) {
+    return {
+      onAdd: function (m) { tool.el = inner.onAdd(m); return tool.el; },
+      onRemove: function (m) { if (inner.onRemove) { inner.onRemove(m); } else if (tool.el && tool.el.parentNode) { tool.el.parentNode.removeChild(tool.el); } tool.el = null; },
+      getDefaultPosition: function () { return tool.position; },
+    };
+  }
+
+  // A page element placed in a corner of the map: it moves into the corner and back where it was when removed.
+  function elementControl(tool, element) {
+    var home = null;
+    var next = null;
+    return {
+      onAdd: function () {
+        home = element.parentNode;
+        next = element.nextSibling;
+        element.classList.add('maplibregl-ctrl', 'smap-tool');
+        tool.el = element;
+        return element;
+      },
+      onRemove: function () {
+        element.classList.remove('maplibregl-ctrl', 'smap-tool');
+        if (home) { home.insertBefore(element, next && next.parentNode === home ? next : null); } else if (element.parentNode) { element.parentNode.removeChild(element); }
+        tool.el = null;
+      },
+      getDefaultPosition: function () { return tool.position; },
+    };
+  }
+
+  /**
+   * Registers a tool floating on the map, shown or hidden by setToolVisible / setToolsVisible and the tools control.
+   *   map.addTool('legend', document.getElementById('legend'), { label: 'Legend', position: 'bottom-left' })
+   *   map.addTool('zoom', 'navigation', { options: { showCompass: false } })
+   * @param {string} id  1-64 letters, digits, '-', '_', '.'; adding an id again replaces the first
+   * @param {Element|Object|string} target  a page element, an engine control (onAdd / onRemove), or a kind the SDK
+   *        makes: 'navigation', 'geolocate', 'fullscreen', 'scale', or the mobile SDKs' 'zoom' (navigation without the
+   *        compass), 'compass' (without the zoom buttons) and 'locate' (geolocate)
+   * @param {Object} [o]  label (shown on its button), position ('top-left', 'top-right', 'bottom-left', 'bottom-right',
+   *        or 'none': an element stays where the page put it), options (of a kind's engine control)
+   */
+  SMap.prototype.addTool = function (id, target, o) {
+    o = o || {};
+    if (typeof id !== 'string' || !TOOL_ID.test(id)) { throw new Error('sMap: a tool id is 1-64 letters, digits, "-", "_" or "."'); }
+    var kind = typeof target === 'string' ? TOOL_KINDS[target] : null;
+    if (typeof target === 'string') {
+      if (!kind) { throw new Error('sMap: unknown tool kind "' + target + '"'); }
+      if (!engine[kind.control]) { throw new Error('sMap: the rendering engine has no ' + kind.control); }
+    } else if (!isElement(target) && !(target && typeof target.onAdd === 'function')) {
+      throw new Error('sMap: a tool is an element, an engine control or a tool kind');
+    }
+    var position = o.position || (kind ? kind.position : (isElement(target) ? (target.parentNode ? 'none' : 'top-left') : 'top-right'));
+    if (position !== 'none' && TOOL_CORNERS.indexOf(position) < 0) { throw new Error('sMap: unknown tool position "' + position + '"'); }
+    if (position === 'none' && !isElement(target)) { throw new Error('sMap: only an element may stay out of the map\'s corners'); }
+    if (this._toolIndex(id) >= 0) { this.removeTool(id); }
+    var tool = { id: id, label: String(o.label || (kind ? kind.label : id)), position: position, el: null, control: null };
+    if (kind) { tool.control = toolControl(tool, new engine[kind.control](o.options || kind.options)); }
+    else if (!isElement(target)) { tool.control = toolControl(tool, target); }
+    else if (position !== 'none') { tool.control = elementControl(tool, target); }
+    else { tool.el = target; }
+    this._tools.push(tool);
+    if (this.engine) { this._mountTool(tool); }
+    this._renderToolsControl();
+    return this;
+  };
+
+  /** Removes a tool: an engine control leaves the map, a page element is shown again where the page put it. */
+  SMap.prototype.removeTool = function (id) {
+    var i = this._toolIndex(id);
+    if (i < 0) { return this; }
+    var tool = this._tools[i];
+    this._tools.splice(i, 1);
+    if (tool.el) { tool.el.classList.remove('smap-tool-hidden'); }
+    if (tool.control && this.engine && tool.mounted) { this.engine.removeControl(tool.control); }
+    this._renderToolsControl();
+    return this;
+  };
+
+  /** Shows or hides one tool. A hidden tool keeps its state and shows again as it was (M57). */
+  SMap.prototype.setToolVisible = function (id, visible) {
+    var tool = this._tools[this._toolIndex(id)];
+    if (!tool || this._toolVisible(tool) === !!visible) { return this; }
+    this._setHidden(tool, !visible);
+    this._renderToolsControl();
+    this._toolsChanged(id);
+    return this;
+  };
+
+  /** Shows or hides every tool. The map data credit, the sMap badge and the tools control always stay (M51). */
+  SMap.prototype.setToolsVisible = function (visible) {
+    var changed = false;
+    this._tools.forEach(function (tool) {
+      if (this._toolVisible(tool) !== !!visible) { this._setHidden(tool, !visible); changed = true; }
+    }, this);
+    if (changed) { this._renderToolsControl(); this._toolsChanged(null); }
+    return this;
+  };
+
+  /** The tools in the order added: [{ id, label, visible }]. */
+  SMap.prototype.tools = function () {
+    return this._tools.map(function (tool) { return { id: tool.id, label: tool.label, visible: this._toolVisible(tool) }; }, this);
+  };
+
+  /** Calls handler({ hidden: [ids], changed: id | null }) after every change; the SDK keeps no state itself (M53). */
+  SMap.prototype.onToolsChange = function (handler) { this._toolHandlers.push(handler); return this; };
+  SMap.prototype.offToolsChange = function (handler) {
+    this._toolHandlers = this._toolHandlers.filter(function (h) { return h !== handler; });
+    return this;
+  };
+
+  SMap.prototype._toolIndex = function (id) {
+    for (var i = 0; i < this._tools.length; i++) { if (this._tools[i].id === id) { return i; } }
+    return -1;
+  };
+  SMap.prototype._toolVisible = function (tool) { return !this._toolsHidden[tool.id]; };
+  SMap.prototype._setHidden = function (tool, hidden) {
+    if (hidden) { this._toolsHidden[tool.id] = true; } else { delete this._toolsHidden[tool.id]; }
+    if (tool.el) { tool.el.classList.toggle('smap-tool-hidden', hidden); }
+  };
+  SMap.prototype._toolsChanged = function (id) {
+    var hidden = this._tools.filter(function (t) { return !this._toolVisible(t); }, this).map(function (t) { return t.id; });
+    this._toolHandlers.slice().forEach(function (h) { h({ hidden: hidden, changed: id }); });
+  };
+
+  SMap.prototype._mountTool = function (tool) {
+    // The tools control joins the map with its first tool, so a map without tools is exactly as before.
+    if (this._toolsControlAt && !this._toolsControl && this.engine.addControl) {
+      this._toolsControl = toolsControl(this);
+      this.engine.addControl(this._toolsControl, this._toolsControlAt);
+    }
+    if (tool.control && this.engine.addControl) { this.engine.addControl(tool.control, tool.position); tool.mounted = true; }
+    if (tool.el) { tool.el.classList.toggle('smap-tool-hidden', !this._toolVisible(tool)); }
+  };
+
+  // Called once the engine exists: every tool registered before it.
+  SMap.prototype._mountTools = function () {
+    this._tools.forEach(function (tool) { this._mountTool(tool); }, this);
+    this._renderToolsControl();
+  };
+  SMap.prototype._renderToolsControl = function () { if (this._toolsControl) { this._toolsControl._render(); } };
+
+  // The tools control: one button that opens a panel with one toggle per tool (pressed = shown), Show all and Hide all.
+  // It is not a tool and is never hidden; it joins the map with the first tool and is not drawn while none is left.
+  function toolsControl(map) {
+    var el = null;
+    var button = null;
+    var panel = null;
+    var drawn = null;
+    var text = {};
+    Object.keys(TOOLS_TEXT).forEach(function (k) { text[k] = map._toolsLabels[k] || TOOLS_TEXT[k]; });
+    function open(on) {
+      panel.hidden = !on;
+      button.setAttribute('aria-expanded', on ? 'true' : 'false');
+    }
+    function close() { if (panel && !panel.hidden) { open(false); } }
+    function key(e) { if (e.key === 'Escape' && !panel.hidden) { open(false); button.focus(); } }
+    function make(doc, tag, className, label) {
+      var b = doc.createElement(tag);
+      b.className = className;
+      if (tag === 'button') { b.type = 'button'; }
+      if (label !== undefined) { b.textContent = label; }
+      return b;
+    }
+    var control = {
+      onAdd: function (m) {
+        var doc = m.getContainer().ownerDocument;
+        el = make(doc, 'div', 'maplibregl-ctrl maplibregl-ctrl-group smap-tools');
+        button = make(doc, 'button', 'smap-tools-button');
+        button.innerHTML = TOOLS_ICON;
+        button.title = text.button;
+        button.setAttribute('aria-label', text.button);
+        button.setAttribute('aria-haspopup', 'true');
+        button.addEventListener('click', function () { open(panel.hidden); });
+        panel = make(doc, 'div', 'smap-tools-panel');
+        panel.setAttribute('role', 'group');
+        panel.setAttribute('aria-label', text.button);
+        el.appendChild(button);
+        el.appendChild(panel);
+        el.addEventListener('keydown', key);
+        open(false);
+        m.on('click', close);
+        return el;
+      },
+      onRemove: function (m) {
+        m.off('click', close);
+        if (el && el.parentNode) { el.parentNode.removeChild(el); }
+        el = null;
+        drawn = null;
+      },
+      _render: function () {
+        if (!el) { return; }
+        var doc = el.ownerDocument;
+        el.classList.toggle('smap-tools-empty', map._tools.length === 0);
+        // The same tools as last time: only the pressed states change, so a toggle keeps the keyboard focus.
+        var signature = JSON.stringify(map._tools.map(function (t) { return [t.id, t.label]; }));
+        if (signature === drawn) {
+          map._tools.forEach(function (tool, i) { panel.children[i].setAttribute('aria-pressed', map._toolVisible(tool) ? 'true' : 'false'); });
+          return;
+        }
+        drawn = signature;
+        while (panel.firstChild) { panel.removeChild(panel.firstChild); }
+        map._tools.forEach(function (tool) {
+          var item = make(doc, 'button', 'smap-tools-item', tool.label);
+          item.setAttribute('aria-pressed', map._toolVisible(tool) ? 'true' : 'false');
+          item.setAttribute('data-tool', tool.id);
+          item.addEventListener('click', function () { map.setToolVisible(tool.id, !map._toolVisible(tool)); });
+          panel.appendChild(item);
+        });
+        var all = make(doc, 'div', 'smap-tools-all');
+        var show = make(doc, 'button', 'smap-tools-show-all', text.showAll);
+        show.addEventListener('click', function () { map.setToolsVisible(true); });
+        var hide = make(doc, 'button', 'smap-tools-hide-all', text.hideAll);
+        hide.addEventListener('click', function () { map.setToolsVisible(false); });
+        all.appendChild(show);
+        all.appendChild(hide);
+        panel.appendChild(all);
+      },
+    };
+    return control;
+  }
+
   // ------------------------------------------------------------------ Style Specification sources and layers (M24)
 
   function clone(v) { return v === undefined ? undefined : JSON.parse(JSON.stringify(v)); }

package/dist/smap.mjs

@@ -1,5 +1,5 @@
 /* Generated by js/build.mjs from js/src (see SOURCE.json). Do not edit. */
-/*! sMap Web SDK 1.1.2. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
+/*! sMap Web SDK 1.1.5. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
 
 var smapCore = null;
 function smapCreateEngine() {
@@ -28352,7 +28352,7 @@ function smapCreateSdk(engine, interop) {
 })(typeof self !== 'undefined' ? self : this, function (engine, interop) {
   'use strict';
 
-  var VERSION = '1.1.2';
+  var VERSION = '1.1.5';
   var FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
   var BASEMAP_SOURCE = 'basemap';
   var BUILDINGS_LAYER = 'smap-buildings-3d';
@@ -28805,11 +28805,20 @@ function smapCreateSdk(engine, interop) {
     // True between a style's load and the next style change. The engine's own isStyleLoaded() turns false while any
     // source is loading data, which would leave layers added meanwhile waiting for a load that never comes.
     this._styleReady = false;
+    // Map tools (M49-M57): the controls and panels floating on the map that the caller registered, in the order added.
+    var toolOptions = options.tools || {};
+    this._tools = [];
+    this._toolsHidden = {};
+    (toolOptions.hidden || []).forEach(function (id) { this._toolsHidden[id] = true; }, this);
+    this._toolsControlAt = toolOptions.control === undefined ? 'top-right' : toolOptions.control;
+    this._toolsLabels = toolOptions.labels || {};
+    this._toolsControl = null;
+    this._toolHandlers = [];
 
     var self = this;
     var engineOptions = {};
     for (var k in options) {
-      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D'].indexOf(k) < 0) {
+      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D', 'tools'].indexOf(k) < 0) {
         engineOptions[k] = options[k];
       }
     }
@@ -28842,6 +28851,7 @@ function smapCreateSdk(engine, interop) {
         self.engine.addControl(badge, 'bottom-right');
         badge._place();
       }
+      self._mountTools();
       self.engine.on('style.load', function () { self._styleReady = true; self._restore(); });
       self._keyboard3D();
       // One click handler for every layer's popup: the engine's hit test over those layers, the top feature opens.
@@ -29325,6 +29335,249 @@ function smapCreateSdk(engine, interop) {
   SMap.prototype.flyTo = function (o) { this.engine.flyTo(o); return this; };
   SMap.prototype.remove = function () { clearTimeout(this._refreshTimer); if (this.engine) { this.engine.remove(); } };
 
+  // ------------------------------------------------------------------ map tools (M49-M57)
+
+  var TOOL_ID = /^[A-Za-z0-9._-]{1,64}$/;
+  var TOOL_CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+  // The tools the SDK makes by name: the engine control, its English label (the caller may give another) and corner.
+  var TOOL_KINDS = {
+    navigation: { control: 'NavigationControl', label: 'Zoom', position: 'top-left' },
+    geolocate: { control: 'GeolocateControl', label: 'Locate', position: 'top-left' },
+    fullscreen: { control: 'FullscreenControl', label: 'Full screen', position: 'top-left' },
+    scale: { control: 'ScaleControl', label: 'Scale', position: 'bottom-left' },
+    // The mobile SDKs' names for the same controls, so one tool list serves every platform.
+    zoom: { control: 'NavigationControl', label: 'Zoom', position: 'top-left', options: { showCompass: false } },
+    compass: { control: 'NavigationControl', label: 'Compass', position: 'top-left', options: { showZoom: false } },
+    locate: { control: 'GeolocateControl', label: 'Locate', position: 'top-left' },
+  };
+  var TOOLS_ICON = '<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true" focusable="false" fill="none" ' +
+    'stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 7h10M18 7h2M4 17h2M10 17h10"/>' +
+    '<circle cx="16" cy="7" r="2"/><circle cx="8" cy="17" r="2"/></svg>';
+  var TOOLS_TEXT = { button: 'Map tools', showAll: 'Show all', hideAll: 'Hide all' };
+
+  function isElement(v) { return !!v && typeof v === 'object' && v.nodeType === 1; }
+
+  // An engine control whose element the SDK can find again to show or hide it: the control's own onAdd, its element kept.
+  function toolControl(tool, inner) {
+    return {
+      onAdd: function (m) { tool.el = inner.onAdd(m); return tool.el; },
+      onRemove: function (m) { if (inner.onRemove) { inner.onRemove(m); } else if (tool.el && tool.el.parentNode) { tool.el.parentNode.removeChild(tool.el); } tool.el = null; },
+      getDefaultPosition: function () { return tool.position; },
+    };
+  }
+
+  // A page element placed in a corner of the map: it moves into the corner and back where it was when removed.
+  function elementControl(tool, element) {
+    var home = null;
+    var next = null;
+    return {
+      onAdd: function () {
+        home = element.parentNode;
+        next = element.nextSibling;
+        element.classList.add('maplibregl-ctrl', 'smap-tool');
+        tool.el = element;
+        return element;
+      },
+      onRemove: function () {
+        element.classList.remove('maplibregl-ctrl', 'smap-tool');
+        if (home) { home.insertBefore(element, next && next.parentNode === home ? next : null); } else if (element.parentNode) { element.parentNode.removeChild(element); }
+        tool.el = null;
+      },
+      getDefaultPosition: function () { return tool.position; },
+    };
+  }
+
+  /**
+   * Registers a tool floating on the map, shown or hidden by setToolVisible / setToolsVisible and the tools control.
+   *   map.addTool('legend', document.getElementById('legend'), { label: 'Legend', position: 'bottom-left' })
+   *   map.addTool('zoom', 'navigation', { options: { showCompass: false } })
+   * @param {string} id  1-64 letters, digits, '-', '_', '.'; adding an id again replaces the first
+   * @param {Element|Object|string} target  a page element, an engine control (onAdd / onRemove), or a kind the SDK
+   *        makes: 'navigation', 'geolocate', 'fullscreen', 'scale', or the mobile SDKs' 'zoom' (navigation without the
+   *        compass), 'compass' (without the zoom buttons) and 'locate' (geolocate)
+   * @param {Object} [o]  label (shown on its button), position ('top-left', 'top-right', 'bottom-left', 'bottom-right',
+   *        or 'none': an element stays where the page put it), options (of a kind's engine control)
+   */
+  SMap.prototype.addTool = function (id, target, o) {
+    o = o || {};
+    if (typeof id !== 'string' || !TOOL_ID.test(id)) { throw new Error('sMap: a tool id is 1-64 letters, digits, "-", "_" or "."'); }
+    var kind = typeof target === 'string' ? TOOL_KINDS[target] : null;
+    if (typeof target === 'string') {
+      if (!kind) { throw new Error('sMap: unknown tool kind "' + target + '"'); }
+      if (!engine[kind.control]) { throw new Error('sMap: the rendering engine has no ' + kind.control); }
+    } else if (!isElement(target) && !(target && typeof target.onAdd === 'function')) {
+      throw new Error('sMap: a tool is an element, an engine control or a tool kind');
+    }
+    var position = o.position || (kind ? kind.position : (isElement(target) ? (target.parentNode ? 'none' : 'top-left') : 'top-right'));
+    if (position !== 'none' && TOOL_CORNERS.indexOf(position) < 0) { throw new Error('sMap: unknown tool position "' + position + '"'); }
+    if (position === 'none' && !isElement(target)) { throw new Error('sMap: only an element may stay out of the map\'s corners'); }
+    if (this._toolIndex(id) >= 0) { this.removeTool(id); }
+    var tool = { id: id, label: String(o.label || (kind ? kind.label : id)), position: position, el: null, control: null };
+    if (kind) { tool.control = toolControl(tool, new engine[kind.control](o.options || kind.options)); }
+    else if (!isElement(target)) { tool.control = toolControl(tool, target); }
+    else if (position !== 'none') { tool.control = elementControl(tool, target); }
+    else { tool.el = target; }
+    this._tools.push(tool);
+    if (this.engine) { this._mountTool(tool); }
+    this._renderToolsControl();
+    return this;
+  };
+
+  /** Removes a tool: an engine control leaves the map, a page element is shown again where the page put it. */
+  SMap.prototype.removeTool = function (id) {
+    var i = this._toolIndex(id);
+    if (i < 0) { return this; }
+    var tool = this._tools[i];
+    this._tools.splice(i, 1);
+    if (tool.el) { tool.el.classList.remove('smap-tool-hidden'); }
+    if (tool.control && this.engine && tool.mounted) { this.engine.removeControl(tool.control); }
+    this._renderToolsControl();
+    return this;
+  };
+
+  /** Shows or hides one tool. A hidden tool keeps its state and shows again as it was (M57). */
+  SMap.prototype.setToolVisible = function (id, visible) {
+    var tool = this._tools[this._toolIndex(id)];
+    if (!tool || this._toolVisible(tool) === !!visible) { return this; }
+    this._setHidden(tool, !visible);
+    this._renderToolsControl();
+    this._toolsChanged(id);
+    return this;
+  };
+
+  /** Shows or hides every tool. The map data credit, the sMap badge and the tools control always stay (M51). */
+  SMap.prototype.setToolsVisible = function (visible) {
+    var changed = false;
+    this._tools.forEach(function (tool) {
+      if (this._toolVisible(tool) !== !!visible) { this._setHidden(tool, !visible); changed = true; }
+    }, this);
+    if (changed) { this._renderToolsControl(); this._toolsChanged(null); }
+    return this;
+  };
+
+  /** The tools in the order added: [{ id, label, visible }]. */
+  SMap.prototype.tools = function () {
+    return this._tools.map(function (tool) { return { id: tool.id, label: tool.label, visible: this._toolVisible(tool) }; }, this);
+  };
+
+  /** Calls handler({ hidden: [ids], changed: id | null }) after every change; the SDK keeps no state itself (M53). */
+  SMap.prototype.onToolsChange = function (handler) { this._toolHandlers.push(handler); return this; };
+  SMap.prototype.offToolsChange = function (handler) {
+    this._toolHandlers = this._toolHandlers.filter(function (h) { return h !== handler; });
+    return this;
+  };
+
+  SMap.prototype._toolIndex = function (id) {
+    for (var i = 0; i < this._tools.length; i++) { if (this._tools[i].id === id) { return i; } }
+    return -1;
+  };
+  SMap.prototype._toolVisible = function (tool) { return !this._toolsHidden[tool.id]; };
+  SMap.prototype._setHidden = function (tool, hidden) {
+    if (hidden) { this._toolsHidden[tool.id] = true; } else { delete this._toolsHidden[tool.id]; }
+    if (tool.el) { tool.el.classList.toggle('smap-tool-hidden', hidden); }
+  };
+  SMap.prototype._toolsChanged = function (id) {
+    var hidden = this._tools.filter(function (t) { return !this._toolVisible(t); }, this).map(function (t) { return t.id; });
+    this._toolHandlers.slice().forEach(function (h) { h({ hidden: hidden, changed: id }); });
+  };
+
+  SMap.prototype._mountTool = function (tool) {
+    // The tools control joins the map with its first tool, so a map without tools is exactly as before.
+    if (this._toolsControlAt && !this._toolsControl && this.engine.addControl) {
+      this._toolsControl = toolsControl(this);
+      this.engine.addControl(this._toolsControl, this._toolsControlAt);
+    }
+    if (tool.control && this.engine.addControl) { this.engine.addControl(tool.control, tool.position); tool.mounted = true; }
+    if (tool.el) { tool.el.classList.toggle('smap-tool-hidden', !this._toolVisible(tool)); }
+  };
+
+  // Called once the engine exists: every tool registered before it.
+  SMap.prototype._mountTools = function () {
+    this._tools.forEach(function (tool) { this._mountTool(tool); }, this);
+    this._renderToolsControl();
+  };
+  SMap.prototype._renderToolsControl = function () { if (this._toolsControl) { this._toolsControl._render(); } };
+
+  // The tools control: one button that opens a panel with one toggle per tool (pressed = shown), Show all and Hide all.
+  // It is not a tool and is never hidden; it joins the map with the first tool and is not drawn while none is left.
+  function toolsControl(map) {
+    var el = null;
+    var button = null;
+    var panel = null;
+    var drawn = null;
+    var text = {};
+    Object.keys(TOOLS_TEXT).forEach(function (k) { text[k] = map._toolsLabels[k] || TOOLS_TEXT[k]; });
+    function open(on) {
+      panel.hidden = !on;
+      button.setAttribute('aria-expanded', on ? 'true' : 'false');
+    }
+    function close() { if (panel && !panel.hidden) { open(false); } }
+    function key(e) { if (e.key === 'Escape' && !panel.hidden) { open(false); button.focus(); } }
+    function make(doc, tag, className, label) {
+      var b = doc.createElement(tag);
+      b.className = className;
+      if (tag === 'button') { b.type = 'button'; }
+      if (label !== undefined) { b.textContent = label; }
+      return b;
+    }
+    var control = {
+      onAdd: function (m) {
+        var doc = m.getContainer().ownerDocument;
+        el = make(doc, 'div', 'maplibregl-ctrl maplibregl-ctrl-group smap-tools');
+        button = make(doc, 'button', 'smap-tools-button');
+        button.innerHTML = TOOLS_ICON;
+        button.title = text.button;
+        button.setAttribute('aria-label', text.button);
+        button.setAttribute('aria-haspopup', 'true');
+        button.addEventListener('click', function () { open(panel.hidden); });
+        panel = make(doc, 'div', 'smap-tools-panel');
+        panel.setAttribute('role', 'group');
+        panel.setAttribute('aria-label', text.button);
+        el.appendChild(button);
+        el.appendChild(panel);
+        el.addEventListener('keydown', key);
+        open(false);
+        m.on('click', close);
+        return el;
+      },
+      onRemove: function (m) {
+        m.off('click', close);
+        if (el && el.parentNode) { el.parentNode.removeChild(el); }
+        el = null;
+        drawn = null;
+      },
+      _render: function () {
+        if (!el) { return; }
+        var doc = el.ownerDocument;
+        el.classList.toggle('smap-tools-empty', map._tools.length === 0);
+        // The same tools as last time: only the pressed states change, so a toggle keeps the keyboard focus.
+        var signature = JSON.stringify(map._tools.map(function (t) { return [t.id, t.label]; }));
+        if (signature === drawn) {
+          map._tools.forEach(function (tool, i) { panel.children[i].setAttribute('aria-pressed', map._toolVisible(tool) ? 'true' : 'false'); });
+          return;
+        }
+        drawn = signature;
+        while (panel.firstChild) { panel.removeChild(panel.firstChild); }
+        map._tools.forEach(function (tool) {
+          var item = make(doc, 'button', 'smap-tools-item', tool.label);
+          item.setAttribute('aria-pressed', map._toolVisible(tool) ? 'true' : 'false');
+          item.setAttribute('data-tool', tool.id);
+          item.addEventListener('click', function () { map.setToolVisible(tool.id, !map._toolVisible(tool)); });
+          panel.appendChild(item);
+        });
+        var all = make(doc, 'div', 'smap-tools-all');
+        var show = make(doc, 'button', 'smap-tools-show-all', text.showAll);
+        show.addEventListener('click', function () { map.setToolsVisible(true); });
+        var hide = make(doc, 'button', 'smap-tools-hide-all', text.hideAll);
+        hide.addEventListener('click', function () { map.setToolsVisible(false); });
+        all.appendChild(show);
+        all.appendChild(hide);
+        panel.appendChild(all);
+      },
+    };
+    return control;
+  }
+
   // ------------------------------------------------------------------ Style Specification sources and layers (M24)
 
   function clone(v) { return v === undefined ? undefined : JSON.parse(JSON.stringify(v)); }
@@ -30293,7 +30546,7 @@ function SMapMap(options) {
   SMapMap.prototype = core.Map.prototype;
   return new core.Map(options);
 }
-var smapVersion = "1.1.2";
+var smapVersion = "1.1.5";
 var smapStyles = ['light', 'white', 'grayscale', 'dark', 'black'];
 /** The bundled rendering engine, for anything the SDK does not wrap (loaded on the first call). */
 function smapGetEngine() { return smapLoad().engine; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap",
-  "version": "1.1.2",
+  "version": "1.1.5",
   "description": "sMap for the web: maps from Superroute's sMap service, the Web SDK (map view) and the JS client (tokens, nearest node, styles, tiles).",
   "license": "MIT",
   "author": "Goodneo Solutions",

package/types/smap.d.cts

@@ -292,10 +292,39 @@ export interface MapOptions {
   popup?: PopupOptions;
   /** Shown while a popup's content is a pending promise (HTML string or DOM node; default pulsing dots). */
   popupLoading?: string | Node;
+  /** Map tools: the starting state, where the tools control sits (or false for none) and its labels. */
+  tools?: ToolsOptions;
   /** Every other option goes to the rendering engine. */
   [engineOption: string]: unknown;
 }
 
+/** A corner of the map, or 'none' for an element that stays where the page put it. */
+export type ToolPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
+/** The tools the SDK makes by name. */
+export type ToolKind = 'navigation' | 'geolocate' | 'fullscreen' | 'scale' | 'zoom' | 'compass' | 'locate';
+export interface ToolOptions {
+  /** Shown on the tool's button in the tools control and read by screen readers. */
+  label?: string;
+  position?: ToolPosition;
+  /** Options of a kind's engine control (e.g. `{ showCompass: false }` for navigation). */
+  options?: Record<string, unknown>;
+}
+export interface ToolsOptions {
+  /** Ids of the tools hidden from the start. */
+  hidden?: string[];
+  /** Where the tools control sits ('top-right' by default), or false to leave it out. */
+  control?: Exclude<ToolPosition, 'none'> | false;
+  /** The tools control's texts (English by default). */
+  labels?: { button?: string; showAll?: string; hideAll?: string };
+}
+export interface ToolState { id: string; label: string; visible: boolean }
+export interface ToolsChangeEvent {
+  /** Ids of the registered tools that are hidden now. */
+  hidden: string[];
+  /** The tool switched, or null when every tool was switched at once. */
+  changed: string | null;
+}
+
 /** addData: how the file is read, then the options of addPoints / addLines / addPolygons for its parts. */
 export type DataOptions = ReadOptions & PointOptions & LineOptions & PolygonOptions;
 
@@ -497,6 +526,22 @@ export declare class Map {
   closePopup(): this;
   setAutoZoom(on: boolean): this;
   autoZoom(): boolean;
+  /**
+   * Registers a tool floating on the map: a page element, an engine control, or a kind the SDK makes. Adding an id
+   * again replaces the first. The map data credit, the sMap badge and the tools control are never tools.
+   */
+  addTool(id: string, target: HTMLElement | { onAdd(map: any): HTMLElement; onRemove?(map: any): void } | ToolKind, options?: ToolOptions): this;
+  /** Removes a tool: an engine control leaves the map, a page element is shown again where the page put it. */
+  removeTool(id: string): this;
+  /** Shows or hides one tool; a hidden tool keeps its state. */
+  setToolVisible(id: string, visible: boolean): this;
+  /** Shows or hides every tool. */
+  setToolsVisible(visible: boolean): this;
+  /** The tools in the order added. */
+  tools(): ToolState[];
+  /** Called after every change; the SDK keeps no state itself. */
+  onToolsChange(handler: (event: ToolsChangeEvent) => void): this;
+  offToolsChange(handler: (event: ToolsChangeEvent) => void): this;
   on(type: string, ...args: any[]): this;
   off(type: string, ...args: any[]): this;
   once(type: string, ...args: any[]): any;

package/types/smap.d.mts

@@ -292,10 +292,39 @@ export interface MapOptions {
   popup?: PopupOptions;
   /** Shown while a popup's content is a pending promise (HTML string or DOM node; default pulsing dots). */
   popupLoading?: string | Node;
+  /** Map tools: the starting state, where the tools control sits (or false for none) and its labels. */
+  tools?: ToolsOptions;
   /** Every other option goes to the rendering engine. */
   [engineOption: string]: unknown;
 }
 
+/** A corner of the map, or 'none' for an element that stays where the page put it. */
+export type ToolPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
+/** The tools the SDK makes by name. */
+export type ToolKind = 'navigation' | 'geolocate' | 'fullscreen' | 'scale' | 'zoom' | 'compass' | 'locate';
+export interface ToolOptions {
+  /** Shown on the tool's button in the tools control and read by screen readers. */
+  label?: string;
+  position?: ToolPosition;
+  /** Options of a kind's engine control (e.g. `{ showCompass: false }` for navigation). */
+  options?: Record<string, unknown>;
+}
+export interface ToolsOptions {
+  /** Ids of the tools hidden from the start. */
+  hidden?: string[];
+  /** Where the tools control sits ('top-right' by default), or false to leave it out. */
+  control?: Exclude<ToolPosition, 'none'> | false;
+  /** The tools control's texts (English by default). */
+  labels?: { button?: string; showAll?: string; hideAll?: string };
+}
+export interface ToolState { id: string; label: string; visible: boolean }
+export interface ToolsChangeEvent {
+  /** Ids of the registered tools that are hidden now. */
+  hidden: string[];
+  /** The tool switched, or null when every tool was switched at once. */
+  changed: string | null;
+}
+
 /** addData: how the file is read, then the options of addPoints / addLines / addPolygons for its parts. */
 export type DataOptions = ReadOptions & PointOptions & LineOptions & PolygonOptions;
 
@@ -497,6 +526,22 @@ export declare class Map {
   closePopup(): this;
   setAutoZoom(on: boolean): this;
   autoZoom(): boolean;
+  /**
+   * Registers a tool floating on the map: a page element, an engine control, or a kind the SDK makes. Adding an id
+   * again replaces the first. The map data credit, the sMap badge and the tools control are never tools.
+   */
+  addTool(id: string, target: HTMLElement | { onAdd(map: any): HTMLElement; onRemove?(map: any): void } | ToolKind, options?: ToolOptions): this;
+  /** Removes a tool: an engine control leaves the map, a page element is shown again where the page put it. */
+  removeTool(id: string): this;
+  /** Shows or hides one tool; a hidden tool keeps its state. */
+  setToolVisible(id: string, visible: boolean): this;
+  /** Shows or hides every tool. */
+  setToolsVisible(visible: boolean): this;
+  /** The tools in the order added. */
+  tools(): ToolState[];
+  /** Called after every change; the SDK keeps no state itself. */
+  onToolsChange(handler: (event: ToolsChangeEvent) => void): this;
+  offToolsChange(handler: (event: ToolsChangeEvent) => void): this;
   on(type: string, ...args: any[]): this;
   off(type: string, ...args: any[]): this;
   once(type: string, ...args: any[]): any;