@superrouteca/smap 1.1.2 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap",
-  "version": "1.1.2",
+  "version": "1.1.6",
   "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,45 @@ 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>;
+}
+/** A data-layer tool: one or more layer ids (yours, or the basemap's) shown and hidden with the tool. */
+export interface ToolLayers { layer: string | string[] }
+export interface ToolsOptions {
+  /** Ids of the tools hidden from the start. */
+  hidden?: string[];
+  /**
+   * Where the tools control sits: 'toolbar' (the default) is the last button of the map's toolbar, the corner holding
+   * the navigation control (top left without one), kept last when controls join it later; a corner places it there;
+   * false leaves it out.
+   */
+  control?: 'toolbar' | 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 +532,30 @@ 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; or data layers
+   * (`{ layer: 'stops' }`, `{ layer: ['stops', 'stop-labels'] }`) whose layout visibility follows the tool, a layer
+   * added later under a hidden tool's id starting hidden and an id without a layer left alone. 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 | ToolLayers, 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;
+  /**
+   * A plan editor on this map (OPEN-ROUTE-EDIT E10): the plan drawn as layers `<id>:legs`, `<id>:starts`, `<id>:stops`
+   * and `<id>:unassigned`, stops dragged within and between routes, and the ready-made panel as the map tool
+   * `<id>-editor` (unless `panel: false`). Every edit is a plan.* call of the Open Platform.
+   */
+  planEditor(options: MapPlanEditorOptions): MapPlanEditor;
   on(type: string, ...args: any[]): this;
   off(type: string, ...args: any[]): this;
   once(type: string, ...args: any[]): any;
@@ -566,6 +625,366 @@ export declare class PMTilesArchive {
 /** Registers deck.gl's map overlay module (`@deck.gl/mapbox`) for addDeckLayer. */
 export declare function useDeck(module: { MapboxOverlay: any } | { default: { MapboxOverlay: any } }): any;
 
+// ------------------------------------------------------------------ plan editor (OPEN-ROUTE-EDIT E10)
+
+/**
+ * The answer of `POST /v1/plan/token`, which your own server calls with its API token (never the browser). The
+ * provider may hand it on as it is; `expires_at` decides when the editor asks again.
+ */
+export interface PlanTokenAnswer {
+  /** `sr_pet_…`, sent as `Authorization: Bearer sr_pet_…`. */
+  access_token: string;
+  token_type?: 'Bearer';
+  expires_in?: number;
+  /** ISO 8601 with offset; the editor asks for a new token 30 s before it. */
+  expires_at?: string;
+  scopes?: string[];
+  origins?: string[] | null;
+}
+/**
+ * How plan calls are authorised, always as `Authorization: Bearer …`: a short-lived plan editor token from your own
+ * server (asked again 30 s before its `expires_at` and once after a 401 `SESSION_EXPIRED`), or a map key (`smk_…`)
+ * with plan editing switched on. Any other refusal (`SESSION_REVOKED`, `TOKEN_INVALID`, 403 `NOT_AUTHORIZED`) is
+ * raised as an error with its `reason`.
+ */
+export type PlanCredentials =
+  | { token: () => string | PlanTokenAnswer | { data: PlanTokenAnswer } | Promise<string | PlanTokenAnswer | { data: PlanTokenAnswer }> }
+  | { key: string };
+
+/** A location: `{ lat, lng }` (as the plan calls take it) or `[lng, lat]`. */
+export type PlanLocation = { lat: number; lng: number } | [number, number];
+
+export interface PlanVehicle {
+  id: string;
+  start?: PlanLocation | null;
+  end?: PlanLocation | null;
+  return_to_start?: boolean | null;
+  capacity?: unknown;
+  skills?: string[];
+  time_window?: unknown;
+  max_tasks?: number | null;
+  max_distance_meters?: number | null;
+  max_travel_time_seconds?: number | null;
+  [field: string]: unknown;
+}
+export interface PlanJob {
+  id: string;
+  location: PlanLocation;
+  service_seconds?: number | null;
+  amount?: unknown;
+  skills?: string[];
+  time_windows?: unknown;
+  [field: string]: unknown;
+}
+export interface PlanRoute { vehicle_id: string; stops: string[]; reverse?: boolean }
+/** A plan as the plan calls take it. */
+export interface Plan {
+  vehicles: PlanVehicle[];
+  jobs: PlanJob[];
+  routes: PlanRoute[];
+  region?: 'NA' | 'EU' | 'AU' | 'ASIA' | string;
+  profile?: 'car' | 'van' | 'truck' | 'bike' | 'foot' | 'motorcycle' | string;
+  /** ISO 8601 with offset. */
+  departed_at?: string;
+}
+/** The plan as the editor holds it: routes in driving order (one per vehicle) and every job on no route. */
+export interface PlanState extends Plan { unassigned: string[] }
+
+export interface PlanViolation { rule: string; message?: string; [field: string]: unknown }
+export interface PricedStop {
+  type: 'start' | 'job' | 'end';
+  id?: string;
+  sequence?: number;
+  reachable?: boolean;
+  arrival?: string | null;
+  leg_distance_meters?: number | null;
+  leg_duration_seconds?: number | null;
+  /** Encoded polyline (precision 5) of the hop into this stop. */
+  leg_geometry?: string | null;
+  violations?: PlanViolation[];
+  [field: string]: unknown;
+}
+export interface PricedRoute {
+  vehicle_id: string;
+  stop_count: number;
+  task_count: number;
+  distance_meters: number;
+  duration_seconds: number;
+  service_seconds?: number;
+  waiting_seconds?: number;
+  departure?: string;
+  completion?: string;
+  unreachable_legs: number;
+  violations: PlanViolation[];
+  violation_count: number;
+  stops: PricedStop[];
+}
+export interface PlanSummary { routes: number; tasks: number; distance_meters: number; duration_seconds: number; unreachable_legs: number; violations: number }
+/** The plan's prices and judgement as the last answer gave them. */
+export interface PlanResult { routes: PricedRoute[]; summary: PlanSummary | null }
+
+export interface InsertChoice {
+  feasible: boolean;
+  vehicle_id: string;
+  position: number;
+  after?: string | null;
+  added_distance_meters: number;
+  added_duration_seconds: number;
+  added_waiting_seconds?: number;
+  arrival?: string | null;
+  waiting_seconds?: number;
+  service_start?: string | null;
+  violations?: PlanViolation[];
+}
+/** One inserted job: whether it was placed, the positions answered (best first) and which one it is at. */
+export interface InsertChoices { job: string; placed: boolean; reason?: 'no_vehicle' | 'no_feasible_position'; choices: InsertChoice[]; chosen: number | null }
+
+export type PlanEditKind = 'set' | 'recost' | 'resequence' | 'move' | 'remove' | 'insert' | 'refine' | 'undo' | 'redo' | 'lock' | 'choices' | 'error';
+export interface PlanChangeEvent {
+  kind: PlanEditKind;
+  plan: PlanState | null;
+  result: PlanResult | null;
+  /** What the call answered about the edit (`move`, `removed`, `insert`, `refine`, `resequence` of the answer). */
+  answer: unknown;
+  /** True while the plan drawn has not been priced yet (an edit on its way). */
+  pending: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+export interface PlanEditorError extends Error {
+  status: number;
+  /** The Open Platform's error code (`VALIDATION_FAILED`, `SESSION_EXPIRED`, `NOT_AUTHORIZED`, …); never localized. */
+  code: string | null;
+  details: unknown;
+  /** Why, where the service says (`expired`, `key_revoked`, `entitlements_changed`, `origin_not_allowed`, `plan_editing_off`, …). */
+  reason: string | null;
+}
+export interface PlanSnapshotEvent {
+  /** `opened`, `failed` (calls go on without one), or the X-Plan-Matrix of an answer: `used`, `expired`, `unavailable`, `mismatch`. */
+  status: 'opened' | 'failed' | 'used' | 'expired' | 'unavailable' | 'mismatch';
+  matrix: string | null;
+  expires_at?: string | null;
+  node?: string | null;
+  error?: unknown;
+}
+export interface PlanPreview { routes: PlanRoute[]; result: PlanResult }
+/** An edit's outcome; null when a newer edit cancelled it. */
+export interface PlanEditOutcome { kind: string; plan: PlanState; result: PlanResult; answer: unknown }
+export interface PlanEditorState {
+  plan: PlanState | null;
+  result: PlanResult | null;
+  busy: boolean;
+  error: { kind: string; status: number; code: string | null; message: string; reason: string | null } | null;
+  canUndo: boolean;
+  canRedo: boolean;
+  choices: InsertChoices[] | null;
+  locked: string[];
+  last: { kind: string; answer: unknown } | null;
+  preview: PlanPreview | null;
+}
+
+export interface PlanEditorOptions {
+  credentials: PlanCredentials;
+  /**
+   * A native app's identity, sent as `X-SMap-App` (and `X-SMap-App-Cert`): `android:<package>` with its certificate,
+   * `apple:<bundle id>` or `windows:<id>`. Pages leave it out: the browser's Origin names them.
+   */
+  app?: string | { id: string; cert?: string };
+  /** The Open Platform, `https://open.superroute.ca` by default. */
+  baseUrl?: string;
+  /** The fetch to use (the page's by default). */
+  fetch?: typeof fetch;
+  /** The starting plan. */
+  plan?: Plan;
+  /** Used when the plan names none. */
+  region?: string;
+  profile?: string;
+  /** Open and use a distance snapshot (default true). */
+  snapshot?: boolean;
+  /** Ask for each leg's line, for drawing (default true). */
+  geometry?: boolean;
+  /** Positions offered per inserted job, 1-10 (default 3). */
+  insertLimit?: number;
+  /** What insert ranks by (the service's default: duration). */
+  objective?: 'duration' | 'distance';
+}
+
+export interface PlanEditorEvents {
+  change: PlanChangeEvent;
+  busy: { busy: boolean };
+  error: { error: PlanEditorError; kind: string };
+  snapshot: PlanSnapshotEvent;
+  /** A preview's prices, or null when it is cleared. */
+  preview: PlanPreview | null;
+  destroy: null;
+}
+
+/** The plan editor's state and calls, without a map (the map layer and the panel build on it). */
+export declare class PlanEditor {
+  constructor(options: PlanEditorOptions);
+  /** Replaces the plan; the history starts again from it and it is priced (plan.recost). */
+  setPlan(plan: Plan): Promise<PlanEditOutcome | null>;
+  /** The plan in the shape it is sent, with `unassigned`. */
+  getPlan(): PlanState | null;
+  getResult(): PlanResult | null;
+  state(): PlanEditorState;
+  /** Gives a route a new driving order (plan.resequence): every stop of the route once. */
+  resequence(vehicleId: string, stops: string[]): Promise<PlanEditOutcome | null>;
+  /** Moves stops to a vehicle's route at `position` (from 1, counted without them; omitted: last) (plan.move). */
+  move(stops: string | string[], vehicleId: string, position?: number | null): Promise<PlanEditOutcome | null>;
+  /** Takes stops off their routes (plan.remove). */
+  remove(stops: string | string[]): Promise<PlanEditOutcome | null>;
+  /** A stop dropped before the stop at `position` of a route as drawn: a resequence within its route, a move otherwise. */
+  dropStop(stopId: string, vehicleId: string, position: number): Promise<PlanEditOutcome | null>;
+  /** Inserts new jobs, or places unassigned jobs given by id, at their cheapest positions (plan.insert). */
+  insert(jobs: PlanJob | string | Array<PlanJob | string>, options?: { limit?: number; objective?: 'duration' | 'distance'; nearest?: number }): Promise<PlanEditOutcome | null>;
+  /** The positions the last insert answered. */
+  choices(): InsertChoices[] | null;
+  clearChoices(): this;
+  /** Puts an inserted job at another of its answered positions (plan.move). */
+  choose(jobId: string, index: number): Promise<PlanEditOutcome | null>;
+  /** Re-orders chosen routes around the locked stops (plan.refine); kept only when better. */
+  refine(options?: { vehicleIds?: string[]; freeze?: string[] }): Promise<PlanEditOutcome | null>;
+  /** Prices the plan again as it is (plan.recost). */
+  recost(): Promise<PlanEditOutcome | null>;
+  /** Locked stops stay on their route, in their order, when routes are refined. */
+  lock(stops: string | string[]): this;
+  unlock(stops: string | string[]): this;
+  locked(): string[];
+  isLocked(stopId: string): boolean;
+  undo(): Promise<PlanResult | PlanEditOutcome | null>;
+  redo(): Promise<PlanResult | PlanEditOutcome | null>;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  isBusy(): boolean;
+  /** Prices other routes without changing the plan (plan.recost); a newer preview cancels the one before. */
+  preview(routes: PlanRoute[]): Promise<PlanPreview | null>;
+  clearPreview(): this;
+  on<K extends keyof PlanEditorEvents>(type: K, handler: (event: PlanEditorEvents[K]) => void): this;
+  off<K extends keyof PlanEditorEvents>(type: K, handler: (event: PlanEditorEvents[K]) => void): this;
+  /** Cancels its calls, closes its snapshot, and removes its map layers and panel. */
+  destroy(): void;
+}
+
+/** The panel's text keys; `labels` replaces any of them. */
+export type PlanTextKey = 'editor' | 'busy' | 'undo' | 'redo' | 'refine' | 'total' | 'distance' | 'drivingTime' | 'stops' |
+  'violations' | 'unreachable' | 'unassigned' | 'noStops' | 'place' | 'remove' | 'lock' | 'unlock' | 'choicesFor' | 'choice' |
+  'added' | 'arrival' | 'choose' | 'chosen' | 'close' | 'notPlaced' | 'preview' | 'refined' | 'notRefined' | 'error' |
+  'pending' | 'km' | 'hours' | 'minutes' | 'rule.capacity' | 'rule.max_tasks' | 'rule.max_distance' |
+  'rule.max_travel_time' | 'rule.vehicle_time_window' | 'rule.skills' | 'rule.time_window' | 'rule.unreachable';
+/** The panel's languages. */
+export type PlanLanguage = 'en' | 'zh-Hans' | 'zh-Hant' | 'de' | 'es' | 'fr' | 'it' | 'nl' | 'pt' | 'sr' | 'hu' | 'pl' | 'sk' | 'cs';
+
+export interface MapPlanEditorOptions extends PlanEditorOptions {
+  /** Prefix of the layer ids (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 (default the map's); any BCP-47 tag, English when none of the 14 fits. */
+  language?: string;
+  /** Own texts by key, over the panel's. */
+  labels?: Partial<Record<PlanTextKey, string>>;
+  /** The ready-made panel (default true): false for none, or where it sits and its tool label. */
+  panel?: boolean | { position?: Exclude<ToolPosition, 'none'>; label?: string; id?: string; className?: string; labels?: Partial<Record<PlanTextKey, string>> };
+}
+
+/** A plan editor on a map, with its layers and (unless turned off) its panel. */
+export interface MapPlanEditor extends PlanEditor {
+  /** The ready-made panel; null with `panel: false` or before the map has its engine. */
+  panel: { element: HTMLElement; setLanguage(language: string): void; render(): void; destroy(): void } | null;
+  layer: { remove(): void; features(): { legs: GeoJSONFeature[]; stops: GeoJSONFeature[]; unassigned: GeoJSONFeature[]; starts: GeoJSONFeature[] } };
+}
+
+/** The panel's texts in each of its 14 languages. */
+export declare const planTexts: Record<PlanLanguage, Record<PlanTextKey, string>>;
+
+/** A feature the plan editor draws; `properties.kind` says which. */
+export interface PlanFeature {
+  type: 'Feature';
+  geometry: { type: 'Point'; coordinates: [number, number] } | { type: 'LineString'; coordinates: Array<[number, number]> };
+  properties: {
+    /** The `id` the features were made for (the layer prefix). */
+    smap_plan: string;
+    kind: 'leg' | 'stop' | 'start' | 'unassigned';
+    /** A stop's or job's id. */
+    id?: string;
+    vehicle_id?: string;
+    /** A stop's place in its route from 1; a leg's: the stop it leads to (past the last stop: the end). */
+    position?: number;
+    /** A stop's number as drawn. */
+    label?: string;
+    color: string;
+    /** A stop's border: dark red with a violation, near black when locked, otherwise its route's colour. */
+    border?: string;
+    locked?: boolean;
+    violated?: boolean;
+  };
+}
+/** The features of a plan, one list per layer. */
+export interface PlanFeatures { legs: PlanFeature[]; stops: PlanFeature[]; unassigned: PlanFeature[]; starts: PlanFeature[] }
+/** Where a dropped stop goes: before the stop at `position` of the vehicle's route as drawn (past the last: after it). */
+export interface PlanDropTarget { vehicle_id: string; position: number }
+/** A drop as an edit: a new order within the stop's route, or a move to another route (position null: last). */
+export type PlanDropEdit = { kind: 'resequence'; vehicle_id: string; stops: string[] } | { kind: 'move'; vehicle_id: string; position: number | null };
+/** A stop dragged on a map, with the preview of its target (see planEditorParts.planDrag). */
+export interface PlanDrag {
+  /** The pointer went down on a stop or an unassigned job (`point` in pixels, for the drag threshold). */
+  start(stopId: string, point?: { x: number; y: number }): void;
+  /** The pointer moved: the features under it (any objects with the features' `properties`). Answers the target. */
+  move(hits: Array<{ properties?: Record<string, unknown> }>, point?: { x: number; y: number }): PlanDropTarget | null;
+  /** The pointer was released: drops the stop on the target under `hits`, or on the last target when none are given. */
+  end(hits?: Array<{ properties?: Record<string, unknown> }> | null): Promise<PlanEditOutcome | null>;
+  cancel(): void;
+  /** The stop being dragged, or null. */
+  dragging(): string | null;
+  /** True once the pointer moved past the threshold. */
+  moved(): boolean;
+  target(): PlanDropTarget | null;
+}
+/** The ready-made panel. */
+export interface PlanPanel { element: HTMLElement; setLanguage(language: string): void; render(): void; destroy(): void }
+export interface PlanPanelOptions {
+  /** Any BCP-47 tag; English when none of the 14 fits. */
+  language?: string;
+  labels?: Partial<Record<PlanTextKey, string>>;
+  document?: Document;
+  colors?: string[];
+  className?: string;
+}
+/**
+ * The parts a plan editor on another map library is built from (the tool adapters use them): the features to draw,
+ * where a drop lands, a drag with its preview, and the panel with its stylesheet.
+ */
+export interface PlanEditorParts {
+  /** The features of the editor's plan, each marked with `smap_plan: id`. */
+  planFeatures(editor: PlanEditor, id: string, colors?: string[]): PlanFeatures;
+  /** Where a drop on these features goes: before a stop, into a leg, or first after a start; null: nowhere. */
+  dropTarget(hits: Array<{ properties?: Record<string, unknown> }>, draggedId: string): PlanDropTarget | null;
+  /** The edit a drop makes on these routes; null when nothing changes. */
+  dropEdit(routes: PlanRoute[], stopId: string, vehicleId: string, position: number): PlanDropEdit | null;
+  /** The editor's routes after the drop (for editor.preview); null when nothing changes. */
+  dropRoutes(editor: PlanEditor, stopId: string, target: PlanDropTarget | null): PlanRoute[] | null;
+  /** The features within `tolerance` pixels of a point, nearest first (points 12 px, lines 8 px by default). */
+  featuresAt(features: PlanFeatures | PlanFeature[], project: (lngLat: [number, number]) => { x: number; y: number }, point: { x: number; y: number }, options?: { tolerance?: number }): PlanFeature[];
+  /** A drag of a stop: the threshold (4 px), the preview of its target after `previewMs` (250) and the drop. */
+  planDrag(editor: PlanEditor, options?: { preview?: boolean; previewMs?: number; threshold?: number }): PlanDrag;
+  createPanel(editor: PlanEditor, options?: PlanPanelOptions): PlanPanel;
+  /** Adds the panel's stylesheet (the `.smap-plan-*` rules of smap.css) to a document once. */
+  injectCss(doc: Document): void;
+  /** The panel's texts in a language, with own texts over them. */
+  textsFor(language: string, labels?: Partial<Record<PlanTextKey, string>>): Record<PlanTextKey, string>;
+  /** The panel's language for a BCP-47 tag. */
+  panelLanguage(tag: string): PlanLanguage;
+  /** An encoded polyline (precision 5) as [[lng, lat], …]. */
+  decodePolyline(text: string, precision?: number): Array<[number, number]>;
+  /** The route colours, one per vehicle in the plan's order (repeated). */
+  colors: string[];
+}
+/** The parts of the plan editor for bindings on other map libraries. */
+export declare const planEditorParts: PlanEditorParts;
+
 declare const sMap: {
   Map: typeof Map;
   version: string;
@@ -584,5 +1003,8 @@ declare const sMap: {
   parseWmtsCapabilities: typeof parseWmtsCapabilities;
   PMTilesArchive: typeof PMTilesArchive;
   useDeck: typeof useDeck;
+  PlanEditor: typeof PlanEditor;
+  planTexts: typeof planTexts;
+  planEditorParts: typeof planEditorParts;
 };
 export default sMap;