@defra/interactive-map 0.0.15-alpha → 0.0.17-alpha

package/src/App/components/PopupMenu/usePopupMenu.js

@@ -0,0 +1,258 @@
+import { useState, useMemo, useEffect } from 'react'
+import { stringToKebab } from '../../../utils/stringToKebab.js'
+
+/**
+ * Computes the position and alignment style for the popup menu based on the
+ * triggering button's bounding rect. Positions above/below and left/center/right
+ * depending on which third of the screen the button centre falls in.
+ *
+ * @param {DOMRect|null} buttonRect - Bounding rect of the trigger button, or null.
+ * @returns {{ style: object, direction: string, halign: string }}
+ */
+const getMenuStyle = (buttonRect) => {
+  if (!buttonRect) {
+    return { style: {}, direction: 'below' }
+  }
+  const style = {}
+  let direction
+  if (buttonRect.top >= window.innerHeight / 2) {
+    style.bottom = `${window.innerHeight - buttonRect.top}px`
+    direction = 'above'
+  } else {
+    style.top = `${buttonRect.bottom}px`
+    direction = 'below'
+  }
+  const buttonCenterX = (buttonRect.left + buttonRect.right) / 2
+  let halign
+  if (buttonCenterX > (window.innerWidth * 2) / 3) { // NOSONAR, third of a page width
+    style.right = `${window.innerWidth - buttonRect.right}px`
+    halign = 'right'
+  } else if (buttonCenterX < window.innerWidth / 3) { // NOSONAR, third of a page width
+    style.left = `${buttonRect.left}px`
+    halign = 'left'
+  } else {
+    style.left = `${buttonCenterX}px`
+    halign = 'center'
+  }
+  return { style, direction, halign }
+}
+
+/**
+ * Invokes an item's action via buttonConfig.onClick (if configured) or item.onClick.
+ * For keyboard-triggered activations also dispatches a synthetic MouseEvent so that
+ * any window-level click listeners (e.g. editVertexMode) fire as expected.
+ * The synthetic event is marked _fromKeyboardActivation so handleItemClick can
+ * ignore it and avoid double-activation.
+ *
+ * @param {React.SyntheticEvent} e   - The triggering React event.
+ * @param {object}               item - The item being activated.
+ * @param {object}               ctx  - Dependencies: { buttonConfig, evaluateProp, pluginId, id }.
+ */
+const activateItem = (e, item, { buttonConfig, evaluateProp, pluginId, id }) => {
+  const menuItemConfig = buttonConfig[item.id]
+  if (typeof menuItemConfig?.onClick === 'function') {
+    menuItemConfig.onClick(e, evaluateProp(ctx => ctx, pluginId))
+  } else if (typeof item.onClick === 'function') {
+    item.onClick(e.nativeEvent)
+  } else {
+    // No action
+  }
+  if (e.nativeEvent instanceof KeyboardEvent) {
+    const el = document.getElementById(`${id}-${stringToKebab(item.id)}`)
+    if (el) {
+      const click = new MouseEvent('click', { bubbles: true, cancelable: true })
+      click._fromKeyboardActivation = true
+      el.dispatchEvent(click)
+    }
+  }
+}
+
+/**
+ * Builds the keydown handler for the menu UL. Handles Escape/Tab (close & focus),
+ * ArrowDown/Up (navigate visible items), Home/End (jump to ends),
+ * Enter (activate and close), Space (activate; close only for non-checkbox items).
+ *
+ * @param {object}   p
+ * @param {Array}    p.items           - All menu item descriptors.
+ * @param {number[]} p.visibleIndices  - Indices of non-hidden items.
+ * @param {number}   p.index           - Currently highlighted index.
+ * @param {Function} p.setIndex        - State setter for highlighted index.
+ * @param {Set}      p.disabledButtons - IDs of disabled items.
+ * @param {object}   p.instigator      - DOM node of the trigger button.
+ * @param {Function} p.setIsOpen       - Callback to close the menu.
+ * @param {object}   p.activateCtx     - Context passed through to activateItem.
+ * @returns {Function} onKeyDown handler for the menu element.
+ */
+const createMenuKeyDownHandler = ({ items, visibleIndices, index, setIndex, disabledButtons, instigator, setIsOpen, activateCtx }) => {
+  const closeAndFocus = (e, preventDefault = false) => {
+    if (preventDefault && e?.preventDefault) {
+      e.preventDefault()
+    }
+    instigator.focus()
+    setIsOpen(false)
+  }
+
+  const navigateVisible = (e) => {
+    e.preventDefault()
+    const n = visibleIndices.length
+    if (n === 0) {
+      return
+    }
+    const pos = visibleIndices.indexOf(index)
+    let nextPos
+    if (e.key === 'ArrowDown') {
+      nextPos = pos === -1 ? 0 : (pos + 1) % n
+    } else if (pos === -1) {
+      nextPos = n - 1
+    } else {
+      nextPos = (pos - 1 + n) % n
+    }
+    setIndex(visibleIndices[nextPos])
+  }
+
+  const handleEnter = (e) => {
+    e.preventDefault()
+    const item = items[index]
+    if (item && !disabledButtons.has(item.id)) {
+      activateItem(e, item, activateCtx)
+    }
+    instigator.focus()
+    setIsOpen(false)
+  }
+
+  const handleSpace = (e) => {
+    e.preventDefault()
+    const item = items[index]
+    if (!item || disabledButtons.has(item.id)) {
+      return
+    }
+    activateItem(e, item, activateCtx)
+    if (!(item.isPressed !== undefined || item.pressedWhen)) {
+      instigator.focus()
+      setIsOpen(false)
+    }
+  }
+
+  return (e) => {
+    if (['Escape', 'Esc'].includes(e.key)) {
+      closeAndFocus(e, true)
+      return
+    }
+    if (e.key === 'Tab') {
+      closeAndFocus(e)
+      return
+    }
+    if (['ArrowDown', 'ArrowUp'].includes(e.key)) {
+      navigateVisible(e)
+      return
+    }
+    if (e.key === 'Home' && visibleIndices.length) {
+      setIndex(visibleIndices[0])
+      return
+    }
+    if (e.key === 'End' && visibleIndices.length) {
+      setIndex(visibleIndices[visibleIndices.length - 1])
+      return
+    }
+    if (e.key === 'Enter') {
+      handleEnter(e)
+    }
+    if (e.key === ' ') {
+      handleSpace(e)
+    }
+  }
+}
+
+/**
+ * Custom hook encapsulating all state and event-handler logic for PopupMenu.
+ *
+ * @param {object}   params
+ * @param {Array}    params.items            - Menu item descriptors.
+ * @param {Set}      params.hiddenButtons    - IDs of items that should not be visible.
+ * @param {number}   [params.startIndex]     - Exact index to select on mount; takes precedence over startPos.
+ * @param {string}   [params.startPos]       - 'first' | 'last' — initial selection strategy.
+ * @param {object}   params.instigator       - DOM node of the button that opened the menu.
+ * @param {string}   params.instigatorKey    - Key used to look up instigator in buttonRefs.
+ * @param {object}   params.buttonRefs       - Ref map of all registered button DOM nodes.
+ * @param {object}   params.buttonConfig     - Config map that may override item onClick handlers.
+ * @param {Set}      params.disabledButtons  - IDs of currently disabled items.
+ * @param {string}   params.pluginId         - Plugin context passed to evaluateProp.
+ * @param {Function} params.evaluateProp     - Context evaluator from useEvaluateProp.
+ * @param {string}   params.id               - App-level ID prefix for DOM element IDs.
+ * @param {object}   params.menuRef          - Ref to the menu UL element.
+ * @param {Function} params.setIsOpen        - Callback to open/close the menu.
+ * @param {DOMRect}  params.buttonRect       - Bounding rect of the trigger button for positioning.
+ * @returns {{ index: number, handleMenuKeyDown: Function, handleItemClick: Function,
+ *             menuStyle: object, menuDirection: string, menuHAlign: string }}
+ */
+export const usePopupMenu = ({
+  items, hiddenButtons, startIndex, startPos, instigator, instigatorKey,
+  buttonRefs, buttonConfig, disabledButtons, pluginId, evaluateProp, id, menuRef, setIsOpen, buttonRect
+}) => {
+  const visibleIndices = useMemo(() => {
+    const visible = []
+    items.forEach((item, idx) => {
+      if (!hiddenButtons.has(item.id)) {
+        visible.push(idx)
+      }
+    })
+    return visible
+  }, [items, hiddenButtons])
+
+  const [index, setIndex] = useState(() => {
+    if (typeof startIndex === 'number') {
+      return startIndex
+    }
+    if (startPos === 'first') {
+      return visibleIndices[0] ?? -1
+    }
+    if (startPos === 'last') {
+      return visibleIndices[visibleIndices.length - 1] ?? -1
+    }
+    return -1
+  })
+
+  const activateCtx = { buttonConfig, evaluateProp, pluginId, id }
+
+  const handleMenuKeyDown = createMenuKeyDownHandler({
+    items, visibleIndices, index, setIndex, disabledButtons, instigator, setIsOpen, activateCtx
+  })
+
+  const handleOutside = (e) => {
+    if (menuRef.current?.contains(e.target) || buttonRefs.current[instigatorKey]?.contains(e.target)) {
+      return
+    }
+    setIsOpen(false)
+  }
+
+  const handleItemClick = (e, item) => {
+    if (e.nativeEvent._fromKeyboardActivation || disabledButtons.has(item.id)) {
+      return
+    }
+    setIsOpen(false)
+    activateItem(e, item, activateCtx)
+  }
+
+  useEffect(() => {
+    menuRef.current?.focus()
+    if (startPos === 'first') {
+      setIndex(visibleIndices[0] ?? -1)
+    } else if (startPos === 'last') {
+      setIndex(visibleIndices[visibleIndices.length - 1] ?? -1)
+    } else {
+      // No action
+    }
+    const handleResize = () => setIsOpen(false)
+    document.addEventListener('focusin', handleOutside)
+    document.addEventListener('pointerdown', handleOutside)
+    window.addEventListener('resize', handleResize)
+    return () => {
+      document.removeEventListener('focusin', handleOutside)
+      document.removeEventListener('pointerdown', handleOutside)
+      window.removeEventListener('resize', handleResize)
+    }
+  }, [])
+
+  const { style: menuStyle, direction: menuDirection, halign: menuHAlign } = getMenuStyle(buttonRect)
+  return { index, handleMenuKeyDown, handleItemClick, menuStyle, menuDirection, menuHAlign }
+}

