@defra/interactive-map 0.0.40-alpha → 0.0.41-alpha

package/src/App/hooks/useLayoutMeasurements.js

@@ -4,58 +4,61 @@ import { useApp } from '../store/appContext.js'
 import { useMap } from '../store/mapContext.js'
 import { getSafeZoneInset } from '../../utils/getSafeZoneInset.js'
 
+const BANNER_DOCKED_CLASS = 'im-o-app__banner--docked'
+const BANNER_PANEL_SELECTOR = '.im-c-panel--banner'
+
 const buttonHeight = (ref) => ref?.current?.offsetHeight ?? 0
+const buttonWidth = (ref) => ref?.current?.offsetWidth ?? 0
+
+// Max of both sides, so centred content doesn't lean toward the emptier one.
+const symmetricWidth = (left, right) => left || right ? Math.max(left, right) : 0
+
+const subSlotMaxHeight = (columnHeight, siblingButtons, gap) => columnHeight - (siblingButtons ? siblingButtons + gap : 0)
+
+// bottomRightHeight is 0 when empty, falling back to the attributions' own height for spacing.
+const rightOffsetBottom = (containerPad, bottomRightHeight, attributionsHeight, gap) =>
+  containerPad + (bottomRightHeight > 0 ? bottomRightHeight + gap : attributionsHeight)
+
+// Mobile's actions bar sits in flow (already reflected in baseBottom); tablet/desktop's floats, so this clears it too.
+const hintBottom = (main, bottom, actionsEl, gap) => {
+  const baseBottom = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
+  const actionsHeight = actionsEl?.offsetHeight ?? 0
+  const actionsOffset = actionsHeight > 0 ? main.offsetHeight - actionsEl.offsetTop : 0
+  return Math.max(baseBottom, actionsOffset + gap)
+}
 
-const topColWidth = (left, right) =>
-  left || right ? Math.max(left, right) : 0
+// Space between .im-o-app__left/.im-o-app__right for the banner to dock in.
+const bannerGutterWidth = (mainWidth, sideColWidth, gap) => mainWidth - (sideColWidth * 2) - (gap * 2)
 
-const subSlotMaxHeight = (columnHeight, siblingButtons, gap) =>
-  columnHeight - (siblingButtons ? siblingButtons + gap : 0)
+const isBannerDocked = (gutterWidth, preferredWidth) => gutterWidth >= preferredWidth
+
+// Widest explicit width configured on a banner panel, if any, overriding the default.
+const bannerConfiguredWidth = (bannerEl) => {
+  const widths = Array.from(bannerEl?.querySelectorAll(BANNER_PANEL_SELECTOR) ?? [])
+    .map(el => Number.parseInt(el.style.width, 10))
+    .filter(w => !Number.isNaN(w))
+  return widths.length ? Math.max(...widths) : null
+}
+
+// Mobile always stacks full-width, so any inline width Panel.jsx applied is ignored.
+const clearBannerPanelWidths = (bannerEl) => {
+  bannerEl?.querySelectorAll(BANNER_PANEL_SELECTOR).forEach(el => { el.style.width = '' })
+}
+
+// Docked insets to the side-column width; stacked is full-bleed.
+const bannerInset = (isDocked, primaryGap, sideColWidth, gap) =>
+  isDocked ? primaryGap + sideColWidth + gap : primaryGap
 
 /**
- * Manages all layout measurements for the map overlay and dispatches the safe
- * zone inset used by the map to pad `fitBounds` / `setView` operations.
- *
- * ## Lifecycle
- *
- * The safe zone must only be dispatched once every plugin button's reactive
- * props (`hiddenWhen`, `enableWhen`, `pressedWhen`, `expandedWhen`) have been
- * evaluated for the current app/map state. Dispatching too early — before
- * buttons that affect layout (e.g. the actions bar) have their correct
- * visibility — produces a stale inset that causes the map to jump when the UI
- * then settles into its real state.
- *
- * ### Trigger events
- * The following state changes can alter which buttons are visible and therefore
- * how much space the UI occupies:
- *   - `breakpoint`   — responsive layout changes (desktop ↔ mobile / tablet)
- *   - `mapSize`      — map container size variant changes
- *   - `isMapReady`   — plugins are enabled on `map:ready`, changing button visibility
- *   - `isFullscreen` — fullscreen entry/exit changes which buttons are visible
- *   - `appVisible`   — app shown/hidden by parent HTML outside React (hybrid mode)
- *
- * When any of these change, `CLEAR_PLUGINS_EVALUATED` is dispatched (Effect 2),
- * which prevents the safe zone from being re-dispatched until
- * `useButtonStateEvaluator` has completed a full pass with no button state
- * changes and sets `PLUGINS_EVALUATED` again.
- *
- * ### Safe zone dispatch
- * Effect 3 fires whenever `arePluginsEvaluated` transitions to `true`, at which
- * point DOM dimensions are stable and `getSafeZoneInset` can be read reliably.
- * A `requestAnimationFrame` is used to ensure the browser has committed all
- * layout changes before measuring.
- *
- * ### Resize observer
- * Effect 4 keeps CSS custom properties up to date whenever any observed element
- * resizes (e.g. panels opening, banner appearing, actions buttons toggling).
- * It does not dispatch the safe zone — safe zone dispatch is owned entirely by
- * Effect 3 to prevent jumps on panel open/close and other non-structural resizes.
+ * Computes layout CSS vars for the map overlay and dispatches the safe zone inset used
+ * for `fitBounds`/`setView`. Waits for `arePluginsEvaluated` so the inset reflects final
+ * button visibility rather than a mid-evaluation state, which would make the map jump.
  */
