@superrouteca/smap 1.0.6 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "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",
@@ -62,6 +62,14 @@
     "prepack": "cp ../LICENSE LICENSE",
     "test": "node --test test/*.test.mjs test/*.test.cjs"
   },
+  "peerDependencies": {
+    "@deck.gl/mapbox": "^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@deck.gl/mapbox": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "esbuild": "0.28.2",
     "maplibre-gl": "6.16.0"

package/types/smap.d.cts

@@ -2,6 +2,74 @@
 // smap.d.cts hold the same text (test/types.test.mjs checks).
 
 export type StyleFlavor = 'light' | 'white' | 'grayscale' | 'dark' | 'black';
+/** A saved custom style of sMap (`custom:sms_…`), served in every label language. */
+export type CustomStyleName = `custom:${string}`;
+
+/**
+ * Where a layer is drawn relative to the basemap: `bottom` (over land and water, under everything else), `roads`
+ * (under roads), `labels` (under labels), `top`. Without a slot (or `before`) a layer draws as in 1.0: on top, in the
+ * order added.
+ */
+export type Slot = 'bottom' | 'roads' | 'labels' | 'top';
+
+/** Where a layer goes: a slot, or under one named layer (yours or the basemap's), and its order inside. */
+export interface Placement {
+  slot?: Slot;
+  /** A layer id to draw under, instead of a slot. */
+  before?: string;
+  /** Higher draws on top inside the same slot; equal values keep the order added. */
+  zIndex?: number;
+}
+
+/** A source of the Style Specification v8 (geojson, vector, raster, raster-dem, image, video). */
+export interface StyleSource { type: string; attribution?: string; [key: string]: unknown }
+/** A layer of the Style Specification v8, passed to the engine as it is. */
+export interface StyleLayer { id: string; type: string; source?: string | StyleSource; 'source-layer'?: string; paint?: Record<string, unknown>; layout?: Record<string, unknown>; filter?: unknown; minzoom?: number; maxzoom?: number; [key: string]: unknown }
+
+/** One basemap class's override (contract §1): every field optional. */
+export interface BasemapOverride {
+  visible?: boolean;
+  /** Fill, line or background colour; text colour for labels (never casings). */
+  color?: string;
+  /** Casing colour (roads). */
+  casing?: string;
+  /** Text halo colour (labels). */
+  halo?: string;
+  /** 0 to 1. */
+  opacity?: number;
+  /** Line width factor, 0.25 to 4. */
+  width?: number;
+}
+export type BasemapClass = 'land' | 'landcover' | 'parks' | 'landuse' | 'airports' | 'water' | 'roads' | 'roads.paths' | 'roads.minor' | 'roads.major' |
+  'roads.highway' | 'buildings' | 'rail' | 'boundaries' | 'labels' | 'labels.addresses' | 'labels.water' | 'labels.roads' | 'labels.places' | 'pois';
+/** Basemap overrides by class; `roads` and `labels` apply to every `roads.*` / `labels.*` class (the class itself wins). */
+export type BasemapOverrides = Partial<Record<BasemapClass, BasemapOverride>>;
+/** The class table (shared/basemap-classes.json). */
+export interface BasemapClassTable {
+  paint: Record<string, Record<string, string>>;
+  classes: Record<string, Array<{ layer: string; role: 'background' | 'fill' | 'line' | 'casing' | 'label' }>>;
+}
+
+/** File formats read on the device and by sMap's converting endpoint. */
+export type FileFormat = 'kml' | 'kmz' | 'gpx' | 'polyline' | 'polyline6' | 'wkt' | 'wkb' | 'csv' | 'topojson' | 'geojson';
+/** What a file is read from: text, bytes, or a parsed JSON object (GeoJSON, TopoJSON). */
+export type FileInput = string | ArrayBuffer | Uint8Array | Record<string, unknown>;
+export interface ReadOptions {
+  /** Guessed from `name`'s extension or the content when omitted (polylines are never guessed). */
+  format?: FileFormat;
+  /** CSV latitude column (guessed from common headings when omitted). */
+  lat?: string;
+  /** CSV longitude column. */
+  lng?: string;
+  /** A file name, for its extension. */
+  name?: string;
+}
+export interface ConvertOptions extends ReadOptions {
+  /** The map service (default https://tile.srsr.ca; a map's own address for map.convert). */
+  baseUrl?: string;
+  apiKey?: string;
+  token?: string;
+}
 
 /** A position as [longitude, latitude]. */
 export type LngLatLike = [number, number] | { lng: number; lat: number } | { lon: number; lat: number };
@@ -79,11 +147,16 @@ interface CommonLayerOptions {
   maxzoom?: number;
   /** A feature property used as the feature id. */
   idProperty?: string;
+  /** A slot (`bottom`, `roads`, `labels`, `top`); without one (or `before`) the layer draws on top, as in 1.0. */
+  slot?: Slot;
+  /** A layer id to draw under, instead of a slot. */
+  before?: string;
   /**
    * The popup opened when the top feature at a click is this layer's; called only then. A point's popup opens at the
-   * point, a line's or area's where it was clicked. `popupTemplate('<b>{name}</b>')` gives a fast, escaped one.
+   * point, a line's or area's where it was clicked. A string is a template (`'<b>{name}</b>'`, as popupTemplate:
+   * every {name} the feature's property, HTML-escaped), and the one form written by toJSON.
    */
-  popup?: (properties: Record<string, unknown>, feature: GeoJSONFeature) => PopupContent | Promise<PopupContent>;
+  popup?: string | ((properties: Record<string, unknown>, feature: GeoJSONFeature) => PopupContent | Promise<PopupContent>);
   /** This layer's popup options, over the map's `popup` defaults. */
   popupOptions?: PopupOptions;
   /** Shown while this layer's popup content is a pending promise (HTML string or DOM node; default pulsing dots). */
@@ -198,8 +271,8 @@ export interface MapOptions {
   getToken?: () => string | Promise<string>;
   /** A map key (`smk_…`) whose allowlist names this site; with a token both are sent and the token is checked first. */
   apiKey?: string;
-  /** A colour scheme, or a style URL or object of your own. */
-  style?: StyleFlavor | string | Record<string, unknown>;
+  /** A colour scheme, a saved custom style (`custom:<id>`), or a style URL or object of your own. */
+  style?: StyleFlavor | CustomStyleName | string | Record<string, unknown>;
   /** Label language as a BCP-47 tag (`en`, `fr`, `zh-Hans`, …); the browser language by default. */
   language?: string;
   /** The map service, `https://tile.srsr.ca` by default. */
@@ -223,6 +296,115 @@ export interface MapOptions {
   [engineOption: string]: unknown;
 }
 
+/** addData: how the file is read, then the options of addPoints / addLines / addPolygons for its parts. */
+export type DataOptions = ReadOptions & PointOptions & LineOptions & PolygonOptions;
+
+export interface RasterLayerOptions extends Placement {
+  /** XYZ templates ({z}/{x}/{y}). */
+  tiles?: string | string[];
+  /** An XYZ template, or a TileJSON address. */
+  url?: string;
+  /** Default 256. */
+  tileSize?: number;
+  /** Shown beside the map's credit. */
+  attribution?: string;
+  opacity?: number;
+  minzoom?: number;
+  maxzoom?: number;
+  bounds?: [number, number, number, number];
+  scheme?: 'xyz' | 'tms';
+}
+export interface WmsLayerOptions extends Placement {
+  url: string;
+  layers: string | string[];
+  styles?: string | string[];
+  /** Default image/png. */
+  format?: string;
+  /** Default true. */
+  transparent?: boolean;
+  /** Default 1.3.0 (CRS=EPSG:3857); 1.1.1 sends SRS. */
+  version?: '1.3.0' | '1.1.1';
+  /** More GetMap parameters. */
+  params?: Record<string, string | number>;
+  tileSize?: number;
+  attribution?: string;
+  opacity?: number;
+  minzoom?: number;
+  maxzoom?: number;
+}
+export interface WmtsLayerOptions extends Placement {
+  /** The GetCapabilities address (or the service address), or a REST template with {TileMatrix}, {TileRow}, {TileCol}. */
+  url?: string;
+  /** The capabilities document as text, instead of fetching `url`. */
+  capabilities?: string;
+  layer?: string;
+  /** A Web Mercator matrix set (found from the capabilities when omitted). */
+  tileMatrixSet?: string;
+  style?: string;
+  format?: string;
+  /** REST (the layer's resource template) or KVP (GetTile); REST when the capabilities offer it. */
+  encoding?: 'rest' | 'kvp';
+  attribution?: string;
+  opacity?: number;
+  minzoom?: number;
+  maxzoom?: number;
+}
+export interface VectorTilesOptions extends Placement {
+  /** Mapbox Vector Tile templates. */
+  tiles?: string | string[];
+  /** A TileJSON address, or a PMTiles archive (ending in .pmtiles or pmtiles://…). */
+  url?: string;
+  /** A PMTiles archive address. */
+  pmtiles?: string;
+  /** Style layers drawing the tiles; their `source` is this id when they name none. */
+  layers?: StyleLayer[];
+  attribution?: string;
+  minzoom?: number;
+  maxzoom?: number;
+  bounds?: [number, number, number, number];
+  promoteId?: string | Record<string, string>;
+}
+export interface ArcGisLayerOptions extends Placement {
+  /** A MapServer / ImageServer (raster tiles) or VectorTileServer address. */
+  url: string;
+  /** VectorTileServer: style layers (the service's own root style when omitted). */
+  layers?: StyleLayer[];
+  /** The service's copyright text when omitted. */
+  attribution?: string;
+  opacity?: number;
+  minzoom?: number;
+  maxzoom?: number;
+}
+
+/** The shared layer description (shared/LAYER-JSON.md). */
+export interface LayerDescription {
+  type: 'smap.layers';
+  version: 1;
+  basemap?: { style?: StyleFlavor | CustomStyleName; language?: string; overrides?: BasemapOverrides };
+  sources?: Record<string, StyleSource>;
+  layers: Array<{
+    id: string;
+    kind: 'points' | 'lines' | 'polygons' | 'style';
+    slot?: Slot;
+    before?: string;
+    zIndex?: number;
+    visible?: boolean;
+    group?: string;
+    data?: GeoJSONFeatureCollection;
+    options?: Record<string, unknown>;
+    layer?: StyleLayer;
+  }>;
+}
+
+export interface RasterUrlOptions {
+  /** Label language. */
+  lang?: string;
+  /** 512 px tiles (@2x). */
+  retina?: boolean;
+  baseUrl?: string;
+  apiKey?: string;
+}
+
 export interface FlyToOptions {
   center?: LngLatLike;
   zoom?: number;
@@ -246,7 +428,7 @@ 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;
-  setStyle(style: StyleFlavor | string | Record<string, unknown>): this;
+  setStyle(style: StyleFlavor | CustomStyleName | string | Record<string, unknown>): this;
   setLanguage(language: string): this;
   setProjection(projection: 'mercator' | 'globe'): this;
   setBuildings3D(on: boolean, options?: BuildingsOptions): this;
@@ -255,9 +437,58 @@ export declare class Map {
   addPolygons(id: string, data: LayerData, options?: PolygonOptions): this;
   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. */
   removeLayer(id: string): this;
   /** Layer ids in draw order, bottom first. */
   layers(): string[];
+  /** Adds a Style Specification v8 source, kept across style and language changes. */
+  addSource(id: string, source: StyleSource): this;
+  /** Removes a source and the style layers that read it. */
+  removeSource(id: string): this;
+  /** The sources added with addSource. */
+  sources(): Record<string, StyleSource>;
+  /** Adds a Style Specification v8 layer as it is; without a slot or `before` it draws on top. */
+  addStyleLayer(layer: StyleLayer, placement?: Placement): this;
+  setPaint(layerId: string, name: string, value: unknown): this;
+  setLayout(layerId: string, name: string, value: unknown): this;
+  /** null clears the filter. */
+  setFilter(layerId: string, filter: unknown[] | null): this;
+  /** A style layer (yours or the basemap's) as a Style Specification object; null when there is none. */
+  getStyleLayer(layerId: string): StyleLayer | null;
+  /** Where each slot begins in the current basemap (layer ids; `top` is undefined). */
+  slots(): Record<Slot, string | undefined>;
+  /** Shows, hides and recolours the basemap by class; replaces the previous overrides ({} clears them). */
+  setBasemap(overrides: BasemapOverrides): this;
+  /** The basemap overrides in force. */
+  basemap(): BasemapOverrides;
+  /** Reads a file and draws it as `<id>` (points), `<id>:lines` and `<id>:areas`. */
+  addData(id: string, input: FileInput | Blob, options?: DataOptions): Promise<this>;
+  /** A layer's features (an addData group together) as GeoJSON. */
+  toGeoJSON(layerId: string): GeoJSONFeatureCollection;
+  /** A layer's features as a KML document. */
+  toKML(layerId: string): string;
+  /** Converts a file on sMap (POST /v1/convert) with this map's address, key and token. */
+  convert(input: FileInput | Blob, options?: ConvertOptions): Promise<GeoJSONFeatureCollection>;
+  /** sMap's raster tiles of a style (default the map's own) as a {z}/{x}/{y} template on this map's node and key. */
+  rasterUrl(style?: StyleFlavor | CustomStyleName, options?: Pick<RasterUrlOptions, 'lang' | 'retina'>): string;
+  addRasterLayer(id: string, options: RasterLayerOptions): this;
+  addWmsLayer(id: string, options: WmsLayerOptions): this;
+  addWmtsLayer(id: string, options: WmtsLayerOptions): Promise<this>;
+  addVectorTiles(id: string, options: VectorTilesOptions): this;
+  addArcGisLayer(id: string, options: ArcGisLayerOptions): Promise<this>;
+  /** The map's layers as the shared layer description. */
+  toJSON(): LayerDescription;
+  /** Loads a layer description (an object or its text). */
+  loadLayers(json: LayerDescription | string): this;
+  /** A deck.gl layer drawn interleaved with the basemap (load deck.gl first with useDeck). */
+  addDeckLayer(layer: any, placement?: Pick<Placement, 'slot' | 'before'>): this;
+  removeDeckLayer(id: string): this;
+  deckLayers(): any[];
+  /**
+   * The map's deck.gl overlay (MapboxOverlay), made on first use; `props` are other deck.gl props (getTooltip,
+   * onClick, pickingRadius, …). Null before the map is ready or when deck.gl is not loaded.
+   */
+  deckOverlay(props?: Record<string, unknown>): any | null;
   fitLayer(id: string, options?: FitOptions): this;
   flyTo(options: FlyToOptions): this;
   /** Opens the map's popup at a position, closing the one open before (one popup per map). */
@@ -284,11 +515,74 @@ export declare function getEngine(): any;
  */
 export declare function popupTemplate(template: string): (properties: Record<string, unknown> | null | undefined, feature?: GeoJSONFeature) => string;
 
+/** The slot names. */
+export declare const slots: Slot[];
+
+export interface Formats {
+  list: FileFormat[];
+  /** Reads a file into a FeatureCollection, on the device. */
+  read(input: FileInput, options?: ReadOptions): GeoJSONFeatureCollection;
+  /** Reads a Blob or File (the format from its name when not given). */
+  readFile(file: Blob & { name?: string }, options?: ReadOptions): Promise<GeoJSONFeatureCollection>;
+  /** Writes GeoJSON text or a KML document. */
+  write(data: LayerData, format: 'geojson' | 'kml', options?: { name?: string }): string;
+  toKML(data: LayerData, options?: { name?: string }): string;
+  sniff(input: FileInput): FileFormat | null;
+  formatOfName(name: string): FileFormat | null;
+  decodePolyline(text: string, precision?: number): Array<[number, number]>;
+  encodePolyline(coordinates: Array<[number, number] | number[]>, precision?: number): string;
+}
+/** File formats read on the device (KML, KMZ, GPX, polylines, WKT, WKB, CSV, TopoJSON, GeoJSON). */
+export declare const formats: Formats;
+/** Converts a file on sMap (POST /v1/convert). */
+export declare function convert(input: FileInput | Blob, options?: ConvertOptions): Promise<GeoJSONFeatureCollection>;
+/** 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. */
+export declare function rasterTileJsonUrl(style: StyleFlavor | CustomStyleName, options?: RasterUrlOptions): string;
+/** The style URL of a scheme or a custom style. */
+export declare function styleUrl(style: StyleFlavor | CustomStyleName, options?: { lang?: string; baseUrl?: string; apiKey?: string }): string;
+/** A style with basemap overrides applied (a copy); throws on an unknown class or field. */
+export declare function applyBasemapOverrides<S extends { layers?: StyleLayer[] }>(style: S, overrides: BasemapOverrides | null | undefined, table?: BasemapClassTable): S;
+/** The basemap class table. */
+export declare function basemapClasses(): BasemapClassTable;
+/** Where each slot begins in a list of basemap layer ids. */
+export declare function slotAnchors(layerIds: string[], table?: BasemapClassTable): Record<Slot, string | undefined>;
+export interface WmtsCapabilities {
+  layers: Array<{ id: string; title: string; styles: Array<{ id: string; isDefault: boolean }>; formats: string[]; tileMatrixSets: string[]; resourceUrls: Array<{ format: string; template: string }>; bounds: [number, number, number, number] | null }>;
+  tileMatrixSets: Record<string, { id: string; crs: string; wellKnown: string; matrices: Array<{ id: string; zoom: number; tileWidth: number }> }>;
+  getTile: string | null;
+}
+/** Reads WMTS 1.0.0 capabilities. */
+export declare function parseWmtsCapabilities(xml: string): WmtsCapabilities;
+/** A PMTiles v3 archive read by HTTP range requests. */
+export declare class PMTilesArchive {
+  constructor(url: string, fetchRange?: (url: string, offset: number, length: number) => Promise<Uint8Array | ArrayBuffer> | Uint8Array);
+  header(): Promise<Record<string, unknown>>;
+  metadata(): Promise<Record<string, unknown>>;
+  tile(z: number, x: number, y: number): Promise<Uint8Array | null>;
+  tileJSON(): Promise<Record<string, unknown>>;
+}
+/** Registers deck.gl's map overlay module (`@deck.gl/mapbox`) for addDeckLayer. */
+export declare function useDeck(module: { MapboxOverlay: any } | { default: { MapboxOverlay: any } }): any;
+
 declare const sMap: {
   Map: typeof Map;
   version: string;
   styles: StyleFlavor[];
   getEngine: typeof getEngine;
   popupTemplate: typeof popupTemplate;
+  slots: Slot[];
+  formats: Formats;
+  convert: typeof convert;
+  rasterUrl: typeof rasterUrl;
+  rasterTileJsonUrl: typeof rasterTileJsonUrl;
+  styleUrl: typeof styleUrl;
+  applyBasemapOverrides: typeof applyBasemapOverrides;
+  basemapClasses: typeof basemapClasses;
+  slotAnchors: typeof slotAnchors;
+  parseWmtsCapabilities: typeof parseWmtsCapabilities;
+  PMTilesArchive: typeof PMTilesArchive;
+  useDeck: typeof useDeck;
 };
 export default sMap;