@feltmaps/js-sdk 1.5.0-next.6 → 1.5.0-next.7

package/dist/{types-CQwkpLq-.d.cts → types-XLCA2cX-.d.cts}

@@ -378,7 +378,7 @@ declare const ImageCreateSchema: z.ZodObject<Omit<{
     attributes?: Record<string, unknown> | undefined;
     opacity?: number | undefined;
 }>;
-declare const PlaceReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objectUtil.extendShape<{
+declare const PlaceReadSchema: z.ZodObject<z.objectUtil.extendShape<z.objectUtil.extendShape<{
     id: z.ZodString;
     groupId: z.ZodNullable<z.ZodString>;
     color: z.ZodString;
@@ -393,9 +393,10 @@ declare const PlaceReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objec
     symbol: z.ZodString;
     frame: z.ZodNullable<z.ZodEnum<["frame-circle", "frame-square"]>>;
     hideLabel: z.ZodBoolean;
-}>, "coordinates">, "strip", z.ZodTypeAny, {
+}>, "strip", z.ZodTypeAny, {
     symbol: string;
     type: "Place";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -408,6 +409,7 @@ declare const PlaceReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objec
 }, {
     symbol: string;
     type: "Place";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -515,7 +517,7 @@ declare const PolygonReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.obj
     fillOpacity: number;
     areaMarker: boolean;
 }>;
-declare const CircleReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objectUtil.extendShape<z.objectUtil.extendShape<{
+declare const CircleReadSchema: z.ZodObject<z.objectUtil.extendShape<z.objectUtil.extendShape<z.objectUtil.extendShape<{
     id: z.ZodString;
     groupId: z.ZodNullable<z.ZodString>;
     color: z.ZodString;
@@ -536,8 +538,9 @@ declare const CircleReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.obje
     radiusDisplayUnit: z.ZodNullable<z.ZodEnum<["meter", "kilometer", "foot", "mile"]>>;
     fillOpacity: z.ZodNumber;
     radiusMarker: z.ZodBoolean;
-}>, "coordinates">, "strip", z.ZodTypeAny, {
+}>, "strip", z.ZodTypeAny, {
     type: "Circle";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -555,6 +558,7 @@ declare const CircleReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.obje
     radiusMarker: boolean;
 }, {
     type: "Circle";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -1317,7 +1321,7 @@ declare const GetElementGroupsConstraintSchema: z.ZodObject<{
     ids?: string[] | undefined;
 }>;
 /**
- * The parameters for the `onElementChange` listener.
+ * The parameters for the `onElementChange` and the `onElementCreate` listeners.
  *
  * @group Elements
  */
@@ -1326,6 +1330,22 @@ interface ElementChangeCallbackParams {
      * The new data for the element or null if the element was removed.
      */
     element: Element | null;
+    /**
+     * Whether or not this element is still being created by a drawing tool.
+     *
+     * For example, if the user begins drawing a polygon, they need to place
+     * multiple points until they've ultimately completed the polygon. All
+     * the time they are still placing points, this will be true.
+     *
+     * For elements that require text entry (such as Places, Text and Notes)
+     * this will be true all the time the user is typing text until the point
+     * at which the user finishes, by pressing Escape for example.
+     *
+     * If the user is editing an existing element, this will be false.
+     *
+     * For elements that are created programatically, this will be false.
+     */
+    isBeingCreated: boolean;
 }
 /**
  * The parameters for the `onElementGroupChange` listener.
@@ -1464,6 +1484,40 @@ declare const SetVisibilityRequestSchema: z.ZodObject<{
     show?: string[] | undefined;
     hide?: string[] | undefined;
 }>;
+/**
+ * Specifies the direction to sort data in
+ *
+ * @group Types
+ */
+type SortDirection = z.infer<typeof SortDirectionSchema>;
+/** @ignore */
+declare const SortDirectionSchema: z.ZodEnum<["asc", "desc"]>;
+/**
+ * Configuration for sorting data by a specific attribute
+ *
+ * @group Types
+ */
+interface SortConfig extends zInfer<typeof SortConfigSchema> {
+}
+/** @ignore */
+declare const SortConfigSchema: z.ZodObject<{
+    /**
+     * The attribute to sort by. What this represents depends on the context.
+     * For instance, when sorting features in a data table, the attribute is
+     * the column to sort by.
+     */
+    attribute: z.ZodString;
+    /**
+     * The direction to sort in
+     */
+    direction: z.ZodEnum<["asc", "desc"]>;
+}, "strip", z.ZodTypeAny, {
+    attribute: string;
+    direction: "asc" | "desc";
+}, {
+    attribute: string;
+    direction: "asc" | "desc";
+}>;
 
 /**
  * A feature is a single geographical item in a layer.
@@ -1888,6 +1942,31 @@ declare const FilterLogicGateSchema: z.ZodEnum<["and", "or"]>;
 type FilterExpression = z.infer<typeof FilterExpressionSchema>;
 declare const FilterExpressionSchema: z.ZodUnion<[z.ZodTuple<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodEnum<["in", "ni"]>, z.ZodUnion<[z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>, "many">, z.ZodNull]>], null>, z.ZodTuple<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodEnum<["lt", "gt", "le", "ge", "eq", "ne", "cn", "nc", "is", "isnt"]>, z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>], null>]>;
 /**
+ * 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"]
+ *   ]
+ * ]
+ * ```
+ *
  * @group Filters
  */
 type FilterTernary = [
@@ -1900,6 +1979,12 @@ type FilterTernary = [
  * 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
+ * {@link FilterTernary}. 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:
  * - `lt`: Less than
@@ -1917,17 +2002,82 @@ type FilterTernary = [
  *
  * @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
+ *     ]
+ *   ]
+ * });
  * ```
  *
  * @group Filters
@@ -2179,8 +2329,8 @@ declare const GetLayerCategoriesParamsSchema: z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     values?: {
         boundary?: [number, number][] | {
             type: "Polygon";
@@ -2199,8 +2349,8 @@ declare const GetLayerCategoriesParamsSchema: z.ZodObject<{
     filters?: boolean | [string | null, "in" | "ni", (string | number | boolean | null)[] | null] | [string | null, "lt" | "gt" | "le" | "ge" | "eq" | "ne" | "cn" | "nc" | "is" | "isnt", string | number | boolean | null] | FilterTernary | null | undefined;
     limit?: number | undefined;
 }, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     values?: {
         boundary?: [number, number][] | {
             type: "Polygon";
@@ -2370,8 +2520,8 @@ declare const GetLayerHistogramParamsSchema: z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     steps: number[] | {
         type: "equal-intervals";
         count: number;
@@ -2396,8 +2546,8 @@ declare const GetLayerHistogramParamsSchema: z.ZodObject<{
     } | [number, number, number, number] | undefined;
     filters?: boolean | [string | null, "in" | "ni", (string | number | boolean | null)[] | null] | [string | null, "lt" | "gt" | "le" | "ge" | "eq" | "ne" | "cn" | "nc" | "is" | "isnt", string | number | boolean | null] | FilterTernary | null | undefined;
 }, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     steps: number[] | {
         type: "equal-intervals";
         count: number;
@@ -3044,4 +3194,4 @@ declare const ViewportFitBoundsParamsSchema: z.ZodObject<{
     bounds: [number, number, number, number];
 }>;
 
-export type { ImageElementUpdate as $, AggregationMethod as A, FeatureSelection as B, ConfigurableToolType as C, ToolSettingsMap as D, Element as E, Filters as F, Geometry as G, ToolSettingsChangeEvent as H, InputToolSettings as I, zInfer as J, SetViewportCenterZoomParams as K, Layer as L, MapInteractionEvent as M, ViewportConstraints as N, ViewportFitBoundsParams as O, ViewportCenterZoom as P, CircleElementCreate as Q, CircleElementRead as R, SetVisibilityRequest as S, ToolType as T, CircleElementUpdate as U, ViewportState as V, HighlighterElementCreate as W, HighlighterElementRead as X, HighlighterElementUpdate as Y, ImageElementCreate as Z, ImageElementRead as _, GetElementsConstraint as a, LinkElementRead as a0, MarkerElementCreate as a1, MarkerElementRead as a2, MarkerElementUpdate as a3, NoteElementCreate as a4, NoteElementRead as a5, NoteElementUpdate as a6, PathElementCreate as a7, PathElementRead as a8, PathElementUpdate as a9, LngLatTuple as aA, MultiLineStringGeometry as aB, MultiPolygonGeometry as aC, PointGeometry as aD, PolygonGeometry as aE, CircleToolSettings as aF, HighlighterToolSettings as aG, LineToolSettings as aH, MarkerToolSettings as aI, NoteToolSettings as aJ, PinToolSettings as aK, PlaceFrame as aL, PlaceSymbol as aM, PolygonToolSettings as aN, RouteToolSettings as aO, TextToolSettings as aP, UnionToIntersection as aQ, PromiseOrNot as aR, PlaceElementCreate as aa, PlaceElementRead as ab, PlaceElementUpdate as ac, PolygonElementCreate as ad, PolygonElementRead as ae, PolygonElementUpdate as af, TextElementCreate as ag, TextElementRead as ah, TextElementUpdate as ai, LayerProcessingStatus as aj, RasterValue as ak, FilterExpression as al, FilterLogicGate as am, FilterTernary as an, AggregationConfig as ao, MultiAggregationConfig as ap, ValueConfiguration as aq, ElementGroupNode as ar, ElementNode as as, FeatureNode as at, LayerGroupNode as au, LayerNode as av, FeltBoundary as aw, FeltZoom as ax, LatLng as ay, LineStringGeometry as az, ElementGroup as b, GetElementGroupsConstraint as c, ElementChangeCallbackParams as d, ElementGroupChangeCallbackParams as e, ElementCreate as f, ElementUpdate as g, GetLayersConstraint as h, LayerChangeCallbackParams as i, LayerGroup as j, GetLayerGroupsConstraint as k, LayerGroupChangeCallbackParams as l, LegendItemIdentifier as m, LegendItem as n, LegendItemsConstraint as o, LegendItemChangeCallbackParams as p, LayerFilters as q, GetRenderedFeaturesConstraint as r, Feature as s, GetLayerCategoriesParams as t, GetLayerCategoriesGroup as u, GetLayerHistogramParams as v, GetLayerHistogramBin as w, GetLayerCalculationParams as x, MapDetails as y, EntityNode as z };
+export type { ImageElementRead as $, AggregationMethod as A, FeatureSelection as B, ConfigurableToolType as C, ToolSettingsMap as D, Element as E, Filters as F, Geometry as G, ToolSettingsChangeEvent as H, InputToolSettings as I, zInfer as J, SortConfig as K, Layer as L, MapInteractionEvent as M, SetViewportCenterZoomParams as N, ViewportConstraints as O, ViewportFitBoundsParams as P, ViewportCenterZoom as Q, CircleElementCreate as R, SetVisibilityRequest as S, ToolType as T, CircleElementRead as U, ViewportState as V, CircleElementUpdate as W, HighlighterElementCreate as X, HighlighterElementRead as Y, HighlighterElementUpdate as Z, ImageElementCreate as _, GetElementsConstraint as a, ImageElementUpdate as a0, LinkElementRead as a1, MarkerElementCreate as a2, MarkerElementRead as a3, MarkerElementUpdate as a4, NoteElementCreate as a5, NoteElementRead as a6, NoteElementUpdate as a7, PathElementCreate as a8, PathElementRead as a9, LineStringGeometry as aA, LngLatTuple as aB, MultiLineStringGeometry as aC, MultiPolygonGeometry as aD, PointGeometry as aE, PolygonGeometry as aF, SortDirection as aG, CircleToolSettings as aH, HighlighterToolSettings as aI, LineToolSettings as aJ, MarkerToolSettings as aK, NoteToolSettings as aL, PinToolSettings as aM, PlaceFrame as aN, PlaceSymbol as aO, PolygonToolSettings as aP, RouteToolSettings as aQ, TextToolSettings as aR, UnionToIntersection as aS, PromiseOrNot as aT, PathElementUpdate as aa, PlaceElementCreate as ab, PlaceElementRead as ac, PlaceElementUpdate as ad, PolygonElementCreate as ae, PolygonElementRead as af, PolygonElementUpdate as ag, TextElementCreate as ah, TextElementRead as ai, TextElementUpdate as aj, LayerProcessingStatus as ak, RasterValue as al, FilterExpression as am, FilterLogicGate as an, FilterTernary as ao, AggregationConfig as ap, MultiAggregationConfig as aq, ValueConfiguration as ar, ElementGroupNode as as, ElementNode as at, FeatureNode as au, LayerGroupNode as av, LayerNode as aw, FeltBoundary as ax, FeltZoom as ay, LatLng as az, ElementGroup as b, GetElementGroupsConstraint as c, ElementChangeCallbackParams as d, ElementGroupChangeCallbackParams as e, ElementCreate as f, ElementUpdate as g, GetLayersConstraint as h, LayerChangeCallbackParams as i, LayerGroup as j, GetLayerGroupsConstraint as k, LayerGroupChangeCallbackParams as l, LegendItemIdentifier as m, LegendItem as n, LegendItemsConstraint as o, LegendItemChangeCallbackParams as p, LayerFilters as q, GetRenderedFeaturesConstraint as r, Feature as s, GetLayerCategoriesParams as t, GetLayerCategoriesGroup as u, GetLayerHistogramParams as v, GetLayerHistogramBin as w, GetLayerCalculationParams as x, MapDetails as y, EntityNode as z };

package/dist/{types-CQwkpLq-.d.ts → types-XLCA2cX-.d.ts}

@@ -378,7 +378,7 @@ declare const ImageCreateSchema: z.ZodObject<Omit<{
     attributes?: Record<string, unknown> | undefined;
     opacity?: number | undefined;
 }>;
-declare const PlaceReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objectUtil.extendShape<{
+declare const PlaceReadSchema: z.ZodObject<z.objectUtil.extendShape<z.objectUtil.extendShape<{
     id: z.ZodString;
     groupId: z.ZodNullable<z.ZodString>;
     color: z.ZodString;
@@ -393,9 +393,10 @@ declare const PlaceReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objec
     symbol: z.ZodString;
     frame: z.ZodNullable<z.ZodEnum<["frame-circle", "frame-square"]>>;
     hideLabel: z.ZodBoolean;
-}>, "coordinates">, "strip", z.ZodTypeAny, {
+}>, "strip", z.ZodTypeAny, {
     symbol: string;
     type: "Place";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -408,6 +409,7 @@ declare const PlaceReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objec
 }, {
     symbol: string;
     type: "Place";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -515,7 +517,7 @@ declare const PolygonReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.obj
     fillOpacity: number;
     areaMarker: boolean;
 }>;
-declare const CircleReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.objectUtil.extendShape<z.objectUtil.extendShape<{
+declare const CircleReadSchema: z.ZodObject<z.objectUtil.extendShape<z.objectUtil.extendShape<z.objectUtil.extendShape<{
     id: z.ZodString;
     groupId: z.ZodNullable<z.ZodString>;
     color: z.ZodString;
@@ -536,8 +538,9 @@ declare const CircleReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.obje
     radiusDisplayUnit: z.ZodNullable<z.ZodEnum<["meter", "kilometer", "foot", "mile"]>>;
     fillOpacity: z.ZodNumber;
     radiusMarker: z.ZodBoolean;
-}>, "coordinates">, "strip", z.ZodTypeAny, {
+}>, "strip", z.ZodTypeAny, {
     type: "Circle";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -555,6 +558,7 @@ declare const CircleReadSchema: z.ZodObject<Omit<z.objectUtil.extendShape<z.obje
     radiusMarker: boolean;
 }, {
     type: "Circle";
+    coordinates: [number, number];
     id: string;
     groupId: string | null;
     color: string;
@@ -1317,7 +1321,7 @@ declare const GetElementGroupsConstraintSchema: z.ZodObject<{
     ids?: string[] | undefined;
 }>;
 /**
- * The parameters for the `onElementChange` listener.
+ * The parameters for the `onElementChange` and the `onElementCreate` listeners.
  *
  * @group Elements
  */
@@ -1326,6 +1330,22 @@ interface ElementChangeCallbackParams {
      * The new data for the element or null if the element was removed.
      */
     element: Element | null;
+    /**
+     * Whether or not this element is still being created by a drawing tool.
+     *
+     * For example, if the user begins drawing a polygon, they need to place
+     * multiple points until they've ultimately completed the polygon. All
+     * the time they are still placing points, this will be true.
+     *
+     * For elements that require text entry (such as Places, Text and Notes)
+     * this will be true all the time the user is typing text until the point
+     * at which the user finishes, by pressing Escape for example.
+     *
+     * If the user is editing an existing element, this will be false.
+     *
+     * For elements that are created programatically, this will be false.
+     */
+    isBeingCreated: boolean;
 }
 /**
  * The parameters for the `onElementGroupChange` listener.
@@ -1464,6 +1484,40 @@ declare const SetVisibilityRequestSchema: z.ZodObject<{
     show?: string[] | undefined;
     hide?: string[] | undefined;
 }>;
+/**
+ * Specifies the direction to sort data in
+ *
+ * @group Types
+ */
+type SortDirection = z.infer<typeof SortDirectionSchema>;
+/** @ignore */
+declare const SortDirectionSchema: z.ZodEnum<["asc", "desc"]>;
+/**
+ * Configuration for sorting data by a specific attribute
+ *
+ * @group Types
+ */
+interface SortConfig extends zInfer<typeof SortConfigSchema> {
+}
+/** @ignore */
+declare const SortConfigSchema: z.ZodObject<{
+    /**
+     * The attribute to sort by. What this represents depends on the context.
+     * For instance, when sorting features in a data table, the attribute is
+     * the column to sort by.
+     */
+    attribute: z.ZodString;
+    /**
+     * The direction to sort in
+     */
+    direction: z.ZodEnum<["asc", "desc"]>;
+}, "strip", z.ZodTypeAny, {
+    attribute: string;
+    direction: "asc" | "desc";
+}, {
+    attribute: string;
+    direction: "asc" | "desc";
+}>;
 
 /**
  * A feature is a single geographical item in a layer.
@@ -1888,6 +1942,31 @@ declare const FilterLogicGateSchema: z.ZodEnum<["and", "or"]>;
 type FilterExpression = z.infer<typeof FilterExpressionSchema>;
 declare const FilterExpressionSchema: z.ZodUnion<[z.ZodTuple<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodEnum<["in", "ni"]>, z.ZodUnion<[z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>, "many">, z.ZodNull]>], null>, z.ZodTuple<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodEnum<["lt", "gt", "le", "ge", "eq", "ne", "cn", "nc", "is", "isnt"]>, z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>], null>]>;
 /**
+ * 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"]
+ *   ]
+ * ]
+ * ```
+ *
  * @group Filters
  */
 type FilterTernary = [
@@ -1900,6 +1979,12 @@ type FilterTernary = [
  * 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
+ * {@link FilterTernary}. 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:
  * - `lt`: Less than
@@ -1917,17 +2002,82 @@ type FilterTernary = [
  *
  * @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
+ *     ]
+ *   ]
+ * });
  * ```
  *
  * @group Filters
@@ -2179,8 +2329,8 @@ declare const GetLayerCategoriesParamsSchema: z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     values?: {
         boundary?: [number, number][] | {
             type: "Polygon";
@@ -2199,8 +2349,8 @@ declare const GetLayerCategoriesParamsSchema: z.ZodObject<{
     filters?: boolean | [string | null, "in" | "ni", (string | number | boolean | null)[] | null] | [string | null, "lt" | "gt" | "le" | "ge" | "eq" | "ne" | "cn" | "nc" | "is" | "isnt", string | number | boolean | null] | FilterTernary | null | undefined;
     limit?: number | undefined;
 }, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     values?: {
         boundary?: [number, number][] | {
             type: "Polygon";
@@ -2370,8 +2520,8 @@ declare const GetLayerHistogramParamsSchema: z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     steps: number[] | {
         type: "equal-intervals";
         count: number;
@@ -2396,8 +2546,8 @@ declare const GetLayerHistogramParamsSchema: z.ZodObject<{
     } | [number, number, number, number] | undefined;
     filters?: boolean | [string | null, "in" | "ni", (string | number | boolean | null)[] | null] | [string | null, "lt" | "gt" | "le" | "ge" | "eq" | "ne" | "cn" | "nc" | "is" | "isnt", string | number | boolean | null] | FilterTernary | null | undefined;
 }, {
-    layerId: string;
     attribute: string;
+    layerId: string;
     steps: number[] | {
         type: "equal-intervals";
         count: number;
@@ -3044,4 +3194,4 @@ declare const ViewportFitBoundsParamsSchema: z.ZodObject<{
     bounds: [number, number, number, number];
 }>;
 
-export type { ImageElementUpdate as $, AggregationMethod as A, FeatureSelection as B, ConfigurableToolType as C, ToolSettingsMap as D, Element as E, Filters as F, Geometry as G, ToolSettingsChangeEvent as H, InputToolSettings as I, zInfer as J, SetViewportCenterZoomParams as K, Layer as L, MapInteractionEvent as M, ViewportConstraints as N, ViewportFitBoundsParams as O, ViewportCenterZoom as P, CircleElementCreate as Q, CircleElementRead as R, SetVisibilityRequest as S, ToolType as T, CircleElementUpdate as U, ViewportState as V, HighlighterElementCreate as W, HighlighterElementRead as X, HighlighterElementUpdate as Y, ImageElementCreate as Z, ImageElementRead as _, GetElementsConstraint as a, LinkElementRead as a0, MarkerElementCreate as a1, MarkerElementRead as a2, MarkerElementUpdate as a3, NoteElementCreate as a4, NoteElementRead as a5, NoteElementUpdate as a6, PathElementCreate as a7, PathElementRead as a8, PathElementUpdate as a9, LngLatTuple as aA, MultiLineStringGeometry as aB, MultiPolygonGeometry as aC, PointGeometry as aD, PolygonGeometry as aE, CircleToolSettings as aF, HighlighterToolSettings as aG, LineToolSettings as aH, MarkerToolSettings as aI, NoteToolSettings as aJ, PinToolSettings as aK, PlaceFrame as aL, PlaceSymbol as aM, PolygonToolSettings as aN, RouteToolSettings as aO, TextToolSettings as aP, UnionToIntersection as aQ, PromiseOrNot as aR, PlaceElementCreate as aa, PlaceElementRead as ab, PlaceElementUpdate as ac, PolygonElementCreate as ad, PolygonElementRead as ae, PolygonElementUpdate as af, TextElementCreate as ag, TextElementRead as ah, TextElementUpdate as ai, LayerProcessingStatus as aj, RasterValue as ak, FilterExpression as al, FilterLogicGate as am, FilterTernary as an, AggregationConfig as ao, MultiAggregationConfig as ap, ValueConfiguration as aq, ElementGroupNode as ar, ElementNode as as, FeatureNode as at, LayerGroupNode as au, LayerNode as av, FeltBoundary as aw, FeltZoom as ax, LatLng as ay, LineStringGeometry as az, ElementGroup as b, GetElementGroupsConstraint as c, ElementChangeCallbackParams as d, ElementGroupChangeCallbackParams as e, ElementCreate as f, ElementUpdate as g, GetLayersConstraint as h, LayerChangeCallbackParams as i, LayerGroup as j, GetLayerGroupsConstraint as k, LayerGroupChangeCallbackParams as l, LegendItemIdentifier as m, LegendItem as n, LegendItemsConstraint as o, LegendItemChangeCallbackParams as p, LayerFilters as q, GetRenderedFeaturesConstraint as r, Feature as s, GetLayerCategoriesParams as t, GetLayerCategoriesGroup as u, GetLayerHistogramParams as v, GetLayerHistogramBin as w, GetLayerCalculationParams as x, MapDetails as y, EntityNode as z };
+export type { ImageElementRead as $, AggregationMethod as A, FeatureSelection as B, ConfigurableToolType as C, ToolSettingsMap as D, Element as E, Filters as F, Geometry as G, ToolSettingsChangeEvent as H, InputToolSettings as I, zInfer as J, SortConfig as K, Layer as L, MapInteractionEvent as M, SetViewportCenterZoomParams as N, ViewportConstraints as O, ViewportFitBoundsParams as P, ViewportCenterZoom as Q, CircleElementCreate as R, SetVisibilityRequest as S, ToolType as T, CircleElementRead as U, ViewportState as V, CircleElementUpdate as W, HighlighterElementCreate as X, HighlighterElementRead as Y, HighlighterElementUpdate as Z, ImageElementCreate as _, GetElementsConstraint as a, ImageElementUpdate as a0, LinkElementRead as a1, MarkerElementCreate as a2, MarkerElementRead as a3, MarkerElementUpdate as a4, NoteElementCreate as a5, NoteElementRead as a6, NoteElementUpdate as a7, PathElementCreate as a8, PathElementRead as a9, LineStringGeometry as aA, LngLatTuple as aB, MultiLineStringGeometry as aC, MultiPolygonGeometry as aD, PointGeometry as aE, PolygonGeometry as aF, SortDirection as aG, CircleToolSettings as aH, HighlighterToolSettings as aI, LineToolSettings as aJ, MarkerToolSettings as aK, NoteToolSettings as aL, PinToolSettings as aM, PlaceFrame as aN, PlaceSymbol as aO, PolygonToolSettings as aP, RouteToolSettings as aQ, TextToolSettings as aR, UnionToIntersection as aS, PromiseOrNot as aT, PathElementUpdate as aa, PlaceElementCreate as ab, PlaceElementRead as ac, PlaceElementUpdate as ad, PolygonElementCreate as ae, PolygonElementRead as af, PolygonElementUpdate as ag, TextElementCreate as ah, TextElementRead as ai, TextElementUpdate as aj, LayerProcessingStatus as ak, RasterValue as al, FilterExpression as am, FilterLogicGate as an, FilterTernary as ao, AggregationConfig as ap, MultiAggregationConfig as aq, ValueConfiguration as ar, ElementGroupNode as as, ElementNode as at, FeatureNode as au, LayerGroupNode as av, LayerNode as aw, FeltBoundary as ax, FeltZoom as ay, LatLng as az, ElementGroup as b, GetElementGroupsConstraint as c, ElementChangeCallbackParams as d, ElementGroupChangeCallbackParams as e, ElementCreate as f, ElementUpdate as g, GetLayersConstraint as h, LayerChangeCallbackParams as i, LayerGroup as j, GetLayerGroupsConstraint as k, LayerGroupChangeCallbackParams as l, LegendItemIdentifier as m, LegendItem as n, LegendItemsConstraint as o, LegendItemChangeCallbackParams as p, LayerFilters as q, GetRenderedFeaturesConstraint as r, Feature as s, GetLayerCategoriesParams as t, GetLayerCategoriesGroup as u, GetLayerHistogramParams as v, GetLayerHistogramBin as w, GetLayerCalculationParams as x, MapDetails as y, EntityNode as z };