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

package/providers/beta/openlayers/src/openlayersProvider.js

@@ -11,7 +11,7 @@ import { attachMapEvents } from './mapEvents.js'
 import { attachAppEvents, createMapStyleLayer } from './appEvents.js'
 import { getAreaDimensions, getCardinalMove, getExtentFromGeoJSON, getPaddedExtent, isGeometryObscured } from './utils/spatial.js'
 import { updateHighlightedFeatures } from './utils/highlightFeatures.js'
-import { queryFeatures } from './utils/queryFeatures.js'
+import { queryFeatures, getVisibleFeatures } from './utils/queryFeatures.js'
 import { collectTileFragments } from './utils/vtTileFragments.js'
 import { setupHoverCursor } from './utils/hoverCursor.js'
 import { applyOpenLayersFixes } from './utils/openLayersFixes.js'
@@ -223,8 +223,8 @@ export default class OpenLayersProvider extends MapProvider {
     this._onHoverMove = setupHoverCursor(this.map, layerIds, this._onHoverMove)
   }
 
-  getVisibleFeatures (_layerIds) {
-    return []
+  getVisibleFeatures (layerIds) {
+    return getVisibleFeatures(this.map, layerIds)
   }
 
   updateHighlightedFeatures (selectedFeatures, activeFeatures, stylesMap) {

package/providers/beta/openlayers/src/openlayersProvider.test.js

@@ -26,13 +26,15 @@ const mockMapGetSize = jest.fn(() => [800, 600])
 const mockMapSetTarget = jest.fn()
 const mockMapGetPixel = jest.fn(() => [100, 200])
 const mockMapGetCoord = jest.fn(() => [400000, 300000])
+const mockMapGetLayers = jest.fn(() => ({ forEach: jest.fn() }))
 const mockMapInstance = {
   once: mockMapOnce,
   getSize: mockMapGetSize,
   setTarget: mockMapSetTarget,
   getPixelFromCoordinate: mockMapGetPixel,
   getCoordinateFromPixel: mockMapGetCoord,
-  getView: jest.fn(() => mockViewInstance)
+  getView: jest.fn(() => mockViewInstance),
+  getLayers: mockMapGetLayers
 }
 
 const mockSource = {}
@@ -329,8 +331,9 @@ describe('OpenLayersProvider', () => {
       expect(provider.getBounds()).toEqual([1.13, 2.46, 3.99, 4])
     })
 
-    it('getVisibleFeatures returns empty array', () => {
-      expect(provider.getVisibleFeatures()).toEqual([])
+    it('getVisibleFeatures delegates to the map (no layers registered here — see queryFeatures.test.js)', () => {
+      expect(provider.getVisibleFeatures(['draw'])).toEqual([])
+      expect(mockMapGetLayers).toHaveBeenCalled()
     })
 
     it('getResolution delegates to view.getResolution', () => {

package/providers/beta/openlayers/src/utils/queryFeatures.js

@@ -1,6 +1,7 @@
 import VectorTileLayer from 'ol/layer/VectorTile.js'
 import VectorLayer from 'ol/layer/Vector.js'
 import GeoJSON from 'ol/format/GeoJSON.js'
+import TileState from 'ol/TileState.js'
 import { renderFeatureToGeoJSON } from './vtTileFragments.js'
 
 const CRS = 'EPSG:27700'
@@ -75,3 +76,74 @@ export const queryFeatures = (map, point, options = {}) => {
 
   return results
 }
+
+/**
+ * Returns every currently visible feature for the given layer ids, in the same
+ * { id, layer: { id }, geometry, properties } shape queryFeatures() above uses — mirrors
+ * MapLibre's map.queryRenderedFeatures(undefined, { layers }). Used by the interact plugin's
+ * Features list (collectVisibleFeatures in useMapItemList.js) to find selectable/labelled
+ * features without requiring a click.
+ *
+ * VectorTileLayer features come from currently-loaded tiles, the same source
+ * collectTileFragments() reads (see vtTileFragments.js) — OL only loads tiles for the current
+ * viewport (plus a small buffer), so "loaded" is a reasonable proxy for "visible" without a
+ * separate extent check. A single logical feature can be split across tile boundaries, so
+ * fragments are deduplicated the same way queryFeatures() does above.
+ * VectorLayer features come directly from the source's current-viewport extent.
+ */
+export const getVisibleFeatures = (map, layerIds) => {
+  const wanted = new Set(layerIds)
+  const results = []
+  const seenKeys = new Set()
+  const extent = map.getView().calculateExtent(map.getSize())
+
+  map.getLayers().forEach(mapLayer => {
+    if (mapLayer instanceof VectorTileLayer) {
+      const sourceTiles = mapLayer.getSource()?.sourceTiles_
+      if (!sourceTiles) {
+        return
+      }
+      Object.values(sourceTiles).forEach(tile => {
+        if (tile.getState() !== TileState.LOADED) {
+          return
+        }
+        tile.getFeatures().forEach(feature => {
+          const mapboxLayer = feature.get('mapbox-layer')
+          const styleLayerId = mapboxLayer?.id
+          // background-type layers have no features in MapLibre — skip to match behaviour
+          if (!styleLayerId || !wanted.has(styleLayerId) || mapboxLayer?.type === 'background') {
+            return
+          }
+          const key = `${styleLayerId}:${getVtFeatureId(feature)}`
+          if (seenKeys.has(key)) {
+            return
+          }
+          seenKeys.add(key)
+          results.push({
+            id: feature.getId(),
+            layer: { id: styleLayerId },
+            geometry: renderFeatureToGeoJSON(feature),
+            properties: feature.getProperties()
+          })
+        })
+      })
+    } else if (mapLayer instanceof VectorLayer) {
+      const layerId = mapLayer.get('layerId')
+      if (!layerId || !wanted.has(layerId) || mapLayer.get('_highlight')) {
+        return
+      }
+      mapLayer.getSource()?.getFeaturesInExtent(extent).forEach(feature => {
+        results.push({
+          id: feature.getId(),
+          layer: { id: layerId },
+          geometry: geoJsonFormat.writeGeometryObject(feature.getGeometry()),
+          properties: feature.getProperties()
+        })
+      })
+    } else {
+      // other layer types (e.g. TileLayer) — skip
+    }
+  })
+
+  return results
+}

package/providers/beta/openlayers/src/utils/queryFeatures.test.js

@@ -1,11 +1,13 @@
-import { queryFeatures } from './queryFeatures.js'
+import { queryFeatures, getVisibleFeatures } from './queryFeatures.js'
 
 import VectorTileLayer from 'ol/layer/VectorTile.js'
 import VectorLayer from 'ol/layer/Vector.js'
+import TileState from 'ol/TileState.js'
 import { renderFeatureToGeoJSON } from './vtTileFragments.js'
 
 jest.mock('ol/layer/VectorTile.js', () => ({ __esModule: true, default: class VectorTileLayer {} }))
 jest.mock('ol/layer/Vector.js', () => ({ __esModule: true, default: class VectorLayer {} }))
+jest.mock('ol/TileState.js', () => ({ __esModule: true, default: { LOADED: 'loaded', LOADING: 'loading' } }))
 jest.mock('ol/format/GeoJSON.js', () => ({
   __esModule: true,
   default: jest.fn(() => ({
@@ -179,3 +181,122 @@ describe('queryFeatures', () => {
     expect(queryFeatures(map, { x: 0, y: 0 })).toHaveLength(2)
   })
 })
+
+describe('getVisibleFeatures', () => {
+  beforeEach(() => jest.clearAllMocks())
+
+  const EXTENT = [0, 0, 100, 100]
+
+  const makeExtentMap = (layers = []) => ({
+    getView: () => ({ calculateExtent: () => EXTENT }),
+    getSize: () => [800, 600],
+    getLayers: () => ({ forEach: cb => layers.forEach(cb) })
+  })
+
+  const makeTile = (features, state = TileState.LOADED) => ({
+    getState: () => state,
+    getFeatures: () => features
+  })
+
+  const makeVTLayerWithTiles = (tiles) => Object.assign(new VectorTileLayer(), {
+    getSource: () => ({ sourceTiles_: tiles })
+  })
+
+  const makeVectorLayerWithFeatures = (layerId, features, isHighlight = false) => {
+    const source = { getFeaturesInExtent: jest.fn(() => features) }
+    return Object.assign(new VectorLayer(), {
+      get: (key) => {
+        if (key === 'layerId') return layerId
+        if (key === '_highlight') return isHighlight || undefined
+        return undefined
+      },
+      getSource: () => source
+    })
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* VectorTile layer features                                          */
+  /* ------------------------------------------------------------------ */
+
+  it('returns a loaded VT feature matching a requested layer id', () => {
+    const feature = makeVTFeature({ id: 1, styleLayerId: 'roads' })
+    const layer = makeVTLayerWithTiles({ a: makeTile([feature]) })
+    const results = getVisibleFeatures(makeExtentMap([layer]), ['roads'])
+    expect(results).toHaveLength(1)
+    expect(results[0]).toMatchObject({ id: 1, layer: { id: 'roads' } })
+  })
+
+  it('skips VT features whose style layer id is not requested', () => {
+    const feature = makeVTFeature({ id: 1, styleLayerId: 'buildings' })
+    const layer = makeVTLayerWithTiles({ a: makeTile([feature]) })
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['roads'])).toEqual([])
+  })
+
+  it('skips tiles that are not loaded', () => {
+    const feature = makeVTFeature({ id: 1, styleLayerId: 'roads' })
+    const layer = makeVTLayerWithTiles({ a: makeTile([feature], TileState.LOADING) })
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['roads'])).toEqual([])
+  })
+
+  it('skips background-type VT features', () => {
+    const feature = makeVTFeature({ styleLayerId: 'roads', type: 'background' })
+    const layer = makeVTLayerWithTiles({ a: makeTile([feature]) })
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['roads'])).toEqual([])
+  })
+
+  it('deduplicates the same feature split across multiple loaded tiles', () => {
+    const feature = makeVTFeature({ id: 1, styleLayerId: 'roads' })
+    const layer = makeVTLayerWithTiles({ a: makeTile([feature]), b: makeTile([feature]) })
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['roads'])).toHaveLength(1)
+  })
+
+  it('does nothing when the VectorTileLayer has no loaded tiles yet', () => {
+    const layer = makeVTLayerWithTiles(undefined)
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['roads'])).toEqual([])
+  })
+
+  /* ------------------------------------------------------------------ */
+  /* Vector layer features                                              */
+  /* ------------------------------------------------------------------ */
+
+  it('returns Vector layer features in the current extent for a requested layer id', () => {
+    const feature = makeVectorFeature('f1', { type: 'Point' })
+    const layer = makeVectorLayerWithFeatures('draw', [feature])
+    const results = getVisibleFeatures(makeExtentMap([layer]), ['draw'])
+    expect(results).toHaveLength(1)
+    expect(results[0]).toMatchObject({ id: 'f1', layer: { id: 'draw' } })
+  })
+
+  it('queries the source with the current view extent', () => {
+    const feature = makeVectorFeature('f1')
+    const layer = makeVectorLayerWithFeatures('draw', [feature])
+    const source = layer.getSource()
+    getVisibleFeatures(makeExtentMap([layer]), ['draw'])
+    expect(source.getFeaturesInExtent).toHaveBeenCalledWith(EXTENT)
+  })
+
+  it('skips Vector layers whose layerId is not requested', () => {
+    const layer = makeVectorLayerWithFeatures('other', [makeVectorFeature('f1')])
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['draw'])).toEqual([])
+  })
+
+  it('skips highlight overlay Vector layers', () => {
+    const layer = makeVectorLayerWithFeatures('draw', [makeVectorFeature('f1')], true)
+    expect(getVisibleFeatures(makeExtentMap([layer]), ['draw'])).toEqual([])
+  })
+
+  /* ------------------------------------------------------------------ */
+  /* Mixed / other layers                                               */
+  /* ------------------------------------------------------------------ */
+
+  it('skips layers that are neither VectorTileLayer nor VectorLayer', () => {
+    expect(getVisibleFeatures(makeExtentMap([{}]), ['draw'])).toEqual([])
+  })
+
+  it('returns results from both VT and Vector layers in one call', () => {
+    const vtLayer = makeVTLayerWithTiles({ a: makeTile([makeVTFeature({ id: 1, styleLayerId: 'roads' })]) })
+    const vecLayer = makeVectorLayerWithFeatures('draw', [makeVectorFeature('f1')])
+    const results = getVisibleFeatures(makeExtentMap([vtLayer, vecLayer]), ['roads', 'draw'])
+    expect(results).toHaveLength(2)
+  })
+})

