@defra/interactive-map 0.0.17-alpha → 0.0.19-alpha

package/src/App/components/Panel/Panel.jsx

@@ -6,12 +6,12 @@ import { useModalPanelBehaviour } from '../../hooks/useModalPanelBehaviour.js'
 import { useIsScrollable } from '../../hooks/useIsScrollable.js'
 import { Icon } from '../Icon/Icon'
 
-const computePanelState = (bpConfig, triggeringElement) => {
+const computePanelState = (bpConfig, triggeringElement, focus, focusOnOpen) => {
   const isAside = bpConfig.slot === 'side' && bpConfig.open && !bpConfig.modal
   const isDialog = !isAside && bpConfig.dismissible
   const isModal = bpConfig.modal === true
   const isDismissible = bpConfig.dismissible !== false
-  const shouldFocus = Boolean(isModal || triggeringElement)
+  const shouldFocus = isModal || (focusOnOpen !== false && (focusOnOpen === true || focus === true || Boolean(triggeringElement)))
   const buttonContainerEl = bpConfig.slot.endsWith('button') ? triggeringElement?.parentNode : undefined
   return { isAside, isDialog, isModal, isDismissible, shouldFocus, buttonContainerEl }
 }
@@ -58,15 +58,15 @@ const buildBodyProps = ({ bodyRef, panelBodyClass, isBodyScrollable, elementId }
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
-export const Panel = ({ panelId, panelConfig, props, WrappedChild, label, html, children, isOpen = true, rootRef }) => {
+export const Panel = ({ panelId, panelConfig, props, focusOnOpen, WrappedChild, label, html, children, isOpen = true, rootRef }) => {
   const { id } = useConfig()
-  const { dispatch, breakpoint, layoutRefs } = useApp()
+  const { dispatch, breakpoint, layoutRefs, interfaceType } = useApp()
 
   const rootEl = document.getElementById(`${id}-im-app`)
   const bpConfig = panelConfig[breakpoint]
   const elementId = `${id}-panel-${stringToKebab(panelId)}`
 
-  const { isAside, isDialog, isModal, isDismissible, shouldFocus, buttonContainerEl } = computePanelState(bpConfig, props?.triggeringElement)
+  const { isAside, isDialog, isModal, isDismissible, shouldFocus, buttonContainerEl } = computePanelState(bpConfig, props?.triggeringElement, panelConfig.focus, focusOnOpen) // nosonar
 
   // For persistent panels, gate modal behaviour on open state
   const isModalActive = isModal && isOpen
@@ -81,7 +81,7 @@ export const Panel = ({ panelId, panelConfig, props, WrappedChild, label, html,
   const panelRef = rootRef || internalPanelRef
 
   const handleClose = () => {
-    requestAnimationFrame(() => { (props?.triggeringElement || layoutRefs.viewportRef.current).focus?.() })
+    requestAnimationFrame(() => { (props?.triggeringElement || layoutRefs.viewportRef.current).focus?.({ preventScroll: interfaceType !== 'keyboard' }) })
     dispatch({ type: 'CLOSE_PANEL', payload: panelId })
   }
 

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

@@ -104,6 +104,43 @@ describe('Panel', () => {
     })
   })
 
+  describe('focus behaviour', () => {
+    it('focuses panel on mount when focus: true', () => {
+      const { container } = renderPanel({ focus: true })
+      const panel = container.firstChild
+      expect(panel).toHaveAttribute('tabIndex', '-1')
+      expect(document.activeElement).toBe(panel)
+    })
+
+    it('does not focus panel on mount when focus: false and no triggering element or modal', () => {
+      const { container } = renderPanel({ focus: false })
+      const panel = container.firstChild
+      expect(panel).not.toHaveAttribute('tabIndex')
+      expect(document.activeElement).not.toBe(panel)
+    })
+
+    it('focuses panel on mount when modal even if focus: false', () => {
+      const { container } = renderPanel({ focus: false, desktop: { slot: 'overlay', dismissible: true, modal: true } })
+      const panel = container.firstChild
+      expect(panel).toHaveAttribute('tabIndex', '-1')
+      expect(document.activeElement).toBe(panel)
+    })
+
+    it('focuses panel when focusOnOpen is true regardless of panelConfig.focus', () => {
+      const { container } = renderPanel({ focus: false }, { focusOnOpen: true })
+      const panel = container.firstChild
+      expect(panel).toHaveAttribute('tabIndex', '-1')
+      expect(document.activeElement).toBe(panel)
+    })
+
+    it('does not focus panel when focusOnOpen is false even if panelConfig.focus is true', () => {
+      const { container } = renderPanel({ focus: true }, { focusOnOpen: false })
+      const panel = container.firstChild
+      expect(panel).not.toHaveAttribute('tabIndex')
+      expect(document.activeElement).not.toBe(panel)
+    })
+  })
+
   describe('close functionality', () => {
     it('focuses triggeringElement on close for button slots', () => {
       const focusMock = jest.fn()

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

@@ -2,6 +2,7 @@ import React, { useRef, useEffect, useState } from 'react'
 import { EVENTS as events } from '../../../config/events.js'
 import { createPortal } from 'react-dom'
 import { useConfig } from '../../store/configContext.js'
+
 import { useApp } from '../../store/appContext.js'
 import { useMap } from '../../store/mapContext.js'
 import { MapController } from './MapController.jsx'
@@ -14,9 +15,10 @@ import { Markers } from '../Markers/Markers'
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
-export const Viewport = ({ keyboardHintPortalRef }) => {
+export const Viewport = () => {
   const { id, mapProvider, mapLabel, keyboardHintText } = useConfig()
   const { interfaceType, mode, previousMode, layoutRefs, safeZoneInset } = useApp()
+  const { mainRef } = layoutRefs
   const { mapSize } = useMap()
 
   const mapContainerRef = useRef(null)
@@ -49,18 +51,6 @@ export const Viewport = ({ keyboardHintPortalRef }) => {
     }
   }, [mode])
 
-  // Toggle external class based on keyboard hint
-  useEffect(() => {
-    const mainEl = layoutRefs.mainRef?.current
-    if (!mainEl) {
-      return undefined
-    }
-
-    mainEl.classList.toggle('im-o-app__main--keyboard-hint-visible', showHint)
-
-    return () => mainEl?.classList.remove('im-o-app__main--keyboard-hint-visible')
-  }, [showHint])
-
   return (
     <>
       <MapController mapContainerRef={mapContainerRef} />
@@ -74,14 +64,14 @@ export const Viewport = ({ keyboardHintPortalRef }) => {
         onBlur={handleBlur}
         ref={layoutRefs.viewportRef}
       >
-        {showHint && keyboardHintPortalRef?.current && createPortal(
+        {showHint && mainRef?.current && createPortal(
           <div
             className='im-c-viewport__keyboard-hint'
             aria-hidden='true'
             ref={keyboardHintRef}
             dangerouslySetInnerHTML={{ __html: keyboardHintText }}
           />,
-          keyboardHintPortalRef.current
+          mainRef.current
         )}
         <div className='im-c-viewport__map-container' ref={mapContainerRef} />
         <div className='im-c-viewport__features' />

package/src/App/components/Viewport/Viewport.module.scss

@@ -31,8 +31,10 @@
 
 .im-c-viewport__keyboard-hint {
     position: absolute;
+    bottom: var(--keyboard-hint-bottom, var(--primary-gap));
     left: 50%;
     transform: translateX(-50%);
+    z-index: 1001;
     text-wrap: nowrap;
 
     color: var(--tooltip-foreground-color);

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

@@ -1,5 +1,5 @@
 import React from 'react'
-import { render, fireEvent, cleanup } from '@testing-library/react'
+import { render, cleanup } from '@testing-library/react'
 import { Viewport } from './Viewport.jsx'
 import { useConfig } from '../../store/configContext.js'
 import { useApp } from '../../store/appContext.js'
@@ -23,15 +23,18 @@ jest.mock('../CrossHair/CrossHair', () => ({ CrossHair: jest.fn(() => <div data-
 jest.mock('../Markers/Markers', () => ({ Markers: jest.fn(() => <div data-testid='markers' />) }))
 
 describe('Viewport', () => {
-  let keyboardHintPortalRef
+  let viewportEl
+  let mainEl
   const mockMapProvider = { initMap: jest.fn(), updateMap: jest.fn(), clearHighlightedLabel: jest.fn() }
 
   beforeEach(() => {
     cleanup()
     jest.clearAllMocks()
 
-    keyboardHintPortalRef = { current: document.createElement('div') }
-    document.body.appendChild(keyboardHintPortalRef.current)
+    viewportEl = document.createElement('div')
+    mainEl = document.createElement('div')
+    document.body.appendChild(viewportEl)
+    document.body.appendChild(mainEl)
 
     // ---------------------------
     // Hook mocks
@@ -47,7 +50,7 @@ describe('Viewport', () => {
       interfaceType: 'desktop',
       mode: 'default',
       previousMode: 'default',
-      layoutRefs: { viewportRef: { current: null }, mainRef: { current: null }, safeZoneRef: { current: null } },
+      layoutRefs: { mainRef: { current: mainEl }, viewportRef: { current: viewportEl }, safeZoneRef: { current: null } },
       safeZoneInset: {}
     })
 
@@ -75,14 +78,17 @@ describe('Viewport', () => {
     useMapEvents.mockImplementation(() => {})
   })
 
-  afterEach(() => document.body.removeChild(keyboardHintPortalRef.current))
+  afterEach(() => {
+    viewportEl.remove()
+    mainEl.remove()
+  })
 
   const renderViewport = () => {
-    const { container, rerender, unmount } = render(<Viewport keyboardHintPortalRef={keyboardHintPortalRef} />)
+    const { container, rerender, unmount } = render(<Viewport />)
     const viewport = container.querySelector('.im-c-viewport')
     const mapContainer = container.querySelector('.im-c-viewport__map-container')
     const safeZone = container.querySelector('.im-c-viewport__safezone')
-    const keyboardHint = keyboardHintPortalRef.current.querySelector('.im-c-viewport__keyboard-hint')
+    const keyboardHint = mainEl.querySelector('.im-c-viewport__keyboard-hint')
     const crossHair = container.querySelector('[data-testid="cross-hair"]')
     const markers = container.querySelector('[data-testid="markers"]')
     return { viewport, mapContainer, safeZone, keyboardHint, crossHair, markers, rerender, unmount }
@@ -109,14 +115,6 @@ describe('Viewport', () => {
     expect(keyboardHint.innerHTML).toBe('Press arrow keys')
   })
 
-  it('handles focus and blur events updating keyboard hint visibility', () => {
-    const { viewport, keyboardHint } = renderViewport()
-    fireEvent.focus(viewport)
-    fireEvent.blur(viewport)
-    expect(keyboardHint).toBeInTheDocument()
-    expect(keyboardHint.innerHTML).toBe('Press arrow keys')
-  })
-
   it('attaches keyboard shortcuts', () => {
     renderViewport()
     expect(useKeyboardShortcuts).toHaveBeenCalled()
@@ -137,25 +135,10 @@ describe('Viewport', () => {
       interfaceType: 'desktop',
       mode: 'edit',
       previousMode: 'default',
-      layoutRefs: { viewportRef: { current: viewport }, mainRef: { current: null }, safeZoneRef: { current: null } },
+      layoutRefs: { mainRef: { current: mainEl }, viewportRef: { current: viewport }, safeZoneRef: { current: null } },
       safeZoneInset: {}
     })
-    rerender(<Viewport keyboardHintPortalRef={keyboardHintPortalRef} />)
+    rerender(<Viewport />)
     expect(focusMock).toHaveBeenCalled()
   })
-
-  it('toggles main element class for keyboard hint and cleans up on unmount', () => {
-    const mainEl = document.createElement('div')
-    useApp.mockReturnValueOnce({
-      interfaceType: 'desktop',
-      mode: 'default',
-      previousMode: 'default',
-      layoutRefs: { viewportRef: { current: null }, mainRef: { current: mainEl }, safeZoneRef: { current: null } },
-      safeZoneInset: {}
-    })
-    const { unmount } = renderViewport()
-    expect(mainEl.classList.contains('im-o-app__main--keyboard-hint-visible')).toBe(true)
-    unmount()
-    expect(mainEl.classList.contains('im-o-app__main--keyboard-hint-visible')).toBe(false)
-  })
 })

package/src/App/hooks/useInterfaceAPI.js

@@ -54,16 +54,16 @@ export const useInterfaceAPI = () => {
       }
     }
 
-    const handleAppVisible = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: true })
-    const handleAppHidden = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: false })
+    const handleAppOpened = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: true })
+    const handleAppClosed = () => dispatchRef.current({ type: 'TOGGLE_APP_VISIBLE', payload: false })
     const handleAddPanel = ({ id, config }) => dispatchRef.current({ type: 'ADD_PANEL', payload: { id, config } })
     const handleRemovePanel = (id) => dispatchRef.current({ type: 'REMOVE_PANEL', payload: id })
-    const handleShowPanel = (id) => dispatchRef.current({ type: 'OPEN_PANEL', payload: { panelId: id } })
+    const handleShowPanel = ({ id, focus = true }) => dispatchRef.current({ type: 'OPEN_PANEL', payload: { panelId: id, focusOnOpen: focus } })
     const handleHidePanel = (id) => dispatchRef.current({ type: 'CLOSE_PANEL', payload: id })
     const handleAddControl = ({ id, config }) => dispatchRef.current({ type: 'ADD_CONTROL', payload: { id, config } })
 
-    eventBus.on(events.APP_VISIBLE, handleAppVisible)
-    eventBus.on(events.APP_HIDDEN, handleAppHidden)
+    eventBus.on(events.APP_OPENED, handleAppOpened)
+    eventBus.on(events.APP_CLOSED, handleAppClosed)
     eventBus.on(events.APP_ADD_BUTTON, handleAddButton)
     eventBus.on(events.APP_TOGGLE_BUTTON_STATE, handleToggleButtonState)
     eventBus.on(events.APP_ADD_PANEL, handleAddPanel)
@@ -73,8 +73,8 @@ export const useInterfaceAPI = () => {
     eventBus.on(events.APP_ADD_CONTROL, handleAddControl)
 
     return () => {
-      eventBus.off(events.APP_VISIBLE, handleAppVisible)
-      eventBus.off(events.APP_HIDDEN, handleAppHidden)
+      eventBus.off(events.APP_OPENED, handleAppOpened)
+      eventBus.off(events.APP_CLOSED, handleAppClosed)
       eventBus.off(events.APP_ADD_BUTTON, handleAddButton)
       eventBus.off(events.APP_TOGGLE_BUTTON_STATE, handleToggleButtonState)
       eventBus.off(events.APP_ADD_PANEL, handleAddPanel)

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

@@ -0,0 +1,162 @@
+import { renderHook, act } from '@testing-library/react'
+import { useInterfaceAPI } from './useInterfaceAPI.js'
+import { useApp } from '../store/appContext.js'
+import { useService } from '../store/serviceContext.js'
+
+jest.mock('../store/appContext.js')
+jest.mock('../store/serviceContext.js')
+
+const makeEventBus = () => {
+  const handlers = {}
+  return {
+    on: jest.fn((event, handler) => { handlers[event] = handler }),
+    off: jest.fn(),
+    emit: (event, payload) => handlers[event]?.(payload),
+    _handlers: handlers
+  }
+}
+
+describe('useInterfaceAPI', () => {
+  let mockDispatch, mockEventBus, mockState
+
+  beforeEach(() => {
+    mockDispatch = jest.fn()
+    mockEventBus = makeEventBus()
+    mockState = {
+      hiddenButtons: new Set(),
+      disabledButtons: new Set(),
+      pressedButtons: new Set(),
+      expandedButtons: new Set()
+    }
+
+    useApp.mockReturnValue({ dispatch: mockDispatch, ...mockState })
+    useService.mockReturnValue({ eventBus: mockEventBus })
+  })
+
+  it('dispatches ADD_BUTTON on app:addbutton', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:addbutton', { id: 'btn1', config: { label: 'Test' } }))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'ADD_BUTTON', payload: { id: 'btn1', config: { label: 'Test' } } })
+  })
+
+  it('also dispatches ADD_BUTTON for each menuItem', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:addbutton', {
+      id: 'btn1',
+      config: {
+        label: 'Parent',
+        menuItems: [
+          { id: 'item1', label: 'Item 1' },
+          { id: 'item2', label: 'Item 2' }
+        ]
+      }
+    }))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'ADD_BUTTON', payload: { id: 'btn1', config: expect.objectContaining({ label: 'Parent' }) } })
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'ADD_BUTTON', payload: { id: 'item1', config: { id: 'item1', label: 'Item 1', isMenuItem: true } } })
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'ADD_BUTTON', payload: { id: 'item2', config: { id: 'item2', label: 'Item 2', isMenuItem: true } } })
+  })
+
+  it('dispatches TOGGLE_APP_VISIBLE true on app:opened', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:opened'))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'TOGGLE_APP_VISIBLE', payload: true })
+  })
+
+  it('dispatches TOGGLE_APP_VISIBLE false on app:closed', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:closed'))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'TOGGLE_APP_VISIBLE', payload: false })
+  })
+
+  it('dispatches ADD_PANEL on app:addpanel', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:addpanel', { id: 'panel1', config: { title: 'My Panel' } }))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'ADD_PANEL', payload: { id: 'panel1', config: { title: 'My Panel' } } })
+  })
+
+  it('dispatches REMOVE_PANEL on app:removepanel', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:removepanel', 'panel1'))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'REMOVE_PANEL', payload: 'panel1' })
+  })
+
+  it('dispatches OPEN_PANEL with focusOnOpen:true on app:showpanel by default', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:showpanel', { id: 'panel1' }))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'OPEN_PANEL', payload: { panelId: 'panel1', focusOnOpen: true } })
+  })
+
+  it('dispatches OPEN_PANEL with focusOnOpen:false when focus:false', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:showpanel', { id: 'panel1', focus: false }))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'OPEN_PANEL', payload: { panelId: 'panel1', focusOnOpen: false } })
+  })
+
+  it('dispatches CLOSE_PANEL on app:hidepanel', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:hidepanel', 'panel1'))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'CLOSE_PANEL', payload: 'panel1' })
+  })
+
+  it('dispatches ADD_CONTROL on app:addcontrol', () => {
+    renderHook(() => useInterfaceAPI())
+    act(() => mockEventBus.emit('app:addcontrol', { id: 'ctrl1', config: { position: 'top-left' } }))
+    expect(mockDispatch).toHaveBeenCalledWith({ type: 'ADD_CONTROL', payload: { id: 'ctrl1', config: { position: 'top-left' } } })
+  })
+
+  describe('handleToggleButtonState', () => {
+    it.each([
+      ['hidden', 'TOGGLE_BUTTON_HIDDEN', 'isHidden'],
+      ['disabled', 'TOGGLE_BUTTON_DISABLED', 'isDisabled'],
+      ['pressed', 'TOGGLE_BUTTON_PRESSED', 'isPressed'],
+      ['expanded', 'TOGGLE_BUTTON_EXPANDED', 'isExpanded']
+    ])('sets %s to explicit boolean value when provided', (prop, actionType, payloadKey) => {
+      renderHook(() => useInterfaceAPI())
+      act(() => mockEventBus.emit('app:togglebuttonstate', { id: 'btn1', prop, value: true }))
+      expect(mockDispatch).toHaveBeenCalledWith({ type: actionType, payload: { id: 'btn1', [payloadKey]: true } })
+
+      mockDispatch.mockClear()
+      act(() => mockEventBus.emit('app:togglebuttonstate', { id: 'btn1', prop, value: false }))
+      expect(mockDispatch).toHaveBeenCalledWith({ type: actionType, payload: { id: 'btn1', [payloadKey]: false } })
+    })
+
+    it.each([
+      ['hidden', 'TOGGLE_BUTTON_HIDDEN', 'isHidden', 'hiddenButtons'],
+      ['disabled', 'TOGGLE_BUTTON_DISABLED', 'isDisabled', 'disabledButtons'],
+      ['pressed', 'TOGGLE_BUTTON_PRESSED', 'isPressed', 'pressedButtons'],
+      ['expanded', 'TOGGLE_BUTTON_EXPANDED', 'isExpanded', 'expandedButtons']
+    ])('toggles %s when no boolean value provided', (prop, actionType, payloadKey, stateKey) => {
+      renderHook(() => useInterfaceAPI())
+
+      // Not in set → toggles to true
+      act(() => mockEventBus.emit('app:togglebuttonstate', { id: 'btn1', prop }))
+      expect(mockDispatch).toHaveBeenCalledWith({ type: actionType, payload: { id: 'btn1', [payloadKey]: true } })
+
+      // Already in set → toggles to false
+      mockDispatch.mockClear()
+      mockState[stateKey].add('btn1')
+      act(() => mockEventBus.emit('app:togglebuttonstate', { id: 'btn1', prop }))
+      expect(mockDispatch).toHaveBeenCalledWith({ type: actionType, payload: { id: 'btn1', [payloadKey]: false } })
+    })
+
+    it('does nothing for unknown prop', () => {
+      renderHook(() => useInterfaceAPI())
+      act(() => mockEventBus.emit('app:togglebuttonstate', { id: 'btn1', prop: 'unknown', value: true }))
+      expect(mockDispatch).not.toHaveBeenCalled()
+    })
+  })
+
+  it('removes all event listeners on unmount', () => {
+    const { unmount } = renderHook(() => useInterfaceAPI())
+    unmount()
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:opened', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:closed', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:addbutton', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:togglebuttonstate', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:addpanel', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:removepanel', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:showpanel', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:hidepanel', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:addcontrol', expect.any(Function))
+  })
+})

