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

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

@@ -2,6 +2,7 @@ import { renderHook, act } from '@testing-library/react'
 import { useFeatureItems } from './useFeatureItems.js'
 
 const SET_FEATURES = 'map:setfeatures' // NOSONAR
+const SET_FEATURES_SUPPRESSED = 'map:setfeaturessuppressed' // NOSONAR
 
 const makeEventBus = () => {
   const listeners = {}
@@ -37,11 +38,18 @@ describe('useFeatureItems — event subscription', () => {
     expect(eb.on).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
   })
 
+  it('subscribes to map:setfeaturessuppressed on mount', () => {
+    const eb = makeEventBus()
+    renderHook(() => useFeatureItems(eb))
+    expect(eb.on).toHaveBeenCalledWith(SET_FEATURES_SUPPRESSED, expect.any(Function))
+  })
+
   it('unsubscribes on unmount', () => {
     const eb = makeEventBus()
     const { unmount } = renderHook(() => useFeatureItems(eb))
     unmount()
     expect(eb.off).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
+    expect(eb.off).toHaveBeenCalledWith(SET_FEATURES_SUPPRESSED, expect.any(Function))
   })
 
   it('does not subscribe when eventBus is undefined', () => {
@@ -96,3 +104,52 @@ describe('useFeatureItems — multiselectable updates', () => {
     expect(result.current.multiselectable).toBe(false)
   })
 })
+
+// ─── useFeatureItems — suppression ───────────────────────────────────────────
+
+describe('useFeatureItems — suppression', () => {
+  const items = [{ id: 'a', label: 'Feature A' }]
+
+  it('reports empty items while suppressed, regardless of what was last set', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    expect(result.current.items).toEqual([])
+  })
+
+  it('restores the last known items once suppression is lifted', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: false }))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('defaults suppressed to false when the payload omits it', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, {}))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('defaults suppressed to false when the event carries no payload at all', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('a features update received while suppressed is still applied once restored', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    expect(result.current.items).toEqual([]) // still suppressed
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: false }))
+    expect(result.current.items).toEqual(items)
+  })
+})

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/initialiseApp.js

@@ -5,7 +5,7 @@ import { createButtonRegistry } from './registry/buttonRegistry.js'
 import { createPanelRegistry } from './registry/panelRegistry.js'
 import { createControlRegistry } from './registry/controlRegistry.js'
 import { createPluginRegistry } from './registry/pluginRegistry.js'
-import { setProviderSupportedShortcuts } from './registry/keyboardShortcutRegistry.js'
+import { createKeyboardShortcutRegistry } from './registry/keyboardShortcutRegistry.js'
 import { mergeManifests } from './registry/mergeManifests.js'
 import { App } from './App.jsx'
 
@@ -19,13 +19,15 @@ const getOrCreateRegistries = (rootElement) => {
     const buttonRegistry = createButtonRegistry()
     const panelRegistry = createPanelRegistry()
     const controlRegistry = createControlRegistry()
+    const keyboardShortcutRegistry = createKeyboardShortcutRegistry()
     const pluginRegistry = createPluginRegistry({
       registerButton: buttonRegistry.registerButton,
       registerPanel: panelRegistry.registerPanel,
-      registerControl: controlRegistry.registerControl
+      registerControl: controlRegistry.registerControl,
+      registerKeyboardShortcut: keyboardShortcutRegistry.registerKeyboardShortcut
     })
 
-    registries = { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry }
+    registries = { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry, keyboardShortcutRegistry }
     registryMap.set(rootElement, registries)
   }
   return registries
