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

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

@@ -0,0 +1 @@
+export { COLORS, SIZES, TOLERANCES, KEYBOARD, MAP_SIZE_SCALES } from '../../defaults.js'

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

@@ -0,0 +1,35 @@
+/**
+ * Event names used by the MapLibre draw adapter, grouped by origin.
+ *
+ * - MAPBOX_DRAW_EVENTS: stock events fired by @mapbox/mapbox-gl-draw itself.
+ * - CUSTOM_DRAW_EVENTS: events this codebase's custom modes / adapter dispatch on the map
+ *   (also under the `draw.*` namespace).
+ * - STYLE_DATA_EVENT: the one native MapLibre map event the adapter listens to (to keep draw
+ *   layers on top after a style reload).
+ *
+ * The adapter normalises all of these onto the shared, framework-agnostic event bus.
+ */
+
+// Stock @mapbox/mapbox-gl-draw events, fired by the library itself.
+export const MAPBOX_DRAW_EVENTS = {
+  CREATE: 'draw.create',
+  UPDATE: 'draw.update',
+  MODE_CHANGE: 'draw.modechange'
+}
+
+// Custom draw events dispatched by this codebase's modes / adapter.
+export const CUSTOM_DRAW_EVENTS = {
+  EDIT_FINISH: 'draw.editfinish',
+  CANCEL: 'draw.cancel',
+  VERTEX_SELECTION: 'draw.vertexselection',
+  VERTEX_CHANGE: 'draw.vertexchange',
+  UNDO_CHANGE: 'draw.undochange',
+  UNDO: 'draw.undo',
+  GEOMETRY_CHANGE: 'draw.geometrychange',
+  INTERFACE_TYPE_CHANGE: 'draw.interfacetypechange',
+  PLACEMENT_BLOCKED: 'draw.placementblocked',
+  NUDGE_VERTEX: 'draw.nudgevertex'
+}
+
+// Native MapLibre map event (not a draw event) — fires whenever the map style data changes.
+export const STYLE_DATA_EVENT = 'styledata'

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

