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

package/src/App/components/{MoveControl/MoveControl.jsx → MoveControls/MoveControls.jsx}

@@ -18,13 +18,13 @@ const ZOOM_ACTIONS = [
   { id: 'nudgeZoomOut', label: 'Zoom out', announceLabel: 'Zoomed out', method: 'zoomOut' }
 ]
 
-export const MoveControl = () => {
+export const MoveControls = () => {
   const { id: appId, mapProvider, panDelta, nudgePanDelta, zoomDelta, nudgeZoomDelta } = useConfig()
   const { dispatch, expandedButtons, nudgeStepSize, interfaceType, layoutRefs } = useApp()
   const { isAtMaxZoom, isAtMinZoom } = useMap()
   const { announce } = useService()
 
-  const isOpen = expandedButtons.has('moveControl')
+  const isOpen = expandedButtons.has('moveControls')
   const firstDirectionButtonId = `${appId}-pan-up`
 
   useEffect(() => {
@@ -41,7 +41,7 @@ export const MoveControl = () => {
   // Registry buttons (declared via a plugin's manifest) auto-return focus to the map
   // viewport after a click (see createButtonClickHandler in mapButtons.js) unless
   // marked keepFocus — which is how e.g. draw's own toolbar buttons never leave
-  // keyboard shortcuts (like arrow-key vertex nudging) stranded afterward. MoveControl
+  // keyboard shortcuts (like arrow-key vertex nudging) stranded afterward. MoveControls
   // renders its own buttons directly, bypassing that mechanism entirely, so it has to
   // replicate the same return-to-viewport behaviour itself. But unlike a one-off
   // action button, the D-pad is meant to be pressed repeatedly — a keyboard/switch
@@ -70,7 +70,7 @@ export const MoveControl = () => {
 
     // Any plugin can claim the D-pad for something other than panning the map (e.g.
     // moving a selected draw vertex) by setting mapProvider.activeMoveTarget — a
-    // generic { move(dx, dy, isLargeStep), label? } contract. MoveControl doesn't
+    // generic { move(dx, dy, isLargeStep), label? } contract. MoveControls doesn't
     // know or care what's claiming it; it just checks for a claimant before
     // defaulting to its own panBy behaviour. Read fresh on every click rather than
     // subscribed to reactively, since it's a plain mapProvider property, not state.
@@ -107,7 +107,7 @@ export const MoveControl = () => {
   // first tabbing all the way back to the map. Handling arrow keys here — while
   // focus is anywhere within this control, not just on a direction button — covers
   // that directly, without needing draw's (or the app's own) keyboard-shortcut
-  // guards to special-case MoveControl's buttons. Only arrow keys are handled;
+  // guards to special-case MoveControls' buttons. Only arrow keys are handled;
   // other shortcuts (delete/escape/undo) still require focus on the viewport,
   // which mouse/touch users already get back automatically after any click here.
   const handleContainerKeyDown = (e) => {
@@ -120,12 +120,12 @@ export const MoveControl = () => {
   }
 
   const containerClassName = [
-    'im-c-move-control',
-    !isOpen && 'im-c-move-control--collapsed'
+    'im-c-move-controls',
+    !isOpen && 'im-c-move-controls--collapsed'
   ].filter(Boolean).join(' ')
 
   const directionsGroup = (
-    <div key='directions' role='group' aria-label='Direction controls' className='im-c-move-control__directions'>{/* NOSONAR - div with role="group" is correct for a button group */}
+    <div key='directions' role='group' aria-label='Direction controls' className='im-c-move-controls__directions'>{/* NOSONAR - div with role="group" is correct for a button group */}
       {DIRECTIONS.map(({ id, verb, dx, dy }) => (
         <MapButton
           key={id}
@@ -154,7 +154,7 @@ export const MoveControl = () => {
   )
 
   const zoomGroup = (
-    <div key='zoom' role='group' aria-label='Zoom controls' className='im-c-move-control__zoom'>{/* NOSONAR - div with role="group" is correct for a button group */}
+    <div key='zoom' role='group' aria-label='Zoom controls' className='im-c-move-controls__zoom'>{/* NOSONAR - div with role="group" is correct for a button group */}
       {ZOOM_ACTIONS.map(({ id, label, announceLabel, method }) => (
         <MapButton
           key={id}
@@ -169,7 +169,7 @@ export const MoveControl = () => {
   )
 
   return (
-    <div id={`${appId}-move-control-content`} className={containerClassName} onKeyDown={handleContainerKeyDown}>{/* NOSONAR - only catches arrow-key bubbling from the real, already-focusable button descendants below; the div itself needs no role/tabIndex */}
+    <div id={`${appId}-move-controls-content`} className={containerClassName} onKeyDown={handleContainerKeyDown} data-map-keyboard-scope>{/* NOSONAR - only catches arrow-key bubbling from the real, already-focusable button descendants below; the div itself needs no role/tabIndex */}
       {directionsGroup}
       {zoomGroup}
     </div>

package/src/App/components/{MoveControl/MoveControl.module.scss → MoveControls/MoveControls.module.scss}

@@ -1,62 +1,62 @@
 @use '../../../scss/tools/index' as tools;
 
 // ===================================================
-// Component: MoveControl
+// Component: MoveControls
 // ===================================================
 
 // 1. Base styles
-.im-c-move-control {
+.im-c-move-controls {
     display: flex;
     flex-direction: column;
     align-items: center;
     gap: var(--divider-gap);
 }
 
-.im-c-move-control.im-c-move-control--collapsed {
+.im-c-move-controls.im-c-move-controls--collapsed {
     display: none;
 }
 
 // 2. Elements
-.im-c-move-control__directions {
+.im-c-move-controls__directions {
     display: grid;
     grid-template-columns: repeat(3, var(--button-size));
     grid-template-rows: repeat(3, var(--button-size));
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-up {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-up {
     grid-column: 2;
     grid-row: 1;
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-left {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-left {
     grid-column: 1;
     grid-row: 2;
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-right {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-right {
     grid-column: 3;
     grid-row: 2;
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-down {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-down {
     grid-column: 2;
     grid-row: 3;
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--nudge-step-toggle {
+.im-c-move-controls__directions .im-c-button-wrapper--nudge-step-toggle {
     grid-column: 2;
     grid-row: 2;
 }
 
-.im-c-move-control__directions .im-c-map-button--pan-up svg {
+.im-c-move-controls__directions .im-c-map-button--pan-up svg {
     transform: rotate(180deg);
 }
 
-.im-c-move-control__directions .im-c-map-button--pan-left svg {
+.im-c-move-controls__directions .im-c-map-button--pan-left svg {
     transform: rotate(90deg);
 }
 
-.im-c-move-control__directions .im-c-map-button--pan-right svg {
+.im-c-move-controls__directions .im-c-map-button--pan-right svg {
     transform: rotate(-90deg);
 }
 
@@ -66,35 +66,35 @@
 // express a plus-shaped grid where the centre button touches all four neighbours —
 // clip-path is set directly per button instead, clipping only the side(s) where it
 // touches another button and leaving the exposed side(s) showing the shadow as normal.
-.im-c-move-control__directions .im-c-button-wrapper--pan-up .im-c-map-button::before {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-up .im-c-map-button::before {
     clip-path: inset(-20px -20px 0 -20px); // touches nudge-step-toggle below
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-left .im-c-map-button::before {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-left .im-c-map-button::before {
     clip-path: inset(-20px 0 -20px -20px); // touches nudge-step-toggle to the right
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-right .im-c-map-button::before {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-right .im-c-map-button::before {
     clip-path: inset(-20px -20px -20px 0); // touches nudge-step-toggle to the left
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--pan-down .im-c-map-button::before {
+.im-c-move-controls__directions .im-c-button-wrapper--pan-down .im-c-map-button::before {
     clip-path: inset(0 -20px -20px -20px); // touches nudge-step-toggle above
 }
 
-.im-c-move-control__directions .im-c-button-wrapper--nudge-step-toggle .im-c-map-button::before {
+.im-c-move-controls__directions .im-c-button-wrapper--nudge-step-toggle .im-c-map-button::before {
     clip-path: inset(0); // touches all four neighbours
 }
 
 // Same inverted "pressed" treatment already used for actions-slot toggle buttons
 // (e.g. draw's Snap toggle) — reused here so Nudge mode reads consistently active.
-.im-c-move-control .im-c-map-button[aria-pressed="true"] {
+.im-c-move-controls .im-c-map-button[aria-pressed="true"] {
     color: var(--pressed-button-foreground-color);
     border-color: var(--pressed-button-border-color);
     background-color: var(--pressed-button-background-color);
 }
 
-// The trigger lives in the right-top slot, outside .im-c-move-control, so this is
+// The trigger lives in the right-top slot, outside .im-c-move-controls, so this is
 // its own top-level rule. Same colour treatment as above, but keyed off
 // aria-expanded rather than aria-pressed — the trigger is correctly a disclosure
 // button (it reveals the control below), not a toggle button, so it doesn't carry
@@ -106,26 +106,26 @@
 // hovering the expanded trigger button was a coin-flip decided by cascade order —
 // one cssnano mergeRules reshuffle in production and hover started winning,
 // showing the hover tint instead of the pressed colours. The sibling
-// .im-c-move-control .im-c-map-button[aria-pressed="true"] rule above never had
+// .im-c-move-controls .im-c-map-button[aria-pressed="true"] rule above never had
 // this problem (it's already (0,3,0), safely ahead of hover); this one needed the
 // same headroom.
-.im-c-map-button.im-c-map-button--move-control[aria-expanded="true"] {
+.im-c-map-button.im-c-map-button--move-controls[aria-expanded="true"] {
     color: var(--pressed-button-foreground-color);
     border-color: var(--pressed-button-border-color);
     background-color: var(--pressed-button-background-color);
 }
 
-.im-c-move-control__zoom {
+.im-c-move-controls__zoom {
     display: flex;
     flex-direction: row;
 }
 
 // A simple two-item linear row, so the standard button-group corner/shadow treatment
 // applies directly (matches .im-o-app__top's first/last-child pattern).
-.im-c-move-control__zoom .im-c-button-wrapper--nudge-zoom-in .im-c-map-button {
+.im-c-move-controls__zoom .im-c-button-wrapper--nudge-zoom-in .im-c-map-button {
     @include tools.border-focus-corner-override($corners: 'left');
 }
 
-.im-c-move-control__zoom .im-c-button-wrapper--nudge-zoom-out .im-c-map-button {
+.im-c-move-controls__zoom .im-c-button-wrapper--nudge-zoom-out .im-c-map-button {
     @include tools.border-focus-corner-override($corners: 'right');
 }

package/src/App/components/{MoveControl/MoveControl.test.jsx → MoveControls/MoveControls.test.jsx}

@@ -1,6 +1,6 @@
 import React from 'react'
 import { render, screen, fireEvent } from '@testing-library/react'
-import { MoveControl } from './MoveControl.jsx'
+import { MoveControls } from './MoveControls.jsx'
 import { useApp } from '../../store/appContext.js'
 import { useConfig } from '../../store/configContext.js'
 import { useMap } from '../../store/mapContext.js'
@@ -11,19 +11,19 @@ jest.mock('../../store/configContext.js', () => ({ useConfig: jest.fn() }))
 jest.mock('../../store/mapContext.js', () => ({ useMap: jest.fn() }))
 jest.mock('../../store/serviceContext.js', () => ({ useService: jest.fn() }))
 
-describe('MoveControl', () => {
+describe('MoveControls', () => {
   let dispatch
   let mapProvider
   let announce
 
   // MapButton and Tooltip also read from useApp() (buttonRefs, interfaceType), so every
-  // mockReturnValue needs to carry these alongside the fields MoveControl itself reads.
+  // mockReturnValue needs to carry these alongside the fields MoveControls itself reads.
   const buildAppState = (overrides) => ({
     buttonRefs: { current: {} },
     interfaceType: 'mouse',
     breakpoint: 'desktop',
     dispatch,
-    expandedButtons: new Set(['moveControl']),
+    expandedButtons: new Set(['moveControls']),
     nudgeStepSize: 'large',
     layoutRefs: { viewportRef: { current: { focus: jest.fn() } } },
     ...overrides
@@ -50,29 +50,29 @@ describe('MoveControl', () => {
   afterEach(() => jest.clearAllMocks())
 
   it('renders with the id matching the trigger button aria-controls value', () => {
-    const { container } = render(<MoveControl />)
-    expect(container.querySelector('#im-move-control-content')).toBeInTheDocument()
+    const { container } = render(<MoveControls />)
+    expect(container.querySelector('#im-move-controls-content')).toBeInTheDocument()
   })
 
-  it('is not visually collapsed when moveControl is expanded', () => {
-    const { container } = render(<MoveControl />)
-    expect(container.querySelector('.im-c-move-control--collapsed')).not.toBeInTheDocument()
+  it('is not visually collapsed when moveControls is expanded', () => {
+    const { container } = render(<MoveControls />)
+    expect(container.querySelector('.im-c-move-controls--collapsed')).not.toBeInTheDocument()
   })
 
   it('moves focus to the first direction button when the control opens', () => {
-    const { rerender } = render(<MoveControl />)
+    const { rerender } = render(<MoveControls />)
     useApp.mockReturnValue(buildAppState({ expandedButtons: new Set() }))
-    rerender(<MoveControl />)
+    rerender(<MoveControls />)
 
-    useApp.mockReturnValue(buildAppState({ expandedButtons: new Set(['moveControl']) }))
-    rerender(<MoveControl />)
+    useApp.mockReturnValue(buildAppState({ expandedButtons: new Set(['moveControls']) }))
+    rerender(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Move up' })).toHaveFocus()
   })
 
   it('renders the directions group before the zoom group at every breakpoint', () => {
     ['mobile', 'tablet', 'desktop'].forEach(breakpoint => {
       useApp.mockReturnValue(buildAppState({ breakpoint }))
-      const { container, unmount } = render(<MoveControl />)
+      const { container, unmount } = render(<MoveControls />)
       const groups = container.querySelectorAll('[role="group"]')
       expect(groups[0]).toHaveAttribute('aria-label', 'Direction controls')
       expect(groups[1]).toHaveAttribute('aria-label', 'Zoom controls')
@@ -80,14 +80,14 @@ describe('MoveControl', () => {
     })
   })
 
-  it('is collapsed when moveControl is not expanded', () => {
+  it('is collapsed when moveControls is not expanded', () => {
     useApp.mockReturnValue(buildAppState({ expandedButtons: new Set() }))
-    const { container } = render(<MoveControl />)
-    expect(container.querySelector('.im-c-move-control--collapsed')).toBeInTheDocument()
+    const { container } = render(<MoveControls />)
+    expect(container.querySelector('.im-c-move-controls--collapsed')).toBeInTheDocument()
   })
 
   it('labels direction buttons "Move" and pans by the large delta by default', () => {
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
     expect(mapProvider.panBy).toHaveBeenCalledWith([100, 0])
     expect(announce).toHaveBeenCalledWith('Moved right')
@@ -95,7 +95,7 @@ describe('MoveControl', () => {
 
   it('labels direction buttons "Nudge" and pans by the small delta when nudgeStepSize is small', () => {
     useApp.mockReturnValue(buildAppState({ nudgeStepSize: 'small' }))
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Nudge up' }))
     expect(mapProvider.panBy).toHaveBeenCalledWith([0, -5])
     expect(announce).toHaveBeenCalledWith('Nudged up')
@@ -103,7 +103,7 @@ describe('MoveControl', () => {
 
   it('routes direction clicks to mapProvider.activeMoveTarget instead of panning, when a plugin has claimed it', () => {
     mapProvider.activeMoveTarget = { move: jest.fn(), label: 'vertex' }
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
     expect(mapProvider.activeMoveTarget.move).toHaveBeenCalledWith(1, 0, true)
     expect(mapProvider.panBy).not.toHaveBeenCalled()
@@ -112,22 +112,22 @@ describe('MoveControl', () => {
 
   it('falls back to panning once activeMoveTarget is released', () => {
     mapProvider.activeMoveTarget = { move: jest.fn(), label: 'vertex' }
-    const { rerender } = render(<MoveControl />)
+    const { rerender } = render(<MoveControls />)
     mapProvider.activeMoveTarget = null
-    rerender(<MoveControl />)
+    rerender(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
     expect(mapProvider.panBy).toHaveBeenCalledWith([100, 0])
   })
 
   it('omits the target label from the announcement when activeMoveTarget has none', () => {
     mapProvider.activeMoveTarget = { move: jest.fn() }
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Move up' }))
     expect(announce).toHaveBeenCalledWith('Moved up')
   })
 
   it('zooms in and out by the large delta by default and announces the action', () => {
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
     expect(mapProvider.zoomIn).toHaveBeenCalledWith(1)
     expect(announce).toHaveBeenCalledWith('Zoomed in')
@@ -139,26 +139,26 @@ describe('MoveControl', () => {
 
   it('zooms by the small delta when nudgeStepSize is small', () => {
     useApp.mockReturnValue(buildAppState({ nudgeStepSize: 'small' }))
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
     expect(mapProvider.zoomIn).toHaveBeenCalledWith(0.1)
   })
 
   it('disables the zoom in button at max zoom, and zoom out at min zoom', () => {
     useMap.mockReturnValue({ isAtMaxZoom: true, isAtMinZoom: false })
-    const { rerender } = render(<MoveControl />)
+    const { rerender } = render(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Zoom in' })).toHaveAttribute('aria-disabled', 'true')
     expect(screen.getByRole('button', { name: 'Zoom out' })).not.toHaveAttribute('aria-disabled')
 
     useMap.mockReturnValue({ isAtMaxZoom: false, isAtMinZoom: true })
-    rerender(<MoveControl />)
+    rerender(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Zoom in' })).not.toHaveAttribute('aria-disabled')
     expect(screen.getByRole('button', { name: 'Zoom out' })).toHaveAttribute('aria-disabled', 'true')
   })
 
   it('does not zoom when the relevant button is disabled at max/min zoom', () => {
     useMap.mockReturnValue({ isAtMaxZoom: true, isAtMinZoom: true })
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
     fireEvent.click(screen.getByRole('button', { name: 'Zoom out' }))
     expect(mapProvider.zoomIn).not.toHaveBeenCalled()
@@ -177,7 +177,7 @@ describe('MoveControl', () => {
     it('returns focus to the viewport after panning on mouse/touch, so arrow-key shortcuts elsewhere are not left stranded on the D-pad button', () => {
       const appState = buildAppState({ interfaceType: 'mouse' })
       useApp.mockReturnValue(appState)
-      render(<MoveControl />)
+      render(<MoveControls />)
 
       fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
       expect(appState.layoutRefs.viewportRef.current.focus).toHaveBeenCalled()
@@ -185,19 +185,19 @@ describe('MoveControl', () => {
 
     it('keeps focus on the button when driven by keyboard, so repeated Enter/Space presses do not require re-tabbing', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
       expect(rafSpy).not.toHaveBeenCalled()
     })
 
     it('also returns focus after zooming on mouse/touch, but not on keyboard', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'mouse' }))
-      const { rerender } = render(<MoveControl />)
+      const { rerender } = render(<MoveControls />)
       fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
       expect(rafSpy).toHaveBeenCalledTimes(1)
 
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
-      rerender(<MoveControl />)
+      rerender(<MoveControls />)
       fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
       expect(rafSpy).toHaveBeenCalledTimes(1)
     })
@@ -205,7 +205,7 @@ describe('MoveControl', () => {
     it('also returns focus after a vertex nudge via activeMoveTarget on mouse/touch', () => {
       mapProvider.activeMoveTarget = { move: jest.fn(), label: 'vertex' }
       useApp.mockReturnValue(buildAppState({ interfaceType: 'touch' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
       expect(rafSpy).toHaveBeenCalledTimes(1)
     })
@@ -217,7 +217,7 @@ describe('MoveControl', () => {
     // arrow keys without first tabbing all the way back out to the map.
     it('pans the map on an arrow key, regardless of which button currently has focus', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       // Focus a button unrelated to the direction being pressed, to prove this
       // isn't just reading the focused button's own handler.
       fireEvent.focus(screen.getByRole('button', { name: 'Zoom in' }))
@@ -229,7 +229,7 @@ describe('MoveControl', () => {
     it('routes the arrow key through activeMoveTarget when a plugin has claimed the control', () => {
       mapProvider.activeMoveTarget = { move: jest.fn(), label: 'vertex' }
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.keyDown(screen.getByRole('button', { name: 'Move up' }), { key: 'ArrowUp' })
       expect(mapProvider.activeMoveTarget.move).toHaveBeenCalledWith(0, -1, true)
       expect(mapProvider.panBy).not.toHaveBeenCalled()
@@ -237,14 +237,14 @@ describe('MoveControl', () => {
 
     it('ignores non-arrow keys, leaving default behaviour (e.g. Enter/Space activating the focused button) untouched', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.keyDown(screen.getByRole('button', { name: 'Move up' }), { key: 'Enter' })
       expect(mapProvider.panBy).not.toHaveBeenCalled()
     })
 
     it('shift+arrow overrides the Precision toggle to the small step, matching the map\'s own native keyboard shortcuts', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard', nudgeStepSize: 'large' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.keyDown(screen.getByRole('button', { name: 'Move right' }), { key: 'ArrowRight', shiftKey: true })
       expect(mapProvider.panBy).toHaveBeenCalledWith([5, 0])
       expect(announce).toHaveBeenCalledWith('Nudged right')
@@ -252,7 +252,7 @@ describe('MoveControl', () => {
 
     it('shift+arrow still resolves to the small step when Precision is already on (idempotent, not a toggle-relative flip)', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard', nudgeStepSize: 'small' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.keyDown(screen.getByRole('button', { name: 'Nudge right' }), { key: 'ArrowRight', shiftKey: true })
       expect(mapProvider.panBy).toHaveBeenCalledWith([5, 0])
       expect(announce).toHaveBeenCalledWith('Nudged right')
@@ -261,14 +261,14 @@ describe('MoveControl', () => {
     it('shift+arrow overrides activeMoveTarget.move to the small step too', () => {
       mapProvider.activeMoveTarget = { move: jest.fn(), label: 'vertex' }
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard', nudgeStepSize: 'large' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.keyDown(screen.getByRole('button', { name: 'Move up' }), { key: 'ArrowUp', shiftKey: true })
       expect(mapProvider.activeMoveTarget.move).toHaveBeenCalledWith(0, -1, false)
     })
 
     it('arrow key without shift still follows the Precision toggle as before', () => {
       useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard', nudgeStepSize: 'large' }))
-      render(<MoveControl />)
+      render(<MoveControls />)
       fireEvent.keyDown(screen.getByRole('button', { name: 'Move right' }), { key: 'ArrowRight' })
       expect(mapProvider.panBy).toHaveBeenCalledWith([100, 0])
       expect(announce).toHaveBeenCalledWith('Moved right')
@@ -276,11 +276,11 @@ describe('MoveControl', () => {
   })
 
   it('has a stable "Precision" label regardless of state', () => {
-    const { rerender } = render(<MoveControl />)
+    const { rerender } = render(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Precision' })).toBeInTheDocument()
 
     useApp.mockReturnValue(buildAppState({ nudgeStepSize: 'small' }))
-    rerender(<MoveControl />)
+    rerender(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Precision' })).toBeInTheDocument()
   })
 
@@ -294,29 +294,29 @@ describe('MoveControl', () => {
       return document.getElementById(button.getAttribute('aria-labelledby'))
     }
 
-    const { rerender } = render(<MoveControl />)
+    const { rerender } = render(<MoveControls />)
     let tooltip = getOwnTooltip()
     expect(tooltip.querySelector('[aria-hidden="true"]')).toHaveTextContent('(Off)')
     expect(tooltip).toHaveTextContent('Precision (Off)')
 
     useApp.mockReturnValue(buildAppState({ nudgeStepSize: 'small' }))
-    rerender(<MoveControl />)
+    rerender(<MoveControls />)
     tooltip = getOwnTooltip()
     expect(tooltip.querySelector('[aria-hidden="true"]')).toHaveTextContent('(On)')
     expect(tooltip).toHaveTextContent('Precision (On)')
   })
 
   it('reflects precision mode via aria-pressed, not via label changes', () => {
-    const { rerender } = render(<MoveControl />)
+    const { rerender } = render(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Precision' })).toHaveAttribute('aria-pressed', 'false')
 
     useApp.mockReturnValue(buildAppState({ nudgeStepSize: 'small' }))
-    rerender(<MoveControl />)
+    rerender(<MoveControls />)
     expect(screen.getByRole('button', { name: 'Precision' })).toHaveAttribute('aria-pressed', 'true')
   })
 
   it('toggles precision on and announces it when currently in large-step mode', () => {
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Precision' }))
     expect(dispatch).toHaveBeenCalledWith({ type: 'TOGGLE_NUDGE_STEP' })
     expect(announce).toHaveBeenCalledWith('Precision on')
@@ -324,7 +324,7 @@ describe('MoveControl', () => {
 
   it('toggles precision off and announces it when currently in small-step mode', () => {
     useApp.mockReturnValue(buildAppState({ nudgeStepSize: 'small' }))
-    render(<MoveControl />)
+    render(<MoveControls />)
     fireEvent.click(screen.getByRole('button', { name: 'Precision' }))
     expect(dispatch).toHaveBeenCalledWith({ type: 'TOGGLE_NUDGE_STEP' })
     expect(announce).toHaveBeenCalledWith('Precision off')

package/src/App/components/Viewport/Viewport.jsx

@@ -18,7 +18,7 @@ import { Markers } from '../Markers/Markers'
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
 export const Viewport = () => {
-  const { id, mapProvider, mapLabel, keyboardHintText } = useConfig()
+  const { id, mapProvider, mapLabel, keyboardHintText, focusOnMount } = useConfig()
   const { mode, previousMode, layoutRefs, safeZoneInset, dispatch } = useApp()
   const { mapSize } = useMap()
   const { eventBus, hints } = useService()
@@ -62,6 +62,13 @@ export const Viewport = () => {
     }
   }, [mode])
 
+  // Focus the viewport on mount when opened by a genuine launcher click (see InteractiveMap.js's _handleButtonClick), never on an auto-load or resize.
+  useEffect(() => {
+    if (focusOnMount) {
+      layoutRefs.viewportRef?.current.focus()
+    }
+  }, [])
+
   return (
     <>
       <MapController mapContainerRef={mapContainerRef} />
@@ -71,6 +78,7 @@ export const Viewport = () => {
         aria-label={mapLabel}
         role='application'
         tabIndex='0' // nosonar
+        data-map-keyboard-scope
         onFocus={handleFocus}
         onBlur={handleBlur}
         ref={layoutRefs.viewportRef}

package/src/App/components/Viewport/Viewport.test.jsx

@@ -115,6 +115,17 @@ describe('Viewport rendering', () => {
     onViewportFocusChange(false)
     expect(hints.dismiss).toHaveBeenCalled()
   })
+
+  it('focuses the viewport on mount when focusOnMount is true', () => {
+    useConfig.mockReturnValueOnce({ ...useConfig(), focusOnMount: true })
+    const { viewport } = renderViewport()
+    expect(viewport).toHaveFocus()
+  })
+
+  it('does not focus the viewport on mount when focusOnMount is false', () => {
+    renderViewport()
+    expect(viewportEl).not.toHaveFocus()
+  })
 })
 
 describe('Viewport interactions', () => {

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