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

package/src/App/hooks/useSpatialListItems.js

@@ -0,0 +1,51 @@
+import { useState, useEffect } from 'react'
+
+const SET_SPATIAL_LIST = 'map:setspatiallist'
+const SET_SPATIAL_LIST_SUPPRESSED = 'map:setspatiallistsuppressed'
+
+/**
+ * Subscribes to map:setspatiallist for the listbox item list, and
+ * map:setspatiallistsuppressed (any plugin can emit this) to report items as empty while
+ * suppressed regardless of what's actually visible — which is what drives <SpatialList>'s own
+ * tabIndex/aria-hidden.
+ *
+ * Items always carry at least { id, label, x?, y? } — SpatialList.jsx/useSpatialListFocus.js
+ * only ever read those. Whichever plugin currently owns the list (via spatialListRegistry —
+ * interact today, draw's edit-mode vertices in future) may include further fields of its own
+ * on each item; those simply ride along unused here. `label` is that same owner's own name for
+ * what the list currently represents (e.g. "Map features", or "Shape points" while draw holds
+ * an exclusive claim) — see spatialListRegistry.js.
+ *
+ * @param {object} eventBus
+ * @returns {{ items: Array<{ id: string, label: string, x?: number, y?: number }>, multiselectable: boolean, label: string|undefined, focusable: boolean }}
+ */
+export function useSpatialListItems (eventBus) {
+  const [items, setItems] = useState([])
+  const [multiselectable, setMultiselectable] = useState(false)
+  const [label, setLabel] = useState(undefined)
+  const [focusable, setFocusable] = useState(true)
+  const [suppressed, setSuppressed] = useState(false)
+
+  useEffect(() => {
+    if (!eventBus) {
+      return undefined
+    }
+    const handleSetSpatialList = ({ items: next = [], multiselectable: nextMultiselectable = false, label: nextLabel, focusable: nextFocusable = true } = {}) => {
+      setItems(next)
+      setMultiselectable(nextMultiselectable)
+      setLabel(nextLabel)
+      setFocusable(nextFocusable)
+    }
+    const handleSuppressed = ({ suppressed: next = false } = {}) => {
+      setSuppressed(next)
+    }
+    eventBus.on(SET_SPATIAL_LIST, handleSetSpatialList)
+    eventBus.on(SET_SPATIAL_LIST_SUPPRESSED, handleSuppressed)
+    return () => {
+      eventBus.off(SET_SPATIAL_LIST, handleSetSpatialList)
+      eventBus.off(SET_SPATIAL_LIST_SUPPRESSED, handleSuppressed)
+    }
+  }, [eventBus])
+
+  return { items: suppressed ? [] : items, multiselectable, label, focusable }
+}

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