@@ -0,0 +1,126 @@
+import MapboxDraw from '@mapbox/mapbox-gl-draw'
+import { DisabledMode } from './modes/disabledMode.js'
+import { EditVertexMode } from './modes/editVertexMode.js'
+import { DrawPolygonMode } from './modes/drawPolygonMode.js'
+import { DrawLineMode } from './modes/drawLineMode.js'
+import { createDrawStyles, updateDrawStyles } from './styles.js'
+import { initMapLibreSnap } from './mapboxSnap.js'
+import { createUndoStack } from '../../utils/undoStack.js'
+import { setupTouchClickWorkaround } from './utils/touchClickWorkaround.js'
+import { applyTouchVertexColors } from './modes/editVertexMode/touchHandlers.js'
+import { resolveColors } from '../../utils/resolveColors.js'
+import { TOLERANCES, MAP_SIZE_SCALES } from './defaults.js'
+
+/**
+ * Creates and manages a MapLibre/Mapbox Draw control instance configured for polygon editing.
+ * Returns an object with a `.remove()` cleanup function that removes all listeners
+ * and safely disposes of the Draw control.
+ *
+ * Features:
+ * - Custom modes for editing and drawing vertices
+ * - Dynamic runtime style updates on `events.MAP_SET_STYLE` event
+ * - Safe reapplication of styles if map.setStyle is called
+ *
+ * @param {string} options.mapStyle - Map style object
+ * @param {Object} options.mapProvider - Object containing the map instance
+ * @param {Object} options.eventBus - Event bus for app-level events
+ * @param {Object} [options.pluginConfig] - Plugin-level colour/size overrides — see resolveColors()
+ * @returns {{ draw: MapboxDraw, remove: Function }} draw instance and cleanup function
+ */
+export const createMapboxDraw = ({ mapStyle, mapProvider, events, eventBus, snapLayers, pluginConfig = {} }) => {
+  const { map } = mapProvider
+
+  // --- Configure MapLibre GL Draw CSS classes ---
+  MapboxDraw.constants.classes.CONTROL_BASE = 'maplibregl-ctrl'
+  MapboxDraw.constants.classes.CONTROL_PREFIX = 'maplibregl-ctrl-'
+  MapboxDraw.constants.classes.CONTROL_GROUP = 'maplibregl-ctrl-group'
+
+  // --- Register custom modes ---
+  const modes = {
+    ...MapboxDraw.modes,
+    disabled: DisabledMode,
+    edit_vertex: EditVertexMode,
+    draw_polygon: DrawPolygonMode,
+    draw_line: DrawLineMode
+  }
+
+  // --- Create or reuse MapLibre Draw instance ---
+  let draw = mapProvider._mapboxDrawInstance
+  if (draw) {
+    // Update modes on existing draw instance when adapter is recreated
+    Object.assign(draw.modes, modes)
+  } else {
+    draw = new MapboxDraw({
+      modes,
+      styles: createDrawStyles(mapStyle, pluginConfig),
+      displayControlsDefault: false,
+      userProperties: true,
+      defaultMode: 'disabled'
+    })
+    map.addControl(draw)
+    mapProvider._mapboxDrawInstance = draw
+  }
+
+  // mapbox-gl-draw swallows tap clicks in disabled mode — synthesize them
+  const touchClickWorkaround = setupTouchClickWorkaround(map, draw)
+
+  // We need a reference to this
+  mapProvider.draw = draw
+  map._drawCurrentMapStyle = mapStyle
+  // Stashed on the map (alongside _drawCurrentMapStyle) so mode code that only
+  // has `this.map` — e.g. touchHandlers.js's addTouchVertexTarget — can still
+  // resolve colour overrides without pluginConfig being threaded through every
+  // mode's option object.
+  map._drawPluginConfig = pluginConfig
+  // Initialize snap as disabled (matches initialState.snap = false)
+  mapProvider.snapEnabled = false
+  // Initialize undo stack (reuse if already exists)
+  let undoStack = mapProvider.undoStack
+  if (!undoStack) {
+    undoStack = createUndoStack((length) => map.fire('draw.undochange', { length }))
+    mapProvider.undoStack = undoStack
+  }
+  map._undoStack = undoStack
+
+  // --- Initialize MapboxSnap using external module ---
+  // Start with status: false to match initial snap disabled state
+  const snapColors = resolveColors(mapStyle, pluginConfig)
+  initMapLibreSnap(map, draw, {
+    layers: snapLayers,
+    radius: pluginConfig.snapRadius ?? TOLERANCES.snapRadius,
+    rules: ['vertex', 'edge'],
+    colors: { vertex: snapColors.snapVertex, edge: snapColors.snapEdge }
+  })
+
+  // --- Update colour scheme ---
+  const handleSetMapStyle = (e) => {
+    map._drawCurrentMapStyle = e
+    map.once('idle', () => {
+      updateDrawStyles(map, e, pluginConfig)
+      const svg = map._drawEditContainer?.querySelector('[data-im-draw-touch-target]')
+      applyTouchVertexColors(svg, e, pluginConfig)
+    })
+  }
+  eventBus.on(events.MAP_SET_STYLE, handleSetMapStyle)
+
+  // --- Update map scale ---
+  const handleSetMapSize = (e) => {
+    map.fire('draw.scalechange', { scale: MAP_SIZE_SCALES[e] })
+  }
+  eventBus.on(events.MAP_SET_SIZE, handleSetMapSize)
+
+  // --- Return instance and cleanup function ---
+  return {
+    draw,
+    remove () {
+      touchClickWorkaround.remove()
+      // Remove event listeners
+      eventBus.off(events.MAP_SET_STYLE, handleSetMapStyle)
+      eventBus.off(events.MAP_SET_SIZE, handleSetMapSize)
+      // Disable draw mode but keep control on map for reuse
+      draw.changeMode('disabled')
+      // Clear adapter reference (but not _mapboxDrawInstance so it persists)
+      mapProvider.draw = null
+    }
+  }
+}

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

