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

package/providers/maplibre/src/utils/symbolImages.test.js

@@ -1,9 +1,6 @@
-import { anchorToMaplibre, getSymbolImageId, registerSymbols } from './symbolImages.js'
+import { anchorToMaplibre, addSymbolsToMap } from './symbolImages.js'
 import { symbolRegistry } from '../../../../src/services/symbolRegistry.js'
 
-const STYLE_ID = 'test'
-const mapStyle = { id: STYLE_ID }
-
 beforeAll(() => {
   globalThis.URL.createObjectURL = jest.fn(() => 'blob:mock')
   globalThis.URL.revokeObjectURL = jest.fn()
@@ -87,142 +84,100 @@ describe('anchorToMaplibre', () => {
   })
 })
 
-// ─── getSymbolImageId ─────────────────────────────────────────────────────────
-
-describe('getSymbolImageId', () => {
-  it('returns null when dataset has no symbol', () => {
-    expect(getSymbolImageId({}, mapStyle, symbolRegistry)).toBeNull()
-  })
-
-  it('returns null for an unregistered symbol id', () => {
-    expect(getSymbolImageId({ symbol: 'does-not-exist' }, mapStyle, symbolRegistry)).toBeNull()
-  })
-
-  it('returns a string prefixed symbol- for normal state', () => {
-    const id = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry)
-    expect(typeof id).toBe('string')
-    expect(id).toMatch(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/)
-  })
-
-  it('returns a string prefixed symbol-sel- for selected state', () => {
-    const id = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry, true)
-    expect(typeof id).toBe('string')
-    expect(id).toMatch(/^symbol-sel-[a-z0-9]+-\d+(\.\d+)?x$/)
-  })
-
-  it('normal and selected ids differ for the same dataset', () => {
-    const normalId = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry, false)
-    const selectedId = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry, true)
-    expect(normalId).not.toBe(selectedId)
-  })
-
-  it('same dataset and style always produces the same id', () => {
-    const id1 = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry)
-    const id2 = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry)
-    expect(id1).toBe(id2)
-  })
-
-  it('different symbols produce different ids', () => {
-    const pinId = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry)
-    const circleId = getSymbolImageId({ symbol: 'circle' }, mapStyle, symbolRegistry)
-    expect(pinId).not.toBe(circleId)
-  })
-
-  it('different backgrounds produce different ids', () => {
-    const redId = getSymbolImageId({ symbol: 'pin', symbolBackgroundColor: '#ff0000' }, mapStyle, symbolRegistry)
-    const blueId = getSymbolImageId({ symbol: 'pin', symbolBackgroundColor: '#0000ff' }, mapStyle, symbolRegistry)
-    expect(redId).not.toBe(blueId)
-  })
-
-  it('resolves inline symbolSvgContent', () => {
-    const dataset = {
-      symbolSvgContent: '<circle cx="19" cy="19" r="12" fill="{{backgroundColor}}"/>',
-      symbolViewBox: '0 0 38 38',
-      symbolAnchor: [0.5, 0.5]
-    }
-    const id = getSymbolImageId(dataset, mapStyle, symbolRegistry)
-    expect(id).toMatch(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/)
-  })
-})
-
-// ─── registerSymbols ──────────────────────────────────────────────────────────
+// ─── addSymbolsToMap ──────────────────────────────────────────────────────────
 
 const makeMap = (existingIds = []) => ({
-  _symbolImageMap: {},
+  _activeSymbolImageMap: {},
+  _selectedSymbolImageMap: {},
   hasImage: jest.fn((id) => existingIds.includes(id)),
   addImage: jest.fn()
 })
+const STYLE_ID = 'test'
+const mapStyle = { id: STYLE_ID }
 
