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

package/plugins/draw/src/adapterEvents.js

@@ -0,0 +1,127 @@
+/**
+ * What stage of the draw/edit lifecycle a geometry validation call is running at.
+ * Passed as `context.phase` through validateGeometry (validation/validateGeometry.js)
+ * to the default rules (validation/rules.js) and the user's `onGeometryChange` callback.
+ *
+ * @typedef {'preview' | 'place' | 'create' | 'edit-start' |
+ *   'commit-add' | 'commit-move' | 'commit-insert' | 'commit-delete'} GeometryChangePhase
+ *
+ *   'preview'       - live, in-progress feedback (drag / rubber-band); nothing
+ *                     has committed yet, and nothing can be vetoed at this stage.
+ *                     While drawing, this single check also drives the
+ *                     Add-point button (see liveDrawChecks.js) — it isn't only
+ *                     a display concern, just never a commit/veto one.
+ *   'place'         - a candidate vertex is genuinely about to be committed
+ *                     (a real click/tap/Add-point press), evaluated once,
+ *                     synchronously; a HARD_RULES failure vetoes it outright
+ *                     and it never appears. Never fires continuously — that's
+ *                     'preview''s job (see above).
+ *   'create'        - a whole new feature just finished being drawn.
+ *   'edit-start'    - an existing feature was just loaded into an edit session;
+ *                     nothing has changed yet, this is the baseline check.
+ *   'commit-add'    - a vertex was added while drawing.
+ *   'commit-move'   - a vertex was dragged/nudged while editing.
+ *   'commit-insert' - a vertex was inserted at a midpoint while editing.
+ *   'commit-delete' - a vertex was removed while editing.
+ */
+
+/**
+ * The single event object passed to a user's `onGeometryChange` callback
+ * (validateGeometry.js) — `onGeometryChange({ feature, ...context })`. Not every
+ * field is present on every phase; see each field's own doc below.
+ *
+ * While drawing, every rubber-band mouse-move invokes this callback ONCE,
+ * throttled to one call per animation frame, always with `phase: 'preview'` —
+ * even before any vertex is committed, since a location-based rule can be
+ * meaningful against a single candidate point. Its verdict is combined
+ * (internally, in liveDrawChecks.js) with two independently-floored built-in
+ * checks to drive BOTH the dashed stroke / Done gate AND the Add-point button —
+ * you don't need to do anything to support both; they share this one call. A
+ * separate, genuinely momentary call with `phase: 'place'` (see
+ * GeometryChangePhase) fires only for a real placement attempt, evaluated
+ * synchronously, never continuously. Earlier versions of this plugin called
+ * the callback twice per mouse-move (once per phase, for the same instant) —
+ * that's been unified into the single 'preview' call described here.
+ *
+ * @typedef {object} GeometryChangeEvent
+ * @property {object} feature - GeoJSON feature representing the shape at this
+ *   point. Always present. During 'preview' this is the in-progress feature
+ *   (placed vertices + rubber-band cursor); at every other phase it's the
+ *   committed/candidate feature for that specific change.
+ * @property {GeometryChangePhase} phase - what stage of the draw/edit lifecycle
+ *   this is. Always present.
+ * @property {'draw_polygon' | 'draw_line' | 'edit_vertex'} mode - the active draw
+ *   mode. Always present.
+ * @property {number} [vertexIndex] - index of the vertex being placed, added,
+ *   moved, inserted, or deleted. Present on 'place' and every 'commit-*' phase;
+ *   absent on 'preview', 'create', and 'edit-start' (those have no single vertex
+ *   to point at).
+ * @property {number} [numVertices] - count of already-committed vertices,
+ *   excluding any in-progress rubber-band cursor point. Present on every
+ *   'preview' call, with no minimum — including 0, against the very first
+ *   candidate point, before any vertex is committed. Note this is a lower bar
+ *   than the built-in live rules, which stay skipped until the geometry type's
+ *   minimum vertex count is reached (self-intersection/area are meaningless
+ *   below that).
+ */
+
+/**
+ * Shared adapter event contract.
+ *
+ * Both draw adapters (MaplibreDrawAdapter, OLDrawAdapter) expose an on/off bus
+ * that emits these events. events.js and the api entry points consume them, so
+ * the names and payload shapes below are the contract between the adapters and
+ * the framework-agnostic plugin layer.
+ *
+ * Engine-specific event names stay with their adapter — e.g. the map-level
+ * `draw.*` events mapbox-gl-draw fires live in adapters/maplibre/drawEvents.js,
+ * and the MapLibre adapter normalises them onto this contract.
+ *
+ * Payloads:
+ *   CREATE                 GeoJSON feature that was drawn
+ *   EDIT_FINISH            GeoJSON feature after editing
+ *   CANCEL                 (none)
+ *   VERTEX_SELECTION       { index, numVertices }
+ *   VERTEX_CHANGE          { numVertices }
+ *   UNDO_CHANGE            number — current undo stack length
+ *   UPDATE                 GeoJSON feature after a vertex operation
+ *   GEOMETRY_CHANGE        Two payload shapes share this event:
+ *                            - Preview (draw/split live update): the in-progress
+ *                              feature itself (has `coordinates`, no `phase`).
+ *                            - Commit-level validation: `{ feature, phase, vertexIndex }`
+ *                              where phase ∈ 'commit-add' | 'commit-move' |
+ *                              'commit-insert' | 'commit-delete' (see GeometryChangePhase).
+ *                              events.js validates these and reverts invalid ones.
+ *                          Listeners must guard for the shape they expect.
+ *   INTERFACE_TYPE_CHANGE  { interfaceType: 'mouse' | 'touch' | 'keyboard' }
+ *   PLACEMENT_BLOCKED      { feature, reason, phase: 'place', mode, vertexIndex } —
+ *                          a REAL placement attempt (click/tap/Add-point press)
+ *                          was rejected by validatePlacement (hard rule or user
+ *                          callback), evaluated once, synchronously; feature is
+ *                          the candidate geometry that was refused. Distinct from
+ *                          CAN_PLACE_CHANGE below, which is a continuous forecast
+ *                          of this same outcome, not an attempt.
+ *   VALIDITY_CHANGE        { valid, reason } — the live validity of the displayed
+ *                          shape flipped while editing (drag/nudge in progress).
+ *                          Drives the Done gate in edit mode, where the displayed
+ *                          shape is exactly what Done finishes. Fires on flips only.
+ *   CAN_PLACE_CHANGE       { canPlace, reason } — whether placing a vertex at the
+ *                          crosshair would be vetoed flipped while drawing. Drives
+ *                          the Add-point button. Derived from the same 'preview'
+ *                          check that drives the dashed stroke (liveDrawChecks.js),
+ *                          not a separate attempt — fires on flips only.
+ */
+export const ADAPTER_EVENTS = {
+  CREATE: 'create',
+  EDIT_FINISH: 'editfinish',
+  CANCEL: 'cancel',
+  VERTEX_SELECTION: 'vertexselection',
+  VERTEX_CHANGE: 'vertexchange',
+  UNDO_CHANGE: 'undochange',
+  UPDATE: 'update',
+  GEOMETRY_CHANGE: 'geometrychange',
+  INTERFACE_TYPE_CHANGE: 'interfacetypechange',
+  PLACEMENT_BLOCKED: 'placementblocked',
+  VALIDITY_CHANGE: 'validitychange',
+  CAN_PLACE_CHANGE: 'canplacechange'
+}