package/src/App/hooks/useButtonStateEvaluator.js

@@ -1,4 +1,3 @@
-// src/core/hooks/useButtonStateEvaluator.js
 import { useLayoutEffect, useContext } from 'react'
 import { useApp } from '../store/appContext.js'
 import { useConfig } from '../store/configContext.js'
@@ -61,6 +60,12 @@ export function useButtonStateEvaluator (evaluateProp) {
     }
 
     const { dispatch } = appState
+    let dispatchCount = 0
+
+    const trackingDispatch = (action) => {
+      dispatchCount++
+      dispatch(action)
+    }
 
     pluginRegistry.registeredPlugins.forEach(plugin => {
       const buttons = (plugin?.manifest?.buttons ?? []).flatMap(b => [b, ...(b.menuItems ?? [])])
@@ -70,10 +75,15 @@ export function useButtonStateEvaluator (evaluateProp) {
           btn,
           pluginId: plugin.id,
           appState,
-          dispatch,
+          dispatch: trackingDispatch,
           evaluateProp
         })
       )
     })
+
+    if (dispatchCount === 0 && !appState.arePluginsEvaluated) {
+      // No changes and flag not yet set — all button states have settled.
+      dispatch({ type: 'PLUGINS_EVALUATED' })
+    }
   }, [appState, pluginContext, evaluateProp])
 }

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