@@ -0,0 +1,217 @@
+import { renderHook, act } from '@testing-library/react'
+import { useSpatialListItems } from './useSpatialListItems.js'
+
+const SET_FEATURES = 'map:setspatiallist' // NOSONAR
+const SET_FEATURES_SUPPRESSED = 'map:setspatiallistsuppressed' // NOSONAR
+
+const makeEventBus = () => {
+  const listeners = {}
+  return {
+    on: jest.fn((eventName, fn) => { listeners[eventName] = fn }),
+    off: jest.fn(),
+    emit: (eventName, payload) => listeners[eventName]?.(payload)
+  }
+}
+
+// ─── useSpatialListItems — initial state ─────────────────────────────────────────
+
+describe('useSpatialListItems — initial state', () => {
+  it('returns empty items and multiselectable false before any event', () => {
+    const { result } = renderHook(() => useSpatialListItems(makeEventBus()))
+    expect(result.current.items).toEqual([])
+    expect(result.current.multiselectable).toBe(false)
+  })
+
+  it('returns empty items and multiselectable false when eventBus is undefined', () => {
+    const { result } = renderHook(() => useSpatialListItems(undefined))
+    expect(result.current.items).toEqual([])
+    expect(result.current.multiselectable).toBe(false)
+  })
+})
+
+// ─── useSpatialListItems — event subscription ────────────────────────────────────
+
+describe('useSpatialListItems — event subscription', () => {
+  it('subscribes to map:setfeatures on mount', () => {
+    const eb = makeEventBus()
+    renderHook(() => useSpatialListItems(eb))
+    expect(eb.on).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
+  })
+
+  it('subscribes to map:setfeaturessuppressed on mount', () => {
+    const eb = makeEventBus()
+    renderHook(() => useSpatialListItems(eb))
+    expect(eb.on).toHaveBeenCalledWith(SET_FEATURES_SUPPRESSED, expect.any(Function))
+  })
+
+  it('unsubscribes on unmount', () => {
+    const eb = makeEventBus()
+    const { unmount } = renderHook(() => useSpatialListItems(eb))
+    unmount()
+    expect(eb.off).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
+    expect(eb.off).toHaveBeenCalledWith(SET_FEATURES_SUPPRESSED, expect.any(Function))
+  })
+
+  it('does not subscribe when eventBus is undefined', () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    renderHook(() => useSpatialListItems(undefined))
+    expect(spy).not.toHaveBeenCalled()
+    spy.mockRestore()
+  })
+})
+
+// ─── useSpatialListItems — items updates ─────────────────────────────────────────
+
+describe('useSpatialListItems — items updates', () => {
+  it('updates items when map:setfeatures is emitted', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    const items = [{ id: 'a', label: 'Feature A' }, { id: 'b', label: 'Feature B' }]
+    act(() => eb.emit(SET_FEATURES, { items }))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('clears items when emitted with an empty array', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [{ id: 'a', label: 'A' }] }))
+    act(() => eb.emit(SET_FEATURES, { items: [] }))
+    expect(result.current.items).toEqual([])
+  })
+
+  it('defaults items to empty array when items key is missing from payload', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, {}))
+    expect(result.current.items).toEqual([])
+  })
+
+  it('defaults items to empty array when the event carries no payload at all', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES))
+    expect(result.current.items).toEqual([])
+  })
+})
+
+// ─── useSpatialListItems — label updates ─────────────────────────────────────────
+
+describe('useSpatialListItems — label updates', () => {
+  it('returns undefined label before any event', () => {
+    const { result } = renderHook(() => useSpatialListItems(makeEventBus()))
+    expect(result.current.label).toBeUndefined()
+  })
+
+  it('returns whatever label the current provider declared', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [], label: 'Shape points' }))
+    expect(result.current.label).toBe('Shape points')
+  })
+
+  it('updates the label when a later event declares a different one', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [], label: 'Map features' }))
+    act(() => eb.emit(SET_FEATURES, { items: [], label: 'Shape points' }))
+    expect(result.current.label).toBe('Shape points')
+  })
+})
+
+// ─── useSpatialListItems — focusable updates ─────────────────────────────────────
+
+describe('useSpatialListItems — focusable updates', () => {
+  it('defaults to focusable: true before any event', () => {
+    const { result } = renderHook(() => useSpatialListItems(makeEventBus()))
+    expect(result.current.focusable).toBe(true)
+  })
+
+  it('defaults to focusable: true when the event omits it', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [] }))
+    expect(result.current.focusable).toBe(true)
+  })
+
+  it('reflects an explicit focusable: false from the current provider', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [], focusable: false }))
+    expect(result.current.focusable).toBe(false)
+  })
+
+  it('reverts to true once a later event omits it again (e.g. draw released its claim)', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [], focusable: false }))
+    act(() => eb.emit(SET_FEATURES, { items: [] }))
+    expect(result.current.focusable).toBe(true)
+  })
+})
+
+// ─── useSpatialListItems — multiselectable updates ───────────────────────────────
+
+describe('useSpatialListItems — multiselectable updates', () => {
+  it('sets multiselectable true when emitted with multiselectable: true', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [], multiselectable: true }))
+    expect(result.current.multiselectable).toBe(true)
+  })
+
+  it('defaults multiselectable to false when not present in payload', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [] }))
+    expect(result.current.multiselectable).toBe(false)
+  })
+})
+
+// ─── useSpatialListItems — suppression ───────────────────────────────────────────
+
+describe('useSpatialListItems — suppression', () => {
+  const items = [{ id: 'a', label: 'Feature A' }]
+
+  it('reports empty items while suppressed, regardless of what was last set', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    expect(result.current.items).toEqual([])
+  })
+
+  it('restores the last known items once suppression is lifted', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: false }))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('defaults suppressed to false when the payload omits it', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, {}))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('defaults suppressed to false when the event carries no payload at all', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('a features update received while suppressed is still applied once restored', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useSpatialListItems(eb))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    expect(result.current.items).toEqual([]) // still suppressed
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: false }))
+    expect(result.current.items).toEqual(items)
+  })
+})

