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

package/src/App/components/MoveControl/MoveControl.jsx

@@ -7,10 +7,10 @@ import { useService } from '../../store/serviceContext.js'
 import { resolveStepAmount } from '../../../utils/resolveNudgeStep.js'
 
 const DIRECTIONS = [
-  { id: 'panUp', verb: 'up', dx: 0, dy: -1 },
-  { id: 'panDown', verb: 'down', dx: 0, dy: 1 },
-  { id: 'panLeft', verb: 'left', dx: -1, dy: 0 },
-  { id: 'panRight', verb: 'right', dx: 1, dy: 0 }
+  { id: 'panUp', verb: 'up', dx: 0, dy: -1, key: 'ArrowUp' },
+  { id: 'panDown', verb: 'down', dx: 0, dy: 1, key: 'ArrowDown' },
+  { id: 'panLeft', verb: 'left', dx: -1, dy: 0, key: 'ArrowLeft' },
+  { id: 'panRight', verb: 'right', dx: 1, dy: 0, key: 'ArrowRight' }
 ]
 
 const ZOOM_ACTIONS = [
@@ -20,7 +20,7 @@ const ZOOM_ACTIONS = [
 
 export const MoveControl = () => {
   const { id: appId, mapProvider, panDelta, nudgePanDelta, zoomDelta, nudgeZoomDelta } = useConfig()
-  const { dispatch, expandedButtons, nudgeStepSize } = useApp()
+  const { dispatch, expandedButtons, nudgeStepSize, interfaceType, layoutRefs } = useApp()
   const { isAtMaxZoom, isAtMinZoom } = useMap()
   const { announce } = useService()
 
@@ -38,16 +38,62 @@ export const MoveControl = () => {
   // keyboard-shortcut vocabulary, so the label always describes the step size in effect.
   const actionWord = isLargeStep ? 'Move' : 'Nudge'
 
-  const handlePan = (dx, dy, verb) => {
-    const amount = resolveStepAmount(isLargeStep, nudgePanDelta, panDelta)
+  // 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
+  // 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
+  // user tabs to a direction button once and presses Enter/Space many times in a row,
+  // which requires focus to stay put. So this only returns focus when the interface
+  // type isn't 'keyboard': a mouse/touch user doesn't need retained focus to click the
+  // same visible button again, and returning it immediately means they can switch to
+  // arrow keys right after without an extra click into the map first.
+  const returnFocusToViewport = () => {
+    if (interfaceType !== 'keyboard') {
+      requestAnimationFrame(() => layoutRefs.viewportRef.current?.focus())
+    }
+  }
+
+  const handlePan = (dx, dy, verb, shiftKey = false) => {
+    // Shift is a momentary "use the small step" override — matching the map's own
+    // native keyboard shortcuts (keyboardActions.js's getPan/getZoom: "Shift held
+    // selects the fine nudge amount... not a large step") — regardless of what the
+    // Precision toggle currently says. Only the arrow-key path below passes a
+    // shiftKey; button clicks don't, so they're unaffected and still follow the
+    // toggle exactly as before. Button labels also stay toggle-only (WAI-ARIA
+    // stable-name pattern) — only the actual step taken and its announcement
+    // reflect a momentary Shift override.
+    const effectiveIsLargeStep = shiftKey ? false : isLargeStep
+    const effectiveActionWord = effectiveIsLargeStep ? 'Move' : 'Nudge'
+
+    // 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
+    // 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.
+    const activeMoveTarget = mapProvider.activeMoveTarget
+    if (activeMoveTarget) {
+      activeMoveTarget.move(dx, dy, effectiveIsLargeStep)
+      const target = activeMoveTarget.label ? `${activeMoveTarget.label} ` : ''
+      announce(`${effectiveActionWord}d ${target}${verb}`)
+      returnFocusToViewport()
+      return
+    }
+
+    const amount = resolveStepAmount(effectiveIsLargeStep, nudgePanDelta, panDelta)
     mapProvider.panBy([dx * amount, dy * amount])
-    announce(`${actionWord}d ${verb}`)
+    announce(`${effectiveActionWord}d ${verb}`)
+    returnFocusToViewport()
   }
 
   const handleZoom = (method, label) => {
     const amount = resolveStepAmount(isLargeStep, nudgeZoomDelta, zoomDelta)
     mapProvider[method](amount)
     announce(label)
+    returnFocusToViewport()
   }
 
   const handleToggleStep = () => {
@@ -55,6 +101,24 @@ export const MoveControl = () => {
     announce(isLargeStep ? 'Precision on' : 'Precision off')
   }
 
+  // A keyboard user tabs to a direction button and can repeat-press Enter/Space on
+  // it (see returnFocusToViewport above — focus deliberately stays put for
+  // 'keyboard'), but that leaves them unable to fall back to raw arrow keys without
+  // 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;
+  // 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) => {
+    const direction = DIRECTIONS.find(({ key }) => key === e.key)
+    if (!direction) {
+      return
+    }
+    e.preventDefault()
+    handlePan(direction.dx, direction.dy, direction.verb, e.shiftKey)
+  }
+
   const containerClassName = [
     'im-c-move-control',
     !isOpen && 'im-c-move-control--collapsed'
@@ -105,7 +169,7 @@ export const MoveControl = () => {
   )
 
   return (
-    <div id={`${appId}-move-control-content`} className={containerClassName}>
+    <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 */}
       {directionsGroup}
       {zoomGroup}
     </div>

package/src/App/components/MoveControl/MoveControl.module.scss

@@ -12,7 +12,7 @@
     gap: var(--divider-gap);
 }
 
-.im-c-move-control--collapsed {
+.im-c-move-control.im-c-move-control--collapsed {
     display: none;
 }
 
@@ -99,7 +99,17 @@
 // 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
 // aria-pressed itself; the colour is purely a visual echo of its expanded state.
-.im-c-map-button--move-control[aria-expanded="true"] {
+//
+// Compound selector (base class + variant class), not the variant class alone —
+// same reasoning as the --collapsed rule above. This selector's specificity was
+// tied with .im-c-map-button:hover (MapButton.module.scss), both (0,2,0), so
+// 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
+// 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"] {
     color: var(--pressed-button-foreground-color);
     border-color: var(--pressed-button-border-color);
     background-color: var(--pressed-button-background-color);

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

@@ -25,6 +25,7 @@ describe('MoveControl', () => {
     dispatch,
     expandedButtons: new Set(['moveControl']),
     nudgeStepSize: 'large',
+    layoutRefs: { viewportRef: { current: { focus: jest.fn() } } },
     ...overrides
   })
 
@@ -100,6 +101,31 @@ describe('MoveControl', () => {
     expect(announce).toHaveBeenCalledWith('Nudged up')
   })
 
+  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 />)
+    fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
+    expect(mapProvider.activeMoveTarget.move).toHaveBeenCalledWith(1, 0, true)
+    expect(mapProvider.panBy).not.toHaveBeenCalled()
+    expect(announce).toHaveBeenCalledWith('Moved vertex right')
+  })
+
+  it('falls back to panning once activeMoveTarget is released', () => {
+    mapProvider.activeMoveTarget = { move: jest.fn(), label: 'vertex' }
+    const { rerender } = render(<MoveControl />)
+    mapProvider.activeMoveTarget = null
+    rerender(<MoveControl />)
+    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 />)
+    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 />)
     fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
@@ -139,6 +165,116 @@ describe('MoveControl', () => {
     expect(mapProvider.zoomOut).not.toHaveBeenCalled()
   })
 
+  describe('returning focus to the viewport after a click', () => {
+    let rafSpy
+
+    beforeEach(() => {
+      rafSpy = jest.spyOn(global, 'requestAnimationFrame').mockImplementation(cb => { cb(); return 1 })
+    })
+
+    afterEach(() => rafSpy.mockRestore())
+
+    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 />)
+
+      fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
+      expect(appState.layoutRefs.viewportRef.current.focus).toHaveBeenCalled()
+    })
+
+    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 />)
+      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 />)
+      fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
+      expect(rafSpy).toHaveBeenCalledTimes(1)
+
+      useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
+      rerender(<MoveControl />)
+      fireEvent.click(screen.getByRole('button', { name: 'Zoom in' }))
+      expect(rafSpy).toHaveBeenCalledTimes(1)
+    })
+
+    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 />)
+      fireEvent.click(screen.getByRole('button', { name: 'Move right' }))
+      expect(rafSpy).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('arrow keys while focus is anywhere within the control', () => {
+    // A keyboard user who tabs to a direction button and repeat-presses Enter keeps
+    // focus there (see the describe block above) — this lets them fall back to raw
+    // 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 />)
+      // 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' }))
+      fireEvent.keyDown(screen.getByRole('button', { name: 'Zoom in' }), { key: 'ArrowRight' })
+      expect(mapProvider.panBy).toHaveBeenCalledWith([100, 0])
+      expect(announce).toHaveBeenCalledWith('Moved right')
+    })
+
+    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 />)
+      fireEvent.keyDown(screen.getByRole('button', { name: 'Move up' }), { key: 'ArrowUp' })
+      expect(mapProvider.activeMoveTarget.move).toHaveBeenCalledWith(0, -1, true)
+      expect(mapProvider.panBy).not.toHaveBeenCalled()
+    })
+
+    it('ignores non-arrow keys, leaving default behaviour (e.g. Enter/Space activating the focused button) untouched', () => {
+      useApp.mockReturnValue(buildAppState({ interfaceType: 'keyboard' }))
+      render(<MoveControl />)
+      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 />)
+      fireEvent.keyDown(screen.getByRole('button', { name: 'Move right' }), { key: 'ArrowRight', shiftKey: true })
+      expect(mapProvider.panBy).toHaveBeenCalledWith([5, 0])
+      expect(announce).toHaveBeenCalledWith('Nudged right')
+    })
+
+    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 />)
+      fireEvent.keyDown(screen.getByRole('button', { name: 'Nudge right' }), { key: 'ArrowRight', shiftKey: true })
+      expect(mapProvider.panBy).toHaveBeenCalledWith([5, 0])
+      expect(announce).toHaveBeenCalledWith('Nudged right')
+    })
+
+    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 />)
+      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 />)
+      fireEvent.keyDown(screen.getByRole('button', { name: 'Move right' }), { key: 'ArrowRight' })
+      expect(mapProvider.panBy).toHaveBeenCalledWith([100, 0])
+      expect(announce).toHaveBeenCalledWith('Moved right')
+    })
+  })
+
   it('has a stable "Precision" label regardless of state', () => {
     const { rerender } = render(<MoveControl />)
     expect(screen.getByRole('button', { name: 'Precision' })).toBeInTheDocument()

package/src/App/hooks/useHintsAPI.js

@@ -0,0 +1,67 @@
+import { useEffect, useRef } from 'react'
+import { EVENTS as events } from '../../config/events.js'
+import { useService } from '../store/serviceContext.js'
+import { useApp } from '../store/appContext.js'
+
+/**
+ * Wires the public showHint()/dismissHint() API onto the hints service.
+ * The hints service already owns its own subscriber list (see Hints.jsx),
+ * so this just forwards eventBus commands to it — no React state involved.
+ */
+export const useHintsAPI = () => {
+  const { eventBus, hints } = useService()
+  const { layoutRefs } = useApp()
+  const isHintActiveRef = useRef(false)
+
+  useEffect(() => {
+    const handleShowHint = ({ text, options } = {}) => {
+      if (!text) {
+        return
+      }
+      hints.show(text, options)
+    }
+    const handleDismissHint = () => hints.dismiss()
+
+    eventBus.on(events.APP_SHOW_HINT, handleShowHint)
+    eventBus.on(events.APP_DISMISS_HINT, handleDismissHint)
+
+    return () => {
+      eventBus.off(events.APP_SHOW_HINT, handleShowHint)
+      eventBus.off(events.APP_DISMISS_HINT, handleDismissHint)
+    }
+  }, [eventBus, hints])
+
+  // Escape dismisses the active hint when the keypress originates inside this
+  // map instance. The viewport and features listbox already dismiss hints on
+  // Escape within their own narrower focus scope (useKeyboardHint.js /
+  // useFeatureFocus.js) — this covers hints shown via the public showHint()
+  // API from anywhere else in the same map's UI (e.g. a plugin button).
+  //
+  // Listening on document (rather than the map's own container) and checking
+  // containment ourselves, rather than a container-scoped listener, is
+  // deliberate: with multiple map instances on one page, each has its own
+  // hints service and its own isHintActiveRef, so without the containment
+  // check an Escape press anywhere on the host page would dismiss a hint on
+  // every instance that happened to have one showing — including maps the
+  // user isn't even looking at.
+  useEffect(() => {
+    return hints.subscribe((hint) => {
+      isHintActiveRef.current = Boolean(hint)
+    })
+  }, [hints])
+
+  useEffect(() => {
+    const handleKeyDown = (e) => {
+      if (e.key !== 'Escape' || !isHintActiveRef.current) {
+        return
+      }
+      const container = layoutRefs.appContainerRef?.current
+      if (container && !container.contains(e.target)) {
+        return
+      }
+      hints.dismiss()
+    }
+    document.addEventListener('keydown', handleKeyDown)
+    return () => document.removeEventListener('keydown', handleKeyDown)
+  }, [hints, layoutRefs])
+}

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

@@ -0,0 +1,145 @@
+import { renderHook, act } from '@testing-library/react'
+import { useHintsAPI } from './useHintsAPI.js'
+import { useService } from '../store/serviceContext.js'
+import { useApp } from '../store/appContext.js'
+
+jest.mock('../store/serviceContext.js')
+jest.mock('../store/appContext.js')
+
+const makeEventBus = () => {
+  const handlers = {}
+  return {
+    on: jest.fn((event, handler) => { handlers[event] = handler }),
+    off: jest.fn(),
+    emit: (event, payload) => handlers[event]?.(payload),
+    _handlers: handlers
+  }
+}
+
+const makeHints = () => {
+  let subscriber = null
+  return {
+    show: jest.fn(),
+    dismiss: jest.fn(),
+    subscribe: jest.fn((fn) => {
+      subscriber = fn
+      return () => { subscriber = null }
+    }),
+    _emit: (hint) => subscriber?.(hint)
+  }
+}
+
+const pressEscape = (target) => {
+  target.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+}
+
+describe('useHintsAPI', () => {
+  let mockEventBus, mockHints, containerEl, insideEl, outsideEl
+
+  beforeEach(() => {
+    mockEventBus = makeEventBus()
+    mockHints = makeHints()
+    useService.mockReturnValue({ eventBus: mockEventBus, hints: mockHints })
+
+    // Simulates this map instance's root DOM (layoutRefs.appContainerRef),
+    // plus an element outside it — standing in for a second map instance,
+    // or unrelated content elsewhere on the host page.
+    containerEl = document.createElement('div')
+    insideEl = document.createElement('button')
+    containerEl.appendChild(insideEl)
+    document.body.appendChild(containerEl)
+
+    outsideEl = document.createElement('button')
+    document.body.appendChild(outsideEl)
+
+    useApp.mockReturnValue({ layoutRefs: { appContainerRef: { current: containerEl } } })
+  })
+
+  afterEach(() => {
+    containerEl.remove()
+    outsideEl.remove()
+  })
+
+  it('calls hints.show with text and options on app:showhint', () => {
+    renderHook(() => useHintsAPI())
+    act(() => mockEventBus.emit('app:showhint', { text: 'Press Enter to select', options: { duration: 2000 } }))
+    expect(mockHints.show).toHaveBeenCalledWith('Press Enter to select', { duration: 2000 })
+  })
+
+  it('ignores app:showhint with no text', () => {
+    renderHook(() => useHintsAPI())
+    act(() => mockEventBus.emit('app:showhint', {}))
+    act(() => mockEventBus.emit('app:showhint'))
+    expect(mockHints.show).not.toHaveBeenCalled()
+  })
+
+  it('calls hints.dismiss on app:dismisshint', () => {
+    renderHook(() => useHintsAPI())
+    act(() => mockEventBus.emit('app:dismisshint'))
+    expect(mockHints.dismiss).toHaveBeenCalled()
+  })
+
+  it('unsubscribes on unmount', () => {
+    const { unmount } = renderHook(() => useHintsAPI())
+    unmount()
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:showhint', expect.any(Function))
+    expect(mockEventBus.off).toHaveBeenCalledWith('app:dismisshint', expect.any(Function))
+  })
+
+  describe('Escape key', () => {
+    it('dismisses the active hint when Escape originates inside this map instance', () => {
+      renderHook(() => useHintsAPI())
+      act(() => mockHints._emit({ html: 'Press Enter to select' }))
+
+      act(() => pressEscape(insideEl))
+      expect(mockHints.dismiss).toHaveBeenCalled()
+    })
+
+    it('does not dismiss when Escape originates outside this map instance', () => {
+      // e.g. a second map instance on the page, or unrelated host-page content
+      renderHook(() => useHintsAPI())
+      act(() => mockHints._emit({ html: 'Press Enter to select' }))
+
+      act(() => pressEscape(outsideEl))
+      expect(mockHints.dismiss).not.toHaveBeenCalled()
+    })
+
+    it('does nothing on Escape when no hint is showing', () => {
+      renderHook(() => useHintsAPI())
+      act(() => pressEscape(insideEl))
+      expect(mockHints.dismiss).not.toHaveBeenCalled()
+    })
+
+    it('stops reacting to Escape once the hint has been dismissed', () => {
+      renderHook(() => useHintsAPI())
+      act(() => mockHints._emit({ html: 'Press Enter to select' }))
+      act(() => mockHints._emit(null)) // hints service reports no active hint
+
+      act(() => pressEscape(insideEl))
+      expect(mockHints.dismiss).not.toHaveBeenCalled()
+    })
+
+    it('falls back to dismissing when appContainerRef is not yet available', () => {
+      useApp.mockReturnValue({ layoutRefs: { appContainerRef: { current: null } } })
+      renderHook(() => useHintsAPI())
+      act(() => mockHints._emit({ html: 'Press Enter to select' }))
+
+      act(() => pressEscape(outsideEl))
+      expect(mockHints.dismiss).toHaveBeenCalled()
+    })
+
+    it('removes the keydown listener on unmount', () => {
+      const addSpy = jest.spyOn(document, 'addEventListener')
+      const removeSpy = jest.spyOn(document, 'removeEventListener')
+
+      const { unmount } = renderHook(() => useHintsAPI())
+      expect(addSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+
+      unmount()
+      expect(removeSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+
+      addSpy.mockRestore()
+      removeSpy.mockRestore()
+    })
+  })
+})

package/src/App/renderer/PluginInits.jsx

@@ -3,6 +3,7 @@ import React, { useEffect } from 'react'
 import { withPluginContexts } from './pluginWrapper.js'
 import { withPluginApiContexts, usePluginApiState } from './pluginApiWrapper.js'
 import { useInterfaceAPI } from '../hooks/useInterfaceAPI.js'
+import { useHintsAPI } from '../hooks/useHintsAPI.js'
 import { useApp } from '../store/appContext.js'
 import { useConfig } from '../store/configContext.js'
 import { useEvaluateProp } from '../hooks/useEvaluateProp.js'
@@ -53,6 +54,9 @@ export const PluginInits = () => {
   // Add button, panel and control API methods (Needs to be top-level)
   useInterfaceAPI()
 
+  // Wire the showHint()/dismissHint() public API onto the hints service
+  useHintsAPI()
+
   // Evaluate reactive button states globally
   const evaluateProp = useEvaluateProp()
   useButtonStateEvaluator(evaluateProp)

package/src/App/renderer/PluginInits.test.jsx

@@ -6,6 +6,7 @@ import { useButtonStateEvaluator } from '../hooks/useButtonStateEvaluator.js'
 import { withPluginApiContexts } from './pluginApiWrapper.js'
 import { withPluginContexts } from './pluginWrapper.js'
 import { useInterfaceAPI } from '../hooks/useInterfaceAPI.js'
+import { useHintsAPI } from '../hooks/useHintsAPI.js'
 import { useApp } from '../store/appContext.js'
 import { useConfig } from '../store/configContext.js'
 
@@ -29,6 +30,10 @@ jest.mock('../hooks/useInterfaceAPI.js', () => ({
   useInterfaceAPI: jest.fn()
 }))
 
+jest.mock('../hooks/useHintsAPI.js', () => ({
+  useHintsAPI: jest.fn()
+}))
+
 jest.mock('../hooks/useEvaluateProp.js', () => ({
   useEvaluateProp: jest.fn(() => (x) => x)
 }))
@@ -59,10 +64,11 @@ describe('PluginInits', () => {
     useConfig.mockReturnValue({ pluginRegistry: pluginRegistryMock })
   })
 
-  it('calls useButtonStateEvaluator and useInterfaceAPI on render', () => {
+  it('calls useButtonStateEvaluator, useInterfaceAPI and useHintsAPI on render', () => {
     render(<PluginInits />)
     expect(useButtonStateEvaluator).toHaveBeenCalled()
     expect(useInterfaceAPI).toHaveBeenCalled()
+    expect(useHintsAPI).toHaveBeenCalled()
   })
 
   it('renders nothing when no plugins registered', () => {

package/src/InteractiveMap/InteractiveMap.js

@@ -3,6 +3,7 @@
 /**
  * @typedef {import('../types.js').ButtonDefinition} ButtonDefinition
  * @typedef {import('../types.js').ControlDefinition} ControlDefinition
+ * @typedef {import('../types.js').HintOptions} HintOptions
  * @typedef {import('../types.js').InteractiveMapConfig} InteractiveMapConfig
  * @typedef {import('../types.js').MarkerOptions} MarkerOptions
  * @typedef {import('../types.js').PanelDefinition} PanelDefinition
@@ -481,6 +482,25 @@ export default class InteractiveMap {
     this.eventBus.emit(events.APP_ADD_CONTROL, { id, config })
   }
 
+  /**
+   * Show a toast hint, announced to screen readers via the live region.
+   * Replaces any hint currently showing and restarts its dismiss timer.
+   *
+   * @param {string} text - Hint text. May contain simple HTML (e.g. `<kbd>`).
+   * @param {HintOptions} [options] - Optional hint behaviour.
+   */
+  showHint (text, options) {
+    this.eventBus.emit(events.APP_SHOW_HINT, { text, options })
+  }
+
+  /**
+   * Dismiss the active toast hint, if any. No-op if no hint is showing.
+   * Mainly useful for hints shown with `{ duration: 0 }`, which otherwise persist indefinitely.
+   */
+  dismissHint () {
+    this.eventBus.emit(events.APP_DISMISS_HINT)
+  }
+
   /**
    * Fit the map view to a bounding box or GeoJSON geometry, respecting the safe zone padding.
    *

package/src/InteractiveMap/InteractiveMap.test.js

@@ -579,4 +579,11 @@ describe('InteractiveMap — Public API Methods', () => {
     expect(map.eventBus.emitWhenReady).toHaveBeenCalledWith('map:fittobounds', bbox)
     expect(map.eventBus.emitWhenReady).toHaveBeenCalledWith('map:setview', { center, zoom: 12 })
   })
+
+  it('showHint and dismissHint emit correct events', () => {
+    map.showHint('Press <kbd>Enter</kbd> to select', { duration: 2000 })
+    map.dismissHint()
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:showhint', { text: 'Press <kbd>Enter</kbd> to select', options: { duration: 2000 } })
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:dismisshint')
+  })
 })

package/src/config/events.js

@@ -47,6 +47,10 @@ export const EVENTS = {
   APP_HIDE_PANEL: 'app:hidepanel',
   /** @internal Add a control. Payload: { id, config } */
   APP_ADD_CONTROL: 'app:addcontrol',
+  /** @internal Show a toast hint, announced to screen readers. Payload: { text, options } */
+  APP_SHOW_HINT: 'app:showhint',
+  /** @internal Dismiss the active toast hint, if any. */
+  APP_DISMISS_HINT: 'app:dismisshint',
 
   // ============================================
   // App responses (end-user / subscribe)

package/src/scss/settings/_dimensions.scss

@@ -31,6 +31,9 @@
     --tooltip-font-size: 14px;
     --tooltip-border-radius: 3px;
 
+    // Hints
+    --hint-max-width: 320px;
+
     // Panels
     --min-panel-width: 260px;
     --panel-close-button-gap: 4px;