@@ -0,0 +1,268 @@
+import MapboxDraw from '@mapbox/mapbox-gl-draw'
+import { createDrawStyles, updateDrawStyles } from './styles.js'
+import { initMapLibreSnap } from './mapboxSnap.js'
+import { createUndoStack } from '../../utils/undoStack.js'
+import { setupTouchClickWorkaround } from './utils/touchClickWorkaround.js'
+import { applyTouchVertexColors } from './modes/editVertexMode/touchHandlers.js'
+import { resolveColors } from '../../utils/resolveColors.js'
+import { TOLERANCES, MAP_SIZE_SCALES } from './defaults.js'
+import { createMapboxDraw } from './mapboxDraw.js'
+
+jest.mock('@mapbox/mapbox-gl-draw', () => {
+  const MockDraw = jest.fn(function () {
+    this.modes = {}
+    this.changeMode = jest.fn()
+  })
+  MockDraw.constants = { classes: {} }
+  MockDraw.modes = { existing_mode: { id: 'existing' } }
+  return { __esModule: true, default: MockDraw }
+})
+
+jest.mock('./modes/disabledMode.js', () => ({ DisabledMode: { id: 'disabled' } }))
+jest.mock('./modes/editVertexMode.js', () => ({ EditVertexMode: { id: 'edit_vertex' } }))
+jest.mock('./modes/drawPolygonMode.js', () => ({ DrawPolygonMode: { id: 'draw_polygon' } }))
+jest.mock('./modes/drawLineMode.js', () => ({ DrawLineMode: { id: 'draw_line' } }))
+jest.mock('./styles.js', () => ({
+  createDrawStyles: jest.fn(() => ['style']),
+  updateDrawStyles: jest.fn()
+}))
+jest.mock('./mapboxSnap.js', () => ({ initMapLibreSnap: jest.fn() }))
+jest.mock('../../utils/undoStack.js', () => ({ createUndoStack: jest.fn(() => ({ id: 'undo-stack' })) }))
+jest.mock('./utils/touchClickWorkaround.js', () => ({ setupTouchClickWorkaround: jest.fn() }))
+jest.mock('./modes/editVertexMode/touchHandlers.js', () => ({ applyTouchVertexColors: jest.fn() }))
+jest.mock('../../utils/resolveColors.js', () => ({
+  resolveColors: jest.fn(() => ({ snapVertex: 'resolved-vertex', snapEdge: 'resolved-edge' }))
+}))
+jest.mock('./defaults.js', () => ({
+  TOLERANCES: { snapRadius: 12 },
+  MAP_SIZE_SCALES: { medium: 1.5 }
+}))
+
+const EVENTS = { MAP_SET_STYLE: 'map:setstyle', MAP_SET_SIZE: 'map:setsize' }
+
+const handlerFor = (mockFn, eventName) =>
+  mockFn.mock.calls.find(([name]) => name === eventName)?.[1]
+
+const createMap = () => ({
+  addControl: jest.fn(),
+  once: jest.fn(),
+  on: jest.fn(),
+  off: jest.fn(),
+  fire: jest.fn()
+})
+
+const setup = ({ existingDraw, existingUndoStack, pluginConfig } = {}) => {
+  const map = createMap()
+  const mapProvider = {
+    map,
+    _mapboxDrawInstance: existingDraw,
+    undoStack: existingUndoStack
+  }
+  const eventBus = { on: jest.fn(), off: jest.fn(), emit: jest.fn() }
+  const removeWorkaround = jest.fn()
+  setupTouchClickWorkaround.mockReturnValue({ remove: removeWorkaround })
+
+  const result = createMapboxDraw({
+    mapStyle: 'light',
+    mapProvider,
+    events: EVENTS,
+    eventBus,
+    snapLayers: ['layer-a'],
+    ...(pluginConfig !== undefined ? { pluginConfig } : {})
+  })
+
+  return { map, mapProvider, eventBus, removeWorkaround, result }
+}
+
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+describe('createMapboxDraw – instance creation', () => {
+  test('configures the MapLibre control CSS class constants', () => {
+    setup()
+    expect(MapboxDraw.constants.classes).toMatchObject({
+      CONTROL_BASE: 'maplibregl-ctrl',
+      CONTROL_PREFIX: 'maplibregl-ctrl-',
+      CONTROL_GROUP: 'maplibregl-ctrl-group'
+    })
+  })
+
+  test('creates a new draw instance with the custom modes and adds it to the map', () => {
+    const { map, mapProvider, result } = setup()
+
+    expect(MapboxDraw).toHaveBeenCalledTimes(1)
+    const options = MapboxDraw.mock.calls[0][0]
+    expect(options).toMatchObject({
+      styles: ['style'],
+      displayControlsDefault: false,
+      userProperties: true,
+      defaultMode: 'disabled'
+    })
+    expect(options.modes).toMatchObject({
+      existing_mode: { id: 'existing' },
+      disabled: { id: 'disabled' },
+      edit_vertex: { id: 'edit_vertex' },
+      draw_polygon: { id: 'draw_polygon' },
+      draw_line: { id: 'draw_line' }
+    })
+    expect(createDrawStyles).toHaveBeenCalledWith('light', {})
+
+    const draw = MapboxDraw.mock.instances[0]
+    expect(map.addControl).toHaveBeenCalledWith(draw)
+    expect(mapProvider._mapboxDrawInstance).toBe(draw)
+    expect(mapProvider.draw).toBe(draw)
+    expect(result.draw).toBe(draw)
+  })
+
+  test('reuses an existing draw instance and merges modes instead of creating a new one', () => {
+    const existingDraw = { modes: { old: {} }, changeMode: jest.fn() }
+    const { map, mapProvider } = setup({ existingDraw })
+
+    expect(MapboxDraw).not.toHaveBeenCalled()
+    expect(map.addControl).not.toHaveBeenCalled()
+    expect(existingDraw.modes).toMatchObject({
+      old: {},
+      disabled: { id: 'disabled' },
+      edit_vertex: { id: 'edit_vertex' }
+    })
+    expect(mapProvider.draw).toBe(existingDraw)
+  })
+})
+
+describe('createMapboxDraw – setup side effects', () => {
+  test('sets up the touch-click workaround and records provider state', () => {
+    const { map, mapProvider } = setup()
+
+    expect(setupTouchClickWorkaround).toHaveBeenCalledWith(map, mapProvider.draw)
+    expect(map._drawCurrentMapStyle).toBe('light')
+    expect(mapProvider.snapEnabled).toBe(false)
+  })
+
+  test('stashes pluginConfig on the map for mode code that only has `this.map`', () => {
+    const pluginConfig = { shapeStroke: '#custom' }
+    const { map } = setup({ pluginConfig })
+
+    expect(map._drawPluginConfig).toBe(pluginConfig)
+  })
+
+  test('defaults pluginConfig to {} when not provided', () => {
+    const { map } = setup()
+
+    expect(map._drawPluginConfig).toEqual({})
+  })
+
+  test('creates an undo stack when none exists and wires it to the map', () => {
+    const { map, mapProvider } = setup()
+
+    expect(createUndoStack).toHaveBeenCalledTimes(1)
+    expect(mapProvider.undoStack).toEqual({ id: 'undo-stack' })
+    expect(map._undoStack).toBe(mapProvider.undoStack)
+
+    // The callback passed to createUndoStack fires a draw.undochange event
+    const undoCallback = createUndoStack.mock.calls[0][0]
+    undoCallback(3)
+    expect(map.fire).toHaveBeenCalledWith('draw.undochange', { length: 3 })
+  })
+
+  test('reuses an existing undo stack', () => {
+    const existingUndoStack = { id: 'existing-stack' }
+    const { map } = setup({ existingUndoStack })
+
+    expect(createUndoStack).not.toHaveBeenCalled()
+    expect(map._undoStack).toBe(existingUndoStack)
+  })
+
+  test('initializes snapping with the default radius, rules, and resolved colours', () => {
+    const { map, mapProvider } = setup()
+
+    expect(initMapLibreSnap).toHaveBeenCalledWith(map, mapProvider.draw, {
+      layers: ['layer-a'],
+      radius: TOLERANCES.snapRadius,
+      rules: ['vertex', 'edge'],
+      colors: { vertex: 'resolved-vertex', edge: 'resolved-edge' }
+    })
+  })
+
+  test('a pluginConfig.snapRadius overrides the default snap radius', () => {
+    const { map, mapProvider } = setup({ pluginConfig: { snapRadius: 20 } })
+
+    expect(initMapLibreSnap).toHaveBeenCalledWith(map, mapProvider.draw, expect.objectContaining({
+      radius: 20
+    }))
+  })
+
+  test('resolves snap colours from mapStyle + pluginConfig', () => {
+    const pluginConfig = { snapVertex: '#custom' }
+    setup({ pluginConfig })
+
+    expect(resolveColors).toHaveBeenCalledWith('light', pluginConfig)
+  })
+})
+
+describe('createMapboxDraw – event handlers', () => {
+  test('MAP_SET_STYLE updates the current style and restyles on idle', () => {
+    const { map, eventBus } = setup()
+
+    const styleHandler = handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)
+    map._drawEditContainer = { querySelector: jest.fn(() => 'svg-el') }
+    styleHandler('dark')
+
+    expect(map._drawCurrentMapStyle).toBe('dark')
+
+    const idleCallback = handlerFor(map.once, 'idle')
+    idleCallback()
+    expect(updateDrawStyles).toHaveBeenCalledWith(map, 'dark', {})
+    expect(map._drawEditContainer.querySelector).toHaveBeenCalledWith('[data-im-draw-touch-target]')
+    expect(applyTouchVertexColors).toHaveBeenCalledWith('svg-el', 'dark', {})
+  })
+
+  test('MAP_SET_STYLE idle handler tolerates a missing edit container', () => {
+    const { map, eventBus } = setup()
+
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(map.once, 'idle')()
+
+    expect(applyTouchVertexColors).toHaveBeenCalledWith(undefined, 'dark', {})
+  })
+
+  test('MAP_SET_STYLE passes pluginConfig through to restyling and touch colours', () => {
+    const pluginConfig = { editStroke: '#custom' }
+    const { map, eventBus } = setup({ pluginConfig })
+
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(map.once, 'idle')()
+
+    expect(updateDrawStyles).toHaveBeenCalledWith(map, 'dark', pluginConfig)
+    expect(applyTouchVertexColors).toHaveBeenCalledWith(undefined, 'dark', pluginConfig)
+  })
+
+  test('draw.interfacetypechange is not handled here — the adapter normalises it onto the bus', () => {
+    const { map } = setup()
+    expect(map.on).not.toHaveBeenCalledWith('draw.interfacetypechange', expect.any(Function))
+  })
+
+  test('MAP_SET_SIZE fires a scale change using the size lookup', () => {
+    const { map, eventBus } = setup()
+
+    handlerFor(eventBus.on, EVENTS.MAP_SET_SIZE)('medium')
+
+    expect(map.fire).toHaveBeenCalledWith('draw.scalechange', { scale: MAP_SIZE_SCALES.medium })
+  })
+})
+
+describe('createMapboxDraw – cleanup', () => {
+  test('remove() detaches listeners, disables draw and clears the adapter reference', () => {
+    const { mapProvider, eventBus, removeWorkaround, result } = setup()
+    const draw = mapProvider.draw
+
+    result.remove()
+
+    expect(removeWorkaround).toHaveBeenCalledTimes(1)
+    expect(eventBus.off).toHaveBeenCalledWith(EVENTS.MAP_SET_STYLE, expect.any(Function))
+    expect(eventBus.off).toHaveBeenCalledWith(EVENTS.MAP_SET_SIZE, expect.any(Function))
+    expect(draw.changeMode).toHaveBeenCalledWith('disabled')
+    expect(mapProvider.draw).toBeNull()
+    expect(mapProvider._mapboxDrawInstance).toBe(draw)
+  })
+})

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