-describe('registerSymbols — registration', () => {
+describe('addSymbolsToMap — registration', () => {
   it('returns early and does not touch map for empty configs', async () => {
     const map = makeMap()
-    await registerSymbols(map, [], mapStyle, symbolRegistry)
+    await addSymbolsToMap(map, [], mapStyle, symbolRegistry)
     expect(map.hasImage).not.toHaveBeenCalled()
     expect(map.addImage).not.toHaveBeenCalled()
   })
 
-  it('resets _symbolImageMap before processing', async () => {
+  it('resets _activeSymbolImageMap and _selectedSymbolImageMap before processing', async () => {
     const map = makeMap()
-    map._symbolImageMap = { stale: 'entry' }
-    await registerSymbols(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
-    expect(map._symbolImageMap).not.toHaveProperty('stale')
+    map._activeSymbolImageMap = { stale: 'entry' }
+    map._selectedSymbolImageMap = { stale: 'entry' }
+    await addSymbolsToMap(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
+    expect(map._activeSymbolImageMap).not.toHaveProperty('stale')
+    expect(map._selectedSymbolImageMap).not.toHaveProperty('stale')
   })
 
-  it('calls addImage for normal and selected variants', async () => {
+  it('calls addImage for normal, active and selected variants', async () => {
     const map = makeMap()
-    await registerSymbols(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
-    expect(map.addImage).toHaveBeenCalledTimes(2)
+    await addSymbolsToMap(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
+    expect(map.addImage).toHaveBeenCalledTimes(3) // NOSONAR S109 — normal, active, selected
     expect(map.addImage).toHaveBeenCalledWith(expect.stringMatching(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/), expect.any(Object), { pixelRatio: 2 })
+    expect(map.addImage).toHaveBeenCalledWith(expect.stringMatching(/^symbol-act-[a-z0-9]+-\d+(\.\d+)?x$/), expect.any(Object), { pixelRatio: 2 })
     expect(map.addImage).toHaveBeenCalledWith(expect.stringMatching(/^symbol-sel-[a-z0-9]+-\d+(\.\d+)?x$/), expect.any(Object), { pixelRatio: 2 })
   })
 
-  it('populates _symbolImageMap with normal → selected id pairs', async () => {
+  it('populates _activeSymbolImageMap and _selectedSymbolImageMap with normal → variant id pairs', async () => {
     const map = makeMap()
-    await registerSymbols(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
-    const normalId = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry, false)
-    const selectedId = getSymbolImageId({ symbol: 'pin' }, mapStyle, symbolRegistry, true)
-    expect(map._symbolImageMap[normalId]).toBe(selectedId)
-  })
-
-  it('skips addImage when image is already registered', async () => {
-    const normalId = getSymbolImageId({ symbol: 'circle' }, mapStyle, symbolRegistry, false)
-    const selectedId = getSymbolImageId({ symbol: 'circle' }, mapStyle, symbolRegistry, true)
-    const map = makeMap([normalId, selectedId])
-    await registerSymbols(map, [{ symbol: 'circle' }], mapStyle, symbolRegistry)
+    await addSymbolsToMap(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
+    const normalId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, false)
+    const activeId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, true)
+    const selectedId = map._selectedSymbolImageMap[normalId]
+    expect(map._activeSymbolImageMap[normalId]).toBe(activeId)
+    expect(selectedId).toMatch(/^symbol-sel-[a-z0-9]+-\d+(\.\d+)?x$/)
+  })
+
+  it('skips addImage when all three variant images are already registered', async () => {
+    // Run once to discover the selected image ID (not derivable without rasterising)
+    const setupMap = makeMap()
+    await addSymbolsToMap(setupMap, [{ symbol: 'circle' }], mapStyle, symbolRegistry)
+    const normalId = symbolRegistry.getSymbolImageId({ symbol: 'circle' }, mapStyle, false)
+    const activeId = symbolRegistry.getSymbolImageId({ symbol: 'circle' }, mapStyle, true)
+    const selectedId = setupMap._selectedSymbolImageMap[normalId]
+
+    const map = makeMap([normalId, activeId, selectedId])
+    await addSymbolsToMap(map, [{ symbol: 'circle' }], mapStyle, symbolRegistry)
     expect(map.addImage).not.toHaveBeenCalled()
   })
 
   it('processes multiple configs independently', async () => {
     const map = makeMap()
-    await registerSymbols(map, [{ symbol: 'pin' }, { symbol: 'circle' }], mapStyle, symbolRegistry)
-    expect(map.addImage).toHaveBeenCalledTimes(4)
-    expect(Object.keys(map._symbolImageMap)).toHaveLength(2)
+    await addSymbolsToMap(map, [{ symbol: 'pin' }, { symbol: 'circle' }], mapStyle, symbolRegistry)
+    expect(map.addImage).toHaveBeenCalledTimes(6) // NOSONAR S109 — 2 configs × 3 variants each
+    expect(Object.keys(map._activeSymbolImageMap)).toHaveLength(2)
+    expect(Object.keys(map._selectedSymbolImageMap)).toHaveLength(2)
   })
 })
 
-describe('registerSymbols — null results and caching', () => {
+describe('addSymbolsToMap — null results and caching', () => {
   it('does not call addImage when rasteriseSymbolImage returns null', async () => {
-    // getSymbolImageId (called twice — normal + selected) needs a real symbolDef to produce imageIds,
+    // getSymbolImageId (called twice — normal + active) needs a real symbolDef to produce imageIds,
     // but rasteriseSymbolImage must get undefined from getSymbolDef so it returns null.
-    // The registry.get call order: [1] getSymbolImageId normal, [2] getSymbolImageId selected,
-    // [3] rasteriseSymbolImage normal, [4] rasteriseSymbolImage selected.
+    // The registry.get call order: [1] getSymbolImageId normal, [2] getSymbolImageId active,
+    // [3] rasteriseSymbolImage normal, [4] rasteriseSymbolImage active, [5] rasteriseSymbolImage selected.
     const pinDef = symbolRegistry.get('pin')
     const getSpy = jest.spyOn(symbolRegistry, 'get')
       .mockReturnValueOnce(pinDef)
       .mockReturnValueOnce(pinDef)
       .mockReturnValueOnce(undefined)
       .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined)
     const map = makeMap()
-    await registerSymbols(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
+    await addSymbolsToMap(map, [{ symbol: 'pin' }], mapStyle, symbolRegistry)
     expect(map.addImage).not.toHaveBeenCalled()
     getSpy.mockRestore()
   })
 
   it('skips config when symbolDef cannot be resolved', async () => {
     const map = makeMap()
-    await registerSymbols(map, [{ symbol: 'no-such-symbol' }], mapStyle, symbolRegistry)
+    await addSymbolsToMap(map, [{ symbol: 'no-such-symbol' }], mapStyle, symbolRegistry)
     expect(map.addImage).not.toHaveBeenCalled()
-    expect(map._symbolImageMap).toEqual({})
+    expect(map._activeSymbolImageMap).toEqual({})
+    expect(map._selectedSymbolImageMap).toEqual({})
   })
 
   it('reuses cached imageData when called again with the same pixelRatio', async () => {
@@ -230,19 +185,19 @@ describe('registerSymbols — null results and caching', () => {
     const uniqueRatio = 7
 
     const map1 = makeMap()
-    const blobCallsBefore = globalThis.URL.createObjectURL.mock.calls.length
-    await registerSymbols(map1, [{ symbol: 'pin' }], mapStyle, symbolRegistry, uniqueRatio)
-    const blobCallsAfterFirst = globalThis.URL.createObjectURL.mock.calls.length
-    // Rasterisation ran — blob was created
-    expect(blobCallsAfterFirst).toBeGreaterThan(blobCallsBefore)
+    const getContextCallsBefore = HTMLCanvasElement.prototype.getContext.mock.calls.length
+    await addSymbolsToMap(map1, [{ symbol: 'pin' }], mapStyle, symbolRegistry, uniqueRatio)
+    const getContextCallsAfterFirst = HTMLCanvasElement.prototype.getContext.mock.calls.length
+    // Rasterisation ran — canvas was used
+    expect(getContextCallsAfterFirst).toBeGreaterThan(getContextCallsBefore)
 
     // Second call with a fresh map (hasImage → false) but same ratio → cache hit
     const map2 = makeMap()
-    await registerSymbols(map2, [{ symbol: 'pin' }], mapStyle, symbolRegistry, uniqueRatio)
-    const blobCallsAfterSecond = globalThis.URL.createObjectURL.mock.calls.length
-    // No new blob created — rasterisation was skipped via cache
-    expect(blobCallsAfterSecond).toBe(blobCallsAfterFirst)
+    await addSymbolsToMap(map2, [{ symbol: 'pin' }], mapStyle, symbolRegistry, uniqueRatio)
+    const getContextCallsAfterSecond = HTMLCanvasElement.prototype.getContext.mock.calls.length
+    // No new canvas — rasterisation was skipped via cache
+    expect(getContextCallsAfterSecond).toBe(getContextCallsAfterFirst)
     // addImage still called because map2 has no pre-registered images
-    expect(map2.addImage).toHaveBeenCalledTimes(2)
+    expect(map2.addImage).toHaveBeenCalledTimes(3) // NOSONAR S109 — normal, active, selected
   })
 })

package/rollup.esm.mjs

@@ -82,7 +82,7 @@ const PREACT_EXTERNALS = [
 // dependency so it auto-installs for consumers and is resolved transparently.
 const BABEL_RUNTIME_EXTERNAL = /@babel\/runtime/
 
-const createESMConfig = (entryPath, outDir, isCore = false, manualChunks = null) => {
+const createESMConfig = (entryPath, outDir, isCore = false, manualChunks = null, extraExternals = []) => {
   const esmDir = path.resolve(__dirname, outDir)
   // Use the parent dir as output.dir so CSS can be emitted to css/index.css
   // (a sibling subdir) without Rollup 4's ban on ".." in emitted file names.
@@ -108,7 +108,8 @@ const createESMConfig = (entryPath, outDir, isCore = false, manualChunks = null)
           // instance from their own node_modules rather than a 1 MB copy bundled
           // into the provider.  (UMD keeps it bundled — no bundler available there.)
           'maplibre-gl',
-          /^@arcgis\/core/
+          /^@arcgis\/core/,
+          ...extraExternals
         ],
 
     plugins: [
@@ -228,6 +229,16 @@ const ALL_BUILDS = [
     outDir: 'providers/beta/esri/dist/esm',
     manualChunks: (id) => { if (id.includes('/esriProvider')) return 'im-esri-provider' }
   },
+  {
+    entryPath: './providers/beta/openlayers/src/index.js',
+    outDir: 'providers/beta/openlayers/dist/esm',
+    extraExternals: [/^ol\//, 'proj4'],
+    manualChunks: (id) => {
+      if (id.includes('/openlayersProvider')) {
+        return 'im-openlayers-provider'
+      }
+    }
+  },
 
   // Plugins — each lazy-loads ./manifest.js; manualChunks names that split chunk
   {
@@ -293,5 +304,5 @@ const buildsToRun = BUILD_TARGET
   : ALL_BUILDS
 
 export default buildsToRun.map(b =>
-  createESMConfig(b.entryPath, b.outDir, b.isCore || false, b.manualChunks || null)
+  createESMConfig(b.entryPath, b.outDir, b.isCore || false, b.manualChunks || null, b.extraExternals || [])
 )

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

@@ -1,4 +1,5 @@
 .im-c-actions {
+  position: relative;
   display: flex;
   flex-direction: row;
   justify-content: center;

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

@@ -6,6 +6,9 @@ import * as AppContext from '../../store/appContext' // import the module to moc
 // Simple child component to handle isHidden
 const TestChild = ({ isHidden, children, ...props }) => <div {...props}>{children}</div>
 
+const ACTIONS_SELECTOR = '.im-c-actions'
+const HIDDEN_CLASS = 'im-c-actions--hidden'
+
 describe('Actions component', () => {
   const mockUseApp = {
     openPanels: {},
@@ -53,8 +56,8 @@ describe('Actions component', () => {
         <TestChild isHidden data-testid='child2'>Child 2</TestChild>
       </Actions>
     )
-    const container = screen.getByTestId('child1').closest('.im-c-actions')
-    expect(container).toHaveClass('im-c-actions--hidden')
+    const container = screen.getByTestId('child1').closest(ACTIONS_SELECTOR)
+    expect(container).toHaveClass(HIDDEN_CLASS)
   })
 
   it('shows the container when at least one child is visible', () => {
@@ -64,7 +67,17 @@ describe('Actions component', () => {
         <TestChild isHidden data-testid='child2'>Child 2</TestChild>
       </Actions>
     )
-    const container = screen.getByTestId('child1').closest('.im-c-actions')
-    expect(container).not.toHaveClass('im-c-actions--hidden')
+    const container = screen.getByTestId('child1').closest(ACTIONS_SELECTOR)
+    expect(container).not.toHaveClass(HIDDEN_CLASS)
+  })
+
+  it('hides the container when all visible children have variant touch', () => {
+    render(
+      <Actions slot='actions'>
+        <TestChild isHidden={false} variant='touch' data-testid='child1'>Child 1</TestChild>
+      </Actions>
+    )
+    const container = screen.getByTestId('child1').closest(ACTIONS_SELECTOR)
+    expect(container).toHaveClass(HIDDEN_CLASS)
   })
 })

package/src/App/components/Hints/Hints.jsx

@@ -0,0 +1,52 @@
+import React, { useState, useEffect } from 'react'
+import { createPortal } from 'react-dom'
+import { useConfig } from '../../store/configContext.js'
+import { useService } from '../../store/serviceContext.js'
+import { useApp } from '../../store/appContext.js'
+
+/**
+ * Renders the active keyboard hint as a toast portaled into im-o-app__main.
+ * Positioned above the actions bar using --hint-bottom. All visual
+ * hints pass through here; screen reader announcements are handled internally
+ * by the hints service so callers only need hints.show().
+ *
+ * The container element (id="${mapId}-hints") is always in the DOM after mount
+ * so aria-describedby references remain valid even when no hint is showing.
+ */
+// eslint-disable-next-line camelcase, react/jsx-pascal-case
+// sonarjs/disable-next-line function-name
+export const Hints = () => {
+  const { id, keyboardHintText } = useConfig()
+  const { hints } = useService()
+  const { layoutRefs } = useApp()
+  const [activeHint, setActiveHint] = useState(null)
+  const [mounted, setMounted] = useState(false)
+
+  useEffect(() => {
+    setMounted(true)
+    return hints.subscribe(setActiveHint)
+  }, [hints])
+
+  if (!mounted || !layoutRefs.mainRef?.current) {
+    return null
+  }
+
+  return createPortal(
+    <div className='im-o-hints'>
+      <div id={`${id}-hints`} className='im-c-hints'>
+        {activeHint && (
+          <div
+            className='im-c-hints__hint'
+            dangerouslySetInnerHTML={{ __html: activeHint.html }}
+          />
+        )}
+      </div>
+      <div
+        id={`${id}-keyboard-desc`}
+        className='im-u-visually-hidden'
+        dangerouslySetInnerHTML={{ __html: keyboardHintText }}
+      />
+    </div>,
+    layoutRefs.mainRef.current
+  )
+}

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

@@ -0,0 +1,37 @@
+// ===================================================
+// Object: KeyboardHints (layout wrapper)
+// ===================================================
+
+.im-o-hints {
+  position: absolute;
+  bottom: var(--hint-bottom, var(--primary-gap));
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 1001;
+}
+
+// ===================================================
+// Component: KeyboardHints
+// ===================================================
+
+.im-c-hints {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--divider-gap);
+}
+
+.im-c-hints__hint {
+  text-wrap: nowrap;
+
+  color: var(--tooltip-foreground-color);
+  background-color: var(--tooltip-background-color);
+  border-radius: var(--tooltip-border-radius);
+  padding: var(--tooltip-padding);
+  font-size: var(--tooltip-font-size);
+  line-height: 1.2;
+}
+
+.im-c-hints__hint kbd {
+  border: var(--kbd-tooltip-border);
+}

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

@@ -0,0 +1,104 @@
+import React from 'react'
+import { render, act } from '@testing-library/react'
+import { Hints } from './Hints.jsx'
+import { useConfig } from '../../store/configContext.js'
+import { useService } from '../../store/serviceContext.js'
+import { useApp } from '../../store/appContext.js'
+
+jest.mock('../../store/configContext.js', () => ({ useConfig: jest.fn() }))
+jest.mock('../../store/serviceContext.js', () => ({ useService: jest.fn() }))
+jest.mock('../../store/appContext.js', () => ({ useApp: jest.fn() }))
+
+const CONTAINER_ID = '#test-map-hints'
+const HINT_CLASS = '.im-c-hints__hint'
+
+let capturedSubscriber
+let mockHints
+
+const setup = ({ mainEl = document.createElement('div') } = {}) => {
+  capturedSubscriber = null
+  mockHints = {
+    subscribe: jest.fn((fn) => {
+      capturedSubscriber = fn
+      return () => {}
+    })
+  }
+  useConfig.mockReturnValue({ id: 'test-map', keyboardHintText: '<kbd>Alt</kbd> + <kbd>K</kbd>' })
+  useService.mockReturnValue({ hints: mockHints })
+  useApp.mockReturnValue({ layoutRefs: { mainRef: { current: mainEl } } })
+  if (mainEl) document.body.appendChild(mainEl)
+  return mainEl
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  jest.clearAllMocks()
+})
+
+// ─── rendering ───────────────────────────────────────────────────────────────
+
+describe('Hints — rendering', () => {
+  it('renders the container into mainRef after mount', () => {
+    const mainEl = setup()
+    render(<Hints />)
+    expect(mainEl.querySelector(CONTAINER_ID)).toBeTruthy()
+  })
+
+  it('renders a persistent keyboard-desc span with the hint text', () => {
+    const mainEl = setup()
+    render(<Hints />)
+    const desc = mainEl.querySelector('#test-map-keyboard-desc')
+    expect(desc).toBeTruthy()
+    expect(desc.innerHTML).toBe('<kbd>Alt</kbd> + <kbd>K</kbd>')
+  })
+
+  it('renders no hint content when there is no active hint', () => {
+    const mainEl = setup()
+    render(<Hints />)
+    expect(mainEl.querySelector(HINT_CLASS)).toBeNull()
+  })
+
+  it('renders hint content when subscriber fires with a hint', () => {
+    const mainEl = setup()
+    render(<Hints />)
+    act(() => capturedSubscriber({ html: '<kbd>Enter</kbd> to select' }))
+    const hint = mainEl.querySelector(HINT_CLASS)
+    expect(hint).toBeTruthy()
+    expect(hint.innerHTML).toBe('<kbd>Enter</kbd> to select')
+  })
+
+  it('removes hint content when subscriber fires with null', () => {
+    const mainEl = setup()
+    render(<Hints />)
+    act(() => capturedSubscriber({ html: 'hello' }))
+    act(() => capturedSubscriber(null))
+    expect(mainEl.querySelector(HINT_CLASS)).toBeNull()
+  })
+})
+
+// ─── lifecycle ───────────────────────────────────────────────────────────────
+
+describe('Hints — lifecycle', () => {
+  it('subscribes to hints on mount', () => {
+    setup()
+    render(<Hints />)
+    expect(mockHints.subscribe).toHaveBeenCalled()
+  })
+
+  it('unsubscribes on unmount', () => {
+    const unsub = jest.fn()
+    setup()
+    mockHints = { subscribe: jest.fn(() => unsub) }
+    useService.mockReturnValue({ hints: mockHints })
+    const { unmount } = render(<Hints />)
+    unmount()
+    expect(unsub).toHaveBeenCalled()
+  })
+
+  it('renders nothing when mainRef is null', () => {
+    setup({ mainEl: null })
+    useApp.mockReturnValue({ layoutRefs: { mainRef: { current: null } } })
+    const { container } = render(<Hints />)
+    expect(container.innerHTML).toBe('')
+  })
+})

package/src/App/components/KeyboardHelp/KeyboardHelp.jsx

@@ -1,33 +1,71 @@
 // src/components/KeyboardHelp.jsx
 import React from 'react'
 import { useConfig } from '../../store/configContext'
+import { useApp } from '../../store/appContext.js'
 import { getKeyboardShortcuts } from '../../registry/keyboardShortcutRegistry.js'
+import { Tabs } from '../Tabs/Tabs.jsx'
+
+const ShortcutList = ({ items }) => (
+  <dl className='im-c-keyboard-help__list'>
+    {items.map((item) => (
+      <div key={item.id} className='im-c-keyboard-help__item'>
+        <dt className='im-c-keyboard-help__title'>{item.title}</dt>
+        <dd className='im-c-keyboard-help__description' dangerouslySetInnerHTML={{ __html: item.command }} />
+      </div>
+    ))}
+  </dl>
+)
+
+const buildGroupMap = (shortcuts) => shortcuts.reduce((acc, shortcut) => {
+  const group = shortcut.group || 'Navigate'
+  if (!acc[group]) {
+    acc[group] = []
+  }
+  acc[group].push(shortcut)
+  return acc
+}, {})
+
+const getDefaultTab = (groupEntries, context) => {
+  const exactMatch = groupEntries.find(([, items]) =>
+    items.some(s => (s.context ?? 'viewport') === context)
+  )
+  if (exactMatch) {
+    return exactMatch[0]
+  }
+  const globalMatch = groupEntries.find(([, items]) =>
+    items.some(s => s.context === 'global')
+  )
+  return globalMatch?.[0] ?? groupEntries[0][0]
+}
 
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
-export const KeyboardHelp = () => {
+export const KeyboardHelp = ({ context = 'viewport' }) => { // NOSONAR: project does not use PropTypes
   const appConfig = useConfig()
-  const groups = getKeyboardShortcuts(appConfig).reduce((acc, shortcut) => {
-    acc[shortcut.group] = acc[shortcut.group] || []
-    acc[shortcut.group].push(shortcut)
-    return acc
-  }, {})
+  const { listboxIsActive } = useApp()
+  const allShortcuts = getKeyboardShortcuts(appConfig)
+  const shortcuts = listboxIsActive
+    ? allShortcuts
+    : allShortcuts.filter(s => !s.group && s.context !== 'listbox')
+  const groupMap = buildGroupMap(shortcuts)
+  const groupEntries = Object.entries(groupMap)
+
+  if (groupEntries.length <= 1) {
+    return (
+      <div className='im-c-keyboard-help'>
+        <ShortcutList items={shortcuts} />
+      </div>
+    )
+  }
+
+  const tabs = groupEntries.map(([name, items]) => ({
+    name,
+    content: <ShortcutList items={items} />
+  }))
 
   return (
     <div className='im-c-keyboard-help'>
-      {Object.entries(groups).map(([groupName, items]) => (
-        <div key={groupName} className='im-c-keyboard-help__group'>
-          {/* <h3 className='im-c-keyboard-help__title'>{groupName}</h3> */}
-          <dl className='im-c-keyboard-help__list'>
-            {items.map((item) => (
-              <div key={item.id} className='im-c-keyboard-help__item'>
-                <dt className='im-c-keyboard-help__title'>{item.title}</dt>
-                <dd className='im-c-keyboard-help__description' dangerouslySetInnerHTML={{ __html: item.command }} />
-              </div>
-            ))}
-          </dl>
-        </div>
-      ))}
+      <Tabs tabs={tabs} defaultTab={getDefaultTab(groupEntries, context)} />
     </div>
   )
 }

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

@@ -2,6 +2,8 @@
 // Component: KeyboardHelp
 // ===================================================
 
+@use '../../../scss/tools/index' as tools;
+
 // 1. Base styles
 
 // 2. Elements
@@ -15,6 +17,10 @@
     padding: 10px 0;
     width: 100%;
     border-top: 1px solid var(--content-border-color);
+
+    &:last-child {
+        padding-bottom: 0;
+    }
 }
 
 .im-c-keyboard-help__group:last-child .im-c-keyboard-help__item:last-child {
@@ -40,3 +46,7 @@
     display: block;
     margin-top: 5px;
 }
+
+.im-c-tabs__panel .im-c-keyboard-help__item:first-child {
+    border-top: 0;
+}