@defra/interactive-map 0.0.52-alpha → 0.0.54-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/css/index.css +1 -1
  2. package/dist/esm/im-core.js +1 -1
  3. package/dist/esm/im-shell.js +1 -1
  4. package/dist/umd/im-core.js +1 -1
  5. package/dist/umd/index.js +1 -1
  6. package/docs/api/context.md +30 -12
  7. package/docs/api/marker-config.md +16 -8
  8. package/docs/api/symbol-config.md +24 -9
  9. package/docs/api/symbol-registry.md +49 -14
  10. package/docs/api.md +11 -3
  11. package/docs/plugins/datasets.md +6 -10
  12. package/docs/plugins/draw.md +2 -1
  13. package/docs/plugins/map-key.md +47 -4
  14. package/package.json +1 -1
  15. package/plugins/beta/map-styles/dist/esm/im-map-styles-plugin.js +1 -1
  16. package/plugins/beta/map-styles/dist/umd/im-map-styles-plugin.js +1 -1
  17. package/plugins/beta/map-styles/dist/umd/index.js +1 -1
  18. package/plugins/datasets/dist/esm/im-datasets-ml-adapter.js +1 -1
  19. package/plugins/datasets/dist/esm/im-datasets-ol-adapter.js +1 -1
  20. package/plugins/datasets/dist/esm/im-datasets-plugin.js +1 -1
  21. package/plugins/datasets/dist/esm/mapboxStyleLayerAdapter.js +1 -1
  22. package/plugins/datasets/dist/umd/im-datasets-ml-adapter.js +1 -1
  23. package/plugins/datasets/dist/umd/im-datasets-ol-adapter.js +1 -1
  24. package/plugins/datasets/dist/umd/im-datasets-plugin.js +1 -1
  25. package/plugins/datasets/src/adapters/esri/esriLayerAdapter.js +6 -6
  26. package/plugins/datasets/src/adapters/esri/registry/esriDataset.test.js +1 -1
  27. package/plugins/datasets/src/adapters/maplibre/layerBuilders.js +10 -10
  28. package/plugins/datasets/src/adapters/maplibre/layerBuilders.test.js +22 -6
  29. package/plugins/datasets/src/adapters/maplibre/maplibreLayerAdapter.js +9 -3
  30. package/plugins/datasets/src/adapters/maplibre/maplibreLayerAdapter.test.js +18 -3
  31. package/plugins/datasets/src/adapters/maplibre/registry/mapLibreDataset.js +3 -3
  32. package/plugins/datasets/src/adapters/maplibre/registry/mapLibreDataset.test.js +20 -27
  33. package/plugins/datasets/src/adapters/openlayers/canvasPatternStyle.js +16 -70
  34. package/plugins/datasets/src/adapters/openlayers/canvasPatternStyle.test.js +30 -115
  35. package/plugins/datasets/src/adapters/openlayers/layerBuilders.js +11 -13
  36. package/plugins/datasets/src/adapters/openlayers/layerBuilders.test.js +11 -3
  37. package/plugins/datasets/src/adapters/openlayers/openlayersLayerAdapter.js +48 -19
  38. package/plugins/datasets/src/adapters/openlayers/openlayersLayerAdapter.test.js +101 -13
  39. package/plugins/datasets/src/adapters/openlayers/registry/openLayersDataset.js +27 -28
  40. package/plugins/datasets/src/adapters/openlayers/registry/openLayersDataset.test.js +51 -32
  41. package/plugins/datasets/src/fetch/createDynamicSource.js +2 -2
  42. package/plugins/datasets/src/initialise/DatasetsInit.jsx +2 -2
  43. package/plugins/datasets/src/initialise/defaults.js +16 -27
  44. package/plugins/datasets/src/initialise/defaults.test.js +25 -57
  45. package/plugins/datasets/src/initialise/initialiseDatasets.js +1 -4
  46. package/plugins/datasets/src/reducers/__data__/demoDatasets.js +1 -3
  47. package/plugins/datasets/src/reducers/mappedDatasetsReducer.test.js +1 -1
  48. package/plugins/datasets/src/registry/dataset.js +23 -17
  49. package/plugins/datasets/src/registry/dataset.test.js +114 -11
  50. package/plugins/datasets/src/registry/mapboxStyleDataset.js +1 -1
  51. package/plugins/datasets/src/registry/mapboxStyleDataset.test.js +1 -1
  52. package/plugins/draw/dist/esm/im-draw-ml-adapter.js +1 -1
  53. package/plugins/draw/dist/esm/im-draw-ol-adapter.js +1 -1
  54. package/plugins/draw/dist/esm/im-draw-plugin.js +1 -1
  55. package/plugins/draw/dist/esm/index.js +1 -1
  56. package/plugins/draw/dist/esm/liveDrawChecks.js +1 -1
  57. package/plugins/draw/dist/umd/im-draw-ml-adapter.js +1 -1
  58. package/plugins/draw/dist/umd/im-draw-ol-adapter.js +1 -1
  59. package/plugins/draw/dist/umd/im-draw-plugin.js +1 -1
  60. package/plugins/draw/dist/umd/index.js +1 -1
  61. package/plugins/draw/src/DrawInit.jsx +7 -5
  62. package/plugins/draw/src/DrawInit.test.jsx +18 -2
  63. package/plugins/draw/src/adapters/maplibre/MaplibreDrawAdapter.js +11 -5
  64. package/plugins/draw/src/adapters/maplibre/MaplibreDrawAdapter.test.js +27 -11
  65. package/plugins/draw/src/adapters/maplibre/mapboxDraw.js +12 -9
  66. package/plugins/draw/src/adapters/maplibre/mapboxDraw.test.js +18 -0
  67. package/plugins/draw/src/adapters/maplibre/pointSymbolImages.js +81 -56
  68. package/plugins/draw/src/adapters/maplibre/pointSymbolImages.test.js +149 -80
  69. package/plugins/draw/src/adapters/openlayers/OLDrawAdapter.js +7 -6
  70. package/plugins/draw/src/adapters/openlayers/OLDrawAdapter.test.js +22 -25
  71. package/plugins/draw/src/adapters/openlayers/core/OLDrawManager.js +26 -8
  72. package/plugins/draw/src/adapters/openlayers/core/OLDrawManager.test.js +58 -16
  73. package/plugins/draw/src/adapters/openlayers/core/styles.js +33 -20
  74. package/plugins/draw/src/adapters/openlayers/core/styles.test.js +47 -21
  75. package/plugins/draw/src/adapters/openlayers/olDraw.js +16 -12
  76. package/plugins/draw/src/adapters/openlayers/olDraw.test.js +27 -32
  77. package/plugins/draw/src/adapters/openlayers/point/pointSymbolImages.js +44 -49
  78. package/plugins/draw/src/adapters/openlayers/point/pointSymbolImages.test.js +100 -119
  79. package/plugins/draw/src/defaults.js +2 -6
  80. package/plugins/draw/src/utils/stripInternalProperties.test.js +2 -1
  81. package/plugins/draw/src/utils/symbolKeys.js +3 -4
  82. package/plugins/interact/dist/esm/im-interact-plugin.js +1 -1
  83. package/plugins/interact/dist/umd/im-interact-plugin.js +1 -1
  84. package/plugins/interact/dist/umd/index.js +1 -1
  85. package/plugins/map-key/dist/css/index.css +1 -1
  86. package/plugins/map-key/dist/esm/im-map-key-plugin.js +1 -1
  87. package/plugins/map-key/dist/umd/im-map-key-plugin.js +1 -2
  88. package/plugins/map-key/dist/umd/index.js +1 -1
  89. package/plugins/map-key/src/components/Key/Key.jsx +8 -4
  90. package/plugins/map-key/src/components/Key/Key.module.scss +144 -53
  91. package/plugins/map-key/src/components/Key/KeyGroupItem.jsx +36 -3
  92. package/plugins/map-key/src/components/Key/KeyGroupItem.test.jsx +44 -2
  93. package/plugins/map-key/src/components/Key/KeyItem.jsx +2 -2
  94. package/plugins/map-key/src/components/Key/KeySvg.jsx +19 -18
  95. package/plugins/map-key/src/components/Key/KeySvg.test.jsx +25 -18
  96. package/plugins/map-key/src/components/Key/KeySvgPattern.jsx +1 -2
  97. package/plugins/map-key/src/components/Key/KeySvgPattern.test.jsx +3 -1
  98. package/plugins/map-key/src/components/Key/KeySvgRamp.jsx +35 -6
  99. package/plugins/map-key/src/components/Key/KeySvgRamp.test.jsx +56 -16
  100. package/plugins/map-key/src/components/Key/KeySvgSymbol.jsx +26 -12
  101. package/plugins/map-key/src/components/Key/KeySvgSymbol.test.jsx +24 -74
  102. package/plugins/map-key/src/components/Key/MapKey.jsx +3 -1
  103. package/plugins/map-key/src/components/Key/svgProperties.js +8 -2
  104. package/plugins/map-key/src/components/Key/useRampOrientation.js +61 -0
  105. package/plugins/map-key/src/components/Key/useRampOrientation.test.jsx +155 -0
  106. package/plugins/map-key/src/index.js +34 -0
  107. package/plugins/map-key/src/reducers/mergeKeyGroupItems.test.js +15 -0
  108. package/plugins/map-key/src/registry/index.js +0 -2
  109. package/plugins/map-key/src/registry/index.test.js +1 -9
  110. package/plugins/map-key/src/utils/groupStyles.js +5 -2
  111. package/plugins/menu/src/registry/index.js +0 -2
  112. package/plugins/menu/src/registry/index.test.js +1 -9
  113. package/plugins/search/dist/esm/im-search-plugin.js +1 -1
  114. package/plugins/search/dist/umd/im-search-plugin.js +1 -1
  115. package/plugins/search/dist/umd/index.js +1 -1
  116. package/plugins/search/src/Search.jsx +0 -1
  117. package/plugins/search/src/components/Form/Form.jsx +3 -3
  118. package/plugins/search/src/components/Suggestions/Suggestions.jsx +2 -0
  119. package/plugins/search/src/components/Suggestions/Suggestions.test.jsx +6 -0
  120. package/plugins/search/src/defaults.js +3 -0
  121. package/plugins/search/src/events/formHandlers.js +3 -9
  122. package/plugins/search/src/events/formHandlers.test.js +6 -9
  123. package/plugins/search/src/events/inputHandlers.js +8 -2
  124. package/plugins/search/src/events/inputHandlers.test.js +20 -0
  125. package/plugins/search/src/events/suggestionHandlers.js +3 -5
  126. package/plugins/search/src/events/suggestionHandlers.test.js +5 -8
  127. package/plugins/search/src/utils/showResult.js +9 -0
  128. package/plugins/search/src/utils/showResult.test.js +16 -0
  129. package/providers/beta/esri/dist/esm/im-esri-provider.js +1 -1
  130. package/providers/beta/openlayers/dist/esm/im-openlayers-provider.js +1 -1
  131. package/providers/beta/openlayers/dist/umd/im-openlayers-provider.js +1 -1
  132. package/providers/beta/openlayers/dist/umd/index.js +1 -1
  133. package/providers/beta/openlayers/src/openlayersProvider.js +102 -2
  134. package/providers/beta/openlayers/src/openlayersProvider.test.js +95 -0
  135. package/providers/beta/openlayers/src/utils/highlightFeatures.js +20 -25
  136. package/providers/beta/openlayers/src/utils/highlightFeatures.test.js +73 -38
  137. package/providers/beta/openlayers/src/utils/patternImages.js +61 -0
  138. package/providers/beta/openlayers/src/utils/patternImages.test.js +74 -0
  139. package/providers/beta/openlayers/src/utils/symbolImages.js +103 -95
  140. package/providers/beta/openlayers/src/utils/symbolImages.test.js +136 -85
  141. package/providers/mapProvider.js +53 -1
  142. package/providers/mapProvider.test.js +6 -0
  143. package/providers/maplibre/dist/esm/im-maplibre-provider.js +1 -1
  144. package/providers/maplibre/dist/umd/im-maplibre-provider.js +1 -1
  145. package/providers/maplibre/dist/umd/index.js +1 -1
  146. package/providers/maplibre/src/maplibreProvider.js +50 -17
  147. package/providers/maplibre/src/maplibreProvider.test.js +74 -20
  148. package/providers/maplibre/src/utils/highlightFeatures.js +19 -14
  149. package/providers/maplibre/src/utils/highlightFeatures.test.js +20 -14
  150. package/providers/maplibre/src/utils/patternImages.js +46 -29
  151. package/providers/maplibre/src/utils/patternImages.test.js +52 -4
  152. package/providers/maplibre/src/utils/symbolImages.js +80 -39
  153. package/providers/maplibre/src/utils/symbolImages.test.js +157 -54
  154. package/src/App/components/Hints/Hints.module.scss +1 -1
  155. package/src/App/components/Markers/Markers.jsx +16 -25
  156. package/src/App/components/Markers/Markers.test.jsx +34 -48
  157. package/src/App/components/Markers/SymbolLabelMarker.jsx +1 -1
  158. package/src/App/components/Markers/SymbolMarker.jsx +1 -1
  159. package/src/App/components/Viewport/Viewport.jsx +6 -4
  160. package/src/App/components/Viewport/Viewport.test.jsx +18 -1
  161. package/src/App/hooks/useMapAnnouncements.js +7 -2
  162. package/src/App/hooks/useMapAnnouncements.test.js +13 -2
  163. package/src/App/hooks/useModalPanelBehaviour.js +3 -1
  164. package/src/App/initialiseApp.js +1 -1
  165. package/src/App/store/ServiceProvider.jsx +12 -3
  166. package/src/App/store/ServiceProvider.test.jsx +39 -0
  167. package/src/InteractiveMap/InteractiveMap.js +3 -3
  168. package/src/config/appConfig.js +1 -5
  169. package/src/config/mapSizeScales.js +8 -0
  170. package/src/config/symbolConfig.js +101 -25
  171. package/src/services/mapFocus.js +64 -0
  172. package/src/services/mapFocus.test.js +76 -0
  173. package/src/services/patternRegistry.js +97 -76
  174. package/src/services/patternRegistry.test.js +19 -1
  175. package/src/services/symbolComposer.js +184 -0
  176. package/src/services/symbolComposer.test.js +132 -0
  177. package/src/services/symbolRegistry.js +326 -155
  178. package/src/services/symbolRegistry.test.js +334 -32
  179. package/src/types.js +11 -5
  180. package/src/utils/detectInterfaceType.js +16 -5
  181. package/src/utils/detectInterfaceType.test.js +32 -0
  182. package/src/utils/hashString.js +23 -0
  183. package/src/utils/hashString.test.js +29 -0
  184. package/src/utils/imageDataCache.js +43 -0
  185. package/src/utils/imageDataCache.test.js +38 -0
  186. package/src/utils/pathBounds.js +330 -0
  187. package/src/utils/pathBounds.test.js +145 -0
  188. package/src/utils/patternUtils.js +0 -8
  189. package/src/utils/patternUtils.test.js +0 -25
  190. package/src/utils/recentImageSets.js +35 -0
  191. package/src/utils/recentImageSets.test.js +46 -0
  192. package/src/utils/symbolUtils.js +26 -29
  193. package/src/utils/symbolUtils.test.js +27 -41
  194. package/plugins/map-key/dist/umd/im-map-key-plugin.js.LICENSE.txt +0 -1
