@defra/forms-engine-plugin 4.0.41 → 4.0.42

package/src/client/javascripts/location-map.js

@@ -0,0 +1,766 @@
+// @ts-expect-error - no types
+import OsGridRef, { LatLon } from 'geodesy/osgridref.js'
+
+/**
+ * Converts lat long to easting and northing
+ * @param {object} param
+ * @param {number} param.lat
+ * @param {number} param.long
+ * @returns {{ easting: number, northing: number }}
+ */
+function latLongToEastingNorthing({ lat, long }) {
+  const point = new LatLon(lat, long)
+
+  return point.toOsGrid()
+}
+
+/**
+ * Converts easting and northing to lat long
+ * @param {object} param
+ * @param {number} param.easting
+ * @param {number} param.northing
+ * @returns {{ lat: number, long: number }}
+ */
+function eastingNorthingToLatLong({ easting, northing }) {
+  const point = new OsGridRef(easting, northing)
+  const latLong = point.toLatLon()
+
+  return { lat: latLong.latitude, long: latLong.longitude }
+}
+
+/**
+ * Converts lat long to an ordnance survey grid reference
+ * @param {object} param
+ * @param {number} param.lat
+ * @param {number} param.long
+ * @returns {string}
+ */
+function latLongToOsGridRef({ lat, long }) {
+  const point = new LatLon(lat, long)
+
+  return point.toOsGrid().toString()
+}
+
+/**
+ * Converts an ordnance survey grid reference to lat long
+ * @param {string} osGridRef
+ * @returns {{ lat: number, long: number }}
+ */
+function osGridRefToLatLong(osGridRef) {
+  const point = OsGridRef.parse(osGridRef)
+  const latLong = point.toLatLon()
+
+  return { lat: latLong.latitude, long: latLong.longitude }
+}
+
+// Center of UK
+const DEFAULT_LAT = 53.825564
+const DEFAULT_LONG = -2.421975
+
+/** @type {InteractiveMapInitConfig} */
+const defaultConfig = {
+  zoom: '6',
+  center: [DEFAULT_LONG, DEFAULT_LAT]
+}
+
+const COMPANY_SYMBOL_CODE = 169
+const LOCATION_FIELD_SELECTOR = 'input.govuk-input'
+const EVENTS = {
+  interactMarkerChange: 'interact:markerchange'
+}
+
+const defaultData = {
+  VTS_OUTDOOR_URL: '/api/maps/vts/OS_VTS_3857_Outdoor.json',
+  VTS_DARK_URL: '/api/maps/vts/OS_VTS_3857_Dark.json',
+  VTS_BLACK_AND_WHITE_URL: '/api/maps/vts/OS_VTS_3857_Black_and_White.json'
+}
+
+/**
+ * Make a form submit handler that only allows submissions from allowed buttons
+ * @param {HTMLButtonElement[]} buttons - the form buttons to allow submissions
+ */
+export function formSubmitFactory(buttons) {
+  /**
+   * The submit handler
+   * @param {SubmitEvent} e
+   */
+  const onFormSubmit = function (e) {
+    if (
+      !(e.submitter instanceof HTMLButtonElement) ||
+      !buttons.includes(e.submitter)
+    ) {
+      e.preventDefault()
+    }
+  }
+
+  return onFormSubmit
+}
+
+/**
+ * Initialise location maps
+ * @param {Partial<MapsEnvironmentConfig>} config - the map configuration
+ */
+export function initMaps(config = {}) {
+  const {
+    assetPath = '/assets',
+    apiPath = '/form/api',
+    data = defaultData
+  } = config
+  const locations = document.querySelectorAll('.app-location-field')
+
+  // TODO: Fix this in `interactive-map`
+  // If there are location components on the page fix up the main form submit
+  // handler so it doesn't fire when using the integrated map search feature
+  if (locations.length) {
+    const form = document.querySelector('form')
+
+    if (form === null) {
+      return
+    }
+
+    const buttons = Array.from(form.querySelectorAll('button'))
+    form.addEventListener('submit', formSubmitFactory(buttons), false)
+  }
+
+  locations.forEach((location, index) => {
+    processLocation({ assetPath, apiPath, data }, location, index)
+  })
+}
+
+/**
+ * OS API request proxy factory
+ * @param {string} apiPath - the root API path
+ */
+export function makeTileRequestTransformer(apiPath) {
+  /**
+   * Proxy OS API requests via our server
+   * @param {string} url - the request URL
+   * @param {string} resourceType - the resource type
+   */
+  return function transformTileRequest(url, resourceType) {
+    // Only proxy OS API requests that don't already have a key
+    if (resourceType !== 'Style' && url.startsWith('https://api.os.uk')) {
+      const urlObj = new URL(url)
+      if (!urlObj.searchParams.has('key')) {
+        return {
+          url: `${apiPath}/map-proxy?url=${encodeURIComponent(url)}`,
+          headers: {}
+        }
+      }
+    }
+
+    const spritesPath =
+      'https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main'
+
+    // Proxy sprite requests
+    if (url.startsWith(spritesPath)) {
+      const path = url.substring(spritesPath.length)
+      return {
+        url: `${apiPath}/maps/vts${path}`,
+        headers: {}
+      }
+    }
+
+    return { url, headers: {} }
+  }
+}
+
+/**
+ * Processes a location field to add map capability
+ * @param {MapsEnvironmentConfig} config - the location field element
+ * @param {Element} location - the location field element
+ * @param {*} index - the 0-based index
+ */
+function processLocation(config, location, index) {
+  if (!(location instanceof HTMLDivElement)) {
+    return
+  }
+
+  const locationInputs = location.querySelector('.app-location-field-inputs')
+  if (!(locationInputs instanceof HTMLDivElement)) {
+    return
+  }
+  const locationType = location.dataset.locationtype
+
+  // Check for support
+  const supportedLocations = [
+    'latlongfield',
+    'eastingnorthingfield',
+    'osgridreffield'
+  ]
+  if (!locationType || !supportedLocations.includes(locationType)) {
+    return
+  }
+
+  const mapContainer = document.createElement('div')
+  const mapId = `map_${index}`
+
+  mapContainer.setAttribute('id', mapId)
+  mapContainer.setAttribute('class', 'map-container')
+
+  const initConfig = getInitMapConfig(location) ?? defaultConfig
+
+  locationInputs.after(mapContainer)
+
+  const { map, interactPlugin } = createMap(mapId, initConfig, config)
+
+  map.on(
+    'map:ready',
+    /**
+     * Callback function which fires when the map is ready
+     * @param {object} e - the event
+     * @param {MapLibreMap} e.map - the map provider instance
+     */
+    function onMapReady(e) {
+      switch (locationType) {
+        case 'latlongfield':
+          bindLatLongField(location, map, e.map)
+          break
+        case 'eastingnorthingfield':
+          bindEastingNorthingField(location, map, e.map)
+          break
+        case 'osgridreffield':
+          bindOsGridRefField(location, map, e.map)
+          break
+        default:
+          throw new Error('Not implemented')
+      }
+
+      // Add info panel
+      map.addPanel('info', {
+        showLabel: true,
+        label: 'How to use the map',
+        mobile: {
+          slot: 'bottom',
+          initiallyOpen: true,
+          dismissable: true,
+          modal: false
+        },
+        tablet: {
+          slot: 'bottom',
+          initiallyOpen: true,
+          dismissable: true,
+          modal: false
+        },
+        desktop: {
+          slot: 'bottom',
+          initiallyOpen: true,
+          dismissable: true,
+          modal: false
+        },
+        html: 'If using a map click on a point to update the location.<br><br>If using a keyboard, navigate to the point, centering the crosshair at the location and press enter.'
+      })
+
+      // Enable the interact plugin
+      interactPlugin.enable()
+    }
+  )
+}
+
+/**
+ * Create a Defra map instance
+ * @param {string} mapId - the map id
+ * @param {InteractiveMapInitConfig} initConfig - the map initial configuration
+ * @param {MapsEnvironmentConfig} mapsConfig - the map environment params
+ */
+function createMap(mapId, initConfig, mapsConfig) {
+  const { assetPath, apiPath, data = defaultData } = mapsConfig
+  const logoAltText = 'Ordnance survey logo'
+
+  // @ts-expect-error - Defra namespace currently comes from UMD support files
+  const defra = window.defra
+
+  const interactPlugin = defra.interactPlugin({
+    dataLayers: [],
+    markerColor: { outdoor: '#ff0000', dark: '#00ff00' },
+    interactionMode: 'marker',
+    multiSelect: false
+  })
+
+  /** @type {InteractiveMap} */
+  const map = new defra.InteractiveMap(mapId, {
+    ...initConfig,
+    mapProvider: defra.maplibreProvider(),
+    reverseGeocodeProvider: defra.openNamesProvider({
+      url: `${apiPath}/reverse-geocode-proxy?easting={easting}&northing={northing}`
+    }),
+    behaviour: 'inline',
+    minZoom: 6,
+    maxZoom: 18,
+    containerHeight: '400px',
+    enableZoomControls: true,
+    transformRequest: makeTileRequestTransformer(apiPath),
+    plugins: [
+      defra.mapStylesPlugin({
+        mapStyles: [
+          {
+            id: 'outdoor',
+            label: 'Outdoor',
+            url: data.VTS_OUTDOOR_URL,
+            thumbnail: `${assetPath}/interactive-map/assets/images/outdoor-map-thumb.jpg`,
+            logo: `${assetPath}/interactive-map/assets/images/os-logo.svg`,
+            logoAltText,
+            attribution: `Contains OS data ${String.fromCodePoint(COMPANY_SYMBOL_CODE)} Crown copyright and database rights ${new Date().getFullYear()}`,
+            backgroundColor: '#f5f5f0'
+          },
+          {
+            id: 'dark',
+            label: 'Dark',
+            url: data.VTS_DARK_URL,
+            mapColorScheme: 'dark',
+            appColorScheme: 'dark',
+            thumbnail: `${assetPath}/interactive-map/assets/images/dark-map-thumb.jpg`,
+            logo: `${assetPath}/interactive-map/assets/images/os-logo-white.svg`,
+            logoAltText,
+            attribution: `Contains OS data ${String.fromCodePoint(COMPANY_SYMBOL_CODE)} Crown copyright and database rights ${new Date().getFullYear()}`
+          },
+          {
+            id: 'black-and-white',
+            label: 'Black/White',
+            url: data.VTS_BLACK_AND_WHITE_URL,
+            thumbnail: `${assetPath}/interactive-map/assets/images/black-and-white-map-thumb.jpg`,
+            logo: `${assetPath}/interactive-map/assets/images/os-logo-black.svg`,
+            logoAltText,
+            attribution: `Contains OS data ${String.fromCodePoint(COMPANY_SYMBOL_CODE)} Crown copyright and database rights ${new Date().getFullYear()}`
+          }
+        ]
+      }),
+      interactPlugin,
+      defra.searchPlugin({
+        osNamesURL: `${apiPath}/geocode-proxy?query={query}`,
+        width: '300px',
+        showMarker: false
+      }),
+      defra.scaleBarPlugin({
+        units: 'metric'
+      })
+    ]
+  })
+
+  return { map, interactPlugin }
+}
+
+/**
+ * Gets initial map config for a location field
+ * @param {HTMLDivElement} locationField - the location field element
+ */
+function getInitMapConfig(locationField) {
+  const locationType = locationField.dataset.locationtype
+
+  switch (locationType) {
+    case 'latlongfield':
+      return getInitLatLongMapConfig(locationField)
+    case 'eastingnorthingfield':
+      return getInitEastingNorthingMapConfig(locationField)
+    case 'osgridreffield':
+      return getInitOsGridRefMapConfig(locationField)
+    default:
+      throw new Error('Not implemented')
+  }
+}
+
+/**
+ * Validates lat and long is numeric and within UK bounds
+ * @param {string} strLat - the latitude string
+ * @param {string} strLong - the longitude string
+ * @returns {{ valid: false } | { valid: true, value: { lat: number, long: number } }}
+ */
+function validateLatLong(strLat, strLong) {
+  const lat = strLat.trim() && Number(strLat.trim())
+  const long = strLong.trim() && Number(strLong.trim())
+
+  if (!lat || !long) {
+    return { valid: false }
+  }
+
+  const latMin = 49.85
+  const latMax = 60.859
+  const longMin = -13.687
+  const longMax = 1.767
+
+  const latInBounds = lat >= latMin && lat <= latMax
+  const longInBounds = long >= longMin && long <= longMax
+
+  if (!latInBounds || !longInBounds) {
+    return { valid: false }
+  }
+
+  return { valid: true, value: { lat, long } }
+}
+
+/**
+ * Validates easting and northing is numeric and within UK bounds
+ * @param {string} strEasting - the easting string
+ * @param {string} strNorthing - the northing string
+ * @returns {{ valid: false } | { valid: true, value: { easting: number, northing: number } }}
+ */
+function validateEastingNorthing(strEasting, strNorthing) {
+  const easting = strEasting.trim() && Number(strEasting.trim())
+  const northing = strNorthing.trim() && Number(strNorthing.trim())
+
+  if (!easting || !northing) {
+    return { valid: false }
+  }
+
+  const eastingMin = 0
+  const eastingMax = 700000
+  const northingMin = 0
+  const northingMax = 1300000
+
+  const latInBounds = easting >= eastingMin && easting <= eastingMax
+  const longInBounds = northing >= northingMin && northing <= northingMax
+
+  if (!latInBounds || !longInBounds) {
+    return { valid: false }
+  }
+
+  return { valid: true, value: { easting, northing } }
+}
+
+/**
+ * Validates OS grid reference is correct
+ * @param {string} osGridRef - the OsGridRef
+ * @returns {{ valid: false } | { valid: true, value: string }}
+ */
+function validateOsGridRef(osGridRef) {
+  if (!osGridRef) {
+    return { valid: false }
+  }
+
+  const pattern =
+    /^((([sS]|[nN])[a-hA-Hj-zJ-Z])|(([tT]|[oO])[abfglmqrvwABFGLMQRVW])|([hH][l-zL-Z])|([jJ][lmqrvwLMQRVW]))\s?(([0-9]{3})\s?([0-9]{3})|([0-9]{4})\s?([0-9]{4})|([0-9]{5})\s?([0-9]{5}))$/
+
+  const match = pattern.exec(osGridRef)
+
+  if (match === null) {
+    return { valid: false }
+  }
+
+  return { valid: true, value: match[0] }
+}
+
+/**
+ * Gets the inputs for a latlong location field
+ * @param {HTMLDivElement} locationField - the latlong location field element
+ */
+function getLatLongInputs(locationField) {
+  const inputs = locationField.querySelectorAll(LOCATION_FIELD_SELECTOR)
+
+  if (inputs.length !== 2) {
+    throw new Error('Expected 2 inputs for lat and long')
+  }
+
+  const latInput = /** @type {HTMLInputElement} */ (inputs[0])
+  const longInput = /** @type {HTMLInputElement} */ (inputs[1])
+
+  return { latInput, longInput }
+}
+
+/**
+ * Gets the inputs for a easting/northing location field
+ * @param {HTMLDivElement} locationField - the eastingnorthing location field element
+ */
+function getEastingNorthingInputs(locationField) {
+  const inputs = locationField.querySelectorAll(LOCATION_FIELD_SELECTOR)
+
+  if (inputs.length !== 2) {
+    throw new Error('Expected 2 inputs for easting and northing')
+  }
+
+  const eastingInput = /** @type {HTMLInputElement} */ (inputs[0])
+  const northingInput = /** @type {HTMLInputElement} */ (inputs[1])
+
+  return { eastingInput, northingInput }
+}
+
+/**
+ * Gets the input for a OS grid reference location field
+ * @param {HTMLDivElement} locationField - the osgridref location field element
+ */
+function getOsGridRefInput(locationField) {
+  const input = locationField.querySelector(LOCATION_FIELD_SELECTOR)
+
+  if (input === null) {
+    throw new Error('Expected 1 input for osgridref')
+  }
+
+  return /** @type {HTMLInputElement} */ (input)
+}
+
+/**
+ * Get the initial map config for a center point
+ * @param {MapCenter} center - the point
+ */
+function getInitMapCenterConfig(center) {
+  return {
+    zoom: '16',
+    center,
+    markers: [
+      {
+        id: 'location',
+        coords: center
+      }
+    ]
+  }
+}
+
+/**
+ * Gets initial map config for a latlong location field
+ * @param {HTMLDivElement} locationField - the latlong location field element
+ * @returns {InteractiveMapInitConfig | undefined}
+ */
+function getInitLatLongMapConfig(locationField) {
+  const { latInput, longInput } = getLatLongInputs(locationField)
+  const result = validateLatLong(latInput.value, longInput.value)
+
+  if (!result.valid) {
+    return undefined
+  }
+
+  /** @type {MapCenter} */
+  const center = [result.value.long, result.value.lat]
+
+  return getInitMapCenterConfig(center)
+}
+
+/**
+ * Gets initial map config for a easting/northing location field
+ * @param {HTMLDivElement} locationField - the eastingnorthing location field element
+ * @returns {InteractiveMapInitConfig | undefined}
+ */
+function getInitEastingNorthingMapConfig(locationField) {
+  const { eastingInput, northingInput } =
+    getEastingNorthingInputs(locationField)
+  const result = validateEastingNorthing(
+    eastingInput.value,
+    northingInput.value
+  )
+
+  if (!result.valid) {
+    return undefined
+  }
+
+  const latlong = eastingNorthingToLatLong(result.value)
+
+  /** @type {MapCenter} */
+  const center = [latlong.long, latlong.lat]
+
+  return getInitMapCenterConfig(center)
+}
+
+/**
+ * Gets initial map config for an OS grid reference location field
+ * @param {HTMLDivElement} locationField - the osgridref location field element
+ * @returns {InteractiveMapInitConfig | undefined}
+ */
+function getInitOsGridRefMapConfig(locationField) {
+  const osGridRefInput = getOsGridRefInput(locationField)
+  const result = validateOsGridRef(osGridRefInput.value)
+
+  if (!result.valid) {
+    return undefined
+  }
+
+  const latlong = osGridRefToLatLong(result.value)
+
+  /** @type {MapCenter} */
+  const center = [latlong.long, latlong.lat]
+
+  return getInitMapCenterConfig(center)
+}
+
+/**
+ * Bind a latlong field to the map
+ * @param {HTMLDivElement} locationField - the latlong location field
+ * @param {InteractiveMap} map - the map component instance (of InteractiveMap)
+ * @param {MapLibreMap} mapProvider - the map provider instance (of MapLibreMap)
+ */
+function bindLatLongField(locationField, map, mapProvider) {
+  const { latInput, longInput } = getLatLongInputs(locationField)
+
+  map.on(
+    EVENTS.interactMarkerChange,
+    /**
+     * Callback function which fires when the map marker changes
+     * @param {object} e - the event
+     * @param {[number, number]} e.coords - the map marker coordinates
+     */
+    function onInteractMarkerChange(e) {
+      const maxPrecision = 7
+      latInput.value = e.coords[1].toFixed(maxPrecision)
+      longInput.value = e.coords[0].toFixed(maxPrecision)
+    }
+  )
+
+  /**
+   * Lat & long input change event listener
+   * Update the map view location when the inputs are changed
+   */
+  function onUpdateInputs() {
+    const result = validateLatLong(latInput.value, longInput.value)
+
+    if (result.valid) {
+      /** @type {MapCenter} */
+      const center = [result.value.long, result.value.lat]
+
+      centerMap(map, mapProvider, center)
+    }
+  }
+
+  latInput.addEventListener('change', onUpdateInputs, false)
+  longInput.addEventListener('change', onUpdateInputs, false)
+}
+
+/**
+ * Bind an eastingnorthing field to the map
+ * @param {HTMLDivElement} locationField - the eastingnorthing location field
+ * @param {InteractiveMap} map - the map component instance (of InteractiveMap)
+ * @param {MapLibreMap} mapProvider - the map provider instance (of MapLibreMap)
+ */
+function bindEastingNorthingField(locationField, map, mapProvider) {
+  const { eastingInput, northingInput } =
+    getEastingNorthingInputs(locationField)
+
+  map.on(
+    EVENTS.interactMarkerChange,
+    /**
+     * Callback function which fires when the map marker changes
+     * @param {object} e - the event
+     * @param {[number, number]} e.coords - the map marker coordinates
+     */
+    function onInteractMarkerChange(e) {
+      const maxPrecision = 0
+      const point = latLongToEastingNorthing({
+        lat: e.coords[1],
+        long: e.coords[0]
+      })
+
+      eastingInput.value = point.easting.toFixed(maxPrecision)
+      northingInput.value = point.northing.toFixed(maxPrecision)
+    }
+  )
+
+  /**
+   * Easting & northing input change event listener
+   * Update the map view location when the inputs are changed
+   */
+  function onUpdateInputs() {
+    const result = validateEastingNorthing(
+      eastingInput.value,
+      northingInput.value
+    )
+
+    if (result.valid) {
+      const latlong = eastingNorthingToLatLong(result.value)
+
+      /** @type {MapCenter} */
+      const center = [latlong.long, latlong.lat]
+
+      centerMap(map, mapProvider, center)
+    }
+  }
+
+  eastingInput.addEventListener('change', onUpdateInputs, false)
+  northingInput.addEventListener('change', onUpdateInputs, false)
+}
+
+/**
+ * Bind an OS grid reference field to the map
+ * @param {HTMLDivElement} locationField - the osgridref location field
+ * @param {InteractiveMap} map - the map component instance (of InteractiveMap)
+ * @param {MapLibreMap} mapProvider - the map provider instance (of MapLibreMap)
+ */
+function bindOsGridRefField(locationField, map, mapProvider) {
+  const osGridRefInput = getOsGridRefInput(locationField)
+
+  map.on(
+    EVENTS.interactMarkerChange,
+    /**
+     * Callback function which fires when the map marker changes
+     * @param {object} e - the event
+     * @param {[number, number]} e.coords - the map marker coordinates
+     */
+    function onInteractMarkerChange(e) {
+      const point = latLongToOsGridRef({
+        lat: e.coords[1],
+        long: e.coords[0]
+      })
+
+      osGridRefInput.value = point
+    }
+  )
+
+  /**
+   * OS grid reference input change event listener
+   * Update the map view location when the input is changed
+   */
+  function onUpdateInput() {
+    const result = validateOsGridRef(osGridRefInput.value)
+
+    if (result.valid) {
+      const latlong = osGridRefToLatLong(result.value)
+
+      /** @type {MapCenter} */
+      const center = [latlong.long, latlong.lat]
+
+      centerMap(map, mapProvider, center)
+    }
+  }
+
+  osGridRefInput.addEventListener('change', onUpdateInput, false)
+}
+
+/**
+ * Updates the marker position and moves the map view port the new location
+ * @param {InteractiveMap} map - the map component instance (of InteractiveMap)
+ * @param {MapLibreMap} mapProvider - the map provider instance (of MapLibreMap)
+ * @param {MapCenter} center - the point
+ */
+function centerMap(map, mapProvider, center) {
+  // Move the 'location' marker to the new point
+  map.addMarker('location', center)
+
+  // Pan & zoom the map to the new valid location
+  mapProvider.flyTo({
+    center,
+    zoom: 14,
+    essential: true
+  })
+}
+
+/**
+ * @typedef {object} InteractiveMap - an instance of a InteractiveMap
+ * @property {Function} on - register callback listeners to map events
+ * @property {Function} addPanel - adds a new panel to the map
+ * @property {Function} addMarker - adds/updates a marker
+ */
+
+/**
+ * @typedef {object} MapLibreMap
+ * @property {Function} flyTo - pans/zooms to a new location
+ */
+
+/**
+ * @typedef {[number, number]} MapCenter - Map center point as [long, lat]
+ */
+
+/**
+ * @typedef {object} InteractiveMapInitConfig - additional config that can be provided to InteractiveMap
+ * @property {string} zoom - the zoom level of the map
+ * @property {MapCenter} center - the center point of the map
+ * @property {{ id: string, coords: MapCenter}[]} [markers] - the markers to add to the map
+ */
+
+/**
+ * @typedef {object} TileData
+ * @property {string} VTS_OUTDOOR_URL - the outdoor tile URL
+ * @property {string} VTS_DARK_URL - the dark tile URL
+ * @property {string} VTS_BLACK_AND_WHITE_URL - the black and white tile URL
+ */
+
+/**
+ * @typedef {object} MapsEnvironmentConfig
+ * @property {string} assetPath - the root asset path
+ * @property {string} apiPath - the root API path
+ * @property {TileData} data - the tile data config
+ */