@defra/interactive-map 0.0.22-alpha → 0.0.24-alpha

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

@@ -0,0 +1,87 @@
+import { renderHook, act } from '@testing-library/react'
+import { useMarkerCursor } from './useMarkerCursor.js'
+
+const HIT_BOUNDS = { left: 10, top: 10, right: 50, bottom: 50 }
+const CURSOR_INSIDE = { clientX: 20, clientY: 20 }
+const CURSOR_OUTSIDE = { clientX: 100, clientY: 100 }
+
+const makeMarker = (overrides = {}) => ({ id: 'marker-1', isVisible: true, symbol: 'pin', ...overrides })
+
+const makeMarkers = (marker, bounds) => {
+  const markerRefs = new Map()
+  if (bounds) markerRefs.set(marker.id, { getBoundingClientRect: () => bounds })
+  return { items: [marker], markerRefs }
+}
+
+const fireMove = (vp, { clientX, clientY }) => act(() => {
+  vp.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, clientX, clientY }))
+})
+
+let viewport
+
+beforeEach(() => {
+  viewport = document.createElement('div')
+  viewport.className = 'im-c-viewport'
+  document.body.appendChild(viewport)
+})
+
+afterEach(() => { viewport.remove() })
+
+describe('useMarkerCursor — inactive guards', () => {
+  it('does not track cursor when interactActive is false', () => {
+    const markers = makeMarkers(makeMarker(), HIT_BOUNDS)
+    renderHook(() => useMarkerCursor(markers, false, { current: viewport }))
+    fireMove(viewport, CURSOR_INSIDE)
+    expect(viewport.style.cursor).toBe('')
+  })
+
+  it('does not track cursor when viewport ref is null', () => {
+    const markers = makeMarkers(makeMarker(), HIT_BOUNDS)
+    renderHook(() => useMarkerCursor(markers, true, { current: null }))
+    fireMove(viewport, CURSOR_INSIDE)
+    expect(viewport.style.cursor).toBe('')
+  })
+})
+
+describe('useMarkerCursor — cursor tracking', () => {
+  it('sets cursor to pointer when mousemove lands inside a marker', () => {
+    const markers = makeMarkers(makeMarker(), HIT_BOUNDS)
+    renderHook(() => useMarkerCursor(markers, true, { current: viewport }))
+    fireMove(viewport, CURSOR_INSIDE)
+    expect(viewport.style.cursor).toBe('pointer')
+  })
+
+  it('cursor stays empty when mousemove is outside all markers', () => {
+    const markers = makeMarkers(makeMarker(), HIT_BOUNDS)
+    renderHook(() => useMarkerCursor(markers, true, { current: viewport }))
+    fireMove(viewport, CURSOR_OUTSIDE)
+    expect(viewport.style.cursor).toBe('')
+  })
+
+  it('cursor stays empty when marker has no ref element', () => {
+    const markers = makeMarkers(makeMarker(), null)
+    renderHook(() => useMarkerCursor(markers, true, { current: viewport }))
+    fireMove(viewport, CURSOR_INSIDE)
+    expect(viewport.style.cursor).toBe('')
+  })
+
+  it('skips standalone label markers in the cursor hit test', () => {
+    const marker = makeMarker({ label: 'lbl', symbol: null, symbolSvgContent: null })
+    const markers = makeMarkers(marker, HIT_BOUNDS)
+    renderHook(() => useMarkerCursor(markers, true, { current: viewport }))
+    fireMove(viewport, CURSOR_INSIDE)
+    expect(viewport.style.cursor).toBe('')
+  })
+
+  it('clears cursor when interactActive becomes false', () => {
+    const markers = makeMarkers(makeMarker(), HIT_BOUNDS)
+    const { rerender } = renderHook(
+      ({ active }) => useMarkerCursor(markers, active, { current: viewport }),
+      { initialProps: { active: true } }
+    )
+    fireMove(viewport, CURSOR_INSIDE)
+    expect(viewport.style.cursor).toBe('pointer')
+    act(() => rerender({ active: false }))
+    expect(viewport.style.cursor).toBe('')
+  })
+})

package/src/App/hooks/useMarkersAPI.js