package/src/App/hooks/useLayoutMeasurements.js

@@ -51,80 +51,72 @@ const subSlotMaxHeight = (columnHeight, siblingButtons, gap) =>
  * It does not dispatch the safe zone — safe zone dispatch is owned entirely by
  * Effect 3 to prevent jumps on panel open/close and other non-structural resizes.
  */
-export function useLayoutMeasurements () {
-  const { dispatch, breakpoint, layoutRefs, arePluginsEvaluated, appVisible, isFullscreen } = useApp()
-  const { mapSize, isMapReady } = useMap()
-
+function calculateLayout (layoutRefs) {
   const {
-    appContainerRef,
-    mainRef,
-    bannerRef,
-    topRef,
-    topLeftColRef,
-    topRightColRef,
-    leftTopRef,
-    leftBottomRef,
-    rightTopRef,
-    rightBottomRef,
-    bottomRef,
-    bottomRightRef,
-    attributionsRef,
-    drawerRef,
-    actionsRef
+    appContainerRef, mainRef, topRef, topLeftColRef, topRightColRef,
+    bottomRef, attributionsRef, bottomRightRef, leftTopRef, leftBottomRef,
+    rightTopRef, rightBottomRef
   } = layoutRefs
 
-  // --------------------------------
-  // 1. Calculate layout CSS vars (pure side effect, no dispatch)
-  // --------------------------------
-  const calculateLayout = () => {
-    const appContainer = appContainerRef.current
-    const main = mainRef.current
-    const top = topRef.current
-    const topLeftCol = topLeftColRef.current
-    const topRightCol = topRightColRef.current
-    const bottom = bottomRef.current
-    const attributions = attributionsRef.current
-
-    if ([main, top, bottom].some(r => !r)) {
-      return
-    }
+  const appContainer = appContainerRef.current
+  const main = mainRef.current
+  const top = topRef.current
+  const topLeftCol = topLeftColRef.current
+  const topRightCol = topRightColRef.current
+  const bottom = bottomRef.current
+  const attributions = attributionsRef.current
 
-    const root = document.documentElement
-    const dividerGap = Number.parseInt(getComputedStyle(root).getPropertyValue('--divider-gap'), 10)
-
-    // === Top column width ===
-    appContainer.style.setProperty('--top-col-width', `${topColWidth(topLeftCol.offsetWidth, topRightCol.offsetWidth)}px`)
-
-    // === Left container offsets ===
-    const leftOffsetTop = topLeftCol.offsetHeight + top.offsetTop
-    const leftColumnHeight = bottom.offsetTop - leftOffsetTop - dividerGap
-    appContainer.style.setProperty('--left-offset-top', `${leftOffsetTop}px`)
-    appContainer.style.setProperty('--left-offset-bottom', `${main.offsetHeight - bottom.offsetTop + dividerGap}px`)
-    appContainer.style.setProperty('--left-top-max-height', `${leftColumnHeight}px`)
-
-    // === Right container offsets ===
-    // Mirrors the top formula (topRightCol.offsetHeight + top.offsetTop):
-    // bottomRight.offsetHeight is 0 when no buttons so the offset collapses to just
-    // the padding between the bottom of the bottom container and the bottom of main.
-    const bottomRightHeight = bottomRightRef?.current?.offsetHeight ?? 0
-    const bottomContainerPad = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
-    const rightOffsetTop = topRightCol.offsetHeight + top.offsetTop
-    const rightEffectiveBottom = bottom.offsetTop + bottom.offsetHeight - bottomRightHeight
-    const rightColumnHeight = rightEffectiveBottom - rightOffsetTop - dividerGap
-    const rightOffsetBottom = bottomContainerPad + (bottomRightHeight > 0 ? (bottomRightHeight + dividerGap) : attributions.offsetHeight)
-    appContainer.style.setProperty('--right-offset-top', `${rightOffsetTop}px`)
-    appContainer.style.setProperty('--right-offset-bottom', `${rightOffsetBottom}px`)
-    appContainer.style.setProperty('--right-top-max-height', `${rightColumnHeight}px`)
-
-    // === Sub-slot panel max-heights ===
-    appContainer.style.setProperty('--left-top-panel-max-height', `${subSlotMaxHeight(leftColumnHeight, buttonHeight(leftBottomRef), dividerGap)}px`)
-    appContainer.style.setProperty('--left-bottom-panel-max-height', `${subSlotMaxHeight(leftColumnHeight, buttonHeight(leftTopRef), dividerGap)}px`)
-    appContainer.style.setProperty('--right-top-panel-max-height', `${subSlotMaxHeight(rightColumnHeight, buttonHeight(rightBottomRef), dividerGap)}px`)
-    appContainer.style.setProperty('--right-bottom-panel-max-height', `${subSlotMaxHeight(rightColumnHeight, buttonHeight(rightTopRef), dividerGap)}px`)
+  if ([main, top, bottom].some(r => !r)) {
+    return
   }
 
+  const root = document.documentElement
+  const dividerGap = Number.parseInt(getComputedStyle(root).getPropertyValue('--divider-gap'), 10)
+
+  // === Top column width ===
+  appContainer.style.setProperty('--top-col-width', `${topColWidth(topLeftCol.offsetWidth, topRightCol.offsetWidth)}px`)
+
+  // === Left container offsets ===
+  const leftOffsetTop = topLeftCol.offsetHeight + top.offsetTop
+  const leftColumnHeight = bottom.offsetTop - leftOffsetTop - dividerGap
+  appContainer.style.setProperty('--left-offset-top', `${leftOffsetTop}px`)
+  appContainer.style.setProperty('--left-offset-bottom', `${main.offsetHeight - bottom.offsetTop + dividerGap}px`)
+  appContainer.style.setProperty('--left-top-max-height', `${leftColumnHeight}px`)
+
+  // === Right container offsets ===
+  // Mirrors the top formula (topRightCol.offsetHeight + top.offsetTop):
+  // bottomRight.offsetHeight is 0 when no buttons so the offset collapses to just
+  // the padding between the bottom of the bottom container and the bottom of main.
+  const bottomRightHeight = bottomRightRef?.current?.offsetHeight ?? 0
+  const bottomContainerPad = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
+  const rightOffsetTop = topRightCol.offsetHeight + top.offsetTop
+  const rightEffectiveBottom = bottom.offsetTop + bottom.offsetHeight - bottomRightHeight
+  const rightColumnHeight = rightEffectiveBottom - rightOffsetTop - dividerGap
+  const rightOffsetBottom = bottomContainerPad + (bottomRightHeight > 0 ? (bottomRightHeight + dividerGap) : attributions.offsetHeight)
+  appContainer.style.setProperty('--right-offset-top', `${rightOffsetTop}px`)
+  appContainer.style.setProperty('--right-offset-bottom', `${rightOffsetBottom}px`)
+  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`)
+
+  // === Sub-slot panel max-heights ===
+  appContainer.style.setProperty('--left-top-panel-max-height', `${subSlotMaxHeight(leftColumnHeight, buttonHeight(leftBottomRef), dividerGap)}px`)
+  appContainer.style.setProperty('--left-bottom-panel-max-height', `${subSlotMaxHeight(leftColumnHeight, buttonHeight(leftTopRef), dividerGap)}px`)
+  appContainer.style.setProperty('--right-top-panel-max-height', `${subSlotMaxHeight(rightColumnHeight, buttonHeight(rightBottomRef), dividerGap)}px`)
+  appContainer.style.setProperty('--right-bottom-panel-max-height', `${subSlotMaxHeight(rightColumnHeight, buttonHeight(rightTopRef), dividerGap)}px`)
+}
+
+export function useLayoutMeasurements () {
+  const { dispatch, breakpoint, layoutRefs, arePluginsEvaluated, appVisible, isFullscreen } = useApp()
+  const { mapSize, isMapReady } = useMap()
+
+  const { bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef, actionsRef } = layoutRefs
+
   // --------------------------------
-  // 2. Clear the evaluated flag when structural inputs change so the safe zone
+  // 1. Clear the evaluated flag when structural inputs change so the safe zone
   //    is not dispatched until useButtonStateEvaluator has completed a full
   //    pass with the new app/map state and set PLUGINS_EVALUATED.
   // --------------------------------
@@ -133,7 +125,7 @@ export function useLayoutMeasurements () {
   }, [breakpoint, mapSize, isMapReady, appVisible, isFullscreen])
 
   // --------------------------------
-  // 3. Once all plugin button props have been evaluated (arePluginsEvaluated),
+  // 2. Once all plugin button props have been evaluated (arePluginsEvaluated),
   //    recalculate layout and dispatch the safe zone inset.
   //    RAF required to ensure browser layout is committed before measuring.
   // --------------------------------
@@ -142,7 +134,7 @@ export function useLayoutMeasurements () {
       return
     }
     requestAnimationFrame(() => {
-      calculateLayout()
+      calculateLayout(layoutRefs)
       const safeZoneInset = getSafeZoneInset(layoutRefs)
       if (safeZoneInset) {
         dispatch({ type: 'SET_SAFE_ZONE_INSET', payload: { safeZoneInset } })
@@ -151,13 +143,13 @@ export function useLayoutMeasurements () {
   }, [arePluginsEvaluated])
 
   // --------------------------------
-  // 4. Recalculate CSS vars whenever observed elements resize (panels, banner,
+  // 3. Recalculate CSS vars whenever observed elements resize (panels, banner,
   //    actions buttons, etc.). Safe zone is intentionally not dispatched here —
-  //    that is Effect 3's responsibility.
+  //    that is Effect 2's responsibility.
   // --------------------------------
   useResizeObserver([bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, actionsRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef], () => {
     requestAnimationFrame(() => {
-      calculateLayout()
+      calculateLayout(layoutRefs)
     })
   })
 }

package/src/App/hooks/useMarkersAPI.js

@@ -5,12 +5,9 @@ import { useService } from '../store/serviceContext.js'
 import { scaleFactor } from '../../config/appConfig.js'
 import { EVENTS as events } from '../../config/events.js'
 
-// Vertical offset to align the marker tip with the coordinate point
-const MARKER_ANCHOR_OFFSET_Y = 19
-
 /**
  * Projects geographic coordinates to screen pixel position, scaled for the
- * current map size and offset so the marker tip aligns with the point.
+ * current map size. Anchor alignment is handled in CSS by the Markers component.
  *
  * @param {Array<number>} coords - [lng, lat] geographic coordinates
  * @param {Object} mapProvider - Map provider instance with `mapToScreen` method
@@ -25,7 +22,7 @@ export const projectCoords = (coords, mapProvider, mapSize, isMapReady) => {
   const { x, y } = mapProvider.mapToScreen(coords)
   return {
     x: x * scaleFactor[mapSize],
-    y: y * scaleFactor[mapSize] - MARKER_ANCHOR_OFFSET_Y
+    y: y * scaleFactor[mapSize]
   }
 }