@superrouteca/smap-arcgis 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.1.1 — 2026-10-27
+
+- The vector basemap draws: water, land, roads, labels and icons appear in every colour scheme and label language
+  (with 1.1.0, `createSMapBasemap()` and `createVectorTileLayer()` loaded without an error and drew nothing). The style
+  is converted into what ArcGIS's vector tile layer supports before it is handed over; sMap's own style is unchanged.
+- What the conversion simplifies, compared with the sMap web map: a label shows the name in the label language and,
+  for a name in another script, the local name on a second line, in one font (the per-script fonts are not used);
+  labels that sMap places at one of several positions keep the first position; layer properties ArcGIS does not
+  have are left out, and 3D buildings are drawn flat. `layer.smap.simplified` lists every simplification of the
+  style shown.
+- `toArcGISStyle()` converts any style the same way (for a `VectorTileLayer` of your own); `convertStyle: false`
+  hands sMap's style to ArcGIS unchanged.
+- Chinese, Japanese and Korean labels show in the vector basemap: sMap 1.1.1 serves them in its fonts. Chinese
+  characters take the Simplified Chinese form in every language.
+
 ## 1.1.0 — 2026-10-27
 
 - First version.

package/README.md

@@ -48,6 +48,21 @@ An existing ArcGIS app switches its basemap and keeps every layer: `map.basemap
 
 The layers on their own: `createVectorTileLayer(options)` and `createRasterTileLayer(options)`.
 
+### The vector style in ArcGIS
+
+ArcGIS's `VectorTileLayer` supports part of the Style Specification, so the vector basemap converts sMap's style
+before handing it over (`toArcGISStyle(style)` does the same for a `VectorTileLayer` of your own; `convertStyle: false`
+hands the style over unchanged). Compared with the sMap web map:
+
+- a label shows the name in the label language and, for a name in another script, the local name on a second line,
+  in one font;
+- a label that sMap places at one of several positions keeps the first one;
+- layer properties ArcGIS does not have are left out, and 3D buildings are drawn flat;
+- Chinese, Japanese and Korean labels are drawn with sMap's own fonts (sMap 1.1.1 or later); Chinese characters take
+  the Simplified Chinese form in every language.
+
+`basemap.smap.simplified` lists each simplification of the style shown (`"<layer>: <what>"`).
+
 ### Keys, tokens and nodes
 
 `createSMapBasemap` (and the layer functions) install one request interceptor per session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap-arcgis",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "sMap for the ArcGIS Maps SDK for JavaScript: sMap basemaps (vector and raster), sMap layers as graphics, and ArcGIS REST services on sMap maps.",
   "license": "MIT",
   "author": "Goodneo Solutions",
@@ -50,7 +50,7 @@
     "typecheck": "tsc -p test/tsconfig.json"
   },
   "dependencies": {
-    "@superrouteca/smap": "1.1.0"
+    "@superrouteca/smap": "1.1.1"
   },
   "peerDependencies": {
     "@arcgis/core": "^5.0.0"
@@ -62,6 +62,7 @@
   },
   "devDependencies": {
     "@arcgis/core": "5.1.27",
+    "@maplibre/maplibre-gl-style-spec": "26.4.4",
     "typescript": "6.0.3"
   }
 }

package/src/basemap.js

@@ -8,6 +8,7 @@ import VectorTileLayer from '@arcgis/core/layers/VectorTileLayer.js';
 import WebTileLayer from '@arcgis/core/layers/WebTileLayer.js';
 import { applyBasemapOverrides } from '@superrouteca/smap';
 import { createSession, ATTRIBUTION } from './session.js';
+import { toArcGISStyle } from './style.js';
 
 const installed = new WeakMap();
 
@@ -76,10 +77,17 @@ export async function createVectorTileLayer(options = {}) {
   let style = options.style || 'light';
   let language = options.language;
   let overrides = options.basemap || null;
-  // Basemap options (contract §1: show, hide and recolour by class), applied by the SDK's own function.
+  let simplified = [];
+  // Basemap options (contract §1: show, hide and recolour by class), applied by the SDK's own function; then the
+  // style is converted into what ArcGIS's VectorTileLayer draws (style.js; `convertStyle: false` hands it over as is).
   const styled = async () => {
     const doc = await session.style(style, language);
-    return overrides && Object.keys(overrides).length ? applyBasemapOverrides(doc, overrides) : doc;
+    const own = overrides && Object.keys(overrides).length ? applyBasemapOverrides(doc, overrides) : doc;
+    if (options.convertStyle === false) { simplified = []; return own; }
+    const changes = [];
+    const out = toArcGISStyle(own, { language, changes });
+    simplified = changes;
+    return out;
   };
   const layer = new VectorTileLayer({
     id: options.id || 'smap-vector',
@@ -93,6 +101,8 @@ export async function createVectorTileLayer(options = {}) {
     get style() { return style; },
     get language() { return language; },
     basemap() { return overrides ? { ...overrides } : {}; },
+    /** What the conversion for ArcGIS simplified in the style now shown, one line per layer and property. */
+    get simplified() { return simplified.slice(); },
     setStyle(next) { style = next; return reload(); },
     setLanguage(next) { language = next; return reload(); },
     setBasemap(next) { overrides = next && Object.keys(next).length ? { ...next } : null; return reload(); },

package/src/index.js

@@ -1,6 +1,7 @@
 // @superrouteca/smap-arcgis — sMap and the ArcGIS Maps SDK for JavaScript both ways.
 export { Session, createSession, FLAVORS, ATTRIBUTION } from './session.js';
 export { installInterceptor, createVectorTileLayer, createRasterTileLayer, createSMapBasemap, addAttribution } from './basemap.js';
+export { toArcGISStyle, styleLanguage, nameExpression } from './style.js';
 export { createGraphicsLayer, symbolFor, toArcGisGeometries, toFeatures, zoomToScale } from './graphics.js';
 export { addArcGisService, queryFeatures, serviceInfo, parseServiceUrl, withToken, symbolToSimplestyle, rendererStyle } from './services.js';
-export const version = '1.1.0';
+export const version = '1.1.1';

package/src/style.js

@@ -0,0 +1,251 @@
+// sMap's styles made readable by the ArcGIS Maps SDK's VectorTileLayer, which implements only part of the style
+// specification. Measured against @arcgis/core 5.1.27 (its views/2d/engine/vectorTiles: expression.js, Filter.js,
+// StyleProperty.js, StyleDefinition.js) and checked in a browser:
+//
+//  - `is-supported-script` is not implemented: a text-field that uses it fails to parse and the tiles holding such
+//    features draw nothing at all (with sMap's label expressions: the whole basemap stays empty). It becomes `true`.
+//  - `format` joins its sections with commas: one section becomes its text, several are joined with `concat`.
+//  - `coalesce` stops at the first value that is not null, but a missing property reads as undefined there, so
+//    `coalesce(get name:en, get name)` gives nothing for a feature without name:en: a chain of `get` becomes
+//    `case(has …)`.
+//  - a filter that mixes the legacy syntax and expressions (`["all", ["==", "kind", "x"], ["!", ["has", "y"]]]`) is
+//    converted as if it were all legacy and breaks: every filter is written as an expression.
+//  - properties it has no definition for (text-variable-anchor, text-radial-offset, the *-sort-key of fill / line /
+//    circle, line-gradient, …) are left out or approximated, layer types it cannot draw are left out (fill-extrusion
+//    becomes a flat fill).
+//
+// The server's style is never changed: the conversion works on a copy. `changes`, when given, receives one line per
+// simplification.
+
+const UNIMPLEMENTED = new Set(['collator', 'image', 'number-format', 'accumulated', 'feature-state', 'line-progress',
+  'within', 'heatmap-density', 'distance', 'global-state', 'elevation']);
+const COMPARISONS = new Set(['==', '!=', '<', '<=', '>', '>=']);
+const LAYER_TYPES = new Set(['background', 'fill', 'line', 'symbol', 'circle']);
+// Layout and paint properties of the style specification that @arcgis/core 5.1.27 has no definition for.
+const DROPPED = new Set(['fill-sort-key', 'fill-layer-opacity', 'line-sort-key', 'line-gradient', 'line-layer-opacity',
+  'icon-pitch-alignment', 'icon-text-fit', 'icon-text-fit-padding', 'symbol-height-anchor', 'symbol-height-offset',
+  'symbol-z-order', 'text-pitch-alignment', 'text-variable-anchor-offset', 'circle-sort-key', 'circle-pitch-alignment',
+  'circle-pitch-scale']);
+const ANCHOR_OFFSET = { center: [0, 0], top: [0, 1], bottom: [0, -1], left: [1, 0], right: [-1, 0],
+  'top-left': [0.7, 0.7], 'top-right': [-0.7, 0.7], 'bottom-left': [0.7, -0.7], 'bottom-right': [-0.7, -0.7] };
+
+class Unsupported extends Error {}
+
+const isGet = (e) => Array.isArray(e) && e[0] === 'get' && e.length === 2 && typeof e[1] === 'string';
+const clone = (v) => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+
+/** The language of sMap's labels: the first `name:<lang>` the style reads. */
+export function styleLanguage(style) {
+  const m = JSON.stringify((style && style.layers) || []).match(/"name:([A-Za-z-]+)"/);
+  return m ? m[1] : null;
+}
+
+/** A label in `language` (else the name in the local language), in expressions ArcGIS evaluates. */
+export function nameExpression(language) {
+  const chain = [];
+  if (language) { chain.push(['get', 'name:' + language]); }
+  chain.push(['get', 'pgf:name'], ['get', 'name']);
+  return rewrite(['coalesce', ...chain], { note() {} });
+}
+
+/** Rewrites one expression into what ArcGIS evaluates; throws Unsupported where it cannot. */
+function rewrite(e, ctx) {
+  if (!Array.isArray(e) || e.length === 0 || typeof e[0] !== 'string') {
+    return Array.isArray(e) ? e.map((x) => rewrite(x, ctx)) : e;
+  }
+  const op = e[0];
+  if (op === 'literal') { return e; }
+  if (op === 'is-supported-script') { ctx.note('is-supported-script read as true (local names are always shown)'); return true; }
+  if (op === 'resolved-locale') { return ctx.language || 'en'; }
+  if (op === 'image') { return rewrite(e[1], ctx); }
+  if (op === 'number-format') { return ['to-string', rewrite(e[1], ctx)]; }
+  if (op === 'format') {
+    const texts = [];
+    let options = false;
+    for (let i = 1; i < e.length; i++) {
+      const a = e[i];
+      if (a && typeof a === 'object' && !Array.isArray(a)) { if (Object.keys(a).length) { options = true; } continue; }
+      texts.push(rewrite(a, ctx));
+    }
+    if (texts.length > 1 || options) { ctx.note('format: sections joined into one text' + (options ? ', section fonts and sizes dropped' : '')); }
+    return texts.length === 1 ? texts[0] : ['concat', ...texts];
+  }
+  if (op === 'coalesce') {
+    const args = e.slice(1).map((x) => rewrite(x, ctx));
+    let out = args[args.length - 1];
+    for (let i = args.length - 2; i >= 0; i--) {
+      out = isGet(args[i]) ? ['case', ['has', args[i][1]], args[i], out] : ['coalesce', args[i], out];
+    }
+    return out;
+  }
+  if (COMPARISONS.has(op) && e.length === 4) { ctx.note(op + ': collator dropped'); return [op, rewrite(e[1], ctx), rewrite(e[2], ctx)]; }
+  if (UNIMPLEMENTED.has(op)) { throw new Unsupported(op); }
+  return [op, ...e.slice(1).map((x) => rewrite(x, ctx))];
+}
+
+// maplibre's test of whether a filter is written as an expression (the legacy syntax otherwise).
+function isExpressionFilter(f) {
+  if (f === true || f === false) { return true; }
+  if (!Array.isArray(f) || f.length === 0) { return false; }
+  switch (f[0]) {
+    case 'has': return f.length >= 2 && f[1] !== '$id' && f[1] !== '$type';
+    case 'in': return f.length >= 3 && (typeof f[1] !== 'string' || Array.isArray(f[2]));
+    case '!in': case '!has': case 'none': return false;
+    case '==': case '!=': case '>': case '>=': case '<': case '<=': return f.length !== 3 || Array.isArray(f[1]) || Array.isArray(f[2]);
+    case 'any': case 'all':
+      for (const x of f.slice(1)) { if (!isExpressionFilter(x) && typeof x !== 'boolean') { return false; } }
+      return true;
+    default: return true;
+  }
+}
+
+function legacyKey(k) { return k === '$type' ? ['geometry-type'] : k === '$id' ? ['id'] : ['get', k]; }
+
+// A legacy filter as an expression (the style specification's own conversion, without its type guards).
+function legacyToExpression(f) {
+  if (!Array.isArray(f) || f.length === 0) { return true; }
+  const [op, ...a] = f;
+  switch (op) {
+    case 'any': case 'all': return [op, ...a.map(filterExpression)];
+    case 'none': return ['!', ['any', ...a.map(filterExpression)]];
+    case 'has': return a[0] === '$type' ? true : a[0] === '$id' ? ['has-id'] : ['has', a[0]];
+    case '!has': return ['!', legacyToExpression(['has', a[0]])];
+    case 'in': return ['in', legacyKey(a[0]), ['literal', a.slice(1)]];
+    case '!in': return ['!', ['in', legacyKey(a[0]), ['literal', a.slice(1)]]];
+    case '!=': return ['!', ['==', legacyKey(a[0]), a[1]]];
+    case '==': case '<': case '<=': case '>': case '>=': return [op, legacyKey(a[0]), a[1]];
+    default: return true;
+  }
+}
+
+function filterExpression(f) {
+  if (typeof f === 'boolean') { return f; }
+  return isExpressionFilter(f) ? f : legacyToExpression(f);
+}
+
+// ArcGIS reads a bare boolean inside all / any as a legacy filter (and then the whole filter as legacy): booleans are
+// folded away.
+function foldBooleans(f) {
+  if (!Array.isArray(f) || (f[0] !== 'all' && f[0] !== 'any' && f[0] !== '!')) { return f; }
+  if (f[0] === '!') { const x = foldBooleans(f[1]); return typeof x === 'boolean' ? !x : ['!', x]; }
+  const all = f[0] === 'all';
+  const kept = [];
+  for (const x of f.slice(1).map(foldBooleans)) {
+    if (x === all) { continue; }
+    if (x === !all) { return !all; }
+    kept.push(x);
+  }
+  return kept.length === 0 ? all : kept.length === 1 ? kept[0] : [f[0], ...kept];
+}
+
+// text-variable-anchor (and text-radial-offset) as one text-anchor and text-offset: the first anchor of each list.
+function fixedAnchor(layout, note) {
+  const first = (v) => (Array.isArray(v) && v[0] === 'literal' ? first(v[1]) : Array.isArray(v) ? v[0] : v);
+  const anchors = layout['text-variable-anchor'];
+  const radial = layout['text-radial-offset'];
+  delete layout['text-variable-anchor'];
+  delete layout['text-radial-offset'];
+  if (anchors === undefined) {
+    if (radial !== undefined) { note('text-radial-offset dropped'); }
+    return;
+  }
+  const r = typeof radial === 'number' ? radial : 0;
+  const offset = (a) => (ANCHOR_OFFSET[a] || [0, 0]).map((x) => x * r);
+  if (Array.isArray(anchors) && anchors[0] === 'step') {
+    const anchor = ['step', anchors[1]];
+    const off = ['step', anchors[1]];
+    for (let i = 2; i < anchors.length; i++) {
+      if (i % 2 === 1) { anchor.push(anchors[i]); off.push(anchors[i]); continue; }
+      const a = first(anchors[i]);
+      anchor.push(a);
+      off.push(['literal', offset(a)]);
+    }
+    if (layout['text-anchor'] === undefined) { layout['text-anchor'] = anchor; }
+    if (r && layout['text-offset'] === undefined) { layout['text-offset'] = off; }
+  } else {
+    const a = first(anchors);
+    if (layout['text-anchor'] === undefined && typeof a === 'string') { layout['text-anchor'] = a; }
+    if (r && layout['text-offset'] === undefined) { layout['text-offset'] = offset(a); }
+  }
+  note('text-variable-anchor: the first anchor only' + (radial !== undefined ? ', text-radial-offset as text-offset' : ''));
+}
+
+function convertLayer(layer, ctx) {
+  const l = clone(layer);
+  const note = (what) => ctx.changes.push(l.id + ': ' + what);
+  if (l.type === 'fill-extrusion') {
+    l.type = 'fill';
+    const p = l.paint || {};
+    l.paint = {};
+    if (p['fill-extrusion-color'] !== undefined) { l.paint['fill-color'] = p['fill-extrusion-color']; }
+    if (p['fill-extrusion-opacity'] !== undefined) { l.paint['fill-opacity'] = p['fill-extrusion-opacity']; }
+    if (p['fill-extrusion-pattern'] !== undefined) { l.paint['fill-pattern'] = p['fill-extrusion-pattern']; }
+    note('fill-extrusion drawn as a flat fill');
+  }
+  if (!LAYER_TYPES.has(l.type)) { note('layer type ' + l.type + ' left out'); return null; }
+  if (l.type !== 'background' && ctx.sources && !(ctx.sources[l.source] && ctx.sources[l.source].type === 'vector')) {
+    note('layer of a ' + ((ctx.sources[l.source] && ctx.sources[l.source].type) || 'missing') + ' source left out');
+    return null;
+  }
+  const lctx = { language: ctx.language, note };
+  if (l.filter !== undefined) {
+    try {
+      l.filter = foldBooleans(rewrite(filterExpression(l.filter), lctx));
+      if (l.filter === true) { delete l.filter; } else if (l.filter === false) { l.filter = ['==', 1, 0]; }
+    } catch (e) {
+      if (!(e instanceof Unsupported)) { throw e; }
+      note('filter with ' + e.message + ' dropped');
+      delete l.filter;
+    }
+  }
+  if (l.layout && (l.layout['text-variable-anchor'] !== undefined || l.layout['text-radial-offset'] !== undefined)) { fixedAnchor(l.layout, note); }
+  for (const kind of ['layout', 'paint']) {
+    const props = l[kind];
+    if (!props) { continue; }
+    for (const name of Object.keys(props)) {
+      if (DROPPED.has(name)) { delete props[name]; note(name + ' dropped'); continue; }
+      if (name === 'text-overlap' || name === 'icon-overlap') {
+        const v = props[name];
+        delete props[name];
+        const allow = name.replace('-overlap', '-allow-overlap');
+        if (props[allow] === undefined && typeof v === 'string') { props[allow] = v !== 'never'; }
+        note(name + ' as ' + allow);
+        continue;
+      }
+      try { props[name] = rewrite(props[name], lctx); } catch (e) {
+        if (!(e instanceof Unsupported)) { throw e; }
+        if (name === 'text-field') {
+          props[name] = nameExpression(ctx.language);
+          note('text-field with ' + e.message + ' read as the name in the label language');
+        } else {
+          delete props[name];
+          note(name + ' with ' + e.message + ' dropped');
+        }
+      }
+    }
+  }
+  return l;
+}
+
+/**
+ * A copy of an sMap style (or any style of the specification) that ArcGIS's VectorTileLayer draws: filters written
+ * as expressions, labels without the operators ArcGIS lacks, and properties it has no definition for left out or
+ * approximated (see the top of this file).
+ *
+ * @param {object} style  a style document
+ * @param {{ language?: string, changes?: string[] }} [options]  `language` of the fallback label (read from the
+ *        style when not given); `changes` receives one line per simplification
+ * @returns {object} the converted copy
+ */
+export function toArcGISStyle(style, options = {}) {
+  if (!style || !Array.isArray(style.layers)) { return style; }
+  const changes = [];
+  const ctx = { language: options.language || styleLanguage(style), sources: style.sources || null, changes };
+  const out = { ...style, layers: [] };
+  for (const layer of style.layers) {
+    const l = convertLayer(layer, ctx);
+    if (l) { out.layers.push(l); }
+  }
+  if (Array.isArray(options.changes)) { options.changes.push(...[...new Set(changes)]); }
+  return out;
+}

package/types/index.d.ts

@@ -86,10 +86,27 @@ export interface SMapVectorInfo extends SMapLayerInfo {
   /** Basemap options by class (contract §1), replacing the previous ones; `{}` clears. */
   setBasemap(overrides: BasemapOverrides): Promise<VectorTileLayer>;
   basemap(): BasemapOverrides;
+  /** What the conversion for ArcGIS simplified in the style now shown ("<layer id>: <what>"), see toArcGISStyle. */
+  readonly simplified: string[];
 }
-export declare function createVectorTileLayer(options?: LayerCommon & { basemap?: BasemapOverrides }): Promise<VectorTileLayer & { smap: SMapVectorInfo }>;
+interface VectorOptions {
+  basemap?: BasemapOverrides;
+  /** false hands sMap's style to ArcGIS unconverted (default true: see toArcGISStyle). */
+  convertStyle?: boolean;
+}
+export declare function createVectorTileLayer(options?: LayerCommon & VectorOptions): Promise<VectorTileLayer & { smap: SMapVectorInfo }>;
 export declare function createRasterTileLayer(options?: LayerCommon & { retina?: boolean }): Promise<WebTileLayer & { smap: SMapLayerInfo }>;
-export declare function createSMapBasemap(options?: LayerCommon & { raster?: boolean; retina?: boolean; basemapId?: string; basemap?: BasemapOverrides }): Promise<Basemap & { smap: SMapLayerInfo | SMapVectorInfo }>;
+export declare function createSMapBasemap(options?: LayerCommon & VectorOptions & { raster?: boolean; retina?: boolean; basemapId?: string }): Promise<Basemap & { smap: SMapLayerInfo | SMapVectorInfo }>;
+/**
+ * A copy of a style that ArcGIS's VectorTileLayer draws: filters as expressions, labels without the operators ArcGIS
+ * lacks (is-supported-script, format, coalesce of properties), properties and layer types ArcGIS has no definition
+ * for left out or approximated. `changes` receives one line per simplification.
+ */
+export declare function toArcGISStyle<T extends { layers?: unknown[] } | null | undefined>(style: T, options?: { language?: string; changes?: string[] }): T;
+/** The label language of an sMap style (the first name:<lang> it reads), or null. */
+export declare function styleLanguage(style: { layers?: unknown[] }): string | null;
+/** The label expression the conversion falls back to: the name in `language`, else the local name. */
+export declare function nameExpression(language?: string | null): unknown[];
 export declare function addAttribution(view: { ui: { add(el: HTMLElement, position: string): void }; container?: HTMLElement | null }, options?: { document?: Document }): HTMLElement;
 
 export type GraphicsKind = 'points' | 'lines' | 'areas';