@defra/interactive-map 0.0.22-alpha → 0.0.23-alpha

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

@@ -38,7 +38,8 @@ describe('mapButtons module', () => {
       pressedButtons: new Set(),
       expandedButtons: new Set(),
       buttonConfig: {},
-      panelConfig: {}
+      panelConfig: {},
+      layoutRefs: { viewportRef: { current: { focus: jest.fn() } } }
     }
     appState.buttonConfig = ({})
     getPanelConfig.mockReturnValue({})
@@ -227,6 +228,41 @@ describe('mapButtons module', () => {
       // dispatch should NOT be called because panelId is missing
       expect(appState.dispatch).not.toHaveBeenCalled()
     })
+
+    it('focuses viewport via requestAnimationFrame after onClick when not toggle and no keepFocus', () => {
+      const rafSpy = jest.spyOn(global, 'requestAnimationFrame').mockImplementation(cb => { cb(); return 1 })
+      const viewportFocusSpy = jest.spyOn(appState.layoutRefs.viewportRef.current, 'focus')
+      const onClick = jest.fn()
+      render({ ...baseBtn, onClick }).props.onClick({})
+      expect(viewportFocusSpy).toHaveBeenCalled()
+      rafSpy.mockRestore()
+      viewportFocusSpy.mockRestore()
+    })
+
+    it('does not call requestAnimationFrame when keepFocus is true', () => {
+      const rafSpy = jest.spyOn(global, 'requestAnimationFrame')
+      const onClick = jest.fn()
+      render({ ...baseBtn, onClick, keepFocus: true }).props.onClick({})
+      expect(rafSpy).not.toHaveBeenCalled()
+      rafSpy.mockRestore()
+    })
+
+    it('does not call requestAnimationFrame when button is a toggle (pressedWhen set)', () => {
+      const rafSpy = jest.spyOn(global, 'requestAnimationFrame')
+      const onClick = jest.fn()
+      render({ ...baseBtn, onClick, pressedWhen: jest.fn() }).props.onClick({})
+      expect(rafSpy).not.toHaveBeenCalled()
+      rafSpy.mockRestore()
+    })
+
+    it('includes focusOnOpen: false in OPEN_PANEL payload when keepFocus is true', () => {
+      const mockButtonEl = document.createElement('button')
+      render({ ...baseBtn, panelId: 'p1', keepFocus: true }).props.onClick({ currentTarget: mockButtonEl })
+      expect(appState.dispatch).toHaveBeenCalledWith({
+        type: 'OPEN_PANEL',
+        payload: { panelId: 'p1', props: { triggeringElement: mockButtonEl }, focusOnOpen: false }
+      })
+    })
   })
 
   // -------------------------

package/src/App/store/ServiceProvider.jsx

@@ -1,6 +1,7 @@
 // src/App/store/ServiceProvider.jsx
 import React, { createContext, useMemo, useRef } from 'react'
 import { createAnnouncer } from '../../services/announcer.js'
+import { createHints } from '../../services/hints.js'
 import { reverseGeocode } from '../../services/reverseGeocode.js'
 import { useConfig } from '../store/configContext.js'
 import { closeApp } from '../../services/closeApp.js'
