@defra/interactive-map 0.0.43-fmp-experimental → 0.0.44-alpha

package/src/App/components/Panel/Panel.jsx

@@ -2,31 +2,20 @@ import React, { useRef, useEffect, useMemo } from 'react'
 import { useConfig } from '../../store/configContext'
 import { useApp } from '../../store/appContext'
 import { stringToKebab } from '../../../utils/stringToKebab.js'
+import { getPanelElementId } from '../../../utils/getPanelElementId.js'
 import { useModalPanelBehaviour } from '../../hooks/useModalPanelBehaviour.js'
 import { useIsScrollable } from '../../hooks/useIsScrollable.js'
+import { classifyPanel, getPanelRole } from '../../../utils/getPanelRole.js'
 import { Icon } from '../Icon/Icon'
 import { Tabs } from '../Tabs/Tabs.jsx'
 
 const computePanelState = (bpConfig, triggeringElement, focus, focusOnOpen) => {
-  const isAside = bpConfig.slot === 'side' && bpConfig.open && !bpConfig.modal
-  const isDialog = !isAside && bpConfig.dismissible
-  const isModal = bpConfig.modal === true
-  const isDismissible = bpConfig.dismissible !== false
+  const { isModal, isAside, isDismissible, isDialog } = classifyPanel(bpConfig)
   const shouldFocus = isModal || focusOnOpen === true || (focusOnOpen !== false && focus !== false && (focus === true || Boolean(triggeringElement)))
   const buttonContainerEl = bpConfig.slot.endsWith('button') ? triggeringElement?.parentNode : undefined
   return { isAside, isDialog, isModal, isDismissible, shouldFocus, buttonContainerEl }
 }
 