@@ -22,6 +22,7 @@ describe('useButtonStateEvaluator', () => {
       hiddenButtons: new Set(),
       pressedButtons: new Set(),
       expandedButtons: new Set(),
+      arePluginsEvaluated: true, // stable by default; override in settlement tests
       dispatch: mockDispatch
     }
     useApp.mockReturnValue(mockAppState)
@@ -149,8 +150,6 @@ describe('useButtonStateEvaluator', () => {
   })
 
   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: {} },
@@ -158,9 +157,44 @@ describe('useButtonStateEvaluator', () => {
     ]
 
     renderHook(() => useButtonStateEvaluator((fn) => fn()))
+    expect(mockDispatch).not.toHaveBeenCalled()
+  })
+
+  // --- Plugin evaluation settlement ---
+
+  it('dispatches PLUGINS_EVALUATED when no button states changed and arePluginsEvaluated is false', () => {
+    mockAppState.arePluginsEvaluated = false
+    renderHook(() => useButtonStateEvaluator((fn) => fn()))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'PLUGINS_EVALUATED' })
+  })
 
-    // If the fallback (|| []) works, the code continues to the next plugin
-    // without throwing a "cannot read property forEach of undefined" error.
+  it('does not dispatch PLUGINS_EVALUATED when arePluginsEvaluated is already true', () => {
+    mockAppState.arePluginsEvaluated = true
+    renderHook(() => useButtonStateEvaluator((fn) => fn()))
     expect(mockDispatch).not.toHaveBeenCalled()
   })
