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

package/src/App/hooks/useMarkersAPI.js

@@ -5,22 +5,101 @@ import { useService } from '../store/serviceContext.js'
 import { scaleFactor } from '../../config/appConfig.js'
 import { EVENTS as events } from '../../config/events.js'
 
-// Pure function - easier to test
+// Vertical offset to align the marker tip with the coordinate point
+const MARKER_ANCHOR_OFFSET_Y = 19
+
+/**
+ * Projects geographic coordinates to screen pixel position, scaled for the
+ * current map size and offset so the marker tip aligns with the point.
+ *
+ * @param {Array<number>} coords - [lng, lat] geographic coordinates
+ * @param {Object} mapProvider - Map provider instance with `mapToScreen` method
+ * @param {string} mapSize - Current map size key (e.g. 'small', 'medium', 'large')
+ * @param {boolean} isMapReady - Whether the map has finished initialising
+ * @returns {{ x: number, y: number }} Screen position in pixels
+ */
 export const projectCoords = (coords, mapProvider, mapSize, isMapReady) => {
   if (!mapProvider || !isMapReady) {
     return { x: 0, y: 0 }
   }
   const { x, y } = mapProvider.mapToScreen(coords)
-  return { x: x * scaleFactor[mapSize], y: y * scaleFactor[mapSize] - 19 }
+  return {
+    x: x * scaleFactor[mapSize],
+    y: y * scaleFactor[mapSize] - MARKER_ANCHOR_OFFSET_Y
+  }
+}
+
+/**
+ * Reprojects and repositions all marker DOM elements to their current screen
+ * coordinates. Called on map render and resize events.
+ *
+ * @param {Array<Object>} items - Marker state items from the store
+ * @param {Map<string, HTMLElement>} markerRefs - Map of marker id to DOM element
+ * @param {Object} mapProvider - Map provider instance
+ * @param {string} mapSize - Current map size key
+ * @param {boolean} isMapReady - Whether the map has finished initialising
+ */
+const updateMarkerPositions = (items, markerRefs, mapProvider, mapSize, isMapReady) => {
+  items.forEach(marker => {
+    const ref = markerRefs.get(marker.id)
+    if (!ref || !marker.coords) {
+      return
+    }
+
+    const { x, y } = projectCoords(marker.coords, mapProvider, mapSize, isMapReady)
+    ref.style.transform = `translate(${x}px, ${y}px)`
+    ref.style.display = 'block'
+  })
+}
+
+/**
+ * Registers event bus listeners for adding and removing markers via
+ * APP_ADD_MARKER and APP_REMOVE_MARKER events.
+ *
+ * @param {Object} eventBus - Application event bus
+ * @param {Object} markers - Markers API object with `add` and `remove` methods
+ */
+const useMarkerEventListeners = (eventBus, markers) => {
+  useEffect(() => {
+    const handleAddMarker = (payload = {}) => {
+      if (!payload?.id || !payload?.coords) {
+        return
+      }
+      const { id, coords, options } = payload
+      markers.add(id, coords, options)
+    }
+    eventBus.on(events.APP_ADD_MARKER, handleAddMarker)
+
+    const handleRemoveMarker = (id) => {
+      if (!id) {
+        return
+      }
+      markers.remove(id)
+    }
+    eventBus.on(events.APP_REMOVE_MARKER, handleRemoveMarker)
+
+    return () => {
+      eventBus.off(events.APP_ADD_MARKER, handleAddMarker)
+      eventBus.off(events.APP_REMOVE_MARKER, handleRemoveMarker)
+    }
+  }, [])
 }
 
