@defra/interactive-map 0.0.57-alpha → 0.0.58-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/docs/assets/css/docusaurus.scss +7 -1
- package/docs/plugins/draw.md +244 -195
- package/package.json +1 -1
- package/plugins/draw/dist/esm/im-draw-plugin.js +1 -1
- package/plugins/draw/dist/umd/im-draw-plugin.js +1 -1
- package/plugins/draw/src/adapterEvents.js +13 -9
- package/plugins/draw/src/api/createNewShape.js +2 -2
- 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/split.js +3 -0
- package/plugins/draw/src/api/split.test.js +5 -0
- package/plugins/draw/src/events.js +18 -14
- package/plugins/draw/src/events.test.js +71 -0
- package/plugins/draw/src/validation/commitChecks.js +3 -1
- package/plugins/draw/src/validation/commitChecks.test.js +6 -2
package/docs/plugins/draw.md
CHANGED
|
@@ -87,28 +87,36 @@ Plugin-level check, called after each committed change to a shape. Can return a
|
|
|
87
87
|
|
|
88
88
|
---
|
|
89
89
|
|
|
90
|
+
### `onGeometryFinish`
|
|
91
|
+
|
|
92
|
+
**Type:** `Function`
|
|
93
|
+
|
|
94
|
+
Plugin-level check, called when a shape is finished. Can return a Promise. Can be overridden per call. See [`onGeometryFinish`](#ongeometryfinishevent-context).
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
90
98
|
### Colour and size overrides
|
|
91
99
|
|
|
92
100
|
> [!NOTE]
|
|
93
101
|
> Each colour accepts a plain colour string or a style-keyed object (e.g. `{ light: '#1d70b8', dark: '#ffffff' }`).
|
|
94
102
|
|
|
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`
|
|
103
|
+
| Property | Description |
|
|
104
|
+
|----------|-------------|
|
|
105
|
+
| `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 |
|
|
106
|
+
| `shapeFill` | **Type:** `string \| Record<string, string>`<br />Default fill colour for an inactive shape, when the feature sets no `fill` of its own |
|
|
107
|
+
| `strokeWidth` | **Type:** `number`<br />**Default:** `2`<br />Default stroke width in pixels |
|
|
108
|
+
| `editStroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour of the shape currently being drawn or edited |
|
|
109
|
+
| `editFill` | **Type:** `string \| Record<string, string>`<br />Fill colour of the shape currently being drawn or edited |
|
|
110
|
+
| `editVertex` | **Type:** `string \| Record<string, string>`<br />Colour of placed, unselected vertex handles |
|
|
111
|
+
| `editMidpoint` | **Type:** `string \| Record<string, string>`<br />Colour of the midpoint handles used to insert a new vertex on an edge |
|
|
112
|
+
| `editActive` | **Type:** `string \| Record<string, string>`<br />Colour of the currently selected/active vertex handle |
|
|
113
|
+
| `editHalo` | **Type:** `string \| Record<string, string>`<br />Colour of the halo drawn behind vertex/midpoint handles for contrast |
|
|
114
|
+
| `invalidStroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour of the dashed outline shown while the shape fails validation |
|
|
115
|
+
| `splitValid` | **Type:** `string \| Record<string, string>`<br />Colour of the split line while it would produce a valid split |
|
|
116
|
+
| `splitInvalid` | **Type:** `string \| Record<string, string>`<br />Colour of the split line while it would not produce a valid split |
|
|
117
|
+
| `snapVertex` | **Type:** `string \| Record<string, string>`<br />Colour of the snap indicator shown over a vertex |
|
|
118
|
+
| `snapEdge` | **Type:** `string \| Record<string, string>`<br />Colour of the snap indicator shown over an edge |
|
|
119
|
+
| `snapRadius` | **Type:** `number`<br />**Default:** `12`<br />Snap tolerance in pixels |
|
|
112
120
|
|
|
113
121
|
```js
|
|
114
122
|
createDrawPlugin({
|
|
@@ -121,151 +129,136 @@ createDrawPlugin({
|
|
|
121
129
|
|
|
122
130
|
## Validation
|
|
123
131
|
|
|
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.
|
|
132
|
+
Every change is checked against the built-in rules, then against your own callbacks if you set them.
|
|
128
133
|
|
|
129
134
|
### Built-in rules
|
|
130
135
|
|
|
131
|
-
| Rule |
|
|
132
|
-
|
|
133
|
-
| Minimum vertices |
|
|
134
|
-
| Self-intersection |
|
|
135
|
-
|
|
|
136
|
-
| Non-zero area | Polygon | Gates the Done button — a collinear/degenerate ring can't be finished |
|
|
137
|
-
|
|
138
|
-
Rule failures gate the Done button (the shape can pass through interim invalid states while being built or reshaped, shown with a dashed outline) except the placement-time self-intersection check, which is a hard veto — that specific vertex is rejected and never placed.
|
|
136
|
+
| Rule | Description |
|
|
137
|
+
|------|-------------|
|
|
138
|
+
| Minimum vertices | A polygon needs 3 vertices and a line 2 before it can be finished |
|
|
139
|
+
| 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 |
|
|
140
|
+
| Non-zero area | A flat polygon, with all its vertices in a line, can't be finished |
|
|
139
141
|
|
|
140
|
-
|
|
142
|
+
While a rule fails, the shape has a dashed outline.
|
|
141
143
|
|
|
142
|
-
|
|
144
|
+
### Callbacks
|
|
143
145
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
measurements.update(event.feature)
|
|
150
|
-
return rules.check(event, context)
|
|
151
|
-
}
|
|
152
|
-
})
|
|
153
|
-
```
|
|
146
|
+
| Callback | Description |
|
|
147
|
+
|----------|-------------|
|
|
148
|
+
| [`onGeometryPreview`](#ongeometrypreviewevent) | Live checks while a shape is drawn or dragged, and before a vertex is placed. Must answer straight away |
|
|
149
|
+
| [`onGeometryChange`](#ongeometrychangeevent-context) | After each change. Can return a Promise. The latest result enables or disables Done |
|
|
150
|
+
| [`onGeometryFinish`](#ongeometryfinishevent-context) | When a shape is finished. Can return a Promise. Decides whether the shape is created, or the edit finishes |
|
|
154
151
|
|
|
155
|
-
|
|
152
|
+
#### Setting the callbacks
|
|
156
153
|
|
|
157
|
-
|
|
154
|
+
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.
|
|
158
155
|
|
|
159
|
-
|
|
160
|
-
|---|---|
|
|
161
|
-
| `true` / `undefined` | Valid |
|
|
162
|
-
| `false` | Invalid, no reason shown |
|
|
163
|
-
| `{ valid, reason, announcement, recheckOnFinish }` | Valid or invalid, with these optional fields |
|
|
156
|
+
They aren't used by `split`, `merge`, `addFeature` or `setStyle`.
|
|
164
157
|
|
|
165
|
-
|
|
166
|
-
|---|---|---|
|
|
167
|
-
| `reason` | `string` | Why the shape is invalid. Shown as a hint toast and sent with [`draw:geometryinvalid`](#drawgeometryinvalid) |
|
|
168
|
-
| `announcement` | `string` | Announced to screen readers instead of draw's own message, whether the result is valid or not. When set, `reason` isn't shown as a hint toast, so you can present the issue yourself. From `onGeometryPreview`, only a rejected placement is announced |
|
|
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) |
|
|
158
|
+
#### What they return
|
|
170
159
|
|
|
171
|
-
|
|
160
|
+
| Value | Description |
|
|
161
|
+
|-------|-------------|
|
|
162
|
+
| `true` | Valid |
|
|
163
|
+
| `undefined` | Valid |
|
|
164
|
+
| `false` | Invalid, with no reason shown |
|
|
165
|
+
| `result.valid` | Whether the shape is valid |
|
|
166
|
+
| `result.reason` | Why the shape is invalid. Shown as a hint and sent with [`draw:geometryinvalid`](#drawgeometryinvalid) |
|
|
167
|
+
| `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
168
|
|
|
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 |
|
|
169
|
+
#### What they receive
|
|
180
170
|
|
|
181
|
-
|
|
171
|
+
| Property | Description |
|
|
172
|
+
|----------|-------------|
|
|
173
|
+
| `event.feature` | The shape being checked, as a GeoJSON feature |
|
|
174
|
+
| `event.phase` | Why the callback was called. See each callback below |
|
|
175
|
+
| `event.mode` | The draw mode: `'draw_polygon'`, `'draw_line'`, `'draw_point'`, `'edit_vertex'` or `'edit_point'` |
|
|
176
|
+
| `event.vertexIndex` | The vertex being placed or changed. Only on `'place'`, and on a `'change'` to a single vertex |
|
|
177
|
+
| `event.numVertices` | How many vertices have been placed, not counting the one following the pointer. Only on `'preview'` |
|
|
178
|
+
| `event.detail` | The `detail` passed to [`recheckGeometry`](#recheckgeometrydetail). Only on `'recheck'` |
|
|
179
|
+
| `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` |
|
|
180
|
+
| `context.revision` | A number that increases with every check. Not passed to `onGeometryPreview` |
|
|
182
181
|
|
|
183
|
-
|
|
182
|
+
#### Debouncing
|
|
184
183
|
|
|
185
|
-
|
|
184
|
+
Debouncing and timeouts are up to you. Waiting on `signal` gives a debounce that cancels itself when the shape changes again:
|
|
186
185
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
186
|
+
```js
|
|
187
|
+
const wait = (ms, signal) => new Promise((resolve, reject) => {
|
|
188
|
+
const timer = setTimeout(resolve, ms)
|
|
189
|
+
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason) }, { once: true })
|
|
190
|
+
})
|
|
191
191
|
|
|
192
|
-
|
|
192
|
+
createDrawPlugin({
|
|
193
|
+
onGeometryPreview: (event) => ({
|
|
194
|
+
valid: isEastOfWalesBorder(event.feature.geometry),
|
|
195
|
+
reason: 'Points must be placed east of the England/Wales border'
|
|
196
|
+
}),
|
|
197
|
+
onGeometryChange: async ({ feature }, { signal }) => {
|
|
198
|
+
infoPanel.update(measureArea(feature))
|
|
199
|
+
await wait(300, signal)
|
|
200
|
+
const response = await fetch('/api/boundary-checks', { method: 'POST', body: JSON.stringify(feature), signal })
|
|
201
|
+
return response.json() // { valid, reason }
|
|
202
|
+
}
|
|
203
|
+
})
|
|
204
|
+
```
|
|
193
205
|
|
|
194
|
-
|
|
206
|
+
## `onGeometryPreview(event)`
|
|
195
207
|
|
|
196
|
-
**Signature:** `
|
|
208
|
+
**Signature:** `onGeometryPreview(event) => result`
|
|
197
209
|
|
|
198
|
-
|
|
210
|
+
Must answer straight away. A Promise counts as valid. It runs on every frame of a drag, so keep it quick.
|
|
199
211
|
|
|
200
212
|
| Phase | When |
|
|
201
213
|
|-------|------|
|
|
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` |
|
|
214
|
+
| `'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 |
|
|
215
|
+
| `'place'` | Before a vertex is placed by a click, tap, <kbd>Enter</kbd> or Add point. An invalid result rejects the vertex |
|
|
207
216
|
|
|
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 |
|
|
217
|
+
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.
|
|
212
218
|
|
|
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.
|
|
219
|
+
## `onGeometryChange(event, context)`
|
|
217
220
|
|
|
218
|
-
|
|
221
|
+
**Signature:** `onGeometryChange(event, context) => result | Promise<result>`
|
|
219
222
|
|
|
220
|
-
|
|
223
|
+
Called after each change to a shape.
|
|
221
224
|
|
|
222
|
-
|
|
225
|
+
| Phase | When |
|
|
226
|
+
|-------|------|
|
|
227
|
+
| `'change'` | The shape changed, including with [`setGeometry`](#setgeometrygeometry) or undo |
|
|
228
|
+
| `'edit-start'` | `editFeature` opened the shape |
|
|
229
|
+
| `'recheck'` | [`recheckGeometry`](#recheckgeometrydetail) was called |
|
|
230
|
+
| `'create'` | Only without `onGeometryFinish`. A new shape was finished without a passing result, such as a new point |
|
|
231
|
+
| `'edit-finish'` | Only without `onGeometryFinish`, when the last result set `recheckOnFinish`. Done was pressed on an edit |
|
|
223
232
|
|
|
224
|
-
|
|
225
|
-
createDrawPlugin({
|
|
226
|
-
onGeometryChange: ({ feature, phase }, { signal }) => {
|
|
227
|
-
// Update the panel without waiting for it, so finishing never waits on it.
|
|
228
|
-
// The signal cancels the request if the shape changes again.
|
|
229
|
-
contextPanel.update(feature, { signal })
|
|
233
|
+
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.
|
|
230
234
|
|
|
231
|
-
|
|
232
|
-
if (phase === 'change' || phase === 'edit-start') {
|
|
233
|
-
return { valid: true, recheckOnFinish: true }
|
|
234
|
-
}
|
|
235
|
-
// 'create', 'edit-finish' and 'recheck' are checked by the service
|
|
236
|
-
return validateWithService(feature, { signal })
|
|
237
|
-
}
|
|
238
|
-
})
|
|
239
|
-
```
|
|
235
|
+
## `onGeometryFinish(event, context)`
|
|
240
236
|
|
|
241
|
-
|
|
237
|
+
**Signature:** `onGeometryFinish(event, context) => result | Promise<result>`
|
|
242
238
|
|
|
243
|
-
|
|
239
|
+
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`.
|
|
244
240
|
|
|
245
|
-
|
|
241
|
+
| Phase | When |
|
|
242
|
+
|-------|------|
|
|
243
|
+
| `'create'` | A new shape or point was finished |
|
|
244
|
+
| `'edit-finish'` | Done was pressed on an edit |
|
|
246
245
|
|
|
247
|
-
|
|
246
|
+
Draw waits for the result. A new shape that fails 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.
|
|
248
247
|
|
|
249
|
-
|
|
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
|
-
})
|
|
248
|
+
This updates a panel on every change, and validates the shape once it's finished:
|
|
254
249
|
|
|
250
|
+
```js
|
|
255
251
|
createDrawPlugin({
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
}
|
|
260
|
-
|
|
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
|
-
}
|
|
252
|
+
// Returns nothing, so every change counts as valid
|
|
253
|
+
onGeometryChange: ({ feature }, { signal }) => {
|
|
254
|
+
contextPanel.update(feature, { signal })
|
|
255
|
+
},
|
|
256
|
+
onGeometryFinish: ({ feature }, { signal }) => validateWithService(feature, { signal })
|
|
266
257
|
})
|
|
267
258
|
```
|
|
268
259
|
|
|
260
|
+
Don't `await` the panel update. `onGeometryChange` would then be pending until the panel replies, and finishing would wait for it.
|
|
261
|
+
|
|
269
262
|
## Methods
|
|
270
263
|
|
|
271
264
|
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).
|
|
@@ -276,16 +269,17 @@ Methods are called on the plugin instance. `newPolygon`, `newLine`, `newPoint`,
|
|
|
276
269
|
|
|
277
270
|
Start drawing a new polygon.
|
|
278
271
|
|
|
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.
|
|
272
|
+
| Argument | Description |
|
|
273
|
+
|----------|-------------|
|
|
274
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID to assign the finished feature |
|
|
275
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Overrides the plugin-level `snapLayers` for this session |
|
|
276
|
+
| `options.onGeometryPreview` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryPreview` for this session — see [Validation](#validation) |
|
|
277
|
+
| `options.onGeometryChange` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
|
|
278
|
+
| `options.onGeometryFinish` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryFinish` for this session — see [Validation](#validation) |
|
|
279
|
+
| `options.stroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour for this shape |
|
|
280
|
+
| `options.fill` | **Type:** `string \| Record<string, string>`<br />Fill colour for this shape |
|
|
281
|
+
| `options.strokeWidth` | **Type:** `number`<br />Stroke width in pixels for this shape |
|
|
282
|
+
| `options.properties` | **Type:** `Object`<br />Custom GeoJSON properties to set on the finished feature |
|
|
289
283
|
|
|
290
284
|
```js
|
|
291
285
|
drawPlugin.newPolygon(crypto.randomUUID(), {
|
|
@@ -313,22 +307,23 @@ drawPlugin.newLine(crypto.randomUUID(), {
|
|
|
313
307
|
|
|
314
308
|
Start drawing a new point. Unlike `newPolygon`/`newLine`, it commits as soon as a point is placed — there's no Done step.
|
|
315
309
|
|
|
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.
|
|
310
|
+
| Argument | Description |
|
|
311
|
+
|----------|-------------|
|
|
312
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID to assign the finished feature |
|
|
313
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Overrides the plugin-level `snapLayers` for this session |
|
|
314
|
+
| `options.onGeometryPreview` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryPreview` for this session — see [Validation](#validation) |
|
|
315
|
+
| `options.onGeometryChange` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
|
|
316
|
+
| `options.onGeometryFinish` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryFinish` for this session — see [Validation](#validation) |
|
|
317
|
+
| `options.properties` | **Type:** `Object`<br />Custom GeoJSON properties to set on the finished feature |
|
|
318
|
+
| `options.symbol` | **Type:** `string`<br />Built-in symbol id — `'pin'`, `'circle'`, `'square'`, `'hexagon'`, `'triangle'`, or `'diamond'` |
|
|
319
|
+
| `options.symbolSvgContent` | **Type:** `string`<br />Custom SVG markup, used instead of `symbol` |
|
|
320
|
+
| `options.symbolBackgroundColor` | **Type:** `string \| Record<string, string>`<br />Symbol background colour |
|
|
321
|
+
| `options.symbolForegroundColor` | **Type:** `string \| Record<string, string>`<br />Symbol foreground colour |
|
|
322
|
+
| `options.symbolGraphic` | **Type:** `string`<br />Overrides the symbol's inner graphic (built-in name or SVG path data) |
|
|
323
|
+
| `options.symbolHaloWidth` | **Type:** `number`<br />Symbol halo width |
|
|
324
|
+
| `options.symbolViewBox` | **Type:** `string`<br />SVG `viewBox`, for use with `symbolSvgContent` |
|
|
325
|
+
| `options.symbolAnchor` | **Type:** `[number, number]`<br />Normalised `[x, y]` anchor point |
|
|
326
|
+
| `options.symbolSize` | **Type:** `'small' \| 'medium' \| 'large'`<br />Symbol size — see [Symbol Config](../api/symbol-config.md#size) |
|
|
332
327
|
|
|
333
328
|
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
329
|
|
|
@@ -345,12 +340,13 @@ drawPlugin.newPoint(crypto.randomUUID(), {
|
|
|
345
340
|
|
|
346
341
|
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
342
|
|
|
348
|
-
| Argument |
|
|
349
|
-
|
|
350
|
-
| `featureId` | `string
|
|
351
|
-
| `options.snapLayers` | `string[]
|
|
352
|
-
| `options.onGeometryPreview` | `Function
|
|
353
|
-
| `options.onGeometryChange` | `Function
|
|
343
|
+
| Argument | Description |
|
|
344
|
+
|----------|-------------|
|
|
345
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the feature to edit |
|
|
346
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Overrides the plugin-level `snapLayers` for this session |
|
|
347
|
+
| `options.onGeometryPreview` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryPreview` for this session — see [Validation](#validation) |
|
|
348
|
+
| `options.onGeometryChange` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
|
|
349
|
+
| `options.onGeometryFinish` | **Type:** `Function`<br />Replaces the plugin-level `onGeometryFinish` for this session — see [Validation](#validation) |
|
|
354
350
|
|
|
355
351
|
```js
|
|
356
352
|
const editSuccess = drawPlugin.editFeature(selectedFeatureId)
|
|
@@ -365,15 +361,15 @@ if (!editSuccess) {
|
|
|
365
361
|
|
|
366
362
|
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
363
|
|
|
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
|
|
364
|
+
| Argument | Description |
|
|
365
|
+
|----------|-------------|
|
|
366
|
+
| `feature.id` | **Type:** `string`<br />**Required**<br />Feature ID |
|
|
367
|
+
| `feature.type` | **Type:** `string`<br />Defaults to `'Feature'` if omitted |
|
|
368
|
+
| `feature.geometry` | **Type:** `GeoJSON.Geometry`<br />**Required**<br />`Point`, `LineString`, or `Polygon` geometry |
|
|
369
|
+
| `feature.stroke` | **Type:** `string \| Record<string, string>`<br />Stroke colour (`LineString`/`Polygon`) |
|
|
370
|
+
| `feature.fill` | **Type:** `string \| Record<string, string>`<br />Fill colour (`Polygon`) |
|
|
371
|
+
| `feature.strokeWidth` | **Type:** `number`<br />Stroke width in pixels (`LineString`/`Polygon`) |
|
|
372
|
+
| `feature.properties` | **Type:** `Object`<br />Custom GeoJSON properties — a `Point`'s `symbol`-family properties go here (see `newPoint` above) |
|
|
377
373
|
|
|
378
374
|
A feature with a missing/unsupported `geometry.type` or no `geometry.coordinates` is logged as a warning and ignored.
|
|
379
375
|
|
|
@@ -403,10 +399,10 @@ interactiveMap.on('draw:ready', () => {
|
|
|
403
399
|
|
|
404
400
|
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
401
|
|
|
406
|
-
| Argument |
|
|
407
|
-
|
|
408
|
-
| `featureId` | `string
|
|
409
|
-
| `styleChanges` | `Object
|
|
402
|
+
| Argument | Description |
|
|
403
|
+
|----------|-------------|
|
|
404
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the feature to update |
|
|
405
|
+
| `styleChanges` | **Type:** `Object`<br />**Required**<br />Any mix of `stroke`, `fill`, `strokeWidth`, or `symbol`-family properties |
|
|
410
406
|
|
|
411
407
|
```js
|
|
412
408
|
drawPlugin.setStyle('monument1', { symbolBackgroundColor: { outdoor: '#1d70b8', dark: '#4c9ed9' } })
|
|
@@ -418,9 +414,9 @@ drawPlugin.setStyle('monument1', { symbolBackgroundColor: { outdoor: '#1d70b8',
|
|
|
418
414
|
|
|
419
415
|
Remove one or more features from the map.
|
|
420
416
|
|
|
421
|
-
| Argument |
|
|
422
|
-
|
|
423
|
-
| `featureIds` | `string[]
|
|
417
|
+
| Argument | Description |
|
|
418
|
+
|----------|-------------|
|
|
419
|
+
| `featureIds` | **Type:** `string[]`<br />IDs of the features to remove |
|
|
424
420
|
|
|
425
421
|
```js
|
|
426
422
|
drawPlugin.deleteFeature(['test1234'])
|
|
@@ -434,10 +430,10 @@ Start drawing a line across a polygon to split it in two. Splitting is a pure co
|
|
|
434
430
|
|
|
435
431
|
Always snaps to the polygon's own outline, in addition to any layers in `snapLayers`.
|
|
436
432
|
|
|
437
|
-
| Argument |
|
|
438
|
-
|
|
439
|
-
| `featureId` | `string
|
|
440
|
-
| `options.snapLayers` | `string[]
|
|
433
|
+
| Argument | Description |
|
|
434
|
+
|----------|-------------|
|
|
435
|
+
| `featureId` | **Type:** `string`<br />**Required**<br />ID of the polygon to split |
|
|
436
|
+
| `options.snapLayers` | **Type:** `string[]`<br />Additional layers to snap against, on top of the polygon's own outline |
|
|
441
437
|
|
|
442
438
|
```js
|
|
443
439
|
drawPlugin.split(selectedFeatureId)
|
|
@@ -461,9 +457,9 @@ interactiveMap.on('draw:split', (event) => {
|
|
|
461
457
|
|
|
462
458
|
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
459
|
|
|
464
|
-
| Argument |
|
|
465
|
-
|
|
466
|
-
| `featureIds` | `string[]
|
|
460
|
+
| Argument | Description |
|
|
461
|
+
|----------|-------------|
|
|
462
|
+
| `featureIds` | **Type:** `string[]`<br />IDs of the polygons to merge |
|
|
467
463
|
|
|
468
464
|
**Returns:** the merged GeoJSON feature, or `null` if the merge failed (e.g. the polygons aren't actually contiguous).
|
|
469
465
|
|
|
@@ -487,9 +483,9 @@ interactiveMap.on('draw:merge', (event) => {
|
|
|
487
483
|
|
|
488
484
|
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
485
|
|
|
490
|
-
| Argument |
|
|
491
|
-
|
|
492
|
-
| `geometry` | `GeoJSON.Geometry
|
|
486
|
+
| Argument | Description |
|
|
487
|
+
|----------|-------------|
|
|
488
|
+
| `geometry` | **Type:** `GeoJSON.Geometry`<br />**Required**<br />The new geometry, of the same type as the shape being edited |
|
|
493
489
|
|
|
494
490
|
```js
|
|
495
491
|
drawPlugin.setGeometry(correctedBoundary)
|
|
@@ -501,9 +497,9 @@ drawPlugin.setGeometry(correctedBoundary)
|
|
|
501
497
|
|
|
502
498
|
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
499
|
|
|
504
|
-
| Argument |
|
|
505
|
-
|
|
506
|
-
| `detail` | `any
|
|
500
|
+
| Argument | Description |
|
|
501
|
+
|----------|-------------|
|
|
502
|
+
| `detail` | **Type:** `any`<br />Passed to `onGeometryChange` as `event.detail`, for example to tell an ignored warning from a retry |
|
|
507
503
|
|
|
508
504
|
```js
|
|
509
505
|
const ignoredWarnings = new Set()
|
|
@@ -595,7 +591,12 @@ Emitted once the draw plugin has initialised. Safe to call API methods from here
|
|
|
595
591
|
|
|
596
592
|
Emitted when `newPolygon`, `newLine`, or `newPoint` starts a new draw session.
|
|
597
593
|
|
|
598
|
-
**Payload:**
|
|
594
|
+
**Payload:**
|
|
595
|
+
|
|
596
|
+
| Property | Description |
|
|
597
|
+
|----------|-------------|
|
|
598
|
+
| `payload.mode` | **Type:** `'draw_polygon' \| 'draw_line' \| 'draw_point'`<br />The draw mode |
|
|
599
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the new feature |
|
|
599
600
|
|
|
600
601
|
---
|
|
601
602
|
|
|
@@ -603,7 +604,12 @@ Emitted when `newPolygon`, `newLine`, or `newPoint` starts a new draw session.
|
|
|
603
604
|
|
|
604
605
|
Emitted when `editFeature` opens an existing feature for editing.
|
|
605
606
|
|
|
606
|
-
**Payload:**
|
|
607
|
+
**Payload:**
|
|
608
|
+
|
|
609
|
+
| Property | Description |
|
|
610
|
+
|----------|-------------|
|
|
611
|
+
| `payload.mode` | **Type:** `'edit_polygon' \| 'edit_line' \| 'edit_point'`<br />The kind of shape being edited |
|
|
612
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the feature being edited |
|
|
607
613
|
|
|
608
614
|
---
|
|
609
615
|
|
|
@@ -625,9 +631,15 @@ Emitted when an existing feature finishes an edit session (via `editFeature`).
|
|
|
625
631
|
|
|
626
632
|
### `draw:reopened`
|
|
627
633
|
|
|
628
|
-
Emitted when a new shape is finished, its
|
|
634
|
+
Emitted when a new shape is finished, its check fails, and it reopens in edit mode. See [Validation](#validation).
|
|
635
|
+
|
|
636
|
+
**Payload:**
|
|
629
637
|
|
|
630
|
-
|
|
638
|
+
| Property | Description |
|
|
639
|
+
|----------|-------------|
|
|
640
|
+
| `payload.feature` | **Type:** `GeoJSON.Feature`<br />The reopened shape |
|
|
641
|
+
| `payload.status` | **Type:** `'invalid' \| 'error'`<br />`'invalid'` if the check failed, `'error'` if it threw or rejected |
|
|
642
|
+
| `payload.reason` | **Type:** `string \| null`<br />Why the check failed, or `null` if the result gave no reason |
|
|
631
643
|
|
|
632
644
|
---
|
|
633
645
|
|
|
@@ -641,7 +653,7 @@ Emitted when the Cancel button is pressed during a draw or edit session. Cancell
|
|
|
641
653
|
|
|
642
654
|
### `draw:updated`
|
|
643
655
|
|
|
644
|
-
Emitted after a committed vertex operation (add/move/insert/delete) while editing.
|
|
656
|
+
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
657
|
|
|
646
658
|
**Payload:** the updated `GeoJSON.Feature`
|
|
647
659
|
|
|
@@ -651,7 +663,12 @@ Emitted after a committed vertex operation (add/move/insert/delete) while editin
|
|
|
651
663
|
|
|
652
664
|
Emitted when the selected vertex changes in edit mode.
|
|
653
665
|
|
|
654
|
-
**Payload:**
|
|
666
|
+
**Payload:**
|
|
667
|
+
|
|
668
|
+
| Property | Description |
|
|
669
|
+
|----------|-------------|
|
|
670
|
+
| `payload.index` | **Type:** `number`<br />The selected vertex, or `-1` when nothing is selected |
|
|
671
|
+
| `payload.numVertices` | **Type:** `number`<br />How many vertices the shape has |
|
|
655
672
|
|
|
656
673
|
---
|
|
657
674
|
|
|
@@ -659,7 +676,11 @@ Emitted when the selected vertex changes in edit mode.
|
|
|
659
676
|
|
|
660
677
|
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
678
|
|
|
662
|
-
**Payload:**
|
|
679
|
+
**Payload:**
|
|
680
|
+
|
|
681
|
+
| Property | Description |
|
|
682
|
+
|----------|-------------|
|
|
683
|
+
| `payload.interfaceType` | **Type:** `'mouse' \| 'touch' \| 'keyboard'`<br />The input device now in use |
|
|
663
684
|
|
|
664
685
|
---
|
|
665
686
|
|
|
@@ -667,7 +688,16 @@ Emitted when the input device changes mid-session (e.g. switching from mouse to
|
|
|
667
688
|
|
|
668
689
|
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
690
|
|
|
670
|
-
**Payload:**
|
|
691
|
+
**Payload:**
|
|
692
|
+
|
|
693
|
+
| Property | Description |
|
|
694
|
+
|----------|-------------|
|
|
695
|
+
| `payload.feature` | **Type:** `GeoJSON.Feature`<br />The shape that failed the check |
|
|
696
|
+
| `payload.reason` | **Type:** `string`<br />Why the check failed |
|
|
697
|
+
| `payload.source` | **Type:** `'rules' \| 'callback'`<br />`'rules'` for a built-in rule, `'callback'` for `onGeometryPreview`, `onGeometryChange` or `onGeometryFinish` |
|
|
698
|
+
| `payload.phase` | **Type:** `string`<br />The phase of the check that failed. See [Validation](#validation) |
|
|
699
|
+
| `payload.mode` | **Type:** `string`<br />The draw mode |
|
|
700
|
+
| `payload.vertexIndex` | **Type:** `number`<br />The vertex involved, when there is one |
|
|
671
701
|
|
|
672
702
|
---
|
|
673
703
|
|
|
@@ -683,7 +713,11 @@ Emitted after `addFeature` adds a feature to the map.
|
|
|
683
713
|
|
|
684
714
|
Emitted after `deleteFeature` removes a feature.
|
|
685
715
|
|
|
686
|
-
**Payload:**
|
|
716
|
+
**Payload:**
|
|
717
|
+
|
|
718
|
+
| Property | Description |
|
|
719
|
+
|----------|-------------|
|
|
720
|
+
| `payload.featureId` | **Type:** `string[]`<br />The IDs passed to `deleteFeature` |
|
|
687
721
|
|
|
688
722
|
---
|
|
689
723
|
|
|
@@ -691,7 +725,12 @@ Emitted after `deleteFeature` removes a feature.
|
|
|
691
725
|
|
|
692
726
|
Emitted after `setStyle` updates a feature's style.
|
|
693
727
|
|
|
694
|
-
**Payload:**
|
|
728
|
+
**Payload:**
|
|
729
|
+
|
|
730
|
+
| Property | Description |
|
|
731
|
+
|----------|-------------|
|
|
732
|
+
| `payload.featureId` | **Type:** `string`<br />ID of the updated feature |
|
|
733
|
+
| `payload.properties` | **Type:** `Object`<br />The style and symbol properties that were applied |
|
|
695
734
|
|
|
696
735
|
---
|
|
697
736
|
|
|
@@ -699,7 +738,12 @@ Emitted after `setStyle` updates a feature's style.
|
|
|
699
738
|
|
|
700
739
|
Emitted when `split` computes a successful split.
|
|
701
740
|
|
|
702
|
-
**Payload:**
|
|
741
|
+
**Payload:**
|
|
742
|
+
|
|
743
|
+
| Property | Description |
|
|
744
|
+
|----------|-------------|
|
|
745
|
+
| `payload.originalFeatureId` | **Type:** `string`<br />ID of the polygon that was split |
|
|
746
|
+
| `payload.featureCollection` | **Type:** `GeoJSON.FeatureCollection`<br />The two resulting polygons |
|
|
703
747
|
|
|
704
748
|
---
|
|
705
749
|
|
|
@@ -707,7 +751,12 @@ Emitted when `split` computes a successful split.
|
|
|
707
751
|
|
|
708
752
|
Emitted when `merge` computes a successful merge.
|
|
709
753
|
|
|
710
|
-
**Payload:**
|
|
754
|
+
**Payload:**
|
|
755
|
+
|
|
756
|
+
| Property | Description |
|
|
757
|
+
|----------|-------------|
|
|
758
|
+
| `payload.originalFeatureIds` | **Type:** `string[]`<br />IDs of the polygons that were merged |
|
|
759
|
+
| `payload.feature` | **Type:** `GeoJSON.Feature`<br />The merged polygon |
|
|
711
760
|
|
|
712
761
|
```js
|
|
713
762
|
interactiveMap.on('draw:created', (feature) => {
|