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

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

@@ -0,0 +1,285 @@
+import React, { useRef } from 'react'
+import { render, fireEvent, act } from '@testing-library/react'
+import { SpatialList } from './SpatialList.jsx'
+import { useSpatialListFocus } from '../../hooks/useSpatialListFocus.js'
+import { useConfig } from '../../store/configContext.js'
+
+jest.mock('../../store/configContext.js', () => ({ useConfig: jest.fn() }))
+
+const APP_ID = 'test-app'
+const LISTBOX = '[role="listbox"]' // NOSONAR
+const OPTION = '[role="option"]' // NOSONAR
+const ARIA_SELECTED = 'aria-selected'
+const ITEMS = [
+  { id: 'f1', label: 'Feature One' },
+  { id: 'f2', label: 'Feature Two' }
+]
+
+beforeEach(() => {
+  useConfig.mockReturnValue({ id: APP_ID })
+})
+
+// ─── SpatialList — rendering ─────────────────────────────────────────────────────
+
+describe('SpatialList — rendering', () => {
+  it('renders a listbox with the correct id', () => {
+    const { container } = render(<SpatialList />)
+    expect(container.querySelector(`#${APP_ID}-spatial-list`)).toBeTruthy()
+    expect(container.querySelector(LISTBOX)).toBeTruthy() // NOSONAR
+  })
+
+  it('renders no options when items is empty', () => {
+    const { container } = render(<SpatialList />)
+    expect(container.querySelectorAll('[role="option"]')).toHaveLength(0) // NOSONAR
+  })
+
+  it('defaults aria-label to "Map features" when no label prop is given', () => {
+    const { container } = render(<SpatialList />)
+    expect(container.querySelector(LISTBOX).getAttribute('aria-label')).toBe('Map features')
+  })
+
+  it('uses whatever label prop is given, e.g. for draw\'s edit-mode vertices', () => {
+    const { container } = render(<SpatialList label='Shape points' />)
+    expect(container.querySelector(LISTBOX).getAttribute('aria-label')).toBe('Shape points')
+  })
+
+  it('renders one option per item with correct id, data-id and label', () => {
+    const { container } = render(<SpatialList items={ITEMS} />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options).toHaveLength(2)
+    expect(options[0].getAttribute('id')).toBe(`${APP_ID}-spatial-list-item-f1`)
+    expect(options[0].dataset.id).toBe('f1')
+    expect(options[0].textContent).toBe('Feature One')
+    expect(options[1].getAttribute('id')).toBe(`${APP_ID}-spatial-list-item-f2`)
+    expect(options[1].dataset.id).toBe('f2')
+    expect(options[1].textContent).toBe('Feature Two')
+  })
+
+  it('positions an option at its x/y when provided, for coordinate-based AT overlays (e.g. Voice Control)', () => {
+    const itemsWithPosition = [{ id: 'f1', label: 'Feature One', x: 120, y: 340 }]
+    const { container } = render(<SpatialList items={itemsWithPosition} />)
+    const option = container.querySelector(OPTION)
+    expect(option.style.left).toBe('120px')
+    expect(option.style.top).toBe('340px')
+  })
+
+  it('does not set left/top when an item has no x/y', () => {
+    const { container } = render(<SpatialList items={ITEMS} />)
+    const option = container.querySelector(OPTION)
+    expect(option.style.left).toBe('')
+    expect(option.style.top).toBe('')
+  })
+
+  it('sets aria-selected on items present in selectedIds', () => {
+    const { container } = render(<SpatialList items={ITEMS} selectedIds={['f1']} />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0]).toHaveAttribute(ARIA_SELECTED, 'true')
+    expect(options[1]).toHaveAttribute(ARIA_SELECTED, 'false')
+  })
+
+  it('sets aria-selected on multiple items when selectedIds has multiple entries', () => {
+    const { container } = render(<SpatialList items={ITEMS} selectedIds={['f1', 'f2']} />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0]).toHaveAttribute(ARIA_SELECTED, 'true')
+    expect(options[1]).toHaveAttribute(ARIA_SELECTED, 'true')
+  })
+
+  it('does not set aria-selected from activeItemId alone', () => {
+    const { container } = render(<SpatialList items={ITEMS} activeItemId='f1' />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0]).toHaveAttribute(ARIA_SELECTED, 'false')
+    expect(options[1]).toHaveAttribute(ARIA_SELECTED, 'false')
+  })
+
+  it('gives the active item tabIndex 0 and every other item tabIndex -1 (roving tabindex)', () => {
+    const { container } = render(<SpatialList items={ITEMS} activeItemId='f2' />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0].getAttribute('tabIndex')).toBe('-1')
+    expect(options[1].getAttribute('tabIndex')).toBe('0')
+  })
+
+  it('falls back to tabbableId for roving tabindex when activeItemId is absent', () => {
+    const { container } = render(<SpatialList items={ITEMS} tabbableId='f1' />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0].getAttribute('tabIndex')).toBe('0')
+    expect(options[1].getAttribute('tabIndex')).toBe('-1')
+  })
+
+  it('gives every item tabIndex -1 when focusable is false, even the active one — never a real Tab stop', () => {
+    const { container } = render(<SpatialList items={ITEMS} activeItemId='f2' focusable={false} />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0].getAttribute('tabIndex')).toBe('-1')
+    expect(options[1].getAttribute('tabIndex')).toBe('-1')
+  })
+
+  it('sets aria-multiselectable when multiselectable is true', () => {
+    const { container } = render(<SpatialList items={ITEMS} multiselectable />)
+    expect(container.querySelector(LISTBOX).getAttribute('aria-multiselectable')).toBe('true') // NOSONAR
+  })
+
+  it('omits aria-multiselectable when multiselectable is false', () => {
+    const { container } = render(<SpatialList items={ITEMS} />)
+    expect(container.querySelector(LISTBOX).getAttribute('aria-multiselectable')).toBeNull() // NOSONAR
+  })
+
+  it('is not aria-hidden when items are present', () => {
+    const { container } = render(<SpatialList items={ITEMS} />)
+    const ul = container.querySelector(LISTBOX) // NOSONAR
+    expect(ul.getAttribute('aria-hidden')).toBeNull()
+  })
+
+  it('is aria-hidden and has no options when items is empty', () => {
+    const { container } = render(<SpatialList />)
+    const ul = container.querySelector(LISTBOX) // NOSONAR
+    expect(ul.getAttribute('aria-hidden')).toBe('true')
+    expect(container.querySelectorAll(OPTION)).toHaveLength(0) // NOSONAR
+  })
+
+  it('sets aria-describedby to the shared hints container id', () => {
+    const { container } = render(<SpatialList />)
+    expect(container.querySelector(LISTBOX).getAttribute('aria-describedby')).toBe(`${APP_ID}-keyboard-desc`) // NOSONAR
+  })
+})
+
+// ─── SpatialList — interactions ──────────────────────────────────────────────────
+
+describe('SpatialList — interactions', () => {
+  it('calls onFocus when the listbox receives focus', () => {
+    const onFocus = jest.fn()
+    const { container } = render(<SpatialList onFocus={onFocus} />)
+    fireEvent.focus(container.querySelector(LISTBOX)) // NOSONAR
+    expect(onFocus).toHaveBeenCalled()
+  })
+
+  it('calls onBlur when the listbox loses focus', () => {
+    const onBlur = jest.fn()
+    const { container } = render(<SpatialList onBlur={onBlur} />)
+    fireEvent.blur(container.querySelector(LISTBOX)) // NOSONAR
+    expect(onBlur).toHaveBeenCalled()
+  })
+
+  it('calls onSelectItem with the clicked item id', () => {
+    const onSelectItem = jest.fn()
+    const { container } = render(<SpatialList items={ITEMS} onSelectItem={onSelectItem} />)
+    fireEvent.click(container.querySelectorAll(OPTION)[1]) // NOSONAR
+    expect(onSelectItem).toHaveBeenCalledWith('f2')
+  })
+
+  it('does not throw on click when onSelectItem is not provided', () => {
+    const { container } = render(<SpatialList items={ITEMS} />)
+    expect(() => fireEvent.click(container.querySelectorAll(OPTION)[0])).not.toThrow() // NOSONAR
+  })
+})
+
+// ─── SpatialList + useSpatialListFocus — roving tabindex wired together for real ────
+//
+// The tests above exercise SpatialList in isolation (mocked onFocus/onBlur), and
+// useSpatialListFocus.test.js exercises the hook in isolation (onFocus/onBlur called
+// directly, not via real DOM events). Neither can catch a bug where moving real focus
+// between sibling options — which roving tabindex does on every arrow key — fires a
+// genuine native focusin that bubbles up and re-triggers React's onFocus on the <ul>.
+// Only rendering both together with real (unmocked) focus exercises that bubbling path.
+
+const RovingHarness = ({ eventBus }) => {
+  const viewportRef = useRef(document.createElement('div'))
+  const spatialListRef = useRef(null)
+  const { activeItemId, tabbableId, selectedIds, onFocus, onBlur, selectItem } = useSpatialListFocus({
+    viewportRef, spatialListRef, items: ITEMS, eventBus, hints: { subscribe: () => () => {}, dismiss: () => {} }
+  })
+  return (
+    <SpatialList
+      ref={spatialListRef} activeItemId={activeItemId} tabbableId={tabbableId} selectedIds={selectedIds}
+      items={ITEMS} onFocus={onFocus} onBlur={onBlur} onSelectItem={selectItem}
+    />
+  )
+}
+
+describe('SpatialList + useSpatialListFocus — roving tabindex real focus events', () => {
+  it('emits map:setactivefeature exactly once when arrowing to the next option', () => {
+    const eb = { on: jest.fn(), off: jest.fn(), emit: jest.fn() }
+    const { container } = render(<RovingHarness eventBus={eb} />)
+    act(() => container.querySelector('[data-id="f1"]').focus())
+    eb.emit.mockClear()
+    fireEvent.keyDown(container.querySelector(LISTBOX), { key: 'ArrowDown' }) // NOSONAR
+    expect(eb.emit).toHaveBeenCalledTimes(1)
+    expect(eb.emit).toHaveBeenCalledWith('map:setactiveitem', { id: 'f2' })
+  })
+
+  it('moves real DOM focus to the next option on ArrowDown', () => {
+    const eb = { on: jest.fn(), off: jest.fn(), emit: jest.fn() }
+    const { container } = render(<RovingHarness eventBus={eb} />)
+    act(() => container.querySelector('[data-id="f1"]').focus())
+    fireEvent.keyDown(container.querySelector(LISTBOX), { key: 'ArrowDown' }) // NOSONAR
+    expect(document.activeElement.dataset.id).toBe('f2')
+  })
+
+  // A real pub/sub bus, with a minimal fake "interact plugin" listening on it — mirroring what
+  // useSpatialList.js actually does: track the last map:setactivefeature id, and on
+  // map:selectfeature, mark THAT id selected and fire interact:selectionchange back. This is
+  // the closest reproduction of the real reported bug: Enter only ever selecting the first item
+  // because every arrow move was clobbering the active id back to a stale value.
+  const makeFakeInteractBus = () => {
+    const listeners = {}
+    let lastActiveId = null
+    const bus = {
+      on: (event, fn) => { (listeners[event] ??= []).push(fn) },
+      off: (event, fn) => { listeners[event] = (listeners[event] ?? []).filter(f => f !== fn) },
+      emit: (event, payload) => { (listeners[event] ?? []).forEach(fn => fn(payload)) }
+    }
+    bus.on('map:setactiveitem', ({ id }) => { lastActiveId = id })
+    bus.on('map:selectitem', () => {
+      bus.emit('interact:selectionchange', { selectedMarkers: lastActiveId ? [lastActiveId] : [] })
+    })
+    return bus
+  }
+
+  it('selects the item that is actually focused, not the first item, after navigating and pressing Enter', () => {
+    const eb = makeFakeInteractBus()
+    const { container } = render(<RovingHarness eventBus={eb} />)
+    act(() => container.querySelector('[data-id="f1"]').focus())
+    const listbox = container.querySelector(LISTBOX)
+    fireEvent.keyDown(listbox, { key: 'ArrowDown' }) // NOSONAR — moves to f2
+    fireEvent.keyDown(listbox, { key: 'Enter' })
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0]).toHaveAttribute(ARIA_SELECTED, 'false') // f1 — must not be the one selected
+    expect(options[1]).toHaveAttribute(ARIA_SELECTED, 'true') // f2 — the one actually focused
+  })
+
+  it('keeps navigating correctly after a selection (does not get stuck reverting to the first item)', () => {
+    const eb = makeFakeInteractBus()
+    const { container } = render(<RovingHarness eventBus={eb} />)
+    act(() => container.querySelector('[data-id="f1"]').focus())
+    const listbox = container.querySelector(LISTBOX)
+    fireEvent.keyDown(listbox, { key: 'ArrowDown' }) // NOSONAR — f1 -> f2
+    fireEvent.keyDown(listbox, { key: 'Enter' }) // select f2
+    fireEvent.keyDown(listbox, { key: 'ArrowUp' }) // f2 -> f1
+    expect(document.activeElement.dataset.id).toBe('f1')
+    expect(container.querySelectorAll(OPTION)[0].tabIndex).toBe(0)
+  })
+
+  it('selecting a marker on the map does not move the roving tabindex position — only aria-selected changes', () => {
+    const eb = makeFakeInteractBus()
+    const { container } = render(<RovingHarness eventBus={eb} />)
+    // Simulates repeatedly clicking a single marker on the map — never touches the list at all.
+    act(() => { eb.emit('interact:selectionchange', { selectedMarkers: ['f1'] }) })
+    act(() => { eb.emit('interact:selectionchange', { selectedMarkers: ['f2'] }) })
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0].tabIndex).toBe(0) // f1 — the structural first item, unmoved
+    expect(options[1].tabIndex).toBe(-1)
+    expect(options[0]).toHaveAttribute(ARIA_SELECTED, 'false')
+    expect(options[1]).toHaveAttribute(ARIA_SELECTED, 'true') // only this changed
+  })
+
+  it('moves real focus to match the selected item when Tab lands somewhere else', () => {
+    const eb = makeFakeInteractBus()
+    const { container } = render(<RovingHarness eventBus={eb} />)
+    // f2 selected via a map click before any keyboard interaction — tabbableId stays on the
+    // structural first item (f1), so Tab lands there first.
+    act(() => { eb.emit('interact:selectionchange', { selectedMarkers: ['f2'] }) })
+    expect(container.querySelectorAll(OPTION)[0].tabIndex).toBe(0) // Tab will land on f1
+    act(() => container.querySelector('[data-id="f1"]').focus()) // simulates the Tab press
+    // onFocus resolves to the selected item (f2) and must move real focus there to match —
+    // otherwise the list's own focus/announcement would disagree with what the map highlights.
+    expect(document.activeElement.dataset.id).toBe('f2')
+  })
+})

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

