@defra/interactive-map 0.0.3-alpha → 0.0.5-alpha

package/src/App/store/mapActionsMap.js

@@ -1,3 +1,12 @@
+/**
+ * Generic reducer action that shallow-merges the payload into state.
+ * Shared by MAP_MOVE, MAP_MOVE_END and MAP_FIRST_IDLE.
+ */
+const mergePayload = (state, payload) => ({
+  ...state,
+  ...payload
+})
+
 const setMapReady = (state) => {
   return {
     ...state,
@@ -5,27 +14,6 @@ const setMapReady = (state) => {
   }
 }
 
-const mapMove = (state, payload) => {
-  return {
-    ...state,
-    ...payload
-  }
-}
-
-const mapMoveEnd = (state, payload) => {
-  return {
-    ...state,
-    ...payload
-  }
-}
-
-const mapFirstIdle = (state, payload) => {
-  return {
-    ...state,
-    ...payload
-  }
-}
-
 const setMapStyle = (state, payload) => {
   return {
     ...state,
@@ -78,9 +66,9 @@ const removeMarker = (state, payload) => {
 
 export const actionsMap = {
   SET_MAP_READY: setMapReady,
-  MAP_MOVE: mapMove,
-  MAP_MOVE_END: mapMoveEnd,
-  MAP_FIRST_IDLE: mapFirstIdle,
+  MAP_MOVE: mergePayload,
+  MAP_MOVE_END: mergePayload,
+  MAP_FIRST_IDLE: mergePayload,
   SET_MAP_STYLE: setMapStyle,
   SET_MAP_SIZE: setMapSize,
   UPDATE_CROSS_HAIR: updateCrossHair,

package/src/App/store/mapReducer.js

@@ -19,7 +19,7 @@ export const initialState = (config) => {
 
   return {
     isMapReady: false,
-    mapStyle: !pluginHandlesMapStyles ? mapStyle : null,
+    mapStyle: pluginHandlesMapStyles ? null : mapStyle,
     mapSize,
     center,
     zoom,

package/src/InteractiveMap/InteractiveMap.js

@@ -1,5 +1,16 @@
 // src/InteractiveMap/InteractiveMap.js
+
+/**
+ * @typedef {import('../types.js').ButtonDefinition} ButtonDefinition
+ * @typedef {import('../types.js').ControlDefinition} ControlDefinition
+ * @typedef {import('../types.js').InteractiveMapConfig} InteractiveMapConfig
+ * @typedef {import('../types.js').MarkerOptions} MarkerOptions
+ * @typedef {import('../types.js').PanelDefinition} PanelDefinition
+ */
+
 import '../scss/main.scss'
+// Polyfills to ensure entry point works on all devices
+import './polyfills.js'
 import historyManager from './historyManager.js'
 import { parseDataProperties } from './parseDataProperties.js'
 import { checkDeviceSupport } from './deviceChecker.js'
@@ -13,14 +24,26 @@ import { createInterfaceDetector, getInterfaceType } from '../utils/detectInterf
 import { createReverseGeocode } from '../services/reverseGeocode.js'
 import { EVENTS as events } from '../config/events.js'
 import { createEventBus } from '../services/eventBus.js'
+import { toggleInertElements } from '../utils/toggleInertElements.js'
 
+/**
+ * Main entry point for the Interactive Map component.
+ * Handles initialization, lifecycle, and public API methods.
+ */
 export default class InteractiveMap {
   _openButton = null
   _root = null // keep react root internally
   _breakpointDetector = null
   _interfaceDetectorCleanup = null
   _hybridBehaviourCleanup = null
-
+  _isHidden = false // tracks if map is hidden but preserved (hybrid mode)
+
+  /**
+   * Create a new InteractiveMap instance.
+   *
+   * @param {string} id - The DOM element ID to mount the map into.
+   * @param {Partial<InteractiveMapConfig>} [props={}] - Configuration options.
+   */
   constructor (id, props = {}) {
     this.id = id
     this.rootEl = document.getElementById(id)
@@ -62,7 +85,6 @@ export default class InteractiveMap {
     })
   }
 
-  // Private methods
   _initialize () {
     if (['buttonFirst', 'hybrid'].includes(this.config.behaviour)) {
       this._openButton = createButton(this.config, this.rootEl, (e) => {
@@ -80,20 +102,48 @@ export default class InteractiveMap {
   }
 
   _handleButtonClick (e) {
-    this.loadApp()
     history.pushState({ isBack: true }, '', e.currentTarget.getAttribute('href'))
+    if (this._isHidden) {
+      this.showApp()
+    } else {
+      this.loadApp()
+    }
+  }
+
+  _removeMapParamFromUrl (href, key) {
+    const regex = new RegExp(`[?&]${key}=[^&]*(&|$)`)
+
+    if (!regex.test(href)) {
+      return href
+    }
+
+    return href
+      .replace(regex, (_, p1) => {
+        return p1 === '&' ? '?' : ''
+      })
+      .replace(/\?$/, '')
   }
 
   _handleExitClick () {
-    this.removeApp()
-    // Remove the map param from the URL using regex to prevent encoding
+    if (this.config.preserveStateOnClose) {
+      this.hideApp()
+    } else {
+      this.removeApp()
+    }
+
     const key = this.config.mapViewParamKey
     const href = location.href
-    const newUrl = href.replace(new RegExp(`[?&]${key}=[^&]*(&|$)`), (_, p1) => (p1 === '&' ? '?' : '')).replace(/\?$/, '')
+    const newUrl = this._removeMapParamFromUrl(href, key)
+
     history.replaceState(history.state, '', newUrl)
   }
 
-  // Public methods
+  /**
+   * Load and initialize the map application.
+   *
+   * @internal Not intended for end-user use.
+   * @returns {Promise<void>}
+   */
   async loadApp () {
     if (this._openButton) {
       this._openButton.style.display = 'none'
@@ -130,10 +180,10 @@ export default class InteractiveMap {
       delete appInstance._root
 
       // Only assign properties but don't eventBus methods
-      const protectedKeys = ['on', 'off', 'emit']
+      const protectedKeys = new Set(['on', 'off', 'emit'])
 
       Object.keys(appInstance).forEach(key => {
-        if (!protectedKeys.includes(key)) {
+        if (!protectedKeys.has(key)) {
           this[key] = appInstance[key]
         }
       })
@@ -146,6 +196,11 @@ export default class InteractiveMap {
     }
   }
 
+  /**
+   * Remove the map application and restore the initial state.
+   *
+   * @internal Not intended for end-user use.
+   */
   removeApp () {
     if (this._root && typeof this.unmount === 'function') {
       this.unmount()
@@ -162,6 +217,57 @@ export default class InteractiveMap {
     this.eventBus.emit(events.MAP_DESTROY, { mapId: this.id })
   }
 
+  /**
+   * Hide the map application without destroying it (preserves state).
+   * Used in hybrid mode when resizing below breakpoint.
+   *
+   * @internal Not intended for end-user use.
+   */
+  hideApp () {
+    this._isHidden = true
+    this.rootEl.style.display = 'none'
+
+    // Restore inert elements before focusing button
+    toggleInertElements({ containerEl: this.rootEl, isFullscreen: false })
+
+    if (this._openButton) {
+      this._openButton.removeAttribute('style')
+      this._openButton.focus()
+    }
+
+    // Remove fullscreen classes
+    document.documentElement.classList.remove('im-is-fullscreen')
+    this.rootEl.classList.remove('im-is-fullscreen')
+
+    // Reset page title (remove prepended map title)
+    const parts = document.title.split(': ')
+    if (parts.length > 1) {
+      document.title = parts[parts.length - 1]
+    }
+  }
+
+  /**
+   * Show a previously hidden map application.
+   * Used in hybrid mode when resizing above breakpoint or clicking button.
+   *
+   * @internal Not intended for end-user use.
+   */
+  showApp () {
+    this._isHidden = false
+    this.rootEl.style.display = ''
+
+    if (this._openButton) {
+      this._openButton.style.display = 'none'
+    }
+
+    updateDOMState(this)
+  }
+
+  /**
+   * Destroy the map instance and clean up all resources.
+   *
+   * @internal Not intended for end-user use.
+   */
   destroy () {
     this.removeApp()
     this._breakpointDetector?.destroy()
@@ -171,54 +277,129 @@ export default class InteractiveMap {
     this.eventBus.destroy()
   }
 
-  // API - EventBus methods
+  /**
+   * Subscribe to an event.
+   *
+   * @param {string} event - Event name.
+   * @param {Function} callback - Event handler.
+   */
   on (...args) {
     this.eventBus.on(...args)
   }
 
+  /**
+   * Unsubscribe from an event.
+   *
+   * @param {string} event - Event name.
+   * @param {Function} callback - Event handler to remove.
+   */
   off (...args) {
     this.eventBus.off(...args)
   }
 
+  /**
+   * Emit an event.
+   *
+   * @param {string} event - Event name.
+   * @param {any} [data] - Event data.
+   */
   emit (...args) {
     this.eventBus.emit(...args)
   }
 
-  // API - location markers
+  /**
+   * Add a marker to the map.
+   *
+   * @param {string} id - Unique marker identifier.
+   * @param {[number, number]} coords - Coordinates [lng, lat] or [easting, northing] depending on crs.
+   * @param {MarkerOptions} [options] - Optional marker appearance options.
+   */
   addMarker (id, coords, options) {
     this.eventBus.emit(events.APP_ADD_MARKER, { id, coords, options })
   }
 
+  /**
+   * Remove a marker from the map.
+   *
+   * @param {string} id - Marker identifier to remove.
+   */
   removeMarker (id) {
     this.eventBus.emit(events.APP_REMOVE_MARKER, id)
   }
 
-  // API - change app mode
+  /**
+   * Set the application mode.
+   *
+   * @param {string} mode - Mode identifier.
+   */
   setMode (mode) {
     this.eventBus.emit(events.APP_SET_MODE, mode)
   }
 
-  // Interface API add button/panel/control, remove panel
+  /**
+   * Add a button to the UI.
+   *
+   * @param {string} id - Unique button identifier.
+   * @param {ButtonDefinition} config - Button configuration.
+   */
   addButton (id, config) {
     this.eventBus.emit(events.APP_ADD_BUTTON, { id, config })
   }
 
+  /**
+   * Set or toggle a button state.
+   *
+   * @param {string} id - Button identifier.
+   * @param {'hidden'|'pressed'|'disabled'} prop - The button state to change.
+   * @param {boolean} [value] - Optional boolean. If provided, sets state explicitly; otherwise toggles.
+   */
+  toggleButtonState (id, prop, value) {
+    this.eventBus.emit(events.APP_TOGGLE_BUTTON_STATE, { id, prop, value })
+  }
+
+  /**
+   * Add a panel to the UI.
+   *
+   * @param {string} id - Unique panel identifier.
+   * @param {PanelDefinition} config - Panel configuration.
+   */
   addPanel (id, config) {
     this.eventBus.emit(events.APP_ADD_PANEL, { id, config })
   }
 
+  /**
+   * Remove a panel from the UI.
+   *
+   * @param {string} id - Panel identifier to remove.
+   */
   removePanel (id) {
     this.eventBus.emit(events.APP_REMOVE_PANEL, id)
   }
 
+  /**
+   * Show a panel.
+   *
+   * @param {string} id - Panel identifier to show.
+   */
   showPanel (id) {
     this.eventBus.emit(events.APP_SHOW_PANEL, id)
   }
 
+  /**
+   * Hide a panel.
+   *
+   * @param {string} id - Panel identifier to hide.
+   */
   hidePanel (id) {
     this.eventBus.emit(events.APP_HIDE_PANEL, id)
   }
 
+  /**
+   * Add a custom control to the UI.
+   *
+   * @param {string} id - Unique control identifier.
+   * @param {ControlDefinition} config - Control configuration.
+   */
   addControl (id, config) {
     this.eventBus.emit(events.APP_ADD_CONTROL, { id, config })
   }

package/src/InteractiveMap/InteractiveMap.test.js

@@ -268,20 +268,23 @@ describe('InteractiveMap Core Functionality', () => {
     expect(() => map.destroy()).not.toThrow()
   })
 
-  it('_handleExitClick removes app and calls replaceState', () => {
+  it('_handleExitClick removes app when preserveStateOnClose is false', () => {
     const replaceStateSpy = jest.spyOn(history, 'replaceState').mockImplementation(() => {})
 
     const map = new InteractiveMap('map', {
       behaviour: 'buttonFirst',
       mapProvider: mapProviderMock,
-      mapViewParamKey: 'mv'
+      mapViewParamKey: 'mv',
+      preserveStateOnClose: false
     })
 
     const removeAppSpy = jest.spyOn(map, 'removeApp').mockImplementation(() => {})
+    const hideAppSpy = jest.spyOn(map, 'hideApp').mockImplementation(() => {})
 
     map._handleExitClick()
 
     expect(removeAppSpy).toHaveBeenCalled()
+    expect(hideAppSpy).not.toHaveBeenCalled()
     expect(replaceStateSpy).toHaveBeenCalledWith(
       history.state,
       '',
@@ -289,8 +292,158 @@ describe('InteractiveMap Core Functionality', () => {
     )
 
     removeAppSpy.mockRestore()
+    hideAppSpy.mockRestore()
     replaceStateSpy.mockRestore()
   })
+
+  it('_handleExitClick hides app when preserveStateOnClose is true', () => {
+    const replaceStateSpy = jest.spyOn(history, 'replaceState').mockImplementation(() => {})
+
+    const map = new InteractiveMap('map', {
+      behaviour: 'buttonFirst',
+      mapProvider: mapProviderMock,
+      mapViewParamKey: 'mv',
+      preserveStateOnClose: true
+    })
+
+    const removeAppSpy = jest.spyOn(map, 'removeApp').mockImplementation(() => {})
+    const hideAppSpy = jest.spyOn(map, 'hideApp').mockImplementation(() => {})
+
+    map._handleExitClick()
+
+    expect(hideAppSpy).toHaveBeenCalled()
+    expect(removeAppSpy).not.toHaveBeenCalled()
+    expect(replaceStateSpy).toHaveBeenCalled()
+
+    removeAppSpy.mockRestore()
+    hideAppSpy.mockRestore()
+    replaceStateSpy.mockRestore()
+  })
+
+  it('_handleButtonClick calls showApp when map is hidden', async () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    map._isHidden = true
+    const showAppSpy = jest.spyOn(map, 'showApp').mockImplementation(() => {})
+    const loadAppSpy = jest.spyOn(map, 'loadApp').mockResolvedValue()
+    const pushStateSpy = jest.spyOn(history, 'pushState').mockImplementation(() => {})
+    const fakeEvent = { currentTarget: { getAttribute: jest.fn().mockReturnValue('/?mv=map') } }
+
+    await openButtonCallback(fakeEvent)
+
+    expect(showAppSpy).toHaveBeenCalled()
+    expect(loadAppSpy).not.toHaveBeenCalled()
+    expect(pushStateSpy).toHaveBeenCalled()
+
+    showAppSpy.mockRestore()
+    loadAppSpy.mockRestore()
+    pushStateSpy.mockRestore()
+  })
+
+  it('hideApp sets _isHidden and hides element', () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    map._openButton = mockButtonInstance
+
+    map.hideApp()
+
+    expect(map._isHidden).toBe(true)
+    expect(map.rootEl.style.display).toBe('none')
+    expect(mockButtonInstance.removeAttribute).toHaveBeenCalledWith('style')
+    expect(mockButtonInstance.focus).toHaveBeenCalled()
+  })
+
+  it('hideApp restores document title when it contains a map prefix', () => {
+    document.title = 'Map View: Original Page Title'
+
+    const map = new InteractiveMap('map', {
+      behaviour: 'buttonFirst',
+      mapProvider: mapProviderMock
+    })
+
+    map._openButton = mockButtonInstance
+    map.hideApp()
+
+    expect(document.title).toBe('Original Page Title')
+  })
+
+  it('hideApp works when _openButton is null', () => {
+    const map = new InteractiveMap('map', {
+      behaviour: 'buttonFirst',
+      mapProvider: mapProviderMock
+    })
+
+    map._openButton = null
+    map.hideApp()
+
+    expect(map._isHidden).toBe(true)
+    expect(map.rootEl.style.display).toBe('none')
+  })
+
+  it('showApp sets _isHidden false and shows element', () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    map._isHidden = true
+    map._openButton = mockButtonInstance
+    map.rootEl.style.display = 'none'
+
+    map.showApp()
+
+    expect(map._isHidden).toBe(false)
+    expect(map.rootEl.style.display).toBe('')
+    expect(mockButtonInstance.style.display).toBe('none')
+    expect(updateDOMState).toHaveBeenCalledWith(map)
+  })
+
+  it('showApp works when _openButton is null', () => {
+    const map = new InteractiveMap('map', {
+      behaviour: 'buttonFirst',
+      mapProvider: mapProviderMock
+    })
+
+    map._isHidden = true
+    map._openButton = null
+    map.rootEl.style.display = 'none'
+
+    map.showApp()
+
+    expect(map._isHidden).toBe(false)
+    expect(map.rootEl.style.display).toBe('')
+    expect(updateDOMState).toHaveBeenCalledWith(map)
+  })
+})
+
+describe('_removeMapParamFromUrl', () => {
+  let map
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="map"></div>'
+    map = new InteractiveMap('map', {
+      mapProvider: { load: jest.fn() },
+      mapViewParamKey: 'mv'
+    })
+  })
+
+  it('removes param when followed by another param (& branch)', () => {
+    const href = 'https://example.com/page?mv=map&foo=1'
+    const result = map._removeMapParamFromUrl(href, 'mv')
+    expect(result).toBe('https://example.com/page?foo=1')
+  })
+
+  it('removes param when it is the last param (end-of-string branch)', () => {
+    const href = 'https://example.com/page?foo=1&mv=map'
+    const result = map._removeMapParamFromUrl(href, 'mv')
+    expect(result).toBe('https://example.com/page?foo=1')
+  })
+
+  it('removes lone param and trailing ?', () => {
+    const href = 'https://example.com/page?mv=map'
+    const result = map._removeMapParamFromUrl(href, 'mv')
+    expect(result).toBe('https://example.com/page')
+  })
+
+  it('returns href unchanged when param does not exist (no-match branch)', () => {
+    const href = 'https://example.com/page?foo=1'
+    const result = map._removeMapParamFromUrl(href, 'mv')
+    expect(result).toBe(href)
+  })
 })
 
 describe('InteractiveMap Public API Methods', () => {
@@ -347,4 +500,13 @@ describe('InteractiveMap Public API Methods', () => {
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', 'panel2')
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:hidepanel', 'panel3')
   })
+
+  it('delegates toggleButtonState correctly', () => {
+    map.toggleButtonState('btn-1', 'disabled', true)
+
+    expect(map.eventBus.emit).toHaveBeenCalledWith(
+      'app:togglebuttonstate',
+      { id: 'btn-1', prop: 'disabled', value: true }
+    )
+  })
 })

package/src/InteractiveMap/behaviourController.js

@@ -1,5 +1,6 @@
 import { getQueryParam } from '../utils/queryString.js'
 import { isHybridFullscreen } from '../utils/getIsFullscreen.js'
+import { updateDOMState } from './domStateManager.js'
 import defaults from '../config/defaults.js'
 
 // -----------------------------------------------------------------------------
@@ -56,9 +57,18 @@ function setupBehavior (mapInstance) {
 
     const handleChange = () => {
       if (shouldLoadComponent(mapInstance.config)) {
-        mapInstance.loadApp()
+        if (mapInstance._isHidden) {
+          mapInstance.showApp()
+        } else if (mapInstance._root == null) {
+          mapInstance.loadApp()
+        } else {
+          // Map is showing - update DOM state for fullscreen/inline transition
+          updateDOMState(mapInstance)
+        }
+      } else if (mapInstance._root) {
+        mapInstance.hideApp()
       } else {
-        mapInstance.removeApp()
+        // No action
       }
     }