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

package/src/App/components/Viewport/{Features.test.jsx → SpatialList.test.jsx}

@@ -1,7 +1,7 @@
 import React, { useRef } from 'react'
 import { render, fireEvent, act } from '@testing-library/react'
-import { Features } from './Features.jsx'
-import { useFeatureFocus } from '../../hooks/useFeatureFocus.js'
+import { SpatialList } from './SpatialList.jsx'
+import { useSpatialListFocus } from '../../hooks/useSpatialListFocus.js'
 import { useConfig } from '../../store/configContext.js'
 
 jest.mock('../../store/configContext.js', () => ({ useConfig: jest.fn() }))
@@ -19,145 +19,162 @@ beforeEach(() => {
   useConfig.mockReturnValue({ id: APP_ID })
 })
 
-// ─── Features — rendering ─────────────────────────────────────────────────────
+// ─── SpatialList — rendering ─────────────────────────────────────────────────────
 
-describe('Features — rendering', () => {
+describe('SpatialList — rendering', () => {
   it('renders a listbox with the correct id', () => {
-    const { container } = render(<Features />)
-    expect(container.querySelector(`#${APP_ID}-features`)).toBeTruthy()
+    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(<Features />)
+    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(<Features items={ITEMS} />)
+    const { container } = render(<SpatialList items={ITEMS} />)
     const options = container.querySelectorAll(OPTION)
     expect(options).toHaveLength(2)
-    expect(options[0].getAttribute('id')).toBe(`${APP_ID}-feature-f1`)
+    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}-feature-f2`)
+    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(<Features items={itemsWithPosition} />)
+    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(<Features items={ITEMS} />)
+    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(<Features items={ITEMS} selectedIds={['f1']} />)
+    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(<Features items={ITEMS} selectedIds={['f1', 'f2']} />)
+    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 activeFeatureId alone', () => {
-    const { container } = render(<Features items={ITEMS} activeFeatureId='f1' />)
+  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(<Features items={ITEMS} activeFeatureId='f2' />)
+    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 activeFeatureId is absent', () => {
-    const { container } = render(<Features items={ITEMS} tabbableId='f1' />)
+  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(<Features items={ITEMS} multiselectable />)
+    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(<Features items={ITEMS} />)
+    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(<Features items={ITEMS} />)
+    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(<Features />)
+    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(<Features />)
+    const { container } = render(<SpatialList />)
     expect(container.querySelector(LISTBOX).getAttribute('aria-describedby')).toBe(`${APP_ID}-keyboard-desc`) // NOSONAR
   })
 })
 
-// ─── Features — interactions ──────────────────────────────────────────────────
+// ─── SpatialList — interactions ──────────────────────────────────────────────────
 
-describe('Features — interactions', () => {
+describe('SpatialList — interactions', () => {
   it('calls onFocus when the listbox receives focus', () => {
     const onFocus = jest.fn()
-    const { container } = render(<Features onFocus={onFocus} />)
+    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(<Features onBlur={onBlur} />)
+    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(<Features items={ITEMS} onSelectItem={onSelectItem} />)
+    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(<Features items={ITEMS} />)
+    const { container } = render(<SpatialList items={ITEMS} />)
     expect(() => fireEvent.click(container.querySelectorAll(OPTION)[0])).not.toThrow() // NOSONAR
   })
 })
 
-// ─── Features + useFeatureFocus — roving tabindex wired together for real ────
+// ─── SpatialList + useSpatialListFocus — roving tabindex wired together for real ────
 //
-// The tests above exercise Features in isolation (mocked onFocus/onBlur), and
-// useFeatureFocus.test.js exercises the hook in isolation (onFocus/onBlur called
+// 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>.
@@ -165,19 +182,19 @@ describe('Features — interactions', () => {
 
 const RovingHarness = ({ eventBus }) => {
   const viewportRef = useRef(document.createElement('div'))
-  const featuresRef = useRef(null)
-  const { activeFeatureId, tabbableId, selectedIds, onFocus, onBlur, selectItem } = useFeatureFocus({
-    viewportRef, featuresRef, items: ITEMS, eventBus, hints: { subscribe: () => () => {}, dismiss: () => {} }
+  const spatialListRef = useRef(null)
+  const { activeItemId, tabbableId, selectedIds, onFocus, onBlur, selectItem } = useSpatialListFocus({
+    viewportRef, spatialListRef, items: ITEMS, eventBus, hints: { subscribe: () => () => {}, dismiss: () => {} }
   })
   return (
-    <Features
-      ref={featuresRef} activeFeatureId={activeFeatureId} tabbableId={tabbableId} selectedIds={selectedIds}
+    <SpatialList
+      ref={spatialListRef} activeItemId={activeItemId} tabbableId={tabbableId} selectedIds={selectedIds}
       items={ITEMS} onFocus={onFocus} onBlur={onBlur} onSelectItem={selectItem}
     />
   )
 }
 
-describe('Features + useFeatureFocus — roving tabindex real focus events', () => {
+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} />)
@@ -185,7 +202,7 @@ describe('Features + useFeatureFocus — roving tabindex real focus events', ()
     eb.emit.mockClear()
     fireEvent.keyDown(container.querySelector(LISTBOX), { key: 'ArrowDown' }) // NOSONAR
     expect(eb.emit).toHaveBeenCalledTimes(1)
-    expect(eb.emit).toHaveBeenCalledWith('map:setactivefeature', { id: 'f2' })
+    expect(eb.emit).toHaveBeenCalledWith('map:setactiveitem', { id: 'f2' })
   })
 
   it('moves real DOM focus to the next option on ArrowDown', () => {
@@ -197,7 +214,7 @@ describe('Features + useFeatureFocus — roving tabindex real focus events', ()
   })
 
   // A real pub/sub bus, with a minimal fake "interact plugin" listening on it — mirroring what
-  // useMapItemList.js actually does: track the last map:setactivefeature id, and on
+  // 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.
@@ -209,8 +226,8 @@ describe('Features + useFeatureFocus — roving tabindex real focus events', ()
       off: (event, fn) => { listeners[event] = (listeners[event] ?? []).filter(f => f !== fn) },
       emit: (event, payload) => { (listeners[event] ?? []).forEach(fn => fn(payload)) }
     }
-    bus.on('map:setactivefeature', ({ id }) => { lastActiveId = id })
-    bus.on('map:selectfeature', () => {
+    bus.on('map:setactiveitem', ({ id }) => { lastActiveId = id })
+    bus.on('map:selectitem', () => {
       bus.emit('interact:selectionchange', { selectedMarkers: lastActiveId ? [lastActiveId] : [] })
     })
     return bus

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, tabbableId, selectedIds, onFocus: handleFeaturesFocus, onBlur: handleFeaturesBlur, selectItem } = 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)
 
@@ -94,7 +104,7 @@ export const Viewport = () => {
           <Markers />
         </div>
       </div>
-      <Features ref={featuresRef} activeFeatureId={activeFeatureId} tabbableId={tabbableId} selectedIds={selectedIds} multiselectable={multiselectable} items={featureItems} onFocus={onFeaturesFocus} onBlur={onFeaturesBlur} onSelectItem={selectItem} />
+      <SpatialList ref={spatialListRef} activeItemId={activeItemId} tabbableId={tabbableId} selectedIds={selectedIds} multiselectable={multiselectable} items={spatialListItems} label={spatialListLabel} focusable={spatialListFocusable} onFocus={onSpatialListFocus} onBlur={onSpatialListBlur} onSelectItem={selectItem} />
     </>
   )
 }

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

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

package/src/App/hooks/useCrossHairAPI.js

@@ -36,13 +36,13 @@ const assignCrossHairAPI = (crossHair, el, mapProvider, dispatch, updatePosition
   // tree while invisible. An earlier version kept it ax-tree-present here so Voice Control
   // could re-summon it by name, but that made "Show Names" put a "Target" label over
   // nothing whenever it was genuinely hidden, which is more confusing than helpful. Voice
-  // Control's real route back is opening MoveControls (a normal, always-visible, always-named
-  // button) — see isMoveControlsOpen below — so the crosshair itself doesn't need to stay
-  // discoverable while it's not actually there. Blocked outright while MoveControls is open:
+  // Control's real route back is opening MapControls (a normal, always-visible, always-named
+  // button) — see isMapControlsOpen below — so the crosshair itself doesn't need to stay
+  // discoverable while it's not actually there. Blocked outright while MapControls is open:
   // that panel is a deliberate, explicit "I can't drag/pinch this map" signal from the user,
   // which should win over whatever mouse-vs-touch/keyboard inference would otherwise decide.
   crossHair.hide = () => {
-    if (crossHair.isMoveControlsOpen) {
+    if (crossHair.isMapControlsOpen) {
       return
     }
     el.style.display = 'none'
@@ -124,7 +124,7 @@ export const useCrossHair = () => {
   // read the stale value and incorrectly block itself. Setting it directly in the render body
   // (matches DrawInit.jsx's shouldShowCrosshairRef convention) guarantees it's current before
   // ANY component's effects run, since React finishes rendering the whole tree first.
-  crossHair.isMoveControlsOpen = expandedButtons?.has('moveControls')
+  crossHair.isMapControlsOpen = expandedButtons?.has('mapControls')
 
   return {
     crossHair,

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

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

package/src/App/hooks/useHintsAPI.js

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