@@ -13,18 +14,20 @@ export const ServiceProvider = ({ eventBus, children }) => {
   const { id, handleExitClick, symbolDefaults: constructorSymbolDefaults } = useConfig()
   const mapStatusRef = useRef(null)
   const announce = useMemo(() => createAnnouncer(mapStatusRef), [])
+  const hints = useMemo(() => createHints(announce), [announce])
 
   symbolRegistry.setDefaults(constructorSymbolDefaults || {})
 
   const services = useMemo(() => ({
     announce,
+    hints,
     reverseGeocode: (zoom, center) => reverseGeocode(zoom, center),
     eventBus,
     mapStatusRef,
     closeApp: () => closeApp(id, handleExitClick, eventBus),
     symbolRegistry,
     patternRegistry
-  }), [announce])
+  }), [announce, hints])
 
   return (
     <ServiceContext.Provider value={services}>

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

@@ -11,6 +11,11 @@ jest.mock('../../services/announcer.js', () => ({
   createAnnouncer: jest.fn(() => jest.fn())
 }))
 
+const mockShow = jest.fn()
+jest.mock('../../services/hints.js', () => ({
+  createHints: jest.fn(() => ({ show: mockShow, dismiss: jest.fn(), subscribe: jest.fn() }))
+}))
+
 jest.mock('../../services/reverseGeocode.js', () => ({
   reverseGeocode: jest.fn(() => 'mockedReverseGeocode')
 }))
@@ -57,6 +62,12 @@ describe('ServiceProvider', () => {
     expect(result.current).toBeTruthy()
   })
 
+  test('hints.show() delegates to createHints show', () => {
+    const { result } = renderHook(() => React.useContext(ServiceContext), { wrapper })
+    result.current.hints.show('<b>test</b>', { duration: 2000 })
+    expect(mockShow).toHaveBeenCalledWith('<b>test</b>', { duration: 2000 })
+  })
+
   test('closeApp calls closeApp service with id and handleExitClick', () => {
     const mockHandleExitClick = jest.fn()
     const { useConfig } = require('../store/configContext.js')

package/src/App/store/appActionsMap.js

@@ -23,7 +23,7 @@ function buildOpenPanels (state, panelId, breakpoint, props, focusOnOpen) {
   return {
     ...(isExclusiveNonModal ? {} : filteredPanels),
     ...(isModal ? state.openPanels : {}),
-    [panelId]: { props, ...(focusOnOpen && { focusOnOpen: true }) }
+    [panelId]: { props, ...(focusOnOpen !== undefined && { focusOnOpen }) }
   }
 }
 
@@ -158,6 +158,9 @@ const setPluginsEvaluated = (state) =>
 const clearPluginsEvaluated = (state) =>
   state.arePluginsEvaluated ? { ...state, arePluginsEvaluated: false } : state
 
+const setListboxActive = (state) =>
+  state.listboxIsActive ? state : { ...state, listboxIsActive: true }
+
 const setSafeZoneInset = (state, { safeZoneInset, syncMapPadding = true }) => {
   return shallowEqual(state.safeZoneInset, safeZoneInset)
     ? state
@@ -373,6 +376,7 @@ export const actionsMap = {
   SET_MODE: setMode,
   PLUGINS_EVALUATED: setPluginsEvaluated,
   CLEAR_PLUGINS_EVALUATED: clearPluginsEvaluated,
+  SET_LISTBOX_ACTIVE: setListboxActive,
   SET_SAFE_ZONE_INSET: setSafeZoneInset,
   REVERT_MODE: revertMode,
   OPEN_PANEL: openPanel,

package/src/App/store/appActionsMap.test.js

@@ -425,4 +425,17 @@ describe('actionsMap full coverage', () => {
       expect(res.openPanels).toHaveProperty('p1')
     })
   })
+
+  describe('SET_LISTBOX_ACTIVE', () => {
+    test('sets listboxIsActive to true when currently false', () => {
+      const res = actionsMap.SET_LISTBOX_ACTIVE({ ...state, listboxIsActive: false })
+      expect(res.listboxIsActive).toBe(true)
+    })
+
+    test('returns same state reference when listboxIsActive is already true', () => {
+      const activeState = { ...state, listboxIsActive: true }
+      const res = actionsMap.SET_LISTBOX_ACTIVE(activeState)
+      expect(res).toBe(activeState)
+    })
+  })
 })

package/src/App/store/appReducer.js

@@ -47,6 +47,7 @@ export const initialState = (config) => {
     hasExclusiveControl: false,
     openPanels,
     previousOpenPanels: {},
+    listboxIsActive: false,
     syncMapPadding: true,
     pluginRegistry,
     buttonRegistry,

package/src/App/store/mapActionsMap.js

@@ -36,7 +36,8 @@ const updateCrossHair = (state, payload) => {
 
 const upsertMarker = (state, payload) => {
   const map = new Map(state.markers.items.map(item => [item.id, item]))
-  map.set(payload.id, payload)
+  const existing = map.get(payload.id) || {}
+  map.set(payload.id, { ...existing, ...payload })
   const newItems = Array.from(map.values())
 
   return {

package/src/InteractiveMap/InteractiveMap.js

@@ -336,6 +336,18 @@ export default class InteractiveMap {
     this.eventBus.emit(events.APP_ADD_MARKER, { id, coords, options })
   }
 
+  /**
+   * Update an existing marker's options without replacing it. No-op if the marker id is not found.
+   * Merges the provided options into the existing marker — unspecified properties are preserved.
+   * Pass `coords` inside options to move the marker to new coordinates.
+   *
+   * @param {string} id - Marker identifier to update.
+   * @param {MarkerOptions & { coords?: [number, number] }} [options] - Properties to merge into the marker.
+   */
+  updateMarker (id, options) {
+    this.eventBus.emit(events.APP_UPDATE_MARKER, { id, options })
+  }
+
   /**
    * Remove a marker from the map.
    *

package/src/InteractiveMap/InteractiveMap.test.js

@@ -586,6 +586,7 @@ describe('InteractiveMap Public API Methods', () => {
     map.off('testEvent', cb)
     map.emit('customEvent', 123)
     map.addMarker('marker-1', coords, options)
+    map.updateMarker('marker-1', options)
     map.removeMarker('marker-1')
     map.setMode('test-mode')
 
@@ -593,6 +594,7 @@ describe('InteractiveMap Public API Methods', () => {
     expect(map.eventBus.off).toHaveBeenCalledWith('testEvent', cb)
     expect(map.eventBus.emit).toHaveBeenCalledWith('customEvent', 123)
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:addmarker', { id: 'marker-1', coords, options })
+    expect(map.eventBus.emit).toHaveBeenCalledWith('app:updatemarker', { id: 'marker-1', options })
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:removemarker', 'marker-1')
     expect(map.eventBus.emit).toHaveBeenCalledWith('app:setmode', 'test-mode')
   })

package/src/config/appConfig.js

@@ -45,6 +45,7 @@ export const defaultAppConfig = {
     group: { name: 'zoom', label: 'Zoom controls', order: 0 },
     label: 'Zoom in',
     iconId: 'plus',
+    keepFocus: true,
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomIn(appConfig.zoomDelta),
     excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMaxZoom,
@@ -56,6 +57,7 @@ export const defaultAppConfig = {
     group: { name: 'zoom', label: 'Zoom controls', order: 0 },
     label: 'Zoom out',
     iconId: 'minus',
+    keepFocus: true,
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomOut(appConfig.zoomDelta),
     excludeWhen: ({ appState, appConfig }) => !appConfig.enableZoomControls || appState.interfaceType === 'touch',
     enableWhen: ({ mapState }) => !mapState.isAtMinZoom,
@@ -78,7 +80,7 @@ export const defaultAppConfig = {
       ...keyboardBasePanelSlots,
       width: '500px'
     },
-    render: () => <KeyboardHelp />
+    render: (props) => <KeyboardHelp context={props?.context} />
   }],
 
   icons: [{

package/src/config/appConfig.test.js

@@ -1,6 +1,10 @@
 import { render } from '@testing-library/react'
 import { defaultAppConfig, defaultButtonConfig, scaleFactor } from './appConfig'
 
+jest.mock('../App/store/appContext.js', () => ({
+  useApp: () => ({ listboxIsActive: false })
+}))
+
 describe('defaultAppConfig', () => {
   const appState = {
     layoutRefs: { appContainerRef: { current: document.createElement('div') } },

package/src/config/defaults.js

@@ -21,7 +21,7 @@ const defaults = {
   hasExitButton: false,
   hybridWidth: null, // Defaults to maxMobileWidth if not set
   keyboardHintText: '<span class="im-u-visually-hidden">Press </span><kbd>Alt</kbd> + <kbd>K</kbd> <span class="im-u-visually-hidden">to view </span>keyboard shortcuts',
-  mapLabel: 'Interactive map',
+  mapLabel: 'Interactive map application',
   mapProvider: null,
   mapSize: 'small',
   manageHistoryState: true,

package/src/config/events.js

@@ -25,6 +25,8 @@ export const EVENTS = {
 
   /** @internal Add a marker. Payload: { id, coords, options } */
   APP_ADD_MARKER: 'app:addmarker',
+  /** @internal Update an existing marker's options. No-op if id not found. Payload: { id, options } */
+  APP_UPDATE_MARKER: 'app:updatemarker',
   /** @internal Remove a marker. Payload: id */
   APP_REMOVE_MARKER: 'app:removemarker',
   /** @internal Set application mode. Payload: mode */
@@ -121,6 +123,12 @@ 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 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 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/config/mapTheme.js

@@ -4,18 +4,20 @@
  * used both by the symbol SVG renderer (JS canvas) and injected as
  * CSS custom properties onto the app container for CSS-rendered elements.
  *
- * Per-style overrides take precedence: set `haloColor`, `selectedColor`, or
+ * Per-style overrides take precedence: set `haloColor`, `selectedColor`, `activeColor`, or
  * `foregroundColor` directly on a `MapStyleConfig` to override these defaults.
  */
-export const SCHEME_COLORS = {
+export const THEME_COLORS = {
   light: {
     haloColor: '#ffffff',
     selectedColor: '#0b0c0c',
+    activeColor: '#ffdd00',
     foregroundColor: '#0b0c0c'
   },
   dark: {
     haloColor: '#0b0c0c',
     selectedColor: '#ffffff',
+    activeColor: '#ffdd00',
     foregroundColor: '#ffffff'
   }
 }
@@ -30,10 +32,11 @@ export const SCHEME_COLORS = {
  * @returns {{ haloColor: string, selectedColor: string, foregroundColor: string }}
  */
 export const resolveMapTheme = (mapStyle) => {
-  const scheme = SCHEME_COLORS[mapStyle?.mapColorScheme] ?? SCHEME_COLORS.light
+  const scheme = THEME_COLORS[mapStyle?.mapColorScheme] ?? THEME_COLORS.light
   return {
     haloColor: mapStyle?.haloColor ?? scheme.haloColor,
     selectedColor: mapStyle?.selectedColor ?? scheme.selectedColor,
+    activeColor: mapStyle?.activeColor ?? scheme.activeColor,
     foregroundColor: mapStyle?.foregroundColor ?? scheme.foregroundColor
   }
 }
@@ -47,10 +50,11 @@ export const resolveMapTheme = (mapStyle) => {
  * @returns {Object} CSS custom property object
  */
 export const getMapThemeVars = (mapStyle) => {
-  const { haloColor, selectedColor, foregroundColor } = resolveMapTheme(mapStyle)
+  const { haloColor, selectedColor, activeColor, foregroundColor } = resolveMapTheme(mapStyle)
   return {
     '--map-overlay-halo-color': haloColor,
     '--map-overlay-selected-color': selectedColor,
+    '--map-overlay-active-color': activeColor,
     '--map-overlay-foreground-color': foregroundColor
   }
 }

package/src/config/symbolConfig.js

@@ -7,11 +7,18 @@
 export const symbolDefaults = {
   symbol: 'pin',
   backgroundColor: '#ca3535',
-  foregroundColor: '#ffffff',
-  haloWidth: '1',
-  selectedWidth: '6'
+  foregroundColor: '#ffffff'
 }
 
+/** Stroke width for the halo (background shape outline) in SVG units */
+export const HALO_STROKE_WIDTH = 2
+
+/** Stroke width for the selected state — symbol rings and feature highlight lines */
+export const SELECTED_STROKE_WIDTH = 3
+
+/** Stroke width for the active (keyboard cursor) state — double selected, extends 1× each side */
+export const ACTIVE_STROKE_WIDTH = SELECTED_STROKE_WIDTH * 2
+
 /**
  * Built-in graphic path data strings for use with the `graphic` token.
  *
@@ -46,35 +53,35 @@ export const graphics = {
 }
 
 // ─── Built-in symbol definitions ─────────────────────────────────────────────
-// Each symbol uses a 38×38 viewBox. SVG templates use {{token}} placeholders
+// Each symbol uses a 44×44 viewBox. SVG templates use {{token}} placeholders
 // resolved at render time by the symbolRegistry.
 
 export const pin = {
   id: 'pin',
-  viewBox: '0 0 38 38',
+  viewBox: '0 0 44 44',
   anchor: [0.5, 0.9], // NOSONAR
   graphic: graphics.dot,
-  svg: `<path d="M19 33.499c-5.318-5-12-9.509-12-16.998 0-6.583 5.417-12 12-12s12 5.417 12 12c0 7.489-6.682 11.998-12 16.998z" fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
-  <path d="M19 33.499c-5.318-5-12-9.509-12-16.998 0-6.583 5.417-12 12-12s12 5.417 12 12c0 7.489-6.682 11.998-12 16.998z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
-  <g transform="translate(19, 16) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
+  svg: `<path d="M22 40.999c-3.621 0-8.306-5.864-10.258-8.3C9.02 29.302 6 23.66 6 19.002a16.01 16.01 0 0 1 16-16 16.01 16.01 0 0 1 16 16c0 4.658-3.02 10.3-5.742 13.697-1.952 2.437-6.637 8.3-10.258 8.3z" fill="{{selectedColor}}" stroke="{{activeColor}}" stroke-width="6" paint-order="stroke fill"/>
+  <path d="M22 7.001a12.01 12.01 0 0 1 12 12c0 7.623-10.377 17.998-12 17.998S10 26.624 10 19.001a12.01 12.01 0 0 1 12-12z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="2" paint-order="stroke fill"/>
+  <g transform="translate(22, 19) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
 }
 
 export const circle = {
   id: 'circle',
-  viewBox: '0 0 38 38',
+  viewBox: '0 0 44 44',
   anchor: [0.5, 0.5],
   graphic: graphics.dot,
-  svg: `<path d="M19 7C12.376 7 7 12.376 7 19s5.376 12 12 12a12.01 12.01 0 0 0 12-12A12.01 12.01 0 0 0 19 7z" fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
-  <path d="M19 7C12.376 7 7 12.376 7 19s5.376 12 12 12a12.01 12.01 0 0 0 12-12A12.01 12.01 0 0 0 19 7z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
-  <g transform="translate(19, 19) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
+  svg: `<circle cx="22" cy="22" r="16" fill="{{selectedColor}}" stroke="{{activeColor}}" stroke-width="6" paint-order="stroke fill"/>
+  <circle cx="22" cy="22" r="12" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="2" paint-order="stroke fill"/>
+  <g transform="translate(22, 22) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
 }
 
 export const square = {
   id: 'square',
-  viewBox: '0 0 38 38',
+  viewBox: '0 0 44 44',
   anchor: [0.5, 0.5],
   graphic: graphics.dot,
-  svg: `<path d="M28 7a3 3 0 0 1 3 3v18a3 3 0 0 1-3 3H10a3 3 0 0 1-3-3V10a3 3 0 0 1 3-3h18z" fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
-  <path d="M28 7a3 3 0 0 1 3 3v18a3 3 0 0 1-3 3H10a3 3 0 0 1-3-3V10a3 3 0 0 1 3-3h18z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
-  <g transform="translate(19, 19) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
+  svg: `<path d="M13 6h18c3.863 0 7 3.137 7 7v18c0 3.863-3.137 7-7 7H13c-3.863 0-7-3.137-7-7V13c0-3.863 3.137-7 7-7" fill="{{selectedColor}}" stroke="{{activeColor}}" stroke-width="6" paint-order="stroke fill"/>
+  <path d="M13 34a3 3 0 0 1-3-3V13a3 3 0 0 1 3-3h18a3 3 0 0 1 3 3v18a3 3 0 0 1-3 3H13z" fill-rule="nonzero" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="2" paint-order="stroke fill"/>
+  <g transform="translate(22, 22) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
 }

package/src/scss/main.scss

@@ -17,6 +17,7 @@
 
 // Components: specific UI components. Using 'CSS in Component' pattern
 @use '../App/components/KeyboardHelp/KeyboardHelp.module';
+@use '../App/components/Tabs/Tabs.module';
 @use '../App/components/MapButton/MapButton.module';
 @use '../App/components/Panel/Panel.module';
 @use '../App/components/Icon/Icon.module';
@@ -25,8 +26,10 @@
 @use '../App/components/PopupMenu/PopupMenu.module';
 @use '../App/components/Attributions/Attributions.module';
 @use '../App/components/Logo/Logo.module';
+@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/Actions/Actions.module';
 
 // Components that dont have a corresponding React Component

package/src/scss/tools/_border-focus.scss

@@ -11,7 +11,6 @@
 /// @include border-focus-base($offset: -1px, $border: panel, $box-shadow: panel);
 /// ```
 @mixin border-focus-base($type: null, $is-inset: null) {
-  position: relative;
   border: 0;
   
   // Border radius

package/src/services/eventBus.js

@@ -31,6 +31,21 @@ class EventBus {
     return this
   }
 
+  /**
+   * Register a one-time handler that removes itself after the first call.
+   *
+   * @param {string} eventName
+   * @param {Function} handler
+   * @returns {this}
+   */
+  once (eventName, handler) {
+    const wrapper = (...args) => {
+      this.off(eventName, wrapper)
+      handler(...args)
+    }
+    return this.on(eventName, wrapper)
+  }
+
   /**
    * Remove a handler for an event. Omit `handler` to remove all handlers.
    *

package/src/services/eventBus.test.js

@@ -82,6 +82,17 @@ describe('EventBus singleton', () => {
     console.error.mockRestore()
   })
 
+  it('once fires the handler exactly once', () => {
+    const handler = jest.fn()
+    eventBus.once('single', handler)
+
+    eventBus.emit('single', 'a')
+    eventBus.emit('single', 'b')
+
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(handler).toHaveBeenCalledWith('a')
+  })
+
   it('destroys all events', () => {
     const handler = jest.fn()
     eventBus.on('destroyMe', handler)

package/src/services/hints.js

@@ -0,0 +1,47 @@
+const stripHtml = (html) => html.replace(/<[^<>]*>/g, '')
+
+/**
+ * Creates the hints service. Manages a single active toast hint shown in the
+ * Hints container. Calling show() replaces any current hint and
+ * restarts the dismiss timer. Internally calls announce() so screen readers
+ * receive the message through the live region without callers needing to pair
+ * the two calls manually.
+ */
+export function createHints (announce) {
+  const subscribers = new Set()
+  let current = null
+  let timer = null
+
+  const notify = () => subscribers.forEach(fn => fn(current))
+
+  const clearTimer = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+
+  const dismiss = () => {
+    clearTimer()
+    current = null
+    notify()
+  }
+
+  const show = (html, options = {}) => {
+    const { duration = 4000, announce: announceText } = options
+    clearTimer()
+    current = { html }
+    notify()
+    announce(announceText ?? stripHtml(html), 'plugin')
+    if (duration > 0) {
+      timer = setTimeout(dismiss, duration)
+    }
+  }
+
+  const subscribe = (fn) => {
+    subscribers.add(fn)
+    return () => subscribers.delete(fn)
+  }
+
+  return { show, dismiss, subscribe }
+}

package/src/services/hints.test.js

@@ -0,0 +1,110 @@
+import { createHints } from './hints.js'
+
+let announce
+let hints
+
+beforeEach(() => {
+  jest.useFakeTimers()
+  announce = jest.fn()
+  hints = createHints(announce)
+})
+
+afterEach(() => {
+  jest.useRealTimers()
+})
+
+// ─── show() ──────────────────────────────────────────────────────────────────
+
+describe('show', () => {
+  it('notifies subscribers with the html payload', () => {
+    const sub = jest.fn()
+    hints.subscribe(sub)
+    hints.show('<kbd>Enter</kbd> to select')
+    expect(sub).toHaveBeenCalledWith({ html: '<kbd>Enter</kbd> to select' })
+  })
+
+  it('calls announce with stripped html', () => {
+    hints.show('<kbd>Enter</kbd> to select')
+    expect(announce).toHaveBeenCalledWith('Enter to select', 'plugin')
+  })
+
+  it('calls announce with custom text when announce option is provided', () => {
+    hints.show('<kbd>Alt+K</kbd> help', { announce: 'Press Alt+K for keyboard controls' })
+    expect(announce).toHaveBeenCalledWith('Press Alt+K for keyboard controls', 'plugin')
+  })
+
+  it('replaces an existing hint and resets the timer', () => {
+    const sub = jest.fn()
+    hints.subscribe(sub)
+    hints.show('first', { duration: 2000 })
+    hints.show('second', { duration: 2000 })
+    jest.advanceTimersByTime(2000)
+    expect(sub).toHaveBeenLastCalledWith(null)
+    // Only one dismiss fired (the second hint's timer)
+    expect(sub).toHaveBeenCalledTimes(3) // show1, show2, dismiss
+  })
+
+  it('auto-dismisses after duration', () => {
+    const sub = jest.fn()
+    hints.subscribe(sub)
+    hints.show('hello', { duration: 3000 })
+    jest.advanceTimersByTime(3000)
+    expect(sub).toHaveBeenLastCalledWith(null)
+  })
+
+  it('does not auto-dismiss when duration is 0', () => {
+    const sub = jest.fn()
+    hints.subscribe(sub)
+    hints.show('persistent', { duration: 0 })
+    jest.advanceTimersByTime(60000)
+    expect(sub).not.toHaveBeenCalledWith(null)
+  })
+})
+
+// ─── dismiss() ───────────────────────────────────────────────────────────────
+
+describe('dismiss', () => {
+  it('clears the active hint and notifies', () => {
+    const sub = jest.fn()
+    hints.subscribe(sub)
+    hints.show('hello')
+    hints.dismiss()
+    expect(sub).toHaveBeenLastCalledWith(null)
+  })
+
+  it('cancels the auto-dismiss timer', () => {
+    const sub = jest.fn()
+    hints.subscribe(sub)
+    hints.show('hello', { duration: 3000 })
+    hints.dismiss()
+    sub.mockClear()
+    jest.advanceTimersByTime(3000)
+    expect(sub).not.toHaveBeenCalled()
+  })
+
+  it('is safe to call when no hint is active', () => {
+    expect(() => hints.dismiss()).not.toThrow()
+  })
+})
+
+// ─── subscribe / unsubscribe ──────────────────────────────────────────────────
+
+describe('subscribe', () => {
+  it('returns an unsubscribe function', () => {
+    const sub = jest.fn()
+    const unsub = hints.subscribe(sub)
+    unsub()
+    hints.show('hello')
+    expect(sub).not.toHaveBeenCalled()
+  })
+
+  it('notifies multiple subscribers', () => {
+    const sub1 = jest.fn()
+    const sub2 = jest.fn()
+    hints.subscribe(sub1)
+    hints.subscribe(sub2)
+    hints.show('hello')
+    expect(sub1).toHaveBeenCalled()
+    expect(sub2).toHaveBeenCalled()
+  })
+})