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

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

@@ -0,0 +1,957 @@
+import { renderHook, act } from '@testing-library/react'
+import { useSpatialListFocus } from './useSpatialListFocus.js'
+
+const ITEMS = [
+  { id: 'a', label: 'Feature A' },
+  { id: 'b', label: 'Feature B' },
+  { id: 'c', label: 'Feature C' }
+]
+
+const SET_ACTIVE = 'map:setactiveitem' // NOSONAR
+const SELECT = 'map:selectitem'
+const SELECTION_CHANGE = 'interact:selectionchange'
+
+const makeEventBus = () => {
+  const listeners = {}
+  return {
+    on: jest.fn((eventName, fn) => { listeners[eventName] = fn }),
+    off: jest.fn(),
+    emit: jest.fn(),
+    trigger: (eventName, payload) => listeners[eventName]?.(payload)
+  }
+}
+
+const makeRefs = ({ viewportFocus } = {}) => {
+  const viewportEl = document.createElement('div')
+  viewportEl.focus = viewportFocus ?? jest.fn()
+  return {
+    viewportRef: { current: viewportEl },
+    spatialListRef: { current: document.createElement('ul') },
+    hints: { subscribe: jest.fn(() => jest.fn()), dismiss: jest.fn() }
+  }
+}
+
+const fireKey = (el, key) => {
+  let event
+  act(() => {
+    event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true })
+    el.dispatchEvent(event)
+  })
+  return event
+}
+
+// ─── useSpatialListFocus — initial state ─────────────────────────────────────────
+
+describe('useSpatialListFocus — initial state', () => {
+  it('activeItemId starts as null', () => {
+    const { result } = renderHook(() => useSpatialListFocus(makeRefs()))
+    expect(result.current.activeItemId).toBeNull()
+  })
+
+  it('exposes onFocus function', () => {
+    const { result } = renderHook(() => useSpatialListFocus(makeRefs()))
+    expect(typeof result.current.onFocus).toBe('function')
+  })
+
+  it('exposes onBlur function', () => {
+    const { result } = renderHook(() => useSpatialListFocus(makeRefs()))
+    expect(typeof result.current.onBlur).toBe('function')
+  })
+})
+
+// ─── useSpatialListFocus — onFocus ────────────────────────────────────────────────
+
+describe('useSpatialListFocus — onFocus', () => {
+  it('sets activeItemId to first item on first focus (no previous, no selected)', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('a')
+  })
+
+  it('does nothing when items is empty', () => {
+    const { result } = renderHook(() => useSpatialListFocus(makeRefs()))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBeNull()
+  })
+
+  it('sets active to first selected item (highest priority)', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'b', layerId: 'roads' }] }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('b')
+  })
+
+  it('selected item takes priority over last active position', () => {
+    const eb = makeEventBus()
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS, eventBus: eb }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown') // last active = 'b'
+    act(() => result.current.onBlur())
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'c', layerId: 'roads' }] }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('c') // selected beats last-active
+    unmount(); el.remove()
+  })
+
+  it('restores last active position when nothing is selected', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown') // last active = 'b'
+    act(() => result.current.onBlur())
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('b')
+    unmount(); el.remove()
+  })
+
+  it('falls back to first item when previous active is no longer in the list', () => {
+    const eb = makeEventBus()
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, rerender, unmount } = renderHook(
+      ({ items }) => useSpatialListFocus({ ...refs, items, eventBus: eb }),
+      { initialProps: { items: ITEMS } }
+    )
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown') // active = 'b'
+    act(() => result.current.onBlur())
+    const NEW_ITEMS = [{ id: 'x', label: 'X' }, { id: 'y', label: 'Y' }]
+    rerender({ items: NEW_ITEMS })
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('x')
+    unmount(); el.remove()
+  })
+
+  it('prefers the item nearest the map center over the structurally-first one', () => {
+    const items = [
+      { id: 'a', label: 'A', x: 0, y: 0 },
+      { id: 'b', label: 'B', x: 100, y: 100 },
+      { id: 'c', label: 'C', x: 500, y: 500 }
+    ]
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items, centerScreenPoint: { x: 90, y: 90 } }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('b')
+  })
+
+  it('falls back to the first item when no centerScreenPoint is given, even with positioned items', () => {
+    const items = [
+      { id: 'a', label: 'A', x: 0, y: 0 },
+      { id: 'b', label: 'B', x: 100, y: 100 }
+    ]
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('a')
+  })
+
+  it('falls back to the first item when centerScreenPoint is given but no item carries a screen position', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, centerScreenPoint: { x: 90, y: 90 } }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('a')
+  })
+})
+
+// ─── useSpatialListFocus — onBlur ─────────────────────────────────────────────────
+
+describe('useSpatialListFocus — onBlur', () => {
+  it('clears activeItemId when focus leaves the listbox', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS }))
+    act(() => result.current.onFocus())
+    expect(result.current.activeItemId).toBe('a')
+    act(() => result.current.onBlur())
+    expect(result.current.activeItemId).toBeNull()
+  })
+
+  it('emits map:setactivefeature with null on blur', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    act(() => result.current.onBlur())
+    expect(eb.emit).toHaveBeenCalledWith(SET_ACTIVE, { id: null })
+  })
+
+  it('does not throw when eventBus is not provided', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS }))
+    expect(() => act(() => result.current.onBlur())).not.toThrow()
+  })
+
+  // The "moving between sibling options shouldn't count as a real blur/focus" behavior is
+  // driven by an internal isInternalFocusMoveRef, set only while focusOption()'s own .focus()
+  // call is synchronously in flight — not observable by calling onFocus/onBlur directly here,
+  // since that requires a real DOM focus transition bubbling through React. See the
+  // "SpatialList + useSpatialListFocus — roving tabindex real focus events" suite in SpatialList.test.jsx,
+  // which renders the real markup and is the only level this can be faithfully exercised at
+  // (and is where the regression this guards against was actually found).
+})
+
+// ─── useSpatialListFocus — keydown listener lifecycle ────────────────────────────
+
+describe('useSpatialListFocus — keydown listener lifecycle', () => {
+  it('does not attach listener when spatialListRef.current is null', () => {
+    const refs = makeRefs()
+    refs.spatialListRef = { current: null }
+    const spy = jest.spyOn(document.body, 'addEventListener')
+    renderHook(() => useSpatialListFocus(refs))
+    expect(spy).not.toHaveBeenCalledWith('keydown', expect.any(Function))
+    spy.mockRestore()
+  })
+
+  it('attaches and removes keydown listener on the features element', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    const addSpy = jest.spyOn(el, 'addEventListener')
+    const removeSpy = jest.spyOn(el, 'removeEventListener')
+    const { unmount } = renderHook(() => useSpatialListFocus(refs))
+    expect(addSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+    unmount()
+    expect(removeSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+  })
+})
+
+// ─── useSpatialListFocus — unhandled keys ────────────────────────────────────────
+
+describe('useSpatialListFocus — unhandled keys', () => {
+  it('does nothing for keys that are not Escape or Arrow', () => {
+    const viewportFocus = jest.fn()
+    const refs = makeRefs({ viewportFocus })
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    fireKey(el, 'Tab')
+    expect(result.current.activeItemId).toBeNull()
+    expect(viewportFocus).not.toHaveBeenCalled()
+    el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — Escape key ────────────────────────────────────────────
+
+describe('useSpatialListFocus — Escape key', () => {
+  it('dismisses hint on Escape when hint is visible', () => {
+    const refs = makeRefs()
+    refs.hints.subscribe.mockImplementation((fn) => {
+      fn({ html: 'test' })
+      return jest.fn()
+    })
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'Escape')
+    expect(refs.hints.dismiss).toHaveBeenCalled()
+    expect(refs.viewportRef.current.focus).not.toHaveBeenCalled()
+    el.remove()
+  })
+
+  it('focuses the viewport on Escape when no hint is visible', () => {
+    const viewportFocus = jest.fn()
+    const refs = makeRefs({ viewportFocus })
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'Escape')
+    expect(refs.hints.dismiss).not.toHaveBeenCalled()
+    expect(viewportFocus).toHaveBeenCalled()
+    el.remove()
+  })
+
+  it('does not throw when viewportRef.current is null', () => {
+    const refs = { viewportRef: { current: null }, spatialListRef: { current: document.createElement('ul') }, hints: { subscribe: jest.fn(() => jest.fn()), dismiss: jest.fn() } }
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    renderHook(() => useSpatialListFocus(refs))
+    expect(() => fireKey(el, 'Escape')).not.toThrow()
+    el.remove()
+  })
+
+  it('stops propagation on Escape so the viewport keyboard handler does not also handle it', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    const event = new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).toHaveBeenCalled()
+    el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — ArrowDown navigation ───────────────────────────────────
+
+describe('useSpatialListFocus — ArrowDown navigation', () => {
+  const setup = () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    return { result, el, unmount }
+  }
+
+  it('selects first item when no item is active', () => {
+    const { result, el, unmount } = setup()
+    fireKey(el, 'ArrowDown')
+    expect(result.current.activeItemId).toBe('a')
+    unmount(); el.remove()
+  })
+
+  it('advances to next item', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown')
+    expect(result.current.activeItemId).toBe('b')
+    unmount(); el.remove()
+  })
+
+  it('clamps at last item', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown')
+    fireKey(el, 'ArrowDown')
+    fireKey(el, 'ArrowDown')
+    expect(result.current.activeItemId).toBe('c')
+    unmount(); el.remove()
+  })
+
+  it('does nothing when items is empty', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus(refs))
+    fireKey(el, 'ArrowDown')
+    expect(result.current.activeItemId).toBeNull()
+    unmount(); el.remove()
+  })
+
+  it('stops propagation on ArrowDown so the viewport keyboard handler does not pan the map', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    const event = new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true, cancelable: true })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).toHaveBeenCalled()
+    unmount(); el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — ArrowUp navigation ────────────────────────────────────
+
+describe('useSpatialListFocus — ArrowUp navigation', () => {
+  it('selects last item when no item is active', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    fireKey(el, 'ArrowUp')
+    expect(result.current.activeItemId).toBe('c')
+    unmount(); el.remove()
+  })
+
+  it('moves to previous item', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown')
+    fireKey(el, 'ArrowUp')
+    expect(result.current.activeItemId).toBe('a')
+    unmount(); el.remove()
+  })
+
+  it('clamps at first item', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowUp')
+    fireKey(el, 'ArrowUp')
+    expect(result.current.activeItemId).toBe('a')
+    unmount(); el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — Alt+Arrow spatial navigation ──────────────────────────
+
+describe('useSpatialListFocus — Alt+Arrow spatial navigation', () => {
+  const POSITIONED_ITEMS = [
+    { id: 'center', label: 'Center', x: 0, y: 0 },
+    { id: 'up', label: 'Up', x: 0, y: -10 },
+    { id: 'right', label: 'Right', x: 10, y: 0 }
+  ]
+
+  const setup = (items = POSITIONED_ITEMS) => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items }))
+    return { result, el, unmount }
+  }
+
+  const fireAltKey = (el, key, type = 'keydown') => {
+    let event
+    act(() => {
+      event = new KeyboardEvent(type, { key, altKey: true, bubbles: true, cancelable: true })
+      el.dispatchEvent(event)
+    })
+    return event
+  }
+
+  it('moves to the item spatially nearest in the pressed direction, not the next item in list order', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus()) // resolves to 'center', the first item
+    fireAltKey(el, 'ArrowRight')
+    expect(result.current.activeItemId).toBe('right')
+    unmount(); el.remove()
+  })
+
+  it('emits map:setactivefeature for the spatially-found item', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: POSITIONED_ITEMS, eventBus: makeEventBus() }))
+    act(() => result.current.onFocus())
+    fireAltKey(el, 'ArrowUp')
+    expect(result.current.activeItemId).toBe('up')
+    unmount(); el.remove()
+  })
+
+  it('prevents the browser default (e.g. Alt+Arrow history navigation) on keydown', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    let event
+    act(() => {
+      event = new KeyboardEvent('keydown', { key: 'ArrowRight', altKey: true, bubbles: true, cancelable: true })
+    })
+    const preventSpy = jest.spyOn(event, 'preventDefault')
+    act(() => el.dispatchEvent(event))
+    expect(preventSpy).toHaveBeenCalled()
+    unmount(); el.remove()
+  })
+
+  it('stops the matching keyup from bubbling to the viewport label-navigation binding on a shared ancestor', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    let event
+    act(() => {
+      event = new KeyboardEvent('keyup', { key: 'ArrowRight', altKey: true, bubbles: true, cancelable: true })
+    })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).toHaveBeenCalled()
+    unmount(); el.remove()
+  })
+
+  it('leaves a plain (non-Alt) arrow keyup alone — sequential navigation has already handled it on keydown', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    let event
+    act(() => {
+      event = new KeyboardEvent('keyup', { key: 'ArrowRight', altKey: false, bubbles: true, cancelable: true })
+    })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).not.toHaveBeenCalled()
+    unmount(); el.remove()
+  })
+
+  it('stops an Alt+Enter keyup from bubbling to the viewport center-label binding on a shared ancestor', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    let event
+    act(() => {
+      event = new KeyboardEvent('keyup', { key: 'Enter', altKey: true, bubbles: true, cancelable: true })
+    })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).toHaveBeenCalled()
+    unmount(); el.remove()
+  })
+
+  it('leaves an Alt+<other> keyup alone — nothing else uses this modifier here', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    let event
+    act(() => {
+      event = new KeyboardEvent('keyup', { key: 'i', altKey: true, bubbles: true, cancelable: true })
+    })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).not.toHaveBeenCalled()
+    unmount(); el.remove()
+  })
+
+  it('is a no-op when no item lies in the pressed direction — stays on the current item', () => {
+    const { result, el, unmount } = setup([{ id: 'only', label: 'Only', x: 0, y: 0 }])
+    act(() => result.current.onFocus())
+    fireAltKey(el, 'ArrowRight')
+    expect(result.current.activeItemId).toBe('only')
+    unmount(); el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — Home/End navigation ───────────────────────────────────
+
+describe('useSpatialListFocus — Home/End navigation', () => {
+  const setup = () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    return { result, el, unmount }
+  }
+
+  it('jumps to the first item on Home from anywhere in the list', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    fireKey(el, 'ArrowDown')
+    fireKey(el, 'Home')
+    expect(result.current.activeItemId).toBe('a')
+    unmount(); el.remove()
+  })
+
+  it('jumps to the last item on End from anywhere in the list', () => {
+    const { result, el, unmount } = setup()
+    act(() => result.current.onFocus())
+    fireKey(el, 'End')
+    expect(result.current.activeItemId).toBe('c')
+    unmount(); el.remove()
+  })
+
+  it('does nothing when items is empty', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus(refs))
+    fireKey(el, 'Home')
+    fireKey(el, 'End')
+    expect(result.current.activeItemId).toBeNull()
+    unmount(); el.remove()
+  })
+
+  it('stops propagation on Home/End so the viewport keyboard handler does not also handle it', () => {
+    const { el, unmount } = setup()
+    for (const key of ['Home', 'End']) {
+      const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true })
+      const stopSpy = jest.spyOn(event, 'stopPropagation')
+      act(() => el.dispatchEvent(event))
+      expect(stopSpy).toHaveBeenCalled()
+    }
+    unmount()
+  })
+
+  it('emits map:setactivefeature with the boundary id', () => {
+    const eb = makeEventBus()
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS, eventBus: eb }))
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    fireKey(el, 'End')
+    expect(eb.emit).toHaveBeenCalledWith(SET_ACTIVE, { id: 'c' })
+    unmount(); el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — eventBus integration ───────────────────────────────────
+
+describe('useSpatialListFocus — eventBus: map:setactivefeature listener', () => {
+  it('subscribes to map:setactivefeature on mount and unsubscribes on unmount', () => {
+    const eb = makeEventBus()
+    const { unmount } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    expect(eb.on).toHaveBeenCalledWith(SET_ACTIVE, expect.any(Function))
+    unmount()
+    expect(eb.off).toHaveBeenCalledWith(SET_ACTIVE, expect.any(Function))
+  })
+
+  it('updates activeItemId when map:setactivefeature is received', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    act(() => eb.trigger(SET_ACTIVE, { id: 'a' }))
+    expect(result.current.activeItemId).toBe('a')
+  })
+
+  it('clears activeItemId when map:setactivefeature is received with null', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => eb.trigger(SET_ACTIVE, { id: 'a' }))
+    act(() => eb.trigger(SET_ACTIVE, { id: null }))
+    expect(result.current.activeItemId).toBeNull()
+  })
+})
+
+const setupWithBus = () => {
+  const eb = makeEventBus()
+  const refs = makeRefs()
+  const el = refs.spatialListRef.current
+  document.body.appendChild(el)
+  const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS, eventBus: eb }))
+  return { eb, el, result, unmount }
+}
+
+describe('useSpatialListFocus — eventBus: map:setactivefeature emit', () => {
+  afterEach(() => { document.body.innerHTML = '' })
+
+  it('emits map:setactivefeature with first item id on onFocus', () => {
+    const { eb, result } = setupWithBus()
+    act(() => result.current.onFocus())
+    expect(eb.emit).toHaveBeenCalledWith(SET_ACTIVE, { id: 'a' })
+  })
+
+  it('emits map:setactivefeature with new id on ArrowDown', () => {
+    const { eb, result, el, unmount } = setupWithBus()
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    fireKey(el, 'ArrowDown')
+    expect(eb.emit).toHaveBeenCalledWith(SET_ACTIVE, { id: 'b' })
+    unmount()
+  })
+
+  it('does not emit when eventBus is not provided', () => {
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    expect(() => {
+      act(() => result.current.onFocus())
+      fireKey(el, 'ArrowDown')
+    }).not.toThrow()
+    unmount()
+  })
+})
+
+// ─── useSpatialListFocus — interact:selectionchange listener ─────────────────────
+
+describe('useSpatialListFocus — interact:selectionchange listener', () => {
+  it('subscribes to interact:selectionchange on mount and unsubscribes on unmount', () => {
+    const eb = makeEventBus()
+    const { unmount } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    expect(eb.on).toHaveBeenCalledWith(SELECTION_CHANGE, expect.any(Function))
+    unmount()
+    expect(eb.off).toHaveBeenCalledWith(SELECTION_CHANGE, expect.any(Function))
+  })
+
+  it('sets selectedIds from selected features', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 27665979, layerId: 'hedges' }] }))
+    expect(result.current.selectedIds).toEqual(['27665979'])
+  })
+
+  it('sets selectedIds from multiple selected features', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'f1', layerId: 'roads' }, { featureId: 'f2', layerId: 'roads' }] }))
+    expect(result.current.selectedIds).toEqual(['f1', 'f2'])
+  })
+
+  it('sets selectedIds from selected markers', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedMarkers: ['m1', 'm2'] }))
+    expect(result.current.selectedIds).toEqual(['m1', 'm2'])
+  })
+
+  it('sets selectedIds from both features and markers when both are selected', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'f1', layerId: 'roads' }], selectedMarkers: ['m1'] }))
+    expect(result.current.selectedIds).toEqual(['f1', 'm1'])
+  })
+
+  it('clears selectedIds when selection becomes empty', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'f1', layerId: 'roads' }] }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [], selectedMarkers: [] }))
+    expect(result.current.selectedIds).toEqual([])
+  })
+
+  it('does not move activeItemId when selectionchange fires (cursor is keyboard-only)', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'a', layerId: 'roads' }] }))
+    expect(result.current.activeItemId).toBeNull()
+  })
+})
+
+// ─── useSpatialListFocus — map interaction returns focus to viewport ──────────────
+
+describe('useSpatialListFocus — map pointerdown returns focus to viewport', () => {
+  const pointerDown = (target) => act(() => {
+    target.dispatchEvent(new Event('pointerdown', { bubbles: true, cancelable: true }))
+  })
+
+  it('focuses the viewport when pointer lands on the map while listbox is focused', () => {
+    const viewportFocus = jest.fn()
+    const refs = makeRefs({ viewportFocus })
+    document.body.appendChild(refs.viewportRef.current)
+    const mapCanvas = document.createElement('canvas')
+    refs.viewportRef.current.appendChild(mapCanvas)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    viewportFocus.mockClear()
+    pointerDown(mapCanvas)
+    expect(viewportFocus).toHaveBeenCalled()
+    unmount()
+  })
+
+  it('does not move focus when pointer lands inside the listbox', () => {
+    const viewportFocus = jest.fn()
+    const refs = makeRefs({ viewportFocus })
+    document.body.appendChild(refs.viewportRef.current)
+    refs.viewportRef.current.appendChild(refs.spatialListRef.current)
+    const option = document.createElement('li')
+    refs.spatialListRef.current.appendChild(option)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.onFocus())
+    viewportFocus.mockClear()
+    pointerDown(option)
+    expect(viewportFocus).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('does not move focus when pointer fires while listbox is not focused', () => {
+    const viewportFocus = jest.fn()
+    const refs = makeRefs({ viewportFocus })
+    document.body.appendChild(refs.viewportRef.current)
+    const mapCanvas = document.createElement('canvas')
+    refs.viewportRef.current.appendChild(mapCanvas)
+    const { unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    pointerDown(mapCanvas)
+    expect(viewportFocus).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  afterEach(() => { document.body.innerHTML = '' })
+})
+
+// ─── useSpatialListFocus — Enter and Space keys ───────────────────────────────────
+
+describe('useSpatialListFocus — Enter and Space keys', () => {
+  afterEach(() => { document.body.innerHTML = '' })
+
+  it('emits map:selectfeature on Enter', () => {
+    const { eb, result, el, unmount } = setupWithBus()
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    fireKey(el, 'Enter')
+    expect(eb.emit).toHaveBeenCalledWith(SELECT)
+    unmount()
+  })
+
+  it('emits map:selectfeature on Space', () => {
+    const { eb, result, el, unmount } = setupWithBus()
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    fireKey(el, ' ')
+    expect(eb.emit).toHaveBeenCalledWith(SELECT)
+    unmount()
+  })
+
+  it('stops propagation on Enter', () => {
+    const { el, result, unmount } = setupWithBus()
+    act(() => result.current.onFocus())
+    const event = new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).toHaveBeenCalled()
+    unmount()
+  })
+
+  it('stops propagation on Space', () => {
+    const { el, result, unmount } = setupWithBus()
+    act(() => result.current.onFocus())
+    const event = new KeyboardEvent('keydown', { key: ' ', bubbles: true, cancelable: true })
+    const stopSpy = jest.spyOn(event, 'stopPropagation')
+    act(() => el.dispatchEvent(event))
+    expect(stopSpy).toHaveBeenCalled()
+    unmount()
+  })
+})
+
+// ─── useSpatialListFocus — items change while focused ─────────────────────────────
+
+describe('useSpatialListFocus — items change while focused', () => {
+  afterEach(() => { document.body.innerHTML = '' })
+
+  const setupRerender = (initialItems) => {
+    const eb = makeEventBus()
+    const refs = makeRefs()
+    document.body.appendChild(refs.spatialListRef.current)
+    const { result, rerender, unmount } = renderHook(
+      ({ items }) => useSpatialListFocus({ ...refs, items, eventBus: eb }),
+      { initialProps: { items: initialItems } }
+    )
+    return { eb, result, rerender, unmount }
+  }
+
+  it('keeps current active item when it is still in the updated list', () => {
+    const { result, rerender, unmount } = setupRerender(ITEMS)
+    act(() => result.current.onFocus()) // active = 'a'
+    act(() => { rerender({ items: [{ id: 'a', label: 'A updated' }, { id: 'd', label: 'D' }] }) })
+    expect(result.current.activeItemId).toBe('a')
+    unmount()
+  })
+
+  it('re-picks by priority when current active item leaves the list — first selected wins', () => {
+    const { eb, result, rerender, unmount } = setupRerender(ITEMS)
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'c', layerId: 'l' }] }))
+    act(() => result.current.onFocus()) // active = 'a' (first, no prev)
+    act(() => { rerender({ items: [{ id: 'c', label: 'C' }, { id: 'd', label: 'D' }] }) }) // 'a' gone
+    expect(result.current.activeItemId).toBe('c') // first selected
+    unmount()
+  })
+
+  it('re-picks first item when active leaves and no selected item is in the new list', () => {
+    const { result, rerender, unmount } = setupRerender(ITEMS)
+    act(() => result.current.onFocus()) // active = 'a'
+    act(() => { rerender({ items: [{ id: 'x', label: 'X' }, { id: 'y', label: 'Y' }] }) })
+    expect(result.current.activeItemId).toBe('x')
+    unmount()
+  })
+
+  it('does not change active item when the listbox is not focused', () => {
+    const { result, rerender, unmount } = setupRerender(ITEMS)
+    // never called onFocus — isFocusedRef stays false
+    act(() => { rerender({ items: [{ id: 'x', label: 'X' }] }) })
+    expect(result.current.activeItemId).toBeNull()
+    unmount()
+  })
+
+  it('emits map:setactivefeature with new id when re-pick occurs', () => {
+    const { eb, result, rerender, unmount } = setupRerender(ITEMS)
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    act(() => { rerender({ items: [{ id: 'x', label: 'X' }] }) }) // 'a' gone
+    expect(eb.emit).toHaveBeenCalledWith('map:setactiveitem', { id: 'x' })
+    unmount()
+  })
+
+  it('clears active and emits null when items list becomes empty while focused', () => {
+    const { eb, result, rerender, unmount } = setupRerender(ITEMS)
+    act(() => result.current.onFocus())
+    eb.emit.mockClear()
+    act(() => { rerender({ items: [] }) })
+    expect(result.current.activeItemId).toBeNull()
+    expect(eb.emit).toHaveBeenCalledWith('map:setactiveitem', { id: null })
+    unmount()
+  })
+})
+
+// ─── useSpatialListFocus — tabbableId (roving tabindex resting position) ─────────
+
+describe('useSpatialListFocus — tabbableId', () => {
+  it('is null when items is empty', () => {
+    const { result } = renderHook(() => useSpatialListFocus(makeRefs()))
+    expect(result.current.tabbableId).toBeNull()
+  })
+
+  it('defaults to the item nearest the map center before the list has ever been focused', () => {
+    const items = [
+      { id: 'a', label: 'A', x: 0, y: 0 },
+      { id: 'b', label: 'B', x: 100, y: 100 }
+    ]
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items, centerScreenPoint: { x: 90, y: 90 } }))
+    expect(result.current.tabbableId).toBe('b')
+  })
+
+  it('defaults to the first item before the list has ever been focused', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS }))
+    expect(result.current.tabbableId).toBe('a')
+  })
+
+  // Unlike onFocus's own resolution, tabbableId deliberately ignores selection — "prefer the
+  // selected item" is a real-Tab-in-only concern. If tabbableId also preferred it, selecting a
+  // single marker by clicking it on the map (which never touches lastActiveIdRef) would relocate
+  // tabIndex to match it on every click.
+  it('is not influenced by a selection change before any position is established', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedFeatures: [{ featureId: 'b', layerId: 'roads' }] }))
+    expect(result.current.tabbableId).toBe('a')
+  })
+
+  it('does not chase a single item toggled selected/deselected purely via mouse clicks, with no keyboard interaction at all', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedMarkers: ['a'] }))
+    expect(result.current.tabbableId).toBe('a')
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedMarkers: ['b'] })) // clicked a different marker
+    expect(result.current.tabbableId).toBe('a') // still the structural first item — never moved
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedMarkers: ['c'] }))
+    expect(result.current.tabbableId).toBe('a')
+  })
+
+  it('stays on the established position when a selection change arrives from elsewhere (e.g. clicking a marker on the map)', () => {
+    const eb = makeEventBus()
+    const refs = makeRefs()
+    const el = refs.spatialListRef.current
+    document.body.appendChild(el)
+    const { result, unmount } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS, eventBus: eb }))
+    act(() => result.current.onFocus()) // establishes position at 'a'
+    fireKey(el, 'ArrowDown') // establishes position at 'b'
+    act(() => result.current.onBlur())
+    // A selection made outside the list (e.g. a mouse click on a map marker) never touches
+    // lastActiveIdRef — it only changes selectedIds via interact:selectionchange.
+    act(() => eb.trigger(SELECTION_CHANGE, { selectedMarkers: ['c'] }))
+    expect(result.current.tabbableId).toBe('b') // stays put — does not jump to the newly-selected 'c'
+    unmount(); el.remove()
+  })
+})
+
+// ─── useSpatialListFocus — selectItem (click / touch / voice-control activation) ─
+
+describe('useSpatialListFocus — selectItem', () => {
+  afterEach(() => { document.body.innerHTML = '' })
+
+  it('sets activeItemId to the clicked item', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS }))
+    act(() => result.current.selectItem('b'))
+    expect(result.current.activeItemId).toBe('b')
+  })
+
+  it('emits map:setactivefeature then map:selectfeature for the clicked item', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS, eventBus: eb }))
+    act(() => result.current.selectItem('b'))
+    expect(eb.emit).toHaveBeenNthCalledWith(1, SET_ACTIVE, { id: 'b' })
+    expect(eb.emit).toHaveBeenNthCalledWith(2, SELECT)
+  })
+
+  it('moves real DOM focus to the clicked option', () => {
+    const refs = makeRefs()
+    const option = document.createElement('li')
+    option.dataset.id = 'b'
+    option.focus = jest.fn()
+    refs.spatialListRef.current.appendChild(option)
+    const { result } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    act(() => result.current.selectItem('b'))
+    expect(option.focus).toHaveBeenCalledWith({ preventScroll: true })
+  })
+
+  it('does not throw when eventBus is not provided', () => {
+    const { result } = renderHook(() => useSpatialListFocus({ ...makeRefs(), items: ITEMS }))
+    expect(() => act(() => result.current.selectItem('b'))).not.toThrow()
+  })
+
+  it('does not throw when spatialListRef.current is null (e.g. unmounted)', () => {
+    const refs = { ...makeRefs(), spatialListRef: { current: null } }
+    const { result } = renderHook(() => useSpatialListFocus({ ...refs, items: ITEMS }))
+    expect(() => act(() => result.current.selectItem('b'))).not.toThrow()
+    expect(result.current.activeItemId).toBe('b') // state still updates even though there's no element to focus
+  })
+})