@@ -0,0 +1,39 @@
+import { COLORS, TOLERANCES } from './defaults.js'
+import { applyMapboxSnapPatches } from './snap/prototypePatches.js'
+import { pollUntil } from './snap/sourceData.js'
+import { createSnapInstance } from './snap/snapInstance.js'
+import { registerStyleLoadHandler, registerZoomHandlers } from './snap/mapHandlers.js'
+import { DRAW_HOT_SOURCE } from './snap/constants.js'
+
+/** Initialize MapboxSnap with MapLibre + MapboxDraw */
+export function initMapLibreSnap (map, draw, snapOptions = {}) {
+  // Prevent multiple initializations (causes event listener duplication)
+  if (map._snapInitialized) {
+    return map._snapInstance
+  }
+  map._snapInitialized = true
+
+  const {
+    layers = [],
+    radius = TOLERANCES.snapRadius,
+    rules = ['vertex', 'midpoint', 'edge'],
+    status = false,
+    onSnapped = () => {},
+    colors = {}
+  } = snapOptions
+  const config = { layers, radius, rules, status, onSnapped }
+
+  // Apply global patches to the MapboxSnap prototype
+  applyMapboxSnapPatches({ vertex: COLORS.snapVertex, midpoint: COLORS.snapMidpoint, edge: COLORS.snapEdge, ...colors })
+
+  registerStyleLoadHandler(map, draw, config)
+  registerZoomHandlers(map)
+
+  // Initial setup - poll until the draw source exists
+  pollUntil(
+    () => map._removed ? null : map.getSource(DRAW_HOT_SOURCE),
+    (source) => createSnapInstance(map, draw, source, config)
+  )
+
+  return map._snapInstance
+}

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

