@superrouteca/smap-leaflet 0.0.0-stage → 1.1.0

package/src/index.js

@@ -0,0 +1,304 @@
+// @superrouteca/smap-leaflet — sMap in Leaflet: the vector map (an sMap map drawn in a Leaflet pane, with sMap's
+// layers, popups and Auto Zoom) or raster tiles, and the sMap badge and data credit in Leaflet's corner.
+// Leaflet-style calls on an sMap map are in './compat.js' (`@superrouteca/smap-leaflet/compat`).
+import * as LeafletModule from 'leaflet';
+import * as sMapModule from '@superrouteca/smap';
+import { SMapAccess, checkStyle, rasterPath, stylePath, FLAVORS, DEFAULT_BASE } from './common/access.js';
+import { OSM_ATTRIBUTION, createBadge } from './common/badge.js';
+import { createEmbedded, hasWebGL2 } from './common/embed.js';
+
+// Leaflet's module build has named exports, its main build a default export: either works.
+const L = LeafletModule.default && LeafletModule.default.Layer ? LeafletModule.default : LeafletModule;
+const SDK = sMapModule.default && sMapModule.default.Map ? sMapModule.default : sMapModule;
+
+export const version = '1.1.0';
+export { FLAVORS as styles, checkStyle, rasterPath, stylePath, SMapAccess, DEFAULT_BASE, OSM_ATTRIBUTION };
+
+/** Options that belong to Leaflet, not to the sMap map. */
+const LEAFLET_OPTIONS = ['pane', 'interactive', 'sdk', 'attribution', 'zIndex', 'className'];
+/** Options of the service access (key, token, nodes); the rest of a raster layer's options go to Leaflet. */
+const ACCESS_OPTIONS = ['baseUrl', 'token', 'getToken', 'apiKey', 'nodes', 'nearest', 'fetch', 'timeoutMs', 'client'];
+
+function pick(o, keys, inside) {
+  const out = {};
+  Object.keys(o || {}).forEach(function (k) { if ((keys.indexOf(k) >= 0) === inside) { out[k] = o[k]; } });
+  return out;
+}
+
+// ------------------------------------------------------------------ badge (one per map)
+
+/** The sMap badge as a Leaflet control (bottom right, above the attribution). */
+export const SMapBadge = L.Control.extend({
+  options: { position: 'bottomright' },
+  onAdd: function (map) { return createBadge(map.getContainer().ownerDocument); },
+});
+
+function holdBadge(map) {
+  const held = map._smapBadge || (map._smapBadge = { control: null, count: 0 });
+  held.count += 1;
+  if (!held.control) { held.control = new SMapBadge().addTo(map); }
+}
+
+function releaseBadge(map) {
+  const held = map._smapBadge;
+  if (!held) { return; }
+  held.count -= 1;
+  if (held.count <= 0 && held.control) { held.control.remove(); held.control = null; held.count = 0; }
+}
+
+function setCredits(map, layer, list) {
+  const ac = map && map.attributionControl;
+  const before = layer._credits || [];
+  layer._credits = list || [];
+  if (!ac) { return; }
+  before.forEach(function (a) { ac.removeAttribution(a); });
+  layer._credits.forEach(function (a) { ac.addAttribution(a); });
+}
+
+// ------------------------------------------------------------------ vector: an sMap map in a pane
+
+/** sMap map calls a layer forwards once its map is ready (each returns the layer). */
+export const FORWARDED = ['setStyle', 'setLanguage', 'setBasemap', 'setAutoZoom', 'addPoints', 'addLines', 'addPolygons',
+  'addData', 'setData', 'setVisible', 'fitLayer', 'addSource', 'removeSource', 'addStyleLayer',
+  'setPaint', 'setLayout', 'setFilter', 'addRasterLayer', 'addWmsLayer', 'addWmtsLayer', 'addVectorTiles', 'addArcGisLayer',
+  'loadLayers'];
+
+/**
+ * The sMap vector map as a Leaflet layer. Options: every sMap map option (style incl. `custom:<id>`, language, apiKey,
+ * token, getToken, baseUrl, nodes, nearest, popup, popupLoading, autoZoom) plus `pane` (default `tilePane`) and
+ * `interactive` (Leaflet's clicks and pointer moves reach sMap's layers; default true).
+ */
+export const SMapLayer = L.Layer.extend({
+  options: { pane: 'tilePane', interactive: true },
+
+  initialize: function (options) {
+    options = options || {};
+    L.setOptions(this, pick(options, ['pane', 'interactive'], true));
+    this._sdk = options.sdk || SDK;
+    this._smapOptions = pick(options, LEAFLET_OPTIONS, false);
+    if (this._smapOptions.style !== undefined && typeof this._smapOptions.style === 'string' && this._smapOptions.style.indexOf('://') < 0) {
+      checkStyle(this._smapOptions.style);
+    }
+    const self = this;
+    this.ready = new Promise(function (resolve) { self._resolveReady = resolve; });
+    this._embedded = null;
+    this._credits = [];
+  },
+
+  onAdd: function (map) {
+    if (!this._container) {
+      this._container = L.DomUtil.create('div', 'leaflet-smap-layer' + (map._zoomAnimated ? ' leaflet-zoom-animated' : ''));
+      // A click on an open popup is the popup's: Leaflet neither drags nor closes it.
+      L.DomEvent.on(this._container, 'mousedown touchstart pointerdown click dblclick wheel contextmenu', function (e) {
+        const t = e.target;
+        if (t && t.closest && t.closest('.maplibregl-popup')) { L.DomEvent.stopPropagation(e); }
+      });
+    }
+    this.getPane().appendChild(this._container);
+    this._size();
+    if (!this._embedded) {
+      const self = this;
+      const c = map.getCenter();
+      this._embedded = createEmbedded(this._sdk, this._container, Object.assign({}, this._smapOptions, {
+        center: [c.lng, c.lat],
+        zoom: map.getZoom() - 1,
+      }), {
+        move: function (t, how) { self._moveLeaflet(t, how); },
+        attribution: function (list) { setCredits(self._map, self, list); },
+        cursor: function (cursor) { if (self._map) { self._map.getContainer().style.cursor = cursor; } },
+      });
+      this._embedded.ready.then(function (m) { self._update(); self._resolveReady(m); });
+    } else {
+      this._embedded.resize();
+    }
+    holdBadge(map);
+    setCredits(map, this, this._embedded.credits().length ? this._embedded.credits() : [OSM_ATTRIBUTION]);
+    this._update();
+  },
+
+  onRemove: function (map) {
+    setCredits(map, this, []);
+    this._credits = [];
+    releaseBadge(map);
+    if (this._container && this._container.parentNode) { this._container.parentNode.removeChild(this._container); }
+  },
+
+  getEvents: function () {
+    const ev = { viewreset: this._update, move: this._update, moveend: this._update, zoom: this._update, zoomend: this._update, resize: this._resize };
+    if (this._map && this._map._zoomAnimated) { ev.zoomanim = this._animateZoom; }
+    if (this.options.interactive) {
+      ev.click = this._forward;
+      ev.dblclick = this._forward;
+      ev.contextmenu = this._forward;
+      ev.mousemove = this._forward;
+      ev.mouseout = this._forwardOut;
+    }
+    return ev;
+  },
+
+  /** The sMap map (null until it is ready); `await layer.ready` gives it once it is. */
+  getSMap: function () { return this._embedded && this._embedded.engine() ? this._embedded.map : null; },
+
+  /** Removes the layer from its map and deletes the sMap map. */
+  destroy: function () {
+    if (this._map) { this.remove(); }
+    if (this._embedded) { this._embedded.remove(); this._embedded = null; }
+    return this;
+  },
+
+  /** sMap map calls whose answer is a value: `layer.call('basemap')` resolves to it. */
+  call: function (name) {
+    const args = Array.prototype.slice.call(arguments, 1);
+    return this.ready.then(function (m) {
+      if (typeof m[name] !== 'function') { throw new Error('sMap: this version of @superrouteca/smap has no ' + name + '()'); }
+      return m[name].apply(m, args);
+    });
+  },
+
+  _size: function () {
+    const size = this._map.getSize();
+    this._container.style.width = size.x + 'px';
+    this._container.style.height = size.y + 'px';
+  },
+
+  _resize: function () {
+    this._size();
+    if (this._embedded) { this._embedded.resize(); }
+    this._update();
+  },
+
+  _update: function () {
+    const map = this._map;
+    if (!map || !this._embedded || map._animatingZoom) { return; }
+    L.DomUtil.setPosition(this._container, map.containerPointToLayerPoint([0, 0]));
+    const c = map.getCenter();
+    // Leaflet counts zoom in 256 px tiles, the sMap map in 512 px tiles: one level apart.
+    this._embedded.sync({ center: { lng: c.lng, lat: c.lat }, zoom: map.getZoom() - 1 });
+  },
+
+  _animateZoom: function (e) {
+    const map = this._map;
+    const scale = map.getZoomScale(e.zoom);
+    const offset = map._latLngBoundsToNewLayerBounds(map.getBounds(), e.zoom, e.center).min;
+    L.DomUtil.setTransform(this._container, offset, scale);
+  },
+
+  _forward: function (e) {
+    if (!this._embedded || !e.containerPoint || !e.latlng) { return; }
+    if (this._embedded.inPopup(e.originalEvent)) { return; }
+    this._embedded.forward(e.type, e.containerPoint.x, e.containerPoint.y, { lng: e.latlng.lng, lat: e.latlng.lat }, e.originalEvent);
+  },
+
+  _forwardOut: function (e) {
+    if (!this._embedded) { return; }
+    const c = this._map.getCenter();
+    this._embedded.forward('mouseout', -1, -1, { lng: c.lng, lat: c.lat }, e.originalEvent);
+  },
+
+  // The sMap map asked to move (Auto Zoom, fitLayer, flyTo, a popup panning into view): Leaflet moves, and the
+  // sMap map follows on Leaflet's move events.
+  _moveLeaflet: function (t, how) {
+    const map = this._map;
+    if (!map) { return; }
+    const latlng = L.latLng(t.center.lat, t.center.lng);
+    const zoom = t.zoom + 1;
+    const seconds = how.duration !== undefined ? how.duration / 1000 : undefined;
+    if (how.fly && how.animate) { map.flyTo(latlng, zoom, seconds !== undefined ? { duration: seconds } : {}); return; }
+    map.setView(latlng, zoom, how.animate ? { animate: true, duration: seconds } : { animate: false });
+  },
+});
+
+FORWARDED.forEach(function (name) {
+  SMapLayer.prototype[name] = function () {
+    const args = Array.prototype.slice.call(arguments);
+    if (name === 'setStyle' && typeof args[0] === 'string' && args[0].indexOf('://') < 0) { checkStyle(args[0]); }
+    this.call.apply(this, [name].concat(args)).catch(function (e) { if (typeof console !== 'undefined') { console.error(e); } });
+    return this;
+  };
+});
+// Leaflet's own openPopup / closePopup (a popup bound to the layer) stay Leaflet's; the sMap map's popup has its own names.
+/** Opens the sMap map's popup at [lng, lat]. */
+SMapLayer.prototype.openSMapPopup = function (lngLat, content, options) { this.call('openPopup', lngLat, content, options).catch(function () {}); return this; };
+/** Closes the sMap map's popup. */
+SMapLayer.prototype.closeSMapPopup = function () { this.call('closePopup').catch(function () {}); return this; };
+/** Removes one of the sMap map's layers (the sMap map's removeLayer; Leaflet's removeLayer belongs to the map). */
+SMapLayer.prototype.removeSMapLayer = function (id) { this.call('removeLayer', id).catch(function () {}); return this; };
+
+/** The sMap vector map as a Leaflet layer. */
+export function smapLayer(options) { return new SMapLayer(options); }
+
+// ------------------------------------------------------------------ raster tiles
+
+/**
+ * sMap raster tiles (256 px, or 512 px drawn for high-density screens) as a Leaflet grid layer: for browsers without
+ * WebGL, or wherever images are wanted. Tiles are read with the map key or token from the nearest node, moving to the
+ * next node when one fails. Options: style (a scheme or `custom:<id>`), language, retina (default: the screen's),
+ * the access options (apiKey, token, getToken, baseUrl, nodes, nearest) and Leaflet's grid layer options.
+ */
+export const SMapRasterLayer = L.GridLayer.extend({
+  initialize: function (options) {
+    options = options || {};
+    this._access = options.access || new SMapAccess(pick(options, ACCESS_OPTIONS, true));
+    this._style = checkStyle(options.style || 'light');
+    this._language = options.language || (typeof navigator !== 'undefined' && navigator.language) || 'en';
+    this._retina = options.retina !== undefined ? !!options.retina : (typeof window !== 'undefined' && window.devicePixelRatio > 1);
+    const rest = pick(options, ACCESS_OPTIONS.concat(['style', 'language', 'retina', 'access']), false);
+    if (rest.attribution === undefined) { rest.attribution = OSM_ATTRIBUTION; }
+    L.GridLayer.prototype.initialize.call(this, rest);
+  },
+
+  onAdd: function (map) {
+    L.GridLayer.prototype.onAdd.call(this, map);
+    holdBadge(map);
+  },
+
+  onRemove: function (map) {
+    releaseBadge(map);
+    L.GridLayer.prototype.onRemove.call(this, map);
+  },
+
+  createTile: function (coords, done) {
+    const tile = L.DomUtil.create('img', 'leaflet-tile');
+    tile.alt = '';
+    tile.setAttribute('role', 'presentation');
+    const access = this._access;
+    const style = this._style;
+    const o = { lang: this._language, retina: this._retina };
+    access.start()
+      .then(function () { return access.rasterTile(style, coords.z, coords.x, coords.y, o); })
+      .then(function (blob) {
+        const url = URL.createObjectURL(blob);
+        tile.onload = function () { URL.revokeObjectURL(url); done(null, tile); };
+        tile.onerror = function (e) { URL.revokeObjectURL(url); done(e || new Error('sMap: tile image failed'), tile); };
+        tile.src = url;
+      })
+      .catch(function (e) { done(e, tile); });
+    return tile;
+  },
+
+  /** Switches the scheme (or `custom:<id>`) and reloads the tiles. */
+  setStyle: function (style) { this._style = checkStyle(style); this.redraw(); return this; },
+  /** Switches the label language and reloads the tiles. */
+  setLanguage: function (language) { this._language = language; this.redraw(); return this; },
+  /** The access in use (token, nodes). */
+  getAccess: function () { return this._access; },
+});
+
+export function smapRasterLayer(options) { return new SMapRasterLayer(options); }
+
+/**
+ * The sMap basemap the browser can draw: the vector map where WebGL 2 exists, raster tiles elsewhere.
+ * `mode: 'vector' | 'raster' | 'auto'` (default auto).
+ */
+export function smapBasemap(options) {
+  const o = Object.assign({}, options);
+  const mode = o.mode || 'auto';
+  delete o.mode;
+  if (mode === 'raster' || (mode === 'auto' && !hasWebGL2())) { return new SMapRasterLayer(o); }
+  return new SMapLayer(o);
+}
+
+export { hasWebGL2 };
+
+const SMapLeaflet = { version, styles: FLAVORS, SMapLayer, smapLayer, SMapRasterLayer, smapRasterLayer, smapBasemap, SMapBadge, SMapAccess, hasWebGL2, rasterPath, checkStyle };
+export default SMapLeaflet;

