@superrouteca/smap-deckgl 1.1.5 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.6 — 2026-10-28
+
+- Plan editor: `addPlanEditor(deck, options)` draws a plan of routes as deck.gl layers beside the app's own and lets a
+  person drag stops within and between routes, with the stop's new place priced while it is dragged. The ready-made
+  panel in 14 languages (routes, totals, violations, undo and redo, insert positions) sits in a corner of the map.
+  Every edit is a call of the Open Platform's plan editing.
+
 ## 1.1.5 — 2026-10-28
 
 - The version follows the shared 1.1.5 release; no change of its own.

package/README.md

@@ -165,6 +165,40 @@ Then pick a style by its id (`smap-light`, `smap-dark`, `smap-custom-sms_…`),
 A map key goes in the style URL itself, so a key is enough even where `transformRequest` is not passed; a token needs
 `transformRequest`. kepler.gl shows the OpenStreetMap credit from the style's sources.
 
+## Plan editor
+
+`addPlanEditor(deck, options)` lets a person edit a plan of routes on a deck.gl 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. Every edit is one call of the Open Platform's plan editing with the whole plan (see
+the plan editor of `@superrouteca/smap`); nothing is kept on a server, so keep the plan from the `change` event.
+
+```js
+import { Deck } from '@deck.gl/core';
+import { addPlanEditor } from '@superrouteca/smap-deckgl';
+
+const deck = new Deck({ parent: document.getElementById('map'), controller: true, initialViewState, layers: [myLayer] });
+const plan = addPlanEditor(deck, {
+  // A short-lived plan editor token your own server mints with POST /v1/plan/token, or { key: 'smk_…' }.
+  credentials: { token: () => fetch('/plan-token').then((r) => r.json()) },
+  plan: { vehicles, jobs, routes },
+  language: 'fr',
+});
+plan.editor.on('change', (e) => save(e.plan));
+```
+
+- **Layers**: `plan:legs`, `plan:starts`, `plan:unassigned` and `plan:stops` (`id` changes the prefix, `colors` the
+  route colours), added to the deck's own layers and replaced on every change; the app's layers stay. Pass
+  `onLayers(layers)` to place them yourself (for example with `deckLayers(map)` on an sMap map); `plan.layers()`
+  gives them at any time.
+- **Dragging** uses deck.gl's drag callbacks on the stop and job layers: drop a stop on another stop to put it before
+  that stop, or on a route's line to put it into that leg. The map does not pan while a stop is dragged, and the plan
+  with the stop at its target is priced and shown in the panel as a preview (`preview: false` turns it off).
+- **The panel** sits in a corner of the deck.gl container (`panel: { position: 'top-left' }`, default top right; or
+  `container`), in 14 languages with your own `labels`; its stylesheet is added to the page (`css: false` leaves it to
+  you). `panel: false` leaves it out, for a panel of your own on `plan.editor.state()` and its events.
+- `editor`: draw and edit an editor you made (`new PlanEditor(...)` from `@superrouteca/smap`); `remove()` then leaves
+  it running. Otherwise `remove()` also ends the editor, and ending the editor removes everything.
+
 ## Example
 
 [`examples/index.html`](examples/index.html): serve the repository root (`npx serve .`) and open

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap-deckgl",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "sMap for deck.gl: sMap as the basemap of deck.gl apps (interleaved or drawn by deck.gl), deck.gl layers on sMap maps, and kepler.gl map styles.",
   "license": "MIT",
   "author": "Goodneo Solutions",
@@ -46,7 +46,7 @@
     "typecheck": "tsc -p test/tsconfig.json"
   },
   "dependencies": {
-    "@superrouteca/smap": "1.1.5"
+    "@superrouteca/smap": "1.1.6"
   },
   "peerDependencies": {
     "@deck.gl/core": "^9.0.0",
@@ -59,6 +59,7 @@
     "@deck.gl/layers": "9.4.0",
     "@deck.gl/geo-layers": "9.4.0",
     "@deck.gl/mapbox": "9.4.0",
+    "jsdom": "30.1.3",
     "typescript": "6.0.3"
   }
 }

package/src/index.js

