@superrouteca/smap-openlayers 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 an OpenLayers map — drag a stop within its
+  route or onto another route (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 a vector layer 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

@@ -136,6 +136,40 @@ A layer's opacity, zoom range and the source's attributions come along. Without
 top, in the order added. `addOpenLayersLayers` skips an sMap basemap already in the OpenLayers map and lists what it
 could not add in `skipped`.
 
+## Plan editor
+
+`addPlanEditor(map, options)` lets a person edit a plan of routes on an OpenLayers map: 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-openlayers';
+
+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();
+```
+
+- `plan.layer` is a vector layer with the legs, the vehicles' starts, the unassigned jobs and the stops (numbered in
+  route order, outlined dark red with a violation, near black when locked); `features()` gives them as GeoJSON.
+- `plan.interaction` drags a stop or an unassigned job: 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).
+- `plan.control` holds the ready-made panel (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. `id` marks the features, `colors`
+  sets the route colours. `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-openlayers",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "sMap for OpenLayers: maps from Superroute's sMap service as an OpenLayers layer (vector or raster), and OpenLayers sources 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": {
     "jsdom": "30.1.3",

package/src/index.js

@@ -12,11 +12,12 @@ import * as sMapModule from '@superrouteca/smap';
 import { SMapAccess, checkStyle, rasterPath, stylePath, FLAVORS, DEFAULT_BASE } from './common/access.js';
 import { OSM_ATTRIBUTION, createBadge } from './common/badge.js';
 import { createEmbedded, hasWebGL2 } 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, hasWebGL2 };
+export const version = '1.1.6';
+export { FLAVORS as styles, checkStyle, rasterPath, stylePath, SMapAccess, DEFAULT_BASE, OSM_ATTRIBUTION, hasWebGL2, addPlanEditor };
 
 /** OpenLayers layer options; everything else of SMapLayer's options goes to the sMap map. */
 const LAYER_OPTIONS = ['className', 'opacity', 'visible', 'extent', 'zIndex', 'minResolution', 'maxResolution', 'minZoom', 'maxZoom', 'properties', 'map'];
@@ -322,5 +323,5 @@ export function smapBasemap(options) {
   return new SMapLayer(o);
 }
 
-const SMapOpenLayers = { version, styles: FLAVORS, SMapLayer, smapLayer, SMapRasterSource, smapRasterSource, SMapRasterLayer, smapRasterLayer, smapBasemap, SMapBadge, SMapAccess, hasWebGL2, rasterPath, checkStyle };
+const SMapOpenLayers = { version, styles: FLAVORS, SMapLayer, smapLayer, SMapRasterSource, smapRasterSource, SMapRasterLayer, smapRasterLayer, smapBasemap, SMapBadge, SMapAccess, hasWebGL2, rasterPath, checkStyle, addPlanEditor };
 export default SMapOpenLayers;

package/src/plan.js