package/plugins/draw/src/adapterEvents.test.js

@@ -0,0 +1,20 @@
+import { ADAPTER_EVENTS } from './adapterEvents.js'
+
+describe('adapter event contract', () => {
+  test('event names are stable — renaming a value breaks adapter consumers', () => {
+    expect(ADAPTER_EVENTS).toEqual({
+      CREATE: 'create',
+      EDIT_FINISH: 'editfinish',
+      CANCEL: 'cancel',
+      VERTEX_SELECTION: 'vertexselection',
+      VERTEX_CHANGE: 'vertexchange',
+      UNDO_CHANGE: 'undochange',
+      UPDATE: 'update',
+      GEOMETRY_CHANGE: 'geometrychange',
+      INTERFACE_TYPE_CHANGE: 'interfacetypechange',
+      PLACEMENT_BLOCKED: 'placementblocked',
+      VALIDITY_CHANGE: 'validitychange',
+      CAN_PLACE_CHANGE: 'canplacechange'
+    })
+  })
+})

package/plugins/draw/src/adapters/adapterContract.test.js

@@ -0,0 +1,48 @@
+import { MaplibreDrawAdapter } from './maplibre/MaplibreDrawAdapter.js'
+import { OLDrawAdapter } from './openlayers/OLDrawAdapter.js'
+
+/**
+ * The shared adapter contract: events.js, DrawInit and the api entry points are
+ * written against this surface, so both adapters must implement all of it — even
+ * where an engine needs only a documented no-op (deleteVertex on MapLibre,
+ * setFeatureProperty on OpenLayers). A method added to one adapter but not the
+ * other fails here before it fails at runtime on the other engine.
+ */
+const CONTRACT_METHODS = [
+  'changeMode',
+  'getMode',
+  'setInterfaceType',
+  'done',
+  'cancel',
+  'undo',
+  'deleteVertex',
+  'nudgeSelectedVertex',
+  'get',
+  'add',
+  'delete',
+  'deleteAll',
+  'setSnapEnabled',
+  'setSnapLayers',
+  'isSnapEnabled',
+  'setFeatureProperty',
+  'setGeometryValid',
+  'setInvalid',
+  'on',
+  'off',
+  'remove'
+]
+
+describe.each([
+  ['MaplibreDrawAdapter', MaplibreDrawAdapter],
+  ['OLDrawAdapter', OLDrawAdapter]
+])('%s adapter contract', (name, Adapter) => {
+  test.each(CONTRACT_METHODS)('implements %s()', (method) => {
+    expect(typeof Adapter.prototype[method]).toBe('function')
+  })
+
+  test('exposes the _geometryValidator accessor pair (user callback storage)', () => {
+    const descriptor = Object.getOwnPropertyDescriptor(Adapter.prototype, '_geometryValidator')
+    expect(typeof descriptor?.get).toBe('function')
+    expect(typeof descriptor?.set).toBe('function')
+  })
+})

