@defra/interactive-map 0.0.43-fmp-experimental → 0.0.45-alpha

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, keyboardShortcutRegistry, eventBus, breakpointDetector } = options
+  const { pluginRegistry, buttonRegistry, panelRegistry, controlRegistry, keyboardShortcutRegistry, spatialListRegistry, eventBus, breakpointDetector } = options
 
   const layoutRefs = {
     appContainerRef: useRef(null),
@@ -96,7 +96,8 @@ export const AppProvider = ({ options, children }) => {
     buttonRegistry,
     panelRegistry,
     controlRegistry,
-    keyboardShortcutRegistry
+    keyboardShortcutRegistry,
+    spatialListRegistry
   }), [state, dispatch])
 
   return (

package/src/App/store/ServiceProvider.jsx

@@ -10,7 +10,7 @@ import { patternRegistry } from '../../services/patternRegistry.js'
 
 export const ServiceContext = createContext(null)
 
-export const ServiceProvider = ({ eventBus, children }) => {
+export const ServiceProvider = ({ eventBus, pluginRegistry, children }) => {
   const { id, handleExitClick, symbolDefaults: constructorSymbolDefaults } = useConfig()
   const mapStatusRef = useRef(null)
   const announce = useMemo(() => createAnnouncer(mapStatusRef), [])
@@ -26,8 +26,10 @@ export const ServiceProvider = ({ eventBus, children }) => {
     mapStatusRef,
     closeApp: () => closeApp(id, handleExitClick, eventBus),
     symbolRegistry,
-    patternRegistry
-  }), [announce, hints])
+    patternRegistry,
+    // See pluginRegistry.js's getPlugin() for what this does and doesn't guarantee.
+    getPlugin: (pluginId) => pluginRegistry?.getPlugin(pluginId)
+  }), [announce, hints, pluginRegistry])
 
   return (
     <ServiceContext.Provider value={services}>

package/src/App/store/ServiceProvider.test.jsx

@@ -34,7 +34,10 @@ jest.mock('../store/configContext.js', () => ({
 
 describe('ServiceProvider', () => {
   const mockEventBus = { on: jest.fn(), off: jest.fn(), emit: jest.fn() }
-  const wrapper = ({ children }) => <ServiceProvider eventBus={mockEventBus}>{children}</ServiceProvider>
+  const mockPluginRegistry = { getPlugin: jest.fn(() => ({ newPolygon: jest.fn() })) }
+  const wrapper = ({ children }) => (
+    <ServiceProvider eventBus={mockEventBus} pluginRegistry={mockPluginRegistry}>{children}</ServiceProvider>
+  )
 
   test('provides announce, reverseGeocode, eventBus, and closeApp via context', () => {
     const { result } = renderHook(() => React.useContext(ServiceContext), { wrapper })
@@ -68,6 +71,22 @@ describe('ServiceProvider', () => {
     expect(mockShow).toHaveBeenCalledWith('<b>test</b>', { duration: 2000 })
   })
 
+  test('getPlugin delegates to pluginRegistry.getPlugin', () => {
+    const { result } = renderHook(() => React.useContext(ServiceContext), { wrapper })
+
+    const plugin = result.current.getPlugin('draw')
+
+    expect(mockPluginRegistry.getPlugin).toHaveBeenCalledWith('draw')
+    expect(plugin).toEqual({ newPolygon: expect.any(Function) })
+  })
+
+  test('getPlugin returns undefined when no pluginRegistry is provided', () => {
+    const noRegistryWrapper = ({ children }) => <ServiceProvider eventBus={mockEventBus}>{children}</ServiceProvider>
+    const { result } = renderHook(() => React.useContext(ServiceContext), { wrapper: noRegistryWrapper })
+
+    expect(result.current.getPlugin('draw')).toBeUndefined()
+  })
+
   test('closeApp calls closeApp service with id and handleExitClick', () => {
     const mockHandleExitClick = jest.fn()
     const { useConfig } = require('../store/configContext.js')

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

@@ -1,5 +1,5 @@
 import { KeyboardHelp } from '../App/components/KeyboardHelp/KeyboardHelp.jsx'
-import { MoveControls } from '../App/components/MoveControls/MoveControls.jsx'
+import { MapControls } from '../App/components/MapControls/MapControls.jsx'
 
 const keyboardBasePanelSlots = {
   slot: 'middle',
@@ -13,7 +13,7 @@ const buttonSlots = {
   showLabel: false
 }
 
-const moveControlsSlot = {
+const mapControlsSlot = {
   slot: 'right-bottom'
 }
 
@@ -53,7 +53,7 @@ export const defaultAppConfig = {
     desktop: journeyContinueSlots
   }, {
     id: 'exit',
-    label: 'Exit',
+    label: 'Close map view',
     iconId: 'close',
     onClick: (_e, { services }) => services.closeApp(),
     excludeWhen: ({ appConfig, appState }) => !appConfig.hasExitButton || !appState.isFullscreen,
@@ -79,7 +79,7 @@ export const defaultAppConfig = {
     iconId: 'plus',
     keepFocus: true,
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomIn(appConfig.zoomDelta),
-    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMoveControls || appState.interfaceType === 'touch',
+    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMapControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMaxZoom,
     mobile: buttonSlots,
     tablet: buttonSlots,
@@ -91,23 +91,23 @@ export const defaultAppConfig = {
     iconId: 'minus',
     keepFocus: true,
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomOut(appConfig.zoomDelta),
-    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMoveControls || appState.interfaceType === 'touch',
+    excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appConfig.enableMapControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMinZoom,
     mobile: buttonSlots,
     tablet: buttonSlots,
     desktop: buttonSlots
   }, {
-    id: 'moveControls',
-    label: 'Move and zoom controls',
+    id: 'mapControls',
+    label: 'Map controls',
     iconId: 'move',
     keepFocus: true,
     isExpanded: false,
-    ariaControls: ({ appConfig }) => `${appConfig.id}-move-controls-content`,
+    ariaControls: ({ appConfig }) => `${appConfig.id}-map-controls-content`,
     onClick: (_e, { appState }) => appState.dispatch({
       type: 'TOGGLE_BUTTON_EXPANDED',
-      payload: { id: 'moveControls', isExpanded: !appState.expandedButtons.has('moveControls') }
+      payload: { id: 'mapControls', isExpanded: !appState.expandedButtons.has('mapControls') }
     }),
-    excludeWhen: ({ appConfig }) => !appConfig.enableMoveControls,
+    excludeWhen: ({ appConfig }) => !appConfig.enableMapControls,
     mobile: buttonSlots,
     tablet: buttonSlots,
     desktop: buttonSlots
@@ -131,13 +131,13 @@ export const defaultAppConfig = {
   }],
 
   controls: [{
-    id: 'moveControls',
+    id: 'mapControls',
     label: 'Move and zoom',
-    excludeWhen: ({ appConfig }) => !appConfig.enableMoveControls,
-    mobile: moveControlsSlot,
-    tablet: moveControlsSlot,
-    desktop: moveControlsSlot,
-    render: MoveControls
+    excludeWhen: ({ appConfig }) => !appConfig.enableMapControls,
+    mobile: mapControlsSlot,
+    tablet: mapControlsSlot,
+    desktop: mapControlsSlot,
+    render: MapControls
   }],
 
   icons: [{
@@ -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/config/appConfig.test.js

@@ -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 moveControlsBtn = buttons.find(b => b.id === 'moveControls')
+  const mapControlsBtn = buttons.find(b => b.id === 'mapControls')
 
   // --- 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 (enableMoveControls)
+      // Branch B: Second part of OR is true (enableMapControls)
       expect(btn.excludeWhen({
-        appConfig: { enableZoomControls: true, enableMoveControls: true },
+        appConfig: { enableZoomControls: true, enableMapControls: true },
         appState: { interfaceType: 'mouse' }
       })).toBe(true)
 
       // Branch C: Third part of OR is true (interfaceType === 'touch')
       expect(btn.excludeWhen({
-        appConfig: { enableZoomControls: true, enableMoveControls: false },
+        appConfig: { enableZoomControls: true, enableMapControls: false },
         appState: { interfaceType: 'touch' }
       })).toBe(true)
 
       // Branch D: All parts are false (Result: false)
       expect(btn.excludeWhen({
-        appConfig: { enableZoomControls: true, enableMoveControls: false },
+        appConfig: { enableZoomControls: true, enableMapControls: false },
         appState: { interfaceType: 'mouse' }
       })).toBe(false)
     })
@@ -183,37 +183,37 @@ describe('defaultAppConfig', () => {
   })
 
   // --- 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('covers all branches of mapControls excludeWhen', () => {
+    expect(mapControlsBtn.excludeWhen({ appConfig: { enableMapControls: false } })).toBe(true)
+    expect(mapControlsBtn.excludeWhen({ appConfig: { enableMapControls: true } })).toBe(false)
   })
 
-  it('moveControls ariaControls resolves the control element id', () => {
-    expect(moveControlsBtn.ariaControls({ appConfig: { id: 'im' } })).toBe('im-move-controls-content')
+  it('mapControls ariaControls resolves the control element id', () => {
+    expect(mapControlsBtn.ariaControls({ appConfig: { id: 'im' } })).toBe('im-map-controls-content')
   })
 
-  it('moveControls onClick toggles TOGGLE_BUTTON_EXPANDED based on current state', () => {
+  it('mapControls onClick toggles TOGGLE_BUTTON_EXPANDED based on current state', () => {
     const dispatch = jest.fn()
 
-    moveControlsBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set() } })
+    mapControlsBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set() } })
     expect(dispatch).toHaveBeenCalledWith({
       type: 'TOGGLE_BUTTON_EXPANDED',
-      payload: { id: 'moveControls', isExpanded: true }
+      payload: { id: 'mapControls', isExpanded: true }
     })
 
     dispatch.mockClear()
-    moveControlsBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set(['moveControls']) } })
+    mapControlsBtn.onClick({}, { appState: { dispatch, expandedButtons: new Set(['mapControls']) } })
     expect(dispatch).toHaveBeenCalledWith({
       type: 'TOGGLE_BUTTON_EXPANDED',
-      payload: { id: 'moveControls', isExpanded: false }
+      payload: { id: 'mapControls', isExpanded: 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)
+  it('covers all branches of mapControls control excludeWhen', () => {
+    const control = defaultAppConfig.controls.find(c => c.id === 'mapControls')
+    expect(control.excludeWhen({ appConfig: { enableMapControls: false } })).toBe(true)
+    expect(control.excludeWhen({ appConfig: { enableMapControls: true } })).toBe(false)
   })
 
   // --- SUPPLEMENTARY CONFIGS ---

package/src/config/defaults.js

@@ -16,7 +16,7 @@ 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,
-  enableMoveControls: true,
+  enableMapControls: true,
   enableZoomControls: true,
   genericErrorText: 'There was a problem loading the map. Please try again later.',
   hasExitButton: false,
@@ -32,7 +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.',
+  mapControlsHintText: '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/events.js

@@ -145,14 +145,14 @@ export const EVENTS = {
   MAP_SET_STYLE: 'map:setstyle',
   /** @internal Set map size. Payload: { width, height } */
   MAP_SET_SIZE: 'map:setsize',
-  /** @internal Set the accessible features list. Payload: { items: { id: string, label: string }[] } */
-  MAP_SET_FEATURES: 'map:setfeatures',
-  /** @internal Suppress/restore the accessible features list. Payload: { suppressed: boolean } */
-  MAP_SET_FEATURES_SUPPRESSED: 'map:setfeaturessuppressed',
-  /** @internal Set the active feature in the accessible features list. Payload: { id: string | null } */
-  MAP_SET_ACTIVE_FEATURE: 'map:setactivefeature',
-  /** @internal Select the active listbox feature as the real selection (Enter key). Payload: none */
-  MAP_SELECT_FEATURE: 'map:selectfeature',
+  /** @internal Set the accessible spatial list's items. Payload: { items: { id: string, label: string }[], multiselectable: boolean, label?: string } */
+  MAP_SET_SPATIAL_LIST: 'map:setspatiallist',
+  /** @internal Suppress/restore the accessible spatial list. Payload: { suppressed: boolean } */
+  MAP_SET_SPATIAL_LIST_SUPPRESSED: 'map:setspatiallistsuppressed',
+  /** @internal Set the active item in the accessible spatial list (roving tabindex position). Payload: { id: string | null } */
+  MAP_SET_ACTIVE_ITEM: 'map:setactiveitem',
+  /** @internal Select the active spatial list item as the real selection (Enter key). Payload: none */
+  MAP_SELECT_ITEM: 'map:selectitem',
   /** @internal Set pixel ratio. Payload: pixelRatio */
   MAP_SET_PIXEL_RATIO: 'map:setpixelratio',
   /** @internal Fit the map to a bounding box. Payload: [west, south, east, north] */

package/src/scss/main.scss

@@ -29,9 +29,9 @@
 @use '../App/components/Hints/Hints.module';
 @use '../App/components/CrossHair/CrossHair.module';
 @use '../App/components/Markers/Markers.module';
-@use '../App/components/Viewport/Features.module';
+@use '../App/components/Viewport/SpatialList.module';
 @use '../App/components/Actions/Actions.module';
-@use '../App/components/MoveControls/MoveControls.module';
+@use '../App/components/MapControls/MapControls.module';
 
 // Components that dont have a corresponding React Component
 @use 'components';

package/src/scss/tools/_govuk-content.scss

@@ -0,0 +1,29 @@
+// ===================================================
+// Tool: govuk-content-fallback-colors
+// ===================================================
+// Resets GOV.UK Frontend's own text-colour classes back onto our theme tokens, since they set
+// colour explicitly rather than inheriting it. !important wins against a third-party stylesheet
+// whose specificity and load order we don't control. Deliberately-coloured components (tags,
+// error/warning text, buttons, .govuk-link--inverse/--text-colour/--muted) are left untouched so
+// their built-in contrast pairing isn't broken.
+// stylelint-disable declaration-no-important -- resetting a third-party stylesheet's own colours, see comment above
+@mixin govuk-content-fallback-colors {
+    :is(
+        .govuk-body, .govuk-body-l, .govuk-body-m, .govuk-body-s, .govuk-body-xs,
+        .govuk-heading-xl, .govuk-heading-l, .govuk-heading-m, .govuk-heading-s,
+        .govuk-list, .govuk-label, .govuk-fieldset__legend,
+        .govuk-table, .govuk-table__cell, .govuk-table__header
+    ) {
+        color: var(--foreground-color) !important;
+    }
+
+    // GOV.UK Frontend renders these as its muted grey, matching our --secondary-text-color.
+    :is(.govuk-hint, .govuk-caption-xl, .govuk-caption-l, .govuk-caption-m, .govuk-caption-s) {
+        color: var(--secondary-text-color) !important;
+    }
+
+    .govuk-link:is(:link, :visited) {
+        color: var(--content-link-color) !important;
+    }
+}
+// stylelint-enable declaration-no-important

package/src/scss/tools/_index.scss

@@ -1,2 +1,3 @@
 @forward 'border-focus';
-@forward 'link-focus';
+@forward 'link-focus';
+@forward 'govuk-content';

package/src/test-utils.js

@@ -37,6 +37,14 @@ export const createMockRegistries = (overrides = {}) => {
       registerKeyboardShortcut: jest.fn(),
       setProviderSupportedShortcuts: jest.fn(),
       getKeyboardShortcuts: jest.fn(() => [])
+    },
+    spatialListRegistry: {
+      registerItemProvider: jest.fn(),
+      unregisterItemProvider: jest.fn(),
+      claimExclusive: jest.fn(),
+      releaseExclusive: jest.fn(),
+      notifyItemsChanged: jest.fn(),
+      clear: jest.fn()
     }
   }
 }

package/src/types.js

@@ -306,10 +306,10 @@
  * Get the dimensions of the visible map area as a formatted string (e.g., '400m by 750m').
  *
  * @property {(from: [number, number], to: [number, number]) => string} getCardinalMove
- * Get cardinal direction and distance between two coordinates ([lng, lat] or [easting, northing] depending on the crs of the map provider). Returns a formatted string (e.g., 'north 400m' or 'south 400m, west 750m').
+ * Get cardinal direction and distance between two coordinates ([lng, lat] or [easting, northing] depending on the crs of the map provider). Returns a formatted string (e.g., 'north 400 metres' or 'south 400 metres, west 750 metres').
  *
  * @property {() => number} getResolution
- * Get map resolution in meters per pixel.
+ * Get map resolution in metres per pixel.
  *
  * @property {(coords: [number, number]) => { x: number, y: number }} mapToScreen
  * Convert map coordinates ([lng, lat] or [easting, northing] depending on the crs of the map provider) to screen pixel position (x from left edge, y from top edge of viewport).
@@ -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.
  *
@@ -725,16 +765,18 @@
  * @property {boolean} [enableFullscreen=false]
  * Whether a toggle fullscreen button is displayed.
  *
- * @property {boolean} [enableMoveControls=true]
- * Whether the move controls are displayed — a button that reveals directional pan,
- * zoom, and step-size buttons, providing a non-dragging alternative to panning
- * and zooming the map (WCAG 2.5.7). Unlike enableZoomControls, it remains visible
- * when the interface type is 'touch'. When enabled, enableZoomControls' buttons
- * are hidden to avoid duplicating zoom controls.
+ * @property {boolean} [enableMapControls=true]
+ * Whether the map controls are displayed — a button that reveals on-screen move,
+ * zoom, and precision buttons, plus a target point, typically used to place or
+ * select features on the map without a drag gesture. This gives a non-dragging way
+ * to operate the map, for anyone who can't perform a drag/pinch gesture (e.g.
+ * switch access users) and for voice interfaces such as Voice Control, which can
+ * trigger a button click but not a drag. When enabled, enableZoomControls' buttons
+ * are hidden to avoid duplication.
  *
  * @property {boolean} [enableZoomControls=true]
  * Whether zoom control buttons are displayed. Not displayed when the interface
- * type is 'touch', or when enableMoveControls is enabled.
+ * type is 'touch', or when enableMapControls is enabled.
  *
  * @property {[number, number, number, number]} [extent]
  * Initial extent [minX, minY, maxX, maxY]. Equivalent to bounds; use whichever matches your map provider's terminology.
@@ -766,8 +808,8 @@
  * @property {string} [mapLabel='Interactive map']
  * Accessible label for the map, announced by screen readers. Also prefixed onto mapHintText, so give each map on a page a distinct label.
  *
- * @property {string} [moveControlsHintText]
- * Visually hidden text describing the move controls button, appended to keyboardHintText when enableMoveControls is true.
+ * @property {string} [mapControlsHintText]
+ * Visually hidden text describing the map controls button, appended to keyboardHintText when enableMapControls is true.
  *
  * @property {MapProviderDescriptor} [mapProvider]
  * A factory function that returns a map provider instance (e.g. maplibreProvider()).

package/src/utils/findNearestItemInDirection.js

@@ -0,0 +1,29 @@
+import { spatialNavigate } from './spatialNavigate.js'
+
+/**
+ * Item-list-shaped counterpart to spatialNavigate's raw pixel-array contract: given a list of
+ * items each carrying screen coordinates, finds the id of whichever one is spatially nearest
+ * to the current item in the given direction. Used to move roving-tabindex focus in a listbox
+ * spatially (Alt+Arrow) rather than sequentially (plain Arrow/Home/End) — the same items list
+ * already built for sequential navigation works here unchanged, whether it holds map features
+ * or (in future) something else entirely, as long as each item carries x/y.
+ *
+ * Items missing x/y are skipped — they have no screen position to navigate by. If none of the
+ * items have coordinates, or the list is empty, currentId is returned unchanged.
+ *
+ * @param {Array<{id: string, x?: number, y?: number}>} items
+ * @param {string|null} currentId
+ * @param {'ArrowUp'|'ArrowDown'|'ArrowLeft'|'ArrowRight'} direction
+ * @returns {string|null} The id to move to — currentId unchanged if nothing qualifies.
+ */
+export function findNearestItemInDirection (items, currentId, direction) {
+  const positioned = items.filter(item => item.x != null && item.y != null)
+  if (!positioned.length) {
+    return currentId
+  }
+  const pixels = positioned.map(item => [item.x, item.y])
+  const currentIndex = positioned.findIndex(item => item.id === currentId)
+  const start = currentIndex === -1 ? pixels[0] : pixels[currentIndex]
+  const nextIndex = spatialNavigate(start, pixels, direction)
+  return positioned[nextIndex]?.id ?? currentId
+}

package/src/utils/findNearestItemInDirection.test.js

@@ -0,0 +1,67 @@
+import { findNearestItemInDirection } from './findNearestItemInDirection.js'
+
+describe('findNearestItemInDirection', () => {
+  const items = [
+    { id: 'center', x: 0, y: 0 },
+    { id: 'up', x: 0, y: -10 },
+    { id: 'down', x: 0, y: 10 },
+    { id: 'left', x: -10, y: 0 },
+    { id: 'right', x: 10, y: 0 }
+  ]
+
+  test.each([
+    ['ArrowUp', 'up'],
+    ['ArrowDown', 'down'],
+    ['ArrowLeft', 'left'],
+    ['ArrowRight', 'right']
+  ])('finds the nearest item to the %s of the current one', (direction, expectedId) => {
+    expect(findNearestItemInDirection(items, 'center', direction)).toBe(expectedId)
+  })
+
+  test('returns the current id unchanged when nothing qualifies in that direction', () => {
+    const single = [{ id: 'only', x: 0, y: 0 }]
+    expect(findNearestItemInDirection(single, 'only', 'ArrowUp')).toBe('only')
+  })
+
+  test('returns currentId unchanged when the item list is empty', () => {
+    expect(findNearestItemInDirection([], 'anything', 'ArrowUp')).toBe('anything')
+  })
+
+  test('skips items with no screen coordinates', () => {
+    const withUnpositioned = [
+      { id: 'center', x: 0, y: 0 },
+      { id: 'no-coords' },
+      { id: 'up', x: 0, y: -10 }
+    ]
+    expect(findNearestItemInDirection(withUnpositioned, 'center', 'ArrowUp')).toBe('up')
+  })
+
+  test('returns currentId unchanged when no item has coordinates at all', () => {
+    const noneWithCoords = [{ id: 'a' }, { id: 'b' }]
+    expect(findNearestItemInDirection(noneWithCoords, 'a', 'ArrowUp')).toBe('a')
+  })
+
+  test('treats an unresolvable currentId as starting from the first positioned item', () => {
+    expect(findNearestItemInDirection(items, 'not-in-list', 'ArrowRight')).toBe('right')
+  })
+})
+
+// spatialNavigate's own contract guarantees a valid index in practice (see its own tests), so
+// this can't be reached through findNearestItemInDirection's real dependency — mocked here,
+// matching labels.test.js's identical fallback test for navigateToNextLabel, purely to prove
+// the defensive `?? currentId` itself degrades gracefully rather than crashing if that
+// guarantee were ever weakened.
+describe('findNearestItemInDirection — defensive fallback', () => {
+  afterEach(() => {
+    jest.dontMock('./spatialNavigate.js')
+    jest.resetModules()
+  })
+
+  test('falls back to currentId if spatialNavigate ever returns an out-of-range index', () => {
+    jest.resetModules()
+    jest.doMock('./spatialNavigate.js', () => ({ spatialNavigate: () => -1 }))
+    const { findNearestItemInDirection: fn } = require('./findNearestItemInDirection.js')
+    const items = [{ id: 'center', x: 0, y: 0 }, { id: 'up', x: 0, y: -10 }]
+    expect(fn(items, 'center', 'ArrowUp')).toBe('center')
+  })
+})

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)}`