package/providers/maplibre/src/defaults.test.js

@@ -0,0 +1,26 @@
+import { DEFAULTS, supportedShortcuts } from './defaults.js'
+
+describe('DEFAULTS', () => {
+  it('keeps animationDuration below the 500ms core debounce time', () => {
+    expect(DEFAULTS.animationDuration).toBeLessThan(500)
+  })
+
+  it('exposes coordinatePrecision', () => {
+    expect(DEFAULTS.coordinatePrecision).toBe(7)
+  })
+})
+
+describe('supportedShortcuts', () => {
+  it('lists the keyboard shortcuts this provider supports', () => {
+    expect(supportedShortcuts).toEqual([
+      'showKeyboardHelp',
+      'selectControl',
+      'moveLarge',
+      'nudgeMap',
+      'zoomLarge',
+      'nudgeZoom',
+      'highlightLabelAtCenter',
+      'highlightNextLabel'
+    ])
+  })
+})

package/src/App/components/CrossHair/CrossHair.jsx

@@ -16,24 +16,32 @@ export const CrossHair = () => {
   const { isVisible, isPinnedToMap, state } = crossHair
 
   return (
-    <svg
-      id={`${id}-cross-hair`}
+    <button
+      tabIndex='-1'
       ref={crossHairRef}
-      className='im-c-cross-hair'
-      width='38'
-      height='38'
-      viewBox='0 0 38 38'
-      fillRule='evenodd'
-      fill='currentColor'
+      id={`${id}-cross-hair`}
+      className='im-c-cross-hair-button'
+      onClick={() => crossHair.activate?.()}
       style={{
         position: 'absolute',
         left: isPinnedToMap ? 0 : '50%',
         top: isPinnedToMap ? 0 : '50%',
-        pointerEvents: 'none',
         display: isVisible ? 'block' : 'none'
       }}
     >
-      <path d={paths[state || 'active']} />
-    </svg>
+      <svg
+        width='38'
+        height='38'
+        viewBox='0 0 38 38'
+        fillRule='evenodd'
+        fill='currentColor'
+      >
+        <path d={paths[state || 'active']} />
+      </svg>
+      {/* "Target" — shorter and easier for Voice Control users to say than "Cross hair"
+          ("Click Target"); a general-purpose map is unlikely to already have a feature/marker
+          named "Target" that this would collide with. */}
+      <span className='im-u-visually-hidden'>Target</span>
+    </button>
   )
 }

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