@@ -0,0 +1,156 @@
+// The plan editor (Superroute OPEN-ROUTE-EDIT E10) on an OpenLayers map: the plan drawn as a vector layer, stops
+// dragged within and between routes through a pointer interaction, and the ready-made panel as an OpenLayers control.
+// The editor itself (state, calls, undo / redo, the panel) is the Web SDK's: PlanEditor and planEditorParts.
+import VectorLayer from 'ol/layer/Vector.js';
+import VectorSource from 'ol/source/Vector.js';
+import GeoJSON from 'ol/format/GeoJSON.js';
+import PointerInteraction from 'ol/interaction/Pointer.js';
+import Control from 'ol/control/Control.js';
+import { Style, Stroke, Fill, Circle as CircleStyle, Text } from 'ol/style.js';
+import { fromLonLat } from 'ol/proj.js';
+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', 'zIndex', 'plan'];
+const CORNERS = { 'top-left': { top: '8px', left: '8px' }, 'top-right': { top: '8px', right: '8px' }, 'bottom-left': { bottom: '24px', left: '8px' }, 'bottom-right': { bottom: '24px', right: '8px' } };
+
+function editorOptions(options) {
+  const out = {};
+  Object.keys(options).forEach(function (k) { if (OWN.indexOf(k) < 0) { out[k] = options[k]; } });
+  return out;
+}
+
+function styleFor(feature, cache) {
+  const p = feature.getProperties();
+  const key = [p.kind, p.color, p.border, p.label].join('|');
+  if (cache[key]) { return cache[key]; }
+  let style;
+  if (p.kind === 'leg') {
+    style = [new Style({ stroke: new Stroke({ color: '#ffffff', width: 7 }) }), new Style({ stroke: new Stroke({ color: p.color, width: 4 }) })];
+  } else if (p.kind === 'stop') {
+    style = new Style({
+      image: new CircleStyle({ radius: 11, fill: new Fill({ color: p.color }), stroke: new Stroke({ color: p.border || p.color, width: 3 }) }),
+      text: new Text({ text: String(p.label || ''), fill: new Fill({ color: '#ffffff' }), font: 'bold 11px sans-serif' }),
+      zIndex: 3,
+    });
+  } else if (p.kind === 'unassigned') {
+    style = new Style({ image: new CircleStyle({ radius: 8, fill: new Fill({ color: '#9ca3af' }), stroke: new Stroke({ color: '#ffffff', width: 2 }) }), zIndex: 2 });
+  } else {
+    style = new Style({ image: new CircleStyle({ radius: 8, fill: new Fill({ color: p.color }), stroke: new Stroke({ color: '#ffffff', width: 2 }) }), zIndex: 1 });
+  }
+  cache[key] = style;
+  return style;
+}
+
+/**
+ * A plan editor on an OpenLayers map.
+ *   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), `zIndex` (of the layer).
+ * @returns {{ editor, layer, interaction, control, panel, features(): Object, remove(): void }}
+ */
+export function addPlanEditor(map, options) {
+  options = options || {};
+  if (!map || typeof map.addLayer !== 'function') { throw new Error('sMap: addPlanEditor(map, options) needs an OpenLayers 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 doc = (map.getTargetElement && map.getTargetElement() && map.getTargetElement().ownerDocument) || (typeof document !== 'undefined' ? document : null);
+  const format = new GeoJSON();
+  const source = new VectorSource();
+  const cache = {};
+  const layer = new VectorLayer({ source, style: function (f) { return styleFor(f, cache); }, zIndex: options.zIndex === undefined ? 10 : options.zIndex, properties: { smapPlan: id } });
+  const drag = parts.planDrag(editor, { preview: options.preview !== false });
+  let removed = false;
+
+  function features() { return parts.planFeatures(editor, id, options.colors); }
+  function draw() {
+    if (removed) { return; }
+    const f = features();
+    const all = [].concat(f.legs, f.starts, f.unassigned, f.stops);
+    source.clear(true);
+    source.addFeatures(format.readFeatures({ type: 'FeatureCollection', features: all }, { featureProjection: 'EPSG:3857' }));
+  }
+  // OpenLayers' own hit detection (forEachFeatureAtPixel) reads the rendered canvas; the plan's features are tested
+  // in pixels here instead, so it also works before a frame is drawn (and under test without a canvas).
+  function hitsAt(pixel) {
+    const point = { x: pixel[0], y: pixel[1] };
+    const project = function (lngLat) { const px = map.getPixelFromCoordinate(fromLonLat(lngLat)); return px ? { x: px[0], y: px[1] } : { x: Infinity, y: Infinity }; };
+    return parts.featuresAt(features(), project, point);
+  }
+  function dragged() {
+    const stopId = drag.dragging();
+    return source.getFeatures().filter(function (x) { const p = x.getProperties(); return (p.kind === 'stop' || p.kind === 'unassigned') && p.id === stopId; })[0] || null;
+  }
+
+  const interaction = new PointerInteraction({
+    handleDownEvent: function (e) {
+      if (removed || !e.pixel) { return false; }
+      const hit = hitsAt(e.pixel).filter(function (f) { return f.properties.kind === 'stop' || f.properties.kind === 'unassigned'; })[0];
+      if (!hit) { return false; }
+      drag.start(hit.properties.id, { x: e.pixel[0], y: e.pixel[1] });
+      return true;   // the drag is this interaction's: the map does not pan
+    },
+    handleDragEvent: function (e) {
+      if (!drag.dragging() || !e.pixel) { return; }
+      drag.move(hitsAt(e.pixel), { x: e.pixel[0], y: e.pixel[1] });
+      const f = drag.moved() ? dragged() : null;
+      if (f && e.coordinate) { f.getGeometry().setCoordinates(e.coordinate); }
+    },
+    handleUpEvent: function (e) {
+      if (!drag.dragging()) { return false; }
+      const moved = drag.moved();
+      drag.end(e && e.pixel ? hitsAt(e.pixel) : null);
+      if (moved) { draw(); }   // the pin goes back to its place until the answer moves it
+      return false;
+    },
+  });
+
+  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 position = CORNERS[po.position] ? po.position : 'top-right';
+    const element = doc.createElement('div');
+    element.className = 'smap-plan-control smap-plan-' + position + ' ol-unselectable';
+    element.setAttribute('aria-label', po.label || parts.textsFor(language, po.labels || options.labels).editor);
+    Object.assign(element.style, { position: 'absolute' }, CORNERS[position]);
+    element.appendChild(panel.element);
+    control = new Control({ element });
+  }
+
+  const onChange = function () { draw(); };
+  editor.on('change', onChange);
+  const gone = function () { handle.remove(); };
+  editor.on('destroy', gone);
+  map.addLayer(layer);
+  map.addInteraction(interaction);
+  if (control) { map.addControl(control); }
+  draw();
+  if (own && options.plan) { editor.setPlan(options.plan).catch(function () {}); }
+
+  const handle = {
+    editor, layer, interaction, control, panel, features,
+    remove: function () {
+      if (removed) { return; }
+      removed = true;
+      drag.cancel();
+      editor.off('change', onChange);
+      editor.off('destroy', gone);
+      map.removeLayer(layer);
+      map.removeInteraction(interaction);
+      if (control) { map.removeControl(control); }
+      if (panel) { panel.destroy(); }
+      if (own) { editor.destroy(); }
+    },
+  };
+  return handle;
+}

package/types/index.d.ts

@@ -4,7 +4,11 @@ import TileLayer from 'ol/layer/Tile.js';
 import XYZ from 'ol/source/XYZ.js';
 import Control from 'ol/control/Control.js';
 import type { Options as XYZOptions } from 'ol/source/XYZ.js';
-import type { Map as SMapMap, MapOptions as SMapMapOptions, StyleFlavor } from '@superrouteca/smap';
+import type { Map as SMapMap, MapOptions as SMapMapOptions, StyleFlavor, PlanEditor, PlanEditorOptions, PlanFeatures, PlanPanel, PlanTextKey } from '@superrouteca/smap';
+import type OlMap from 'ol/Map.js';
+import type VectorLayer from 'ol/layer/Vector.js';
+import type VectorSource from 'ol/source/Vector.js';
+import type PointerInteraction from 'ol/interaction/Pointer.js';
 import type SMapClient from '@superrouteca/smap/client';
 
 export type { StyleFlavor };
@@ -164,6 +168,42 @@ export declare const DEFAULT_BASE: string;
 export declare const OSM_ATTRIBUTION: string;
 export declare const FORWARDED: 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 })) & {
+  /** Marks the features (`properties.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;
+  /** The vector layer's z-index (default 10). */
+  zIndex?: number;
+};
+/** A plan editor on an OpenLayers map. */
+export interface OpenLayersPlanEditor {
+  editor: PlanEditor;
+  /** The plan: legs, starts, unassigned jobs and stops, in the view's projection. */
+  layer: VectorLayer<VectorSource>;
+  /** Drags stops and unassigned jobs; the map does not pan while one is dragged. */
+  interaction: PointerInteraction;
+  /** The panel as a control; null with `panel: false`. */
+  control: Control | null;
+  panel: PlanPanel | null;
+  /** The features drawn, in longitude / latitude. */
+  features(): PlanFeatures;
+  /** Takes the layer, interaction and control off the map; ends the editor when this call made it. */
+  remove(): void;
+}
+/** A plan editor on an OpenLayers map: the plan drawn, stops dragged within and between routes, the panel. */
+export declare function addPlanEditor(map: OlMap, options: PlanEditorBindingOptions): OpenLayersPlanEditor;
+
 declare const SMapOpenLayers: {
   version: string;
   styles: StyleFlavor[];
@@ -179,5 +219,6 @@ declare const SMapOpenLayers: {
   hasWebGL2: typeof hasWebGL2;
   rasterPath: typeof rasterPath;
   checkStyle: typeof checkStyle;
+  addPlanEditor: typeof addPlanEditor;
 };
 export default SMapOpenLayers;