@@ -0,0 +1,91 @@
+import { applyMapboxSnapPatches } from './snap/prototypePatches.js'
+import { registerStyleLoadHandler, registerZoomHandlers } from './snap/mapHandlers.js'
+import { createSnapInstance } from './snap/snapInstance.js'
+import { initMapLibreSnap } from './mapboxSnap.js'
+
+const DRAW_SOURCE = 'mapbox-gl-draw-hot'
+
+jest.mock('./snap/prototypePatches.js', () => ({ applyMapboxSnapPatches: jest.fn() }))
+jest.mock('./snap/mapHandlers.js', () => ({
+  registerStyleLoadHandler: jest.fn(),
+  registerZoomHandlers: jest.fn()
+}))
+jest.mock('./snap/snapInstance.js', () => ({
+  createSnapInstance: jest.fn((map) => {
+    map._snapInstance = { id: 'snap' }
+    return map._snapInstance
+  })
+}))
+jest.mock('./snap/sourceData.js', () => ({
+  pollUntil: jest.fn((checkFn, onSuccess) => {
+    const result = checkFn()
+    if (result) {
+      onSuccess(result)
+    }
+  })
+}))
+jest.mock('./defaults.js', () => ({
+  COLORS: { snapVertex: 'v', snapMidpoint: 'm', snapEdge: 'e' },
+  TOLERANCES: { snapRadius: 12 }
+}))
+
+const makeMap = (overrides = {}) => ({
+  getSource: jest.fn(() => ({ id: 'hot' })),
+  ...overrides
+})
+
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+describe('initMapLibreSnap', () => {
+  test('returns the existing instance and skips setup when already initialized', () => {
+    const map = { _snapInitialized: true, _snapInstance: { id: 'existing' } }
+
+    expect(initMapLibreSnap(map, {}, {})).toEqual({ id: 'existing' })
+    expect(applyMapboxSnapPatches).not.toHaveBeenCalled()
+    expect(registerStyleLoadHandler).not.toHaveBeenCalled()
+  })
+
+  test('applies patches, registers handlers and creates the instance', () => {
+    const map = makeMap()
+    const draw = { id: 'draw' }
+
+    const result = initMapLibreSnap(map, draw, { layers: ['a'] })
+
+    expect(applyMapboxSnapPatches).toHaveBeenCalledWith({ vertex: 'v', midpoint: 'm', edge: 'e' })
+    expect(registerStyleLoadHandler).toHaveBeenCalledWith(map, draw, expect.objectContaining({ layers: ['a'], radius: 12 }))
+    expect(registerZoomHandlers).toHaveBeenCalledWith(map)
+    expect(createSnapInstance).toHaveBeenCalledWith(map, draw, { id: 'hot' }, expect.any(Object))
+    expect(map.getSource).toHaveBeenCalledWith(DRAW_SOURCE)
+    expect(result).toEqual({ id: 'snap' })
+  })
+
+  test('merges custom snap colours over the defaults', () => {
+    initMapLibreSnap(makeMap(), {}, { colors: { vertex: 'custom' } })
+    expect(applyMapboxSnapPatches).toHaveBeenCalledWith({ vertex: 'custom', midpoint: 'm', edge: 'e' })
+  })
+
+  test('uses the configured default radius when none is supplied', () => {
+    initMapLibreSnap(makeMap(), {}, {})
+    expect(registerStyleLoadHandler.mock.calls[0][2].radius).toBe(12)
+  })
+
+  test('defaults snapOptions to an empty object when omitted', () => {
+    const map = makeMap()
+    expect(() => initMapLibreSnap(map, {})).not.toThrow()
+    expect(createSnapInstance).toHaveBeenCalled()
+  })
+
+  test('provides a no-op default onSnapped handler', () => {
+    initMapLibreSnap(makeMap(), {}, {})
+    const passedConfig = registerStyleLoadHandler.mock.calls[0][2]
+    expect(passedConfig.onSnapped()).toBeUndefined()
+  })
+
+  test('does not create an instance when the map has already been removed', () => {
+    const map = makeMap({ _removed: true })
+    initMapLibreSnap(map, {}, {})
+    expect(createSnapInstance).not.toHaveBeenCalled()
+  })
+})

