Skip to content

Commit 7b334e7

Browse files
tomhickstomhicks
authored
Fix various doc examples and add better Filters docs (#32)
* Fix various doc examples and add better Filters docs * Mention FilterTernary * Improve docs for filter ternaries * Include changelog in docs * Don't reduce changelog and top-level readme heading levels
1 parent 7c4ef6a commit 7b334e7

18 files changed

+382
-138
lines changed

‎customTheme.mjs

+9-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,15 @@ export function load(app) {
1919

2020
class MyMarkdownTheme extends MarkdownTheme {
2121
render(page, template) {
22-
return super.render(page, template).replace(/^##/gm, "#");
22+
const defaultValue = super.render(page, template);
23+
if (
24+
page.filename.endsWith("CHANGELOG.md") ||
25+
page.filename.endsWith("docs/README.md")
26+
) {
27+
return defaultValue;
28+
} else {
29+
return defaultValue.replace(/^##/gm, "#");
30+
}
2331
}
2432

2533
getRenderContext(page) {

‎docs/CHANGELOG.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# @feltmaps/js-sdk
2+
3+
## 1.4.0
4+
5+
### Minor Changes
6+
7+
* 555a25a: Add clearSelection method
8+
* 1f5d950: Add option to pass auth token when embedding
9+
10+
## 1.3.0
11+
12+
### Minor Changes
13+
14+
* 4bbde62: Allow setting a note to show with layer filters
15+
16+
## 1.2.0
17+
18+
### Minor Changes
19+
20+
* 7badd4b: Add onMapIdle event
21+
* 41efd53: Add selectFeature method to select feature by layer and feature ID
22+
* 208c492: Add areaQuery param to getRenderedFeatures
23+
24+
## 1.1.0
25+
26+
### Minor Changes
27+
28+
* 5f607ec: Return style with layers, and allow updating layer styles via setLayerStyle
29+
30+
### Patch Changes
31+
32+
* 3a8bec8: Fix API reference link in README
33+
34+
## 1.0.2
35+
36+
### Major Changes
37+
38+
* Release v1 of Felt JS SDK

‎docs/Elements/ElementsController.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ The requested element group.
114114
### Example
115115

116116
```typescript
117-
felt.getElementGroup("element-group-1");
117+
const elementGroup = await felt.getElementGroup("element-group-1");
118118
```
119119

120120
***

‎docs/Layers/FilterTernary.md

+26
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
11
***
22

33
> **FilterTernary**: \[[`FilterTernary`](FilterTernary.md) | [`FilterExpression`](FilterExpression.md) | `null` | `boolean`, [`FilterLogicGate`](FilterLogicGate.md), [`FilterTernary`](FilterTernary.md) | [`FilterExpression`](FilterExpression.md) | `null` | `boolean`]
4+
5+
A `FilterTernary` is a tree structure for combining expressions with logical operators.
6+
7+
When combining three or more conditions, you must use proper nesting rather than a flat list.
8+
9+
# Example
10+
11+
```typescript
12+
// A simple filter with a single condition
13+
const filter = [
14+
["AREA", "gt", 30_000],
15+
"and",
16+
["COLOR", "eq", "red"]
17+
]
18+
19+
// A complex filter with multiple conditions
20+
const filter = [
21+
["AREA", "gt", 30_000],
22+
"and",
23+
[
24+
["COLOR", "eq", "red"],
25+
"or",
26+
["TYPE", "eq", "residential"]
27+
]
28+
]
29+
```

‎docs/Layers/Filters.md

+75-4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@
55
Filters can be used to change which features in a layer are rendered. Filters can be
66
applied to a layer by the `setLayerFilters` method on the Felt controller.
77

8+
Filters use a tree structure for combining expressions with logical operators, called a
9+
[FilterTernary](FilterTernary.md). When combining three or more conditions, you must use proper nesting
10+
rather than a flat list.
11+
12+
See the examples below for the correct structure to use when building complex filters.
13+
814
# Remarks
915

1016
The possible operators are:
@@ -26,15 +32,80 @@ The allowed boolean operators are:
2632
# Example
2733

2834
```typescript
29-
// a simple filter
35+
// 1. Simple filter: single condition
3036
felt.setLayerFilters({
3137
layerId: "layer-1",
3238
filters: ["AREA", "gt", 30_000],
3339
});
3440

35-
// compound filters can be constructed using boolean logic:
41+
// 2. Basic compound filter: two conditions with AND
42+
felt.setLayerFilters({
43+
layerId: "layer-1",
44+
filters: [
45+
["AREA", "gt", 30_000], // First condition
46+
"and", // Logic operator
47+
["COLOR", "eq", "red"] // Second condition
48+
]
49+
});
50+
51+
// 3. Complex filter: three or more conditions require nesting
52+
// ⚠️ IMPORTANT: Filters use a tree structure, not a flat list
3653
felt.setLayerFilters({
3754
layerId: "layer-1",
38-
filters: [["AREA", "gt", 30_000], "and", ["COLOR", "eq", "red"]]
39-
})
55+
filters: [
56+
["AREA", "gt", 30_000], // First condition
57+
"and", // First logic operator
58+
[ // Nested group starts
59+
["COLOR", "eq", "red"], // Second condition
60+
"and", // Second logic operator
61+
["TYPE", "eq", "residential"] // Third condition
62+
] // Nested group ends
63+
]
64+
});
65+
66+
// 4. Even more complex: four conditions with proper nesting
67+
// Visual structure:
68+
// AND
69+
// / \
70+
// condition AND
71+
// / \
72+
// condition AND
73+
// / \
74+
// condition condition
75+
felt.setLayerFilters({
76+
layerId: "layer-1",
77+
filters: [
78+
["AREA", "gt", 30_000], // First condition
79+
"and",
80+
[
81+
["COLOR", "eq", "red"], // Second condition
82+
"and",
83+
[
84+
["TYPE", "eq", "residential"], // Third condition
85+
"and",
86+
["YEAR", "gt", 2000] // Fourth condition
87+
]
88+
]
89+
]
90+
});
91+
92+
// 5. Mixed operators: combining AND and OR
93+
// Visual structure:
94+
// AND
95+
// / \
96+
// condition OR
97+
// / \
98+
// condition condition
99+
felt.setLayerFilters({
100+
layerId: "layer-1",
101+
filters: [
102+
["AREA", "gt", 30_000], // Must have large area
103+
"and",
104+
[
105+
["COLOR", "eq", "red"], // Must be either red
106+
"or",
107+
["TYPE", "eq", "residential"] // OR residential type
108+
]
109+
]
110+
});
40111
```

‎docs/Layers/LayersController.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ The requested layer.
3333
### Example
3434

3535
```typescript
36-
const layers = await felt.getLayer({ ids: ["layer-1", "layer-2"] });
36+
const layer = await felt.getLayer("layer-1");
3737
```
3838

3939
***
@@ -185,7 +185,7 @@ The requested layer group.
185185
### Example
186186

187187
```typescript
188-
felt.getLayerGroup("layer-group-1");
188+
const layerGroup = await felt.getLayerGroup("layer-group-1");
189189
```
190190

191191
***

‎docs/Main/FeltController.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ The requested element group.
127127
### Example
128128

129129
```typescript
130-
felt.getElementGroup("element-group-1");
130+
const elementGroup = await felt.getElementGroup("element-group-1");
131131
```
132132

133133
***
@@ -264,7 +264,7 @@ The requested layer.
264264
### Example
265265

266266
```typescript
267-
const layers = await felt.getLayer({ ids: ["layer-1", "layer-2"] });
267+
const layer = await felt.getLayer("layer-1");
268268
```
269269

270270
***
@@ -416,7 +416,7 @@ The requested layer group.
416416
### Example
417417

418418
```typescript
419-
felt.getLayerGroup("layer-group-1");
419+
const layerGroup = await felt.getLayerGroup("layer-group-1");
420420
```
421421

422422
***
@@ -993,7 +993,7 @@ Sets the tool to use for drawing elements on the map.
993993

994994
### Example
995995

996-
```ts
996+
```typescript
997997
// Set the tool to "marker"
998998
felt.setTool("marker");
999999

@@ -1017,7 +1017,7 @@ The current tool, or `null` if no tool is in use.
10171017

10181018
### Example
10191019

1020-
```ts
1020+
```typescript
10211021
const tool = await felt.getTool(); // "marker", "polygon", etc.
10221022
```
10231023

@@ -1044,7 +1044,7 @@ A function to unsubscribe from the listener
10441044

10451045
### Example
10461046

1047-
```ts
1047+
```typescript
10481048
const unsubscribe = felt.onToolChange({
10491049
handler: tool => console.log(tool),
10501050
});

‎docs/README.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# API Reference
22

3-
# Modules
3+
## Documents
4+
5+
* [CHANGELOG](CHANGELOG.md)
6+
7+
## Modules
48

59
* [Elements](Elements/README.md)
610
* [Interactions](Interactions/README.md)

‎docs/Tools/ToolsController.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Sets the tool to use for drawing elements on the map.
2626

2727
### Example
2828

29-
```ts
29+
```typescript
3030
// Set the tool to "marker"
3131
felt.setTool("marker");
3232

@@ -50,7 +50,7 @@ The current tool, or `null` if no tool is in use.
5050

5151
### Example
5252

53-
```ts
53+
```typescript
5454
const tool = await felt.getTool(); // "marker", "polygon", etc.
5555
```
5656

@@ -77,7 +77,7 @@ A function to unsubscribe from the listener
7777

7878
### Example
7979

80-
```ts
80+
```typescript
8181
const unsubscribe = felt.onToolChange({
8282
handler: tool => console.log(tool),
8383
});

0 commit comments

Comments
 (0)