@defra/interactive-map 0.0.42-fmp-4 → 0.0.43-alpha

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

@@ -93,6 +93,22 @@ describe('createKeyboardShortcutRegistry', () => {
     ])
   })
 
+  test('a mapProviderAgnostic core shortcut is included even when no provider declares support for it', () => {
+    jest.resetModules()
+    jest.doMock('../controls/keyboardShortcuts.js', () => ({
+      coreShortcuts: [
+        { id: 'ordinary', description: 'Ordinary' },
+        { id: 'agnostic', description: 'Agnostic', mapProviderAgnostic: true }
+      ]
+    }))
+    const registry = require('./keyboardShortcutRegistry.js').createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts([]) // no provider support declared at all
+
+    expect(registry.getKeyboardShortcuts()).toEqual([
+      { id: 'agnostic', description: 'Agnostic', mapProviderAgnostic: true }
+    ])
+  })
+
   test('two registry instances are fully isolated from each other', () => {
     // This is the multi-map-on-a-page scenario: a shortcut registered by one map
     // (e.g. a plugin) must never leak into another map's help panel, and each map's

package/src/App/renderer/HtmlElementHost.jsx

@@ -2,8 +2,7 @@
 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'
-import { allowedSlots } from './slots.js'
+import { resolveTargetSlot, isControlVisible, isConsumerHtml, isPanelSlotEligible, getAllowedModalPanelId } from './slotHelpers.js'
 
 /**
  * Maps slot names to their corresponding layout refs.
@@ -90,28 +89,13 @@ const PersistentPanel = ({ panelId, config, isOpen, openPanelProps, focusOnOpen,
   const bpConfig = config[breakpoint]
   const targetSlot = bpConfig ? resolveTargetSlot(bpConfig, breakpoint) : null
 
-  // Determine visibility using the same logic as mapPanels
-  const isVisible = (() => {
-    // 1. Initial Guard: Basic requirements
-    if (!isOpen || !bpConfig || !targetSlot) {
-      return false
-    }
-
-    // 2. Slot Validation
-    const isNextToButton = targetSlot.endsWith('-button')
-    const isSlotAllowed = allowedSlots.panel.includes(targetSlot) || isNextToButton
-
-    if (!isSlotAllowed) {
-      return false
-    }
-
-    // 3. Business Logic: Combine remaining conditions into a single "fail" check
-    const isForbiddenModal = bpConfig.modal && panelId !== allowedModalPanelId
-    const isForbiddenInline = config.inline === false && !isFullscreen
-    const isInvalidMode = !isModeAllowed(config, mode)
-
-    return !(isForbiddenModal || isForbiddenInline || isInvalidMode)
-  })()
+  // Same eligibility/modal-exclusivity rules as mapPanels.js (see slotHelpers.js), combined into
+  // one boolean since isVisible alone decides whether useDomProjection shows it.
+  const isVisible = Boolean(
+    isOpen && bpConfig && targetSlot &&
+    isPanelSlotEligible(config, { targetSlot, mode, isFullscreen }) &&
+    (!bpConfig.modal || panelId === allowedModalPanelId)
+  )
 
   useDomProjection(panelRootRef, targetSlot, isVisible, layoutRefs, breakpoint)
 
@@ -181,14 +165,10 @@ export const HtmlElementHost = () => {
   )
 
   // Determine which modal panel is allowed (topmost open modal)
-  const allowedModalPanelId = useMemo(() => {
-    const openPanelEntries = Object.entries(openPanels)
-    const modalPanels = openPanelEntries.filter(([panelId]) => {
-      const cfg = panelConfig[panelId]?.[breakpoint]
-      return cfg?.modal
-    })
-    return modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null // NOSONAR - .at() unsupported on Chrome < 92
-  }, [openPanels, panelConfig, breakpoint])
+  const allowedModalPanelId = useMemo(
+    () => getAllowedModalPanelId(openPanels, panelConfig, breakpoint),
+    [openPanels, panelConfig, breakpoint]
+  )
 
   if (!htmlPanels.length && !htmlControls.length) {
     return null

package/src/App/renderer/mapButtons.js

@@ -3,6 +3,7 @@ import { MapButton } from '../components/MapButton/MapButton.jsx'
 import { allowedSlots } from './slots.js'
 import { groupByKey } from './groupByKey.js'
 import { orderItems } from './orderItems.js'
+import { classifyPanel, getPanelRole } from '../../utils/getPanelRole.js'
 import { logger } from '../../services/logger.js'
 
 function getMatchingButtons ({ appState, buttonConfig, slot, evaluateProp }) {
@@ -118,6 +119,8 @@ function SlotButton ({ buttonId, config, appState, appConfig, evaluateProp }) {
   const bpConfig = config[appState.breakpoint] ?? {}
   const handleClick = createButtonClickHandler(config, appState, evaluateProp)
   const isPanelOpen = !!(config.panelId && appState.openPanels[config.panelId])
+  const panelBpConfig = config.panelId ? appState.panelConfig?.[config.panelId]?.[appState.breakpoint] : undefined
+  const panelRole = panelBpConfig ? getPanelRole(classifyPanel(panelBpConfig)) : undefined
 
   return (
     <MapButton
@@ -133,6 +136,7 @@ function SlotButton ({ buttonId, config, appState, appConfig, evaluateProp }) {
       isPressed={(config.isPressed !== undefined || config.pressedWhen) ? appState.pressedButtons.has(buttonId) : undefined}
       isExpanded={(config.isExpanded !== undefined || config.expandedWhen) ? appState.expandedButtons.has(buttonId) : undefined}
       isPanelOpen={isPanelOpen}
+      panelRole={panelRole}
       onClick={handleClick}
       panelId={config.panelId}
       menuItems={config.menuItems}

package/src/App/renderer/mapButtons.test.js

@@ -170,6 +170,26 @@ describe('mapButtons module', () => {
       expect(result.props).toMatchObject({ isDisabled: true, isHidden: true, isPressed: true, isExpanded: true })
     })
 
+    it.each([
+      [{ slot: 'right-top', open: false }, 'dialog'],
+      [{ slot: 'right-top', open: false, dismissible: false }, 'region'],
+      [{ slot: 'side', open: true }, 'complementary']
+    ])('derives panelRole %j -> %s from the target panel\'s breakpoint config', (panelBpConfig, expectedRole) => {
+      const state = { ...appState, panelConfig: { p1: { desktop: panelBpConfig } } }
+      const result = render({ ...baseBtn, panelId: 'p1' }, state)
+      expect(result.props.panelRole).toBe(expectedRole)
+    })
+
+    it('leaves panelRole undefined when the button has no panelId', () => {
+      const result = render(baseBtn)
+      expect(result.props.panelRole).toBeUndefined()
+    })
+
+    it('leaves panelRole undefined when the target panel has no config at this breakpoint', () => {
+      const result = render({ ...baseBtn, panelId: 'missing' })
+      expect(result.props.panelRole).toBeUndefined()
+    })
+
     it('uses empty object fallback for missing breakpoint config', () => {
       const result = render(baseBtn, { ...appState, breakpoint: 'mobile' })
       expect(result.props.showLabel).toBe(true)

package/src/App/renderer/mapPanels.js

@@ -2,8 +2,7 @@
 import React from 'react'
 import { withPluginContexts } from './pluginWrapper.js'
 import { Panel } from '../components/Panel/Panel.jsx'
-import { allowedSlots } from './slots.js'
-import { resolveTargetSlot, isModeAllowed, isConsumerHtml } from './slotHelpers.js'
+import { resolveTargetSlot, isConsumerHtml, isPanelSlotEligible, getAllowedModalPanelId } from './slotHelpers.js'
 import { mapControls } from './mapControls.js'
 import { orderItems } from './orderItems.js'
 import { groupIntoTabs } from './groupIntoTabs.js'
@@ -11,69 +10,49 @@ import { stringToKebab } from '../../utils/stringToKebab.js'
 import { logger } from '../../services/logger.js'
 
 /**
- * Determines whether a panel should be rendered in the given slot.
- * Checks slot eligibility, mode restrictions, inline/fullscreen constraints,
- * and ensures only the topmost modal panel is shown.
+ * Maps every configured panel eligible for the given layout slot to a renderable entry — open or
+ * closed alike, so a button's aria-controls id always resolves to a stable, permanently-mounted
+ * <Panel> (hidden when closed). buildPanelBody only runs while open, so nothing expensive mounts
+ * before then.
  */
-const isPanelVisible = (panelId, config, bpConfig, { targetSlot, slot, mode, isFullscreen, allowedModalPanelId }) => {
-  const isNextToButton = targetSlot.endsWith('-button')
-  if (!allowedSlots.panel.includes(targetSlot) && !isNextToButton) {
-    return false
+// Consumer HTML panels are managed by HtmlElementHost; the rest need a breakpoint config and to
+// be eligible for this slot. Returns null (skip) or the pieces the caller needs.
+const getEligiblePanelConfig = (panelId, panelConfig, breakpoint, { slot, mode, isFullscreen }) => {
+  const config = panelConfig[panelId]
+  if (!config || isConsumerHtml(config)) {
+    return null
   }
-  if (!isModeAllowed(config, mode)) {
-    return false
+  const bpConfig = config[breakpoint]
+  if (!bpConfig) {
+    return null
   }
-  if (config.inline === false && !isFullscreen) {
-    return false
+  const targetSlot = resolveTargetSlot(bpConfig, breakpoint)
+  if (!isPanelSlotEligible(config, { targetSlot, slot, mode, isFullscreen })) {
+    return null
   }
-  if (targetSlot !== slot) {
-    return false
-  }
-  if (bpConfig.modal && panelId !== allowedModalPanelId) {
-    return false
-  }
-  return true
+  return { config, bpConfig }
 }
 
-/**
- * Maps open panels to renderable entries for a given layout slot.
- * Filters panels by slot, breakpoint, mode, and modal state, then wraps
- * each panel's render function with the appropriate plugin contexts.
- */
+// A losing modal panel (see getAllowedModalPanelId) still gets a shell — it's just not open.
+const resolveIsOpen = (openEntry, bpConfig, panelId, allowedModalPanelId) =>
+  Boolean(openEntry) && (!bpConfig.modal || panelId === allowedModalPanelId)
+
 export function mapPanels ({ slot, appState, evaluateProp }) {
   const { breakpoint, pluginRegistry, panelConfig, mode, openPanels } = appState
 
-  const openPanelEntries = Object.entries(openPanels)
-
-  const modalPanels = openPanelEntries.filter(([panelId]) => {
-    const cfg = panelConfig[panelId]?.[breakpoint]
-    return cfg?.modal
-  })
-  const allowedModalPanelId = modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null // NOSONAR, .at() is only Chrome 90+
-
-  return openPanelEntries.map(([panelId, { props, focusOnOpen }]) => {
-    const config = panelConfig[panelId]
-    if (!config) {
-      return null
-    }
-
-    // Consumer HTML panels are managed by HtmlElementHost
-    if (isConsumerHtml(config)) {
-      return null
-    }
+  // Only the most-recently-opened modal panel is ever actually shown — see isOpen below.
+  const allowedModalPanelId = getAllowedModalPanelId(openPanels, panelConfig, breakpoint)
 
-    const bpConfig = config[breakpoint]
-    if (!bpConfig) {
+  return Object.keys(panelConfig).map((panelId) => {
+    const eligible = getEligiblePanelConfig(panelId, panelConfig, breakpoint, { slot, mode, isFullscreen: appState.isFullscreen })
+    if (!eligible) {
       return null
     }
+    const { config, bpConfig } = eligible
 
-    const targetSlot = resolveTargetSlot(bpConfig, breakpoint)
-
-    if (!isPanelVisible(panelId, config, bpConfig, {
-      targetSlot, slot, mode, isFullscreen: appState.isFullscreen, allowedModalPanelId
-    })) {
-      return null
-    }
+    const openEntry = openPanels[panelId]
+    const isOpen = resolveIsOpen(openEntry, bpConfig, panelId, allowedModalPanelId)
+    const { props = {}, focusOnOpen } = openEntry ?? {}
 
     const plugin = pluginRegistry.registeredPlugins.find(p => p.id === config.pluginId)
     const pluginId = plugin?.id
@@ -92,7 +71,8 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
           panelConfig={config}
           props={props}
           focusOnOpen={focusOnOpen}
-          {...buildPanelBody({ panelId, config, bpConfig, props, plugin, pluginId, html, label, appState, evaluateProp })}
+          isOpen={isOpen}
+          {...(isOpen ? buildPanelBody({ panelId, config, bpConfig, props, plugin, pluginId, html, label, appState, evaluateProp }) : {})}
           label={label}
           html={html}
         />

package/src/App/renderer/mapPanels.test.js

@@ -40,8 +40,25 @@ describe('mapPanels', () => {
     defaultAppState.panelConfig = ({ p1: baseConfig })
   })
 
-  it('returns empty array when no panels are open', () => {
-    expect(map({ ...defaultAppState, openPanels: {} })).toEqual([])
+  it('renders a closed shell (not nothing) for an eligible panel that is not open', () => {
+    const result = map({ ...defaultAppState, openPanels: {} })
+    expect(result).toHaveLength(1)
+    expect(result[0]).toMatchObject({ id: 'p1', type: 'panel', order: 1 })
+    expect(result[0].element.props.isOpen).toBe(false)
+  })
+
+  it('does not build a closed panel\'s body before it opens', () => {
+    const renderFn = jest.fn(() => <div>child</div>)
+    defaultAppState.panelConfig = ({ p1: { ...baseConfig, render: renderFn } })
+    const result = map({ ...defaultAppState, openPanels: {} })
+    expect(mapControls).not.toHaveBeenCalled()
+    expect(withPluginContexts).not.toHaveBeenCalled()
+    expect(result[0].element.props.items).toBeUndefined()
+    expect(result[0].element.props.tabs).toBeUndefined()
+  })
+
+  it('returns an empty array only when there is nothing eligible for the slot at all', () => {
+    expect(map({ ...defaultAppState, panelConfig: {} })).toEqual([])
   })
 
   it('skips panel if config is missing', () => {
@@ -49,6 +66,11 @@ describe('mapPanels', () => {
     expect(map()).toEqual([])
   })
 
+  it('skips a registered panelId whose config is falsy', () => {
+    defaultAppState.panelConfig = ({ p1: null })
+    expect(map()).toEqual([])
+  })
+
   it('skips panel if breakpoint config is missing', () => {
     defaultAppState.panelConfig = ({ p1: {} })
     expect(map()).toEqual([])
@@ -92,7 +114,7 @@ describe('mapPanels', () => {
     expect(result).toEqual([])
   })
 
-  it('only allows last opened modal panel', () => {
+  it('renders both modal panels\' shells but only marks the last-opened one as open', () => {
     defaultAppState.panelConfig = ({
       p1: { desktop: { modal: true }, includeModes: ['view'] },
       p2: { desktop: { modal: true }, includeModes: ['view'] }
@@ -101,7 +123,10 @@ describe('mapPanels', () => {
       ...defaultAppState,
       openPanels: { p1: { props: {} }, p2: { props: {} } }
     }
-    expect(map(state, 'modal').map(r => r.id)).toEqual(['p2'])
+    const result = map(state, 'modal')
+    expect(result.map(r => r.id).sort()).toEqual(['p1', 'p2'])
+    expect(result.find(r => r.id === 'p1').element.props.isOpen).toBe(false)
+    expect(result.find(r => r.id === 'p2').element.props.isOpen).toBe(true)
   })
 
   it('wraps render function with plugin context', () => {

package/src/App/renderer/slotHelpers.js

@@ -60,3 +60,36 @@ export const isControlVisible = (control, { breakpoint, mode, isFullscreen }) =>
 export const isConsumerHtml = (config) => {
   return typeof config.html === 'string' && !config.pluginId
 }
+
+/**
+ * Whether a panel is eligible for a target slot (slot type, mode, inline/fullscreen) —
+ * independent of open state and modal exclusivity (see getAllowedModalPanelId). `slot`, if
+ * given, also requires an exact match to the panel's resolved targetSlot.
+ */
+export const isPanelSlotEligible = (config, { targetSlot, slot, mode, isFullscreen }) => {
+  const isNextToButton = targetSlot.endsWith('-button')
+  if (!allowedSlots.panel.includes(targetSlot) && !isNextToButton) {
+    return false
+  }
+  if (!isModeAllowed(config, mode)) {
+    return false
+  }
+  if (config.inline === false && !isFullscreen) {
+    return false
+  }
+  if (slot !== undefined && targetSlot !== slot) {
+    return false
+  }
+  return true
+}
+
+// The id of the most-recently-opened modal panel — the only one actually allowed to show.
+export const getAllowedModalPanelId = (openPanels, panelConfig, breakpoint) => {
+  const openModalPanelIds = Object.keys(openPanels).filter(panelId => panelConfig[panelId]?.[breakpoint]?.modal)
+  return openModalPanelIds.length > 0 ? openModalPanelIds[openModalPanelIds.length - 1] : null // NOSONAR, .at() is only Chrome 90+
+}
+
+// Whether any modal-configured panel is open — drives the modal backdrop's visibility.
+export const hasOpenModalPanel = (openPanels, panelConfig, breakpoint) => {
+  return getAllowedModalPanelId(openPanels, panelConfig, breakpoint) !== null
+}

package/src/App/renderer/slotHelpers.test.js

@@ -1,6 +1,6 @@
-import { resolveTargetSlot, isModeAllowed, isControlVisible, isConsumerHtml } from './slotHelpers.js'
+import { resolveTargetSlot, isModeAllowed, isControlVisible, isConsumerHtml, isPanelSlotEligible, getAllowedModalPanelId, hasOpenModalPanel } from './slotHelpers.js'
 
-jest.mock('./slots.js', () => ({ allowedSlots: { control: ['inset', 'banner', 'actions'] } }))
+jest.mock('./slots.js', () => ({ allowedSlots: { control: ['inset', 'banner', 'actions'], panel: ['header', 'modal', 'left-top'] } }))
 
 describe('resolveTargetSlot', () => {
   it('returns modal for modal panels', () => {
@@ -85,3 +85,80 @@ describe('isConsumerHtml', () => {
     expect(isConsumerHtml({ render: () => {} })).toBe(false)
   })
 })
+
+describe('isPanelSlotEligible', () => {
+  const base = { includeModes: ['view'] }
+  const ctx = { targetSlot: 'header', mode: 'view', isFullscreen: false }
+
+  it('returns true for a panel in an allowed slot', () => {
+    expect(isPanelSlotEligible(base, ctx)).toBe(true)
+  })
+
+  it('returns false when the target slot is not an allowed panel slot', () => {
+    expect(isPanelSlotEligible(base, { ...ctx, targetSlot: 'invalid' })).toBe(false)
+  })
+
+  it('allows a target slot next to a button even though it is not a named panel slot', () => {
+    expect(isPanelSlotEligible(base, { ...ctx, targetSlot: 'my-button-button' })).toBe(true)
+  })
+
+  it('returns false when mode is not allowed', () => {
+    expect(isPanelSlotEligible({ includeModes: ['edit'] }, ctx)).toBe(false)
+  })
+
+  it('returns false when inline:false and not fullscreen', () => {
+    expect(isPanelSlotEligible({ ...base, inline: false }, ctx)).toBe(false)
+  })
+
+  it('returns true when inline:false and fullscreen', () => {
+    expect(isPanelSlotEligible({ ...base, inline: false }, { ...ctx, isFullscreen: true })).toBe(true)
+  })
+
+  it('returns false when a specific requested slot is given and the target slot does not match it', () => {
+    expect(isPanelSlotEligible(base, { ...ctx, slot: 'left-top' })).toBe(false)
+  })
+
+  it('returns true when a specific requested slot is given and matches the target slot', () => {
+    expect(isPanelSlotEligible(base, { ...ctx, slot: 'header' })).toBe(true)
+  })
+
+  it('skips the requested-slot check entirely when slot is omitted (HtmlElementHost usage)', () => {
+    expect(isPanelSlotEligible(base, { targetSlot: 'header', mode: 'view', isFullscreen: false })).toBe(true)
+  })
+})
+
+describe('getAllowedModalPanelId', () => {
+  const panelConfig = {
+    p1: { desktop: { modal: true } },
+    p2: { desktop: { modal: true } },
+    p3: { desktop: {} }
+  }
+
+  it('returns null when no modal panel is open', () => {
+    expect(getAllowedModalPanelId({ p3: { props: {} } }, panelConfig, 'desktop')).toBeNull()
+  })
+
+  it('returns the only open modal panel', () => {
+    expect(getAllowedModalPanelId({ p1: { props: {} } }, panelConfig, 'desktop')).toBe('p1')
+  })
+
+  it('returns the most recently opened modal panel when more than one is open', () => {
+    expect(getAllowedModalPanelId({ p1: { props: {} }, p2: { props: {} } }, panelConfig, 'desktop')).toBe('p2')
+  })
+
+  it('returns null when there are no open panels at all', () => {
+    expect(getAllowedModalPanelId({}, panelConfig, 'desktop')).toBeNull()
+  })
+})
+
+describe('hasOpenModalPanel', () => {
+  const panelConfig = { p1: { desktop: { modal: true } }, p2: { desktop: {} } }
+
+  it('returns false when no modal panel is open', () => {
+    expect(hasOpenModalPanel({ p2: { props: {} } }, panelConfig, 'desktop')).toBe(false)
+  })
+
+  it('returns true when a modal panel is open', () => {
+    expect(hasOpenModalPanel({ p1: { props: {} } }, panelConfig, 'desktop')).toBe(true)
+  })
+})

package/src/InteractiveMap/InteractiveMap.js

@@ -461,12 +461,23 @@ export default class InteractiveMap {
    * Focus is moved to the panel by default. Set `focus: false` in options to
    * suppress this — useful when showing a panel and you want focus to remain on the button.
    *
+   * When the panel is later closed, focus returns to `triggeringElement` if one is given or
+   * can be inferred, falling back to the map viewport otherwise. If `triggeringElement` isn't
+   * passed explicitly, whatever currently has real DOM focus is captured automatically (e.g. a
+   * selected item in the map features list) — this only needs to be passed explicitly when the
+   * panel is opened from something that doesn't hold focus at the time (e.g a timer, or a
+   * genuine mouse click, which doesn't reliably focus its target in every browser).
+   *
    * @param {string} id - Panel identifier to show.
    * @param {object} [options]
    * @param {boolean} [options.focus=true] - Whether to move focus to the panel.
+   * @param {HTMLElement} [options.triggeringElement] - Element to return focus to on close.
+   *   Defaults to the currently focused element, if any.
    */
-  showPanel (id, { focus = true } = {}) {
-    this.eventBus.emit(events.APP_SHOW_PANEL, { id, focus })
+  showPanel (id, { focus = true, triggeringElement } = {}) {
+    const resolvedTriggeringElement = triggeringElement ??
+      (document.activeElement && document.activeElement !== document.body ? document.activeElement : undefined)
+    this.eventBus.emit(events.APP_SHOW_PANEL, { id, focus, triggeringElement: resolvedTriggeringElement })
   }
 
   /**

package/src/InteractiveMap/InteractiveMap.test.js

@@ -580,6 +580,39 @@ describe('InteractiveMap — Public API Methods', () => {
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:togglebuttonstate', { id: 'btn-1', prop: 'disabled', value: true })
   })
 
+  describe('showPanel — triggeringElement', () => {
+    afterEach(() => { document.body.innerHTML = '' })
+
+    it('passes an explicit triggeringElement through unchanged', () => {
+      const el = document.createElement('button')
+      map.showPanel('panel1', { triggeringElement: el })
+      expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', { id: 'panel1', focus: true, triggeringElement: el })
+    })
+
+    it('auto-captures the currently focused element when none is given', () => {
+      const el = document.createElement('button')
+      document.body.appendChild(el)
+      el.focus()
+      map.showPanel('panel1')
+      expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', { id: 'panel1', focus: true, triggeringElement: el })
+    })
+
+    it('does not fall back to document.body as a triggeringElement', () => {
+      document.body.focus?.() // no-op in jsdom, but document.activeElement defaults to body regardless
+      map.showPanel('panel1')
+      expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', { id: 'panel1', focus: true, triggeringElement: undefined })
+    })
+
+    it('an explicit triggeringElement takes priority over the currently focused element', () => {
+      const focused = document.createElement('button')
+      document.body.appendChild(focused)
+      focused.focus()
+      const explicit = document.createElement('button')
+      map.showPanel('panel1', { triggeringElement: explicit })
+      expect(map.eventBus.emit).toHaveBeenCalledWith('app:showpanel', { id: 'panel1', focus: true, triggeringElement: explicit })
+    })
+  })
+
   it('setContinueEnabled enables and disables the journey continue button', () => {
     map.setContinueEnabled(true)
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:togglebuttonstate', { id: 'journeyContinue', prop: 'disabled', value: false })

package/src/config/appConfig.js

@@ -98,7 +98,7 @@ export const defaultAppConfig = {
     desktop: buttonSlots
   }, {
     id: 'moveControls',
-    label: 'Move and zoom controls',
+    label: 'Map controls',
     iconId: 'move',
     keepFocus: true,
     isExpanded: false,
@@ -157,7 +157,7 @@ export const defaultAppConfig = {
     svgContent: '<path d="m6 9 6 6 6-6"/>'
   }, {
     id: 'move',
-    svgContent: '<path d="M12 2v20"/><path d="m15 19-3 3-3-3"/><path d="m19 9 3 3-3 3"/><path d="M2 12h20"/><path d="m5 9-3 3 3 3"/><path d="m9 5 3-3 3 3"/>'
+    svgContent: '<path d="M11.146 15.854a1.207 1.207 0 0 1 1.708 0l1.56 1.56A2 2 0 0 1 15 18.828V21a1 1 0 0 1-1 1h-4a1 1 0 0 1-1-1v-2.172a2 2 0 0 1 .586-1.414z"/><path d="M18.828 15a2 2 0 0 1-1.414-.586l-1.56-1.56a1.207 1.207 0 0 1 0-1.708l1.56-1.56A2 2 0 0 1 18.828 9H21a1 1 0 0 1 1 1v4a1 1 0 0 1-1 1z"/><path d="M6.586 14.414A2 2 0 0 1 5.172 15H3a1 1 0 0 1-1-1v-4a1 1 0 0 1 1-1h2.172a2 2 0 0 1 1.414.586l1.56 1.56a1.207 1.207 0 0 1 0 1.708z"/><path d="M9 3a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2.172a2 2 0 0 1-.586 1.414l-1.56 1.56a1.207 1.207 0 0 1-1.708 0l-1.56-1.56A2 2 0 0 1 9 5.172z"/>'
   }, {
     id: 'precision',
     svgContent: '<circle cx="12" cy="12" r="10"/><line x1="22" x2="18" y1="12" y2="12"/><line x1="6" x2="2" y1="12" y2="12"/><line x1="12" x2="12" y1="6" y2="2"/><line x1="12" x2="12" y1="22" y2="18"/>'

package/src/types.js

@@ -629,6 +629,43 @@
  * Raw SVG content (without the outer SVG tag).
  */
 
+/**
+ * Describes a single row in the keyboard shortcuts help panel (opened via Shift+?).
+ * Plugins register these via `PluginManifest.keyboardShortcuts`; core (built-in)
+ * shortcuts share this same shape internally.
+ *
+ * @typedef {Object} KeyboardShortcutDefinition
+ *
+ * @property {string} command
+ * HTML string describing the key combination, rendered as markup — wrap keys in
+ * `<kbd>` tags, e.g. `'<kbd>Shift</kbd> + <kbd>K</kbd>'`. If it uses the Alt key,
+ * label it per platform (macOS calls it Option, not Alt) — see the shared `isMac()`
+ * helper and its use in the app's own core shortcuts.
+ *
+ * @property {'viewport' | 'listbox' | 'global'} [context='viewport']
+ * Which help-panel context this shortcut applies to. Used only to choose the panel's
+ * default open tab — it doesn't affect whether the row is shown.
+ *
+ * @property {string} [group='Navigate']
+ * Tab label the shortcut is grouped under in the help panel. Shortcuts sharing a group
+ * (case/whitespace-insensitive) appear together under one tab; if every visible shortcut
+ * shares one group, the panel renders as a flat list with no tabs.
+ *
+ * @property {string} id
+ * Unique shortcut identifier.
+ *
+ * @property {string[]} [requiredConfig]
+ * App config keys that must all be truthy for the shortcut to appear in the help panel.
+ *
+ * @property {string} title
+ * Accessible title shown in the help panel.
+ *
+ * @property {boolean} [visuallyHidden=false]
+ * When true, the row is hidden from sighted users but stays in the DOM and remains
+ * discoverable by assistive technology. Use for a shortcut with no visual affordance to
+ * discover it by otherwise — e.g. one whose only effect is a screen reader announcement.
+ */
+
 /**
  * Manifest defining a plugin's buttons, panels, controls, API methods, and state.
  *
@@ -649,6 +686,9 @@
  * @property {ComponentType} [InitComponent]
  * Initialization component.
  *
+ * @property {KeyboardShortcutDefinition[]} [keyboardShortcuts]
+ * Keyboard shortcut definitions shown in the keyboard shortcuts help panel.
+ *
  * @property {PanelDefinition[]} [panels]
  * Panel definitions.
  *

package/src/utils/getPanelElementId.js

@@ -0,0 +1,4 @@
+import { stringToKebab } from './stringToKebab.js'
+
+// Shared by MapButton (aria-controls) and Panel (its own root id) so they can't drift apart.
+export const getPanelElementId = (idPrefix, panelId) => `${idPrefix}-panel-${stringToKebab(panelId)}`

package/src/utils/getPanelElementId.test.js

@@ -0,0 +1,11 @@
+import { getPanelElementId } from './getPanelElementId.js'
+
+describe('getPanelElementId', () => {
+  it('builds the id from the idPrefix and kebab-cased panelId', () => {
+    expect(getPanelElementId('prefix', 'Settings')).toBe('prefix-panel-settings')
+  })
+
+  it('kebab-cases a camelCase panelId', () => {
+    expect(getPanelElementId('map1', 'layerOptions')).toBe('map1-panel-layer-options')
+  })
+})

package/src/utils/getPanelRole.js

@@ -0,0 +1,22 @@
+// Shared panel dialog/modality classification, used by Panel.jsx (to render the panel's
+// own role/aria-modal) and MapButton.jsx (to decide a trigger button's aria-haspopup) so
+// the two can't drift apart.
+
+// WCAG requires a modal to always be dismissible, so modal:true forces it regardless of config.
+export const classifyPanel = (bpConfig) => {
+  const isModal = bpConfig.modal === true
+  const isAside = bpConfig.slot === 'side' && bpConfig.open && !isModal
+  const isDismissible = isModal || bpConfig.dismissible !== false
+  const isDialog = !isAside && isDismissible
+  return { isModal, isAside, isDismissible, isDialog }
+}
+
+export const getPanelRole = ({ isDialog, isDismissible }) => {
+  if (isDialog) {
+    return 'dialog'
+  }
+  if (isDismissible) {
+    return 'complementary'
+  }
+  return 'region'
+}