+
+  it('does not dispatch CLEAR_PLUGINS_EVALUATED or PLUGINS_EVALUATED when button states change', () => {
+    mockAppState.arePluginsEvaluated = false
+    mockPluginRegistry.registeredPlugins = [{
+      id: 'p1',
+      manifest: { buttons: [{ id: 'btn1', hiddenWhen: () => true }] }
+    }]
+
+    renderHook(() => useButtonStateEvaluator((fn) => fn()))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'TOGGLE_BUTTON_HIDDEN', payload: { id: 'btn1', isHidden: true } })
+    expect(mockDispatch).not.toHaveBeenCalledWith({ type: 'CLEAR_PLUGINS_EVALUATED' })
+    expect(mockDispatch).not.toHaveBeenCalledWith({ type: 'PLUGINS_EVALUATED' })
+  })
+
+  it('does not dispatch CLEAR_PLUGINS_EVALUATED when button states change and already evaluated', () => {
+    mockAppState.arePluginsEvaluated = true
+    mockPluginRegistry.registeredPlugins = [{
+      id: 'p1',
+      manifest: { buttons: [{ id: 'btn1', hiddenWhen: () => true }] }
+    }]
+
+    renderHook(() => useButtonStateEvaluator((fn) => fn()))
+    expect(mockDispatch).not.toHaveBeenCalledWith({ type: 'CLEAR_PLUGINS_EVALUATED' })
+  })
 })

package/src/App/hooks/useInterfaceAPI.js

@@ -54,12 +54,16 @@ export const useInterfaceAPI = () => {
       }
     }
 
+    const handleAppVisible = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: true })
+    const handleAppHidden = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: false })
     const handleAddPanel = ({ id, config }) => dispatchRef.current({ type: 'ADD_PANEL', payload: { id, config } })
     const handleRemovePanel = (id) => dispatchRef.current({ type: 'REMOVE_PANEL', payload: id })
     const handleShowPanel = (id) => dispatchRef.current({ type: 'OPEN_PANEL', payload: { panelId: id } })
     const handleHidePanel = (id) => dispatchRef.current({ type: 'CLOSE_PANEL', payload: id })
     const handleAddControl = ({ id, config }) => dispatchRef.current({ type: 'ADD_CONTROL', payload: { id, config } })
 
+    eventBus.on(events.APP_VISIBLE, handleAppVisible)
+    eventBus.on(events.APP_HIDDEN, handleAppHidden)
     eventBus.on(events.APP_ADD_BUTTON, handleAddButton)
     eventBus.on(events.APP_TOGGLE_BUTTON_STATE, handleToggleButtonState)
     eventBus.on(events.APP_ADD_PANEL, handleAddPanel)
