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

package/src/App/hooks/useKeyboardShortcuts.js

@@ -5,6 +5,71 @@ import { useConfig } from '../store/configContext.js'
 import { useApp } from '../store/appContext.js'
 import { useService } from '../store/serviceContext.js'
 
+const normalizeKey = (e) => {
+  let key
+
+  // Use e.code for letters to avoid 'dead' keys with Alt/AltGr
+  if (/^Key[A-Z]$/.test(e.code)) {
+    key = e.code.slice(3) // NOSONAR: strip "Key" prefix, e.g. "KeyI" -> "I"
+  } else {
+    key = e.key // works for arrows, numpad, punctuation
+  }
+
+  // Normalize numpad add/subtract to symbols
+  if (key === 'Add' || key === 'NumpadAdd') {
+    key = '+'
+  } else if (key === 'Subtract' || key === 'NumpadSubtract') {
+    key = '-'
+  } else {
+    // No action
+  }
+
+  // Check altKey first: AltGr (used on many non-US keyboards) reports both altKey
+  // and ctrlKey as true, and should still resolve to the Alt+ binding, not Ctrl+.
+  if (e.altKey) {
+    return `Alt+${key}`
+  }
+  if (e.ctrlKey) {
+    return `Ctrl+${key}`
+  }
+  return key
+}
+
+const resolveAction = (actions, type, key) => {
+  const actionName = keyboardMappings[type][key]
+  return actionName && actions[actionName] ? actionName : null
+}
+
+// keydown (pan/zoom) stays on the viewport so arrows only fire when the map has focus.
+// keyup (Alt+K and other global shortcuts) attaches to the app container so it fires
+// from anywhere within the app, including the features listbox.
+const createKeyEventHandlers = (actions) => {
+  const handleKeyDown = (e) => {
+    const key = normalizeKey(e)
+    const actionName = resolveAction(actions, 'keydown', key)
+    if (actionName) {
+      actions[actionName](e)
+      e.preventDefault()
+      return
+    }
+    // A keyup-bound shortcut (e.g. Alt+Arrow label navigation) still acts on release,
+    // but its browser default (e.g. arrow-key scroll) must be suppressed now or it's too late.
+    if (resolveAction(actions, 'keyup', key)) {
+      e.preventDefault()
+    }
+  }
+
+  const handleKeyUp = (e) => {
+    const actionName = resolveAction(actions, 'keyup', normalizeKey(e))
+    if (actionName) {
+      actions[actionName](e)
+      e.preventDefault()
+    }
+  }
+
+  return { handleKeyDown, handleKeyUp }
+}
+
 export function useKeyboardShortcuts (containerRef) {
   const { mapProvider, panDelta, nudgePanDelta, zoomDelta, nudgeZoomDelta, readMapText } = useConfig()
   const { dispatch, layoutRefs } = useApp()
@@ -27,42 +92,8 @@ export function useKeyboardShortcuts (containerRef) {
       readMapText
     })
 
-    const normalizeKey = (e) => {
-      let key
-
-      // Use e.code for letters to avoid 'dead' keys with Alt/AltGr
-      if (/^Key[A-Z]$/.test(e.code)) {
-        key = e.code.slice(3) // NOSONAR: strip "Key" prefix, e.g. "KeyI" -> "I"
-      } else {
-        key = e.key // works for arrows, numpad, punctuation
-      }
-
-      // Normalize numpad add/subtract to symbols
-      if (key === 'Add' || key === 'NumpadAdd') {
-        key = '+'
-      } else if (key === 'Subtract' || key === 'NumpadSubtract') {
-        key = '-'
-      } else {
-        // No action
-      }
-
-      return e.altKey ? `Alt+${key}` : key
-    }
-
-    const handle = (type) => (e) => {
-      const actionName = keyboardMappings[type][normalizeKey(e)]
-      if (actionName && actions[actionName]) {
-        actions[actionName](e)
-        e.preventDefault()
-      }
-    }
-
-    const handleKeyDown = handle('keydown')
-    const handleKeyUp = handle('keyup')
+    const { handleKeyDown, handleKeyUp } = createKeyEventHandlers(actions)
 
