@defra/interactive-map 0.0.21-alpha → 0.0.23-alpha

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

@@ -0,0 +1,97 @@
+import { renderHook, act } from '@testing-library/react'
+import { useFeatureItems } from './useFeatureItems.js'
+
+const SET_FEATURES = 'map:setfeatures' // NOSONAR
+
+const makeEventBus = () => {
+  const listeners = {}
+  return {
+    on: jest.fn((e, fn) => { listeners[e] = fn }),
+    off: jest.fn(),
+    emit: (e, payload) => listeners[e]?.(payload)
+  }
+}
+
+// ─── useFeatureItems — initial state ─────────────────────────────────────────
+
+describe('useFeatureItems — initial state', () => {
+  it('returns empty items and multiselectable false before any event', () => {
+    const { result } = renderHook(() => useFeatureItems(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(() => useFeatureItems(undefined))
+    expect(result.current.items).toEqual([])
+    expect(result.current.multiselectable).toBe(false)
+  })
+})
+
+// ─── useFeatureItems — event subscription ────────────────────────────────────
+
+describe('useFeatureItems — event subscription', () => {
+  it('subscribes to map:setfeatures on mount', () => {
+    const eb = makeEventBus()
+    renderHook(() => useFeatureItems(eb))
+    expect(eb.on).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
+  })
+
+  it('unsubscribes on unmount', () => {
+    const eb = makeEventBus()
+    const { unmount } = renderHook(() => useFeatureItems(eb))
+    unmount()
+    expect(eb.off).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
+  })
+
+  it('does not subscribe when eventBus is undefined', () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    renderHook(() => useFeatureItems(undefined))
+    spy.mockRestore()
+  })
+})
+
+// ─── useFeatureItems — items updates ─────────────────────────────────────────
+
+describe('useFeatureItems — items updates', () => {
+  it('updates items when map:setfeatures is emitted', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(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(() => useFeatureItems(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(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, {}))
+    expect(result.current.items).toEqual([])
+  })
+})
+
+// ─── useFeatureItems — multiselectable updates ───────────────────────────────
+
+describe('useFeatureItems — multiselectable updates', () => {
+  it('sets multiselectable true when emitted with multiselectable: true', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(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(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items: [] }))
+    expect(result.current.multiselectable).toBe(false)
+  })
+})

package/src/App/hooks/useFocusVisible.js

@@ -1,12 +1,9 @@
-import { useEffect, useRef } from 'react'
+import { useEffect } from 'react'
 import { useApp } from '../store/appContext.js'
