@elastic/ems-client 8.1.0 → 8.3.1

package/.backportrc.json

@@ -1,5 +1,27 @@
 {
   "upstream": "elastic/ems-client",
-  "branches": [{ "name": "7.x", "checked": true }, "7.2", "7.6", "7.7", "7.8", "7.9"],
-  "labels": ["backport"]
-}
+  "branches": [
+    {
+      "name": "8.2",
+      "checked": true
+    },
+    "8.1",
+    "8.0",
+    "7.17",
+    "7.16",
+    "7.16",
+    "7.15",
+    "7.14",
+    "7.12",
+    "7.11",
+    "7.10",
+    "7.9",
+    "7.8",
+    "7.7",
+    "7.6",
+    "7.2"
+  ],
+  "labels": [
+    "backport"
+  ]
+}

package/.ci/jobs/elastic+ems-client+pull-request.yml

@@ -15,4 +15,5 @@
         allow-whitelist-orgs-as-admins: true
         github-hooks: true
         cancel-builds-on-update: true
+        status-context: ems-client
     publishers: []

package/CHANGELOG.md

@@ -3,6 +3,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [8.3.1] - 2022-05-06
+
+ - Added static methods to help translating basemap labels and blending colors to paint properties #105
+- Add optional `format` argument to `getMinZoom` and `getMaxZoom` #90
+
+## [8.3.0] - 2022-04-18
+
+### Changed
+ - Default EMS version is 8.3 #104
+ - Bump maplibre-gl to 2.1.9 #103
+
+## [8.2.0] - 2022-03-24
+
+### Changed
+ - Default EMS version is 8.2
+ - Removed getOrigin method #91
+
 ## [8.1.0] - 2021-11-09
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elastic/ems-client",
-  "version": "8.1.0",
+  "version": "8.3.1",
   "description": "JavaScript client library for the Elastic Maps Service",
   "main": "target/node/index.js",
   "browser": "target/web/index.js",
@@ -39,6 +39,7 @@
     "@types/lru-cache": "^5.1.0",
     "@types/topojson-client": "^3.0.0",
     "@types/topojson-specification": "^1.0.1",
+    "chroma-js": "^2.1.0",
     "lodash": "^4.17.15",
     "lru-cache": "^6.0.0",
     "semver": "^7.3.2",
@@ -50,6 +51,7 @@
     "@babel/plugin-proposal-class-properties": "^7.5.5",
     "@babel/preset-env": "^7.5.5",
     "@babel/preset-typescript": "^7.9.0",
+    "@types/chroma-js": "^2.1.3",
     "@types/jest": "^26.0.10",
     "@types/lodash": "^4.14.150",
     "@types/node": "^13.13.5",
@@ -63,10 +65,10 @@
     "eslint-plugin-prettier": "^3.1.3",
     "husky": "^4.2.5",
     "jest": "^26.4.0",
-    "maplibre-gl": "^1.15.2",
+    "maplibre-gl": "2.1.9",
     "node-fetch": "^2.6.1",
     "prettier": "^2.0.5",
     "ts-jest": "^26.2.0",
-    "typescript": "^3.9.2"
+    "typescript": "4.6.3"
   }
 }

package/src/ems_client.ts

@@ -16,7 +16,7 @@ import { toAbsoluteUrl } from './utils';
 import { ParsedUrlQueryInput } from 'querystring';
 import LRUCache from 'lru-cache';
 
