Skip to content

Commit 6ccd003

Browse files
tomhickstomhicks
authored
Improve explanations in controller docs (#112)
* Improve explanations in controller docs * docs(changeset): Improve controller method documentation
1 parent 3627491 commit 6ccd003

File tree

17 files changed

+813
-350
lines changed

17 files changed

+813
-350
lines changed

‎.changeset/tall-beds-scream.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@feltmaps/js-sdk": minor
3+
---
4+
5+
Improve controller method documentation

‎docs/Elements/ElementsController.md

Lines changed: 84 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ map, and make changes to their visibility.
1515
1616
Get a single element from the map by its id.
1717

18+
Use this method when you know the specific ID of an element and want to retrieve
19+
its current state. This is more efficient than getting all elements and filtering.
20+
1821
### Parameters
1922

2023
| Parameter | Type | Description |
@@ -25,7 +28,7 @@ Get a single element from the map by its id.
2528

2629
`Promise`\<`null` | [`Element`](Element.md)>
2730

28-
The requested element.
31+
A promise that resolves to the requested element, or `null` if not found.
2932

3033
### Example
3134

@@ -56,6 +59,9 @@ property of the element, with some differences:
5659

5760
* Text, Note and Image elements do not return geometry, so will return `null`.
5861

62+
Use this method when you need the geometric representation of an element for
63+
spatial analysis or visualization purposes.
64+
5965
### Parameters
6066

6167
| Parameter | Type | Description |
@@ -66,6 +72,8 @@ property of the element, with some differences:
6672

6773
`Promise`\<`null` | [`GeoJsonGeometry`](../Shared/GeoJsonGeometry.md)>
6874

75+
A promise that resolves to the element's geometry in GeoJSON format, or `null` if the element has no geometry.
76+
6977
### Example
7078

7179
```typescript
@@ -82,17 +90,20 @@ console.log(geometry?.type, geometry?.coordinates);
8290
Gets elements from the map, according to the constraints supplied. If no
8391
constraints are supplied, all elements will be returned.
8492

93+
Use this method to retrieve multiple elements, optionally filtered by constraints.
94+
This is useful for bulk operations or when you need to analyze all elements on the map.
95+
8596
### Parameters
8697

87-
| Parameter | Type | Description |
88-
| ------------- | --------------------------------------------------- | --------------------------------------------------------------- |
89-
| `constraint`? | [`GetElementsConstraint`](GetElementsConstraint.md) | The constraints to apply to the elements returned from the map. |
98+
| Parameter | Type | Description |
99+
| ------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
100+
| `constraint`? | [`GetElementsConstraint`](GetElementsConstraint.md) | Optional constraints to apply to the elements returned from the map. |
90101

91102
### Returns
92103

93104
`Promise`\<(`null` | [`Element`](Element.md))\[]>
94105

95-
All elements on the map.
106+
A promise that resolves to an array of elements, ordered by the order specified in Felt.
96107

97108
### Remarks
98109

@@ -114,17 +125,20 @@ const elements = await felt.getElements();
114125
115126
Get an element group from the map by its id.
116127

128+
Element groups allow you to organize related elements together and control
129+
their visibility as a unit.
130+
117131
### Parameters
118132

119-
| Parameter | Type |
120-
| --------- | -------- |
121-
| `id` | `string` |
133+
| Parameter | Type | Description |
134+
| --------- | -------- | -------------------------------------------- |
135+
| `id` | `string` | The id of the element group you want to get. |
122136

123137
### Returns
124138

125139
`Promise`\<`null` | [`ElementGroup`](ElementGroup.md)>
126140

127-
The requested element group.
141+
A promise that resolves to the requested element group, or `null` if not found.
128142

129143
### Example
130144

@@ -141,17 +155,20 @@ const elementGroup = await felt.getElementGroup("element-group-1");
141155
Gets element groups from the map, according to the filters supplied. If no
142156
constraints are supplied, all element groups will be returned in rendering order.
143157

158+
Use this method to retrieve multiple element groups, optionally filtered by constraints.
159+
This is useful for bulk operations on element groups.
160+
144161
### Parameters
145162

146-
| Parameter | Type | Description |
147-
| ------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
148-
| `constraint`? | [`GetElementGroupsConstraint`](GetElementGroupsConstraint.md) | The constraints to apply to the element groups returned from the map. |
163+
| Parameter | Type | Description |
164+
| ------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- |
165+
| `constraint`? | [`GetElementGroupsConstraint`](GetElementGroupsConstraint.md) | Optional constraints to apply to the element groups returned from the map. |
149166

150167
### Returns
151168

152169
`Promise`\<(`null` | [`ElementGroup`](ElementGroup.md))\[]>
153170

154-
The requested element groups.
171+
A promise that resolves to an array of element groups in rendering order.
155172

156173
### Example
157174

@@ -167,16 +184,21 @@ const elementGroups = await felt.getElementGroups({ ids: ["element-group-1", "el
167184
168185
Hide or show element groups with the given ids.
169186

187+
Use this method to control the visibility of multiple element groups at once.
188+
This is more efficient than hiding/showing individual elements.
189+
170190
### Parameters
171191

172-
| Parameter | Type |
173-
| ------------ | ----------------------------------------------------------- |
174-
| `visibility` | [`SetVisibilityRequest`](../Shared/SetVisibilityRequest.md) |
192+
| Parameter | Type | Description |
193+
| ------------ | ----------------------------------------------------------- | ------------------------------------------------ |
194+
| `visibility` | [`SetVisibilityRequest`](../Shared/SetVisibilityRequest.md) | The visibility configuration for element groups. |
175195

176196
### Returns
177197

178198
`Promise`\<`void`>
179199

200+
A promise that resolves when the visibility changes are applied.
201+
180202
### Example
181203

182204
```typescript
@@ -191,16 +213,21 @@ felt.setElementGroupVisibility({ show: ["element-group-1", "element-group-2"], h
191213
192214
Create a new element on the map.
193215

216+
Use this method to programmatically create elements on the map. Elements created
217+
via the SDK are only available to the current session and are not persisted.
218+
194219
### Parameters
195220

196-
| Parameter | Type |
197-
| --------- | ----------------------------------- |
198-
| `element` | [`ElementCreate`](ElementCreate.md) |
221+
| Parameter | Type | Description |
222+
| --------- | ----------------------------------- | ------------------------------------ |
223+
| `element` | [`ElementCreate`](ElementCreate.md) | The element configuration to create. |
199224

200225
### Returns
201226

202227
`Promise`\<[`Element`](Element.md)>
203228

229+
A promise that resolves to the created element.
230+
204231
### Example
205232

206233
```typescript
@@ -215,16 +242,21 @@ const element = await felt.createElement({ type: "Place", coordinates: [10, 10]
215242
216243
Update an element on the map. The element type must be specified.
217244

245+
Use this method to modify existing elements. You can update properties like
246+
coordinates, styling, and metadata.
247+
218248
### Parameters
219249

220-
| Parameter | Type |
221-
| --------- | ----------------------------------- |
222-
| `element` | [`ElementUpdate`](ElementUpdate.md) |
250+
| Parameter | Type | Description |
251+
| --------- | ----------------------------------- | --------------------------------- |
252+
| `element` | [`ElementUpdate`](ElementUpdate.md) | The element update configuration. |
223253

224254
### Returns
225255

226256
`Promise`\<[`Element`](Element.md)>
227257

258+
A promise that resolves to the updated element.
259+
228260
### Example
229261

230262
```typescript
@@ -252,16 +284,20 @@ await felt.updateElement({
252284
253285
Delete an element from the map.
254286

287+
Use this method to remove elements from the map. This operation cannot be undone.
288+
255289
### Parameters
256290

257-
| Parameter | Type |
258-
| --------- | -------- |
259-
| `id` | `string` |
291+
| Parameter | Type | Description |
292+
| --------- | -------- | -------------------------------- |
293+
| `id` | `string` | The id of the element to delete. |
260294

261295
### Returns
262296

263297
`Promise`\<`void`>
264298

299+
A promise that resolves when the element is deleted.
300+
265301
### Example
266302

267303
```typescript
@@ -276,6 +312,18 @@ await felt.deleteElement("element-1");
276312
277313
Adds a listener for when an element is created.
278314

315+
This will fire when elements are created programmatically, or when the
316+
user starts creating an element with a drawing tool.
317+
318+
When the user creates an element with a drawing tool, it can begin in
319+
an invalid state, such as if you've just placed a single point in a polygon.
320+
321+
You can use the `isBeingCreated` property to determine if the element is
322+
still being created by a drawing tool.
323+
324+
If you want to know when the element is finished being created, you can
325+
use the [\`onElementCreateEnd\`](ElementsController.md#onelementcreateend) listener.
326+
279327
### Parameters
280328

281329
| Parameter | Type | Description |
@@ -287,7 +335,7 @@ Adds a listener for when an element is created.
287335

288336
`VoidFunction`
289337

290-
A function to unsubscribe from the listener
338+
A function to unsubscribe from the listener.
291339

292340
### Example
293341

@@ -327,7 +375,7 @@ add the marker, type a label, then finally deselect the element.
327375

328376
`VoidFunction`
329377

330-
A function to unsubscribe from the listener
378+
A function to unsubscribe from the listener.
331379

332380
### Example
333381

@@ -370,7 +418,7 @@ still being created by a drawing tool.
370418

371419
`VoidFunction`
372420

373-
A function to unsubscribe from the listener
421+
A function to unsubscribe from the listener.
374422

375423
### Example
376424

@@ -392,6 +440,9 @@ unsubscribe();
392440
393441
Adds a listener for when an element is deleted.
394442

443+
Use this to react to element deletions, such as cleaning up related data
444+
or updating your application state.
445+
395446
### Parameters
396447

397448
| Parameter | Type | Description |
@@ -405,7 +456,7 @@ Adds a listener for when an element is deleted.
405456

406457
`VoidFunction`
407458

408-
A function to unsubscribe from the listener
459+
A function to unsubscribe from the listener.
409460

410461
### Example
411462

@@ -427,6 +478,9 @@ unsubscribe();
427478
428479
Adds a listener for when an element group changes.
429480

481+
Use this to react to changes in element groups, such as when elements are
482+
added to or removed from groups.
483+
430484
### Parameters
431485

432486
| Parameter | Type |
@@ -440,7 +494,7 @@ Adds a listener for when an element group changes.
440494

441495
`VoidFunction`
442496

443-
A function to unsubscribe from the listener
497+
A function to unsubscribe from the listener.
444498

445499
### Example
446500

‎docs/Interactions/InteractionsController.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ The Interactions controller allows you to observe interactions with the map
1212

1313
> **onPointerClick**(`params`: \{ `handler`: (`event`: [`MapInteractionEvent`](MapInteractionEvent.md)) => `void`; }): `VoidFunction`
1414
15-
Allows you to be notified the user clicks on the map.
15+
Allows you to be notified when the user clicks on the map.
16+
17+
Use this to react to user clicks on the map, such as triggering custom
18+
actions or collecting interaction data.
1619

1720
### Parameters
1821

@@ -25,7 +28,7 @@ Allows you to be notified the user clicks on the map.
2528

2629
`VoidFunction`
2730

28-
A function to unsubscribe from the listener
31+
A function to unsubscribe from the listener.
2932

3033
### Example
3134

@@ -44,7 +47,10 @@ unsubscribe();
4447

4548
> **onPointerMove**(`params`: \{ `handler`: (`event`: [`MapInteractionEvent`](MapInteractionEvent.md)) => `void`; }): `VoidFunction`
4649
47-
Allows you to be notified the user moves the mouse over the map.
50+
Allows you to be notified when the user moves the mouse over the map.
51+
52+
Use this to track mouse movement and detect features under the cursor,
53+
such as for hover effects or real-time data display.
4854

4955
### Parameters
5056

@@ -57,7 +63,7 @@ Allows you to be notified the user moves the mouse over the map.
5763

5864
`VoidFunction`
5965

60-
A function to unsubscribe from the listener
66+
A function to unsubscribe from the listener.
6167

6268
### Example
6369

0 commit comments

Comments
 (0)