@deck.gl/carto 9.0.14 → 9.0.15

package/package.json

@@ -3,7 +3,7 @@
   "description": "CARTO official integration with Deck.gl. Build geospatial applications using CARTO and Deck.gl.",
   "license": "MIT",
   "type": "module",
-  "version": "9.0.14",
+  "version": "9.0.15",
   "publishConfig": {
     "access": "public"
   },
@@ -47,14 +47,14 @@
     "@loaders.gl/mvt": "^4.2.0",
     "@loaders.gl/schema": "^4.2.0",
     "@loaders.gl/tiles": "^4.2.0",
-    "@luma.gl/constants": "^9.0.11",
-    "@luma.gl/core": "^9.0.11",
-    "@luma.gl/shadertools": "^9.0.11",
+    "@luma.gl/constants": "^9.0.14",
+    "@luma.gl/core": "^9.0.14",
+    "@luma.gl/shadertools": "^9.0.14",
     "@math.gl/web-mercator": "^4.0.0",
     "@types/d3-array": "^3.0.2",
     "@types/d3-color": "^1.4.2",
     "@types/d3-scale": "^3.0.0",
-    "cartocolor": "^4.0.2",
+    "cartocolor": "^5.0.2",
     "d3-array": "^3.2.0",
     "d3-color": "^3.1.0",
     "d3-format": "^3.1.0",
@@ -73,5 +73,5 @@
     "@deck.gl/layers": "^9.0.0",
     "@loaders.gl/core": "^4.2.0"
   },
-  "gitHead": "c04824ba260eab253cf0fd5d743ce8c3dada0762"
+  "gitHead": "4eecc3c070efa04baecc83b3d5f4ddacb4ba147c"
 }

package/src/api/basemap.ts

@@ -0,0 +1,100 @@
+import {MapViewState} from '@deck.gl/core';
+import {
+  GOOGLE_BASEMAPS,
+  CARTO_MAP_STYLES,
+  applyLayerGroupFilters,
+  fetchStyle,
+  getStyleUrl,
+  someLayerGroupsDisabled
+} from '../basemap';
+import {APIErrorContext, Basemap, KeplerMapConfig, MapLibreBasemapProps} from './types';
+
+const CUSTOM_STYLE_ID_PREFIX = 'custom:';
+const DEFAULT_CARTO_STYLE = 'positron';
+
+function mapLibreViewpros(config: KeplerMapConfig): Omit<MapLibreBasemapProps, 'style'> {
+  const {longitude, latitude, ...rest} = config.mapState as MapViewState;
+  return {
+    center: [longitude, latitude],
+    ...rest
+  };
+}
+
+/**
+ * Get basemap properties for Carto map.
+ *
+ * For maplibre-based basemaps it returns style or style URL that can be used with  `maplibregl.Map` compatible component.
+ *  * style url is returned for non-filtered standard Carto basemaps or if user used style URL directly in configuration
+ *  * filtered style object returned for Carto basemaps with layer groups filtered
+ *
+ * For Google-maps base maps, it returns options that can be used with `google.maps.Map` constructor.
+ */
+export async function fetchBasemapProps({
+  config,
+  errorContext,
+
+  applyLayerFilters = true
+}: {
+  config: KeplerMapConfig;
+
+  /** By default `fetchBasemapProps` applies layers filters to style. Set this to `false` to disable it. */
+  applyLayerFilters?: boolean;
+  errorContext?: APIErrorContext;
+}): Promise<Basemap | null> {
+  const {mapStyle} = config;
+  const styleType = mapStyle.styleType || DEFAULT_CARTO_STYLE;
+  if (styleType.startsWith(CUSTOM_STYLE_ID_PREFIX)) {
+    const currentCustomStyle = config.customBaseMaps?.customStyle;
+    if (currentCustomStyle) {
+      return {
+        type: 'maplibre',
+        props: {
+          style: currentCustomStyle.style || currentCustomStyle.url,
+          ...mapLibreViewpros(config)
+        },
+        attribution: currentCustomStyle.customAttribution
+      };
+    }
+  }
+
+  if (CARTO_MAP_STYLES.includes(styleType)) {
+    const {visibleLayerGroups} = mapStyle;
+    const styleUrl = getStyleUrl(styleType);
+    let style = styleUrl;
+    let rawStyle = styleUrl;
+    if (applyLayerFilters && visibleLayerGroups && someLayerGroupsDisabled(visibleLayerGroups)) {
+      rawStyle = await fetchStyle({styleUrl, errorContext});
+      style = applyLayerGroupFilters(rawStyle, visibleLayerGroups);
+    }
+    return {
+      type: 'maplibre',
+      props: {
+        style,
+        ...mapLibreViewpros(config)
+      },
+      visibleLayerGroups,
+      rawStyle
+    };
+  }
+  const googleBasemapDef = GOOGLE_BASEMAPS[styleType];
+  if (googleBasemapDef) {
+    const {mapState} = config;
+    return {
+      type: 'google-maps',
+      props: {
+        ...googleBasemapDef,
+        center: {lat: mapState.latitude, lng: mapState.longitude},
+        zoom: mapState.zoom + 1,
+        tilt: mapState.pitch,
+        heading: mapState.bearing
+      }
+    };
+  }
+  return {
+    type: 'maplibre',
+    props: {
+      style: getStyleUrl(DEFAULT_CARTO_STYLE),
+      ...mapLibreViewpros(config)
+    }
+  };
+}