+/**
+ * Hook that provides the markers API and ref callback for positioning marker
+ * elements on the map. Attaches `add`, `remove`, and `getMarker` methods to the
+ * markers store object and keeps marker positions in sync with map render and
+ * resize events.
+ *
+ * @returns {{ markers: Object, markerRef: Function }}
+ */
 export const useMarkers = () => {
   const { mapProvider } = useConfig()
   const { eventBus } = useService()
   const { markers, dispatch, mapSize, isMapReady } = useMap()
   const markerRefs = useRef(new Map())
 
-  // --- API: Attach methods to markers object ---
+  // Attach add, remove, and getMarker methods to the markers store object
   useEffect(() => {
     if (!mapProvider) {
       return
@@ -42,11 +121,11 @@ export const useMarkers = () => {
     }
   }, [mapProvider, markers, dispatch, mapSize])
 
-  // Update marker position on events.MAP_RENDER
+  // Ref callback: stores marker DOM refs and subscribes to MAP_RENDER for repositioning
   const markerRef = useCallback((id) => (el) => {
     if (!el) {
       markerRefs.current.delete(id)
-      return
+      return undefined
     }
     markerRefs.current.set(id, el)
 
@@ -54,17 +133,7 @@ export const useMarkers = () => {
       if (!isMapReady || !mapProvider) {
         return
       }
-
-      markers.items.forEach(marker => {
-        const ref = markerRefs.current.get(marker.id)
-        if (!ref || !marker.coords) {
-          return
-        }
-
-        const { x, y } = projectCoords(marker.coords, mapProvider, mapSize, isMapReady)
-        ref.style.transform = `translate(${x}px, ${y}px)`
-        ref.style.display = 'block'
-      })
+      updateMarkerPositions(markers.items, markerRefs.current, mapProvider, mapSize, isMapReady)
     }
     eventBus.on(events.MAP_RENDER, updateMarkers)
 
@@ -73,47 +142,16 @@ export const useMarkers = () => {
     }
   }, [markers, mapProvider, isMapReady, mapSize])
 
-  // Update all markers on map resize
+  // Reproject all markers when the map size changes
   useEffect(() => {
     if (!isMapReady || !mapProvider) {
       return
     }
 
-    markers.items.forEach(marker => {
-      const ref = markerRefs.current.get(marker.id)
-      if (!ref || !marker.coords) {
-        return
-      }
-
-      const { x, y } = projectCoords(marker.coords, mapProvider, mapSize, isMapReady)
-      ref.style.transform = `translate(${x}px, ${y}px)`
-    })
+    updateMarkerPositions(markers.items, markerRefs.current, mapProvider, mapSize, isMapReady)
   }, [mapSize, markers.items, mapProvider, isMapReady])
 
-  // Respond to external API calls via eventBus
-  useEffect(() => {
-    const handleAddMarker = (payload = {}) => {
-      if (!payload || !payload.id || !payload.coords) {
-        return
-      }
-      const { id, coords, options } = payload
-      markers.add(id, coords, options)
-    }
-    eventBus.on(events.APP_ADD_MARKER, handleAddMarker)
-
-    const handleRemoveMarker = (id) => {
-      if (!id) {
-        return
-      }
-      markers.remove(id)
-    }
-    eventBus.on(events.APP_REMOVE_MARKER, handleRemoveMarker)
-
-    return () => {
-      eventBus.off(events.APP_ADD_MARKER, handleAddMarker)
-      eventBus.off(events.APP_REMOVE_MARKER, handleRemoveMarker)
-    }
-  }, [])
+  useMarkerEventListeners(eventBus, markers)
 
   return { markers, markerRef }
 }

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

@@ -115,4 +115,52 @@ describe('useMediaQueryDispatch', () => {
       payload: { preferredColorScheme: 'light', prefersReducedMotion: true }
     })
   })
