@superrouteca/smap-mapbox 1.1.5 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.6 — 2026-10-28
+
+- Plan editor: `addPlanEditor(map, options)` edits a plan of routes on a Mapbox GL JS map — drag a stop within its
+  route or onto another route with mouse or touch (priced as a preview while dragging), take stops off, place new
+  orders, refine and undo or redo, each a call of the Open Platform's plan editing. The routes are drawn as layers of
+  the map and the ready-made panel in 14 languages sits in a corner as a control.
+
 ## 1.1.5 — 2026-10-28
 
 - The version follows the shared 1.1.5 release; no change of its own.

package/README.md

@@ -126,6 +126,41 @@ sMap slot (`bottom` → `bottom`, `middle` → `labels`, `top` → `top`); optio
 none; without any, a layer draws on top in the order added. `prefix` renames every source and layer; `layers` or
 `filter` choose them. Icons of the style's own sprite are not loaded (a warning says so).
 
+## Plan editor
+
+`addPlanEditor(map, options)` lets a person edit a plan of routes on a Mapbox GL JS map (or an `SMapMapbox`): drag a
+stop within its route or onto another route, take stops off, place new orders at the positions the service ranks
+best, refine routes around locked stops, and undo or redo. Each edit is one call of the Open Platform's plan editing
+with the whole plan; the answer replaces the routes, distances, times and violations drawn. Nothing is kept on a
+server: keep the plan from the `change` event. The editor is the Web SDK's (`PlanEditor` of `@superrouteca/smap`), so
+its calls, events and credentials are the same (see the Web SDK README, "Plan editor").
+
+```js
+import { addPlanEditor } from '@superrouteca/smap-mapbox';
+
+const plan = addPlanEditor(map, {
+  // Your own server mints the token with POST /v1/plan/token; or { key: 'smk_…' } with plan editing switched on.
+  credentials: { token: () => fetch('/plan-token').then((r) => r.json()) },
+  plan: { region: 'NA', profile: 'car', vehicles, jobs, routes },
+  language: 'fr',
+});
+plan.editor.on('change', (e) => save(e.plan));
+// later
+plan.remove();
+```
+
+- The plan is drawn as GeoJSON sources and layers named after `id` (default `plan`): `plan:legs` (with
+  `plan:legs-casing` under it), `plan:starts`, `plan:unassigned`, `plan:stops` and `plan:stops-label`; `before` puts
+  them under a layer of your style. They are added once the style has loaded (`plan.ready`).
+- Press on a stop or an unassigned job and drag it: drop it on a stop to put it before that stop, on a route's line to
+  put it into that leg, or on a vehicle's start to make it the first stop. The map does not pan meanwhile, and the
+  plan with the stop at the target is priced as a preview (`preview: false` turns that off). Mouse and touch both work.
+- The ready-made panel is a control (top right; `panel: { position, className, labels, label }`, or `panel: false`):
+  routes and totals, violations, undo / redo / refine, the unassigned jobs and insert positions, in 14 languages. Its
+  stylesheet is added to the page unless `css: false`.
+- `editor: myEditor` binds an editor you made; `remove()` then leaves it running. `editor.destroy()` also removes
+  everything from the map.
+
 ## Example
 
 `examples/index.html` shows both ways. Serve the repository root (for example `npx serve .`) and open

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap-mapbox",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "sMap for Mapbox GL JS: maps from Superroute's sMap service in Mapbox GL JS, and Mapbox GL JS styles and layers on an sMap map.",
   "license": "MIT",
   "author": "Goodneo Solutions",