package/types/compat.d.ts

@@ -0,0 +1,226 @@
+// Types of @superrouteca/smap-leaflet/compat: Leaflet-style calls on an sMap map.
+import type { Map as SMapMap } from '@superrouteca/smap';
+
+export type LatLngInput = [number, number] | [number, number, number] | { lat: number; lng: number } | { lat: number; lon: number };
+export interface LatLng { lat: number; lng: number }
+export type BoundsInput = LatLngBounds | [LatLngInput, LatLngInput] | LatLngInput[];
+export type PopupContentInput = string | HTMLElement | ((layer: Layer) => string | HTMLElement);
+
+export interface PopupOptions {
+  className?: string;
+  maxWidth?: number;
+  minWidth?: number;
+  closeButton?: boolean;
+  closeOnClick?: boolean;
+  autoPan?: boolean;
+  offset?: [number, number] | { x: number; y: number };
+}
+
+export interface PathOptions {
+  stroke?: boolean;
+  color?: string;
+  weight?: number;
+  opacity?: number;
+  fill?: boolean;
+  fillColor?: string | null;
+  fillOpacity?: number;
+  /** Dash and gap lengths in pixels, `'8, 4'` or `[8, 4]`. */
+  dashArray?: string | number[] | null;
+}
+
+export interface LeafletEvent {
+  type: string;
+  target: unknown;
+  sourceTarget?: unknown;
+  layer?: Layer;
+  latlng?: LatLng;
+  containerPoint?: { x: number; y: number };
+  originalEvent?: Event;
+  [key: string]: unknown;
+}
+
+export declare class LatLngBounds {
+  extend(p: LatLngInput | LatLngBounds): this;
+  isValid(): boolean;
+  getSouthWest(): LatLng;
+  getNorthEast(): LatLng;
+  getNorthWest(): LatLng;
+  getSouthEast(): LatLng;
+  getWest(): number;
+  getSouth(): number;
+  getEast(): number;
+  getNorth(): number;
+  getCenter(): LatLng;
+  contains(p: LatLngInput | LatLngBounds): boolean;
+  toLngLatArray(): [[number, number], [number, number]];
+}
+
+declare class Evented {
+  on(type: string, fn: (e: LeafletEvent) => void, context?: unknown): this;
+  on(map: Record<string, (e: LeafletEvent) => void>, context?: unknown): this;
+  off(type?: string, fn?: (e: LeafletEvent) => void, context?: unknown): this;
+  once(type: string, fn: (e: LeafletEvent) => void, context?: unknown): this;
+  fire(type: string, data?: Record<string, unknown>, propagate?: boolean): this;
+  listens(type: string): boolean;
+}
+
+export declare class Layer extends Evented {
+  options: Record<string, any>;
+  feature?: { type: 'Feature'; properties: Record<string, unknown> | null; geometry: unknown };
+  addTo(target: CompatMap | LayerGroup | SMapMap): this;
+  remove(): this;
+  removeFrom(target: CompatMap | LayerGroup | SMapMap): this;
+  bindPopup(content: PopupContentInput, options?: PopupOptions): this;
+  unbindPopup(): this;
+  openPopup(latlng?: LatLngInput): this;
+  closePopup(): this;
+  togglePopup(): this;
+  setPopupContent(content: PopupContentInput): this;
+  getBounds(): LatLngBounds;
+  toGeoJSON(): unknown;
+  setStyle(style: PathOptions): this;
+  bringToFront(): this;
+}
+
+export declare class Marker extends Layer {
+  constructor(latlng: LatLngInput, options?: { icon?: Icon; opacity?: number; zIndexOffset?: number; title?: string });
+  getLatLng(): LatLng;
+  setLatLng(latlng: LatLngInput): this;
+  setIcon(icon: Icon): this;
+  setOpacity(opacity: number): this;
+  setZIndexOffset(z: number): this;
+}
+export declare class CircleMarker extends Layer {
+  constructor(latlng: LatLngInput, options?: PathOptions & { radius?: number });
+  getLatLng(): LatLng;
+  setLatLng(latlng: LatLngInput): this;
+  setRadius(radius: number): this;
+  getRadius(): number;
+}
+export declare class Circle extends CircleMarker {
+  constructor(latlng: LatLngInput, options?: (PathOptions & { radius?: number }) | number);
+}
+export declare class Polyline extends Layer {
+  constructor(latlngs: unknown[], options?: PathOptions);
+  getLatLngs(): unknown[];
+  setLatLngs(latlngs: unknown[]): this;
+  addLatLng(latlng: LatLngInput): this;
+  isEmpty(): boolean;
+}
+export declare class Polygon extends Polyline {}
+export declare class Rectangle extends Polygon {
+  constructor(bounds: BoundsInput, options?: PathOptions);
+  setBounds(bounds: BoundsInput): this;
+}
+export declare class TileLayer extends Layer {
+  constructor(url: string, options?: { subdomains?: string | string[]; attribution?: string; opacity?: number; tileSize?: number; minZoom?: number; maxZoom?: number; maxNativeZoom?: number; tms?: boolean; detectRetina?: boolean; [placeholder: string]: unknown });
+  setUrl(url: string): this;
+  setOpacity(opacity: number): this;
+  getAttribution(): string | undefined;
+  tileUrls(): string[];
+}
+export declare class WmsLayer extends TileLayer {
+  setParams(params: Record<string, unknown>): this;
+}
+export declare class LayerGroup extends Layer {
+  constructor(layers?: Layer[], options?: Record<string, unknown>);
+  addLayer(layer: Layer): this;
+  removeLayer(layer: Layer | number): this;
+  hasLayer(layer: Layer): boolean;
+  clearLayers(): this;
+  eachLayer(fn: (layer: Layer) => void, context?: unknown): this;
+  getLayers(): Layer[];
+  getLayer(id: number): Layer | null;
+  getLayerId(layer: Layer): number;
+  invoke(name: string, ...args: unknown[]): this;
+}
+export declare class FeatureGroup extends LayerGroup {}
+export interface GeoJSONOptions {
+  style?: PathOptions | ((feature: any) => PathOptions);
+  pointToLayer?: (feature: any, latlng: LatLng) => Layer;
+  onEachFeature?: (feature: any, layer: Layer) => void;
+  filter?: (feature: any) => boolean;
+  coordsToLatLng?: (coords: number[]) => LatLngInput;
+}
+export declare class GeoJSON extends FeatureGroup {
+  constructor(data?: unknown, options?: GeoJSONOptions);
+  addData(data: unknown): this;
+  resetStyle(layer?: Layer): this;
+}
+export declare class Popup {
+  constructor(options?: PopupOptions, source?: Layer);
+  setLatLng(latlng: LatLngInput): this;
+  getLatLng(): LatLng | null;
+  setContent(content: PopupContentInput): this;
+  getContent(): PopupContentInput | null;
+  openOn(map: CompatMap | SMapMap): this;
+  close(): this;
+  remove(): this;
+}
+export declare class Icon { constructor(options: { iconUrl?: string; iconSize?: [number, number]; iconAnchor?: [number, number]; [key: string]: unknown }); options: Record<string, unknown> }
+export declare class DivIcon extends Icon {}
+
+/** A Leaflet-style map over an sMap map: zoom levels as Leaflet counts them (one above the sMap map's). */
+export declare class CompatMap extends Evented {
+  readonly smap: SMapMap;
+  readonly engine: any;
+  addLayer(layer: Layer): this;
+  removeLayer(layer: Layer): this;
+  hasLayer(layer: Layer): boolean;
+  eachLayer(fn: (layer: Layer) => void, context?: unknown): this;
+  getCenter(): LatLng;
+  getZoom(): number;
+  getBounds(): LatLngBounds;
+  getMinZoom(): number;
+  getMaxZoom(): number;
+  setView(center: LatLngInput, zoom?: number, options?: { animate?: boolean; duration?: number }): this;
+  setZoom(zoom: number, options?: { animate?: boolean }): this;
+  zoomIn(delta?: number, options?: { animate?: boolean }): this;
+  zoomOut(delta?: number, options?: { animate?: boolean }): this;
+  panTo(center: LatLngInput, options?: { animate?: boolean; duration?: number }): this;
+  panBy(offset: [number, number] | { x: number; y: number }, options?: { animate?: boolean }): this;
+  flyTo(center: LatLngInput, zoom?: number, options?: { duration?: number }): this;
+  fitBounds(bounds: BoundsInput, options?: { padding?: [number, number]; paddingTopLeft?: [number, number]; paddingBottomRight?: [number, number]; maxZoom?: number; animate?: boolean }): this;
+  flyToBounds(bounds: BoundsInput, options?: Record<string, unknown>): this;
+  invalidateSize(): this;
+  getContainer(): HTMLElement;
+  getSize(): { x: number; y: number };
+  project(latlng: LatLngInput): { x: number; y: number };
+  unproject(point: [number, number] | { x: number; y: number }): LatLng;
+  latLngToContainerPoint(latlng: LatLngInput): { x: number; y: number };
+  containerPointToLatLng(point: [number, number] | { x: number; y: number }): LatLng;
+  openPopup(content: PopupContentInput | Popup, latlng?: LatLngInput, options?: PopupOptions): this;
+  closePopup(): this;
+  remove(): this;
+}
+
+export interface LeafletCompat {
+  version: string;
+  map: CompatMap;
+  marker(latlng: LatLngInput, options?: ConstructorParameters<typeof Marker>[1]): Marker;
+  circleMarker(latlng: LatLngInput, options?: ConstructorParameters<typeof CircleMarker>[1]): CircleMarker;
+  circle(latlng: LatLngInput, options?: ConstructorParameters<typeof Circle>[1]): Circle;
+  polyline(latlngs: unknown[], options?: PathOptions): Polyline;
+  polygon(latlngs: unknown[], options?: PathOptions): Polygon;
+  rectangle(bounds: BoundsInput, options?: PathOptions): Rectangle;
+  geoJSON(data?: unknown, options?: GeoJSONOptions): GeoJSON;
+  geoJson(data?: unknown, options?: GeoJSONOptions): GeoJSON;
+  tileLayer: ((url: string, options?: ConstructorParameters<typeof TileLayer>[1]) => TileLayer) & { wms(url: string, options?: Record<string, unknown>): WmsLayer };
+  layerGroup(layers?: Layer[], options?: Record<string, unknown>): LayerGroup;
+  featureGroup(layers?: Layer[], options?: Record<string, unknown>): FeatureGroup;
+  popup(options?: PopupOptions, source?: Layer): Popup;
+  icon(options: ConstructorParameters<typeof Icon>[0]): Icon;
+  divIcon(options?: Record<string, unknown>): DivIcon;
+  latLng(a: LatLngInput | number, b?: number): LatLng | null;
+  latLngBounds(a: BoundsInput | LatLngInput, b?: LatLngInput): LatLngBounds;
+  Marker: typeof Marker; CircleMarker: typeof CircleMarker; Circle: typeof Circle; Polyline: typeof Polyline; Polygon: typeof Polygon;
+  Rectangle: typeof Rectangle; GeoJSON: typeof GeoJSON; TileLayer: typeof TileLayer; LayerGroup: typeof LayerGroup;
+  FeatureGroup: typeof FeatureGroup; Popup: typeof Popup; Icon: typeof Icon; DivIcon: typeof DivIcon;
+}
+
+/** Leaflet-style calls on an sMap map (after `await map.ready`). */
+export declare function createLeafletCompat(smap: SMapMap): LeafletCompat;
+export declare function toLatLng(v: LatLngInput | null | undefined): LatLng | null;
+export declare function latLngBounds(a: BoundsInput | LatLngInput, b?: LatLngInput): LatLngBounds;
+export declare function withAlpha(color: string, alpha?: number): string;
+export default createLeafletCompat;