@@ -1,36 +1,96 @@
1
1
  import { getValueForStyle } from '../utils/getValueForStyle.js'
2
- import { symbolDefaults, pin, circle, square, graphics } from '../config/symbolConfig.js'
3
- import { getSymbolStyleColors, getSymbolViewBox } from '../utils/symbolUtils.js'
2
+ import { symbolDefaults, pin, circle, square, hexagon, triangle, diamond, graphics, DEFAULT_SYMBOL_VIEWBOX } from '../config/symbolConfig.js'
3
+ import { getSymbolStyleColors, getSymbolScale } from '../utils/symbolUtils.js'
4
4
  import { THEME_COLORS } from '../config/mapTheme.js'
5
5
  import { rasteriseToImageData } from '../utils/rasteriseToImageData.js'
6
+ import { hashString } from '../utils/hashString.js'
7
+ import { createImageDataCache } from '../utils/imageDataCache.js'
8
+ import {
9
+ composeSymbolDef, applyAnchorOverride, scaleSvgSymbolDef, renderComposed, renderTemplate
10
+ } from './symbolComposer.js'
6
11
 
7
- const symbols = new Map()
8
- // Module-level cache: imageId → ImageData. Avoids re-rasterising identical symbols.
9
- const imageDataCache = new Map()
10
- let _constructorDefaults = {}
12
+ // Shared by every registry: imageId → ImageData. Every style or pixel-ratio change brings new
13
+ // ids, so it's bounded.
14
+ const IMAGE_DATA_CACHE_SIZE = 256
15
+ const imageDataCache = createImageDataCache(IMAGE_DATA_CACHE_SIZE)
11
16
 