@@ -1,14 +1,35 @@
-.im-c-cross-hair {
-  position: absolute;
-  top: 0;
-  left: 0;
-  pointer-events: none;
+// The crosshair is wrapped in a real <button> (tabIndex="-1") so it's a genuine, accessibility-
+// focusable target for coordinate-based AT (e.g. macOS Voice Control's Show Numbers/Names) —
+// see CrossHair.jsx — without being a Tab stop.
+.im-c-cross-hair-button {
+  // Reset native chrome to zero: default padding/border/background otherwise shift and
+  // decorate the crosshair icon, since position/margin below assumes the content-box starts
+  // exactly at the border-box edge.
+  appearance: none;
+  border: 0;
+  background: none;
+  padding: 0;
+  font: inherit;
+  cursor: inherit;
+
+  // Explicit size, matching the SVG's own width/height, plus the negative margin that shifts
+  // the box by half its own size — so the button's *own* geometry, not just its child SVG's, is
+  // centred on wherever CrossHair.jsx's inline top/left positions it. This is what a coordinate-
+  // based AT overlay (e.g. Voice Control) reads to place its badge — without it, the button's
+  // content-box collapses to 0×0 (its only child is position:absolute, contributing nothing to
+  // normal-flow sizing), so the badge would land at the anchor point's corner, not on the icon.
+  width: 38px;
+  height: 38px;
   margin: -19px 0 0 -19px;
-}
 
-.im-c-cross-hair path {
-  stroke-width: 3;
-  stroke: var(--map-overlay-halo-color);
-  fill: var(--map-overlay-foreground-color);
-  paint-order: stroke fill;
-}
+  svg {
+    display: block;
+  }
+
+  path {
+    stroke-width: 3;
+    stroke: var(--map-overlay-halo-color);
+    fill: var(--map-overlay-foreground-color);
+    paint-order: stroke fill;
+  }
+}

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