package/plugins/draw/src/adapters/maplibre/modes/createDrawMode.js

@@ -0,0 +1,58 @@
+import { createLifecycle } from './drawMode/lifecycle.js'
+import { createClickHandlers } from './drawMode/clickHandlers.js'
+import { createUndoHandlers } from './drawMode/undoHandlers.js'
+import { createKeyboardHandlers } from './drawMode/keyboardHandlers.js'
+import { createPointerHandlers } from './drawMode/pointerHandlers.js'
+import { createRenderHelpers } from './drawMode/renderHelpers.js'
+
+/**
+ * Factory function to create a draw mode for either polygons or lines.
+ * Shared behaviour (event handling, snap detection, undo, rubber band, keyboard
+ * drawing) is split across ./drawMode/* handler modules and composed here.
+ *
+ * @param {Object} ParentMode - DrawPolygon or DrawLineString from mapbox-gl-draw
+ * @param {Object} config - Configuration for the mode
+ * @param {string} config.featureProp - Property name on state ('polygon' or 'line')
+ * @param {string} config.geometryType - 'Polygon' or 'LineString'
+ * @param {Function} config.getCoords - Function to get coordinates from feature
+ * @param {Function} config.validateClick - Validation function for clicks
+ * @param {Function} config.getPlacedCoords - Function to get placed vertex coordinates from a display geojson
+ */
+export const createDrawMode = (ParentMode, config) => {
+  const {
+    featureProp,
+    geometryType,
+    getCoords,
+    validateClick,
+    getPlacedCoords,
+    excludeFeatureIdFromSetup = false,
+    finishOnInvalidClick = false // For lines: finish when clicking same spot (like double-click)
+  } = config
+
+  const deps = {
+    ParentMode,
+    featureProp,
+    geometryType,
+    getCoords,
+    validateClick,
+    getPlacedCoords,
+    excludeFeatureIdFromSetup,
+    finishOnInvalidClick,
+    getFeature: (state) => state[featureProp],
+    // ring is [...placed, last_placed, rubber_band]; splice(-2,1) removes last_placed
+    RUBBER_BAND_OFFSET: 2,
+    // Only these keys signal a switch to keyboard drawing (matches the OL adapter's
+    // drawInput) — modifier keys and shortcut chords like cmd+z must not show the crosshair
+    INTERFACE_KEYS: new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Enter'])
+  }
+
+  return {
+    ...ParentMode,
+    ...createLifecycle(deps),
+    ...createClickHandlers(deps),
+    ...createUndoHandlers(deps),
+    ...createKeyboardHandlers(deps),
+    ...createPointerHandlers(deps),
+    ...createRenderHelpers(deps)
+  }
+}

