@defra/interactive-map 0.0.4-alpha → 0.0.5-alpha

package/src/App/components/Viewport/Viewport.module.scss

@@ -71,7 +71,7 @@
     height: 66.66%;
 
     > *:first-child {
-        transform: scale(150%);
+        transform: scale(1.5);
     }
 }
 
@@ -80,7 +80,7 @@
     height: 50%;
 
     > *:first-child {
-        transform: scale(200%);
+        transform: scale(2);
     }
 }
 

package/src/App/controls/keyboardActions.js

@@ -35,11 +35,12 @@ export const createKeyboardActions = (mapProvider, announce, {
 
     zoomOut: (e) => mapProvider.zoomOut(getZoom(e.shiftKey)),
 
-    getInfo: async (e) => {
+    getInfo: async (_e) => {
       const coord = mapProvider.getCenter()
       const place = await reverseGeocode(mapProvider.getZoom(), coord)
       const area = mapProvider.getAreaDimensions?.()
-      announce(`${place}.${area ? ' Covering ' + area + '.' : ''}`, 'core')
+      const message = area ? `${place}. Covering ${area}.` : `${place}.`
+      announce(message, 'core')
     },
 
     highlightNextLabel: (e) => {

package/src/App/controls/keyboardShortcuts.js

@@ -48,13 +48,15 @@ export const coreShortcuts = [
     group: 'Labels',
     title: 'Highlight label at centre',
     command: '<kbd>Alt</kbd> + <kbd>Enter</kbd>',
-    enabled: false
+    enabled: false,
+    requiredConfig: ['readMapText']
   },
   {
     id: 'highlightNextLabel',
     group: 'Labels',
     title: 'Highlight nearby label',
     command: '<kbd>Alt</kbd> + <kbd>→</kbd>, <kbd>←</kbd>, <kbd>↑</kbd> or <kbd>↓</kbd>',
-    enabled: false
+    enabled: false,
+    requiredConfig: ['readMapText']
   }
 ]

package/src/App/hooks/useButtonStateEvaluator.js

@@ -4,6 +4,52 @@ import { useApp } from '../store/appContext.js'
 import { useConfig } from '../store/configContext.js'
 import { PluginContext } from '../store/PluginProvider.jsx'
 
+function evaluateButtonState ({ btn, pluginId, appState, dispatch, evaluateProp }) {
+  const checks = [{
+    prop: 'enableWhen',
+    state: appState.disabledButtons,
+    action: 'TOGGLE_BUTTON_DISABLED',
+    invert: true,
+    key: 'isDisabled'
+  },
+  {
+    prop: 'hiddenWhen',
+    state: appState.hiddenButtons,
+    action: 'TOGGLE_BUTTON_HIDDEN',
+    key: 'isHidden'
+  },
+  {
+    prop: 'pressedWhen',
+    state: appState.pressedButtons,
+    action: 'TOGGLE_BUTTON_PRESSED',
+    key: 'isPressed'
+  },
+  {
+    prop: 'expandedWhen',
+    state: appState.expandedButtons,
+    action: 'TOGGLE_BUTTON_EXPANDED',
+    key: 'isExpanded'
+  }]
+
+  checks.forEach(({ prop, state, action, key, invert }) => {
+    if (typeof btn[prop] !== 'function') {
+      return
+    }
+
+    try {
+      const result = evaluateProp(btn[prop], pluginId)
+      const next = invert ? !result : result
+      const current = state.has(btn.id)
+
+      if (current !== next) {
+        dispatch({ type: action, payload: { id: btn.id, [key]: next } })
+      }
+    } catch (err) {
+      console.warn(`${prop} error for button ${btn.id}:`, err)
+    }
+  })
+}
+
 export function useButtonStateEvaluator (evaluateProp) {
   const appState = useApp()
   const { pluginRegistry } = useConfig()
@@ -13,54 +59,21 @@ export function useButtonStateEvaluator (evaluateProp) {
     if (!appState?.dispatch || !pluginContext) {
       return
     }
-    const { dispatch } = appState
 
-    pluginRegistry.registeredPlugins.forEach((plugin) => {
-      const buttons = plugin?.manifest?.buttons || []
-
-      buttons.forEach((btn) => {
-        const pluginId = plugin.id
-
-        // EnableWhen
-        if (typeof btn.enableWhen === 'function') {
-          try {
-            const shouldBeEnabled = evaluateProp(btn.enableWhen, pluginId)
-            const currentlyDisabled = appState.disabledButtons.has(btn.id)
-            const isDisabled = !shouldBeEnabled
-            if (currentlyDisabled !== isDisabled) {
-              dispatch({ type: 'TOGGLE_BUTTON_DISABLED', payload: { id: btn.id, isDisabled } })
-            }
-          } catch (err) {
-            console.warn(`enableWhen error for button ${btn.id}:`, err)
-          }
-        }
+    const { dispatch } = appState
 
-        // HiddenWhen
-        if (typeof btn.hiddenWhen === 'function') {
-          try {
-            const shouldBeHidden = evaluateProp(btn.hiddenWhen, pluginId)
-            const currentlyHidden = appState.hiddenButtons.has(btn.id)
-            if (currentlyHidden !== shouldBeHidden) {
-              dispatch({ type: 'TOGGLE_BUTTON_HIDDEN', payload: { id: btn.id, isHidden: shouldBeHidden } })
-            }
-          } catch (err) {
-            console.warn(`hiddenWhen error for button ${btn.id}:`, err)
-          }
-        }
+    pluginRegistry.registeredPlugins.forEach(plugin => {
+      const buttons = (plugin?.manifest?.buttons ?? []).flatMap(b => [b, ...(b.menuItems ?? [])])
 
-        // PressedWhen
-        if (typeof btn.pressedWhen === 'function') {
-          try {
-            const shouldBePressed = evaluateProp(btn.pressedWhen, pluginId)
-            const currentlyPressed = appState.pressedButtons.has(btn.id)
-            if (currentlyPressed !== shouldBePressed) {
-              dispatch({ type: 'TOGGLE_BUTTON_PRESSED', payload: { id: btn.id, isPressed: shouldBePressed } })
-            }
-          } catch (err) {
-            console.warn(`pressedWhen error for button ${btn.id}:`, err)
-          }
-        }
-      })
+      buttons.forEach(btn =>
+        evaluateButtonState({
+          btn,
+          pluginId: plugin.id,
+          appState,
+          dispatch,
+          evaluateProp
+        })
+      )
     })
   }, [appState, pluginContext, evaluateProp])
 }

package/src/App/hooks/useButtonStateEvaluator.test.js

@@ -21,6 +21,7 @@ describe('useButtonStateEvaluator', () => {
       disabledButtons: new Set(),
       hiddenButtons: new Set(),
       pressedButtons: new Set(),
+      expandedButtons: new Set(),
       dispatch: mockDispatch
     }
     useApp.mockReturnValue(mockAppState)
@@ -89,15 +90,30 @@ describe('useButtonStateEvaluator', () => {
     })
   })
 
+  it('toggles button expanded state based on expandedWhen', () => {
+    mockPluginRegistry.registeredPlugins = [{
+      id: 'p1',
+      manifest: { buttons: [{ id: 'btn1', expandedWhen: () => true }] }
+    }]
+
+    renderHook(() => useButtonStateEvaluator((fn) => fn()))
+    expect(mockDispatch).toHaveBeenCalledWith({
+      type: 'TOGGLE_BUTTON_EXPANDED',
+      payload: { id: 'btn1', isExpanded: true }
+    })
+  })
+
   it('does not dispatch if state already matches', () => {
     mockAppState.disabledButtons.add('btn1')
     mockAppState.hiddenButtons.add('btn2')
     mockAppState.pressedButtons.add('btn3')
+    mockAppState.expandedButtons.add('btn4')
 
     mockPluginRegistry.registeredPlugins = [
       { id: 'p1', manifest: { buttons: [{ id: 'btn1', enableWhen: () => false }] } },
       { id: 'p2', manifest: { buttons: [{ id: 'btn2', hiddenWhen: () => true }] } },
-      { id: 'p3', manifest: { buttons: [{ id: 'btn3', pressedWhen: () => true }] } }
+      { id: 'p3', manifest: { buttons: [{ id: 'btn3', pressedWhen: () => true }] } },
+      { id: 'p4', manifest: { buttons: [{ id: 'btn4', expandedWhen: () => true }] } }
     ]
 
     renderHook(() => useButtonStateEvaluator((fn) => fn()))
@@ -112,13 +128,14 @@ describe('useButtonStateEvaluator', () => {
         buttons: [
           { id: 'btn1', enableWhen: failingFn },
           { id: 'btn2', hiddenWhen: failingFn },
-          { id: 'btn3', pressedWhen: failingFn }
+          { id: 'btn3', pressedWhen: failingFn },
+          { id: 'btn4', expandedWhen: failingFn }
         ]
       }
     }]
 
     renderHook(() => useButtonStateEvaluator((fn, pluginId) => fn(pluginId)))
-    expect(console.warn).toHaveBeenCalledTimes(3)
+    expect(console.warn).toHaveBeenCalledTimes(4)
     expect(mockDispatch).not.toHaveBeenCalled()
   })
 
@@ -130,4 +147,20 @@ describe('useButtonStateEvaluator', () => {
     renderHook(() => useButtonStateEvaluator((fn) => fn({ pluginState: {} })))
     expect(enableWhen).toHaveBeenCalled()
   })
+
+  it('covers fallback to empty array when manifest or buttons is missing', () => {
+    // Branch 1: Plugin exists but manifest is missing
+    // Branch 2: Manifest exists but buttons is missing
+    mockPluginRegistry.registeredPlugins = [
+      { id: 'p1' },
+      { id: 'p2', manifest: {} },
+      { id: 'p3', manifest: { buttons: null } }
+    ]
+
+    renderHook(() => useButtonStateEvaluator((fn) => fn()))
+
+    // If the fallback (|| []) works, the code continues to the next plugin
+    // without throwing a "cannot read property forEach of undefined" error.
+    expect(mockDispatch).not.toHaveBeenCalled()
+  })
 })

