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

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

package/src/InteractiveMap/domStateManager.test.js

@@ -69,6 +69,27 @@ describe('updateDOMState', () => {
     }
   })
 
+  it('isFullscreen override forces non-fullscreen even when URL param matches', () => {
+    mapInstance.config.behaviour = 'buttonFirst'
+    queryString.getQueryParam.mockReturnValue('map') // URL says fullscreen
+
+    updateDOMState(mapInstance, { isFullscreen: false }) // but override says no
+
+    expect(document.documentElement.classList.contains('im-is-fullscreen')).toBe(false)
+    expect(rootEl.style.height).toBe('auto')
+  })
+
+  it('buttonFirst with manageHistoryState false is always fullscreen regardless of URL', () => {
+    mapInstance.config.behaviour = 'buttonFirst'
+    mapInstance.config.manageHistoryState = false
+    queryString.getQueryParam.mockReturnValue(null) // no mv param in URL
+
+    updateDOMState(mapInstance)
+
+    expect(document.documentElement.classList.contains('im-is-fullscreen')).toBe(true)
+    expect(mapInstance.rootEl.style.height).toBe('100%')
+  })
+
   describe('hybrid behaviour', () => {
     beforeEach(() => {
       mapInstance.config.behaviour = 'hybrid'

package/src/InteractiveMap/historyManager.js

@@ -40,6 +40,32 @@ function closeMap (mapInstance) {
   }
 }
 
+/**
+ * Syncs a single map instance against the current URL view parameter.
+ *
+ * @param {MapInstance} mapInstance
+ * @param {string|null} viewId - The current `mv` query param value.
+ * @private
+ */
+function syncMapInstance (mapInstance, viewId) {
+  if (mapInstance.config.manageHistoryState === false) {
+    return
+  }
+
+  const shouldBeOpen = mapInstance.id === viewId
+  const isHybridVisible = mapInstance.config.behaviour === 'hybrid' && !isHybridFullscreen(mapInstance.config)
+  const isOpen = mapInstance.rootEl?.children.length
+
+  if (shouldBeOpen && (!isOpen || mapInstance._isHidden)) {
+    openMap(mapInstance)
+    return
+  }
+
+  if (!shouldBeOpen && isOpen && !isHybridVisible) {
+    closeMap(mapInstance)
+  }
+}
+
 /**
  * Handles the `popstate` event triggered by browser back/forward navigation.
  *
@@ -56,21 +82,7 @@ function closeMap (mapInstance) {
  */
 function handlePopstate () {
   const viewId = getQueryParam(defaults.mapViewParamKey)
-
-  for (const mapInstance of components.values()) {
-    const shouldBeOpen = mapInstance.id === viewId
-    const isHybridVisible = mapInstance.config.behaviour === 'hybrid' && !isHybridFullscreen(mapInstance.config)
-    const isOpen = mapInstance.rootEl?.children.length
-
-    if (shouldBeOpen && (!isOpen || mapInstance._isHidden)) {
-      openMap(mapInstance)
-      continue
-    }
-
-    if (!shouldBeOpen && isOpen && !isHybridVisible) {
-      closeMap(mapInstance)
-    }
-  }
+  components.forEach(mapInstance => syncMapInstance(mapInstance, viewId))
 }
 
 // -----------------------------------------------------------------------------
@@ -105,7 +117,7 @@ let initialized = false
  */
 function register (component) {
   if (!initialized) {
-    window.addEventListener('popstate', handlePopstate)
+    globalThis.addEventListener('popstate', handlePopstate)
     initialized = true
   }
 

package/src/InteractiveMap/historyManager.test.js

@@ -141,6 +141,23 @@ describe('historyManager', () => {
     expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 768px)')
   })
 
+  it('skips component when manageHistoryState is false', () => {
+    const managedComponent = {
+      id: 'managed',
+      config: { behaviour: 'buttonFirst', hybridWidth: null, maxMobileWidth: 640, manageHistoryState: false },
+      rootEl: document.createElement('div'),
+      loadApp: jest.fn(),
+      removeApp: jest.fn(),
+      _isHidden: false
+    }
+    historyManager.register(managedComponent)
+    queryString.getQueryParam.mockReturnValue('managed')
+
+    window.dispatchEvent(popstateEvent)
+
+    expect(managedComponent.loadApp).not.toHaveBeenCalled()
+  })
+
   it('unregisters component', () => {
     historyManager.register(component1)
     component1.rootEl.appendChild(document.createElement('div'))

package/src/config/appConfig.js

@@ -24,7 +24,7 @@ export const defaultAppConfig = {
     label: 'Exit',
     iconId: 'close',
     onClick: (_e, { services }) => services.closeApp(),
-    excludeWhen: ({ appConfig, appState }) => !appConfig.hasExitButton || !(appState.isFullscreen && (new URL(window.location.href)).searchParams.has(appConfig.mapViewParamKey)),
+    excludeWhen: ({ appConfig, appState }) => !appConfig.hasExitButton || !appState.isFullscreen,
     mobile: exitButtonSlots,
     tablet: exitButtonSlots,
     desktop: exitButtonSlots
@@ -115,6 +115,7 @@ export const defaultButtonConfig = {
 // Used by addPanel
 export const defaultPanelConfig = {
   label: 'Panel',
+  focus: true,
   mobile: {
     slot: 'drawer',
     open: true,

package/src/config/appConfig.test.js

@@ -23,28 +23,18 @@ describe('defaultAppConfig', () => {
 
   // --- EXIT BUTTON (Line 27 Coverage) ---
   it('covers all branches of exitBtn excludeWhen', () => {
-    const config = { hasExitButton: true, mapViewParamKey: 'view' }
-
     expect(exitBtn.excludeWhen({
-      appConfig: { ...config, hasExitButton: false },
+      appConfig: { hasExitButton: false },
       appState: { isFullscreen: true }
     })).toBe(true)
 
-    window.history.pushState({}, '', '?view=map')
     expect(exitBtn.excludeWhen({
-      appConfig: config,
+      appConfig: { hasExitButton: true },
       appState: { isFullscreen: false }
     })).toBe(true)
 
-    window.history.pushState({}, '', '?wrong=param')
-    expect(exitBtn.excludeWhen({
-      appConfig: config,
-      appState: { isFullscreen: true }
-    })).toBe(true)
-
-    window.history.pushState({}, '', '?view=map')
     expect(exitBtn.excludeWhen({
-      appConfig: config,
+      appConfig: { hasExitButton: true },
       appState: { isFullscreen: true }
     })).toBe(false)
   })

package/src/config/defaults.js

@@ -16,7 +16,7 @@ const defaults = {
   containerHeight: '600px',
   deviceNotSupportedText: 'Your device is not supported. A map is available with a more up-to-date browser or device.',
   enableFullscreen: false,
-  enableZoomControls: false,
+  enableZoomControls: true,
   genericErrorText: 'There was a problem loading the map. Please try again later.',
   hasExitButton: false,
   hybridWidth: null, // Defaults to maxMobileWidth if not set
@@ -24,6 +24,7 @@ const defaults = {
   mapLabel: 'Interactive map',
   mapProvider: null,
   mapSize: 'small',
+  manageHistoryState: true,
   mapViewParamKey: 'mv',
   maxMobileWidth: 640,
   minDesktopWidth: 835,

package/src/config/events.js

@@ -62,32 +62,34 @@ export const EVENTS = {
   APP_READY: 'app:ready',
 
   /**
-   * Emitted when the map application becomes visible after being hidden.
+   * Emitted when the map application has opened and is visible.
    *
-   * This can occur in 'hybrid behaviour' responsive scenarios where the map is already initialized
-   * (e.g. initialized inline on desktop) but was hidden and then shown again
-   * (e.g. resizing to mobile and opening the map).
+   * Fired after initial load (`loadApp`) and when the app is shown again after being hidden (`showApp`).
+   * Subscribe to this event to react whenever the map becomes visible to the user.
    *
-   * @remarks
-   * - Only emitted when transitioning from hidden → visible.
-   * - Not fired on initial open.
-   * - The existing map state may be preserved depending on configuration.
+   * Payload: `{ statePreserved: boolean }` — `true` if the map state was preserved from a previous session.
+   *
+   * @example
+   * map.on(EVENTS.APP_OPENED, ({ statePreserved }) => {
+   *   console.log('Map opened, state preserved:', statePreserved)
+   * })
    */
-  APP_VISIBLE: 'app:visible',
+  APP_OPENED: 'app:opened',
 
   /**
-   * Emitted when the map application becomes hidden.
+   * Emitted when the map application has closed and is no longer visible.
+   *
+   * Fired when the app is hidden (`hideApp`) or removed (`removeApp`).
+   * Subscribe to this event to react whenever the map is closed.
    *
-   * This can occur in 'hybrid behaviour' responsive scenarios where the map was initialized inline
-   * (e.g. visible on desktop) but then becomes hidden
-   * (e.g. resizing to mobile or closing the map view).
+   * Payload: `{ statePreserved: boolean }` — `true` if the map state was preserved (i.e. can be restored).
    *
-   * @remarks
-   * - Only emitted when transitioning from visible → hidden.
-   * - Not fired on initial load if the map starts hidden.
-   * - The map state may be preserved depending on configuration.
+   * @example
+   * map.on(EVENTS.APP_CLOSED, ({ statePreserved }) => {
+   *   console.log('Map closed, state preserved:', statePreserved)
+   * })
    */
-  APP_HIDDEN: 'app:hidden',
+  APP_CLOSED: 'app:closed',
 
   /**
    * Emitted when a panel is opened.
@@ -202,9 +204,6 @@ export const EVENTS = {
    */
   MAP_CLICK: 'map:click',
 
-  /** Emitted when the user exits the map (e.g., via the close button). */
-  MAP_EXIT: 'map:exit',
-
   /** Emitted when the map is destroyed. Payload: { mapId: string } */
   MAP_DESTROY: 'map:destroy'
 }

package/src/services/closeApp.js

@@ -1,13 +1,4 @@
 // src/services/closeApp.js
-import { EVENTS as events } from '../config/events.js'
-
-export function closeApp (mapId, handleExitClick, eventBus) {
-  eventBus.emit(events.MAP_EXIT, { mapId })
-
-  if (history.state?.isBack) {
-    history.back()
-    return
-  }
-
+export function closeApp (_mapId, handleExitClick) {
   handleExitClick()
 }

package/src/services/closeApp.test.js

@@ -1,49 +1,9 @@
 import { closeApp } from './closeApp'
 
 describe('closeApp', () => {
-  let handleExitClickMock
-  let mockEventBus
-
-  beforeEach(() => {
-    handleExitClickMock = jest.fn()
-    mockEventBus = {
-      emit: jest.fn(),
-      on: jest.fn(),
-      off: jest.fn()
-    }
-    jest.spyOn(history, 'back').mockImplementation(() => {})
-  })
-
-  afterEach(() => {
-    jest.restoreAllMocks()
-    jest.clearAllMocks()
-  })
-
-  it('calls history.back() when history.state.isBack is true', () => {
-    Object.defineProperty(history, 'state', {
-      value: { isBack: true },
-      writable: true,
-      configurable: true
-    })
-
-    closeApp('map-123', handleExitClickMock, mockEventBus)
-
-    expect(mockEventBus.emit).toHaveBeenCalledWith('map:exit', { mapId: 'map-123' })
-    expect(history.back).toHaveBeenCalled()
-    expect(handleExitClickMock).not.toHaveBeenCalled()
-  })
-
-  it('calls handleExitClick when history.state.isBack is not true', () => {
-    Object.defineProperty(history, 'state', {
-      value: null,
-      writable: true,
-      configurable: true
-    })
-
-    closeApp('map-123', handleExitClickMock, mockEventBus)
-
-    expect(mockEventBus.emit).toHaveBeenCalledWith('map:exit', { mapId: 'map-123' })
-    expect(history.back).not.toHaveBeenCalled()
+  it('calls handleExitClick', () => {
+    const handleExitClickMock = jest.fn()
+    closeApp('map-123', handleExitClickMock)
     expect(handleExitClickMock).toHaveBeenCalled()
   })
 })

package/src/types.js

@@ -591,7 +591,7 @@
  * @property {boolean} [enableFullscreen=false]
  * Whether a toggle fullscreen button is displayed.
  *
- * @property {boolean} [enableZoomControls=false]
+ * @property {boolean} [enableZoomControls=true]
  * Whether zoom control buttons are displayed.
  *
  * @property {[number, number, number, number]} [extent]
@@ -661,6 +661,11 @@
  * @property {PluginDescriptor[]} [plugins]
  * Plugins to load.
  *
+ * @property {boolean} [manageHistoryState=true]
+ * Whether the library should manage browser history state (pushState/replaceState) when opening and closing the map.
+ * Set to `false` in SPA frameworks (e.g. React Router, Docusaurus) that intercept history API calls.
+ * When `false`, listen to `APP_OPENED` and `APP_CLOSED` events and manage navigation in your router instead.
+ *
  * @property {boolean} [preserveStateOnClose=false]
  * Whether to preserve the map state when closed via back button or exit button.
  * When true, the map is hidden but not destroyed, preserving markers, zoom, etc.

package/src/utils/mapStateSync.js

@@ -1,4 +1,11 @@
-// Internal (not exported) - Accept optional search string for testing
+/**
+ * Reads center and zoom for a given map ID from a URL search string.
+ * The `search` parameter is accepted explicitly to keep this function pure and testable.
+ *
+ * @param {string} id - Map instance ID.
+ * @param {string} search - URL search string (e.g. `window.location.search`).
+ * @returns {{ center: [number, number], zoom: number } | null}
+ */
 const getMapStateFromURL = (id, search) => {
   const params = new URLSearchParams(search)
   const centerStr = params.get(`${id}:center`)
@@ -11,30 +18,61 @@ const getMapStateFromURL = (id, search) => {
   return { center: [lng, lat], zoom }
 }
 
+/**
+ * Persists map center and zoom into the page URL without triggering navigation.
+ *
+ * Existing query parameters are preserved. Parameters for this map ID are
+ * replaced if already present. Builds the URL manually to avoid percent-encoding
+ * colons and commas that URLSearchParams would otherwise encode.
+ *
+ * @param {string} id - Map instance ID, used as a namespace prefix for the params.
+ * @param {{ center?: [number, number], zoom?: number }} state - Map state to write.
+ * @param {string} [currentHref] - URL to update. Defaults to `window.location.href`.
+ * @returns {void}
+ */
 const setMapStateInURL = (id, state, currentHref = window.location.href) => {
-  // Use the passed href or the global one
   const url = new URL(currentHref || 'http://localhost')
-  const params = [...new URLSearchParams(url.search)].map(([key, value]) => `${key}=${value}`)
+
+  const newKeys = new Set()
   const newParams = []
 
   if (state.center) {
-    newParams.push(`${id}:center=${state.center[0]},${state.center[1]}`)
+    const key = `${id}:center`
+    newKeys.add(key)
+    newParams.push(`${key}=${state.center[0]},${state.center[1]}`)
   }
   if (state.zoom != null) {
-    newParams.push(`${id}:zoom=${state.zoom}`)
+    const key = `${id}:zoom`
+    newKeys.add(key)
+    newParams.push(`${key}=${state.zoom}`)
   }
 
-  const filteredParams = params.filter(p => {
-    return !newParams.some(np => np.split('=')[0] === p.split('=')[0])
+  const existingParams = []
+  url.searchParams.forEach((value, key) => {
+    if (!newKeys.has(key)) {
+      existingParams.push(`${key}=${value}`)
+    }
   })
 
-  const hash = url.hash || ''
-  const newUrl = `${url.origin}${url.pathname}?${[...filteredParams, ...newParams].join('&')}${hash}`
+  const allParams = [...existingParams, ...newParams].join('&')
+  const search = allParams ? '?' + allParams : ''
+  const newUrl = `${url.origin}${url.pathname}${search}${url.hash}`
   window.history.replaceState(window.history.state, '', newUrl)
 }
 
+/**
+ * Returns the initial map view state, preferring any saved state from the URL.
+ *
+ * Resolution order:
+ * 1. Center/zoom encoded in the URL search string for this map ID.
+ * 2. A `bounds` value if provided (used to fit the view on load).
+ * 3. The configured `center` and `zoom` defaults.
+ *
+ * @param {{ id: string, center: [number, number], zoom: number, bounds?: any }} config - Map config.
+ * @param {string} [search] - URL search string. Defaults to `window.location.search`.
+ * @returns {{ center: [number, number], zoom: number } | { bounds: any }}
+ */
 const getInitialMapState = ({ id, center, zoom, bounds }, search = window.location.search) => {
-  // Pass search string down to the internal function
   const savedState = getMapStateFromURL(id, search)
   if (savedState) {
     return {