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

package/src/InteractiveMap/InteractiveMap.test.js

@@ -39,8 +39,8 @@ jest.mock('../utils/detectInterfaceType.js', () => ({
 }))
 jest.mock('../services/reverseGeocode.js', () => ({ createReverseGeocode: jest.fn() }))
 jest.mock('../services/eventBus.js', () => ({
-  createEventBus: jest.fn(() => ({ on: jest.fn(), off: jest.fn(), emit: jest.fn(), destroy: jest.fn() })),
-  default: { on: jest.fn(), off: jest.fn(), emit: jest.fn(), destroy: jest.fn() }
+  createEventBus: jest.fn(() => ({ on: jest.fn(), off: jest.fn(), emit: jest.fn(), emitWhenReady: jest.fn(), destroy: jest.fn() })),
+  default: { on: jest.fn(), off: jest.fn(), emit: jest.fn(), emitWhenReady: jest.fn(), destroy: jest.fn() }
 }))
 jest.mock('../App/initialiseApp.js', () => ({ initialiseApp: jest.fn() }))
 
@@ -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')
   })
 
@@ -513,12 +635,12 @@ describe('InteractiveMap Public API Methods', () => {
   it('fitToBounds emits MAP_FIT_TO_BOUNDS with bbox', () => {
     const bbox = [-0.489, 51.28, 0.236, 51.686]
     map.fitToBounds(bbox)
-    expect(map.eventBus.emit).toHaveBeenCalledWith('map:fittobounds', bbox)
+    expect(map.eventBus.emitWhenReady).toHaveBeenCalledWith('map:fittobounds', bbox)
   })
 
   it('setView emits MAP_SET_VIEW with opts', () => {
     const opts = { center: [-0.1276, 51.5074], zoom: 12 }
     map.setView(opts)
-    expect(map.eventBus.emit).toHaveBeenCalledWith('map:setview', opts)
+    expect(map.eventBus.emitWhenReady).toHaveBeenCalledWith('map:setview', opts)
   })
 })

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/services/eventBus.js

@@ -1,16 +1,43 @@
 class EventBus {
   constructor () {
     this.events = {}
+    this._queued = {}
   }
 
+  /**
+   * Register a handler for an event. If a value was queued via `emitWhenReady`
+   * before any listeners existed, the handler is called immediately with that
+   * value and the queue is cleared.
+   *
+   * @param {string} eventName
+   * @param {Function} handler
+   * @returns {this}
+   */
   on (eventName, handler) {
     if (!this.events[eventName]) {
       this.events[eventName] = []
     }
     this.events[eventName].push(handler)
+
+    if (this._queued[eventName] !== undefined) {
+      try {
+        handler(...this._queued[eventName])
+      } catch (error) {
+        console.error(`Error in event handler for '${eventName}':`, error)
+      }
+      delete this._queued[eventName]
+    }
+
     return this
   }
 
+  /**
+   * Remove a handler for an event. Omit `handler` to remove all handlers.
+   *
+   * @param {string} eventName
+   * @param {Function} [handler]
+   * @returns {this}
+   */
   off (eventName, handler) {
     if (!this.events[eventName]) {
       return this
@@ -23,6 +50,13 @@ class EventBus {
     return this
   }
 
+  /**
+   * Emit an event, calling all registered handlers synchronously.
+   *
+   * @param {string} eventName
+   * @param {...*} args
+   * @returns {this}
+   */
   emit (eventName, ...args) {
     if (!this.events[eventName]) {
       return this
@@ -38,13 +72,40 @@ class EventBus {
     return this
   }
 
+  /**
+   * Like `emit`, but queues the args if no listeners are registered yet.
+   * The first listener to subscribe will receive the queued value immediately,
+   * after which the queue is cleared. Subsequent `emitWhenReady` calls for the
+   * same event before a listener arrives replace the queued value.
+   *
+   * Use this for events that may be emitted before the listener side is ready
+   * (e.g. called from `map:ready` before React effects have run).
+   *
+   * @param {string} eventName
+   * @param {...*} args
+   * @returns {this}
+   */
+  emitWhenReady (eventName, ...args) {
+    if (!this.events[eventName] || this.events[eventName].length === 0) {
+      this._queued[eventName] = args
+      return this
+    }
+    return this.emit(eventName, ...args)
+  }
+
+  /**
+   * Remove all handlers and clear any queued events.
+   */
   destroy () {
     this.events = {}
+    this._queued = {}
   }
 }
 
 /**
  * Factory for map-local EventBus
+ *
+ * @returns {EventBus}
  */
 export function createEventBus () {
   return new EventBus()