-function calculateLayout (layoutRefs) {
+function calculateLayout (layoutRefs, breakpoint) {
   const {
     appContainerRef, mainRef, topRef, topLeftColRef, topRightColRef,
     bottomRef, attributionsRef, bottomRightRef, leftTopRef, leftBottomRef,
-    rightTopRef, rightBottomRef, actionsRef
+    rightTopRef, rightBottomRef, actionsRef, bannerRef, leftRef, rightRef
   } = layoutRefs
 
   const appContainer = appContainerRef.current
@@ -65,6 +68,7 @@ function calculateLayout (layoutRefs) {
   const topRightCol = topRightColRef.current
   const bottom = bottomRef.current
   const attributions = attributionsRef.current
+  const banner = bannerRef?.current
 
   if ([main, top, bottom].some(r => !r)) {
     return
@@ -72,41 +76,62 @@ function calculateLayout (layoutRefs) {
 
   const root = document.documentElement
   const dividerGap = Number.parseInt(getComputedStyle(root).getPropertyValue('--divider-gap'), 10)
+  const primaryGap = Number.parseInt(getComputedStyle(root).getPropertyValue('--primary-gap'), 10)
 
   // === Top column width ===
-  appContainer.style.setProperty('--top-col-width', `${topColWidth(topLeftCol.offsetWidth, topRightCol.offsetWidth)}px`)
+  const topColWidthPx = symmetricWidth(topLeftCol.offsetWidth, topRightCol.offsetWidth)
+  appContainer.style.setProperty('--top-col-width', `${topColWidthPx}px`)
+
+  // === Banner: docks centred between the side columns when there's room, otherwise
+  // stacks full-width. Mobile always stacks. ===
+  const isMobile = breakpoint === 'mobile'
+  if (isMobile) {
+    clearBannerPanelWidths(banner)
+  }
+  const bannerHeight = buttonHeight(bannerRef)
+  const hasBanner = bannerHeight > 0
+  const bannerSideColWidth = symmetricWidth(buttonWidth(leftRef), buttonWidth(rightRef))
+  const defaultPreferredWidth = Number.parseInt(getComputedStyle(root).getPropertyValue('--banner-preferred-width'), 10)
+  const preferredWidth = bannerConfiguredWidth(banner) ?? defaultPreferredWidth
+  appContainer.style.setProperty('--banner-preferred-width', `${preferredWidth}px`)
+  const gutterWidth = bannerGutterWidth(top.offsetWidth, bannerSideColWidth, dividerGap)
+  const isDocked = !isMobile && isBannerDocked(gutterWidth, preferredWidth)
+  banner?.classList.toggle(BANNER_DOCKED_CLASS, isDocked)
+
+  const bannerSideInset = `${bannerInset(isDocked, primaryGap, bannerSideColWidth, dividerGap)}px`
+  appContainer.style.setProperty('--banner-left', bannerSideInset)
+  appContainer.style.setProperty('--banner-right', bannerSideInset)
+
+  // Sits at the top row's bottom edge; top.offsetHeight already includes a trailing gap.
+  const isBannerStacked = hasBanner && !isDocked
+  const bannerTop = hasBanner ? top.offsetTop + top.offsetHeight : 0
+  appContainer.style.setProperty('--banner-top', `${bannerTop}px`)
+
+  // Stacked pushes the side columns below the banner plus a trailing gap — added here, not
+  // via a CSS last-child margin, since closed consumer HTML panels stay in the DOM (display:none).
+  const sideOffsetTop = (colHeight) => isBannerStacked
+    ? bannerTop + bannerHeight + dividerGap
+    : colHeight + top.offsetTop
 
   // === Left container offsets ===
-  const leftOffsetTop = topLeftCol.offsetHeight + top.offsetTop
+  const leftOffsetTop = sideOffsetTop(topLeftCol.offsetHeight)
   const leftColumnHeight = bottom.offsetTop - leftOffsetTop - dividerGap
   appContainer.style.setProperty('--left-offset-top', `${leftOffsetTop}px`)
   appContainer.style.setProperty('--left-offset-bottom', `${main.offsetHeight - bottom.offsetTop + dividerGap}px`)
   appContainer.style.setProperty('--left-top-max-height', `${leftColumnHeight}px`)
 
-  // === Right container offsets ===
-  // Mirrors the top formula (topRightCol.offsetHeight + top.offsetTop):
-  // bottomRight.offsetHeight is 0 when no buttons so the offset collapses to just
-  // the padding between the bottom of the bottom container and the bottom of main.
-  const bottomRightHeight = bottomRightRef?.current?.offsetHeight ?? 0
+  // === Right container offsets === (mirrors the left formula)
+  const bottomRightHeight = buttonHeight(bottomRightRef)
   const bottomContainerPad = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
-  const rightOffsetTop = topRightCol.offsetHeight + top.offsetTop
+  const rightOffsetTop = sideOffsetTop(topRightCol.offsetHeight)
   const rightEffectiveBottom = bottom.offsetTop + bottom.offsetHeight - bottomRightHeight
   const rightColumnHeight = rightEffectiveBottom - rightOffsetTop - dividerGap
-  const rightOffsetBottom = bottomContainerPad + (bottomRightHeight > 0 ? (bottomRightHeight + dividerGap) : attributions.offsetHeight)
   appContainer.style.setProperty('--right-offset-top', `${rightOffsetTop}px`)
-  appContainer.style.setProperty('--right-offset-bottom', `${rightOffsetBottom}px`)
+  appContainer.style.setProperty('--right-offset-bottom', `${rightOffsetBottom(bottomContainerPad, bottomRightHeight, attributions.offsetHeight, dividerGap)}px`)
   appContainer.style.setProperty('--right-top-max-height', `${rightColumnHeight}px`)
 
   // === Keyboard hint bottom offset ===
-  // On mobile the actions bar is in-flow so baseBottom already accounts for it.
-  // On tablet/desktop the actions bar is position:absolute (not in flow), so baseBottom
-  // only sees the bottom padding. actionsOffset measures the gap from the actions bar's
-  // top edge to the bottom of main, ensuring the hint always clears the floating bar.
-  const actionsEl = actionsRef?.current
-  const actionsHeight = actionsEl?.offsetHeight ?? 0
-  const baseBottom = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
-  const actionsOffset = actionsHeight > 0 ? main.offsetHeight - actionsEl.offsetTop : 0
-  appContainer.style.setProperty('--hint-bottom', `${Math.max(baseBottom, actionsOffset + dividerGap)}px`)
+  appContainer.style.setProperty('--hint-bottom', `${hintBottom(main, bottom, actionsRef?.current, dividerGap)}px`)
 
   // === Sub-slot panel max-heights ===
   appContainer.style.setProperty('--left-top-panel-max-height', `${subSlotMaxHeight(leftColumnHeight, buttonHeight(leftBottomRef), dividerGap)}px`)
@@ -119,28 +144,20 @@ export function useLayoutMeasurements () {
   const { dispatch, breakpoint, layoutRefs, arePluginsEvaluated, appVisible, isFullscreen } = useApp()
   const { mapSize, isMapReady } = useMap()
 
-  const { bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef, actionsRef } = layoutRefs
+  const { bannerRef, mainRef, headerRef, topRef, topLeftColRef, topRightColRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef, actionsRef, leftRef, rightRef } = layoutRefs
 
-  // --------------------------------
-  // 1. Clear the evaluated flag when structural inputs change so the safe zone
-  //    is not dispatched until useButtonStateEvaluator has completed a full
-  //    pass with the new app/map state and set PLUGINS_EVALUATED.
-  // --------------------------------
+  // 1. Clear the evaluated flag on structural changes, gating the safe zone until re-evaluated.
   useLayoutEffect(() => {
     dispatch({ type: 'CLEAR_PLUGINS_EVALUATED' })
   }, [breakpoint, mapSize, isMapReady, appVisible, isFullscreen])
 
-  // --------------------------------
-  // 2. Once all plugin button props have been evaluated (arePluginsEvaluated),
-  //    recalculate layout and dispatch the safe zone inset.
-  //    RAF required to ensure browser layout is committed before measuring.
-  // --------------------------------
+  // 2. Once evaluated, recalculate layout and dispatch the safe zone (RAF waits for layout to commit).
   useLayoutEffect(() => {
     if (!arePluginsEvaluated) {
       return
     }
     requestAnimationFrame(() => {
-      calculateLayout(layoutRefs)
+      calculateLayout(layoutRefs, breakpoint)
       const safeZoneInset = getSafeZoneInset(layoutRefs)
       if (safeZoneInset) {
         dispatch({ type: 'SET_SAFE_ZONE_INSET', payload: { safeZoneInset } })
@@ -148,20 +165,14 @@ export function useLayoutMeasurements () {
     })
   }, [arePluginsEvaluated])
 
-  // --------------------------------
-  // 3. Recalculate CSS vars whenever observed elements resize (panels, banner,
-  //    actions buttons, etc.). Safe zone is intentionally not dispatched here —
-  //    that is Effect 2's responsibility.
-  // --------------------------------
-  // Stable reference — all entries are ref objects from useApp that never change.
-  // Prevents useResizeObserver's effect from re-running (and cancelling its RAF)
-  // on every render due to a new array literal being passed each time.
+  // 3. Recalculate CSS vars on resize; safe zone dispatch stays Effect 2's job.
+  // Memoized so useResizeObserver doesn't re-run (and cancel its RAF) on every render.
   const observedRefs = useMemo(
-    () => [bannerRef, mainRef, topRef, topLeftColRef, topRightColRef, actionsRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef],
+    () => [bannerRef, mainRef, headerRef, topRef, topLeftColRef, topRightColRef, actionsRef, bottomRef, bottomRightRef, leftTopRef, leftBottomRef, rightTopRef, rightBottomRef, drawerRef, leftRef, rightRef],
     []
   )
 
   useResizeObserver(observedRefs, () => {
-    calculateLayout(layoutRefs)
+    calculateLayout(layoutRefs, breakpoint)
   })
 }

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

@@ -20,10 +20,13 @@ const el = (props = {}) => {
 const refs = (o = {}) => ({
   appContainerRef: { current: o.appContainer || el() },
   mainRef: { current: o.main === null ? null : el({ offsetHeight: 500, ...o.main }) },
+  headerRef: { current: el(o.header) },
   bannerRef: { current: el(o.banner) },
   topRef: { current: o.top === null ? null : el({ offsetTop: 10, ...o.top }) },
   topLeftColRef: { current: el({ offsetHeight: 50, offsetWidth: 200, ...o.topLeftCol }) },
   topRightColRef: { current: el({ offsetHeight: 40, offsetWidth: 180, ...o.topRightCol }) },
+  leftRef: { current: el(o.left) },
+  rightRef: { current: el(o.right) },
   bottomRef: { current: o.bottom === null ? null : el({ offsetTop: 400, ...o.bottom }) },
   bottomRightRef: { current: el({ offsetTop: 400, ...o.bottomRight }) },
   leftTopRef: { current: el({ offsetHeight: 0, ...o.leftTop }) },
@@ -140,6 +143,63 @@ describe('useLayoutMeasurements', () => {
     expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--top-col-width', expected)
   })
 
+  test('clears inline banner panel widths on mobile', () => {
+    const { layoutRefs } = setup({ app: { breakpoint: 'mobile' } })
+    const panel = document.createElement('div')
+    panel.className = 'im-c-panel--banner'
+    panel.style.width = '250px'
+    layoutRefs.bannerRef.current.appendChild(panel)
+    renderHook(() => useLayoutMeasurements())
+    expect(panel.style.width).toBe('')
+  })
+
+  test('uses widest parseable banner panel width, ignoring unparseable ones', () => {
+    const { layoutRefs } = setup()
+    const banner = layoutRefs.bannerRef.current
+    const panel = (width) => {
+      const p = document.createElement('div')
+      p.className = 'im-c-panel--banner'
+      p.style.width = width
+      return p
+    }
+    banner.appendChild(panel('250px'))
+    banner.appendChild(panel('auto')) // unparseable, filtered out
+    banner.appendChild(panel('400px'))
+    renderHook(() => useLayoutMeasurements())
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--banner-preferred-width', '400px')
+  })
+
+  test('falls back to default preferred width when banner element is absent', () => {
+    const { layoutRefs } = setup()
+    layoutRefs.bannerRef.current = null
+    renderHook(() => useLayoutMeasurements())
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--banner-preferred-width', '8px')
+  })
+
+  test('docks the banner when the gutter is wide enough for the preferred width', () => {
+    const { layoutRefs } = setup({ refs: { top: { offsetWidth: 1000 } } })
+    renderHook(() => useLayoutMeasurements())
+    // docked: primaryGap (8) + sideColWidth (0) + dividerGap (8)
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--banner-left', '16px')
+  })
+
+  test('treats a null leftRef current as 0 width in the banner gutter calc', () => {
+    const { layoutRefs } = setup({ refs: { top: { offsetWidth: 1000 }, right: { offsetWidth: 20 } } })
+    layoutRefs.leftRef.current = null
+    renderHook(() => useLayoutMeasurements())
+    // symmetricWidth(0, 20) = 20; docked: primaryGap (8) + sideColWidth (20) + dividerGap (8)
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--banner-left', '36px')
+  })
+
+  test('stacks a present banner below the top row when not docked', () => {
+    const { layoutRefs } = setup({ refs: { banner: { offsetHeight: 30 } } })
+    renderHook(() => useLayoutMeasurements())
+    // bannerTop = top.offsetTop (10) + top.offsetHeight (0)
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--banner-top', '10px')
+    // stacked: left column pushed below the banner (bannerTop 10 + bannerHeight 30 + dividerGap 8)
+    expect(layoutRefs.appContainerRef.current.style.setProperty).toHaveBeenCalledWith('--left-offset-top', '48px')
+  })
+
   test('uses 0 when bottomRightRef current is null', () => {
     const { layoutRefs } = setup()
     layoutRefs.bottomRightRef.current = null
@@ -264,7 +324,7 @@ describe('useLayoutMeasurements', () => {
     const { layoutRefs } = setup()
     renderHook(() => useLayoutMeasurements())
     expect(useResizeObserver).toHaveBeenCalledWith(
-      [layoutRefs.bannerRef, layoutRefs.mainRef, layoutRefs.topRef, layoutRefs.topLeftColRef, layoutRefs.topRightColRef, layoutRefs.actionsRef, layoutRefs.bottomRef, layoutRefs.bottomRightRef, layoutRefs.leftTopRef, layoutRefs.leftBottomRef, layoutRefs.rightTopRef, layoutRefs.rightBottomRef, layoutRefs.drawerRef],
+      [layoutRefs.bannerRef, layoutRefs.mainRef, layoutRefs.headerRef, layoutRefs.topRef, layoutRefs.topLeftColRef, layoutRefs.topRightColRef, layoutRefs.actionsRef, layoutRefs.bottomRef, layoutRefs.bottomRightRef, layoutRefs.leftTopRef, layoutRefs.leftBottomRef, layoutRefs.rightTopRef, layoutRefs.rightBottomRef, layoutRefs.drawerRef, layoutRefs.leftRef, layoutRefs.rightRef],
       expect.any(Function)
     )
     layoutRefs.appContainerRef.current.style.setProperty.mockClear()

package/src/App/layout/Layout.jsx

@@ -45,27 +45,26 @@ export const Layout = () => {
           <SlotRenderer slot={layoutSlots.SIDE} />
         </div>
         <div className='im-o-app__main' ref={layoutRefs.mainRef}>
-          {['mobile', 'tablet'].includes(breakpoint) && (
-            <div className='im-o-app__banner' ref={layoutRefs.bannerRef}>
-              <SlotRenderer slot={layoutSlots.BANNER} />
-            </div>
-          )}
+          <div className='im-o-app__header' ref={layoutRefs.headerRef}>
+            <SlotRenderer slot={layoutSlots.HEADER} />
+          </div>
           <div className='im-o-app__top' ref={layoutRefs.topRef}>
             <div className='im-o-app__top-col' ref={layoutRefs.topLeftColRef}>
               <SlotRenderer slot={layoutSlots.TOP_LEFT} />
             </div>
             <div className='im-o-app__top-col'>
               <SlotRenderer slot={layoutSlots.TOP_MIDDLE} />
-              {['desktop'].includes(breakpoint) && (
-                <div className='im-o-app__banner' ref={layoutRefs.bannerRef}>
-                  <SlotRenderer slot={layoutSlots.BANNER} />
-                </div>
-              )}
             </div>
             <div className='im-o-app__top-col' ref={layoutRefs.topRightColRef}>
               <SlotRenderer slot={layoutSlots.TOP_RIGHT} />
             </div>
           </div>
+          {/* Docked (centred in the top-column gutter) vs stacked (full-width, below the
+              whole top row) is decided in useLayoutMeasurements — same DOM position either
+              way, so reading/tab order stays identical across breakpoints and modes. */}
+          <div className='im-o-app__banner' ref={layoutRefs.bannerRef}>
+            <SlotRenderer slot={layoutSlots.BANNER} />
+          </div>
           <div className='im-o-app__left' ref={layoutRefs.leftRef}>
             <div className='im-o-app__left-top' ref={layoutRefs.leftTopRef}>
               <SlotRenderer slot={layoutSlots.LEFT_TOP} />

package/src/App/layout/Layout.test.jsx

@@ -36,6 +36,7 @@ describe('Layout', () => {
   const mockRefs = {
     appContainerRef: React.createRef(),
     mainRef: React.createRef(),
+    headerRef: React.createRef(),
     bannerRef: React.createRef(),
     topRef: React.createRef(),
     topLeftColRef: React.createRef(),
@@ -89,6 +90,7 @@ describe('Layout', () => {
     expect(screen.getByTestId('attributions')).toBeInTheDocument()
 
     expect(screen.getByTestId('slot-side')).toBeInTheDocument()
+    expect(screen.getByTestId('slot-header')).toBeInTheDocument()
     expect(screen.getByTestId('slot-banner')).toBeInTheDocument()
     expect(screen.getByTestId('slot-top-left')).toBeInTheDocument()
     expect(screen.getByTestId('slot-bottom-right')).toBeInTheDocument()

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

@@ -76,16 +76,41 @@
 }
 
 // ---------------------------------------------------
-// Banner: Panels only
+// Banner: docks centred between the side columns or stacks full-width; mode and position are set in JS.
 // ---------------------------------------------------
 
 .im-o-app__banner {
+  position: absolute;
+  top: var(--banner-top);
+  left: var(--banner-left);
+  right: var(--banner-right);
+  z-index: 9;
   display: flex;
   flex-direction: column;
   gap: var(--divider-gap);
 }
 
-.im-o-app__banner .im-c-panel:last-child {
+// Trailing gap below the banner is added in JS, not via a last-child margin, since closed consumer HTML panels stay in the DOM.
+
+// Stacked fills full width; docked caps the width and centres it.
+.im-o-app__banner--docked .im-c-panel--banner {
+  max-width: var(--banner-preferred-width);
+  margin-inline: auto;
+}
+
+// ---------------------------------------------------
+// Header: normal flow, above the top row — pushes everything below it down for free.
+// ---------------------------------------------------
+
+// z-index only, no position — flex items get stacking priority from z-index alone, and must stay above .im-o-app__top's since header comes first in the DOM.
+.im-o-app__header {
+  z-index: 11;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.im-o-app__header:not(:empty) {
   margin-bottom: var(--divider-gap);
 }
 
@@ -93,7 +118,9 @@
 // Top: Includes a panel and buttons in colums
 // ---------------------------------------------------
 
+// z-index only (see .im-o-app__header's comment above) — must stay below its value.
 .im-o-app__top {
+  z-index: 10;
   display: flex;
   margin-bottom: auto;
   justify-content: space-between;
@@ -421,10 +448,6 @@
   .im-o-app__modal .im-c-panel--banner {
     margin: var(--primary-gap);
   }
-
-  .im-o-app__banner {
-    z-index: 9;
-  }
 }
 
 // Desktop modal banner margin
@@ -447,13 +470,6 @@
   opacity: 0;
 }
 
-// Banner on desktop
-.im-o-app--desktop .im-c-panel--banner {
-  margin-left: auto;
-  margin-right: auto;
-  max-width: var(--banner-max-desktop-width);
-}
-
 // Actions inset when width is greater
 .im-o-app--tablet, .im-o-app--desktop {
   .im-o-app__actions {
@@ -466,8 +482,7 @@
       max-width: var(--action-bar-max-width);
     }
 
-    // max-height animation on a bottom-anchored element grows upward, looking like
-    // a slide-up. Override to opacity-only so the bar fades in instead.
+    // Opacity-only so it fades in instead of visually sliding up.
     @media (prefers-reduced-motion: no-preference) {
       .im-c-actions {
         transition: opacity var(--duration) ease;
@@ -498,8 +513,7 @@
     clip-path: inset(-20px 0 0 0);
 }
 
-// Inset focus ring on panels that are flush with the container edge,
-// so the ::after ring isn't clipped by the parent overflow:hidden
+// Inset the focus ring so it isn't clipped by the parent's overflow:hidden.
 .im-o-app--mobile .im-o-app__drawer .im-c-panel::after,
 .im-o-app--mobile .im-o-app__actions .im-c-panel::after,
 .im-o-app__modal .im-c-panel--drawer::after {

package/src/App/registry/pluginRegistry.js

@@ -11,7 +11,7 @@ function validateSlots (item, type) {
   const allowed = allowedSlots[type]
   BREAKPOINTS.forEach(bp => {
     const slot = item[bp]?.slot
-    if (slot && !allowed.includes(slot) && !(type === 'panel' && slot.endsWith('-button'))) {
+    if (slot && !allowed.includes(slot) && !(type === 'panel' && slot.endsWith('-button')) && !(type === 'control' && slot.endsWith('-panel'))) {
       logger.warn(`${type} "${item.id}" has invalid slot "${slot}" at breakpoint "${bp}". Allowed slots: ${allowed.join(', ')}.`)
     }
   })

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

@@ -171,6 +171,18 @@ describe('pluginRegistry', () => {
       pluginRegistry.registerPlugin(plugin)
       expect(console.warn).not.toHaveBeenCalled()
     })
+
+    it('does not warn for a control targeting a panel-body slot', () => {
+      const plugin = {
+        id: 'inject-plugin',
+        config: {},
+        manifest: {
+          controls: [{ id: 'ctrl1', desktop: { slot: 'map-styles-panel' } }]
+        }
+      }
+      pluginRegistry.registerPlugin(plugin)
+      expect(console.warn).not.toHaveBeenCalled()
+    })
   })
 
   it('clears all registered plugins', () => {

package/src/App/renderer/HtmlElementHost.jsx

@@ -28,6 +28,10 @@ export const getSlotRef = (slot, layoutRefs) => {
     const el = document.querySelector(`[data-button-slot="${slot}"]`)
     return el ? { current: el } : null
   }
+  if (slot?.endsWith('-panel')) {
+    const el = document.querySelector(`[data-panel-slot="${slot}"]`)
+    return el ? { current: el } : null
+  }
 
   return slotRefMap[slot] || null
 }
@@ -37,8 +41,13 @@ export const getSlotRef = (slot, layoutRefs) => {
  * Moves the wrapper into the target slot when visible, hides it otherwise.
  * Depends on breakpoint to handle conditionally rendered slot containers
  * (e.g. the banner slot swaps DOM nodes between mobile and desktop).
+ *
+ * `anchorKey` is an optional extra dependency for anchors that aren't always present in the
+ * DOM — e.g. a `-panel` target only exists while that panel is open — so the projection is
+ * re-attempted whenever it changes, rather than only on mount. Stable/persistent anchors
+ * (named layout slots, `-button` targets) don't need it since they never come and go.
  */
-export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint) => {
+export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint, anchorKey) => {
   const layoutRefsRef = useRef(layoutRefs)
   layoutRefsRef.current = layoutRefs
 
@@ -66,7 +75,7 @@ export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs,
     return () => {
       wrapper.style.display = 'none'
     }
-  }, [isVisible, targetSlot, breakpoint, wrapperRef])
+  }, [isVisible, targetSlot, breakpoint, wrapperRef, anchorKey])
 }
 
 /**
@@ -126,13 +135,17 @@ const PersistentPanel = ({ panelId, config, isOpen, openPanelProps, focusOnOpen,
  */
 const PersistentControl = ({ control, appState }) => {
   const wrapperRef = useRef(null)
-  const { breakpoint, mode, isFullscreen, layoutRefs } = appState
+  const { breakpoint, mode, isFullscreen, layoutRefs, openPanels } = appState
 
   const bpConfig = control[breakpoint]
   const isVisible = isControlVisible(control, { breakpoint, mode, isFullscreen })
   const targetSlot = bpConfig?.slot || null
 
-  useDomProjection(wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint)
+  // A control targeting a panel's body (`<panelId>-panel`) needs its DOM anchor re-resolved
+  // whenever panels open/close, since that anchor only exists while the target panel is open.
+  const anchorKey = targetSlot?.endsWith('-panel') ? Object.keys(openPanels || {}).sort((a, b) => a.localeCompare(b)).join(',') : null
+
+  useDomProjection(wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint, anchorKey)
 
   const innerHtml = useMemo(() => ({ __html: control.html }), [control.html])
 
@@ -174,7 +187,7 @@ export const HtmlElementHost = () => {
       const cfg = panelConfig[panelId]?.[breakpoint]
       return cfg?.modal
     })
-    return modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null
+    return modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null // NOSONAR - .at() unsupported on Chrome < 92
   }, [openPanels, panelConfig, breakpoint])
 
   if (!htmlPanels.length && !htmlControls.length) {

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

@@ -313,6 +313,60 @@ describe('HtmlElementHost', () => {
     expect(getSlotRef('nonexistent-button', {})).toBeNull()
   })
 
+  test('getSlotRef returns wrapped element for panel slot when element exists', () => {
+    const el = document.createElement('div')
+    el.dataset.panelSlot = 'map-styles-panel'
+    document.body.appendChild(el)
+    expect(getSlotRef('map-styles-panel', {})).toEqual({ current: el })
+    el.remove()
+  })
+
+  test('getSlotRef returns null for panel slot when no element found', () => {
+    expect(getSlotRef('nonexistent-panel', {})).toBeNull()
+  })
+
+  it('re-attempts DOM projection into a panel-body slot once its anchor appears (panel opens)', () => {
+    const controlConfig = {
+      mapStylesNote: { id: 'mapStylesNote', desktop: { slot: 'map-styles-panel' }, html: '<p>Injected note</p>' }
+    }
+
+    // A real React-rendered node, mimicking the real Panel.jsx body div — present in the DOM
+    // throughout, but only gains the data-panel-slot marker once the panel "opens".
+    const panelBodyRef = React.createRef()
+
+    mockApp({ controlConfig, openPanels: {} })
+    const { rerender } = render(
+      <div>
+        <div ref={panelBodyRef} />
+        <HtmlElementHost />
+      </div>
+    )
+
+    // Anchor isn't marked yet (panel closed) — nothing to project into
+    expect(panelBodyRef.current.querySelector('.im-c-control')).toBeNull()
+
+    // Panel opens: its body anchor is marked, and openPanels changes (two entries, so the
+    // anchorKey sort's localeCompare comparator actually runs)
+    panelBodyRef.current.setAttribute('data-panel-slot', 'map-styles-panel')
+    mockApp({ controlConfig, openPanels: { mapStyles: { props: {} }, other: { props: {} } } })
+    rerender(
+      <div>
+        <div ref={panelBodyRef} />
+        <HtmlElementHost />
+      </div>
+    )
+
+    expect(panelBodyRef.current.querySelector('.im-c-control')).toBeTruthy()
+  })
+
+  it('does not crash a panel-targeting control when appState.openPanels is missing', () => {
+    const controlConfig = {
+      mapStylesNote: { id: 'mapStylesNote', desktop: { slot: 'map-styles-panel' }, html: '<p>Injected note</p>' }
+    }
+    mockApp({ controlConfig, openPanels: undefined })
+    expect(() => render(<HtmlElementHost />)).not.toThrow()
+  })
+
   it('does not append child if slotRef exists but current is null', () => {
     // 1. Setup refs where the slot exists in the map but the DOM node (current) is null
     const incompleteRefs = {