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

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

package/src/services/symbolRegistry.test.js

@@ -1,12 +1,16 @@
 import { symbolRegistry } from './symbolRegistry.js'
-import { symbolDefaults } from '../config/symbolConfig.js'
-import { SCHEME_COLORS } from '../config/mapTheme.js'
+import { symbolDefaults, pin } from '../config/symbolConfig.js'
+import { THEME_COLORS } from '../config/mapTheme.js'
 import { getValueForStyle } from '../utils/getValueForStyle.js'
 
 const STYLE_ID = 'test'
 const mapStyle = { id: STYLE_ID }
+const COLOR_OVERRIDE = '#ff0000'
+const FILL_OVERRIDE = `fill="${COLOR_OVERRIDE}"`
 
 beforeEach(() => {
+  symbolRegistry.clear()
+  symbolRegistry.initialise()
   symbolRegistry.setDefaults({})
 })
 
@@ -58,20 +62,20 @@ describe('symbolRegistry — setDefaults / getDefaults', () => {
   })
 
   it('constructor defaults override hardcoded defaults', () => {
-    symbolRegistry.setDefaults({ backgroundColor: '#ff0000', symbol: 'circle' })
+    symbolRegistry.setDefaults({ backgroundColor: COLOR_OVERRIDE, symbol: 'circle' })
     const defaults = symbolRegistry.getDefaults()
-    expect(defaults.backgroundColor).toBe('#ff0000')
+    expect(defaults.backgroundColor).toBe(COLOR_OVERRIDE)
     expect(defaults.symbol).toBe('circle')
   })
 
   it('constructor defaults do not affect unset properties', () => {
-    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    symbolRegistry.setDefaults({ backgroundColor: COLOR_OVERRIDE })
     const defaults = symbolRegistry.getDefaults()
     expect(defaults.foregroundColor).toBe(symbolDefaults.foregroundColor)
   })
 
   it('setDefaults with null or undefined resets to hardcoded defaults', () => {
-    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    symbolRegistry.setDefaults({ backgroundColor: COLOR_OVERRIDE })
     symbolRegistry.setDefaults(null)
     expect(symbolRegistry.getDefaults().backgroundColor).toBe(symbolDefaults.backgroundColor)
   })
@@ -81,24 +85,23 @@ describe('symbolRegistry — resolve', () => {
   const BACKGROUND_SVG = '<path fill="{{backgroundColor}}"/>'
   const symbolDef = {
     id: 'test',
-    svg: '<path fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/><path fill="{{foregroundColor}}" stroke="{{selectedColor}}"/>'
+    svg: '<path fill="{{backgroundColor}}" stroke="{{haloColor}}"/><path fill="{{foregroundColor}}" stroke="{{selectedColor}}"/><path stroke="{{activeColor}}"/>'
   }
 
   it('injects default token values when no overrides given', () => {
     const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
     expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
     expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.foregroundColor, STYLE_ID)}"`)
-    expect(resolved).toContain(`stroke-width="${symbolDefaults.haloWidth}"`)
   })
 
-  it('always produces empty selectedColor token — ring is hidden', () => {
+  it('always produces empty selectedColor and activeColor tokens — rings are hidden', () => {
     const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
-    expect(resolved).toContain('stroke=""')
+    expect(resolved).toContain('stroke="none"')
   })
 
   it('uses light scheme haloColor when mapStyle has no haloColor', () => {
     const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
-    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.haloColor}"`)
+    expect(resolved).toContain(`stroke="${THEME_COLORS.light.haloColor}"`)
   })
 
   it('uses mapStyle.haloColor when provided', () => {
@@ -107,8 +110,8 @@ describe('symbolRegistry — resolve', () => {
   })
 
   it('overrides default backgroundColor with a plain string', () => {
-    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: '#ff0000' }, mapStyle)
-    expect(resolved).toContain('fill="#ff0000"')
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: COLOR_OVERRIDE }, mapStyle)
+    expect(resolved).toContain(FILL_OVERRIDE)
   })
 
   it('overrides default with a style-keyed color', () => {
@@ -163,48 +166,70 @@ describe('symbolRegistry — resolve', () => {
   })
 })
 
