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

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()
+  })
+})

package/src/services/patternRegistry.js

@@ -1,5 +1,6 @@
 import { BUILT_IN_PATTERNS } from '../config/patternConfig.js'
-
+import { getValueForStyle } from '../utils/getValueForStyle.js'
+import { KEY_BORDER_PATH, getEffectivePixelRatio, injectColors, hashString } from '../utils/patternUtils.js'
 const patterns = new Map()
 
 export const patternRegistry = {
@@ -31,6 +32,73 @@ export const patternRegistry = {
    */
   list () {
     return [...patterns.values()]
+  },
+
+  /**
+   * Clears all registered patterns (including built-ins). Mainly for testing purposes.
+   */
+  clear () {
+    patterns.clear()
+  },
+
+  /**
+   * Returns the raw (un-coloured) inner SVG content for a style's pattern.
+   * Precedence: inline fillPatternSvgContent → named fillPattern from registry.
+   *
+   * @param {Object} style
+   * @returns {string|null}
+   */
+  getPatternInnerContent (style) {
+    if (style.fillPatternSvgContent) {
+      return style.fillPatternSvgContent
+    }
+    if (style.fillPattern) {
+      return this.get(style.fillPattern)?.svgContent ?? null
+    }
+    return null
+  },
+
+  /**
+ * Returns colour-injected SVG path content for use in Key panel pattern symbols.
+ * Returns { border, content } where border is the rounded-rect outline and content
+ * is the pattern fill. Returns null if the style has no pattern.
+ *
+ * @param {Object} style
+ * @param {string} mapStyleId
+ * @returns {{ border: string, content: string }|null}
+ */
+  getKeyPatternPaths (style, mapStyleId) {
+    const innerContent = this.getPatternInnerContent(style)
+    if (!innerContent) {
+      return null
+    }
+    const fg = getValueForStyle(style.fillPatternForegroundColor, mapStyleId) || 'black'
+    const bg = getValueForStyle(style.fillPatternBackgroundColor, mapStyleId) || 'transparent'
+    const borderStroke = getValueForStyle(style.stroke, mapStyleId) || fg
+    const keyPatternPaths = {
+      border: injectColors(KEY_BORDER_PATH, borderStroke, bg),
+      content: injectColors(innerContent, fg, bg)
+    }
+    return keyPatternPaths
+  },
+
+  /**
+ * Returns a deterministic image ID for a pattern + resolved colour + pixel ratio combination.
+ *
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @param {number} [pixelRatio=1]
+ * @returns {string|null}
+ */
+  getPatternImageId (dataset, mapStyleId, pixelRatio = 1) {
+    const innerContent = this.getPatternInnerContent(dataset)
+    if (!innerContent) {
+      return null
+    }
+    const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
+    const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
+    const effectiveRatio = getEffectivePixelRatio(pixelRatio)
+    return `pattern-${hashString(innerContent + fg + bg)}-${effectiveRatio}x`
   }
 }
 

package/src/services/patternRegistry.test.js

@@ -1,5 +1,5 @@
 import { patternRegistry } from './patternRegistry.js'
-
+import { KEY_BORDER_PATH } from '../utils/patternUtils.js'
 describe('patternRegistry', () => {
   describe('built-in patterns', () => {
     test.each([
@@ -45,4 +45,115 @@ describe('patternRegistry', () => {
       expect(all.every(p => p.id && p.svgContent)).toBe(true)
     })
   })
+
+  describe('getPatternInnerContent', () => {
+    test('returns fillPatternSvgContent when set (inline SVG takes precedence)', () => {
+      const style = { fillPatternSvgContent: '<path d="custom"/>', fillPattern: 'dot' }
+      expect(patternRegistry.getPatternInnerContent(style)).toBe('<path d="custom"/>')
+    })
+
+    test('returns svgContent from registry for a named fillPattern', () => {
+      const style = { fillPattern: 'dot' }
+      patternRegistry.register('dot', '<path d="M4 4" fill="{{foregroundColor}}"/>')
+      expect(patternRegistry.getPatternInnerContent(style)).toBe('<path d="M4 4" fill="{{foregroundColor}}"/>')
+    })
+
+    test('returns null for an unregistered fillPattern name', () => {
+      const style = { fillPattern: 'unknown-pattern' }
+      expect(patternRegistry.getPatternInnerContent(style)).toBeNull()
+    })
+
+    test('returns null when no pattern is configured', () => {
+      expect(patternRegistry.getPatternInnerContent({})).toBeNull()
+    })
+  })
+
+  describe('getKeyPatternPaths', () => {
+    test('returns border and content strings with colours injected', () => {
+      const dataset = {
+        fillPattern: 'dot',
+        fillPatternForegroundColor: 'red',
+        fillPatternBackgroundColor: 'white',
+        stroke: 'black'
+      }
+      const result = patternRegistry.getKeyPatternPaths(dataset, 'style-a')
+      expect(result).not.toBeNull()
+      expect(result.border).toContain('black') // stroke colour
+      expect(result.border).toContain('white') // background colour
+      expect(result.content).toContain('red') // foreground colour
+      expect(result.border).not.toContain('{{foregroundColor}}')
+      expect(result.content).not.toContain('{{foregroundColor}}')
+    })
+
+    test('returns null when no pattern content is found', () => {
+      expect(patternRegistry.getKeyPatternPaths({ fillPattern: 'unknown' }, 'style-a')).toBeNull()
+    })
+
+    test('falls back to "black" fg and "transparent" bg when colour properties are absent', () => {
+      const result = patternRegistry.getKeyPatternPaths({ fillPattern: 'dot' }, 'style-a')
+      expect(result).not.toBeNull()
+      expect(result.content).toContain('black')
+      expect(result.border).toContain('transparent')
+    })
+
+    test('border stroke falls back to foreground colour when stroke is absent', () => {
+      const result = patternRegistry.getKeyPatternPaths(
+        { fillPattern: 'dot', fillPatternForegroundColor: 'green' },
+        'style-a'
+      )
+      expect(result).not.toBeNull()
+      // borderStroke falls back to fg ('green'), so the border uses green for both stroke and background
+      expect(result.border).toContain('green')
+    })
+
+    test('KEY_BORDER_PATH contains foregroundColor and backgroundColor tokens', () => {
+      expect(KEY_BORDER_PATH).toContain('{{foregroundColor}}')
+      expect(KEY_BORDER_PATH).toContain('{{backgroundColor}}')
+    })
+  })
+
+  describe('patternRegistry.getPatternImageId', () => {
+    test('returns a deterministic string id', () => {
+      const dataset = { fillPattern: 'dot', fillPatternForegroundColor: 'red', fillPatternBackgroundColor: 'blue' }
+      const id = patternRegistry.getPatternImageId(dataset, 'style-a')
+      expect(typeof id).toBe('string')
+      expect(id).toMatch(/^pattern-/)
+      expect(id).toBe(patternRegistry.getPatternImageId(dataset, 'style-a'))
+    })
+
+    test('returns null when no pattern content is found', () => {
+      expect(patternRegistry.getPatternImageId({ fillPattern: 'unknown' }, 'style-a')).toBeNull()
+    })
+
+    test('produces different ids for different colours', () => {
+      const base = { fillPattern: 'dot' }
+      const idA = patternRegistry.getPatternImageId({ ...base, fillPatternForegroundColor: 'red' }, 'style-a')
+      const idB = patternRegistry.getPatternImageId({ ...base, fillPatternForegroundColor: 'blue' }, 'style-a')
+      expect(idA).not.toBe(idB)
+    })
+
+    test('floors effective ratio at 2 * so low-DPI ids match 2x', () => {
+      const dataset = { fillPattern: 'dot' }
+      const id1x = patternRegistry.getPatternImageId(dataset, 'style-a', 1)
+      expect(id1x).toMatch(/-2x$/)
+    })
+
+    test('produces different ids for pixelRatios above the floor', () => {
+      const dataset = { fillPattern: 'dot' }
+      const id2x = patternRegistry.getPatternImageId(dataset, 'style-a', 2)
+      const id3x = patternRegistry.getPatternImageId(dataset, 'style-a', 3)
+      expect(id2x).not.toBe(id3x)
+      expect(id2x).toMatch(/-4x$/)
+      expect(id3x).toMatch(/-6x$/)
+    })
+
+    test('falls back to "black" foreground and "transparent" background when colours are absent', () => {
+      const id = patternRegistry.getPatternImageId({ fillPattern: 'dot' }, 'style-a')
+      const idExplicit = patternRegistry.getPatternImageId(
+        { fillPattern: 'dot', fillPatternForegroundColor: 'black', fillPatternBackgroundColor: 'transparent' },
+        'style-a'
+      )
+      expect(id).toBe(idExplicit)
+    })
+  })
 })

package/src/services/reverseGeocode.js

@@ -7,6 +7,10 @@ export function createReverseGeocode ({ url, transformRequest, load }, crs) {
   }
 }
 
+export function hasReverseGeocode () {
+  return reverseGeocodeFn !== null
+}
+
 export function reverseGeocode (zoom, coord) {
   if (!reverseGeocodeFn) {
     throw new Error('ReverseGeocode not initialised')

package/src/services/reverseGeocode.test.js

@@ -1,5 +1,5 @@
 // reverseGeocode.test.js
-import { createReverseGeocode, reverseGeocode } from './reverseGeocode'
+import { createReverseGeocode, reverseGeocode, hasReverseGeocode } from './reverseGeocode'
 
 describe('reverseGeocode module', () => {
   beforeEach(() => {
@@ -11,6 +11,10 @@ describe('reverseGeocode module', () => {
     expect(() => reverseGeocode(10, [0, 0])).toThrow('ReverseGeocode not initialised')
   })
 
+  it('hasReverseGeocode returns false before initialisation', () => {
+    expect(hasReverseGeocode()).toBe(false)
+  })
+
   it('sets reverseGeocodeFn via createReverseGeocode and calls providerFn correctly', async () => {
     const mockProviderFn = jest.fn().mockResolvedValue('result')
 
@@ -44,6 +48,12 @@ describe('reverseGeocode module', () => {
     expect(result).toBe('result')
   })
 
+  it('hasReverseGeocode returns true after initialisation', () => {
+    const config = { url: 'x', transformRequest: jest.fn(), load: jest.fn().mockResolvedValue(jest.fn()) }
+    createReverseGeocode(config, 'EPSG:4326')
+    expect(hasReverseGeocode()).toBe(true)
+  })
+
   it('supports multiple calls after initialisation', async () => {
     const mockProviderFn = jest.fn().mockResolvedValue('ok')
 

package/src/services/symbolRegistry.js

@@ -1,21 +1,33 @@
 import { getValueForStyle } from '../utils/getValueForStyle.js'
 import { symbolDefaults, pin, circle, square, graphics } from '../config/symbolConfig.js'
-import { SCHEME_COLORS } from '../config/mapTheme.js'
+import { getSymbolStyleColors, getSymbolViewBox } from '../utils/symbolUtils.js'
+import { THEME_COLORS } from '../config/mapTheme.js'
+import { rasteriseToImageData } from '../../providers/maplibre/src/utils/rasteriseToImageData.js'
 
 const symbols = new Map()
+// Module-level cache: imageId → ImageData. Avoids re-rasterising identical symbols.
+const imageDataCache = new Map()
 let _constructorDefaults = {}
 
+const HASH_BASE = 36
+
+const hashString = (str) => {
+  let hash = 0
+  for (const ch of str) {
+    hash = Math.trunc(((hash << 5) - hash) + ch.codePointAt(0))
+  }
+  return Math.abs(hash).toString(HASH_BASE)
+}
+
 // Keys that are structural — not token values for SVG substitution
 const STRUCTURAL = new Set(['id', 'svg', 'viewBox', 'anchor', 'symbol', 'symbolSvgContent'])
 
-// selectedWidth is app-wide — not overridable at symbol registration level.
-// selectedColor is a map style concern — always injected from mapStyle, never from cascade.
-const REGISTRY_EXCLUDED = new Set([...STRUCTURAL, 'selectedWidth'])
+// selectedColor and activeColor are map style concerns — always injected from mapStyle, never from cascade.
 
 function resolveValues (symbolDef, markerValues, mapStyle) {
   const mapStyleId = mapStyle?.id
   const symbolTokens = Object.fromEntries(
-    Object.entries(symbolDef || {}).filter(([k]) => !REGISTRY_EXCLUDED.has(k))
+    Object.entries(symbolDef || {}).filter(([k]) => !STRUCTURAL.has(k))
   )
   const constructorTokens = Object.fromEntries(
     Object.entries(_constructorDefaults).filter(([k]) => !STRUCTURAL.has(k))
@@ -24,10 +36,11 @@ function resolveValues (symbolDef, markerValues, mapStyle) {
     Object.entries(markerValues).filter(([, v]) => v != null)
   )
   const merged = { ...symbolDefaults, ...constructorTokens, ...symbolTokens, ...defined }
-  // haloColor and selectedColor are map style concerns — always injected from mapStyle, never from the cascade
-  const scheme = SCHEME_COLORS[mapStyle?.mapColorScheme] ?? SCHEME_COLORS.light
+  // haloColor, selectedColor and activeColor are map style concerns — always injected from mapStyle, never from the cascade
+  const scheme = THEME_COLORS[mapStyle?.mapColorScheme] ?? THEME_COLORS.light
   merged.haloColor = mapStyle?.haloColor ?? scheme.haloColor
   merged.selectedColor = mapStyle?.selectedColor ?? scheme.selectedColor
+  merged.activeColor = mapStyle?.activeColor ?? scheme.activeColor
   if (typeof merged.graphic === 'string' && graphics[merged.graphic]) {
     merged.graphic = graphics[merged.graphic]
   }
@@ -77,37 +90,159 @@ export const symbolRegistry = {
   },
 
   /**
-   * Resolve a symbol's SVG string for normal (unselected) rendering.
-   * The selected ring is always hidden regardless of cascade values.
+   * Clears all registered symbols (including built-ins). Mainly for testing purposes.
+   */
+  clear () {
+    symbols.clear()
+  },
+
+  /**
+   * Clears all registered symbols (including built-ins). Mainly for testing purposes.
+   */
+  initialise () {
+    this.register(pin)
+    this.register(circle)
+    this.register(square)
+  },
+
+  /**
+   * Resolve a symbol's SVG string for normal (unselected, inactive) rendering.
+   * Both selectedColor and activeColor are set to 'none' — all rings hidden.
    *
    * @param {Object} symbolDef - Symbol definition
    * @param {Object} styleColors - Token overrides
-   * @param {Object} mapStyle - Current map style config (provides selectedColor, haloColor)
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
    * @returns {string} Resolved SVG string
    */
   resolve (symbolDef, styleColors, mapStyle) {
     const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
     if (!symbolDef) { return '' }
-    colors.selectedColor = ''
+    colors.selectedColor = 'none'
+    colors.activeColor = 'none'
     return resolveLayer(symbolDef.svg, colors)
   },
 
   /**
-   * Resolve a symbol's SVG string for selected rendering.
-   * selectedColor comes from mapStyle.selectedColor (or the hardcoded fallback).
+   * Resolve a symbol's SVG string for active (keyboard cursor) rendering.
+   * Both selectedColor (committed ring) and activeColor (focus ring) are shown simultaneously,
+   * so an item that is active always displays both rings regardless of selection state.
    *
    * @param {Object} symbolDef - Symbol definition
    * @param {Object} styleColors - Token overrides
-   * @param {Object} mapStyle - Current map style config (provides selectedColor, haloColor)
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
+   * @returns {string} Resolved SVG string
+   */
+  resolveActive (symbolDef, styleColors, mapStyle) {
+    const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
+    if (!symbolDef) { return '' }
+    return resolveLayer(symbolDef.svg, colors)
+  },
+
+  /**
+   * Resolve a symbol's SVG string for committed-selection rendering.
+   * selectedColor (committed ring) is shown; activeColor is set to 'none'.
+   *
+   * @param {Object} symbolDef - Symbol definition
+   * @param {Object} styleColors - Token overrides
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
    * @returns {string} Resolved SVG string
    */
   resolveSelected (symbolDef, styleColors, mapStyle) {
     const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
     if (!symbolDef) { return '' }
+    colors.activeColor = 'none'
     return resolveLayer(symbolDef.svg, colors)
+  },
+
+  // ─── Image IDs ────────────────────────────────────────────────────────────────
+
+  /**
+ * Returns a deterministic image ID for a symbol in normal or selected state.
+ * Based on the hash of the fully resolved SVG content and the pixel ratio.
+ *
+ * @param {Object} style
+ * @param {Object} mapStyle - Current map style config (provides id, selectedColor, haloColor)
+ * @param {boolean} [selected=false]
+ * @param {number} [pixelRatio=2] - Device pixel ratio × map size scale factor
+ * @returns {string|null}
+ */
+  getSymbolImageId (style, mapStyle, active = false, pixelRatio = 2) {
+    const symbolDef = this.getSymbolDef(style)
+    if (!symbolDef) {
+      return null
+    }
+    const styleColors = getSymbolStyleColors(style)
+    const resolved = active
+      ? this.resolveActive(symbolDef, styleColors, mapStyle)
+      : this.resolve(symbolDef, styleColors, mapStyle)
+    return `symbol-${active ? 'act-' : ''}${hashString(resolved)}-${pixelRatio}x`
+  },
+
+  /**
+   * Resolves the symbolDef for a style's symbol config.
+   *
+   * style.symbol is a string symbol ID (e.g. 'pin').
+   * style.symbolSvgContent is inline SVG content for a custom symbol.
+   *
+   * @param {Object} style
+   * @returns {Object|undefined}
+   */
+  getSymbolDef (style) {
+    if (style.symbolSvgContent) {
+      return { svg: style.symbolSvgContent }
+    }
+    if (style.symbol) {
+      return this.get(style.symbol)
+    }
+    return undefined
+  },
+
+  /**
+ * Rasterise one variant of a symbol to ImageData for use as a MapLibre image.
+ * Results are cached by imageId so identical symbols are only rendered once.
+ *
+ * @param {Object} style - Dataset or marker config with symbol properties
+ * @param {Object} mapStyle - Current map style config
+ * @param {'normal'|'active'|'selected'} variant
+ *   - `'normal'`   — no rings (default display)
+ *   - `'active'`   — both rings (keyboard cursor, yellow + black)
+ *   - `'selected'` — selected ring only (black)
+ * @param {number} pixelRatio - Device pixel ratio × map size scale factor
+ * @returns {Promise<{imageId: string, imageData: ImageData}|null>}
+ */
+  async rasteriseSymbolImage (style, mapStyle, variant, pixelRatio) {
+    const symbolDef = this.getSymbolDef(style)
+    if (!symbolDef) {
+      return null
+    }
+    const styleColors = getSymbolStyleColors(style)
+    let resolvedContent, prefix
+    if (variant === 'active') {
+      resolvedContent = this.resolveActive(symbolDef, styleColors, mapStyle)
+      prefix = 'act-'
+    } else if (variant === 'selected') {
+      resolvedContent = this.resolveSelected(symbolDef, styleColors, mapStyle)
+      prefix = 'sel-'
+    } else {
+      resolvedContent = this.resolve(symbolDef, styleColors, mapStyle)
+      prefix = ''
+    }
+
+    const imageId = `symbol-${prefix}${hashString(resolvedContent)}-${pixelRatio}x`
+
+    let imageData = imageDataCache.get(imageId)
+    if (!imageData) {
+      const viewBox = getSymbolViewBox(style, symbolDef)
+      const [,, width, height] = viewBox.split(' ').map(Number)
+      // Render at pixelRatio× to keep icons crisp at the current device DPI and map size.
+      // MapLibre receives the matching pixelRatio so the image displays at its original logical size.
+      const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="${width * pixelRatio}" height="${height * pixelRatio}" viewBox="${viewBox}">${resolvedContent}</svg>`
+      imageData = await rasteriseToImageData(svgString, width * pixelRatio, height * pixelRatio)
+      imageDataCache.set(imageId, imageData)
+    }
+
+    return { imageId, imageData }
   }
 }
 
-symbolRegistry.register(pin)
-symbolRegistry.register(circle)
-symbolRegistry.register(square)
+symbolRegistry.initialise()