@defra/interactive-map 0.0.36-alpha → 0.0.38-alpha

package/plugins/draw/src/adapters/maplibre/snap/sourceData.test.js

@@ -0,0 +1,62 @@
+import { pollUntil, patchSourceData } from './sourceData.js'
+
+describe('pollUntil', () => {
+  beforeEach(() => {
+    global.requestAnimationFrame = jest.fn()
+  })
+
+  test('stops when checkFn returns null', () => {
+    const onSuccess = jest.fn()
+    pollUntil(() => null, onSuccess)
+    expect(onSuccess).not.toHaveBeenCalled()
+    expect(global.requestAnimationFrame).not.toHaveBeenCalled()
+  })
+
+  test('calls onSuccess when checkFn returns a truthy value', () => {
+    const onSuccess = jest.fn()
+    pollUntil(() => 'ready', onSuccess)
+    expect(onSuccess).toHaveBeenCalledWith('ready')
+  })
+
+  test('reschedules via requestAnimationFrame until the value becomes available', () => {
+    const values = [undefined, 'ready']
+    let i = 0
+    global.requestAnimationFrame = jest.fn((cb) => cb())
+    const onSuccess = jest.fn()
+
+    pollUntil(() => values[i++], onSuccess)
+
+    expect(global.requestAnimationFrame).toHaveBeenCalledTimes(1)
+    expect(onSuccess).toHaveBeenCalledWith('ready')
+  })
+})
+
+describe('patchSourceData', () => {
+  test('ignores a nullish source', () => {
+    expect(() => patchSourceData(null)).not.toThrow()
+  })
+
+  test('ignores a source that already exposes _data.features', () => {
+    const existing = { features: [] }
+    const source = { _data: existing }
+    patchSourceData(source)
+    expect(source._data).toBe(existing)
+  })
+
+  test('installs a _data accessor that normalizes assigned values', () => {
+    const source = {}
+    patchSourceData(source)
+
+    expect(source._data).toEqual({ type: 'FeatureCollection', features: [] })
+
+    const fc = { type: 'FeatureCollection', features: [{ id: 1 }] }
+    source._data = fc
+    expect(source._data).toBe(fc)
+
+    source._data = 'nonsense'
+    expect(source._data).toEqual({ type: 'FeatureCollection', features: [] })
+
+    source._data = { features: 'not-array' }
+    expect(source._data).toEqual({ type: 'FeatureCollection', features: [] })
+  })
+})

package/plugins/draw/src/adapters/maplibre/styles.js

