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

package/src/services/eventBus.test.js

@@ -94,6 +94,76 @@ describe('EventBus singleton', () => {
   })
 })
 
+describe('emitWhenReady', () => {
+  beforeEach(() => {
+    eventBus.destroy()
+  })
+
+  it('fires immediately when listeners are already registered', () => {
+    const handler = jest.fn()
+    eventBus.on('ready', handler)
+
+    eventBus.emitWhenReady('ready', 'value')
+
+    expect(handler).toHaveBeenCalledWith('value')
+  })
+
+  it('queues the call and replays to the first subscriber when no listeners exist', () => {
+    const handler = jest.fn()
+
+    eventBus.emitWhenReady('ready', 'value')
+    expect(handler).not.toHaveBeenCalled()
+
+    eventBus.on('ready', handler)
+    expect(handler).toHaveBeenCalledWith('value')
+  })
+
+  it('clears the queue after replaying so subsequent subscribers do not receive it', () => {
+    const first = jest.fn()
+    const second = jest.fn()
+
+    eventBus.emitWhenReady('ready', 'value')
+    eventBus.on('ready', first)
+    eventBus.on('ready', second)
+
+    expect(first).toHaveBeenCalledWith('value')
+    expect(second).not.toHaveBeenCalled()
+  })
+
+  it('replaces a queued value if emitWhenReady is called again before a subscriber arrives', () => {
+    const handler = jest.fn()
+
+    eventBus.emitWhenReady('ready', 'first')
+    eventBus.emitWhenReady('ready', 'second')
+    eventBus.on('ready', handler)
+
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(handler).toHaveBeenCalledWith('second')
+  })
+
+  it('catches and logs errors thrown by a handler during queued replay', () => {
+    const error = new Error('boom')
+    const handler = jest.fn(() => { throw error })
+    jest.spyOn(console, 'error').mockImplementation(() => {})
+
+    eventBus.emitWhenReady('ready', 'value')
+    eventBus.on('ready', handler)
+
+    expect(console.error).toHaveBeenCalledWith("Error in event handler for 'ready':", error)
+    console.error.mockRestore()
+  })
+
+  it('clears queued events on destroy', () => {
+    const handler = jest.fn()
+
+    eventBus.emitWhenReady('ready', 'value')
+    eventBus.destroy()
+    eventBus.on('ready', handler)
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+})
+
 describe('createEventBus factory', () => {
   /**
    * Test to ensure coverage for the factory function (Line 50).

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 {

package/src/utils/mapStateSync.test.js

@@ -33,11 +33,10 @@ describe('mapStateSync utilities', () => {
   })
 
   describe('setMapStateInURL', () => {
-    it('preserves history state and filters params (Line 28)', () => {
+    it('writes center and zoom into the URL', () => {
       const mockHref = 'http://test.com/path?existing=true'
       setMapStateInURL('map1', { center: [10, 20], zoom: 5 }, mockHref)
 
-      // Verification of Line 28: First arg must be global history state
       expect(globalThis.history.replaceState).toHaveBeenCalledWith(
         globalThis.history.state,
         '',
@@ -45,21 +44,42 @@ describe('mapStateSync utilities', () => {
       )
     })
 
-    it('uses fallback localhost URL (Line 17)', () => {
+    it('replaces existing map params when already present in the URL', () => {
+      setMapStateInURL('map1', { center: [10, 20], zoom: 5 }, 'http://test.com?map1:center=1,2&map1:zoom=3')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toContain('map1:center=10,20')
+      expect(url).toContain('map1:zoom=5')
+      expect(url).not.toContain('map1:center=1,2')
+    })
+
+    it('preserves unrelated existing params (e.g. mv)', () => {
+      setMapStateInURL('map1', { center: [10, 20], zoom: 5 }, 'http://test.com/path?mv=map1')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toContain('mv=map1')
+      expect(url).toContain('map1:center=10,20')
+    })
+
+    it('uses fallback localhost URL when href is null', () => {
       setMapStateInURL('map1', { zoom: 10 }, null)
-      const lastCall = globalThis.history.replaceState.mock.calls[0][2]
-      expect(lastCall).toContain('http://localhost')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toContain('http://localhost')
     })
 
-    it('handles state where zoom is nullish (Line 24)', () => {
+    it('omits zoom when zoom is null', () => {
       setMapStateInURL('map1', { center: [0, 0], zoom: null }, 'http://test.com')
-      const lastCall = globalThis.history.replaceState.mock.calls[0][2]
-      expect(lastCall).not.toContain('zoom')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).not.toContain('zoom')
     })
 
-    it('triggers the default href parameter', () => {
+    it('uses window.location.href when no href is provided', () => {
       setMapStateInURL('map1', { zoom: 10 })
       expect(globalThis.history.replaceState).toHaveBeenCalled()
     })
+
+    it('produces a URL with no search string when state is empty and no existing params', () => {
+      setMapStateInURL('map1', {}, 'http://test.com/path')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toBe('http://test.com/path')
+    })
   })
 })

package/assets/css/docusaurus.css

@@ -1,104 +0,0 @@
-/* Custom styles for the Interactive Map docs site */
-
-.app-section {
-  padding: 40px 0;
-}
-
-.govuk-template__body.app-homepage .govuk-template__body-inner {
-  background-color: #f4f8fb;
-}
-
-.app-section {
-  background-color: #ffffff;
-}
-
-.app-section--features {
-  background-color: #f4f8fb;
-  border-bottom: 1px solid #8eb8dc;
-}
-
-.app-prose-scope .app-section--features p:not(.app-no-prose *) {
-  margin-bottom: 0;
-}
-
-.app-section--features .govuk-grid-column-one-third:not(:first-child) {
-  margin-top: 30px;
-
-  @media (min-width: 48.125em) {
-    margin-top: 0;
-  }
-}
-
-/* Hero image */
-.govuk-template--rebranded .app-masthead .govuk-grid-row {
-  @media (min-width: 48.125em) {
-    display: flex;
-  }
-}
-
-.govuk-template--rebranded .app-masthead .govuk-grid-column-one-third-from-desktop {
-  @media (min-width: 48.125em) {
-    background-image: url('/images/hero.png');
-    background-repeat: no-repeat;
-    background-position: center bottom;
-    background-size: 200px;
-  }
-}
-
-/* Black */
-/* .govuk-template--rebranded .govuk-service-navigation:not(.govuk-service-navigation--inverse) .govuk-service-navigation__list__link,
-.govuk-template--rebranded .govuk-service-navigation:not(.govuk-service-navigation--inverse) .govuk-service-navigation__toggle {
-  color: #0b0c0c !important;
-}
-
-.govuk-template--rebranded .govuk-service-navigation:not(.govuk-service-navigation--inverse) .govuk-service-navigation__list__item--active {
-  border-color: #0b0c0c !important;
-} */
-
-/* Color 100% */
-.govuk-template--rebranded .app-masthead .govuk-button--inverse,
-.govuk-template--rebranded .app-masthead .govuk-button--inverse:visited,
-.govuk-template--rebranded .app-masthead .govuk-button--inverse:active,
-.govuk-template--rebranded .app-masthead .govuk-button--inverse:hover {
-  color: #008531;
-}
-
-/* Background colour 100% */
-.govuk-template--rebranded .govuk-header__link--homepage:not(:focus),
-.govuk-template--rebranded .govuk-header,
-.govuk-template--rebranded .govuk-service-navigation.govuk-service-navigation--inverse,
-.govuk-template--rebranded .app-masthead {
-  background-color: #008531 !important;
-}
-
-/* Box shadow colur #083d29 */
-.govuk-template--rebranded .app-masthead .govuk-button--inverse {
-  box-shadow: 0 2px 0 #0b5c3e;
-}
-
-/* Background colour 4% tint */
-/* .govuk-template--rebranded .app-homepage .app-section.app-section--features,
-.govuk-template--rebranded .govuk-template__body.app-homepage .govuk-template__body-inner,
-.govuk-template--rebranded .govuk-service-navigation,
-.govuk-template--rebranded .govuk-footer {
-  background-color: #f5faf7 !important;
-} */
-
-/* Border colour 100% */
-/* .govuk-template--rebranded .govuk-footer {
-  border-color: #008531 !important;
-} */
-
-/* Border colour 30% tint */
-/* .govuk-template--rebranded .app-homepage .app-section.app-section--features,
-.govuk-template--rebranded .govuk-service-navigation {
-  border-color: #b3dac1 !important;
-} */
-
-/* Border colour 50% tint */
-.govuk-template--rebranded .app-homepage .govuk-service-navigation--inverse .govuk-width-container {
-  border-color: #66B683 !important;
-}
-
-
-/* #8eb8dc */

package/docs/examples.mdx

@@ -1,70 +0,0 @@
-import DemoMapInline from '../demo/DemoMapInline.js'
-import DemoMapButton from '../demo/DemoMapButton.js'
-
-# Examples
-
-See [Getting started](getting-started) for installation and full configuration options.
-
-## Inline map
-
-Embed an interactive map directly on the page, allowing users to explore and interact with the map without leaving the current context.
-
-<DemoMapInline />
-
-```js
-import InteractiveMap from '@defra/interactive-map'
-import maplibreProvider from '@defra/interactive-map/providers/maplibre'
-import searchPlugin from '@defra/interactive-map/plugins/search'
-import scaleBarPlugin from '@defra/interactive-map/plugins/scale-bar'
-import mapStylesPlugin from '@defra/interactive-map/plugins/map-styles'
-
-new InteractiveMap('my-map', {
-  behaviour: 'inline',
-  mapProvider: maplibreProvider(),
-  mapStyle: {
-    url: '/assets/my-map-style.json',
-    attribution: '© OpenStreetMap contributors'
-  },
-  center: [-1.6, 53.1],
-  zoom: 6,
-  containerHeight: '500px',
-  enableZoomControls: true,
-  plugins: [
-    searchPlugin({ customDatasets: [nominatimDataset], showMarker: true }),
-    scaleBarPlugin({ units: 'metric' }),
-    mapStylesPlugin({ mapStyles: [...] })
-  ]
-})
-```
-
-## Button-triggered map
-
-Trigger the map to show on button press, allowing users to access the map when needed without it taking up space on the page by default.
-
-<DemoMapButton />
-
-```js
-import InteractiveMap from '@defra/interactive-map'
-import maplibreProvider from '@defra/interactive-map/providers/maplibre'
-import searchPlugin from '@defra/interactive-map/plugins/search'
-import scaleBarPlugin from '@defra/interactive-map/plugins/scale-bar'
-import mapStylesPlugin from '@defra/interactive-map/plugins/map-styles'
-
-new InteractiveMap('my-map', {
-  behaviour: 'buttonFirst',
-  mapProvider: maplibreProvider(),
-  mapStyle: {
-    url: '/assets/my-map-style.json',
-    attribution: '© OpenStreetMap contributors'
-  },
-  center: [-1.6, 53.1],
-  zoom: 6,
-  containerHeight: '500px',
-  enableZoomControls: true,
-  plugins: [
-    searchPlugin({ customDatasets: [nominatimDataset], showMarker: true }),
-    scaleBarPlugin({ units: 'metric' }),
-    mapStylesPlugin({ mapStyles: [...] })
-  ]
-})
-```