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

package/plugins/draw/src/api/split.js

@@ -0,0 +1,117 @@
+import { splitPolygon } from '../utils/spatial.js'
+import { ADAPTER_EVENTS } from '../adapterEvents.js'
+
+const INVALID_REASON = 'Line does not split the shape into two parts'
+const MIN_LINE_VERTICES = 2
+const SPLITTER_ID = '_splitter'
+
+const computeIsValid = (polygonFeature, feature) => {
+  const coordinates = feature.geometry?.coordinates
+  if (!coordinates || coordinates.length < MIN_LINE_VERTICES) {
+    return false
+  }
+  return !!splitPolygon(polygonFeature, { id: SPLITTER_ID, geometry: feature.geometry })
+}
+
+// Colours the splitter line preview. Uses setDrawingPreviewProperty rather than
+// setFeatureProperty since the line has no stable id until it's created.
+const applySplitPreview = ({ draw, polygonFeature, feature }) => {
+  const isValid = computeIsValid(polygonFeature, feature)
+  draw.setDrawingPreviewProperty('splitter', isValid ? 'valid' : 'invalid')
+  return isValid
+}
+
+// Colours the preview and gates Done/the finish gesture for a committed vertex.
+const applySplitCommit = ({ draw, dispatch, polygonFeature, feature }) => {
+  const isValid = applySplitPreview({ draw, polygonFeature, feature })
+  dispatch({ type: 'SET_ACTION', payload: { name: 'split', isValid } })
+  dispatch({ type: 'SET_GEOMETRY_VALID', payload: isValid })
+  draw.setGeometryValid(isValid)
+  return isValid
+}
+
+// Installed as draw._geometryValidator. 'place' and 'create' are no-ops — a split
+// isn't complete until its last vertex, so checking those would block placement
+// and hijack an early finish into edit mode.
+const createSplitValidator = ({ draw, dispatch, polygonFeature }) => ({ feature, phase }) => {
+  let isValid
+  if (phase === 'preview') {
+    isValid = applySplitPreview({ draw, polygonFeature, feature })
+  } else if (phase?.startsWith('commit-')) {
+    isValid = applySplitCommit({ draw, dispatch, polygonFeature, feature })
+  } else {
+    return { valid: true }
+  }
+  return isValid ? { valid: true } : { valid: false, reason: INVALID_REASON }
+}
+
+/**
+ * Start drawing a split line for a polygon.
+ *
+ * @param {object} context - plugin context
+ * @param {string} featureId - ID of the polygon to split
+ * @param {object} options - Options including snapLayers.
+ */
+export const split = ({ appState, appConfig, pluginState, mapState, mapProvider, services }, featureId, options = {}) => {
+  const { dispatch } = pluginState
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return
+  }
+
+  const polygonFeature = draw.get(featureId)
+
+  // Swap in split's own rule; restored in stopListening.
+  const previousValidator = draw._geometryValidator
+  draw._geometryValidator = createSplitValidator({ draw, dispatch, polygonFeature })
+
+  // Always include the draw outline layer so the split line snaps to it
+  const snapLayers = ['stroke-inactive.cold', ...(options.snapLayers || [])]
+  draw.setSnapLayers(snapLayers)
+  dispatch({ type: 'SET_HAS_SNAP_LAYERS', payload: true })
+
+  draw.changeMode('draw_line', {
+    container: appState.layoutRefs.viewportRef.current,
+    addVertexButtonId: `${appConfig.id}-draw-add-point`,
+    interfaceType: appState.interfaceType,
+    crossHair: mapState?.crossHair,
+    getSnapEnabled: () => draw.isSnapEnabled(),
+    featureId: SPLITTER_ID,
+    properties: { splitter: 'invalid' }
+  })
+
+  // Unregister everything scoped to this session.
+  const stopListening = () => {
+    draw._geometryValidator = previousValidator
+    draw.off(ADAPTER_EVENTS.CREATE, onSplitCreate)
+    draw.off(ADAPTER_EVENTS.CANCEL, onSplitCancel)
+  }
+
+  // Compute split result once the line is finalised. The splitter line only ever
+  // exists to compute this — it must never linger in the draw store afterwards.
+  const onSplitCreate = (geojsonFeature) => {
+    stopListening()
+    draw.delete(SPLITTER_ID)
+    const featureCollection = splitPolygon(polygonFeature, geojsonFeature)
+
+    dispatch({ type: 'SET_ACTION', payload: { name: 'split', isValid: !!featureCollection } })
+
+    if (featureCollection) {
+      eventBus.emit('draw:split', {
+        originalFeatureId: featureId,
+        featureCollection
+      })
+    }
+  }
+
+  // Abandoned (e.g. Escape) — just stop listening.
+  const onSplitCancel = () => { stopListening() }
+
+  draw.on(ADAPTER_EVENTS.CREATE, onSplitCreate)
+  draw.on(ADAPTER_EVENTS.CANCEL, onSplitCancel)
+
+  dispatch({ type: 'SET_MODE', payload: 'draw_line' })
+  dispatch({ type: 'SET_ACTION', payload: { name: 'split' } })
+}

