feat(heremap): allow choosing map engine via prop

src/HEREMap.tsx

@@ -5,6 +5,7 @@
 
 import { HEREMapContext } from './context'
 import type { DefaultLayers } from './types'
+import { useLegacyRasterLayers } from './useLegacyRasterLayers'
 import { useRasterLayers } from './useRasterLayers'
 import { useVectorLayers } from './useVectorLayers'
 import { getPlatform } from './utils/get-platform'
@@ -19,6 +20,14 @@
   interactive?: boolean,
   routes?: object[],
   truckRestrictions?: boolean,
+  /**
+   * Specify the engine type. Choose between the newer HARP engine, or the legacy P2D engine.
+   * The WEBGL engine is not supported by this library.
+   *
+   * Note that the P2D engine is no longer supported by HERE and may be shut down at any moment.
+   * It's only provided for legacy reasons for a transitional period.
+   */
+  engineType?: H.Map.EngineType,
   showActiveAndInactiveTruckRestrictions?: boolean,
   trafficLayer?: boolean,
   useSatellite?: boolean,
@@ -83,7 +92,16 @@
   animateZoom,
   animateCenter,
   useVectorTiles,
+  engineType = H.Map.EngineType.HARP,
 }, ref) => {
+  if (engineType === H.Map.EngineType.WEBGL) {
+    throw new Error('WEBGL Engine is not supported.')
+  }
+
+  if (engineType !== H.Map.EngineType.HARP && useVectorTiles) {
+    throw new Error('Vector tiles can only be used with the HARP engine.')
+  }
+
   const uniqueIdRef = useRef<string>(uniqueId())
 
   const [map, setMap] = useState<H.Map>(null)
@@ -100,7 +118,7 @@
     trafficLayer,
     truckRestrictions,
     useSatellite,
-    useVectorTiles,
+    enableVectorLayers: useVectorTiles,
   })
 
   useRasterLayers({
@@ -113,7 +131,20 @@
     truckRestrictions,
     showActiveAndInactiveTruckRestrictions,
     useSatellite,
-    useVectorTiles,
+    enableRasterLayers: !useVectorTiles && engineType === H.Map.EngineType.HARP,
+    hidpi,
+  })
+
+  useLegacyRasterLayers({
+    apiKey,
+    congestion,
+    defaultLayers: defaultLayersRef.current,
+    language,
+    map,
+    trafficLayer,
+    truckRestrictions,
+    useSatellite,
+    enableRasterLayers: !useVectorTiles && engineType === H.Map.EngineType.P2D,
     hidpi,
   })
 
