@superrouteca/smap-mapbox 0.0.0-stage → 1.1.1

package/src/on-smap.js

@@ -0,0 +1,101 @@
+// @superrouteca/smap-mapbox/on-smap — Mapbox GL JS styles and layers on an sMap map, through the sMap map's own
+// Style Specification calls (addSource, addStyleLayer):
+//
+//   import { loadMapboxStyle, copyMapboxLayers } from '@superrouteca/smap-mapbox/on-smap';
+//   const report = await loadMapboxStyle(smapMap, myStudioStyleJson);   // its own sources and layers, on sMap
+//   copyMapboxLayers(mapboxMap, smapMap);                                // an app's layers, moved over as they are
+//
+// Sources hosted by Mapbox (mapbox:// and api.mapbox.com) need a Mapbox account and its terms, so they are left out
+// and listed; so are the layers reading them, and a style's background / sky / fog (they would cover sMap's basemap).
+// A Mapbox GL JS v3 `slot` becomes an sMap slot (bottom → bottom, middle → labels, top → top); a layer without a slot
+// draws on top, in the order added, as in 1.0.
+
+const SLOTS = { bottom: 'bottom', middle: 'labels', top: 'top' };
+const COVERING = ['background', 'sky', 'fog'];
+
+function isMapboxHosted(source) {
+  if (!source) { return false; }
+  const urls = [source.url, source.data].concat(source.tiles || []).filter(function (u) { return typeof u === 'string'; });
+  return urls.some(function (u) { return /^mapbox:\/\//.test(u) || /^https?:\/\/([a-z0-9-]+\.)*mapbox\.com\//i.test(u); });
+}
+
+function need(smap, name) {
+  if (typeof smap[name] !== 'function') { throw new Error('sMap: this needs @superrouteca/smap 1.1.0 (' + name + ')'); }
+}
+
+/**
+ * Adds a Mapbox GL JS style's (or a part of one's) sources and layers to an sMap map.
+ *
+ * @param {Object} smap      an sMap map (after `await map.ready`)
+ * @param {Object|string} style  a style document, or its address (fetched; a mapbox:// address is refused)
+ * @param {Object} [options]
+ *   prefix (put before every source and layer id, default none), layers (ids to take; default all), filter(layer),
+ *   slot / before (for layers that name no slot of their own), fetch
+ * @returns {Promise<{ sources: string[], layers: string[], skipped: Array<{ id: string, reason: string }>, warnings: string[] }>}
+ */
+export async function loadMapboxStyle(smap, style, options) {
+  const o = Object.assign({ prefix: '' }, options);
+  need(smap, 'addSource');
+  need(smap, 'addStyleLayer');
+  let doc = style;
+  if (typeof style === 'string') {
+    if (/^mapbox:\/\//.test(style)) { throw new Error('sMap: a mapbox:// style is hosted by Mapbox and needs a Mapbox account; pass the style document instead'); }
+    const f = o.fetch || fetch;
+    const res = await f(style);
+    if (!res.ok) { throw new Error('sMap: the style could not be read (HTTP ' + res.status + ')'); }
+    doc = await res.json();
+  }
+  if (!doc || !Array.isArray(doc.layers)) { throw new Error('sMap: not a style document (no layers)'); }
+  const report = { sources: [], layers: [], skipped: [], warnings: [] };
+  const name = function (id) { return o.prefix + id; };
+  const sources = doc.sources || {};
+  const left = {};
+  Object.keys(sources).forEach(function (id) {
+    if (isMapboxHosted(sources[id])) { left[id] = true; report.skipped.push({ id: id, reason: 'hosted by Mapbox (needs a Mapbox account)' }); }
+  });
+  const wanted = function (l) { return (!o.layers || o.layers.indexOf(l.id) >= 0) && (!o.filter || o.filter(l)); };
+  const used = {};
+  doc.layers.forEach(function (l) { if (wanted(l) && typeof l.source === 'string') { used[l.source] = true; } });
+  Object.keys(sources).forEach(function (id) {
+    if (left[id] || !used[id]) { return; }
+    smap.addSource(name(id), sources[id]);
+    report.sources.push(name(id));
+  });
+  if ((doc.sprite && doc.layers.some(function (l) { return l.layout && l.layout['icon-image']; })) || doc.imports) {
+    report.warnings.push('icons of the style\'s own sprite are not loaded: add them with the sMap map\'s images, or draw points with addPoints');
+  }
+  doc.layers.forEach(function (l) {
+    if (!wanted(l)) { return; }
+    if (COVERING.indexOf(l.type) >= 0) { report.skipped.push({ id: l.id, reason: 'a ' + l.type + ' layer would cover the sMap basemap' }); return; }
+    if (typeof l.source === 'string' && left[l.source]) { report.skipped.push({ id: l.id, reason: 'reads a source hosted by Mapbox' }); return; }
+    if (typeof l.source === 'string' && !sources[l.source]) { report.skipped.push({ id: l.id, reason: 'reads a source the style does not have (' + l.source + ')' }); return; }
+    const layer = JSON.parse(JSON.stringify(l));
+    layer.id = name(l.id);
+    if (typeof layer.source === 'string') { layer.source = name(layer.source); }
+    const slot = layer.slot ? SLOTS[layer.slot] : undefined;
+    delete layer.slot;
+    const placement = {};
+    if (slot) { placement.slot = slot; }
+    else if (o.slot) { placement.slot = o.slot; }
+    if (!placement.slot && o.before) { placement.before = o.before; }
+    if (Object.keys(placement).length) { smap.addStyleLayer(layer, placement); } else { smap.addStyleLayer(layer); }
+    report.layers.push(layer.id);
+  });
+  return report;
+}
+
+/** Adds Mapbox GL JS layers (style layer objects; inline sources as they are) to an sMap map. */
+export function addMapboxLayers(smap, layers, options) {
+  return loadMapboxStyle(smap, { version: 8, sources: (options && options.sources) || {}, layers: layers }, options);
+}
+
+/**
+ * Moves an existing Mapbox GL JS map's own layers onto an sMap map: every source and layer of its style except the
+ * Mapbox-hosted basemap (or those `layers` names / `filter` keeps). The Mapbox GL JS map is left as it is.
+ */
+export function copyMapboxLayers(mapboxMap, smap, options) {
+  const style = mapboxMap.getStyle();
+  return loadMapboxStyle(smap, style, options);
+}
+
+export { isMapboxHosted };

package/types/index.d.ts

@@ -0,0 +1,165 @@
+// Types of @superrouteca/smap-mapbox.
+import type * as mapboxgl from 'mapbox-gl';
+import type { Map as SMapMap, StyleFlavor, BasemapOverrides, StyleLayer, StyleSource, Slot, PointOptions, LineOptions, PolygonOptions,
+  LayerData, PopupOptions, PopupContent, FitOptions, RasterLayerOptions, VectorTilesOptions, WmsLayerOptions, WmtsLayerOptions, ArcGisLayerOptions,
+  LayerDescription, DataOptions, FileInput, LngLatLike } 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}`;
+/** An sMap slot, or Mapbox GL JS' own `middle` (= `labels`). */
+export type AnySlot = Slot | 'middle';
+/** The Mapbox GL JS module (`import mapboxgl from 'mapbox-gl'`): only its Map class is used. */
+export interface MapboxModule { Map: typeof mapboxgl.Map }
+
+/** 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 SMapMapboxOptions extends AccessOptions, Omit<Partial<mapboxgl.MapOptions>, 'style'> {
+  style?: SMapStyle;
+  language?: string;
+  /** Basemap class overrides (contract §1). */
+  basemap?: BasemapOverrides;
+  /** 3D buildings from the basemap. */
+  buildings3D?: boolean | { color?: string; opacity?: number };
+  /** Default popup options of sMap's layers. */
+  popup?: PopupOptions;
+  popupLoading?: string | Node;
+  /** Auto Zoom for sMap's pins (default true). */
+  autoZoom?: boolean;
+  /** An access of your own (shared with smapTransformRequest). */
+  access?: SMapAccess;
+  /** A Mapbox GL JS map you made, instead of `container` (see SMapMapbox.attach). */
+  map?: mapboxgl.Map;
+  /** With `map`: which of its layers stay (default: all but the Mapbox-hosted basemap, background and sky). */
+  keep?: (layer: StyleLayer) => boolean;
+  /** The sMap Web SDK module to use (default the installed `@superrouteca/smap`). */
+  sdk?: unknown;
+}
+
+/** sMap in Mapbox GL JS: sMap's style drawn by Mapbox GL JS, sMap's own layers on an overlay sMap map. */
+export declare class SMapMapbox {
+  constructor(mapbox: MapboxModule, options: SMapMapboxOptions);
+  /** Attaches to a Mapbox GL JS map you made: its basemap becomes sMap's, its own layers stay. */
+  static attach(mapbox: MapboxModule, map: mapboxgl.Map, options?: SMapMapboxOptions): SMapMapbox;
+  /** Resolves once the style has loaded. */
+  readonly ready: Promise<SMapMapbox>;
+  /** The Mapbox GL JS map (set once `ready` resolves). */
+  readonly map: mapboxgl.Map;
+  readonly access: SMapAccess;
+  setStyle(style: SMapStyle): this;
+  setLanguage(language: string): this;
+  setBasemap(overrides: BasemapOverrides): this;
+  basemap(): BasemapOverrides;
+  setBuildings3D(on: boolean, options?: { color?: string; opacity?: number }): this;
+  /** The basemap layer a slot begins at (undefined for `top`). */
+  slotLayer(slot?: Slot): string | undefined;
+  addSource(id: string, source: StyleSource): this;
+  removeSource(id: string): this;
+  addStyleLayer(layer: StyleLayer & { slot?: AnySlot }, placement?: { slot?: AnySlot; before?: string }): this;
+  setPaint(layerId: string, name: string, value: unknown): this;
+  setLayout(layerId: string, name: string, value: unknown): this;
+  setFilter(layerId: string, filter: unknown[] | null): this;
+  addRasterLayer(id: string, options: RasterLayerOptions): this;
+  addVectorTiles(id: string, options: VectorTilesOptions): this;
+  /** The overlay sMap map (made on first use). */
+  overlay(): Promise<SMapMap>;
+  /** An sMap map call on the overlay, resolving to its answer (e.g. `call('toGeoJSON', 'stops')`). */
+  call<T = unknown>(name: string, ...args: unknown[]): Promise<T>;
+  addPoints(id: string, data: LayerData, options?: PointOptions): this;
+  addLines(id: string, data: LayerData, options?: LineOptions): this;
+  addPolygons(id: string, data: LayerData, options?: PolygonOptions): this;
+  addData(id: string, input: FileInput | Blob, options?: DataOptions): this;
+  setData(id: string, data: LayerData): this;
+  setVisible(id: string, visible: boolean): this;
+  removeLayer(id: string): this;
+  fitLayer(id: string, options?: FitOptions): this;
+  openPopup(lngLat: LngLatLike, content: PopupContent | Promise<PopupContent>, options?: PopupOptions): this;
+  closePopup(): this;
+  setAutoZoom(on: boolean): this;
+  addWmsLayer(id: string, options: WmsLayerOptions): this;
+  addWmtsLayer(id: string, options: WmtsLayerOptions): this;
+  addArcGisLayer(id: string, options: ArcGisLayerOptions): this;
+  addDeckLayer(layer: unknown): this;
+  removeDeckLayer(id: string): this;
+  loadLayers(json: LayerDescription | string): this;
+  remove(): void;
+}
+
+/** The sMap badge as a Mapbox GL JS control. */
+export declare class SMapBadgeControl implements mapboxgl.IControl {
+  onAdd(map: mapboxgl.Map): HTMLElement;
+  onRemove(): void;
+}
+
+/** A Mapbox GL JS transformRequest for sMap (node, token, map key); other URLs go to `next` or unchanged. */
+export declare function smapTransformRequest(access: SMapAccess, next?: (url: string, resourceType?: string) => { url: string; headers?: Record<string, string> }): (url: string, resourceType?: string) => { url: string; headers?: Record<string, string> };
+export declare function createMap(mapbox: MapboxModule, options: SMapMapboxOptions): Promise<SMapMapbox>;
+export declare function switchBasemap(mapbox: MapboxModule, map: mapboxgl.Map, options?: SMapMapboxOptions): Promise<SMapMapbox>;
+export declare function smapAccess(options?: AccessOptions): SMapAccess;
+export declare function userPart(style: { sources?: Record<string, unknown>; layers?: StyleLayer[] }, basemapDoc: { sources?: Record<string, unknown>; layers?: StyleLayer[] } | null, extraBasemapLayers?: string[]): { sources: Record<string, unknown>; layers: Array<{ layer: StyleLayer; before: string | null }> };
+export declare function mergeUserPart<S extends { sources?: Record<string, unknown>; layers?: StyleLayer[] }>(doc: S, part: ReturnType<typeof userPart>): S;
+export declare function isMapboxSource(source: unknown): 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;
+export declare const attribution: string;
+export declare const OVERLAY_CALLS: string[];
+
+declare const SMapMapboxModule: {
+  version: string;
+  styles: StyleFlavor[];
+  SMapMapbox: typeof SMapMapbox;
+  createMap: typeof createMap;
+  switchBasemap: typeof switchBasemap;
+  smapAccess: typeof smapAccess;
+  smapTransformRequest: typeof smapTransformRequest;
+  SMapBadgeControl: typeof SMapBadgeControl;
+  SMapAccess: typeof SMapAccess;
+  checkStyle: typeof checkStyle;
+  rasterPath: typeof rasterPath;
+};
+export default SMapMapboxModule;

package/types/on-smap.d.ts

@@ -0,0 +1,28 @@
+// Types of @superrouteca/smap-mapbox/on-smap: Mapbox GL JS styles and layers on an sMap map.
+import type { Map as SMapMap, StyleLayer, StyleSource, Slot } from '@superrouteca/smap';
+
+export interface LoadOptions {
+  /** Put before every source and layer id (default none). */
+  prefix?: string;
+  /** The layer ids to take (default all). */
+  layers?: string[];
+  filter?: (layer: StyleLayer) => boolean;
+  /** For layers that name no slot of their own. */
+  slot?: Slot;
+  before?: string;
+  fetch?: typeof fetch;
+}
+
+export interface LoadReport {
+  sources: string[];
+  layers: string[];
+  skipped: Array<{ id: string; reason: string }>;
+  warnings: string[];
+}
+
+type StyleDocument = { version?: number; sources?: Record<string, StyleSource>; layers: Array<StyleLayer & { slot?: string }>; sprite?: unknown; [key: string]: unknown };
+
+export declare function loadMapboxStyle(smap: SMapMap, style: StyleDocument | string, options?: LoadOptions): Promise<LoadReport>;
+export declare function addMapboxLayers(smap: SMapMap, layers: Array<StyleLayer & { slot?: string }>, options?: LoadOptions & { sources?: Record<string, StyleSource> }): Promise<LoadReport>;
+export declare function copyMapboxLayers(mapboxMap: { getStyle(): any }, smap: SMapMap, options?: LoadOptions): Promise<LoadReport>;
+export declare function isMapboxHosted(source: unknown): boolean;