CR: typos and docs clarifications

docs/api-reference/carto/basemap.md

@@ -38,7 +38,7 @@ To use pre-bundled scripts:
 <script src="https://unpkg.com/@deck.gl/carto@^9.0.0/dist.min.js"></script>
 
 <!-- or -->
-<script src="https://unpkg.com/@deck.gl@^9.0.0/core/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/core/@^9.0.0/dist.min.js"></script>
 <script src="https://unpkg.com/@deck.gl/layers@^9.0.0/dist.min.js"></script>
 <script src="https://unpkg.com/@deck.gl/mesh-layers@^9.0.0/dist.min.js"></script>
 <script src="https://unpkg.com/@deck.gl/geo-layers@^9.0.0/dist.min.js"></script>
@@ -50,7 +50,7 @@ To use pre-bundled scripts:
 ```
 
 ```js
-const map = new mapboxgl.Map({
+const map = new maplibregl.Map({
   container: 'map',
   style: deck.carto.BASEMAP.POSITRON,
   interactive: false

modules/carto/src/api/basemap.ts

@@ -7,12 +7,12 @@ import {
   getStyleUrl,
   someLayerGroupsDisabled
 } from '../basemap';
-import {APIErrorContext, Basemap, KeplerMapConfig, MaplibreBasemapProps} from './types';
+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'> {
+function mapLibreViewpros(config: KeplerMapConfig): Omit<MapLibreBasemapProps, 'style'> {
   const {longitude, latitude, ...rest} = config.mapState as MapViewState;
   return {
     center: [longitude, latitude],

modules/carto/src/api/fetch-map.ts

@@ -216,7 +216,7 @@ export type FetchMapOptions = {
 
 export type FetchMapResult = ParseMapResult & {
   /**
-   * Basemap properties
+   * Basemap properties.
    */
   basemap: Basemap | null;
   stopAutoRefresh?: () => void;

modules/carto/src/api/index.ts

@@ -8,7 +8,7 @@ export type {
   RequestType,
   QueryParameters,
   Basemap,
-  MaplibreBasemap,
+  MapLibreBasemap,
   GoogleBasemap
 } from './types';
 export {query} from './query';

modules/carto/src/api/types.ts

@@ -208,7 +208,7 @@ export type KeplerMapConfig = {
 
 export type BasemapType = 'maplibre' | 'google-maps';
 
-export type Basemap = MaplibreBasemap | GoogleBasemap;
+export type Basemap = MapLibreBasemap | GoogleBasemap;
 
 export type BasemapCommon = {
   /**
@@ -227,17 +227,15 @@ export type BasemapCommon = {
   props: Record<string, any>;
 };
 
-export type MaplibreBasemap = BasemapCommon & {
+export type MapLibreBasemap = BasemapCommon & {
   type: 'maplibre';
 
   /**
-   * Basemap style URL or style object.
+   * MapLibre map properties.
    *
-   * Note, layers in this style may be filtered by `visibleLayerGroups`.
-   *
-   * Non-filtered pristine version is stored in `rawStyle` property.
+   * Meant to be passed to directly to `maplibregl.Map` object.
    */
-  props: MaplibreBasemapProps;
+  props: MapLibreBasemapProps;
 
   /**
    * Layer groups to be displayed in the basemap.
@@ -251,8 +249,8 @@ export type MaplibreBasemap = BasemapCommon & {
   rawStyle?: string | Record<string, any>;
 };
 
-// Cherry-pick of google maplibregl Map API props that are supported/provided by fetchMap interface
-export type MaplibreBasemapProps = {
+// 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;
@@ -265,11 +263,13 @@ export type GoogleBasemap = BasemapCommon & {
 
   /**
    * 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
+// Cherry-pick of Google Map API props that are supported/provided by fetchMap interface
 export type GoogleBasemapProps = {
   mapTypeId: string;
   mapId?: string;

modules/carto/src/index.ts

@@ -38,14 +38,15 @@ export {fetchBasemapProps} from './api/basemap';
 export type {
   APIErrorContext,
   FetchMapOptions,
+  FetchMapResult,
   Format,
   MapType,
   RequestType,
   QueryParameters,
   QueryOptions,
-  Basemap,
-  MaplibreBasemap,
-  GoogleBasemap
+  Basemap as _Basemap,
+  MapLibreBasemap as _MapLibreBasemap,
+  GoogleBasemap as _GoogleBasemap
 } from './api/index';
 
 import {

test/apps/carto-map/app.ts

@@ -1,4 +1,10 @@
-import {BASEMAP, fetchMap, FetchMapOptions, GoogleBasemap, MaplibreBasemap} from '@deck.gl/carto';
+import {
+  BASEMAP,
+  fetchMap,
+  FetchMapOptions,
+  _GoogleBasemap as GoogleBasemap,
+  _MapLibreBasemap as MapLibreBasemap
+} from '@deck.gl/carto';
 import {Deck} from '@deck.gl/core';
 import mapboxgl from 'mapbox-gl';
 import 'mapbox-gl/dist/mapbox-gl.css';
@@ -20,10 +26,32 @@ const GOOGLE_MAPS_API_KEY = '';
 const apiBaseUrl = 'https://gcp-us-east1.api.carto.com';
 // const apiBaseUrl = 'https://gcp-us-east1-05.dev.api.carto.com';
 
+async function createMapWithDeckController(result: FetchMapResult) {
+  const deck = new Deck({canvas: 'deck-canvas'});
+  // Get map info from CARTO and update deck
+  const {initialViewState, layers} = result;
+  deck.setProps({initialViewState, layers});
+
+  const basemap = result.basemap as MapLibreBasemap;
+  const map = new mapboxgl.Map({
+    container: 'map',
+    ...basemap.props,
+    interactive: false
+  });
+  deck.setProps({
+    controller: true,
+    onViewStateChange: ({viewState}) => {
+      const {longitude, latitude, ...rest} = viewState;
+      map.jumpTo({center: [longitude, latitude], ...rest});
+    }
+  });
+  return deck;
+}
+
 async function createMapWithMapboxOverlay(result: FetchMapResult) {
   document.getElementById('deck-canvas')!.style.display = 'none';
 
-  const basemap = result.basemap as MaplibreBasemap;
+  const basemap = result.basemap as MapLibreBasemap;
   const map = new mapboxgl.Map({
     container: 'map',
     ...basemap?.props,
@@ -39,10 +67,11 @@ async function createMapWithMapboxOverlay(result: FetchMapResult) {
   const overlay = new MapboxOverlay({layers: result.layers});
   map.addControl(overlay);
 
-  return map;
+  return overlay;
 }
 
 async function createMapWithGoogleMapsOverlay(result: FetchMapResult) {
+  document.getElementById('deck-canvas')!.style.display = 'none';
   const loader = new Loader({apiKey: GOOGLE_MAPS_API_KEY});
   const googlemaps = await loader.importLibrary('maps');
 
@@ -81,6 +110,7 @@ async function createMap(cartoMapId: string) {
     deck = await createMapWithGoogleMapsOverlay(result);
   } else {
     deck = await createMapWithMapboxOverlay(result);
+    // deck = await createMapWithDeckController(result);
   }
 }
 

test/apps/carto-map/index.html

@@ -31,6 +31,7 @@
   <body>
     <div id="container">
       <div id="map"></div>
+      <canvas id="deck-canvas"></canvas>
     </div>
     <script type="module" src='app.ts'></script>
   </body>

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

@@ -1,4 +1,4 @@
-import {BASEMAP, CartoAPIError, MaplibreBasemap} from '@deck.gl/carto';
+import {BASEMAP, CartoAPIError, _MapLibreBasemap as MapLibreBasemap} from '@deck.gl/carto';
 import test from 'tape-catch';
 import {withMockFetchMapsV3} from '../mock-fetch';
 import {KeplerMapConfig} from '@deck.gl/carto/api/types';
@@ -82,7 +82,7 @@ test('fetchBasemapProps#carto - with filters', async t =>
     t.equals(calls.length, 1, 'should call fetch only once');
     t.equals(calls[0].url, BASEMAP.VOYAGER, 'should request voyager style');
     t.equals(r.type, 'maplibre', 'proper basemap type is returned');
-    const r2 = r as MaplibreBasemap;
+    const r2 = r as MapLibreBasemap;
     t.equals(r2.rawStyle, mockedCartoStyle, 'raw style is returned');
     t.deepEquals(
       r2.props.style,