package/plugins/draw/src/api/split.test.js

@@ -0,0 +1,204 @@
+import { split } from './split.js'
+import { splitPolygon } from '../utils/spatial.js'
+
+jest.mock('../utils/spatial.js', () => ({ splitPolygon: jest.fn() }))
+
+const makeContext = (overrides = {}) => {
+  const dispatch = jest.fn()
+  const eventBus = { emit: jest.fn() }
+  const draw = {
+    get: jest.fn(() => ({ id: 'poly' })),
+    setSnapLayers: jest.fn(),
+    changeMode: jest.fn(),
+    on: jest.fn(),
+    off: jest.fn(),
+    isSnapEnabled: jest.fn(() => true),
+    setGeometryValid: jest.fn(),
+    setDrawingPreviewProperty: jest.fn(),
+    delete: jest.fn()
+  }
+  const context = {
+    appState: { layoutRefs: { viewportRef: { current: 'viewport' } }, interfaceType: 'mouse' },
+    appConfig: { id: 'app' },
+    pluginState: { dispatch },
+    mapState: { crossHair: true },
+    mapProvider: { draw },
+    services: { eventBus },
+    ...overrides
+  }
+  return { context, dispatch, draw, eventBus }
+}
+
+const handlerFor = (draw, event) => draw.on.mock.calls.find(([name]) => name === event)?.[1]
+
+const lineFeature = (coordinates) => ({ type: 'Feature', geometry: { type: 'LineString', coordinates } })
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('split', () => {
+  test('does nothing when there is no draw instance', () => {
+    const { context, dispatch } = makeContext({ mapProvider: { draw: null } })
+    expect(() => split(context, 'poly')).not.toThrow()
+    expect(dispatch).not.toHaveBeenCalled()
+  })
+
+  test('sets up the splitter line drawing, installs a validator, and registers listeners', () => {
+    const { context, dispatch, draw } = makeContext()
+
+    split(context, 'poly')
+
+    expect(typeof draw._geometryValidator).toBe('function')
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['stroke-inactive.cold'])
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: true })
+    expect(draw.changeMode).toHaveBeenCalledWith('draw_line', expect.objectContaining({
+      container: 'viewport',
+      addVertexButtonId: 'app-draw-add-point',
+      interfaceType: 'mouse',
+      crossHair: true,
+      featureId: '_splitter',
+      properties: { splitter: 'invalid' }
+    }))
+    expect(draw.on).toHaveBeenCalledWith('create', expect.any(Function))
+    expect(draw.on).toHaveBeenCalledWith('cancel', expect.any(Function))
+    expect(draw.on).not.toHaveBeenCalledWith('geometrychange', expect.anything())
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_MODE', payload: 'draw_line' })
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_ACTION', payload: { name: 'split' } })
+    expect(draw.changeMode.mock.calls[0][1].getSnapEnabled()).toBe(true)
+  })
+
+  test('merges option snapLayers with the outline layer', () => {
+    const { context, draw } = makeContext()
+    split(context, 'poly', { snapLayers: ['extra'] })
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['stroke-inactive.cold', 'extra'])
+  })
+
+  test('finalising the line computes a valid split, emits the result, and restores the previous validator', () => {
+    const { context, dispatch, draw, eventBus } = makeContext()
+    const polygonFeature = { id: 'poly' }
+    const featureCollection = { type: 'FeatureCollection' }
+    const previousValidator = jest.fn()
+    draw._geometryValidator = previousValidator
+    draw.get.mockReturnValue(polygonFeature)
+    splitPolygon.mockReturnValue(featureCollection)
+
+    split(context, 'poly')
+    const onCreate = handlerFor(draw, 'create')
+    const geojson = { id: 'line' }
+    onCreate(geojson)
+
+    expect(draw.off).toHaveBeenCalledWith('create', onCreate)
+    expect(draw.off).toHaveBeenCalledWith('cancel', expect.any(Function))
+    expect(splitPolygon).toHaveBeenCalledWith(polygonFeature, geojson)
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_ACTION', payload: { name: 'split', isValid: true } })
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:split', { originalFeatureId: 'poly', featureCollection })
+    expect(draw._geometryValidator).toBe(previousValidator)
+    // The splitter line only ever existed to compute the split — it must not
+    // linger in the draw store afterwards.
+    expect(draw.delete).toHaveBeenCalledWith('_splitter')
+  })
+
+  test('cancelling the splitter line stops listening and restores the previous validator', () => {
+    const { context, draw } = makeContext()
+    const previousValidator = jest.fn()
+    draw._geometryValidator = previousValidator
+
+    split(context, 'poly')
+    const onCancel = handlerFor(draw, 'cancel')
+    onCancel()
+
+    expect(draw.off).toHaveBeenCalledWith('create', expect.any(Function))
+    expect(draw.off).toHaveBeenCalledWith('cancel', onCancel)
+    expect(splitPolygon).not.toHaveBeenCalled()
+    expect(draw._geometryValidator).toBe(previousValidator)
+  })
+
+  test('finalising the line computes an invalid split and does not emit', () => {
+    const { context, dispatch, draw, eventBus } = makeContext()
+    splitPolygon.mockReturnValue(null)
+
+    split(context, 'poly')
+    handlerFor(draw, 'create')({ id: 'line' })
+
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_ACTION', payload: { name: 'split', isValid: false } })
+    expect(eventBus.emit).not.toHaveBeenCalled()
+    expect(draw.delete).toHaveBeenCalledWith('_splitter')
+  })
+
+  describe('the installed draw._geometryValidator', () => {
+    test('never blocks a hard placement veto (phase: place)', () => {
+      const { context, dispatch, draw } = makeContext()
+      split(context, 'poly')
+      dispatch.mockClear()
+
+      const result = draw._geometryValidator({ feature: lineFeature([[0, 0], [1, 1]]), phase: 'place', mode: 'draw_line', vertexIndex: 1 })
+
+      expect(result).toEqual({ valid: true })
+      expect(splitPolygon).not.toHaveBeenCalled()
+      expect(draw.setDrawingPreviewProperty).not.toHaveBeenCalled()
+      expect(dispatch).not.toHaveBeenCalledWith(expect.objectContaining({ type: 'SET_ACTION' }))
+    })
+
+    test('never blocks the whole-feature finish check (phase: create)', () => {
+      const { context, dispatch, draw } = makeContext()
+      split(context, 'poly')
+      dispatch.mockClear()
+
+      const result = draw._geometryValidator({ feature: lineFeature([[0, 0], [1, 1]]), phase: 'create', mode: 'draw_line' })
+
+      expect(result).toEqual({ valid: true })
+      expect(splitPolygon).not.toHaveBeenCalled()
+      expect(dispatch).not.toHaveBeenCalledWith(expect.objectContaining({ type: 'SET_ACTION' }))
+    })
+
+    test('the live preview (phase: preview) only updates the visual colour, never Done-gating — even with just 1 placed vertex', () => {
+      const { context, dispatch, draw } = makeContext()
+      const polygonFeature = { id: 'poly' }
+      draw.get.mockReturnValue(polygonFeature)
+      splitPolygon.mockReturnValue({ type: 'FeatureCollection' })
+      split(context, 'poly')
+      dispatch.mockClear()
+
+      // 1 placed vertex + the rubber-band cursor. validateDisplayedGeometry only
+      // gates the built-in rules by numVertices, not a caller's own rule, so this
+      // must still reach the validator (numVertices: 1, below MIN_VERTICES.LineString).
+      const feature = lineFeature([[0, 0], [1, 1]])
+      const result = draw._geometryValidator({ feature, phase: 'preview', mode: 'draw_line', numVertices: 1 })
+
+      expect(splitPolygon).toHaveBeenCalledWith(polygonFeature, { id: '_splitter', geometry: feature.geometry })
+      expect(draw.setDrawingPreviewProperty).toHaveBeenCalledWith('splitter', 'valid')
+      // Committed Done-gating (pluginState.geometryValid / map._drawGeometryValid) must only
+      // change on an actual commit — otherwise a live "what if you added a point here" check
+      // could flicker a just-committed valid split back to disabled.
+      expect(dispatch).not.toHaveBeenCalled()
+      expect(draw.setGeometryValid).not.toHaveBeenCalled()
+      expect(result).toEqual({ valid: true })
+    })
+
+    test('a committed vertex (phase: commit-add) updates both the visual colour and Done-gating', () => {
+      const { context, dispatch, draw } = makeContext()
+      splitPolygon.mockReturnValue(null)
+      split(context, 'poly')
+
+      const feature = lineFeature([[0, 0], [1, 1]])
+      const result = draw._geometryValidator({ feature, phase: 'commit-add', mode: 'draw_line', vertexIndex: 1 })
+
+      expect(draw.setDrawingPreviewProperty).toHaveBeenCalledWith('splitter', 'invalid')
+      expect(dispatch).toHaveBeenCalledWith({ type: 'SET_ACTION', payload: { name: 'split', isValid: false } })
+      expect(dispatch).toHaveBeenCalledWith({ type: 'SET_GEOMETRY_VALID', payload: false })
+      expect(draw.setGeometryValid).toHaveBeenCalledWith(false)
+      expect(result).toEqual({ valid: false, reason: expect.any(String) })
+    })
+
+    test('a line with fewer than two coordinates is treated as invalid without calling splitPolygon', () => {
+      const { context, draw } = makeContext()
+      split(context, 'poly')
+
+      const feature = lineFeature([[0, 0]])
+      const result = draw._geometryValidator({ feature, phase: 'preview', mode: 'draw_line', numVertices: 0 })
+
+      expect(splitPolygon).not.toHaveBeenCalled()
+      expect(draw.setDrawingPreviewProperty).toHaveBeenCalledWith('splitter', 'invalid')
+      expect(result).toEqual({ valid: false, reason: expect.any(String) })
+    })
+  })
+})