package/types/index.d.ts

@@ -0,0 +1,152 @@
+// Types of @superrouteca/smap-leaflet.
+import * as L from 'leaflet';
+import type { Map as SMapMap, MapOptions as SMapMapOptions, StyleFlavor } from '@superrouteca/smap';
+import type SMapClient from '@superrouteca/smap/client';
+
+export type { StyleFlavor };
+/** A colour scheme or a saved custom style (`custom:<id>`). */
+export type SMapStyle = StyleFlavor | `custom:${string}`;
+
+/** How the adapters reach the service: a map key or a token (renewed through getToken), the nearest node. */
+export interface AccessOptions {
+  /** The map service, `https://tile.srsr.ca` by default. */
+  baseUrl?: string;
+  /** A map key (`smk_…`) whose allowlist names this site. */
+  apiKey?: string;
+  token?: string;
+  /** Called at start and again two minutes before each token expires. */
+  getToken?: () => string | Promise<string>;
+  /** Node URLs known in advance, used while `baseUrl` is down. */
+  nodes?: string[];
+  /** Read from the nearest node (default true). */
+  nearest?: boolean;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  /** A JS client of your own instead of the options above. */
+  client?: SMapClient;
+}
+
+/** The service access the raster layer uses (token, node order, failover). */
+export declare class SMapAccess {
+  constructor(options?: AccessOptions);
+  readonly client: SMapClient;
+  readonly baseUrl: string;
+  start(): Promise<this>;
+  refresh(): Promise<string | null>;
+  token(): string | null;
+  nodes(): string[];
+  head(): string;
+  isOurs(url: string): boolean;
+  headers(url: string): Record<string, string>;
+  rewrite(url: string): string;
+  failed(url: string): void;
+  withKey(path: string): string;
+  style(style: SMapStyle, language?: string): Promise<Record<string, unknown>>;
+  rasterTile(style: SMapStyle, z: number, x: number, y: number, options?: { lang?: string; retina?: boolean }): Promise<Blob>;
+  rasterTemplate(style: SMapStyle, options?: { lang?: string; retina?: boolean }): string;
+  on(listener: (type: 'token' | 'nodes', value: unknown) => void): this;
+  stop(): void;
+}
+
+export interface SMapLayerOptions extends Omit<SMapMapOptions, 'container' | 'style'> {
+  /** A colour scheme, `custom:<id>`, or a style URL or object of your own. */
+  style?: SMapStyle | string | Record<string, unknown>;
+  /** The Leaflet pane the map is drawn in (default `tilePane`). */
+  pane?: string;
+  /** Leaflet's clicks and pointer moves reach sMap's layers (popups, Auto Zoom, onClick, hover); default true. */
+  interactive?: boolean;
+  /** The sMap Web SDK module to use (default the installed `@superrouteca/smap`). */
+  sdk?: unknown;
+}
+
+/** The sMap vector map in a Leaflet pane. The sMap map's calls are forwarded once it is ready. */
+export declare class SMapLayer extends L.Layer {
+  constructor(options?: SMapLayerOptions);
+  /** Resolves to the sMap map once it is ready. */
+  readonly ready: Promise<SMapMap>;
+  /** The sMap map, or null before it is ready. */
+  getSMap(): SMapMap | null;
+  /** An sMap map call whose answer is a value (e.g. `call('basemap')`, `call('toJSON')`). */
+  call<T = unknown>(name: string, ...args: unknown[]): Promise<T>;
+  /** Removes the layer and deletes its sMap map. */
+  destroy(): this;
+  setStyle(style: SMapStyle | string | Record<string, unknown>): this;
+  setLanguage(language: string): this;
+  setBasemap(overrides: Record<string, Record<string, unknown>>): this;
+  setAutoZoom(on: boolean): this;
+  addPoints(id: string, data: unknown, options?: Record<string, unknown>): this;
+  addLines(id: string, data: unknown, options?: Record<string, unknown>): this;
+  addPolygons(id: string, data: unknown, options?: Record<string, unknown>): this;
+  addData(id: string, input: unknown, options?: Record<string, unknown>): this;
+  setData(id: string, data: unknown): this;
+  setVisible(id: string, visible: boolean): this;
+  fitLayer(id: string, options?: Record<string, unknown>): this;
+  /** Opens the sMap map's popup (Leaflet's openPopup stays Leaflet's own). */
+  openSMapPopup(lngLat: [number, number] | { lng: number; lat: number }, content: unknown, options?: Record<string, unknown>): this;
+  closeSMapPopup(): this;
+  addSource(id: string, source: Record<string, unknown>): this;
+  removeSource(id: string): this;
+  addStyleLayer(layer: Record<string, unknown>, options?: { before?: string; slot?: 'bottom' | 'roads' | 'labels' | 'top' }): this;
+  setPaint(layerId: string, name: string, value: unknown): this;
+  setLayout(layerId: string, name: string, value: unknown): this;
+  setFilter(layerId: string, filter: unknown): this;
+  addRasterLayer(id: string, options: Record<string, unknown>): this;
+  addWmsLayer(id: string, options: Record<string, unknown>): this;
+  addWmtsLayer(id: string, options: Record<string, unknown>): this;
+  addVectorTiles(id: string, options: Record<string, unknown>): this;
+  addArcGisLayer(id: string, options: Record<string, unknown>): this;
+  loadLayers(json: unknown): this;
+  /** Removes one of the sMap map's layers. */
+  removeSMapLayer(id: string): this;
+}
+
+export interface SMapRasterLayerOptions extends AccessOptions, L.GridLayerOptions {
+  style?: SMapStyle;
+  language?: string;
+  /** 512 px tiles for high-density screens (default: the screen's pixel ratio above 1). */
+  retina?: boolean;
+  /** An access of your own, shared between layers. */
+  access?: SMapAccess;
+}
+
+/** sMap raster tiles as a Leaflet grid layer. */
+export declare class SMapRasterLayer extends L.GridLayer {
+  constructor(options?: SMapRasterLayerOptions);
+  setStyle(style: SMapStyle): this;
+  setLanguage(language: string): this;
+  getAccess(): SMapAccess;
+}
+
+/** The sMap badge as a Leaflet control. */
+export declare class SMapBadge extends L.Control {}
+
+export declare function smapLayer(options?: SMapLayerOptions): SMapLayer;
+export declare function smapRasterLayer(options?: SMapRasterLayerOptions): SMapRasterLayer;
+/** The vector map where WebGL 2 exists, raster tiles elsewhere (`mode`, default `auto`). */
+export declare function smapBasemap(options?: (SMapLayerOptions & SMapRasterLayerOptions) & { mode?: 'auto' | 'vector' | 'raster' }): SMapLayer | SMapRasterLayer;
+export declare function hasWebGL2(doc?: Document): boolean;
+export declare function checkStyle(style?: string): SMapStyle;
+export declare function rasterPath(style: SMapStyle, z: number, x: number, y: number, options?: { lang?: string; retina?: boolean }): string;
+export declare function stylePath(style: SMapStyle, lang?: string): string;
+export declare const styles: StyleFlavor[];
+export declare const version: string;
+export declare const DEFAULT_BASE: string;
+export declare const OSM_ATTRIBUTION: string;
+/** The sMap map calls an SMapLayer forwards. */
+export declare const FORWARDED: string[];
+
+declare const SMapLeaflet: {
+  version: string;
+  styles: StyleFlavor[];
+  SMapLayer: typeof SMapLayer;
+  smapLayer: typeof smapLayer;
+  SMapRasterLayer: typeof SMapRasterLayer;
+  smapRasterLayer: typeof smapRasterLayer;
+  smapBasemap: typeof smapBasemap;
+  SMapBadge: typeof SMapBadge;
+  SMapAccess: typeof SMapAccess;
+  hasWebGL2: typeof hasWebGL2;
+  rasterPath: typeof rasterPath;
+  checkStyle: typeof checkStyle;
+};
+export default SMapLeaflet;