@@ -50,33 +50,43 @@ const updateMarkerPositions = (items, markerRefs, mapProvider, mapSize, isMapRea
 }
 
 /**
- * Registers event bus listeners for adding and removing markers via
- * APP_ADD_MARKER and APP_REMOVE_MARKER events.
+ * Registers event bus listeners for adding, updating and removing markers via
+ * APP_ADD_MARKER, APP_UPDATE_MARKER and APP_REMOVE_MARKER events.
  *
  * @param {Object} eventBus - Application event bus
- * @param {Object} markers - Markers API object with `add` and `remove` methods
+ * @param {Object} markers - Markers API object with `add`, `update` and `remove` methods
  */
-const useMarkerEventListeners = (eventBus, markers) => {
+const useMarkerEventListeners = (eventBus, markersRef) => {
   useEffect(() => {
     const handleAddMarker = (payload = {}) => {
       if (!payload?.id || !payload?.coords) {
         return
       }
       const { id, coords, options } = payload
-      markers.add(id, coords, options)
+      markersRef.current.add(id, coords, options)
     }
     eventBus.on(events.APP_ADD_MARKER, handleAddMarker)
 
+    const handleUpdateMarker = (payload = {}) => {
+      if (!payload?.id) {
+        return
+      }
+      const { id, options } = payload
+      markersRef.current.update(id, options)
+    }
+    eventBus.on(events.APP_UPDATE_MARKER, handleUpdateMarker)
+
     const handleRemoveMarker = (id) => {
       if (!id) {
         return
       }
-      markers.remove(id)
+      markersRef.current.remove(id)
     }
     eventBus.on(events.APP_REMOVE_MARKER, handleRemoveMarker)
 
     return () => {
       eventBus.off(events.APP_ADD_MARKER, handleAddMarker)
+      eventBus.off(events.APP_UPDATE_MARKER, handleUpdateMarker)
       eventBus.off(events.APP_REMOVE_MARKER, handleRemoveMarker)
     }
   }, [])
@@ -84,8 +94,8 @@ const useMarkerEventListeners = (eventBus, markers) => {
 
 /**
  * Hook that provides the markers API and ref callback for positioning marker
- * elements on the map. Attaches `add`, `remove`, and `getMarker` methods to the
- * markers store object and keeps marker positions in sync with map render and
+ * elements on the map. Attaches `add`, `update`, `remove`, and `getMarker` methods
+ * to the markers store object and keeps marker positions in sync with map render and
  * resize events.
  *
  * @returns {{ markers: Object, markerRef: Function }}
@@ -95,6 +105,7 @@ export const useMarkers = () => {
   const { eventBus } = useService()
   const { markers, dispatch, mapSize, isMapReady } = useMap()
   const markerRefs = useRef(new Map())
+  const markersRef = useRef(markers)
 
   // Attach add, remove, and getMarker methods to the markers store object.
   // useLayoutEffect ensures these are assigned before paint so rapid clicks can't
@@ -104,6 +115,7 @@ export const useMarkers = () => {
       return
     }
 
+    markersRef.current = markers
     markers.markerRefs = markerRefs.current
 
     markers.add = (id, coords, options) => {
@@ -111,6 +123,17 @@ export const useMarkers = () => {
       dispatch({ type: 'UPSERT_LOCATION_MARKER', payload: { id, coords, ...options, x, y, isVisible: true } })
     }
 
+    markers.update = (id, options = {}) => {
+      const existing = markers.items.find(m => m.id === id)
+      if (!existing) {
+        return
+      }
+      const { coords, ...rest } = options
+      const resolvedCoords = coords ?? existing.coords
+      const { x, y } = projectCoords(resolvedCoords, mapProvider, mapSize, isMapReady)
+      dispatch({ type: 'UPSERT_LOCATION_MARKER', payload: { id, coords: resolvedCoords, ...rest, x, y } })
+    }
+
     markers.remove = (id) => {
       dispatch({ type: 'REMOVE_LOCATION_MARKER', payload: id })
     }
@@ -150,7 +173,7 @@ export const useMarkers = () => {
     updateMarkerPositions(markers.items, markerRefs.current, mapProvider, mapSize, isMapReady)
   }, [mapSize, markers.items, mapProvider, isMapReady])
 
-  useMarkerEventListeners(eventBus, markers)
+  useMarkerEventListeners(eventBus, markersRef)
 
   return { markers, markerRef }
 }

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

@@ -15,6 +15,8 @@ jest.mock('../../services/eventBus.js', () => ({
 }))
 jest.mock('../../config/appConfig.js', () => ({ scaleFactor: { small: 1, medium: 2, large: 3 } }))
 
+// ─── projectCoords ────────────────────────────────────────────────────────────
+
 describe('projectCoords', () => {
   const mockProvider = { mapToScreen: jest.fn(() => ({ x: 100, y: 200 })) }
 
@@ -29,41 +31,44 @@ describe('projectCoords', () => {
   })
 })
 
-describe('useMarkers', () => {
-  let mockMapProvider, mockDispatch, mockMarkers, mockElement, mockEventBus
-
-  beforeEach(() => {
-    mockMapProvider = { mapToScreen: jest.fn(() => ({ x: 100, y: 200 })) }
-    mockDispatch = jest.fn()
-    mockMarkers = { items: [] }
-    mockElement = { style: {} }
-    mockEventBus = { on: jest.fn(), off: jest.fn(), emit: jest.fn() }
-
-    eventBus.on = jest.fn()
-    eventBus.off = jest.fn()
-
-    useConfig.mockReturnValue({ mapProvider: mockMapProvider })
-    useService.mockReturnValue({ eventBus: mockEventBus })
-    useMap.mockReturnValue({
-      markers: mockMarkers,
-      dispatch: mockDispatch,
-      mapSize: 'medium',
-      isMapReady: true
-    })
+// ─── useMarkers shared setup ──────────────────────────────────────────────────
+
+const makeCtx = () => {
+  const ctx = {
+    mockMapProvider: { mapToScreen: jest.fn(() => ({ x: 100, y: 200 })) },
+    mockDispatch: jest.fn(),
+    mockMarkers: { items: [] },
+    mockElement: { style: {} },
+    mockEventBus: { on: jest.fn(), off: jest.fn(), emit: jest.fn() }
+  }
+  eventBus.on = jest.fn()
+  eventBus.off = jest.fn()
+  useConfig.mockReturnValue({ mapProvider: ctx.mockMapProvider })
+  useService.mockReturnValue({ eventBus: ctx.mockEventBus })
+  useMap.mockReturnValue({
+    markers: ctx.mockMarkers,
+    dispatch: ctx.mockDispatch,
+    mapSize: 'medium',
+    isMapReady: true
   })
+  return ctx
+}
+
+// ─── useMarkers — API setup ───────────────────────────────────────────────────
+
+describe('useMarkers — API setup', () => {
+  let ctx
+  beforeEach(() => { ctx = makeCtx() })
 
   it('returns markers and markerRef', () => {
     const { result } = renderHook(() => useMarkers())
-    expect(result.current).toMatchObject({ markers: mockMarkers, markerRef: expect.any(Function) })
+    expect(result.current).toMatchObject({ markers: ctx.mockMarkers, markerRef: expect.any(Function) })
   })
 
-  it('returns early when mapProvider is null (line 24)', () => {
+  it('returns early when mapProvider is null', () => {
     useConfig.mockReturnValue({ mapProvider: null })
-    mockMarkers.items = [{ id: 'm1', label: 'Test' }]
-
+    ctx.mockMarkers.items = [{ id: 'm1', label: 'Test' }]
     const { result } = renderHook(() => useMarkers())
-
-    // The markers object should not have the API methods attached
     expect(result.current.markers.add).toBeUndefined()
     expect(result.current.markers.remove).toBeUndefined()
     expect(result.current.markers.getMarker).toBeUndefined()
@@ -71,122 +76,186 @@ describe('useMarkers', () => {
   })
 
   it('getMarker returns correct marker', () => {
-    mockMarkers.items = [{ id: 'm1', label: 'First' }, { id: 'm2', label: 'Second' }]
+    ctx.mockMarkers.items = [{ id: 'm1', label: 'First' }, { id: 'm2', label: 'Second' }]
     const { result } = renderHook(() => useMarkers())
-
-    // Found
     expect(result.current.markers.getMarker('m2')).toEqual({ id: 'm2', label: 'Second' })
-    // Not found
     expect(result.current.markers.getMarker('nonexistent')).toBeUndefined()
   })
+})
 
-  it('markerRef stores and removes refs (line 54)', () => {
-    const { result } = renderHook(() => useMarkers())
-    const ref = result.current.markerRef('m1')
+// ─── useMarkers — markerRef and positioning ───────────────────────────────────
 
-    act(() => ref(mockElement))
-    expect(result.current.markers.markerRefs.get('m1')).toBe(mockElement)
+describe('useMarkers — markerRef and positioning', () => {
+  let ctx
+  beforeEach(() => { ctx = makeCtx() })
 
-    act(() => ref(null)) // line 54 early return
+  it('markerRef stores and removes DOM refs', () => {
+    const { result } = renderHook(() => useMarkers())
+    const ref = result.current.markerRef('m1')
+    act(() => ref(ctx.mockElement))
+    expect(result.current.markers.markerRefs.get('m1')).toBe(ctx.mockElement)
+    act(() => ref(null))
     expect(result.current.markers.markerRefs.has('m1')).toBe(false)
   })
 
-  it('updateMarkers skips missing coords or ref (line 71)', () => {
-    mockMarkers.items = [
+  it('updateMarkers skips markers with missing coords or no ref', () => {
+    ctx.mockMarkers.items = [
       { id: 'm1', coords: { lat: 1, lng: 1 } },
-      { id: 'm2', coords: null }, // line 71: missing coords
-      { id: 'm3', coords: { lat: 0, lng: 0 } } // line 71: missing ref
+      { id: 'm2', coords: null },
+      { id: 'm3', coords: { lat: 0, lng: 0 } }
     ]
     const { result } = renderHook(() => useMarkers())
-    act(() => result.current.markerRef('m1')(mockElement))
-
-    const renderCallback = mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')[1]
+    act(() => result.current.markerRef('m1')(ctx.mockElement))
+    const renderCallback = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')[1]
     act(() => renderCallback())
-    expect(mockElement.style.transform).toBe('translate(200px, 400px)')
+    expect(ctx.mockElement.style.transform).toBe('translate(200px, 400px)')
   })
 
-  it('skips map:render when not ready or no provider (line 60)', () => {
-    useMap.mockReturnValue({ markers: mockMarkers, dispatch: mockDispatch, mapSize: 'medium', isMapReady: false })
+  it('skips map:render callback when not ready or no provider', () => {
+    useMap.mockReturnValue({ markers: ctx.mockMarkers, dispatch: ctx.mockDispatch, mapSize: 'medium', isMapReady: false })
     const { result } = renderHook(() => useMarkers())
-    act(() => result.current.markerRef('m1')(mockElement))
-
-    const renderCallback = mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')?.[1]
-    if (renderCallback) act(() => renderCallback()) // line 60: early return
+    act(() => result.current.markerRef('m1')(ctx.mockElement))
+    const renderCallback = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')?.[1]
+    if (renderCallback) act(() => renderCallback())
+    expect(ctx.mockElement.style.transform).toBeUndefined()
   })
 
   it('updates positions on mapSize change', () => {
-    mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 } }]
+    ctx.mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 } }]
     const { result, rerender } = renderHook(() => useMarkers())
-    act(() => result.current.markerRef('m1')(mockElement))
-
-    useMap.mockReturnValue({
-      markers: mockMarkers,
-      dispatch: mockDispatch,
-      mapSize: 'large',
-      isMapReady: true
-    })
+    act(() => result.current.markerRef('m1')(ctx.mockElement))
+    useMap.mockReturnValue({ markers: ctx.mockMarkers, dispatch: ctx.mockDispatch, mapSize: 'large', isMapReady: true })
     rerender()
-    expect(mockElement.style.transform).toBe('translate(300px, 600px)')
+    expect(ctx.mockElement.style.transform).toBe('translate(300px, 600px)')
   })
+})
 
-  it('handles app:addmarker safely', () => {
-    renderHook(() => useMarkers())
-    const addPayload = { id: 'm1', coords: { lat: 1, lng: 1 }, options: { label: 'Test' } }
+// ─── useMarkers — add/update/remove event handlers ───────────────────────────
 
-    const handleAddMarker = mockEventBus.on.mock.calls.find(call => call[0] === 'app:addmarker')[1]
-    act(() => handleAddMarker(addPayload))
-    expect(mockDispatch).toHaveBeenCalledWith({
+describe('useMarkers — add/update/remove event handlers', () => {
+  let ctx
+  beforeEach(() => { ctx = makeCtx() })
+
+  it('handles app:addmarker — dispatches with projected coords', () => {
+    renderHook(() => useMarkers())
+    const handleAddMarker = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:addmarker')[1]
+    act(() => handleAddMarker({ id: 'm1', coords: { lat: 1, lng: 1 }, options: { label: 'Test' } }))
+    expect(ctx.mockDispatch).toHaveBeenCalledWith({
       type: 'UPSERT_LOCATION_MARKER',
       payload: { id: 'm1', coords: { lat: 1, lng: 1 }, label: 'Test', x: 200, y: 400, isVisible: true }
     })
   })
 
-  it('does not crash on undefined/null payload', () => {
+  it('handles app:addmarker guard — ignores missing id or coords', () => {
     renderHook(() => useMarkers())
-    const handleAddMarker = mockEventBus.on.mock.calls.find(call => call[0] === 'app:addmarker')[1]
-
+    const handleAddMarker = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:addmarker')[1]
     act(() => handleAddMarker(undefined))
     act(() => handleAddMarker(null))
-    act(() => handleAddMarker({})) // missing id
-    act(() => handleAddMarker({ id: 'm1' })) // missing coords
-    expect(mockDispatch).not.toHaveBeenCalled()
+    act(() => handleAddMarker({}))
+    act(() => handleAddMarker({ id: 'm1' }))
+    expect(ctx.mockDispatch).not.toHaveBeenCalled()
   })
 
-  it('handles app:removemarker safely (guard)', () => {
+  it('handles app:updatemarker guard — ignores missing id (lines 71-73)', () => {
+    ctx.mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 } }]
     renderHook(() => useMarkers())
-    const handleRemoveMarker = mockEventBus.on.mock.calls.find(call => call[0] === 'app:removemarker')[1]
+    const handleUpdateMarker = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:updatemarker')[1]
+    act(() => handleUpdateMarker(undefined))
+    act(() => handleUpdateMarker(null))
+    act(() => handleUpdateMarker({}))
+    expect(ctx.mockDispatch).not.toHaveBeenCalled()
+  })
 
-    act(() => handleRemoveMarker('m1')) // valid id
-    expect(mockDispatch).toHaveBeenCalledWith({ type: 'REMOVE_LOCATION_MARKER', payload: 'm1' })
+  it('handles app:updatemarker — dispatches update for valid id (lines 74-75)', () => {
+    ctx.mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 } }]
+    renderHook(() => useMarkers())
+    const handleUpdateMarker = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:updatemarker')[1]
+    act(() => handleUpdateMarker({ id: 'm1', options: { showLabel: true } }))
+    expect(ctx.mockDispatch).toHaveBeenCalledWith({
+      type: 'UPSERT_LOCATION_MARKER',
+      payload: { id: 'm1', coords: { lat: 1, lng: 1 }, showLabel: true, x: 200, y: 400 }
+    })
+  })
 
-    act(() => handleRemoveMarker(undefined)) // guard triggers
+  it('handles app:removemarker — dispatches and guards null/undefined', () => {
+    renderHook(() => useMarkers())
+    const handleRemoveMarker = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:removemarker')[1]
+    act(() => handleRemoveMarker('m1'))
+    expect(ctx.mockDispatch).toHaveBeenCalledWith({ type: 'REMOVE_LOCATION_MARKER', payload: 'm1' })
+    act(() => handleRemoveMarker(undefined))
     act(() => handleRemoveMarker(null))
-    expect(mockDispatch).toHaveBeenCalledTimes(1)
+    expect(ctx.mockDispatch).toHaveBeenCalledTimes(1)
   })
+})
+
+// ─── useMarkers — markers.update ─────────────────────────────────────────────
 
-  it('cleans up map:render listener on unmount', () => {
+describe('useMarkers — markers.update', () => {
+  let ctx
+  beforeEach(() => { ctx = makeCtx() })
+
+  it('dispatches using existing coords when none provided (lines 127-134)', () => {
+    ctx.mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 }, label: 'Old' }]
     const { result } = renderHook(() => useMarkers())
+    act(() => result.current.markers.update('m1', { showLabel: true }))
+    expect(ctx.mockDispatch).toHaveBeenCalledWith({
+      type: 'UPSERT_LOCATION_MARKER',
+      payload: { id: 'm1', coords: { lat: 1, lng: 1 }, showLabel: true, x: 200, y: 400 }
+    })
+  })
 
-    let cleanup
-    act(() => { cleanup = result.current.markerRef('m1')(mockElement) })
+  it('is a no-op when marker id is not found (lines 128-130)', () => {
+    ctx.mockMarkers.items = []
+    const { result } = renderHook(() => useMarkers())
+    act(() => result.current.markers.update('nonexistent', { showLabel: true }))
+    expect(ctx.mockDispatch).not.toHaveBeenCalled()
+  })
 
-    const updateCallback = mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')[1]
-    act(() => { if (cleanup) cleanup() })
+  it('uses provided coords over existing (lines 131-133)', () => {
+    ctx.mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 } }]
+    const { result } = renderHook(() => useMarkers())
+    const newCoords = { lat: 5, lng: 5 }
+    act(() => result.current.markers.update('m1', { coords: newCoords, showLabel: true }))
+    expect(ctx.mockDispatch).toHaveBeenCalledWith({
+      type: 'UPSERT_LOCATION_MARKER',
+      payload: { id: 'm1', coords: newCoords, showLabel: true, x: 200, y: 400 }
+    })
+  })
 
-    expect(mockEventBus.off).toHaveBeenCalledWith('map:render', updateCallback)
+  it('uses default empty options when none provided (line 126)', () => {
+    ctx.mockMarkers.items = [{ id: 'm1', coords: { lat: 1, lng: 1 } }]
+    const { result } = renderHook(() => useMarkers())
+    act(() => result.current.markers.update('m1'))
+    expect(ctx.mockDispatch).toHaveBeenCalledWith({
+      type: 'UPSERT_LOCATION_MARKER',
+      payload: { id: 'm1', coords: { lat: 1, lng: 1 }, x: 200, y: 400 }
+    })
   })
+})
 
-  it('cleans up eventBus listeners on unmount', () => {
-    const { unmount } = renderHook(() => useMarkers())
+// ─── useMarkers — cleanup ─────────────────────────────────────────────────────
 
-    // Get the registered callbacks
-    const addCallback = mockEventBus.on.mock.calls.find(call => call[0] === 'app:addmarker')[1]
-    const removeCallback = mockEventBus.on.mock.calls.find(call => call[0] === 'app:removemarker')[1]
+describe('useMarkers — cleanup', () => {
+  let ctx
+  beforeEach(() => { ctx = makeCtx() })
 
-    unmount()
+  it('cleans up map:render listener when markerRef is called with null', () => {
+    const { result } = renderHook(() => useMarkers())
+    let cleanup
+    act(() => { cleanup = result.current.markerRef('m1')(ctx.mockElement) })
+    const updateCallback = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')[1]
+    act(() => { if (cleanup) cleanup() })
+    expect(ctx.mockEventBus.off).toHaveBeenCalledWith('map:render', updateCallback)
+  })
 
-    // Verify both listeners were removed
-    expect(mockEventBus.off).toHaveBeenCalledWith('app:addmarker', addCallback)
-    expect(mockEventBus.off).toHaveBeenCalledWith('app:removemarker', removeCallback)
+  it('cleans up add/update/remove eventBus listeners on unmount', () => {
+    const { unmount } = renderHook(() => useMarkers())
+    const addCallback = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:addmarker')[1]
+    const updateCallback = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:updatemarker')[1]
+    const removeCallback = ctx.mockEventBus.on.mock.calls.find(call => call[0] === 'app:removemarker')[1]
+    unmount()
+    expect(ctx.mockEventBus.off).toHaveBeenCalledWith('app:addmarker', addCallback)
+    expect(ctx.mockEventBus.off).toHaveBeenCalledWith('app:updatemarker', updateCallback)
+    expect(ctx.mockEventBus.off).toHaveBeenCalledWith('app:removemarker', removeCallback)
   })
 })

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

@@ -256,9 +256,10 @@ describe('useModalPanelBehaviour', () => {
     })
 
     it('handles null focus targets gracefully', () => {
+      refs.panel.current.focus = jest.fn()
       render(<TestComponent />)
       dispatchFocusIn(null)
-      expect(true).toBe(true)
+      expect(refs.panel.current.focus).not.toHaveBeenCalled()
     })
   })
 

package/src/App/layout/Layout.jsx

@@ -10,6 +10,7 @@ import { Attributions } from '../components/Attributions/Attributions'
 import { layoutSlots } from '../renderer/slots'
 import { SlotRenderer } from '../renderer/SlotRenderer'
 import { HtmlElementHost } from '../renderer/HtmlElementHost'
+import { Hints } from '../components/Hints/Hints.jsx'
 import { getMapThemeVars } from '../../config/mapTheme.js'
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
@@ -110,6 +111,7 @@ export const Layout = () => {
           </div>
         </div>
       </div>
+      <Hints />
       <HtmlElementHost />
     </div>
   )

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

@@ -21,6 +21,9 @@ jest.mock('../components/Attributions/Attributions', () => ({
 jest.mock('../renderer/SlotRenderer', () => ({
   SlotRenderer: jest.fn(({ slot }) => <div data-testid={`slot-${slot.toLowerCase()}`} />)
 }))
+jest.mock('../components/Hints/Hints', () => ({
+  Hints: jest.fn(() => null)
+}))
 
 // Mock hooks
 jest.mock('../store/configContext', () => ({ useConfig: jest.fn() }))

package/src/App/registry/keyboardShortcutRegistry.js

@@ -10,8 +10,9 @@ const pluginShortcutIds = new Set()
 let providerSupportedIds = new Set()
 
 export const registerKeyboardShortcut = ({ shortcut }) => {
-  // Only add if we haven't seen this ID before
-  if (!pluginShortcutIds.has(shortcut.id)) {
+  if (pluginShortcutIds.has(shortcut.id)) {
+    pluginShortcutHelp[pluginShortcutHelp.findIndex(s => s.id === shortcut.id)] = shortcut
+  } else {
     pluginShortcutIds.add(shortcut.id)
     pluginShortcutHelp.push(shortcut)
   }

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

@@ -29,17 +29,15 @@ describe('keyboardShortcutRegistry', () => {
     expect(shortcuts).toContain(shortcut)
   })
 
-  test('registerKeyboardShortcut should ignore duplicate plugin shortcuts', () => {
+  test('registerKeyboardShortcut updates an existing shortcut when re-registered with the same id', () => {
     const shortcut = { id: 'duplicate', description: 'First' }
-    const duplicateShortcut = { id: 'duplicate', description: 'Second' }
-    // Register the first one
+    const updatedShortcut = { id: 'duplicate', description: 'Second' }
     registerKeyboardShortcut({ shortcut })
-    // Try to register a second shortcut with the same ID
-    registerKeyboardShortcut({ shortcut: duplicateShortcut })
+    registerKeyboardShortcut({ shortcut: updatedShortcut })
     const shortcuts = getKeyboardShortcuts()
-    // Only the first shortcut should exist
-    expect(shortcuts).toContain(shortcut)
-    expect(shortcuts).not.toContain(duplicateShortcut)
+    expect(shortcuts).toContain(updatedShortcut)
+    expect(shortcuts).not.toContain(shortcut)
+    expect(shortcuts.filter(s => s.id === 'duplicate')).toHaveLength(1)
   })
 
   test('setProviderSupportedShortcuts should filter core shortcuts', () => {

package/src/App/renderer/mapButtons.js

@@ -52,10 +52,14 @@ function getMatchingButtons ({ appState, buttonConfig, slot, evaluateProp }) {
 function createButtonClickHandler (btn, appState, evaluateProp) {
   const [, config] = btn
   const isPanelOpen = !!(config.panelId && appState.openPanels[config.panelId])
+  const isToggle = config.isPressed !== undefined || !!config.pressedWhen
 
   return (e) => {
     if (typeof config.onClick === 'function') {
       config.onClick(e, evaluateProp(ctx => ctx, config.pluginId))
+      if (!isToggle && !config.keepFocus) {
+        requestAnimationFrame(() => appState.layoutRefs.viewportRef.current?.focus())
+      }
       return
     }
 
@@ -65,7 +69,7 @@ function createButtonClickHandler (btn, appState, evaluateProp) {
         type: isPanelOpen ? 'CLOSE_PANEL' : 'OPEN_PANEL',
         payload: isPanelOpen
           ? config.panelId
-          : { panelId: config.panelId, props: { triggeringElement } }
+          : { panelId: config.panelId, props: { triggeringElement }, ...(config.keepFocus && { focusOnOpen: false }) }
       })
     }
   }