package/src/App/hooks/useCrossHairAPI.js

@@ -6,6 +6,53 @@ import { useService } from '../store/serviceContext.js'
 import { scaleFactor } from '../../config/appConfig.js'
 import { EVENTS as events } from '../../config/events.js'
 
+const assignCrossHairAPI = (crossHair, el, mapProvider, dispatch, updatePosition) => {
+  crossHair.pinToMap = (coords, state) => {
+    const { x, y } = mapProvider.mapToScreen(coords)
+    crossHair.coords = coords
+    dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isPinnedToMap: true, isVisible: true, coords, state } })
+    updatePosition(el, x, y)
+  }
+
+  crossHair.fixAtCenter = () => {
+    el.style.left = '50%'
+    el.style.top = '50%'
+    el.style.transform = 'translate(0,0)'
+    el.style.display = 'block'
+    dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isPinnedToMap: false, isVisible: true } })
+  }
+
+  crossHair.remove = () => {
+    el.style.display = 'none'
+    dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isPinnedToMap: false, isVisible: false } })
+  }
+
+  crossHair.show = () => {
+    el.style.display = 'block'
+    dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: true } })
+  }
+
+  crossHair.hide = () => {
+    el.style.display = 'none'
+    dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: false } })
+  }
+
+  crossHair.setStyle = (state) => {
+    dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { state } })
+  }
+
+  crossHair.getDetail = () => {
+    const coords = crossHair.isPinnedToMap ? crossHair.coords : mapProvider.getCenter()
+
+    return {
+      state: crossHair.state,
+      point: mapProvider.mapToScreen(coords),
+      zoom: mapProvider.getZoom(),
+      coords
+    }
+  }
+}
+
 export const useCrossHair = () => {
   const { mapProvider } = useConfig()
   const { safeZoneInset } = useApp()
@@ -25,55 +72,10 @@ export const useCrossHair = () => {
 
   const crossHairRef = useCallback(el => {
     if (!el) {
-      return
-    }
-
-    // --- API ---
-
-    crossHair.pinToMap = (coords, state) => {
-      const { x, y } = mapProvider.mapToScreen(coords)
-      crossHair.coords = coords
-      dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isPinnedToMap: true, isVisible: true, coords, state } })
-      updatePosition(el, x, y)
-    }
-
-    crossHair.fixAtCenter = () => {
-      el.style.left = '50%'
-      el.style.top = '50%'
-      el.style.transform = 'translate(0,0)'
-      el.style.display = 'block'
-      dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isPinnedToMap: false, isVisible: true } })
-    }
-
-    crossHair.remove = () => {
-      el.style.display = 'none'
-      dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isPinnedToMap: false, isVisible: false } })
+      return undefined
     }
 