-const getPanelRole = (isDialog, isDismissible) => {
-  if (isDialog) {
-    return 'dialog'
-  }
-  if (isDismissible) {
-    return 'complementary'
-  }
-  return 'region'
-}
-
 const buildPanelClassNames = (slot, showLabel) => [
   'im-c-panel',
   `im-c-panel--${slot}`,
@@ -38,15 +27,17 @@ const buildPanelBodyClassNames = (showLabel, isDismissible) => [
   !showLabel && isDismissible && 'im-c-panel__body--offset'
 ].filter(Boolean).join(' ')
 
-const buildPanelProps = ({ elementId, shouldFocus, isDialog, isDismissible, isModal, width, panelClass, slot }) => ({
+const buildPanelProps = ({ elementId, shouldFocus, isDialog, isDismissible, isModal, width, panelClass, slot, isOpen }) => ({
   id: elementId,
   'aria-labelledby': `${elementId}-label`,
   tabIndex: shouldFocus ? -1 : undefined, // nosonar
-  role: getPanelRole(isDialog, isDismissible),
+  role: getPanelRole({ isDialog, isDismissible }),
   'aria-modal': isDialog && isModal ? 'true' : undefined,
   style: width ? { width } : undefined,
   className: panelClass,
-  'data-slot': slot
+  'data-slot': slot,
+  // Panel is mounted permanently (see mapPanels.js); hidden is what actually opens/closes it.
+  hidden: !isOpen
 })
 
 const buildBodyProps = ({ bodyRef, panelBodyClass, isBodyScrollable, elementId }) => ({
@@ -112,7 +103,7 @@ export const Panel = ({ panelId, panelConfig, props, focusOnOpen, WrappedChild,
 
   const rootEl = document.getElementById(`${id}-im-app`)
   const bpConfig = panelConfig[breakpoint]
-  const elementId = `${id}-panel-${stringToKebab(panelId)}`
+  const elementId = getPanelElementId(id, panelId)
 
   const { isAside, isDialog, isModal, isDismissible, shouldFocus, buttonContainerEl } = computePanelState(bpConfig, props?.triggeringElement, panelConfig.focus, focusOnOpen) // nosonar
 
@@ -129,7 +120,15 @@ export const Panel = ({ panelId, panelConfig, props, focusOnOpen, WrappedChild,
   const panelRef = rootRef || internalPanelRef
 
   const handleClose = () => {
-    requestAnimationFrame(() => { (props?.triggeringElement || layoutRefs.viewportRef.current).focus?.({ preventScroll: interfaceType !== 'keyboard' }) })
+    requestAnimationFrame(() => {
+      // Re-checked here, not at handleClose-call time — the triggering element (a button, a
+      // Features-list item, ...) may have been removed from the DOM while the panel was open
+      // (e.g. the map panned and the feature it came from dropped out of the current list).
+      // document.contains() on a detached node is false, not a throw, so this is a plain check.
+      const triggeringElement = props?.triggeringElement
+      const focusTarget = triggeringElement && document.contains(triggeringElement) ? triggeringElement : layoutRefs.viewportRef.current
+      focusTarget?.focus?.({ preventScroll: interfaceType !== 'keyboard' })
+    })
     dispatch({ type: 'CLOSE_PANEL', payload: panelId })
   }
 
@@ -149,7 +148,7 @@ export const Panel = ({ panelId, panelConfig, props, focusOnOpen, WrappedChild,
   const panelBodyClass = buildPanelBodyClassNames(bpConfig.showLabel ?? true, isDismissible)
   const innerHtmlProp = useMemo(() => html ? { __html: html } : null, [html])
 
-  const panelProps = buildPanelProps({ elementId, shouldFocus, isDialog, isDismissible, isModal, width: bpConfig.width, panelClass, slot: bpConfig.slot })
+  const panelProps = buildPanelProps({ elementId, shouldFocus, isDialog, isDismissible, isModal, width: bpConfig.width, panelClass, slot: bpConfig.slot, isOpen })
   const bodyProps = buildBodyProps({ bodyRef, panelBodyClass, isBodyScrollable, elementId })
   // DOM anchor for controls DOM-projected via the JS/consumer-HTML API — see HtmlElementHost.jsx.
   // Only present on the items-capable body below: dangerouslySetInnerHTML owns the static-html

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

@@ -20,6 +20,11 @@
     pointer-events: auto;
     color: var(--foreground-color);
     background-color: var(--background-color);
+
+    // Override needed: display: flex above beats the browser's default [hidden] rule otherwise.
+    &[hidden] {
+        display: none;
+    }
 }
 
 // 2. Elements

package/src/App/components/Panel/Panel.test.jsx

@@ -102,6 +102,20 @@ describe('Panel', () => {
       expect(dialog).toHaveAttribute('aria-modal', 'true')
       expect(dialog).toHaveAttribute('tabIndex', '-1')
     })
+
+    it('renders dialog role and aria-modal for a modal panel even when dismissible is left unset (WCAG requires a modal to be dismissible)', () => {
+      renderPanel({ desktop: { slot: 'overlay', modal: true } })
+      const dialog = screen.getByRole('dialog')
+      expect(dialog).toHaveAttribute('aria-modal', 'true')
+      expect(screen.getByRole('button', { name: 'Close Settings' })).toBeInTheDocument()
+    })
+
+    it('renders dialog role and aria-modal for a modal panel even when dismissible: false is set (a non-dismissible modal would trap keyboard/AT users)', () => {
+      renderPanel({ desktop: { slot: 'overlay', modal: true, dismissible: false } })
+      const dialog = screen.getByRole('dialog')
+      expect(dialog).toHaveAttribute('aria-modal', 'true')
+      expect(screen.getByRole('button', { name: 'Close Settings' })).toBeInTheDocument()
+    })
   })
 
   describe('focus behaviour', () => {
@@ -142,9 +156,18 @@ describe('Panel', () => {
   })
 
   describe('close functionality', () => {
+    // document.contains() needs a real Node — a plain { focus: jest.fn() } mock object throws
+    // ("parameter 1 is not of type 'Node'"), so triggeringElement here is a real element, spied
+    // on and attached to the document, matching what production always passes
+    // (e.currentTarget / document.activeElement).
+    const makeAttachedTriggeringElement = () => {
+      const el = document.createElement('button')
+      document.body.appendChild(el)
+      return { el, focusMock: jest.spyOn(el, 'focus') }
+    }
+
     it('focuses triggeringElement on close for button slots', () => {
-      const focusMock = jest.fn()
-      const triggeringElement = { focus: focusMock, parentNode: document.createElement('div') }
+      const { el: triggeringElement, focusMock } = makeAttachedTriggeringElement()
 
       renderPanel(
         { desktop: { slot: 'top-button', dismissible: true, open: false } },
@@ -157,8 +180,7 @@ describe('Panel', () => {
     })
 
     it('handles close for non-button slots', () => {
-      const focusMock = jest.fn()
-      const triggeringElement = { focus: focusMock, parentNode: document.createElement('div') }
+      const { el: triggeringElement, focusMock } = makeAttachedTriggeringElement()
 
       renderPanel(
         { desktop: { slot: 'overlay', dismissible: true, modal: true } },
@@ -176,6 +198,20 @@ describe('Panel', () => {
       expect(layoutRefs.viewportRef.current.focus).toHaveBeenCalled()
       expect(dispatch).toHaveBeenCalledWith({ type: 'CLOSE_PANEL', payload: 'Settings' })
     })
+
+    it('falls back to viewportRef focus when triggeringElement has been removed from the DOM', () => {
+      const triggeringElement = document.createElement('button') // never attached
+      const focusMock = jest.spyOn(triggeringElement, 'focus')
+
+      renderPanel(
+        { desktop: { slot: 'side', dismissible: true, open: false } },
+        { props: { triggeringElement } }
+      )
+
+      fireEvent.click(screen.getByRole('button', { name: 'Close Settings' }))
+      expect(focusMock).not.toHaveBeenCalled()
+      expect(layoutRefs.viewportRef.current.focus).toHaveBeenCalled()
+    })
   })
 
   describe('content rendering', () => {
@@ -308,4 +344,33 @@ describe('Panel', () => {
       })
     })
   })
+
+  describe('isOpen (always-mounted, hidden-toggle)', () => {
+    it('renders hidden (not unmounted) when isOpen is false, so its id stays a real element', () => {
+      renderPanel({}, { isOpen: false })
+      const panel = document.getElementById('app-panel-settings')
+      expect(panel).toBeInTheDocument()
+      expect(panel).toHaveAttribute('hidden')
+    })
+
+    it('does not focus a closed panel, even one that would otherwise auto-focus (modal)', () => {
+      renderPanel({ desktop: { slot: 'overlay', dismissible: true, modal: true } }, { isOpen: false })
+      const panel = document.getElementById('app-panel-settings')
+      expect(document.activeElement).not.toBe(panel)
+    })
+
+    it('keeps the same DOM node (no swap/remount) across an isOpen transition, and un-hides it once open', () => {
+      const panelConfig = { desktop: { slot: 'side', open: true, dismissible: false, modal: false, showLabel: true } }
+      const { rerender } = render(<Panel panelId='Settings' panelConfig={panelConfig} label='Settings' isOpen={false} />)
+      const panelWhileClosed = document.getElementById('app-panel-settings')
+      expect(panelWhileClosed).toHaveAttribute('hidden')
+
+      rerender(<Panel panelId='Settings' panelConfig={panelConfig} label='Settings' isOpen items={[{ id: 'a', element: <p>Item</p> }]} />)
+
+      const panelWhileOpen = document.getElementById('app-panel-settings')
+      expect(panelWhileOpen).toBe(panelWhileClosed)
+      expect(panelWhileOpen).not.toHaveAttribute('hidden')
+      expect(screen.getByText('Item')).toBeInTheDocument()
+    })
+  })
 })

package/src/App/components/PopupMenu/PopupMenu.jsx

@@ -21,7 +21,8 @@ const MenuItem = ({ item, isSelected, hiddenButtons, disabledButtons, pressedBut
   </li>
 )
 
-export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, startPos, startIndex, menuRef, items, setIsOpen, buttonRect }) => {
+// isOpen defaults to true so direct/standalone usage doesn't need to pass it.
+export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, startPos, startIndex, menuRef, items, setIsOpen, buttonRect, isOpen = true }) => {
   const { id } = useConfig()
   const { buttonRefs, buttonConfig, hiddenButtons, disabledButtons, pressedButtons, layoutRefs } = useApp()
   const instigatorKey = buttonId ?? instigatorId
@@ -43,7 +44,8 @@ export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, start
     id,
     menuRef,
     setIsOpen,
-    buttonRect
+    buttonRect,
+    isOpen
   })
 
   return createPortal(
@@ -56,11 +58,13 @@ export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, start
       style={menuStyle}
       role='menu' // NOSONAR
       tabIndex='-1'
+      hidden={!isOpen}
       aria-labelledby={instigatorKey}
       aria-activedescendant={index >= 0 ? `${id}-${stringToKebab(items[index].id)}` : undefined}
       onKeyDown={handleMenuKeyDown}
     >
-      {items.map((item, i) => (
+      {/* Items only mount once open — the <ul> above stays in the DOM either way. */}
+      {isOpen && items.map((item, i) => (
         <MenuItem
           key={item.id}
           item={item}

package/src/App/components/PopupMenu/PopupMenu.test.jsx

@@ -651,4 +651,75 @@ describe('PopupMenu', () => {
     window.dispatchEvent(new Event('resize'))
     expect(mockSetIsOpen).toHaveBeenCalledWith(false)
   })
+
+  describe('isOpen (always-mounted, hidden-toggle)', () => {
+    it('renders a hidden, empty menu when isOpen is false, without grabbing focus or item content', () => {
+      renderMenu({ isOpen: false })
+      const ul = screen.getByRole('menu', { hidden: true })
+      expect(ul).toHaveAttribute('hidden')
+      expect(screen.queryByText('Item 1')).not.toBeInTheDocument()
+      expect(document.activeElement).not.toBe(ul)
+    })
+
+    it('keeps the same ul node across an isOpen transition (no swap/remount) and un-hides it once open', () => {
+      const { rerender } = renderMenu({ isOpen: false })
+      const ulWhileClosed = screen.getByRole('menu', { hidden: true })
+
+      rerender(
+        <PopupMenu
+          id='menu'
+          pluginId='plugin1'
+          instigatorId='instigator'
+          startPos='first'
+          menuRef={menuRef}
+          items={items}
+          setIsOpen={mockSetIsOpen}
+          isOpen
+        />
+      )
+
+      const ulWhileOpen = screen.getByRole('menu')
+      expect(ulWhileOpen).toBe(ulWhileClosed)
+      expect(ulWhileOpen).not.toHaveAttribute('hidden')
+      expect(screen.getByText('Item 1')).toBeInTheDocument()
+      expect(document.activeElement).toBe(ulWhileOpen)
+    })
+
+    it('resets selection on every open rather than carrying over a stale index from a previous open', () => {
+      const { rerender } = renderMenu({ startPos: 'first', startIndex: undefined })
+      expectSelected('Item 1')
+
+      // Close, then reopen via a plain click — selection should reset, not carry over.
+      rerender(
+        <PopupMenu
+          id='menu'
+          pluginId='plugin1'
+          instigatorId='instigator'
+          menuRef={menuRef}
+          items={items}
+          setIsOpen={mockSetIsOpen}
+          isOpen={false}
+        />
+      )
+      rerender(
+        <PopupMenu
+          id='menu'
+          pluginId='plugin1'
+          instigatorId='instigator'
+          menuRef={menuRef}
+          items={items}
+          setIsOpen={mockSetIsOpen}
+          isOpen
+        />
+      )
+      expectNotSelected('Item 1')
+      expectNotSelected('Item 2')
+    })
+
+    it('defaults isOpen to true for direct/standalone usage', () => {
+      renderMenu()
+      expect(screen.getByRole('menu')).not.toHaveAttribute('hidden')
+      expect(screen.getByText('Item 1')).toBeInTheDocument()
+    })
+  })
 })

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

@@ -275,12 +275,14 @@ const createMenuKeyDownHandler = ({ items, visibleIndices, index, setIndex, disa
  * @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.
+ * @param {boolean}  [params.isOpen]         - Whether the menu is currently open (PopupMenu stays
+ *   mounted; this just toggles visibility, so setup/teardown here is keyed on isOpen, not mount).
  * @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
+  buttonRefs, buttonConfig, disabledButtons, pluginId, evaluateProp, id, menuRef, setIsOpen, buttonRect, isOpen
 }) => {
   const { dispatch, layoutRefs } = useApp()
   const viewportRef = layoutRefs.viewportRef
@@ -329,15 +331,14 @@ export const usePopupMenu = ({
     }
   }
 
+  // Keyed on isOpen (not mount) since PopupMenu stays mounted; resolveInitialIndex re-runs each
+  // open so selection resets instead of carrying over from a previous open.
   useEffect(() => {
-    menuRef.current?.focus()
-    if (startPos === 'first') {
-      setIndex(visibleIndices[0] ?? -1)
-    } else if (startPos === 'last') {
-      setIndex(visibleIndices[visibleIndices.length - 1] ?? -1) // NOSONAR .length - 1 used instead of .at(-1) for wider browser support
-    } else {
-      // No action
+    if (!isOpen) {
+      return undefined
     }
+    menuRef.current?.focus()
+    setIndex(resolveInitialIndex(startIndex, startPos, visibleIndices))
     const handleResize = () => setIsOpen(false)
     document.addEventListener('focusin', handleOutside)
     document.addEventListener('pointerdown', handleOutside)
@@ -347,7 +348,7 @@ export const usePopupMenu = ({
       document.removeEventListener('pointerdown', handleOutside)
       window.removeEventListener('resize', handleResize)
     }
-  }, [])
+  }, [isOpen])
 
   const { style: menuStyle, direction: menuDirection, halign: menuHAlign } = getMenuStyle(buttonRect)
   return { index, handleMenuKeyDown, handleItemClick, menuStyle, menuDirection, menuHAlign }

package/src/App/components/Viewport/MapStatus.jsx

@@ -11,7 +11,7 @@ export const MapStatus = () => {
     <div // NOSONAR: div + status role is semantically correct here, <output> implies a calculation result
       ref={mapStatusRef}
       role='status'
-      className='im-c-viewport__status'
+      className='im-u-visually-hidden'
     />
   )
 }

package/src/App/components/Viewport/SpatialList.jsx

@@ -0,0 +1,47 @@
+import React, { forwardRef } from 'react'
+import { useConfig } from '../../store/configContext.js'
+
+// Accessible spatial list: a listbox whose items are positioned to match wherever they are on
+// the map, navigable both sequentially (Arrow/Home/End) and spatially (Alt+Arrow — see
+// useSpatialListFocus.js). Content is whatever the current spatialListRegistry provider
+// contributes; `label` names it for aria-label accordingly.
+export const SpatialList = forwardRef(({ activeItemId, tabbableId, selectedIds = [], multiselectable = false, items = [], label = 'Map features', focusable = true, onFocus, onBlur, onSelectItem }, ref) => {
+  const { id } = useConfig()
+  const hasItems = items.length > 0
+  // Roving tabindex: exactly one option is a Tab stop at a time — see useSpatialListFocus.js.
+  const currentId = activeItemId ?? tabbableId
+  return (
+    <ul // NOSONAR: role='listbox' is correct for custom composite widget; native <select> cannot host SVG marker elements
+      id={`${id}-spatial-list`}
+      ref={ref}
+      role='listbox' // NOSONAR
+      aria-hidden={hasItems ? undefined : true}
+      aria-label={label}
+      aria-describedby={`${id}-keyboard-desc`}
+      aria-multiselectable={multiselectable || undefined}
+      className='im-c-spatial-list'
+      onFocus={onFocus}
+      onBlur={onBlur}
+    >
+      {items.map(item => (
+        <li // NOSONAR: role='option' overrides implicit listitem; this is the correct ARIA listbox child pattern.
+          // tabIndex/onClick let voice control and screen readers reach and activate each option
+          // directly. focusable: false (draw's vertex/midpoint items) keeps every item out of
+          // the Tab order — that population already has a full keyboard path via the map itself.
+          key={item.id} id={`${id}-spatial-list-item-${item.id}`} role='option' // NOSONAR
+          data-id={item.id}
+          tabIndex={focusable && item.id === currentId ? 0 : -1}
+          aria-selected={selectedIds.includes(item.id)}
+          // Positions the (visually clipped) option over its on-map feature, so AT overlays like
+          // Voice Control's "Show Numbers" number it at the right screen position.
+          style={item.x != null ? { left: item.x, top: item.y } : undefined}
+          onClick={() => onSelectItem?.(item.id)}
+        >
+          {item.label}
+        </li>
+      ))}
+    </ul>
+  )
+})
+
+SpatialList.displayName = 'SpatialList'

package/src/App/components/Viewport/{Features.module.scss → SpatialList.module.scss}

@@ -1,10 +1,10 @@
 @use '../../../scss/tools/index' as tools;
 
 // ===================================================
-// Component: Features
+// Component: SpatialList
 // ===================================================
 
-.im-c-features {
+.im-c-spatial-list {
   position: absolute;
   inset: 0;
   pointer-events: none;
@@ -16,10 +16,6 @@
     $is-inset: true
   );
 
-  &[data-focus-visible="true"][aria-activedescendant]::after {
-    opacity: 0;
-  }
-
   [role="option"] {
     position: absolute;
     width: 1px;
@@ -27,5 +23,9 @@
     overflow: hidden;
     clip-path: inset(50%);
     white-space: nowrap;
+    // Roving tabindex moves real focus (and click activation) onto individual options, so they
+    // need pointer events re-enabled — overridden off .im-c-spatial-list's pointer-events: none,
+    // which otherwise lets mouse interaction pass through to the map everywhere else.
+    pointer-events: auto;
   }
 }