@@ -0,0 +1,207 @@
+// styles.js
+import { SIZES } from './defaults.js'
+import { resolveColors } from '../../utils/resolveColors.js'
+
+// `defaultValue` is the already-resolved fallback (colors[defaultsKey] — the
+// plugin-config override if one was set, else the built-in default), not the
+// raw COLORS constant, so a shapeStroke/shapeFill override applies to every
+// feature that doesn't set its own stroke/fill property.
+const getUserProp = (mapStyle, prop, defaultValue) => [
+  'coalesce',
+  ['get', `user_${prop}${mapStyle.id.charAt(0).toUpperCase() + mapStyle.id.slice(1)}`],
+  ['get', `user_${prop}`],
+  defaultValue
+]
+
+// Inactive lines and fills
+const fillInactive = (mapStyle, colors) => ({
+  id: 'fill-inactive',
+  type: 'fill',
+  filter: ['all', ['==', '$type', 'Polygon'], ['==', 'active', 'false']],
+  paint: { 'fill-color': getUserProp(mapStyle, 'fill', colors.shapeFill) }
+})
+
+const strokeInactive = (mapStyle, colors) => ({
+  id: 'stroke-inactive',
+  type: 'line',
+  filter: ['all', ['any', ['==', '$type', 'Polygon'], ['==', '$type', 'LineString']], ['==', 'active', 'false'], ['!has', 'user_splitter']],
+  layout: { 'line-cap': 'round', 'line-join': 'round' },
+  paint: {
+    'line-color': getUserProp(mapStyle, 'stroke', colors.shapeStroke),
+    'line-width': colors.strokeWidth
+  }
+})
+
+// Active lines and fills (sketch during drawing)
+const fillActive = (editFillColor) => ({
+  id: 'fill-active',
+  type: 'fill',
+  filter: ['all', ['==', '$type', 'Polygon'], ['==', 'active', 'true']],
+  paint: { 'fill-color': editFillColor }
+})
+
+const strokeActive = (editStrokeColor) => ({
+  id: 'stroke-active',
+  type: 'line',
+  filter: ['all', ['any', ['==', '$type', 'Polygon'], ['==', '$type', 'LineString']], ['==', 'active', 'true'], ['!has', 'user_splitter']],
+  layout: { 'line-cap': 'round', 'line-join': 'round' },
+  paint: { 'line-color': editStrokeColor, 'line-width': 2, 'line-opacity': 1 }
+})
+
+// Dashed stroke shown in place of stroke-active while the shape is invalid. Same
+// filter as stroke-active; the adapter's setInvalid() toggles the two layers'
+// visibility (line-dasharray can't be data-driven per feature in MapLibre).
+const strokeActiveInvalid = (invalidStrokeColor) => ({
+  id: 'stroke-active-invalid',
+  type: 'line',
+  filter: ['all', ['any', ['==', '$type', 'Polygon'], ['==', '$type', 'LineString']], ['==', 'active', 'true'], ['!has', 'user_splitter']],
+  layout: { 'line-cap': 'round', 'line-join': 'round', visibility: 'none' },
+  paint: {
+    'line-color': invalidStrokeColor,
+    'line-width': 2,
+    'line-dasharray': [0.2, 2], // NOSONAR
+    'line-opacity': 1
+  }
+})
+
+// Splitter line
+const drawInvalidSplitter = (splitInvalidColor) => ({
+  id: 'stroke-invalid-splitter',
+  type: 'line',
+  filter: ['all', ['==', '$type', 'LineString'], ['==', 'active', 'true'], ['==', 'user_splitter', 'invalid']],
+  layout: { 'line-cap': 'round', 'line-join': 'round' },
+  paint: {
+    'line-color': splitInvalidColor,
+    'line-width': 2,
+    'line-dasharray': [0.2, 2], // NOSONAR
+    'line-opacity': 1
+  }
+})
+
+const drawValidSplitter = (splitValidColor) => ({
+  id: 'stroke-valid-splitter',
+  type: 'line',
+  filter: ['all', ['==', '$type', 'LineString'], ['==', 'active', 'true'], ['==', 'user_splitter', 'valid']],
+  layout: { 'line-cap': 'round', 'line-join': 'round' },
+  paint: {
+    'line-color': splitValidColor,
+    'line-width': 2,
+    'line-opacity': 1
+  }
+})
+
+// Dashed preview line
+const drawPreviewLine = (editStrokeColor) => ({
+  id: 'stroke-preview-line',
+  type: 'line',
+  filter: ['all', ['==', '$type', 'LineString'], ['==', 'active', 'true'], ['!has', 'user_splitter']],
+  layout: { 'line-cap': 'round', 'line-join': 'round' },
+  paint: { 'line-color': editStrokeColor, 'line-width': 2, 'line-dasharray': [0.2, 2], 'line-opacity': 1 } // NOSONAR
+})
+
+// Vertex layers ('draw-vertex' = display-only markers on placed vertices while drawing)
+const vertex = (editVertexColor, vertexRadius) => ({
+  id: 'vertex',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['in', 'meta', 'vertex', 'draw-vertex']],
+  paint: { 'circle-radius': vertexRadius, 'circle-color': editVertexColor }
+})
+
+const vertexHalo = (editHaloColor, editActiveColor, vertexHaloRadius) => ({
+  id: 'vertex-halo',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'vertex'], ['==', 'active', 'true']],
+  paint: { 'circle-radius': vertexHaloRadius, 'circle-stroke-width': 3, 'circle-color': editHaloColor, 'circle-stroke-color': editActiveColor }
+})
+
+const vertexActive = (editVertexColor, vertexRadius) => ({
+  id: 'vertex-active',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'vertex'], ['==', 'active', 'true']],
+  paint: { 'circle-radius': vertexRadius, 'circle-color': editVertexColor }
+})
+
+// Midpoints
+const midpoint = (editMidpointColor, midpointRadius) => ({
+  id: 'midpoint',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'midpoint']],
+  paint: { 'circle-radius': midpointRadius, 'circle-color': editMidpointColor }
+})
+
+const midpointHalo = (editHaloColor, editActiveColor, midpointHaloRadius) => ({
+  id: 'midpoint-halo',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'midpoint'], ['==', 'active', 'true']],
+  paint: { 'circle-radius': midpointHaloRadius, 'circle-stroke-width': 3, 'circle-color': editHaloColor, 'circle-stroke-color': editActiveColor }
+})
+
+const midpointActive = (editMidpointColor, midpointRadius) => ({
+  id: 'midpoint-active',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'midpoint'], ['==', 'active', 'true']],
+  paint: { 'circle-radius': midpointRadius, 'circle-color': editMidpointColor }
+})
+
+const circle = (editStrokeColor) => ({
+  id: 'circle',
+  type: 'line',
+  filter: ['==', 'id', 'circle'],
+  paint: { 'line-color': editStrokeColor, 'line-width': 2, 'line-opacity': 0.8 }
+})
+
+const touchVertexIndicator = () => ({
+  id: 'touch-vertex-indicator',
+  type: 'circle',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'touch-vertex-indicator']],
+  paint: { 'circle-radius': 30, 'circle-color': '#3bb2d0', 'circle-stroke-width': 3, 'circle-stroke-color': '#ffffff', 'circle-opacity': 0.9 }
+})
+
+// `pluginConfig` lets callers override any of these colours/strokeWidth — see
+// resolveColors() and the draw plugin's own options docs. Unaffected keys
+// still resolve to the built-in COLORS/SIZES defaults.
+const createDrawStyles = (mapStyle, pluginConfig = {}) => {
+  const colors = resolveColors(mapStyle, pluginConfig)
+  const { vertexRadius, midpointRadius, vertexHaloRadius, midpointHaloRadius } = SIZES
+
+  return [
+    fillInactive(mapStyle, colors),
+    fillActive(colors.editFill),
+    strokeActive(colors.editStroke),
+    strokeActiveInvalid(colors.invalidStroke),
+    strokeInactive(mapStyle, colors),
+    drawInvalidSplitter(colors.splitInvalid),
+    drawValidSplitter(colors.splitValid),
+    drawPreviewLine(colors.editStroke),
+    midpoint(colors.editMidpoint, midpointRadius),
+    midpointHalo(colors.editHalo, colors.editActive, midpointHaloRadius),
+    midpointActive(colors.editMidpoint, midpointRadius),
+    vertex(colors.editVertex, vertexRadius),
+    vertexHalo(colors.editHalo, colors.editActive, vertexHaloRadius),
+    vertexActive(colors.editVertex, vertexRadius),
+    circle(colors.editStroke),
+    touchVertexIndicator()
+  ]
+}
+
+/**
+ * Helper to iterate over a MapLibre map and apply new paint properties
+ */
+const updateDrawStyles = (map, mapStyle, pluginConfig = {}) => {
+  const layers = createDrawStyles(mapStyle, pluginConfig)
+  layers.forEach(layer => {
+    Object.entries(layer.paint).forEach(([prop, value]) => {
+      if (map.getLayer(`${layer.id}.cold`)) {
+        map.setPaintProperty(`${layer.id}.cold`, prop, value)
+      }
+      if (map.getLayer(`${layer.id}.hot`)) {
+        map.setPaintProperty(`${layer.id}.hot`, prop, value)
+      }
+    })
+  })
+}
+
+export {
+  createDrawStyles,
+  updateDrawStyles
+}