+import { getInterfaceType } from '../../utils/detectInterfaceType.js'
 
 export function useFocusVisible () {
-  const { interfaceType, layoutRefs } = useApp()
-  const interfaceTypeRef = useRef(interfaceType)
-
-  // Keep ref in sync - synchronous update ensures it's always current
-  interfaceTypeRef.current = interfaceType
+  const { layoutRefs } = useApp()
 
   useEffect(() => {
     const scope = layoutRefs.appContainerRef.current
@@ -15,7 +12,7 @@ export function useFocusVisible () {
     }
 
     function handleFocusIn (e) {
-      e.target.dataset.focusVisible = interfaceTypeRef.current === 'keyboard'
+      e.target.dataset.focusVisible = getInterfaceType() === 'keyboard'
     }
 
     function handleFocusOut (e) {

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

@@ -1,8 +1,12 @@
 import { renderHook } from '@testing-library/react'
 import { useFocusVisible } from './useFocusVisible'
 import { useApp } from '../store/appContext.js'
+import { getInterfaceType } from '../../utils/detectInterfaceType.js'
 
 jest.mock('../store/appContext.js')
+jest.mock('../../utils/detectInterfaceType.js', () => ({
+  getInterfaceType: jest.fn(() => 'keyboard')
+}))
 
 describe('useFocusVisible', () => {
   let mockAppContainerRef, addEventListenerSpy, removeEventListenerSpy
@@ -13,8 +17,8 @@ describe('useFocusVisible', () => {
     addEventListenerSpy = jest.spyOn(document, 'addEventListener')
     removeEventListenerSpy = jest.spyOn(document, 'removeEventListener')
 
+    getInterfaceType.mockReturnValue('keyboard')
     useApp.mockReturnValue({
-      interfaceType: 'keyboard',
       layoutRefs: { appContainerRef: mockAppContainerRef }
     })
   })
@@ -26,7 +30,6 @@ describe('useFocusVisible', () => {
 
   it('returns early when no scope', () => {
     useApp.mockReturnValue({
-      interfaceType: 'keyboard',
       layoutRefs: { appContainerRef: { current: null } }
     })
 
@@ -58,10 +61,7 @@ describe('useFocusVisible', () => {
   })
 
   it('does not set focusVisible on focusin when not keyboard', () => {
-    useApp.mockReturnValue({
-      interfaceType: 'touch',
-      layoutRefs: { appContainerRef: mockAppContainerRef }
-    })
+    getInterfaceType.mockReturnValue('touch')
 
     renderHook(() => useFocusVisible())
 

package/src/App/hooks/useKeyboardHint.js

@@ -1,47 +1,26 @@
 import { useEffect } from 'react'
+import { getInterfaceType } from '../../utils/detectInterfaceType.js'
 
 export function useKeyboardHint ({
-  interfaceType,
   containerRef,
-  keyboardHintRef,
-  keyboardHintVisible,
   onViewportFocusChange
 }) {
-  const showHint = keyboardHintVisible
-
   useEffect(() => {
-    if (!showHint || !containerRef.current) {
+    const el = containerRef.current
+    if (!el) {
       return undefined
     }
-
-    const containerEl = containerRef.current
-
     const handleKeyDown = (e) => {
-      if (['Escape', 'Tab'].includes(e.key)) {
-        onViewportFocusChange(false)
-      }
-    }
-
-    const handleMouseDown = (e) => {
-      const clickedInsideViewport = containerEl.contains(e.target)
-      const clickedInsideHint = keyboardHintRef.current?.contains(e.target)
-
-      if (clickedInsideViewport && !clickedInsideHint) {
+      if (e.key === 'Escape') {
         onViewportFocusChange(false)
       }
     }
-
-    containerEl.addEventListener('keydown', handleKeyDown)
-    containerEl.addEventListener('mousedown', handleMouseDown)
-
-    return () => {
-      containerEl.removeEventListener('keydown', handleKeyDown)
-      containerEl.removeEventListener('mousedown', handleMouseDown)
-    }
-  }, [showHint, containerRef, keyboardHintRef, onViewportFocusChange])
+    el.addEventListener('keydown', handleKeyDown)
+    return () => { el.removeEventListener('keydown', handleKeyDown) }
+  }, [containerRef, onViewportFocusChange])
 
   const handleFocus = () => {
-    if (interfaceType === 'keyboard') {
+    if (getInterfaceType() === 'keyboard') {
       onViewportFocusChange(true)
     }
   }
@@ -50,9 +29,5 @@ export function useKeyboardHint ({
     onViewportFocusChange(false)
   }
 
-  return {
-    showHint,
-    handleFocus,
-    handleBlur
-  }
+  return { handleFocus, handleBlur }
 }

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

@@ -1,136 +1,86 @@
 import { renderHook, act } from '@testing-library/react'
 import { useKeyboardHint } from './useKeyboardHint'
+import { getInterfaceType } from '../../utils/detectInterfaceType.js'
 
-const createRefs = () => ({
-  containerRef: { current: document.createElement('div') },
-  keyboardHintRef: { current: document.createElement('div') }
-})
+jest.mock('../../utils/detectInterfaceType.js', () => ({
+  getInterfaceType: jest.fn(() => 'keyboard')
+}))
 
 const defaultProps = (overrides = {}) => ({
-  interfaceType: 'keyboard',
-  keyboardHintVisible: true,
+  containerRef: { current: document.createElement('div') },
   onViewportFocusChange: jest.fn(),
-  ...createRefs(),
   ...overrides
 })
 
-describe('useKeyboardHint', () => {
-  test('returns handlers and showHint', () => {
-    const { result } = renderHook(() => useKeyboardHint(defaultProps()))
+// ─── return shape ─────────────────────────────────────────────────────────────
 
-    expect(result.current.showHint).toBe(true)
+describe('useKeyboardHint — return shape', () => {
+  test('returns focus and blur handlers', () => {
+    const { result } = renderHook(() => useKeyboardHint(defaultProps()))
     expect(typeof result.current.handleFocus).toBe('function')
     expect(typeof result.current.handleBlur).toBe('function')
   })
+})
 
-  test('useEffect early-returns when showHint = false', () => {
-    const props = defaultProps({ keyboardHintVisible: false })
-    const spy = jest.spyOn(props.containerRef.current, 'addEventListener')
-
-    renderHook(() => useKeyboardHint(props))
-
-    expect(spy).not.toHaveBeenCalled()
-    spy.mockRestore()
-  })
-
-  test('keydown Escape and Tab trigger onViewportFocusChange(false)', () => {
-    const props = defaultProps()
-
-    renderHook(() => useKeyboardHint(props))
-
-    const keys = ['Escape', 'Tab']
-    keys.forEach(key => {
-      act(() => {
-        props.containerRef.current.dispatchEvent(
-          new KeyboardEvent('keydown', { key })
-        )
-      })
-    })
-
-    expect(props.onViewportFocusChange).toHaveBeenCalledTimes(2)
-    expect(props.onViewportFocusChange).toHaveBeenCalledWith(false)
-  })
-
-  test('keydown with other keys does NOT trigger onViewportFocusChange', () => {
-    const props = defaultProps()
-
-    renderHook(() => useKeyboardHint(props))
-
-    const keys = ['Enter', 'a']
-    keys.forEach(key => {
-      act(() => {
-        props.containerRef.current.dispatchEvent(
-          new KeyboardEvent('keydown', { key })
-        )
-      })
-    })
-
-    expect(props.onViewportFocusChange).not.toHaveBeenCalled()
-  })
+// ─── keydown listener ────────────────────────────────────────────────────────
 
-  test('mousedown inside container but outside hint triggers false', () => {
+describe('useKeyboardHint — keydown listener', () => {
+  test('Escape calls onViewportFocusChange(false)', () => {
     const props = defaultProps()
-    const child = document.createElement('div')
-    props.containerRef.current.appendChild(child)
-
     renderHook(() => useKeyboardHint(props))
-
     act(() => {
-      child.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+      props.containerRef.current.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
     })
-
     expect(props.onViewportFocusChange).toHaveBeenCalledWith(false)
   })
 
-  test('mousedown inside keyboardHintRef does NOT trigger change', () => {
+  test('non-Escape keydown does not call onViewportFocusChange', () => {
     const props = defaultProps()
-    props.containerRef.current.appendChild(props.keyboardHintRef.current)
-
     renderHook(() => useKeyboardHint(props))
-
     act(() => {
-      props.keyboardHintRef.current.dispatchEvent(
-        new MouseEvent('mousedown', { bubbles: true })
-      )
+      props.containerRef.current.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }))
     })
-
     expect(props.onViewportFocusChange).not.toHaveBeenCalled()
   })
 
-  test('cleanup removes event listeners', () => {
+  test('does nothing when containerRef.current is null', () => {
+    const props = defaultProps({ containerRef: { current: null } })
+    expect(() => renderHook(() => useKeyboardHint(props))).not.toThrow()
+  })
+
+  test('cleanup removes keydown listener on unmount', () => {
     const props = defaultProps()
     const spy = jest.spyOn(props.containerRef.current, 'removeEventListener')
-
     const { unmount } = renderHook(() => useKeyboardHint(props))
-
     unmount()
-    expect(spy).toHaveBeenCalled()
+    expect(spy).toHaveBeenCalledWith('keydown', expect.any(Function))
   })
+})
+
+// ─── handleFocus / handleBlur ─────────────────────────────────────────────────
 
-  test('handleFocus triggers true only for keyboard interface', () => {
+describe('useKeyboardHint — handleFocus / handleBlur', () => {
+  beforeEach(() => getInterfaceType.mockReturnValue('keyboard'))
+
+  test('handleFocus calls onViewportFocusChange(true) for keyboard interface', () => {
     const props = defaultProps()
     const { result } = renderHook(() => useKeyboardHint(props))
-
     act(() => result.current.handleFocus())
-
     expect(props.onViewportFocusChange).toHaveBeenCalledWith(true)
   })
 
-  test('handleFocus does not trigger if interfaceType is not keyboard', () => {
-    const props = defaultProps({ interfaceType: 'mouse' })
+  test('handleFocus does not call onViewportFocusChange for non-keyboard interface', () => {
+    getInterfaceType.mockReturnValue('mouse')
+    const props = defaultProps()
     const { result } = renderHook(() => useKeyboardHint(props))
-
     act(() => result.current.handleFocus())
-
     expect(props.onViewportFocusChange).not.toHaveBeenCalled()
   })
 
-  test('handleBlur always triggers false', () => {
+  test('handleBlur always calls onViewportFocusChange(false)', () => {
     const props = defaultProps({ interfaceType: 'mouse' })
     const { result } = renderHook(() => useKeyboardHint(props))
-
     act(() => result.current.handleBlur())
-
     expect(props.onViewportFocusChange).toHaveBeenCalledWith(false)
   })
 })

package/src/App/hooks/useKeyboardShortcuts.js

@@ -7,12 +7,13 @@ import { useService } from '../store/serviceContext.js'
 
 export function useKeyboardShortcuts (containerRef) {
   const { mapProvider, panDelta, nudgePanDelta, zoomDelta, nudgeZoomDelta, readMapText } = useConfig()
-  const { interfaceType, dispatch } = useApp()
+  const { dispatch, layoutRefs } = useApp()
   const { announce } = useService()
 
   useEffect(() => {
     const el = containerRef.current
-    if (!el || interfaceType !== 'keyboard') {
+    const appEl = layoutRefs.appContainerRef?.current
+    if (!el || !appEl) {
       return undefined
     }
 
@@ -59,16 +60,18 @@ export function useKeyboardShortcuts (containerRef) {
     const handleKeyDown = handle('keydown')
     const handleKeyUp = handle('keyup')
 
+    // keydown (pan/zoom) stays on the viewport so arrows only fire when the map has focus.
+    // keyup (Alt+K and other global shortcuts) attaches to the app container so it fires
+    // from anywhere within the app, including the features listbox.
     el.addEventListener('keydown', handleKeyDown)
-    el.addEventListener('keyup', handleKeyUp)
+    appEl.addEventListener('keyup', handleKeyUp)
 
     return () => {
       el.removeEventListener('keydown', handleKeyDown)
-      el.removeEventListener('keyup', handleKeyUp)
+      appEl.removeEventListener('keyup', handleKeyUp)
     }
   }, [
     containerRef,
-    interfaceType,
     mapProvider,
     panDelta,
     nudgePanDelta,

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

@@ -15,6 +15,7 @@ jest.mock('../store/mapContext.js')
 jest.mock('../store/serviceContext.js')
 
 const setup = (overrides = {}) => {
+  const appContainerRef = { current: document.createElement('div') }
   useConfig.mockReturnValue({
     mapProvider: 'google',
     reverseGeocode: { showMarker: true },
@@ -25,7 +26,7 @@ const setup = (overrides = {}) => {
     readMapText: jest.fn(),
     ...overrides.config
   })
-  useApp.mockReturnValue({ interfaceType: 'keyboard', dispatch: jest.fn(), ...overrides.app })
+  useApp.mockReturnValue({ dispatch: jest.fn(), layoutRefs: { appContainerRef }, ...overrides.app })
   useMap.mockReturnValue({ crossHair: { lat: 0, lng: 0 }, ...overrides.map })
   useService.mockReturnValue({ announce: jest.fn(), ...overrides.service })
 
@@ -34,20 +35,22 @@ const setup = (overrides = {}) => {
   keyboardMappings.keydown = overrides.keydown || {}
   keyboardMappings.keyup = overrides.keyup || {}
 
-  return { containerRef: { current: document.createElement('div') }, actions }
+  return { containerRef: { current: document.createElement('div') }, appContainerRef, actions }
 }
 
 describe('useKeyboardShortcuts', () => {
   beforeEach(jest.clearAllMocks)
 
-  test('early returns when no container or not keyboard interface', () => {
+  test('early returns when no container', () => {
     setup()
     renderHook(() => useKeyboardShortcuts({ current: null }))
     expect(createKeyboardActions).not.toHaveBeenCalled()
+  })
 
-    setup({ app: { interfaceType: 'mouse' } })
-    renderHook(() => useKeyboardShortcuts({ current: document.createElement('div') }))
-    expect(createKeyboardActions).not.toHaveBeenCalled()
+  test('registers shortcuts regardless of interface type', () => {
+    const { containerRef } = setup()
+    renderHook(() => useKeyboardShortcuts(containerRef))
+    expect(createKeyboardActions).toHaveBeenCalled()
   })
 
   test('creates actions with correct config', () => {
@@ -121,7 +124,7 @@ describe('useKeyboardShortcuts', () => {
   })
 
   test('handles Alt+key combinations and keyup events', () => {
-    const { containerRef, actions } = setup({
+    const { containerRef, appContainerRef, actions } = setup({
       keydown: { 'Alt+S': 'search' },
       keyup: { ArrowUp: 'stopPan' },
       actions: { search: jest.fn(), stopPan: jest.fn() }
@@ -131,7 +134,7 @@ describe('useKeyboardShortcuts', () => {
     containerRef.current.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyS', key: 's', altKey: true }))
     expect(actions.search).toHaveBeenCalled()
 
-    containerRef.current.dispatchEvent(new KeyboardEvent('keyup', { key: 'ArrowUp' }))
+    appContainerRef.current.dispatchEvent(new KeyboardEvent('keyup', { key: 'ArrowUp' }))
     expect(actions.stopPan).toHaveBeenCalled()
   })
 
@@ -156,11 +159,12 @@ describe('useKeyboardShortcuts', () => {
   })
 
   test('cleanup removes event listeners', () => {
-    const { containerRef } = setup()
-    const spy = jest.spyOn(containerRef.current, 'removeEventListener')
+    const { containerRef, appContainerRef } = setup()
+    const viewportSpy = jest.spyOn(containerRef.current, 'removeEventListener')
+    const appSpy = jest.spyOn(appContainerRef.current, 'removeEventListener')
     const { unmount } = renderHook(() => useKeyboardShortcuts(containerRef))
     unmount()
-    expect(spy).toHaveBeenCalledWith('keydown', expect.any(Function))
-    expect(spy).toHaveBeenCalledWith('keyup', expect.any(Function))
+    expect(viewportSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+    expect(appSpy).toHaveBeenCalledWith('keyup', expect.any(Function))
   })
 })

package/src/App/hooks/useLayoutMeasurements.js

@@ -55,7 +55,7 @@ function calculateLayout (layoutRefs) {
   const {
     appContainerRef, mainRef, topRef, topLeftColRef, topRightColRef,
     bottomRef, attributionsRef, bottomRightRef, leftTopRef, leftBottomRef,
-    rightTopRef, rightBottomRef
+    rightTopRef, rightBottomRef, actionsRef
   } = layoutRefs
 
   const appContainer = appContainerRef.current
@@ -98,9 +98,15 @@ function calculateLayout (layoutRefs) {
   appContainer.style.setProperty('--right-top-max-height', `${rightColumnHeight}px`)
 
   // === Keyboard hint bottom offset ===
-  // Distance from the bottom of im-o-app__bottom to the bottom of im-o-app__main.
-  // Used to position the hint above the bottom bar (and above drawers on mobile).
-  appContainer.style.setProperty('--keyboard-hint-bottom', `${main.offsetHeight - bottom.offsetTop - bottom.offsetHeight}px`)
+  // On mobile the actions bar is in-flow so baseBottom already accounts for it.
+  // On tablet/desktop the actions bar is position:absolute (not in flow), so baseBottom
+  // only sees the bottom padding. actionsOffset measures the gap from the actions bar's
+  // top edge to the bottom of main, ensuring the hint always clears the floating bar.
+  const actionsEl = actionsRef?.current
+  const actionsHeight = actionsEl?.offsetHeight ?? 0
+  const baseBottom = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
+  const actionsOffset = actionsHeight > 0 ? main.offsetHeight - actionsEl.offsetTop : 0
+  appContainer.style.setProperty('--hint-bottom', `${Math.max(baseBottom, actionsOffset + dividerGap)}px`)
 
   // === Sub-slot panel max-heights ===
   appContainer.style.setProperty('--left-top-panel-max-height', `${subSlotMaxHeight(leftColumnHeight, buttonHeight(leftBottomRef), dividerGap)}px`)

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

@@ -100,6 +100,36 @@ describe('useLayoutMeasurements', () => {
     expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith(varName, expected)
   })
 
+  test.each([
+    [
+      'no actions (height 0) — uses base gap',
+      { main: { offsetHeight: 500 }, bottom: { offsetTop: 400 }, actions: { offsetTop: 450, offsetHeight: 0 } },
+      '100px' // baseBottom = 500 - 400 - 0 = 100
+    ],
+    [
+      'actions floating above base gap (tablet/desktop) — uses actionsOffset + dividerGap',
+      { main: { offsetHeight: 500 }, bottom: { offsetTop: 440, offsetHeight: 20 }, actions: { offsetTop: 408, offsetHeight: 60 } },
+      '100px' // actionsOffset = 500 - 408 = 92, 92 + 8 = 100 > baseBottom (40)
+    ],
+    [
+      'base gap already larger than actionsOffset (mobile in-flow) — base gap wins',
+      { main: { offsetHeight: 500 }, bottom: { offsetTop: 350 }, actions: { offsetTop: 430, offsetHeight: 40 } },
+      '150px' // baseBottom = 150 > actionsOffset (70) + dividerGap (8) = 78
+    ]
+  ])('calculates --hint-bottom for %s', (_, refOverrides, expected) => {
+    const { layoutRefs } = setup({ refs: refOverrides })
+    renderHook(() => useLayoutMeasurements())
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--hint-bottom', expected)
+  })
+
+  test('calculates --hint-bottom when actionsRef.current is null', () => {
+    const { layoutRefs } = setup()
+    layoutRefs.actionsRef.current = null
+    renderHook(() => useLayoutMeasurements())
+    // actionsHeight = 0, falls back to baseBottom = 500 - 400 - 0 = 100
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--hint-bottom', '100px')
+  })
+
   test.each([
     [{ offsetWidth: 250 }, { offsetWidth: 200 }, '250px'],
     [{ offsetWidth: 0 }, { offsetWidth: 200 }, '200px'],

package/src/App/hooks/useMapURLSync.js

@@ -10,11 +10,11 @@ import { EVENTS as events } from '../../config/events.js'
  * shared via a link.
  */
 export function useMapURLSync () {
-  const { id } = useConfig()
+  const { id, urlPosition } = useConfig()
   const { eventBus } = useService()
 
   useEffect(() => {
-    if (!id) {
+    if (!id || urlPosition !== 'sync') {
       return undefined
     }
 
@@ -27,5 +27,5 @@ export function useMapURLSync () {
 
     eventBus.on(events.MAP_STATE_UPDATED, handleStateUpdate)
     return () => eventBus.off(events.MAP_STATE_UPDATED, handleStateUpdate)
-  }, [id])
+  }, [id, urlPosition])
 }

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

@@ -25,7 +25,7 @@ describe('useMapURLSync', () => {
   })
 
   it('registers map:stateupdated listener and cleans up', () => {
-    useConfig.mockReturnValue({ id: 'map123' })
+    useConfig.mockReturnValue({ id: 'map123', urlPosition: 'sync' })
 
     const { unmount } = renderHook(() => useMapURLSync())
     expect(mockEventBus.on).toHaveBeenCalledWith('map:stateupdated', expect.any(Function))
@@ -35,7 +35,7 @@ describe('useMapURLSync', () => {
   })
 
   it('calls setMapStateInURL on map:stateupdated', () => {
-    useConfig.mockReturnValue({ id: 'map123' })
+    useConfig.mockReturnValue({ id: 'map123', urlPosition: 'sync' })
 
     renderHook(() => useMapURLSync())
 
@@ -50,7 +50,7 @@ describe('useMapURLSync', () => {
   })
 
   it('does nothing if id is falsy', () => {
-    useConfig.mockReturnValue({ id: null })
+    useConfig.mockReturnValue({ id: null, urlPosition: 'sync' })
 
     const { unmount } = renderHook(() => useMapURLSync())
     expect(mockEventBus.on).not.toHaveBeenCalled()
@@ -58,4 +58,21 @@ describe('useMapURLSync', () => {
 
     unmount() // cleanup should not throw
   })
+
+  it('does not register listener when urlPosition is none', () => {
+    useConfig.mockReturnValue({ id: 'map123', urlPosition: 'none' })
+
+    const { unmount } = renderHook(() => useMapURLSync())
+    expect(mockEventBus.on).not.toHaveBeenCalled()
+
+    unmount()
+    expect(mockEventBus.off).not.toHaveBeenCalled()
+  })
+
+  it('does not register listener when urlPosition is readOnly', () => {
+    useConfig.mockReturnValue({ id: 'map123', urlPosition: 'readOnly' })
+
+    renderHook(() => useMapURLSync())
+    expect(mockEventBus.on).not.toHaveBeenCalled()
+  })
 })