package/plugins/draw/src/adapters/loadDrawAdapter.js

@@ -0,0 +1,14 @@
+export const loadDrawAdapter = async (mapProvider, options) => {
+  switch (mapProvider.name) {
+    case 'MapLibreProvider': {
+      const { MaplibreDrawAdapter } = await import(/* webpackChunkName: "im-draw-ml-adapter" */ './maplibre/MaplibreDrawAdapter.js')
+      return new MaplibreDrawAdapter(mapProvider, options)
+    }
+    case 'OpenLayersProvider': {
+      const { OLDrawAdapter } = await import(/* webpackChunkName: "im-draw-ol-adapter" */ './openlayers/OLDrawAdapter.js')
+      return new OLDrawAdapter(mapProvider, options)
+    }
+    default:
+      throw new Error(`No draw adapter available for map provider "${mapProvider.name}"`)
+  }
+}

package/plugins/draw/src/adapters/loadDrawAdapter.test.js

@@ -0,0 +1,53 @@
+import { loadDrawAdapter } from './loadDrawAdapter.js'
+import { MaplibreDrawAdapter } from './maplibre/MaplibreDrawAdapter.js'
+import { OLDrawAdapter } from './openlayers/OLDrawAdapter.js'
+
+jest.mock('./maplibre/MaplibreDrawAdapter.js', () => ({
+  MaplibreDrawAdapter: jest.fn(function (mapProvider, options) {
+    this.mapProvider = mapProvider
+    this.options = options
+  })
+}))
+
+jest.mock('./openlayers/OLDrawAdapter.js', () => ({
+  OLDrawAdapter: jest.fn(function (mapProvider, options) {
+    this.mapProvider = mapProvider
+    this.options = options
+  })
+}))
+
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+describe('loadDrawAdapter', () => {
+  test('loads the MapLibre adapter for a MapLibreProvider', async () => {
+    const mapProvider = { name: 'MapLibreProvider' }
+    const options = { mapStyle: 'light' }
+
+    const adapter = await loadDrawAdapter(mapProvider, options)
+
+    expect(MaplibreDrawAdapter).toHaveBeenCalledWith(mapProvider, options)
+    expect(OLDrawAdapter).not.toHaveBeenCalled()
+    expect(adapter).toBeInstanceOf(MaplibreDrawAdapter)
+  })
+
+  test('loads the OpenLayers adapter for an OpenLayersProvider', async () => {
+    const mapProvider = { name: 'OpenLayersProvider' }
+    const options = { mapStyle: 'dark' }
+
+    const adapter = await loadDrawAdapter(mapProvider, options)
+
+    expect(OLDrawAdapter).toHaveBeenCalledWith(mapProvider, options)
+    expect(MaplibreDrawAdapter).not.toHaveBeenCalled()
+    expect(adapter).toBeInstanceOf(OLDrawAdapter)
+  })
+
+  test('throws for an unsupported map provider', async () => {
+    await expect(loadDrawAdapter({ name: 'SomethingElse' }, {}))
+      .rejects.toThrow('No draw adapter available for map provider "SomethingElse"')
+
+    expect(MaplibreDrawAdapter).not.toHaveBeenCalled()
+    expect(OLDrawAdapter).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,367 @@
+import { createMapboxDraw } from './mapboxDraw.js'
+import { getSnapInstance, clearSnapState, clearSnapIndicator } from './utils/snapHelpers.js'
+import { createEventBus } from '../../utils/eventBus.js'
+import { MAPBOX_DRAW_EVENTS, CUSTOM_DRAW_EVENTS, STYLE_DATA_EVENT } from './drawEvents.js'
+import { ADAPTER_EVENTS } from '../../adapterEvents.js'
+import { createLiveStroke } from '../../validation/liveStroke.js'
+import { createLiveDrawChecks } from '../../validation/liveDrawChecks.js'
+
+const polygonFeature = (coordinates) => ({ type: 'Feature', geometry: { type: 'Polygon', coordinates } })
+const lineFeature = (coordinates) => ({ type: 'Feature', geometry: { type: 'LineString', coordinates } })
+
+// The displayed feature + placed-vertex count for the live stroke check. MapLibre's
+// fire() copies the payload onto an Event whose `type` is the event name, so the
+// geometry type is clobbered — it comes from the draw mode, or (in edit, where the
+// mode covers both shapes) from the coordinate nesting: a polygon's coordinates are
+// rings (one level deeper than a line's). Draw-mode coordinates carry a trailing
+// rubber-band point; edit-mode coordinates are all committed vertices.
+export const displayedShape = (mode, coordinates) => {
+  if (mode === 'draw_polygon') {
+    return { feature: polygonFeature(coordinates), numVertices: (coordinates[0]?.length ?? 1) - 1 }
+  }
+  if (mode === 'draw_line') {
+    return { feature: lineFeature(coordinates), numVertices: (coordinates?.length ?? 1) - 1 }
+  }
+  if (mode === 'edit_vertex') {
+    return Array.isArray(coordinates[0]?.[0])
+      ? { feature: polygonFeature(coordinates), numVertices: coordinates[0]?.length ?? 0 }
+      : { feature: lineFeature(coordinates), numVertices: coordinates?.length ?? 0 }
+  }
+  return null
+}
+
+/**
+ * Draw adapter for MapLibre GL.
+ *
+ * Wraps the MapboxDraw instance and normalises its map-event-based API into the
+ * shared adapter interface consumed by events.js, DrawInit, and the api entry points.
+ *
+ * Adapter interface (also implemented by OLDrawAdapter):
+ *   changeMode(name, options)
+ *   getMode()
+ *   setInterfaceType(type)
+ *   done() / cancel() / undo() / deleteVertex()
+ *   nudgeSelectedVertex(dx, dy, isLargeStep)
+ *   get(id) / add(feature) / delete(id) / deleteAll()
+ *   setSnapEnabled(bool) / setSnapLayers(layers) / isSnapEnabled()
+ *   setFeatureProperty(id, property, value) / setDrawingPreviewProperty(property, value)
+ *   on(event, handler) / off(event, handler)
+ *   remove()
+ */
+export class MaplibreDrawAdapter {
+  constructor (mapProvider, options) {
+    this._mapProvider = mapProvider
+    this._map = mapProvider.map
+    this._bus = createEventBus()
+    this._editingFeatureId = null
+
+    const { draw, remove } = createMapboxDraw({
+      mapStyle: options.mapStyle,
+      mapProvider,
+      events: options.events,
+      eventBus: options.eventBus,
+      snapLayers: options.snapLayers,
+      pluginConfig: options.pluginConfig ?? {}
+    })
+
+    this._draw = draw
+    this._cleanupDraw = remove
+
+    // Single owner of the dashed-stroke state: live rubber-band / drag moves feed
+    // update() (default rules sync, user callback throttled) and committed verdicts
+    // (events.js) land via setInvalid → set(), so the cached state always mirrors
+    // the rendered layers. onChange does the actual layer toggle; in edit mode the
+    // displayed shape is exactly what Done finishes, so validity flips also gate
+    // the Done button (events.js dispatches them).
+    this._liveStroke = createLiveStroke({
+      onChange: (invalid, reason) => {
+        this._applyStrokeInvalid(invalid)
+        if (this._draw.getMode() === 'edit_vertex') {
+          this._bus.emit(ADAPTER_EVENTS.VALIDITY_CHANGE, { valid: !invalid, reason })
+        }
+      }
+    })
+
+    // Draw-mode-only: computes both the stroke/Done verdict and the Add-point
+    // verdict from a SINGLE throttled call to the user's callback per rubber-band
+    // move (see liveDrawChecks.js for why), and is flip-guarded itself. The
+    // stroke verdict still routes through _liveStroke.set() — that instance is
+    // also driven independently by edit mode and must stay the single source of
+    // truth for the rendered stroke across mode switches. The Add-point verdict
+    // has no such cross-mode instance to stay in sync with, so it emits directly.
+    this._liveDrawChecks = createLiveDrawChecks({
+      onStrokeChange: (invalid, reason) => this._liveStroke.set(invalid, reason),
+      onPlaceChange: (vetoed, reason) => this._bus.emit(ADAPTER_EVENTS.CAN_PLACE_CHANGE, { canPlace: !vetoed, reason })
+    })
+
+    // Normalise ML map events → the shared adapter event contract (adapterEvents.js).
+    // The OL adapter emits the same contract directly from OLDrawManager.
+    this._mapHandlers = {
+      create: (e) => this._bus.emit(ADAPTER_EVENTS.CREATE, e.features[0]),
+      editfinish: (e) => this._bus.emit(ADAPTER_EVENTS.EDIT_FINISH, e.features[0]),
+      cancel: () => this._bus.emit(ADAPTER_EVENTS.CANCEL),
+      // Normalise typo: the ML modes fire numVertecies, the contract uses numVertices
+      vertexselection: (e) => this._bus.emit(ADAPTER_EVENTS.VERTEX_SELECTION, { ...e, numVertices: e.numVertecies }),
+      vertexchange: (e) => this._bus.emit(ADAPTER_EVENTS.VERTEX_CHANGE, { ...e, numVertices: e.numVertecies }),
+      undochange: (e) => this._bus.emit(ADAPTER_EVENTS.UNDO_CHANGE, e.length),
+      update: (e) => this._bus.emit(ADAPTER_EVENTS.UPDATE, e.features[0]),
+      geometrychange: (e) => {
+        // Phase-less events are rubber-band moves carrying the displayed feature
+        // (placed vertices + cursor) — they drive the live invalid stroke, and are
+        // cached for setDrawingPreviewProperty (the in-progress feature has no
+        // stable id yet — only assigned once drawing actually finishes — so it
+        // can't be targeted via setFeatureProperty).
+        if (!e?.phase) {
+          this._updateLiveStroke(e)
+          this._currentDrawEvent = e
+        }
+        this._bus.emit(ADAPTER_EVENTS.GEOMETRY_CHANGE, e)
+      },
+      placementblocked: (e) => this._bus.emit(ADAPTER_EVENTS.PLACEMENT_BLOCKED, e),
+      interfacetypechange: (e) => this._bus.emit(ADAPTER_EVENTS.INTERFACE_TYPE_CHANGE, { interfaceType: e.interfaceType }),
+      modechange: (e) => this._handleModeChange(e),
+      styledata: () => this._handleStyleData()
+    }
+
+    this._map.on(MAPBOX_DRAW_EVENTS.CREATE, this._mapHandlers.create)
+    this._map.on(CUSTOM_DRAW_EVENTS.EDIT_FINISH, this._mapHandlers.editfinish)
+    this._map.on(CUSTOM_DRAW_EVENTS.CANCEL, this._mapHandlers.cancel)
+    this._map.on(CUSTOM_DRAW_EVENTS.VERTEX_SELECTION, this._mapHandlers.vertexselection)
+    this._map.on(CUSTOM_DRAW_EVENTS.VERTEX_CHANGE, this._mapHandlers.vertexchange)
+    this._map.on(CUSTOM_DRAW_EVENTS.UNDO_CHANGE, this._mapHandlers.undochange)
+    this._map.on(MAPBOX_DRAW_EVENTS.UPDATE, this._mapHandlers.update)
+    this._map.on(CUSTOM_DRAW_EVENTS.GEOMETRY_CHANGE, this._mapHandlers.geometrychange)
+    this._map.on(CUSTOM_DRAW_EVENTS.PLACEMENT_BLOCKED, this._mapHandlers.placementblocked)
+    this._map.on(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, this._mapHandlers.interfacetypechange)
+    this._map.on(MAPBOX_DRAW_EVENTS.MODE_CHANGE, this._mapHandlers.modechange)
+    this._map.on(STYLE_DATA_EVENT, this._mapHandlers.styledata)
+  }
+
+  changeMode (name, options = {}) {
+    if (name === 'edit_vertex') {
+      this._editingFeatureId = options.featureId ?? null
+    }
+    // A fresh draw always starts with a solid stroke and a placeable crosshair;
+    // the live checks own both from here.
+    if (name === 'draw_polygon' || name === 'draw_line') {
+      this._liveStroke.set(false)
+      this._liveDrawChecks.reset()
+    }
+    this._draw.changeMode(name, options)
+    // The underlying mapbox-gl-draw control's public changeMode API is silent by
+    // default (it never fires 'draw.modechange'), so every mode change requested
+    // through this adapter must drive the same cleanup manually.
+    this._handleModeChange({ mode: name })
+  }
+
+  // Live invalid-stroke driver: called on every rubber-band move (draw) and vertex
+  // drag / nudge (edit) with the displayed feature. Edit mode has no Add-point
+  // gate, so it goes straight through the live-stroke controller as before. Draw
+  // mode routes through _liveDrawChecks instead, which computes both the stroke
+  // and Add-point verdicts from one throttled user-callback call (see
+  // liveDrawChecks.js).
+  _updateLiveStroke (e) {
+    if (!e?.coordinates) { return }
+    const mode = this._draw.getMode()
+    const shape = displayedShape(mode, e.coordinates)
+    if (!shape) { return }
+    if (mode === 'draw_polygon' || mode === 'draw_line') {
+      this._liveDrawChecks.update({ feature: shape.feature, numVertices: shape.numVertices, context: { mode }, onGeometryChange: this._geometryValidator })
+    } else {
+      this._liveStroke.update({ ...shape, context: { mode }, onGeometryChange: this._geometryValidator })
+    }
+  }
+
+  getMode () { return this._draw.getMode() }
+
+  setInterfaceType (type) {
+    this._map.fire(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, { interfaceType: type })
+  }
+
+  done () {
+    this._mapProvider.undoStack?.clear()
+    const mode = this._draw.getMode()
+    if (mode === 'edit_vertex' && this._editingFeatureId) {
+      // Leaving edit_vertex here — hide immediately rather than waiting on the
+      // async disable() the EDIT_FINISH handler fires later (see changeMode()).
+      this._handleModeChange({ mode: 'disabled' })
+      this._map.fire(CUSTOM_DRAW_EVENTS.EDIT_FINISH, { features: [this._draw.get(this._editingFeatureId)] })
+      return
+    }
+    if (mode === 'draw_polygon' || mode === 'draw_line') {
+      this._draw.changeMode('disabled')
+      this._handleModeChange({ mode: 'disabled' })
+    }
+  }
+
+  cancel () {
+    this._mapProvider.undoStack?.clear()
+    const mode = this._draw.getMode()
+    // trash() only belongs to an in-progress, never-committed draw — it deletes
+    // whatever's selected. For edit_vertex, events.js's handleCancel has already
+    // restored the original feature via draw.add() before this runs; trash()
+    // here would instead run mapbox-gl-draw's direct_select onTrash on the
+    // mode's own live state (removing the selected vertex, or — if the
+    // in-progress edit happened to leave the shape invalid — deleting the
+    // entire feature), silently discarding the just-restored original.
+    if (mode === 'draw_polygon' || mode === 'draw_line') {
+      this._draw.trash()
+    }
+    this._draw.changeMode('disabled')
+    this._handleModeChange({ mode: 'disabled' })
+  }
+
+  undo () {
+    this._map.fire(CUSTOM_DRAW_EVENTS.UNDO)
+  }
+
+  // MoveControl's D-pad, routed here via mapProvider.activeMoveTarget (see
+  // events.js) once a vertex is selected. Bridged into the running edit mode the
+  // same way setInterfaceType is, since the adapter has no direct reference to the
+  // mode's live state.
+  nudgeSelectedVertex (dx, dy, isLargeStep) {
+    this._map.fire(CUSTOM_DRAW_EVENTS.NUDGE_VERTEX, { dx, dy, isLargeStep })
+  }
+
+  // Record the current geometry validity so the draw mode can block finish gestures
+  // (double-click / click-to-close) while the in-progress shape is invalid.
+  setGeometryValid (valid) {
+    this._map._drawGeometryValid = valid
+  }
+
+  // The api entry points assign the active user validator to the adapter; store it
+  // on the map (like _drawGeometryValid) so modes can veto placements synchronously.
+  set _geometryValidator (fn) { this._map._drawGeometryValidator = fn }
+  get _geometryValidator () { return this._map._drawGeometryValidator }
+
+  // Committed-verdict write (events.js, edit mode): routed through the live-stroke
+  // controller so its cached state stays in sync with the rendered layers.
+  setInvalid (invalid) {
+    this._liveStroke.set(invalid)
+  }
+
+  // Toggle the active shape's stroke between solid (valid) and dashed (invalid) by
+  // swapping which of the two overlaid stroke layers is visible; the fill is hidden
+  // while invalid so the shape reads as an outline only. Only the live-stroke
+  // controller calls this — everything else goes through setInvalid.
+  _applyStrokeInvalid (invalid) {
+    this._setLayerVisibility('stroke-active', !invalid)
+    this._setLayerVisibility('stroke-active-invalid', invalid)
+    this._setLayerVisibility('fill-active', !invalid)
+  }
+
+  _setLayerVisibility (id, visible) {
+    ['hot', 'cold'].forEach((suffix) => {
+      const layerId = `${id}.${suffix}`
+      if (this._map.getLayer(layerId)) {
+        this._map.setLayoutProperty(layerId, 'visibility', visible ? 'visible' : 'none')
+      }
+    })
+  }
+
+  deleteVertex () {
+    // Intentionally a no-op on MapLibre. The shared events layer calls draw.deleteVertex()
+    // from the delete-point button, but the ML edit mode already handles deletion itself:
+    // via the keyboard (Backspace/Delete) and its own window-click listener matching
+    // deleteVertexButtonId (see editVertexMode.onButtonClick). Deleting here too would
+    // double-delete. The OL adapter implements this for real; here it only satisfies the
+    // shared adapter interface.
+  }
+
+  get (id) { return this._draw.get(id) }
+  add (feature) { return this._draw.add(feature) }
+  delete (id) { this._draw.delete(id) }
+  deleteAll () { this._draw.deleteAll() }
+
+  setSnapEnabled (bool) {
+    this._mapProvider.snapEnabled = bool
+    const snap = getSnapInstance(this._map)
+    if (snap?.setSnapStatus) { snap.setSnapStatus(bool) }
+    if (!bool && snap) {
+      clearSnapState(snap)
+      if (this._map.getLayer('snap-helper-circle')) {
+        this._map.setLayoutProperty('snap-helper-circle', 'visibility', 'none')
+      }
+    }
+  }
+
+  setSnapLayers (layers) {
+    const snap = getSnapInstance(this._map)
+    if (snap?.setSnapLayers) {
+      snap.setSnapLayers(layers)
+    } else if (layers) {
+      this._map._pendingSnapLayers = layers
+    } else {
+      // No action
+    }
+  }
+
+  isSnapEnabled () {
+    return this._mapProvider.snapEnabled === true
+  }
+
+  setFeatureProperty (id, property, value) {
+    this._draw.setFeatureProperty(id, property, value)
+  }
+
+  // Tag the feature currently being drawn (rubber-band, not yet created — so it
+  // has no stable id to target via setFeatureProperty) with a property, and
+  // re-render so the change is visible immediately. Used for live preview styling
+  // while drawing, e.g. split's valid/invalid line colour. A no-op once nothing
+  // has been drawn yet this session, or outside draw_polygon/draw_line.
+  setDrawingPreviewProperty (property, value) {
+    const e = this._currentDrawEvent
+    if (e?.properties) {
+      e.properties[property] = value
+    }
+    e?.ctx?.store?.render()
+  }
+
+  on (type, handler) {
+    this._bus.on(type, handler)
+  }
+
+  off (type, handler) {
+    this._bus.off(type, handler)
+  }
+
+  _handleModeChange (e) {
+    const DRAW_MODES = new Set(['draw_polygon', 'draw_line', 'edit_vertex'])
+    if (!DRAW_MODES.has(e.mode)) {
+      clearSnapIndicator(getSnapInstance(this._map), this._map)
+    }
+  }
+
+  // Keeps draw layers on top after MapLibre style reloads
+  _handleStyleData () {
+    // A style reload re-adds the draw layers with their spec-default visibility
+    // (solid stroke shown, dashed hidden) — re-assert the cached stroke state so
+    // an invalid shape stays dashed across the reload.
+    this._liveStroke.refresh()
+    const layers = this._map.getStyle().layers || []
+    if (!layers.length || layers[layers.length - 1].source?.startsWith('mapbox-gl-draw')) {
+      return
+    }
+    layers
+      .filter(l => l.source?.startsWith('mapbox-gl-draw'))
+      .forEach(l => this._map.moveLayer(l.id))
+  }
+
+  remove () {
+    this._map.off(MAPBOX_DRAW_EVENTS.CREATE, this._mapHandlers.create)
+    this._map.off(CUSTOM_DRAW_EVENTS.EDIT_FINISH, this._mapHandlers.editfinish)
+    this._map.off(CUSTOM_DRAW_EVENTS.CANCEL, this._mapHandlers.cancel)
+    this._map.off(CUSTOM_DRAW_EVENTS.VERTEX_SELECTION, this._mapHandlers.vertexselection)
+    this._map.off(CUSTOM_DRAW_EVENTS.VERTEX_CHANGE, this._mapHandlers.vertexchange)
+    this._map.off(CUSTOM_DRAW_EVENTS.UNDO_CHANGE, this._mapHandlers.undochange)
+    this._map.off(MAPBOX_DRAW_EVENTS.UPDATE, this._mapHandlers.update)
+    this._map.off(CUSTOM_DRAW_EVENTS.GEOMETRY_CHANGE, this._mapHandlers.geometrychange)
+    this._map.off(CUSTOM_DRAW_EVENTS.PLACEMENT_BLOCKED, this._mapHandlers.placementblocked)
+    this._map.off(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, this._mapHandlers.interfacetypechange)
+    this._map.off(MAPBOX_DRAW_EVENTS.MODE_CHANGE, this._mapHandlers.modechange)
+    this._map.off(STYLE_DATA_EVENT, this._mapHandlers.styledata)
+    this._liveStroke.destroy()
+    this._liveDrawChecks.destroy()
+    this._cleanupDraw()
+  }
+}