-    crossHair.show = () => {
-      el.style.display = 'block'
-      dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: true } })
-    }
-
-    crossHair.hide = () => {
-      el.style.display = 'none'
-      dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: false } })
-    }
-
-    crossHair.setStyle = (state) => {
-      dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { state } })
-    }
-
-    crossHair.getDetail = () => {
-      const coords = crossHair.isPinnedToMap ? crossHair.coords : mapProvider.getCenter()
-
-      return {
-        state: crossHair.state,
-        point: mapProvider.mapToScreen(coords),
-        zoom: mapProvider.getZoom(),
-        coords
-      }
-    }
+    assignCrossHairAPI(crossHair, el, mapProvider, dispatch, updatePosition)
 
     const handleRender = () => {
       if (crossHair.coords && crossHair.isPinnedToMap) {

package/src/App/hooks/useFocusVisible.js

@@ -11,7 +11,7 @@ export function useFocusVisible () {
   useEffect(() => {
     const scope = layoutRefs.appContainerRef.current
     if (!scope) {
-      return
+      return undefined
     }
 
     function handleFocusIn (e) {
@@ -22,7 +22,7 @@ export function useFocusVisible () {
       delete e.target.dataset.focusVisible
     }
 
-    function handlePointerdown (e) {
+    function handlePointerdown () {
       delete document.activeElement.dataset.focusVisible
     }
 

package/src/App/hooks/useInterfaceAPI.js

@@ -5,12 +5,19 @@ import { useApp } from '../store/appContext.js'
 import { useService } from '../store/serviceContext.js'
 
 export const useInterfaceAPI = () => {
-  const { dispatch, hiddenButtons, pressedButtons, disabledButtons } = useApp()
+  const { dispatch, hiddenButtons, disabledButtons, pressedButtons, expandedButtons } = useApp()
   const { eventBus } = useService()
 
   useEffect(() => {
     const handleAddButton = ({ id, config }) => {
+      // Add the button
       dispatch({ type: 'ADD_BUTTON', payload: { id, config } })
+      // Add all optional menu items as individual buttons
+      if (Array.isArray(config.menuItems)) {
+        config.menuItems.forEach(item => {
+          dispatch({ type: 'ADD_BUTTON', payload: { id: item.id, config: item } })
+        })
+      }
     }
 
     const handleToggleButtonState = ({ id, prop, value }) => {
@@ -20,14 +27,19 @@ export const useInterfaceAPI = () => {
           dispatch({ type: 'TOGGLE_BUTTON_HIDDEN', payload: { id, isHidden } })
           break
         }
+        case 'disabled': {
+          const isDisabled = typeof value === 'boolean' ? value : !disabledButtons.has(id)
+          dispatch({ type: 'TOGGLE_BUTTON_DISABLED', payload: { id, isDisabled } })
+          break
+        }
         case 'pressed': {
           const isPressed = typeof value === 'boolean' ? value : !pressedButtons.has(id)
           dispatch({ type: 'TOGGLE_BUTTON_PRESSED', payload: { id, isPressed } })
           break
         }
-        case 'disabled': {
-          const isDisabled = typeof value === 'boolean' ? value : !disabledButtons.has(id)
-          dispatch({ type: 'TOGGLE_BUTTON_DISABLED', payload: { id, isDisabled } })
+        case 'expanded': {
+          const isExpanded = typeof value === 'boolean' ? value : !expandedButtons.has(id)
+          dispatch({ type: 'TOGGLE_BUTTON_EXPANDED', payload: { id, isExpanded } })
           break
         }
         default:

package/src/App/hooks/useKeyboardHint.js

@@ -11,7 +11,7 @@ export function useKeyboardHint ({
 
   useEffect(() => {
     if (!showHint || !containerRef.current) {
-      return
+      return undefined
     }
 
     const containerEl = containerRef.current

package/src/App/hooks/useKeyboardShortcuts.js

@@ -13,7 +13,7 @@ export function useKeyboardShortcuts (containerRef) {
   useEffect(() => {
     const el = containerRef.current
     if (!el || interfaceType !== 'keyboard') {
-      return
+      return undefined
     }
 
     const actions = createKeyboardActions(mapProvider, announce, {
@@ -31,7 +31,7 @@ export function useKeyboardShortcuts (containerRef) {
 
       // Use e.code for letters to avoid 'dead' keys with Alt/AltGr
       if (/^Key[A-Z]$/.test(e.code)) {
-        key = e.code.slice(3) // "KeyI" -> "I"
+        key = e.code.slice(3) // NOSONAR: strip "Key" prefix, e.g. "KeyI" -> "I"
       } else {
         key = e.key // works for arrows, numpad, punctuation
       }
@@ -41,6 +41,8 @@ export function useKeyboardShortcuts (containerRef) {
         key = '+'
       } else if (key === 'Subtract' || key === 'NumpadSubtract') {
         key = '-'
+      } else {
+        // No action
       }
 
       return e.altKey ? `Alt+${key}` : key

package/src/App/hooks/useMapAnnouncements.js

@@ -5,6 +5,39 @@ import { useService } from '../store/serviceContext.js'
 import { getMapStatusMessage } from '../../utils/getMapStatusMessage.js'
 import { EVENTS as events } from '../../config/events.js'
 
+const resolveMessage = (previous, current, mapProvider) => {
+  const zoomChanged = previous.zoom !== current.zoom
+  const centerChanged =
+    previous.center[0] !== current.center[0] ||
+    previous.center[1] !== current.center[1]
+
+  const areaDimensions = mapProvider.getAreaDimensions()
+
+  // Panned only
+  if (centerChanged && !zoomChanged) {
+    const direction = mapProvider.getCardinalMove(previous.center, current.center)
+    return getMapStatusMessage.moved({ direction, areaDimensions })
+  }
+
+  // Zoomed only
+  if (!centerChanged && zoomChanged) {
+    return getMapStatusMessage.zoomed({
+      ...current,
+      from: previous.zoom,
+      to: current.zoom,
+      areaDimensions
+    })
+  }
+
+  // No change
+  if (!centerChanged && !zoomChanged) {
+    return getMapStatusMessage.noChange({ ...current })
+  }
+
+  // Panned and zoomed
+  return getMapStatusMessage.newArea({ ...current, areaDimensions })
+}
+
 export function useMapAnnouncements () {
   const { mapProvider } = useConfig()
   const { eventBus, announce } = useService()
@@ -15,38 +48,7 @@ export function useMapAnnouncements () {
         return
       }
 
-      const zoomChanged = previous.zoom !== current.zoom
-      const centerChanged =
-        previous.center[0] !== current.center[0] ||
-        previous.center[1] !== current.center[1]
-
-      const areaDimensions = mapProvider.getAreaDimensions()
-      let message
-
-      if (centerChanged && !zoomChanged) {
-        const direction = mapProvider.getCardinalMove(previous.center, current.center)
-        message = getMapStatusMessage.moved({
-          direction,
-          areaDimensions
-        })
-      } else if (!centerChanged && zoomChanged) {
-        message = getMapStatusMessage.zoomed({
-          ...current,
-          from: previous.zoom,
-          to: current.zoom,
-          areaDimensions
-        })
-      } else if (!centerChanged && !zoomChanged) {
-        message = getMapStatusMessage.noChange({
-          ...current
-        })
-      } else {
-        message = getMapStatusMessage.newArea({
-          ...current,
-          areaDimensions
-        })
-      }
-
+      const message = resolveMessage(previous, current, mapProvider)
       if (message) {
         announce(message, 'core')
       }

package/src/App/hooks/useMapEvents.js

@@ -2,13 +2,24 @@ import { useEffect } from 'react'
 import { useConfig } from '../store/configContext.js'
 import { useService } from '../store/serviceContext.js'
 
+/**
+ * Subscribes to map events via the shared event bus for the lifetime of
+ * the consuming component. Handlers are automatically unsubscribed on
+ * unmount or when the eventMap reference changes.
+ *
+ * Supported events include clicks, pans, zooms, style changes and more
+ * — see `EVENTS` in `config/events.js` for the full list.
+ *
+ * @param {Object<string, Function>} [eventMap={}] - A map of event names to
+ *   callback functions.
+ */
 export function useMapEvents (eventMap = {}) {
   const { mapProvider } = useConfig()
   const { eventBus } = useService()
 
   useEffect(() => {
     if (!mapProvider) {
-      return
+      return undefined
     }
 
     const handlers = {}

package/src/App/hooks/useMapProviderOverrides.js

@@ -32,14 +32,14 @@ export const useMapProviderOverrides = () => {
 
   useEffect(() => {
     if (!mapProvider) {
-      return
+      return undefined
     }
 
     const originalFitToBounds = mapProvider.fitToBounds
 
     mapProvider.fitToBounds = (bounds, skipPaddingCalc = false) => {
       if (!bounds) {
-        return
+        return undefined
       }
 
       // Calculate and set safe zone padding unless explicitly skipped
@@ -54,7 +54,7 @@ export const useMapProviderOverrides = () => {
 
     mapProvider.setView = ({ center, zoom }) => {
       if (!center) {
-        return
+        return undefined
       }
 
       updatePadding()

package/src/App/hooks/useMapStateSync.js

@@ -4,6 +4,12 @@ import { useMap } from '../store/mapContext.js'
 import { useService } from '../store/serviceContext.js'
 import { EVENTS as events } from '../../config/events.js'
 
+/**
+ * Keeps React state in sync with the map provider by listening to move,
+ * move-end and first-idle events. On each move-end it also emits a
+ * MAP_STATE_UPDATED event carrying both the previous and current state,
+ * which other hooks (e.g. useMapAnnouncements) use to determine what changed.
+ */
 export function useMapStateSync () {
   const { mapProvider } = useConfig()
   const { dispatch } = useMap()
@@ -14,7 +20,7 @@ export function useMapStateSync () {
 
   useEffect(() => {
     if (!mapProvider) {
-      return
+      return undefined
     }
 
     // Handle map move

package/src/App/hooks/useMapURLSync.js

@@ -4,13 +4,18 @@ import { useConfig } from '../store/configContext.js'
 import { useService } from '../store/serviceContext.js'
 import { EVENTS as events } from '../../config/events.js'
 
+/**
+ * Persists the current map center and zoom into the page URL whenever the
+ * map state changes, allowing the view to be restored on page reload or
+ * shared via a link.
+ */
 export function useMapURLSync () {
   const { id } = useConfig()
   const { eventBus } = useService()
 
   useEffect(() => {
     if (!id) {
-      return
+      return undefined
     }
 
     const handleStateUpdate = ({ current }) => {