package/src/App/initialiseApp.js

@@ -6,6 +6,7 @@ import { createPanelRegistry } from './registry/panelRegistry.js'
 import { createControlRegistry } from './registry/controlRegistry.js'
 import { createPluginRegistry } from './registry/pluginRegistry.js'
 import { createKeyboardShortcutRegistry } from './registry/keyboardShortcutRegistry.js'
+import { createSpatialListRegistry } from './registry/spatialListRegistry.js'
 import { mergeManifests } from './registry/mergeManifests.js'
 import { App } from './App.jsx'
 
@@ -13,13 +14,14 @@ const rootMap = new WeakMap()
 const mapProviderMap = new WeakMap()
 const registryMap = new WeakMap()
 
-const getOrCreateRegistries = (rootElement) => {
+const getOrCreateRegistries = (rootElement, eventBus) => {
   let registries = registryMap.get(rootElement)
   if (!registries) {
     const buttonRegistry = createButtonRegistry()
     const panelRegistry = createPanelRegistry()
     const controlRegistry = createControlRegistry()
     const keyboardShortcutRegistry = createKeyboardShortcutRegistry()
+    const spatialListRegistry = createSpatialListRegistry({ eventBus })
     const pluginRegistry = createPluginRegistry({
       registerButton: buttonRegistry.registerButton,
       registerPanel: panelRegistry.registerPanel,
@@ -27,7 +29,7 @@ const getOrCreateRegistries = (rootElement) => {
       registerKeyboardShortcut: keyboardShortcutRegistry.registerKeyboardShortcut
     })
 
-    registries = { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry, keyboardShortcutRegistry }
+    registries = { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry, keyboardShortcutRegistry, spatialListRegistry }
     registryMap.set(rootElement, registries)
   }
   return registries
@@ -73,7 +75,7 @@ export async function initialiseApp (rootElement, {
   }
 
   // Reuse or create registries (persist across app open/close cycles)
-  const { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry, keyboardShortcutRegistry } = getOrCreateRegistries(rootElement)
+  const { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry, keyboardShortcutRegistry, spatialListRegistry } = getOrCreateRegistries(rootElement, eventBus)
   const { registerPlugin } = pluginRegistry
 
   // Register provider-supported shortcuts
@@ -124,6 +126,7 @@ export async function initialiseApp (rootElement, {
     controlRegistry={controlRegistry}
     pluginRegistry={pluginRegistry}
     keyboardShortcutRegistry={keyboardShortcutRegistry}
+    spatialListRegistry={spatialListRegistry}
     mapProvider={mapProvider}
               />)
 

package/src/App/initialiseApp.test.js

@@ -50,6 +50,10 @@ jest.mock('./registry/keyboardShortcutRegistry.js', () => ({
   createKeyboardShortcutRegistry: jest.fn(() => mockRegistries.keyboardShortcutRegistry)
 }))
 
+jest.mock('./registry/spatialListRegistry.js', () => ({
+  createSpatialListRegistry: jest.fn(() => mockRegistries.spatialListRegistry)
+}))
+
 jest.mock('./registry/mergeManifests.js', () => ({
   mergeManifests: jest.fn((base, override) => ({ ...base, ...override }))
 }))
@@ -193,4 +197,11 @@ describe('initialiseApp', () => {
     const rendered = createRoot.mock.results[0].value.render.mock.calls[0][0]
     expect(rendered.props.keyboardShortcutRegistry).toBe(mockRegistries.keyboardShortcutRegistry)
   })
+
+  test('passes spatialListRegistry through to the rendered App', async () => {
+    await initApp()
+
+    const rendered = createRoot.mock.results[0].value.render.mock.calls[0][0]
+    expect(rendered.props.spatialListRegistry).toBe(mockRegistries.spatialListRegistry)
+  })
 })

package/src/App/layout/Layout.jsx

@@ -11,14 +11,16 @@ import { layoutSlots } from '../renderer/slots'
 import { SlotRenderer } from '../renderer/SlotRenderer'
 import { HtmlElementHost } from '../renderer/HtmlElementHost'
 import { Hints } from '../components/Hints/Hints.jsx'
+import { hasOpenModalPanel } from '../renderer/slotHelpers.js'
 import { getMapThemeVars } from '../../config/mapTheme.js'
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
 export const Layout = () => {
   const { id, mapLabel, mapHintText } = useConfig()
-  const { breakpoint, interfaceType, preferredColorScheme, layoutRefs, isLayoutReady, hasExclusiveControl, isFullscreen } = useApp()
+  const { breakpoint, interfaceType, preferredColorScheme, layoutRefs, isLayoutReady, hasExclusiveControl, isFullscreen, openPanels, panelConfig } = useApp()
   const { mapStyle } = useMap()
+  const showModalBackdrop = hasOpenModalPanel(openPanels ?? {}, panelConfig ?? {}, breakpoint)
 
   useLayoutMeasurements()
   useFocusVisible()
@@ -108,7 +110,7 @@ export const Layout = () => {
           </div>
           <div className='im-o-app__modal' ref={layoutRefs.modalRef}>
             <SlotRenderer slot={layoutSlots.MODAL} />
-            <div className='im-o-app__modal-backdrop' />
+            <div className={`im-o-app__modal-backdrop${showModalBackdrop ? ' im-o-app__modal-backdrop--visible' : ''}`} />
           </div>
         </div>
       </div>

package/src/App/layout/Layout.test.jsx

@@ -95,6 +95,27 @@ describe('Layout', () => {
     expect(screen.getByTestId('slot-top-left')).toBeInTheDocument()
     expect(screen.getByTestId('slot-bottom-right')).toBeInTheDocument()
     expect(screen.getByTestId('slot-modal')).toBeInTheDocument()
+
+    const backdrop = root.querySelector('.im-o-app__modal-backdrop')
+    expect(backdrop).toBeInTheDocument()
+    expect(backdrop).not.toHaveClass('im-o-app__modal-backdrop--visible')
+  })
+
+  test('shows the modal backdrop only while a modal-configured panel is open', () => {
+    useApp.mockReturnValue({
+      breakpoint: 'mobile',
+      interfaceType: 'map',
+      preferredColorScheme: 'dark',
+      layoutRefs: mockRefs,
+      isLayoutReady: true,
+      hasExclusiveControl: false,
+      isFullscreen: true,
+      openPanels: { settings: { props: {} } },
+      panelConfig: { settings: { mobile: { modal: true } } }
+    })
+    render(<Layout />)
+    const root = document.getElementById('myApp-im-app')
+    expect(root.querySelector('.im-o-app__modal-backdrop')).toHaveClass('im-o-app__modal-backdrop--visible')
   })
 
   test('applies "not-ready" class when layout is not ready', () => {

package/src/App/layout/layout.module.scss

@@ -363,7 +363,13 @@
     z-index: 1000;
   }
 
-  .im-c-panel + .im-o-app__modal-backdrop {
+  // Visibility is JS-driven (Layout.jsx) since multiple panels can share this slot.
+  .im-o-app__modal-backdrop {
+    display: none;
+  }
+
+  .im-o-app__modal-backdrop--visible {
+    display: block;
     position: absolute;
     top: 0;
     left: 0;

package/src/App/registry/keyboardShortcutRegistry.js

@@ -19,8 +19,8 @@ const _setProviderSupportedShortcuts = (state, ids = []) => {
 
 const _getKeyboardShortcuts = (state, appConfig = {}) => {
   const filteredCore = coreShortcuts.filter(s => {
-    // Must be supported by provider
-    if (!state.providerSupportedIds.has(s.id)) {
+    // Must be supported by the map provider, unless the shortcut is map-provider-agnostic (no capability dependency, so no adapter needs to declare it).
+    if (!s.mapProviderAgnostic && !state.providerSupportedIds.has(s.id)) {
       return false
     }
     // Check requiredConfig - all specified config values must be truthy

package/src/App/registry/keyboardShortcutRegistry.test.js

@@ -93,6 +93,22 @@ describe('createKeyboardShortcutRegistry', () => {
     ])
   })
 
+  test('a mapProviderAgnostic core shortcut is included even when no provider declares support for it', () => {
+    jest.resetModules()
+    jest.doMock('../controls/keyboardShortcuts.js', () => ({
+      coreShortcuts: [
+        { id: 'ordinary', description: 'Ordinary' },
+        { id: 'agnostic', description: 'Agnostic', mapProviderAgnostic: true }
+      ]
+    }))
+    const registry = require('./keyboardShortcutRegistry.js').createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts([]) // no provider support declared at all
+
+    expect(registry.getKeyboardShortcuts()).toEqual([
+      { id: 'agnostic', description: 'Agnostic', mapProviderAgnostic: true }
+    ])
+  })
+
   test('two registry instances are fully isolated from each other', () => {
     // This is the multi-map-on-a-page scenario: a shortcut registered by one map
     // (e.g. a plugin) must never leak into another map's help panel, and each map's

package/src/App/registry/pluginRegistry.js

@@ -73,9 +73,22 @@ export function createPluginRegistry ({ registerButton, registerPanel, registerC
     registeredPlugins.length = 0
   }
 
+  /**
+   * Look up another registered plugin's instance by id. Returns `undefined`
+   * if not registered; found doesn't mean ready to call — see services.getPlugin
+   * in docs/api/context.md.
+   *
+   * @param {string} id - Plugin id, e.g. `'draw'`.
+   * @returns {object|undefined}
+   */
+  function getPlugin (id) {
+    return registeredPlugins.find(plugin => plugin.id === id)?._originalPlugin
+  }
+
   return {
     registeredPlugins,
     registerPlugin,
+    getPlugin,
     clear
   }
 }

package/src/App/registry/pluginRegistry.test.js

@@ -185,6 +185,21 @@ describe('pluginRegistry', () => {
     })
   })
 
+  describe('getPlugin', () => {
+    it('returns the _originalPlugin reference for a registered plugin id', () => {
+      const originalPlugin = { newPolygon: jest.fn() }
+      const plugin = { id: 'draw', config: {}, manifest: {}, _originalPlugin: originalPlugin }
+
+      pluginRegistry.registerPlugin(plugin)
+
+      expect(pluginRegistry.getPlugin('draw')).toBe(originalPlugin)
+    })
+
+    it('returns undefined for an id that is not registered', () => {
+      expect(pluginRegistry.getPlugin('does-not-exist')).toBeUndefined()
+    })
+  })
+
   it('clears all registered plugins', () => {
     const pluginA = { id: 'A', config: {}, manifest: {} }
     const pluginB = { id: 'B', config: {}, manifest: {} }

package/src/App/registry/spatialListRegistry.js

@@ -0,0 +1,104 @@
+import { EVENTS as events } from '../../config/events.js'
+
+/**
+ * Central registry for plugins that contribute items to the shared spatial list (see
+ * SpatialList.jsx). Plugins register a live item provider — `{ getItems, exclusive? }` —
+ * instead of emitting the list event themselves, so exclusive takeover (draw mid-edit) and
+ * additive participation (interact's features/markers) both work safely with any number of
+ * contributors.
+ *
+ * `getItems()` returns `{ items, multiselectable, label, focusable }`, called fresh on every
+ * recompute rather than snapshotted at registration. `label` becomes the listbox's aria-label;
+ * `focusable: false` (draw's vertex/midpoint items) keeps every item out of the Tab order —
+ * see SpatialList.jsx. `exclusive: true` claims sole ownership while held (see
+ * claimExclusive/releaseExclusive); everything else is additive and gets concatenated
+ * together. Providers call notifyItemsChanged whenever their own items would differ — the
+ * registry never polls, it only recomputes in response to a caller flagging a change.
+ */
+export function createSpatialListRegistry ({ eventBus }) {
+  const providers = new Map() // pluginId -> { getItems, exclusive }
+  let exclusiveOwner = null
+
+  const recompute = () => {
+    let items = []
+    let multiselectable = false
+    let label
+    let focusable
+
+    if (exclusiveOwner && providers.has(exclusiveOwner)) {
+      const result = providers.get(exclusiveOwner).getItems() ?? {}
+      items = result.items ?? []
+      multiselectable = !!result.multiselectable
+      label = result.label
+      focusable = result.focusable
+    } else {
+      // Exclusive-capable providers only ever contribute while actually holding the
+      // claim (the branch above) — not just whenever nobody happens to hold it.
+      providers.forEach((provider) => {
+        if (provider.exclusive) { return }
+        const result = provider.getItems() ?? {}
+        items = items.concat(result.items ?? [])
+        multiselectable = multiselectable || !!result.multiselectable
+        // First additive provider (in registration order) with a label/focusable value
+        // wins — there's no principled way to merge two different values, and today
+        // only interact ever contributes additively, so this is just "whatever it
+        // declares".
+        label = label ?? result.label
+        focusable = focusable ?? result.focusable
+      })
+    }
+
+    eventBus.emit(events.MAP_SET_SPATIAL_LIST, { items, multiselectable, label, focusable })
+  }
+
+  function registerItemProvider (pluginId, { getItems, exclusive = false }) {
+    providers.set(pluginId, { getItems, exclusive })
+    recompute()
+  }
+
+  function unregisterItemProvider (pluginId) {
+    providers.delete(pluginId)
+    if (exclusiveOwner === pluginId) {
+      exclusiveOwner = null
+    }
+    recompute()
+  }
+
+  // Mirrors mapProvider.activeMoveTarget's single-claim contract (MapControls.jsx),
+  // generalised to however many participants are registered rather than always
+  // exactly two — only one exclusive claim can be held at a time, and holding it
+  // means every other registered provider is ignored until it's released.
+  function claimExclusive (pluginId) {
+    exclusiveOwner = pluginId
+    recompute()
+  }
+
+  function releaseExclusive (pluginId) {
+    if (exclusiveOwner === pluginId) {
+      exclusiveOwner = null
+      recompute()
+    }
+  }
+
+  function notifyItemsChanged (pluginId) {
+    if (!providers.has(pluginId)) { return }
+    // If someone else holds the exclusive claim, this provider isn't feeding the
+    // list right now regardless of what changed for it — nothing to recompute.
+    if (exclusiveOwner && exclusiveOwner !== pluginId) { return }
+    recompute()
+  }
+
+  function clear () {
+    providers.clear()
+    exclusiveOwner = null
+  }
+
+  return {
+    registerItemProvider,
+    unregisterItemProvider,
+    claimExclusive,
+    releaseExclusive,
+    notifyItemsChanged,
+    clear
+  }
+}