@defra/interactive-map 0.0.40-alpha → 0.0.42-alpha

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

@@ -2,10 +2,7 @@
 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.
+// `defaultValue` is the already-resolved fallback (plugin-config override or built-in default), so a shapeStroke/shapeFill override applies to every feature without its own.
 const getUserProp = (mapStyle, prop, defaultValue) => [
   'coalesce',
   ['get', `user_${prop}${mapStyle.id.charAt(0).toUpperCase() + mapStyle.id.slice(1)}`],
@@ -13,11 +10,18 @@ const getUserProp = (mapStyle, prop, defaultValue) => [
   defaultValue
 ]
 
+// Every feature gets an incrementing user_sortKey property when it's created (see
+// MaplibreDrawAdapter.js's _nextSortKey) — later-drawn features paint on top of earlier ones
+// within the same shared layer, instead of the order being incidental to which of mapbox-gl-
+// draw's cold/hot buckets a feature happens to be in.
+const SORT_KEY_PROP = ['get', 'user_sortKey']
+
 // Inactive lines and fills
 const fillInactive = (mapStyle, colors) => ({
   id: 'fill-inactive',
   type: 'fill',
   filter: ['all', ['==', '$type', 'Polygon'], ['==', 'active', 'false']],
+  layout: { 'fill-sort-key': SORT_KEY_PROP },
   paint: { 'fill-color': getUserProp(mapStyle, 'fill', colors.shapeFill) }
 })
 
@@ -25,7 +29,7 @@ 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' },
+  layout: { 'line-cap': 'round', 'line-join': 'round', 'line-sort-key': SORT_KEY_PROP },
   paint: {
     'line-color': getUserProp(mapStyle, 'stroke', colors.shapeStroke),
     'line-width': colors.strokeWidth
@@ -48,9 +52,7 @@ const strokeActive = (editStrokeColor) => ({
   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).
+// Dashed stroke shown in place of stroke-active while invalid — the adapter's setInvalid() toggles the two layers' visibility (line-dasharray can't be data-driven per feature).
 const strokeActiveInvalid = (invalidStrokeColor) => ({
   id: 'stroke-active-invalid',
   type: 'line',
@@ -150,6 +152,32 @@ const circle = (editStrokeColor) => ({
   paint: { 'line-color': editStrokeColor, 'line-width': 2, 'line-opacity': 0.8 }
 })
 
+// A committed point renders its resolved symbol-config icon (pointSymbolImages.js writes user_symbolImageId/user_symbolIconAnchor onto each feature). While a point is being edited (active:'true'), icon-image swaps to its precomputed "selected" variant — the same one the interact plugin's own highlight uses — so the look persists for the whole edit session instead of disappearing when that highlight is cleared on entering edit mode.
+// icon-offset is deliberately NOT a per-feature `get` here — MapLibre's GeoJSON sources
+// silently JSON.stringify array properties, so it would read back a string, not an array.
+// pointSymbolImages.js's registerSymbolIconOffset overwrites this default via
+// setLayoutProperty with a `match` expression once a point needs a non-zero offset.
+const pointSymbol = () => ({
+  id: 'point-symbol',
+  type: 'symbol',
+  filter: ['all', ['==', '$type', 'Point'], ['==', 'meta', 'feature']],
+  layout: {
+    'icon-image': [
+      'case',
+      ['==', ['get', 'active'], 'true'],
+      ['coalesce', ['get', 'user_symbolSelectedImageId'], ['get', 'user_symbolImageId']],
+      ['get', 'user_symbolImageId']
+    ],
+    'icon-anchor': ['get', 'user_symbolIconAnchor'],
+    'icon-offset': ['literal', [0, 0]],
+    'icon-allow-overlap': true,
+    'icon-ignore-placement': true,
+    'symbol-sort-key': SORT_KEY_PROP
+  },
+  // Empty but required — updateDrawStyles() below iterates every layer's paint object unconditionally.
+  paint: {}
+})
+
 const touchVertexIndicator = () => ({
   id: 'touch-vertex-indicator',
   type: 'circle',
@@ -157,9 +185,7 @@ const touchVertexIndicator = () => ({
   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.
+// `pluginConfig` lets callers override any of these colours/strokeWidth (see resolveColors()); unaffected keys fall back to the built-in defaults.
 const createDrawStyles = (mapStyle, pluginConfig = {}) => {
   const colors = resolveColors(mapStyle, pluginConfig)
   const { vertexRadius, midpointRadius, vertexHaloRadius, midpointHaloRadius } = SIZES
@@ -170,6 +196,7 @@ const createDrawStyles = (mapStyle, pluginConfig = {}) => {
     strokeActive(colors.editStroke),
     strokeActiveInvalid(colors.invalidStroke),
     strokeInactive(mapStyle, colors),
+    pointSymbol(),
     drawInvalidSplitter(colors.splitInvalid),
     drawValidSplitter(colors.splitValid),
     drawPreviewLine(colors.editStroke),

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

@@ -11,12 +11,51 @@ describe('createDrawStyles', () => {
     const layers = createDrawStyles(mapStyle)
     expect(layers.map((l) => l.id)).toEqual([
       'fill-inactive', 'fill-active', 'stroke-active', 'stroke-active-invalid', 'stroke-inactive',
+      'point-symbol',
       '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 point-symbol layer is data-driven per feature and only matches real committed point features', () => {
+    const layers = createDrawStyles(mapStyle)
+    const point = findLayer(layers, 'point-symbol')
+    expect(point.filter).toEqual(['all', ['==', '$type', 'Point'], ['==', 'meta', 'feature']])
+    expect(point.layout['icon-anchor']).toEqual(['get', 'user_symbolIconAnchor'])
+    // Static default — pointSymbolImages.js's registerSymbolIconOffset overwrites this via
+    // setLayoutProperty with a match expression once a point needs a non-zero offset (a raw
+    // per-feature `get` here would read back a JSON.stringify'd string, not the real array —
+    // see that function's comment).
+    expect(point.layout['icon-offset']).toEqual(['literal', [0, 0]])
+    expect(point.layout['icon-allow-overlap']).toBe(true)
+  })
+
+  // Drives predictable draw-order stacking within each shared layer (a later-drawn feature
+  // paints above an earlier one) — see MaplibreDrawAdapter.js's _nextSortKey/sortKey property.
+  test('fill/line/symbol layers sort by the per-feature user_sortKey property', () => {
+    const layers = createDrawStyles(mapStyle)
+    expect(findLayer(layers, 'fill-inactive').layout['fill-sort-key']).toEqual(['get', 'user_sortKey'])
+    expect(findLayer(layers, 'stroke-inactive').layout['line-sort-key']).toEqual(['get', 'user_sortKey'])
+    expect(findLayer(layers, 'point-symbol').layout['symbol-sort-key']).toEqual(['get', 'user_sortKey'])
+  })
+
+  // While a point is the one being edited (edit_point mode's toDisplayFeatures sets
+  // active:'true' just for it), icon-image swaps to the same precomputed "selected" (black
+  // ring) variant the interact plugin's own selection highlight already uses — see
+  // pointSymbol()'s own comment — so the look persists for the whole edit session instead of
+  // disappearing when the interact plugin's selection gets cleared on entering edit mode.
+  test('the point-symbol layer swaps to the selected-variant icon while active, falling back to the normal one if no variant was resolved', () => {
+    const layers = createDrawStyles(mapStyle)
+    const point = findLayer(layers, 'point-symbol')
+    expect(point.layout['icon-image']).toEqual([
+      'case',
+      ['==', ['get', 'active'], 'true'],
+      ['coalesce', ['get', 'user_symbolSelectedImageId'], ['get', 'user_symbolImageId']],
+      ['get', 'user_symbolImageId']
+    ])
+  })
+
   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')

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

@@ -0,0 +1,79 @@
+import { CUSTOM_DRAW_EVENTS } from '../drawEvents.js'
+import { getSnapInstance, clearSnapIndicator } from './snapHelpers.js'
+
+// Builds the `handlers` map both modes' setupEventListeners bind to bindEditModeListeners —
+// the base set of window/container/scale/move/interface-type-change handlers is identical
+// in both, bound to whichever mode instance is passed in; `extra` supplies the handlers that
+// differ per mode (nudge, plus edit_vertex's own selectionchange/update).
+export const buildEditModeHandlers = (mode, state, extra = {}) => {
+  const bind = (handler) => (event) => handler.call(mode, state, event)
+  const handlers = {
+    keydown: bind(mode.onKeydown),
+    keyup: bind(mode.onKeyup),
+    pointerdown: bind(mode.onPointerevent),
+    pointermove: bind(mode.onPointerevent),
+    pointerup: bind(mode.onPointerevent),
+    click: bind(mode.onButtonClick),
+    touchstart: bind(mode.onTouchstart),
+    touchmove: bind(mode.onTouchmove),
+    touchend: bind(mode.onTouchend),
+    scalechange: bind(mode.onScaleChange),
+    move: bind(mode.onMove),
+    interfacetypechange: bind(mode.onInterfaceTypeChange)
+  }
+  for (const [name, handler] of Object.entries(extra)) {
+    handlers[name] = bind(handler)
+  }
+  return handlers
+}
+
+// Shared DOM/map event wiring for edit_point and edit_vertex — both modes' setupEventListeners
+// bind the exact same base set of window/container listeners plus scale/move/interface-type-
+// change/nudge map events; edit_vertex additionally wires its own selectionchange/update map
+// events on top of this. Each mode still builds its own `handlers` map (bound to its own onXxx
+// methods) — this just wires/unwires it, keyed on the handler names both modes share (the
+// nudge entry is named `nudge` in both, even though what it does — nudgePointByDelta vs
+// nudgeVertexByDelta — differs per mode).
+export const bindEditModeListeners = (state, map, handlers) => {
+  window.addEventListener('keydown', handlers.keydown, { capture: true })
+  window.addEventListener('keyup', handlers.keyup, { capture: true })
+  window.addEventListener('click', handlers.click)
+  state.container.addEventListener('pointerdown', handlers.pointerdown)
+  state.container.addEventListener('pointermove', handlers.pointermove)
+  state.container.addEventListener('pointerup', handlers.pointerup)
+  state.container.addEventListener('touchstart', handlers.touchstart, { passive: false })
+  state.container.addEventListener('touchmove', handlers.touchmove, { passive: false })
+  state.container.addEventListener('touchend', handlers.touchend, { passive: false })
+  map.on('draw.scalechange', handlers.scalechange)
+  map.on('move', handlers.move)
+  map.on(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, handlers.interfacetypechange)
+  map.on(CUSTOM_DRAW_EVENTS.NUDGE_VERTEX, handlers.nudge)
+}
+
+// Mirrors bindEditModeListeners, plus the dragPan re-enable both modes' onStop does right
+// alongside it (dragPan is disabled for the duration of the edit session elsewhere).
+export const unbindEditModeListeners = (state, map, handlers) => {
+  state.container.removeEventListener('pointerdown', handlers.pointerdown)
+  state.container.removeEventListener('pointermove', handlers.pointermove)
+  state.container.removeEventListener('pointerup', handlers.pointerup)
+  state.container.removeEventListener('touchstart', handlers.touchstart)
+  state.container.removeEventListener('touchmove', handlers.touchmove)
+  state.container.removeEventListener('touchend', handlers.touchend)
+  map.off('draw.scalechange', handlers.scalechange)
+  map.off('move', handlers.move)
+  map.off(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, handlers.interfacetypechange)
+  map.off(CUSTOM_DRAW_EVENTS.NUDGE_VERTEX, handlers.nudge)
+  map.dragPan.enable()
+  window.removeEventListener('click', handlers.click)
+  window.removeEventListener('keydown', handlers.keydown, { capture: true })
+  window.removeEventListener('keyup', handlers.keyup, { capture: true })
+}
+
+// Clear any snap indicator left over from a previous interaction — both edit modes do this
+// once, at onSetup.
+export const clearActiveSnapIndicator = (map) => {
+  const snap = getSnapInstance(map)
+  if (snap) {
+    clearSnapIndicator(snap, map)
+  }
+}

package/plugins/draw/src/adapters/maplibre/utils/editModeEvents.test.js

@@ -0,0 +1,135 @@
+import { bindEditModeListeners, unbindEditModeListeners, clearActiveSnapIndicator, buildEditModeHandlers } from './editModeEvents.js'
+import { CUSTOM_DRAW_EVENTS } from '../drawEvents.js'
+
+const makeHandlers = () => ({
+  keydown: jest.fn(),
+  keyup: jest.fn(),
+  click: jest.fn(),
+  pointerdown: jest.fn(),
+  pointermove: jest.fn(),
+  pointerup: jest.fn(),
+  touchstart: jest.fn(),
+  touchmove: jest.fn(),
+  touchend: jest.fn(),
+  scalechange: jest.fn(),
+  move: jest.fn(),
+  interfacetypechange: jest.fn(),
+  nudge: jest.fn()
+})
+
+const makeMap = () => ({ on: jest.fn(), off: jest.fn(), dragPan: { enable: jest.fn() } })
+
+describe('bindEditModeListeners', () => {
+  test('wires the shared window/container listeners and map events', () => {
+    const state = { container: document.createElement('div') }
+    jest.spyOn(window, 'addEventListener')
+    jest.spyOn(state.container, 'addEventListener')
+    const map = makeMap()
+    const handlers = makeHandlers()
+
+    bindEditModeListeners(state, map, handlers)
+
+    expect(window.addEventListener).toHaveBeenCalledWith('keydown', handlers.keydown, { capture: true })
+    expect(window.addEventListener).toHaveBeenCalledWith('keyup', handlers.keyup, { capture: true })
+    expect(window.addEventListener).toHaveBeenCalledWith('click', handlers.click)
+    expect(state.container.addEventListener).toHaveBeenCalledWith('pointerdown', handlers.pointerdown)
+    expect(state.container.addEventListener).toHaveBeenCalledWith('pointermove', handlers.pointermove)
+    expect(state.container.addEventListener).toHaveBeenCalledWith('pointerup', handlers.pointerup)
+    expect(state.container.addEventListener).toHaveBeenCalledWith('touchstart', handlers.touchstart, { passive: false })
+    expect(state.container.addEventListener).toHaveBeenCalledWith('touchmove', handlers.touchmove, { passive: false })
+    expect(state.container.addEventListener).toHaveBeenCalledWith('touchend', handlers.touchend, { passive: false })
+    expect(map.on).toHaveBeenCalledWith('draw.scalechange', handlers.scalechange)
+    expect(map.on).toHaveBeenCalledWith('move', handlers.move)
+    expect(map.on).toHaveBeenCalledWith(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, handlers.interfacetypechange)
+    expect(map.on).toHaveBeenCalledWith(CUSTOM_DRAW_EVENTS.NUDGE_VERTEX, handlers.nudge)
+
+    window.addEventListener.mockRestore()
+  })
+})
+
+describe('unbindEditModeListeners', () => {
+  test('tears down the shared window/container listeners and map events, and re-enables dragPan', () => {
+    const state = { container: document.createElement('div') }
+    jest.spyOn(window, 'removeEventListener')
+    jest.spyOn(state.container, 'removeEventListener')
+    const map = makeMap()
+    const handlers = makeHandlers()
+
+    unbindEditModeListeners(state, map, handlers)
+
+    expect(state.container.removeEventListener).toHaveBeenCalledWith('pointerdown', handlers.pointerdown)
+    expect(state.container.removeEventListener).toHaveBeenCalledWith('pointermove', handlers.pointermove)
+    expect(state.container.removeEventListener).toHaveBeenCalledWith('pointerup', handlers.pointerup)
+    expect(state.container.removeEventListener).toHaveBeenCalledWith('touchstart', handlers.touchstart)
+    expect(state.container.removeEventListener).toHaveBeenCalledWith('touchmove', handlers.touchmove)
+    expect(state.container.removeEventListener).toHaveBeenCalledWith('touchend', handlers.touchend)
+    expect(map.off).toHaveBeenCalledWith('draw.scalechange', handlers.scalechange)
+    expect(map.off).toHaveBeenCalledWith('move', handlers.move)
+    expect(map.off).toHaveBeenCalledWith(CUSTOM_DRAW_EVENTS.INTERFACE_TYPE_CHANGE, handlers.interfacetypechange)
+    expect(map.off).toHaveBeenCalledWith(CUSTOM_DRAW_EVENTS.NUDGE_VERTEX, handlers.nudge)
+    expect(map.dragPan.enable).toHaveBeenCalled()
+    expect(window.removeEventListener).toHaveBeenCalledWith('click', handlers.click)
+    expect(window.removeEventListener).toHaveBeenCalledWith('keydown', handlers.keydown, { capture: true })
+    expect(window.removeEventListener).toHaveBeenCalledWith('keyup', handlers.keyup, { capture: true })
+
+    window.removeEventListener.mockRestore()
+  })
+})
+
+describe('clearActiveSnapIndicator', () => {
+  test('clears the indicator when a snap instance is present', () => {
+    const snap = { snapStatus: true, snapCoords: [1, 2] }
+    const map = { _snapInstance: snap, getLayer: jest.fn(() => null), setLayoutProperty: jest.fn() }
+
+    clearActiveSnapIndicator(map)
+
+    expect(snap.snapStatus).toBe(false)
+    expect(snap.snapCoords).toBeNull()
+  })
+
+  test('is a no-op without a snap instance', () => {
+    expect(() => clearActiveSnapIndicator({})).not.toThrow()
+  })
+})
+
+describe('buildEditModeHandlers', () => {
+  test('builds the shared base handlers bound to the given mode and state', () => {
+    const mode = {
+      onKeydown: jest.fn(),
+      onKeyup: jest.fn(),
+      onPointerevent: jest.fn(),
+      onButtonClick: jest.fn(),
+      onTouchstart: jest.fn(),
+      onTouchmove: jest.fn(),
+      onTouchend: jest.fn(),
+      onScaleChange: jest.fn(),
+      onMove: jest.fn(),
+      onInterfaceTypeChange: jest.fn()
+    }
+    const state = {}
+    const handlers = buildEditModeHandlers(mode, state)
+
+    expect(Object.keys(handlers).sort()).toEqual([
+      'click', 'interfacetypechange', 'keydown', 'keyup', 'move', 'pointerdown',
+      'pointermove', 'pointerup', 'scalechange', 'touchend', 'touchmove', 'touchstart'
+    ])
+    handlers.keydown('event')
+    handlers.pointerdown('down-event')
+    handlers.pointermove('move-event')
+    expect(mode.onKeydown).toHaveBeenCalledWith(state, 'event')
+    // pointerdown/pointermove/pointerup all route through the single onPointerevent handler
+    expect(mode.onPointerevent).toHaveBeenCalledWith(state, 'down-event')
+    expect(mode.onPointerevent).toHaveBeenCalledWith(state, 'move-event')
+  })
+
+  test('binds extra per-mode handlers (e.g. nudge, selectionchange, update) alongside the base set', () => {
+    const mode = { onNudgeVertex: jest.fn(), onSelectionChange: jest.fn() }
+    const state = {}
+    const handlers = buildEditModeHandlers(mode, state, { nudge: mode.onNudgeVertex, selectionchange: mode.onSelectionChange })
+
+    handlers.nudge('e1')
+    handlers.selectionchange('e2')
+    expect(mode.onNudgeVertex).toHaveBeenCalledWith(state, 'e1')
+    expect(mode.onSelectionChange).toHaveBeenCalledWith(state, 'e2')
+  })
+})

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

@@ -0,0 +1,42 @@
+// Shared by editPointMode/undoHandlers.js and editVertexMode/undoHandlers.js — recording an
+// undo op and feeding it to commit-level validation is identical plumbing for both modes; only
+// the op types themselves differ (a Point only ever moves, a ring vertex can also be inserted
+// or deleted), which each mode still declares locally via its own UNDO_OP_PHASE/
+// UNDO_INVERSE_PHASE maps (read here off `this`, since pushUndo is mixed into both modes).
+export const sharedUndoHandlers = {
+  // Fire geometry change event (for external listeners)
+  fireGeometryChange (state) {
+    const feature = this.getFeature(state.featureId)
+    if (feature) {
+      this.map.fire('draw.update', {
+        features: [feature.toGeoJSON()],
+        action: 'change_coordinates'
+      })
+    }
+  },
+
+  // Emit a commit-level geometrychange (feature + change phase + vertex index) so the
+  // validation layer can accept or reject the change. Deferred a tick to avoid
+  // re-entrancy: rejection calls draw.undo(), which must run after the current
+  // mutation (and its undo bookkeeping) has fully settled.
+  emitGeometryValidation (phase, vertexIndex, featureId) {
+    if (!phase) { return }
+    setTimeout(() => {
+      const feature = this.getFeature(featureId)
+      if (!feature) { return }
+      this.map.fire('draw.geometrychange', { feature: feature.toGeoJSON(), phase, vertexIndex })
+    }, 0)
+  },
+
+  // Undo support
+  pushUndo (operation) {
+    const undoStack = this.map._undoStack
+    if (!undoStack) {
+      return
+    }
+    undoStack.push(operation)
+    // Every edit commit (move/insert/delete, via mouse/touch/keyboard/D-pad) records an undo
+    // op here, so this is the single point that feeds commit-level validation.
+    this.emitGeometryValidation(this.UNDO_OP_PHASE[operation.type], operation.vertexIndex, operation.featureId)
+  }
+}

package/plugins/draw/src/adapters/maplibre/utils/geometryValidation.test.js

@@ -0,0 +1,85 @@
+import { sharedUndoHandlers } from './geometryValidation.js'
+import { createUndoStack } from '../../../utils/undoStack.js'
+
+const makeCtx = (overrides = {}) => ({
+  ...sharedUndoHandlers,
+  UNDO_OP_PHASE: { move: 'commit-move' },
+  map: { fire: jest.fn(), _undoStack: createUndoStack(() => {}) },
+  getFeature: jest.fn((id) => (id === 'missing' ? undefined : { toGeoJSON: () => ({ type: 'Feature', id }) })),
+  ...overrides
+})
+
+describe('fireGeometryChange', () => {
+  test('fires draw.update only when the feature exists', () => {
+    const ctx = makeCtx()
+    ctx.fireGeometryChange({ featureId: 'feat-1' })
+    expect(ctx.map.fire).toHaveBeenCalledWith('draw.update', expect.objectContaining({ action: 'change_coordinates' }))
+
+    ctx.map.fire.mockClear()
+    ctx.fireGeometryChange({ featureId: 'missing' })
+    expect(ctx.map.fire).not.toHaveBeenCalled()
+  })
+})
+
+describe('emitGeometryValidation', () => {
+  test('does nothing without a phase', () => {
+    jest.useFakeTimers()
+    const ctx = makeCtx()
+    ctx.emitGeometryValidation(undefined, 0, 'feat-1')
+    jest.runAllTimers()
+    expect(ctx.map.fire).not.toHaveBeenCalled()
+    jest.useRealTimers()
+  })
+
+  test('fires a deferred draw.geometrychange with the phase, vertexIndex and feature', () => {
+    jest.useFakeTimers()
+    const ctx = makeCtx()
+    ctx.emitGeometryValidation('commit-move', 2, 'feat-1')
+    // Deferred a tick to avoid re-entrancy — nothing fired synchronously.
+    expect(ctx.map.fire).not.toHaveBeenCalled()
+
+    jest.runAllTimers()
+    expect(ctx.map.fire).toHaveBeenCalledWith('draw.geometrychange', expect.objectContaining({
+      phase: 'commit-move',
+      vertexIndex: 2,
+      feature: expect.any(Object)
+    }))
+    jest.useRealTimers()
+  })
+
+  test('does not fire once the feature is gone', () => {
+    jest.useFakeTimers()
+    const ctx = makeCtx()
+    ctx.emitGeometryValidation('commit-move', 0, 'missing')
+    jest.runAllTimers()
+    expect(ctx.map.fire).not.toHaveBeenCalled()
+    jest.useRealTimers()
+  })
+})
+
+describe('pushUndo', () => {
+  test('is a no-op without a stack', () => {
+    const ctx = makeCtx({ map: { fire: jest.fn(), _undoStack: null } })
+    expect(() => ctx.pushUndo({ type: 'move' })).not.toThrow()
+  })
+
+  test('pushes the operation and emits validation for a mapped op type', () => {
+    jest.useFakeTimers()
+    const ctx = makeCtx()
+    ctx.pushUndo({ type: 'move', featureId: 'feat-1', vertexIndex: 0 })
+    expect(ctx.map._undoStack.length).toBe(1)
+
+    jest.runAllTimers()
+    expect(ctx.map.fire).toHaveBeenCalledWith('draw.geometrychange', expect.objectContaining({ phase: 'commit-move' }))
+    jest.useRealTimers()
+  })
+
+  test('does not emit validation for an unmapped op type', () => {
+    jest.useFakeTimers()
+    const ctx = makeCtx()
+    ctx.pushUndo({ type: 'unmapped', featureId: 'feat-1' })
+    jest.runAllTimers()
+    expect(ctx.map.fire).not.toHaveBeenCalled()
+    jest.useRealTimers()
+  })
+})

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

@@ -0,0 +1,34 @@
+// Shared by editPointMode/keyboardHandlers.js and editVertexMode/keyboardHandlers.js — both
+// modes gate their shortcuts on the same "is focus somewhere that should eat the keystroke"
+// and "is this the undo chord" questions, independent of the ring-vs-single-coordinate
+// bookkeeping the rest of each mode's keyboard handling differs on.
+export const ARROW_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'])
+export const ARROW_OFFSETS = { ArrowUp: [0, -1], ArrowDown: [0, 1], ArrowLeft: [-1, 0], ArrowRight: [1, 0] }
+
+const INTERACTIVE_TAGS = new Set(['INPUT', 'TEXTAREA', 'BUTTON', 'SELECT', 'A'])
+
+// Keyboard shortcuts are ignored while a form control outside the map viewport has
+// focus, but still work for elements inside the viewport (e.g. draw toolbar buttons).
+export const isInteractiveElementFocused = (state) => {
+  const el = document.activeElement
+  if (!el || el === document.body) { return false }
+  if (state.container?.contains(el)) { return false }
+  return INTERACTIVE_TAGS.has(el.tagName) || el.isContentEditable || el.hasAttribute('tabindex')
+}
+
+export const isUndoShortcut = (e) => e.key === 'z' && (e.metaKey || e.ctrlKey) && !e.shiftKey
+
+// Mixin method — spread into both modes' keyboardHandlers so `this.handleUndo` resolves to
+// whichever mode it's mixed into.
+export const sharedKeyboardHandlers = {
+  // Cmd/Ctrl+Z: undo the last edit, unless the user is typing in a text field.
+  handleUndoShortcut (state, e) {
+    const tag = document.activeElement?.tagName
+    if (tag === 'INPUT' || tag === 'TEXTAREA') {
+      return
+    }
+    e.preventDefault()
+    e.stopPropagation()
+    this.handleUndo(state)
+  }
+}

package/plugins/draw/src/adapters/maplibre/utils/keyboardShortcuts.test.js

@@ -0,0 +1,78 @@
+import { isInteractiveElementFocused, isUndoShortcut, sharedKeyboardHandlers } from './keyboardShortcuts.js'
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('isInteractiveElementFocused', () => {
+  test('returns false when nothing has been focused (activeElement defaults to body)', () => {
+    expect(document.activeElement).toBe(document.body)
+    expect(isInteractiveElementFocused({ container: document.createElement('div') })).toBe(false)
+  })
+
+  test('returns false for focus inside the container', () => {
+    const container = document.createElement('div')
+    const button = document.createElement('button')
+    container.appendChild(button)
+    document.body.appendChild(container)
+    button.focus()
+    expect(isInteractiveElementFocused({ container })).toBe(false)
+  })
+
+  test('returns true for an interactive tag focused outside the container', () => {
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    input.focus()
+    expect(isInteractiveElementFocused({ container: document.createElement('div') })).toBe(true)
+  })
+
+  test('returns true for a tabindex/contentEditable element focused outside the container', () => {
+    const div = document.createElement('div')
+    div.tabIndex = 0
+    document.body.appendChild(div)
+    div.focus()
+    expect(isInteractiveElementFocused({ container: document.createElement('div') })).toBe(true)
+  })
+
+  test('a missing container is treated as outside — falls through to the tag/attribute check', () => {
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    input.focus()
+    expect(isInteractiveElementFocused({ container: undefined })).toBe(true)
+  })
+})
+
+describe('isUndoShortcut', () => {
+  test('true for Cmd+Z or Ctrl+Z without shift', () => {
+    expect(isUndoShortcut({ key: 'z', metaKey: true })).toBe(true)
+    expect(isUndoShortcut({ key: 'z', ctrlKey: true })).toBe(true)
+  })
+
+  test('falsy when shift is also held, the key is wrong, or no modifier is held', () => {
+    expect(isUndoShortcut({ key: 'z', metaKey: true, shiftKey: true })).toBe(false)
+    expect(isUndoShortcut({ key: 'y', metaKey: true })).toBe(false)
+    expect(isUndoShortcut({ key: 'z' })).toBeFalsy()
+  })
+})
+
+describe('sharedKeyboardHandlers.handleUndoShortcut', () => {
+  test('swallows the default/propagation and delegates to handleUndo', () => {
+    const handleUndo = jest.fn()
+    const e = { preventDefault: jest.fn(), stopPropagation: jest.fn() }
+    sharedKeyboardHandlers.handleUndoShortcut.call({ handleUndo }, {}, e)
+    expect(e.preventDefault).toHaveBeenCalled()
+    expect(e.stopPropagation).toHaveBeenCalled()
+    expect(handleUndo).toHaveBeenCalled()
+  })
+
+  test('is ignored while typing in an input/textarea', () => {
+    const input = document.createElement('input')
+    document.body.appendChild(input)
+    input.focus()
+    const handleUndo = jest.fn()
+    const e = { preventDefault: jest.fn(), stopPropagation: jest.fn() }
+    sharedKeyboardHandlers.handleUndoShortcut.call({ handleUndo }, {}, e)
+    expect(handleUndo).not.toHaveBeenCalled()
+    expect(e.preventDefault).not.toHaveBeenCalled()
+  })
+})

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

@@ -52,7 +52,8 @@ export function getSnapCoords (snap) {
 }
 
 /**
- * Trigger snap detection at a given point
+ * Trigger snap detection at a given point. Marked `_explicit` so it still runs even while
+ * setAutoSnapSuspended (below) has silenced the library's own auto-query.
  * @param {MapboxSnap} snap - Snap instance
  * @param {maplibregl.Map} map - Map instance
  * @param {{ x: number, y: number }} point - Screen point
@@ -64,10 +65,22 @@ export function triggerSnapAtPoint (snap, map, point) {
   }
 
   const lngLat = map.unproject(point)
-  snap.snapToClosestPoint({ point, lngLat })
+  snap.snapToClosestPoint({ point, lngLat, _explicit: true })
   return true
 }
 
+/**
+ * Silences the snap library's own mousemove-driven auto-query (see prototypePatches.js), which
+ * otherwise re-snaps at the raw cursor and fights an edit mode's own offset-aware drag query.
+ * @param {MapboxSnap} snap - Snap instance
+ * @param {boolean} suspended
+ */
+export function setAutoSnapSuspended (snap, suspended) {
+  if (snap) {
+    snap._autoSnapSuspended = suspended
+  }
+}
+
 /**
  * Trigger snap detection at map center (for touch/keyboard modes)
  * @param {MapboxSnap} snap - Snap instance
@@ -82,7 +95,7 @@ export function triggerSnapAtCenter (snap, map) {
 
   const center = map.getCenter()
   const point = map.project(center)
-  snap.snapToClosestPoint({ point, lngLat: center })
+  snap.snapToClosestPoint({ point, lngLat: center, _explicit: true })
   return true
 }