12
- const HASH_BASE = 36
17
+ // The viewBox is part of the id: it sets the rasterised image's size, so the same SVG content at
18
+ // two viewBoxes (e.g. symbolSvgContent with different symbolViewBox values) is two images.
19
+ const imageIdFor = (prefix, resolvedSvg, viewBox, pixelRatio) => {
20
+ const content = `${viewBox}|${resolvedSvg}`
21
+ return `symbol-${prefix}${hashString(content)}-${pixelRatio}x`
22
+ }
23
+
24
+ // Keys that are structural — not token values for SVG substitution
25
+ const STRUCTURAL = new Set([
26
+ 'id', 'svg', 'viewBox', 'anchor', 'symbol', 'svgContent', 'size', 'symbolSvgContent', 'symbolSize',
27
+ 'path', 'bounds', 'anchorPoint', 'graphicCentre', 'bodyBox', 'transform', 'scale'
28
+ ])
29
+
30
+ // Each symbol image variant: the resolve method that draws it, and its image id prefix
31
+ const SYMBOL_VARIANTS = {
32
+ normal: { resolveWith: 'resolve', prefix: '' },
33
+ active: { resolveWith: 'resolveActive', prefix: 'act-' },
34
+ selected: { resolveWith: 'resolveSelected', prefix: 'sel-' }
35
+ }
36
+
37
+ const POINT_LENGTH = 2
38
+ const BOX_LENGTH = 4 // [x, y, width, height], and a viewBox's four values
13
39
 
