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

package/plugins/draw/src/adapters/openlayers/utils/touchTarget.js

@@ -0,0 +1,8 @@
+// Re-export centralized touch target utilities from shared implementation
+export {
+  createTouchTarget,
+  applyTouchTargetColors,
+  showTouchTarget,
+  hideTouchTarget,
+  isOnTouchTarget
+} from '../../../utils/touchTarget.js'

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

@@ -0,0 +1,22 @@
+import { flattenStyleProperties } from '../utils/flattenStyleProperties.js'
+
+export const addFeature = ({ mapProvider, services }, feature) => {
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return
+  }
+
+  const { stroke, fill, strokeWidth, properties, ...featureRest } = feature
+  const flatFeature = {
+    ...featureRest,
+    properties: {
+      ...properties,
+      ...flattenStyleProperties({ stroke, fill, strokeWidth })
+    }
+  }
+
+  draw.add(flatFeature)
+  eventBus.emit('draw:add', flatFeature)
+}

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

@@ -0,0 +1,41 @@
+import { addFeature } from './addFeature.js'
+import { flattenStyleProperties } from '../utils/flattenStyleProperties.js'
+
+jest.mock('../utils/flattenStyleProperties.js', () => ({
+  flattenStyleProperties: jest.fn(() => ({ _flat: true }))
+}))
+
+const setup = (draw) => {
+  const eventBus = { emit: jest.fn() }
+  return { context: { mapProvider: { draw }, services: { eventBus } }, eventBus }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('addFeature', () => {
+  test('does nothing when there is no draw instance', () => {
+    const { context, eventBus } = setup(undefined)
+    addFeature(context, { id: 'a' })
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('flattens style properties and adds the feature', () => {
+    const draw = { add: jest.fn() }
+    const { context, eventBus } = setup(draw)
+    const feature = { id: 'a', geometry: {}, stroke: 'red', fill: 'blue', strokeWidth: 2, properties: { name: 'x' } }
+
+    addFeature(context, feature)
+
+    expect(flattenStyleProperties).toHaveBeenCalledWith({ stroke: 'red', fill: 'blue', strokeWidth: 2 })
+    const expected = { id: 'a', geometry: {}, properties: { name: 'x', _flat: true } }
+    expect(draw.add).toHaveBeenCalledWith(expected)
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:add', expected)
+  })
+
+  test('handles a feature without existing properties', () => {
+    const draw = { add: jest.fn() }
+    const { context } = setup(draw)
+    addFeature(context, { id: 'b', geometry: {} })
+    expect(draw.add).toHaveBeenCalledWith({ id: 'b', geometry: {}, properties: { _flat: true } })
+  })
+})

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

@@ -0,0 +1,11 @@
+export const deleteFeature = ({ mapProvider, services }, featureId) => {
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return
+  }
+
+  draw.delete(featureId)
+  eventBus.emit('draw:delete', { featureId })
+}

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

@@ -0,0 +1,24 @@
+import { deleteFeature } from './deleteFeature.js'
+
+const setup = (draw) => {
+  const eventBus = { emit: jest.fn() }
+  return { context: { mapProvider: { draw }, services: { eventBus } }, eventBus }
+}
+
+describe('deleteFeature', () => {
+  test('does nothing when there is no draw instance', () => {
+    const { context, eventBus } = setup(undefined)
+    deleteFeature(context, 'id1')
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('deletes the feature and emits the delete event', () => {
+    const draw = { delete: jest.fn() }
+    const { context, eventBus } = setup(draw)
+
+    deleteFeature(context, 'id1')
+
+    expect(draw.delete).toHaveBeenCalledWith('id1')
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:delete', { featureId: 'id1' })
+  })
+})

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

@@ -0,0 +1,54 @@
+import { MAP_SIZE_SCALES } from '../defaults.js'
+import { validateGeometry } from '../validation/validateGeometry.js'
+
+export const editFeature = ({ appState, appConfig, mapState, pluginConfig, pluginState, mapProvider, services }, featureId, options = {}) => {
+  const { dispatch } = pluginState
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return false
+  }
+
+  const existingFeature = draw.get(featureId)
+  if (!existingFeature) {
+    return false
+  }
+
+  // Per-call callback overrides the plugin-level one; events.js reads this on every commit.
+  draw._geometryValidator = options.onGeometryChange ?? pluginConfig.onGeometryChange
+
+  const editModeMap = { LineString: 'edit_line', Polygon: 'edit_polygon' }
+  eventBus.emit('draw:editstart', { mode: editModeMap[existingFeature.geometry.type] })
+
+  const snapLayers = options.snapLayers === undefined ? (pluginConfig.snapLayers ?? null) : options.snapLayers
+  draw.setSnapLayers(snapLayers)
+  dispatch({ type: 'SET_HAS_SNAP_LAYERS', payload: snapLayers?.length > 0 })
+
+  draw.changeMode('edit_vertex', {
+    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 feature = draw.get(featureId)
+  dispatch({
+    type: 'SET_FEATURE',
+    payload: { feature, tempFeature: feature }
+  })
+
+  dispatch({ type: 'SET_MODE', payload: 'edit_vertex' })
+
+  // Seed the Done-button gate and the stroke from the feature's starting validity
+  // so an already invalid feature opens dashed and cannot be "finished" until fixed.
+  const { valid } = validateGeometry(feature, { phase: 'edit-start', mode: 'edit_vertex' }, { onGeometryChange: draw._geometryValidator })
+  dispatch({ type: 'SET_GEOMETRY_VALID', payload: valid })
+  draw.setInvalid?.(!valid)
+
+  return true
+}

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

@@ -0,0 +1,134 @@
+import { editFeature } from './editFeature.js'
+
+jest.mock('../defaults.js', () => ({ MAP_SIZE_SCALES: { medium: 1.5, large: 2 } }))
+
+const makeContext = (overrides = {}) => {
+  const dispatch = jest.fn()
+  const eventBus = { emit: jest.fn() }
+  const draw = {
+    get: jest.fn(() => ({ id: 'f1', geometry: { type: 'Polygon' } })),
+    setSnapLayers: jest.fn(),
+    changeMode: jest.fn(),
+    isSnapEnabled: jest.fn(() => true)
+  }
+  const context = {
+    appState: { layoutRefs: { viewportRef: { current: 'viewport' } }, interfaceType: 'mouse' },
+    appConfig: { id: 'app' },
+    mapState: { mapSize: 'medium' },
+    pluginConfig: { snapLayers: ['pc-layer'] },
+    pluginState: { dispatch },
+    mapProvider: { draw },
+    services: { eventBus },
+    ...overrides
+  }
+  return { context, dispatch, eventBus, draw }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('editFeature', () => {
+  test('returns false when there is no draw instance', () => {
+    const { context } = makeContext({ mapProvider: { draw: null } })
+    expect(editFeature(context, 'f1')).toBe(false)
+  })
+
+  test('returns false when the feature does not exist', () => {
+    const { context, draw, eventBus } = makeContext()
+    draw.get.mockReturnValue(undefined)
+    expect(editFeature(context, 'missing')).toBe(false)
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('enters edit mode for a polygon and wires all options', () => {
+    const { context, dispatch, eventBus, draw } = makeContext()
+
+    const result = editFeature(context, 'f1')
+
+    expect(result).toBe(true)
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:editstart', { mode: 'edit_polygon' })
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['pc-layer'])
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: true })
+
+    expect(draw.changeMode).toHaveBeenCalledWith('edit_vertex', expect.objectContaining({
+      container: 'viewport',
+      deleteVertexButtonId: 'app-draw-delete-point',
+      undoButtonId: 'app-draw-undo',
+      isPanEnabled: true,
+      interfaceType: 'mouse',
+      scale: 1.5,
+      featureId: 'f1'
+    }))
+
+    const opts = draw.changeMode.mock.calls[0][1]
+    expect(opts.getSnapEnabled()).toBe(true)
+    expect(draw.isSnapEnabled).toHaveBeenCalled()
+
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_FEATURE', payload: { feature: { id: 'f1', geometry: { type: 'Polygon' } }, tempFeature: { id: 'f1', geometry: { type: 'Polygon' } } } })
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_MODE', payload: 'edit_vertex' })
+  })
+
+  test('uses edit_line mode for a line string', () => {
+    const { context, eventBus, draw } = makeContext()
+    draw.get.mockReturnValue({ id: 'f1', geometry: { type: 'LineString' } })
+    editFeature(context, 'f1')
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:editstart', { mode: 'edit_line' })
+  })
+
+  test('stores a per-call onGeometryChange validator, overriding the plugin-level one', () => {
+    const pluginOnGeometryChange = jest.fn()
+    const onGeometryChange = jest.fn()
+    const { context, draw } = makeContext({ pluginConfig: { snapLayers: ['pc-layer'], onGeometryChange: pluginOnGeometryChange } })
+    editFeature(context, 'f1', { onGeometryChange })
+    expect(draw._geometryValidator).toBe(onGeometryChange)
+  })
+
+  test('seeds the geometry-valid gate from the feature starting validity', () => {
+    const { context, dispatch, draw } = makeContext()
+    // A valid square → gate opens.
+    draw.get.mockReturnValue({ id: 'f1', geometry: { type: 'Polygon', coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]] } })
+    editFeature(context, 'f1')
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_GEOMETRY_VALID', payload: true })
+  })
+
+  test('seeds the gate closed for an already self-intersecting feature', () => {
+    const { context, dispatch, draw } = makeContext()
+    draw.get.mockReturnValue({ id: 'f1', geometry: { type: 'Polygon', coordinates: [[[0, 0], [1, 1], [1, 0], [0, 1], [0, 0]]] } })
+    editFeature(context, 'f1')
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_GEOMETRY_VALID', payload: false })
+  })
+
+  test('seeds the stroke alongside the gate — an invalid feature opens edit mode dashed', () => {
+    const { context, draw } = makeContext()
+    draw.setInvalid = jest.fn()
+    draw.get.mockReturnValue({ id: 'f1', geometry: { type: 'Polygon', coordinates: [[[0, 0], [1, 1], [1, 0], [0, 1], [0, 0]]] } })
+    editFeature(context, 'f1')
+    expect(draw.setInvalid).toHaveBeenCalledWith(true)
+
+    draw.setInvalid.mockClear()
+    draw.get.mockReturnValue({ id: 'f1', geometry: { type: 'Polygon', coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]] } })
+    editFeature(context, 'f1')
+    expect(draw.setInvalid).toHaveBeenCalledWith(false)
+  })
+
+  test('disables panning for the keyboard interface', () => {
+    const { context, draw } = makeContext({
+      appState: { layoutRefs: { viewportRef: { current: 'viewport' } }, interfaceType: 'keyboard' }
+    })
+    editFeature(context, 'f1')
+    expect(draw.changeMode.mock.calls[0][1].isPanEnabled).toBe(false)
+  })
+
+  test('prefers explicit option snapLayers over the plugin config', () => {
+    const { context, draw, dispatch } = makeContext()
+    editFeature(context, 'f1', { snapLayers: ['opt-layer'] })
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['opt-layer'])
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: true })
+  })
+
+  test('falls back to null snapLayers when neither option nor config is set', () => {
+    const { context, draw, dispatch } = makeContext({ pluginConfig: {} })
+    editFeature(context, 'f1')
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(null)
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: false })
+  })
+})

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