@@ -4,5 +4,6 @@ export { createVectorBasemapLayer, createRasterBasemapLayer, tileSubLayers } fro
 export { createSMapDeck, deckLayers, registerDeck, addAttribution } from './overlay.js';
 export { pointsLayers, linesLayers, polygonsLayers, popupTooltip, toFeatures, accessor } from './layers.js';
 export { keplerMapStyles, keplerTransformRequest } from './kepler.js';
+export { addPlanEditor } from './plan.js';
 export { parseColor, evaluate, compileStyle, drawTile } from './style.js';
-export const version = '1.1.5';
+export const version = '1.1.6';

package/src/plan.js

@@ -0,0 +1,164 @@
+// The plan editor (OPEN-ROUTE-EDIT E10) on a deck.gl map: the plan drawn as deck.gl layers, stops dragged through
+// deck.gl's own drag callbacks onto another stop or a route's line, and the ready-made panel in a corner of the deck.gl
+// container. Every edit is a plan.* call of the Open Platform made by the SDK's PlanEditor.
+import { PlanEditor, planEditorParts } from '@superrouteca/smap';
+import { linesLayers, pointsLayers } from './layers.js';
+
+const EDITOR_OPTIONS = ['credentials', 'baseUrl', 'fetch', 'app', 'region', 'profile', 'snapshot', 'geometry', 'insertLimit', 'objective'];
+const CORNERS = {
+  'top-left': 'top:10px;left:10px', 'top-right': 'top:10px;right:10px',
+  'bottom-left': 'bottom:10px;left:10px', 'bottom-right': 'bottom:30px;right:10px',
+};
+
+const fc = (features) => ({ type: 'FeatureCollection', features });
+// A feature behind a deck.gl pick: points pick their feature, lines a { path, feature } row.
+const featureOf = (object) => (object && object.feature ? object.feature : object);
+
+function withProps(layer, props) {
+  return typeof layer.clone === 'function' ? layer.clone(props) : new layer.constructor(layer.props, props);
+}
+
+/**
+ * A plan editor drawn by deck.gl.
+ *
+ *   const plan = addPlanEditor(deck, { credentials: { token: getPlanToken }, plan, language: 'fr' });
+ *   plan.editor.on('change', (e) => save(e.plan));
+ *
+ * @param {object} deck  a Deck (or anything with setProps / props / pickMultipleObjects, such as a MapboxOverlay)
+ * @param {object} options  the PlanEditor options or `editor` (an editor of your own), and `id` (layer id prefix,
+ *   default 'plan'), `colors`, `preview` (default true), `language`, `labels`, `panel` (default true; false, or
+ *   { position, className, labels, container }), `css` (default true), `container` (where the panel goes; default
+ *   the deck.gl canvas's parent), `onLayers(layers)` (to place the layers yourself instead of setProps)
+ */
+export function addPlanEditor(deck, options = {}) {
+  if (!deck || typeof deck.setProps !== 'function') { throw new Error('sMap: addPlanEditor(deck, options) needs a deck.gl Deck or overlay'); }
+  const P = planEditorParts;
+  const id = options.id || 'plan';
+  const ids = { legs: id + ':legs', starts: id + ':starts', unassigned: id + ':unassigned', stops: id + ':stops', drag: id + ':drag' };
+  const own = !options.editor;
+  const editor = options.editor || new PlanEditor(Object.fromEntries(Object.entries(options).filter(([k]) => EDITOR_OPTIONS.includes(k))));
+  const drag = P.planDrag(editor, { preview: options.preview !== false });
+  let removed = false;
+  let current = [];
+  let dragAt = null;
+  let savedController;
+
+  function setPan(on) {
+    const props = deck.props || {};
+    if (!on) {
+      if (props.controller === undefined || props.controller === null || props.controller === false) { savedController = undefined; return; }
+      savedController = props.controller;
+      deck.setProps({ controller: Object.assign({}, typeof props.controller === 'object' ? props.controller : {}, { dragPan: false }) });
+    } else if (savedController !== undefined) {
+      deck.setProps({ controller: savedController });
+      savedController = undefined;
+    }
+  }
+
+  function hitsAt(x, y) {
+    if (typeof deck.pickMultipleObjects !== 'function') { return []; }
+    const picked = deck.pickMultipleObjects({ x, y, radius: 6, layerIds: [ids.legs, ids.starts, ids.stops] }) || [];
+    return picked.map((p) => featureOf(p.object)).filter((f) => f && f.properties && f.properties.smap_plan === id);
+  }
+
+  const dragProps = {
+    onDragStart(info) {
+      const f = featureOf(info && info.object);
+      if (removed || !f || !f.properties || (f.properties.kind !== 'stop' && f.properties.kind !== 'unassigned')) { return false; }
+      drag.start(f.properties.id, { x: info.x, y: info.y });
+      setPan(false);
+      return true;
+    },
+    onDrag(info) {
+      if (!drag.dragging()) { return false; }
+      drag.move(hitsAt(info.x, info.y), { x: info.x, y: info.y });
+      if (drag.moved() && info.coordinate) { dragAt = [info.coordinate[0], info.coordinate[1]]; update(); }
+      return true;
+    },
+    onDragEnd(info) {
+      if (!drag.dragging()) { return false; }
+      setPan(true);
+      dragAt = null;
+      update();
+      drag.end(info && typeof info.x === 'number' ? hitsAt(info.x, info.y) : null);
+      return true;
+    },
+  };
+
+  function build() {
+    const f = P.planFeatures(editor, id, options.colors);
+    // The casing comes first, under the line.
+    const legs = linesLayers(ids.legs, fc(f.legs), { color: { property: 'color' }, width: 4, casing: true, pickable: true });
+    const starts = pointsLayers(ids.starts, fc(f.starts), { marker: { shape: 'circle', fill: { property: 'color' }, border: '#ffffff', size: 18 }, pickable: true });
+    const [unassigned, ...unRest] = pointsLayers(ids.unassigned, fc(f.unassigned), { marker: { shape: 'circle', fill: '#9ca3af', border: '#ffffff', size: 18 }, pickable: true });
+    const [stops, ...stopRest] = pointsLayers(ids.stops, fc(f.stops), { marker: { shape: 'pin', fill: { property: 'color' }, border: { property: 'border' }, text: { property: 'label' } }, pickable: true });
+    const out = legs.concat(starts, [withProps(unassigned, dragProps)], unRest, [withProps(stops, dragProps)], stopRest);
+    if (dragAt) {
+      out.push(...pointsLayers(ids.drag, [{ lng: dragAt[0], lat: dragAt[1] }], { marker: { shape: 'circle', fill: '#111827', border: '#ffffff', size: 16 } }));
+    }
+    return out;
+  }
+
+  function update() {
+    if (removed) { return; }
+    current = build();
+    if (typeof options.onLayers === 'function') { options.onLayers(current.slice()); return; }
+    const others = ((deck.props && deck.props.layers) || []).filter((l) => !l || !String(l.id).startsWith(id + ':'));
+    deck.setProps({ layers: others.concat(current) });
+  }
+
+  // The panel, in a corner of the deck.gl container.
+  let panel = null;
+  let wrapper = null;
+  if (options.panel !== false) {
+    const po = typeof options.panel === 'object' && options.panel ? options.panel : {};
+    const canvas = typeof deck.getCanvas === 'function' ? deck.getCanvas() : null;
+    const container = po.container || options.container || (canvas && canvas.parentElement) || null;
+    const doc = (container && container.ownerDocument) || options.document || (typeof document !== 'undefined' ? document : null);
+    if (doc) {
+      if (options.css !== false) { P.injectCss(doc); }
+      panel = P.createPanel(editor, { language: options.language || 'en', labels: po.labels || options.labels, document: doc, colors: options.colors, className: po.className });
+      if (container) {
+        wrapper = doc.createElement('div');
+        wrapper.className = 'smap-deck-plan-editor';
+        wrapper.setAttribute('style', 'position:absolute;z-index:2;pointer-events:auto;' + (CORNERS[po.position || 'top-right'] || CORNERS['top-right']));
+        wrapper.setAttribute('aria-label', po.label || P.textsFor(options.language || 'en', po.labels || options.labels).editor);
+        wrapper.appendChild(panel.element);
+        container.appendChild(wrapper);
+      }
+    }
+  }
+
+  const onChange = () => update();
+  editor.on('change', onChange);
+  const gone = () => handle.remove();
+  editor.on('destroy', gone);
+
+  const handle = {
+    editor,
+    panel,
+    /** The plan's deck.gl layers as last drawn. */
+    layers: () => current.slice(),
+    features: () => P.planFeatures(editor, id, options.colors),
+    remove() {
+      if (removed) { return; }
+      removed = true;
+      drag.cancel();
+      setPan(true);
+      editor.off('change', onChange);
+      editor.off('destroy', gone);
+      if (typeof options.onLayers === 'function') { options.onLayers([]); } else {
+        deck.setProps({ layers: ((deck.props && deck.props.layers) || []).filter((l) => !l || !String(l.id).startsWith(id + ':')) });
+      }
+      current = [];
+      if (panel) { panel.destroy(); }
+      if (wrapper && wrapper.parentNode) { wrapper.parentNode.removeChild(wrapper); }
+      if (own) { editor.destroy(); }
+    },
+    // For tests: the drag callbacks the layers carry.
+    _drag: dragProps,
+  };
+  update();
+  if (own && options.plan) { editor.setPlan(options.plan).catch(() => {}); }
+  return handle;
+}