14
- const hashString = (str) => {
15
- let hash = 0
16
- for (const ch of str) {
17
- hash = Math.trunc(((hash << 5) - hash) + ch.codePointAt(0))
40
+ const isNumberList = (value, length) => Array.isArray(value) && value.length === length && value.every(Number.isFinite)
41
+
42
+ // Built-in shape format — bounds, anchorPoint and graphicCentre are all required
43
+ const validatePathSymbolDef = ({ id, bounds, anchorPoint, graphicCentre }) => {
44
+ if (!isNumberList(bounds, BOX_LENGTH)) {
45
+ throw new TypeError(`symbolRegistry.register: symbol "${id}" has a "path" but no valid "bounds" ([x, y, width, height])`)
46
+ }
47
+ if (!isNumberList(anchorPoint, POINT_LENGTH) || !isNumberList(graphicCentre, POINT_LENGTH)) {
48
+ throw new TypeError(`symbolRegistry.register: symbol "${id}" has a "path" but no valid "anchorPoint" and "graphicCentre" ([x, y])`)
18
49
  }
19
- return Math.abs(hash).toString(HASH_BASE)
20
50
  }
21
51
 
22
- // Keys that are structural — not token values for SVG substitution
23
- const STRUCTURAL = new Set(['id', 'svg', 'viewBox', 'anchor', 'symbol', 'symbolSvgContent'])
52
+ const validateSvgSymbolDef = ({ id, svg, viewBox, anchor }) => {
53
+ if (typeof svg !== 'string' || !svg) {
54
+ throw new TypeError(`symbolRegistry.register: symbol "${id}" needs an "svg" template`)
55
+ }
56
+ if (typeof viewBox !== 'string' || viewBox.trim().split(/[\s,]+/).length !== BOX_LENGTH) {
57
+ throw new TypeError(`symbolRegistry.register: symbol "${id}" needs a "viewBox" ('minX minY width height')`)
58
+ }
59
+ if (anchor !== undefined && !isNumberList(anchor, POINT_LENGTH)) {
60
+ throw new TypeError(`symbolRegistry.register: symbol "${id}" has an invalid "anchor" — expected [x, y] in 0–1`)
61
+ }
62
+ }
63
+
64
+ // Fails fast with a message naming the symbol, rather than a crash at render time.
65
+ const validateSymbolDef = (symbolDef) => {
66
+ if (typeof symbolDef?.id !== 'string' || !symbolDef.id) {
67
+ throw new TypeError('symbolRegistry.register: a symbol needs a string "id"')
68
+ }
69
+ if (symbolDef.path) {
70
+ validatePathSymbolDef(symbolDef)
71
+ } else {
72
+ validateSvgSymbolDef(symbolDef)
73
+ }
74
+ }
75
+
76
+ function renderSymbol (symbolDef, values) {
77
+ if (symbolDef.path) {
78
+ // Accept an unsized (registered) built-in def too, rendering it at medium
79
+ const sized = symbolDef.transform ? symbolDef : composeSymbolDef(symbolDef, 1)
80
+ return renderComposed(sized, values)
81
+ }
82
+ return renderTemplate(symbolDef.svg, values)
83
+ }
24
84
 
25
85
  // selectedColor and activeColor are map style concerns — always injected from mapStyle, never from cascade.
26
86
 
27
- function resolveValues (symbolDef, markerValues, mapStyle) {
87
+ function resolveValues (symbolDef, markerValues, mapStyle, constructorDefaults) {
28
88
  const mapStyleId = mapStyle?.id
29
89
  const symbolTokens = Object.fromEntries(
30
90
  Object.entries(symbolDef || {}).filter(([k]) => !STRUCTURAL.has(k))
31
91
  )
32
92
  const constructorTokens = Object.fromEntries(
33
- Object.entries(_constructorDefaults).filter(([k]) => !STRUCTURAL.has(k))
93
+ Object.entries(constructorDefaults).filter(([k]) => !STRUCTURAL.has(k))
34
94
  )
35
95
  const defined = Object.fromEntries(
36
96
  Object.entries(markerValues).filter(([, v]) => v != null)
@@ -49,200 +109,311 @@ function resolveValues (symbolDef, markerValues, mapStyle) {
49
109
  )
50
110
  }
51
111
 
52
- function resolveLayer (svgString, values) {
53
- return Object.entries(values).reduce(
54
- (svg, [token, value]) => svg.replaceAll(`{{${token}}}`, value),
55
- svgString
56
- )
57
- }
58
-
59
- export const symbolRegistry = {
112
+ // Sizing, variants, image ids, rasterising and the key symbol. They read the registry only through
113
+ // `this` (its symbols, defaults and resolve methods), so every registry shares them.
114
+ const symbolImageMethods = {
60
115
  /**
61
- * Set constructor-level defaults. Called once during app initialisation.
62
- * Merges onto symbolDefaults to form the app-wide token baseline.
116
+ * The sized symbol definition for a marker's options, falling back to this map's defaults for
117
+ * each: `svgContent` or `symbol`, `size`, `viewBox` and `anchor`.
63
118
  *
64
- * @param {Object} defaults - Constructor symbolDefaults config
119
+ * @param {Object} options - marker options
120
+ * @returns {Object|undefined} undefined when neither names a known symbol
65
121
  */
66
- setDefaults (defaults) {
67
- _constructorDefaults = defaults || {}
122
+ getMarkerSymbolDef (options) {
123
+ const defaults = this.getDefaults()
124
+ const svgContent = options.svgContent || defaults.svgContent
125
+ const baseDef = svgContent ? { svg: svgContent } : this.get(options.symbol || defaults.symbol)
126
+ if (!baseDef) {
127
+ return undefined
128
+ }
129
+ return this.getSizedSymbolDef(baseDef, {
130
+ viewBox: options.viewBox || defaults.viewBox,
131
+ size: options.size ?? defaults.size,
132
+ anchor: options.anchor ?? defaults.anchor
133
+ })
68
134
  },
69
135
 
70
136
  /**
71
- * Returns the merged app-wide defaults (hardcoded + constructor overrides).
72
- * Includes both structural properties (symbol, viewBox, anchor) and token values.
137
+ * A symbol's SVG for one variant: normal (no rings), active (both rings) or selected (black ring).
73
138
  *
74
- * @returns {Object}
139
+ * @param {Object} symbolDef
140
+ * @param {Object} styleColors - token overrides
141
+ * @param {Object} mapStyle
142
+ * @param {'normal'|'active'|'selected'} variant
143
+ * @returns {string}
75
144
  */
76
- getDefaults () {
77
- return { ...symbolDefaults, ..._constructorDefaults }
78
- },
79
-
80
- register (symbolDef) {
81
- symbols.set(symbolDef.id, symbolDef)
82
- },
83
-
84
- get (id) {
85
- return symbols.get(id)
86
- },
87
-
88
- list () {
89
- return [...symbols.values()]
145
+ resolveVariant (symbolDef, styleColors, mapStyle, variant) {
146
+ const { resolveWith } = SYMBOL_VARIANTS[variant] ?? SYMBOL_VARIANTS.normal
147
+ return this[resolveWith](symbolDef, styleColors, mapStyle)
90
148
  },
91
149
 
92
150
  /**
93
- * Clears all registered symbols (including built-ins). Mainly for testing purposes.
94
- */
95
- clear () {
96
- symbols.clear()
97
- },
98
-
99
- /**
100
- * Clears all registered symbols (including built-ins). Mainly for testing purposes.
151
+ * A dataset style's symbol as the map key draws it: always medium, whatever size the map uses,
152
+ * and in the page's colour scheme (mapStyle.appColorScheme) rather than the map's.
153
+ *
154
+ * @param {Object} style - a dataset style
155
+ * @param {Object} mapStyle - current map style config
156
+ * @returns {{ svg: string, viewBox: string }|null} null when the style has no known symbol
101
157
  */
102
- initialise () {
103
- this.register(pin)
104
- this.register(circle)
105
- this.register(square)
158
+ getKeySymbol (style, mapStyle) {
159
+ const symbolDef = this.getSymbolDef({ ...style, symbolSize: 'medium' })
160
+ if (!symbolDef) {
161
+ return null
162
+ }
163
+ const keyMapStyle = { ...mapStyle, mapColorScheme: mapStyle?.appColorScheme ?? 'light' }
164
+ return { svg: this.resolve(symbolDef, getSymbolStyleColors(style), keyMapStyle), viewBox: symbolDef.viewBox }
106
165
  },
107
166
 
108
167
  /**
109
- * Resolve a symbol's SVG string for normal (unselected, inactive) rendering.
110
- * Both selectedColor and activeColor are set to 'none' — all rings hidden.
168
+ * A symbol variant's resolved SVG and image id, from the hash of that SVG, its viewBox and the
169
+ * pixel ratio.
111
170
  *
112
- * @param {Object} symbolDef - Symbol definition
113
- * @param {Object} styleColors - Token overrides
114
- * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
115
- * @returns {string} Resolved SVG string
171
+ * @param {Object} style
172
+ * @param {Object} mapStyle
173
+ * @param {'normal'|'active'|'selected'} variant
174
+ * @param {number} pixelRatio
175
+ * @returns {{ symbolDef: Object, resolvedContent: string, imageId: string }|null}
116
176
  */
117
- resolve (symbolDef, styleColors, mapStyle) {
118
- const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
119
- if (!symbolDef) { return '' }
120
- colors.selectedColor = 'none'
121
- colors.activeColor = 'none'
122
- return resolveLayer(symbolDef.svg, colors)
177
+ resolveSymbolImage (style, mapStyle, variant, pixelRatio) {
178
+ const symbolDef = this.getSymbolDef(style)
179
+ if (!symbolDef) {
180
+ return null
181
+ }
182
+ const { prefix } = SYMBOL_VARIANTS[variant] ?? SYMBOL_VARIANTS.normal
183
+ const resolvedContent = this.resolveVariant(symbolDef, getSymbolStyleColors(style), mapStyle, variant)
184
+ return { symbolDef, resolvedContent, imageId: imageIdFor(prefix, resolvedContent, symbolDef.viewBox, pixelRatio) }
123
185
  },
124
186
 
125
187
  /**
126
- * Resolve a symbol's SVG string for active (keyboard cursor) rendering.
127
- * Both selectedColor (committed ring) and activeColor (focus ring) are shown simultaneously,
128
- * so an item that is active always displays both rings regardless of selection state.
188
+ * A deterministic image id for one variant of a symbol, without rasterising it.
129
189
  *
130
- * @param {Object} symbolDef - Symbol definition
131
- * @param {Object} styleColors - Token overrides
132
- * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
133
- * @returns {string} Resolved SVG string
190
+ * @param {Object} style
191
+ * @param {Object} mapStyle - Current map style config (provides id, selectedColor, haloColor)
192
+ * @param {'normal'|'active'|'selected'} variant
193
+ * @param {number} pixelRatio - Device pixel ratio × map size scale factor
194
+ * @returns {string|null}
134
195
  */
135
- resolveActive (symbolDef, styleColors, mapStyle) {
136
- const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
137
- if (!symbolDef) { return '' }
138
- return resolveLayer(symbolDef.svg, colors)
196
+ getSymbolImageId (style, mapStyle, variant, pixelRatio) {
197
+ return this.resolveSymbolImage(style, mapStyle, variant, pixelRatio)?.imageId ?? null
139
198
  },
140
199
 
141
200
  /**
142
- * Resolve a symbol's SVG string for committed-selection rendering.
143
- * selectedColor (committed ring) is shown; activeColor is set to 'none'.
201
+ * The image ids of all three variants of a symbol, without rasterising them.
144
202
  *
145
- * @param {Object} symbolDef - Symbol definition
146
- * @param {Object} styleColors - Token overrides
147
- * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
148
- * @returns {string} Resolved SVG string
203
+ * @param {Object} style
204
+ * @param {Object} mapStyle
205
+ * @param {number} pixelRatio - Device pixel ratio × map size scale factor
206
+ * @returns {{ normal: string, active: string, selected: string }|null} null for an unknown symbol
149
207
  */
150
- resolveSelected (symbolDef, styleColors, mapStyle) {
151
- const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
152
- if (!symbolDef) { return '' }
153
- colors.activeColor = 'none'
154
- return resolveLayer(symbolDef.svg, colors)
155
- },
156
-
157
- // ─── Image IDs ────────────────────────────────────────────────────────────────
158
-
159
- /**
160
- * Returns a deterministic image ID for a symbol in normal or selected state.
161
- * Based on the hash of the fully resolved SVG content and the pixel ratio.
162
- *
163
- * @param {Object} style
164
- * @param {Object} mapStyle - Current map style config (provides id, selectedColor, haloColor)
165
- * @param {boolean} [selected=false]
166
- * @param {number} [pixelRatio=2] - Device pixel ratio × map size scale factor
167
- * @returns {string|null}
168
- */
169
- getSymbolImageId (style, mapStyle, active = false, pixelRatio = 2) {
170
- const symbolDef = this.getSymbolDef(style)
171
- if (!symbolDef) {
208
+ getSymbolImageIds (style, mapStyle, pixelRatio) {
209
+ const normal = this.getSymbolImageId(style, mapStyle, 'normal', pixelRatio)
210
+ if (!normal) {
172
211
  return null
173
212
  }
174
- const styleColors = getSymbolStyleColors(style)
175
- const resolved = active
176
- ? this.resolveActive(symbolDef, styleColors, mapStyle)
177
- : this.resolve(symbolDef, styleColors, mapStyle)
178
- return `symbol-${active ? 'act-' : ''}${hashString(resolved)}-${pixelRatio}x`
213
+ return {
214
+ normal,
215
+ active: this.getSymbolImageId(style, mapStyle, 'active', pixelRatio),
216
+ selected: this.getSymbolImageId(style, mapStyle, 'selected', pixelRatio)
217
+ }
179
218
  },
180
219
 
181
220
  /**
182
- * Resolves the symbolDef for a style's symbol config.
221
+ * Resolves the symbolDef for a dataset or draw style's symbol config, sized for
222
+ * style.symbolSize. Marker options drop the symbol prefix (`svgContent`, `size`, `viewBox`,
223
+ * `anchor`), so markers size their definition with getSizedSymbolDef instead.
183
224
  *
184
225
  * style.symbol is a string symbol ID (e.g. 'pin').
185
226
  * style.symbolSvgContent is inline SVG content for a custom symbol.
227
+ * style.symbolViewBox overrides the viewBox of an SVG-template symbol.
228
+ * style.symbolAnchor overrides the anchor — see getSizedSymbolDef.
186
229
  *
187
230
  * @param {Object} style
188
- * @returns {Object|undefined}
231
+ * @returns {Object|undefined} with viewBox and anchor for that size
189
232
  */
190
233
  getSymbolDef (style) {
191
- if (style.symbolSvgContent) {
192
- return { svg: style.symbolSvgContent }
193
- }
194
- if (style.symbol) {
195
- return this.get(style.symbol)
234
+ const baseDef = style.symbolSvgContent ? { svg: style.symbolSvgContent } : style.symbol && this.get(style.symbol)
235
+ if (!baseDef) {
236
+ return undefined
196
237
  }
197
- return undefined
238
+ return this.getSizedSymbolDef(baseDef, { viewBox: style.symbolViewBox, size: style.symbolSize, anchor: style.symbolAnchor })
198
239
  },
199
240
 
200
241
  /**
201
- * Rasterise one variant of a symbol to ImageData for use as a MapLibre image.
202
- * Results are cached by imageId so identical symbols are only rendered once.
203
- *
204
- * @param {Object} style - Dataset or marker config with symbol properties
205
- * @param {Object} mapStyle - Current map style config
206
- * @param {'normal'|'active'|'selected'} variant
207
- * - `'normal'` — no rings (default display)
208
- * - `'active'` — both rings (keyboard cursor, yellow + black)
209
- * - `'selected'` — selected ring only (black)
210
- * @param {number} pixelRatio - Device pixel ratio × map size scale factor
211
- * @returns {Promise<{imageId: string, imageData: ImageData}|null>}
212
- */
242
+ * Sizes a symbol definition for rendering. Built-in (path-based) symbols are composed at the
243
+ * size's scale with fixed-width rings; SVG-template symbols are scaled as a whole. The result
244
+ * always carries the viewBox and anchor for that size.
245
+ *
246
+ * @param {Object} symbolDef - a registered definition or { svg } for inline content
247
+ * @param {Object} [options]
248
+ * @param {string} [options.viewBox] - viewBox override, SVG-template symbols only
249
+ * @param {string} [options.size] - 'small' | 'medium' | 'large', else the map's default
250
+ * @param {number[]} [options.anchor] - anchor override, [x, y] in 0–1: a fraction of a built-in
251
+ * shape itself (so it stays on the same point at every size), or of an SVG-template symbol's viewBox
252
+ * @returns {Object}
253
+ */
254
+ getSizedSymbolDef (symbolDef, { viewBox, size, anchor } = {}) {
255
+ const scale = getSymbolScale(size ?? this.getDefaults().size)
256
+ const sized = symbolDef.path
257
+ ? composeSymbolDef(symbolDef, scale)
258
+ : scaleSvgSymbolDef(symbolDef, viewBox ?? symbolDef.viewBox ?? DEFAULT_SYMBOL_VIEWBOX, scale)
259
+ return applyAnchorOverride(sized, anchor)
260
+ },
261
+
262
+ /**
263
+ * Rasterises one variant of a symbol to ImageData, for a map provider to register.
264
+ * Results are cached by imageId so identical symbols are only rendered once.
265
+ *
266
+ * @param {Object} style - Dataset or marker config with symbol properties
267
+ * @param {Object} mapStyle - Current map style config
268
+ * @param {'normal'|'active'|'selected'} variant
269
+ * - `'normal'` — no rings (default display)
270
+ * - `'active'` — both rings (keyboard cursor, yellow + black)
271
+ * - `'selected'` — selected ring only (black)
272
+ * @param {number} pixelRatio - Device pixel ratio × map size scale factor
273
+ * @returns {Promise<{imageId: string, imageData: ImageData}|null>}
274
+ */
213
275
  async rasteriseSymbolImage (style, mapStyle, variant, pixelRatio) {
214
- const symbolDef = this.getSymbolDef(style)
215
- if (!symbolDef) {
276
+ const resolved = this.resolveSymbolImage(style, mapStyle, variant, pixelRatio)
277
+ if (!resolved) {
216
278
  return null
217
279
  }
218
- const styleColors = getSymbolStyleColors(style)
219
- let resolvedContent, prefix
220
- if (variant === 'active') {
221
- resolvedContent = this.resolveActive(symbolDef, styleColors, mapStyle)
222
- prefix = 'act-'
223
- } else if (variant === 'selected') {
224
- resolvedContent = this.resolveSelected(symbolDef, styleColors, mapStyle)
225
- prefix = 'sel-'
226
- } else {
227
- resolvedContent = this.resolve(symbolDef, styleColors, mapStyle)
228
- prefix = ''
229
- }
230
-
231
- const imageId = `symbol-${prefix}${hashString(resolvedContent)}-${pixelRatio}x`
280
+ const { symbolDef: { viewBox }, resolvedContent, imageId } = resolved
232
281
 
233
282
  let imageData = imageDataCache.get(imageId)
234
283
  if (!imageData) {
235
- const viewBox = getSymbolViewBox(style, symbolDef)
236
284
  const [,, width, height] = viewBox.split(' ').map(Number)
237
285
  // Render at pixelRatio× to keep icons crisp at the current device DPI and map size.
238
- // MapLibre receives the matching pixelRatio so the image displays at its original logical size.
286
+ // The provider registers it at the same pixelRatio, so it displays at its logical size.
239
287
  const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="${width * pixelRatio}" height="${height * pixelRatio}" viewBox="${viewBox}">${resolvedContent}</svg>`
240
- imageData = await rasteriseToImageData(svgString, width * pixelRatio, height * pixelRatio)
241
- imageDataCache.set(imageId, imageData)
288
+ imageData = await imageDataCache.rasteriseOnce(imageId, () => rasteriseToImageData(svgString, width * pixelRatio, height * pixelRatio))
242
289
  }
243
290
 
244
291
  return { imageId, imageData }
245
292
  }
246
293
  }
247
294
 
248
- symbolRegistry.initialise()
295
+ /**
296
+ * Creates a symbol registry: the built-in symbols plus any registered custom ones, and the
297
+ * app's symbolDefaults. Each map instance has its own, so maps on the same page can register
298
+ * different symbols and defaults.
299
+ *
300
+ * @returns {Object} the registry
301
+ */
302
+ export const createSymbolRegistry = () => {
303
+ const symbols = new Map()
304
+ let constructorDefaults = {}
305
+
306
+ const registry = {
307
+ /**
308
+ * Sets this map's constructor-level defaults (its symbolDefaults config).
309
+ * Merges onto symbolDefaults to form this map's token baseline.
310
+ *
311
+ * @param {Object} defaults - Constructor symbolDefaults config
312
+ */
313
+ setDefaults (defaults) {
314
+ constructorDefaults = defaults || {}
315
+ },
316
+
317
+ /**
318
+ * Returns this map's merged defaults (hardcoded + constructor overrides).
319
+ * Includes both structural properties (symbol, viewBox, anchor) and token values.
320
+ *
321
+ * @returns {Object}
322
+ */
323
+ getDefaults () {
324
+ return { ...symbolDefaults, ...constructorDefaults }
325
+ },
326
+
327
+ /**
328
+ * Register a custom symbol: an SVG template with {{token}} placeholders, its viewBox and an
329
+ * optional anchor. Throws a descriptive error for an incomplete definition.
330
+ *
331
+ * @param {Object} symbolDef
332
+ */
333
+ register (symbolDef) {
334
+ validateSymbolDef(symbolDef)
335
+ symbols.set(symbolDef.id, symbolDef)
336
+ },
337
+
338
+ get (id) {
339
+ return symbols.get(id)
340
+ },
341
+
342
+ list () {
343
+ return [...symbols.values()]
344
+ },
345
+
346
+ /**
347
+ * Clears all registered symbols (including built-ins). Mainly for testing purposes.
348
+ */
349
+ clear () {
350
+ symbols.clear()
351
+ },
352
+
353
+ /**
354
+ * Registers the built-in symbols. Called when the registry is created.
355
+ */
356
+ initialise () {
357
+ this.register(pin)
358
+ this.register(circle)
359
+ this.register(square)
360
+ this.register(hexagon)
361
+ this.register(triangle)
362
+ this.register(diamond)
363
+ },
364
+
365
+ /**
366
+ * Resolve a symbol's SVG string for normal (unselected, inactive) rendering.
367
+ * Both selectedColor and activeColor are set to 'none' — all rings hidden.
368
+ *
369
+ * @param {Object} symbolDef - Symbol definition
370
+ * @param {Object} styleColors - Token overrides
371
+ * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
372
+ * @returns {string} Resolved SVG string
373
+ */
374
+ resolve (symbolDef, styleColors, mapStyle) {
375
+ const colors = resolveValues(symbolDef, styleColors || {}, mapStyle, constructorDefaults)
376
+ if (!symbolDef) { return '' }
377
+ colors.selectedColor = 'none'
378
+ colors.activeColor = 'none'
379
+ return renderSymbol(symbolDef, colors)
380
+ },
381
+
382
+ /**
383
+ * Resolve a symbol's SVG string for active (keyboard cursor) rendering.
384
+ * Both selectedColor (committed ring) and activeColor (focus ring) are shown simultaneously,
385
+ * so an item that is active always displays both rings regardless of selection state.
386
+ *
387
+ * @param {Object} symbolDef - Symbol definition
388
+ * @param {Object} styleColors - Token overrides
389
+ * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
390
+ * @returns {string} Resolved SVG string
391
+ */
392
+ resolveActive (symbolDef, styleColors, mapStyle) {
393
+ const colors = resolveValues(symbolDef, styleColors || {}, mapStyle, constructorDefaults)
394
+ if (!symbolDef) { return '' }
395
+ return renderSymbol(symbolDef, colors)
396
+ },
397
+
398
+ /**
399
+ * Resolve a symbol's SVG string for committed-selection rendering.
400
+ * selectedColor (committed ring) is shown; activeColor is set to 'none'.
401
+ *
402
+ * @param {Object} symbolDef - Symbol definition
403
+ * @param {Object} styleColors - Token overrides
404
+ * @param {Object} mapStyle - Current map style config (provides selectedColor, activeColor, haloColor)
405
+ * @returns {string} Resolved SVG string
406
+ */
407
+ resolveSelected (symbolDef, styleColors, mapStyle) {
408
+ const colors = resolveValues(symbolDef, styleColors || {}, mapStyle, constructorDefaults)
409
+ if (!symbolDef) { return '' }
410
+ colors.activeColor = 'none'
411
+ return renderSymbol(symbolDef, colors)
412
+ },
413
+
414
+ ...symbolImageMethods
415
+ }
416
+
417
+ registry.initialise()
418
+ return registry
419
+ }