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

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

@@ -19,7 +19,7 @@ describe('projectCoords', () => {
   const mockProvider = { mapToScreen: jest.fn(() => ({ x: 100, y: 200 })) }
 
   it('returns scaled coordinates when ready', () => {
-    expect(projectCoords({ lat: 1, lng: 1 }, mockProvider, 'medium', true)).toEqual({ x: 200, y: 381 })
+    expect(projectCoords({ lat: 1, lng: 1 }, mockProvider, 'medium', true)).toEqual({ x: 200, y: 400 })
   })
 
   it('returns zero when not ready or no provider', () => {
@@ -102,7 +102,7 @@ describe('useMarkers', () => {
 
     const renderCallback = mockEventBus.on.mock.calls.find(call => call[0] === 'map:render')[1]
     act(() => renderCallback())
-    expect(mockElement.style.transform).toBe('translate(200px, 381px)')
+    expect(mockElement.style.transform).toBe('translate(200px, 400px)')
   })
 
   it('skips map:render when not ready or no provider (line 60)', () => {
@@ -126,7 +126,7 @@ describe('useMarkers', () => {
       isMapReady: true
     })
     rerender()
-    expect(mockElement.style.transform).toBe('translate(300px, 581px)')
+    expect(mockElement.style.transform).toBe('translate(300px, 600px)')
   })
 
   it('handles app:addmarker safely', () => {
@@ -137,7 +137,7 @@ describe('useMarkers', () => {
     act(() => handleAddMarker(addPayload))
     expect(mockDispatch).toHaveBeenCalledWith({
       type: 'UPSERT_LOCATION_MARKER',
-      payload: { id: 'm1', coords: { lat: 1, lng: 1 }, label: 'Test', x: 200, y: 381, isVisible: true }
+      payload: { id: 'm1', coords: { lat: 1, lng: 1 }, label: 'Test', x: 200, y: 400, isVisible: true }
     })
   })
 

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 { getMapThemeVars } from '../../config/mapTheme.js'
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
@@ -30,13 +31,12 @@ export const Layout = () => {
         `im-o-app--${interfaceType}`,
         `im-o-app--${isFullscreen ? 'fullscreen' : 'inline'}`,
         `im-o-app--${mapStyle?.appColorScheme || preferredColorScheme}-app`,
-        `im-o-app--${mapStyle?.mapColorScheme || 'light'}-map`,
         hasExclusiveControl && 'im-o-app--exclusive-control'
       ].filter(Boolean).join(' ')}
-      style={{ backgroundColor: mapStyle?.backgroundColor || undefined }}
+      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.test.jsx

@@ -72,9 +72,11 @@ describe('Layout', () => {
     expect(root.className).toContain('im-o-app--map')
     expect(root.className).toContain('im-o-app--inline')
     expect(root.className).toContain('im-o-app--light-app')
-    expect(root.className).toContain('im-o-app--dark-map')
     expect(root.className).toContain('im-o-app--exclusive-control')
     expect(root.style.backgroundColor).toBe('pink')
+    expect(root.style.getPropertyValue('--map-overlay-halo-color')).toBe('#0b0c0c')
+    expect(root.style.getPropertyValue('--map-overlay-selected-color')).toBe('#ffffff')
+    expect(root.style.getPropertyValue('--map-overlay-foreground-color')).toBe('#ffffff')
 
     const overlay = root.querySelector('.im-o-app__overlay')
     expect(overlay.className).not.toContain('not-ready')
@@ -123,7 +125,7 @@ describe('Layout', () => {
 
     const root = document.getElementById('myApp-im-app')
     expect(root.className).toContain('im-o-app--dark-app')
-    expect(root.className).toContain('im-o-app--light-map') // fallback
+    expect(root.className).not.toContain('im-o-app--light-map')
     expect(root.style.backgroundColor).toBe('')
     expect(root.className).not.toContain('exclusive-control')
   })

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/ServiceProvider.jsx

@@ -1,27 +1,29 @@
 // src/App/store/ServiceProvider.jsx
 import React, { createContext, useMemo, useRef } from 'react'
-import { EVENTS } from '../../config/events.js'
 import { createAnnouncer } from '../../services/announcer.js'
 import { reverseGeocode } from '../../services/reverseGeocode.js'
 import { useConfig } from '../store/configContext.js'
 import { closeApp } from '../../services/closeApp.js'
-import { logger } from '../../services/logger.js'
+import { symbolRegistry } from '../../services/symbolRegistry.js'
+import { patternRegistry } from '../../services/patternRegistry.js'
 
 export const ServiceContext = createContext(null)
 
 export const ServiceProvider = ({ eventBus, children }) => {
-  const { id, handleExitClick } = useConfig()
+  const { id, handleExitClick, symbolDefaults: constructorSymbolDefaults } = useConfig()
   const mapStatusRef = useRef(null)
   const announce = useMemo(() => createAnnouncer(mapStatusRef), [])
 
+  symbolRegistry.setDefaults(constructorSymbolDefaults || {})
+
   const services = useMemo(() => ({
     announce,
     reverseGeocode: (zoom, center) => reverseGeocode(zoom, center),
-    events: EVENTS,
     eventBus,
     mapStatusRef,
     closeApp: () => closeApp(id, handleExitClick, eventBus),
-    logger
+    symbolRegistry,
+    patternRegistry
   }), [announce])
 
   return (

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/App/store/mapActionsMap.js

@@ -12,12 +12,10 @@ const setMapReady = (state) => ({
   isMapReady: true
 })
 
-const setMapStyle = (state, payload) => {
-  return {
-    ...state,
-    mapStyle: payload
-  }
-}
+const setMapStyle = (state, payload) => ({
+  ...state,
+  mapStyle: payload
+})
 
 const setMapSize = (state, payload) => {
   return {

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

@@ -46,8 +46,9 @@ describe('actionsMap', () => {
   })
 
   test('SET_MAP_STYLE sets mapStyle', () => {
-    const result = actionsMap.SET_MAP_STYLE(state, 'satellite')
-    expect(result.mapStyle).toBe('satellite')
+    const mapStyle = { id: 'satellite' }
+    const result = actionsMap.SET_MAP_STYLE(state, mapStyle)
+    expect(result.mapStyle).toBe(mapStyle)
     expect(result.otherProp).toBe(state.otherProp)
   })
 

package/src/App/store/mapReducer.js

@@ -17,10 +17,11 @@ export const initialState = (config) => {
   // Does a plugin handle map styles
   const pluginHandlesMapStyles = !!registeredPlugins?.find(plugin => plugin.config?.handlesMapStyle)
 
+  const initialMapStyle = pluginHandlesMapStyles ? null : mapStyle
   return {
     isMapReady: false,
     mapProvider: null,
-    mapStyle: pluginHandlesMapStyles ? null : mapStyle,
+    mapStyle: initialMapStyle,
     mapSize,
     center,
     zoom,

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()
+  }
 }

package/src/InteractiveMap/InteractiveMap.test.js

@@ -117,7 +117,7 @@ describe('InteractiveMap Core Functionality', () => {
   })
 
   it('open button click calls _handleButtonClick / loadApp', async () => {
-    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', manageHistoryState: true, mapProvider: mapProviderMock })
     const loadSpy = jest.spyOn(map, 'loadApp').mockResolvedValue()
     const pushStateSpy = jest.spyOn(history, 'pushState').mockImplementation(() => {})
     const fakeEvent = { currentTarget: { getAttribute: jest.fn().mockReturnValue('/?mv=map') } }
@@ -195,7 +195,7 @@ describe('InteractiveMap Core Functionality', () => {
     expect(map.unmount).toHaveBeenCalled()
     expect(mockButtonInstance.removeAttribute).toHaveBeenCalledWith('style')
     expect(mockButtonInstance.focus).toHaveBeenCalled()
-    expect(updateDOMState).toHaveBeenCalledWith(map)
+    expect(updateDOMState).toHaveBeenCalledWith(map, { isFullscreen: false })
   })
 
   it('skips unmount if _root is falsy or unmount is not a function', () => {
@@ -275,6 +275,7 @@ describe('InteractiveMap Core Functionality', () => {
       behaviour: 'buttonFirst',
       mapProvider: mapProviderMock,
       mapViewParamKey: 'mv',
+      manageHistoryState: true,
       preserveStateOnClose: false
     })
 
@@ -303,6 +304,7 @@ describe('InteractiveMap Core Functionality', () => {
       behaviour: 'buttonFirst',
       mapProvider: mapProviderMock,
       mapViewParamKey: 'mv',
+      manageHistoryState: true,
       preserveStateOnClose: true
     })
 
@@ -321,7 +323,7 @@ describe('InteractiveMap Core Functionality', () => {
   })
 
   it('_handleButtonClick calls showApp when map is hidden', async () => {
-    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', manageHistoryState: true, mapProvider: mapProviderMock })
     map._isHidden = true
     const showAppSpy = jest.spyOn(map, 'showApp').mockImplementation(() => {})
     const loadAppSpy = jest.spyOn(map, 'loadApp').mockResolvedValue()
@@ -339,6 +341,126 @@ describe('InteractiveMap Core Functionality', () => {
     pushStateSpy.mockRestore()
   })
 
+  it('_handleButtonClick skips pushState when manageHistoryState is false', async () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', manageHistoryState: false, mapProvider: mapProviderMock })
+    expect(map.config.manageHistoryState).toBe(false)
+    const pushStateSpy = jest.spyOn(history, 'pushState').mockImplementation(() => {})
+    const fakeEvent = { currentTarget: { getAttribute: jest.fn().mockReturnValue('/?mv=map') } }
+
+    await openButtonCallback(fakeEvent)
+
+    expect(pushStateSpy).not.toHaveBeenCalled()
+    pushStateSpy.mockRestore()
+  })
+
+  it('_handleExitClick calls history.back() when history.state.isBack is true', () => {
+    const backSpy = jest.spyOn(history, 'back').mockImplementation(() => {})
+    Object.defineProperty(history, 'state', { value: { isBack: true }, writable: true, configurable: true })
+
+    const map = new InteractiveMap('map', {
+      behaviour: 'buttonFirst',
+      mapProvider: mapProviderMock,
+      mapViewParamKey: 'mv',
+      manageHistoryState: true,
+      preserveStateOnClose: false
+    })
+    jest.spyOn(map, 'removeApp').mockImplementation(() => {})
+
+    map._handleExitClick()
+
+    expect(backSpy).toHaveBeenCalled()
+    Object.defineProperty(history, 'state', { value: null, writable: true, configurable: true })
+    backSpy.mockRestore()
+  })
+
+  it('_handleExitClick skips history when manageHistoryState is false', () => {
+    const backSpy = jest.spyOn(history, 'back').mockImplementation(() => {})
+    const replaceStateSpy = jest.spyOn(history, 'replaceState').mockImplementation(() => {})
+
+    const map = new InteractiveMap('map', {
+      behaviour: 'buttonFirst',
+      mapProvider: mapProviderMock,
+      mapViewParamKey: 'mv',
+      manageHistoryState: false,
+      preserveStateOnClose: false
+    })
+    jest.spyOn(map, 'removeApp').mockImplementation(() => {})
+
+    map._handleExitClick()
+
+    expect(backSpy).not.toHaveBeenCalled()
+    expect(replaceStateSpy).not.toHaveBeenCalled()
+    backSpy.mockRestore()
+    replaceStateSpy.mockRestore()
+  })
+
+  it('loadApp emits APP_OPENED with statePreserved: false', async () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    await map.loadApp()
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:opened', { statePreserved: false })
+  })
+
+  it('removeApp emits APP_CLOSED with statePreserved: false', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    map._root = {}
+    map.unmount = jest.fn()
+    map.removeApp()
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:closed', { statePreserved: false })
+  })
+
+  it('hideApp emits APP_CLOSED with statePreserved: true', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    map.hideApp()
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:closed', { statePreserved: true })
+  })
+
+  it('showApp emits APP_OPENED with statePreserved: true', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    map._isHidden = true
+    map.showApp()
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:opened', { statePreserved: true })
+  })
+
+  it('open() shows hidden map', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    const showSpy = jest.spyOn(map, 'showApp').mockImplementation(() => {})
+    map._isHidden = true
+    map.open()
+    expect(showSpy).toHaveBeenCalled()
+    showSpy.mockRestore()
+  })
+
+  it('open() loads map when not yet initialised', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    const loadSpy = jest.spyOn(map, 'loadApp').mockResolvedValue()
+    map._root = null
+    map._isHidden = false
+    map.open()
+    expect(loadSpy).toHaveBeenCalled()
+    loadSpy.mockRestore()
+  })
+
+  it('open() is a no-op when already open', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    const loadSpy = jest.spyOn(map, 'loadApp').mockResolvedValue()
+    const showSpy = jest.spyOn(map, 'showApp').mockImplementation(() => {})
+    map._root = {}
+    map._isHidden = false
+    map.open()
+    expect(loadSpy).not.toHaveBeenCalled()
+    expect(showSpy).not.toHaveBeenCalled()
+    loadSpy.mockRestore()
+    showSpy.mockRestore()
+  })
+
+  it('close() delegates to _handleExitClick', () => {
+    const map = new InteractiveMap('map', { mapProvider: mapProviderMock })
+    const exitSpy = jest.spyOn(map, '_handleExitClick').mockImplementation(() => {})
+    map.close()
+    expect(exitSpy).toHaveBeenCalled()
+    exitSpy.mockRestore()
+  })
+
   it('hideApp sets _isHidden and hides element', () => {
     const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
     map._openButton = mockButtonInstance
@@ -497,7 +619,7 @@ describe('InteractiveMap Public API Methods', () => {
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:removepanel', 'panel1')
 
     // New assertions for coverage
-    expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', 'panel2')
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', { id: 'panel2', focus: true })
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:hidepanel', 'panel3')
   })
 

package/src/InteractiveMap/domStateManager.js

@@ -14,11 +14,21 @@ function updatePageTitle ({ pageTitle, isFullscreen }) {
 }
 
 function getIsFullscreen (config) {
-  const { id, behaviour } = config
-  const hasViewParam = getQueryParam(defaults.mapViewParamKey) === id
+  const { id, behaviour, manageHistoryState } = config
 
-  return behaviour === 'mapOnly' ||
-         (hasViewParam && (behaviour === 'buttonFirst' || isHybridFullscreen(config)))
+  if (behaviour === 'mapOnly') {
+    return true
+  }
+
+  if (behaviour === 'buttonFirst') {
+    // When the SPA manages history, the app is always fullscreen when loaded
+    if (manageHistoryState === false) {
+      return true
+    }
+    return getQueryParam(defaults.mapViewParamKey) === id
+  }
+
+  return isHybridFullscreen(config) && getQueryParam(defaults.mapViewParamKey) === id
 }
 
 // -----------------------------------------------------------------------------
@@ -36,12 +46,14 @@ function getIsFullscreen (config) {
  * @param {string} mapInstance.config.behaviour - Behaviour mode ("mapOnly", "buttonFirst", "hybrid").
  * @param {string|number} mapInstance.config.containerHeight - Height to use when not fullscreen.
  * @param {HTMLElement} mapInstance.rootEl - Root element of the app.
+ * @param {Object} [options]
+ * @param {boolean} [options.isFullscreen] - Override the computed fullscreen state.
  * @returns {void}
  */
-function updateDOMState (mapInstance) {
+function updateDOMState (mapInstance, { isFullscreen: isFullscreenOverride } = {}) {
   const { config, rootEl } = mapInstance
   const { pageTitle, behaviour, containerHeight } = config
-  const isFullscreen = getIsFullscreen(config)
+  const isFullscreen = isFullscreenOverride ?? getIsFullscreen(config)
 
   if (['mapOnly', 'buttonFirst', 'hybrid'].includes(behaviour)) {
     toggleInertElements({ containerEl: rootEl, isFullscreen })