@defra/forms-engine-plugin 4.13.0 → 4.14.0

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

@@ -7,6 +7,7 @@ import {
   getCentroidGridRef,
   getCoordinateGridRef
 } from './map.js'
+import { formatDelimtedList } from './utils.js'
 
 const helpPanelConfig = {
   showLabel: true,
@@ -28,8 +29,63 @@ const helpPanelConfig = {
     open: true,
     dismissible: true,
     modal: false
-  },
-  html: '<p class="govuk-body-s govuk-!-margin-bottom-2">You can add points, shapes or lines to the map.</p><ul class="govuk-list govuk-list--number govuk-body-s"><li>Search for a county, place or postcode</li><li>Use the + and - icons to zoom in and out</li><li>Double‑click, or select \'Done\', when you have finished drawing a line or shape</li><li>Give the location a name</li></ul>'
+  }
+}
+
+/**
+ * @param {boolean} allowLine
+ * @param {boolean} allowShape
+ */
+function getLineOrShapeText(allowLine, allowShape) {
+  if (allowLine && allowShape) {
+    return 'a line or shape'
+  }
+  if (allowLine) {
+    return 'a line'
+  }
+  if (allowShape) {
+    return 'a shape'
+  }
+  return ''
+}
+
+/**
+ * @param {boolean} allowPoint
+ * @param {boolean} allowLine
+ * @param {boolean} allowShape
+ */
+function getAllowedTypesPhrase(allowPoint, allowLine, allowShape) {
+  const items = []
+
+  if (allowPoint) {
+    items.push('points')
+  }
+  if (allowLine) {
+    items.push('lines')
+  }
+  if (allowShape) {
+    items.push('shapes')
+  }
+
+  return formatDelimtedList(items, ',', 'or')
+}
+
+/**
+ * @param {boolean} allowPoint
+ * @param {boolean} allowLine
+ * @param {boolean} allowShape
+ */
+export function getHelpPanelHtml(allowPoint, allowLine, allowShape) {
+  const lineOrShapeText = getLineOrShapeText(allowLine, allowShape)
+  const doneExtra = lineOrShapeText
+    ? `<li>Double‑click, or select 'Done', when you have finished drawing ${lineOrShapeText}</li>`
+    : ''
+  const allowedTypesText = getAllowedTypesPhrase(
+    allowPoint,
+    allowLine,
+    allowShape
+  )
+  return `<p class="govuk-body-s govuk-!-margin-bottom-2">You can add ${allowedTypesText} to the map.</p><ul class="govuk-list govuk-list--number govuk-body-s"><li>Search for a county, place or postcode</li><li>Use the + and - icons to zoom in and out</li>${doneExtra}<li>Give the location a name</li></ul>`
 }
 
 const lineFeatureProperties = {
@@ -157,7 +213,18 @@ export function processGeospatial(config, geospatial, index) {
   const { map, interactPlugin } = createMap(mapId, initConfig, config)
   const featuresManager = getFeaturesManager(geojson)
   const activeFeatureManager = getActiveFeatureManager()
-  const uiManager = getUIManager(geojson, map, mapId, listEl, geospatialInput)
+  const geometryTypes = geospatial.dataset.geometrytypes ?? 'point,line,shape'
+  const options = {
+    geometryTypes
+  }
+  const uiManager = getUIManager(
+    geojson,
+    map,
+    mapId,
+    listEl,
+    geospatialInput,
+    options
+  )
 
   /**
    * @type {Context}
@@ -492,16 +559,32 @@ function getValueRenderer(geojson, geospatialInput) {
  * @param {string} mapId - the ID of the map
  * @param {HTMLDivElement} listEl - where to render the feature list
  * @param {HTMLTextAreaElement} geospatialInput - the geospatial textarea
+ * @param {UIManagerOptions} options - extra options such as allowable geometry types
  */
-function getUIManager(geojson, map, mapId, listEl, geospatialInput) {
+function getUIManager(geojson, map, mapId, listEl, geospatialInput, options) {
+  /**
+   * Get a CSV list of geometry types the user can create
+   * @returns {string[]}
+   */
+  function getAllowableGeometryTypes() {
+    return options.geometryTypes ? options.geometryTypes.split(',') : []
+  }
+
   /**
    * Toggle the hidden state of the action buttons
    * @type {ToggleActionButtons}
    */
   function toggleActionButtons(hidden) {
-    map.toggleButtonState('btnAddPoint', 'hidden', hidden)
-    map.toggleButtonState('btnAddPolygon', 'hidden', hidden)
-    map.toggleButtonState('btnAddLine', 'hidden', hidden)
+    const types = getAllowableGeometryTypes()
+    if (types.includes('point')) {
+      map.toggleButtonState('btnAddPoint', 'hidden', hidden)
+    }
+    if (types.includes('shape')) {
+      map.toggleButtonState('btnAddPolygon', 'hidden', hidden)
+    }
+    if (types.includes('line')) {
+      map.toggleButtonState('btnAddLine', 'hidden', hidden)
+    }
   }
 
   /**
@@ -528,7 +611,8 @@ function getUIManager(geojson, map, mapId, listEl, geospatialInput) {
     renderValue,
     listEl,
     toggleActionButtons,
-    focusDescriptionInput
+    focusDescriptionInput,
+    getAllowableGeometryTypes
   }
 }
 
@@ -572,7 +656,8 @@ function createContainers(geospatialInput, index) {
 function onMapReadyFactory(context) {
   const { map, activeFeatureManager, uiManager, interactPlugin, drawPlugin } =
     context
-  const { toggleActionButtons, renderList } = uiManager
+  const { toggleActionButtons, renderList, getAllowableGeometryTypes } =
+    uiManager
   const { resetActiveFeature } = activeFeatureManager
 
   /**
@@ -581,53 +666,67 @@ function onMapReadyFactory(context) {
    * @param {MapLibreMap} e.map - the map provider instance
    */
   return function onMapReady(e) {
+    const types = getAllowableGeometryTypes()
+    const allowPoint = types.includes('point')
+    const allowLine = types.includes('line')
+    const allowShape = types.includes('shape')
+
     // Add info panel
-    map.addPanel('info', helpPanelConfig)
-
-    map.addButton('btnAddPoint', {
-      variant: 'tertiary',
-      label: 'Add point',
-      iconSvgContent: POINT_SVG,
-      onClick: () => {
-        resetActiveFeature()
-        toggleActionButtons(true)
-        renderList(true)
-        interactPlugin.enable()
-      },
-      mobile: { slot: 'actions' },
-      tablet: { slot: 'actions' },
-      desktop: { slot: 'actions' }
+    map.addPanel('info', {
+      ...helpPanelConfig,
+      html: getHelpPanelHtml(allowPoint, allowLine, allowShape)
     })
 
-    map.addButton('btnAddPolygon', {
-      variant: 'tertiary',
-      label: 'Add shape',
-      iconSvgContent: POLYGON_SVG,
-      onClick: () => {
-        resetActiveFeature()
-        toggleActionButtons(true)
-        renderList(true)
-        drawPlugin.newPolygon(generateID(), polygonFeatureProperties)
-      },
-      mobile: { slot: 'actions' },
-      tablet: { slot: 'actions' },
-      desktop: { slot: 'actions' }
-    })
+    if (allowPoint) {
+      map.addButton('btnAddPoint', {
+        variant: 'tertiary',
+        label: 'Add point',
+        iconSvgContent: POINT_SVG,
+        onClick: () => {
+          resetActiveFeature()
+          toggleActionButtons(true)
+          renderList(true)
+          interactPlugin.enable()
+        },
+        mobile: { slot: 'actions' },
+        tablet: { slot: 'actions' },
+        desktop: { slot: 'actions' }
+      })
+    }
 
-    map.addButton('btnAddLine', {
-      variant: 'tertiary',
-      label: 'Add line',
-      iconSvgContent: LINE_SVG,
-      onClick: () => {
-        resetActiveFeature()
-        toggleActionButtons(true)
-        renderList(true)
-        drawPlugin.newLine(generateID(), lineFeatureProperties)
-      },
-      mobile: { slot: 'actions' },
-      tablet: { slot: 'actions' },
-      desktop: { slot: 'actions' }
-    })
+    if (allowShape) {
+      map.addButton('btnAddPolygon', {
+        variant: 'tertiary',
+        label: 'Add shape',
+        iconSvgContent: POLYGON_SVG,
+        onClick: () => {
+          resetActiveFeature()
+          toggleActionButtons(true)
+          renderList(true)
+          drawPlugin.newPolygon(generateID(), polygonFeatureProperties)
+        },
+        mobile: { slot: 'actions' },
+        tablet: { slot: 'actions' },
+        desktop: { slot: 'actions' }
+      })
+    }
+
+    if (allowLine) {
+      map.addButton('btnAddLine', {
+        variant: 'tertiary',
+        label: 'Add line',
+        iconSvgContent: LINE_SVG,
+        onClick: () => {
+          resetActiveFeature()
+          toggleActionButtons(true)
+          renderList(true)
+          drawPlugin.newLine(generateID(), lineFeatureProperties)
+        },
+        mobile: { slot: 'actions' },
+        tablet: { slot: 'actions' },
+        desktop: { slot: 'actions' }
+      })
+    }
 
     // Set the map provider on the context
     context.mapProvider = e.map
@@ -1055,6 +1154,12 @@ function onListElKeydownFactory() {
  * @returns {void}
  */
 
+/**
+ * Returns the list of geometry types a user can create
+ * @callback GetAllowableGeometryTypes
+ * @returns {string[]}
+ */
+
 /**
  * Set focus to the last description input
  * @callback FocusDescriptionInput
@@ -1084,6 +1189,7 @@ function onListElKeydownFactory() {
  * @property {HTMLDivElement} listEl - the summary list of features
  * @property {ToggleActionButtons} toggleActionButtons - function that toggles the action buttons
  * @property {FocusDescriptionInput} focusDescriptionInput - function that sets focus to a description input element
+ * @property {GetAllowableGeometryTypes} getAllowableGeometryTypes - function that returns the array of geometry types a user can create
  */
 
 /**
@@ -1098,5 +1204,5 @@ function onListElKeydownFactory() {
  */
 
 /**
- * @import { MapLibreMap } from './map.js'
+ * @import { MapLibreMap, UIManagerOptions } from './map.js'
  */

package/src/client/javascripts/map.js

@@ -395,6 +395,11 @@ export function centerMap(map, mapProvider, center) {
  * @property {TileData} data - the tile data config
  */
 
+/**
+ * @typedef {object} UIManagerOptions
+ * @property {string} [geometryTypes] - the CSV list of geometry types that a user can create
+ */
+
 /**
  * @import { Feature } from '../../server/plugins/engine/types.js'
  */

package/src/client/javascripts/utils.js

@@ -0,0 +1,23 @@
+/**
+ * Builds a text representation of a list in the form 'a, b, c, d or e'
+ * @param {string[]} items
+ * @param {string} separator
+ * @param {string} lastSpearator
+ */
+export function formatDelimtedList(items, separator, lastSpearator) {
+  if (items.length === 0) {
+    return ''
+  }
+
+  if (items.length === 1) {
+    return items[0]
+  }
+
+  if (items.length === 2) {
+    return `${items[0]} ${lastSpearator} ${items[1]}`
+  }
+
+  const last = items.pop()
+  const separatorAndSpace = `${separator} `
+  return `${items.join(separatorAndSpace)} ${lastSpearator} ${last}`
+}

package/src/server/forms/simple-form.yaml

@@ -25,6 +25,15 @@ pages:
           required: true
         schema: {}
         id: b68df7f1-d4f4-4c17-83c8-402f584906c9
+      - type: GeospatialField
+        title: Where do you live?
+        name: applicantLocation
+        shortDescription: Your location
+        hint: ''
+        options:
+          required: true
+        schema: {}
+        id: e18116e0-7c3e-416a-af42-6f229017c5b1
     next: []
     id: 622a35ec-3795-418a-81f3-a45746959045
   - title: Upload a copy of your passport

package/src/server/plugins/engine/components/GeospatialField.ts

@@ -31,18 +31,21 @@ export class GeospatialField extends FormComponent {
 
     const { options } = def
 
-    let formSchema = getGeospatialSchema(options.countries?.at(0))
+    const formSchema = getGeospatialSchema(def)
       .label(this.label)
-      .required()
+      .messages({
+        'array.min': messageTemplate.featuresMin as string,
+        'array.max': messageTemplate.featuresMax as string,
+        'array.length': messageTemplate.featuresLength as string
+      })
 
-    formSchema = formSchema.max(50)
+    this.formSchema = formSchema
+    this.stateSchema = formSchema.default(null)
 
-    if (options.required !== false) {
-      formSchema = formSchema.min(1)
+    if (options.required === false) {
+      this.stateSchema = this.stateSchema.allow(null)
     }
 
-    this.formSchema = formSchema
-    this.stateSchema = formSchema.default(null)
     this.options = options
   }
 
@@ -93,6 +96,7 @@ export class GeospatialField extends FormComponent {
     return {
       ...viewModel,
       country: this.options.countries?.at(0),
+      geometryTypes: this.options.geometryTypes,
       value
     }
   }

package/src/server/plugins/engine/components/helpers/geospatial.ts

@@ -1,5 +1,6 @@
 import {
   GeospatialFieldOptionsCountryEnum,
+  type GeospatialFieldComponent,
   type GeospatialFieldOptionsCountry
 } from '@defra/forms-model'
 import Bourne from '@hapi/bourne'
@@ -31,7 +32,8 @@ const Joi = JoiBase.extend({
     from: 'string',
     method(value, helpers) {
       if (typeof value === 'string') {
-        if (value.trim() === '') {
+        const trimmed = value.trim()
+        if (trimmed === '' || trimmed === '[]') {
           return {
             value: undefined
           }
@@ -96,14 +98,48 @@ const featureSchema = Joi.object<Feature>().keys({
   geometry: featureGeometrySchema
 })
 
-const geospatialSchema = Joi.array<Feature[]>()
-  .items(featureSchema)
-  .unique('id')
-  .required()
+function applySchemaConstraints(
+  schema: JoiBase.ArraySchema<Feature[]>,
+  def: GeospatialFieldComponent
+) {
+  const { options, schema: constraints } = def
+  const isOptional = options.required === false
+
+  if (typeof constraints?.length === 'number') {
+    schema = schema.length(constraints.length)
+  } else {
+    if (typeof constraints?.min === 'number') {
+      schema = schema.min(constraints.min)
+    } else if (!isOptional) {
+      schema = schema.min(1)
+    }
+
+    schema = schema.max(
+      typeof constraints?.max === 'number' ? constraints.max : 50
+    )
+  }
+
+  if (isOptional) {
+    schema = schema.optional()
+  } else {
+    schema = schema.required()
+  }
+
+  return schema
+}
+
+export function getGeospatialSchema(
+  def: GeospatialFieldComponent
+): JoiBase.ArraySchema<Feature[]> {
+  const { options = {} } = def
+  const country: GeospatialFieldOptionsCountry | undefined =
+    options.countries?.at(0)
 
-export function getGeospatialSchema(country?: GeospatialFieldOptionsCountry) {
   if (!country) {
-    return geospatialSchema
+    return applySchemaConstraints(
+      Joi.array<Feature[]>().items(featureSchema).unique('id'),
+      def
+    )
   }
 
   const validateCountryBounds: CustomValidator = (value, helpers) => {
@@ -128,10 +164,12 @@ export function getGeospatialSchema(country?: GeospatialFieldOptionsCountry) {
     return value
   }
 
-  return Joi.array<Feature[]>()
-    .items(featureSchema.custom(validateCountryBounds))
-    .unique('id')
-    .required()
+  return applySchemaConstraints(
+    Joi.array<Feature[]>()
+      .items(featureSchema.custom(validateCountryBounds))
+      .unique('id'),
+    def
+  )
 }
 
 /**

package/src/server/plugins/engine/pageControllers/validationOptions.ts

@@ -64,7 +64,10 @@ export const messageTemplate: Record<string, JoiExpression> = {
   dateMax: '{{#title}} must be the same as or before {{#limit}}',
   arrayMin: 'Select at least {{#limit}} options from the list',
   arrayMax: 'Only {{#limit}} can be selected from the list',
-  arrayLength: 'Select only {{#limit}} options from the list'
+  arrayLength: 'Select only {{#limit}} options from the list',
+  featuresMin: 'Define at least {{#limit}} features',
+  featuresMax: 'Only {{#limit}} features can be defined',
+  featuresLength: 'Define exactly {{#limit}} features'
 }
 
 export const messages: LanguageMessagesExt = {

package/src/server/plugins/engine/views/components/geospatialfield.html

@@ -1,7 +1,7 @@
 {% from "govuk/components/textarea/macro.njk" import govukTextarea %}
 
 {% macro GeospatialField(component) %}
-  <div class="app-geospatial-field" data-country="{{component.model.country}}">
+  <div class="app-geospatial-field" data-country="{{component.model.country}}" data-geometryTypes="{{component.model.geometryTypes}}">
     {{ govukTextarea(component.model) }}
   </div>
 {% endmacro %}