@@ -70,15 +72,15 @@ export async function initialiseApp (rootElement, {
     mapProviderMap.set(rootElement, mapProvider)
   }
 
+  // Reuse or create registries (persist across app open/close cycles)
+  const { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry, keyboardShortcutRegistry } = getOrCreateRegistries(rootElement)
+  const { registerPlugin } = pluginRegistry
+
   // Register provider-supported shortcuts
   if (mapProvider.capabilities?.supportedShortcuts) {
-    setProviderSupportedShortcuts(mapProvider.capabilities.supportedShortcuts)
+    keyboardShortcutRegistry.setProviderSupportedShortcuts(mapProvider.capabilities.supportedShortcuts)
   }
 
-  // Reuse or create registries (persist across app open/close cycles)
-  const { buttonRegistry, panelRegistry, controlRegistry, pluginRegistry } = getOrCreateRegistries(rootElement)
-  const { registerPlugin } = pluginRegistry
-
   // Clear previous plugins (but keep runtime additions)
   pluginRegistry.clear()
 
@@ -121,6 +123,7 @@ export async function initialiseApp (rootElement, {
     panelRegistry={panelRegistry}
     controlRegistry={controlRegistry}
     pluginRegistry={pluginRegistry}
+    keyboardShortcutRegistry={keyboardShortcutRegistry}
     mapProvider={mapProvider}
               />)
 

package/src/App/initialiseApp.test.js

@@ -3,7 +3,6 @@ import { initialiseApp } from './initialiseApp.js'
 import { createRoot } from 'react-dom/client'
 import { EVENTS as events } from '../config/events.js'
 import { createMockRegistries } from '../test-utils.js'
-import { setProviderSupportedShortcuts } from './registry/keyboardShortcutRegistry.js'
 
 // --------------------------------------------------
 // Shared mocks
@@ -48,7 +47,7 @@ jest.mock('./registry/pluginRegistry.js', () => ({
 }))
 
 jest.mock('./registry/keyboardShortcutRegistry.js', () => ({
-  setProviderSupportedShortcuts: jest.fn()
+  createKeyboardShortcutRegistry: jest.fn(() => mockRegistries.keyboardShortcutRegistry)
 }))
 
 jest.mock('./registry/mergeManifests.js', () => ({
@@ -179,6 +178,19 @@ describe('initialiseApp', () => {
 
     await initApp()
 
-    expect(setProviderSupportedShortcuts).not.toHaveBeenCalled()
+    expect(mockRegistries.keyboardShortcutRegistry.setProviderSupportedShortcuts).not.toHaveBeenCalled()
+  })
+
+  test('registers provider-supported shortcuts on the per-instance registry', async () => {
+    await initApp()
+
+    expect(mockRegistries.keyboardShortcutRegistry.setProviderSupportedShortcuts).toHaveBeenCalledWith(['ctrl+a'])
+  })
+
+  test('passes keyboardShortcutRegistry through to the rendered App', async () => {
+    await initApp()
+
+    const rendered = createRoot.mock.results[0].value.render.mock.calls[0][0]
+    expect(rendered.props.keyboardShortcutRegistry).toBe(mockRegistries.keyboardShortcutRegistry)
   })
 })

package/src/App/layout/Layout.jsx

@@ -16,7 +16,7 @@ import { getMapThemeVars } from '../../config/mapTheme.js'
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
 export const Layout = () => {
-  const { id } = useConfig()
+  const { id, mapLabel, mapHintText } = useConfig()
   const { breakpoint, interfaceType, preferredColorScheme, layoutRefs, isLayoutReady, hasExclusiveControl, isFullscreen } = useApp()
   const { mapStyle } = useMap()
 
@@ -37,33 +37,34 @@ export const Layout = () => {
       style={{ backgroundColor: mapStyle?.backgroundColor || undefined, ...getMapThemeVars(mapStyle) }}
       ref={layoutRefs.appContainerRef}
     >
+      {/* Leads with mapLabel so screen reader users can tell multiple maps on a page apart. */}
+      <div className='im-u-visually-hidden'>{mapLabel}. {mapHintText}</div>
       <Viewport />
       <div className={`im-o-app__overlay${isLayoutReady ? '' : ' im-o-app__overlay--not-ready'}`}>
         <div className='im-o-app__side' ref={layoutRefs.sideRef}>
           <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()