package/plugins/draw/src/defaults.js

@@ -0,0 +1,52 @@
+const BLUE = 'rgba(29,112,184,1)'
+const WHITE = '#ffffff'
+const BLACK = 'rgba(11,12,12,1)'
+const LIGHT_BLUE = 'rgba(29,112,184,0.1)'
+const LIGHT_WHITE = 'rgba(255,255,255,0.1)'
+const RED = 'rgba(212,53,28,1)'
+const MID_ORANGE = 'rgba(212,53,28,0.5)'
+const MID_BLUE = 'rgba(29,112,184,0.5)'
+const GREEN = 'rgba(40,161,151,1)'
+
+export const COLORS = {
+  editStroke: { light: BLUE, dark: WHITE },
+  editFill: { light: LIGHT_BLUE, dark: LIGHT_WHITE },
+  editVertex: { light: BLUE, dark: WHITE },
+  editMidpoint: { light: BLUE, dark: WHITE },
+  editHalo: { light: WHITE, dark: BLACK },
+  editActive: { light: BLACK, dark: WHITE },
+  splitInvalid: { light: BLUE, dark: WHITE },
+  splitValid: { light: BLUE, dark: WHITE },
+  invalidStroke: { light: BLUE, dark: WHITE },
+  shapeStroke: RED,
+  shapeFill: MID_ORANGE,
+  snapVertex: MID_ORANGE,
+  snapMidpoint: GREEN,
+  snapEdge: MID_BLUE
+}
+
+export const SIZES = {
+  strokeWidth: 2,
+  vertexRadius: 6,
+  midpointRadius: 4,
+  vertexHaloRadius: 8,
+  midpointHaloRadius: 6,
+  touchTargetSize: 48,
+  touchIndicatorRadius: 30
+}
+
+export const TOLERANCES = {
+  snapRadius: 12
+}
+
+export const KEYBOARD = {
+  nudgeAmount: 1,
+  stepAmount: 5
+}
+
+// Scale factor applied to draw UI (touch targets, vertex handles) per app map size
+export const MAP_SIZE_SCALES = {
+  small: 1,
+  medium: 1.5,
+  large: 2
+}

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

