@feltmaps/js-sdk 1.5.0-next.9 → 1.6.0-next.0

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { E as Element, G as Geometry, a as GetElementsConstraint, b as ElementGroup, c as GetElementGroupsConstraint, S as SetVisibilityRequest, d as ElementChangeCallbackParams, e as ElementGroupChangeCallbackParams, f as ElementCreate, g as ElementUpdate, L as Layer, h as GetLayersConstraint, i as LayerChangeCallbackParams, j as LayerGroup, k as GetLayerGroupsConstraint, l as LayerGroupChangeCallbackParams, m as LegendItemIdentifier, n as LegendItem, o as LegendItemsConstraint, p as LegendItemChangeCallbackParams, q as LayerFilters, F as Filters, r as GetRenderedFeaturesConstraint, s as Feature, t as GetLayerCategoriesParams, u as GetLayerCategoriesGroup, v as GetLayerHistogramParams, w as GetLayerHistogramBin, A as AggregationMethod, x as GetLayerCalculationParams, M as MapInteractionEvent, y as MapDetails, z as EntityNode, B as FeatureSelection, T as ToolType, I as InputToolSettings, C as ConfigurableToolType, D as ToolSettingsMap, H as ToolSettingsChangeEvent, J as zInfer, K as SortConfig, V as ViewportState, N as SetViewportCenterZoomParams, O as ViewportConstraints, P as ViewportFitBoundsParams, Q as ViewportCenterZoom } from './types-6AWHhIPp.js';
-export { ap as AggregationConfig, R as CircleElementCreate, U as CircleElementRead, W as CircleElementUpdate, aH as CircleToolSettings, as as ElementGroupNode, at as ElementNode, au as FeatureNode, ax as FeltBoundary, ay as FeltZoom, am as FilterExpression, an as FilterLogicGate, ao as FilterTernary, X as HighlighterElementCreate, Y as HighlighterElementRead, Z as HighlighterElementUpdate, aI as HighlighterToolSettings, _ as ImageElementCreate, $ as ImageElementRead, a0 as ImageElementUpdate, az as LatLng, av as LayerGroupNode, aw as LayerNode, ak as LayerProcessingStatus, aA as LineStringGeometry, aJ as LineToolSettings, a1 as LinkElementRead, aB as LngLatTuple, a2 as MarkerElementCreate, a3 as MarkerElementRead, a4 as MarkerElementUpdate, aK as MarkerToolSettings, aq as MultiAggregationConfig, aC as MultiLineStringGeometry, aD as MultiPolygonGeometry, a5 as NoteElementCreate, a6 as NoteElementRead, a7 as NoteElementUpdate, aL as NoteToolSettings, a8 as PathElementCreate, a9 as PathElementRead, aa as PathElementUpdate, aM as PinToolSettings, ab as PlaceElementCreate, ac as PlaceElementRead, ad as PlaceElementUpdate, aN as PlaceFrame, aO as PlaceSymbol, aE as PointGeometry, ae as PolygonElementCreate, af as PolygonElementRead, ag as PolygonElementUpdate, aF as PolygonGeometry, aP as PolygonToolSettings, al as RasterValue, aQ as RouteToolSettings, aG as SortDirection, ah as TextElementCreate, ai as TextElementRead, aj as TextElementUpdate, aR as TextToolSettings, ar as ValueConfiguration } from './types-6AWHhIPp.js';
+import { E as Element, G as GeoJsonGeometry, a as GetElementsConstraint, b as ElementGroup, c as GetElementGroupsConstraint, S as SetVisibilityRequest, d as ElementChangeCallbackParams, e as ElementGroupChangeCallbackParams, f as ElementCreate, g as ElementUpdate, M as MapInteractionEvent, h as MapDetails, i as EntityNode, F as FeatureSelection, T as ToolType, I as InputToolSettings, C as ConfigurableToolType, j as ToolSettingsMap, k as ToolSettingsChangeEvent, z as zInfer, l as SortConfig, V as ViewportState, m as SetViewportCenterZoomParams, n as ViewportConstraints, o as ViewportFitBoundsParams, L as LayersController, p as ViewportCenterZoom } from './types-B241Rd9q.js';
+export { aF as AggregationConfig, aG as AggregationMethod, q as CircleElementCreate, r as CircleElementRead, s as CircleElementUpdate, b4 as CircleToolSettings, a1 as CreateLayersFromGeoJsonParams, a2 as DataOnlyLayer, aO as ElementGroupNode, aP as ElementNode, aQ as FeatureNode, aT as FeltBoundary, a3 as FeltTiledVectorSource, aU as FeltZoom, az as FilterExpression, aA as FilterLogicGate, aB as FilterTernary, aC as Filters, a4 as GeoJsonDataVectorSource, aV as GeoJsonFeature, a5 as GeoJsonFileVectorSource, aW as GeoJsonProperties, a6 as GeoJsonUrlVectorSource, aD as GeometryFilter, aH as GetLayerCalculationParams, aI as GetLayerCategoriesGroup, aJ as GetLayerCategoriesParams, a7 as GetLayerGroupsConstraint, aK as GetLayerHistogramBin, aL as GetLayerHistogramParams, a8 as GetLayersConstraint, a9 as GetRenderedFeaturesConstraint, H as HighlighterElementCreate, t as HighlighterElementRead, u as HighlighterElementUpdate, b5 as HighlighterToolSettings, v as ImageElementCreate, w as ImageElementRead, x as ImageElementUpdate, aX as LatLng, aa as Layer, ab as LayerChangeCallbackParams, ac as LayerCommon, ap as LayerFeature, aE as LayerFilters, ad as LayerGroup, ae as LayerGroupChangeCallbackParams, aR as LayerGroupNode, aS as LayerNode, af as LayerProcessingStatus, ar as LayerSchema, as as LayerSchemaAttribute, at as LayerSchemaBooleanAttribute, au as LayerSchemaCommonAttribute, av as LayerSchemaDateAttribute, aw as LayerSchemaDateTimeAttribute, ax as LayerSchemaNumericAttribute, ay as LayerSchemaTextAttribute, ag as LegendItem, ah as LegendItemChangeCallbackParams, ai as LegendItemIdentifier, aj as LegendItemsConstraint, aY as LineStringGeometry, b6 as LineToolSettings, y as LinkElementRead, aZ as LngLatTuple, A as MarkerElementCreate, B as MarkerElementRead, D as MarkerElementUpdate, b7 as MarkerToolSettings, aM as MultiAggregationConfig, a_ as MultiLineStringGeometry, a$ as MultiPointGeometry, b0 as MultiPolygonGeometry, N as NoteElementCreate, J as NoteElementRead, K as NoteElementUpdate, b8 as NoteToolSettings, P as PathElementCreate, O as PathElementRead, Q as PathElementUpdate, b9 as PinToolSettings, R as PlaceElementCreate, U as PlaceElementRead, W as PlaceElementUpdate, ba as PlaceFrame, bb as PlaceSymbol, b1 as PointGeometry, X as PolygonElementCreate, Y as PolygonElementRead, Z as PolygonElementUpdate, b2 as PolygonGeometry, bc as PolygonToolSettings, ak as RasterBand, al as RasterLayer, am as RasterLayerSource, aq as RasterValue, bd as RouteToolSettings, b3 as SortDirection, _ as TextElementCreate, $ as TextElementRead, a0 as TextElementUpdate, be as TextToolSettings, an as UpdateLayerParams, aN as ValueConfiguration, ao as VectorLayer } from './types-B241Rd9q.js';
 import { z } from 'zod';
 
 /**
@@ -25,7 +25,23 @@ interface ElementsController {
      */
     id: string): Promise<Element | null>;
     /**
-     * Get the geometry of an element.
+     * Get the geometry of an element in GeoJSON geometry format.
+     *
+     * For most element types, the geometry returned is based on the `coordinates`
+     * property of the element, with some differences:
+     *
+     * - For Circle elements, the geometry is a Polygon drawn from the `center` and
+     * `radius` properties.
+     *
+     * - Path elements become MultiLineString geometries.
+     *
+     * - Marker elements return a MultiLineString of the path traced by the user
+     * as they drew the marker. Note that this is not the polygon formed by filled-in
+     * "pen" stroke, which doesn't exactly follow the path traced by the user as it
+     * is smoothed and interpolated to create a continuous line.
+     *
+     * - Text, Note and Image elements do not return geometry, so will return `null`.
+     *
      *
      * @example
      * ```typescript
@@ -37,7 +53,7 @@ interface ElementsController {
     /**
      * The id of the element you want to get the geometry of.
      */