@@ -1,5 +1,5 @@
 import React from 'react'
-import { render } from '@testing-library/react'
+import { render, fireEvent } from '@testing-library/react'
 import { CrossHair } from './CrossHair.jsx'
 import { useCrossHair } from '../../hooks/useCrossHairAPI.js'
 
@@ -9,6 +9,9 @@ jest.mock('../../store/configContext', () => ({ useConfig: jest.fn(() => ({ id:
 describe('CrossHair', () => {
   const crossHairRef = React.createRef()
 
+  // Positioning/visibility/sizing all live on the outer <button> (tabIndex="-1" — a real,
+  // accessibility-focusable-but-not-Tab-stop element, so coordinate-based AT like Voice Control
+  // can find it, at the right geometry); the SVG itself is a plain, unstyled child.
   const renderWith = (overrides = {}) => {
     useCrossHair.mockReturnValue({
       crossHairRef,
@@ -19,43 +22,64 @@ describe('CrossHair', () => {
         ...overrides
       }
     })
-    return render(<CrossHair />).container.querySelector('svg')
+    const { container } = render(<CrossHair />)
+    return { button: container.querySelector('button'), svg: container.querySelector('svg') }
   }
 
   it('renders visible active marker when pinned', () => {
-    const svg = renderWith()
+    const { button, svg } = renderWith()
     const path = svg.querySelector('path')
 
-    expect(svg).toHaveClass('im-c-cross-hair')
-    expect(svg).toHaveStyle({
+    expect(button).toHaveClass('im-c-cross-hair-button')
+    expect(button).toHaveStyle({
       position: 'absolute',
       left: 0,
       top: 0,
-      pointerEvents: 'none',
       display: 'block'
     })
     expect(path.getAttribute('d')).toContain('M5.035 20H1v-2h4.035C5.525') // active path
   })
 
   it('positions marker at center when not pinned', () => {
-    const svg = renderWith({ isPinnedToMap: false })
+    const { button } = renderWith({ isPinnedToMap: false })
 
-    expect(svg).toHaveStyle({
+    expect(button).toHaveStyle({
       left: '50%',
       top: '50%'
     })
   })
 
+  // Fully removed from the layout/accessibility tree when hidden, not just faded — so Voice
+  // Control's Show Names never puts a "Target" label over nothing. Its real route back is
+  // opening MoveControls (a normal, always-visible button), not re-discovering this element.
   it('hides marker when not visible', () => {
-    const svg = renderWith({ isVisible: false })
-    expect(svg).toHaveStyle({ display: 'none' })
+    const { button } = renderWith({ isVisible: false })
+    expect(button).toHaveStyle({ display: 'none' })
+  })
+
+  it('invokes crossHair.activate() on click, for Voice Control / mouse / touch activation', () => {
+    const activate = jest.fn()
+    const { button } = renderWith({ activate })
+    fireEvent.click(button)
+    expect(activate).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not throw when clicked with no activate() assigned', () => {
+    const { button } = renderWith()
+    expect(() => fireEvent.click(button)).not.toThrow()
+  })
+
+  it('is not a Tab stop, but is a real button for coordinate-based AT (e.g. Voice Control) to find', () => {
+    const { button } = renderWith()
+    expect(button.tabIndex).toBe(-1)
+    expect(button.tagName).toBe('BUTTON')
   })
 
   it.each([
     ['inactive', 'M5.035 20H1v-2h4.035a13.98'],
     [undefined, 'M5.035 20H1v-2h4.035C5.525'] // fallback to active
   ])('renders correct path for state=%s', (state, expected) => {
-    const svg = renderWith({ state })
+    const { svg } = renderWith({ state })
     expect(svg.querySelector('path').getAttribute('d')).toContain(expected)
   })
 })

package/src/App/components/KeyboardHelp/KeyboardHelp.jsx

@@ -10,7 +10,10 @@ const DEFAULT_GROUP = 'Navigate'
 const ShortcutList = ({ items }) => (
   <dl className='im-c-keyboard-help__list'>
     {items.map((item) => (
-      <div key={item.id} className='im-c-keyboard-help__item'>
+      <div
+        key={item.id}
+        className={`im-c-keyboard-help__item${item.visuallyHidden ? ' im-u-visually-hidden' : ''}`}
+      >
         <dt className='im-c-keyboard-help__title'>{item.title}</dt>
         <dd className='im-c-keyboard-help__description' dangerouslySetInnerHTML={{ __html: item.command }} />
       </div>

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

@@ -68,6 +68,23 @@ describe('KeyboardHelp — flat list', () => {
     render(<KeyboardHelp />)
     expect(screen.getByText('↑')).toBeInTheDocument()
   })
+
+  it('visually hides a shortcut flagged visuallyHidden but keeps it in the DOM for assistive tech', () => {
+    getKeyboardShortcuts.mockReturnValue([
+      ...VIEWPORT_SHORTCUTS,
+      { id: 'sr', context: 'viewport', title: 'Get info', command: '<kbd>Alt</kbd> + <kbd>I</kbd>', visuallyHidden: true }
+    ])
+    render(<KeyboardHelp />)
+    const item = screen.getByText('Get info').closest('.im-c-keyboard-help__item')
+    expect(item).toHaveClass('im-u-visually-hidden')
+  })
+
+  it('does not visually hide a regular shortcut', () => {
+    getKeyboardShortcuts.mockReturnValue(VIEWPORT_SHORTCUTS)
+    render(<KeyboardHelp />)
+    const item = screen.getByText('Move').closest('.im-c-keyboard-help__item')
+    expect(item).not.toHaveClass('im-u-visually-hidden')
+  })
 })
 
 // ─── tab UI (multiple groups) ─────────────────────────────────────────────────

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

@@ -1,6 +1,7 @@
 // components/MapButton.jsx
 import React, { useState, useRef, useCallback } from 'react'
 import { stringToKebab } from '../../../utils/stringToKebab'
+import { getPanelElementId } from '../../../utils/getPanelElementId.js'
 import { Tooltip } from '../Tooltip/Tooltip'
 import { Icon } from '../Icon/Icon'
 import { SlotRenderer } from '../../renderer/SlotRenderer'
@@ -88,6 +89,10 @@ const makePopupKeyUpHandler = (hasMenu, buttonRefs, buttonId, setMenuStartPos, s
 const getButtonSlot = (panelId, buttonId) =>
   panelId ? `${stringToKebab(buttonId)}-button` : undefined
 
+// aria-haspopup only accepts these role-shaped tokens (plus 'true', unused here) — any other
+// controlled-element role (e.g. a panel's 'complementary'/'region') means no aria-haspopup.
+const HASPOPUP_ROLES = new Set(['menu', 'listbox', 'tree', 'grid', 'dialog'])
+
 /**
  * Determines the controlled element (panel or popup menu) for ARIA attributes.
  * @param {Object} options - Configuration options
@@ -95,14 +100,16 @@ const getButtonSlot = (panelId, buttonId) =>
  * @param {string} options.panelId - ID of the controlled panel (if applicable)
  * @param {string} options.buttonId - Unique button identifier
  * @param {boolean} options.hasMenu - Whether the button has a popup menu
- * @returns {Object|null} Object with id and type ('panel' or 'popup'), or null if no controlled element
+ * @param {string} [options.panelRole] - The controlled panel's own ARIA role (see getPanelRole.js),
+ *   used for aria-haspopup on the button — undefined when no panel is controlled.
+ * @returns {Object|null} Object with id, type ('panel' or 'popup') and role, or null if no controlled element
  */
-const getControlledElement = ({ idPrefix, panelId, buttonId, hasMenu }) => {
+const getControlledElement = ({ idPrefix, panelId, buttonId, hasMenu, panelRole }) => {
   if (panelId) {
-    return { id: `${idPrefix}-panel-${stringToKebab(panelId)}`, type: 'panel' }
+    return { id: getPanelElementId(idPrefix, panelId), type: 'panel', role: panelRole }
   }
   if (hasMenu) {
-    return { id: `${idPrefix}-popup-${stringToKebab(buttonId)}`, type: 'popup' }
+    return { id: `${idPrefix}-popup-${stringToKebab(buttonId)}`, type: 'popup', role: 'menu' }
   }
   return null
 }
@@ -168,7 +175,7 @@ const buildButtonProps = ({
     'aria-expanded': ariaExpanded,
     'aria-pressed': typeof isPressed === 'boolean' ? isPressed : undefined,
     'aria-controls': controlledElement?.id ?? ariaControls,
-    'aria-haspopup': controlledElement?.type === 'popup' ? 'menu' : undefined,
+    'aria-haspopup': HASPOPUP_ROLES.has(controlledElement?.role) ? controlledElement.role : undefined,
     ...(href
       ? { href, target: '_blank', onKeyUp: handleKeyUp, role: 'button' }
       : { type: 'button' })
@@ -191,6 +198,7 @@ const buildButtonProps = ({
  * @param {boolean} [props.isExpanded] - Whether content controlled by the button is expanded
  * @param {boolean} [props.isHidden=false] - Whether to hide the button (CSS display: none)
  * @param {boolean} [props.isPanelOpen=false] - Whether the controlled panel is open
+ * @param {string} [props.panelRole] - The controlled panel's own ARIA role, used for aria-haspopup
  * @param {string} [props.variant] - CSS variant class for styling (e.g., 'primary')
  * @param {Function} [props.onClick] - Custom click handler
  * @param {string} [props.panelId] - ID of the panel controlled by this button
@@ -212,6 +220,7 @@ export const MapButton = ({
   isExpanded,
   isHidden,
   isPanelOpen,
+  panelRole,
   variant,
   onClick,
   panelId,
@@ -239,7 +248,7 @@ export const MapButton = ({
   const hasMenu = menuItems?.length >= 1
   const showIcon = iconId || iconSvgContent || hasMenu
   const buttonSlot = getButtonSlot(panelId, buttonId)
-  const controlledElement = getControlledElement({ idPrefix, panelId, buttonId, hasMenu })
+  const controlledElement = getControlledElement({ idPrefix, panelId, buttonId, hasMenu, panelRole })
 
   /**
    * Handles button click events.
@@ -301,7 +310,10 @@ export const MapButton = ({
     >
       {showLabel ? buttonEl : <Tooltip content={label}>{buttonEl}</Tooltip>}
       {buttonSlot && <SlotRenderer slot={buttonSlot} />}
-      {isPopupOpen && <PopupMenu popupMenuId={controlledElement.id} buttonId={buttonId} startPos={menuStartPos} menuRef={menuRef} items={menuItems} setIsOpen={setIsPopupOpen} buttonRect={menuRect} />}
+      {/* Mounted permanently, not just while open, so its aria-controls id stays a stable node. */}
+      {controlledElement?.type === 'popup' && (
+        <PopupMenu popupMenuId={controlledElement.id} buttonId={buttonId} startPos={menuStartPos} menuRef={menuRef} items={menuItems} setIsOpen={setIsPopupOpen} buttonRect={menuRect} isOpen={isPopupOpen} />
+      )}
     </div>
   )
 }