@defra/interactive-map 0.0.4-alpha → 0.0.6-alpha

package/src/InteractiveMap/historyManager.test.js

@@ -13,19 +13,25 @@ describe('historyManager', () => {
   beforeEach(() => {
     component1 = {
       id: 'map',
-      config: { behaviour: 'buttonFirst', hybridWidth: null, maxMobileWidth: 640 },
+      config: { behaviour: 'buttonFirst', hybridWidth: null, maxMobileWidth: 640, preserveStateOnClose: false },
       rootEl: document.createElement('div'),
       loadApp: jest.fn(),
       removeApp: jest.fn(),
-      openButton: { focus: jest.fn() }
+      hideApp: jest.fn(),
+      showApp: jest.fn(),
+      openButton: { focus: jest.fn() },
+      _isHidden: false
     }
     component2 = {
       id: 'list',
-      config: { behaviour: 'hybrid', hybridWidth: null, maxMobileWidth: 640 },
+      config: { behaviour: 'hybrid', hybridWidth: null, maxMobileWidth: 640, preserveStateOnClose: false },
       rootEl: document.createElement('div'),
       loadApp: jest.fn(),
       removeApp: jest.fn(),
-      openButton: { focus: jest.fn() }
+      hideApp: jest.fn(),
+      showApp: jest.fn(),
+      openButton: { focus: jest.fn() },
+      _isHidden: false
     }
     popstateEvent = new PopStateEvent('popstate')
     jest.clearAllMocks()
@@ -63,7 +69,8 @@ describe('historyManager', () => {
     expect(component1.loadApp).not.toHaveBeenCalled()
   })
 
-  it('removes component and focuses button when view param does not match', () => {
+  it('removes component when view param does not match and preserveStateOnClose is false', () => {
+    component1.config.preserveStateOnClose = false
     component1.rootEl.appendChild(document.createElement('div'))
     historyManager.register(component1)
     queryString.getQueryParam.mockReturnValue(null)
@@ -71,7 +78,19 @@ describe('historyManager', () => {
     window.dispatchEvent(popstateEvent)
 
     expect(component1.removeApp).toHaveBeenCalled()
-    expect(component1.openButton.focus).toHaveBeenCalled()
+    expect(component1.hideApp).not.toHaveBeenCalled()
+  })
+
+  it('hides component when view param does not match and preserveStateOnClose is true', () => {
+    component1.config.preserveStateOnClose = true
+    component1.rootEl.appendChild(document.createElement('div'))
+    historyManager.register(component1)
+    queryString.getQueryParam.mockReturnValue(null)
+
+    window.dispatchEvent(popstateEvent)
+
+    expect(component1.hideApp).toHaveBeenCalled()
+    expect(component1.removeApp).not.toHaveBeenCalled()
   })
 
   it('does not remove hybrid component when viewport is wide (inline mode)', () => {
@@ -87,6 +106,7 @@ describe('historyManager', () => {
   })
 
   it('removes hybrid component when viewport is narrow and view does not match', () => {
+    component2.config.preserveStateOnClose = false
     component2.rootEl.appendChild(document.createElement('div'))
     historyManager.register(component2)
     queryString.getQueryParam.mockReturnValue(null)
@@ -98,6 +118,17 @@ describe('historyManager', () => {
     expect(component2.removeApp).toHaveBeenCalled()
   })
 
+  it('calls showApp when view param matches and component is hidden', () => {
+    component1._isHidden = true
+    historyManager.register(component1)
+    queryString.getQueryParam.mockReturnValue('map')
+
+    window.dispatchEvent(popstateEvent)
+
+    expect(component1.showApp).toHaveBeenCalled()
+    expect(component1.loadApp).not.toHaveBeenCalled()
+  })
+
   it('uses hybridWidth for media query when provided', () => {
     component2.config.hybridWidth = 768
     component2.rootEl.appendChild(document.createElement('div'))

package/src/InteractiveMap/polyfills.js

@@ -0,0 +1,39 @@
+// crypto.randomUUID
+if (typeof crypto !== 'undefined' && !crypto.randomUUID) {
+  let last = 0
+  crypto.randomUUID = () => {
+    last = Math.max(Date.now(), last + 1)
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c, i) => {
+      const v = i < 12 ? Number.parseInt(last.toString(16).padStart(12, '0')[i], 16) : Math.random() * 16 | 0 // NOSONAR
+      return (c === 'x' ? v : (v & 0x3 | 0x8)).toString(16)
+    })
+  }
+}
+
+// AbortSignal.throwIfAborted
+const needsThrowIfAborted = typeof AbortController !== 'undefined' &&
+  !Object.getPrototypeOf(new AbortController().signal).throwIfAborted
+
+if (needsThrowIfAborted) {
+  const signalProto = Object.getPrototypeOf(new AbortController().signal)
+  signalProto.throwIfAborted = function () {
+    if (this.aborted) {
+      const err = new Error('The operation was aborted.')
+      err.name = 'AbortError'
+      throw err
+    }
+  }
+}
+
+// Inject polyfill into web workers created from blob URLs (e.g. MapLibre GL)
+// Workers have their own global scope so main thread polyfills don't apply
+if (needsThrowIfAborted && typeof URL !== 'undefined' && URL.createObjectURL) {
+  const _createObjectURL = URL.createObjectURL.bind(URL)
+  URL.createObjectURL = (blob) => {
+    if (blob instanceof Blob && blob.type === 'text/javascript') {
+      const p = 'if(typeof AbortController!=="undefined"){var _p=Object.getPrototypeOf(new AbortController().signal);if(!_p.throwIfAborted){_p.throwIfAborted=function(){if(this.aborted){var e=new Error("The operation was aborted.");e.name="AbortError";throw e}}}}\n'
+      blob = new Blob([p, blob], { type: 'text/javascript' })
+    }
+    return _createObjectURL(blob)
+  }
+}

package/src/InteractiveMap/polyfills.test.js

@@ -0,0 +1,127 @@
+describe('Polyfills', () => {
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+  const originalCryptoUUID = crypto.randomUUID
+  const originalCreateObjectURL = URL.createObjectURL
+  const signalProto = Object.getPrototypeOf(new AbortController().signal)
+  const originalThrowIfAborted = signalProto.throwIfAborted
+
+  beforeEach(() => {
+    jest.resetModules()
+  })
+
+  afterEach(() => {
+    Object.defineProperty(crypto, 'randomUUID', {
+      value: originalCryptoUUID,
+      configurable: true,
+      writable: true
+    })
+
+    URL.createObjectURL = originalCreateObjectURL
+
+    if (originalThrowIfAborted) {
+      signalProto.throwIfAborted = originalThrowIfAborted
+    } else {
+      delete signalProto.throwIfAborted
+    }
+  })
+
+  const load = () => jest.isolateModules(() => require('./polyfills.js'))
+
+  // Helper to read Blob text in environments without blob.text()
+  const readBlobText = (blob) => new Promise((resolve) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(reader.result)
+    reader.readAsText(blob)
+  })
+
+  describe('crypto.randomUUID', () => {
+    test('polyfills crypto.randomUUID when missing (Lines 3-8)', () => {
+      Object.defineProperty(crypto, 'randomUUID', {
+        value: undefined,
+        configurable: true,
+        writable: true
+      })
+
+      load()
+
+      expect(typeof crypto.randomUUID).toBe('function')
+      expect(crypto.randomUUID()).toMatch(UUID_RE)
+    })
+
+    test('crypto.randomUUID generates unique UUIDs', () => {
+      Object.defineProperty(crypto, 'randomUUID', {
+        value: undefined,
+        configurable: true,
+        writable: true
+      })
+      load()
+      const ids = new Set(Array.from({ length: 100 }, () => crypto.randomUUID()))
+      expect(ids.size).toBe(100)
+    })
+
+    test('does not overwrite existing crypto.randomUUID', () => {
+      const fake = jest.fn(() => 'fake')
+      Object.defineProperty(crypto, 'randomUUID', {
+        value: fake,
+        configurable: true,
+        writable: true
+      })
+      load()
+      expect(crypto.randomUUID).toBe(fake)
+    })
+  })
+
+  describe('AbortSignal.throwIfAborted', () => {
+    test('throws AbortError when aborted (True branch)', () => {
+      delete signalProto.throwIfAborted
+      load()
+      const ac = new AbortController()
+      ac.abort()
+      expect(() => ac.signal.throwIfAborted()).toThrow('The operation was aborted.')
+    })
+
+    test('does nothing when not aborted (False branch)', () => {
+      delete signalProto.throwIfAborted
+      load()
+      const ac = new AbortController()
+      // This call should execute line 20, see that aborted is false, and return undefined
+      expect(() => ac.signal.throwIfAborted()).not.toThrow()
+    })
+
+    test('wraps URL.createObjectURL for JS blobs', async () => {
+      delete signalProto.throwIfAborted
+
+      const mockCreate = jest.fn(() => 'blob:mock')
+      URL.createObjectURL = mockCreate
+
+      load()
+
+      const content = 'console.log(1)'
+      const blob = new Blob([content], { type: 'text/javascript' })
+      const result = URL.createObjectURL(blob)
+
+      expect(result).toBe('blob:mock')
+      expect(mockCreate).toHaveBeenCalled()
+
+      const passedBlob = mockCreate.mock.calls[0][0]
+      const text = await readBlobText(passedBlob)
+
+      expect(text).toContain('throwIfAborted')
+      expect(text).toContain(content)
+    })
+
+    test('does not wrap URL.createObjectURL for non-JS blobs', () => {
+      delete signalProto.throwIfAborted
+      const mockCreate = jest.fn(() => 'blob:mock')
+      URL.createObjectURL = mockCreate
+
+      load()
+
+      const blob = new Blob(['{}'], { type: 'application/json' })
+      URL.createObjectURL(blob)
+
+      expect(mockCreate).toHaveBeenCalledWith(blob)
+    })
+  })
+})

package/src/config/appConfig.js

@@ -18,12 +18,12 @@ const exitButtonSlots = {
 }
 
 // Default app buttons, panels and icons
-export const appConfig = {
+export const defaultAppConfig = {
   buttons: [{
     id: 'exit',
     label: 'Exit',
     iconId: 'close',
-    onClick: (e, { services }) => services.closeApp(),
+    onClick: (_e, { services }) => services.closeApp(),
     excludeWhen: ({ appConfig, appState }) => !appConfig.hasExitButton || !(appState.isFullscreen && (new URL(window.location.href)).searchParams.has(appConfig.mapViewParamKey)),
     mobile: exitButtonSlots,
     tablet: exitButtonSlots,
@@ -32,7 +32,7 @@ export const appConfig = {
     id: 'fullscreen',
     label: () => `${document.fullscreenElement ? 'Exit' : 'Enter'} fullscreen`,
     iconId: () => document.fullscreenElement ? 'minimise' : 'maximise',
-    onClick: (e, { appState }) => {
+    onClick: (_e, { appState }) => {
       const container = appState.layoutRefs.appContainerRef.current
       document.fullscreenElement ? document.exitFullscreen() : container.requestFullscreen()
     },
@@ -45,7 +45,7 @@ export const appConfig = {
     group: 'zoom',
     label: 'Zoom in',
     iconId: 'plus',
-    onClick: (e, { mapProvider, appConfig }) => mapProvider.zoomIn(appConfig.zoomDelta),
+    onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomIn(appConfig.zoomDelta),
     excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMaxZoom,
     mobile: buttonSlots,
@@ -56,7 +56,7 @@ export const appConfig = {
     group: 'zoom',
     label: 'Zoom out',
     iconId: 'minus',
-    onClick: (e, { mapProvider, appConfig }) => mapProvider.zoomOut(appConfig.zoomDelta),
+    onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomOut(appConfig.zoomDelta),
     excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMinZoom,
     mobile: buttonSlots,

package/src/config/appConfig.test.js

@@ -1,75 +1,140 @@
 import { render } from '@testing-library/react'
-import { appConfig } from './appConfig'
+import { defaultAppConfig, defaultButtonConfig, scaleFactor, markerSvgPaths } from './appConfig'
 
-describe('appConfig', () => {
-  const appState = { layoutRefs: { appContainerRef: { current: document.createElement('div') } }, isFullscreen: false }
-  const buttons = appConfig.buttons
+describe('defaultAppConfig', () => {
+  const appState = {
+    layoutRefs: { appContainerRef: { current: document.createElement('div') } },
+    isFullscreen: false,
+    interfaceType: 'mouse'
+  }
+
+  const buttons = defaultAppConfig.buttons
   const fullscreenBtn = buttons.find(b => b.id === 'fullscreen')
   const exitBtn = buttons.find(b => b.id === 'exit')
+  const zoomInBtn = buttons.find(b => b.id === 'zoomIn')
+  const zoomOutBtn = buttons.find(b => b.id === 'zoomOut')
 
+  // --- UI RENDER TESTS ---
   it('renders KeyboardHelp panel', () => {
-    const panel = appConfig.panels.find(p => p.id === 'keyboardHelp')
+    const panel = defaultAppConfig.panels.find(p => p.id === 'keyboardHelp')
     const { container } = render(panel.render())
     expect(container.querySelector('.im-c-keyboard-help')).toBeInTheDocument()
   })
 
-  it('evaluates dynamic button properties', () => {
-    // label
-    expect(typeof fullscreenBtn.label).toBe('function')
-    expect(fullscreenBtn.label({ appState, appConfig })).toMatch(/fullscreen/)
+  // --- 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 },
+      appState: { isFullscreen: true }
+    })).toBe(true)
+
+    window.history.pushState({}, '', '?view=map')
+    expect(exitBtn.excludeWhen({
+      appConfig: config,
+      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,
+      appState: { isFullscreen: true }
+    })).toBe(false)
+  })
+
+  it('calls exit button onClick correctly', () => {
+    const servicesMock = { closeApp: jest.fn() }
+    exitBtn.onClick({}, { services: servicesMock })
+    expect(servicesMock.closeApp).toHaveBeenCalled()
+  })
+
+  // --- FULLSCREEN BUTTON (Line 39 Coverage) ---
+  it('evaluates fullscreen label and icon states', () => {
+    const containerMock = { requestFullscreen: jest.fn() }
+    Object.defineProperty(document, 'fullscreenElement', { value: null, writable: true, configurable: true })
 
-    // iconId
-    expect(typeof fullscreenBtn.iconId).toBe('function')
-    expect(fullscreenBtn.iconId({ appState, appConfig })).toBe('maximise')
+    expect(fullscreenBtn.label({ appState })).toBe('Enter fullscreen')
+    expect(fullscreenBtn.iconId({ appState })).toBe('maximise')
 
-    // excludeWhen
-    expect(exitBtn.excludeWhen({ appConfig: { hasExitButton: false } })).toBe(true)
-    expect(fullscreenBtn.excludeWhen({ appState, appConfig: { enableFullscreen: true } })).toBe(false)
+    Object.defineProperty(document, 'fullscreenElement', { value: containerMock, writable: true, configurable: true })
+    expect(fullscreenBtn.label({ appState })).toBe('Exit fullscreen')
+    expect(fullscreenBtn.iconId({ appState })).toBe('minimise')
+  })
+
+  it('covers all branches of fullscreen excludeWhen', () => {
+    expect(fullscreenBtn.excludeWhen({ appConfig: { enableFullscreen: false }, appState: { isFullscreen: false } })).toBe(true)
+    expect(fullscreenBtn.excludeWhen({ appConfig: { enableFullscreen: true }, appState: { isFullscreen: true } })).toBe(true)
+    expect(fullscreenBtn.excludeWhen({ appConfig: { enableFullscreen: true }, appState: { isFullscreen: false } })).toBe(false)
   })
 
   it('calls fullscreen onClick correctly', () => {
     const containerMock = { requestFullscreen: jest.fn() }
-    const appStateMock = { layoutRefs: { appContainerRef: { current: containerMock } }, isFullscreen: false }
-
-    Object.defineProperty(document, 'fullscreenElement', { value: null, writable: true })
+    const appStateMock = { layoutRefs: { appContainerRef: { current: containerMock } } }
     document.exitFullscreen = jest.fn()
 
-    // Enter fullscreen
+    Object.defineProperty(document, 'fullscreenElement', { value: null, writable: true, configurable: true })
     fullscreenBtn.onClick({}, { appState: appStateMock })
     expect(containerMock.requestFullscreen).toHaveBeenCalled()
-    expect(document.exitFullscreen).not.toHaveBeenCalled()
 
-    // Exit fullscreen
-    Object.defineProperty(document, 'fullscreenElement', { value: containerMock })
+    Object.defineProperty(document, 'fullscreenElement', { value: containerMock, writable: true, configurable: true })
     fullscreenBtn.onClick({}, { appState: appStateMock })
     expect(document.exitFullscreen).toHaveBeenCalled()
   })
 
-  it('evaluates fullscreen button label and iconId for both fullscreen states', () => {
-    const containerMock = { requestFullscreen: jest.fn() }
-
-    // Not in fullscreen
-    Object.defineProperty(document, 'fullscreenElement', { value: null, writable: true })
-    expect(fullscreenBtn.label({ appState, appConfig })).toBe('Enter fullscreen')
-    expect(fullscreenBtn.iconId({ appState, appConfig })).toBe('maximise')
+  // --- ZOOM BUTTONS (Line 60 & 70 Coverage) ---
+  it('covers all branches of zoom excludeWhen for BOTH buttons', () => {
+    // We run this test for both ZoomIn and ZoomOut to ensure
+    // identical lines in both button configs are covered.
+    [zoomInBtn, zoomOutBtn].forEach((btn) => {
+      // Branch A: First part of OR is true (!enableZoomControls)
+      expect(btn.excludeWhen({
+        appConfig: { enableZoomControls: false },
+        appState: { interfaceType: 'mouse' }
+      })).toBe(true)
+
+      // Branch B: Second part of OR is true (interfaceType === 'touch')
+      expect(btn.excludeWhen({
+        appConfig: { enableZoomControls: true },
+        appState: { interfaceType: 'touch' }
+      })).toBe(true)
+
+      // Branch C: Both parts are false (Result: false)
+      expect(btn.excludeWhen({
+        appConfig: { enableZoomControls: true },
+        appState: { interfaceType: 'mouse' }
+      })).toBe(false)
+    })
+  })
 
-    // In fullscreen
-    Object.defineProperty(document, 'fullscreenElement', { value: containerMock, writable: true })
-    expect(fullscreenBtn.label({ appState, appConfig })).toBe('Exit fullscreen')
-    expect(fullscreenBtn.iconId({ appState, appConfig })).toBe('minimise')
+  it('evaluates zoom enableWhen logic', () => {
+    expect(zoomInBtn.enableWhen({ mapState: { isAtMaxZoom: true } })).toBe(false)
+    expect(zoomInBtn.enableWhen({ mapState: { isAtMaxZoom: false } })).toBe(true)
+    expect(zoomOutBtn.enableWhen({ mapState: { isAtMinZoom: true } })).toBe(false)
+    expect(zoomOutBtn.enableWhen({ mapState: { isAtMinZoom: false } })).toBe(true)
   })
 
-  it('calls exit button onClick correctly', () => {
-    const fakeEvent = {}
-    const servicesMock = { closeApp: jest.fn() }
-    const handleExitClickMock = jest.fn()
+  it('triggers mapProvider zoom methods on click', () => {
+    const mapProviderMock = { zoomIn: jest.fn(), zoomOut: jest.fn() }
+    const appConfigMock = { zoomDelta: 2 }
 
-    exitBtn.onClick(fakeEvent, { services: servicesMock, appConfig: { handleExitClick: handleExitClickMock } })
+    zoomInBtn.onClick({}, { mapProvider: mapProviderMock, appConfig: appConfigMock })
+    expect(mapProviderMock.zoomIn).toHaveBeenCalledWith(2)
 
-    // Assert that the services.closeApp() is called
-    expect(servicesMock.closeApp).toHaveBeenCalled()
+    zoomOutBtn.onClick({}, { mapProvider: mapProviderMock, appConfig: appConfigMock })
+    expect(mapProviderMock.zoomOut).toHaveBeenCalledWith(2)
+  })
 
-    // If your button no longer calls handleExitClick in the current logic, this should NOT be called
-    expect(handleExitClickMock).not.toHaveBeenCalled()
+  // --- SUPPLEMENTARY CONFIGS ---
+  it('exports supplementary configs and constants', () => {
+    expect(defaultButtonConfig.label).toBe('Button')
+    expect(scaleFactor.large).toBe(2)
+    expect(markerSvgPaths[0].shape).toBe('pin')
   })
 })

package/src/config/defaults.js

@@ -33,6 +33,7 @@ const defaults = {
   nudgeZoomDelta: 0.1,
   panDelta: 100,
   pageTitle: 'Map view',
+  preserveStateOnClose: false,
   readMapText: false,
   reverseGeocodeProvider: null,
   zoomDelta: 1

package/src/index.umd.js

@@ -6,7 +6,7 @@ import * as JSXRuntime from 'react/jsx-runtime'
 
 import InteractiveMap from './index.js'
 
-const g = typeof window !== 'undefined' ? window : globalThis
+const g = typeof window === 'undefined' ? globalThis : window
 
 // Create `defra` namespace if missing
 g.defra = g.defra || {}

package/src/scss/main.scss

@@ -21,6 +21,7 @@
 @use '../App/components/Panel/Panel.module';
 @use '../App/components/Viewport/Viewport.module';
 @use '../App/components/Tooltip/Tooltip.module';
+@use '../App/components/PopupMenu/PopupMenu.module';
 @use '../App/components/Attributions/Attributions.module';
 @use '../App/components/Logo/Logo.module';
 @use '../App/components/CrossHair/CrossHair.module';

package/src/scss/settings/_colors.scss

@@ -43,7 +43,7 @@
     --fixed-foreground-color: #0b0c0c;
 
     // Content
-    --app-border-color: #b1b4b6;
+    --app-border-color: #cecece;
     --content-border-color: #f3f2f1;
     --secondary-text-color: #505a5f;
     --image-placeholder-color: #b1b4b6;

package/src/scss/settings/_dimensions.scss

@@ -37,6 +37,10 @@
     --banner-max-desktop-width: 400px;
     --banner-collapse-margin: 14px;
 
+    // Popup menu
+    --popup-menu-min-width: 200px;
+    --popup-menu-max-width: 300px;
+
     // Action bar (Needs to fit evently if tools are in right hand column)
     --action-bar-max-width: calc(100% - (var(--button-size) * 2) - (var(--primary-gap) * 4));
 

package/src/services/eventBus.test.js

@@ -1,5 +1,5 @@
 // src/services/eventBus.test.js
-import eventBus from './eventBus.js'
+import eventBus, { createEventBus } from './eventBus.js'
 
 describe('EventBus singleton', () => {
   beforeEach(() => {
@@ -93,3 +93,26 @@ describe('EventBus singleton', () => {
     expect(eventBus.events).toEqual({})
   })
 })
+
+describe('createEventBus factory', () => {
+  /**
+   * Test to ensure coverage for the factory function (Line 50).
+   * Validates that createEventBus returns a fresh, working EventBus instance.
+   */
+  it('creates a new, independent EventBus instance', () => {
+    const newBus = createEventBus()
+    const handler = jest.fn()
+
+    // Verify it is an instance of the same logic
+    expect(newBus).toHaveProperty('on')
+    expect(newBus).toHaveProperty('emit')
+
+    // Verify it is independent of the singleton
+    newBus.on('instanceTest', handler)
+    eventBus.emit('instanceTest', 'data') // Emit on singleton
+    expect(handler).not.toHaveBeenCalled()
+
+    newBus.emit('instanceTest', 'data') // Emit on the new instance
+    expect(handler).toHaveBeenCalledWith('data')
+  })
+})

package/src/test-utils.js

@@ -48,6 +48,7 @@ export const createMockAppState = (overrides = {}) => {
     disabledButtons: new Set(),
     hiddenButtons: new Set(),
     pressedButtons: new Set(),
+    expandedButtons: new Set(),
     buttonConfig: registries.buttonRegistry.getButtonConfig(),
     panelConfig: registries.panelRegistry.getPanelConfig(),
     controlConfig: registries.controlRegistry.getControlConfig(),

package/src/types.js

@@ -568,6 +568,11 @@
  * @property {PluginDescriptor[]} [plugins]
  * Plugins to load.
  *
+ * @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.
+ * Useful for list/map toggle scenarios. Only applies to 'hybrid' and 'buttonFirst' behaviours.
+ *
  * @property {boolean} [readMapText=false]
  * Whether map text labels can be selected and read aloud by assistive technologies.
  *