@defra/interactive-map 0.0.17-alpha → 0.0.18-alpha

package/src/services/symbolRegistry.js

@@ -0,0 +1,113 @@
+import { getValueForStyle } from '../utils/getValueForStyle.js'
+import { symbolDefaults, pin, circle, square, graphics } from '../config/symbolConfig.js'
+import { SCHEME_COLORS } from '../config/mapTheme.js'
+
+const symbols = new Map()
+let _constructorDefaults = {}
+
+// 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'])
+
+function resolveValues (symbolDef, markerValues, mapStyle) {
+  const mapStyleId = mapStyle?.id
+  const symbolTokens = Object.fromEntries(
+    Object.entries(symbolDef || {}).filter(([k]) => !REGISTRY_EXCLUDED.has(k))
+  )
+  const constructorTokens = Object.fromEntries(
+    Object.entries(_constructorDefaults).filter(([k]) => !STRUCTURAL.has(k))
+  )
+  const defined = Object.fromEntries(
+    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
+  merged.haloColor = mapStyle?.haloColor ?? scheme.haloColor
+  merged.selectedColor = mapStyle?.selectedColor ?? scheme.selectedColor
+  if (typeof merged.graphic === 'string' && graphics[merged.graphic]) {
+    merged.graphic = graphics[merged.graphic]
+  }
+  return Object.fromEntries(
+    Object.entries(merged).map(([token, value]) => [token, getValueForStyle(value, mapStyleId) || ''])
+  )
+}
+
+function resolveLayer (svgString, values) {
+  return Object.entries(values).reduce(
+    (svg, [token, value]) => svg.replaceAll(`{{${token}}}`, value),
+    svgString
+  )
+}
+
+export const symbolRegistry = {
+  /**
+   * Set constructor-level defaults. Called once during app initialisation.
+   * Merges onto symbolDefaults to form the app-wide token baseline.
+   *
+   * @param {Object} defaults - Constructor symbolDefaults config
+   */
+  setDefaults (defaults) {
+    _constructorDefaults = defaults || {}
+  },
+
+  /**
+   * Returns the merged app-wide defaults (hardcoded + constructor overrides).
+   * Includes both structural properties (symbol, viewBox, anchor) and token values.
+   *
+   * @returns {Object}
+   */
+  getDefaults () {
+    return { ...symbolDefaults, ..._constructorDefaults }
+  },
+
+  register (symbolDef) {
+    symbols.set(symbolDef.id, symbolDef)
+  },
+
+  get (id) {
+    return symbols.get(id)
+  },
+
+  list () {
+    return [...symbols.values()]
+  },
+
+  /**
+   * Resolve a symbol's SVG string for normal (unselected) rendering.
+   * The selected ring is always hidden regardless of cascade values.
+   *
+   * @param {Object} symbolDef - Symbol definition
+   * @param {Object} styleColors - Token overrides
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, haloColor)
+   * @returns {string} Resolved SVG string
+   */
+  resolve (symbolDef, styleColors, mapStyle) {
+    const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
+    if (!symbolDef) { return '' }
+    colors.selectedColor = ''
+    return resolveLayer(symbolDef.svg, colors)
+  },
+
+  /**
+   * Resolve a symbol's SVG string for selected rendering.
+   * selectedColor comes from mapStyle.selectedColor (or the hardcoded fallback).
+   *
+   * @param {Object} symbolDef - Symbol definition
+   * @param {Object} styleColors - Token overrides
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, haloColor)
+   * @returns {string} Resolved SVG string
+   */
+  resolveSelected (symbolDef, styleColors, mapStyle) {
+    const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
+    if (!symbolDef) { return '' }
+    return resolveLayer(symbolDef.svg, colors)
+  }
+}
+
+symbolRegistry.register(pin)
+symbolRegistry.register(circle)
+symbolRegistry.register(square)

package/src/services/symbolRegistry.test.js

@@ -0,0 +1,262 @@
+import { symbolRegistry } from './symbolRegistry.js'
+import { symbolDefaults } from '../config/symbolConfig.js'
+import { SCHEME_COLORS } from '../config/mapTheme.js'
+import { getValueForStyle } from '../utils/getValueForStyle.js'
+
+const STYLE_ID = 'test'
+const mapStyle = { id: STYLE_ID }
+
+beforeEach(() => {
+  symbolRegistry.setDefaults({})
+})
+
+describe('symbolRegistry — built-in symbols', () => {
+  it('registers pin by default', () => {
+    const pin = symbolRegistry.get('pin')
+    expect(pin).toBeDefined()
+    expect(pin.id).toBe('pin')
+    expect(pin.anchor).toEqual([0.5, 0.9])
+    expect(typeof pin.svg).toBe('string')
+  })
+
+  it('registers circle by default', () => {
+    const circle = symbolRegistry.get('circle')
+    expect(circle).toBeDefined()
+    expect(circle.id).toBe('circle')
+    expect(circle.anchor).toEqual([0.5, 0.5])
+  })
+
+  it('lists both built-in symbols', () => {
+    const ids = symbolRegistry.list().map(s => s.id)
+    expect(ids).toContain('pin')
+    expect(ids).toContain('circle')
+  })
+})
+
+describe('symbolRegistry — register / get', () => {
+  it('registers and retrieves a custom symbol', () => {
+    const custom = {
+      id: 'test-diamond',
+      viewBox: '0 0 20 20',
+      anchor: [0.5, 0.5],
+      svg: '<rect fill="{{backgroundColor}}"/>'
+    }
+    symbolRegistry.register(custom)
+    expect(symbolRegistry.get('test-diamond')).toBe(custom)
+  })
+
+  it('returns undefined for an unregistered id', () => {
+    expect(symbolRegistry.get('does-not-exist')).toBeUndefined()
+  })
+})
+
+describe('symbolRegistry — setDefaults / getDefaults', () => {
+  it('getDefaults returns hardcoded defaults when no constructor defaults set', () => {
+    const defaults = symbolRegistry.getDefaults()
+    expect(defaults.symbol).toBe('pin')
+    expect(defaults.backgroundColor).toBe(symbolDefaults.backgroundColor)
+  })
+
+  it('constructor defaults override hardcoded defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#ff0000', symbol: 'circle' })
+    const defaults = symbolRegistry.getDefaults()
+    expect(defaults.backgroundColor).toBe('#ff0000')
+    expect(defaults.symbol).toBe('circle')
+  })
+
+  it('constructor defaults do not affect unset properties', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    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(null)
+    expect(symbolRegistry.getDefaults().backgroundColor).toBe(symbolDefaults.backgroundColor)
+  })
+})
+
+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}}"/>'
+  }
+
+  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', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain('stroke=""')
+  })
+
+  it('uses light scheme haloColor when mapStyle has no haloColor', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.haloColor}"`)
+  })
+
+  it('uses mapStyle.haloColor when provided', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, { id: STYLE_ID, haloColor: '#336699' })
+    expect(resolved).toContain('stroke="#336699"')
+  })
+
+  it('overrides default backgroundColor with a plain string', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: '#ff0000' }, mapStyle)
+    expect(resolved).toContain('fill="#ff0000"')
+  })
+
+  it('overrides default with a style-keyed color', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: { [STYLE_ID]: '#aabbcc', other: '#112233' } }, mapStyle)
+    expect(resolved).toContain('fill="#aabbcc"')
+  })
+
+  it('ignores null override values — defaults are preserved', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: null }, mapStyle)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
+  })
+
+  it('replaces custom tokens not in defaults', () => {
+    const customDef = { id: 'custom', svg: '<path fill="{{accentColor}}"/>' }
+    const resolved = symbolRegistry.resolve(customDef, { accentColor: '#123456' }, mapStyle)
+    expect(resolved).toContain('fill="#123456"')
+  })
+
+  it('handles null styleColors — uses all defaults', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, null, mapStyle)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.foregroundColor, STYLE_ID)}"`)
+  })
+
+  it('replaces token with empty string when override is an empty string', () => {
+    const def = { id: 'es', svg: BACKGROUND_SVG }
+    const resolved = symbolRegistry.resolve(def, { backgroundColor: '' }, mapStyle)
+    expect(resolved).toContain('fill=""')
+  })
+
+  it('returns empty string for null symbolDef', () => {
+    expect(symbolRegistry.resolve(null, {}, mapStyle)).toBe('')
+  })
+
+  it('constructor defaults take precedence over hardcoded defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#abcdef' })
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain('fill="#abcdef"')
+  })
+
+  it('symbol-level token defaults take precedence over constructor defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#abcdef' })
+    const defWithToken = { id: 'td', svg: BACKGROUND_SVG, backgroundColor: '#111111' }
+    const resolved = symbolRegistry.resolve(defWithToken, {}, mapStyle)
+    expect(resolved).toContain('fill="#111111"')
+  })
+
+  it('marker-level overrides take precedence over symbol-level defaults', () => {
+    const defWithToken = { id: 'td2', svg: BACKGROUND_SVG, backgroundColor: '#111111' }
+    const resolved = symbolRegistry.resolve(defWithToken, { backgroundColor: '#ffffff' }, mapStyle)
+    expect(resolved).toContain('fill="#ffffff"')
+  })
+})
+
+describe('symbolRegistry — resolveSelected', () => {
+  const symbolDef = {
+    id: 'test-sel',
+    svg: '<path stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/><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('uses mapStyle.selectedColor when provided', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
+    expect(resolved).toContain('stroke="#ff0000"')
+  })
+
+  it('uses selectedWidth from symbolDefaults', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke-width="${symbolDefaults.selectedWidth}"`)
+  })
+
+  it('handles null styleColors — uses cascade defaults', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, null, mapStyle)
+    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+  })
+
+  it('returns empty string for null symbolDef', () => {
+    expect(symbolRegistry.resolveSelected(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"')
+  })
+
+  it('still resolves other tokens correctly', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, { backgroundColor: '#d4351c' }, mapStyle)
+    expect(resolved).toContain('fill="#d4351c"')
+  })
+})
+
+describe('symbolRegistry — graphic token', () => {
+  const graphicDef = {
+    id: 'test-graphic',
+    graphic: 'M10 10 L20 20',
+    svg: '<path d="{{graphic}}" fill="{{foregroundColor}}"/>'
+  }
+
+  it('substitutes graphic d attribute from symbol-level default', () => {
+    const resolved = symbolRegistry.resolve(graphicDef, {}, mapStyle)
+    expect(resolved).toContain('d="M10 10 L20 20"')
+  })
+
+  it('resolves named graphic string to built-in path data', () => {
+    const resolved = symbolRegistry.resolve(graphicDef, { graphic: 'cross' }, mapStyle)
+    expect(resolved).toContain('d="M6 3H10V6H13V10H10V13H6V10H3V6H6Z"')
+  })
+
+  it('overrides symbol-level graphic with marker-level value', () => {
+    const resolved = symbolRegistry.resolve(graphicDef, { graphic: 'M0 0 L38 38' }, mapStyle)
+    expect(resolved).toContain('d="M0 0 L38 38"')
+  })
+
+  it('overrides graphic via constructor defaults', () => {
+    symbolRegistry.setDefaults({ graphic: 'M5 5 L15 15' })
+    const defNoGraphic = { id: 'no-graphic', svg: '<path d="{{graphic}}"/>' }
+    const resolved = symbolRegistry.resolve(defNoGraphic, {}, mapStyle)
+    expect(resolved).toContain('d="M5 5 L15 15"')
+  })
+
+  it('marker-level graphic overrides constructor default', () => {
+    symbolRegistry.setDefaults({ graphic: 'M5 5 L15 15' })
+    const defNoGraphic = { id: 'no-graphic2', svg: '<path d="{{graphic}}"/>' }
+    const resolved = symbolRegistry.resolve(defNoGraphic, { graphic: 'M1 1 L2 2' }, mapStyle)
+    expect(resolved).toContain('d="M1 1 L2 2"')
+  })
+
+  it('built-in pin symbol has a graphic default', () => {
+    const pin = symbolRegistry.get('pin')
+    expect(typeof pin.graphic).toBe('string')
+    expect(pin.graphic.length).toBeGreaterThan(0)
+  })
+
+  it('built-in circle symbol has a graphic default', () => {
+    const circle = symbolRegistry.get('circle')
+    expect(typeof circle.graphic).toBe('string')
+    expect(circle.graphic.length).toBeGreaterThan(0)
+  })
+
+  it('pin resolves graphic token into its svg within a g transform', () => {
+    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)')
+  })
+})

package/src/types.js

@@ -316,15 +316,67 @@
  * Alt text for logo.
  *
  * @property {'light' | 'dark'} [mapColorScheme]
- * Map color scheme. Used to determine the style of controls on the map. eg. Halo colours etc
+ * Map colour scheme. Sets the default values of `haloColor`, `selectedColor`, and `foregroundColor`
+ * when not explicitly provided, and signals to map overlay components which tonal range to use.
+ * `'light'` (default): dark overlays on a light basemap. `'dark'`: light overlays on a dark or aerial basemap.
  *
  * @property {string} [thumbnail]
  * URL to thumbnail image.
  *
+ * @property {string} [haloColor]
+ * Halo colour for elements rendered on top of the map (e.g. symbol outlines). Provides contrast
+ * between overlay elements and the map background. Falls back to `#ffffff` (light) or `#0b0c0c` (dark).
+ * Injected as the `--map-overlay-halo-color` CSS custom property.
+ *
+ * @property {string} [selectedColor]
+ * Theme colour for selected state — used by map overlay components to indicate a selected feature.
+ * Falls back to `#0b0c0c` (light) or `#ffffff` (dark).
+ * Injected as the `--map-overlay-selected-color` CSS custom property.
+ *
+ * @property {string} [foregroundColor]
+ * Foreground colour for elements rendered on top of the map (e.g. text or iconography in overlay components).
+ * Falls back to `#0b0c0c` (light) or `#ffffff` (dark).
+ * Injected as the `--map-overlay-foreground-color` CSS custom property.
+ *
  * @property {string} url
  * URL to the style.json (Mapbox Style Specification).
  */
 
+/**
+ * App-wide symbol appearance defaults. All properties are optional.
+ * Color values may be a plain string or an object keyed by map style ID.
+ *
+ * @typedef {Object} SymbolDefaults
+ *
+ * @property {string} [symbol='pin']
+ * Default symbol ID. Built-in values: `'pin'`, `'circle'`.
+ *
+ * @property {string} [symbolSvgContent]
+ * Default inner SVG path content. When set, overrides `symbol`.
+ *
+ * @property {string} [viewBox='0 0 38 38']
+ * Default SVG viewBox.
+ *
+ * @property {[number, number]} [anchor=[0.5, 0.5]]
+ * Default anchor point as a normalised [x, y] pair.
+ *
+ * @property {string | Record<string, string>} [backgroundColor='#ca3535']
+ * Default background fill colour.
+ *
+ * @property {string | Record<string, string>} [foregroundColor='#ffffff']
+ * Default foreground fill colour.
+ *
+ * @property {string} [haloWidth='1']
+ * Default halo stroke width in SVG units.
+ *
+ * @property {string} [graphic]
+ * Default SVG `d` attribute value for the foreground graphic path. Each built-in symbol sets
+ * its own default (a small dot). Override to swap the graphic across all markers globally.
+ *
+ * @property {string} [selectedWidth='6']
+ * Selection ring stroke width in SVG units. App-wide only — ignored at symbol registration and marker creation level.
+ */
+
 /**
  * Configuration for a map marker.
  *
@@ -341,15 +393,47 @@
  */
 
 /**
- * Options for customizing marker appearance.
+ * Options for customizing marker appearance. Any key corresponds to a token in the symbol's SVG template.
+ * Color values may be a plain string or an object keyed by map style ID e.g. `{ outdoor: '#fff', dark: '#000' }`.
  *
  * @typedef {Object} MarkerOptions
  *
- * @property {string | Record<string, string>} [color]
- * Marker color or object with colors keyed by style ID.
+ * @property {string} [symbol]
+ * Symbol id to use for this marker (e.g. 'pin', 'circle'). Overrides the default `symbolDefaults.symbol` option.
+ *
+ * @property {string} [symbolSvgContent]
+ * Inner SVG path content (no `<svg>` wrapper) to use instead of a registered symbol.
+ * Use `{{token}}` placeholders for colours — e.g. `fill="{{backgroundColor}}"`.
+ * When set, `symbol` is ignored.
+ *
+ * @property {string} [viewBox]
+ * SVG viewBox attribute for the symbol, e.g. `'0 0 38 38'`.
+ * Defaults to the registered symbol's viewBox, or `'0 0 38 38'`.
+ *
+ * @property {[number, number]} [anchor]
+ * Anchor point as a normalised [x, y] pair where [0, 0] is top-left and [1, 1] is bottom-right.
+ * Determines which point on the symbol aligns with the geographic coordinate.
+ * Defaults to the registered symbol's anchor, or `[0.5, 0.5]` (centre).
+ *
+ * @property {string | Record<string, string>} [backgroundColor]
+ * Background fill colour of the symbol.
+ *
+ * @property {string | Record<string, string>} [foregroundColor]
+ * Foreground fill colour of the symbol (e.g. the inner dot on a pin).
+ *
+ * @property {string} [haloWidth]
+ * Stroke width of the halo in SVG units. Defaults to `'1'`.
+ *
+ * @property {string} [graphic]
+ * SVG `d` attribute value for the foreground graphic path. Replaces the foreground shape of the
+ * symbol while keeping its background, halo and selection ring intact. Each built-in symbol
+ * (`pin`, `circle`) provides a default dot; pass a different `d` string to swap it.
+ * Use named values from `graphics.js` or supply your own path data.
+ *
+ * @example
+ * import { graphics } from './config/symbolConfig.js'
+ * markers.add('id', coords, { symbol: 'pin', graphic: graphics.cross })
  *
- * @property {string} [shape]
- * Marker shape (e.g., 'pin').
  */
 
 /**
@@ -540,14 +624,12 @@
  * @property {string} [mapViewParamKey='mv']
  * URL query parameter key used to control map view state.
  *
- * @property {string | Record<string, string>} [markerColor='#ff0000']
- * Colour used for map markers. May be a single colour value or an object keyed by map style ID.
- *
  * @property {MarkerConfig[]} [markers]
  * Initial markers to display on the map.
  *
- * @property {string} [markerShape='pin']
- * Shape used for map markers.
+ * @property {Partial<SymbolDefaults>} [symbolDefaults]
+ * App-wide defaults for symbol appearance. Merged onto the hardcoded defaults in symbolDefaults.js.
+ * Values cascade: symbolDefaults.js → constructor symbolDefaults → symbol registration → marker creation.
  *
  * @property {[number, number, number, number]} [maxExtent]
  * Maximum viewable extent [west, south, east, north].

package/src/utils/patternUtils.js

@@ -0,0 +1,94 @@
+import { getValueForStyle } from '../utils/getValueForStyle.js'
+
+// Border path rendered behind the pattern content in Key panel symbols (20×20 coordinate space).
+export const KEY_BORDER_PATH = '<path d="M19 2.862v14.275c0 1.028-.835 1.862-1.862 1.862H2.863c-1.028 0-1.862-.835-1.862-1.862V2.862C1.001 1.834 1.836 1 2.863 1h14.275C18.166 1 19 1.835 19 2.862z" fill="{{backgroundColor}}" stroke="{{foregroundColor}}" stroke-width="2"/>'
+
+export const hashString = (str) => {
+  let hash = 0
+  for (const ch of str) {
+    hash = ((hash << 5) - hash) + ch.codePointAt(0)
+    hash = hash & hash
+  }
+  return Math.abs(hash).toString(36) // NOSONAR: base36 encoding for compact alphanumeric hash string
+}
+
+/**
+ * Replaces {{foregroundColor}} and {{backgroundColor}} tokens in SVG content with resolved colour values.
+ *
+ * @param {string} content - SVG path string with colour tokens
+ * @param {string} foregroundColor
+ * @param {string} backgroundColor
+ * @returns {string}
+ */
+export const injectColors = (content, foregroundColor, backgroundColor) =>
+  content
+    .replace(/\{\{foregroundColor\}\}/g, foregroundColor || 'black')
+    .replace(/\{\{backgroundColor\}\}/g, backgroundColor || 'transparent')
+
+/**
+ * Returns true if a dataset/config has a fill pattern configured.
+ *
+ * @param {Object} dataset
+ * @returns {boolean}
+ */
+export const hasPattern = (dataset) => !!(dataset.fillPattern || dataset.fillPatternSvgContent)
+
+/**
+ * Returns the raw (un-coloured) inner SVG content for a dataset's pattern.
+ * Precedence: inline fillPatternSvgContent → named fillPattern from registry.
+ *
+ * @param {Object} dataset
+ * @param {Object} patternRegistry
+ * @returns {string|null}
+ */
+export const getPatternInnerContent = (dataset, patternRegistry) => {
+  if (dataset.fillPatternSvgContent) {
+    return dataset.fillPatternSvgContent
+  }
+  if (dataset.fillPattern) {
+    return patternRegistry?.get(dataset.fillPattern)?.svgContent ?? null
+  }
+  return null
+}
+
+/**
+ * Returns a deterministic image ID for a pattern + resolved colour combination.
+ *
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @param {Object} patternRegistry
+ * @returns {string|null}
+ */
+export const getPatternImageId = (dataset, mapStyleId, patternRegistry) => {
+  const innerContent = getPatternInnerContent(dataset, patternRegistry)
+  if (!innerContent) {
+    return null
+  }
+  const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
+  const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
+  return `pattern-${hashString(innerContent + fg + bg)}`
+}
+
+/**
+ * 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 dataset has no pattern.
+ *
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @param {Object} patternRegistry
+ * @returns {{ border: string, content: string }|null}
+ */
+export const getKeyPatternPaths = (dataset, mapStyleId, patternRegistry) => {
+  const innerContent = getPatternInnerContent(dataset, patternRegistry)
+  if (!innerContent) {
+    return null
+  }
+  const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
+  const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
+  const borderStroke = getValueForStyle(dataset.stroke, mapStyleId) || fg
+  return {
+    border: injectColors(KEY_BORDER_PATH, borderStroke, bg),
+    content: injectColors(innerContent, fg, bg)
+  }
+}