@superrouteca/smap-arcgis 1.1.5 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.6 — 2026-10-28
+
+- Plan editor: `addPlanEditor(view, options)` draws a plan of routes as a graphics layer on a MapView 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) is placed in the view's UI.
+  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

@@ -126,6 +126,37 @@ await addArcGisService(map, 'parcels', 'https://example.com/arcgis/rest/services
 - Helpers: `queryFeatures(url, options)`, `serviceInfo(url)`, `parseServiceUrl(url)`, `rendererStyle`,
   `symbolToSimplestyle`.
 
+## Plan editor
+
+`addPlanEditor(view, options)` lets a person edit a plan of routes on a MapView: 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 { addPlanEditor } from '@superrouteca/smap-arcgis';
+
+const plan = addPlanEditor(view, {
+  // 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));
+```
+
+- **The layer**: one GraphicsLayer (`plan`, or `id`) on the view's map with the legs, the vehicle starts, the
+  unassigned jobs and a numbered pin per stop (`colors` sets the route colours); each graphic's attributes are its
+  plan feature's (`kind`, `id`, `vehicle_id`, `position`).
+- **Dragging** uses the view's pointer and drag events and its hit test: 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 view 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** is added to the view's UI (top right; `panel: { position: 'top-left' }`), 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-arcgis",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "sMap for the ArcGIS Maps SDK for JavaScript: sMap basemaps (vector and raster), sMap layers as graphics, and ArcGIS REST services on sMap maps.",
   "license": "MIT",
   "author": "Goodneo Solutions",
@@ -50,7 +50,7 @@
     "typecheck": "tsc -p test/tsconfig.json"
   },
   "dependencies": {
-    "@superrouteca/smap": "1.1.5"
+    "@superrouteca/smap": "1.1.6"
   },
   "peerDependencies": {
     "@arcgis/core": "^5.0.0"
@@ -63,6 +63,7 @@
   "devDependencies": {
     "@arcgis/core": "5.1.27",
     "@maplibre/maplibre-gl-style-spec": "26.4.4",
+    "jsdom": "30.1.3",
     "typescript": "6.0.3"
   }
 }

package/src/index.js

@@ -4,4 +4,5 @@ export { installInterceptor, createVectorTileLayer, createRasterTileLayer, creat
 export { toArcGISStyle, styleLanguage, nameExpression } from './style.js';
 export { createGraphicsLayer, symbolFor, toArcGisGeometries, toFeatures, zoomToScale } from './graphics.js';
 export { addArcGisService, queryFeatures, serviceInfo, parseServiceUrl, withToken, symbolToSimplestyle, rendererStyle } from './services.js';
-export const version = '1.1.5';
+export { addPlanEditor } from './plan.js';
+export const version = '1.1.6';

package/src/plan.js

@@ -0,0 +1,160 @@
+// The plan editor (OPEN-ROUTE-EDIT E10) on an ArcGIS MapView: the plan drawn as a GraphicsLayer, stops dragged with
+// the view's own pointer and drag events and hit test onto another stop or a route's line, and the ready-made panel
+// in the view's UI. Every edit is a plan.* call of the Open Platform made by the SDK's PlanEditor.
+import Graphic from '@arcgis/core/Graphic.js';
+import GraphicsLayer from '@arcgis/core/layers/GraphicsLayer.js';
+import { PlanEditor, planEditorParts } from '@superrouteca/smap';
+import { symbolFor, toArcGisGeometries } from './graphics.js';
+
+const EDITOR_OPTIONS = ['credentials', 'baseUrl', 'fetch', 'app', 'region', 'profile', 'snapshot', 'geometry', 'insertLimit', 'objective'];
+
+const LEG = { color: { property: 'color' }, width: 4 };
+const START = { marker: { shape: 'circle', fill: { property: 'color' }, border: '#ffffff', size: 18 } };
+const UNASSIGNED = { marker: { shape: 'circle', fill: '#9ca3af', border: '#ffffff', size: 18 } };
+const STOP = { marker: { shape: 'pin', fill: { property: 'color' }, border: { property: 'border' } } };
+
+/**
+ * A plan editor on an ArcGIS MapView.
+ *
+ *   const plan = addPlanEditor(view, { credentials: { token: getPlanToken }, plan, language: 'fr' });
+ *   plan.editor.on('change', (e) => save(e.plan));
+ *
+ * @param {object} view  a MapView (map, ui, on, hitTest)
+ * @param {object} options  the PlanEditor options or `editor` (an editor of your own), and `id` (layer id, default
+ *   'plan'), `colors`, `preview` (default true), `language`, `labels`, `panel` (default true; false, or
+ *   { position, className, labels }), `css` (default true)
+ */
+export function addPlanEditor(view, options = {}) {
+  if (!view || !view.map || typeof view.on !== 'function') { throw new Error('sMap: addPlanEditor(view, options) needs an ArcGIS MapView with a map'); }
+  const P = planEditorParts;
+  const id = options.id || 'plan';
+  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 });
+  const layer = new GraphicsLayer({ id, title: options.title || id, listMode: 'hide' });
+  view.map.add(layer);
+  let removed = false;
+  let dragGraphic = null;
+
+  function graphicsOf(feature, kind, o) {
+    const props = { ...feature.properties };
+    return toArcGisGeometries(feature.geometry).map((geometry) => new Graphic({ geometry, attributes: props, symbol: symbolFor(kind, props, o) }));
+  }
+  function labelOf(feature) {
+    const geometry = toArcGisGeometries(feature.geometry)[0];
+    return new Graphic({
+      geometry, attributes: { ...feature.properties },
+      symbol: { type: 'text', text: feature.properties.label, color: '#ffffff', font: { size: 8, weight: 'bold', family: 'sans-serif' }, yoffset: 15 },
+    });
+  }
+
+  function draw() {
+    if (removed) { return; }
+    const f = P.planFeatures(editor, id, options.colors);
+    const list = [];
+    f.legs.forEach((x) => list.push(...graphicsOf(x, 'lines', LEG)));
+    f.starts.forEach((x) => list.push(...graphicsOf(x, 'points', START)));
+    f.unassigned.forEach((x) => list.push(...graphicsOf(x, 'points', UNASSIGNED)));
+    f.stops.forEach((x) => { list.push(...graphicsOf(x, 'points', STOP)); list.push(labelOf(x)); });
+    layer.removeAll();
+    layer.addMany(list);
+    dragGraphic = null;
+  }
+
+  function showDrag(mapPoint) {
+    if (dragGraphic) { layer.remove(dragGraphic); dragGraphic = null; }
+    if (!mapPoint) { return; }
+    const geometry = { type: 'point', longitude: mapPoint.longitude, latitude: mapPoint.latitude, spatialReference: { wkid: 4326 } };
+    dragGraphic = new Graphic({ geometry, attributes: { smap_plan_drag: true }, symbol: symbolFor('points', {}, { marker: { shape: 'circle', fill: '#111827', border: '#ffffff', size: 16 } }) });
+    layer.add(dragGraphic);
+  }
+
+  // The plan features under a screen point, as the view's hit test finds them in this layer.
+  function hitsAt(event) {
+    return Promise.resolve(view.hitTest(event, { include: [layer] })).then((r) => ((r && r.results) || [])
+      .map((x) => x.graphic)
+      .filter((g) => g && g.attributes && g.attributes.smap_plan === id && (!g.layer || g.layer === layer) && !(g.symbol && g.symbol.type === 'text'))
+      .map((g) => ({ properties: g.attributes })));
+  }
+
+  // Pointer events arrive in order, hit tests answer later: each answer is used only while its press is current.
+  let press = 0;
+  let pending = Promise.resolve();
+  const handles = [
+    view.on('pointer-down', (e) => {
+      if (removed || (e.button !== undefined && e.button !== 0)) { return; }
+      const mine = ++press;
+      drag.cancel();
+      pending = hitsAt(e).then((hits) => {
+        if (mine !== press || removed) { return; }
+        const hit = hits.find((h) => h.properties.kind === 'stop' || h.properties.kind === 'unassigned');
+        if (hit) { drag.start(hit.properties.id, { x: e.x, y: e.y }); }
+      });
+    }),
+    view.on('drag', (e) => {
+      if (removed || !drag.dragging()) { return; }
+      // The view does not pan while a stop is dragged.
+      if (typeof e.stopPropagation === 'function') { e.stopPropagation(); }
+      const mine = press;
+      const point = { x: e.x, y: e.y };
+      if (e.action === 'end') {
+        pending = pending.then(() => hitsAt(e)).then((hits) => {
+          if (mine !== press) { return; }
+          showDrag(null);
+          drag.end(hits);
+        });
+        return;
+      }
+      pending = pending.then(() => hitsAt(e)).then((hits) => {
+        if (mine !== press || !drag.dragging()) { return; }
+        drag.move(hits, point);
+        if (drag.moved() && typeof view.toMap === 'function') { showDrag(view.toMap(point)); }
+      });
+    }),
+    view.on('pointer-up', () => {
+      // A press that never became a drag.
+      pending = pending.then(() => { if (drag.dragging() && !drag.moved()) { drag.cancel(); } });
+    }),
+  ];
+
+  // The panel in the view's UI.
+  let panel = null;
+  if (options.panel !== false) {
+    const po = typeof options.panel === 'object' && options.panel ? options.panel : {};
+    const container = view.container && view.container.ownerDocument ? view.container : 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 });
+      panel.element.setAttribute('aria-label', po.label || P.textsFor(options.language || 'en', po.labels || options.labels).editor);
+      view.ui.add(panel.element, po.position || 'top-right');
+    }
+  }
+
+  const onChange = () => draw();
+  editor.on('change', onChange);
+  const gone = () => handle.remove();
+  editor.on('destroy', gone);
+
+  const handle = {
+    editor,
+    panel,
+    layer,
+    features: () => P.planFeatures(editor, id, options.colors),
+    remove() {
+      if (removed) { return; }
+      removed = true;
+      press += 1;
+      drag.cancel();
+      editor.off('change', onChange);
+      editor.off('destroy', gone);
+      handles.forEach((h) => h && h.remove && h.remove());
+      view.map.remove(layer);
+      if (panel) { view.ui.remove(panel.element); panel.destroy(); }
+      if (own) { editor.destroy(); }
+    },
+  };
+  draw();
+  if (own && options.plan) { editor.setPlan(options.plan).catch(() => {}); }
+  return handle;
+}

package/types/index.d.ts

@@ -4,6 +4,8 @@ import type VectorTileLayer from '@arcgis/core/layers/VectorTileLayer.js';
 import type WebTileLayer from '@arcgis/core/layers/WebTileLayer.js';
 import type GraphicsLayer from '@arcgis/core/layers/GraphicsLayer.js';
 import type SMapClient from '@superrouteca/smap/client';
+import type MapView from '@arcgis/core/views/MapView.js';
+import type { PlanEditor, PlanEditorOptions, PlanFeatures, PlanPanel, PlanTextKey } from '@superrouteca/smap';
 import type { LayerData, PointOptions, LineOptions, PolygonOptions, GeoJSONFeature, BasemapOverrides } from '@superrouteca/smap';
 
 export * from './services.js';
@@ -128,3 +130,38 @@ export declare function symbolFor(kind: GraphicsKind, properties: Record<string,
 export declare function toArcGisGeometries(geometry: { type: string; coordinates?: unknown; geometries?: unknown[] } | null | undefined): Array<Record<string, unknown>>;
 export declare function toFeatures(data: LayerData): GeoJSONFeature[];
 export declare function zoomToScale(zoom: number): number;
+
+// ------------------------------------------------------------------ plan editor (OPEN-ROUTE-EDIT E10)
+
+export interface ArcGisPlanEditorOptions extends Partial<PlanEditorOptions> {
+  /** An editor of your own to draw and edit; otherwise one is made from the editor options (`credentials` needed). */
+  editor?: PlanEditor;
+  /** The GraphicsLayer's id (default 'plan'). */
+  id?: string;
+  title?: 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 in the view's UI (default true, top right): false for none, or its position, class and texts. */
+  panel?: boolean | { position?: string; className?: string; labels?: Partial<Record<PlanTextKey, string>>; label?: string };
+  /** Add the panel's stylesheet to the page (default true). */
+  css?: boolean;
+}
+export interface ArcGisPlanEditor {
+  editor: PlanEditor;
+  panel: PlanPanel | null;
+  /** The plan's graphics; each graphic's attributes are its plan feature's properties. */
+  layer: GraphicsLayer;
+  features(): PlanFeatures;
+  /** Takes the layer, the view events and the panel away; ends the editor only when this binding made it. */
+  remove(): void;
+}
+/**
+ * A plan editor on an ArcGIS MapView: the plan as a GraphicsLayer, stops dragged onto another stop or a route's line,
+ * and the ready-made panel in the view's UI.
+ */
+export declare function addPlanEditor(view: MapView, options: ArcGisPlanEditorOptions): ArcGisPlanEditor;