@superrouteca/smap 1.1.7 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap",
-  "version": "1.1.7",
+  "version": "1.2.1",
   "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

@@ -166,6 +166,66 @@ interface CommonLayerOptions {
   /** In 3D, W / S tilt and A / D turn the view while the map has focus (default true). */
   keyboard3D?: boolean;
   onClick?: (feature: GeoJSONFeature, event: LayerClickEvent) => void;
+  /**
+   * The map's one tooltip while the pointer is over a feature of this layer: beside a point (or custom marker), at the
+   * pointer on lines and areas. A string is a template as for `popup`; a function returns trusted HTML or a node.
+   */
+  tooltip?: string | ((properties: Record<string, unknown>, feature: GeoJSONFeature) => string | Node | null | undefined);
+  tooltipOptions?: TooltipOptions;
+}
+
+export interface TooltipOptions {
+  /** Where the tooltip sits (default 'top'). */
+  direction?: 'top' | 'bottom' | 'left' | 'right';
+  /** [x, y] pixels added to its place. */
+  offset?: [number, number];
+  className?: string;
+}
+
+/** Where a dragged feature is: [lng, lat], the point in the map in pixels, and the pointer event. */
+export interface DragEvent {
+  lngLat: [number, number];
+  point: { x: number; y: number };
+  originalEvent?: Event;
+}
+
+/** Dragging points and custom markers (G2). The map does not pan while a feature is dragged. */
+interface DragOptions {
+  /** true, or per feature (a function of the properties, or `{ property }`). Default false. */
+  draggable?: boolean | ((properties: Record<string, unknown>, feature: GeoJSONFeature) => boolean) | { property: string; default?: boolean };
+  onDragStart?: (feature: GeoJSONFeature, event: DragEvent) => void;
+  onDrag?: (feature: GeoJSONFeature, event: DragEvent) => void;
+  /** After the release: the layer's data holds the new position (a copy; the objects you gave are not changed). */
+  onDragEnd?: (feature: GeoJSONFeature, event: DragEvent) => void;
+}
+
+/** A value read per feature in JavaScript: a constant, a function of the properties, or `{ property, default }`. */
+export type FeatureValue<T> = T | ((properties: Record<string, unknown>, feature: GeoJSONFeature) => T) | { property: string; default?: T };
+
+/** Custom markers (G1): the caller's own element at each point, laid out above the drawn layers while in view. */
+export interface CustomMarkerOptions extends DragOptions {
+  /** The element of one feature: an element, or trusted HTML (inserted as is, never sanitized). Called when the feature first comes into view and again when its properties change. */
+  render: (properties: Record<string, unknown>, feature: GeoJSONFeature) => Node | string;
+  /** Which point of the element is at the position (default 'center'). */
+  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  /** [x, y] pixels added to the place. */
+  offset?: [number, number];
+  /** Classes added to every marker's element (each sits in a `div.smap-marker`). */
+  className?: string;
+  opacity?: FeatureValue<number>;
+  /** Higher draws on top within the layer; layers draw in their own order. */
+  zIndex?: FeatureValue<number>;
+  /** The property naming each feature (getMarker, and keeping elements across setData); else the feature's id, else '#<index>'. */
+  idProperty?: string;
+  /** The marker under the pointer comes to the front. */
+  riseOnHover?: boolean;
+  minzoom?: number;
+  maxzoom?: number;
+  onClick?: (feature: GeoJSONFeature, event: { originalEvent: Event; lngLat: [number, number] }) => void;
+  popup?: CommonLayerOptions['popup'];
+  popupOptions?: PopupOptions;
+  tooltip?: CommonLayerOptions['tooltip'];
+  tooltipOptions?: TooltipOptions;
 }
 
 /**
@@ -197,7 +257,7 @@ export interface MarkerOptions {
   scale?: number | unknown[];
   /** The pin under the pointer comes to the front (default true). */
   hoverRaise?: boolean;