+
+  it('sets up hybrid media query and dispatches on change', () => {
+    const options = {
+      behaviour: 'hybrid',
+      hybridWidth: 500,
+      maxMobileWidth: 768,
+      appColorScheme: 'light',
+      autoColorScheme: true
+    }
+
+    renderHook(() => useMediaQueryDispatch(dispatch, options))
+
+    // Verify matchMedia was called with the hybrid threshold
+    expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 500px)')
+
+    // Verify addEventListener was called for the 2 standard queries + 1 hybrid query
+    expect(mockMediaQuery.addEventListener).toHaveBeenCalledTimes(3)
+
+    // Find the hybrid change handler (the last one registered)
+    const hybridHandler = mockMediaQuery.addEventListener.mock.calls[2][1]
+
+    // Simulate a media query match event
+    act(() => {
+      hybridHandler({ matches: true })
+    })
+
+    expect(dispatch).toHaveBeenCalledWith({
+      type: 'SET_HYBRID_FULLSCREEN',
+      payload: true
+    })
+  })
+
+  it('falls back to maxMobileWidth for hybrid threshold when hybridWidth is missing', () => {
+    const options = {
+      behaviour: 'hybrid',
+      // hybridWidth is undefined here
+      maxMobileWidth: 800,
+      appColorScheme: 'light',
+      autoColorScheme: true
+    }
+
+    renderHook(() => useMediaQueryDispatch(dispatch, options))
+
+    // This covers the right side of the ?? operator
+    expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 800px)')
+
+    expect(mockMediaQuery.addEventListener).toHaveBeenCalledTimes(3)
+  })
 })

package/src/App/hooks/useModalPanelBehaviour.js

@@ -3,18 +3,10 @@ import { useResizeObserver } from './useResizeObserver.js'
 import { constrainKeyboardFocus } from '../../utils/constrainKeyboardFocus.js'
 import { toggleInertElements } from '../../utils/toggleInertElements.js'
 
