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

package/src/App/components/PopupMenu/PopupMenu.jsx

@@ -21,7 +21,8 @@ const MenuItem = ({ item, isSelected, hiddenButtons, disabledButtons, pressedBut
   </li>
 )
 
-export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, startPos, startIndex, menuRef, items, setIsOpen, buttonRect }) => {
+// isOpen defaults to true so direct/standalone usage doesn't need to pass it.
+export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, startPos, startIndex, menuRef, items, setIsOpen, buttonRect, isOpen = true }) => {
   const { id } = useConfig()
   const { buttonRefs, buttonConfig, hiddenButtons, disabledButtons, pressedButtons, layoutRefs } = useApp()
   const instigatorKey = buttonId ?? instigatorId
@@ -43,7 +44,8 @@ export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, start
     id,
     menuRef,
     setIsOpen,
-    buttonRect
+    buttonRect,
+    isOpen
   })
 
   return createPortal(
@@ -56,11 +58,13 @@ export const PopupMenu = ({ popupMenuId, buttonId, instigatorId, pluginId, start
       style={menuStyle}
       role='menu' // NOSONAR
       tabIndex='-1'
+      hidden={!isOpen}
       aria-labelledby={instigatorKey}
       aria-activedescendant={index >= 0 ? `${id}-${stringToKebab(items[index].id)}` : undefined}
       onKeyDown={handleMenuKeyDown}
     >
-      {items.map((item, i) => (
+      {/* Items only mount once open — the <ul> above stays in the DOM either way. */}
+      {isOpen && items.map((item, i) => (
         <MenuItem
           key={item.id}
           item={item}

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

@@ -651,4 +651,75 @@ describe('PopupMenu', () => {
     window.dispatchEvent(new Event('resize'))
     expect(mockSetIsOpen).toHaveBeenCalledWith(false)
   })
+
+  describe('isOpen (always-mounted, hidden-toggle)', () => {
+    it('renders a hidden, empty menu when isOpen is false, without grabbing focus or item content', () => {
+      renderMenu({ isOpen: false })
+      const ul = screen.getByRole('menu', { hidden: true })
+      expect(ul).toHaveAttribute('hidden')
+      expect(screen.queryByText('Item 1')).not.toBeInTheDocument()
+      expect(document.activeElement).not.toBe(ul)
+    })
+
+    it('keeps the same ul node across an isOpen transition (no swap/remount) and un-hides it once open', () => {
+      const { rerender } = renderMenu({ isOpen: false })
+      const ulWhileClosed = screen.getByRole('menu', { hidden: true })
+
+      rerender(
+        <PopupMenu
+          id='menu'
+          pluginId='plugin1'
+          instigatorId='instigator'
+          startPos='first'
+          menuRef={menuRef}
+          items={items}
+          setIsOpen={mockSetIsOpen}
+          isOpen
+        />
+      )
+
+      const ulWhileOpen = screen.getByRole('menu')
+      expect(ulWhileOpen).toBe(ulWhileClosed)
+      expect(ulWhileOpen).not.toHaveAttribute('hidden')
+      expect(screen.getByText('Item 1')).toBeInTheDocument()
+      expect(document.activeElement).toBe(ulWhileOpen)
+    })
+
+    it('resets selection on every open rather than carrying over a stale index from a previous open', () => {
+      const { rerender } = renderMenu({ startPos: 'first', startIndex: undefined })
+      expectSelected('Item 1')
+
+      // Close, then reopen via a plain click — selection should reset, not carry over.
+      rerender(
+        <PopupMenu
+          id='menu'
+          pluginId='plugin1'
+          instigatorId='instigator'
+          menuRef={menuRef}
+          items={items}
+          setIsOpen={mockSetIsOpen}
+          isOpen={false}
+        />
+      )
+      rerender(
+        <PopupMenu
+          id='menu'
+          pluginId='plugin1'
+          instigatorId='instigator'
+          menuRef={menuRef}
+          items={items}
+          setIsOpen={mockSetIsOpen}
+          isOpen
+        />
+      )
+      expectNotSelected('Item 1')
+      expectNotSelected('Item 2')
+    })
+
+    it('defaults isOpen to true for direct/standalone usage', () => {
+      renderMenu()
+      expect(screen.getByRole('menu')).not.toHaveAttribute('hidden')
+      expect(screen.getByText('Item 1')).toBeInTheDocument()
+    })
+  })
 })

package/src/App/components/PopupMenu/usePopupMenu.js

@@ -275,12 +275,14 @@ const createMenuKeyDownHandler = ({ items, visibleIndices, index, setIndex, disa
  * @param {object}   params.menuRef          - Ref to the menu UL element.
  * @param {Function} params.setIsOpen        - Callback to open/close the menu.
  * @param {DOMRect}  params.buttonRect       - Bounding rect of the trigger button for positioning.
+ * @param {boolean}  [params.isOpen]         - Whether the menu is currently open (PopupMenu stays
+ *   mounted; this just toggles visibility, so setup/teardown here is keyed on isOpen, not mount).
  * @returns {{ index: number, handleMenuKeyDown: Function, handleItemClick: Function,
  *             menuStyle: object, menuDirection: string, menuHAlign: string }}
  */
 export const usePopupMenu = ({
   items, hiddenButtons, startIndex, startPos, instigator, instigatorKey,
-  buttonRefs, buttonConfig, disabledButtons, pluginId, evaluateProp, id, menuRef, setIsOpen, buttonRect
+  buttonRefs, buttonConfig, disabledButtons, pluginId, evaluateProp, id, menuRef, setIsOpen, buttonRect, isOpen
 }) => {
   const { dispatch, layoutRefs } = useApp()
   const viewportRef = layoutRefs.viewportRef
@@ -329,15 +331,14 @@ export const usePopupMenu = ({
     }
   }
 
+  // Keyed on isOpen (not mount) since PopupMenu stays mounted; resolveInitialIndex re-runs each
+  // open so selection resets instead of carrying over from a previous open.
   useEffect(() => {
-    menuRef.current?.focus()
-    if (startPos === 'first') {
-      setIndex(visibleIndices[0] ?? -1)
-    } else if (startPos === 'last') {
-      setIndex(visibleIndices[visibleIndices.length - 1] ?? -1) // NOSONAR .length - 1 used instead of .at(-1) for wider browser support
-    } else {
-      // No action
+    if (!isOpen) {
+      return undefined
     }
+    menuRef.current?.focus()
+    setIndex(resolveInitialIndex(startIndex, startPos, visibleIndices))
     const handleResize = () => setIsOpen(false)
     document.addEventListener('focusin', handleOutside)
     document.addEventListener('pointerdown', handleOutside)
@@ -347,7 +348,7 @@ export const usePopupMenu = ({
       document.removeEventListener('pointerdown', handleOutside)
       window.removeEventListener('resize', handleResize)
     }
-  }, [])
+  }, [isOpen])
 
   const { style: menuStyle, direction: menuDirection, halign: menuHAlign } = getMenuStyle(buttonRect)
   return { index, handleMenuKeyDown, handleItemClick, menuStyle, menuDirection, menuHAlign }

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

@@ -11,7 +11,7 @@ export const MapStatus = () => {
     <div // NOSONAR: div + status role is semantically correct here, <output> implies a calculation result
       ref={mapStatusRef}
       role='status'
-      className='im-c-viewport__status'
+      className='im-u-visually-hidden'
     />
   )
 }

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

@@ -0,0 +1,47 @@
+import React, { forwardRef } from 'react'
+import { useConfig } from '../../store/configContext.js'
+
+// Accessible spatial list: a listbox whose items are positioned to match wherever they are on
+// the map, navigable both sequentially (Arrow/Home/End) and spatially (Alt+Arrow — see
+// useSpatialListFocus.js). Content is whatever the current spatialListRegistry provider
+// contributes; `label` names it for aria-label accordingly.
+export const SpatialList = forwardRef(({ activeItemId, tabbableId, selectedIds = [], multiselectable = false, items = [], label = 'Map features', focusable = true, onFocus, onBlur, onSelectItem }, ref) => {
+  const { id } = useConfig()
+  const hasItems = items.length > 0
+  // Roving tabindex: exactly one option is a Tab stop at a time — see useSpatialListFocus.js.
+  const currentId = activeItemId ?? tabbableId
+  return (
+    <ul // NOSONAR: role='listbox' is correct for custom composite widget; native <select> cannot host SVG marker elements
+      id={`${id}-spatial-list`}
+      ref={ref}
+      role='listbox' // NOSONAR
+      aria-hidden={hasItems ? undefined : true}
+      aria-label={label}
+      aria-describedby={`${id}-keyboard-desc`}
+      aria-multiselectable={multiselectable || undefined}
+      className='im-c-spatial-list'
+      onFocus={onFocus}
+      onBlur={onBlur}
+    >
+      {items.map(item => (
+        <li // NOSONAR: role='option' overrides implicit listitem; this is the correct ARIA listbox child pattern.
+          // tabIndex/onClick let voice control and screen readers reach and activate each option
+          // directly. focusable: false (draw's vertex/midpoint items) keeps every item out of
+          // the Tab order — that population already has a full keyboard path via the map itself.
+          key={item.id} id={`${id}-spatial-list-item-${item.id}`} role='option' // NOSONAR
+          data-id={item.id}
+          tabIndex={focusable && item.id === currentId ? 0 : -1}
+          aria-selected={selectedIds.includes(item.id)}
+          // Positions the (visually clipped) option over its on-map feature, so AT overlays like
+          // Voice Control's "Show Numbers" number it at the right screen position.
+          style={item.x != null ? { left: item.x, top: item.y } : undefined}
+          onClick={() => onSelectItem?.(item.id)}
+        >
+          {item.label}
+        </li>
+      ))}
+    </ul>
+  )
+})
+
+SpatialList.displayName = 'SpatialList'

package/src/App/components/Viewport/{Features.module.scss → SpatialList.module.scss}

@@ -1,10 +1,10 @@
 @use '../../../scss/tools/index' as tools;
 
 // ===================================================
-// Component: Features
+// Component: SpatialList
 // ===================================================
 
-.im-c-features {
+.im-c-spatial-list {
   position: absolute;
   inset: 0;
   pointer-events: none;
@@ -16,10 +16,6 @@
     $is-inset: true
   );
 
-  &[data-focus-visible="true"][aria-activedescendant]::after {
-    opacity: 0;
-  }
-
   [role="option"] {
     position: absolute;
     width: 1px;
@@ -27,5 +23,9 @@
     overflow: hidden;
     clip-path: inset(50%);
     white-space: nowrap;
+    // Roving tabindex moves real focus (and click activation) onto individual options, so they
+    // need pointer events re-enabled — overridden off .im-c-spatial-list's pointer-events: none,
+    // which otherwise lets mouse interaction pass through to the map everywhere else.
+    pointer-events: auto;
   }
 }

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

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

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

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

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

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