Fix various doc examples and add better Filters docs

customTheme.mjs

@@ -19,7 +19,15 @@ export function load(app) {
 
 class MyMarkdownTheme extends MarkdownTheme {
   render(page, template) {
-    return super.render(page, template).replace(/^##/gm, "#");
+    const defaultValue = super.render(page, template);
+    if (
+      page.filename.endsWith("CHANGELOG.md") ||
+      page.filename.endsWith("docs/README.md")
+    ) {
+      return defaultValue;
+    } else {
+      return defaultValue.replace(/^##/gm, "#");
+    }
   }
 
   getRenderContext(page) {

docs/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @feltmaps/js-sdk
+
+## 1.4.0
+
+### Minor Changes
+
+* 555a25a: Add clearSelection method
+* 1f5d950: Add option to pass auth token when embedding
+
+## 1.3.0
+
+### Minor Changes
+
+* 4bbde62: Allow setting a note to show with layer filters
+
+## 1.2.0
+
+### Minor Changes
+
+* 7badd4b: Add onMapIdle event
+* 41efd53: Add selectFeature method to select feature by layer and feature ID
+* 208c492: Add areaQuery param to getRenderedFeatures
+
+## 1.1.0
+
+### Minor Changes
+
+* 5f607ec: Return style with layers, and allow updating layer styles via setLayerStyle
+
+### Patch Changes
+
+* 3a8bec8: Fix API reference link in README
+
+## 1.0.2
+
+### Major Changes
+
+* Release v1 of Felt JS SDK

docs/Elements/ElementsController.md

@@ -114,7 +114,7 @@ The requested element group.
 ### Example
 
 ```typescript
-felt.getElementGroup("element-group-1");
+const elementGroup = await felt.getElementGroup("element-group-1");
 ```
 
 ***

docs/Layers/FilterTernary.md

@@ -1,3 +1,29 @@
 ***
 
 > **FilterTernary**: \[[`FilterTernary`](FilterTernary.md) | [`FilterExpression`](FilterExpression.md) | `null` | `boolean`, [`FilterLogicGate`](FilterLogicGate.md), [`FilterTernary`](FilterTernary.md) | [`FilterExpression`](FilterExpression.md) | `null` | `boolean`]
+
+A `FilterTernary` is a tree structure for combining expressions with logical operators.
+
+When combining three or more conditions, you must use proper nesting rather than a flat list.
+
+# Example
+
+```typescript
+// A simple filter with a single condition
+const filter = [
+  ["AREA", "gt", 30_000],
+  "and",
+  ["COLOR", "eq", "red"]
+]
+
+// A complex filter with multiple conditions
+const filter = [
+  ["AREA", "gt", 30_000],
+  "and",
+  [
+    ["COLOR", "eq", "red"],
+    "or",
+    ["TYPE", "eq", "residential"]
+  ]
+]
+```

docs/Layers/Filters.md

@@ -5,6 +5,12 @@
 Filters can be used to change which features in a layer are rendered. Filters can be
 applied to a layer by the `setLayerFilters` method on the Felt controller.
 
+Filters use a tree structure for combining expressions with logical operators, called a
+[FilterTernary](FilterTernary.md). When combining three or more conditions, you must use proper nesting
+rather than a flat list.
+
+See the examples below for the correct structure to use when building complex filters.
+
 # Remarks
 
 The possible operators are:
@@ -26,15 +32,80 @@ The allowed boolean operators are:
 # Example
 
 ```typescript
-// a simple filter
+// 1. Simple filter: single condition
 felt.setLayerFilters({
   layerId: "layer-1",
   filters: ["AREA", "gt", 30_000],
 });
 
-// compound filters can be constructed using boolean logic:
+// 2. Basic compound filter: two conditions with AND
+felt.setLayerFilters({
+  layerId: "layer-1",
+  filters: [
+    ["AREA", "gt", 30_000],  // First condition
+    "and",                   // Logic operator
+    ["COLOR", "eq", "red"]   // Second condition
+  ]
+});
+
+// 3. Complex filter: three or more conditions require nesting
+// ⚠️ IMPORTANT: Filters use a tree structure, not a flat list
 felt.setLayerFilters({
   layerId: "layer-1",
-  filters: [["AREA", "gt", 30_000], "and", ["COLOR", "eq", "red"]]
-})
+  filters: [
+    ["AREA", "gt", 30_000],                // First condition
+    "and",                                 // First logic operator
+    [                                      // Nested group starts
+      ["COLOR", "eq", "red"],              //   Second condition
+      "and",                               //   Second logic operator
+      ["TYPE", "eq", "residential"]        //   Third condition
+    ]                                      // Nested group ends
+  ]
+});
+
+// 4. Even more complex: four conditions with proper nesting
+// Visual structure:
+//          AND
+//         /   \
+//    condition  AND
+//              /   \
+//        condition  AND
+//                  /   \
+//            condition  condition
+felt.setLayerFilters({
+  layerId: "layer-1",
+  filters: [
+    ["AREA", "gt", 30_000],                // First condition
+    "and",
+    [
+      ["COLOR", "eq", "red"],              // Second condition
+      "and",
+      [
+        ["TYPE", "eq", "residential"],     // Third condition
+        "and",
+        ["YEAR", "gt", 2000]               // Fourth condition
+      ]
+    ]
+  ]
+});
+
+// 5. Mixed operators: combining AND and OR
+// Visual structure:
+//          AND
+//         /   \
+//    condition  OR
+//              /  \
+//        condition condition
+felt.setLayerFilters({
+  layerId: "layer-1",
+  filters: [
+    ["AREA", "gt", 30_000],                // Must have large area
+    "and",
+    [
+      ["COLOR", "eq", "red"],              // Must be either red
+      "or",
+      ["TYPE", "eq", "residential"]        // OR residential type
+    ]
+  ]
+});
 ```

docs/Layers/LayersController.md

@@ -33,7 +33,7 @@ The requested layer.
 ### Example
 
 ```typescript
-const layers = await felt.getLayer({ ids: ["layer-1", "layer-2"] });
+const layer = await felt.getLayer("layer-1");
 ```
 
 ***
@@ -185,7 +185,7 @@ The requested layer group.
 ### Example
 
 ```typescript
-felt.getLayerGroup("layer-group-1");
+const layerGroup = await felt.getLayerGroup("layer-group-1");
 ```
 
 ***

docs/Main/FeltController.md

@@ -127,7 +127,7 @@ The requested element group.
 ### Example
 
 ```typescript
-felt.getElementGroup("element-group-1");
+const elementGroup = await felt.getElementGroup("element-group-1");
 ```
 
 ***
@@ -264,7 +264,7 @@ The requested layer.
 ### Example
 
 ```typescript
-const layers = await felt.getLayer({ ids: ["layer-1", "layer-2"] });
+const layer = await felt.getLayer("layer-1");
 ```
 
 ***
@@ -416,7 +416,7 @@ The requested layer group.
 ### Example
 
 ```typescript
-felt.getLayerGroup("layer-group-1");
+const layerGroup = await felt.getLayerGroup("layer-group-1");
 ```
 
 ***
@@ -993,7 +993,7 @@ Sets the tool to use for drawing elements on the map.
 
 ### Example
 
-```ts
+```typescript
 // Set the tool to "marker"
 felt.setTool("marker");
 
@@ -1017,7 +1017,7 @@ The current tool, or `null` if no tool is in use.
 
 ### Example
 
-```ts
+```typescript
 const tool = await felt.getTool(); // "marker", "polygon", etc.
 ```
 
@@ -1044,7 +1044,7 @@ A function to unsubscribe from the listener
 
 ### Example
 
-```ts
+```typescript
 const unsubscribe = felt.onToolChange({
   handler: tool => console.log(tool),
 });

docs/README.md

@@ -1,6 +1,10 @@
 # API Reference
 
-# Modules
+## Documents
+
+* [CHANGELOG](CHANGELOG.md)
+
+## Modules
 
 * [Elements](Elements/README.md)
 * [Interactions](Interactions/README.md)

docs/Tools/ToolsController.md

@@ -26,7 +26,7 @@ Sets the tool to use for drawing elements on the map.
 
 ### Example
 
-```ts
+```typescript
 // Set the tool to "marker"
 felt.setTool("marker");
 
@@ -50,7 +50,7 @@ The current tool, or `null` if no tool is in use.
 
 ### Example
 
-```ts
+```typescript
 const tool = await felt.getTool(); // "marker", "polygon", etc.
 ```
 
@@ -77,7 +77,7 @@ A function to unsubscribe from the listener
 
 ### Example
 
-```ts
+```typescript
 const unsubscribe = felt.onToolChange({
   handler: tool => console.log(tool),
 });