package/plugins/draw/src/adapters/maplibre/modes/createDrawMode.test.js

@@ -0,0 +1,53 @@
+import { createDrawMode } from './createDrawMode.js'
+
+/**
+ * Tests for the factory's own job: composing ParentMode with every handler group into a
+ * single mode object. The behaviour of each handler group is covered in its colocated
+ * test file under drawMode/ (lifecycle, click, keyboard, undo, pointer, render).
+ */
+
+const POLYGON_CONFIG = {
+  featureProp: 'polygon',
+  geometryType: 'Polygon',
+  getCoords: (f) => f.coordinates[0],
+  validateClick: () => true,
+  getPlacedCoords: () => []
+}
+
+const build = (parent = {}, config = POLYGON_CONFIG) => createDrawMode(parent, config)
+
+describe('createDrawMode composition', () => {
+  test('assembles a mode object with methods from every handler group', () => {
+    const mode = build()
+    const contributed = [
+      'onSetup', 'onStop', // lifecycle
+      'onClick', 'onTap', 'doClick', 'onVertexButtonClick', 'onCreate', // click
+      'pushDrawUndo', 'undoVertex', 'onUndo', // undo
+      'onKeydown', 'onKeyup', 'onKeyUp', // keyboard
+      'onMove', 'onMouseMove', 'onTouchStart', 'onBlur', // pointer
+      'toDisplayFeatures', '_showCrossHair', '_simulateMouse' // render
+    ]
+    for (const method of contributed) {
+      expect(typeof mode[method]).toBe('function')
+    }
+  })
+
+  test('preserves non-overridden ParentMode members and overrides shared ones', () => {
+    const parent = { parentOnly () {}, onClick: 'parent-onclick' }
+    const mode = build(parent)
+    expect(mode.parentOnly).toBe(parent.parentOnly) // passed through
+    expect(typeof mode.onClick).toBe('function') // overridden by the click handlers
+    expect(mode.onClick).not.toBe(parent.onClick)
+  })
+
+  test('passes config through so the getFeature accessor reads the configured feature prop', () => {
+    const polygonMode = build()
+    const lineMode = build({}, { ...POLYGON_CONFIG, featureProp: 'line' })
+    // dispatchVertexChange is config-agnostic, but pushDrawUndo reads getFeature(state).id
+    const map = { _undoStack: { push: jest.fn() }, _undoInProgress: false }
+    polygonMode.pushDrawUndo.call({ map }, { polygon: { id: 'p1' } })
+    lineMode.pushDrawUndo.call({ map }, { line: { id: 'l1' } })
+    expect(map._undoStack.push).toHaveBeenNthCalledWith(1, expect.objectContaining({ featureId: 'p1' }))
+    expect(map._undoStack.push).toHaveBeenNthCalledWith(2, expect.objectContaining({ featureId: 'l1' }))
+  })
+})