-    // keydown (pan/zoom) stays on the viewport so arrows only fire when the map has focus.
-    // keyup (Alt+K and other global shortcuts) attaches to the app container so it fires
-    // from anywhere within the app, including the features listbox.
     el.addEventListener('keydown', handleKeyDown)
     appEl.addEventListener('keyup', handleKeyUp)
 

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

@@ -138,6 +138,58 @@ describe('useKeyboardShortcuts', () => {
     expect(actions.stopPan).toHaveBeenCalled()
   })
 
+  test('does nothing on keyup when the key has no mapped action', () => {
+    const { appContainerRef, actions } = setup({ keyup: { ArrowUp: 'stopPan' }, actions: { stopPan: jest.fn() } })
+    renderHook(() => useKeyboardShortcuts({ current: document.createElement('div') }))
+
+    const evt = new KeyboardEvent('keyup', { key: 'Z' })
+    const spy = jest.spyOn(evt, 'preventDefault')
+    appContainerRef.current.dispatchEvent(evt)
+
+    expect(spy).not.toHaveBeenCalled()
+    expect(actions.stopPan).not.toHaveBeenCalled()
+  })
+
+  test('suppresses the browser default on keydown for a keyup-bound shortcut, without firing the action early', () => {
+    const { containerRef, appContainerRef, actions } = setup({
+      keyup: { 'Alt+ArrowUp': 'highlightNextLabel' },
+      actions: { highlightNextLabel: jest.fn() }
+    })
+    renderHook(() => useKeyboardShortcuts(containerRef))
+
+    const keydownEvt = new KeyboardEvent('keydown', { key: 'ArrowUp', altKey: true })
+    const keydownSpy = jest.spyOn(keydownEvt, 'preventDefault')
+    containerRef.current.dispatchEvent(keydownEvt)
+    expect(keydownSpy).toHaveBeenCalled()
+    expect(actions.highlightNextLabel).not.toHaveBeenCalled()
+
+    appContainerRef.current.dispatchEvent(new KeyboardEvent('keyup', { key: 'ArrowUp', altKey: true }))
+    expect(actions.highlightNextLabel).toHaveBeenCalled()
+  })
+
+  test('normalizes Ctrl+key combinations', () => {
+    const { containerRef, actions } = setup({
+      keydown: { 'Ctrl+I': 'getInfo' },
+      actions: { getInfo: jest.fn() }
+    })
+    renderHook(() => useKeyboardShortcuts(containerRef))
+
+    containerRef.current.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyI', key: 'i', ctrlKey: true }))
+    expect(actions.getInfo).toHaveBeenCalled()
+  })
+
+  test('treats AltGr (altKey + ctrlKey both true) as Alt+, not Ctrl+', () => {
+    const { containerRef, actions } = setup({
+      keydown: { 'Alt+I': 'getInfo', 'Ctrl+I': 'zoomIn' },
+      actions: { getInfo: jest.fn(), zoomIn: jest.fn() }
+    })
+    renderHook(() => useKeyboardShortcuts(containerRef))
+
+    containerRef.current.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyI', key: 'i', altKey: true, ctrlKey: true }))
+    expect(actions.getInfo).toHaveBeenCalled()
+    expect(actions.zoomIn).not.toHaveBeenCalled()
+  })
+
   test('prevents default when action exists, does nothing otherwise', () => {
     const { containerRef } = setup({ keydown: { I: 'zoomIn', X: 'nonExistent' } })
     renderHook(() => useKeyboardShortcuts(containerRef))

package/src/App/hooks/useModalPanelBehaviour.js

@@ -1,4 +1,4 @@
-import { useEffect } from 'react'
+import { useEffect, useLayoutEffect } from 'react'
 import { useResizeObserver } from './useResizeObserver.js'
 import { constrainKeyboardFocus } from '../../utils/constrainKeyboardFocus.js'
 import { toggleInertElements } from '../../utils/toggleInertElements.js'
@@ -62,6 +62,44 @@ const setSlotCSSVar = (slot, layoutRefs, primaryMargin) => {
   root.style.setProperty(MODAL_MAX_HEIGHT, `${mainRect.height - relTop - primaryMargin}px`)
 }
 
+// Computes and applies --modal-inset/--modal-max-height for the panel's current slot. Shared by
+// the resize observer (keeps position correct across later layout changes while open) and the
+// open-triggered layout effect below (panels stay permanently mounted — see mapPanels.js — so
+// opening one doesn't itself resize mainRef and wouldn't otherwise trigger a recalc).
+const recalcModalPosition = ({ isModal, mainRef, panelRef, buttonContainerEl, layoutRefs }) => {
+  if (!isModal || !mainRef.current) {
+    return
+  }
+
+  const root = document.documentElement
+  const styles = getComputedStyle(root)
+  const dividerGap = Number.parseInt(styles.getPropertyValue('--divider-gap'), 10)
+  const primaryMargin = Number.parseInt(styles.getPropertyValue('--primary-gap'), 10)
+  const slot = panelRef.current.dataset.slot
+
+  // Button-adjacent panels: position next to the controlling button.
+  // Use slot name (not buttonContainerEl) as the gate — buttonContainerEl may be undefined
+  // when there is no triggeringElement (e.g. panel opened programmatically).
+  // Dynamically query via aria-controls to handle stale triggeringElement after breakpoint changes.
+  if (slot?.endsWith('-button')) {
+    const panelElId = panelRef.current?.id
+    const currentButtonEl = panelElId ? document.querySelector(`[aria-controls="${panelElId}"]`) : null
+    const effectiveContainer = currentButtonEl?.parentElement ??
+      (buttonContainerEl?.isConnected ? buttonContainerEl : null) ??
+      document.querySelector(`[data-button-slot="${slot}"]`)
+
+    if (!effectiveContainer) {
+      return
+    }
+
+    setButtonCSSVar(effectiveContainer, mainRef, dividerGap)
+    return
+  }
+
+  // Slot-based panels: derive position from the slot container element
+  setSlotCSSVar(slot, layoutRefs, primaryMargin)
+}
+
 const useModalKeyHandler = (panelRef, isModal, handleClose) => {
   useEffect(() => {
     if (!isModal) {
@@ -131,40 +169,16 @@ export function useModalPanelBehaviour ({
 
   useModalKeyHandler(panelRef, isModal, handleClose)
 
-  // === Set --modal-inset and --modal-max-height, recalculate on mainRef resize === //
-  useResizeObserver([mainRef], () => {
-    if (!isModal || !mainRef.current) {
-      return
-    }
-
-    const root = document.documentElement
-    const styles = getComputedStyle(root)
-    const dividerGap = Number.parseInt(styles.getPropertyValue('--divider-gap'), 10)
-    const primaryMargin = Number.parseInt(styles.getPropertyValue('--primary-gap'), 10)
-    const slot = panelRef.current.dataset.slot
-
-    // Button-adjacent panels: position next to the controlling button.
-    // Use slot name (not buttonContainerEl) as the gate — buttonContainerEl may be undefined
-    // when there is no triggeringElement (e.g. panel opened programmatically).
-    // Dynamically query via aria-controls to handle stale triggeringElement after breakpoint changes.
-    if (slot?.endsWith('-button')) {
-      const panelElId = panelRef.current?.id
-      const currentButtonEl = panelElId ? document.querySelector(`[aria-controls="${panelElId}"]`) : null
-      const effectiveContainer = currentButtonEl?.parentElement ??
-        (buttonContainerEl?.isConnected ? buttonContainerEl : null) ??
-        document.querySelector(`[data-button-slot="${slot}"]`)
-
-      if (!effectiveContainer) {
-        return
-      }
-
-      setButtonCSSVar(effectiveContainer, mainRef, dividerGap)
-      return
-    }
+  // === Recalculate on mainRef resize (keeps position correct while already open) === //
+  useResizeObserver([mainRef], () => recalcModalPosition({ isModal, mainRef, panelRef, buttonContainerEl, layoutRefs }))
 
-    // Slot-based panels: derive position from the slot container element
-    setSlotCSSVar(slot, layoutRefs, primaryMargin)
-  })
+  // === Recalculate the moment the panel opens === //
+  // The resize observer above won't fire on its own here: its size cache persists across
+  // opens/closes (the panel no longer mounts fresh each time), and opening a panel doesn't
+  // itself resize mainRef. This is what actually positions the panel at open time.
+  useLayoutEffect(() => {
+    recalcModalPosition({ isModal, mainRef, panelRef, buttonContainerEl, layoutRefs })
+  }, [isModal, mainRef, panelRef, buttonContainerEl, layoutRefs])
 
   // === Click on modal backdrop to close === //
   useEffect(() => {

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

@@ -218,6 +218,65 @@ describe('useModalPanelBehaviour', () => {
     })
   })
 
+  // Regression: panels are mounted permanently and only toggle `hidden` (see mapPanels.js), so
+  // opening one doesn't itself resize mainRef. This uses the *real* useResizeObserver (backed by
+  // a fake ResizeObserver, not the blanket `(_, cb) => cb()` mock used above) so its size-change
+  // dedupe is actually exercised — that dedupe is what silently swallowed the reposition on open.
+  describe('repositioning on open when mainRef never resizes', () => {
+    const buttonSlot = 'map-styles-button'
+
+    beforeEach(() => {
+      const { useResizeObserver: actualUseResizeObserver } = jest.requireActual('./useResizeObserver.js')
+      useResizeObserverModule.useResizeObserver.mockImplementation(actualUseResizeObserver)
+
+      // Real ResizeObserver always delivers once per observe() call — mirror that, and let the
+      // real hook's own prevSizes dedupe decide whether the wrapped callback actually runs.
+      global.ResizeObserver = jest.fn(function (cb) {
+        this.observe = (target) => {
+          const entries = [{ target, contentRect: { width: 100, height: 50 } }]
+          cb(entries)
+        }
+        this.disconnect = jest.fn()
+      })
+      jest.spyOn(global, 'requestAnimationFrame').mockImplementation(cb => { cb(); return 0 })
+      jest.spyOn(global, 'cancelAnimationFrame').mockImplementation(() => {})
+      jest.spyOn(globalThis, 'getComputedStyle').mockReturnValue({ getPropertyValue: () => '8' })
+
+      Object.defineProperty(refs.main.current, 'getBoundingClientRect', {
+        value: () => ({ top: 0, right: 100, bottom: 50, left: 0, width: 100, height: 50 }),
+        configurable: true
+      })
+      Object.defineProperty(elements.buttonContainer, 'getBoundingClientRect', {
+        value: () => ({ top: 10, right: 80, bottom: 40, left: 20, width: 60, height: 30 }),
+        configurable: true
+      })
+
+      refs.panel.current.dataset.slot = buttonSlot
+      const button = document.createElement('button')
+      button.setAttribute(ARIA_CONTROLS, PANEL_ID)
+      elements.buttonContainer.appendChild(button)
+      document.body.appendChild(elements.buttonContainer)
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    it('positions the panel the moment it opens, not just when mainRef resizes', () => {
+      // Mounted closed, as it would be permanently — mainRef's size gets recorded but the
+      // calc no-ops on the isModal guard.
+      const { rerender } = render(<TestComponent isModal={false} />)
+      expect(document.documentElement.style.getPropertyValue(MODAL_INSET)).toBe('')
+
+      // Open it. mainRef hasn't resized, so the resize observer's own delivery is deduped
+      // away — only the open-triggered layout effect can position it here.
+      rerender(<TestComponent isModal />)
+
+      expect(document.documentElement.style.getPropertyValue(MODAL_INSET)).toContain('10px')
+      expect(document.documentElement.style.getPropertyValue(MODAL_MAX_HEIGHT)).toContain('px')
+    })
+  })
+
   describe('focus management', () => {
     it('redirects focus into panel when focus enters app but outside panel', () => {
       refs.panel.current.focus = jest.fn()

package/src/App/hooks/useSpatialListFocus.js

@@ -0,0 +1,296 @@
+import { useState, useEffect, useRef } from 'react'
+import { EVENTS } from '../../config/events.js'
+import { findNearestItemInDirection } from '../../utils/findNearestItemInDirection.js'
+import { spatialNavigate } from '../../utils/spatialNavigate.js'
+import { stopIfGlobalAltKey } from '../../utils/globalAltShortcuts.js'
+
+const ARROW_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'])
+
+// Whichever item is nearest the map's own center point on screen — the entry-point fallback
+// below prefers this over the structurally-first item.
+const findNearestToCenter = (items, centerScreenPoint) => {
+  if (!centerScreenPoint) {
+    return null
+  }
+  const positioned = items.filter(item => item.x != null && item.y != null)
+  if (!positioned.length) {
+    return null
+  }
+  const pixels = positioned.map(item => [item.x, item.y])
+  const idx = spatialNavigate([centerScreenPoint.x, centerScreenPoint.y], pixels, undefined)
+  return positioned[idx].id
+}
+
+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
+  }
+  return idx === -1 ? items[items.length - 1].id : items[Math.max(idx - 1, 0)].id
+}
+
+// ARIA listbox entry priority: first selected → last active (if still in list) → nearest the
+// map center → first item (last resort, e.g. no items carry a screen position at all)
+const resolveEntryId = (items, lastActiveId, selectedIds, centerScreenPoint) => {
+  const firstSelected = items.find(item => selectedIds.includes(item.id))
+  if (firstSelected) {
+    return firstSelected.id
+  }
+  if (lastActiveId && items.some(item => item.id === lastActiveId)) {
+    return lastActiveId
+  }
+  return findNearestToCenter(items, centerScreenPoint) ?? items[0].id
+}
+
+// Roving tabindex: moves real focus to the option matching id (via data-id, avoiding
+// querySelector's CSS-escaping issues with arbitrary ids). Flags isInternalFocusMoveRef around
+// the .focus() call so onFocus/onBlur can tell this apart from a real widget entry/exit.
+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_ITEM back into React state so the roving tabindex position stays current.
+ */
+function useEventBusListeners ({ eventBus, lastActiveIdRef, setActiveItemId, setSelectedIds }) {
+  useEffect(() => {
+    if (!eventBus) {
+      return undefined
+    }
+    const handleSetActive = ({ id }) => {
+      if (id !== null) {
+        lastActiveIdRef.current = id
+      }
+      setActiveItemId(id)
+    }
+    const handleSelectionChange = ({ selectedFeatures = [], selectedMarkers = [] }) => {
+      setSelectedIds([...selectedFeatures.map(f => String(f.featureId)), ...selectedMarkers])
+    }
+    eventBus.on(EVENTS.MAP_SET_ACTIVE_ITEM, handleSetActive)
+    eventBus.on('interact:selectionchange', handleSelectionChange)
+    return () => {
+      eventBus.off(EVENTS.MAP_SET_ACTIVE_ITEM, handleSetActive)
+      eventBus.off('interact:selectionchange', handleSelectionChange)
+    }
+  }, [eventBus])
+}
+
+/**
+ * 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, spatialListRef, isInternalFocusMoveRef, lastActiveIdRef, activeItemIdRef, selectedIdsRef, setActiveItemId, centerScreenPoint }) {
+  useEffect(() => {
+    if (!isFocusedRef.current) {
+      return
+    }
+    if (!items.length) {
+      setActiveItemId(null)
+      eventBus?.emit(EVENTS.MAP_SET_ACTIVE_ITEM, { id: null })
+      return
+    }
+    if (items.some(item => item.id === activeItemIdRef.current)) {
+      return
+    }
+    const nextId = resolveEntryId(items, lastActiveIdRef.current, selectedIdsRef.current, centerScreenPoint)
+    lastActiveIdRef.current = nextId
+    setActiveItemId(nextId)
+    eventBus?.emit(EVENTS.MAP_SET_ACTIVE_ITEM, { id: nextId })
+    focusOption(spatialListRef.current, nextId, isInternalFocusMoveRef)
+  }, [items]) // NOSONAR — eventBus/selectedIds consumed via refs to avoid spurious re-runs on selection change
+}
+
+/**
+ * Attaches keydown/keyup listeners to the listbox element for ARIA keyboard navigation:
+ * - ArrowUp/ArrowDown — move the active item sequentially, moving real focus (roving tabindex)
+ * - Alt+Arrow (any of the four) — move the active item spatially, to whichever item is
+ *   nearest in the pressed direction on screen, same roving-tabindex move as above
+ * - Home/End — jump the active item to the first/last option
+ * - Enter/Space — confirm selection, emitting MAP_SELECT_ITEM
+ * - Escape — return focus to the map viewport
+ */
+function useKeyboardNavigation ({ spatialListRef, viewportRef, items, eventBus, activeItemIdRef, lastActiveIdRef, setActiveItemId, isInternalFocusMoveRef, hints, currentHintRef }) {
+  useEffect(() => {
+    const listboxEl = spatialListRef.current
+    if (!listboxEl) {
+      return undefined
+    }
+    const moveTo = (newId) => {
+      lastActiveIdRef.current = newId
+      setActiveItemId(newId)
+      eventBus?.emit(EVENTS.MAP_SET_ACTIVE_ITEM, { id: newId })
+      focusOption(listboxEl, newId, isInternalFocusMoveRef)
+    }
+    const handleEscape = () => {
+      if (currentHintRef.current) {
+        hints.dismiss()
+      } else {
+        viewportRef.current?.focus()
+      }
+    }
+    // Same modifier as the map's own label navigation, but moves list items instead of labels
+    // while this listbox has focus — the keyup listener below stops it bubbling to that binding.
+    const handleSpatialMove = (event) => {
+      moveTo(findNearestItemInDirection(items, activeItemIdRef.current, event.key))
+    }
+    const handleKeyDown = (event) => {
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        event.stopPropagation()
+        handleEscape()
+      } else if (event.altKey && ARROW_KEYS.has(event.key)) {
+        // preventDefault here (on keydown) suppresses the browser's own Alt+Arrow
+        // history-navigation default.
+        event.preventDefault()
+        event.stopPropagation()
+        handleSpatialMove(event)
+      } else if (event.key === 'ArrowDown' || event.key === 'ArrowUp' || event.key === 'Home' || event.key === 'End') {
+        event.preventDefault()
+        event.stopPropagation()
+        moveTo(getNavigatedId(activeItemIdRef.current, event.key, items))
+      } else if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault()
+        event.stopPropagation()
+        eventBus?.emit(EVENTS.MAP_SELECT_ITEM)
+      } else {
+        // No action
+      }
+    }
+    // Shadows global Alt+<key> shortcuts (src/utils/globalAltShortcuts.js) from bubbling to
+    // the app-wide handler while this listbox has focus.
+    const handleKeyUp = (event) => {
+      stopIfGlobalAltKey(event)
+    }
+    listboxEl.addEventListener('keydown', handleKeyDown)
+    listboxEl.addEventListener('keyup', handleKeyUp)
+    return () => {
+      listboxEl.removeEventListener('keydown', handleKeyDown)
+      listboxEl.removeEventListener('keyup', handleKeyUp)
+    }
+  }, [viewportRef, spatialListRef, items, eventBus])
+}
+
+/**
+ * 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, spatialListRef, isFocusedRef }) {
+  useEffect(() => {
+    const el = viewportRef.current
+    if (!el) {
+      return undefined
+    }
+    const handlePointerDown = (event) => {
+      if (isFocusedRef.current && !spatialListRef.current?.contains(event.target)) {
+        viewportRef.current?.focus()
+      }
+    }
+    el.addEventListener('pointerdown', handlePointerDown)
+    return () => { el.removeEventListener('pointerdown', handlePointerDown) }
+  }, [viewportRef, spatialListRef])
+}
+
+/**
+ * Manages roving-tabindex focus state for the keyboard-accessible feature list. On focus, sets
+ * activeItemId 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, spatialListRef: React.RefObject, items: Array, eventBus: object, centerScreenPoint: {x: number, y: number}|null }} params
+ * @returns {{ activeItemId: string|null, tabbableId: string|null, selectedIds: string[], onFocus: Function, onBlur: Function, selectItem: Function }}
+ */
+export function useSpatialListFocus ({ viewportRef, spatialListRef, items = [], eventBus, hints, centerScreenPoint }) {
+  const [activeItemId, setActiveItemId] = useState(null)
+  const [selectedIds, setSelectedIds] = useState([])
+
+  const isFocusedRef = useRef(false)
+  const lastActiveIdRef = useRef(null) // preserved across blur; restores position on re-focus
+  const activeItemIdRef = 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) => {
+      currentHintRef.current = hint
+    })
+  }, [hints])
+
+  // 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.
+  activeItemIdRef.current = activeItemId
+  selectedIdsRef.current = selectedIds
+
+  useEventBusListeners({ eventBus, lastActiveIdRef, setActiveItemId, setSelectedIds })
+  useItemsRevalidation({ items, eventBus, isFocusedRef, spatialListRef, isInternalFocusMoveRef, lastActiveIdRef, activeItemIdRef, selectedIdsRef, setActiveItemId, centerScreenPoint })
+  useKeyboardNavigation({ spatialListRef, viewportRef, items, eventBus, activeItemIdRef, lastActiveIdRef, setActiveItemId, isInternalFocusMoveRef, hints, currentHintRef })
+  useMapInteractionBlur({ viewportRef, spatialListRef, isFocusedRef })
+
+  // Resting roving-tabindex position — where Tab lands before the list has ever had real focus.
+  // Deliberately never selection-driven (unlike onFocus's own resolution below): sticks to the
+  // last established keyboard position so an unrelated selection change elsewhere doesn't
+  // relocate it.
+  let tabbableId = null
+  if (items.length) {
+    const hasEstablishedPosition = lastActiveIdRef.current && items.some(item => item.id === lastActiveIdRef.current)
+    tabbableId = hasEstablishedPosition ? lastActiveIdRef.current : (findNearestToCenter(items, centerScreenPoint) ?? 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 prefers a selected item over the remembered position (native listbox
+    // behaviour) — unlike tabbableId, which deliberately ignores selection.
+    const id = resolveEntryId(items, lastActiveIdRef.current, selectedIds, centerScreenPoint)
+    lastActiveIdRef.current = id
+    setActiveItemId(id)
+    eventBus?.emit(EVENTS.MAP_SET_ACTIVE_ITEM, { id })
+    // Real focus may have landed on a different option than this resolves to (tabbableId and
+    // resolveEntryId can legitimately disagree) — move it to match so it never disagrees with activeItemId.
+    focusOption(spatialListRef.current, id, isInternalFocusMoveRef)
+  }
+
+  const onBlur = () => {
+    // Ignore focus moving between sibling options (roving tabindex) — not a real exit.
+    if (isInternalFocusMoveRef.current) {
+      return
+    }
+    isFocusedRef.current = false
+    setActiveItemId(null)
+    eventBus?.emit(EVENTS.MAP_SET_ACTIVE_ITEM, { id: null })
+  }
+
+  // Mirrors keyboard Enter/Space: make the clicked item active, focus it, then confirm selection.
+  const selectItem = (id) => {
+    lastActiveIdRef.current = id
+    setActiveItemId(id)
+    eventBus?.emit(EVENTS.MAP_SET_ACTIVE_ITEM, { id })
+    focusOption(spatialListRef.current, id, isInternalFocusMoveRef)
+    eventBus?.emit(EVENTS.MAP_SELECT_ITEM)
+  }
+
+  return { activeItemId, tabbableId, selectedIds, onFocus, onBlur, selectItem }
+}