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

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,6 +37,8 @@ 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}>

package/src/App/registry/keyboardShortcutRegistry.js

@@ -1,15 +1,10 @@
 // src/core/registry/keyboardShortcutRegistry.js
 import { coreShortcuts } from '../controls/keyboardShortcuts.js'
 
-// Stores the actual shortcut objects in insertion order
-const pluginShortcutHelp = []
+// State is passed in explicitly, rather than held at module scope, so each map instance gets its own registry and can't leak shortcuts or provider support into another map's help panel.
 
-// Tracks only IDs for O(1) duplicate detection
-const pluginShortcutIds = new Set()
-
-let providerSupportedIds = new Set()
-
-export const registerKeyboardShortcut = ({ shortcut }) => {
+const _registerKeyboardShortcut = (state, { shortcut }) => {
+  const { pluginShortcutHelp, pluginShortcutIds } = state
   if (pluginShortcutIds.has(shortcut.id)) {
     pluginShortcutHelp[pluginShortcutHelp.findIndex(s => s.id === shortcut.id)] = shortcut
   } else {
@@ -18,14 +13,14 @@ export const registerKeyboardShortcut = ({ shortcut }) => {
   }
 }
 
-export const setProviderSupportedShortcuts = (ids = []) => {
-  providerSupportedIds = new Set(ids)
+const _setProviderSupportedShortcuts = (state, ids = []) => {
+  state.providerSupportedIds = new Set(ids)
 }
 
-export const getKeyboardShortcuts = (appConfig = {}) => {
+const _getKeyboardShortcuts = (state, appConfig = {}) => {
   const filteredCore = coreShortcuts.filter(s => {
     // Must be supported by provider
-    if (!providerSupportedIds.has(s.id)) {
+    if (!state.providerSupportedIds.has(s.id)) {
       return false
     }
     // Check requiredConfig - all specified config values must be truthy
@@ -37,6 +32,23 @@ export const getKeyboardShortcuts = (appConfig = {}) => {
 
   return [
     ...filteredCore, // supported core shortcuts
-    ...pluginShortcutHelp // plugin-defined shortcuts (deduped)
+    ...state.pluginShortcutHelp // plugin-defined shortcuts (deduped)
   ]
 }
+
+// One instance per map — see initialiseApp.js's getOrCreateRegistries.
+export function createKeyboardShortcutRegistry () {
+  const state = {
+    // Stores the actual shortcut objects in insertion order
+    pluginShortcutHelp: [],
+    // Tracks only IDs for O(1) duplicate detection
+    pluginShortcutIds: new Set(),
+    providerSupportedIds: new Set()
+  }
+
+  return {
+    registerKeyboardShortcut: (args) => _registerKeyboardShortcut(state, args),
+    setProviderSupportedShortcuts: (ids) => _setProviderSupportedShortcuts(state, ids),
+    getKeyboardShortcuts: (appConfig) => _getKeyboardShortcuts(state, appConfig)
+  }
+}

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

@@ -1,8 +1,6 @@
 // src/core/registry/keyboardShortcutRegistry.test.js
-describe('keyboardShortcutRegistry', () => {
-  let registerKeyboardShortcut
-  let setProviderSupportedShortcuts
-  let getKeyboardShortcuts
+describe('createKeyboardShortcutRegistry', () => {
+  let createKeyboardShortcutRegistry
   let coreShortcutsMock
 
   beforeEach(() => {
@@ -16,57 +14,55 @@ describe('keyboardShortcutRegistry', () => {
       coreShortcuts: coreShortcutsMock
     }))
 
-    const module = require('./keyboardShortcutRegistry.js')
-    registerKeyboardShortcut = module.registerKeyboardShortcut
-    setProviderSupportedShortcuts = module.setProviderSupportedShortcuts
-    getKeyboardShortcuts = module.getKeyboardShortcuts
+    createKeyboardShortcutRegistry = require('./keyboardShortcutRegistry.js').createKeyboardShortcutRegistry
   })
 
   test('registerKeyboardShortcut should add a plugin shortcut', () => {
+    const registry = createKeyboardShortcutRegistry()
     const shortcut = { id: 'pluginShortcut', description: 'Plugin Shortcut' }
-    registerKeyboardShortcut({ shortcut }) // Pass { shortcut }
-    const shortcuts = getKeyboardShortcuts()
-    expect(shortcuts).toContain(shortcut)
+    registry.registerKeyboardShortcut({ shortcut })
+    expect(registry.getKeyboardShortcuts()).toContain(shortcut)
   })
 
   test('registerKeyboardShortcut updates an existing shortcut when re-registered with the same id', () => {
+    const registry = createKeyboardShortcutRegistry()
     const shortcut = { id: 'duplicate', description: 'First' }
     const updatedShortcut = { id: 'duplicate', description: 'Second' }
-    registerKeyboardShortcut({ shortcut })
-    registerKeyboardShortcut({ shortcut: updatedShortcut })
-    const shortcuts = getKeyboardShortcuts()
+    registry.registerKeyboardShortcut({ shortcut })
+    registry.registerKeyboardShortcut({ shortcut: updatedShortcut })
+    const shortcuts = registry.getKeyboardShortcuts()
     expect(shortcuts).toContain(updatedShortcut)
     expect(shortcuts).not.toContain(shortcut)
     expect(shortcuts.filter(s => s.id === 'duplicate')).toHaveLength(1)
   })
 
   test('setProviderSupportedShortcuts should filter core shortcuts', () => {
-    setProviderSupportedShortcuts(['copy'])
-    const shortcuts = getKeyboardShortcuts()
-    expect(shortcuts).toEqual([{ id: 'copy', description: 'Copy' }])
+    const registry = createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts(['copy'])
+    expect(registry.getKeyboardShortcuts()).toEqual([{ id: 'copy', description: 'Copy' }])
   })
 
   test('setProviderSupportedShortcuts with no argument defaults to empty set', () => {
-    setProviderSupportedShortcuts() // no arguments
-    const shortcuts = getKeyboardShortcuts()
-    expect(shortcuts).toEqual([]) // default empty
+    const registry = createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts() // no ids argument
+    expect(registry.getKeyboardShortcuts()).toEqual([]) // default empty
   })
 
   test('getKeyboardShortcuts should merge core and plugin shortcuts', () => {
-    setProviderSupportedShortcuts(['copy'])
+    const registry = createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts(['copy'])
     const pluginShortcut = { id: 'plugin', description: 'Plugin' }
-    registerKeyboardShortcut({ shortcut: pluginShortcut })
-    const shortcuts = getKeyboardShortcuts()
-    expect(shortcuts).toEqual([
+    registry.registerKeyboardShortcut({ shortcut: pluginShortcut })
+    expect(registry.getKeyboardShortcuts()).toEqual([
       { id: 'copy', description: 'Copy' },
       pluginShortcut
     ])
   })
 
   test('setProviderSupportedShortcuts with empty array returns no core shortcuts', () => {
-    setProviderSupportedShortcuts([])
-    const shortcuts = getKeyboardShortcuts()
-    expect(shortcuts).toEqual([])
+    const registry = createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts([])
+    expect(registry.getKeyboardShortcuts()).toEqual([])
   })
 
   test('getKeyboardShortcuts filters by requiredConfig when appConfig provided', () => {
@@ -77,23 +73,44 @@ describe('keyboardShortcutRegistry', () => {
         { id: 'conditional', description: 'Conditional', requiredConfig: ['featureEnabled'] }
       ]
     }))
-    const module = require('./keyboardShortcutRegistry.js')
-    module.setProviderSupportedShortcuts(['always', 'conditional'])
+    const registry = require('./keyboardShortcutRegistry.js').createKeyboardShortcutRegistry()
+    registry.setProviderSupportedShortcuts(['always', 'conditional'])
 
     // Without config, conditional shortcut is excluded
-    expect(module.getKeyboardShortcuts()).toEqual([
+    expect(registry.getKeyboardShortcuts()).toEqual([
       { id: 'always', description: 'Always shown' }
     ])
 
     // With config false, conditional shortcut is excluded
-    expect(module.getKeyboardShortcuts({ featureEnabled: false })).toEqual([
+    expect(registry.getKeyboardShortcuts({ featureEnabled: false })).toEqual([
       { id: 'always', description: 'Always shown' }
     ])
 
     // With config true, conditional shortcut is included
-    expect(module.getKeyboardShortcuts({ featureEnabled: true })).toEqual([
+    expect(registry.getKeyboardShortcuts({ featureEnabled: true })).toEqual([
       { id: 'always', description: 'Always shown' },
       { id: 'conditional', description: 'Conditional', requiredConfig: ['featureEnabled'] }
     ])
   })
+
+  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
+    // provider-supported-shortcuts filtering must stay independent.
+    const registryA = createKeyboardShortcutRegistry()
+    const registryB = createKeyboardShortcutRegistry()
+
+    registryA.setProviderSupportedShortcuts(['copy'])
+    registryA.registerKeyboardShortcut({ shortcut: { id: 'onlyOnA', description: 'Only on A' } })
+
+    registryB.setProviderSupportedShortcuts(['paste'])
+
+    expect(registryA.getKeyboardShortcuts()).toEqual([
+      { id: 'copy', description: 'Copy' },
+      { id: 'onlyOnA', description: 'Only on A' }
+    ])
+    expect(registryB.getKeyboardShortcuts()).toEqual([
+      { id: 'paste', description: 'Paste' }
+    ])
+  })
 })

package/src/App/registry/pluginRegistry.js

@@ -1,6 +1,5 @@
 // src/core/registry/pluginRegistry.js
 import { registerIcon } from './iconRegistry.js'
-import { registerKeyboardShortcut } from './keyboardShortcutRegistry.js'
 import { allowedSlots } from '../renderer/slots.js'
 import { logger } from '../../services/logger.js'
 
@@ -18,7 +17,7 @@ function validateSlots (item, type) {
   })
 }
 
-export function createPluginRegistry ({ registerButton, registerPanel, registerControl }) {
+export function createPluginRegistry ({ registerButton, registerPanel, registerControl, registerKeyboardShortcut }) {
   const registeredPlugins = []
 
   function registerPlugin (plugin) {

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

@@ -5,7 +5,6 @@ jest.mock('./buttonRegistry.js', () => ({ registerButton: jest.fn() }))
 jest.mock('./panelRegistry.js', () => ({ registerPanel: jest.fn() }))
 jest.mock('./controlRegistry.js', () => ({ registerControl: jest.fn() }))
 jest.mock('./iconRegistry.js', () => ({ registerIcon: jest.fn() }))
-jest.mock('./keyboardShortcutRegistry.js', () => ({ registerKeyboardShortcut: jest.fn() }))
 
 describe('pluginRegistry', () => {
   let pluginRegistry
@@ -18,9 +17,11 @@ describe('pluginRegistry', () => {
     registerPanel = require('./panelRegistry.js').registerPanel
     registerControl = require('./controlRegistry.js').registerControl
     registerIcon = require('./iconRegistry.js').registerIcon
-    registerKeyboardShortcut = require('./keyboardShortcutRegistry.js').registerKeyboardShortcut
+    // registerKeyboardShortcut is injected (per-instance registry), not imported from a module —
+    // see keyboardShortcutRegistry.js's createKeyboardShortcutRegistry.
+    registerKeyboardShortcut = jest.fn()
 
-    pluginRegistry = createPluginRegistry({ registerButton, registerPanel, registerControl })
+    pluginRegistry = createPluginRegistry({ registerButton, registerPanel, registerControl, registerKeyboardShortcut })
   })
 
   it('registers plugin and pushes to registeredPlugins', () => {

package/src/App/store/AppProvider.jsx

@@ -10,7 +10,7 @@ import { useMediaQueryDispatch } from '../hooks/useMediaQueryDispatch.js'
 export const AppContext = createContext(null)
 
 export const AppProvider = ({ options, children }) => {
-  const { pluginRegistry, buttonRegistry, panelRegistry, controlRegistry, eventBus, breakpointDetector } = options
+  const { pluginRegistry, buttonRegistry, panelRegistry, controlRegistry, keyboardShortcutRegistry, eventBus, breakpointDetector } = options
 
   const layoutRefs = {
     appContainerRef: useRef(null),
@@ -94,7 +94,8 @@ export const AppProvider = ({ options, children }) => {
     pluginRegistry,
     buttonRegistry,
     panelRegistry,
-    controlRegistry
+    controlRegistry,
+    keyboardShortcutRegistry
   }), [state, dispatch])
 
   return (

package/src/InteractiveMap/InteractiveMap.js

@@ -111,13 +111,16 @@ export default class InteractiveMap {
         history.pushState({ isBack: true }, '', e.currentTarget.getAttribute('href'))
       }
       this.showApp()
+      // App is already mounted, so focus the viewport directly rather than via a mount effect.
+      this.rootEl.querySelector('[role="application"]')?.focus()
     } else if (this._root) {
       // app already open — no-op, no push
     } else {
       if (this.config.manageHistoryState) {
         history.pushState({ isBack: true }, '', e.currentTarget.getAttribute('href'))
       }
-      this.loadApp()
+      // Only a genuine launcher click moves focus into the map — never a resize/breakpoint transition.
+      this.loadApp({ focusOnMount: true })
     }
   }
 
@@ -175,9 +178,11 @@ export default class InteractiveMap {
    * Load and initialize the map application.
    *
    * @internal Not intended for end-user use.
+   * @param {Object} [options]
+   * @param {boolean} [options.focusOnMount=false] - Focus the viewport once mounted; only set by a genuine launcher click.
    * @returns {Promise<void>}
    */
-  async loadApp () {
+  async loadApp ({ focusOnMount = false } = {}) {
     if (this._root || this._isLoading) {
       return
     }
@@ -204,6 +209,7 @@ export default class InteractiveMap {
         id: this.id,
         initialBreakpoint: this._breakpointDetector.getBreakpoint(),
         initialInterfaceType: getInterfaceType(),
+        focusOnMount,
         ...this.config,
         MapProvider,
         mapProviderConfig,

package/src/InteractiveMap/InteractiveMap.test.js

@@ -185,6 +185,18 @@ describe('InteractiveMap — loadApp', () => {
     expect(typeof map.someMethod).toBe('function')
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:opened', { statePreserved: false, isFullscreen: false })
   })
+
+  it('defaults focusOnMount to false when not passed', async () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    await map.loadApp()
+    expect(initialiseApp).toHaveBeenCalledWith(rootEl, expect.objectContaining({ focusOnMount: false }))
+  })
+
+  it('passes focusOnMount through to initialiseApp when set', async () => {
+    const map = new InteractiveMap('map', { behaviour: 'buttonFirst', mapProvider: mapProviderMock })
+    await map.loadApp({ focusOnMount: true })
+    expect(initialiseApp).toHaveBeenCalledWith(rootEl, expect.objectContaining({ focusOnMount: true }))
+  })
 })
 
 // --- _handleButtonClick ---
@@ -193,25 +205,30 @@ describe('InteractiveMap — _handleButtonClick', () => {
   beforeEach(setupBeforeEach)
   afterEach(() => jest.restoreAllMocks())
 
-  it('pushState and loadApp on first open', async () => {
+  it('pushState and loadApp (with focusOnMount) on first open', async () => {
     const map = new InteractiveMap('map', { behaviour: 'buttonFirst', manageHistoryState: true, mapProvider: mapProviderMock })
     jest.spyOn(map, 'loadApp').mockResolvedValue()
     jest.spyOn(history, 'pushState').mockImplementation(() => {})
     await openButtonCallback({ currentTarget: { getAttribute: jest.fn().mockReturnValue('/?mv=map') } })
-    expect(map.loadApp).toHaveBeenCalled()
+    expect(map.loadApp).toHaveBeenCalledWith({ focusOnMount: true })
     expect(history.pushState).toHaveBeenCalledWith({ isBack: true }, '', '/?mv=map')
   })
 
-  it('calls showApp (not loadApp) when map is hidden', async () => {
+  it('calls showApp (not loadApp) and focuses the viewport when map is hidden', async () => {
     const map = new InteractiveMap('map', { behaviour: 'buttonFirst', manageHistoryState: true, mapProvider: mapProviderMock })
     map._isHidden = true
     jest.spyOn(map, 'showApp').mockImplementation(() => {})
     jest.spyOn(map, 'loadApp').mockResolvedValue()
     jest.spyOn(history, 'pushState').mockImplementation(() => {})
+    const viewport = document.createElement('div')
+    viewport.setAttribute('role', 'application')
+    viewport.setAttribute('tabindex', '0')
+    rootEl.appendChild(viewport)
     await openButtonCallback({ currentTarget: { getAttribute: jest.fn().mockReturnValue('/?mv=map') } })
     expect(map.showApp).toHaveBeenCalled()
     expect(map.loadApp).not.toHaveBeenCalled()
     expect(history.pushState).toHaveBeenCalled()
+    expect(viewport).toHaveFocus()
   })
 
   it('skips pushState when manageHistoryState is false', async () => {

package/src/config/appConfig.js

@@ -1,5 +1,5 @@
 import { KeyboardHelp } from '../App/components/KeyboardHelp/KeyboardHelp.jsx'
-import { MoveControl } from '../App/components/MoveControl/MoveControl.jsx'
+import { MoveControls } from '../App/components/MoveControls/MoveControls.jsx'
 
 const keyboardBasePanelSlots = {
   slot: 'middle',
@@ -13,13 +13,15 @@ const buttonSlots = {
   showLabel: false
 }
 
-const moveControlSlot = {
+const moveControlsSlot = {
   slot: 'right-bottom'
 }
 
 const exitButtonSlots = {
   slot: 'top-left',
-  showLabel: false
+  showLabel: false,
+  // Explicit order so exit always sorts first in its slot.
+  order: 1
 }
 
 const journeyBackSlots = { slot: 'actions', showLabel: true }
@@ -77,7 +79,7 @@ export const defaultAppConfig = {
     iconId: 'plus',
     keepFocus: true,
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomIn(appConfig.zoomDelta),
-    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMoveControl || appState.interfaceType === 'touch',
+    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMoveControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMaxZoom,
     mobile: buttonSlots,
     tablet: buttonSlots,
@@ -89,23 +91,23 @@ export const defaultAppConfig = {
     iconId: 'minus',
     keepFocus: true,
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomOut(appConfig.zoomDelta),
-    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMoveControl || appState.interfaceType === 'touch',
+    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMoveControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMinZoom,
     mobile: buttonSlots,
     tablet: buttonSlots,
     desktop: buttonSlots
   }, {
-    id: 'moveControl',
+    id: 'moveControls',
     label: 'Move and zoom controls',
     iconId: 'move',
     keepFocus: true,
     isExpanded: false,
-    ariaControls: ({ appConfig }) => `${appConfig.id}-move-control-content`,
+    ariaControls: ({ appConfig }) => `${appConfig.id}-move-controls-content`,
     onClick: (_e, { appState }) => appState.dispatch({
       type: 'TOGGLE_BUTTON_EXPANDED',
-      payload: { id: 'moveControl', isExpanded: !appState.expandedButtons.has('moveControl') }
+      payload: { id: 'moveControls', isExpanded: !appState.expandedButtons.has('moveControls') }
     }),
-    excludeWhen: ({ appConfig }) => !appConfig.enableMoveControl,
+    excludeWhen: ({ appConfig }) => !appConfig.enableMoveControls,
     mobile: buttonSlots,
     tablet: buttonSlots,
     desktop: buttonSlots
@@ -129,13 +131,13 @@ export const defaultAppConfig = {
   }],
 
   controls: [{
-    id: 'moveControl',
+    id: 'moveControls',
     label: 'Move and zoom',
-    excludeWhen: ({ appConfig }) => !appConfig.enableMoveControl,
-    mobile: moveControlSlot,
-    tablet: moveControlSlot,
-    desktop: moveControlSlot,
-    render: MoveControl
+    excludeWhen: ({ appConfig }) => !appConfig.enableMoveControls,
+    mobile: moveControlsSlot,
+    tablet: moveControlsSlot,
+    desktop: moveControlsSlot,
+    render: MoveControls
   }],
 
   icons: [{

package/src/config/appConfig.test.js

@@ -2,7 +2,7 @@ import { render } from '@testing-library/react'
 import { defaultAppConfig, defaultButtonConfig, scaleFactor } from './appConfig'
 
 jest.mock('../App/store/appContext.js', () => ({
-  useApp: () => ({ listboxIsActive: false })
+  useApp: () => ({ listboxIsActive: false, keyboardShortcutRegistry: { getKeyboardShortcuts: () => [] } })
 }))
 
 describe('defaultAppConfig', () => {
@@ -19,7 +19,7 @@ describe('defaultAppConfig', () => {
   const journeyContinueBtn = buttons.find(b => b.id === 'journeyContinue')
   const zoomInBtn = buttons.find(b => b.id === 'zoomIn')
   const zoomOutBtn = buttons.find(b => b.id === 'zoomOut')
-  const moveControlBtn = buttons.find(b => b.id === 'moveControl')
+  const moveControlsBtn = buttons.find(b => b.id === 'moveControls')
 
   // --- UI RENDER TESTS ---
   it('renders KeyboardHelp panel', () => {
@@ -144,21 +144,21 @@ describe('defaultAppConfig', () => {
         appState: { interfaceType: 'mouse' }
       })).toBe(true)
 
-      // Branch B: Second part of OR is true (enableMoveControl)
+      // Branch B: Second part of OR is true (enableMoveControls)
       expect(btn.excludeWhen({
-        appConfig: { enableZoomControls: true, enableMoveControl: true },
+        appConfig: { enableZoomControls: true, enableMoveControls: true },
         appState: { interfaceType: 'mouse' }
       })).toBe(true)
 
       // Branch C: Third part of OR is true (interfaceType === 'touch')
       expect(btn.excludeWhen({
-        appConfig: { enableZoomControls: true, enableMoveControl: false },
+        appConfig: { enableZoomControls: true, enableMoveControls: false },
         appState: { interfaceType: 'touch' }
       })).toBe(true)
 
       // Branch D: All parts are false (Result: false)
       expect(btn.excludeWhen({
-        appConfig: { enableZoomControls: true, enableMoveControl: false },
+        appConfig: { enableZoomControls: true, enableMoveControls: false },
         appState: { interfaceType: 'mouse' }
       })).toBe(false)
     })
@@ -182,38 +182,38 @@ describe('defaultAppConfig', () => {
     expect(mapProviderMock.zoomOut).toHaveBeenCalledWith(2)
   })
 
-  // --- MOVE CONTROL TOGGLE BUTTON ---
-  it('covers all branches of moveControl excludeWhen', () => {
-    expect(moveControlBtn.excludeWhen({ appConfig: { enableMoveControl: false } })).toBe(true)
-    expect(moveControlBtn.excludeWhen({ appConfig: { enableMoveControl: true } })).toBe(false)
+  // --- MOVE CONTROLS TOGGLE BUTTON ---
+  it('covers all branches of moveControls excludeWhen', () => {
+    expect(moveControlsBtn.excludeWhen({ appConfig: { enableMoveControls: false } })).toBe(true)
+    expect(moveControlsBtn.excludeWhen({ appConfig: { enableMoveControls: true } })).toBe(false)
   })
 
-  it('moveControl ariaControls resolves the control element id', () => {
-    expect(moveControlBtn.ariaControls({ appConfig: { id: 'im' } })).toBe('im-move-control-content')
+  it('moveControls ariaControls resolves the control element id', () => {
+    expect(moveControlsBtn.ariaControls({ appConfig: { id: 'im' } })).toBe('im-move-controls-content')
   })
 
-  it('moveControl onClick toggles TOGGLE_BUTTON_EXPANDED based on current state', () => {
+  it('moveControls onClick toggles TOGGLE_BUTTON_EXPANDED based on current state', () => {
     const dispatch = jest.fn()
 
-    moveControlBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set() } })
+    moveControlsBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set() } })
     expect(dispatch).toHaveBeenCalledWith({
       type: 'TOGGLE_BUTTON_EXPANDED',
-      payload: { id: 'moveControl', isExpanded: true }
+      payload: { id: 'moveControls', isExpanded: true }
     })
 
     dispatch.mockClear()
-    moveControlBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set(['moveControl']) } })
+    moveControlsBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set(['moveControls']) } })
     expect(dispatch).toHaveBeenCalledWith({
       type: 'TOGGLE_BUTTON_EXPANDED',
-      payload: { id: 'moveControl', isExpanded: false }
+      payload: { id: 'moveControls', isExpanded: false }
     })
   })
 
-  // --- MOVE CONTROL ---
-  it('covers all branches of moveControl control excludeWhen', () => {
-    const control = defaultAppConfig.controls.find(c => c.id === 'moveControl')
-    expect(control.excludeWhen({ appConfig: { enableMoveControl: false } })).toBe(true)
-    expect(control.excludeWhen({ appConfig: { enableMoveControl: true } })).toBe(false)
+  // --- MOVE CONTROLS ---
+  it('covers all branches of moveControls control excludeWhen', () => {
+    const control = defaultAppConfig.controls.find(c => c.id === 'moveControls')
+    expect(control.excludeWhen({ appConfig: { enableMoveControls: false } })).toBe(true)
+    expect(control.excludeWhen({ appConfig: { enableMoveControls: true } })).toBe(false)
   })
 
   // --- SUPPLEMENTARY CONFIGS ---

package/src/config/defaults.js

@@ -16,13 +16,14 @@ const defaults = {
   containerHeight: '600px',
   deviceNotSupportedText: 'Your device is not supported. A map is available with a more up-to-date browser or device.',
   enableFullscreen: false,
-  enableMoveControl: true,
+  enableMoveControls: true,
   enableZoomControls: true,
   genericErrorText: 'There was a problem loading the map. Please try again later.',
   hasExitButton: false,
   backAndContinue: null,
   hybridWidth: null, // Defaults to maxMobileWidth if not set
   keyboardHintText: '<span class="im-u-visually-hidden">Press </span><kbd>Shift</kbd> + <span class="im-u-visually-hidden">Question mark</span><kbd aria-hidden="true">?</kbd> <span class="im-u-visually-hidden">to view </span>keyboard shortcuts',
+  mapHintText: 'Press Tab to focus it. Keyboard commands are only available once it has focus.', // Visually hidden text for assitive technology
   mapLabel: 'Interactive map application',
   mapProvider: null,
   mapSize: 'small',
@@ -31,6 +32,7 @@ const defaults = {
   urlPosition: 'sync',
   maxMobileWidth: 640,
   minDesktopWidth: 835,
+  moveControlsHintText: 'A "Move and zoom controls" button is also available, opening further controls for moving and zooming.',
   nudgePanDelta: 5,
   nudgeZoomDelta: 0.1,
   panDelta: 100,

package/src/config/mergeConfig.js

@@ -13,5 +13,12 @@ export const mergeConfig = (userConfig = {}) => {
     config.mapViewQueryParam = mapViewParamKey
   }
 
+  // mapOnly has no launcher button or history entry to exit back to, so an exit
+  // button never makes sense there regardless of hasExitButton.
+  if (config.behaviour === 'mapOnly' && config.hasExitButton) {
+    console.warn('[InteractiveMap] hasExitButton has no effect when behaviour is \'mapOnly\' — there is nothing to exit to.')
+    config.hasExitButton = false
+  }
+
   return config
 }