@defra/interactive-map 0.0.10-alpha → 0.0.11-alpha

package/src/App/components/Actions/Actions.module.scss

@@ -11,12 +11,17 @@
       padding-top var(--duration) ease, padding-bottom var(--duration) ease;
   }
 
+  &--border-top {
+    border-top: 1px solid var(--app-border-color);
+  }
+
   &--hidden {
     max-height: 0;
     overflow: hidden;
     opacity: 0;
     padding-top: 0;
     padding-bottom: 0;
+    border: 0;
   }
 
   .im-c-button-wrapper--wide {
@@ -30,10 +35,6 @@
   }
 }
 
-.im-c-actions--border-top {
-  border-top: 1px solid var(--app-border-color);
-}
-
 .im-o-app--tablet, .im-o-app--desktop {
   .im-c-actions {
     min-width: 0;

package/src/App/components/MapButton/MapButton.jsx

@@ -26,18 +26,12 @@ const buildButtonClassNames = (buttonId, variant, showLabel) => [
  * Builds CSS class names for the wrapper div that contains the button.
  * @param {string} buttonId - Unique identifier for the button
  * @param {boolean} showLabel - Whether the button label is displayed
- * @param {boolean} groupStart - Whether this button is at the start of a button group
- * @param {boolean} groupMiddle - Whether this button is in the middle of a button group
- * @param {boolean} groupEnd - Whether this button is at the end of a button group
  * @returns {string} Space-separated CSS class names for the wrapper
  */
-const buildWrapperClassNames = (buttonId, showLabel, groupStart, groupMiddle, groupEnd) => [
+const buildWrapperClassNames = (buttonId, showLabel) => [
   'im-c-button-wrapper',
   buttonId && `im-c-button-wrapper--${stringToKebab(buttonId)}`,
-  showLabel && 'im-c-button-wrapper--wide',
-  groupStart && 'im-c-button-wrapper--group-start',
-  groupMiddle && 'im-c-button-wrapper--group-middle',
-  groupEnd && 'im-c-button-wrapper--group-end'
+  showLabel && 'im-c-button-wrapper--wide'
 ].filter(Boolean).join(' ')
 
 /**
@@ -159,9 +153,6 @@ const buildButtonProps = ({
  * @param {Array<Object>} [props.menuItems] - Array of items for popup menu
  * @param {string} [props.idPrefix=''] - Prefix for generated panel/popup IDs
  * @param {string} [props.href] - URL for anchor element; if provided, renders as <a> instead of <button>
- * @param {boolean} [props.groupStart=false] - Whether button is at start of button group
- * @param {boolean} [props.groupMiddle=false] - Whether button is in middle of button group
- * @param {boolean} [props.groupEnd=false] - Whether button is at end of button group
  * @returns {JSX.Element} The rendered button component
  */
 export const MapButton = ({
@@ -180,10 +171,7 @@ export const MapButton = ({
   panelId,
   menuItems,
   idPrefix,
-  href,
-  groupMiddle,
-  groupStart,
-  groupEnd
+  href
 }) => {
   const { id: appId } = useConfig()
   const { buttonRefs } = useApp()
@@ -255,7 +243,7 @@ export const MapButton = ({
 
   return (
     <div
-      className={buildWrapperClassNames(buttonId, showLabel, groupStart, groupMiddle, groupEnd)}
+      className={buildWrapperClassNames(buttonId, showLabel)}
       style={isHidden ? { display: 'none' } : undefined}
     >
       {showLabel ? buttonEl : <Tooltip content={label}>{buttonEl}</Tooltip>}

package/src/App/components/MapButton/MapButton.module.scss

@@ -138,16 +138,16 @@
 }
 
 .im-o-app__right {
-    .im-c-button-wrapper--group-start,
-    .im-c-button-wrapper--group-middle {
-        margin-bottom: calc(-1 * var(--divider-gap));
+    .im-c-button-group {
+        display: flex;
+        flex-direction: column;
     }
 
-    .im-c-button-wrapper--group-start .im-c-map-button {
+    .im-c-button-group .im-c-button-wrapper:first-child .im-c-map-button {
         @include tools.border-focus-corner-override($corners: 'top');
     }
 
-    .im-c-button-wrapper--group-middle .im-c-map-button {
+    .im-c-button-group .im-c-button-wrapper:not(:first-child):not(:last-child) .im-c-map-button {
         @include tools.border-focus-corner-override($corners: 'none');
 
         &::before {
@@ -155,23 +155,23 @@
         }
     }
 
-    .im-c-button-wrapper--group-end .im-c-map-button {
+    .im-c-button-group .im-c-button-wrapper:last-child .im-c-map-button {
         margin-top: 0;
         @include tools.border-focus-corner-override($corners: 'bottom');
     }
 }
 
 .im-o-app__top {
-    .im-c-button-wrapper--group-start,
-    .im-c-button-wrapper--group-middle {
-        margin-right: calc(-1 * var(--divider-gap));
+    .im-c-button-group {
+        display: flex;
+        flex-direction: row;
     }
 
-    .im-c-button-wrapper--group-start .im-c-map-button {
+    .im-c-button-group .im-c-button-wrapper:first-child .im-c-map-button {
         @include tools.border-focus-corner-override($corners: 'left');
     }
 
-    .im-c-button-wrapper--group-middle .im-c-map-button {
+    .im-c-button-group .im-c-button-wrapper:not(:first-child):not(:last-child) .im-c-map-button {
         @include tools.border-focus-corner-override($corners: 'none');
 
         &::before {
@@ -179,7 +179,7 @@
         }
     }
 
-    .im-c-button-wrapper--group-end .im-c-map-button {
+    .im-c-button-group .im-c-button-wrapper:last-child .im-c-map-button {
         @include tools.border-focus-corner-override($corners: 'right');
     }
 }

package/src/App/components/MapButton/MapButton.test.jsx

@@ -66,15 +66,6 @@ describe('MapButton', () => {
     expect(container.firstChild).toHaveStyle('display: none')
   })
 
-  it.each([
-    ['groupStart', 'im-c-button-wrapper--group-start'],
-    ['groupMiddle', 'im-c-button-wrapper--group-middle'],
-    ['groupEnd', 'im-c-button-wrapper--group-end']
-  ])('applies wrapper %s class', (prop, className) => {
-    const { container } = renderButton({ [prop]: true })
-    expect(container.firstChild).toHaveClass(className)
-  })
-
   it('handles panelId aria attributes', () => {
     renderButton({ panelId: 'Settings', idPrefix: 'prefix', isDisabled: true, isPanelOpen: false })
     const button = getButton()

package/src/App/components/Panel/Panel.jsx

@@ -7,10 +7,10 @@ import { useIsScrollable } from '../../hooks/useIsScrollable.js'
 import { Icon } from '../Icon/Icon'
 
 const computePanelState = (bpConfig, triggeringElement) => {
-  const isAside = bpConfig.slot === 'side' && bpConfig.initiallyOpen && !bpConfig.modal
-  const isDialog = !isAside && bpConfig.dismissable
+  const isAside = bpConfig.slot === 'side' && bpConfig.open && !bpConfig.modal
+  const isDialog = !isAside && bpConfig.dismissible
   const isModal = bpConfig.modal === true
-  const isDismissable = bpConfig.dismissable !== false
+  const isDismissable = bpConfig.dismissible !== false
   const shouldFocus = Boolean(isModal || triggeringElement)
   const buttonContainerEl = bpConfig.slot.endsWith('button') ? triggeringElement?.parentNode : undefined
   return { isAside, isDialog, isModal, isDismissable, shouldFocus, buttonContainerEl }
@@ -96,8 +96,8 @@ export const Panel = ({ panelId, panelConfig, props, WrappedChild, label, html,
     }
   }, [isOpen])
 
-  const panelClass = buildPanelClassNames(bpConfig.slot, panelConfig.showLabel)
-  const panelBodyClass = buildPanelBodyClassNames(panelConfig.showLabel, isDismissable)
+  const panelClass = buildPanelClassNames(bpConfig.slot, bpConfig.showLabel ?? true)
+  const panelBodyClass = buildPanelBodyClassNames(bpConfig.showLabel ?? true, isDismissable)
   const innerHtmlProp = useMemo(() => html ? { __html: html } : null, [html])
 
   const panelProps = buildPanelProps({ elementId, shouldFocus, isDialog, isDismissable, isModal, width: bpConfig.width, panelClass })
@@ -110,7 +110,7 @@ export const Panel = ({ panelId, panelConfig, props, WrappedChild, label, html,
     >
       <h2
         id={`${elementId}-label`}
-        className={panelConfig.showLabel ? 'im-c-panel__heading im-e-heading-m' : 'im-u-visually-hidden'}
+        className={(bpConfig.showLabel ?? true) ? 'im-c-panel__heading im-e-heading-m' : 'im-u-visually-hidden'}
       >
         {label}
       </h2>

package/src/App/components/Panel/Panel.test.jsx

@@ -32,8 +32,7 @@ describe('Panel', () => {
 
   const renderPanel = (config = {}, props = {}) => {
     const panelConfig = {
-      showLabel: true,
-      desktop: { slot: 'side', initiallyOpen: true, dismissable: false, modal: false },
+      desktop: { slot: 'side', open: true, dismissible: false, modal: false, showLabel: true },
       ...config
     }
     return render(<Panel panelId='Settings' panelConfig={panelConfig} label='Settings' {...props} />)
@@ -49,17 +48,17 @@ describe('Panel', () => {
     })
 
     it('renders visually hidden label when showLabel=false', () => {
-      renderPanel({ showLabel: false })
+      renderPanel({ desktop: { slot: 'side', open: true, dismissible: false, modal: false, showLabel: false } })
       expect(screen.getByText('Settings')).toHaveClass('im-u-visually-hidden')
     })
 
-    it('applies offset class to body when showLabel=false and dismissable', () => {
-      renderPanel({ showLabel: false, desktop: { slot: 'side', dismissable: true, initiallyOpen: false } })
+    it('applies offset class to body when showLabel=false and dismissible', () => {
+      renderPanel({ desktop: { slot: 'side', dismissible: true, open: false, showLabel: false } })
       expect(screen.getByRole('dialog').querySelector('.im-c-panel__body')).toHaveClass('im-c-panel__body--offset')
     })
 
     it('applies width style if provided', () => {
-      renderPanel({ desktop: { slot: 'side', dismissable: true, initiallyOpen: true, width: '300px' } })
+      renderPanel({ desktop: { slot: 'side', dismissible: true, open: true, width: '300px' } })
       expect(screen.getByRole('complementary')).toHaveStyle({ width: '300px' })
     })
 
@@ -82,23 +81,23 @@ describe('Panel', () => {
   })
 
   describe('role and aria attributes', () => {
-    it('renders region role for non-dismissable panels', () => {
+    it('renders region role for non-dismissible panels', () => {
       renderPanel()
       expect(screen.getByRole('region')).toBeInTheDocument()
     })
 
-    it('renders dialog role for dismissable non-aside panels', () => {
-      renderPanel({ desktop: { slot: 'side', dismissable: true, initiallyOpen: false } })
+    it('renders dialog role for dismissible non-aside panels', () => {
+      renderPanel({ desktop: { slot: 'side', dismissible: true, open: false } })
       expect(screen.getByRole('dialog')).toBeInTheDocument()
     })
 
-    it('renders complementary role for dismissable aside panels', () => {
-      renderPanel({ desktop: { slot: 'side', initiallyOpen: true, dismissable: true } })
+    it('renders complementary role for dismissible aside panels', () => {
+      renderPanel({ desktop: { slot: 'side', open: true, dismissible: true } })
       expect(screen.getByRole('complementary')).toBeInTheDocument()
     })
 
     it('sets aria-modal and tabIndex for modal dialogs', () => {
-      renderPanel({ desktop: { slot: 'overlay', dismissable: true, modal: true } })
+      renderPanel({ desktop: { slot: 'overlay', dismissible: true, modal: true } })
       const dialog = screen.getByRole('dialog')
       expect(dialog).toHaveAttribute('aria-modal', 'true')
       expect(dialog).toHaveAttribute('tabIndex', '-1')
@@ -111,7 +110,7 @@ describe('Panel', () => {
       const triggeringElement = { focus: focusMock, parentNode: document.createElement('div') }
 
       renderPanel(
-        { desktop: { slot: 'top-button', dismissable: true, initiallyOpen: false } },
+        { desktop: { slot: 'top-button', dismissible: true, open: false } },
         { props: { triggeringElement } }
       )
 
@@ -125,7 +124,7 @@ describe('Panel', () => {
       const triggeringElement = { focus: focusMock, parentNode: document.createElement('div') }
 
       renderPanel(
-        { desktop: { slot: 'overlay', dismissable: true, modal: true } },
+        { desktop: { slot: 'overlay', dismissible: true, modal: true } },
         { props: { triggeringElement } }
       )
 
@@ -134,7 +133,7 @@ describe('Panel', () => {
     })
 
     it('falls back to viewportRef focus when no triggeringElement', () => {
-      renderPanel({ desktop: { slot: 'side', dismissable: true, initiallyOpen: false } })
+      renderPanel({ desktop: { slot: 'side', dismissible: true, open: false } })
 
       fireEvent.click(screen.getByRole('button', { name: 'Close Settings' }))
       expect(layoutRefs.viewportRef.current.focus).toHaveBeenCalled()

package/src/App/components/Viewport/MapController.jsx

@@ -38,7 +38,8 @@ export const MapController = ({ mapContainerRef }) => {
         center: initialState.center,
         zoom: initialState.zoom,
         bounds: initialState.bounds,
-        mapStyle
+        mapStyle,
+        mapSize
       })
     })
 

package/src/App/hooks/useLayoutMeasurements.js

@@ -81,7 +81,7 @@ export function useLayoutMeasurements () {
   // --------------------------------
   // 3. Recaluclate CSS vars when elements resize
   // --------------------------------
-  useResizeObserver([bannerRef, mainRef, topRef, actionsRef, footerRef], () => {
+  useResizeObserver([bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, actionsRef, footerRef], () => {
     requestAnimationFrame(() => {
       calculateLayout()
     })

package/src/App/hooks/useLayoutMeasurements.test.js

@@ -114,7 +114,7 @@ describe('useLayoutMeasurements', () => {
     const { layoutRefs } = setup()
     renderHook(() => useLayoutMeasurements())
     expect(useResizeObserver).toHaveBeenCalledWith(
-      [layoutRefs.bannerRef, layoutRefs.mainRef, layoutRefs.topRef, layoutRefs.actionsRef, layoutRefs.footerRef],
+      [layoutRefs.bannerRef, layoutRefs.mainRef, layoutRefs.topRef, layoutRefs.topLeftColRef, layoutRefs.topRightColRef, layoutRefs.actionsRef, layoutRefs.footerRef],
       expect.any(Function)
     )
     layoutRefs.appContainerRef.current.style.setProperty.mockClear()

package/src/App/hooks/useMapProviderOverrides.js

@@ -2,12 +2,13 @@ import { useEffect, useRef } from 'react'
 import { useConfig } from '../store/configContext.js'
 import { useApp } from '../store/appContext.js'
 import { useMap } from '../store/mapContext.js'
+import { EVENTS as events } from '../../config/events.js'
 import { getSafeZoneInset } from '../../utils/getSafeZoneInset.js'
 import { scalePoints } from '../../utils/scalePoints.js'
 import { scaleFactor } from '../../config/appConfig.js'
 
 export const useMapProviderOverrides = () => {
-  const { mapProvider } = useConfig()
+  const { mapProvider, eventBus } = useConfig()
   const { dispatch: appDispatch, layoutRefs } = useApp()
   const { mapSize } = useMap()
 
@@ -67,4 +68,23 @@ export const useMapProviderOverrides = () => {
       mapProvider.setView = originalSetView
     }
   }, [mapProvider, appDispatch, layoutRefs, mapSize])
+
+  // Forward public API events to the (overridden) mapProvider methods so that
+  // interactiveMap.fitToBounds() and interactiveMap.setView() respect safe zone padding.
+  useEffect(() => {
+    if (!mapProvider || !eventBus) {
+      return undefined
+    }
+
+    const handleFitToBounds = (bbox) => mapProvider.fitToBounds(bbox)
+    const handleSetView = (opts) => mapProvider.setView(opts)
+
+    eventBus.on(events.MAP_FIT_TO_BOUNDS, handleFitToBounds)
+    eventBus.on(events.MAP_SET_VIEW, handleSetView)
+
+    return () => {
+      eventBus.off(events.MAP_FIT_TO_BOUNDS, handleFitToBounds)
+      eventBus.off(events.MAP_SET_VIEW, handleSetView)
+    }
+  }, [mapProvider, eventBus])
 }

package/src/App/hooks/useMapProviderOverrides.test.js

@@ -22,15 +22,21 @@ const setup = (overrides = {}) => {
     setPadding: jest.fn(),
     ...overrides.mapProvider
   }
+  const capturedHandlers = {}
+  const eventBus = {
+    on: jest.fn((event, handler) => { capturedHandlers[event] = handler }),
+    off: jest.fn(),
+    ...overrides.eventBus
+  }
 
-  useConfig.mockReturnValue({ mapProvider, ...overrides.config })
+  useConfig.mockReturnValue({ mapProvider, eventBus, ...overrides.config })
   useApp.mockReturnValue({ dispatch, layoutRefs, ...overrides.app })
   useMap.mockReturnValue({ mapSize: 'md', ...overrides.map })
 
   getSafeZoneInset.mockReturnValue({ top: 10, right: 5, bottom: 15, left: 5 })
   scalePoints.mockReturnValue({ top: 20, right: 10, bottom: 30, left: 10 })
 
-  return { dispatch, layoutRefs, mapProvider }
+  return { dispatch, layoutRefs, mapProvider, eventBus, capturedHandlers }
 }
 
 describe('useMapProviderOverrides', () => {
@@ -133,4 +139,47 @@ describe('useMapProviderOverrides', () => {
 
     expect(mapProvider.fitToBounds).not.toBe(firstOverride)
   })
+
+  test('subscribes to MAP_FIT_TO_BOUNDS and MAP_SET_VIEW on eventBus', () => {
+    const { eventBus } = setup()
+    renderHook(() => useMapProviderOverrides())
+
+    expect(eventBus.on).toHaveBeenCalledWith('map:fittobounds', expect.any(Function))
+    expect(eventBus.on).toHaveBeenCalledWith('map:setview', expect.any(Function))
+  })
+
+  test('MAP_FIT_TO_BOUNDS event forwards bbox to mapProvider.fitToBounds', () => {
+    const { mapProvider, capturedHandlers } = setup()
+    const originalFitToBounds = mapProvider.fitToBounds
+    renderHook(() => useMapProviderOverrides())
+
+    capturedHandlers['map:fittobounds']([0, 0, 1, 1])
+
+    expect(originalFitToBounds).toHaveBeenCalledWith([0, 0, 1, 1])
+  })
+
+  test('MAP_SET_VIEW event forwards opts to mapProvider.setView', () => {
+    const { mapProvider, capturedHandlers } = setup()
+    const originalSetView = mapProvider.setView
+    renderHook(() => useMapProviderOverrides())
+
+    capturedHandlers['map:setview']({ center: [1, 2], zoom: 10 })
+
+    expect(originalSetView).toHaveBeenCalledWith({ center: [1, 2], zoom: 10 })
+  })
+
+  test('unsubscribes from MAP_FIT_TO_BOUNDS and MAP_SET_VIEW on unmount', () => {
+    const { eventBus } = setup()
+    const { unmount } = renderHook(() => useMapProviderOverrides())
+
+    unmount()
+
+    expect(eventBus.off).toHaveBeenCalledWith('map:fittobounds', expect.any(Function))
+    expect(eventBus.off).toHaveBeenCalledWith('map:setview', expect.any(Function))
+  })
+
+  test('skips event subscriptions when eventBus is null', () => {
+    setup({ config: { eventBus: null } })
+    expect(() => renderHook(() => useMapProviderOverrides())).not.toThrow()
+  })
 })

package/src/App/layout/Layout.jsx

@@ -94,13 +94,13 @@ export const Layout = () => {
           <div className='im-o-app__actions' ref={layoutRefs.actionsRef}>
             <SlotRenderer slot={layoutSlots.ACTIONS} />
           </div>
+          <div className='im-o-app__modal' ref={layoutRefs.modalRef}>
+            <SlotRenderer slot={layoutSlots.MODAL} />
+            <div className='im-o-app__modal-backdrop' />
+          </div>
         </div>
       </div>
       <HtmlElementHost />
-      <div className='im-o-app__modal' ref={layoutRefs.modalRef}>
-        <SlotRenderer slot={layoutSlots.MODAL} />
-        <div className='im-o-app__modal-backdrop' />
-      </div>
     </div>
   )
 }

package/src/App/layout/layout.module.scss

@@ -261,6 +261,7 @@
   display: flex;
   position: absolute;
   top: 0;
+  left: 0;
   width: 100%;
   height: 100%;
   z-index: 99;

package/src/App/registry/panelRegistry.js

@@ -4,16 +4,7 @@ import { deepMerge } from '../../utils/deepMerge.js'
 
 // Pure utility functions for panel registry operations
 export const registerPanel = (currentConfig, panel) => {
-  const normalizedPanelConfig = Object.fromEntries(
-    Object.entries(panel).map(([key, value]) => [
-      key,
-      {
-        showLabel: true,
-        ...value
-      }
-    ])
-  )
-  return { ...currentConfig, ...normalizedPanelConfig }
+  return { ...currentConfig, ...panel }
 }
 
 export const addPanel = (currentConfig, id, config) => {

package/src/App/registry/panelRegistry.test.js

@@ -2,31 +2,28 @@ import { createPanelRegistry, registerPanel, addPanel, removePanel, getPanelConf
 import { defaultPanelConfig } from '../../config/appConfig.js'
 
 describe('panelRegistry', () => {
-  test('registerPanel should store a panel with showLabel default', () => {
+  test('registerPanel should store a panel', () => {
     const panel = { settings: { title: 'Settings Panel' } }
     const config = registerPanel({}, panel)
     expect(config).toEqual({
       settings: {
-        title: 'Settings Panel',
-        showLabel: true
+        title: 'Settings Panel'
       }
     })
   })
 
   test('registerPanel should merge multiple panels', () => {
     const panel1 = { settings: { title: 'Settings Panel' } }
-    const panel2 = { dashboard: { title: 'Dashboard Panel', showLabel: false } }
+    const panel2 = { dashboard: { title: 'Dashboard Panel' } }
     let config = {}
     config = registerPanel(config, panel1)
     config = registerPanel(config, panel2)
     expect(config).toEqual({
       settings: {
-        title: 'Settings Panel',
-        showLabel: true
+        title: 'Settings Panel'
       },
       dashboard: {
-        title: 'Dashboard Panel',
-        showLabel: false
+        title: 'Dashboard Panel'
       }
     })
   })
@@ -37,8 +34,7 @@ describe('panelRegistry', () => {
     const result = getPanelConfig(config)
     expect(result).toEqual({
       reports: {
-        title: 'Reports Panel',
-        showLabel: true
+        title: 'Reports Panel'
       }
     })
   })
@@ -100,7 +96,6 @@ describe('panelRegistry', () => {
       // Test registerPanel state
       registry.registerPanel({ p1: { title: 'P1' } })
       expect(registry.getPanelConfig()).toHaveProperty('p1')
-      expect(registry.getPanelConfig().p1.showLabel).toBe(true)
 
       // Test addPanel state and return value
       const added = registry.addPanel('p2', { title: 'P2' })

package/src/App/renderer/HtmlElementHost.jsx

@@ -1,5 +1,5 @@
 // src/App/renderer/HtmlElementHost.jsx
-import React, { useRef, useEffect, useMemo } from 'react'
+import React, { useRef, useLayoutEffect, useMemo } from 'react'
 import { useApp } from '../store/appContext.js'
 import { Panel } from '../components/Panel/Panel.jsx'
 import { resolveTargetSlot, isModeAllowed, isControlVisible, isConsumerHtml } from './slotHelpers.js'
@@ -31,16 +31,24 @@ export const getSlotRef = (slot, layoutRefs) => {
  * (e.g. the banner slot swaps DOM nodes between mobile and desktop).
  */
 export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint) => {
-  useEffect(() => {
+  useLayoutEffect(() => {
     const wrapper = wrapperRef.current
 
     if (isVisible) {
       const slotRef = getSlotRef(targetSlot, layoutRefs)
       if (slotRef?.current) {
-        slotRef.current.appendChild(wrapper)
+        const backdrop = slotRef.current.querySelector(':scope > .im-o-app__modal-backdrop')
+        if (backdrop) {
+          slotRef.current.insertBefore(wrapper, backdrop)
+        } else {
+          slotRef.current.appendChild(wrapper)
+        }
         wrapper.style.display = ''
       }
     } else {
+      if (wrapper.parentElement === layoutRefs.modalRef?.current) {
+        layoutRefs.appContainerRef?.current?.appendChild(wrapper)
+      }
       wrapper.style.display = 'none'
     }
 

package/src/App/renderer/HtmlElementHost.test.jsx

@@ -199,6 +199,95 @@ describe('HtmlElementHost', () => {
     expect(container.firstChild).toBeNull() // still renders safely
   })
 
+  it('inserts panel before backdrop when modal slot contains a backdrop element', () => {
+    const modalRef = React.createRef()
+    const appContainerRef = React.createRef()
+    const refs = { ...layoutRefs, modalRef, appContainerRef }
+
+    mockApp({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Menu', desktop: { slot: 'side', modal: true } } },
+      openPanels: { p1: { props: {} } },
+      layoutRefs: refs
+    })
+
+    render(
+      <div>
+        <div ref={appContainerRef}>
+          <div ref={modalRef}>
+            <div className='im-o-app__modal-backdrop' />
+          </div>
+        </div>
+        <HtmlElementHost />
+      </div>
+    )
+
+    const children = Array.from(modalRef.current.children)
+    const panelIndex = children.findIndex(el => el.dataset.testid === 'panel-p1')
+    const backdropIndex = children.findIndex(el => el.classList.contains('im-o-app__modal-backdrop'))
+
+    expect(panelIndex).toBeGreaterThanOrEqual(0)
+    expect(panelIndex).toBeLessThan(backdropIndex)
+  })
+
+  it('moves panel from modal to appContainerRef when hidden', () => {
+    // Create refs
+    const modalRef = React.createRef()
+    const appContainerRef = React.createRef()
+    const refs = { ...layoutRefs, modalRef, appContainerRef }
+
+    // Panel config: modal slot
+    const panelConfig = {
+      p1: { html: '<p>Hi</p>', label: 'Menu', desktop: { slot: 'modal', modal: true } }
+    }
+
+    // App state: panel initially open
+    mockApp({
+      panelConfig,
+      openPanels: { p1: { props: {} } },
+      layoutRefs: refs
+    })
+
+    // Render a harness that includes both refs
+    const { rerender } = render(
+      <div>
+        <div ref={appContainerRef} />
+        <div ref={modalRef} />
+        <HtmlElementHost />
+      </div>
+    )
+
+    // Now it should actually be inside modalRef
+    const panelInModal = modalRef.current.querySelector('[data-testid="panel-p1"]')
+    expect(panelInModal).toBeTruthy()
+    expect(modalRef.current.contains(panelInModal)).toBe(true)
+
+    // Close the panel
+    useApp.mockReturnValue({
+      breakpoint: 'desktop',
+      mode: 'view',
+      isFullscreen: false,
+      panelConfig,
+      controlConfig: {},
+      openPanels: {}, // closed now
+      layoutRefs: refs,
+      dispatch: jest.fn()
+    })
+
+    rerender(
+      <div>
+        <div ref={appContainerRef} />
+        <div ref={modalRef} />
+        <HtmlElementHost />
+      </div>
+    )
+
+    // It should have moved to appContainerRef
+    const panelInApp = appContainerRef.current.querySelector('[data-testid="panel-p1"]')
+    expect(panelInApp).toBeTruthy()
+    expect(appContainerRef.current.contains(panelInApp)).toBe(true)
+    expect(modalRef.current.contains(panelInApp)).toBe(false)
+  })
+
   test('getSlotRef returns null for unknown slot', () => {
     expect(getSlotRef('unknown-slot', {})).toBeNull()
   })