@@ -69,6 +73,8 @@ export const useInterfaceAPI = () => {
     eventBus.on(events.APP_ADD_CONTROL, handleAddControl)
 
     return () => {
+      eventBus.off(events.APP_VISIBLE, handleAppVisible)
+      eventBus.off(events.APP_HIDDEN, handleAppHidden)
       eventBus.off(events.APP_ADD_BUTTON, handleAddButton)
       eventBus.off(events.APP_TOGGLE_BUTTON_STATE, handleToggleButtonState)
       eventBus.off(events.APP_ADD_PANEL, handleAddPanel)

package/src/App/hooks/useLayoutMeasurements.js

@@ -12,8 +12,47 @@ const topColWidth = (left, right) =>
 const subSlotMaxHeight = (columnHeight, siblingButtons, gap) =>
   columnHeight - (siblingButtons ? siblingButtons + gap : 0)
 
+/**
+ * Manages all layout measurements for the map overlay and dispatches the safe
+ * zone inset used by the map to pad `fitBounds` / `setView` operations.
+ *
+ * ## Lifecycle
+ *
+ * The safe zone must only be dispatched once every plugin button's reactive
+ * props (`hiddenWhen`, `enableWhen`, `pressedWhen`, `expandedWhen`) have been
+ * evaluated for the current app/map state. Dispatching too early — before
+ * buttons that affect layout (e.g. the actions bar) have their correct
+ * visibility — produces a stale inset that causes the map to jump when the UI
+ * then settles into its real state.
+ *
+ * ### Trigger events
+ * The following state changes can alter which buttons are visible and therefore
+ * how much space the UI occupies:
+ *   - `breakpoint`   — responsive layout changes (desktop ↔ mobile / tablet)
+ *   - `mapSize`      — map container size variant changes
+ *   - `isMapReady`   — plugins are enabled on `map:ready`, changing button visibility
+ *   - `isFullscreen` — fullscreen entry/exit changes which buttons are visible
+ *   - `appVisible`   — app shown/hidden by parent HTML outside React (hybrid mode)
+ *
+ * When any of these change, `CLEAR_PLUGINS_EVALUATED` is dispatched (Effect 2),
+ * which prevents the safe zone from being re-dispatched until
+ * `useButtonStateEvaluator` has completed a full pass with no button state
+ * changes and sets `PLUGINS_EVALUATED` again.
+ *
+ * ### Safe zone dispatch
+ * Effect 3 fires whenever `arePluginsEvaluated` transitions to `true`, at which
+ * point DOM dimensions are stable and `getSafeZoneInset` can be read reliably.
+ * A `requestAnimationFrame` is used to ensure the browser has committed all
+ * layout changes before measuring.
+ *
+ * ### Resize observer
+ * Effect 4 keeps CSS custom properties up to date whenever any observed element
+ * resizes (e.g. panels opening, banner appearing, actions buttons toggling).
+ * It does not dispatch the safe zone — safe zone dispatch is owned entirely by
+ * Effect 3 to prevent jumps on panel open/close and other non-structural resizes.
+ */
 export function useLayoutMeasurements () {
-  const { dispatch, breakpoint, layoutRefs } = useApp()
+  const { dispatch, breakpoint, layoutRefs, arePluginsEvaluated, appVisible, isFullscreen } = useApp()
   const { mapSize, isMapReady } = useMap()
 
   const {
@@ -23,24 +62,28 @@ export function useLayoutMeasurements () {
     topRef,
     topLeftColRef,
     topRightColRef,
-    footerRef,
-    actionsRef,
     leftTopRef,
     leftBottomRef,
     rightTopRef,
-    rightBottomRef
+    rightBottomRef,
+    bottomRef,
+    bottomRightRef,
+    attributionsRef,
+    drawerRef,
+    actionsRef
   } = layoutRefs
 
-  // -----------------------------
-  // 1. Calculate layout CSS vars (side effect)
-  // -----------------------------
+  // --------------------------------
+  // 1. Calculate layout CSS vars (pure side effect, no dispatch)
+  // --------------------------------
   const calculateLayout = () => {
     const appContainer = appContainerRef.current
     const main = mainRef.current
     const top = topRef.current
     const topLeftCol = topLeftColRef.current
     const topRightCol = topRightColRef.current
-    const bottom = footerRef.current
+    const bottom = bottomRef.current
+    const attributions = attributionsRef.current
 
     if ([main, top, bottom].some(r => !r)) {
       return
@@ -60,10 +103,17 @@ export function useLayoutMeasurements () {
     appContainer.style.setProperty('--left-top-max-height', `${leftColumnHeight}px`)
 
     // === Right container offsets ===
+    // Mirrors the top formula (topRightCol.offsetHeight + top.offsetTop):
+    // bottomRight.offsetHeight is 0 when no buttons so the offset collapses to just
+    // the padding between the bottom of the bottom container and the bottom of main.
+    const bottomRightHeight = bottomRightRef?.current?.offsetHeight ?? 0
+    const bottomContainerPad = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
     const rightOffsetTop = topRightCol.offsetHeight + top.offsetTop
-    const rightColumnHeight = bottom.offsetTop - rightOffsetTop - dividerGap
+    const rightEffectiveBottom = bottom.offsetTop + bottom.offsetHeight - bottomRightHeight
+    const rightColumnHeight = rightEffectiveBottom - rightOffsetTop - dividerGap
+    const rightOffsetBottom = bottomContainerPad + (bottomRightHeight > 0 ? (bottomRightHeight + dividerGap) : attributions.offsetHeight)
     appContainer.style.setProperty('--right-offset-top', `${rightOffsetTop}px`)
-    appContainer.style.setProperty('--right-offset-bottom', `${main.offsetHeight - bottom.offsetTop + dividerGap}px`)
+    appContainer.style.setProperty('--right-offset-bottom', `${rightOffsetBottom}px`)
     appContainer.style.setProperty('--right-top-max-height', `${rightColumnHeight}px`)
 
     // === Sub-slot panel max-heights ===
@@ -74,22 +124,38 @@ export function useLayoutMeasurements () {
   }
 
   // --------------------------------
-  // 2. Run when breakpoint and mapSize change
+  // 2. Clear the evaluated flag when structural inputs change so the safe zone
+  //    is not dispatched until useButtonStateEvaluator has completed a full
+  //    pass with the new app/map state and set PLUGINS_EVALUATED.
   // --------------------------------
   useLayoutEffect(() => {
-    requestAnimationFrame(() => { // Required for Preact
-      calculateLayout()
+    dispatch({ type: 'CLEAR_PLUGINS_EVALUATED' })
+  }, [breakpoint, mapSize, isMapReady, appVisible, isFullscreen])
 
-      // === Set safe zone inset ===
+  // --------------------------------
+  // 3. Once all plugin button props have been evaluated (arePluginsEvaluated),
+  //    recalculate layout and dispatch the safe zone inset.
+  //    RAF required to ensure browser layout is committed before measuring.
+  // --------------------------------
+  useLayoutEffect(() => {
+    if (!arePluginsEvaluated) {
+      return
+    }
+    requestAnimationFrame(() => {
+      calculateLayout()
       const safeZoneInset = getSafeZoneInset(layoutRefs)
-      dispatch({ type: 'SET_SAFE_ZONE_INSET', payload: { safeZoneInset } })
+      if (safeZoneInset) {
+        dispatch({ type: 'SET_SAFE_ZONE_INSET', payload: { safeZoneInset } })
+      }
     })
-  }, [breakpoint, mapSize, isMapReady])
+  }, [arePluginsEvaluated])
 
   // --------------------------------
-  // 3. Recaluclate CSS vars when elements resize
+  // 4. Recalculate CSS vars whenever observed elements resize (panels, banner,
+  //    actions buttons, etc.). Safe zone is intentionally not dispatched here —
+  //    that is Effect 3's responsibility.
   // --------------------------------
-  useResizeObserver([bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, actionsRef, footerRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef], () => {
+  useResizeObserver([bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, actionsRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef], () => {
     requestAnimationFrame(() => {
       calculateLayout()
     })