@defra/interactive-map 0.0.43-alpha → 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/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
+  }
+}

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

@@ -0,0 +1,218 @@
+import { createSpatialListRegistry } from './spatialListRegistry.js'
+
+const SET_FEATURES = 'map:setspatiallist'
+
+const makeEventBus = () => ({ emit: jest.fn() })
+
+const lastEmit = (eventBus) => eventBus.emit.mock.calls.at(-1)[1]
+
+describe('createSpatialListRegistry', () => {
+  test('registering a provider recomputes and emits its items immediately', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.registerItemProvider('a', { getItems: () => ({ items: [{ id: '1' }], multiselectable: false }) })
+    expect(eventBus.emit).toHaveBeenCalledWith(SET_FEATURES, { items: [{ id: '1' }], multiselectable: false })
+  })
+
+  test('concatenates items from every registered provider when no exclusive claim is held', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.registerItemProvider('a', { getItems: () => ({ items: [{ id: '1' }] }) })
+    registry.registerItemProvider('b', { getItems: () => ({ items: [{ id: '2' }] }) })
+    expect(lastEmit(eventBus)).toEqual({ items: [{ id: '1' }, { id: '2' }], multiselectable: false })
+  })
+
+  test('multiselectable is true if any additive provider wants it', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.registerItemProvider('a', { getItems: () => ({ items: [], multiselectable: false }) })
+    registry.registerItemProvider('b', { getItems: () => ({ items: [], multiselectable: true }) })
+    expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: true })
+  })
+
+  test('getItems is called fresh on every recompute, not snapshotted at registration', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    let current = [{ id: 'first' }]
+    registry.registerItemProvider('a', { getItems: () => ({ items: current }) })
+    expect(lastEmit(eventBus)).toEqual({ items: [{ id: 'first' }], multiselectable: false })
+
+    current = [{ id: 'second' }]
+    registry.notifyItemsChanged('a')
+    expect(lastEmit(eventBus)).toEqual({ items: [{ id: 'second' }], multiselectable: false })
+  })
+
+  test('unregistering a provider removes its items from the next recompute', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.registerItemProvider('a', { getItems: () => ({ items: [{ id: '1' }] }) })
+    registry.registerItemProvider('b', { getItems: () => ({ items: [{ id: '2' }] }) })
+    registry.unregisterItemProvider('a')
+    expect(lastEmit(eventBus)).toEqual({ items: [{ id: '2' }], multiselectable: false })
+  })
+
+  test('notifyItemsChanged for an unregistered id is a no-op', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.notifyItemsChanged('ghost')
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  describe('exclusive claims', () => {
+    test('claiming exclusive ownership excludes every other provider\'s items', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [{ id: 'feature-1' }] }) })
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [{ id: 'vertex-1' }] }), exclusive: true })
+
+      registry.claimExclusive('draw')
+      expect(lastEmit(eventBus)).toEqual({ items: [{ id: 'vertex-1' }], multiselectable: false })
+    })
+
+    test('releasing the exclusive claim reverts to the additive merge of everyone else', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [{ id: 'feature-1' }] }) })
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [{ id: 'vertex-1' }] }), exclusive: true })
+      registry.claimExclusive('draw')
+
+      registry.releaseExclusive('draw')
+      expect(lastEmit(eventBus)).toEqual({ items: [{ id: 'feature-1' }], multiselectable: false })
+    })
+
+    test('releaseExclusive from a provider that does not currently hold the claim is a no-op', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [{ id: 'feature-1' }] }) })
+      eventBus.emit.mockClear()
+
+      registry.releaseExclusive('draw') // never claimed it
+      expect(eventBus.emit).not.toHaveBeenCalled()
+    })
+
+    test('a non-exclusive-owning provider\'s own changes are ignored while someone else holds the claim', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      let interactItems = [{ id: 'feature-1' }]
+      registry.registerItemProvider('interact', { getItems: () => ({ items: interactItems }) })
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [{ id: 'vertex-1' }] }), exclusive: true })
+      registry.claimExclusive('draw')
+      eventBus.emit.mockClear()
+
+      interactItems = [{ id: 'feature-2' }] // changed while draw holds exclusive ownership
+      registry.notifyItemsChanged('interact')
+      expect(eventBus.emit).not.toHaveBeenCalled()
+    })
+
+    test('unregistering the current exclusive owner clears the claim and reverts to additive', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [{ id: 'feature-1' }] }) })
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [{ id: 'vertex-1' }] }), exclusive: true })
+      registry.claimExclusive('draw')
+
+      registry.unregisterItemProvider('draw')
+      expect(lastEmit(eventBus)).toEqual({ items: [{ id: 'feature-1' }], multiselectable: false })
+    })
+  })
+
+  describe('label', () => {
+    test('passes through the exclusive claimant\'s own label while its claim is held', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [], label: 'Map features' }) })
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [], label: 'Shape points' }), exclusive: true })
+
+      registry.claimExclusive('draw')
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false, label: 'Shape points' })
+    })
+
+    test('uses the first additive provider\'s label (in registration order) when more than one contributes', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('a', { getItems: () => ({ items: [], label: 'First' }) })
+      registry.registerItemProvider('b', { getItems: () => ({ items: [], label: 'Second' }) })
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false, label: 'First' })
+    })
+
+    test('falls back to a later provider\'s label when an earlier one declares none', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('a', { getItems: () => ({ items: [] }) }) // no label
+      registry.registerItemProvider('b', { getItems: () => ({ items: [], label: 'Second' }) })
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false, label: 'Second' })
+    })
+
+    test('label is undefined when nothing is registered', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('a', { getItems: () => ({ items: [] }) })
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false })
+    })
+  })
+
+  describe('focusable', () => {
+    test('passes through the exclusive claimant\'s own focusable: false while its claim is held', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [] }) }) // focusable defaults true
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [], focusable: false }), exclusive: true })
+
+      registry.claimExclusive('draw')
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false, focusable: false })
+    })
+
+    test('reverts to undefined (consumer default: focusable) once the claim is released', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('interact', { getItems: () => ({ items: [] }) })
+      registry.registerItemProvider('draw', { getItems: () => ({ items: [], focusable: false }), exclusive: true })
+      registry.claimExclusive('draw')
+
+      registry.releaseExclusive('draw')
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false })
+    })
+
+    test('uses the first additive provider\'s explicit focusable value when more than one contributes', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('a', { getItems: () => ({ items: [] }) }) // no explicit value
+      registry.registerItemProvider('b', { getItems: () => ({ items: [], focusable: false }) })
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false, focusable: false })
+    })
+
+    test('focusable is undefined when nothing declares it', () => {
+      const eventBus = makeEventBus()
+      const registry = createSpatialListRegistry({ eventBus })
+      registry.registerItemProvider('a', { getItems: () => ({ items: [] }) })
+      expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false })
+    })
+  })
+
+  test('clear removes every provider and any exclusive claim', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.registerItemProvider('a', { getItems: () => ({ items: [{ id: '1' }] }), exclusive: true })
+    registry.claimExclusive('a')
+
+    registry.clear()
+    eventBus.emit.mockClear()
+    registry.notifyItemsChanged('a') // 'a' is no longer registered
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('a provider whose getItems returns nothing contributes no items and does not throw', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    expect(() => registry.registerItemProvider('a', { getItems: () => undefined })).not.toThrow()
+    expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false })
+  })
+
+  test('an exclusive provider whose getItems returns nothing contributes no items while holding the claim', () => {
+    const eventBus = makeEventBus()
+    const registry = createSpatialListRegistry({ eventBus })
+    registry.registerItemProvider('draw', { getItems: () => undefined, exclusive: true })
+    expect(() => registry.claimExclusive('draw')).not.toThrow()
+    expect(lastEmit(eventBus)).toEqual({ items: [], multiselectable: false })
+  })
+})