@@ -1,7 +1,8 @@
 import React, { useRef, useEffect } from 'react'
-import { useFeatureFocus } from '../../hooks/useFeatureFocus.js'
-import { useFeatureItems } from '../../hooks/useFeatureItems.js'
+import { useSpatialListFocus } from '../../hooks/useSpatialListFocus.js'
+import { useSpatialListItems } from '../../hooks/useSpatialListItems.js'
 import { EVENTS as events } from '../../../config/events.js'
+import { scaleFactor } from '../../../config/appConfig.js'
 import { useConfig } from '../../store/configContext.js'
 import { useApp } from '../../store/appContext.js'
 import { useMap } from '../../store/mapContext.js'
@@ -12,7 +13,7 @@ import { useKeyboardShortcuts } from '../../hooks/useKeyboardShortcuts.js'
 import { useMapEvents } from '../../hooks/useMapEvents.js'
 import { MapStatus } from './MapStatus.jsx'
 import { CrossHair } from '../CrossHair/CrossHair'
-import { Features } from './Features'
+import { SpatialList } from './SpatialList'
 import { Markers } from '../Markers/Markers'
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
@@ -20,14 +21,23 @@ import { Markers } from '../Markers/Markers'
 export const Viewport = () => {
   const { id, mapProvider, mapLabel, keyboardHintText, focusOnMount } = useConfig()
   const { mode, previousMode, layoutRefs, safeZoneInset, dispatch } = useApp()
-  const { mapSize } = useMap()
+  const { mapSize, isMapReady } = useMap()
   const { eventBus, hints } = useService()
 
   const mapContainerRef = useRef(null)
-  const featuresRef = useRef(null)
+  const spatialListRef = useRef(null)
 
-  const { items: featureItems, multiselectable } = useFeatureItems(eventBus)
-  const { activeFeatureId, selectedIds, onFocus: handleFeaturesFocus, onBlur: handleFeaturesBlur } = useFeatureFocus({ viewportRef: layoutRefs.viewportRef, featuresRef, items: featureItems, eventBus, hints })
+  const { items: spatialListItems, multiselectable, label: spatialListLabel, focusable: spatialListFocusable } = useSpatialListItems(eventBus)
+  // Same reference point as Alt+Enter's highlightLabelAtCenter — lets the listbox's entry
+  // fallback prefer whichever item is nearest the middle of the view. Guarded on isMapReady:
+  // the map engine doesn't exist yet on Viewport's first render, so mapToScreen()/getCenter()
+  // would throw; null is a safe, already-handled value (falls back to the first item).
+  let centerScreenPoint = null
+  if (isMapReady) {
+    const centerPixel = mapProvider.mapToScreen(mapProvider.getCenter())
+    centerScreenPoint = { x: centerPixel.x * scaleFactor[mapSize], y: centerPixel.y * scaleFactor[mapSize] }
+  }
+  const { activeItemId, tabbableId, selectedIds, onFocus: handleSpatialListFocus, onBlur: handleSpatialListBlur, selectItem } = useSpatialListFocus({ viewportRef: layoutRefs.viewportRef, spatialListRef, items: spatialListItems, eventBus, hints, centerScreenPoint })
 
   useEffect(() => {
     const handler = () => dispatch({ type: 'SET_LISTBOX_ACTIVE' })
@@ -35,8 +45,8 @@ export const Viewport = () => {
     return () => eventBus.off('interact:listboxcapable', handler)
   }, [eventBus])
 
-  const onFeaturesFocus = () => { handleFeaturesFocus(); hints.show(keyboardHintText, { duration: 0 }) }
-  const onFeaturesBlur = () => { handleFeaturesBlur(); hints.dismiss() }
+  const onSpatialListFocus = () => { handleSpatialListFocus(); hints.show(keyboardHintText, { duration: 0 }) }
+  const onSpatialListBlur = () => { handleSpatialListBlur(); hints.dismiss() }
 
   useKeyboardShortcuts(layoutRefs.viewportRef)
 
@@ -87,14 +97,14 @@ export const Viewport = () => {
       >
         <div className='im-c-viewport__map-container' ref={mapContainerRef} aria-hidden='true' />
         <MapStatus />
-        <div className='im-c-viewport__safezone' style={safeZoneInset} ref={layoutRefs.safeZoneRef} aria-hidden='true'>
+        <div className='im-c-viewport__safezone' style={safeZoneInset} ref={layoutRefs.safeZoneRef}>
           <CrossHair />
         </div>
         <div className='im-c-viewport__markers' aria-hidden='true'>
           <Markers />
         </div>
       </div>
-      <Features ref={featuresRef} activeFeatureId={activeFeatureId} selectedIds={selectedIds} multiselectable={multiselectable} items={featureItems} onFocus={onFeaturesFocus} onBlur={onFeaturesBlur} />
+      <SpatialList ref={spatialListRef} activeItemId={activeItemId} tabbableId={tabbableId} selectedIds={selectedIds} multiselectable={multiselectable} items={spatialListItems} label={spatialListLabel} focusable={spatialListFocusable} onFocus={onSpatialListFocus} onBlur={onSpatialListBlur} onSelectItem={selectItem} />
     </>
   )
 }

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

@@ -21,7 +21,13 @@ jest.mock('../Markers/Markers', () => ({ Markers: jest.fn(() => <div data-testid
 
 const KEYBOARD_HINT_TEXT = 'Test keyboad hint text'
 
-const mockMapProvider = { initMap: jest.fn(), updateMap: jest.fn(), clearHighlightedLabel: jest.fn() }
+const mockMapProvider = {
+  initMap: jest.fn(),
+  updateMap: jest.fn(),
+  clearHighlightedLabel: jest.fn(),
+  getCenter: jest.fn(() => [0, 0]),
+  mapToScreen: jest.fn(() => ({ x: 100, y: 100 }))
+}
 
 function setupHookMocks (mainEl, viewportEl) {
   useConfig.mockReturnValue({
@@ -38,7 +44,7 @@ function setupHookMocks (mainEl, viewportEl) {
     safeZoneInset: {},
     dispatch: jest.fn()
   })
-  useMap.mockReturnValue({ mapSize: 'medium', dispatch: jest.fn() })
+  useMap.mockReturnValue({ mapSize: 'medium', isMapReady: true, dispatch: jest.fn() })
   useService.mockReturnValue({
     announce: jest.fn(),
     hints: { show: jest.fn(), dismiss: jest.fn(), subscribe: jest.fn(() => jest.fn()) },
@@ -89,6 +95,16 @@ describe('Viewport rendering', () => {
     expect(markers).toBeInTheDocument()
   })
 
+  // Regression: Viewport (and MapController, which kicks off map creation) render before the
+  // underlying map engine actually exists — mapProvider.getCenter()/mapToScreen() throw until
+  // then, so the spatial listbox's "nearest to center" entry point must not call them yet.
+  it('does not throw, and skips mapProvider.getCenter/mapToScreen, before the map is ready', () => {
+    useMap.mockReturnValue({ mapSize: 'medium', isMapReady: false, dispatch: jest.fn() })
+    expect(() => renderViewport()).not.toThrow()
+    expect(mockMapProvider.getCenter).not.toHaveBeenCalled()
+    expect(mockMapProvider.mapToScreen).not.toHaveBeenCalled()
+  })
+
   it('renders viewport with correct id and class based on mapSize', () => {
     const { viewport } = renderViewport()
     expect(viewport.id).toBe('test-map-viewport')

package/src/App/controls/keyboardMappings.js

@@ -1,3 +1,8 @@
+import { isMac } from '../../utils/isMac.js'
+
+// getInfo uses Ctrl on Windows/Linux (Alt+letter is reserved for menu mnemonics there) and Alt/Option on Mac — keep in sync with keyboardShortcuts.js's `infoKeyHtml`.
+const infoModifier = isMac() ? 'Alt' : 'Ctrl'
+
 export const keyboardMappings = {
   keydown: {
     ArrowUp: 'panUp',
@@ -17,8 +22,8 @@ export const keyboardMappings = {
     'Alt+ArrowUp': 'highlightNextLabel',
     'Alt+ArrowDown': 'highlightNextLabel',
     'Alt+Enter': 'highlightLabelAtCenter',
-    'Alt+i': 'getInfo',
-    'Alt+I': 'getInfo',
+    [`${infoModifier}+i`]: 'getInfo',
+    [`${infoModifier}+I`]: 'getInfo',
     Escape: 'clearSelection'
   }
 }

package/src/App/controls/keyboardMappings.test.js

@@ -0,0 +1,21 @@
+describe('keyboardMappings', () => {
+  beforeEach(() => jest.resetModules())
+
+  const load = () => require('./keyboardMappings.js').keyboardMappings
+
+  it('binds getInfo to Alt+i/Alt+I on Mac', () => {
+    Object.defineProperty(navigator, 'platform', { value: 'MacIntel', configurable: true })
+    const { keyup } = load()
+    expect(keyup['Alt+i']).toBe('getInfo')
+    expect(keyup['Alt+I']).toBe('getInfo')
+    expect(keyup['Ctrl+i']).toBeUndefined()
+  })
+
+  it('binds getInfo to Ctrl+i/Ctrl+I on non-Mac', () => {
+    Object.defineProperty(navigator, 'platform', { value: 'Win32', configurable: true })
+    const { keyup } = load()
+    expect(keyup['Ctrl+i']).toBe('getInfo')
+    expect(keyup['Ctrl+I']).toBe('getInfo')
+    expect(keyup['Alt+i']).toBeUndefined()
+  })
+})

package/src/App/controls/keyboardShortcuts.js

@@ -1,6 +1,9 @@
 // src/controls/keyboardShortcuts.js
-const isMac = /mac/i.test(navigator.userAgentData?.platform ?? navigator.platform)
-const altKeyHtml = isMac ? '<kbd>Option</kbd>' : '<kbd>Alt</kbd>'
+import { isMac } from '../../utils/isMac.js'
+
+const altKeyHtml = isMac() ? '<kbd>Option</kbd>' : '<kbd>Alt</kbd>'
+// getInfo uses Ctrl on Windows/Linux instead of Alt, which is reserved there for menu mnemonics.
+const infoKeyHtml = isMac() ? '<kbd>Option</kbd>' : '<kbd>Ctrl</kbd>'
 
 export const coreShortcuts = [
   {
@@ -10,6 +13,17 @@ export const coreShortcuts = [
     context: 'global',
     enabled: true
   },
+  {
+    id: 'getInfo',
+    title: 'Get current location and visible area',
+    command: `${infoKeyHtml} + <kbd>I</kbd>`,
+    enabled: true,
+    // No visual equivalent, so hide the row from sighted users but keep it discoverable via assistive tech.
+    visuallyHidden: true,
+    // Only needs getCenter/getZoom, which every map provider implements, so no adapter needs to declare it.
+    mapProviderAgnostic: true,
+    requiredConfig: ['reverseGeocodeProvider']
+  },
   {
     id: 'moveLarge',
     title: 'Move in large steps',

package/src/App/controls/keyboardShortcuts.test.js

@@ -21,4 +21,25 @@ describe('keyboardShortcuts', () => {
       expect(s.command).toContain('<kbd>Alt</kbd>')
     })
   })
+
+  it('marks getInfo as visuallyHidden, map-provider-agnostic and requiring reverseGeocodeProvider', () => {
+    const shortcuts = load()
+    const getInfo = shortcuts.find(s => s.id === 'getInfo')
+    expect(getInfo).toMatchObject({
+      visuallyHidden: true,
+      mapProviderAgnostic: true,
+      requiredConfig: ['reverseGeocodeProvider']
+    })
+  })
+
+  it('uses Ctrl for getInfo on non-Mac and Option on Mac', () => {
+    Object.defineProperty(navigator, 'platform', { value: 'MacIntel', configurable: true })
+    let getInfo = load().find(s => s.id === 'getInfo')
+    expect(getInfo.command).toContain('<kbd>Option</kbd>')
+
+    jest.resetModules()
+    Object.defineProperty(navigator, 'platform', { value: 'Win32', configurable: true })
+    getInfo = load().find(s => s.id === 'getInfo')
+    expect(getInfo.command).toContain('<kbd>Ctrl</kbd>')
+  })
 })

package/src/App/hooks/useCrossHairAPI.js

@@ -32,7 +32,19 @@ const assignCrossHairAPI = (crossHair, el, mapProvider, dispatch, updatePosition
     dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: true } })
   }
 
+  // Fully hidden — display:none, not just faded — rather than staying in the accessibility
+  // tree while invisible. An earlier version kept it ax-tree-present here so Voice Control
+  // could re-summon it by name, but that made "Show Names" put a "Target" label over
+  // nothing whenever it was genuinely hidden, which is more confusing than helpful. Voice
+  // Control's real route back is opening MapControls (a normal, always-visible, always-named
+  // button) — see isMapControlsOpen below — so the crosshair itself doesn't need to stay
+  // discoverable while it's not actually there. Blocked outright while MapControls is open:
+  // that panel is a deliberate, explicit "I can't drag/pinch this map" signal from the user,
+  // which should win over whatever mouse-vs-touch/keyboard inference would otherwise decide.
   crossHair.hide = () => {
+    if (crossHair.isMapControlsOpen) {
+      return
+    }
     el.style.display = 'none'
     dispatch({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: false } })
   }
@@ -55,7 +67,7 @@ const assignCrossHairAPI = (crossHair, el, mapProvider, dispatch, updatePosition
 
 export const useCrossHair = () => {
   const { mapProvider } = useConfig()
-  const { safeZoneInset } = useApp()
+  const { safeZoneInset, expandedButtons } = useApp()
   const { eventBus } = useService()
   const { crossHair, dispatch, mapSize } = useMap()
 
@@ -98,6 +110,22 @@ export const useCrossHair = () => {
     }
   }, [mapSize])
 
+  // A plain property on the shared crossHair object, not dispatched state — every owner
+  // (draw's per-adapter modes, interact's useCrossHairVisibility) already holds this same
+  // object, so mutating it here is all that's needed for hide()'s own guard above to see the
+  // current value live, however long ago it was last set. This alone never shows or hides
+  // anything by itself — it only ever blocks a hide() call already in flight — so it's safe to
+  // run unconditionally even when no plugin that cares about it is loaded at all.
+  //
+  // Deliberately NOT a useEffect: this component's own effects and interact's/draw's own
+  // updateCrossHair effects both react to the same expandedButtons change, and React gives no
+  // ordering guarantee between two different components' effects — if the consumer's effect
+  // (which decides to call hide()) ran before this one updated the flag, hide()'s guard would
+  // read the stale value and incorrectly block itself. Setting it directly in the render body
+  // (matches DrawInit.jsx's shouldShowCrosshairRef convention) guarantees it's current before
+  // ANY component's effects run, since React finishes rendering the whole tree first.
+  crossHair.isMapControlsOpen = expandedButtons?.has('mapControls')
+
   return {
     crossHair,
     crossHairRef

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

@@ -35,7 +35,7 @@ describe('useCrossHair', () => {
     eventBus.off = jest.fn()
 
     useConfig.mockReturnValue({ mapProvider: mockMapProvider })
-    useApp.mockReturnValue({ safeZoneInset: { left: 10, top: 20 } })
+    useApp.mockReturnValue({ safeZoneInset: { left: 10, top: 20 }, expandedButtons: new Set() })
     useService.mockReturnValue({ eventBus: mockEventBus })
     useMap.mockReturnValue({
       crossHair: mockCrossHair,
@@ -98,6 +98,22 @@ describe('useCrossHair', () => {
     expect(mockElement.style.display).toBe('none')
   })
 
+  it('hide() is a no-op while isMapControlsOpen is set', () => {
+    setup()
+    act(() => mockCrossHair.show())
+    mockCrossHair.isMapControlsOpen = true
+
+    act(() => mockCrossHair.hide())
+    expect(mockElement.style.display).toBe('block')
+    expect(mockDispatch).not.toHaveBeenCalledWith({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: false } })
+  })
+
+  it('keeps crossHair.isMapControlsOpen synced with expandedButtons, set synchronously during render (not a useEffect) so it is never stale relative to another component\'s own effect reacting to the same change', () => {
+    useApp.mockReturnValue({ safeZoneInset: { left: 10, top: 20 }, expandedButtons: new Set(['mapControls']) })
+    setup()
+    expect(mockCrossHair.isMapControlsOpen).toBe(true)
+  })
+
   it('setStyle updates state', () => {
     setup()
     act(() => mockCrossHair.setStyle('highlighted'))

package/src/App/hooks/useHintsAPI.js

@@ -32,9 +32,9 @@ export const useHintsAPI = () => {
   }, [eventBus, hints])
 
   // Escape dismisses the active hint when the keypress originates inside this
-  // map instance. The viewport and features listbox already dismiss hints on
+  // map instance. The viewport and spatial listbox already dismiss hints on
   // Escape within their own narrower focus scope (useKeyboardHint.js /
-  // useFeatureFocus.js) — this covers hints shown via the public showHint()
+  // useSpatialListFocus.js) — this covers hints shown via the public showHint()
   // API from anywhere else in the same map's UI (e.g. a plugin button).
   //
   // Listening on document (rather than the map's own container) and checking
@@ -51,12 +51,12 @@ export const useHintsAPI = () => {
   }, [hints])
 
   useEffect(() => {
-    const handleKeyDown = (e) => {
-      if (e.key !== 'Escape' || !isHintActiveRef.current) {
+    const handleKeyDown = (event) => {
+      if (event.key !== 'Escape' || !isHintActiveRef.current) {
         return
       }
       const container = layoutRefs.appContainerRef?.current
-      if (container && !container.contains(e.target)) {
+      if (container && !container.contains(event.target)) {
         return
       }
       hints.dismiss()

package/src/App/hooks/useInterfaceAPI.js

@@ -58,7 +58,8 @@ export const useInterfaceAPI = () => {
     const handleAppClosed = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: false })
     const handleAddPanel = ({ id, config }) => dispatchRef.current({ type: 'ADD_PANEL', payload: { id, config } })
     const handleRemovePanel = (id) => dispatchRef.current({ type: 'REMOVE_PANEL', payload: id })
-    const handleShowPanel = ({ id, focus = true }) => dispatchRef.current({ type: 'OPEN_PANEL', payload: { panelId: id, focusOnOpen: focus } })
+    const handleShowPanel = ({ id, focus = true, triggeringElement }) =>
+      dispatchRef.current({ type: 'OPEN_PANEL', payload: { panelId: id, focusOnOpen: focus, props: triggeringElement ? { triggeringElement } : undefined } })
     const handleHidePanel = (id) => dispatchRef.current({ type: 'CLOSE_PANEL', payload: id })
     const handleAddControl = ({ id, config }) => dispatchRef.current({ type: 'ADD_CONTROL', payload: { id, config } })
 

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

@@ -92,6 +92,15 @@ describe('useInterfaceAPI', () => {
     expect(mockDispatch).toHaveBeenCalledWith({ type: 'OPEN_PANEL', payload: { panelId: 'panel1', focusOnOpen: false } })
   })
 
+  it('dispatches OPEN_PANEL with props.triggeringElement when one is given, so Panel can return focus to it on close', () => {
+    const triggeringElement = document.createElement('button')
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:showpanel', { id: 'panel1', triggeringElement }))
+    expect(mockDispatch).toHaveBeenCalledWith({
+      type: 'OPEN_PANEL', payload: { panelId: 'panel1', focusOnOpen: true, props: { triggeringElement } }
+    })
+  })
+
   it('dispatches CLOSE_PANEL on app:hidepanel', () => {
     renderHook(() => useInterfaceAPI())
     act(() => mockEventBus.emit('app:hidepanel', 'panel1'))