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

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

@@ -56,15 +56,15 @@ describe('useInterfaceAPI', () => {
     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:visible', () => {
+  it('dispatches TOGGLE_APP_VISIBLE true on app:opened', () => {
     renderHook(() => useInterfaceAPI())
-    act(() => mockEventBus.emit('app:visible'))
+    act(() => mockEventBus.emit('app:opened'))
     expect(mockDispatch).toHaveBeenCalledWith({ type: 'TOGGLE_APP_VISIBLE', payload: true })
   })
 
-  it('dispatches TOGGLE_APP_VISIBLE false on app:hidden', () => {
+  it('dispatches TOGGLE_APP_VISIBLE false on app:closed', () => {
     renderHook(() => useInterfaceAPI())
-    act(() => mockEventBus.emit('app:hidden'))
+    act(() => mockEventBus.emit('app:closed'))
     expect(mockDispatch).toHaveBeenCalledWith({ type: 'TOGGLE_APP_VISIBLE', payload: false })
   })
 
@@ -80,10 +80,16 @@ describe('useInterfaceAPI', () => {
     expect(mockDispatch).toHaveBeenCalledWith({ type: 'REMOVE_PANEL', payload: 'panel1' })
   })
 
-  it('dispatches OPEN_PANEL on app:showpanel', () => {
+  it('dispatches OPEN_PANEL with focusOnOpen:true on app:showpanel by default', () => {
     renderHook(() => useInterfaceAPI())
-    act(() => mockEventBus.emit('app:showpanel', 'panel1'))
-    expect(mockDispatch).toHaveBeenCalledWith({ type: 'OPEN_PANEL', payload: { panelId: 'panel1' } })
+    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', () => {
@@ -143,8 +149,8 @@ describe('useInterfaceAPI', () => {
   it('removes all event listeners on unmount', () => {
     const { unmount } = renderHook(() => useInterfaceAPI())
     unmount()
-    expect(mockEventBus.off).toHaveBeenCalledWith('app:visible', expect.any(Function))
-    expect(mockEventBus.off).toHaveBeenCalledWith('app:hidden', expect.any(Function))
+    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))

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/layout/Layout.jsx

@@ -36,7 +36,7 @@ export const Layout = () => {
       style={{ backgroundColor: mapStyle?.backgroundColor || undefined, ...getMapThemeVars(mapStyle) }}
       ref={layoutRefs.appContainerRef}
     >
-      <Viewport keyboardHintPortalRef={layoutRefs.topRef} />
+      <Viewport />
       <div className={`im-o-app__overlay${isLayoutReady ? '' : ' im-o-app__overlay--not-ready'}`}>
         <div className='im-o-app__side' ref={layoutRefs.sideRef}>
           <SlotRenderer slot={layoutSlots.SIDE} />

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

@@ -436,16 +436,9 @@
 // Inline border
 .im-o-app--inline {
   border: var(--app-border-width) solid var(--app-border-color);
+  box-sizing: border-box;
 }
 
-// Hide containers when keyboard hint is visible
-.im-o-app__main--keyboard-hint-visible {
-  .im-o-app__top-col,
-  .im-o-app__right,
-  .im-o-app__right-bottom {
-    opacity: 0;
-  }
-}
 
 // Avoid refresh jump if layout clacs are not ready
 .im-o-app__overlay--not-ready {

package/src/App/renderer/HtmlElementHost.jsx

@@ -39,11 +39,14 @@ export const getSlotRef = (slot, layoutRefs) => {
  * (e.g. the banner slot swaps DOM nodes between mobile and desktop).
  */
 export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint) => {
+  const layoutRefsRef = useRef(layoutRefs)
+  layoutRefsRef.current = layoutRefs
+
   useLayoutEffect(() => {
     const wrapper = wrapperRef.current
 
     if (isVisible) {
-      const slotRef = getSlotRef(targetSlot, layoutRefs)
+      const slotRef = getSlotRef(targetSlot, layoutRefsRef.current)
       if (slotRef?.current) {
         const backdrop = slotRef.current.querySelector(':scope > .im-o-app__modal-backdrop')
         if (backdrop) {
@@ -54,8 +57,8 @@ export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs,
         wrapper.style.display = ''
       }
     } else {
-      if (wrapper.parentElement === layoutRefs.modalRef?.current) {
-        layoutRefs.appContainerRef?.current?.appendChild(wrapper)
+      if (wrapper.parentElement === layoutRefsRef.current.modalRef?.current) {
+        layoutRefsRef.current.appContainerRef?.current?.appendChild(wrapper)
       }
       wrapper.style.display = 'none'
     }
@@ -63,7 +66,7 @@ export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs,
     return () => {
       wrapper.style.display = 'none'
     }
-  }, [isVisible, targetSlot, layoutRefs, breakpoint, wrapperRef])
+  }, [isVisible, targetSlot, breakpoint, wrapperRef])
 }
 
 /**
@@ -71,7 +74,7 @@ export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs,
  * The Panel component stays mounted for the lifetime of the registration.
  * DOM projection moves it between slots; CSS hides it when closed.
  */
-const PersistentPanel = ({ panelId, config, isOpen, openPanelProps, allowedModalPanelId, appState }) => {
+const PersistentPanel = ({ panelId, config, isOpen, openPanelProps, focusOnOpen, allowedModalPanelId, appState }) => {
   const panelRootRef = useRef(null)
   const { breakpoint, mode, isFullscreen, layoutRefs } = appState
 
@@ -108,6 +111,7 @@ const PersistentPanel = ({ panelId, config, isOpen, openPanelProps, allowedModal
       panelId={panelId}
       panelConfig={config}
       props={openPanelProps}
+      focusOnOpen={focusOnOpen}
       html={config.html}
       label={config.label}
       isOpen={isOpen}
@@ -186,6 +190,7 @@ export const HtmlElementHost = () => {
           config={config}
           isOpen={!!openPanels[panelId]}
           openPanelProps={openPanels[panelId]?.props}
+          focusOnOpen={openPanels[panelId]?.focusOnOpen}
           allowedModalPanelId={allowedModalPanelId}
           appState={appState}
         />

package/src/App/renderer/mapPanels.js

@@ -46,7 +46,7 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
   })
   const allowedModalPanelId = modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null
 
-  return openPanelEntries.map(([panelId, { props }]) => {
+  return openPanelEntries.map(([panelId, { props, focusOnOpen }]) => {
     const config = panelConfig[panelId]
     if (!config) {
       return null
@@ -91,6 +91,7 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
           panelId={panelId}
           panelConfig={config}
           props={props}
+          focusOnOpen={focusOnOpen}
           WrappedChild={WrappedChild}
           label={evaluateProp(config.label, pluginId)}
           html={pluginId ? evaluateProp(config.html, pluginId) : config.html}

package/src/App/store/appActionsMap.js

@@ -7,7 +7,7 @@ import { registerPanel as registerPanelFn, addPanel as addPanelFn, removePanel a
 import { registerControl as registerControlFn, addControl as addControlFn } from '../registry/controlRegistry.js'
 
 // Interal helper
-function buildOpenPanels (state, panelId, breakpoint, props) {
+function buildOpenPanels (state, panelId, breakpoint, props, focusOnOpen) {
   const panelConfig = state.panelConfig || state.panelRegistry.getPanelConfig()
   const bpConfig = panelConfig[panelId]?.[breakpoint]
   const isExclusiveNonModal = !!bpConfig.exclusive && !bpConfig.modal
@@ -23,7 +23,7 @@ function buildOpenPanels (state, panelId, breakpoint, props) {
   return {
     ...(isExclusiveNonModal ? {} : filteredPanels),
     ...(isModal ? state.openPanels : {}),
-    [panelId]: { props }
+    [panelId]: { props, ...(focusOnOpen && { focusOnOpen: true }) }
   }
 }
 
@@ -109,12 +109,12 @@ const setInterfaceType = (state, payload) => {
 }
 
 const openPanel = (state, payload) => {
-  const { panelId, props = {} } = payload
+  const { panelId, props = {}, focusOnOpen } = payload
 
   return {
     ...state,
     previousOpenPanels: state.openPanels,
-    openPanels: buildOpenPanels(state, panelId, state.breakpoint, props)
+    openPanels: buildOpenPanels(state, panelId, state.breakpoint, props, focusOnOpen)
   }
 }
 

package/src/App/store/appActionsMap.test.js

@@ -100,6 +100,16 @@ describe('actionsMap full coverage', () => {
     expect(result.openPanels.panel3?.props).toEqual({})
   })
 
+  test('OPEN_PANEL stores focusOnOpen when provided', () => {
+    const result = actionsMap.OPEN_PANEL(state, { panelId: 'panel2', focusOnOpen: true })
+    expect(result.openPanels.panel2?.focusOnOpen).toBe(true)
+  })
+
+  test('OPEN_PANEL omits focusOnOpen when not provided', () => {
+    const result = actionsMap.OPEN_PANEL(state, { panelId: 'panel2' })
+    expect(result.openPanels.panel2?.focusOnOpen).toBeUndefined()
+  })
+
   test('CLOSE_PANEL removes a panel', () => {
     const result = actionsMap.CLOSE_PANEL(state, 'panel1')
     expect(result.openPanels.panel1).toBeUndefined()

package/src/InteractiveMap/InteractiveMap.js

@@ -103,7 +103,9 @@ export default class InteractiveMap {
   }
 
   _handleButtonClick (e) {
-    history.pushState({ isBack: true }, '', e.currentTarget.getAttribute('href'))
+    if (this.config.manageHistoryState) {
+      history.pushState({ isBack: true }, '', e.currentTarget.getAttribute('href'))
+    }
     if (this._isHidden) {
       this.showApp()
     } else {
@@ -132,11 +134,20 @@ export default class InteractiveMap {
       this.removeApp()
     }
 
-    const key = this.config.mapViewParamKey
-    const href = location.href
-    const newUrl = this._removeMapParamFromUrl(href, key)
+    if (!this.config.manageHistoryState) {
+      return
+    }
 
-    history.replaceState(history.state, '', newUrl)
+    // If this history entry was pushed by the map's open button, go back so the
+    // ?mv= entry is preserved as a forward entry (browser forward re-opens the map).
+    // Otherwise (direct URL / bookmark), just strip the param in place.
+    if (history.state?.isBack) {
+      history.back()
+    } else {
+      const key = this.config.mapViewParamKey
+      const newUrl = this._removeMapParamFromUrl(location.href, key)
+      history.replaceState(history.state, '', newUrl)
+    }
   }
 
   /**
@@ -190,6 +201,7 @@ export default class InteractiveMap {
       })
 
       updateDOMState(this)
+      this.eventBus.emit(events.APP_OPENED, { statePreserved: false })
     } catch (err) {
       renderError(this.rootEl, this.config.genericErrorText)
       console.error(err)
@@ -213,8 +225,9 @@ export default class InteractiveMap {
       this._openButton.focus()
     }
 
-    updateDOMState(this)
+    updateDOMState(this, { isFullscreen: false })
 
+    this.eventBus.emit(events.APP_CLOSED, { statePreserved: false })
     this.eventBus.emit(events.MAP_DESTROY, { mapId: this.id })
   }
 
@@ -243,10 +256,10 @@ export default class InteractiveMap {
     // Reset page title (remove prepended map title)
     const parts = document.title.split(': ')
     if (parts.length > 1) {
-      document.title = parts[parts.length - 1]
+      document.title = parts.at(-1)
     }
 
-    this.eventBus.emit(events.APP_HIDDEN)
+    this.eventBus.emit(events.APP_CLOSED, { statePreserved: true })
   }
 
   /**
@@ -265,7 +278,7 @@ export default class InteractiveMap {
 
     updateDOMState(this)
 
-    this.eventBus.emit(events.APP_VISIBLE)
+    this.eventBus.emit(events.APP_OPENED, { statePreserved: true })
   }
 
   /**
@@ -365,6 +378,10 @@ export default class InteractiveMap {
   /**
    * Add a panel to the UI.
    *
+   * Focus is moved to the panel on open by default. Set `focus: false` in the
+   * config to suppress this — useful when adding panels on page load where
+   * stealing focus would be disruptive.
+   *
    * @param {string} id - Unique panel identifier.
    * @param {PanelDefinition} config - Panel configuration.
    */
@@ -384,10 +401,15 @@ export default class InteractiveMap {
   /**
    * Show a panel.
    *
+   * Focus is moved to the panel by default. Set `focus: false` in options to
+   * suppress this — useful when showing a panel and you want focus to remain on the button.
+   *
    * @param {string} id - Panel identifier to show.
+   * @param {object} [options]
+   * @param {boolean} [options.focus=true] - Whether to move focus to the panel.
    */
-  showPanel (id) {
-    this.eventBus.emit(events.APP_SHOW_PANEL, id)
+  showPanel (id, { focus = true } = {}) {
+    this.eventBus.emit(events.APP_SHOW_PANEL, { id, focus })
   }
 
   /**
@@ -426,4 +448,30 @@ export default class InteractiveMap {
   setView (opts) {
     this.eventBus.emit(events.MAP_SET_VIEW, opts)
   }
+
+  /**
+   * Programmatically open the map.
+   *
+   * Equivalent to the user clicking the open button. If the map has been hidden (e.g. in hybrid mode),
+   * it will be shown; otherwise the app will be loaded for the first time.
+   */
+  open () {
+    if (this._isHidden) {
+      this.showApp()
+    } else if (this._root) {
+      // App is already open — no-op
+    } else {
+      this.loadApp()
+    }
+  }
+
+  /**
+   * Programmatically close the map.
+   *
+   * Triggers the same logic as the exit button. If `preserveStateOnClose` is true, the map is hidden
+   * but not destroyed; otherwise the app is removed entirely.
+   */
+  close () {
+    this._handleExitClick()
+  }
 }