package/plugins/draw/src/adapters/maplibre/styles.test.js

@@ -0,0 +1,155 @@
+import { createDrawStyles, updateDrawStyles } from './styles.js'
+import { COLORS, SIZES } from './defaults.js'
+import { getValueForStyle } from '../../utils/getValueForStyle.js'
+
+const findLayer = (layers, id) => layers.find((l) => l.id === id)
+
+describe('createDrawStyles', () => {
+  const mapStyle = { id: 'outdoor', mapColorScheme: 'light' }
+
+  test('returns every draw layer in order', () => {
+    const layers = createDrawStyles(mapStyle)
+    expect(layers.map((l) => l.id)).toEqual([
+      'fill-inactive', 'fill-active', 'stroke-active', 'stroke-active-invalid', 'stroke-inactive',
+      'stroke-invalid-splitter', 'stroke-valid-splitter', 'stroke-preview-line',
+      'midpoint', 'midpoint-halo', 'midpoint-active',
+      'vertex', 'vertex-halo', 'vertex-active', 'circle', 'touch-vertex-indicator'
+    ])
+  })
+
+  test('the invalid stroke layer is a hidden dashed line matching the active shape', () => {
+    const layers = createDrawStyles(mapStyle)
+    const invalid = findLayer(layers, 'stroke-active-invalid')
+    expect(invalid.layout.visibility).toBe('none') // hidden until the shape is invalid
+    expect(invalid.paint['line-dasharray']).toEqual([0.2, 2])
+    expect(invalid.paint['line-color']).toBe(getValueForStyle(COLORS.invalidStroke, 'light'))
+    expect(invalid.filter).toEqual(findLayer(layers, 'stroke-active').filter)
+  })
+
+  test('resolves light-scheme colours', () => {
+    const layers = createDrawStyles({ id: 'outdoor', mapColorScheme: 'light' })
+    expect(findLayer(layers, 'stroke-active').paint['line-color']).toBe(getValueForStyle(COLORS.editStroke, 'light'))
+    expect(findLayer(layers, 'fill-active').paint['fill-color']).toBe(getValueForStyle(COLORS.editFill, 'light'))
+    expect(findLayer(layers, 'vertex').paint['circle-color']).toBe(getValueForStyle(COLORS.editVertex, 'light'))
+    expect(findLayer(layers, 'midpoint').paint['circle-color']).toBe(getValueForStyle(COLORS.editMidpoint, 'light'))
+  })
+
+  test('resolves dark-scheme colours', () => {
+    const layers = createDrawStyles({ id: 'night', mapColorScheme: 'dark' })
+    expect(findLayer(layers, 'stroke-active').paint['line-color']).toBe(getValueForStyle(COLORS.editStroke, 'dark'))
+    expect(findLayer(layers, 'vertex-halo').paint['circle-color']).toBe(getValueForStyle(COLORS.editHalo, 'dark'))
+    expect(findLayer(layers, 'vertex-halo').paint['circle-stroke-color']).toBe(getValueForStyle(COLORS.editActive, 'dark'))
+  })
+
+  test('defaults to the light scheme when none is provided', () => {
+    const layers = createDrawStyles({ id: 'outdoor' })
+    expect(findLayer(layers, 'stroke-active').paint['line-color']).toBe(getValueForStyle(COLORS.editStroke, 'light'))
+  })
+
+  test('applies the configured sizes', () => {
+    const layers = createDrawStyles(mapStyle)
+    expect(findLayer(layers, 'vertex').paint['circle-radius']).toBe(SIZES.vertexRadius)
+    expect(findLayer(layers, 'vertex-halo').paint['circle-radius']).toBe(SIZES.vertexHaloRadius)
+    expect(findLayer(layers, 'midpoint').paint['circle-radius']).toBe(SIZES.midpointRadius)
+    expect(findLayer(layers, 'midpoint-halo').paint['circle-radius']).toBe(SIZES.midpointHaloRadius)
+    expect(findLayer(layers, 'stroke-inactive').paint['line-width']).toBe(SIZES.strokeWidth)
+  })
+
+  test('builds per-style user-property coalesce expressions for inactive fill and stroke', () => {
+    const layers = createDrawStyles({ id: 'outdoor', mapColorScheme: 'light' })
+
+    expect(findLayer(layers, 'fill-inactive').paint['fill-color']).toEqual([
+      'coalesce',
+      ['get', 'user_fillOutdoor'],
+      ['get', 'user_fill'],
+      COLORS.shapeFill
+    ])
+    expect(findLayer(layers, 'stroke-inactive').paint['line-color']).toEqual([
+      'coalesce',
+      ['get', 'user_strokeOutdoor'],
+      ['get', 'user_stroke'],
+      COLORS.shapeStroke
+    ])
+  })
+
+  test('capitalises the style id in the user-property key', () => {
+    const layers = createDrawStyles({ id: 'satellite', mapColorScheme: 'light' })
+    expect(findLayer(layers, 'fill-inactive').paint['fill-color'][1]).toEqual(['get', 'user_fillSatellite'])
+  })
+
+  test('colours the splitter and touch-indicator layers', () => {
+    const layers = createDrawStyles(mapStyle)
+    expect(findLayer(layers, 'stroke-invalid-splitter').paint['line-color']).toBe(getValueForStyle(COLORS.splitInvalid, 'light'))
+    expect(findLayer(layers, 'stroke-valid-splitter').paint['line-color']).toBe(getValueForStyle(COLORS.splitValid, 'light'))
+    expect(findLayer(layers, 'touch-vertex-indicator').paint['circle-color']).toBe('#3bb2d0')
+  })
+
+  test('a pluginConfig override replaces the default colour/width everywhere it applies', () => {
+    const pluginConfig = { editStroke: '#custom-stroke', shapeStroke: '#custom-shape', strokeWidth: 9 }
+    const layers = createDrawStyles(mapStyle, pluginConfig)
+
+    expect(findLayer(layers, 'stroke-active').paint['line-color']).toBe('#custom-stroke')
+    expect(findLayer(layers, 'stroke-preview-line').paint['line-color']).toBe('#custom-stroke')
+    expect(findLayer(layers, 'circle').paint['line-color']).toBe('#custom-stroke')
+    expect(findLayer(layers, 'stroke-inactive').paint['line-color']).toEqual([
+      'coalesce',
+      ['get', 'user_strokeOutdoor'],
+      ['get', 'user_stroke'],
+      '#custom-shape'
+    ])
+    expect(findLayer(layers, 'stroke-inactive').paint['line-width']).toBe(9)
+  })
+
+  test('a per-feature stroke/fill property still wins over a pluginConfig override — coalesce checks it first', () => {
+    const layers = createDrawStyles(mapStyle, { shapeStroke: '#custom-shape' })
+    const [, userStyleKey, userKey, fallback] = findLayer(layers, 'stroke-inactive').paint['line-color']
+    expect(userStyleKey).toEqual(['get', 'user_strokeOutdoor'])
+    expect(userKey).toEqual(['get', 'user_stroke'])
+    expect(fallback).toBe('#custom-shape') // only reached when the feature sets neither
+  })
+})
+
+describe('updateDrawStyles', () => {
+  const mapStyle = { id: 'outdoor', mapColorScheme: 'light' }
+
+  test('applies paint properties to both the cold and hot copies of each layer', () => {
+    const map = { getLayer: jest.fn(() => true), setPaintProperty: jest.fn() }
+
+    updateDrawStyles(map, mapStyle)
+
+    expect(map.setPaintProperty).toHaveBeenCalledWith('fill-inactive.cold', 'fill-color', expect.anything())
+    expect(map.setPaintProperty).toHaveBeenCalledWith('fill-inactive.hot', 'fill-color', expect.anything())
+    expect(map.setPaintProperty).toHaveBeenCalledWith('vertex.cold', 'circle-radius', SIZES.vertexRadius)
+    expect(map.setPaintProperty).toHaveBeenCalledWith('vertex.hot', 'circle-color', expect.anything())
+  })
+
+  test('skips layers that are not present on the map', () => {
+    const map = { getLayer: jest.fn(() => false), setPaintProperty: jest.fn() }
+
+    updateDrawStyles(map, mapStyle)
+
+    expect(map.setPaintProperty).not.toHaveBeenCalled()
+  })
+
+  test('updates only the cold layer when the hot copy is absent', () => {
+    const map = {
+      getLayer: jest.fn((id) => id.endsWith('.cold')),
+      setPaintProperty: jest.fn()
+    }
+
+    updateDrawStyles(map, mapStyle)
+
+    const targets = map.setPaintProperty.mock.calls.map(([id]) => id)
+    expect(targets.length).toBeGreaterThan(0)
+    expect(targets.every((id) => id.endsWith('.cold'))).toBe(true)
+    expect(targets.some((id) => id.endsWith('.hot'))).toBe(false)
+  })
+
+  test('applies a pluginConfig override on the re-styled layers', () => {
+    const map = { getLayer: jest.fn(() => true), setPaintProperty: jest.fn() }
+
+    updateDrawStyles(map, mapStyle, { editStroke: '#custom' })
+
+    expect(map.setPaintProperty).toHaveBeenCalledWith('stroke-active.cold', 'line-color', '#custom')
+  })
+})

