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

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

@@ -1,6 +1,7 @@
-import React from 'react'
-import { render, fireEvent } from '@testing-library/react'
+import React, { useRef } from 'react'
+import { render, fireEvent, act } from '@testing-library/react'
 import { Features } from './Features.jsx'
+import { useFeatureFocus } from '../../hooks/useFeatureFocus.js'
 import { useConfig } from '../../store/configContext.js'
 
 jest.mock('../../store/configContext.js', () => ({ useConfig: jest.fn() }))
@@ -44,6 +45,21 @@ describe('Features — rendering', () => {
     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(<Features 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(<Features 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(<Features items={ITEMS} selectedIds={['f1']} />)
     const options = container.querySelectorAll(OPTION)
@@ -65,14 +81,18 @@ describe('Features — rendering', () => {
     expect(options[1]).toHaveAttribute(ARIA_SELECTED, 'false')
   })
 
-  it('sets aria-activedescendant to the option element id when activeFeatureId is provided', () => {
+  it('gives the active item tabIndex 0 and every other item tabIndex -1 (roving tabindex)', () => {
     const { container } = render(<Features items={ITEMS} activeFeatureId='f2' />)
-    expect(container.querySelector(LISTBOX).getAttribute('aria-activedescendant')).toBe('test-app-feature-f2') // NOSONAR
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0].getAttribute('tabIndex')).toBe('-1')
+    expect(options[1].getAttribute('tabIndex')).toBe('0')
   })
 
-  it('omits aria-activedescendant when activeFeatureId is absent', () => {
-    const { container } = render(<Features items={ITEMS} />)
-    expect(container.querySelector(LISTBOX).getAttribute('aria-activedescendant')).toBeNull() // NOSONAR
+  it('falls back to tabbableId for roving tabindex when activeFeatureId is absent', () => {
+    const { container } = render(<Features items={ITEMS} tabbableId='f1' />)
+    const options = container.querySelectorAll(OPTION)
+    expect(options[0].getAttribute('tabIndex')).toBe('0')
+    expect(options[1].getAttribute('tabIndex')).toBe('-1')
   })
 
   it('sets aria-multiselectable when multiselectable is true', () => {
@@ -85,18 +105,17 @@ describe('Features — rendering', () => {
     expect(container.querySelector(LISTBOX).getAttribute('aria-multiselectable')).toBeNull() // NOSONAR
   })
 
-  it('is tabIndex 0 and not aria-hidden when items are present', () => {
+  it('is not aria-hidden when items are present', () => {
     const { container } = render(<Features items={ITEMS} />)
     const ul = container.querySelector(LISTBOX) // NOSONAR
-    expect(ul.getAttribute('tabIndex')).toBe('0')
     expect(ul.getAttribute('aria-hidden')).toBeNull()
   })
 
-  it('is tabIndex -1 and aria-hidden when items is empty', () => {
+  it('is aria-hidden and has no options when items is empty', () => {
     const { container } = render(<Features />)
     const ul = container.querySelector(LISTBOX) // NOSONAR
-    expect(ul.getAttribute('tabIndex')).toBe('-1')
     expect(ul.getAttribute('aria-hidden')).toBe('true')
+    expect(container.querySelectorAll(OPTION)).toHaveLength(0) // NOSONAR
   })
 
   it('sets aria-describedby to the shared hints container id', () => {
@@ -121,4 +140,129 @@ describe('Features — interactions', () => {
     fireEvent.blur(container.querySelector(LISTBOX)) // NOSONAR
     expect(onBlur).toHaveBeenCalled()
   })
+
+  it('calls onSelectItem with the clicked item id', () => {
+    const onSelectItem = jest.fn()
+    const { container } = render(<Features 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(<Features items={ITEMS} />)
+    expect(() => fireEvent.click(container.querySelectorAll(OPTION)[0])).not.toThrow() // NOSONAR
+  })
+})
+
+// ─── Features + useFeatureFocus — roving tabindex wired together for real ────
+//
+// The tests above exercise Features in isolation (mocked onFocus/onBlur), and
+// useFeatureFocus.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 featuresRef = useRef(null)
+  const { activeFeatureId, tabbableId, selectedIds, onFocus, onBlur, selectItem } = useFeatureFocus({
+    viewportRef, featuresRef, items: ITEMS, eventBus, hints: { subscribe: () => () => {}, dismiss: () => {} }
+  })
+  return (
+    <Features
+      ref={featuresRef} activeFeatureId={activeFeatureId} tabbableId={tabbableId} selectedIds={selectedIds}
+      items={ITEMS} onFocus={onFocus} onBlur={onBlur} onSelectItem={selectItem}
+    />
+  )
+}
+
+describe('Features + useFeatureFocus — 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:setactivefeature', { 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
+  // useMapItemList.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:setactivefeature', ({ id }) => { lastActiveId = id })
+    bus.on('map:selectfeature', () => {
+      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

@@ -27,7 +27,7 @@ export const Viewport = () => {
   const featuresRef = 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 { activeFeatureId, tabbableId, selectedIds, onFocus: handleFeaturesFocus, onBlur: handleFeaturesBlur, selectItem } = useFeatureFocus({ viewportRef: layoutRefs.viewportRef, featuresRef, items: featureItems, eventBus, hints })
 
   useEffect(() => {
     const handler = () => dispatch({ type: 'SET_LISTBOX_ACTIVE' })
@@ -87,14 +87,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} />
+      <Features ref={featuresRef} activeFeatureId={activeFeatureId} tabbableId={tabbableId} selectedIds={selectedIds} multiselectable={multiselectable} items={featureItems} onFocus={onFeaturesFocus} onBlur={onFeaturesBlur} onSelectItem={selectItem} />
     </>
   )
 }

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 MoveControls (a normal, always-visible, always-named
+  // button) — see isMoveControlsOpen below — so the crosshair itself doesn't need to stay
+  // discoverable while it's not actually there. Blocked outright while MoveControls 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.isMoveControlsOpen) {
+      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.isMoveControlsOpen = expandedButtons?.has('moveControls')
+
   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 isMoveControlsOpen is set', () => {
+    setup()
+    act(() => mockCrossHair.show())
+    mockCrossHair.isMoveControlsOpen = true
+
+    act(() => mockCrossHair.hide())
+    expect(mockElement.style.display).toBe('block')
+    expect(mockDispatch).not.toHaveBeenCalledWith({ type: 'UPDATE_CROSS_HAIR', payload: { isVisible: false } })
+  })
+
+  it('keeps crossHair.isMoveControlsOpen 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(['moveControls']) })
+    setup()
+    expect(mockCrossHair.isMoveControlsOpen).toBe(true)
+  })
+
   it('setStyle updates state', () => {
     setup()
     act(() => mockCrossHair.setStyle('highlighted'))

package/src/App/hooks/useFeatureFocus.js

@@ -5,6 +5,12 @@ const getNavigatedId = (id, key, items) => {
   if (!items.length) {
     return id
   }
+  if (key === 'Home') {
+    return items[0].id
+  }
+  if (key === 'End') {
+    return items[items.length - 1].id
+  }
   const idx = items.findIndex(item => item.id === id)
   if (key === 'ArrowDown') {
     return idx === -1 ? items[0].id : items[Math.min(idx + 1, items.length - 1)].id
@@ -24,10 +30,25 @@ const resolveEntryId = (items, lastActiveId, selectedIds) => {
   return items[0].id
 }
 
+// Roving tabindex: moves real focus to the option matching id, found via data-id (avoids
+// CSS-escaping issues a querySelector would have with arbitrary ids). Flags
+// isInternalFocusMoveRef around the .focus() call so onFocus/onBlur can ignore this as an
+// internal move, not a real widget entry/exit — event.relatedTarget can't be used for that:
+// preact/compat (react is aliased to it in this app's build) doesn't populate it on synthetic
+// focus/blur events, so it's silently unreliable outside tests (real React + jsdom).
+const focusOption = (listboxEl, id, isInternalFocusMoveRef) => {
+  const el = Array.from(listboxEl?.children ?? []).find(li => li.dataset.id === String(id))
+  if (!el) {
+    return
+  }
+  isInternalFocusMoveRef.current = true
+  el.focus({ preventScroll: true })
+  isInternalFocusMoveRef.current = false
+}
+
 /**
  * Keeps local selectedIds in sync with interact:selectionchange, and mirrors
- * MAP_SET_ACTIVE_FEATURE back into React state so aria-activedescendant stays current.
- * Also tracks the last non-null active id so it can be restored on re-focus.
+ * MAP_SET_ACTIVE_FEATURE back into React state so the roving tabindex position stays current.
  */
 function useEventBusListeners ({ eventBus, lastActiveIdRef, setActiveFeatureId, setSelectedIds }) {
   useEffect(() => {
@@ -53,12 +74,10 @@ function useEventBusListeners ({ eventBus, lastActiveIdRef, setActiveFeatureId,
 }
 
 /**
- * Revalidates aria-activedescendant when the item list changes while the listbox is focused.
- * If the current active item is no longer in the list (e.g. panned off screen), picks a new one
- * using ARIA priority order: first selected → last active position → first item.
- * Reads eventBus and selectedIds via refs to avoid spurious re-runs on selection change.
+ * Re-picks the active item (ARIA priority order) when it drops out of the item list while
+ * focused — e.g. panned off screen — and moves real focus to it.
  */
-function useItemsRevalidation ({ items, eventBus, isFocusedRef, lastActiveIdRef, activeFeatureIdRef, selectedIdsRef, setActiveFeatureId }) {
+function useItemsRevalidation ({ items, eventBus, isFocusedRef, featuresRef, isInternalFocusMoveRef, lastActiveIdRef, activeFeatureIdRef, selectedIdsRef, setActiveFeatureId }) {
   useEffect(() => {
     if (!isFocusedRef.current) {
       return
@@ -75,16 +94,18 @@ function useItemsRevalidation ({ items, eventBus, isFocusedRef, lastActiveIdRef,
     lastActiveIdRef.current = nextId
     setActiveFeatureId(nextId)
     eventBus?.emit(EVENTS.MAP_SET_ACTIVE_FEATURE, { id: nextId })
+    focusOption(featuresRef.current, nextId, isInternalFocusMoveRef)
   }, [items]) // NOSONAR — eventBus/selectedIds consumed via refs to avoid spurious re-runs on selection change
 }
 
 /**
  * Attaches a keydown listener to the listbox element for ARIA keyboard navigation:
- * - ArrowUp/ArrowDown — move the active item, emitting MAP_SET_ACTIVE_FEATURE
+ * - ArrowUp/ArrowDown — move the active item, moving real focus to it (roving tabindex)
+ * - Home/End — jump the active item to the first/last option
  * - Enter/Space — confirm selection, emitting MAP_SELECT_FEATURE
  * - Escape — return focus to the map viewport
  */
-function useKeyboardNavigation ({ featuresRef, viewportRef, items, eventBus, activeFeatureIdRef, lastActiveIdRef, setActiveFeatureId, hints, currentHintRef }) {
+function useKeyboardNavigation ({ featuresRef, viewportRef, items, eventBus, activeFeatureIdRef, lastActiveIdRef, setActiveFeatureId, isInternalFocusMoveRef, hints, currentHintRef }) {
   useEffect(() => {
     const listboxEl = featuresRef.current
     if (!listboxEl) {
@@ -99,13 +120,14 @@ function useKeyboardNavigation ({ featuresRef, viewportRef, items, eventBus, act
         } else {
           viewportRef.current?.focus()
         }
-      } else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      } else if (event.key === 'ArrowDown' || event.key === 'ArrowUp' || event.key === 'Home' || event.key === 'End') {
         event.preventDefault()
         event.stopPropagation()
         const newId = getNavigatedId(activeFeatureIdRef.current, event.key, items)
         lastActiveIdRef.current = newId
         setActiveFeatureId(newId)
         eventBus?.emit(EVENTS.MAP_SET_ACTIVE_FEATURE, { id: newId })
+        focusOption(listboxEl, newId, isInternalFocusMoveRef)
       } else if (event.key === 'Enter' || event.key === ' ') {
         event.preventDefault()
         event.stopPropagation()
@@ -120,9 +142,8 @@ function useKeyboardNavigation ({ featuresRef, viewportRef, items, eventBus, act
 }
 
 /**
- * Clears listbox focus whenever the user interacts with the map via pointer (mouse or touch).
- * Any pointerdown outside the listbox element moves focus to the viewport, removing the
- * visible focus ring from the listbox without dropping focus to an unknown location.
+ * Returns focus to the viewport when the user interacts with the map via pointer while the
+ * listbox is focused — clears its focus ring without dropping focus to nowhere.
  */
 function useMapInteractionBlur ({ viewportRef, featuresRef, isFocusedRef }) {
   useEffect(() => {
@@ -141,18 +162,12 @@ function useMapInteractionBlur ({ viewportRef, featuresRef, isFocusedRef }) {
 }
 
 /**
- * Manages ARIA listbox focus state for the keyboard-accessible feature list.
- *
- * On focus, sets aria-activedescendant following ARIA priority order:
- *   1. First selected item (if any)
- *   2. Last active position (if still in the list)
- *   3. First item (fallback)
- *
- * On blur, clears the active descendant. Revalidates automatically when the item list
- * changes (e.g. after a map pan) so the active id never points to a stale item.
+ * Manages roving-tabindex focus state for the keyboard-accessible feature list. On focus, sets
+ * activeFeatureId via ARIA priority order (see resolveEntryId); on blur, clears it. Revalidates
+ * when the item list changes (e.g. after a map pan) so it never points to a stale item.
  *
  * @param {{ viewportRef: React.RefObject, featuresRef: React.RefObject, items: Array, eventBus: object }} params
- * @returns {{ activeFeatureId: string|null, selectedIds: string[], onFocus: Function, onBlur: Function }}
+ * @returns {{ activeFeatureId: string|null, tabbableId: string|null, selectedIds: string[], onFocus: Function, onBlur: Function, selectItem: Function }}
  */
 export function useFeatureFocus ({ viewportRef, featuresRef, items = [], eventBus, hints }) {
   const [activeFeatureId, setActiveFeatureId] = useState(null)
@@ -163,6 +178,7 @@ export function useFeatureFocus ({ viewportRef, featuresRef, items = [], eventBu
   const activeFeatureIdRef = useRef(null) // always-current for keydown closure
   const selectedIdsRef = useRef([]) // always-current for items-change effect
   const currentHintRef = useRef(null)
+  const isInternalFocusMoveRef = useRef(false) // true only while focusOption()'s own .focus() call is in flight
 
   useEffect(() => {
     return hints.subscribe((hint) => {
@@ -170,30 +186,72 @@ export function useFeatureFocus ({ viewportRef, featuresRef, items = [], eventBu
     })
   }, [hints])
 
-  useEffect(() => { activeFeatureIdRef.current = activeFeatureId }, [activeFeatureId])
-  useEffect(() => { selectedIdsRef.current = selectedIds }, [selectedIds])
+  // Always-current mirrors for values read from event-listener closures (not React re-renders) —
+  // assigned directly during render, same convention as useVisibleGeometry.js's latestRef.
+  activeFeatureIdRef.current = activeFeatureId
+  selectedIdsRef.current = selectedIds
 
   useEventBusListeners({ eventBus, lastActiveIdRef, setActiveFeatureId, setSelectedIds })
-  useItemsRevalidation({ items, eventBus, isFocusedRef, lastActiveIdRef, activeFeatureIdRef, selectedIdsRef, setActiveFeatureId })
-  useKeyboardNavigation({ featuresRef, viewportRef, items, eventBus, activeFeatureIdRef, lastActiveIdRef, setActiveFeatureId, hints, currentHintRef })
+  useItemsRevalidation({ items, eventBus, isFocusedRef, featuresRef, isInternalFocusMoveRef, lastActiveIdRef, activeFeatureIdRef, selectedIdsRef, setActiveFeatureId })
+  useKeyboardNavigation({ featuresRef, viewportRef, items, eventBus, activeFeatureIdRef, lastActiveIdRef, setActiveFeatureId, isInternalFocusMoveRef, hints, currentHintRef })
   useMapInteractionBlur({ viewportRef, featuresRef, isFocusedRef })
 
+  // Resting roving-tabindex position — where Tab lands before the list has ever had real focus.
+  // activeFeatureId takes priority once the list is actually focused. Deliberately never
+  // selection-driven (unlike onFocus's own resolution below) — sticks to the last established
+  // keyboard position, or the first item if there isn't one yet. "Prefer the selected item" is
+  // an onFocus-only concern (a real Tab-in); if it applied here too, any selection change made
+  // elsewhere (e.g. clicking a marker on the map, which never touches lastActiveIdRef) would
+  // keep relocating tabIndex to follow it, even though nothing about keyboard state changed.
+  let tabbableId = null
+  if (items.length) {
+    const hasEstablishedPosition = lastActiveIdRef.current && items.some(item => item.id === lastActiveIdRef.current)
+    tabbableId = hasEstablishedPosition ? lastActiveIdRef.current : items[0].id
+  }
+
   const onFocus = () => {
     isFocusedRef.current = true
+    // Ignore focus moving between sibling options (roving tabindex) — the keydown/selectItem
+    // path that moved it already resolved and emitted the correct id; re-resolving here would
+    // clobber that emit.
+    if (isInternalFocusMoveRef.current) {
+      return
+    }
     if (!items.length) {
       return
     }
+    // A real Tab-in always prefers a selected item over the remembered position (native listbox
+    // behaviour) — can't reuse tabbableId here, which deliberately does the opposite (sticks to
+    // the remembered position, ignoring selection) once one is established.
     const id = resolveEntryId(items, lastActiveIdRef.current, selectedIds)
     lastActiveIdRef.current = id
     setActiveFeatureId(id)
     eventBus?.emit(EVENTS.MAP_SET_ACTIVE_FEATURE, { id })
+    // Real focus may have landed on a different option than this resolves to — tabbableId (which
+    // decided where Tab lands) can legitimately disagree with resolveEntryId's own priority (e.g.
+    // Tab lands on the structural first item, but a different item is selected and takes
+    // priority here). Move real focus to match so it never disagrees with activeFeatureId.
+    focusOption(featuresRef.current, id, isInternalFocusMoveRef)
   }
 
   const onBlur = () => {
+    // Ignore focus moving between sibling options (roving tabindex) — not a real exit.
+    if (isInternalFocusMoveRef.current) {
+      return
+    }
     isFocusedRef.current = false
     setActiveFeatureId(null)
     eventBus?.emit(EVENTS.MAP_SET_ACTIVE_FEATURE, { id: null })
   }
 
-  return { activeFeatureId, selectedIds, onFocus, onBlur }
+  // Mirrors keyboard Enter/Space: make the clicked item active, focus it, then confirm selection.
+  const selectItem = (id) => {
+    lastActiveIdRef.current = id
+    setActiveFeatureId(id)
+    eventBus?.emit(EVENTS.MAP_SET_ACTIVE_FEATURE, { id })
+    focusOption(featuresRef.current, id, isInternalFocusMoveRef)
+    eventBus?.emit(EVENTS.MAP_SELECT_FEATURE)
+  }
+
+  return { activeFeatureId, tabbableId, selectedIds, onFocus, onBlur, selectItem }
 }