@@ -0,0 +1,30 @@
+import { mergePolygons } from '../utils/spatial.js'
+
+/**
+ * Merge multiple contiguous polygons into a single polygon.
+ *
+ * Pure computation, like split — this does not touch the feature store. The
+ * caller is responsible for deleting the original features and adding the
+ * merged result (see the draw:merge event).
+ *
+ * @param {object} context - plugin context
+ * @param {string[]} featureIds - IDs of the polygons to merge
+ * @returns {object|null} the merged GeoJSON feature, or null if the merge failed
+ */
+export const merge = ({ mapProvider, services }, featureIds) => {
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return null
+  }
+
+  const polygons = featureIds.map((id) => draw.get(id))
+  const feature = mergePolygons(polygons)
+
+  if (feature) {
+    eventBus.emit('draw:merge', { originalFeatureIds: featureIds, feature })
+  }
+
+  return feature
+}

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

@@ -0,0 +1,57 @@
+import { merge } from './merge.js'
+import { mergePolygons } from '../utils/spatial.js'
+
+jest.mock('../utils/spatial.js', () => ({ mergePolygons: jest.fn() }))
+
+const makeContext = (overrides = {}) => {
+  const eventBus = { emit: jest.fn() }
+  const draw = { get: jest.fn((id) => ({ id })) }
+  const context = {
+    mapProvider: { draw },
+    services: { eventBus },
+    ...overrides
+  }
+  return { context, draw, eventBus }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('merge', () => {
+  test('does nothing when there is no draw instance', () => {
+    const { context, eventBus } = makeContext({ mapProvider: { draw: null } })
+    expect(merge(context, ['a', 'b'])).toBeNull()
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('resolves each feature id via the adapter and merges them', () => {
+    const { context, draw } = makeContext()
+    mergePolygons.mockReturnValue({ id: 'a', geometry: { type: 'Polygon', coordinates: [] } })
+
+    merge(context, ['a', 'b'])
+
+    expect(draw.get).toHaveBeenCalledWith('a')
+    expect(draw.get).toHaveBeenCalledWith('b')
+    expect(mergePolygons).toHaveBeenCalledWith([{ id: 'a' }, { id: 'b' }])
+  })
+
+  test('returns the merged feature and emits draw:merge on success', () => {
+    const { context, eventBus } = makeContext()
+    const feature = { id: 'a', geometry: { type: 'Polygon', coordinates: [] } }
+    mergePolygons.mockReturnValue(feature)
+
+    const result = merge(context, ['a', 'b'])
+
+    expect(result).toBe(feature)
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:merge', { originalFeatureIds: ['a', 'b'], feature })
+  })
+
+  test('returns null and does not emit when the merge fails', () => {
+    const { context, eventBus } = makeContext()
+    mergePolygons.mockReturnValue(null)
+
+    const result = merge(context, ['a', 'b'])
+
+    expect(result).toBeNull()
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,41 @@
+import { flattenStyleProperties } from '../utils/flattenStyleProperties.js'
+
+// Near-identical to newPolygon.js, differing only in the 'draw_line'/'draw_polygon'
+// mode string — kept as two small, explicit entry points rather than one
+// mode-parameterised factory. Revisit if a third geometry type is ever added.
+export const newLine = ({ appState, appConfig, pluginConfig, pluginState, mapState, mapProvider, services }, featureId, options = {}) => {
+  const { dispatch } = pluginState
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return
+  }
+
+  eventBus.emit('draw:started', { mode: 'draw_line' })
+
+  const snapLayers = options.snapLayers === undefined ? (pluginConfig.snapLayers ?? null) : options.snapLayers
+  draw.setSnapLayers(snapLayers)
+  dispatch({ type: 'SET_HAS_SNAP_LAYERS', payload: snapLayers?.length > 0 })
+
+  const { stroke, fill, strokeWidth, properties: customProperties, onGeometryChange, ...modeOptions } = options
+  // Per-call callback overrides the plugin-level one; events.js reads this on every commit.
+  draw._geometryValidator = onGeometryChange ?? pluginConfig.onGeometryChange
+  const properties = {
+    ...customProperties,
+    ...flattenStyleProperties({ stroke, fill, strokeWidth })
+  }
+
+  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,
+    ...modeOptions,
+    properties
+  })
+
+  dispatch({ type: 'SET_MODE', payload: 'draw_line' })
+}

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

@@ -0,0 +1,93 @@
+import { newLine } from './newLine.js'
+import { flattenStyleProperties } from '../utils/flattenStyleProperties.js'
+
+jest.mock('../utils/flattenStyleProperties.js', () => ({
+  flattenStyleProperties: jest.fn(() => ({ _flat: true }))
+}))
+
+const makeContext = (overrides = {}) => {
+  const dispatch = jest.fn()
+  const eventBus = { emit: jest.fn() }
+  const draw = { setSnapLayers: jest.fn(), changeMode: jest.fn(), isSnapEnabled: jest.fn(() => false) }
+  const context = {
+    appState: { layoutRefs: { viewportRef: { current: 'viewport' } }, interfaceType: 'mouse' },
+    appConfig: { id: 'app' },
+    pluginConfig: { snapLayers: ['pc-layer'] },
+    pluginState: { dispatch },
+    mapState: { crossHair: true },
+    mapProvider: { draw },
+    services: { eventBus },
+    ...overrides
+  }
+  return { context, dispatch, eventBus, draw }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('newLine', () => {
+  test('does nothing when there is no draw instance', () => {
+    const { context, eventBus } = makeContext({ mapProvider: { draw: null } })
+    newLine(context, 'f1')
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('starts line drawing with flattened style properties', () => {
+    const { context, dispatch, eventBus, draw } = makeContext()
+
+    newLine(context, 'f1', { stroke: 'red', fill: 'blue', strokeWidth: 3, properties: { name: 'x' }, extra: 'opt' })
+
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:started', { mode: 'draw_line' })
+    expect(flattenStyleProperties).toHaveBeenCalledWith({ stroke: 'red', fill: 'blue', strokeWidth: 3 })
+
+    expect(draw.changeMode).toHaveBeenCalledWith('draw_line', expect.objectContaining({
+      container: 'viewport',
+      addVertexButtonId: 'app-draw-add-point',
+      interfaceType: 'mouse',
+      crossHair: true,
+      featureId: 'f1',
+      extra: 'opt',
+      properties: { name: 'x', _flat: true }
+    }))
+
+    const opts = draw.changeMode.mock.calls[0][1]
+    expect(opts.getSnapEnabled()).toBe(false)
+    expect(draw.isSnapEnabled).toHaveBeenCalled()
+
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_MODE', payload: 'draw_line' })
+  })
+
+  test('prefers explicit option snapLayers and flags them', () => {
+    const { context, draw, dispatch } = makeContext()
+    newLine(context, 'f1', { snapLayers: ['opt'] })
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['opt'])
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: true })
+  })
+
+  test('falls back to the plugin config snapLayers', () => {
+    const { context, draw } = makeContext()
+    newLine(context, 'f1')
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['pc-layer'])
+  })
+
+  test('falls back to null when neither option nor config is set', () => {
+    const { context, draw, dispatch } = makeContext({ pluginConfig: {} })
+    newLine(context, 'f1')
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(null)
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: false })
+  })
+
+  test('stores a per-call onGeometryChange validator without leaking it into mode options', () => {
+    const { context, draw } = makeContext()
+    const onGeometryChange = jest.fn()
+    newLine(context, 'f1', { onGeometryChange })
+    expect(draw._geometryValidator).toBe(onGeometryChange)
+    expect(draw.changeMode.mock.calls[0][1]).not.toHaveProperty('onGeometryChange')
+  })
+
+  test('falls back to the plugin-level onGeometryChange validator', () => {
+    const pluginOnGeometryChange = jest.fn()
+    const { context, draw } = makeContext({ pluginConfig: { onGeometryChange: pluginOnGeometryChange } })
+    newLine(context, 'f1')
+    expect(draw._geometryValidator).toBe(pluginOnGeometryChange)
+  })
+})

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

@@ -0,0 +1,41 @@
+import { flattenStyleProperties } from '../utils/flattenStyleProperties.js'
+
+// Near-identical to newLine.js, differing only in the 'draw_polygon'/'draw_line'
+// mode string — kept as two small, explicit entry points rather than one
+// mode-parameterised factory. Revisit if a third geometry type is ever added.
+export const newPolygon = ({ appState, appConfig, pluginConfig, pluginState, mapState, mapProvider, services }, featureId, options = {}) => {
+  const { dispatch } = pluginState
+  const { draw } = mapProvider
+  const { eventBus } = services
+
+  if (!draw) {
+    return
+  }
+
+  eventBus.emit('draw:started', { mode: 'draw_polygon' })
+
+  const snapLayers = options.snapLayers === undefined ? (pluginConfig.snapLayers ?? null) : options.snapLayers
+  draw.setSnapLayers(snapLayers)
+  dispatch({ type: 'SET_HAS_SNAP_LAYERS', payload: snapLayers?.length > 0 })
+
+  const { stroke, fill, strokeWidth, properties: customProperties, onGeometryChange, ...modeOptions } = options
+  // Per-call callback overrides the plugin-level one; events.js reads this on every commit.
+  draw._geometryValidator = onGeometryChange ?? pluginConfig.onGeometryChange
+  const properties = {
+    ...customProperties,
+    ...flattenStyleProperties({ stroke, fill, strokeWidth })
+  }
+
+  draw.changeMode('draw_polygon', {
+    container: appState.layoutRefs.viewportRef.current,
+    addVertexButtonId: `${appConfig.id}-draw-add-point`,
+    interfaceType: appState.interfaceType,
+    crossHair: mapState.crossHair,
+    getSnapEnabled: () => draw.isSnapEnabled(),
+    featureId,
+    ...modeOptions,
+    properties
+  })
+
+  dispatch({ type: 'SET_MODE', payload: 'draw_polygon' })
+}

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

@@ -0,0 +1,93 @@
+import { newPolygon } from './newPolygon.js'
+import { flattenStyleProperties } from '../utils/flattenStyleProperties.js'
+
+jest.mock('../utils/flattenStyleProperties.js', () => ({
+  flattenStyleProperties: jest.fn(() => ({ _flat: true }))
+}))
+
+const makeContext = (overrides = {}) => {
+  const dispatch = jest.fn()
+  const eventBus = { emit: jest.fn() }
+  const draw = { setSnapLayers: jest.fn(), changeMode: jest.fn(), isSnapEnabled: jest.fn(() => true) }
+  const context = {
+    appState: { layoutRefs: { viewportRef: { current: 'viewport' } }, interfaceType: 'mouse' },
+    appConfig: { id: 'app' },
+    pluginConfig: { snapLayers: ['pc-layer'] },
+    pluginState: { dispatch },
+    mapState: { crossHair: false },
+    mapProvider: { draw },
+    services: { eventBus },
+    ...overrides
+  }
+  return { context, dispatch, eventBus, draw }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('newPolygon', () => {
+  test('does nothing when there is no draw instance', () => {
+    const { context, eventBus } = makeContext({ mapProvider: { draw: null } })
+    newPolygon(context, 'f1')
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  test('starts polygon drawing with flattened style properties', () => {
+    const { context, dispatch, eventBus, draw } = makeContext()
+
+    newPolygon(context, 'f1', { stroke: 'red', fill: 'blue', strokeWidth: 3, properties: { name: 'x' }, extra: 'opt' })
+
+    expect(eventBus.emit).toHaveBeenCalledWith('draw:started', { mode: 'draw_polygon' })
+    expect(flattenStyleProperties).toHaveBeenCalledWith({ stroke: 'red', fill: 'blue', strokeWidth: 3 })
+
+    expect(draw.changeMode).toHaveBeenCalledWith('draw_polygon', expect.objectContaining({
+      container: 'viewport',
+      addVertexButtonId: 'app-draw-add-point',
+      interfaceType: 'mouse',
+      crossHair: false,
+      featureId: 'f1',
+      extra: 'opt',
+      properties: { name: 'x', _flat: true }
+    }))
+
+    const opts = draw.changeMode.mock.calls[0][1]
+    expect(opts.getSnapEnabled()).toBe(true)
+    expect(draw.isSnapEnabled).toHaveBeenCalled()
+
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_MODE', payload: 'draw_polygon' })
+  })
+
+  test('prefers explicit option snapLayers and flags them', () => {
+    const { context, draw, dispatch } = makeContext()
+    newPolygon(context, 'f1', { snapLayers: ['opt'] })
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['opt'])
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: true })
+  })
+
+  test('falls back to the plugin config snapLayers', () => {
+    const { context, draw } = makeContext()
+    newPolygon(context, 'f1')
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(['pc-layer'])
+  })
+
+  test('falls back to null when neither option nor config is set', () => {
+    const { context, draw, dispatch } = makeContext({ pluginConfig: {} })
+    newPolygon(context, 'f1')
+    expect(draw.setSnapLayers).toHaveBeenCalledWith(null)
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_HAS_SNAP_LAYERS', payload: false })
+  })
+
+  test('stores a per-call onGeometryChange validator without leaking it into mode options', () => {
+    const { context, draw } = makeContext()
+    const onGeometryChange = jest.fn()
+    newPolygon(context, 'f1', { onGeometryChange })
+    expect(draw._geometryValidator).toBe(onGeometryChange)
+    expect(draw.changeMode.mock.calls[0][1]).not.toHaveProperty('onGeometryChange')
+  })
+
+  test('falls back to the plugin-level onGeometryChange validator', () => {
+    const pluginOnGeometryChange = jest.fn()
+    const { context, draw } = makeContext({ pluginConfig: { onGeometryChange: pluginOnGeometryChange } })
+    newPolygon(context, 'f1')
+    expect(draw._geometryValidator).toBe(pluginOnGeometryChange)
+  })
+})