-export function useModalPanelBehaviour ({
-  mainRef,
-  panelRef,
-  isModal,
-  rootEl,
-  buttonContainerEl,
-  handleClose
-}) {
-  // === Escape and Tab key handling === //
+const useModalKeyHandler = (panelRef, isModal, handleClose) => {
   useEffect(() => {
     if (!isModal) {
-      return
+      return undefined
     }
 
     const handleKeyDown = (e) => {
@@ -36,6 +28,47 @@ export function useModalPanelBehaviour ({
       current?.removeEventListener('keydown', handleKeyDown)
     }
   }, [isModal, panelRef, handleClose])
+}
+
+const useFocusRedirect = (isModal, panelRef, rootEl) => {
+  useEffect(() => {
+    if (!isModal) {
+      return undefined
+    }
+
+    const handleFocusIn = (e) => {
+      const focusedEl = e.target
+      const panelEl = panelRef.current
+
+      if (!focusedEl || !panelEl || !rootEl) {
+        return
+      }
+
+      const isInsideApp = rootEl.contains(focusedEl)
+      const isInsidePanel = panelEl.contains(focusedEl)
+
+      if (isInsideApp && !isInsidePanel) {
+        panelEl.focus()
+      }
+    }
+
+    document.addEventListener('focusin', handleFocusIn)
+
+    return () => {
+      document.removeEventListener('focusin', handleFocusIn)
+    }
+  }, [isModal, panelRef, rootEl])
+}
+
+export function useModalPanelBehaviour ({
+  mainRef,
+  panelRef,
+  isModal,
+  rootEl,
+  buttonContainerEl,
+  handleClose
+}) {
+  useModalKeyHandler(panelRef, isModal, handleClose)
 
   // === Set absolute offset positions and recalculate on mainRef resize === //
   const root = document.documentElement
@@ -55,7 +88,7 @@ export function useModalPanelBehaviour ({
   // === Click on modal backdrop to close === //
   useEffect(() => {
     if (!isModal) {
-      return
+      return undefined
     }
 
     const handleClick = (e) => {
@@ -74,7 +107,7 @@ export function useModalPanelBehaviour ({
   // === Inert everything outside the panel but within the app === //
   useEffect(() => {
     if (!isModal || !panelRef.current || !rootEl) {
-      return
+      return undefined
     }
 
     toggleInertElements({
@@ -92,32 +125,5 @@ export function useModalPanelBehaviour ({
     }
   }, [isModal, panelRef, rootEl])
 
-  // === Redirect focus into the panel if it enters the app === //
-  useEffect(() => {
-    if (!isModal) {
-      return
-    }
-
-    const handleFocusIn = (e) => {
-      const focusedEl = e.target
-      const panelEl = panelRef.current
-
-      if (!focusedEl || !panelEl || !rootEl) {
-        return
-      }
-
-      const isInsideApp = rootEl.contains(focusedEl)
-      const isInsidePanel = panelEl.contains(focusedEl)
-
-      if (isInsideApp && !isInsidePanel) {
-        panelEl.focus()
-      }
-    }
-
-    document.addEventListener('focusin', handleFocusIn)
-
-    return () => {
-      document.removeEventListener('focusin', handleFocusIn)
-    }
-  }, [isModal, panelRef, rootEl])
+  useFocusRedirect(isModal, panelRef, rootEl)
 }

package/src/App/hooks/useResizeObserver.js

@@ -9,10 +9,10 @@ export function useResizeObserver (targetRefs, callback) {
     const elements = refs.map(r => r?.current).filter(Boolean)
 
     if (!elements.length || !callback) {
-      return
+      return undefined
     }
 
-    const observer = new ResizeObserver(entries => {
+    const observer = new window.ResizeObserver(entries => {
       for (const entry of entries) {
         const { width, height } = entry.contentRect
         const prev = prevSizes.current.get(entry.target) || {}

package/src/App/initialiseApp.js

@@ -1,6 +1,6 @@
 import { createRoot } from 'react-dom/client'
 import { EVENTS as events } from '../config/events.js'
-import { appConfig } from '../config/appConfig.js'
+import { defaultAppConfig } from '../config/appConfig.js'
 import { createButtonRegistry } from './registry/buttonRegistry.js'
 import { createPanelRegistry } from './registry/panelRegistry.js'
 import { createControlRegistry } from './registry/controlRegistry.js'
@@ -13,6 +13,47 @@ const rootMap = new WeakMap()
 const mapProviderMap = new WeakMap()
 const registryMap = new WeakMap()
 
+const getOrCreateRegistries = (rootElement) => {
+  let registries = registryMap.get(rootElement)
+  if (!registries) {
+    const buttonRegistry = createButtonRegistry()
+    const panelRegistry = createPanelRegistry()
+    const controlRegistry = createControlRegistry()
+    const pluginRegistry = createPluginRegistry({
+      registerButton: buttonRegistry.registerButton,
+      registerPanel: panelRegistry.registerPanel,
+      registerControl: controlRegistry.registerControl
+    })
+
+    registries = { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry }
+    registryMap.set(rootElement, registries)
+  }
+  return registries
+}
+
+const loadPlugins = async (plugins, registerPlugin) => {
+  for (const plugin of plugins) {
+    if (typeof plugin.load === 'function') {
+      const module = await plugin.load()
+      const { id: pluginId, load, manifest: overrideManifest, ...config } = plugin
+      const { InitComponent, api, reducer, ...baseManifest } = module
+
+      // Merge runtime overrides with module manifest
+      const manifest = mergeManifests(baseManifest, overrideManifest)
+
+      registerPlugin({
+        id: pluginId,
+        InitComponent,
+        api,
+        reducer,
+        config,
+        manifest,
+        _originalPlugin: plugin
+      })
+    }
+  }
+}
+
 export async function initialiseApp (rootElement, {
   MapProvider: MapProviderClass,
   mapProviderConfig,
@@ -35,22 +76,7 @@ export async function initialiseApp (rootElement, {
   }
 
   // Reuse or create registries (persist across app open/close cycles)
-  let registries = registryMap.get(rootElement)
-  if (!registries) {
-    const buttonRegistry = createButtonRegistry()
-    const panelRegistry = createPanelRegistry()
-    const controlRegistry = createControlRegistry()
-    const pluginRegistry = createPluginRegistry({
-      registerButton: buttonRegistry.registerButton,
-      registerPanel: panelRegistry.registerPanel,
-      registerControl: controlRegistry.registerControl
-    })
-
-    registries = { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry }
-    registryMap.set(rootElement, registries)
-  }
-
-  const { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry } = registries
+  const { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry } = getOrCreateRegistries(rootElement)
   const { registerPlugin } = pluginRegistry
 
   // Clear previous plugins (but keep runtime additions)
@@ -59,7 +85,7 @@ export async function initialiseApp (rootElement, {
   // Register default appConfig as a plugin
   registerPlugin({
     id: 'appConfig',
-    manifest: appConfig
+    manifest: defaultAppConfig
   })
 
   // Create root if not already present
@@ -87,26 +113,7 @@ export async function initialiseApp (rootElement, {
   }
 
   // Load plugins
-  for (const plugin of plugins) {
-    if (typeof plugin.load === 'function') {
-      const module = await plugin.load()
-      const { id: pluginId, load, manifest: overrideManifest, ...config } = plugin
-      const { InitComponent, api, reducer, ...baseManifest } = module
-
-      // Merge runtime overrides with module manifest
-      const manifest = mergeManifests(baseManifest, overrideManifest)
-
-      registerPlugin({
-        id: pluginId,
-        InitComponent,
-        api,
-        reducer,
-        config,
-        manifest,
-        _originalPlugin: plugin
-      })
-    }
-  }
+  await loadPlugins(plugins, registerPlugin)
 
   root.render(<App
     {...restProps}

package/src/App/layout/Layout.jsx

@@ -9,6 +9,7 @@ import { Logo } from '../components/Logo/Logo'
 import { Attributions } from '../components/Attributions/Attributions'
 import { layoutSlots } from '../renderer/slots'
 import { SlotRenderer } from '../renderer/SlotRenderer'
+import { HtmlElementHost } from '../renderer/HtmlElementHost'
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
@@ -36,7 +37,7 @@ export const Layout = () => {
       ref={layoutRefs.appContainerRef}
     >
       <Viewport keyboardHintPortalRef={layoutRefs.topRef} />
-      <div className={`im-o-app__overlay${!isLayoutReady ? ' im-o-app__overlay--not-ready' : ''}`}>
+      <div className={`im-o-app__overlay${isLayoutReady ? '' : ' im-o-app__overlay--not-ready'}`}>
         <div className='im-o-app__side' ref={layoutRefs.sideRef}>
           <SlotRenderer slot={layoutSlots.SIDE} />
         </div>
@@ -73,7 +74,7 @@ export const Layout = () => {
               <SlotRenderer slot={layoutSlots.RIGHT_BOTTOM} />
             </div>
           </div>
-          <div className='im-o-app__middle'>
+          <div className='im-o-app__middle' ref={layoutRefs.middleRef}>
             <SlotRenderer slot={layoutSlots.MIDDLE} />
           </div>
           <div className='im-o-app__footer' ref={layoutRefs.footerRef}>
@@ -87,7 +88,7 @@ export const Layout = () => {
               </div>
             </div>
           </div>
-          <div className='im-o-app__bottom'>
+          <div className='im-o-app__bottom' ref={layoutRefs.bottomRef}>
             <SlotRenderer slot={layoutSlots.BOTTOM} />
           </div>
           <div className='im-o-app__actions' ref={layoutRefs.actionsRef}>
@@ -95,7 +96,8 @@ export const Layout = () => {
           </div>
         </div>
       </div>
-      <div className='im-o-app__modal'>
+      <HtmlElementHost />
+      <div className='im-o-app__modal' ref={layoutRefs.modalRef}>
         <SlotRenderer slot={layoutSlots.MODAL} />
         <div className='im-o-app__modal-backdrop' />
       </div>

package/src/App/layout/layout.module.scss

@@ -268,7 +268,10 @@
   // Panel overrides
   .im-c-panel {
     position: absolute;
-    inset: 0 0 auto;
+    top: 0;
+    right: 0;
+    bottom: auto;
+    left: 0;
     z-index: 1000;
   }
 
@@ -318,15 +321,22 @@
   }
 
   [class*="im-c-panel--"][class*="-button"] { // Adjacent to button
-    inset: var(--modal-inset);
+    top: var(--modal-inset);
+    right: var(--modal-inset);
+    bottom: var(--modal-inset);
+    left: var(--modal-inset);
   }
 }
 
-// Mobile and tablet modal banner margin
+// Mobile and tablet
 .im-o-app--mobile, .im-o-app--tablet {
   .im-o-app__modal .im-c-panel--banner {
     margin: var(--primary-gap);
   }
+
+  .im-o-app__banner {
+    z-index: 9;
+  }
 }
 
 // Desktop modal banner margin
@@ -347,7 +357,6 @@
   .im-o-app__right,
   .im-o-app__right-bottom {
     opacity: 0;
-    // visibility: hidden; Breaks focus order in Preact
   }
 }
 
@@ -357,13 +366,6 @@
   opacity: 0;
 }
 
-// Banner on mobile and tablet
-.im-o-app--mobile, .im-o-app--tablet {
-  .im-o-app__banner {
-    z-index: 9;
-  }
-}
-
 // Banner on desktop
 .im-o-app--desktop .im-c-panel--banner {
   margin-left: auto;
@@ -404,12 +406,6 @@
     clip-path: inset(-20px 0 0 0);
 }
 
-// Bottom inset on large devices
-// .im-o-app--tablet .im-o-app__bottom,
-// .im-o-app--desktop .im-o-app__bottom {
-//   margin-top: var(--primary-gap);
-// }
-
 // 4. State styles
 
 // 5. Responsive tweaks

package/src/App/registry/keyboardShortcutRegistry.js

@@ -21,8 +21,18 @@ export const setProviderSupportedShortcuts = (ids = []) => {
   providerSupportedIds = new Set(ids)
 }
 
-export const getKeyboardShortcuts = () => {
-  const filteredCore = coreShortcuts.filter(s => providerSupportedIds.has(s.id))
+export const getKeyboardShortcuts = (appConfig = {}) => {
+  const filteredCore = coreShortcuts.filter(s => {
+    // Must be supported by provider
+    if (!providerSupportedIds.has(s.id)) {
+      return false
+    }
+    // Check requiredConfig - all specified config values must be truthy
+    if (s.requiredConfig) {
+      return s.requiredConfig.every(key => appConfig[key])
+    }
+    return true
+  })
 
   return [
     ...filteredCore, // supported core shortcuts

package/src/App/registry/keyboardShortcutRegistry.test.js

@@ -70,4 +70,32 @@ describe('keyboardShortcutRegistry', () => {
     const shortcuts = getKeyboardShortcuts()
     expect(shortcuts).toEqual([])
   })
+
+  test('getKeyboardShortcuts filters by requiredConfig when appConfig provided', () => {
+    jest.resetModules()
+    jest.doMock('../controls/keyboardShortcuts.js', () => ({
+      coreShortcuts: [
+        { id: 'always', description: 'Always shown' },
+        { id: 'conditional', description: 'Conditional', requiredConfig: ['featureEnabled'] }
+      ]
+    }))
+    const module = require('./keyboardShortcutRegistry.js')
+    module.setProviderSupportedShortcuts(['always', 'conditional'])
+
+    // Without config, conditional shortcut is excluded
+    expect(module.getKeyboardShortcuts()).toEqual([
+      { id: 'always', description: 'Always shown' }
+    ])
+
+    // With config false, conditional shortcut is excluded
+    expect(module.getKeyboardShortcuts({ featureEnabled: false })).toEqual([
+      { id: 'always', description: 'Always shown' }
+    ])
+
+    // With config true, conditional shortcut is included
+    expect(module.getKeyboardShortcuts({ featureEnabled: true })).toEqual([
+      { id: 'always', description: 'Always shown' },
+      { id: 'conditional', description: 'Conditional', requiredConfig: ['featureEnabled'] }
+    ])
+  })
 })

package/src/App/registry/mergeManifests.js

@@ -8,7 +8,7 @@ export function mergeManifests (base = {}, override = {}) {
     }
     const map = new Map(baseArr.map(item => [item.id, item]))
     overrideArr.forEach(item => {
-      if (!item || !item.id) {
+      if (!item?.id) {
         return
       }
       if (map.has(item.id)) {

package/src/App/registry/panelRegistry.js

@@ -30,7 +30,7 @@ export const addPanel = (currentConfig, id, config) => {
 }
 
 export const removePanel = (currentConfig, id) => {
-  const { [id]: _, ...rest } = currentConfig
+  const { [id]: _, ...rest } = currentConfig // NOSONAR - _ is required to destructure out the key
   return rest
 }