@defra/interactive-map 0.0.57-alpha → 0.0.59-alpha
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/esm/im-core.js +1 -1
- package/dist/umd/im-core.js +1 -1
- package/docs/assets/css/docusaurus.scss +7 -1
- package/docs/plugins/draw.md +317 -186
- package/package.json +1 -1
- package/plugins/draw/dist/esm/im-draw-ml-adapter.js +1 -1
- package/plugins/draw/dist/esm/im-draw-ol-adapter.js +1 -1
- package/plugins/draw/dist/esm/im-draw-plugin.js +1 -1
- package/plugins/draw/dist/esm/index.js +1 -1
- package/plugins/draw/dist/esm/liveDrawChecks.js +1 -1
- package/plugins/draw/dist/umd/im-draw-ml-adapter.js +1 -1
- package/plugins/draw/dist/umd/im-draw-ol-adapter.js +1 -1
- package/plugins/draw/dist/umd/im-draw-plugin.js +1 -1
- package/plugins/draw/dist/umd/index.js +1 -1
- package/plugins/draw/src/adapterEvents.js +15 -9
- package/plugins/draw/src/adapters/adapterContract.test.js +1 -0
- package/plugins/draw/src/adapters/maplibre/MaplibreDrawAdapter.js +15 -3
- package/plugins/draw/src/adapters/maplibre/MaplibreDrawAdapter.test.js +27 -0
- package/plugins/draw/src/adapters/maplibre/modes/editPointMode/pointerHandlers.js +8 -19
- package/plugins/draw/src/adapters/maplibre/modes/editPointMode/pointerHandlers.test.js +20 -0
- package/plugins/draw/src/adapters/maplibre/modes/editVertexMode/pointerHandlers.js +6 -17
- package/plugins/draw/src/adapters/maplibre/modes/editVertexMode/pointerHandlers.test.js +19 -0
- package/plugins/draw/src/adapters/maplibre/utils/editModeEvents.js +29 -1
- package/plugins/draw/src/adapters/openlayers/OLDrawAdapter.js +13 -3
- package/plugins/draw/src/adapters/openlayers/OLDrawAdapter.test.js +28 -0
- package/plugins/draw/src/api/addFeature.js +9 -6
- package/plugins/draw/src/api/addFeature.test.js +37 -10
- package/plugins/draw/src/api/createNewShape.js +2 -2
- package/plugins/draw/src/api/editFeature.js +1 -1
- package/plugins/draw/src/api/newPoint.js +2 -2
- package/plugins/draw/src/api/newPoint.test.js +8 -0
- package/plugins/draw/src/api/newPolygon.test.js +8 -0
- package/plugins/draw/src/api/recheckGeometry.js +1 -1
- package/plugins/draw/src/api/recheckGeometry.test.js +2 -2
- package/plugins/draw/src/api/setProperties.js +39 -0
- package/plugins/draw/src/api/setProperties.test.js +74 -0
- package/plugins/draw/src/api/setStyle.js +16 -19
- package/plugins/draw/src/api/setStyle.test.js +17 -2
- package/plugins/draw/src/api/split.js +10 -4
- package/plugins/draw/src/api/split.test.js +30 -2
- package/plugins/draw/src/events.js +110 -64
- package/plugins/draw/src/events.test.js +494 -4
- package/plugins/draw/src/manifest.js +6 -4
- package/plugins/draw/src/manifest.test.js +20 -26
- package/plugins/draw/src/reducer.js +7 -0
- package/plugins/draw/src/reducer.test.js +11 -0
- package/plugins/draw/src/utils/flattenStyleProperties.js +54 -2
- package/plugins/draw/src/utils/flattenStyleProperties.test.js +74 -1
- package/plugins/draw/src/utils/isPlainObject.js +14 -0
- package/plugins/draw/src/utils/isPlainObject.test.js +24 -0
- package/plugins/draw/src/utils/mergeFeatureProperties.js +45 -0
- package/plugins/draw/src/utils/mergeFeatureProperties.test.js +48 -0
- package/plugins/draw/src/utils/stripInternalProperties.js +3 -2
- package/plugins/draw/src/validation/commitChecks.js +32 -12
- package/plugins/draw/src/validation/commitChecks.test.js +73 -13
- package/plugins/draw/src/validation/validateGeometry.js +12 -5
- package/plugins/draw/src/validation/validateGeometry.test.js +18 -0
- package/src/App/store/MapProvider.jsx +1 -0
- package/src/App/store/MapProvider.test.jsx +25 -0
- package/src/App/store/mapActionsMap.js +6 -0
- package/src/App/store/mapActionsMap.test.js +7 -0
- package/src/App/store/mapReducer.js +2 -0
- package/src/App/store/mapReducer.test.js +2 -0
package/docs/plugins/draw.md
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
# Draw Plugin
|
|
2
2
|
|
|
3
|
-
The draw plugin lets users draw and edit
|
|
3
|
+
The draw plugin lets users draw and edit points, lines and polygons on the map. They can place vertices by click, tap or keyboard, and snap to existing map layers. Shapes are checked as they're built. Polygons can also be split and merged.
|
|
4
|
+
|
|
5
|
+
Hooks let you add your own checks at each stage: as vertices are placed, as the shape changes, and when it's finished. Use them to apply your own rules, help users fix or review their shapes, and attach your own data.
|
|
6
|
+
|
|
7
|
+
It works the same with the MapLibre and OpenLayers map providers. The plugin picks the right one from the `mapProvider` you pass to `InteractiveMap`, so there's nothing to configure.
|
|
4
8
|
|
|
5
9
|
> [!IMPORTANT]
|
|
6
10
|
> **Using a bundler (ESM)?** This plugin includes adapters for more than one map provider, so your bundler needs to ignore the map engines you haven't installed. See [Bundler configuration](../getting-started.md#bundler-configuration-esm).
|
|
@@ -87,28 +91,36 @@ Plugin-level check, called after each committed change to a shape. Can return a
|
|
|
87
91
|
|
|
88
92
|
---
|
|
89
93
|
|
|
94
|
+
### `onGeometryFinish`
|
|
95
|
+
|
|
96
|
+
**Type:** `Function`
|
|
97
|
+
|
|
98
|
+
Plugin-level check, called when a shape is finished. Can return a Promise. Can be overridden per call. See [`onGeometryFinish`](#ongeometryfinishevent-context).
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
90
102
|
### Colour and size overrides
|
|
91
103
|
|
|
92
104
|
> [!NOTE]
|
|
93
105
|
> Each colour accepts a plain colour string or a style-keyed object (e.g. `{ light: '#1d70b8', dark: '#ffffff' }`).
|
|
94
106
|
|
|
95
|
-
| Property |
|
|
96
|
-
|
|
97
|
-
| `shapeStroke` | `string \| Record<string, string
|
|
98
|
-
| `shapeFill` | `string \| Record<string, string
|
|
99
|
-
| `strokeWidth` | `number`
|
|
100
|
-
| `editStroke` | `string \| Record<string, string
|
|
101
|
-
| `editFill` | `string \| Record<string, string
|
|
102
|
-
| `editVertex` | `string \| Record<string, string
|
|
103
|
-
| `editMidpoint` | `string \| Record<string, string
|
|
104
|
-
| `editActive` | `string \| Record<string, string
|
|
105
|
-
| `editHalo` | `string \| Record<string, string
|
|
106
|
-
| `invalidStroke` | `string \| Record<string, string
|
|
107
|
-
| `splitValid` | `string \| Record<string, string
|
|
108
|
-
| `splitInvalid` | `string \| Record<string, string
|
|
109
|
-
| `snapVertex` | `string \| Record<string, string
|
|
110
|
-
| `snapEdge` | `string \| Record<string, string
|
|
111
|
-
| `snapRadius` | `number`
|
|
107
|
+
| Property | Description |
|
|
108
|
+
|----------|-------------|
|
|
109
|
+
| `shapeStroke` | **Type:** `string \| Record<string, string>`<br />Default stroke colour for an inactive (not being drawn/edited) shape, when the feature sets no `stroke` of its own |
|
|
110
|
+
| `shapeFill` | **Type:** `string \| Record<string, string>`<br />Default fill colour for an inactive shape, when the feature sets no `fill` of its own |
|
|
111
|
+
| `strokeWidth` | **Type:** `number`<br />**Default:** `2`<br />Default stroke width in pixels |
|
|
112
|
+
| `editStroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour of the shape currently being drawn or edited |
|
|
113
|
+
| `editFill` | **Type:** `string \| Record<string, string>`<br />Fill colour of the shape currently being drawn or edited |
|
|
114
|
+
| `editVertex` | **Type:** `string \| Record<string, string>`<br />Colour of placed, unselected vertex handles |
|
|
115
|
+
| `editMidpoint` | **Type:** `string \| Record<string, string>`<br />Colour of the midpoint handles used to insert a new vertex on an edge |
|
|
116
|
+
| `editActive` | **Type:** `string \| Record<string, string>`<br />Colour of the currently selected/active vertex handle |
|
|
117
|
+
| `editHalo` | **Type:** `string \| Record<string, string>`<br />Colour of the halo drawn behind vertex/midpoint handles for contrast |
|
|
118
|
+
| `invalidStroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour of the dashed outline shown while the shape fails validation |
|
|
119
|
+
| `splitValid` | **Type:** `string \| Record<string, string>`<br />Colour of the split line while it would produce a valid split |
|
|
120
|
+
| `splitInvalid` | **Type:** `string \| Record<string, string>`<br />Colour of the split line while it would not produce a valid split |
|
|
121
|
+
| `snapVertex` | **Type:** `string \| Record<string, string>`<br />Colour of the snap indicator shown over a vertex |
|
|
122
|
+
| `snapEdge` | **Type:** `string \| Record<string, string>`<br />Colour of the snap indicator shown over an edge |
|
|
123
|
+
| `snapRadius` | **Type:** `number`<br />**Default:** `12`<br />Snap tolerance in pixels |
|
|
112
124
|
|
|
113
125
|
```js
|
|
114
126
|
createDrawPlugin({
|
|
@@ -121,154 +133,178 @@ createDrawPlugin({
|
|
|
121
133
|
|
|
122
134
|
## Validation
|
|
123
135
|
|
|
124
|
-
Every
|
|
125
|
-
|
|
126
|
-
- [`onGeometryPreview`](#ongeometrypreviewevent) — synchronous. Gives live feedback while a shape is drawn or dragged, and can reject a vertex before it's placed.
|
|
127
|
-
- [`onGeometryChange`](#ongeometrychangeevent-context) — called after each committed change. Can be asynchronous. Its result for the latest change gates the Done button.
|
|
136
|
+
Every change is checked against the built-in rules, then against your own callbacks if you set them.
|
|
128
137
|
|
|
129
138
|
### Built-in rules
|
|
130
139
|
|
|
131
|
-
| Rule |
|
|
132
|
-
|
|
133
|
-
| Minimum vertices |
|
|
134
|
-
| Self-intersection |
|
|
135
|
-
|
|
|
136
|
-
|
|
140
|
+
| Rule | Description |
|
|
141
|
+
|------|-------------|
|
|
142
|
+
| Minimum vertices | A polygon needs 3 vertices and a line 2 before it can be finished |
|
|
143
|
+
| Self-intersection | A polygon that crosses itself can't be finished. A vertex that would make the drawn path cross itself is rejected and never placed |
|
|
144
|
+
| Non-zero area | A flat polygon, with all its vertices in a line, can't be finished |
|
|
145
|
+
|
|
146
|
+
While a rule fails, the shape has a dashed outline.
|
|
147
|
+
|
|
148
|
+
### Callbacks
|
|
149
|
+
|
|
150
|
+
| Callback | Description |
|
|
151
|
+
|----------|-------------|
|
|
152
|
+
| [`onGeometryPreview`](#ongeometrypreviewevent) | Live checks while a shape is drawn or dragged, and before a vertex is placed. Must answer straight away |
|
|
153
|
+
| [`onGeometryChange`](#ongeometrychangeevent-context) | After each change. Can return a Promise. The latest result enables or disables Done |
|
|
154
|
+
| [`onGeometryFinish`](#ongeometryfinishevent-context) | When a shape is finished. Can return a Promise. Decides whether the shape is created, or the edit finishes |
|
|
137
155
|
|
|
138
|
-
|
|
156
|
+
#### Setting the callbacks
|
|
139
157
|
|
|
140
|
-
|
|
158
|
+
Set them at plugin level, `createDrawPlugin({ onGeometryPreview, onGeometryChange, onGeometryFinish })`, or per call in the options of `newPolygon`, `newLine`, `newPoint` and `editFeature`. Each per-call callback replaces only its plugin-level equivalent for that session. The others still apply. To do more than one thing on a change, call each from one callback.
|
|
141
159
|
|
|
142
|
-
|
|
160
|
+
They aren't used by `split`, `merge`, `addFeature`, `setStyle` or `setProperties`.
|
|
143
161
|
|
|
144
|
-
|
|
162
|
+
#### What they return
|
|
163
|
+
|
|
164
|
+
| Value | Description |
|
|
165
|
+
|-------|-------------|
|
|
166
|
+
| `true` | Valid |
|
|
167
|
+
| `undefined` | Valid |
|
|
168
|
+
| `false` | Invalid, with no reason shown |
|
|
169
|
+
| `result.valid` | Whether the shape is valid |
|
|
170
|
+
| `result.reason` | Why the shape is invalid. Shown as a hint and sent with [`draw:geometryinvalid`](#drawgeometryinvalid) |
|
|
171
|
+
| `result.announcement` | Read out by screen readers instead of draw's own message. When it's set, `reason` isn't shown as a hint, so you can show it yourself. From `onGeometryPreview`, it's only read out for a rejected vertex |
|
|
172
|
+
| `result.properties` | Properties to add to the finished shape. `onGeometryFinish` only, on a passing result. See [Adding properties to the finished shape](#adding-properties-to-the-finished-shape) |
|
|
173
|
+
| `result.reopen` | `true` to reopen a new shape in edit mode, valid, instead of creating it. `onGeometryFinish` only, on a passing result for phase `'create'`. See [Reopening a shape that passes](#reopening-a-shape-that-passes) |
|
|
174
|
+
|
|
175
|
+
#### What they receive
|
|
176
|
+
|
|
177
|
+
| Property | Description |
|
|
178
|
+
|----------|-------------|
|
|
179
|
+
| `event.feature` | The shape being checked, as a GeoJSON feature |
|
|
180
|
+
| `event.phase` | Why the callback was called. See each callback below |
|
|
181
|
+
| `event.mode` | The draw mode: `'draw_polygon'`, `'draw_line'`, `'draw_point'`, `'edit_vertex'` or `'edit_point'` |
|
|
182
|
+
| `event.vertexIndex` | The vertex being placed or changed. Only on `'place'`, and on a `'change'` to a single vertex |
|
|
183
|
+
| `event.numVertices` | How many vertices have been placed, not counting the one following the pointer. Only on `'preview'` |
|
|
184
|
+
| `event.detail` | The `detail` passed to [`recheckGeometry`](#recheckgeometrydetail). Only on `'recheck'` |
|
|
185
|
+
| `context.signal` | An `AbortSignal`, aborted when a newer check starts or the session ends. Pass it to `fetch` to cancel the request. Not passed to `onGeometryPreview` |
|
|
186
|
+
| `context.revision` | A number that increases with every check. Not passed to `onGeometryPreview` |
|
|
187
|
+
|
|
188
|
+
#### Debouncing
|
|
189
|
+
|
|
190
|
+
Debouncing and timeouts are up to you. Waiting on `signal` gives a debounce that cancels itself when the shape changes again:
|
|
145
191
|
|
|
146
192
|
```js
|
|
193
|
+
const wait = (ms, signal) => new Promise((resolve, reject) => {
|
|
194
|
+
const timer = setTimeout(resolve, ms)
|
|
195
|
+
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason) }, { once: true })
|
|
196
|
+
})
|
|
197
|
+
|
|
147
198
|
createDrawPlugin({
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
199
|
+
onGeometryPreview: (event) => ({
|
|
200
|
+
valid: isEastOfWalesBorder(event.feature.geometry),
|
|
201
|
+
reason: 'Points must be placed east of the England/Wales border'
|
|
202
|
+
}),
|
|
203
|
+
onGeometryChange: async ({ feature }, { signal }) => {
|
|
204
|
+
infoPanel.update(measureArea(feature))
|
|
205
|
+
await wait(300, signal)
|
|
206
|
+
const response = await fetch('/api/boundary-checks', { method: 'POST', body: JSON.stringify(feature), signal })
|
|
207
|
+
return response.json() // { valid, reason }
|
|
151
208
|
}
|
|
152
209
|
})
|
|
153
210
|
```
|
|
154
211
|
|
|
155
|
-
|
|
212
|
+
## `onGeometryPreview(event)`
|
|
156
213
|
|
|
157
|
-
|
|
214
|
+
**Signature:** `onGeometryPreview(event) => result`
|
|
158
215
|
|
|
159
|
-
|
|
160
|
-
|---|---|
|
|
161
|
-
| `true` / `undefined` | Valid |
|
|
162
|
-
| `false` | Invalid, no reason shown |
|
|
163
|
-
| `{ valid, reason, announcement, recheckOnFinish }` | Valid or invalid, with these optional fields |
|
|
216
|
+
Must answer straight away. A Promise counts as valid. It runs on every frame of a drag, so keep it quick.
|
|
164
217
|
|
|
165
|
-
|
|
|
166
|
-
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `recheckOnFinish` | `boolean` | `onGeometryChange` only. When the shape is finished, check it again with phase `'create'` or `'edit-finish'` rather than reusing this result. See [Checking once a shape is finished](#checking-once-a-shape-is-finished) |
|
|
218
|
+
| Phase | When |
|
|
219
|
+
|-------|------|
|
|
220
|
+
| `'preview'` | While a shape is drawn or dragged. Drives the dashed outline and the Add point button. While editing, it also enables or disables Done |
|
|
221
|
+
| `'place'` | Before a vertex is placed by a click, tap, <kbd>Enter</kbd> or Add point. An invalid result rejects the vertex |
|
|
170
222
|
|
|
171
|
-
|
|
223
|
+
Use it for rules about a single vertex, such as where the first point can go. `onGeometryChange` isn't called until the shape has its minimum number of vertices.
|
|
172
224
|
|
|
173
|
-
|
|
174
|
-
|----------|------|-------------|
|
|
175
|
-
| `feature` | `GeoJSON.Feature` | The shape being checked — the in-progress feature during `'preview'`, the committed or candidate feature in every other phase |
|
|
176
|
-
| `phase` | `string` | Why the callback was called — see each callback's phases below |
|
|
177
|
-
| `mode` | `'draw_polygon' \| 'draw_line' \| 'draw_point' \| 'edit_vertex' \| 'edit_point'` | The active draw mode |
|
|
178
|
-
| `vertexIndex` | `number` | Index of the vertex being placed, added, moved, inserted or deleted. Present on `'place'`, and on a `'change'` to a single vertex |
|
|
179
|
-
| `numVertices` | `number` | Count of already-committed vertices, excluding any in-progress cursor point. Present on every `'preview'` call |
|
|
225
|
+
## `onGeometryChange(event, context)`
|
|
180
226
|
|
|
181
|
-
|
|
227
|
+
**Signature:** `onGeometryChange(event, context) => result | Promise<result>`
|
|
182
228
|
|
|
183
|
-
|
|
229
|
+
Called after each change to a shape.
|
|
184
230
|
|
|
185
|
-
|
|
231
|
+
| Phase | When |
|
|
232
|
+
|-------|------|
|
|
233
|
+
| `'change'` | The shape changed, including with [`setGeometry`](#setgeometrygeometry) or undo |
|
|
234
|
+
| `'edit-start'` | `editFeature` opened the shape |
|
|
235
|
+
| `'recheck'` | [`recheckGeometry`](#recheckgeometrydetail) was called |
|
|
236
|
+
| `'create'` | Only without `onGeometryFinish`. A new shape was finished without a passing result, such as a new point |
|
|
237
|
+
| `'edit-finish'` | Only without `onGeometryFinish`, when the last result set `recheckOnFinish`. Done was pressed on an edit |
|
|
186
238
|
|
|
187
|
-
|
|
188
|
-
|-------|------|--------|
|
|
189
|
-
| `'preview'` | Every rubber-band move or drag, throttled to once per frame | Drives the dashed outline and the Add point button. While editing, also gates the Done button |
|
|
190
|
-
| `'place'` | A click, tap, <kbd>Enter</kbd> or Add point press, before the vertex is placed | Invalid rejects the vertex — it never appears |
|
|
239
|
+
It's only called once the built-in rules pass, and only the result for the latest change counts. If it fails, throws or rejects, the shape can't be finished: call `recheckGeometry()` to retry. If the shape is finished while a check is running, draw waits for the result.
|
|
191
240
|
|
|
192
|
-
|
|
241
|
+
While a check is running, Done stays as the last result of `onGeometryChange` or `onGeometryFinish` left it: disabled if that result failed, otherwise enabled. When `editFeature` opens a shape, Done is disabled until its `'edit-start'` check passes.
|
|
193
242
|
|
|
194
|
-
|
|
243
|
+
## `onGeometryFinish(event, context)`
|
|
195
244
|
|
|
196
|
-
**Signature:** `
|
|
245
|
+
**Signature:** `onGeometryFinish(event, context) => result | Promise<result>`
|
|
197
246
|
|
|
198
|
-
Called
|
|
247
|
+
Called when a shape is finished, to check the whole shape once. Without it, finishing uses the latest `onGeometryChange` result. If `onGeometryChange` already checks the shape with your service, you don't need `onGeometryFinish`.
|
|
199
248
|
|
|
200
249
|
| Phase | When |
|
|
201
250
|
|-------|------|
|
|
202
|
-
| `'
|
|
203
|
-
| `'
|
|
204
|
-
| `'edit-start'` | `editFeature` opened the shape |
|
|
205
|
-
| `'edit-finish'` | Done was pressed on an edit, with [`recheckOnFinish`](#checking-once-a-shape-is-finished) |
|
|
206
|
-
| `'recheck'` | [`recheckGeometry`](#recheckgeometrydetail) was called. Its `detail` is on `event.detail` |
|
|
251
|
+
| `'create'` | A new shape or point was finished |
|
|
252
|
+
| `'edit-finish'` | Done was pressed on an edit |
|
|
207
253
|
|
|
208
|
-
|
|
209
|
-
|----------|------|-------------|
|
|
210
|
-
| `signal` | `AbortSignal` | Aborted when the shape changes again or the session ends. Pass it to `fetch` to cancel the request |
|
|
211
|
-
| `revision` | `number` | Increases with every check |
|
|
254
|
+
Draw waits for the result. A new shape that fails, or passes with [`reopen`](#reopening-a-shape-that-passes), reopens in edit mode ([`draw:reopened`](#drawreopened)), where Undo starts empty and Cancel discards it. An edit that fails stays open. If the latest `onGeometryChange` result failed, the shape can't be finished, so `onGeometryFinish` isn't called. If an `onGeometryChange` check is still running when the shape is finished, it's cancelled and `onGeometryFinish` decides.
|
|
212
255
|
|
|
213
|
-
|
|
214
|
-
- Only the result for the latest change counts.
|
|
215
|
-
- A shape that fails, or whose check throws or rejects, can't be finished. Call `recheckGeometry()` to retry.
|
|
216
|
-
- If the user finishes while a check is running, draw waits for it. A new shape that then fails is reopened in edit mode ([`draw:reopened`](#drawreopened)). An edit that fails stays open.
|
|
256
|
+
This updates a panel on every change, and validates the shape once it's finished:
|
|
217
257
|
|
|
218
|
-
|
|
258
|
+
```js
|
|
259
|
+
createDrawPlugin({
|
|
260
|
+
// Returns nothing, so every change counts as valid
|
|
261
|
+
onGeometryChange: ({ feature }, { signal }) => {
|
|
262
|
+
contextPanel.update(feature, { signal })
|
|
263
|
+
},
|
|
264
|
+
onGeometryFinish: ({ feature }, { signal }) => validateWithService(feature, { signal })
|
|
265
|
+
})
|
|
266
|
+
```
|
|
219
267
|
|
|
220
|
-
|
|
268
|
+
Don't `await` the panel update. `onGeometryChange` would then be pending until the panel replies: a slow reply is announced as "Checking shape", and finishing the shape cancels it.
|
|
221
269
|
|
|
222
|
-
|
|
270
|
+
#### Adding properties to the finished shape
|
|
271
|
+
|
|
272
|
+
A passing result can include `properties` to store with the shape, such as what the check found. Draw adds them before the shape is created or the edit finishes, so they're in [`draw:created`](#drawcreated) and [`draw:edited`](#drawedited). They follow the same rules as [`setProperties`](#setpropertiesfeatureid-properties).
|
|
223
273
|
|
|
224
274
|
```js
|
|
225
275
|
createDrawPlugin({
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
if (phase === 'change' || phase === 'edit-start') {
|
|
233
|
-
return { valid: true, recheckOnFinish: true }
|
|
276
|
+
onGeometryFinish: async ({ feature }, { signal }) => {
|
|
277
|
+
try {
|
|
278
|
+
return await validateWithService(feature, { signal })
|
|
279
|
+
} catch {
|
|
280
|
+
// Let the user finish, but record that the shape wasn't checked
|
|
281
|
+
return { valid: true, properties: { drawRules: { checked: false, reason: 'error' } } }
|
|
234
282
|
}
|
|
235
|
-
// 'create', 'edit-finish' and 'recheck' are checked by the service
|
|
236
|
-
return validateWithService(feature, { signal })
|
|
237
283
|
}
|
|
238
284
|
})
|
|
239
285
|
```
|
|
240
286
|
|
|
241
|
-
|
|
287
|
+
Keep them under one key of your own, such as `drawRules`, so they don't clash with other properties. `properties` is ignored on a failing result, and from `onGeometryPreview` and `onGeometryChange`.
|
|
242
288
|
|
|
243
|
-
|
|
289
|
+
#### Reopening a shape that passes
|
|
244
290
|
|
|
245
|
-
|
|
291
|
+
A passing result for a new shape can include `reopen: true`, to show the user something before the shape is created, such as suggestions, without blocking it. The shape reopens in edit mode with Done enabled, and [`draw:reopened`](#drawreopened) is sent with `status: 'valid'`.
|
|
246
292
|
|
|
247
|
-
|
|
293
|
+
Pressing Done on the unchanged shape creates it from that same result, including its `properties`, without calling `onGeometryFinish` again. If the user changes the shape first, `onGeometryFinish` is called with phase `'edit-finish'`.
|
|
248
294
|
|
|
249
295
|
```js
|
|
250
|
-
const wait = (ms, signal) => new Promise((resolve, reject) => {
|
|
251
|
-
const timer = setTimeout(resolve, ms)
|
|
252
|
-
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason) }, { once: true })
|
|
253
|
-
})
|
|
254
|
-
|
|
255
296
|
createDrawPlugin({
|
|
256
|
-
|
|
257
|
-
valid:
|
|
258
|
-
|
|
259
|
-
}),
|
|
260
|
-
onGeometryChange: async ({ feature }, { signal }) => {
|
|
261
|
-
infoPanel.update(measureArea(feature))
|
|
262
|
-
await wait(300, signal)
|
|
263
|
-
const response = await fetch('/api/boundary-checks', { method: 'POST', body: JSON.stringify(feature), signal })
|
|
264
|
-
return response.json() // { valid, reason }
|
|
265
|
-
}
|
|
297
|
+
onGeometryFinish: async ({ feature, phase }) => phase === 'create' && hasSuggestions(feature)
|
|
298
|
+
? { valid: true, reopen: true, announcement: '1 suggestion for your shape. Check the issues panel' }
|
|
299
|
+
: { valid: true }
|
|
266
300
|
})
|
|
267
301
|
```
|
|
268
302
|
|
|
303
|
+
`reopen` is ignored on a failing result, which reopens the shape anyway, on `'edit-finish'`, and from `onGeometryPreview` and `onGeometryChange`.
|
|
304
|
+
|
|
269
305
|
## Methods
|
|
270
306
|
|
|
271
|
-
Methods are called on the plugin instance. `newPolygon`, `newLine`, `newPoint`, `editFeature`, `addFeature`, `setStyle`, `deleteFeature`, `split`, `merge`, `setGeometry` and `recheckGeometry` all need `mapProvider.draw` to be ready — call them after [`draw:ready`](#drawready).
|
|
307
|
+
Methods are called on the plugin instance. `newPolygon`, `newLine`, `newPoint`, `editFeature`, `addFeature`, `setStyle`, `setProperties`, `deleteFeature`, `split`, `merge`, `setGeometry` and `recheckGeometry` all need `mapProvider.draw` to be ready — call them after [`draw:ready`](#drawready).
|
|
272
308
|
|
|
273
309
|
---
|
|
274
310
|
|
|
@@ -276,16 +312,17 @@ Methods are called on the plugin instance. `newPolygon`, `newLine`, `newPoint`,
|
|
|
276
312
|
|
|
277
313
|
Start drawing a new polygon.
|
|
278
314
|
|
|
279
|
-
| Argument |
|
|
280
|
-
|
|
281
|
-
| `featureId` | `string
|
|
282
|
-
| `options.snapLayers` | `string[]
|
|
283
|
-
| `options.onGeometryPreview` | `Function
|
|
284
|
-
| `options.onGeometryChange` | `Function
|
|
285
|
-
| `options.
|
|
286
|
-
| `options.
|
|
287
|
-
| `options.
|
|
288
|
-
| `options.
|
|
315
|
+
| Argument | Description |
|
|
316
|
+
|----------|-------------|
|
|
317
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID to assign the finished feature |
|
|
318
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Overrides the plugin-level `snapLayers` for this session |
|
|
319
|
+
| `options.onGeometryPreview` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryPreview` for this session — see [Validation](#validation) |
|
|
320
|
+
| `options.onGeometryChange` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
|
|
321
|
+
| `options.onGeometryFinish` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryFinish` for this session — see [Validation](#validation) |
|
|
322
|
+
| `options.stroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour for this shape |
|
|
323
|
+
| `options.fill` | **Type:** `string \| Record<string, string>`<br />Fill colour for this shape |
|
|
324
|
+
| `options.strokeWidth` | **Type:** `number`<br />Stroke width in pixels for this shape |
|
|
325
|
+
| `options.properties` | **Type:** `Object`<br />Custom GeoJSON properties to set on the finished feature |
|
|
289
326
|
|
|
290
327
|
```js
|
|
291
328
|
drawPlugin.newPolygon(crypto.randomUUID(), {
|
|
@@ -313,22 +350,23 @@ drawPlugin.newLine(crypto.randomUUID(), {
|
|
|
313
350
|
|
|
314
351
|
Start drawing a new point. Unlike `newPolygon`/`newLine`, it commits as soon as a point is placed — there's no Done step.
|
|
315
352
|
|
|
316
|
-
| Argument |
|
|
317
|
-
|
|
318
|
-
| `featureId` | `string
|
|
319
|
-
| `options.snapLayers` | `string[]
|
|
320
|
-
| `options.onGeometryPreview` | `Function
|
|
321
|
-
| `options.onGeometryChange` | `Function
|
|
322
|
-
| `options.
|
|
323
|
-
| `options.
|
|
324
|
-
| `options.
|
|
325
|
-
| `options.
|
|
326
|
-
| `options.
|
|
327
|
-
| `options.
|
|
328
|
-
| `options.
|
|
329
|
-
| `options.
|
|
330
|
-
| `options.
|
|
331
|
-
| `options.
|
|
353
|
+
| Argument | Description |
|
|
354
|
+
|----------|-------------|
|
|
355
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID to assign the finished feature |
|
|
356
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Overrides the plugin-level `snapLayers` for this session |
|
|
357
|
+
| `options.onGeometryPreview` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryPreview` for this session — see [Validation](#validation) |
|
|
358
|
+
| `options.onGeometryChange` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
|
|
359
|
+
| `options.onGeometryFinish` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryFinish` for this session — see [Validation](#validation) |
|
|
360
|
+
| `options.properties` | **Type:** `Object`<br />Custom GeoJSON properties to set on the finished feature |
|
|
361
|
+
| `options.symbol` | **Type:** `string`<br />Built-in symbol id — `'pin'`, `'circle'`, `'square'`, `'hexagon'`, `'triangle'`, or `'diamond'` |
|
|
362
|
+
| `options.symbolSvgContent` | **Type:** `string`<br />Custom SVG markup, used instead of `symbol` |
|
|
363
|
+
| `options.symbolBackgroundColor` | **Type:** `string \| Record<string, string>`<br />Symbol background colour |
|
|
364
|
+
| `options.symbolForegroundColor` | **Type:** `string \| Record<string, string>`<br />Symbol foreground colour |
|
|
365
|
+
| `options.symbolGraphic` | **Type:** `string`<br />Overrides the symbol's inner graphic (built-in name or SVG path data) |
|
|
366
|
+
| `options.symbolHaloWidth` | **Type:** `number`<br />Symbol halo width |
|
|
367
|
+
| `options.symbolViewBox` | **Type:** `string`<br />SVG `viewBox`, for use with `symbolSvgContent` |
|
|
368
|
+
| `options.symbolAnchor` | **Type:** `[number, number]`<br />Normalised `[x, y]` anchor point |
|
|
369
|
+
| `options.symbolSize` | **Type:** `'small' \| 'medium' \| 'large'`<br />Symbol size — see [Symbol Config](../api/symbol-config.md#size) |
|
|
332
370
|
|
|
333
371
|
These mirror [MarkerOptions](../api/marker-config.md#markeroptions)' `symbol`-family properties (prefixed with `symbol` here to sit alongside other feature properties) — see [Symbol Config](../api/symbol-config.md) for the full resolution order and SVG token structure. Points with no symbol config render with the plugin's default marker.
|
|
334
372
|
|
|
@@ -345,12 +383,13 @@ drawPlugin.newPoint(crypto.randomUUID(), {
|
|
|
345
383
|
|
|
346
384
|
Open an existing feature in edit mode — vertex-edit for a `Polygon`/`LineString`, single-coordinate drag for a `Point`. Returns `false` (without doing anything) if the feature doesn't exist or the plugin isn't ready yet — check the return value before assuming the edit session started.
|
|
347
385
|
|
|
348
|
-
| Argument |
|
|
349
|
-
|
|
350
|
-
| `featureId` | `string
|
|
351
|
-
| `options.snapLayers` | `string[]
|
|
352
|
-
| `options.onGeometryPreview` | `Function
|
|
353
|
-
| `options.onGeometryChange` | `Function
|
|
386
|
+
| Argument | Description |
|
|
387
|
+
|----------|-------------|
|
|
388
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the feature to edit |
|
|
389
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Overrides the plugin-level `snapLayers` for this session |
|
|
390
|
+
| `options.onGeometryPreview` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryPreview` for this session — see [Validation](#validation) |
|
|
391
|
+
| `options.onGeometryChange` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
|
|
392
|
+
| `options.onGeometryFinish` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryFinish` for this session — see [Validation](#validation) |
|
|
354
393
|
|
|
355
394
|
```js
|
|
356
395
|
const editSuccess = drawPlugin.editFeature(selectedFeatureId)
|
|
@@ -365,15 +404,17 @@ if (!editSuccess) {
|
|
|
365
404
|
|
|
366
405
|
Add a `Point`, `LineString`, or `Polygon` feature directly to the map without a draw session — e.g. loading in existing shapes on `draw:ready`.
|
|
367
406
|
|
|
368
|
-
| Argument |
|
|
369
|
-
|
|
370
|
-
| `feature.id` | `string
|
|
371
|
-
| `feature.type` | `string
|
|
372
|
-
| `feature.geometry` | `GeoJSON.Geometry
|
|
373
|
-
| `feature.stroke` | `string \| Record<string, string
|
|
374
|
-
| `feature.fill` | `string \| Record<string, string
|
|
375
|
-
| `feature.strokeWidth` | `number
|
|
376
|
-
| `feature.properties` | `Object
|
|
407
|
+
| Argument | Description |
|
|
408
|
+
|----------|-------------|
|
|
409
|
+
| `feature.id` | **Type:** `string`<br />**Required**<br />Feature ID |
|
|
410
|
+
| `feature.type` | **Type:** `string`<br />Defaults to `'Feature'` if omitted |
|
|
411
|
+
| `feature.geometry` | **Type:** `GeoJSON.Geometry`<br />**Required**<br />`Point`, `LineString`, or `Polygon` geometry |
|
|
412
|
+
| `feature.stroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour (`LineString`/`Polygon`). Replaces any stroke colours in `properties` |
|
|
413
|
+
| `feature.fill` | **Type:** `string \| Record<string, string>`<br />Fill colour (`Polygon`). Replaces any fill colours in `properties` |
|
|
414
|
+
| `feature.strokeWidth` | **Type:** `number`<br />Stroke width in pixels (`LineString`/`Polygon`). Replaces any stroke widths in `properties` |
|
|
415
|
+
| `feature.properties` | **Type:** `Object`<br />Custom GeoJSON properties — a `Point`'s `symbol`-family properties go here (see `newPoint` above) |
|
|
416
|
+
|
|
417
|
+
A feature saved from [`draw:created`](#drawcreated) or [`draw:edited`](#drawedited) keeps its style in `properties`, so it can be added back as it is.
|
|
377
418
|
|
|
378
419
|
A feature with a missing/unsupported `geometry.type` or no `geometry.coordinates` is logged as a warning and ignored.
|
|
379
420
|
|
|
@@ -403,10 +444,12 @@ interactiveMap.on('draw:ready', () => {
|
|
|
403
444
|
|
|
404
445
|
Update an existing feature's style — stroke/fill/strokeWidth or, for a `Point`, its `symbol`-family properties (see `newPoint` above). Only the keys you pass are changed; anything else the feature already has is left alone. Returns `false` if the feature doesn't exist.
|
|
405
446
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
|
409
|
-
|
|
447
|
+
Setting `stroke`, `fill` or `strokeWidth` replaces all of its values, including colours set for each map style: `setStyle(id, { stroke: '#d4351c' })` shows the new colour in every map style. Colours for each style are stored as properties named after the style, such as `strokeDark` for a style with the ID `dark`, so avoid giving your own properties names like these.
|
|
448
|
+
|
|
449
|
+
| Argument | Description |
|
|
450
|
+
|----------|-------------|
|
|
451
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the feature to update |
|
|
452
|
+
| `styleChanges` | **Type:** `Object`<br />**Required**<br />Any mix of `stroke`, `fill`, `strokeWidth`, or `symbol`-family properties |
|
|
410
453
|
|
|
411
454
|
```js
|
|
412
455
|
drawPlugin.setStyle('monument1', { symbolBackgroundColor: { outdoor: '#1d70b8', dark: '#4c9ed9' } })
|
|
@@ -414,13 +457,35 @@ drawPlugin.setStyle('monument1', { symbolBackgroundColor: { outdoor: '#1d70b8',
|
|
|
414
457
|
|
|
415
458
|
---
|
|
416
459
|
|
|
460
|
+
### `setProperties(featureId, properties)`
|
|
461
|
+
|
|
462
|
+
Add or change a feature's own properties, such as details from a form or an ID from your backend. They're kept on the feature, so later [`draw:edited`](#drawedited) events include them. Returns `false` if the feature doesn't exist.
|
|
463
|
+
|
|
464
|
+
| Argument | Description |
|
|
465
|
+
|----------|-------------|
|
|
466
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the feature to update |
|
|
467
|
+
| `properties` | **Type:** `Object`<br />**Required**<br />Properties to add or change |
|
|
468
|
+
|
|
469
|
+
- New values replace old ones with the same name. Objects are replaced, not merged.
|
|
470
|
+
- `undefined` values are skipped. `null` is kept, to clear a property.
|
|
471
|
+
- Style properties are ignored with a warning: use [`setStyle`](#setstylefeatureid-stylechanges). So are draw's internal properties.
|
|
472
|
+
- If the feature is being edited, cancelling the edit keeps the properties.
|
|
473
|
+
|
|
474
|
+
```js
|
|
475
|
+
detailsForm.addEventListener('submit', () => {
|
|
476
|
+
drawPlugin.setProperties('field-1', { name: form.name.value, landUse: form.landUse.value })
|
|
477
|
+
})
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
---
|
|
481
|
+
|
|
417
482
|
### `deleteFeature(featureIds)`
|
|
418
483
|
|
|
419
484
|
Remove one or more features from the map.
|
|
420
485
|
|
|
421
|
-
| Argument |
|
|
422
|
-
|
|
423
|
-
| `featureIds` | `string[]
|
|
486
|
+
| Argument | Description |
|
|
487
|
+
|----------|-------------|
|
|
488
|
+
| `featureIds` | **Type:** `string[]`<br />IDs of the features to remove |
|
|
424
489
|
|
|
425
490
|
```js
|
|
426
491
|
drawPlugin.deleteFeature(['test1234'])
|
|
@@ -434,10 +499,10 @@ Start drawing a line across a polygon to split it in two. Splitting is a pure co
|
|
|
434
499
|
|
|
435
500
|
Always snaps to the polygon's own outline, in addition to any layers in `snapLayers`.
|
|
436
501
|
|
|
437
|
-
| Argument |
|
|
438
|
-
|
|
439
|
-
| `featureId` | `string
|
|
440
|
-
| `options.snapLayers` | `string[]
|
|
502
|
+
| Argument | Description |
|
|
503
|
+
|----------|-------------|
|
|
504
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the polygon to split |
|
|
505
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Additional layers to snap against, on top of the polygon's own outline |
|
|
441
506
|
|
|
442
507
|
```js
|
|
443
508
|
drawPlugin.split(selectedFeatureId)
|
|
@@ -461,9 +526,9 @@ interactiveMap.on('draw:split', (event) => {
|
|
|
461
526
|
|
|
462
527
|
Merge multiple contiguous polygons into one. Like `split`, this is a pure computation — it does not touch the map. Listen for the return value or [`draw:merge`](#drawmerge) and call `deleteFeature`/`addFeature` yourself.
|
|
463
528
|
|
|
464
|
-
| Argument |
|
|
465
|
-
|
|
466
|
-
| `featureIds` | `string[]
|
|
529
|
+
| Argument | Description |
|
|
530
|
+
|----------|-------------|
|
|
531
|
+
| `featureIds` | **Type:** `string[]`<br />IDs of the polygons to merge |
|
|
467
532
|
|
|
468
533
|
**Returns:** the merged GeoJSON feature, or `null` if the merge failed (e.g. the polygons aren't actually contiguous).
|
|
469
534
|
|
|
@@ -487,9 +552,9 @@ interactiveMap.on('draw:merge', (event) => {
|
|
|
487
552
|
|
|
488
553
|
Replace the shape in the current edit session, for example with a corrected boundary from a service. The change can be undone, and is checked like any other change, with phase `'change'`. Returns `false` (without doing anything) outside an edit session, or when the geometry type differs from the shape being edited.
|
|
489
554
|
|
|
490
|
-
| Argument |
|
|
491
|
-
|
|
492
|
-
| `geometry` | `GeoJSON.Geometry
|
|
555
|
+
| Argument | Description |
|
|
556
|
+
|----------|-------------|
|
|
557
|
+
| `geometry` | **Type:** `GeoJSON.Geometry`<br />**Required**<br />The new geometry, of the same type as the shape being edited |
|
|
493
558
|
|
|
494
559
|
```js
|
|
495
560
|
drawPlugin.setGeometry(correctedBoundary)
|
|
@@ -501,9 +566,9 @@ drawPlugin.setGeometry(correctedBoundary)
|
|
|
501
566
|
|
|
502
567
|
Call `onGeometryChange` again for the current shape, unchanged, with phase `'recheck'`. Use it when your answer may have changed without the shape changing — for example after the user chooses to ignore a warning — or to retry a check that failed. Returns `false` (without doing anything) outside a draw or edit session, or before the shape has been checked.
|
|
503
568
|
|
|
504
|
-
| Argument |
|
|
505
|
-
|
|
506
|
-
| `detail` | `any
|
|
569
|
+
| Argument | Description |
|
|
570
|
+
|----------|-------------|
|
|
571
|
+
| `detail` | **Type:** `any`<br />Passed to `onGeometryChange` as `event.detail`, for example to tell an ignored warning from a retry |
|
|
507
572
|
|
|
508
573
|
```js
|
|
509
574
|
const ignoredWarnings = new Set()
|
|
@@ -595,7 +660,12 @@ Emitted once the draw plugin has initialised. Safe to call API methods from here
|
|
|
595
660
|
|
|
596
661
|
Emitted when `newPolygon`, `newLine`, or `newPoint` starts a new draw session.
|
|
597
662
|
|
|
598
|
-
**Payload:**
|
|
663
|
+
**Payload:**
|
|
664
|
+
|
|
665
|
+
| Property | Description |
|
|
666
|
+
|----------|-------------|
|
|
667
|
+
| `payload.mode` | **Type:** `'draw_polygon' \| 'draw_line' \| 'draw_point'`<br />The draw mode |
|
|
668
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the new feature |
|
|
599
669
|
|
|
600
670
|
---
|
|
601
671
|
|
|
@@ -603,13 +673,18 @@ Emitted when `newPolygon`, `newLine`, or `newPoint` starts a new draw session.
|
|
|
603
673
|
|
|
604
674
|
Emitted when `editFeature` opens an existing feature for editing.
|
|
605
675
|
|
|
606
|
-
**Payload:**
|
|
676
|
+
**Payload:**
|
|
677
|
+
|
|
678
|
+
| Property | Description |
|
|
679
|
+
|----------|-------------|
|
|
680
|
+
| `payload.mode` | **Type:** `'edit_polygon' \| 'edit_line' \| 'edit_point'`<br />The kind of shape being edited |
|
|
681
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the feature being edited |
|
|
607
682
|
|
|
608
683
|
---
|
|
609
684
|
|
|
610
685
|
### `draw:created`
|
|
611
686
|
|
|
612
|
-
Emitted when a new shape finishes drawing and passes its checks. Also fires for a shape that
|
|
687
|
+
Emitted when a new shape finishes drawing and passes its checks. Also fires for a new shape that was reopened in edit mode ([`draw:reopened`](#drawreopened)) and then finished — from the caller's perspective it's still a creation, not an edit.
|
|
613
688
|
|
|
614
689
|
**Payload:** the finished `GeoJSON.Feature`
|
|
615
690
|
|
|
@@ -625,9 +700,15 @@ Emitted when an existing feature finishes an edit session (via `editFeature`).
|
|
|
625
700
|
|
|
626
701
|
### `draw:reopened`
|
|
627
702
|
|
|
628
|
-
Emitted when a new shape is finished
|
|
703
|
+
Emitted when a new shape is finished and reopens in edit mode: because its check failed, or because a passing `onGeometryFinish` result asked to reopen it (see [Reopening a shape that passes](#reopening-a-shape-that-passes)). See [Validation](#validation).
|
|
629
704
|
|
|
630
|
-
**Payload:**
|
|
705
|
+
**Payload:**
|
|
706
|
+
|
|
707
|
+
| Property | Description |
|
|
708
|
+
|----------|-------------|
|
|
709
|
+
| `payload.feature` | **Type:** `GeoJSON.Feature`<br />The reopened shape |
|
|
710
|
+
| `payload.status` | **Type:** `'valid' \| 'invalid' \| 'error'`<br />`'valid'` if a passing result asked to reopen it, `'invalid'` if the check failed, `'error'` if it threw or rejected |
|
|
711
|
+
| `payload.reason` | **Type:** `string \| null`<br />Why the check failed, or `null` if it passed or the result gave no reason |
|
|
631
712
|
|
|
632
713
|
---
|
|
633
714
|
|
|
@@ -641,7 +722,7 @@ Emitted when the Cancel button is pressed during a draw or edit session. Cancell
|
|
|
641
722
|
|
|
642
723
|
### `draw:updated`
|
|
643
724
|
|
|
644
|
-
Emitted after a committed vertex operation (add/move/insert/delete) while editing.
|
|
725
|
+
Emitted after a committed vertex operation (add/move/insert/delete) while editing. It isn't emitted while a new shape is being drawn. To keep a panel up to date while drawing and editing, use [`onGeometryChange`](#ongeometrychangeevent-context).
|
|
645
726
|
|
|
646
727
|
**Payload:** the updated `GeoJSON.Feature`
|
|
647
728
|
|
|
@@ -651,7 +732,12 @@ Emitted after a committed vertex operation (add/move/insert/delete) while editin
|
|
|
651
732
|
|
|
652
733
|
Emitted when the selected vertex changes in edit mode.
|
|
653
734
|
|
|
654
|
-
**Payload:**
|
|
735
|
+
**Payload:**
|
|
736
|
+
|
|
737
|
+
| Property | Description |
|
|
738
|
+
|----------|-------------|
|
|
739
|
+
| `payload.index` | **Type:** `number`<br />The selected vertex, or `-1` when nothing is selected |
|
|
740
|
+
| `payload.numVertices` | **Type:** `number`<br />How many vertices the shape has |
|
|
655
741
|
|
|
656
742
|
---
|
|
657
743
|
|
|
@@ -659,7 +745,11 @@ Emitted when the selected vertex changes in edit mode.
|
|
|
659
745
|
|
|
660
746
|
Emitted when the input device changes mid-session (e.g. switching from mouse to touch and panning via the Move control) — sync your own `interfaceType` state from this if you're tracking it independently.
|
|
661
747
|
|
|
662
|
-
**Payload:**
|
|
748
|
+
**Payload:**
|
|
749
|
+
|
|
750
|
+
| Property | Description |
|
|
751
|
+
|----------|-------------|
|
|
752
|
+
| `payload.interfaceType` | **Type:** `'mouse' \| 'touch' \| 'keyboard'`<br />The input device now in use |
|
|
663
753
|
|
|
664
754
|
---
|
|
665
755
|
|
|
@@ -667,7 +757,16 @@ Emitted when the input device changes mid-session (e.g. switching from mouse to
|
|
|
667
757
|
|
|
668
758
|
Emitted whenever a check — a built-in rule, a placement rejected by `onGeometryPreview`, or an invalid result from `onGeometryChange` for the latest change — fails. Not emitted for the `'edit-start'` check of a feature that was already invalid. The `reason` is also shown as a hint toast, unless the result has its own `announcement`, or the shape simply hasn't reached its minimum vertex count yet. See [Validation](#validation).
|
|
669
759
|
|
|
670
|
-
**Payload:**
|
|
760
|
+
**Payload:**
|
|
761
|
+
|
|
762
|
+
| Property | Description |
|
|
763
|
+
|----------|-------------|
|
|
764
|
+
| `payload.feature` | **Type:** `GeoJSON.Feature`<br />The shape that failed the check |
|
|
765
|
+
| `payload.reason` | **Type:** `string`<br />Why the check failed |
|
|
766
|
+
| `payload.source` | **Type:** `'rules' \| 'callback'`<br />`'rules'` for a built-in rule, `'callback'` for `onGeometryPreview`, `onGeometryChange` or `onGeometryFinish` |
|
|
767
|
+
| `payload.phase` | **Type:** `string`<br />The phase of the check that failed. See [Validation](#validation) |
|
|
768
|
+
| `payload.mode` | **Type:** `string`<br />The draw mode |
|
|
769
|
+
| `payload.vertexIndex` | **Type:** `number`<br />The vertex involved, when there is one |
|
|
671
770
|
|
|
672
771
|
---
|
|
673
772
|
|
|
@@ -683,7 +782,11 @@ Emitted after `addFeature` adds a feature to the map.
|
|
|
683
782
|
|
|
684
783
|
Emitted after `deleteFeature` removes a feature.
|
|
685
784
|
|
|
686
|
-
**Payload:**
|
|
785
|
+
**Payload:**
|
|
786
|
+
|
|
787
|
+
| Property | Description |
|
|
788
|
+
|----------|-------------|
|
|
789
|
+
| `payload.featureId` | **Type:** `string[]`<br />The IDs passed to `deleteFeature` |
|
|
687
790
|
|
|
688
791
|
---
|
|
689
792
|
|
|
@@ -691,7 +794,25 @@ Emitted after `deleteFeature` removes a feature.
|
|
|
691
794
|
|
|
692
795
|
Emitted after `setStyle` updates a feature's style.
|
|
693
796
|
|
|
694
|
-
**Payload:**
|
|
797
|
+
**Payload:**
|
|
798
|
+
|
|
799
|
+
| Property | Description |
|
|
800
|
+
|----------|-------------|
|
|
801
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the updated feature |
|
|
802
|
+
| `payload.properties` | **Type:** `Object`<br />The style properties that changed. A removed colour is `null`, so you can merge this into your saved copy of the feature |
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
### `draw:propertieschange`
|
|
807
|
+
|
|
808
|
+
Emitted after `setProperties` updates a feature's properties.
|
|
809
|
+
|
|
810
|
+
**Payload:**
|
|
811
|
+
|
|
812
|
+
| Property | Description |
|
|
813
|
+
|----------|-------------|
|
|
814
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the updated feature |
|
|
815
|
+
| `payload.properties` | **Type:** `Object`<br />The properties that were changed |
|
|
695
816
|
|
|
696
817
|
---
|
|
697
818
|
|
|
@@ -699,7 +820,12 @@ Emitted after `setStyle` updates a feature's style.
|
|
|
699
820
|
|
|
700
821
|
Emitted when `split` computes a successful split.
|
|
701
822
|
|
|
702
|
-
**Payload:**
|
|
823
|
+
**Payload:**
|
|
824
|
+
|
|
825
|
+
| Property | Description |
|
|
826
|
+
|----------|-------------|
|
|
827
|
+
| `payload.originalFeatureId` | **Type:** `string`<br />ID of the polygon that was split |
|
|
828
|
+
| `payload.featureCollection` | **Type:** `GeoJSON.FeatureCollection`<br />The two resulting polygons |
|
|
703
829
|
|
|
704
830
|
---
|
|
705
831
|
|
|
@@ -707,7 +833,12 @@ Emitted when `split` computes a successful split.
|
|
|
707
833
|
|
|
708
834
|
Emitted when `merge` computes a successful merge.
|
|
709
835
|
|
|
710
|
-
**Payload:**
|
|
836
|
+
**Payload:**
|
|
837
|
+
|
|
838
|
+
| Property | Description |
|
|
839
|
+
|----------|-------------|
|
|
840
|
+
| `payload.originalFeatureIds` | **Type:** `string[]`<br />IDs of the polygons that were merged |
|
|
841
|
+
| `payload.feature` | **Type:** `GeoJSON.Feature`<br />The merged polygon |
|
|
711
842
|
|
|
712
843
|
```js
|
|
713
844
|
interactiveMap.on('draw:created', (feature) => {
|