@@ -0,0 +1,18 @@
+import { COLORS, SIZES, TOLERANCES, KEYBOARD, MAP_SIZE_SCALES } from './defaults.js'
+
+describe('draw defaults', () => {
+  test('exposes colour variants for the edit palette', () => {
+    expect(COLORS.editStroke).toEqual(expect.objectContaining({ light: expect.any(String), dark: expect.any(String) }))
+    expect(COLORS.shapeStroke).toEqual(expect.any(String))
+  })
+
+  test('exposes numeric sizes and tolerances', () => {
+    expect(SIZES.touchTargetSize).toBe(48)
+    expect(TOLERANCES.snapRadius).toBe(12)
+    expect(KEYBOARD).toEqual({ nudgeAmount: 1, stepAmount: 5 })
+  })
+
+  test('maps app map sizes to scale factors', () => {
+    expect(MAP_SIZE_SCALES).toEqual({ small: 1, medium: 1.5, large: 2 })
+  })
+})

package/plugins/draw/src/draw.scss

@@ -0,0 +1,43 @@
+// Touch vertex target (MapLibre)
+.touch-vertex-target {
+    circle {
+        fill: var(--map-overlay-foreground-color);
+    }
+    path {
+        fill: var(--map-overlay-halo-color);
+    }
+}
+
+// Touch vertex target (OpenLayers)
+.im-draw-touch-target {
+  color: #3b82f6;
+  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.15));
+  cursor: grab;
+
+  &:active {
+    cursor: grabbing;
+  }
+}
+
+// Accessibility: focus visible on buttons
+.im-draw-button:focus-visible {
+  outline: 2px solid #3b82f6;
+  outline-offset: 2px;
+}
+
+// Ensure action buttons take up same width
+.im-c-actions {
+    .im-c-button-wrapper--draw-done,
+    .im-c-button-wrapper--draw-menu,
+    .im-c-button-wrapper--draw-cancel {
+        width: 33.33%;
+    }
+}
+.im-o-app--tablet .im-c-actions,
+.im-o-app--desktop .im-c-actions {
+    .im-c-button-wrapper--draw-done,
+    .im-c-button-wrapper--draw-menu,
+    .im-c-button-wrapper--draw-cancel {
+        width: 100px;
+    }
+}