-describe('symbolRegistry — resolveSelected', () => {
+describe('symbolRegistry — resolveActive (keyboard cursor state)', () => {
   const symbolDef = {
-    id: 'test-sel',
-    svg: '<path stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/><path fill="{{backgroundColor}}"/>'
+    id: 'test-active',
+    svg: '<path fill="{{selectedColor}}" stroke="{{activeColor}}" stroke-width="6"/><path fill="{{backgroundColor}}"/>'
   }
 
-  it('uses light scheme selectedColor when mapStyle has no selectedColor', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
-    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+  it('renders selectedColor from scheme when mapStyle has no selectedColor', () => {
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`fill="${THEME_COLORS.light.selectedColor}"`)
+  })
+
+  it('renders activeColor from scheme when mapStyle has no activeColor', () => {
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke="${THEME_COLORS.light.activeColor}"`)
   })
 
   it('uses mapStyle.selectedColor when provided', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
-    expect(resolved).toContain('stroke="#ff0000"')
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, { id: STYLE_ID, selectedColor: COLOR_OVERRIDE })
+    expect(resolved).toContain(FILL_OVERRIDE)
   })
 
-  it('uses selectedWidth from symbolDefaults', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
-    expect(resolved).toContain(`stroke-width="${symbolDefaults.selectedWidth}"`)
+  it('uses mapStyle.activeColor when provided', () => {
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, { id: STYLE_ID, activeColor: '#00ff00' })
+    expect(resolved).toContain('stroke="#00ff00"')
   })
 
   it('handles null styleColors — uses cascade defaults', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, null, mapStyle)
-    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+    const resolved = symbolRegistry.resolveActive(symbolDef, null, mapStyle)
+    expect(resolved).toContain(`fill="${THEME_COLORS.light.selectedColor}"`)
   })
 
   it('returns empty string for null symbolDef', () => {
-    expect(symbolRegistry.resolveSelected(null, {}, mapStyle)).toBe('')
+    expect(symbolRegistry.resolveActive(null, {}, mapStyle)).toBe('')
   })
 
   it('symbol-level selectedColor is ignored — mapStyle wins', () => {
     const defWithSelected = { ...symbolDef, selectedColor: '#00ff00' }
-    const resolved = symbolRegistry.resolveSelected(defWithSelected, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
-    expect(resolved).toContain('stroke="#ff0000"')
+    const resolved = symbolRegistry.resolveActive(defWithSelected, {}, { id: STYLE_ID, selectedColor: COLOR_OVERRIDE })
+    expect(resolved).toContain(FILL_OVERRIDE)
   })
 
   it('still resolves other tokens correctly', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, { backgroundColor: '#d4351c' }, mapStyle)
+    const resolved = symbolRegistry.resolveActive(symbolDef, { backgroundColor: '#d4351c' }, mapStyle)
     expect(resolved).toContain('fill="#d4351c"')
   })
 })
 
+describe('symbolRegistry — resolveSelected (committed selection state)', () => {
+  const symbolDef = {
+    id: 'test-selected',
+    svg: '<path fill="{{selectedColor}}"/>'
+  }
+
+  it('returns empty string for null symbolDef', () => {
+    expect(symbolRegistry.resolveSelected(null, {}, mapStyle)).toBe('')
+  })
+
+  it('handles null styleColors — uses cascade defaults', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, null, mapStyle)
+    expect(typeof resolved).toBe('string')
+    expect(resolved.length).toBeGreaterThan(0)
+  })
+})
+
 describe('symbolRegistry — graphic token', () => {
   const graphicDef = {
     id: 'test-graphic',
@@ -257,6 +282,91 @@ describe('symbolRegistry — graphic token', () => {
     const pin = symbolRegistry.get('pin')
     const resolved = symbolRegistry.resolve(pin, {}, mapStyle)
     expect(resolved).toContain(`d="${pin.graphic}"`)
-    expect(resolved).toContain('translate(19, 16) scale(0.8) translate(-8, -8)')
+    expect(resolved).toContain('translate(22, 19) scale(0.8) translate(-8, -8)')
+  })
+})
+
+// ─── getSymbolDef ─────────────────────────────────────────────────────────────
+
+describe('getSymbolDef', () => {
+  it('returns undefined when dataset has no symbol', () => {
+    expect(symbolRegistry.getSymbolDef({})).toBeUndefined()
+  })
+
+  it('looks up string symbol id in the registry', () => {
+    expect(symbolRegistry.getSymbolDef({ symbol: 'pin' })).toBe(pin)
+  })
+
+  it('returns undefined for an unregistered string symbol', () => {
+    expect(symbolRegistry.getSymbolDef({ symbol: 'missing' })).toBeUndefined()
+  })
+
+  it('returns inline def from symbolSvgContent with svg key', () => {
+    const dataset = { symbolSvgContent: '<circle/>', symbolViewBox: '0 0 10 10' }
+    const result = symbolRegistry.getSymbolDef(dataset)
+    expect(result.svg).toBe('<circle/>')
+  })
+
+  it('symbolSvgContent takes precedence over symbol id', () => {
+    const result = symbolRegistry.getSymbolDef({ symbol: 'pin', symbolSvgContent: '<circle/>' })
+    expect(result.svg).toBe('<circle/>')
+  })
+})
+
+// ─── getSymbolImageId ─────────────────────────────────────────────────────────
+
+describe('getSymbolImageId', () => {
+  it('returns null when dataset has no symbol', () => {
+    expect(symbolRegistry.getSymbolImageId({}, mapStyle)).toBeNull()
+  })
+
+  it('returns null for an unregistered symbol id', () => {
+    expect(symbolRegistry.getSymbolImageId({ symbol: 'does-not-exist' }, mapStyle)).toBeNull()
+  })
+
+  it('returns a string prefixed symbol- for normal state', () => {
+    const id = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    expect(typeof id).toBe('string')
+    expect(id).toMatch(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/)
+  })
+
+  it('returns a string prefixed symbol-act- for active state', () => {
+    const id = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, true)
+    expect(typeof id).toBe('string')
+    expect(id).toMatch(/^symbol-act-[a-z0-9]+-\d+(\.\d+)?x$/)
+  })
+
+  it('normal and active ids differ for the same dataset', () => {
+    const normalId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, false)
+    const activeId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, true)
+    expect(normalId).not.toBe(activeId)
+  })
+
+  it('same dataset and style always produces the same id', () => {
+    const id1 = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    const id2 = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    expect(id1).toBe(id2)
+  })
+
+  it('different symbols produce different ids', () => {
+    const pinId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    const circleId = symbolRegistry.getSymbolImageId({ symbol: 'circle' }, mapStyle)
+    expect(pinId).not.toBe(circleId)
+  })
+
+  it('different backgrounds produce different ids', () => {
+    const redId = symbolRegistry.getSymbolImageId({ symbol: 'pin', symbolBackgroundColor: '#ff0000' }, mapStyle)
+    const blueId = symbolRegistry.getSymbolImageId({ symbol: 'pin', symbolBackgroundColor: '#0000ff' }, mapStyle)
+    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 = symbolRegistry.getSymbolImageId(dataset, mapStyle)
+    expect(id).toMatch(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/)
   })
 })