package/src/api/fetch-map.ts

@@ -17,10 +17,11 @@ import {
   vectorTableSource,
   vectorTilesetSource
 } from '../sources/index';
-import {parseMap} from './parse-map';
+import {ParseMapResult, parseMap} from './parse-map';
 import {requestWithParameters} from './request-with-parameters';
 import {assert} from '../utils';
-import type {APIErrorContext, Format, MapType, QueryParameters} from './types';
+import type {APIErrorContext, Basemap, Format, MapType, QueryParameters} from './types';
+import {fetchBasemapProps} from './basemap';
 
 type Dataset = {
   id: string;
@@ -213,6 +214,14 @@ export type FetchMapOptions = {
   onNewData?: (map: any) => void;
 };
 
+export type FetchMapResult = ParseMapResult & {
+  /**
+   * Basemap properties.
+   */
+  basemap: Basemap | null;
+  stopAutoRefresh?: () => void;
+};
+
 /* eslint-disable max-statements */
 export async function fetchMap({
   apiBaseUrl = DEFAULT_API_BASE_URL,
@@ -221,7 +230,7 @@ export async function fetchMap({
   headers = {},
   autoRefresh,
   onNewData
-}: FetchMapOptions) {
+}: FetchMapOptions): Promise<FetchMapResult> {
   assert(cartoMapId, 'Must define CARTO map id: fetchMap({cartoMapId: "XXXX-XXXX-XXXX"})');
   assert(apiBaseUrl, 'Must define apiBaseUrl');
 
@@ -272,12 +281,17 @@ export async function fetchMap({
     }
   });
 
-  // Mutates map.datasets so that dataset.data contains data
-  await fillInMapDatasets(map, clientId, apiBaseUrl, headers);
+  const [basemap] = await Promise.all([
+    fetchBasemapProps({config: map.keplerMapConfig.config, errorContext}),
+
+    // Mutates map.datasets so that dataset.data contains data
+    fillInMapDatasets(map, clientId, apiBaseUrl, headers)
+  ]);
 
   // Mutates attributes in visualChannels to contain tile stats
   await fillInTileStats(map, apiBaseUrl);
-  const out = {...parseMap(map), ...{stopAutoRefresh}};
+
+  const out = {...parseMap(map), basemap, ...{stopAutoRefresh}};
 
   const textLayers = out.layers.filter(layer => {
     const pointType = layer.props.pointType || '';

package/src/api/index.ts

@@ -1,6 +1,15 @@
 export {CartoAPIError} from './carto-api-error';
 export {fetchMap} from './fetch-map';
-export type {FetchMapOptions} from './fetch-map';
-export type {APIErrorContext, Format, MapType, RequestType, QueryParameters} from './types';
+export type {FetchMapOptions, FetchMapResult} from './fetch-map';
+export type {
+  APIErrorContext,
+  Format,
+  MapType,
+  RequestType,
+  QueryParameters,
+  Basemap,
+  MapLibreBasemap,
+  GoogleBasemap
+} from './types';
 export {query} from './query';
 export type {QueryOptions} from './query';

package/src/api/parse-map.ts

@@ -1,5 +1,5 @@
 import {GL} from '@luma.gl/constants';
-import {log} from '@deck.gl/core';
+import {Layer, log} from '@deck.gl/core';
 import {
   AGGREGATION,
   getLayer,
@@ -16,14 +16,34 @@ import {
 import PointLabelLayer from '../layers/point-label-layer';
 import {CollisionFilterExtension} from '@deck.gl/extensions';
 import {assert} from '../utils';
-import {MapDataset, MapLayerConfig, VisualChannels} from './types';
+import {KeplerMapConfig, MapDataset, MapLayerConfig, VisualChannels} from './types';
 
 const collisionFilterExtension = new CollisionFilterExtension();
 
+export type ParseMapResult = {
+  /** Map id. */
+  id: string;
+
+  /** Title of map. */
+  title: string;
+
+  /** Description of map. */
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+  initialViewState: any;
+
+  /** @deprecated Use `basemap`. */
+  mapStyle: any;
+  token: string;
+
+  layers: Layer[];
+};
+
 export function parseMap(json) {
   const {keplerMapConfig, datasets, token} = json;
   assert(keplerMapConfig.version === 'v1', 'Only support Kepler v1');
-  const {mapState, mapStyle} = keplerMapConfig.config;
+  const {mapState, mapStyle} = keplerMapConfig.config as KeplerMapConfig;
   const {layers, layerBlending, interactionConfig} = keplerMapConfig.config.visState;
 
   return {
@@ -33,6 +53,7 @@ export function parseMap(json) {
     createdAt: json.createdAt,
     updatedAt: json.updatedAt,
     initialViewState: mapState,
+    /** @deprecated Use `basemap`. */
     mapStyle,
     token,
     layers: layers.reverse().map(({id, type, config, visualChannels}) => {

package/src/api/query.ts

@@ -10,6 +10,7 @@ type UrlParameters = {q: string; queryParameters?: string};
 export const query = async function (options: QueryOptions): Promise<QueryResult> {
   const {
     apiBaseUrl = SOURCE_DEFAULTS.apiBaseUrl,
+    clientId = SOURCE_DEFAULTS.clientId,
     connectionName,
     sqlQuery,
     queryParameters
@@ -22,16 +23,17 @@ export const query = async function (options: QueryOptions): Promise<QueryResult
 
   const baseUrl = buildQueryUrl({apiBaseUrl, connectionName});
   const headers = {Authorization: `Bearer ${options.accessToken}`, ...options.headers};
+  const parameters = {client: clientId, ...urlParameters};
 
   const errorContext: APIErrorContext = {
     requestType: 'SQL',
     connection: options.connectionName,
     type: 'query',
-    source: JSON.stringify(urlParameters, undefined, 2)
+    source: JSON.stringify(parameters, undefined, 2)
   };
   return await requestWithParameters<QueryResult>({
     baseUrl,
-    parameters: urlParameters,
+    parameters,
     headers,
     errorContext
   });

package/src/api/request-with-parameters.ts

@@ -1,4 +1,4 @@
-import {isPureObject} from '@loaders.gl/core';
+import {isPureObject} from '../utils';
 import {CartoAPIError} from './carto-api-error';
 import {DEFAULT_HEADERS, DEFAULT_PARAMETERS, MAX_GET_LENGTH} from './common';
 import type {APIErrorContext} from './types';

package/src/api/types.ts

@@ -2,7 +2,14 @@ import {SCALE_TYPE} from './layer-map';
 
 export type Format = 'json' | 'geojson' | 'tilejson';
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
-export type RequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL';
+export type RequestType =
+  | 'Map data'
+  | 'Map instantiation'
+  | 'Public map'
+  | 'Tile stats'
+  | 'SQL'
+  | 'Basemap style';
+
 export type APIErrorContext = {
   requestType: RequestType;
   mapId?: string;
@@ -176,3 +183,98 @@ export type MapDataset = {
   aggregationResLevel: number | null;
   geoColumn: string;
 };
+
+export interface CustomStyle {
+  url?: string;
+  style?: any;
+  customAttribution?: string;
+}
+
+export type KeplerMapConfig = {
+  mapState: any;
+  mapStyle: {
+    styleType: string;
+    visibleLayerGroups: Record<string, boolean>;
+  };
+  visState: {
+    layers: MapConfigLayer[];
+  };
+  layerBlending: any;
+  interactionConfig: any;
+  customBaseMaps?: {
+    customStyle?: CustomStyle;
+  };
+};
+
+export type BasemapType = 'maplibre' | 'google-maps';
+
+export type Basemap = MapLibreBasemap | GoogleBasemap;
+
+export type BasemapCommon = {
+  /**
+   * Type of basemap.
+   */
+  type: BasemapType;
+
+  /**
+   * Custom attribution for style data if not provided by style definition.
+   */
+  attribution?: string;
+
+  /**
+   * Properties of the basemap. These properties are specific to the basemap type.
+   */
+  props: Record<string, any>;
+};
+
+export type MapLibreBasemap = BasemapCommon & {
+  type: 'maplibre';
+
+  /**
+   * MapLibre map properties.
+   *
+   * Meant to be passed to directly to `maplibregl.Map` object.
+   */
+  props: MapLibreBasemapProps;
+
+  /**
+   * Layer groups to be displayed in the basemap.
+   */
+  visibleLayerGroups?: Record<string, boolean>;
+
+  /**
+   * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+   * can use `applyLayerGroupFilters` again with new settings.
+   */
+  rawStyle?: string | Record<string, any>;
+};
+
+// Cherry-pick of maplibregl Map API props that are supported/provided by fetchMap interface
+export type MapLibreBasemapProps = {
+  style: string | Record<string, any>;
+  center: [number, number];
+  zoom: number;
+  pitch?: number;
+  bearing?: number;
+};
+
+export type GoogleBasemap = BasemapCommon & {
+  type: 'google-maps';
+
+  /**
+   * Google map properties.
+   *
+   * Meant to be passed to directly to `google.maps.Map` object.
+   */
+  props: GoogleBasemapProps;
+};
+
+// Cherry-pick of Google Map API props that are supported/provided by fetchMap interface
+export type GoogleBasemapProps = {
+  mapTypeId: string;
+  mapId?: string;
+  center?: {lat: number; lng: number};
+  zoom?: number;
+  tilt?: number;
+  heading?: number;
+};

package/src/basemap.ts

@@ -1,10 +1,137 @@
-const baseUrl = 'https://basemaps.cartocdn.com/gl/{basemap}-gl-style/style.json';
+import {CartoAPIError} from './api/carto-api-error';
+import {APIErrorContext, GoogleBasemapProps} from './api/types';
+
+const cartoStyleUrlTemplate = 'https://basemaps.cartocdn.com/gl/{basemap}-gl-style/style.json';
+
+export const CARTO_MAP_STYLES = ['positron', 'dark-matter', 'voyager'];
+
+export const GOOGLE_BASEMAPS: Record<string, GoogleBasemapProps> = {
+  roadmap: {
+    mapTypeId: 'roadmap',
+    mapId: '3754c817b510f791'
+  },
+  'google-positron': {
+    mapTypeId: 'roadmap',
+    mapId: 'ea84ae4203ef21cd'
+  },
+  'google-dark-matter': {
+    mapTypeId: 'roadmap',
+    mapId: '2fccc3b36c22a0e2'
+  },
+  'google-voyager': {
+    mapTypeId: 'roadmap',
+    mapId: '885caf1e15bb9ef2'
+  },
+  satellite: {
+    mapTypeId: 'satellite'
+  },
+  hybrid: {
+    mapTypeId: 'hybrid'
+  },
+  terrain: {
+    mapTypeId: 'terrain'
+  }
+};
+
+type StyleLayerGroupSlug = 'label' | 'road' | 'border' | 'building' | 'water' | 'land';
+type StyleLayerGroup = {
+  slug: StyleLayerGroupSlug;
+  filter: (layer: any) => boolean;
+  defaultVisibility: boolean;
+};
+
+export const STYLE_LAYER_GROUPS: StyleLayerGroup[] = [
+  {
+    slug: 'label',
+    filter: ({id}: {id: string}) =>
+      Boolean(
+        id.match(/(?=(label|_label|place-|place_|poi-|poi_|watername_|roadname_|housenumber))/)
+      ),
+    defaultVisibility: true
+  },
+  {
+    slug: 'road',
+    filter: ({id}: {id: string}) =>
+      Boolean(id.match(/(?=(road|railway|tunnel|street|bridge))(?!.*label)/)),
+    defaultVisibility: true
+  },
+  {
+    slug: 'border',
+    filter: ({id}: {id: string}) => Boolean(id.match(/border|boundaries|boundary_/)),
+    defaultVisibility: false
+  },
+  {
+    slug: 'building',
+    filter: ({id}: {id: string}) => Boolean(id.match(/building/)),
+    defaultVisibility: true
+  },
+  {
+    slug: 'water',
+    filter: ({id}: {id: string}) => Boolean(id.match(/(?=(water|stream|ferry))/)),
+    defaultVisibility: true
+  },
+  {
+    slug: 'land',
+    filter: ({id}: {id: string}) =>
+      Boolean(id.match(/(?=(parks|landcover|industrial|sand|hillshade|park_))/)),
+    defaultVisibility: true
+  }
+];
+
+export function applyLayerGroupFilters(
+  style,
+  visibleLayerGroups: Record<StyleLayerGroupSlug, boolean>
+) {
+  if (!Array.isArray(style?.layers)) {
+    return style;
+  }
+
+  const removedLayerFilters = STYLE_LAYER_GROUPS.filter(lg => !visibleLayerGroups[lg.slug]).map(
+    lg => lg.filter
+  );
+
+  const visibleLayers = style.layers.filter(layer =>
+    removedLayerFilters.every(match => !match(layer))
+  );
+
+  return {
+    ...style,
+    layers: visibleLayers
+  };
+}
+
+export function someLayerGroupsDisabled(visibleLayerGroups?: Record<StyleLayerGroupSlug, boolean>) {
+  return visibleLayerGroups && Object.values(visibleLayerGroups).every(Boolean) === false;
+}
+
+export function getStyleUrl(styleType: string) {
+  return cartoStyleUrlTemplate.replace('{basemap}', styleType);
+}
+
+export async function fetchStyle({
+  styleUrl,
+  errorContext
+}: {
+  styleUrl: string;
+  errorContext?: APIErrorContext;
+}) {
+  /* global fetch */
+  let response: Response | undefined;
+  return await fetch(styleUrl, {mode: 'cors'})
+    .then(res => {
+      response = res;
+      return res.json();
+    })
+    .catch(error => {
+      throw new CartoAPIError(error, {...errorContext, requestType: 'Basemap style'}, response);
+    });
+}
 
 export default {
-  VOYAGER: baseUrl.replace('{basemap}', 'voyager'),
-  POSITRON: baseUrl.replace('{basemap}', 'positron'),
-  DARK_MATTER: baseUrl.replace('{basemap}', 'dark-matter'),
-  VOYAGER_NOLABELS: baseUrl.replace('{basemap}', 'voyager-nolabels'),
-  POSITRON_NOLABELS: baseUrl.replace('{basemap}', 'positron-nolabels'),
-  DARK_MATTER_NOLABELS: baseUrl.replace('{basemap}', 'dark-matter-nolabels')
+  VOYAGER: getStyleUrl('voyager'),
+  POSITRON: getStyleUrl('positron'),
+  DARK_MATTER: getStyleUrl('dark-matter'),
+  VOYAGER_NOLABELS: getStyleUrl('voyager-nolabels'),
+  POSITRON_NOLABELS: getStyleUrl('positron-nolabels'),
+  DARK_MATTER_NOLABELS: getStyleUrl('dark-matter-nolabels')
 } as const;

package/src/index.ts

@@ -22,19 +22,31 @@ export {
   VectorTileLayer
 };
 
-export {default as BASEMAP} from './basemap';
+export {
+  default as BASEMAP,
+  GOOGLE_BASEMAPS as _GOOGLE_BASEMAPS,
+  getStyleUrl as _getStyleUrl,
+  fetchStyle as _fetchStyle,
+  applyLayerGroupFilters as _applyLayerGroupFilters,
+  STYLE_LAYER_GROUPS as _STYLE_LAYER_GROUPS
+} from './basemap';
 export {default as colorBins} from './style/color-bins-style';
 export {default as colorCategories} from './style/color-categories-style';
 export {default as colorContinuous} from './style/color-continuous-style';
 export {CartoAPIError, fetchMap, query} from './api/index';
+export {fetchBasemapProps} from './api/basemap';
 export type {
   APIErrorContext,
   FetchMapOptions,
+  FetchMapResult,
   Format,
   MapType,
   RequestType,
   QueryParameters,
-  QueryOptions
+  QueryOptions,
+  Basemap as _Basemap,
+  MapLibreBasemap as _MapLibreBasemap,
+  GoogleBasemap as _GoogleBasemap
 } from './api/index';
 
 import {