@tpzdsp/next-toolkit 1.1.0 → 1.2.0

package/src/components/map/Map.tsx

@@ -0,0 +1,230 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { Map, Overlay, View } from 'ol';
+import { Control, ScaleLine, defaults as defaultControls } from 'ol/control';
+import { fromLonLat } from 'ol/proj';
+
+import { initializeBasemapLayers } from './basemaps';
+import { initializeGeocoder } from './geocoder';
+import { LayerSwitcherControl } from './LayerSwitcherControl';
+import { getPopupPositionClass } from './map';
+import { useMap } from './MapContext';
+import { Popup } from './Popup';
+import type { MapConfig, PopupDirection } from '../../types/map';
+
+export type MapComponentProps = {
+  osMapsApiKey?: string;
+  geocoderUrl: string;
+  basePath: string;
+};
+
+const positionTransforms: Record<PopupDirection, string> = {
+  'bottom-left': 'top-[-2em] right-[1em]',
+  'top-left': 'bottom-[-2em] right-[1em]',
+  'top-right': 'bottom-[-2em] left-[1em]',
+  'bottom-right': 'top-[-2em] left-[1em]',
+};
+
+const arrowStyles: Record<PopupDirection, string> = {
+  'bottom-left': 'right-[-.5em] top-[1em]',
+  'bottom-right': 'left-[-.5em] top-[1em]',
+  'top-left': 'right-[-.5em] bottom-[1em]',
+  'top-right': 'left-[-.5em] bottom-[1em]',
+};
+
+/**
+ * This component  manages the main map, this is where the basemap layers
+ * and basic controls are added to the map. The map component encapsulates
+ * a number of child components, used to interact with the map itself.
+ *
+ * @return {*}
+ */
+export const MapComponent = ({ osMapsApiKey, geocoderUrl, basePath }: MapComponentProps) => {
+  const [popupFeatures, setPopupFeatures] = useState([]);
+  const [popupCoordinate, setPopupCoordinate] = useState<number[] | null>(null);
+  const [popupPositionClass, setPopupPositionClass] = useState<PopupDirection>('bottom-right');
+
+  const mapInitializedRef = useRef(false);
+
+  const overlayRef = useRef<Overlay | null>(null);
+
+  const {
+    mapRef,
+    mapConfig: { center, zoom },
+    setMap,
+    setMapConfig,
+    map,
+    isDrawing,
+    isSamplingPointsLoading,
+  } = useMap();
+
+  useEffect(() => {
+    // Check if map is already initialized to avoid re-initialization
+    if (mapInitializedRef.current) {
+      return;
+    }
+
+    if (!osMapsApiKey) {
+      console.warn('OS Maps API key not provided. Geocoder will not be available.');
+      // Continue with map initialization but skip geocoder
+    }
+
+    // Initialise map's basemap layers.
+    const layers = initializeBasemapLayers();
+
+    const scaleLine = new ScaleLine({
+      units: 'metric',
+    });
+
+    const target = mapRef.current;
+
+    if (!target) {
+      return;
+    }
+
+    const newMap = new Map({
+      target,
+      controls: defaultControls().extend([scaleLine]),
+      layers,
+      view: new View({
+        projection: 'EPSG:3857',
+        // extent: transformExtent(
+        //   [-8.371582, 49.852152, 2.021484, 59.445075],
+        //   'EPSG:4326',
+        //   'EPSG:3857',
+        // ),
+        center: fromLonLat(center),
+        zoom,
+      }),
+    });
+
+    // Mark the map as initialized to prevent re-initialization
+    // This is a workaround to avoid re-initializing the map when the component
+    // re-renders. The map is only initialized once when the component mounts.
+    // This is important because the map is a singleton and should not be
+    // re-initialized.
+    mapInitializedRef.current = true;
+
+    // Create an instance of the custom provider, passing any options that are
+    // required
+    // Only initialize geocoder if API key is available
+    if (osMapsApiKey) {
+      try {
+        const geocoder = initializeGeocoder(osMapsApiKey, geocoderUrl, newMap);
+
+        newMap.addControl(geocoder as Control);
+      } catch (error) {
+        console.error('Failed to initialize geocoder:', error);
+      }
+    }
+
+    newMap.addControl(new LayerSwitcherControl(layers));
+
+    // Setup popup overlay
+    const overlay = new Overlay({
+      element: document.getElementById('popup-container') ?? undefined,
+      positioning: popupPositionClass,
+    });
+
+    overlayRef.current = overlay;
+    newMap.addOverlay(overlay);
+
+    newMap.on('click', (event) => {
+      if (isDrawing) {
+        return;
+      }
+
+      newMap.forEachFeatureAtPixel(event.pixel, (feature) => {
+        const features = feature.get('features');
+
+        if (features?.length > 0) {
+          const coordinate = event.coordinate;
+          const direction = getPopupPositionClass(coordinate, newMap);
+
+          setPopupFeatures(features);
+          setPopupCoordinate(coordinate);
+          setPopupPositionClass(direction); // new state we add below
+          overlay.setPosition(event.coordinate);
+        }
+      });
+    });
+
+    if (!map) {
+      setMap(newMap);
+    }
+
+    return () => {
+      newMap?.setTarget();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []); // This is a rare case where we want to run this only once.
+
+  // Update map config when map is moved
+  useEffect(() => {
+    if (!map) {
+      return;
+    }
+
+    const view = map.getView();
+    const moveHandler = () => {
+      const center = view.getCenter();
+
+      if (center) {
+        setMapConfig((prev: MapConfig) => ({
+          ...prev,
+          center,
+          zoom: view.getZoom()!,
+        }));
+      }
+    };
+
+    map.on('moveend', moveHandler);
+
+    return () => {
+      map.un('moveend', moveHandler);
+    };
+  }, [map, setMapConfig]);
+
+  const closePopup = () => {
+    setPopupFeatures([]);
+    setPopupCoordinate(null);
+
+    if (overlayRef.current) {
+      overlayRef.current.setPosition(undefined);
+    }
+  };
+
+  return (
+    <div className="flex flex-grow min-h-0">
+      <div ref={mapRef} className="flex flex-grow relative z-10" id="map">
+        {isSamplingPointsLoading ? (
+          <div className="absolute inset-0 flex items-center justify-center bg-white/50 z-10">
+            <div
+              className="w-9 h-9 border-4 border-gray-200 border-t-blue-500 rounded-full
+                animate-spin"
+            />
+          </div>
+        ) : null}
+
+        <div className="absolute top-36 z-20" id="geocoder" />
+
+        <div
+          className={`absolute z-20 ${positionTransforms[popupPositionClass]}`}
+          id="popup-container"
+        >
+          {popupFeatures.length > 0 ? (
+            <Popup
+              features={popupFeatures}
+              onClose={closePopup}
+              clickedCoord={popupCoordinate}
+              arrowClasses={arrowStyles[popupPositionClass]}
+              baseUrl={`${basePath}/sampling-point/`}
+            />
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/components/map/MapContext.tsx

@@ -0,0 +1,211 @@
+'use client';
+
+import type { Dispatch, RefObject, ReactNode, SetStateAction } from 'react';
+import { createContext, useContext, useRef, useState, useMemo, useCallback } from 'react';
+
+import type { Coordinate } from 'ol/coordinate';
+import BaseLayer from 'ol/layer/Base';
+import Layer from 'ol/layer/Layer';
+import Map from 'ol/Map';
+import { fromLonLat } from 'ol/proj';
+import ClusterSource from 'ol/source/Cluster';
+import VectorSource from 'ol/source/Vector';
+
+import './projections';
+import { LAYER_NAMES } from './map';
+import type { MapConfig } from '../../types';
+
+export type MapContextType = {
+  mapConfig: MapConfig;
+  setMapConfig: Dispatch<SetStateAction<MapConfig>>;
+  mapRef: RefObject<HTMLDivElement | null>;
+  map: Map | undefined;
+  setMap: Dispatch<SetStateAction<Map | undefined>>;
+  getLayers: () => BaseLayer[] | undefined;
+  addLayer: (layer: Layer) => void;
+  removeLayer: (name: string) => void;
+  clearLayer: (name: string) => void;
+  resetMap: () => void;
+  getLayerByName: (name: string) => BaseLayer | undefined;
+  aoi: Coordinate[][] | null;
+  setAoi: Dispatch<SetStateAction<Coordinate[][] | null>>;
+  selectedLayer: Layer | null;
+  setSelectedLayer: Dispatch<SetStateAction<Layer | null>>;
+  isDrawing: boolean;
+  setIsDrawing: Dispatch<SetStateAction<boolean>>;
+  samplingPoints: string[] | null;
+  setSamplingPoints: Dispatch<SetStateAction<string[] | null>>;
+  isTooManySamplingPoints: boolean;
+  setIsTooManySamplingPoints: Dispatch<SetStateAction<boolean>>;
+  isSamplingPointsLoading: boolean;
+  setIsSamplingPointsLoading: Dispatch<SetStateAction<boolean>>;
+};
+
+type MapProviderProps = {
+  initialState?: Partial<MapContextType>;
+  children: ReactNode;
+};
+
+export const MapContext = createContext<MapContextType | null>(null);
+MapContext.displayName = 'MapContext';
+
+const DEFAULT_LON_LAT = [-3, 53];
+const DEFAULT_ZOOM = 7;
+
+export const MAX_SAMPLING_POINTS = 20;
+const DEFAULT_DURATION = 500;
+
+export const MapProvider = ({ initialState = {}, children }: MapProviderProps) => {
+  const mapRef = useRef(null);
+
+  const [mapConfig, setMapConfig] = useState<MapConfig>({
+    center: DEFAULT_LON_LAT,
+    zoom: DEFAULT_ZOOM,
+  });
+  const [map, setMap] = useState<Map | undefined>();
+  const [aoi, setAoi] = useState<Coordinate[][] | null>(null);
+  const [selectedLayer, setSelectedLayer] = useState<Layer | null>(null);
+  const [isDrawing, setIsDrawing] = useState(false);
+  const [samplingPoints, setSamplingPoints] = useState<string[] | null>(null);
+  const [isTooManySamplingPoints, setIsTooManySamplingPoints] = useState(false);
+  const [isSamplingPointsLoading, setIsSamplingPointsLoading] = useState(false);
+
+  const getLayers = useCallback(() => map?.getLayers().getArray(), [map]);
+
+  const getLayerByName = useCallback(
+    (name: string) => getLayers()?.find((layer) => layer.get('name') === name),
+    [getLayers],
+  );
+
+  const addLayer = useCallback(
+    (layer: Layer) => {
+      // Add layer to map.
+      map?.addLayer(layer);
+    },
+    [map],
+  );
+
+  const removeLayer = useCallback(
+    (name: string) => {
+      const foundLayer = getLayerByName(name);
+
+      map?.removeLayer(foundLayer!);
+    },
+    [getLayerByName, map],
+  );
+
+  const isClearableSource = (source: unknown): source is VectorSource =>
+    typeof (source as VectorSource)?.clear === 'function';
+
+  const clearLayer = useCallback(
+    (name: string) => {
+      const foundLayer = getLayerByName(name) as Layer | undefined;
+
+      if (!foundLayer) {
+        return;
+      }
+
+      const source = foundLayer.getSource?.();
+
+      if (!source) {
+        return;
+      }
+
+      if (source instanceof ClusterSource) {
+        const childSource = source.getSource?.();
+
+        if (isClearableSource(childSource)) {
+          childSource.clear();
+        }
+
+        source.refresh(); // Required to reflect clearing
+      } else if (isClearableSource(source)) {
+        source.clear();
+      }
+    },
+    [getLayerByName],
+  );
+
+  const resetMap = useCallback(() => {
+    if (map) {
+      const view = map.getView();
+
+      // Animate view to default
+      view.animate(
+        {
+          center: fromLonLat(DEFAULT_LON_LAT),
+          duration: DEFAULT_DURATION,
+        },
+        {
+          zoom: DEFAULT_ZOOM,
+          duration: DEFAULT_DURATION,
+        },
+      );
+    }
+
+    // Remove all defined layers
+    Object.values(LAYER_NAMES).forEach(clearLayer);
+
+    // Reset sampling points state
+    setSamplingPoints(null);
+    setIsTooManySamplingPoints(false);
+  }, [map, clearLayer]);
+
+  const contextValue = useMemo(
+    () => ({
+      mapRef,
+      map,
+      setMap,
+      mapConfig,
+      setMapConfig,
+      getLayers,
+      addLayer,
+      removeLayer,
+      getLayerByName,
+      aoi,
+      setAoi,
+      selectedLayer,
+      setSelectedLayer,
+      isDrawing,
+      setIsDrawing,
+      samplingPoints,
+      setSamplingPoints,
+      isTooManySamplingPoints,
+      setIsTooManySamplingPoints,
+      isSamplingPointsLoading,
+      setIsSamplingPointsLoading,
+      clearLayer,
+      resetMap,
+      ...initialState,
+    }),
+    [
+      map,
+      mapConfig,
+      getLayers,
+      addLayer,
+      removeLayer,
+      getLayerByName,
+      aoi,
+      selectedLayer,
+      isDrawing,
+      samplingPoints,
+      isTooManySamplingPoints,
+      isSamplingPointsLoading,
+      clearLayer,
+      resetMap,
+      initialState,
+    ],
+  );
+
+  return <MapContext.Provider value={contextValue}>{children}</MapContext.Provider>;
+};
+
+export const useMap = () => {
+  const context = useContext(MapContext);
+
+  if (!context) {
+    throw Error('The component needs to be wrapped in a <MapProvider /> component.');
+  }
+
+  return context;
+};

package/src/components/map/Popup.tsx

@@ -0,0 +1,74 @@
+'use client';
+
+import { Feature } from 'ol';
+import { GoLinkExternal } from 'react-icons/go';
+import { IoMdCloseCircle } from 'react-icons/io';
+
+import { ExternalLink } from '../../components/link/ExternalLink';
+
+type PopupProps = {
+  features: Feature[];
+  onClose: () => void;
+  clickedCoord: number[] | null;
+  arrowClasses: string;
+  baseUrl: string;
+};
+
+export const Popup = ({
+  features,
+  onClose,
+  clickedCoord,
+  arrowClasses = 'bottom-left',
+  baseUrl,
+}: PopupProps) => {
+  if (!features.length || !clickedCoord) {
+    return null;
+  }
+
+  return (
+    <div className={'relative z-50 w-[300px] shadow-md'}>
+      <button
+        type="button"
+        onClick={onClose}
+        className="absolute z-4 top-[.5em] right-[1em] text-gray-500 hover:text-black text-sm"
+        aria-label="Close popup"
+      >
+        <IoMdCloseCircle size={20} />
+      </button>
+
+      <div
+        className="space-y-2 pt-4 pb-1 overflow-y-auto max-h-[300px] bg-white border border-border
+          rounded-lg divide-y divide-gray-300"
+      >
+        {features.map((feature) => {
+          const id = feature.get('id');
+          const name = feature.get('name');
+          const notation = feature.get('notation');
+          const url = `${baseUrl}${notation}`;
+
+          return (
+            <div key={id}>
+              <strong>
+                <ExternalLink
+                  href={url}
+                  className="px-4 my-2 text-blue-500 underline flex flex-row gap-1 items-center"
+                >
+                  <span>{name}</span>
+
+                  <span className="flex-none w-5 h-5 flex items-center justify-center">
+                    <GoLinkExternal size={20} className="cursor-pointer" />
+                  </span>
+                </ExternalLink>
+              </strong>
+            </div>
+          );
+        })}
+      </div>
+
+      <div
+        className={`absolute z-[-1] w-4 h-4 bg-white border border-gray-300 rotate-45
+          ${arrowClasses}`}
+      />
+    </div>
+  );
+};

package/src/components/map/basemaps.ts

@@ -0,0 +1,79 @@
+import type { StaticImageData } from 'next/image';
+import TileLayer from 'ol/layer/Tile';
+import OSM from 'ol/source/OSM';
+import XYZ from 'ol/source/XYZ';
+
+import OsImage from './images/basemaps/OS.png';
+import SatelliteMapTilerImage from './images/basemaps/satellite-map-tiler.png';
+import SatelliteImage from './images/basemaps/satellite.png';
+import StreetsImage from './images/basemaps/streets.png';
+
+export const initializeBasemapLayers = () => {
+  const osmLayer = new TileLayer({
+    preload: Infinity,
+    source: new OSM(),
+    visible: true,
+  });
+
+  osmLayer.set('name', 'OSM');
+  osmLayer.set('basemap', true);
+  const osImageData = OsImage as unknown as StaticImageData;
+
+  osmLayer.set('image', osImageData.src);
+
+  const osMapsLight = new TileLayer({
+    // attributions: [`© Crown Copyright and Database Rights [insert year of creation] OS AC0000807064`],
+    source: new XYZ({
+      url: '/water-quality-archive/api/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png',
+    }),
+    visible: false,
+  });
+
+  osMapsLight.set('name', 'OS Maps Light');
+  osMapsLight.set('basemap', true);
+  osMapsLight.set('image', osImageData.src);
+
+  const osMapsOutdoor = new TileLayer({
+    // attributions: [`© Crown Copyright and Database Rights [insert year of creation] OS AC0000807064`],
+    source: new XYZ({
+      url: '/water-quality-archive/api/maps/raster/v1/zxy/Outdoor_3857/{z}/{x}/{y}.png',
+    }),
+    visible: false,
+  });
+
+  osMapsOutdoor.set('name', 'OS Maps Outdoor');
+  osMapsOutdoor.set('basemap', true);
+  const streetsImageData = StreetsImage as unknown as StaticImageData;
+
+  osMapsOutdoor.set('image', streetsImageData.src);
+
+  const osMapsRoad = new TileLayer({
+    // attributions: [`© Crown Copyright and Database Rights [insert year of creation] OS AC0000807064`],
+    source: new XYZ({
+      url: '/water-quality-archive/api/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png',
+    }),
+    visible: false,
+  });
+
+  osMapsRoad.set('name', 'OS Maps Road');
+  osMapsRoad.set('basemap', true);
+  const satelliteMapTilerImageData = SatelliteMapTilerImage as unknown as StaticImageData;
+
+  osMapsRoad.set('image', satelliteMapTilerImageData.src);
+
+  const worldImagery = new TileLayer({
+    source: new XYZ({
+      url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}',
+      maxZoom: 19,
+    }),
+    visible: false,
+  });
+
+  worldImagery.set('name', 'ESRI World Imagery');
+  worldImagery.set('basemap', true);
+  const satelliteImageData = SatelliteImage as unknown as StaticImageData;
+
+  worldImagery.set('image', satelliteImageData.src);
+
+  return [osmLayer, osMapsLight, osMapsOutdoor, osMapsRoad, worldImagery];
+};

package/src/components/map/geocoder.ts

@@ -0,0 +1,61 @@
+import { Map } from 'ol';
+import { transformExtent } from 'ol/proj';
+import Geocoder from 'ol-geocoder';
+
+import { EPSG_3857, EPSG_4326 } from './geometries';
+import { osOpenNamesSearch } from './osOpenNamesSearch';
+
+type AddressChosenEvent = {
+  place: {
+    lon: number;
+    lat: number;
+    bbox?: [number, number, number, number]; // [minLon, minLat, maxLon, maxLat]
+    address: {
+      name: string;
+      city?: string;
+      state?: string;
+      country?: string;
+    };
+  };
+};
+
+export const initializeGeocoder = (apiKey: string, geoCoderUrl: string, map: Map) => {
+  if (!apiKey) {
+    console.warn('No API key provided for geocoder initialization.');
+
+    throw new Error(
+      'API key is required for geocoder initialization. Please provide a valid API key.',
+    );
+  }
+
+  const provider = osOpenNamesSearch({
+    url: geoCoderUrl,
+  });
+
+  const geocoder = new Geocoder('nominatim', {
+    provider,
+    key: apiKey,
+    lang: 'en',
+    placeholder: 'Search for ...',
+    targetType: 'text-input',
+    keepOpen: false,
+    preventMarker: true,
+    debug: true,
+  });
+
+  // Since we provide a bbox in the custom provider response,
+  // we also need to handle the address chosen event.
+  geocoder.on('addresschosen', (event: AddressChosenEvent) => {
+    if (event.place.bbox) {
+      const extent3857 = transformExtent(event.place.bbox, EPSG_4326, EPSG_3857);
+
+      map.getView().fit(extent3857, {
+        duration: 500,
+        padding: [50, 50, 50, 50],
+        maxZoom: 18,
+      });
+    }
+  });
+
+  return geocoder;
+};