-const DEFAULT_EMS_VERSION = '8.1';
+const DEFAULT_EMS_VERSION = '8.3';
 
 type URLMeaningfulParts = {
   auth?: string | null;

package/src/ems_service.ts

@@ -6,7 +6,6 @@
  */
 
 import { EMSClient, BaseEmsServiceConfig } from './ems_client';
-import { ORIGIN } from './origin';
 import { toAbsoluteUrl } from './utils';
 
 export interface IEmsService {
@@ -15,7 +14,6 @@ export interface IEmsService {
   getDisplayName(): string;
   getId(): string;
   hasId(id: string): boolean;
-  getOrigin(): string;
   getApiUrl(): string;
 }
 
@@ -50,10 +48,6 @@ export abstract class AbstractEmsService implements IEmsService {
     return attributions.join('|');
   }
 
-  getOrigin(): string {
-    return ORIGIN.EMS;
-  }
-
   /**
    * Checks if url is absolute. If not, prepend the basePath.
    */

package/src/index.ts

@@ -6,6 +6,5 @@
  */
 
 export { EMSClient, FileLayerField } from './ems_client';
-export { ORIGIN } from './origin';
 export { FileLayer } from './file_layer';
 export { TMSService, EmsSprite, EmsSpriteSheet } from './tms_service';

package/src/tms_service.ts

@@ -6,9 +6,16 @@
  */
 
 import _ from 'lodash';
-import { Style as MapLibreStyle, VectorSource as MapLibreVectorSource } from 'maplibre-gl';
+import {
+  DataDrivenPropertyValueSpecification,
+  FormattedSpecification,
+  LayerSpecification,
+  StyleSpecification,
+  VectorSourceSpecification,
+} from 'maplibre-gl';
 import { EMSClient, EmsTmsFormat, TMSServiceConfig } from './ems_client';
 import { AbstractEmsService } from './ems_service';
+import { layerPaintProperty, colorizeColor, blendMode, mbColorDefinition } from './utils';
 
 export type EmsSprite = {
   height: number;
@@ -24,10 +31,10 @@ export type EmsSpriteSheet = {
 };
 
 type EmsVectorSources = {
-  [sourceName: string]: MapLibreVectorSource;
+  [sourceName: string]: VectorSourceSpecification;
 };
 
-type EmsVectorStyle = MapLibreStyle & {
+type EmsVectorStyle = StyleSpecification & {
   sources: EmsVectorSources;
 };
 
@@ -45,6 +52,84 @@ type EmsRasterStyle = {
 };
 
 export class TMSService extends AbstractEmsService {
+  /*
+  List of supported languages with labels and OMT codes extracted
+  from https://openmaptiles.org/languages
+
+  Keys are values for i18.locale from Kibana settings
+  and OMT codes for the rest. 
+  */
+  public static SupportedLanguages = [
+    { key: 'ar', omt: 'ar' },
+    { key: 'az', omt: 'az' },
+    { key: 'be', omt: 'be' },
+    { key: 'bg', omt: 'bg' },
+    { key: 'br', omt: 'br' },
+    { key: 'bs', omt: 'bs' },
+    { key: 'ca', omt: 'ca' },
+    { key: 'cs', omt: 'cs' },
+    { key: 'cy', omt: 'cy' },
+    { key: 'da', omt: 'da' },
+    { key: 'de', omt: 'de' },
+    { key: 'el', omt: 'el' },
+    { key: 'en', omt: 'en' },
+    { key: 'eo', omt: 'eo' },
+    { key: 'es', omt: 'es' },
+    { key: 'et', omt: 'et' },
+    { key: 'fi', omt: 'fi' },
+    { key: 'fr-fr', omt: 'fr' },
+    { key: 'fy', omt: 'fy' },
+    { key: 'ga', omt: 'ga' },
+    { key: 'gd', omt: 'gd' },
+    { key: 'he', omt: 'he' },
+    { key: 'hi-in', omt: 'hi' },
+    { key: 'hr', omt: 'hr' },
+    { key: 'hu', omt: 'hu' },
+    { key: 'hy', omt: 'hy' },
+    { key: 'is', omt: 'is' },
+    { key: 'it', omt: 'it' },
+    { key: 'ja_kana', omt: 'ja_kana' },
+    { key: 'ja_rm', omt: 'ja_rm' },
+    { key: 'ja-jp', omt: 'ja' },
+    { key: 'ka', omt: 'ka' },
+    { key: 'kk', omt: 'kk' },
+    { key: 'kn', omt: 'kn' },
+    { key: 'ko_rm', omt: 'ko_rm' },
+    { key: 'ko', omt: 'ko' },
+    { key: 'la', omt: 'la' },
+    { key: 'lb', omt: 'lb' },
+    { key: 'lt', omt: 'lt' },
+    { key: 'lv', omt: 'lv' },
+    { key: 'mk', omt: 'mk' },
+    { key: 'mt', omt: 'mt' },
+    { key: 'nl', omt: 'nl' },
+    { key: 'no', omt: 'no' },
+    { key: 'pl', omt: 'pl' },
+    { key: 'pt-pt', omt: 'pt' },
+    { key: 'rm', omt: 'rm' },
+    { key: 'ro', omt: 'ro' },
+    { key: 'ru-ru', omt: 'ru' },
+    { key: 'sk', omt: 'sk' },
+    { key: 'sl', omt: 'sl' },
+    { key: 'sq', omt: 'sq' },
+    { key: 'sr-Ltn', omt: 'sr-Ltn' },
+    { key: 'sr', omt: 'sr' },
+    { key: 'sv', omt: 'sv' },
+    { key: 'th', omt: 'th' },
+    { key: 'tr', omt: 'tr' },
+    { key: 'uk', omt: 'uk' },
+    { key: 'zh-cn', omt: 'zh' },
+  ];
+
+  /*
+  Suggested default operations for the different EMS styles
+  */
+  public static colorOperationDefaults = [
+    { style: 'road_map', operation: 'mix', percentage: 0.25 },
+    { style: 'road_map_desaturated', operation: 'screen', percentage: 0.25 },
+    { style: 'dark_map', operation: 'dodge', percentage: 0.25 },
+  ];
+
   protected readonly _config: TMSServiceConfig;
 
   private _getRasterStyleJson = _.once(async (): Promise<EmsRasterStyle | undefined> => {
@@ -80,7 +165,9 @@ export class TMSService extends AbstractEmsService {
         if (url) {
           const sourceUrl = this._proxyPath + this._getAbsoluteUrl(url);
           const extendedUrl = this._emsClient.extendUrlWithParams(sourceUrl);
-          const sourceJson = await this._emsClient.getManifest<MapLibreVectorSource>(extendedUrl);
+          const sourceJson = await this._emsClient.getManifest<VectorSourceSpecification>(
+            extendedUrl
+          );
           const tiles = sourceJson?.tiles?.map((tileUrl) => {
             const directUrl = this._proxyPath + this._getAbsoluteUrl(tileUrl);
             return this._emsClient.extendUrlWithParams(directUrl);
@@ -108,6 +195,91 @@ export class TMSService extends AbstractEmsService {
     this._config = config;
   }
 
+  /*
+  This method returns an array of objects with the layers and the new
+  layout['text-field'] to apply using map.setLayoutProperty
+  */
+  public static transformLanguageProperty(
+    layer: LayerSpecification,
+    lang: string
+  ): DataDrivenPropertyValueSpecification<FormattedSpecification> | undefined {
+    const supportedLang = this.SupportedLanguages.find((l) => l.key === lang);
+    if (layer.type === 'symbol' && layer.layout !== undefined && supportedLang !== undefined) {
+      const omtLang = supportedLang.omt;
+      const textField = layer.layout['text-field'];
+      if (textField && typeof textField === 'string') {
+        return TMSService._getTextField(textField, omtLang);
+      }
+    }
+    return;
+  }
+
+  /*
+  This method returns an array of objects per layer, containing a list of
+  properties with new colors to apply using map.setPaintProperty
+  */
+  public static transformColorProperties(
+    layer: LayerSpecification,
+    color: string,
+    operation: blendMode,
+    percentage: number
+  ): { property: keyof layerPaintProperty; color: mbColorDefinition | undefined }[] {
+    if (['background', 'fill', 'line', 'symbol'].indexOf(layer.type) !== -1 && layer.paint) {
+      const paint = layer.paint as layerPaintProperty;
+      if (layer.type === 'symbol' && Object.keys(paint).length === 0) {
+        paint['text-color'] = 'rgb(0,0,0)';
+      }
+      const types = Object.keys(paint).filter((key) => {
+        return (
+          [
+            'background-color',
+            'circle-color',
+            'circle-stroke-color',
+            'fill-color',
+            'fill-extrusion-color',
+            'fill-outline-color',
+            'icon-color',
+            'icon-halo-color',
+            'line-color',
+            'text-color',
+            'text-halo-color',
+          ].indexOf(key) !== -1
+        );
+      }) as Array<keyof layerPaintProperty>;
+      return types.map((type) => {
+        const paintColor = paint[type];
+        return {
+          property: type,
+          color: paintColor ? colorizeColor(paintColor, color, operation, percentage) : paintColor,
+        };
+      });
+    } else {
+      return [];
+    }
+  }
+
+  private static _getTextField(
+    label: string,
+    lang: string
+  ): DataDrivenPropertyValueSpecification<string> {
+    // Capture {name:xx} labels
+    const labelMatch = label.match(/\{name([:_])(.{2})\}/);
+    if (labelMatch && labelMatch[1] != lang) {
+      // Only apply if the languages are different
+      return ['coalesce', ['get', `name:${lang}`], ['get', `name${labelMatch[1]}${labelMatch[2]}`]];
+    } else if (label.includes('latin') && label.includes('nonlatin')) {
+      // Capture the common pattern {name:latin}\n{name:nonlatin}
+      return [
+        'coalesce',
+        ['get', `name:${lang}`],
+        ['concat', ['get', 'name:latin'], '\n', ['get', 'name:nonlatin']],
+      ];
+    }
+
+    // If no case is found, return the input label
+    return label;
+  }
+
   async getDefaultRasterStyle(): Promise<EmsRasterStyle | undefined> {
     const tileJson = await this._getRasterStyleJson();
     if (tileJson) {
@@ -193,21 +365,37 @@ export class TMSService extends AbstractEmsService {
     return this._emsClient.getValueInLanguage(this._config.name);
   }
 
-  async getMinZoom(): Promise<number | undefined> {
-    const tileJson = await this._getRasterStyleJson();
-    if (tileJson) {
-      return tileJson.minzoom;
-    } else {
-      return;
+  async getMinZoom(format = 'vector'): Promise<number | undefined> {
+    switch (format) {
+      case 'vector':
+        const { sources } = (await this._getVectorStyleJsonInlined()) || { sources: {} };
+        return Math.min(
+          ...Object.values(sources)
+            .map(({ minzoom }) => minzoom)
+            .filter((minzoom): minzoom is number => Number.isFinite(minzoom))
+        );
+      case 'raster':
+        const { minzoom } = (await this._getRasterStyleJson()) || {};
+        return minzoom;
+      default:
+        return;
     }
   }
 
-  async getMaxZoom(): Promise<number | undefined> {
-    const tileJson = await this._getRasterStyleJson();
-    if (tileJson) {
-      return tileJson.maxzoom;
-    } else {
-      return;
+  async getMaxZoom(format = 'vector'): Promise<number | undefined> {
+    switch (format) {
+      case 'vector':
+        const { sources } = (await this._getVectorStyleJsonInlined()) || { sources: {} };
+        return Math.max(
+          ...Object.values(sources)
+            .map(({ maxzoom }) => maxzoom)
+            .filter((maxzoom): maxzoom is number => Number.isFinite(maxzoom))
+        );
+      case 'raster':
+        const { maxzoom } = (await this._getRasterStyleJson()) || {};
+        return maxzoom;
+      default:
+        return;
     }
   }
 

package/src/utils.ts

@@ -5,6 +5,13 @@
  * 2.0.
  */
 
+import chroma, { ChromaStatic } from 'chroma-js';
+import {
+  ColorSpecification,
+  DataDrivenPropertyValueSpecification,
+  PropertyValueSpecification,
+} from 'maplibre-gl';
+
 /**
  * Resolves a target URL path relative to the host.
  * This is specifically useed by the Kibana proxy re-routing.
@@ -25,3 +32,85 @@ export function toAbsoluteUrl(host: string | undefined, path: string): string {
     return host + '/' + path;
   }
 }
+
+/*
+Type with the possible ways to define a color in maplibre
+*/
+export type mbColorDefinition =
+  | PropertyValueSpecification<ColorSpecification>
+  | DataDrivenPropertyValueSpecification<ColorSpecification>;
+
+/*
+A selection of the different maplibre-gl-js properties that refer to a color.
+Taken from maplibre https://github.com/maplibre/maplibre-gl-js/blob/main/src/style-spec/types.g.ts
+*/
+export type layerPaintProperty = {
+  'background-color'?: PropertyValueSpecification<ColorSpecification>;
+  'circle-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'circle-stroke-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'fill-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'fill-extrusion-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'fill-outline-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'icon-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'icon-halo-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'line-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'text-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+  'text-halo-color'?: DataDrivenPropertyValueSpecification<ColorSpecification>;
+};
+
+export type blendMode = Parameters<ChromaStatic['blend']>[2] | 'mix';
+
+/*
+Function to transform a maplibre color definition by a given function.
+*/
+function transformColor(paintColor: mbColorDefinition, func: Function): mbColorDefinition {
+  if (typeof paintColor == 'string') {
+    const modifiedColor = func(paintColor);
+    return `rgba(${modifiedColor.rgba().join(',')})`;
+  } else if (
+    typeof paintColor == 'object' &&
+    'stops' in paintColor &&
+    Array.isArray(paintColor?.stops)
+  ) {
+    const stops = paintColor['stops'].map((stop) => {
+      const newColor = transformColor(stop[1], func);
+      return [stop[0], newColor];
+    });
+    const newPaintColor = { ...paintColor, ...stops };
+    return newPaintColor;
+  } else return paintColor;
+}
+
+/*
+This is the function used to generate the current EMS desaturated roadmap
+*/
+export function desaturateColor(paintColor: mbColorDefinition): mbColorDefinition {
+  return transformColor(paintColor, (color: string) => {
+    return chroma(color).desaturate(1.1).brighten(0.33);
+  });
+}
+
+/*
+Blends an original maplibre color definition with a destination
+color. Accepts different blending modes and an additional `mix`
+option that needs a percentage.
+
+More details: 
+
+https://gka.github.io/chroma.js/#chroma-blend
+https://gka.github.io/chroma.js/#chroma-mix
+*/
+export function colorizeColor(
+  sourceColor: mbColorDefinition,
+  destColor: string,
+  operation: blendMode = 'screen',
+  percentage: number = 0.5
+): mbColorDefinition {
+  return transformColor(sourceColor, (color: string) => {
+    if (operation !== 'mix') {
+      return chroma.blend(chroma(color), destColor, operation);
+    } else {
+      return chroma.mix(chroma(color), destColor, percentage);
+    }
+  });
+}

package/target/ems_service.d.ts

@@ -8,7 +8,6 @@ export interface IEmsService {
     getDisplayName(): string;
     getId(): string;
     hasId(id: string): boolean;
-    getOrigin(): string;
     getApiUrl(): string;
 }
 export declare abstract class AbstractEmsService implements IEmsService {
@@ -21,7 +20,6 @@ export declare abstract class AbstractEmsService implements IEmsService {
         label: string;
     }[];
     getMarkdownAttribution(): string;
-    getOrigin(): string;
     /**
      * Checks if url is absolute. If not, prepend the basePath.
      */

package/target/index.d.ts

@@ -1,4 +1,3 @@
 export { EMSClient, FileLayerField } from './ems_client';
-export { ORIGIN } from './origin';
 export { FileLayer } from './file_layer';
 export { TMSService, EmsSprite, EmsSpriteSheet } from './tms_service';

package/target/node/ems_client.js

@@ -23,7 +23,7 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
 
 function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 
-const DEFAULT_EMS_VERSION = '8.1';
+const DEFAULT_EMS_VERSION = '8.3';
 
 /**
  * plugins cannot have upstream dependencies on core/*-kibana.

package/target/node/ems_service.js

@@ -5,8 +5,6 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.AbstractEmsService = void 0;
 
-var _origin = require("./origin");
-
 var _utils = require("./utils");
 
 function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
@@ -56,10 +54,6 @@ class AbstractEmsService {
 
     return attributions.join('|');
   }
-
-  getOrigin() {
-    return _origin.ORIGIN.EMS;
-  }
   /**
    * Checks if url is absolute. If not, prepend the basePath.
    */

package/target/node/index.js

@@ -33,12 +33,6 @@ Object.defineProperty(exports, "FileLayerField", {
     return _ems_client.FileLayerField;
   }
 });
-Object.defineProperty(exports, "ORIGIN", {
-  enumerable: true,
-  get: function () {
-    return _origin.ORIGIN;
-  }
-});
 Object.defineProperty(exports, "TMSService", {
   enumerable: true,
   get: function () {
@@ -48,8 +42,6 @@ Object.defineProperty(exports, "TMSService", {
 
 var _ems_client = require("./ems_client");
 
-var _origin = require("./origin");
-
 var _file_layer = require("./file_layer");
 
 var _tms_service = require("./tms_service");