package/types/index.d.ts

@@ -3,6 +3,7 @@ import type { Layer, PickingInfo } from '@deck.gl/core';
 import type { MVTLayer, TileLayer } from '@deck.gl/geo-layers';
 import type { MapboxOverlay, MapboxOverlayProps } from '@deck.gl/mapbox';
 import type SMapClient from '@superrouteca/smap/client';
+import type { PlanEditor, PlanEditorOptions, PlanFeatures, PlanPanel, PlanTextKey } from '@superrouteca/smap';
 import type { Map as SMapMap, MapOptions as SMapMapOptions, LayerData, PointOptions, LineOptions, PolygonOptions, GeoJSONFeature, BasemapOverrides, Slot } from '@superrouteca/smap';
 
 /** A colour scheme, or a saved custom style as `custom:<id>`. */
@@ -166,3 +167,41 @@ export declare function drawTile(compiled: CompiledStyle, features: GeoJSONFeatu
   extrusions: Array<{ geometry: unknown; color: RGBA; height: number; base: number }>;
   labels: Array<{ position: [number, number]; text: string; color: RGBA; size: number }>;
 };
+
+// ------------------------------------------------------------------ plan editor (OPEN-ROUTE-EDIT E10)
+
+export interface DeckPlanEditorOptions extends Partial<PlanEditorOptions> {
+  /** An editor of your own to draw and edit; otherwise one is made from the editor options (`credentials` needed). */
+  editor?: PlanEditor;
+  /** Prefix of the layer ids (default 'plan'): `<id>:legs`, `<id>:starts`, `<id>:unassigned`, `<id>:stops`. */
+  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, English when none of the 14 fits. */
+  language?: string;
+  labels?: Partial<Record<PlanTextKey, string>>;
+  /** The ready-made panel (default true): false for none, or its corner, class, texts and container. */
+  panel?: boolean | { position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'; className?: string; labels?: Partial<Record<PlanTextKey, string>>; label?: string; container?: HTMLElement };
+  /** Add the panel's stylesheet to the page (default true). */
+  css?: boolean;
+  /** Where the panel goes (default the deck.gl canvas's parent). */
+  container?: HTMLElement;
+  /** Place the plan's layers yourself (called after every change) instead of the binding setting the deck's layers. */
+  onLayers?: (layers: Layer[]) => void;
+}
+export interface DeckPlanEditor {
+  editor: PlanEditor;
+  panel: PlanPanel | null;
+  /** The plan's deck.gl layers as last drawn. */
+  layers(): Layer[];
+  features(): PlanFeatures;
+  /** Takes the layers, drag handling and panel away; destroys the editor only when this binding made it. */
+  remove(): void;
+}
+/**
+ * A plan editor drawn by deck.gl: the plan as deck.gl layers, stops dragged onto another stop or a route's line, and
+ * the ready-made panel in a corner of the deck.gl container.
+ */
+export declare function addPlanEditor(deck: { setProps(props: Record<string, unknown>): void; props?: { layers?: unknown[]; controller?: unknown }; pickMultipleObjects?(o: { x: number; y: number; radius?: number; layerIds?: string[] }): PickingInfo[]; getCanvas?(): HTMLCanvasElement | null }, options: DeckPlanEditorOptions): DeckPlanEditor;