-  /** From this zoom on (default 13) the number is drawn into the pin, so an upper pin covers a lower one completely; false keeps it a separate layer. */
+  /** Numbers and badges are drawn into each pin, so an upper pin covers a lower one with them. A zoom keeps them their own layers above the pins further out (fewer images where thousands of pins are in view); false keeps them apart at every zoom. */
   bakeZoom?: number | false;
   /**
    * Pins piled up under a click (default on): with `threshold` (4) or more within `radius` (12 px) the map zooms in by
@@ -212,11 +272,164 @@ export interface MarkerOptions {
   badgeMinzoom?: number;
 }
 
-export interface PointOptions extends CommonLayerOptions {
+export type DrawShape = 'polygon' | 'rectangle' | 'circle' | 'line' | 'point';
+
+export interface DrawToolOptions {
+  /** Shapes to start from (each keeps its id, or gets one). */
+  features?: LayerData;
+  /** The shapes offered (default all). */
+  modes?: DrawShape[];
+  /** A new or moved vertex within 10 px of another shape's vertex takes its place (default true). */
+  snap?: boolean;
+  /** The toolbar's corner, or false for none (default 'top-left'). */
+  toolbar?: false | Exclude<ToolPosition, 'none'>;
+  /** The toolbar's texts (English by default). */
+  labels?: Partial<Record<DrawShape | 'hole' | 'delete' | 'undo' | 'redo' | 'finish' | 'cancel', string>>;
+  /** Colour of the shapes (default '#2563eb'); a shape's own `fill` / `stroke` properties win. */
+  color?: string;
+  onChange?: (event: DrawEvent) => void;
+}
+
+export interface DrawEvent {
+  type: 'created' | 'edited' | 'deleted';
+  feature: GeoJSONFeature | null;
+  /** Every shape after the change. */
+  features: GeoJSONFeatureCollection;
+}
+
+/**
+ * Click to add vertices (a click on the first, a double click or Enter finishes; Backspace removes the last; Escape
+ * cancels); drag for rectangles and circles. A selected shape: drag a vertex, drag a midpoint to add one, drag the
+ * shape to move it, Delete removes the selected vertex or shape; Ctrl/⌘+Z undoes, with Shift redoes. A circle is kept
+ * as a 64-point polygon with properties { shape: 'circle', center, radius (metres) }, a rectangle with { shape: 'rectangle' }.
+ */
+export interface DrawTool {
+  readonly id: string;
+  start(shape: DrawShape | 'hole'): this;
+  cancel(): this;
+  select(id: string | number | null): this;
+  selection(): string | number | null;
+  delete(id?: string | number): this;
+  undo(): this;
+  redo(): this;
+  getAll(): GeoJSONFeatureCollection;
+  get(id: string | number): GeoJSONFeature | null;
+  /** Replaces every shape (clears undo). */
+  set(data: LayerData): this;
+  on(type: 'created' | 'edited' | 'deleted' | 'change', handler: (event: DrawEvent) => void): this;
+  off(type: 'created' | 'edited' | 'deleted' | 'change', handler: (event: DrawEvent) => void): this;
+  destroy(): void;
+}
+
+export interface GoogleBaseOptions {
+  /** A Map Tiles API session your server made with your Google key, and that key. */
+  session?: string;
+  key?: string;
+  /** Or the tile URL template and the viewport address (both carrying session and key). */
+  tiles?: string;
+  viewport?: string;
+  type?: 'roadmap' | 'satellite';
+  /** Highest zoom of Google's tiles (default 22). */
+  maxzoom?: number;
+  /** Keep the street map's labels over Google's imagery (default false). */
+  labels?: boolean;
+  /** Called when Google's first tiles fail and none loads. */
+  onFail?: () => void;
+}
+
+export interface ModelOptions extends Placement {
+  /** A .glb or .gltf URL. */
+  model: string;
+  /** Metres per model unit (default 1), or per feature. */
+  size?: FeatureValue<number>;
+  /** Degrees clockwise from north (default 0), or per feature. */
+  heading?: FeatureValue<number>;
+  /** Metres above the ground (default 0), or per feature. */
+  altitude?: FeatureValue<number>;
+  /** [x, y, z] degrees turning the model upright and to face north (default [90, 0, 180]: up +Y, front +Z). */
+  rotate?: [number, number, number];
+  idProperty?: string;
+  minzoom?: number;
+  zIndex?: number;
+}
+
+export interface HeatmapOptions extends Placement {
+  /** A number, or per feature ({ property } or an expression). Default 1. */
+  weight?: StyleValue<number>;
+  /** Pixels (default 20), or an expression of the zoom. */
+  radius?: number | unknown[];
+  intensity?: number | unknown[];
+  opacity?: number;
+  /** Colours from low to high, or [[density 0–1, colour], …]. */
+  colors?: string[] | Array<[number, string]>;
+  minzoom?: number;
+  maxzoom?: number;
+  zIndex?: number;
+}
+
+export interface TerrainOptions {
+  /** Elevation tile URLs with {z}, {x}, {y}. */
+  tiles: string[];
+  /** How heights are packed into the tiles (default 'terrarium'). */
+  encoding?: 'terrarium' | 'mapbox';
+  tileSize?: number;
+  /** The highest zoom of the tiles (default 15). */
+  maxzoom?: number;
+  attribution?: string;
+  /** Heights times this (default 1). */
+  exaggeration?: number;
+  /** Shading of slopes, under the roads (default on). */
+  hillshade?: boolean | { exaggeration?: number; shadow?: string; highlight?: string };
+}
+
+/** Geometry helpers (G14). Positions are [lng, lat], {lng, lat} or a Point. */
+export interface Geo {
+  distance(a: unknown, b: unknown): number;
+  length(line: Array<[number, number]> | GeoJSONFeature | Record<string, unknown>): number;
+  bounds(geojson: unknown): [[number, number], [number, number]] | null;
+  pointInPolygon(point: unknown, polygon: unknown): boolean;
+  nearestPointOnLine(line: unknown, point: unknown): { point: [number, number]; distance: number; index: number; along: number } | null;
+  distanceToLine(line: unknown, point: unknown): number;
+  decodePolyline(encoded: string, precision?: number): Array<[number, number]>;
+  encodePolyline(coordinates: Array<[number, number]>, precision?: number): string;
+}
+
+/** A cluster as `cluster.html` and `cluster.tooltip` see it. */
+export interface ClusterInfo {
+  id: number;
+  count: number;
+  /** The engine's cluster properties (cluster_id, point_count, point_count_abbreviated, …). */
+  properties: Record<string, unknown>;
+  lngLat: [number, number];
+  /** The points inside the cluster (all of them, or the first `limit`). */
+  leaves(limit?: number): Promise<GeoJSONFeature[]>;
+}
+
+export interface ClusterOptions {
+  /** Pixels within which points are grouped (default 50). */
+  radius?: number;
+  /** The last zoom with clusters (default 14); from the next zoom on every point is drawn on its own. */
+  maxZoom?: number;
+  ring?: string | { property: string; limit?: number; color?: string };
+  html?: (cluster: ClusterInfo) => Node | string;
+  /** Classes of each cluster element (with ring or html). */
+  className?: string;
+  /** A click on a cluster zooms in to where it splits (default true). */
+  zoomOnClick?: boolean;
+  onClick?: (feature: GeoJSONFeature, event: { originalEvent: Event; lngLat: [number, number] }) => void;
+  tooltip?: (cluster: ClusterInfo) => string | Node | null | undefined;
+}
+
+export interface PointOptions extends CommonLayerOptions, DragOptions {
   /** Route-map pins instead of circles or an icon. */
   marker?: MarkerOptions;
-  /** Groups nearby points into circles sized by their count; a click zooms in to split them. */
-  cluster?: boolean | { radius?: number; maxZoom?: number };
+  /**
+   * Groups nearby points into circles sized by their count; a click zooms in to split them. With `ring` or `html` the
+   * clusters are drawn as elements: `ring` (a property name, or `{ property, limit, color }`) draws the count inside a
+   * ring of the points' colours, each colour's share of the points (read from at most `limit`, default 500); `html`
+   * draws each cluster yourself.
+   */
+  cluster?: boolean | ClusterOptions;
   clusterColor?: string;
   color?: string;
   radius?: number;
@@ -245,6 +458,10 @@ export interface LineOptions extends CommonLayerOptions {
   shadow?: boolean | { color?: StyleValue; width?: number; opacity?: number };
   /** Arrowheads along the line in its direction (true: every 80 px, 14 px, the line's colour, opacity 0.8). */
   arrows?: boolean | { spacing?: number; size?: number; color?: StyleValue; opacity?: number };
+  /** A property written along each line as a permanent label (repeated every `labelSpacing` px, default 250). */
+  label?: string;
+  labelSpacing?: number;
+  labelColor?: StyleValue;
 }
 
 export interface PolygonOptions extends CommonLayerOptions {
@@ -265,6 +482,13 @@ export interface BuildingsOptions {
 export interface MapOptions {
   /** The element (or its id) the map is drawn in. */
   container: string | HTMLElement;
+  /**
+   * 'auto' (default): the WebGL map, or the canvas map where the browser has no WebGL 2 (or refuses a WebGL context):
+   * sMap's raster tiles of the same scheme with every layer drawn in 2D, through the same calls. 'webgl' never falls
+   * back; 'canvas' always draws in 2D. Without WebGL the map does not tilt or turn and has no 3D buildings, terrain,
+   * hillshade or 3D models; the map fires 'smap.unsupported' with { feature } for each of them that is asked for.
+   */
+  renderer?: 'auto' | 'webgl' | 'canvas';
   /** A map token; or */
   token?: string;
   /** Called at start and again two minutes before each token expires. */
@@ -301,13 +525,40 @@ export interface MapOptions {
 /** 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 type ToolKind = 'navigation' | 'geolocate' | 'fullscreen' | 'scale' | 'zoom' | 'compass' | 'locate' | 'layers';
 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>;
+  /**
+   * Options of a kind's control: the engine control's (e.g. `{ showCompass: false }` for navigation, `{ container }`
+   * for full screen of a page element), or `LayersControlOptions` for 'layers'.
+   */
+  options?: Record<string, unknown> | LayersControlOptions;
+}
+
+/** Imagery in place of the street map (G8): drawn over land, water and roads, under the labels. */
+export interface BaseImagery {
+  /** Tile URLs with {z}, {x}, {y}. */
+  tiles: string[];
+  tileSize?: number;
+  minzoom?: number;
+  maxzoom?: number;
+  attribution?: string;
+  scheme?: 'xyz' | 'tms';
+  /** Keep the street map's labels on top (a hybrid map). Default false. */
+  labels?: boolean;
+}
+
+/** The layer switcher ('layers' tool): base maps one at a time, overlays each on or off. */
+export interface LayersControlOptions {
+  base?: Array<{ id: string; label?: string; style?: StyleFlavor | CustomStyleName | string | Record<string, unknown>; imagery?: BaseImagery }>;
+  overlays?: Array<{ id: string; label?: string; layers: string[]; visible?: boolean }>;
+  /** The base shown at first (default the first). */
+  value?: string;
+  /** The button's label (default 'Layers'). */
+  title?: string;
+  onChange?: (state: { base: string | null; overlays: string[] }) => void;
 }
 /** 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[] }
@@ -463,6 +714,8 @@ export declare class Map {
   readonly ready: Promise<Map>;
   /** The rendering engine's map, for anything the SDK does not wrap (set once `ready` resolves). */
   readonly engine: any;
+  /** The renderer in use: 'webgl', or 'canvas' without WebGL 2. */
+  readonly renderer: 'webgl' | 'canvas';
   setStyle(style: StyleFlavor | CustomStyleName | string | Record<string, unknown>): this;
   setLanguage(language: string): this;
   setProjection(projection: 'mercator' | 'globe'): this;
@@ -470,6 +723,26 @@ export declare class Map {
   addPoints(id: string, data: LayerData, options?: PointOptions): this;
   addLines(id: string, data: LayerData, options?: LineOptions): this;
   addPolygons(id: string, data: LayerData, options?: PolygonOptions): this;
+  /** A drawing and editing tool (G3): polygons, rectangles, circles, lines and points, holes, snapping, undo. */
+  drawTool(options?: DrawToolOptions): DrawTool;
+  /** Selects features by drawing a box or a lasso (G4); null when Escape cancels. */
+  selectArea(options?: { mode?: 'box' | 'lasso'; layers?: string[] }): Promise<{ features: Record<string, GeoJSONFeature[]>; geometry: Record<string, unknown> } | null>;
+  /** Google's base maps read straight from Google with your Map Tiles session (G10); null takes them off. */
+  setGoogleBase(google: GoogleBaseOptions | null): this;
+  /** glTF models at points, turned to each feature's heading (G12); needs sMap.useThree first. */
+  addModels(id: string, data: LayerData, options: ModelOptions): this;
+  /** A heat map of points (G7). */
+  addHeatmap(id: string, data: LayerData, options?: HeatmapOptions): this;
+  /** Relief over elevation tiles with hillshading (G11); null takes it off. */
+  setTerrain(terrain: TerrainOptions | null): this;
+  /** Keeps another sMap map on this map's view, both ways (G13); returns a function that ends it. */
+  syncWith(other: Map, options?: { offsetZoom?: number }): () => void;
+  /** Raster tiles drawn by the page (G14): draw paints one tile on a 2D context scaled to `size` CSS pixels. */
+  addCanvasTiles(id: string, draw: (ctx: CanvasRenderingContext2D, z: number, x: number, y: number, tile: { size: number; canvas: HTMLCanvasElement }) => void | Promise<void>, options?: RasterLayerOptions): this;
+  /** The caller's own element at each point (G1); setData keeps the element of every feature still there. */
+  addCustomMarkers(id: string, data: LayerData, options: CustomMarkerOptions): this;
+  /** The element of one custom marker (made now if it was not in view yet), or null. */
+  getMarker(id: string, key: string | number): HTMLElement | null;
   setData(id: string, data: LayerData): this;
   setVisible(id: string, visible: boolean): this;
   /** Removes a layer of any kind (an addData group whole, a helper layer with its source), or a source of addSource. */
@@ -538,6 +811,12 @@ export declare class Map {
    * 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.
    */
+  /** An element or engine control in a corner, not a tool (never hidden by the tools control). */
+  addControl(target: HTMLElement | { onAdd(map: any): HTMLElement; onRemove?(map: any): void }, position?: Exclude<ToolPosition, 'none'>): this;
+  removeControl(target: HTMLElement | { onAdd(map: any): HTMLElement; onRemove?(map: any): void }): this;
+  /** Imagery (satellite, aerial) in place of the street map; null goes back to the street map. */
+  setBaseImagery(imagery: BaseImagery | null): this;
+  baseImagery(): BaseImagery | null;
   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;
@@ -595,6 +874,8 @@ export interface Formats {
 export declare const formats: Formats;
 /** Converts a file on sMap (POST /v1/convert). */
 export declare function convert(input: FileInput | Blob, options?: ConvertOptions): Promise<GeoJSONFeatureCollection>;
+/** Geometry helpers: distance, length, bounds, point in polygon, nearest point on a line, encoded polylines. */
+export declare const geo: Geo;
 /** sMap's raster tiles of a style as an XYZ template, for tools without vector tiles. */
 export declare function rasterUrl(style: StyleFlavor | CustomStyleName, options?: RasterUrlOptions): string;
 /** The TileJSON address of sMap's raster tiles of a style. */
@@ -623,6 +904,8 @@ export declare class PMTilesArchive {
   tileJSON(): Promise<Record<string, unknown>>;
 }
 /** Registers deck.gl's map overlay module (`@deck.gl/mapbox`) for addDeckLayer. */
+/** Hands three.js and its GLTFLoader to the SDK for addModels (never bundled). */
+export declare function useThree(THREE: any, GLTFLoader: any): { THREE: any; GLTFLoader: any };
 export declare function useDeck(module: { MapboxOverlay: any } | { default: { MapboxOverlay: any } }): any;
 
 // ------------------------------------------------------------------ plan editor (OPEN-ROUTE-EDIT E10)
@@ -1017,6 +1300,7 @@ declare const sMap: {
   slots: Slot[];
   formats: Formats;
   convert: typeof convert;
+  geo: Geo;
   rasterUrl: typeof rasterUrl;
   rasterTileJsonUrl: typeof rasterTileJsonUrl;
   styleUrl: typeof styleUrl;
@@ -1026,6 +1310,7 @@ declare const sMap: {
   parseWmtsCapabilities: typeof parseWmtsCapabilities;
   PMTilesArchive: typeof PMTilesArchive;
   useDeck: typeof useDeck;
+  useThree: typeof useThree;
   PlanEditor: typeof PlanEditor;
   planTexts: typeof planTexts;
   planEditorParts: typeof planEditorParts;