@@ -187,7 +218,7 @@
       zoomOnMarkers,
       zoomOnMarkersSet,
     }
   }, [map])
 
   useEffect(() => {
     if (unmountedRef.current) {
@@ -199,8 +230,6 @@
       apikey: apiKey,
     })
 
-    const engineType = H.Map.EngineType.HARP
-
     defaultLayersRef.current = platform.createDefaultLayers({
       lg: getTileLanguage(language),
       engineType,
@@ -258,7 +287,7 @@
       unmountedRef.current = true
       map?.dispose()
     }
   }, [])
 
   useEffect(() => {
     if (map) {

src/Polyline.tsx

@@ -14,11 +14,17 @@
   data?: object,
   zIndex?: number,
   style?: H.map.SpatialStyle.Options,
+  /**
+   * Sets the arrows style when the P2D engine is in use.
+   * @deprecated This is no longer supported in the newer map engines.
+   */
+  arrows?: H.map.ArrowStyle.Options,
   draggable?: boolean,
 }
 
 export const Polyline: FC<PolylineProps> = ({
   style = defaultMapStyles,
+  arrows,
   data,
   zIndex,
   points,
@@ -61,26 +67,30 @@
 
   useEffect(() => {
     polyline?.setGeometry(line)
   }, [line])
 
   useEffect(() => {
     polyline?.setData(data)
   }, [data])
 
   useEffect(() => {
     polyline?.setZIndex(zIndex)
   }, [zIndex])
 
   useEffect(() => {
     polyline?.setStyle(style)
   }, [style])
 
+  useEffect(() => {
+    polyline?.setArrows(arrows)
+  }, [arrows])
+
   useEffect(() => {
     if (!routesGroup) {
       return
     }
 
-    const routeLine = new H.map.Polyline(line, { style, zIndex, data })
+    const routeLine = new H.map.Polyline(line, { style, zIndex, data, arrows })
     routesGroup.addObject(routeLine)
     setPolyline(routeLine)
     return () => {

src/useLegacyRasterLayers.ts

@@ -0,0 +1,141 @@
+import { useEffect, useMemo } from 'react'
+
+import type { DefaultLayers } from './types'
+import { getTileLanguage } from './utils/languages'
+
+export interface UseRasterLayersProps {
+  map?: H.Map,
+  truckRestrictions?: boolean,
+  trafficLayer?: boolean,
+  useSatellite?: boolean,
+  congestion?: boolean,
+  defaultLayers?: DefaultLayers,
+  apiKey: string,
+  hidpi?: boolean,
+  enableRasterLayers: boolean,
+  language: string,
+  engineType?: H.Map.EngineType,
+}
+
+export const getLayers = (
+  apiKey: string,
+  language: string,
+  hidpi?: boolean,
+) => {
+  const lang = getTileLanguage(language)
+  const ppi = hidpi ? 400 : 100
+  const format = 'png8'
+
+  const getTrafficOverlayProvider = (): H.map.provider.ImageTileProvider.Options => {
+    return {
+      getURL (col, row, level) {
+        return `https://traffic.maps.hereapi.com/v3/flow/mc/${level}/${col}/${row}/${format}?apiKey=${apiKey}&ppi=${ppi}`
+      },
+    }
+  }
+  const getTrafficBaseProvider = (): H.map.provider.ImageTileProvider.Options => {
+    return {
+      getURL (col, row, level) {
+        const style = 'lite.day'
+        return `https://maps.hereapi.com/v3/base/mc/${level}/${col}/${row}/${format}?apiKey=${apiKey}&lang=${lang}&ppi=${ppi}&style=${style}`
+      },
+    }
+  }
+
+  const getTruckLayerProviderLegacy = (enableCongestion: boolean): H.map.provider.ImageTileProvider.Options => {
+    return {
+      max: 20,
+      min: 8,
+      getURL (col, row, level) {
+        return ['https://',
+          '1.base.maps.ls.hereapi.com/maptile/2.1/truckonlytile/newest/normal.day/',
+          level,
+          '/',
+          col,
+          '/',
+          row,
+          '/256/png8',
+          '?style=fleet',
+          '&apiKey=',
+          apiKey,
+          enableCongestion ? '&congestion' : '',
+          '&lg=',
+          lang,
+          '&ppi=',
+          hidpi ? '320' : '72',
+        ].join('')
+      },
+    }
+  }
+  const truckOverlayProvider = new H.map.provider.ImageTileProvider(getTruckLayerProviderLegacy(false))
+  const truckOverlayCongestionProvider = new H.map.provider.ImageTileProvider(getTruckLayerProviderLegacy(true))
+  const trafficOverlayProvider = new H.map.provider.ImageTileProvider(getTrafficOverlayProvider())
+  const trafficBaseProvider = new H.map.provider.ImageTileProvider(getTrafficBaseProvider())
+
+  return {
+    trafficBaseLayer: new H.map.layer.TileLayer(trafficBaseProvider),
+    trafficOverlayLayer: new H.map.layer.TileLayer(trafficOverlayProvider),
+    truckCongestionLayer: new H.map.layer.TileLayer(truckOverlayCongestionProvider),
+    truckOverlayLayer: new H.map.layer.TileLayer(truckOverlayProvider),
+  }
+}
+
+export const useLegacyRasterLayers = ({
+  map,
+  useSatellite,
+  trafficLayer,
+  congestion,
+  truckRestrictions,
+  defaultLayers,
+  apiKey,
+  language,
+  hidpi,
+  enableRasterLayers,
+}: UseRasterLayersProps) => {
+  const layers = useMemo(() => map && getLayers(
+    apiKey,
+    language,
+    hidpi,
+  ), [apiKey, language, hidpi, map])
+
+  useEffect(() => {
+    if (map && layers && enableRasterLayers && defaultLayers) {
+      const satelliteBaseLayer = defaultLayers?.raster.satellite.map
+      const emptyBaseLayer = defaultLayers?.raster.normal.map
+      const baseLayer = useSatellite
+        ? satelliteBaseLayer
+        : trafficLayer
+          ? layers.trafficBaseLayer
+          : emptyBaseLayer
+
+      map.setBaseLayer(baseLayer)
+    }
+  }, [map, useSatellite, defaultLayers, trafficLayer, enableRasterLayers, layers])
+
+  useEffect(() => {
+    if (map && layers && enableRasterLayers) {
+      if (truckRestrictions) {
+        if (congestion) {
+          map.removeLayer(layers.truckOverlayLayer)
+          map.addLayer(layers.truckCongestionLayer)
+        } else {
+          map.removeLayer(layers.truckCongestionLayer)
+          map.addLayer(layers.truckOverlayLayer)
+        }
+      } else {
+        map.removeLayer(layers.truckCongestionLayer)
+        map.removeLayer(layers.truckOverlayLayer)
+      }
+    }
+  }, [truckRestrictions, congestion, map, enableRasterLayers, layers])
+
+  useEffect(() => {
+    if (map && layers && enableRasterLayers) {
+      if (trafficLayer) {
+        map.addLayer(layers.trafficOverlayLayer)
+      } else {
+        map.removeLayer(layers.trafficOverlayLayer)
+      }
+    }
+  }, [trafficLayer, map, enableRasterLayers, layers])
+}

src/useRasterLayers.ts

@@ -13,7 +13,7 @@ export interface UseRasterLayersProps {
   congestion?: boolean,
   defaultLayers?: DefaultLayers,
   apiKey: string,
-  useVectorTiles: boolean,
+  enableRasterLayers: boolean,
   language: string,
   hidpi?: boolean,
 }
@@ -87,52 +87,59 @@ export const useRasterLayers = ({
   defaultLayers,
   apiKey,
   language,
-  useVectorTiles,
+  enableRasterLayers,
   showActiveAndInactiveTruckRestrictions,
+  hidpi,
 }: UseRasterLayersProps) => {
   const truckOverlayLayer = useMemo(() => map && getTruckOverlayLayer({
     apiKey,
     language,
     showActiveAndInactiveTruckRestrictions,
-  }), [apiKey, showActiveAndInactiveTruckRestrictions, language, map])
+    hidpi,
+  }), [apiKey, showActiveAndInactiveTruckRestrictions, language, hidpi, map])
 
   const baseLayer = useMemo(() => map && getBaseLayer({
     apiKey,
     language,
     congestion,
     trafficLayer,
-  }), [apiKey, language, congestion, trafficLayer, map])
+    hidpi,
+  }), [apiKey, language, congestion, trafficLayer, hidpi, map])
 
   useEffect(() => {
-    if (!map || !defaultLayers || !baseLayer || useVectorTiles) {
+    if (!map || !defaultLayers || !baseLayer || !enableRasterLayers) {
       return
     }
 
     const satelliteBaseLayer = defaultLayers?.raster.satellite.map
     map.setBaseLayer(useSatellite ? satelliteBaseLayer : baseLayer)
-  }, [map, useSatellite, defaultLayers, baseLayer, useVectorTiles])
+  }, [map, useSatellite, defaultLayers, baseLayer, enableRasterLayers])
 
   useEffect(() => {
-    if (!map || !truckOverlayLayer) {
+    if (!map || !enableRasterLayers || !truckOverlayLayer) {
       return
     }
 
-    if (truckRestrictions && !useVectorTiles) {
+    if (truckRestrictions) {
       map.addLayer(truckOverlayLayer)
-    } else {
+    }
+
+    return () => {
       map.removeLayer(truckOverlayLayer)
     }
-  }, [truckRestrictions, map, useVectorTiles, truckOverlayLayer])
+  }, [truckRestrictions, map, enableRasterLayers, truckOverlayLayer])
 
   useEffect(() => {
-    if (!map || !defaultLayers) {
+    if (!map || !defaultLayers || !enableRasterLayers) {
       return
     }
 
-    if (trafficLayer && !useVectorTiles) {
+    if (trafficLayer) {
       map.addLayer(defaultLayers.vector.traffic.logistics)
-    } else {
+    }
+
+    return () => {
       map.removeLayer(defaultLayers.vector.traffic.logistics)
     }
-  }, [trafficLayer, map, defaultLayers, useVectorTiles])
+  }, [trafficLayer, map, defaultLayers, enableRasterLayers])
 }