package/plugins/draw/src/events.js

@@ -0,0 +1,237 @@
+/**
+ * Button and map-event wiring for the draw plugin.
+ *
+ * Uses the normalised adapter interface (draw.on/off, draw.done(), draw.cancel(),
+ * draw.setSnapEnabled(), etc.) so this file is map-framework-agnostic.
+ * All MapLibre / OL specifics live in the adapter.
+ */
+import { ADAPTER_EVENTS } from './adapterEvents.js'
+import { validateGeometry } from './validation/validateGeometry.js'
+import { MIN_VERTICES_REASONS } from './validation/rules.js'
+import { MAP_SIZE_SCALES } from './defaults.js'
+
+const EDIT_VERTEX_MODE = 'edit_vertex'
+const GEOMETRY_INVALID_EVENT = 'draw:geometryinvalid'
+
+// A shape that simply hasn't reached its minimum vertex count yet isn't a mistake —
+// it's the normal, expected state of "still being drawn" — so it's excluded below
+// even though it's a genuine SOFT_RULES failure like any other.
+const isIncompleteShape = (reason) => Object.values(MIN_VERTICES_REASONS).includes(reason)
+
+// A discrete, one-shot invalid result (a rejected placement, a finished-but-invalid
+// shape, or a completed commit that failed validation — never a continuous live-drag
+// flip, which goes via onValidityChange/CAN_PLACE_CHANGE instead) gets a hint toast
+// alongside the existing public event, so the reason is visible without every
+// consumer having to wire up their own listener for it. The public event still
+// fires either way — only the hint is skipped for an incomplete shape.
+const createGeometryInvalidEmitter = (eventBus, hints) => (payload) => {
+  eventBus.emit(GEOMETRY_INVALID_EVENT, payload)
+  if (payload.reason && !isIncompleteShape(payload.reason)) { hints.show(payload.reason) }
+}
+
+// Claims MoveControl's D-pad for the currently selected vertex — see the generic
+// mapProvider.activeMoveTarget contract (MoveControl.jsx). Any plugin could use
+// this slot; the draw plugin is just its first consumer.
+const buildVertexMoveTarget = (draw) => ({
+  move: (dx, dy, isLargeStep) => draw.nudgeSelectedVertex(dx, dy, isLargeStep),
+  label: 'vertex'
+})
+
+// Vertex-selection handlers: sync pluginState.selectedVertexIndex, and claim/release
+// MoveControl's D-pad via buildVertexMoveTarget above.
+const createVertexSelectionHandlers = ({ draw, pluginState, mapProvider, eventBus }) => ({
+  onVertexSelection: (e) => {
+    pluginState.dispatch({ type: 'SET_SELECTED_VERTEX_INDEX', payload: e })
+    mapProvider.activeMoveTarget = e.index >= 0 ? buildVertexMoveTarget(draw) : null
+    eventBus.emit('draw:vertexselection', e)
+  },
+  onVertexChange: (e) => {
+    pluginState.dispatch({ type: 'SET_SELECTED_VERTEX_INDEX', payload: { index: -1, numVertices: e.numVertices } })
+    mapProvider.activeMoveTarget = null
+  }
+})
+
+// Re-open a feature in vertex-edit mode (used when a drawn shape finishes invalid).
+// Mirrors the options built by api/editFeature.js. Edit-mode Done is gated by the
+// same validity, so the shape can't be finished until it's fixed.
+const enterEditVertexMode = ({ draw, appState, appConfig, mapState, dispatch }, featureId) => {
+  draw.changeMode(EDIT_VERTEX_MODE, {
+    container: appState?.layoutRefs?.viewportRef?.current,
+    deleteVertexButtonId: `${appConfig?.id}-draw-delete-point`,
+    undoButtonId: `${appConfig?.id}-draw-undo`,
+    isPanEnabled: appState?.interfaceType !== 'keyboard',
+    interfaceType: appState?.interfaceType,
+    scale: MAP_SIZE_SCALES[mapState?.mapSize],
+    featureId,
+    getSnapEnabled: () => draw.isSnapEnabled()
+  })
+  const editing = draw.get(featureId)
+  dispatch({ type: 'SET_FEATURE', payload: { feature: editing, tempFeature: editing } })
+  dispatch({ type: 'SET_MODE', payload: EDIT_VERTEX_MODE })
+  dispatch({ type: 'SET_GEOMETRY_VALID', payload: false })
+  draw.setGeometryValid?.(false)
+  draw.setInvalid?.(true)
+}
+
+function createHandlers ({ appState, appConfig, mapState, pluginState, mapProvider, eventBus, hints, resetState }) {
+  const { draw } = mapProvider
+  const emitGeometryInvalid = createGeometryInvalidEmitter(eventBus, hints)
+  const { feature, tempFeature } = pluginState
+  const { dispatch } = pluginState
+  // A shape that finished invalid and was re-opened in edit mode: its eventual
+  // edit-finish must report as a creation, not an edit.
+  let pendingCreateId = null
+
+  return {
+    handleDone: () => { draw.done() },
+    handleCancel: () => {
+      const mode = draw.getMode()
+      if (mode === EDIT_VERTEX_MODE && tempFeature?.id) { draw.add(feature) }
+      pendingCreateId = null
+      draw.cancel(); resetState()
+      eventBus.emit('draw:cancelled', feature)
+    },
+    handleUndo: () => draw.undo(),
+    handleDeleteVertex: () => draw.deleteVertex(),
+    handleSnap: () => {
+      pluginState.dispatch({ type: 'TOGGLE_SNAP' })
+      draw.setSnapEnabled(!pluginState.snap)
+    },
+    onCreate: (f) => {
+      // A shape can be finished by the Done button OR a map gesture (double-click,
+      // clicking the first vertex, Enter). Only the button is gated, so re-validate
+      // here to catch the gesture paths — an invalid shape must never be finalised.
+      const { valid, reason } = validateGeometry(f, { phase: 'create', mode: draw.getMode() }, { onGeometryChange: draw._geometryValidator })
+      if (!valid) {
+        pendingCreateId = f.id
+        emitGeometryInvalid({ feature: f, reason, phase: 'create', mode: EDIT_VERTEX_MODE })
+        setTimeout(() => enterEditVertexMode({ draw, appState, appConfig, mapState, dispatch }, f.id), 0)
+        return
+      }
+      resetState(); setTimeout(() => draw.changeMode('disabled'), 0); eventBus.emit('draw:created', f)
+    },
+    onEditFinish: (f) => {
+      resetState()
+      setTimeout(() => draw.changeMode('disabled'), 0)
+      // A shape that was drawn-then-fixed reports as a creation, not an edit.
+      if (pendingCreateId && f.id === pendingCreateId) {
+        pendingCreateId = null
+        eventBus.emit('draw:created', f)
+      } else {
+        eventBus.emit('draw:edited', f)
+      }
+    },
+    onCancel: () => {},
+    ...createVertexSelectionHandlers({ draw, pluginState, mapProvider, eventBus }),
+    onUndoChange: (l) => { pluginState.dispatch({ type: 'SET_UNDO_STACK_LENGTH', payload: l }) },
+    onUpdate: (f) => { eventBus.emit('draw:updated', f) },
+    onGeometryChange: (e) => {
+      // Only commit-level changes (commit-add/move/insert/delete) carry a `phase`.
+      // Preview events (e.g. split's live preview) have none and are ignored.
+      if (!e?.phase) { return }
+
+      const mode = draw.getMode()
+      const context = { phase: e.phase, vertexIndex: e.vertexIndex, mode }
+      const { valid, reason } = validateGeometry(e.feature, context, { onGeometryChange: draw._geometryValidator })
+
+      // Rules only gate the Done button — never revert. A shape can pass through
+      // interim invalid states while being built or reshaped.
+      pluginState.dispatch({ type: 'SET_GEOMETRY_VALID', payload: valid })
+      draw.setGeometryValid?.(valid)
+      // The invalid stroke is committed-validity-driven in edit mode only; in draw
+      // mode the adapters drive it live from the displayed geometry (placed
+      // vertices + cursor) on every rubber-band move.
+      if (mode === EDIT_VERTEX_MODE) {
+        draw.setInvalid?.(!valid)
+      }
+      if (!valid) {
+        emitGeometryInvalid({ reason, ...context, feature: e.feature })
+      }
+    },
+    // A vertex placement was rejected (hard rule or user callback veto). Surface it
+    // on the public bus with phase 'place', and as a hint toast, so the reason is visible.
+    onPlacementBlocked: (e) => {
+      emitGeometryInvalid(e)
+    },
+    // Live (mid-drag) validity flip while editing — the displayed shape is exactly
+    // what Done finishes there, so it gates the Done button in real time. Emitted
+    // by the adapters' edit wiring only, on flips only.
+    onValidityChange: (e) => {
+      pluginState.dispatch({ type: 'SET_GEOMETRY_VALID', payload: e.valid })
+      draw.setGeometryValid?.(e.valid)
+    },
+    // Live placement-veto flip while drawing — gates the Add point button so it
+    // never looks active when a tap would be rejected.
+    onCanPlaceChange: (e) => {
+      pluginState.dispatch({ type: 'SET_CAN_ADD_POINT', payload: e.canPlace })
+    },
+    // The mode's interface type changed (device switch mid-draw, or the final
+    // value on mode exit) — relay so the app can sync appState.interfaceType.
+    onInterfaceTypeChange: (e) => {
+      eventBus.emit('draw:interfacetypechange', { interfaceType: e.interfaceType })
+    }
+  }
+}
+
+function attachButtonHandlers (buttonConfig, handlers) {
+  const { drawDone, drawCancel, drawUndo, drawDeletePoint, drawSnap } = buttonConfig
+  drawDone.onClick = handlers.handleDone
+  drawCancel.onClick = handlers.handleCancel
+  drawUndo.onClick = handlers.handleUndo
+  if (drawDeletePoint) { drawDeletePoint.onClick = handlers.handleDeleteVertex }
+  if (drawSnap) { drawSnap.onClick = handlers.handleSnap }
+}
+
+function attachDrawEvents (draw, handlers) {
+  draw.on(ADAPTER_EVENTS.CREATE, handlers.onCreate)
+  draw.on(ADAPTER_EVENTS.EDIT_FINISH, handlers.onEditFinish)
+  draw.on(ADAPTER_EVENTS.CANCEL, handlers.onCancel)
+  draw.on(ADAPTER_EVENTS.VERTEX_SELECTION, handlers.onVertexSelection)
+  draw.on(ADAPTER_EVENTS.VERTEX_CHANGE, handlers.onVertexChange)
+  draw.on(ADAPTER_EVENTS.UNDO_CHANGE, handlers.onUndoChange)
+  draw.on(ADAPTER_EVENTS.UPDATE, handlers.onUpdate)
+  draw.on(ADAPTER_EVENTS.GEOMETRY_CHANGE, handlers.onGeometryChange)
+  draw.on(ADAPTER_EVENTS.PLACEMENT_BLOCKED, handlers.onPlacementBlocked)
+  draw.on(ADAPTER_EVENTS.VALIDITY_CHANGE, handlers.onValidityChange)
+  draw.on(ADAPTER_EVENTS.CAN_PLACE_CHANGE, handlers.onCanPlaceChange)
+  draw.on(ADAPTER_EVENTS.INTERFACE_TYPE_CHANGE, handlers.onInterfaceTypeChange)
+}
+
+function detachButtonHandlers (buttonConfig) {
+  const { drawDone, drawCancel, drawUndo, drawDeletePoint, drawSnap } = buttonConfig
+  drawDone.onClick = null
+  drawCancel.onClick = null
+  drawUndo.onClick = null
+  if (drawDeletePoint) { drawDeletePoint.onClick = null }
+  if (drawSnap) { drawSnap.onClick = null }
+}
+
+function detachDrawEvents (draw, handlers) {
+  draw.off(ADAPTER_EVENTS.CREATE, handlers.onCreate)
+  draw.off(ADAPTER_EVENTS.EDIT_FINISH, handlers.onEditFinish)
+  draw.off(ADAPTER_EVENTS.CANCEL, handlers.onCancel)
+  draw.off(ADAPTER_EVENTS.VERTEX_SELECTION, handlers.onVertexSelection)
+  draw.off(ADAPTER_EVENTS.VERTEX_CHANGE, handlers.onVertexChange)
+  draw.off(ADAPTER_EVENTS.UNDO_CHANGE, handlers.onUndoChange)
+  draw.off(ADAPTER_EVENTS.UPDATE, handlers.onUpdate)
+  draw.off(ADAPTER_EVENTS.GEOMETRY_CHANGE, handlers.onGeometryChange)
+  draw.off(ADAPTER_EVENTS.PLACEMENT_BLOCKED, handlers.onPlacementBlocked)
+  draw.off(ADAPTER_EVENTS.VALIDITY_CHANGE, handlers.onValidityChange)
+  draw.off(ADAPTER_EVENTS.CAN_PLACE_CHANGE, handlers.onCanPlaceChange)
+  draw.off(ADAPTER_EVENTS.INTERFACE_TYPE_CHANGE, handlers.onInterfaceTypeChange)
+}
+
+export function attachEvents ({ appState, appConfig, mapState, pluginState, mapProvider, buttonConfig, eventBus, hints }) {
+  const { draw } = mapProvider
+  const resetState = () => {
+    pluginState.dispatch({ type: 'SET_MODE', payload: null })
+    pluginState.dispatch({ type: 'SET_FEATURE', payload: { feature: null, tempFeature: null } })
+    // Release MoveControl's D-pad back to panning the map whenever a draw/edit
+    // session ends — a stale claim here would silently hijack it for good.
+    mapProvider.activeMoveTarget = null
+  }
+  const handlers = createHandlers({ appState, appConfig, mapState, pluginState, mapProvider, eventBus, hints, resetState })
+  attachButtonHandlers(buttonConfig, handlers)
+  attachDrawEvents(draw, handlers)
+  return () => { detachButtonHandlers(buttonConfig); detachDrawEvents(draw, handlers) }
+}