package/plugins/draw/src/adapters/maplibre/utils/snapHelpers.js

@@ -0,0 +1,202 @@
+/**
+ * Snap helper utilities for draw modes
+ * Provides a consistent interface for snap detection and coordinate retrieval
+ */
+
+import { TOLERANCES } from '../../../defaults.js'
+
+/**
+ * Get the snap instance from the map
+ * @param {maplibregl.Map} map - Map instance
+ * @returns {MapboxSnap|null} Snap instance or null
+ */
+export function getSnapInstance (map) {
+  return map?._snapInstance ?? null
+}
+
+/**
+ * Check if snapping is currently active
+ * @param {MapboxSnap} snap - Snap instance
+ * @returns {boolean} True if snap is active with valid coordinates
+ */
+export function isSnapActive (snap) {
+  // Also check snap.status to ensure snap feature is enabled
+  return !!(snap?.status && snap?.snapStatus && snap.snapCoords?.length >= 2)
+}
+
+/**
+ * Get snapped coordinates as lngLat object
+ * @param {MapboxSnap} snap - Snap instance
+ * @returns {{ lng: number, lat: number }|null} Snapped coordinates or null
+ */
+export function getSnapLngLat (snap) {
+  if (!isSnapActive(snap)) {
+    return null
+  }
+  return {
+    lng: snap.snapCoords[0],
+    lat: snap.snapCoords[1]
+  }
+}
+
+/**
+ * Get snapped coordinates as array [lng, lat]
+ * @param {MapboxSnap} snap - Snap instance
+ * @returns {[number, number]|null} Snapped coordinates or null
+ */
+export function getSnapCoords (snap) {
+  if (!isSnapActive(snap)) {
+    return null
+  }
+  return [snap.snapCoords[0], snap.snapCoords[1]]
+}
+
+/**
+ * Trigger snap detection at a given point
+ * @param {MapboxSnap} snap - Snap instance
+ * @param {maplibregl.Map} map - Map instance
+ * @param {{ x: number, y: number }} point - Screen point
+ * @returns {boolean} True if snap was triggered
+ */
+export function triggerSnapAtPoint (snap, map, point) {
+  if (!snap || !map || !snap.status) {
+    return false
+  }
+
+  const lngLat = map.unproject(point)
+  snap.snapToClosestPoint({ point, lngLat })
+  return true
+}
+
+/**
+ * Trigger snap detection at map center (for touch/keyboard modes)
+ * @param {MapboxSnap} snap - Snap instance
+ * @param {maplibregl.Map} map - Map instance
+ * @returns {boolean} True if snap was triggered
+ */
+export function triggerSnapAtCenter (snap, map) {
+  // Don't trigger snap if library is disabled
+  if (!snap || !map || !snap.status) {
+    return false
+  }
+
+  const center = map.getCenter()
+  const point = map.project(center)
+  snap.snapToClosestPoint({ point, lngLat: center })
+  return true
+}
+
+/**
+ * Clear the snap indicator circle and all internal snap state
+ * @param {MapboxSnap} snap - Snap instance
+ * @param {maplibregl.Map} [map] - Optional map instance for direct layer control
+ */
+export function clearSnapIndicator (snap, map) {
+  if (snap) {
+    snap.snapStatus = false
+    snap.snapCoords = null
+    // Clear arrays in place (avoids creating new objects, reduces GC pressure)
+    if (snap.snappedFeatures?.length) {
+      snap.snappedFeatures.length = 0
+    }
+    if (snap.closeFeatures?.length) {
+      snap.closeFeatures.length = 0
+    }
+    if (snap.lines?.length) {
+      snap.lines.length = 0
+    }
+    // Note: Avoid calling setMapData here - it's expensive in Safari
+  }
+
+  // Just hide the layer - much cheaper than setData() in Safari
+  if (map?.getLayer('snap-helper-circle')) {
+    map.setLayoutProperty('snap-helper-circle', 'visibility', 'none')
+  }
+}
+
+/**
+ * Clear all snap state (for use between drag operations)
+ * @param {MapboxSnap} snap - Snap instance
+ */
+export function clearSnapState (snap) {
+  if (!snap) {
+    return
+  }
+  snap.snapStatus = false
+  snap.snapCoords = null
+  // Clear arrays in place (avoids creating new objects, reduces GC pressure)
+  if (snap.snappedFeatures?.length) {
+    snap.snappedFeatures.length = 0
+  }
+  if (snap.closeFeatures?.length) {
+    snap.closeFeatures.length = 0
+  }
+  if (snap.lines?.length) {
+    snap.lines.length = 0
+  }
+}
+
+/**
+ * Get snap radius in pixels
+ * @param {MapboxSnap} snap - Snap instance
+ * @returns {number} Snap radius in pixels (falls back to the configured default)
+ */
+export function getSnapRadius (snap) {
+  return snap?.options?.radius ?? TOLERANCES.snapRadius
+}
+
+/**
+ * Check if snapping is enabled for a given state
+ * @param {object} state - Mode state with optional getSnapEnabled function
+ * @returns {boolean} True if snapping is enabled
+ */
+export function isSnapEnabled (state) {
+  // Only return true if getSnapEnabled exists and explicitly returns true
+  if (typeof state?.getSnapEnabled !== 'function') {
+    return false
+  }
+  return state.getSnapEnabled() === true
+}
+
+/**
+ * Create a synthetic map event with snapped coordinates
+ * @param {object} e - Original event
+ * @param {MapboxSnap} snap - Snap instance
+ * @returns {object} Event with snapped lngLat or original event
+ */
+export function createSnappedEvent (e, snap) {
+  const lngLat = getSnapLngLat(snap)
+  if (!lngLat) {
+    return e
+  }
+
+  return {
+    ...e,
+    lngLat
+  }
+}
+
+/**
+ * Create a synthetic click event at snapped coordinates
+ * @param {maplibregl.Map} map - Map instance
+ * @param {MapboxSnap} snap - Snap instance
+ * @returns {object|null} Synthetic event or null if no snap
+ */
+export function createSnappedClickEvent (map, snap) {
+  const lngLat = getSnapLngLat(snap)
+  if (!lngLat) {
+    return null
+  }
+
+  const point = map.project([lngLat.lng, lngLat.lat])
+  return {
+    lngLat,
+    point,
+    originalEvent: new MouseEvent('click', {
+      clientX: point.x,
+      clientY: point.y,
+      bubbles: true,
+      cancelable: true
+    })
+  }
+}