-    id: string): Promise<Geometry | null>;
+    id: string): Promise<GeoJsonGeometry | null>;
     /**
      * Gets elements from the map, according to the constraints supplied. If no
      * constraints are supplied, all elements will be returned.
@@ -121,7 +137,7 @@ interface ElementsController {
          * still being created by a drawing tool.
          *
          * If you want to know when the element is finished being created, you can
-         * use the `onToolCreateElementEnd` listener.
+         * use the {@link ElementsController.onElementCreateEnd | `onElementCreateEnd`} listener.
          *
          * @param change - An object describing the change that occurred.
          */
@@ -130,7 +146,7 @@ interface ElementsController {
     /**
      * Listens for when a new element is finished being created by a drawing tool.
      *
-     * This differs from the `onElementCreate` listener, which fires whenever an
+     * This differs from the {@link ElementsController.onElementCreate | `onElementCreate`} listener, which fires whenever an
      * element is first created. This fires when the user finishes creating an element
      * which could be after a series of interactions.
      *
@@ -140,6 +156,7 @@ interface ElementsController {
      *
      * @returns A function to unsubscribe from the listener
      *
+     * @event
      * @example
      * ```typescript
      * const unsubscribe = felt.onToolCreatedElement({
@@ -166,10 +183,10 @@ interface ElementsController {
      * This will fire when an element is being edited, either on the map by the user
      * or programatically.
      *
-     * Like the `onElementCreate` listener, this will fire when an element is
+     * Like the {@link ElementsController.onElementCreate | `onElementCreate`} listener, this will fire when an element is
      * still being created by a drawing tool.
      *
-     * You can check the `isBeingCreated` property to determine if the element is
+     * You can check the {@link ElementChangeCallbackParams.isBeingCreated | `isBeingCreated`} property to determine if the element is
      * still being created by a drawing tool.
      *
      * @returns A function to unsubscribe from the listener
@@ -212,7 +229,7 @@ interface ElementsController {
      * ```typescript
      * const unsubscribe = felt.onElementDelete({
      *   options: { id: "element-1" },
-     *   handler: (element) => console.log(element.id),
+     *   handler: () => console.log("element-1 deleted"),
      * });
      *
      * // later on...
@@ -265,518 +282,33 @@ interface ElementsController {
     createElement(element: ElementCreate): Promise<Element>;
     /**
      * Update an element on the map.
-     */
-    updateElement(element: ElementUpdate): Promise<Element>;
-    /**
-     * Delete an element from the map.
-     */
-    deleteElement(id: string): Promise<void>;
-}
-
-/**
- * The Layers controller allows you to get information about the layers on the
- * map, and make changes to their visibility.
- *
- * Layers can be organised into groups, and their groups can also have their
- * visibility toggled.
- *
- * @group Controller
- * @public
- */
-interface LayersController {
-    /**
-     * Get a single layer from the map by its id.
-     *
-     * @example
-     * ```typescript
-     * const layer = await felt.getLayer("layer-1");
-     * ```
-     * @returns The requested layer.
-     */
-    getLayer(
-    /**
-     * The id of the layer you want to get.
-     */
-    id: string): Promise<Layer | null>;
-    /**
-     * Gets layers from the map, according to the constraints supplied. If no
-     * constraints are supplied, all layers will be returned.
-     *
-     * @remarks The layers in the map, ordered by the order specified in Felt. This is not
-     * necessarily the order that they are drawn in, as Felt draws points above
-     * lines and lines above polygons, for instance.
-     *
-     * @example
-     * ```typescript
-     * const layers = await felt.getLayers();
-     * ```
-     * @returns All layers on the map.
-     */
-    getLayers(
-    /**
-     * The constraints to apply to the layers returned from the map.
-     */
-    constraint?: GetLayersConstraint): Promise<Array<Layer | null>>;
-    /**
-     * Hide or show layers with the given ids.
-     *
-     * @example
-     * ```typescript
-     * felt.setLayerVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] });
-     * ```
-     */
-    setLayerVisibility(visibility: SetVisibilityRequest): Promise<void>;
-    /**
-     * Set the style for a layer using FSL, the Felt Style Language.
-     *
-     * Changes are only for this session, and not persisted. This is useful to make
-     * temporary changes to a layer's style, such as to highlight a particular layer
-     * or feature.
-     *
-     * See the [FSL documentation](https://developers.felt.com/felt-style-language) for details
-     * on how to read and write styles.
-     *
-     * If the style you set is invalid, you will receive an error explaining the problem
-     * in the rejected promise value.
-     *
-     * @example
-     * ```typescript
-     * // first get the current style
-     * const oldStyle = (await felt.getLayer("layer-1")).style;
-     *
-     * felt.setLayerStyle({ id: "layer-1", style: {
-     *   ...oldStyle,
-     *   paint: {
-     *     ...oldStyle.paint,
-     *     color: "red",
-     *   },
-     * } });
-     * ```
-     */
-    setLayerStyle(params: {
-        /**
-         * The id of the layer to set the style for.
-         */
-        id: string;
-        /**
-         * The style to set for the layer.
-         */
-        style: object;
-    }): Promise<void>;
-    /**
-     * Hide or show layers with the given ids from the legend.
-     *
-     * @example
-     * ```typescript
-     * felt.setLayerLegendVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] });
-     * ```
-     */
-    setLayerLegendVisibility(params: SetVisibilityRequest): Promise<void>;
-    /**
-     * Adds a listener for when a layer changes.
      *
-     * @returns A function to unsubscribe from the listener
-     *
-     * @event
      * @example
      * ```typescript
-     * const unsubscribe = felt.onLayerChange({
-     *   options: { id: "layer-1" },
-     *   handler: ({layer}) => console.log(layer.bounds),
+     * // Update a place element's coordinates
+     * await felt.updateElement({
+     *   id: "element-1",
+     *   coordinates: [10, 20]
      * });
      *
-     * // later on...
-     * unsubscribe();
-     * ```
-     */
-    onLayerChange(args: {
-        options: {
-            /**
-             * The id of the layer to listen for changes to.
-             */
-            id: string;
-        };
-        /**
-         * The handler that is called when the layer changes.
-         */
-        handler: (
-        /**
-         * An object describing the change that occurred.
-         */
-        change: LayerChangeCallbackParams) => void;
-    }): VoidFunction;
-    /**
-     * Get a layer group from the map by its id.
-     *
-     * @example
-     * ```typescript
-     * const layerGroup = await felt.getLayerGroup("layer-group-1");
-     * ```
-     * @returns The requested layer group.
-     */
-    getLayerGroup(id: string): Promise<LayerGroup | null>;
-    /**
-     * Gets layer groups from the map, according to the constraints supplied. If no
-     * constraints are supplied, all layer groups will be returned in rendering order.
-     *
-     * @example
-     * ```typescript
-     * const layerGroups = await felt.getLayerGroups({ ids: ["layer-group-1", "layer-group-2"] });
-     * ```
-     * @returns The requested layer groups.
-     */
-    getLayerGroups(
-    /**
-     * The constraints to apply to the layer groups returned from the map.
-     */
-    constraint?: GetLayerGroupsConstraint): Promise<Array<LayerGroup | null>>;
-    /**
-     * Hide or show layer groups with the given ids.
-     *
-     * @example
-     * ```typescript
-     * felt.setLayerGroupVisibility({ show: ["layer-group-1", "layer-group-2"], hide: ["layer-group-3"] });
-     * ```
-     */
-    setLayerGroupVisibility(visibility: SetVisibilityRequest): Promise<void>;
-    /**
-     * Hide or show layer groups with the given ids from the legend.
-     *
-     * @example
-     * ```typescript
-     * felt.setLayerGroupLegendVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] });
-     * ```
-     */
-    setLayerGroupLegendVisibility(params: SetVisibilityRequest): Promise<void>;
-    /**
-     * Adds a listener for when a layer group changes.
-     *
-     * @returns A function to unsubscribe from the listener
-     *
-     * @event
-     * @example
-     * ```typescript
-     * const unsubscribe = felt.onLayerGroupChange({
-     *   options: { id: "layer-group-1" },
-     *   handler: ({layerGroup}) => console.log(layerGroup.id),
+     * // Update a polygon's style
+     * await felt.updateElement({
+     *   id: "element-2",
+     *   color: "#ABC123",
+     *   fillOpacity: 0.5
      * });
-     *
-     * // later on...
-     * unsubscribe();
-     * ```
-     */
-    onLayerGroupChange(args: {
-        options: {
-            id: string;
-        };
-        handler: (change: LayerGroupChangeCallbackParams) => void;
-    }): VoidFunction;
-    /**
-     * Allows you to get the state of a single legend item.
-     *
-     * @example
-     * ```typescript
-     * const legendItem = await felt.getLegendItem({
-     *   id: "legend-item-1",
-     *   layerId: "layer-1",
-     * })
-     * ```
-     */
-    getLegendItem(id: LegendItemIdentifier): Promise<LegendItem | null>;
-    /**
-     * Allows you to obtain the state of several legend items, by passing in
-     * constraints describing which legend items you want.
-     *
-     * If you do not pass any constraints, you will receive all legend items.
-     *
-     * @example
-     * ```typescript
-     * const legendItems = await felt.getLegendItems({layerId: "layer-1"});
-     * ```
-     */
-    getLegendItems(constraint?: LegendItemsConstraint): Promise<Array<LegendItem | null>>;
-    /**
-     * Hide or show legend items with the given identifiers.
-     *
-     * @example
-     * ```typescript
-     * felt.setLegendItemVisibility({
-     *   show: [{layerId: "layer-group-1", id: "item-1-0"}],
-     *   hide: [{layerId: "layer-group-2", id: "item-2-0"}],
-     * })
      * ```
      */
-    setLegendItemVisibility(visibility: {
-        show?: Array<LegendItemIdentifier>;
-        hide?: Array<LegendItemIdentifier>;
-    }): Promise<void>;
-    /**
-     * Adds a listener for when a legend item changes.
-     *
-     * @returns A function to unsubscribe from the listener
-     *
-     * @event
-     * @example
-     * ```typescript
-     * const unsubscribe = felt.onLegendItemChange({
-     *   options: { layerId: "layer-1", id: "item-1-0" },
-     *   handler: ({legendItem}) => console.log(legendItem.visible),
-     * });
-     *
-     * // later on...
-     * unsubscribe();
-     * ```
-     */
-    onLegendItemChange(args: {
-        options: LegendItemIdentifier;
-        handler: (change: LegendItemChangeCallbackParams) => void;
-    }): VoidFunction;
-    /**
-     * Get the filters for a layer.
-     *
-     * @remarks
-     * The return type gives you the filters split up into the various sources
-     * that make up the overall filters for a layer.
-     *
-     * @example
-     * ```typescript
-     * const filters = await felt.getLayerFilters("layer-1");
-     * console.log(filters.combined, filters.style, filters.ephemeral, filters.components);
-     * ```
-     */
-    getLayerFilters(layerId: string): Promise<LayerFilters | null>;
-    /**
-     * Sets the **ephemeral** filters for a layer.
-     *
-     * @example
-     * ```typescript
-     * felt.setLayerFilters({
-     *   layerId: "layer-1",
-     *   filters: ["AREA", "gt", 30_000],
-     * });
-     * ```
-     */
-    setLayerFilters(params: {
-        /**
-         * The layer that you want to set the filters for.
-         */
-        layerId: string;
-        /**
-         * The filters to set for the layer. This will replace any ephemeral filters
-         * that are currently set for the layer.
-         */
-        filters: Filters;
-        /**
-         * A note to display on the layer legend when this filter is applied. When the
-         * note is shown, a reset button will also be shown, allowing the user to clear
-         * the filter.
-         */
-        note?: string;
-    }): Promise<void>;
-    /**
-     * Adds a listener for when a layer's filters change.
-     *
-     * @returns A function to unsubscribe from the listener
-     *
-     * @remarks
-     * This event fires whenever any type of filter changes on the layer, including
-     * ephemeral filters set via the SDK, style-based filters, or filters set through
-     * the Felt UI via Components.
-     *
-     * @event
-     * @example
-     * ```typescript
-     * const unsubscribe = felt.onLayerFiltersChange({
-     *   options: { layerId: "layer-1" },
-     *   handler: ({combined, ephemeral, style, components}) => {
-     *     console.log("Layer filters updated:", {
-     *       combined,  // All filters combined
-     *       ephemeral, // Filters set via SDK
-     *       style,     // Filters from layer style
-     *       components // Filters from UI components
-     *     });
-     *   },
-     * });
-     *
-     * // later on...
-     * unsubscribe();
-     * ```
-     */
-    onLayerFiltersChange(params: {
-        options: {
-            layerId: string;
-        };
-        handler: (change: LayerFilters) => void;
-    }): VoidFunction;
-    /**
-     * Get the features that are currently **rendered** on the map in the viewport.
-     *
-     * Note that this is explicitly about the features that are rendered, which isn't
-     * necessarily a complete list of all the features in the viewport. This is because
-     * of the way features are tiled: at low zoom levels or high feature densities, many
-     * features are omitted from what is rendered on the screen.
-     *
-     * @example
-     * ```typescript
-     * const features = await felt.getRenderedFeatures();
-     * ```
-     */
-    getRenderedFeatures(
-    /**
-     * The constraints to apply to the features returned from the map.
-     */
-    params?: GetRenderedFeaturesConstraint): Promise<Array<Feature>>;
-    /**
-     * Gets values from a layer grouped by a given attribute.
-     *
-     * @remarks
-     * Groups features in your layer by unique values in the specified attribute and calculates
-     * a value for each group. By default, this value is the count of features in each group.
-     *
-     * You can apply filters in two ways:
-     * 1. At the top level (using `boundary` and `filters`), which affects both what categories
-     *    are included and how values are calculated
-     * 2. In the `values` configuration, which only affects the values but keeps all categories
-     *
-     * This two-level filtering is particularly useful when you want to compare subsets of data
-     * while maintaining consistent categories. For example, you might want to show the distribution
-     * of all building types in a city, but only count buildings built after 2000 in each category.
-     *
-     * @example
-     * ```typescript
-     * // Basic grouping: Count of buildings by type
-     * const buildingsByType = await felt.getCategoryData({
-     *   layerId: "buildings",
-     *   attribute: "type"
-     * });
-     *
-     * // Filtered grouping: Only count buildings in downtown
-     * const downtownBuildingsByType = await felt.getCategoryData({
-     *   layerId: "buildings",
-     *   attribute: "type",
-     *   boundary: [-122.43, 47.60, -122.33, 47.62]  // downtown boundary
-     * });
-     *
-     * // Advanced: Show all building types, but only sum floor area of recent buildings
-     * const recentBuildingAreaByType = await felt.getCategoryData({
-     *   layerId: "buildings",
-     *   attribute: "type",
-     *   values: {
-     *     filters: ["year_built", "gte", 2000],
-     *     aggregation: {
-     *       method: "sum",
-     *       attribute: "floor_area"
-     *     }
-     *   }
-     * });
-     *
-     * // Compare residential density across neighborhoods while only counting recent buildings
-     * const newBuildingDensityByNeighborhood = await felt.getCategoryData({
-     *   layerId: "buildings",
-     *   attribute: "neighborhood",
-     *   values: {
-     *     filters: ["year_built", "gte", 2000],
-     *     aggregation: {
-     *       method: "avg",
-     *       attribute: "units_per_acre"
-     *     }
-     *   }
-     * });
-     * ```
-     */
-    getCategoryData(params: GetLayerCategoriesParams): Promise<Array<GetLayerCategoriesGroup>>;
-    /**
-     * Gets a histogram of values from a layer for a given attribute.
-     *
-     * @remarks
-     * Creates bins (ranges) for numeric data and counts how many features fall into each bin,
-     * or returns aggregated values for each bin.
-     *
-     * You can control how the bins are created using the `steps` parameter, choosing from
-     * several methods like equal intervals, quantiles, or natural breaks (Jenks), or passing
-     * in the step values directly if you know how you want to bin the data.
-     *
-     * Like getCategoryData, you can apply filters in two ways:
-     * 1. At the top level (using `boundary` and `filters`), which affects both how the bins
-     *    are calculated and what features are counted in each bin
-     * 2. In the `values` configuration, which only affects what gets counted but keeps the
-     *    bin ranges the same
-     *
-     * This is particularly useful when you want to compare distributions while keeping
-     * consistent bin ranges. For example, you might want to compare the distribution of
-     * building heights in different years while using the same height ranges.
-     *
-     * @example
-     * ```typescript
-     * // Basic histogram: Building heights in 5 natural break bins
-     * const buildingHeights = await felt.getHistogramData({
-     *   layerId: "buildings",
-     *   attribute: "height",
-     *   steps: { type: "jenks", count: 5 }
-     * });
-     *
-     * // Compare old vs new buildings using the same height ranges
-     * const oldBuildingHeights = await felt.getHistogramData({
-     *   layerId: "buildings",
-     *   attribute: "height",
-     *   steps: [0, 20, 50, 100, 200, 500],
-     *   values: {
-     *     filters: ["year_built", "lt", 1950]
-     *   }
-     * });
-     *
-     * const newBuildingHeights = await felt.getHistogramData({
-     *   layerId: "buildings",
-     *   attribute: "height",
-     *   steps: [0, 20, 50, 100, 200, 500],  // Same ranges as above
-     *   values: {
-     *     filters: ["year_built", "gte", 1950]
-     *   }
-     * });
-     * ```
-     */
-    getHistogramData(params: GetLayerHistogramParams): Promise<Array<GetLayerHistogramBin>>;
+    updateElement(element: ElementUpdate): Promise<Element>;
     /**
-     * Calculates a single aggregate value for a layer based on the provided configuration.
-     *
-     * @remarks
-     * Performs statistical calculations on your data, like counting features or computing
-     * averages, sums, etc. You can focus your calculation on specific areas or subsets
-     * of your data using boundaries and filters.
-     *
-     * When no aggregation is specified, it counts features. When an aggregation is provided,
-     * it performs that calculation (average, sum, etc.) on the specified attribute.
+     * Delete an element from the map.
      *
      * @example
      * ```typescript
-     * // Count all residential buildings
-     * const residentialCount = await felt.getAggregates({
-     *   layerId: "buildings",
-     *   filters: ["type", "eq", "residential"]
-     * });
-     *
-     * // Calculate average home value in a specific neighborhood
-     * const avgHomeValue = await felt.getAggregates({
-     *   layerId: "buildings",
-     *   boundary: [-122.43, 47.60, -122.33, 47.62],  // neighborhood boundary
-     *   aggregation: {
-     *     method: "avg",
-     *     attribute: "assessed_value"
-     *   }
-     * });
-     *
-     * // Find the maximum building height for buildings built after 2000
-     * const maxNewBuildingHeight = await felt.getAggregates({
-     *   layerId: "buildings",
-     *   filters: ["year_built", "gte", 2000],
-     *   aggregation: {
-     *     method: "max",
-     *     attribute: "height"
-     *   }
-     * });
+     * await felt.deleteElement("element-1");
      * ```
      */
-    getAggregates<T extends AggregationMethod | "count">(params: GetLayerCalculationParams<T>): Promise<Record<T, number | null>>;
+    deleteElement(id: string): Promise<void>;
 }
 
 /**
@@ -813,8 +345,12 @@ interface InteractionsController {
      * @event
      * @example
      * ```typescript
+     * // Track mouse movement and features under cursor
      * const unsubscribe = felt.onPointerMove({
-     *   handler: (event) => console.log(event.center, event.features),
+     *   handler: (event) => {
+     *     console.log("Mouse position:", event.center);
+     *     console.log("Features under cursor:", event.features);
+     *   }
      * });
      *
      * // later on...
@@ -840,6 +376,16 @@ interface InteractionsController {
 interface MiscController {
     /**
      * Gets the details of the map.
+     *
+     * @example
+     * ```typescript
+     * const details = await felt.getMapDetails();
+     * console.log({
+     *   id: details.id,
+     *   title: details.title,
+     *   description: details.description,
+     * });
+     * ```
      */
     getMapDetails(): Promise<MapDetails>;
 }
