@superrouteca/smap-deckgl 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.1.0 — 2026-10-27
+
+- First version.
+- sMap as the basemap of deck.gl apps: an sMap map with deck.gl drawn interleaved with it (`createSMapDeck`), sMap's
+  vector tiles drawn by deck.gl in sMap's style (`createVectorBasemapLayer`, with labels in any language, custom styles
+  and 3D buildings), or sMap's raster tiles (`createRasterBasemapLayer`). Tiles come from the nearest map node, the
+  next one when a node fails, with a map key or a token that is renewed.
+- deck.gl layers on an sMap map kept by id (`deckLayers`, over the map's `addDeckLayer` / `removeDeckLayer`).
+- sMap's points, pins, lines and areas as deck.gl layers with the SDK's options (`pointsLayers`, `linesLayers`,
+  `polygonsLayers`), simplestyle colours, and popups as deck.gl tooltips (`popupTooltip`).
+- kepler.gl map styles (`keplerMapStyles`, `keplerTransformRequest`).
+- The sMap badge and the OpenStreetMap credit on maps drawn by deck.gl (`addAttribution`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goodneo Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# @superrouteca/smap-deckgl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+sMap and [deck.gl](https://deck.gl) both ways:
+
+- **sMap as the basemap of a deck.gl app**: either an sMap map with deck.gl drawn interleaved with it (deck.gl's map
+  overlay), or sMap's vector tiles drawn by deck.gl itself (an `MVTLayer` coloured by sMap's style), or sMap's raster
+  tiles in a `TileLayer`. The five colour schemes and your saved custom styles, labels in any language, the nearest map
+  node with failover, and a map key or a token with refresh, all included.
+- **deck.gl layers on an sMap map**, through the map's `addDeckLayer`, with helpers that keep layers by id.
+- **sMap's points, pins, lines and areas as deck.gl layers**, with the options of the SDK's `addPoints` / `addLines` /
+  `addPolygons`.
+- **kepler.gl**: sMap's styles as kepler.gl map styles (recipe below).
+
+```sh
+npm install @superrouteca/smap-deckgl @deck.gl/core @deck.gl/layers @deck.gl/geo-layers @deck.gl/mapbox
+```
+
+deck.gl 9 is a peer dependency. The adapter depends on `@superrouteca/smap` (1.1.0) for the map, the nodes, the key and
+the token.
+
+## Access
+
+Every call takes the options of the sMap JS client: `apiKey` (a map key, `smk_…`, whose allowlist names your site),
+or `token` / `getToken` (short-lived tokens from your server), plus `baseUrl` (default `https://tile.srsr.ca`),
+`nodes` and `nearest`. Make one `Session` and pass it as `session` to share it between layers:
+
+```js
+import { createSession } from '@superrouteca/smap-deckgl';
+const session = createSession({ apiKey: 'smk_…' });
+```
+
+## sMap as the deck.gl basemap
+
+### Interleaved with an sMap map
+
+The basemap is a full sMap map (pins, popups, Auto Zoom, 3D buildings, `setStyle`, `setLanguage`, `setBasemap`, …)
+and deck.gl draws between its layers, sharing its depth, through the map's own deck.gl overlay (`addDeckLayer`, deck.gl's
+`MapboxOverlay`; one per map):
+
+```js
+import { createSMapDeck } from '@superrouteca/smap-deckgl';
+import { HexagonLayer } from '@deck.gl/aggregation-layers';
+
+const { map, setLayers, setProps } = await createSMapDeck({
+  container: 'map', apiKey: 'smk_…', style: 'dark', language: 'en', center: [-79.38, 43.65], zoom: 11, pitch: 45,
+  layers: [new HexagonLayer({ id: 'orders', data, getPosition: (d) => d.position, extruded: true, radius: 200 })],
+  deck: { getTooltip: ({ object }) => object && `${object.count} orders` },
+});
+map.setBuildings3D(true);       // the sMap map's own API
+setLayers([/* new layers */]);  // deck.gl's way of updating: new layers with the same ids
+```
+
+Every option except `layers`, `deck` and `sMap` is the sMap map's. deck.gl's map overlay module is handed to the SDK
+for you (`useDeck`).
+
+### Drawn by deck.gl (vector tiles)
+
+For a deck.gl app with its own `Deck`, sMap's vector tiles are an `MVTLayer` coloured by sMap's style: fills, lines,
+point labels and (with `buildings3D`) buildings raised by their height:
+
+```js
+import { Deck } from '@deck.gl/core';
+import { createVectorBasemapLayer, addAttribution } from '@superrouteca/smap-deckgl';
+
+const basemap = await createVectorBasemapLayer({
+  apiKey: 'smk_…', style: 'custom:sms_…', language: 'fr', buildings3D: true,
+  basemap: { pois: { visible: false }, water: { color: '#9cc0e6' } },   // basemap options by class, as map.setBasemap
+});
+new Deck({
+  parent: document.getElementById('map'),
+  initialViewState: { longitude: 2.35, latitude: 48.86, zoom: 12, pitch: 40 },
+  controller: true,
+  layers: [basemap, myLayer],
+});
+addAttribution(document.getElementById('map'));   // the sMap badge and the OpenStreetMap credit
+```
+
+The colour behind the tiles is `basemap.smap.background` (`[r, g, b, a]`): give it to the page. Tiles are read
+through the session: the nearest node, the next one when a node fails, with the key or token.
+
+What deck.gl draws from sMap's style: fill, line, fill-extrusion and point-placed symbol text, with paint and layout
+values evaluated at each tile's zoom (constants, zoom and property functions, and the common expressions). Not drawn:
+icons from the style's sprite, labels placed along lines, label collision, dashes, and patterns. For the complete
+look, use the interleaved map above or the raster layer below.
+
+### Drawn by deck.gl (raster tiles)
+
+The exact sMap look as images, drawn on sMap's nodes:
+
+```js
+import { createRasterBasemapLayer } from '@superrouteca/smap-deckgl';
+const basemap = await createRasterBasemapLayer({ apiKey: 'smk_…', style: 'light', language: 'zh-Hans', retina: true });
+```
+
+## deck.gl layers on an sMap map
+
+An sMap map (1.1.0) takes deck.gl layers with `map.addDeckLayer(layer, { slot, before })` /
+`map.removeDeckLayer(id)`. `deckLayers(map)` hands deck.gl to the SDK and keeps the layers it added by id, so updating
+a layer is adding a new one with the same id, and `set` replaces them all:
+
+```js
+import * as sMap from '@superrouteca/smap';
+import { deckLayers } from '@superrouteca/smap-deckgl';
+import { ArcLayer } from '@deck.gl/layers';
+
+const map = new sMap.Map({ container: 'map', apiKey: 'smk_…' });
+const deck = deckLayers(map);
+deck.add(new ArcLayer({ id: 'flows', data, getSourcePosition: (d) => d.from, getTargetPosition: (d) => d.to }));
+deck.add(new ArcLayer({ id: 'flows', data: next, /* … */ }), { slot: 'labels' });   // replaces 'flows', under the labels
+deck.set([]);                                                                        // removes every layer it added
+```
+
+A layer without a slot draws on top, in the order added.
+
+## sMap's layers as deck.gl layers
+
+`pointsLayers`, `linesLayers` and `polygonsLayers` take the data and options of the SDK's `addPoints`, `addLines` and
+`addPolygons` and return deck.gl layers (bottom first), for a map drawn by deck.gl:
+
+```js
+import { pointsLayers, linesLayers, polygonsLayers, popupTooltip } from '@superrouteca/smap-deckgl';
+import { popupTemplate } from '@superrouteca/smap';
+
+const layers = [
+  ...polygonsLayers('zones', zones, { fill: '#2563eb', opacity: 0.2, outline: '#2563eb' }),
+  ...linesLayers('route', route, { color: { property: 'color' }, width: 5, casing: true }),
+  ...pointsLayers('stops', stops, {
+    marker: { text: { property: 'seq' }, border: { property: 'color' } }, label: 'name',
+    popup: popupTemplate('<b>{name}</b><br>{address}'),
+  }),
+];
+new Deck({ /* … */ layers: [basemap, ...layers], getTooltip: popupTooltip() });
+```
+
+Points: circles, an icon, or route-map pins (`pin` and `circle` shapes, fill, border, number); lines: colour per
+feature, width, opacity, casing, shadow; areas: fill, outline, opacity, and extrusion from a height property. GeoJSON
+simplestyle properties (`marker-color`, `marker-size`, `stroke`, `stroke-width`, `stroke-opacity`, `fill`,
+`fill-opacity`) colour a layer that gives no colour of its own. On a map drawn by deck.gl, popups are deck.gl tooltips
+(HTML strings); clustering, Auto Zoom, dashes, arrows, count badges and zoom ranges are the sMap map's own and are not
+drawn by these layers: put the layers on an sMap map (`map.addPoints`, …) for those.
+
+## kepler.gl
+
+kepler.gl reads Style Specification styles from a URL, so sMap's styles are kepler.gl map styles:
+
+```jsx
+import KeplerGl from '@kepler.gl/components';
+import { keplerMapStyles, keplerTransformRequest } from '@superrouteca/smap-deckgl';
+
+const access = { apiKey: 'smk_…' };   // or { getToken }
+const mapStyles = await keplerMapStyles({ ...access, language: 'en', styles: ['light', 'dark', 'custom:sms_…'] });
+
+<KeplerGl
+  id="map"
+  mapStyles={mapStyles}
+  mapStylesReplaceDefault
+  transformRequest={keplerTransformRequest(access)}
+  width={width}
+  height={height}
+/>;
+```
+
+Then pick a style by its id (`smap-light`, `smap-dark`, `smap-custom-sms_…`), e.g.
+`dispatch(addDataToMap({ datasets, config: { version: 'v1', config: { mapStyle: { styleType: 'smap-dark' } } } }))`.
+A map key goes in the style URL itself, so a key is enough even where `transformRequest` is not passed; a token needs
+`transformRequest`. kepler.gl shows the OpenStreetMap credit from the style's sources.
+
+## Example
+
+[`examples/index.html`](examples/index.html): serve the repository root (`npx serve .`) and open
+`/deckgl/examples/?key=smk_…` (`&mode=vector`, `raster` or `interleaved`).
+
+## Licence
+
+MIT. The map data is © OpenStreetMap contributors; the credit stays visible on every map.

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@superrouteca/smap-deckgl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "sMap for deck.gl: sMap as the basemap of deck.gl apps (interleaved or drawn by deck.gl), deck.gl layers on sMap maps, and kepler.gl map styles.",
+  "license": "MIT",
+  "author": "Goodneo Solutions",
+  "homepage": "https://github.com/Goodneo-Solutions/smap-sdk/tree/main/deckgl#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Goodneo-Solutions/smap-sdk.git",
+    "directory": "deckgl"
+  },
+  "keywords": [
+    "map",
+    "maps",
+    "deck.gl",
+    "kepler.gl",
+    "vector-tiles",
+    "smap",
+    "superroute"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --import ./test/setup.mjs --test test/*.test.mjs",
+    "typecheck": "tsc -p test/tsconfig.json"
+  },
+  "dependencies": {
+    "@superrouteca/smap": "1.1.0"
+  },
+  "peerDependencies": {
+    "@deck.gl/core": "^9.0.0",
+    "@deck.gl/layers": "^9.0.0",
+    "@deck.gl/geo-layers": "^9.0.0",
+    "@deck.gl/mapbox": "^9.0.0"
+  },
+  "devDependencies": {
+    "@deck.gl/core": "9.4.0",
+    "@deck.gl/layers": "9.4.0",
+    "@deck.gl/geo-layers": "9.4.0",
+    "@deck.gl/mapbox": "9.4.0",
+    "typescript": "6.0.3"
+  }
+}

package/src/basemap.js

@@ -0,0 +1,129 @@
+// sMap as the basemap of a deck.gl app drawn by deck.gl itself: its vector tiles through deck.gl's MVTLayer, coloured
+// by sMap's style (schemes and custom styles, any label language), or its raster tiles through a TileLayer.
+import { MVTLayer, TileLayer } from '@deck.gl/geo-layers';
+import { GeoJsonLayer, TextLayer, BitmapLayer } from '@deck.gl/layers';
+import { applyBasemapOverrides } from '@superrouteca/smap';
+import { createSession, ATTRIBUTION } from './session.js';
+import { compileStyle, drawTile } from './style.js';
+
+async function vectorSource(session, doc, sourceId) {
+  const sources = doc.sources || {};
+  const id = sourceId || Object.keys(sources).find((k) => sources[k].type === 'vector');
+  if (!id) { throw new Error('sMap: the style has no vector source'); }
+  const src = sources[id];
+  if (src.tiles && src.tiles.length) { return { id, tiles: src.tiles, minzoom: src.minzoom, maxzoom: src.maxzoom, attribution: src.attribution }; }
+  if (!src.url) { throw new Error('sMap: vector source "' + id + '" has neither tiles nor url'); }
+  const tj = await session.fetch(src.url).then((r) => r.json());
+  return { id, tiles: tj.tiles, minzoom: tj.minzoom ?? src.minzoom, maxzoom: tj.maxzoom ?? src.maxzoom, attribution: tj.attribution };
+}
+
+/** The sub layers drawn for one tile (exported for tests and for apps that draw tiles their own way). */
+export function tileSubLayers(props, compiled, options = {}) {
+  const z = props.tile && props.tile.index ? props.tile.index.z : (props.tile && props.tile.zoom) || 0;
+  const drawn = drawTile(compiled, props.data || [], z, options);
+  const { data: _data, ...base } = props;
+  const sub = [];
+  if (drawn.fills.length) {
+    sub.push(new GeoJsonLayer({
+      ...base, id: props.id + '-fills', data: drawn.fills.map((d) => ({ type: 'Feature', geometry: d.geometry, properties: d })),
+      filled: true, stroked: false, getFillColor: (f) => f.properties.color, pickable: options.pickable || false,
+    }));
+  }
+  if (drawn.lines.length) {
+    sub.push(new GeoJsonLayer({
+      ...base, id: props.id + '-lines', data: drawn.lines.map((d) => ({ type: 'Feature', geometry: d.geometry, properties: d })),
+      filled: false, stroked: true, lineWidthUnits: 'pixels', lineCapRounded: true, lineJointRounded: true,
+      getLineColor: (f) => f.properties.color, getLineWidth: (f) => f.properties.width, pickable: options.pickable || false,
+    }));
+  }
+  if (drawn.extrusions.length) {
+    sub.push(new GeoJsonLayer({
+      ...base, id: props.id + '-buildings', data: drawn.extrusions.map((d) => ({ type: 'Feature', geometry: d.geometry, properties: d })),
+      filled: true, stroked: false, extruded: true, getFillColor: (f) => f.properties.color,
+      getElevation: (f) => Math.max(0, f.properties.height - f.properties.base), material: true, pickable: options.pickable || false,
+    }));
+  }
+  if (drawn.labels.length && options.labels !== false) {
+    sub.push(new TextLayer({
+      ...base, id: props.id + '-labels', data: drawn.labels,
+      getPosition: (d) => d.position, getText: (d) => d.text, getColor: (d) => d.color, getSize: (d) => d.size,
+      sizeUnits: 'pixels', characterSet: 'auto', fontFamily: options.fontFamily || 'Noto Sans, Helvetica, Arial, sans-serif',
+      fontSettings: { sdf: true }, outlineWidth: 2, outlineColor: drawn.labels[0].halo,
+      getTextAnchor: (d) => (d.anchor.includes('left') ? 'start' : d.anchor.includes('right') ? 'end' : 'middle'),
+      getAlignmentBaseline: (d) => (d.anchor.startsWith('top') ? 'top' : d.anchor.startsWith('bottom') ? 'bottom' : 'center'),
+      billboard: true, pickable: false,
+    }));
+  }
+  return sub;
+}
+
+/**
+ * The sMap basemap as a deck.gl MVTLayer: sMap's vector tiles drawn by deck.gl in the scheme or custom style chosen,
+ * labels in `language`, `basemap` overrides by class (as the SDK's setBasemap); tiles read from the nearest node, the
+ * next one on failure, with the map key or token.
+ *
+ * @returns {Promise<MVTLayer>} also carrying `smap: { session, style, background, attribution }`
+ */
+export async function createVectorBasemapLayer(options = {}) {
+  const session = createSession(options.session || options);
+  await session.ready();
+  const style = options.style || 'light';
+  let doc = options.styleDocument || await session.style(style, options.language);
+  // Basemap options (contract §1: show, hide and recolour by class), applied by the SDK's own function.
+  if (options.basemap && Object.keys(options.basemap).length) { doc = applyBasemapOverrides(doc, options.basemap); }
+  const compiled = compileStyle(doc, { source: options.source });
+  const src = await vectorSource(session, doc, compiled.sources[0]);
+  const drawOptions = { labels: options.labels !== false, buildings3D: Boolean(options.buildings3D), fontFamily: options.fontFamily, pickable: options.pickable };
+  const tileFetch = (url, init) => session.fetch(url, init);
+  const layer = new MVTLayer({
+    id: options.id || 'smap-basemap',
+    data: src.tiles,
+    minZoom: src.minzoom ?? 0,
+    maxZoom: src.maxzoom ?? 15,
+    binary: false,
+    // loaders.gl reads every tile with this fetch: the session's, so nearest node, failover, key and token apply.
+    loadOptions: { fetch: tileFetch, core: { fetch: tileFetch }, mvt: { layerProperty: 'layerName' } },
+    renderSubLayers: (props) => tileSubLayers(props, compiled, drawOptions),
+    pickable: Boolean(options.pickable),
+    ...(options.layerProps || {}),
+  });
+  layer.smap = { session, style, background: compiled.background, attribution: src.attribution || ATTRIBUTION };
+  return layer;
+}
+
+/** Bytes of a raster tile through the session (nearest node, failover, key, token) as an ImageBitmap. */
+async function loadRaster(session, url, signal) {
+  const res = await session.fetch(url, { signal });
+  const blob = await res.blob();
+  if (typeof createImageBitmap === 'function') { return createImageBitmap(blob); }
+  return blob;
+}
+
+/**
+ * The sMap basemap as raster tiles (contract §5) in a deck.gl TileLayer: what deck.gl shows where vector drawing is
+ * not wanted, the same scheme or custom style and language. `retina` reads 512 px tiles.
+ */
+export async function createRasterBasemapLayer(options = {}) {
+  const session = createSession(options.session || options);
+  await session.ready();
+  const style = options.style || 'light';
+  const template = session.rasterTemplate(style, { language: options.language, retina: options.retina });
+  const layer = new TileLayer({
+    id: options.id || 'smap-raster',
+    data: template,
+    tileSize: 256,
+    minZoom: 0,
+    maxZoom: options.maxZoom ?? 19,
+    getTileData: ({ index, signal }) => {
+      const url = template.replace('{z}', index.z).replace('{x}', index.x).replace('{y}', index.y);
+      return loadRaster(session, url, signal);
+    },
+    renderSubLayers: (props) => {
+      const bb = props.tile.bbox;
+      return new BitmapLayer({ ...props, data: undefined, image: props.data, bounds: [bb.west, bb.south, bb.east, bb.north] });
+    },
+    ...(options.layerProps || {}),
+  });
+  layer.smap = { session, style, attribution: ATTRIBUTION };
+  return layer;
+}

package/src/index.js

@@ -0,0 +1,8 @@
+// @superrouteca/smap-deckgl — sMap and deck.gl both ways.
+export { Session, createSession, FLAVORS, ATTRIBUTION } from './session.js';
+export { createVectorBasemapLayer, createRasterBasemapLayer, tileSubLayers } from './basemap.js';
+export { createSMapDeck, deckLayers, registerDeck, addAttribution } from './overlay.js';
+export { pointsLayers, linesLayers, polygonsLayers, popupTooltip, toFeatures, accessor } from './layers.js';
+export { keplerMapStyles, keplerTransformRequest } from './kepler.js';
+export { parseColor, evaluate, compileStyle, drawTile } from './style.js';
+export const version = '1.1.0';

package/src/kepler.js

@@ -0,0 +1,31 @@
+// kepler.gl with sMap's styles as its map styles (see the README's kepler.gl recipe).
+import { createSession, FLAVORS } from './session.js';
+
+/**
+ * kepler.gl map styles for sMap's schemes (and custom styles): `{ id, label, url, icon }` each, for the KeplerGl
+ * component's `mapStyles` prop. Waits for the nearest node, so every URL points at it.
+ *
+ * @param {object} options  session options (apiKey / token / getToken, baseUrl, …) or `{ session }`, plus `styles`
+ *                          (default every scheme; `custom:<id>` too), `language` and `labels` ({ styleId: label })
+ */
+export async function keplerMapStyles(options = {}) {
+  const session = createSession(options.session || options);
+  await session.ready();
+  const styles = options.styles || FLAVORS;
+  return styles.map((style) => ({
+    id: 'smap-' + style.replace(':', '-'),
+    label: (options.labels && options.labels[style]) || 'sMap ' + style.replace(/^custom:/, ''),
+    url: session.styleUrl(style, options.language),
+    icon: session.rasterTemplate(style, { language: options.language }).replace('{z}', '3').replace('{x}', '2').replace('{y}', '2'),
+  }));
+}
+
+/**
+ * A transformRequest for kepler.gl's map (the KeplerGl `transformRequest` prop): sMap URLs get the token and the map
+ * key as headers; other URLs pass unchanged.
+ */
+export function keplerTransformRequest(options = {}) {
+  const session = createSession(options.session || options);
+  session.ready().catch(() => {});
+  return (url) => (session.nodeOf(url) ? { url, headers: session.headers() } : { url });
+}