@@ -59,7 +59,7 @@
     }
   },
   "dependencies": {
-    "@superrouteca/smap": "1.1.5"
+    "@superrouteca/smap": "1.1.6"
   },
   "devDependencies": {
     "@types/geojson": "7946.0.16",

package/src/index.js

@@ -9,11 +9,12 @@ import * as sMapModule from '@superrouteca/smap';
 import { SMapAccess, checkStyle, rasterPath, stylePath, FLAVORS, DEFAULT_BASE } from './common/access.js';
 import { OSM_ATTRIBUTION, createBadge, injectCss } from './common/badge.js';
 import { createEmbedded } from './common/embed.js';
+import { addPlanEditor } from './plan.js';
 
 const SDK = sMapModule.default && sMapModule.default.Map ? sMapModule.default : sMapModule;
 
-export const version = '1.1.5';
-export { FLAVORS as styles, checkStyle, rasterPath, stylePath, SMapAccess, DEFAULT_BASE, OSM_ATTRIBUTION };
+export const version = '1.1.6';
+export { FLAVORS as styles, checkStyle, rasterPath, stylePath, SMapAccess, DEFAULT_BASE, OSM_ATTRIBUTION, addPlanEditor };
 
 const ACCESS_OPTIONS = ['baseUrl', 'token', 'getToken', 'apiKey', 'nodes', 'nearest', 'fetch', 'timeoutMs', 'client', 'access'];
 const OWN_OPTIONS = ['style', 'language', 'basemap', 'buildings3D', 'sdk', 'popup', 'popupLoading', 'autoZoom', 'overlay'];
@@ -471,5 +472,5 @@ export function smapAccess(options) { return new SMapAccess(options); }
 
 export { isMapboxSource, OSM_ATTRIBUTION as attribution };
 
-const SMapMapboxModule = { version, styles: FLAVORS, SMapMapbox, createMap, switchBasemap, smapAccess, smapTransformRequest, SMapBadgeControl, SMapAccess, checkStyle, rasterPath };
+const SMapMapboxModule = { version, styles: FLAVORS, SMapMapbox, createMap, switchBasemap, smapAccess, smapTransformRequest, SMapBadgeControl, SMapAccess, checkStyle, rasterPath, addPlanEditor };
 export default SMapMapboxModule;

package/src/plan.js

@@ -0,0 +1,191 @@
+// The plan editor (Superroute OPEN-ROUTE-EDIT E10) on a Mapbox GL JS map: the plan drawn as GeoJSON sources and
+// layers, stops dragged within and between routes through the map's layer events, and the ready-made panel as a
+// control. The editor itself (state, calls, undo / redo, the panel) is the Web SDK's: PlanEditor and planEditorParts.
+import * as sMapModule from '@superrouteca/smap';
+
+const SDK = sMapModule.default && sMapModule.default.PlanEditor ? sMapModule.default : sMapModule;
+
+/** Options of the binding, not of the editor. */
+const OWN = ['editor', 'id', 'colors', 'preview', 'language', 'labels', 'panel', 'css', 'before', 'plan'];
+const POSITIONS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+const fc = function (list) { return { type: 'FeatureCollection', features: list }; };
+
+function editorOptions(options) {
+  const out = {};
+  Object.keys(options).forEach(function (k) { if (OWN.indexOf(k) < 0) { out[k] = options[k]; } });
+  return out;
+}
+
+/**
+ * A plan editor on a Mapbox GL JS map (or an SMapMapbox: its `map` is used).
+ *   const plan = addPlanEditor(map, { credentials: { token: getPlanToken }, plan, language: 'fr' });
+ *   plan.editor.on('change', (e) => save(e.plan));
+ * Options: every PlanEditor option, or `editor` (an editor of your own to bind), plus `id` (default 'plan'),
+ * `colors`, `preview` (default true), `language`, `labels`, `panel` (true | false | { position, className, labels,
+ * label }), `css` (default true: the panel's stylesheet is added to the page), `before` (a layer id to draw under).
+ * @returns {{ editor, layerIds: string[], sourceIds: string[], control, panel, ready: Promise, features(): Object, remove(): void }}
+ */
+export function addPlanEditor(target, options) {
+  options = options || {};
+  const map = target && target.map && typeof target.map.addLayer === 'function' ? target.map : target;
+  if (!map || typeof map.addLayer !== 'function') { throw new Error('sMap: addPlanEditor(map, options) needs a Mapbox GL JS map'); }
+  const parts = SDK.planEditorParts;
+  const own = !options.editor;
+  const editor = options.editor || new SDK.PlanEditor(Object.assign(editorOptions(options), { plan: null }));
+  const id = options.id || 'plan';
+  const src = { legs: id + ':legs', starts: id + ':starts', unassigned: id + ':unassigned', stops: id + ':stops' };
+  const layers = {
+    casing: id + ':legs-casing', legs: id + ':legs', starts: id + ':starts', unassigned: id + ':unassigned', stops: id + ':stops', labels: id + ':stops-label',
+  };
+  const hitLayers = [layers.stops, layers.unassigned, layers.starts, layers.legs];
+  const drag = parts.planDrag(editor, { preview: options.preview !== false });
+  const container = map.getContainer ? map.getContainer() : null;
+  const doc = (container && container.ownerDocument) || (typeof document !== 'undefined' ? document : null);
+  let added = false;
+  let removed = false;
+  let current = null;
+
+  function features() { return parts.planFeatures(editor, id, options.colors); }
+  function draw() {
+    if (removed || !added) { return; }
+    current = features();
+    Object.keys(src).forEach(function (k) { const s = map.getSource(src[k]); if (s) { s.setData(fc(current[k])); } });
+  }
+  function addAll() {
+    if (removed || added) { return; }
+    current = features();
+    Object.keys(src).forEach(function (k) { map.addSource(src[k], { type: 'geojson', data: fc(current[k]) }); });
+    const before = options.before;
+    map.addLayer({ id: layers.casing, type: 'line', source: src.legs, layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: { 'line-color': '#ffffff', 'line-width': 7 } }, before);
+    map.addLayer({ id: layers.legs, type: 'line', source: src.legs, layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: { 'line-color': ['get', 'color'], 'line-width': 4 } }, before);
+    map.addLayer({ id: layers.starts, type: 'circle', source: src.starts, paint: { 'circle-radius': 8, 'circle-color': ['get', 'color'], 'circle-stroke-color': '#ffffff', 'circle-stroke-width': 2 } }, before);
+    map.addLayer({ id: layers.unassigned, type: 'circle', source: src.unassigned, paint: { 'circle-radius': 8, 'circle-color': '#9ca3af', 'circle-stroke-color': '#ffffff', 'circle-stroke-width': 2 } }, before);
+    map.addLayer({ id: layers.stops, type: 'circle', source: src.stops, paint: { 'circle-radius': 11, 'circle-color': ['get', 'color'], 'circle-stroke-color': ['get', 'border'], 'circle-stroke-width': 3 } }, before);
+    map.addLayer({
+      id: layers.labels, type: 'symbol', source: src.stops,
+      layout: { 'text-field': ['get', 'label'], 'text-size': 11, 'text-allow-overlap': true, 'text-ignore-placement': true },
+      paint: { 'text-color': '#ffffff' },
+    }, before);
+    added = true;
+    listen();
+  }
+
+  function hitsAt(point) {
+    if (typeof map.queryRenderedFeatures !== 'function') { return []; }
+    const box = [[point.x - 6, point.y - 6], [point.x + 6, point.y + 6]];
+    return (map.queryRenderedFeatures(box, { layers: hitLayers }) || []).filter(function (f) { return f && f.properties && f.properties.smap_plan === id; });
+  }
+  function setPan(on) { if (map.dragPan) { if (on) { map.dragPan.enable(); } else { map.dragPan.disable(); } } }
+  // The dragged pin follows the pointer; a redraw puts it back.
+  function follow(lngLat) {
+    const stopId = drag.dragging();
+    if (!current || !lngLat) { return; }
+    const kind = current.stops.some(function (f) { return f.properties.id === stopId; }) ? 'stops' : 'unassigned';
+    const s = map.getSource(src[kind]);
+    if (!s) { return; }
+    s.setData(fc(current[kind].map(function (f) {
+      return f.properties.id === stopId ? { type: 'Feature', properties: f.properties, geometry: { type: 'Point', coordinates: [lngLat.lng, lngLat.lat] } } : f;
+    })));
+  }
+
+  function down(e) {
+    if (removed || !e.point || (e.originalEvent && e.originalEvent.button)) { return; }
+    const hit = (e.features && e.features.length ? e.features : hitsAt(e.point)).filter(function (f) {
+      return f.properties && f.properties.smap_plan === id && (f.properties.kind === 'stop' || f.properties.kind === 'unassigned');
+    })[0];
+    if (!hit) { return; }
+    drag.start(hit.properties.id, e.point);
+    setPan(false);
+    if (e.preventDefault) { e.preventDefault(); }
+  }
+  function move(e) {
+    if (!drag.dragging() || !e.point) { return; }
+    drag.move(hitsAt(e.point), e.point);
+    if (drag.moved()) { follow(e.lngLat); }
+  }
+  function up(e) {
+    if (!drag.dragging()) { return; }
+    const moved = drag.moved();
+    setPan(true);
+    drag.end(e && e.point ? hitsAt(e.point) : null);
+    if (moved) { draw(); }
+  }
+  let listening = false;
+  function listen() {
+    if (listening) { return; }
+    listening = true;
+    [layers.stops, layers.unassigned].forEach(function (l) { map.on('mousedown', l, down); map.on('touchstart', l, down); });
+    map.on('mousemove', move);
+    map.on('touchmove', move);
+    map.on('mouseup', up);
+    map.on('touchend', up);
+  }
+
+  let control = null;
+  let panel = null;
+  if (options.panel !== false && doc) {
+    const po = typeof options.panel === 'object' && options.panel ? options.panel : {};
+    if (options.css !== false) { parts.injectCss(doc); }
+    const language = options.language || (typeof navigator !== 'undefined' && navigator.language) || 'en';
+    panel = parts.createPanel(editor, { language, labels: po.labels || options.labels, document: doc, colors: options.colors, className: po.className });
+    const element = doc.createElement('div');
+    element.className = 'mapboxgl-ctrl smap-plan-control';
+    element.setAttribute('aria-label', po.label || parts.textsFor(language, po.labels || options.labels).editor);
+    element.appendChild(panel.element);
+    control = {
+      onAdd: function () { return element; },
+      onRemove: function () { if (element.parentNode) { element.parentNode.removeChild(element); } },
+      getDefaultPosition: function () { return 'top-right'; },
+    };
+    map.addControl(control, POSITIONS.indexOf(po.position) >= 0 ? po.position : 'top-right');
+  }
+
+  const onChange = function () { draw(); };
+  editor.on('change', onChange);
+  const gone = function () { handle.remove(); };
+  editor.on('destroy', gone);
+  const loaded = typeof map.isStyleLoaded === 'function' ? map.isStyleLoaded() : true;
+  const ready = loaded ? Promise.resolve() : new Promise(function (resolve) {
+    let done = false;
+    const go = function () { if (!done) { done = true; resolve(); } };
+    map.once('style.load', go);
+    map.once('load', go);
+  });
+  if (loaded) { addAll(); } else { ready.then(addAll); }
+  // A new style (a scheme or language switch) can leave the plan's sources out: they are added again.
+  const restyled = function () {
+    if (removed || !added || map.getSource(src.legs)) { return; }
+    added = false;
+    addAll();
+  };
+  map.on('style.load', restyled);
+  if (own && options.plan) { editor.setPlan(options.plan).catch(function () {}); }
+
+  const handle = {
+    editor, control, panel, features,
+    ready: ready.then(function () { return handle; }),
+    layerIds: [layers.casing, layers.legs, layers.starts, layers.unassigned, layers.stops, layers.labels],
+    sourceIds: [src.legs, src.starts, src.unassigned, src.stops],
+    remove: function () {
+      if (removed) { return; }
+      removed = true;
+      drag.cancel();
+      setPan(true);
+      map.off('style.load', restyled);
+      editor.off('change', onChange);
+      editor.off('destroy', gone);
+      if (listening) {
+        [layers.stops, layers.unassigned].forEach(function (l) { map.off('mousedown', l, down); map.off('touchstart', l, down); });
+        map.off('mousemove', move); map.off('touchmove', move); map.off('mouseup', up); map.off('touchend', up);
+      }
+      if (added) {
+        handle.layerIds.slice().reverse().forEach(function (l) { if (map.getLayer(l)) { map.removeLayer(l); } });
+        handle.sourceIds.forEach(function (s) { if (map.getSource(s)) { map.removeSource(s); } });
+      }
+      if (control && map.removeControl) { map.removeControl(control); }
+      if (panel) { panel.destroy(); }
+      if (own) { editor.destroy(); }
+    },
+  };
+  return handle;
+}

package/types/index.d.ts

@@ -2,7 +2,7 @@
 import type * as mapboxgl from 'mapbox-gl';
 import type { Map as SMapMap, StyleFlavor, BasemapOverrides, StyleLayer, StyleSource, Slot, PointOptions, LineOptions, PolygonOptions,
   LayerData, PopupOptions, PopupContent, FitOptions, RasterLayerOptions, VectorTilesOptions, WmsLayerOptions, WmtsLayerOptions, ArcGisLayerOptions,
-  LayerDescription, DataOptions, FileInput, LngLatLike } from '@superrouteca/smap';
+  LayerDescription, DataOptions, FileInput, LngLatLike, PlanEditor, PlanEditorOptions, PlanFeatures, PlanPanel, PlanTextKey } from '@superrouteca/smap';
 import type SMapClient from '@superrouteca/smap/client';
 
 export type { StyleFlavor };