@@ -960,10 +506,10 @@ interface ToolsController {
      * @example
      * ```typescript
      * // Set the tool to "marker"
-     * felt.setTool("marker");
+     * await felt.setTool("marker");
      *
      * // put down the tool
-     * felt.setTool(null);
+     * await felt.setTool(null);
      * ```
      */
     setTool(tool: ToolType | null): void;
@@ -1004,18 +550,41 @@ interface ToolsController {
     /**
      * Sets the settings for the current tool.
      *
+     * @example
+     * ```typescript
+     * // Set the settings for the marker tool
+     * await felt.setToolSettings({
+     *   tool: "marker",
+     *   color: "#FE17",
+     * });
+     * ```
+     *
      * @param settings - The settings to set.
      */
     setToolSettings(settings: InputToolSettings): void;
     /**
-     * Gets the settings for the current tool.
+     * Gets the settings for the chosen tool
      *
-     * @returns The settings for the current tool.
+     * @example
+     * ```typescript
+     * const settings = await felt.getToolSettings("marker");
+     * ```
+     *
+     * @returns The settings for the chosen tool.
      */
     getToolSettings<T extends ConfigurableToolType>(tool: T): Promise<ToolSettingsMap[T]>;
     /**
      * Listens for changes to the settings on all tools.
      *
+     * @example
+     * ```typescript
+     * const unsubscribe = felt.onToolSettingsChange({
+     *   handler: settings => console.log(settings),
+     * });
+     *
+     * // later on...
+     * unsubscribe();
+     * ```
      * @returns A function to unsubscribe from the listener
      */
     onToolSettingsChange(args: {
@@ -1174,6 +743,21 @@ interface UiController {
     /**
      * Updates the UI controls on the embedded map.
      *
+     * @example
+     * ```typescript
+     * // Show some UI controls
+     * await felt.updateUiControls({
+     *   showLegend: true,
+     *   fullScreenButton: true,
+     * });
+     *
+     * // Disable some UI options
+     * await felt.updateUiControls({
+     *   cooperativeGestures: false,
+     *   geolocation: false,
+     * });
+     * ```
+     *
      * @param controls - The controls to update.
      */
     updateUiControls(controls: UiControlsOptions): void;
@@ -1187,6 +771,15 @@ interface UiController {
      *
      * This does not affect selection. That means that selectable features and elements
      * will still be selected when clicked.
+     *
+     * @example
+     * ```typescript
+     * // Disable UI when hovering or selecting features
+     * await felt.setOnMapInteractionsUi({
+     *   featureSelectPanel: false,
+     *   featureHoverPanel: false,
+     * });
+     * ```
      */
     setOnMapInteractionsUi(options: UiOnMapInteractionsOptions): void;
     /**
@@ -1239,6 +832,16 @@ interface UiController {
 interface ViewportController {
     /**
      * Gets the current state of the viewport.
+     *
+     * @example
+     * ```typescript
+     * // Get current viewport state
+     * const viewport = await felt.getViewport();
+     * console.log({
+     *   center: viewport.center,
+     *   zoom: viewport.zoom,
+     * });
+     * ```
      */
     getViewport(): Promise<ViewportState>;
     /**
@@ -1255,6 +858,21 @@ interface ViewportController {
     setViewport(viewport: SetViewportCenterZoomParams): void;
     /**
      * Gets the current state of the viewport constraints.
+     *
+     * @example
+     * ```typescript
+     * // Get current viewport constraints
+     * const constraints = await felt.getViewportConstraints();
+     * if (constraints) {
+     *   console.log({
+     *     bounds: constraints.bounds,
+     *     minZoom: constraints.minZoom,
+     *     maxZoom: constraints.maxZoom
+     *   });
+     * } else {
+     *   console.log("No viewport constraints set");
+     * }
+     * ```
      */
     getViewportConstraints(): Promise<ViewportConstraints | null>;
     /**
@@ -1449,17 +1067,17 @@ declare const FeltEmbedOptionsSchema: z.ZodObject<{
         }>;
         zoom: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        zoom: number;
         center: {
             latitude: number;
             longitude: number;
         };
-    }, {
         zoom: number;
+    }, {
         center: {
             latitude: number;
             longitude: number;
         };
+        zoom: number;
     }>>;
 }, "strip", z.ZodTypeAny, {
     origin?: string | undefined;
@@ -1473,11 +1091,11 @@ declare const FeltEmbedOptionsSchema: z.ZodObject<{
         scaleBar?: boolean | undefined;
     } | undefined;
     initialViewport?: {
-        zoom: number;
         center: {
             latitude: number;
             longitude: number;
         };
+        zoom: number;
     } | undefined;
 }, {
     origin?: string | undefined;
@@ -1491,11 +1109,11 @@ declare const FeltEmbedOptionsSchema: z.ZodObject<{
         scaleBar?: boolean | undefined;
     } | undefined;
     initialViewport?: {
-        zoom: number;
         center: {
             latitude: number;
             longitude: number;
         };
+        zoom: number;
     } | undefined;
 }>;
 
@@ -1538,12 +1156,13 @@ declare const FeltEmbedOptionsSchema: z.ZodObject<{
  */
 declare const Felt: {
     /**
-     * Embeds a Felt map into the provided container.
+     * Embeds a Felt map into the provided container, returning a promise that resolves
+     * to a {@link FeltController} object that you can use to control the map.
      *
      * @param container - The container element to embed the map into.
      * @param mapId - The ID of the map to embed.
      * @param options - The options to configure the map.
-     * @returns
+     * @returns A promise for a {@link FeltController}.
      */
     embed(container: HTMLElement, mapId: string, options?: FeltEmbedOptions): Promise<FeltController>;
     /**
@@ -1552,7 +1171,7 @@ declare const Felt: {
      * @param feltWindow - The iframe element containing the Felt map.
      * @returns
      */
-    connect(feltWindow: Window): Promise<FeltController>;
+    connect(feltWindow: Pick<Window, "postMessage">): Promise<FeltController>;
 };
 
-export { AggregationMethod, ConfigurableToolType, Element, ElementChangeCallbackParams, ElementCreate, ElementGroup, ElementGroupChangeCallbackParams, ElementUpdate, type ElementsController, EntityNode, Feature, FeatureSelection, Felt, type FeltController, type FeltEmbedOptions, Filters, Geometry, GetElementGroupsConstraint, GetElementsConstraint, GetLayerCalculationParams, GetLayerCategoriesGroup, GetLayerCategoriesParams, GetLayerGroupsConstraint, GetLayerHistogramBin, GetLayerHistogramParams, GetLayersConstraint, GetRenderedFeaturesConstraint, InputToolSettings, type InteractionsController, Layer, LayerChangeCallbackParams, LayerFilters, LayerGroup, LayerGroupChangeCallbackParams, type LayersController, LegendItem, LegendItemChangeCallbackParams, LegendItemIdentifier, LegendItemsConstraint, MapDetails, MapInteractionEvent, type MiscController, type UiOnMapInteractionsOptions as OnMapInteractionsOptions, type SelectionController, SetViewportCenterZoomParams, SetVisibilityRequest, SortConfig, ToolSettingsChangeEvent, ToolSettingsMap, ToolType, type ToolsController, type UiController, type UiControlsOptions, ViewportCenterZoom, ViewportConstraints, type ViewportController, ViewportFitBoundsParams, ViewportState };
+export { ConfigurableToolType, Element, ElementChangeCallbackParams, ElementCreate, ElementGroup, ElementGroupChangeCallbackParams, ElementUpdate, type ElementsController, EntityNode, FeatureSelection, Felt, type FeltController, type FeltEmbedOptions, GeoJsonGeometry, GetElementGroupsConstraint, GetElementsConstraint, InputToolSettings, type InteractionsController, LayersController, MapDetails, MapInteractionEvent, type MiscController, type UiOnMapInteractionsOptions as OnMapInteractionsOptions, type SelectionController, SetViewportCenterZoomParams, SetVisibilityRequest, SortConfig, ToolSettingsChangeEvent, ToolSettingsMap, ToolType, type ToolsController, type UiController, type UiControlsOptions, ViewportCenterZoom, ViewportConstraints, type ViewportController, ViewportFitBoundsParams, ViewportState };