cleanup + docs

modules/carto/src/api/basemap.ts

@@ -1,14 +1,15 @@
 import {
+  GOOGLE_BASEMAPS,
+  CARTO_MAP_STYLES,
   applyLayerGroupFilters,
-  fetchBasemapStyle,
+  fetchStyle,
   getStyleUrl,
   someLayerGroupsDisabled
 } from '../basemap';
 import {APIErrorContext, KeplerMapConfig} from './types';
 
 const CUSTOM_STYLE_ID_PREFIX = 'custom:';
 const DEFAULT_CARTO_STYLE = 'positron';
-const CARTO_MAP_STYLES = ['positron', 'dark-matter', 'voyager'];
 
 export type BasemapType = 'maplibre' | 'google-maps';
 
@@ -23,7 +24,7 @@ export type MaplibreBasemapProps = {
   /**
    * Basemap style URL or style object.
    *
-   * Note,  layers in this style may be filtered by `visibleLayerGroups`.
+   * Note, layers in this style may be filtered by `visibleLayerGroups`.
    *
    * Non-filtered pristine version is stored in `rawStyle` property.
    */
@@ -34,7 +35,8 @@ export type MaplibreBasemapProps = {
    */
   visibleLayerGroups?: Record<string, boolean>;
 
-  /** If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+  /**
+   * 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>;
@@ -57,60 +59,25 @@ export type GoogleBasemapProps = {
   options: Record<string, any>;
 };
 
-const googleBasemapTypes = [
-  {
-    id: 'roadmap',
-    options: {
-      mapTypeId: 'roadmap',
-      mapId: '3754c817b510f791'
-    }
-  },
-  {
-    id: 'google-positron',
-    options: {
-      mapTypeId: 'roadmap',
-      mapId: 'ea84ae4203ef21cd'
-    }
-  },
-  {
-    id: 'google-dark-matter',
-    options: {
-      mapTypeId: 'roadmap',
-      mapId: '2fccc3b36c22a0e2'
-    }
-  },
-  {
-    id: 'google-voyager',
-    options: {
-      mapTypeId: 'roadmap',
-      mapId: '885caf1e15bb9ef2'
-    }
-  },
-  {
-    id: 'satellite',
-    options: {
-      mapTypeId: 'satellite'
-    }
-  },
-  {
-    id: 'hybrid',
-    options: {
-      mapTypeId: 'hybrid'
-    }
-  },
-  {
-    id: 'terrain',
-    options: {
-      mapTypeId: 'terrain'
-    }
-  }
-];
-
+/**
+ * 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
+  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<BasemapProps | null> {
   const {mapStyle} = config;
@@ -130,9 +97,9 @@ export async function fetchBasemapProps({
     const {visibleLayerGroups} = mapStyle;
     const styleUrl = getStyleUrl(styleType);
     let style = styleUrl;
-    let rawStyle;
-    if (visibleLayerGroups && someLayerGroupsDisabled(visibleLayerGroups)) {
-      rawStyle = await fetchBasemapStyle({styleUrl, errorContext});
+    let rawStyle = styleUrl;
+    if (applyLayerFilters && visibleLayerGroups && someLayerGroupsDisabled(visibleLayerGroups)) {
+      rawStyle = await fetchStyle({styleUrl, errorContext});
       style = applyLayerGroupFilters(rawStyle, visibleLayerGroups);
     }
     return {
@@ -142,11 +109,11 @@ export async function fetchBasemapProps({
       rawStyle
     };
   }
-  const googleBasemapDef = googleBasemapTypes.find(b => b.id === styleType);
+  const googleBasemapDef = GOOGLE_BASEMAPS[styleType];
   if (googleBasemapDef) {
     return {
       type: 'google-maps',
-      options: googleBasemapDef.options
+      options: googleBasemapDef
     };
   }
   return {

modules/carto/src/basemap.ts

@@ -1,9 +1,43 @@
 import {CartoAPIError} from './api/carto-api-error';
 import {APIErrorContext} from './api/types';
 
-export const cartoBasemapsBaseUrl = 'https://basemaps.cartocdn.com/gl';
+const cartoStyleUrlTemplate = `https://basemaps.cartocdn.com/gl/{basemap}-gl-style/style.json`;
 
-const baseUrl = `${cartoBasemapsBaseUrl}/{basemap}-gl-style/style.json`;
+export const CARTO_MAP_STYLES = ['positron', 'dark-matter', 'voyager'];
+
+// this is our local definition, we don't want to drag whole google maps types here
+type GoogleMapProps = {
+  mapTypeId: string;
+  mapId?: string;
+};
+
+export const GOOGLE_BASEMAPS: Record<string, GoogleMapProps> = {
+  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 = {
@@ -75,10 +109,10 @@ export function someLayerGroupsDisabled(visibleLayerGroups?: Record<StyleLayerGr
 }
 
 export function getStyleUrl(styleType: string) {
-  return baseUrl.replace('{basemap}', styleType);
+  return cartoStyleUrlTemplate.replace('{basemap}', styleType);
 }
 
-export async function fetchBasemapStyle({
+export async function fetchStyle({
   styleUrl,
   errorContext
 }: {
@@ -87,10 +121,7 @@ export async function fetchBasemapStyle({
 }) {
   /* global fetch */
   let response: Response | undefined;
-  return await fetch(styleUrl, {
-    mode: 'cors',
-    credentials: 'omit'
-  })
+  return await fetch(styleUrl, {mode: 'cors'})
     .then(res => {
       response = res;
       return res.json();

modules/carto/src/index.ts

@@ -24,14 +24,18 @@ export {
 
 export {
   default as BASEMAP,
+  GOOGLE_BASEMAPS as _GOOGLE_BASEMAPS,
   getStyleUrl as _getStyleUrl,
-  fetchBasemapStyle as _getBasemapStyle,
+  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 {BasemapProps} from './api/basemap';
 export type {
   APIErrorContext,
   FetchMapOptions,

test/modules/carto/api/basemap.spec.ts

@@ -2,7 +2,7 @@ import {BASEMAP, CartoAPIError, fetchMap} from '@deck.gl/carto';
 import test from 'tape-catch';
 import {withMockFetchMapsV3} from '../mock-fetch';
 import {KeplerMapConfig} from '@deck.gl/carto/api/types';
-import {fetchBasemapProps} from '@deck.gl/carto/api/basemap';
+import {fetchBasemapProps} from '@deck.gl/carto';
 
 const mockedMapConfig: KeplerMapConfig = {
   mapState: undefined,
@@ -44,7 +44,12 @@ test('fetchBasemapProps#carto - no filters', async t =>
     t.equals(calls.length, 0, 'no style loaded, when there are no filters');
     t.deepEquals(
       r,
-      {type: 'maplibre', style: BASEMAP.POSITRON, visibleLayerGroups: {}, rawStyle: undefined},
+      {
+        type: 'maplibre',
+        style: BASEMAP.POSITRON,
+        visibleLayerGroups: {},
+        rawStyle: BASEMAP.POSITRON
+      },
       'style is just positron URL'
     );
     t.end();