@defra/interactive-map 0.0.42-fmp-4 → 0.0.43-alpha

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

@@ -23,7 +23,8 @@ jest.mock('../../renderer/SlotRenderer', () => ({
 }))
 
 jest.mock('../PopupMenu/PopupMenu', () => ({
-  PopupMenu: ({ startPos, items, buttonRect }) => {
+  // Mirrors the real component: always mounted, hidden/children gated by isOpen.
+  PopupMenu: ({ popupMenuId, isOpen, startPos, items, buttonRect }) => {
     let selectedIndex = -1
     if (startPos === 'first' && items?.length > 0) {
       selectedIndex = 0
@@ -31,7 +32,11 @@ jest.mock('../PopupMenu/PopupMenu', () => ({
     if (startPos === 'last' && items?.length > 0) {
       selectedIndex = items.length - 1
     }
-    return <div data-testid='popup-menu' data-start-pos={String(startPos)} data-selected-index={String(selectedIndex)} data-has-rect={String(!!buttonRect)}>{items?.map((item, i) => <div key={i} data-testid={`menu-item-${i}`}>{item.label}</div>)}</div>
+    return (
+      <div id={popupMenuId} hidden={!isOpen} data-testid='popup-menu' data-start-pos={String(startPos)} data-selected-index={String(selectedIndex)} data-has-rect={String(!!buttonRect)}>
+        {isOpen && items?.map((item, i) => <div key={i} data-testid={`menu-item-${i}`}>{item.label}</div>)}
+      </div>
+    )
   }
 }))
 
@@ -78,9 +83,20 @@ describe('MapButton', () => {
     expect(button).toHaveAttribute('aria-expanded', 'false')
     expect(button).not.toHaveAttribute('aria-pressed')
     expect(button).toHaveAttribute('aria-controls', 'prefix-panel-settings')
+    expect(button).not.toHaveAttribute('aria-haspopup')
     expect(screen.getByTestId('slot')).toHaveAttribute('data-slot', 'test-button')
   })
 
+  it('sets aria-haspopup="dialog" when the controlled panel is a dialog', () => {
+    renderButton({ panelId: 'Settings', idPrefix: 'prefix', panelRole: 'dialog' })
+    expect(getButton()).toHaveAttribute('aria-haspopup', 'dialog')
+  })
+
+  it.each(['complementary', 'region'])('sets no aria-haspopup when the controlled panel role is %s', (panelRole) => {
+    renderButton({ panelId: 'Settings', idPrefix: 'prefix', panelRole })
+    expect(getButton()).not.toHaveAttribute('aria-haspopup')
+  })
+
   it.each([
     [{ isPressed: true }, 'true'],
     [{ isPressed: 'true' }, undefined]
@@ -118,7 +134,7 @@ describe('MapButton', () => {
     renderButton({ isDisabled: true, menuItems: [{ label: 'Item' }], onClick })
     fireEvent.click(getButton())
     expect(onClick).not.toHaveBeenCalled()
-    expect(screen.queryByTestId('popup-menu')).not.toBeInTheDocument()
+    expect(screen.getByTestId('popup-menu')).not.toBeVisible()
   })
 
   it('stores button refs correctly', () => {
@@ -138,6 +154,28 @@ describe('MapButton', () => {
     expect(button).toHaveAttribute('aria-haspopup', 'menu')
   })
 
+  it('reserves the aria-controls id as a stable, hidden node before the popup has ever been opened', () => {
+    renderButton({ idPrefix: 'prefix', menuItems: [{ label: 'Item' }] })
+    const menu = document.getElementById('prefix-popup-test')
+    expect(menu).toBeInTheDocument()
+    expect(menu).not.toBeVisible()
+  })
+
+  it('keeps the same DOM node (no swap/remount) when opening and closing the popup', () => {
+    renderButton({ idPrefix: 'prefix', menuItems: [{ label: 'Item' }] })
+    const menuBeforeOpen = document.getElementById('prefix-popup-test')
+
+    fireEvent.click(getButton())
+    const menuWhileOpen = document.getElementById('prefix-popup-test')
+    expect(menuWhileOpen).toBe(menuBeforeOpen)
+    expect(menuWhileOpen).toBeVisible()
+
+    fireEvent.click(getButton())
+    const menuAfterClose = document.getElementById('prefix-popup-test')
+    expect(menuAfterClose).toBe(menuBeforeOpen)
+    expect(menuAfterClose).not.toBeVisible()
+  })
+
   it('toggles popup aria-expanded and startPos', () => {
     renderButton({ menuItems: [{ label: 'Item' }] })
     const button = getButton()
@@ -224,7 +262,7 @@ describe('MapButton', () => {
   it('does nothing for unrelated keys', () => {
     renderButton({ menuItems: [{ label: 'Item' }] })
     fireEvent.keyUp(getButton(), { key: 'Enter' })
-    expect(screen.queryByTestId('popup-menu')).not.toBeInTheDocument()
+    expect(screen.getByTestId('popup-menu')).not.toBeVisible()
   })
 
   it.each([

package/src/App/components/Markers/SymbolMarker.jsx

@@ -3,7 +3,7 @@ import { stringToKebab } from '../../../utils/stringToKebab.js'
 const SymbolMarker = ({ marker, mapId, markerRef, isSelected, symbolProps }) => { // NOSONAR: project does not use PropTypes
   const { resolvedSvg, viewBox, anchor, shapeId, scaledWidth, scaledHeight } = symbolProps
   return (
-    <svg // NOSONAR: role='img' with aria-label is the correct ARIA pattern for SVG icons; <img> is not appropriate here
+    <svg
       ref={markerRef(marker.id)}
       id={`${mapId}-marker-${marker.id}`}
       className={[
@@ -15,8 +15,7 @@ const SymbolMarker = ({ marker, mapId, markerRef, isSelected, symbolProps }) =>
       height={scaledHeight}
       viewBox={viewBox}
       overflow='visible'
-      role='img'
-      aria-label={marker.label || 'Map marker'}
+      aria-hidden='true'
       style={{
         display: marker.isVisible ? 'block' : 'none',
         marginLeft: `${-anchor[0] * scaledWidth}px`,

package/src/App/components/Markers/SymbolMarker.test.jsx

@@ -19,19 +19,18 @@ describe('SymbolMarker', () => {
     expect(container.querySelector('svg').getAttribute('id')).toBe('my-map-marker-marker-1')
   })
 
-  it('has role img', () => {
+  // Decorative: the ancestor markers layer is aria-hidden, and Features (the accessible
+  // features listbox) is the sole accessible surface for a marker's label — see Features.jsx.
+  it('is aria-hidden', () => {
     const { container } = render(<SymbolMarker marker={makeMarker()} mapId='map' markerRef={markerRef} isSelected={false} symbolProps={makeSymbolProps()} />)
-    expect(container.querySelector('svg').getAttribute('role')).toBe('img')
+    expect(container.querySelector('svg').getAttribute('aria-hidden')).toBe('true')
   })
 
-  it('aria-label uses marker.label', () => {
+  it('has no role or aria-label, regardless of marker.label', () => {
     const { container } = render(<SymbolMarker marker={makeMarker({ label: 'My location' })} mapId='map' markerRef={markerRef} isSelected={false} symbolProps={makeSymbolProps()} />)
-    expect(container.querySelector('svg').getAttribute('aria-label')).toBe('My location')
-  })
-
-  it('aria-label falls back to Map marker when no label', () => {
-    const { container } = render(<SymbolMarker marker={makeMarker()} mapId='map' markerRef={markerRef} isSelected={false} symbolProps={makeSymbolProps()} />)
-    expect(container.querySelector('svg').getAttribute('aria-label')).toBe('Map marker')
+    const svg = container.querySelector('svg')
+    expect(svg.getAttribute('role')).toBeNull()
+    expect(svg.getAttribute('aria-label')).toBeNull()
   })
 
   it('applies shapeId class', () => {

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/Features.jsx

@@ -1,29 +1,43 @@
 import React, { forwardRef } from 'react'
 import { useConfig } from '../../store/configContext.js'
 
-export const Features = forwardRef(({ activeFeatureId, selectedIds = [], multiselectable = false, items = [], onFocus, onBlur }, ref) => {
+export const Features = forwardRef(({ activeFeatureId, tabbableId, selectedIds = [], multiselectable = false, items = [], onFocus, onBlur, onSelectItem }, ref) => {
   const { id } = useConfig()
   const hasItems = items.length > 0
+  // Roving tabindex: exactly one option is a Tab stop at a time (the focused item while the
+  // list has real focus, otherwise the resting entry position) — see useFeatureFocus.js.
+  const currentId = activeFeatureId ?? tabbableId
   return (
     <ul // NOSONAR: role='listbox' is correct for custom composite widget; native <select> cannot host SVG marker elements
       id={`${id}-features`}
       ref={ref}
       role='listbox' // NOSONAR
-      tabIndex={hasItems ? '0' : '-1'}
       aria-hidden={hasItems ? undefined : true}
       aria-label='Map features'
       aria-describedby={`${id}-keyboard-desc`}
       aria-multiselectable={multiselectable || undefined}
-      aria-activedescendant={activeFeatureId ? `${id}-feature-${activeFeatureId}` : undefined}
       className='im-c-features'
       onFocus={onFocus}
       onBlur={onBlur}
     >
       {items.map(item => (
-        <li // NOSONAR: role='option' overrides implicit listitem; this is the correct ARIA listbox child pattern
+        <li // NOSONAR: role='option' overrides implicit listitem; this is the correct ARIA listbox child pattern.
+          // tabIndex/onClick make each option a real, independently focusable and activatable
+          // control — required so touch screen readers and voice control can reach and operate
+          // it directly, not just app-managed keyboard-arrow navigation.
           key={item.id} id={`${id}-feature-${item.id}`} role='option' // NOSONAR
           data-id={item.id}
+          tabIndex={item.id === currentId ? 0 : -1}
           aria-selected={selectedIds.includes(item.id)}
+          // Positions the (visually clipped) option over its on-map feature — item.x/item.y are
+          // screen coordinates from the interact plugin (see useMapItemList.js). Without this,
+          // every option collapses to the CSS static-position default (~top-left of the
+          // viewport), which is invisible to sighted users but misaligns coordinate-based AT
+          // overlays, e.g. macOS Voice Control's "Show Numbers", which numbers items at their
+          // real position on screen. Items without a resolved position (not yet supported for
+          // dataset/polygon features) fall back to that same default.
+          style={item.x != null ? { left: item.x, top: item.y } : undefined}
+          onClick={() => onSelectItem?.(item.id)}
         >
           {item.label}
         </li>

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

@@ -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-features's pointer-events: none,
+    // which otherwise lets mouse interaction pass through to the map everywhere else.
+    pointer-events: auto;
   }
 }