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

package/scripts/publish-package.sh

@@ -5,6 +5,12 @@ set -e
 VERSION_PATTERN="^v([0-9]{1,}.[0-9]{1,}.[0-9]{1,})(-[0-9A-Za-z-].*)?$"
 PRE_RELEASE_PATTERN="(-[0-9A-Za-z-].*)$"
 
+# Prerelease labels (case-insensitive) that share the "pre-release" npm dist-tag.
+# Any other label (e.g. an experimental feature slug) gets isolated to its own
+# dist-tag instead — see determine_release_tag(). Add to this list if another
+# shared-channel convention (e.g. "rc") is adopted.
+SHARED_PRERELEASE_LABELS=("alpha" "beta")
+
 validate_arguments() {
   if [ -z "$TAG_NAME" ]; then
     echo "ERROR: TAG_NAME is required"
@@ -52,7 +58,37 @@ validate_version_bump() {
   echo "✓ Version check passed"
 }
 
+is_shared_prerelease_label() {
+  local candidate_lower
+  candidate_lower=$(echo "$1" | tr '[:upper:]' '[:lower:]')
+
+  local shared_label
+  for shared_label in "${SHARED_PRERELEASE_LABELS[@]}"; do
+    if [[ "$candidate_lower" == "$shared_label" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
 determine_release_tag() {
+  # Extract the first prerelease identifier: semver splits identifiers on '.',
+  # so this stops at the first dot if there is one ("-fmp.2" -> "fmp"), or runs
+  # to the end of the string if there isn't ("-fmp-2" -> "fmp-2", since hyphens
+  # are legal inside a single identifier). Anything not in
+  # SHARED_PRERELEASE_LABELS (matched case-insensitively) gets isolated to its
+  # own npm dist-tag either way — this is what prevents a mistyped experimental
+  # tag from silently landing in the shared "pre-release" channel, regardless
+  # of whether a dot or hyphen was used before the build number, or how the
+  # label happens to be capitalised.
+  if [[ "$TAG_NAME" =~ -([^.]+) ]]; then
+    local label="${BASH_REMATCH[1]}"
+    if ! is_shared_prerelease_label "$label"; then
+      echo "$label"
+      return
+    fi
+  fi
+
   if [[ "$IS_PRE_RELEASE" == "true" ]] || [[ "$TAG_NAME" =~ $PRE_RELEASE_PATTERN ]]; then
     echo "pre-release"
   else

package/src/App/App.jsx

@@ -19,7 +19,7 @@ export const App = (props) => {
   return (
     <AppProvider options={props}>
       <MapProvider options={props}>
-        <ServiceProvider eventBus={props.eventBus}>
+        <ServiceProvider eventBus={props.eventBus} pluginRegistry={props.pluginRegistry}>
           <PluginProvider>
             <PluginInits />
             <Layout />

package/src/App/App.test.jsx

@@ -70,7 +70,8 @@ describe('App', () => {
   })
 
   test('renders component hierarchy with props', () => {
-    const props = { mapProvider: 'test', extraProp: 'value', eventBus: mockEventBus }
+    const mockPluginRegistry = { getPlugin: jest.fn() }
+    const props = { mapProvider: 'test', extraProp: 'value', eventBus: mockEventBus, pluginRegistry: mockPluginRegistry }
 
     render(<App {...props} />)
 
@@ -98,6 +99,10 @@ describe('App', () => {
     // Verify eventBus exists
     expect(appProviderProps.options.eventBus).toBe(mockEventBus)
     expect(mapProviderProps.options.eventBus).toBe(mockEventBus)
+
+    // Verify pluginRegistry reaches ServiceProvider
+    const serviceProviderProps = ServiceProvider.mock.calls[0][0]
+    expect(serviceProviderProps.pluginRegistry).toBe(mockPluginRegistry)
   })
 
   test('calls removeLoadingState and emits APP_READY on mount', () => {

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

@@ -16,24 +16,38 @@ 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'
+      // "Target" — short for Voice Control to say ("Click Target"). A plain attribute, not a
+      // hidden child <span>, so there's no separate text node for Chrome's AX tree to expose.
+      aria-label='Target'
+      // This button should never take real DOM focus — a screen reader's virtual cursor and
+      // Voice Control can both reach it without that, and real focus landing here would break
+      // keyboard drawing (which requires focus to stay on the viewport container).
+      onMouseDown={(event) => event.preventDefault()}
+      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>
+      {/* aria-hidden: without it, WebKit exposes the <path> as its own accessibility node, and
+          Voice Control activates that instead of bubbling a click up to this button. */}
+      <svg
+        width='38'
+        height='38'
+        viewBox='0 0 38 38'
+        fillRule='evenodd'
+        fill='currentColor'
+        aria-hidden='true'
+      >
+        <path d={paths[state || 'active']} />
+      </svg>
+    </button>
   )
 }

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

@@ -1,14 +1,39 @@
-.im-c-cross-hair {
-  position: absolute;
-  top: 0;
-  left: 0;
-  pointer-events: none;
+// A real <button> (tabIndex="-1") so it's a discoverable target for AT (Voice Control, a screen
+// reader's virtual cursor) without being a Tab stop or ever taking real DOM focus.
+.im-c-cross-hair-button {
+  // Its ancestor (.im-c-viewport__safezone) is pointer-events:none, so this has to opt back in
+  // itself or clicks here pass straight through to the map canvas underneath.
+  pointer-events: auto;
+
+  // Reset native chrome to zero — 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 plus the negative margin centre the button's own geometry (not just its SVG
+  // child's) on wherever CrossHair.jsx's inline top/left positions it — without it, an AT
+  // overlay's 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;
-}
+  outline: 3px solid transparent;
+
+  svg {
+    display: block;
+    // Purely decorative (aria-hidden in CrossHair.jsx) — without this it's still its own
+    // hit-testable target, so a click could resolve to the icon instead of the button.
+    pointer-events: none;
+  }
+
+  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,8 @@ 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", discoverable
+  // by AT like Voice Control without being a Tab stop); the SVG itself is a plain, unstyled child.
   const renderWith = (overrides = {}) => {
     useCrossHair.mockReturnValue({
       crossHairRef,
@@ -19,43 +21,70 @@ 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 MapControls (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('prevents the default mousedown so a real click never gives it focus (or the resulting outline)', () => {
+    const { button } = renderWith()
+    const event = fireEvent.mouseDown(button)
+    expect(event).toBe(false) // fireEvent returns false when preventDefault() was called
+  })
+
+  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/Hints/Hints.jsx

@@ -17,7 +17,7 @@ import { htmlToPlainText } from '../../../utils/htmlToPlainText.js'
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
 export const Hints = () => {
-  const { id, keyboardHintText, enableMoveControls, moveControlsHintText } = useConfig()
+  const { id, keyboardHintText, enableMapControls, mapControlsHintText } = useConfig()
   const { hints } = useService()
   const { layoutRefs } = useApp()
   const [activeHint, setActiveHint] = useState(null)
@@ -33,8 +33,8 @@ export const Hints = () => {
   }
 
   // Composed at render time so overriding one text doesn't drop the other.
-  const keyboardDescriptionHtml = enableMoveControls
-    ? `${keyboardHintText} ${moveControlsHintText}`
+  const keyboardDescriptionHtml = enableMapControls
+    ? `${keyboardHintText} ${mapControlsHintText}`
     : keyboardHintText
 
   return createPortal(

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

@@ -52,13 +52,13 @@ describe('Hints — rendering', () => {
     expect(desc.innerHTML).toBe('Shift + ?')
   })
 
-  it('appends the move-controls hint text when enableMoveControls is true', () => {
+  it('appends the map-controls hint text when enableMapControls is true', () => {
     const mainEl = setup()
     useConfig.mockReturnValue({
       id: 'test-map',
       keyboardHintText: '<kbd>Shift</kbd> + <kbd>?</kbd>',
-      enableMoveControls: true,
-      moveControlsHintText: '<kbd>Arrow keys</kbd> to move'
+      enableMapControls: true,
+      mapControlsHintText: '<kbd>Arrow keys</kbd> to move'
     })
     render(<Hints />)
     const desc = mainEl.querySelector('#test-map-keyboard-desc')

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>
   )
 }

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

@@ -30,8 +30,7 @@
     justify-content: center;
     align-items: center;
 
-    padding-left: var(--button-padding);
-    padding-right: var(--button-padding);
+    padding: 0 var(--button-padding) 0 var(--button-padding);
 
     pointer-events: auto;
     color: var(--foreground-color);

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/{MoveControls/MoveControls.jsx → MapControls/MapControls.jsx}

@@ -18,13 +18,13 @@ const ZOOM_ACTIONS = [
   { id: 'nudgeZoomOut', label: 'Zoom out', announceLabel: 'Zoomed out', method: 'zoomOut' }
 ]
 
-export const MoveControls = () => {
+export const MapControls = () => {
   const { id: appId, mapProvider, panDelta, nudgePanDelta, zoomDelta, nudgeZoomDelta } = useConfig()
   const { dispatch, expandedButtons, nudgeStepSize, interfaceType, layoutRefs } = useApp()
   const { isAtMaxZoom, isAtMinZoom } = useMap()
   const { announce } = useService()
 
-  const isOpen = expandedButtons.has('moveControls')
+  const isOpen = expandedButtons.has('mapControls')
   const firstDirectionButtonId = `${appId}-pan-up`
 
   useEffect(() => {
@@ -41,7 +41,7 @@ export const MoveControls = () => {
   // Registry buttons (declared via a plugin's manifest) auto-return focus to the map
   // viewport after a click (see createButtonClickHandler in mapButtons.js) unless
   // marked keepFocus — which is how e.g. draw's own toolbar buttons never leave
-  // keyboard shortcuts (like arrow-key vertex nudging) stranded afterward. MoveControls
+  // keyboard shortcuts (like arrow-key vertex nudging) stranded afterward. MapControls
   // renders its own buttons directly, bypassing that mechanism entirely, so it has to
   // replicate the same return-to-viewport behaviour itself. But unlike a one-off
   // action button, the D-pad is meant to be pressed repeatedly — a keyboard/switch
@@ -70,7 +70,7 @@ export const MoveControls = () => {
 
     // Any plugin can claim the D-pad for something other than panning the map (e.g.
     // moving a selected draw vertex) by setting mapProvider.activeMoveTarget — a
-    // generic { move(dx, dy, isLargeStep), label? } contract. MoveControls doesn't
+    // generic { move(dx, dy, isLargeStep), label? } contract. MapControls doesn't
     // know or care what's claiming it; it just checks for a claimant before
     // defaulting to its own panBy behaviour. Read fresh on every click rather than
     // subscribed to reactively, since it's a plain mapProvider property, not state.
@@ -107,7 +107,7 @@ export const MoveControls = () => {
   // first tabbing all the way back to the map. Handling arrow keys here — while
   // focus is anywhere within this control, not just on a direction button — covers
   // that directly, without needing draw's (or the app's own) keyboard-shortcut
-  // guards to special-case MoveControls' buttons. Only arrow keys are handled;
+  // guards to special-case MapControls' buttons. Only arrow keys are handled;
   // other shortcuts (delete/escape/undo) still require focus on the viewport,
   // which mouse/touch users already get back automatically after any click here.
   const handleContainerKeyDown = (e) => {
@@ -120,12 +120,12 @@ export const MoveControls = () => {
   }
 
   const containerClassName = [
-    'im-c-move-controls',
-    !isOpen && 'im-c-move-controls--collapsed'
+    'im-c-map-controls',
+    !isOpen && 'im-c-map-controls--collapsed'
   ].filter(Boolean).join(' ')
 
   const directionsGroup = (
-    <div key='directions' role='group' aria-label='Direction controls' className='im-c-move-controls__directions'>{/* NOSONAR - div with role="group" is correct for a button group */}
+    <div key='directions' role='group' aria-label='Direction controls' className='im-c-map-controls__directions'>{/* NOSONAR - div with role="group" is correct for a button group */}
       {DIRECTIONS.map(({ id, verb, dx, dy }) => (
         <MapButton
           key={id}
@@ -154,7 +154,7 @@ export const MoveControls = () => {
   )
 
   const zoomGroup = (
-    <div key='zoom' role='group' aria-label='Zoom controls' className='im-c-move-controls__zoom'>{/* NOSONAR - div with role="group" is correct for a button group */}
+    <div key='zoom' role='group' aria-label='Zoom controls' className='im-c-map-controls__zoom'>{/* NOSONAR - div with role="group" is correct for a button group */}
       {ZOOM_ACTIONS.map(({ id, label, announceLabel, method }) => (
         <MapButton
           key={id}
@@ -169,7 +169,7 @@ export const MoveControls = () => {
   )
 
   return (
-    <div id={`${appId}-move-controls-content`} className={containerClassName} onKeyDown={handleContainerKeyDown} data-map-keyboard-scope>{/* NOSONAR - only catches arrow-key bubbling from the real, already-focusable button descendants below; the div itself needs no role/tabIndex */}
+    <div id={`${appId}-map-controls-content`} className={containerClassName} onKeyDown={handleContainerKeyDown} data-map-keyboard-scope>{/* NOSONAR - only catches arrow-key bubbling from the real, already-focusable button descendants below; the div itself needs no role/tabIndex */}
       {directionsGroup}
       {zoomGroup}
     </div>