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

package/plugins/beta/datasets/src/panels/Key.module.scss

@@ -1,19 +1,58 @@
-.im-c-datasets-key {
+// When groups are present, every direct child gets a border-top
+.im-c-datasets-key--has-groups > * {
+  border-top: 1px solid var(--button-hover-color);
+}
+
+// When no groups, only the first child gets a border-top
+.im-c-datasets-key:not(.im-c-datasets-key--has-groups) > *:first-child {
+  border-top: 1px solid var(--button-hover-color);
+}
 
+.im-c-datasets-key__group:not(:last-child) {
+  padding-bottom: 5px;
 }
 
-.im-c-datasets-key__item-label {
+.im-c-datasets-key__group-heading {
+  padding-top: 15px;
+  padding-bottom: 10px;
+  margin: 0;
+  font-size: 1rem;
+  font-weight: bold;
+  color: var(--foreground-color);
+}
+
+.im-c-datasets-key__item {
   display: flex;
   align-items: start;
-  padding-top: 12px;
-  padding-bottom: 12px;
-  align-self: auto;
+  padding-top: 10px;
+  padding-bottom: 10px;
   font-size: 1rem;
-  line-height: 1.2;
+
+  // When mixed with groups, flat items match group heading spacing
+  .im-c-datasets-key--has-groups > & {
+    padding-top: 15px;
+    padding-bottom: 15px;
+  }
+
+  // First item inside a group — heading already provides top spacing
+  .im-c-datasets-key__group &:first-child {
+    padding-top: 0;
+  }
+}
+
+// No-groups: first item needs 15px below the single border
+.im-c-datasets-key:not(.im-c-datasets-key--has-groups) > .im-c-datasets-key__item:first-child {
+  padding-top: 15px;
 }
 
-.im-c-datasets-key__item-label svg {
+// Last item in all scenarios — flat or inside the last group
+.im-c-datasets-key > .im-c-datasets-key__item:last-child,
+.im-c-datasets-key__group:last-child .im-c-datasets-key__item:last-child {
+  padding-bottom: 5px;
+}
+
+.im-c-datasets-key__item svg {
   position: relative;
   flex-shrink: 0;
-  margin: 0px 13px 0 2px;
-}
+  margin: 0 13px 0 2px;
+}

package/plugins/beta/datasets/src/panels/Layers.jsx

@@ -1,38 +1,141 @@
 import React from 'react'
-import { showDataset } from '../api/showDataset'
-import { hideDataset } from '../api/hideDataset'
+import { setDatasetVisibility } from '../api/setDatasetVisibility'
 
-export const Layers = ({ pluginState, mapProvider }) => {
-  const handleChange = (e) => {
-    const { value, checked } = e.target
-    if (checked) {
-      showDataset({ mapProvider, pluginState }, value)
-    } else {
-      hideDataset({ mapProvider, pluginState }, value)
+const CHECKBOX_LABEL_CLASS = 'im-c-datasets-layers__item-label govuk-label govuk-checkboxes__label'
+
+const hasToggleableSublayers = (dataset) => dataset.sublayers?.some(sublayer => sublayer.toggleVisibility)
+
+/**
+ * Collapse the filtered dataset list into ordered render items:
+ *   { type: 'sublayers', dataset }              — dataset with sublayers (takes precedence)
+ *   { type: 'group', groupLabel, datasets } — datasets sharing a groupLabel
+ *   { type: 'flat', dataset }               — standalone dataset
+ */
+const buildRenderItems = (datasets) => {
+  const seenGroups = new Set()
+  const items = []
+  datasets.forEach(dataset => {
+    if (hasToggleableSublayers(dataset)) {
+      items.push({ type: 'sublayers', dataset })
+      return
     }
+    if (dataset.groupLabel) {
+      if (seenGroups.has(dataset.groupLabel)) {
+        return
+      }
+      seenGroups.add(dataset.groupLabel)
+      items.push({
+        type: 'group',
+        groupLabel: dataset.groupLabel,
+        datasets: datasets.filter(d => !hasToggleableSublayers(d) && d.groupLabel === dataset.groupLabel)
+      })
+      return
+    }
+    items.push({ type: 'flat', dataset })
+  })
+  return items
+}
+
+export const Layers = ({ pluginState }) => {
+  const handleDatasetChange = (e) => {
+    const { value, checked } = e.target
+    setDatasetVisibility({ pluginState }, checked, { datasetId: value })
   }
 
-  return (
-    <div className='im-c-datasets-layers'>
-      <div className='govuk-form-group'>
-        <fieldset className='govuk-fieldset'>
-          <legend className='govuk-visually-hidden'>
-            Layers
-          </legend>
-          <div className='govuk-checkboxes govuk-checkboxes--small' data-module='govuk-checkboxes'>
-            {(pluginState.datasets || []).filter(dataset => dataset.showInLayers).map(dataset => (
-              <div key={dataset.id} className={`im-c-datasets-layers__item${dataset.visibility !== 'hidden' ? ' im-c-datasets-layers__item--checked' : ''}`}>
-                <div className='govuk-checkboxes__item'>
-                  <input className='govuk-checkboxes__input' id={dataset.id} name='layers' type='checkbox' value={dataset.id} checked={dataset.visibility !== 'hidden'} onChange={handleChange} />
-                  <label className='im-c-datasets-layers__item-label govuk-label govuk-checkboxes__label' htmlFor={dataset.id}>
-                    {dataset.label}
-                  </label>
-                </div>
-              </div>
-            ))}
-          </div>
-        </fieldset>
+  const handleSublayerChange = (e) => {
+    const { checked } = e.target
+    const datasetId = e.target.dataset.datasetId
+    const sublayerId = e.target.dataset.sublayerId
+    setDatasetVisibility({ pluginState }, checked, { datasetId, sublayerId })
+  }
+
+  const renderDatasetItem = (dataset) => {
+    const itemClass = `im-c-datasets-layers__item govuk-checkboxes govuk-checkboxes--small${dataset.visibility === 'hidden' ? '' : ' im-c-datasets-layers__item--checked'}`
+    return (
+      <div key={dataset.id} className={itemClass} data-module='govuk-checkboxes'>
+        <div className='govuk-checkboxes__item'>
+          <input
+            className='govuk-checkboxes__input'
+            id={dataset.id}
+            name='layers'
+            type='checkbox'
+            value={dataset.id}
+            checked={dataset.visibility !== 'hidden'}
+            onChange={handleDatasetChange}
+          />
+          <label className={CHECKBOX_LABEL_CLASS} htmlFor={dataset.id}>
+            {dataset.label}
+          </label>
+        </div>
       </div>
+    )
+  }
+
+  const visibleDatasets = (pluginState.datasets || [])
+    .filter(dataset => dataset.toggleVisibility || hasToggleableSublayers(dataset))
+
+  const renderItems = buildRenderItems(visibleDatasets)
+  const hasGroups = renderItems.some(item => item.type === 'sublayers' || item.type === 'group')
+  const containerClass = `im-c-datasets-layers${hasGroups ? ' im-c-datasets-layers--has-groups' : ''}`
+
+  return (
+    <div className={containerClass}>
+      {renderItems.map(item => {
+        if (item.type === 'sublayers') {
+          const { dataset } = item
+          const anySublayerChecked = dataset.sublayers
+            .filter(sublayer => sublayer.toggleVisibility)
+            .some(sublayer => dataset.sublayerVisibility?.[sublayer.id] !== 'hidden')
+          const wrapperClass = `govuk-form-group im-c-datasets-layers-group${anySublayerChecked ? ' im-c-datasets-layers-group--items-checked' : ''}`
+          return (
+            <div key={dataset.id} className={wrapperClass}>
+              <fieldset className='im-c-datasets-layers-group__fieldset'>
+                <legend className='im-c-datasets-layers-group__legend'>{dataset.label}</legend>
+                {dataset.sublayers
+                  .filter(sublayer => sublayer.toggleVisibility)
+                  .map(sublayer => {
+                    const sublayerVisible = dataset.sublayerVisibility?.[sublayer.id] !== 'hidden'
+                    const inputId = `${dataset.id}-${sublayer.id}`
+                    const itemClass = `im-c-datasets-layers__item govuk-checkboxes govuk-checkboxes--small${sublayerVisible ? ' im-c-datasets-layers__item--checked' : ''}`
+                    return (
+                      <div key={sublayer.id} className={itemClass} data-module='govuk-checkboxes'>
+                        <div className='govuk-checkboxes__item'>
+                          <input
+                            className='govuk-checkboxes__input'
+                            id={inputId}
+                            type='checkbox'
+                            checked={sublayerVisible}
+                            data-dataset-id={dataset.id}
+                            data-sublayer-id={sublayer.id}
+                            onChange={handleSublayerChange}
+                          />
+                          <label className={CHECKBOX_LABEL_CLASS} htmlFor={inputId}>
+                            {sublayer.label}
+                          </label>
+                        </div>
+                      </div>
+                    )
+                  })}
+              </fieldset>
+            </div>
+          )
+        }
+
+        if (item.type === 'group') {
+          const anyDatasetChecked = item.datasets.some(d => d.visibility !== 'hidden')
+          const wrapperClass = `govuk-form-group im-c-datasets-layers-group${anyDatasetChecked ? ' im-c-datasets-layers-group--items-checked' : ''}`
+          return (
+            <div key={item.groupLabel} className={wrapperClass}>
+              <fieldset className='im-c-datasets-layers-group__fieldset'>
+                <legend className='im-c-datasets-layers-group__legend'>{item.groupLabel}</legend>
+                {item.datasets.map(dataset => renderDatasetItem(dataset))}
+              </fieldset>
+            </div>
+          )
+        }
+
+        return renderDatasetItem(item.dataset)
+      })}
     </div>
   )
 }

package/plugins/beta/datasets/src/panels/Layers.module.scss

@@ -1,8 +1,37 @@
+// When groups are present, every direct child (groups and flat items) gets a border-top
+.im-c-datasets-layers--has-groups > * {
+  border-top: 1px solid var(--button-hover-color);
+}
+
+// When no groups, only the first child gets a border-top with 15px padding
+.im-c-datasets-layers:not(.im-c-datasets-layers--has-groups) > *:first-child {
+  border-top: 1px solid var(--button-hover-color);
+  padding-top: 10px;
+}
+
+.im-c-datasets-layers > *:last-child {
+  margin-bottom: -5px;
+}
+
+.im-c-datasets-layers-group:not(:last-child) {
+  padding-bottom: 5px;
+}
+
 .im-c-datasets-layers__item {
-  border: 1px solid var(--button-hover-color);
-  padding-left: 10px;
-  &:not(last-child) {
-    margin-bottom: 5px;
+  padding-bottom: 5px;
+
+  .im-c-datasets-layers--has-groups > & {
+    padding-top: 5px;
+  }
+
+  // Items inside a group have no individual padding or spacing between them
+  .im-c-datasets-layers-group & {
+    padding-top: 0;
+    padding-bottom: 0;
+
+    &:not(:last-child) {
+      margin-bottom: 0;
+    }
   }
 }
 
@@ -19,10 +48,6 @@
   color: var(--foreground-color);
 }
 
-.im-c-datasets-layers__item--checked {
-  border-color: var(--app-border-color);
-}
-
 // GovUK style overide
 .im-c-datasets-layers__item .govuk-checkboxes__item {
   flex-wrap: nowrap;
@@ -31,3 +56,20 @@
     margin-left: -3px;
   }
 }
+
+.im-c-datasets-layers-group__fieldset {
+  // Reset browser fieldset defaults
+  border: none;
+  padding: 0;
+  margin: 0;
+  min-width: 0;
+}
+
+.im-c-datasets-layers-group__legend {
+  padding-top: 15px;
+  padding-bottom: 10px;
+  padding-inline: 0;
+  font-size: 1rem;
+  font-weight: bold;
+  color: var(--foreground-color);
+}

package/plugins/beta/datasets/src/reducer.js

@@ -1,16 +1,27 @@
+import { applyDatasetDefaults } from './defaults.js'
+
 const initialState = {
   datasets: null,
-  hiddenFeatures: {} // { [layerId]: { idProperty: string, ids: string[] } }
+  hiddenFeatures: {}, // { [layerId]: { idProperty: string, ids: string[] } }
+  layerAdapter: null
+}
+
+const initSublayerVisibility = (dataset) => {
+  if (!dataset.sublayers?.length) {
+    return dataset
+  }
+  const sublayerVisibility = {}
+  dataset.sublayers.forEach(sublayer => {
+    sublayerVisibility[sublayer.id] = 'visible'
+  })
+  return { ...dataset, sublayerVisibility }
 }
 
 const setDatasets = (state, payload) => {
   const { datasets, datasetDefaults } = payload
   return {
     ...state,
-    datasets: datasets.map(dataset => ({
-      ...datasetDefaults,
-      ...dataset
-    }))
+    datasets: datasets.map(dataset => initSublayerVisibility(applyDatasetDefaults(dataset, datasetDefaults)))
   }
 }
 
@@ -20,7 +31,7 @@ const addDataset = (state, payload) => {
     ...state,
     datasets: [
       ...(state.datasets || []),
-      { ...datasetDefaults, ...dataset }
+      initSublayerVisibility(applyDatasetDefaults(dataset, datasetDefaults))
     ]
   }
 }
@@ -43,6 +54,14 @@ const setDatasetVisibility = (state, payload) => {
   }
 }
 
+const setGlobalVisibility = (state, payload) => {
+  const { visibility } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset => ({ ...dataset, visibility }))
+  }
+}
+
 const hideFeatures = (state, payload) => {
   const { layerId, idProperty, featureIds } = payload
   const existing = state.hiddenFeatures[layerId]
@@ -61,12 +80,15 @@ const hideFeatures = (state, payload) => {
 const showFeatures = (state, payload) => {
   const { layerId, featureIds } = payload
   const existing = state.hiddenFeatures[layerId]
-  if (!existing) return state
+  if (!existing) {
+    return state
+  }
 
   const newIds = existing.ids.filter(id => !featureIds.includes(id))
 
   if (newIds.length === 0) {
-    const { [layerId]: _, ...rest } = state.hiddenFeatures
+    const rest = { ...state.hiddenFeatures }
+    delete rest[layerId]
     return { ...state, hiddenFeatures: rest }
   }
 
@@ -79,13 +101,110 @@ const showFeatures = (state, payload) => {
   }
 }
 
+const setSublayerVisibility = (state, payload) => {
+  const { datasetId, sublayerId, visibility } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset => {
+      if (dataset.id !== datasetId) {
+        return dataset
+      }
+      return {
+        ...dataset,
+        sublayerVisibility: {
+          ...dataset.sublayerVisibility,
+          [sublayerId]: visibility
+        }
+      }
+    })
+  }
+}
+
+const setDatasetStyle = (state, payload) => {
+  const { datasetId, styleChanges } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset =>
+      dataset.id === datasetId ? { ...dataset, ...styleChanges } : dataset
+    )
+  }
+}
+
+const setSublayerStyle = (state, payload) => {
+  const { datasetId, sublayerId, styleChanges } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset => {
+      if (dataset.id !== datasetId) {
+        return dataset
+      }
+      return {
+        ...dataset,
+        sublayers: dataset.sublayers?.map(sublayer =>
+          sublayer.id === sublayerId
+            ? { ...sublayer, style: { ...sublayer.style, ...styleChanges } }
+            : sublayer
+        )
+      }
+    })
+  }
+}
+
+const setOpacity = (state, payload) => {
+  const { datasetId, opacity } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset =>
+      dataset.id === datasetId ? { ...dataset, opacity } : dataset
+    )
+  }
+}
+
+const setGlobalOpacity = (state, payload) => {
+  const { opacity } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset => ({ ...dataset, opacity }))
+  }
+}
+
+const setSublayerOpacity = (state, payload) => {
+  const { datasetId, sublayerId, opacity } = payload
+  return {
+    ...state,
+    datasets: state.datasets?.map(dataset => {
+      if (dataset.id !== datasetId) {
+        return dataset
+      }
+      return {
+        ...dataset,
+        sublayers: dataset.sublayers?.map(sublayer =>
+          sublayer.id === sublayerId
+            ? { ...sublayer, style: { ...sublayer.style, opacity } }
+            : sublayer
+        )
+      }
+    })
+  }
+}
+
+const setLayerAdapter = (state, payload) => ({ ...state, layerAdapter: payload })
+
 const actions = {
   SET_DATASETS: setDatasets,
   ADD_DATASET: addDataset,
   REMOVE_DATASET: removeDataset,
   SET_DATASET_VISIBILITY: setDatasetVisibility,
+  SET_GLOBAL_VISIBILITY: setGlobalVisibility,
+  SET_SUBLAYER_VISIBILITY: setSublayerVisibility,
+  SET_DATASET_STYLE: setDatasetStyle,
+  SET_SUBLAYER_STYLE: setSublayerStyle,
+  SET_OPACITY: setOpacity,
+  SET_GLOBAL_OPACITY: setGlobalOpacity,
+  SET_SUBLAYER_OPACITY: setSublayerOpacity,
   HIDE_FEATURES: hideFeatures,
-  SHOW_FEATURES: showFeatures
+  SHOW_FEATURES: showFeatures,
+  SET_LAYER_ADAPTER: setLayerAdapter
 }
 
 export {

package/plugins/beta/datasets/src/styles/patterns.js

@@ -0,0 +1,157 @@
+import { getValueForStyle } from '../../../../../src/utils/getValueForStyle.js'
+
+// ─── Built-in pattern library ────────────────────────────────────────────────
+// Each value is the inner SVG content (paths only, no wrapper).
+// Paths are authored in a 16×16 coordinate space (power-of-two, tiles seamlessly).
+// Use {{foreground}} and {{background}} tokens for colours.
+
+const BUILT_IN_PATTERNS = {
+  'cross-hatch': '<path d="M0 4.486V3.485h3.5V.001h1v3.484h7.002V.001h1v3.484h3.5v1.001h-3.5v7h3.5v.999h-3.5v3.516h-1v-3.516H4.499v3.516h-1v-3.516H0v-.999h3.5v-7H0zm11.501 0H4.499v7h7.002v-7z" fill="{{foreground}}"/>',
+  'diagonal-cross-hatch': '<path d="M0 8.707V7.293L7.293 0h1.414L16 7.293v1.414L8.707 16H7.293L0 8.707zM.707 8L8 15.293 15.293 8 8 .707.707 8z" fill="{{foreground}}"/>',
+  'forward-diagonal-hatch': '<path d="M16 8.707V7.293L7.293 16h1.414L16 8.707zm-16 0L8.707 0H7.293L0 7.293v1.414z" fill="{{foreground}}"/>',
+  'backward-diagonal-hatch': '<path d="M0 8.707V7.293L8.707 16H7.293L0 8.707zm16 0L7.293 0h1.414L16 7.293v1.414z" fill="{{foreground}}"/>',
+  'horizontal-hatch': '<path d="M0 4.5V3.499h15.999V4.5H0zm0 7h15.999V12.5H0v-1.001z" fill="{{foreground}}"/>',
+  'vertical-hatch': '<path d="M3.501 16.001V0h1v16.001h-1zm7.998 0V0h1v16.001h-1z" fill="{{foreground}}"/>',
+  dot: '<path d="M3.999 2A2 2 0 0 1 6 3.999C6 5.103 5.103 6 3.999 6a2 2 0 0 1-1.999-2.001A2 2 0 0 1 3.999 2zm0 7.999C5.103 10 6 10.897 6 12.001A2 2 0 0 1 3.999 14a2 2 0 0 1-1.999-1.999A2 2 0 0 1 3.999 10zM11.999 2A2 2 0 0 1 14 3.999C14 5.103 13.103 6 11.999 6S10 5.103 10 3.999A2 2 0 0 1 11.999 2zm0 7.999c1.104 0 2.001.897 2.001 2.001A2 2 0 0 1 11.999 14 2 2 0 0 1 10 12.001c0-1.104.897-2.001 1.999-2.001z" fill="{{foreground}}"/>',
+  diamond: '<path d="M4 .465L7.535 4 4 7.535.465 4 4 .465zm0 7.999l3.535 3.535L4 15.535.465 11.999 4 8.464zm8-8l3.535 3.535-3.536 3.536L8.464 4 12 .464zm0 8.001L15.536 12 12 15.536 8.465 12 12 8.465z" fill="{{foreground}}"/>'
+}
+
+// Plugin-controlled border path used in the key symbol (20×20 coordinate space).
+// This is always rendered as the first element, before the user-supplied content.
+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="{{background}}" stroke="{{foreground}}" stroke-width="2"/>'
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+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
+}
+
+export const injectColors = (content, foreground, background) =>
+  content
+    .replace(/\{\{foreground\}\}/g, foreground || 'black')
+    .replace(/\{\{background\}\}/g, background || 'transparent')
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if a dataset 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.
+ * Custom fillPatternSvgContent takes precedence over built-in fillPattern ids.
+ * @param {Object} dataset
+ * @returns {string|null}
+ */
+export const getPatternInnerContent = (dataset) => {
+  if (dataset.fillPatternSvgContent) {
+    return dataset.fillPatternSvgContent
+  }
+  if (dataset.fillPattern && BUILT_IN_PATTERNS[dataset.fillPattern]) {
+    return BUILT_IN_PATTERNS[dataset.fillPattern]
+  }
+  return null
+}
+
+/**
+ * Returns a deterministic image ID for a pattern + resolved colour combination.
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @returns {string|null}
+ */
+export const getPatternImageId = (dataset, mapStyleId) => {
+  const innerContent = getPatternInnerContent(dataset)
+  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 inner SVG path content for use in the Key symbol.
+ * The caller is responsible for wrapping this in the SVG element and border path.
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @returns {{ border: string, content: string }|null}
+ */
+export const getKeyPatternPaths = (dataset, mapStyleId) => {
+  const innerContent = getPatternInnerContent(dataset)
+  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)
+  }
+}
+
+// ─── Rasterisation ────────────────────────────────────────────────────────────
+
+// Module-level cache: imageId → ImageData. Avoids re-rasterising identical patterns.
+const imageDataCache = new Map()
+
+const rasteriseToImageData = (svgString, width, height) =>
+  new Promise((resolve, reject) => {
+    const blob = new Blob([svgString], { type: 'image/svg+xml' })
+    const url = URL.createObjectURL(blob)
+    const img = new Image(width, height)
+    img.onload = () => {
+      const canvas = document.createElement('canvas')
+      canvas.width = width
+      canvas.height = height
+      const ctx = canvas.getContext('2d')
+      ctx.drawImage(img, 0, 0, width, height)
+      URL.revokeObjectURL(url)
+      resolve(ctx.getImageData(0, 0, width, height))
+    }
+    img.onerror = () => {
+      URL.revokeObjectURL(url)
+      reject(new Error(`Failed to rasterise pattern SVG: ${svgString.slice(0, 80)}`))
+    }
+    img.src = url
+  })
+
+/**
+ * Rasterises a dataset's pattern SVG to ImageData, using an in-memory cache
+ * to avoid re-rasterising identical patterns. Framework-agnostic — callers
+ * are responsible for registering the result with their map framework.
+ *
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @returns {Promise<{ imageId: string, imageData: ImageData }|null>}
+ */
+export const rasterisePattern = async (dataset, mapStyleId) => {
+  const innerContent = getPatternInnerContent(dataset)
+  if (!innerContent) {
+    return null
+  }
+
+  const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
+  const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
+  const imageId = `pattern-${hashString(innerContent + fg + bg)}`
+
+  let imageData = imageDataCache.get(imageId)
+  if (!imageData) {
+    const colored = injectColors(innerContent, fg, bg)
+    const bgRect = `<rect width="16" height="16" fill="${bg}"/>`
+    // pixelRatio: 2 means the map treats this as an 8×8 logical tile — crisp on retina screens.
+    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">${bgRect}${colored}</svg>`
+    imageData = await rasteriseToImageData(svgString, 16, 16)
+    imageDataCache.set(imageId, imageData)
+  }
+
+  return { imageId, imageData }
+}