[v8] Align type names with base map libraries (#2474)

Author: Pessimistress

docs/upgrade-guide.md

@@ -1,5 +1,23 @@
 # Upgrade Guide
 
+## Upgrading to v8.0
+
+- All imports from `react-map-gl` should be replaced with one of the following endpoints:
+  + If using with `mapbox-gl@>=3.5.0`: import from `react-map-gl/mapbox`
+  + If using with `mapbox-gl@<3.5.0`: import from `react-map-gl/mapbox-legacy`
+- Some TypeScript types have been renamed to align with the official types from the base map libraries:
+
+  | Old name | New name |
+  |----------|----------|
+  | `MapStyle` | `StyleSpecification` |
+  | `Fog` | `FogSpecification` |
+  | `Light` | `LightSpecification` |
+  | `Terrain` | `TerrainSpecification` |
+  | `Projection` | `ProjectionSpecification` |
+  | `*Layer` | `*LayerSpecification` |
+  | `*SourceRaw` | `*SourceSpecification` |
+
+
 ## Upgrading to v7.1
 
 - `maplibre-gl` users no longer need to install `mapbox-gl` or a placeholder package as dependency. Change your imports to the new endpoint `react-map-gl/maplibre`. Components imported from here do not require setting the `mapLib` prop, and use the types defined by `maplibre-gl`.

examples/mapbox/filter/src/map-style.ts

@@ -1,6 +1,6 @@
-import type {FillLayer} from 'react-map-gl/mapbox';
+import type {FillLayerSpecification} from 'react-map-gl/mapbox';
 
-export const countiesLayer: FillLayer = {
+export const countiesLayer: FillLayerSpecification = {
   id: 'counties',
   source: '',
   type: 'fill',
@@ -11,7 +11,7 @@ export const countiesLayer: FillLayer = {
   }
 };
 // Highlighted county polygons
-export const highlightLayer: FillLayer = {
+export const highlightLayer: FillLayerSpecification = {
   id: 'counties-highlighted',
   type: 'fill',
   source: 'counties',

examples/mapbox/terrain/src/app.tsx

@@ -4,11 +4,11 @@ import Map, {Source, Layer} from 'react-map-gl/mapbox';
 
 import ControlPanel from './control-panel';
 
-import type {SkyLayer} from 'react-map-gl/mapbox';
+import type {SkyLayerSpecification} from 'react-map-gl/mapbox';
 
 const TOKEN = ''; // Set your mapbox token here
 
-const skyLayer: SkyLayer = {
+const skyLayer: SkyLayerSpecification = {
   id: 'sky',
   type: 'sky',
   paint: {

examples/mapbox/zoom-to-bounds/src/map-style.tsx

@@ -1,13 +1,17 @@
-import type {GeoJSONSource, FillLayer, LineLayer} from 'react-map-gl/mapbox';
+import type {
+  GeoJSONSourceSpecification,
+  FillLayerSpecification,
+  LineLayerSpecification
+} from 'react-map-gl/mapbox';
 
 import MAP_STYLE from '../../../map-style-basic-v8.json';
 
-const sfNeighborhoods: GeoJSONSource = {
+const sfNeighborhoods: GeoJSONSourceSpecification = {
   type: 'geojson',
   data: 'https://raw.githubusercontent.com/uber/react-map-gl/master/examples/.data/feature-example-sf.json'
 };
 
-const fillLayer: FillLayer = {
+const fillLayer: FillLayerSpecification = {
   id: 'sf-neighborhoods-fill',
   source: 'sf-neighborhoods',
   type: 'fill',
@@ -18,7 +22,7 @@ const fillLayer: FillLayer = {
   }
 };
 
-const lineLayer: LineLayer = {
+const lineLayer: LineLayerSpecification = {
   id: 'sf-neighborhoods-outline',
   source: 'sf-neighborhoods',
   type: 'line',

examples/maplibre/filter/src/map-style.ts

@@ -1,6 +1,6 @@
-import type {FillLayer} from 'react-map-gl/maplibre';
+import type {FillLayerSpecification} from 'react-map-gl/maplibre';
 
-export const countiesLayer: FillLayer = {
+export const countiesLayer: FillLayerSpecification = {
   id: 'counties',
   source: '',
   type: 'fill',
@@ -10,7 +10,7 @@ export const countiesLayer: FillLayer = {
   }
 };
 // Highlighted county polygons
-export const highlightLayer: FillLayer = {
+export const highlightLayer: FillLayerSpecification = {
   id: 'counties-highlighted',
   type: 'fill',
   source: 'counties',

examples/maplibre/zoom-to-bounds/src/map-style.tsx

@@ -1,13 +1,17 @@
-import type {GeoJSONSource, FillLayer, LineLayer} from 'react-map-gl/maplibre';
+import type {
+  GeoJSONSourceSpecification,
+  FillLayerSpecification,
+  LineLayerSpecification
+} from 'react-map-gl/maplibre';
 
 import MAP_STYLE from '../../../map-style-basic-v8.json';
 
-const sfNeighborhoods: GeoJSONSource = {
+const sfNeighborhoods: GeoJSONSourceSpecification = {
   type: 'geojson',
   data: 'https://raw.githubusercontent.com/visgl/react-map-gl/master/examples/.data/feature-example-sf.json'
 };
 
-const fillLayer: FillLayer = {
+const fillLayer: FillLayerSpecification = {
   id: 'sf-neighborhoods-fill',
   source: 'sf-neighborhoods',
   type: 'fill',
@@ -18,7 +22,7 @@ const fillLayer: FillLayer = {
   }
 };
 
-const lineLayer: LineLayer = {
+const lineLayer: LineLayerSpecification = {
   id: 'sf-neighborhoods-outline',
   source: 'sf-neighborhoods',
   type: 'line',

modules/main/src/mapbox-legacy/components/layer.ts

@@ -4,14 +4,14 @@ import assert from '../utils/assert';
 import {deepEqual} from '../utils/deep-equal';
 
 import type {MapInstance, CustomLayerInterface} from '../types/lib';
-import type {AnyLayer} from '../types/style-spec';
+import type {LayerSpecification} from '../types/style-spec';
 
 // Omiting property from a union type, see
 // https://github.com/microsoft/TypeScript/issues/39556#issuecomment-656925230
 type OptionalId<T> = T extends {id: string} ? Omit<T, 'id'> & {id?: string} : T;
 type OptionalSource<T> = T extends {source: string} ? Omit<T, 'source'> & {source?: string} : T;
 
-export type LayerProps = (OptionalSource<OptionalId<AnyLayer>> | CustomLayerInterface) & {
+export type LayerProps = (OptionalSource<OptionalId<LayerSpecification>> | CustomLayerInterface) & {
   /** If set, the layer will be inserted before the specified layer */
   beforeId?: string;
 };

modules/main/src/mapbox-legacy/components/source.ts

@@ -9,10 +9,14 @@ import type {
   ImageSourceImplemtation,
   AnySourceImplementation
 } from '../types/internal';
-import type {AnySource, ImageSource, VectorSource} from '../types/style-spec';
+import type {
+  SourceSpecification,
+  ImageSourceSpecification,
+  VectorSourceSpecification
+} from '../types/style-spec';
 import type {MapInstance} from '../types/lib';
 
-export type SourceProps = AnySource & {
+export type SourceProps = SourceSpecification & {
   id?: string;
   children?: any;
 };
@@ -61,11 +65,11 @@ function updateSource(source: AnySourceImplementation, props: SourceProps, prevP
       coordinates: props.coordinates
     });
   } else if ('setCoordinates' in source && changedKeyCount === 1 && changedKey === 'coordinates') {
-    source.setCoordinates((props as unknown as ImageSource).coordinates);
+    source.setCoordinates((props as unknown as ImageSourceSpecification).coordinates);
   } else if ('setUrl' in source && changedKey === 'url') {
-    source.setUrl((props as VectorSource).url);
+    source.setUrl((props as VectorSourceSpecification).url);
   } else if ('setTiles' in source && changedKey === 'tiles') {
-    source.setTiles((props as VectorSource).tiles);
+    source.setTiles((props as VectorSourceSpecification).tiles);
   } else {
     // eslint-disable-next-line
     console.warn(`Unable to update <Source> prop: ${changedKey}`);

modules/main/src/mapbox-legacy/mapbox/mapbox.ts

@@ -16,7 +16,13 @@ import type {
   LngLatBoundsLike,
   MapGeoJSONFeature
 } from '../types/common';
-import type {MapStyle, Light, Terrain, Fog, Projection} from '../types/style-spec';
+import type {
+  StyleSpecification,
+  LightSpecification,
+  TerrainSpecification,
+  FogSpecification,
+  ProjectionSpecification
+} from '../types/style-spec';
 import type {MapInstance} from '../types/lib';
 import type {Transform, MapInstanceInternal} from '../types/internal';
 import type {
@@ -57,31 +63,31 @@ export type MapboxProps = Partial<ViewState> &
     // Styling
 
     /** Mapbox style */
-    mapStyle?: string | MapStyle | ImmutableLike<MapStyle>;
+    mapStyle?: string | StyleSpecification | ImmutableLike<StyleSpecification>;
     /** Enable diffing when the map style changes
      * @default true
      */
     styleDiffing?: boolean;
     /** The projection property of the style. Must conform to the Projection Style Specification.
      * @default 'mercator'
      */
-    projection?: Projection;
+    projection?: ProjectionSpecification | ProjectionSpecification['name'];
     /** The fog property of the style. Must conform to the Fog Style Specification .
      * If `undefined` is provided, removes the fog from the map. */
-    fog?: Fog;
+    fog?: FogSpecification;
     /** Light properties of the map. */
-    light?: Light;
+    light?: LightSpecification;
     /** Terrain property of the style. Must conform to the Terrain Style Specification .
      * If `undefined` is provided, removes terrain from the map. */
-    terrain?: Terrain;
+    terrain?: TerrainSpecification;
 
     /** Default layers to query on pointer events */
     interactiveLayerIds?: string[];
     /** CSS cursor */
     cursor?: string;
   };
 
-const DEFAULT_STYLE = {version: 8, sources: {}, layers: []} as MapStyle;
+const DEFAULT_STYLE = {version: 8, sources: {}, layers: []} as StyleSpecification;
 
 const pointerEvents = {
   mousedown: 'onMouseDown',

modules/main/src/mapbox-legacy/types/style-spec.ts

@@ -1,77 +1,34 @@
 /*
  * Mapbox Style Specification types
  */
-// Layers
-import type {
-  BackgroundLayer,
-  SkyLayer,
-  CircleLayer,
-  FillLayer,
-  FillExtrusionLayer,
-  HeatmapLayer,
-  HillshadeLayer,
-  LineLayer,
-  RasterLayer,
-  SymbolLayer
-} from 'mapbox-gl';
-
-export type AnyLayer =
-  | BackgroundLayer
-  | CircleLayer
-  | FillExtrusionLayer
-  | FillLayer
-  | HeatmapLayer
-  | HillshadeLayer
-  | LineLayer
-  | RasterLayer
-  | SymbolLayer
-  | SkyLayer;
-
 export type {
-  BackgroundLayer,
-  SkyLayer,
-  CircleLayer,
-  FillLayer,
-  FillExtrusionLayer,
-  HeatmapLayer,
-  HillshadeLayer,
-  LineLayer,
-  RasterLayer,
-  SymbolLayer
-};
-
-// Sources
-import type {
-  Projection as ProjectionSpecification,
-  GeoJSONSourceRaw as GeoJSONSource,
-  VideoSourceRaw as VideoSource,
-  ImageSourceRaw as ImageSource,
-  VectorSource,
-  RasterSource,
-  CanvasSourceRaw as CanvasSource,
-  RasterDemSource
-} from 'mapbox-gl';
+  // Layers
+  AnyLayer as LayerSpecification,
+  BackgroundLayer as BackgroundLayerSpecification,
+  SkyLayer as SkyLayerSpecification,
+  CircleLayer as CircleLayerSpecification,
+  FillLayer as FillLayerSpecification,
+  FillExtrusionLayer as FillExtrusionLayerSpecification,
+  HeatmapLayer as HeatmapLayerSpecification,
+  HillshadeLayer as HillshadeLayerSpecification,
+  LineLayer as LineLayerSpecification,
+  RasterLayer as RasterLayerSpecification,
+  SymbolLayer as SymbolLayerSpecification,
 
-export type AnySource =
-  | GeoJSONSource
-  | VideoSource
-  | ImageSource
-  | CanvasSource
-  | VectorSource
-  | RasterSource
-  | RasterDemSource;
+  // Sources
+  AnySourceData as SourceSpecification,
+  CanvasSourceRaw as CanvasSourceSpecification,
+  GeoJSONSourceRaw as GeoJSONSourceSpecification,
+  VideoSourceRaw as VideoSourceSpecification,
+  ImageSourceRaw as ImageSourceSpecification,
+  VectorSource as VectorSourceSpecification,
+  RasterSource as RasterSourceSpecification,
+  RasterDemSource as RasterDemSourceSpecification,
 
-export type {
-  GeoJSONSource,
-  VideoSource,
-  ImageSource,
-  CanvasSource,
-  VectorSource,
-  RasterSource,
-  RasterDemSource
-};
-
-// Other
-export type {Style as MapStyle, Light, Fog, TerrainSpecification as Terrain} from 'mapbox-gl';
-
-export type Projection = ProjectionSpecification | ProjectionSpecification['name'];
+  // Style
+  Style as StyleSpecification,
+  Light as LightSpecification,
+  Fog as FogSpecification,
+  TerrainSpecification,
+  Projection as ProjectionSpecification
+} from 'mapbox-gl';