@@ -149,6 +149,43 @@ export declare const OSM_ATTRIBUTION: string;
 export declare const attribution: string;
 export declare const OVERLAY_CALLS: string[];
 
+/** Options of addPlanEditor: the editor's (or an editor of your own as `editor`) and the binding's. */
+export type PlanEditorBindingOptions = (PlanEditorOptions | (Partial<PlanEditorOptions> & { editor: PlanEditor })) & {
+  /** Prefix of the source and layer ids, and the features' `smap_plan` (default 'plan'). */
+  id?: string;
+  /** Route colours, one per vehicle in the plan's order (repeated). */
+  colors?: string[];
+  /** Price the drop target while a stop is dragged (default true). */
+  preview?: boolean;
+  /** The panel's language (any BCP-47 tag; default the browser's). */
+  language?: string;
+  labels?: Partial<Record<PlanTextKey, string>>;
+  /** The ready-made panel (default true): false for none, or its corner, class, texts and label. */
+  panel?: boolean | { position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'; className?: string; labels?: Partial<Record<PlanTextKey, string>>; label?: string };
+  /** Add the panel's stylesheet to the page (default true). */
+  css?: boolean;
+  /** A layer of the map to draw the plan under. */
+  before?: string;
+};
+/** A plan editor on a Mapbox GL JS map. */
+export interface MapboxPlanEditor {
+  editor: PlanEditor;
+  /** `<id>:legs-casing`, `<id>:legs`, `<id>:starts`, `<id>:unassigned`, `<id>:stops`, `<id>:stops-label`. */
+  layerIds: string[];
+  /** `<id>:legs`, `<id>:starts`, `<id>:unassigned`, `<id>:stops` (GeoJSON). */
+  sourceIds: string[];
+  /** The panel as a control; null with `panel: false`. */
+  control: mapboxgl.IControl | null;
+  panel: PlanPanel | null;
+  /** Resolves once the layers are on the map (after the style has loaded). */
+  ready: Promise<MapboxPlanEditor>;
+  features(): PlanFeatures;
+  /** Takes the layers, sources, listeners and control off the map; ends the editor when this call made it. */
+  remove(): void;
+}
+/** A plan editor on a Mapbox GL JS map (or an SMapMapbox): the plan drawn, stops dragged within and between routes, the panel. */
+export declare function addPlanEditor(map: mapboxgl.Map | SMapMapbox, options: PlanEditorBindingOptions): MapboxPlanEditor;
+
 declare const SMapMapboxModule: {
   version: string;
   styles: StyleFlavor[];
@@ -161,5 +198,6 @@ declare const SMapMapboxModule: {
   SMapAccess: typeof SMapAccess;
   checkStyle: typeof checkStyle;
   rasterPath: typeof rasterPath;
+  addPlanEditor: typeof addPlanEditor;
 };
 export default SMapMapboxModule;