@feltmaps/js-sdk 1.5.0-next.2 → 1.5.0-next.21

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, L as Layer, f as GetLayersConstraint, g as LayerChangeCallbackParams, h as LayerGroup, i as GetLayerGroupsConstraint, j as LayerGroupChangeCallbackParams, k as LegendItemIdentifier, l as LegendItem, m as LegendItemsConstraint, n as LegendItemChangeCallbackParams, o as LayerFilters, F as Filters, p as GetRenderedFeaturesConstraint, q as Feature, M as MapInteractionEvent, r as EntityNode, s as FeatureSelection, T as ToolType, I as InputToolSettings, C as ConfigurableToolType, t as ToolSettingsMap, u as ToolSettingsChangeEvent, z as zInfer, V as ViewportState, v as SetViewportCenterZoomParams, w as ViewportConstraints, x as ViewportFitBoundsParams, y as ViewportCenterZoom } from './types-BLsf5GHN.js';
-export { a1 as CircleToolSettings, J as ElementGroupNode, K as ElementNode, N as FeatureNode, Q as FeltBoundary, U as FeltZoom, B as FilterExpression, D as FilterLogicGate, H as FilterTernary, a2 as HighlighterToolSettings, W as LatLng, O as LayerGroupNode, P as LayerNode, A as LayerProcessingStatus, X as LineStringGeometry, a3 as LineToolSettings, Y as LngLatTuple, a4 as MarkerToolSettings, Z as MultiLineStringGeometry, _ as MultiPolygonGeometry, a5 as NoteToolSettings, a6 as PinFrame, a7 as PinSymbol, a8 as PinToolSettings, $ as PointGeometry, a0 as PolygonGeometry, a9 as PolygonToolSettings, R as RasterValue, aa as RouteToolSettings, ab as TextToolSettings } from './types-BLsf5GHN.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, L as Layer, h as GetLayersConstraint, i as LayerChangeCallbackParams, C as CreateLayersFromGeoJsonParams, 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 LayerFeature, t as GeoJsonFeature, u as GetLayerCategoriesParams, v as GetLayerCategoriesGroup, w as GetLayerHistogramParams, x as GetLayerHistogramBin, A as AggregationMethod, y as GetLayerCalculationParams, z as LayerSchema, M as MapInteractionEvent, B as MapDetails, D as EntityNode, H as FeatureSelection, T as ToolType, I as InputToolSettings, J as ConfigurableToolType, K as ToolSettingsMap, N as ToolSettingsChangeEvent, O as zInfer, P as SortConfig, V as ViewportState, Q as SetViewportCenterZoomParams, R as ViewportConstraints, U as ViewportFitBoundsParams, W as ViewportCenterZoom } from './types-f_Zc32jS.js';
+export { aJ as AggregationConfig, X as CircleElementCreate, Y as CircleElementRead, Z as CircleElementUpdate, b2 as CircleToolSettings, an as DataOnlyLayer, aN as ElementGroupNode, aO as ElementNode, aP as FeatureNode, aS as FeltBoundary, ao as FeltTiledVectorSource, aT as FeltZoom, aG as FilterExpression, aH as FilterLogicGate, aI as FilterTernary, ap as GeoJsonDataVectorSource, aq as GeoJsonFileVectorSource, aU as GeoJsonProperties, ar as GeoJsonUrlVectorSource, aK as GeometryFilter, _ as HighlighterElementCreate, $ as HighlighterElementRead, a0 as HighlighterElementUpdate, b3 as HighlighterToolSettings, a1 as ImageElementCreate, a2 as ImageElementRead, a3 as ImageElementUpdate, aV as LatLng, as as LayerCommon, aQ as LayerGroupNode, aR as LayerNode, at as LayerProcessingStatus, az as LayerSchemaAttribute, aA as LayerSchemaBooleanAttribute, aB as LayerSchemaCommonAttribute, aC as LayerSchemaDateAttribute, aD as LayerSchemaDateTimeAttribute, aE as LayerSchemaNumericAttribute, aF as LayerSchemaTextAttribute, aW as LineStringGeometry, b4 as LineToolSettings, a4 as LinkElementRead, aX as LngLatTuple, a5 as MarkerElementCreate, a6 as MarkerElementRead, a7 as MarkerElementUpdate, b5 as MarkerToolSettings, aL as MultiAggregationConfig, aY as MultiLineStringGeometry, aZ as MultiPointGeometry, a_ as MultiPolygonGeometry, a8 as NoteElementCreate, a9 as NoteElementRead, aa as NoteElementUpdate, b6 as NoteToolSettings, ab as PathElementCreate, ac as PathElementRead, ad as PathElementUpdate, b7 as PinToolSettings, ae as PlaceElementCreate, af as PlaceElementRead, ag as PlaceElementUpdate, b8 as PlaceFrame, b9 as PlaceSymbol, a$ as PointGeometry, ah as PolygonElementCreate, ai as PolygonElementRead, aj as PolygonElementUpdate, b0 as PolygonGeometry, ba as PolygonToolSettings, au as RasterBand, av as RasterLayer, aw as RasterLayerSource, ax as RasterValue, bb as RouteToolSettings, b1 as SortDirection, ak as TextElementCreate, al as TextElementRead, am as TextElementUpdate, bc as TextToolSettings, aM as ValueConfiguration, ay as VectorLayer } from './types-f_Zc32jS.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.
@@ -62,7 +78,7 @@ interface ElementsController {
      *
      * @example
      * ```typescript
-     * felt.getElementGroup("element-group-1");
+     * const elementGroup = await felt.getElementGroup("element-group-1");
      * ```
      * @returns The requested element group.
      */
@@ -91,9 +107,88 @@ interface ElementsController {
      * ```
      */
     setElementGroupVisibility(visibility: SetVisibilityRequest): Promise<void>;
+    /**
+     * Adds a listener for when an element is created.
+     *
+     * @returns A function to unsubscribe from the listener
+     *
+     * @event
+     * @example
+     * ```typescript
+     * const unsubscribe = felt.onElementCreate({
+     *   handler: (element) => console.log(element.id),
+     * });
+     *
+     * // later on...
+     * unsubscribe();
+     * ```
+     */
+    onElementCreate(args: {
+        /**
+         * The handler that is called when an element is created.
+         *
+         * This will fire when elements are created programatically, or when the
+         * user starts creating an element with a drawing tool.
+         *
+         * When the user creates an element with a drawing tool, it can begin in
+         * an invalid state, such as if you've just placed a single point in a polygon.
+         *
+         * You can use the `isBeingCreated` property to determine if the element is
+         * still being created by a drawing tool.
+         *
+         * If you want to know when the element is finished being created, you can
+         * use the {@link ElementsController.onElementCreateEnd | `onElementCreateEnd`} listener.
+         *
+         * @param change - An object describing the change that occurred.
+         */
+        handler: (change: ElementChangeCallbackParams) => void;
+    }): VoidFunction;
+    /**
+     * Listens for when a new element is finished being created by a drawing tool.
+     *
+     * 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.
+     *
+     * For example, when creating a polygon, the user places a series of points then
+     * finishes by pressing Enter or Escape. Or when creating a Place element, they
+     * add the marker, type a label, then finally deselect the element.
+     *
+     * @returns A function to unsubscribe from the listener
+     *
+     * @event
+     * @example
+     * ```typescript
+     * const unsubscribe = felt.onToolCreatedElement({
+     *   handler: (params) => console.log(params),
+     * });
+     *
+     * // later on...
+     * unsubscribe();
+     * ```
+     */
+    onElementCreateEnd(args: {
+        /**
+         * The handler to call whenever this event fires.
+         *
+         * @param params - An object containing the element that was created.
+         */
+        handler: (params: {
+            element: Element;
+        }) => void;
+    }): VoidFunction;
     /**
      * Adds a listener for when an element changes.
      *
+     * This will fire when an element is being edited, either on the map by the user
+     * or programatically.
+     *
+     * 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 {@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
      *
      * @event
@@ -124,6 +219,35 @@ interface ElementsController {
          */
         change: ElementChangeCallbackParams) => void;
     }): VoidFunction;
+    /**
+     * Adds a listener for when an element is deleted.
+     *
+     * @returns A function to unsubscribe from the listener
+     *
+     * @event
+     * @example
+     * ```typescript
+     * const unsubscribe = felt.onElementDelete({
+     *   options: { id: "element-1" },
+     *   handler: () => console.log("element-1 deleted"),
+     * });
+     *
+     * // later on...
+     * unsubscribe();
+     * ```
+     */
+    onElementDelete(args: {
+        options: {
+            /**
+             * The id of the element to listen for deletions of.
+             */
+            id: string;
+        };
+        /**
+         * The handler that is called when the element is deleted.
+         */
+        handler: () => void;
+    }): VoidFunction;
     /**
      * Adds a listener for when an element group changes.
      *
@@ -147,6 +271,44 @@ interface ElementsController {
         };
         handler: (change: ElementGroupChangeCallbackParams) => void;
     }): VoidFunction;
+    /**
+     * Create a new element on the map.
+     *
+     * @example
+     * ```typescript
+     * const element = await felt.createElement({ type: "Place", coordinates: [10, 10] });
+     * ```
+     */
+    createElement(element: ElementCreate): Promise<Element>;
+    /**
+     * Update an element on the map.
+     *
+     * @example
+     * ```typescript
+     * // Update a place element's coordinates
+     * await felt.updateElement({
+     *   id: "element-1",
+     *   coordinates: [10, 20]
+     * });
+     *
+     * // Update a polygon's style
+     * await felt.updateElement({
+     *   id: "element-2",
+     *   color: "#ABC123",
+     *   fillOpacity: 0.5
+     * });
+     * ```
+     */
+    updateElement(element: ElementUpdate): Promise<Element>;
+    /**
+     * Delete an element from the map.
+     *
+     * @example
+     * ```typescript
+     * await felt.deleteElement("element-1");
+     * ```
+     */
+    deleteElement(id: string): Promise<void>;
 }
 
 /**
@@ -165,7 +327,7 @@ interface LayersController {
      *
      * @example
      * ```typescript
-     * const layers = await felt.getLayer({ ids: ["layer-1", "layer-2"] });
+     * const layer = await felt.getLayer("layer-1");
      * ```
      * @returns The requested layer.
      */
@@ -281,12 +443,60 @@ interface LayersController {
          */
         change: LayerChangeCallbackParams) => void;
     }): VoidFunction;
+    /**
+     * Adds layers to the map from file or URL sources.
+     *
+     * @remarks This allows you to add temporary layers to the map that don't depend on
+     * any processing by Felt. This is useful for viewing data from external sources or
+     * remote files.
+     *
+     * @returns The layer groups that were created.
+     *
+     * @example
+     * ```typescript
+     * const layerFromFile = await felt.createLayersFromGeoJson({
+     *   source: {
+     *     type: "geoJsonFile",
+     *     file: someFile,
+     *   },
+     *   name: "Parcels",
+     * });
+     *
+     * const layerFromUrl = await felt.createLayersFromGeoJson({
+     *   source: {
+     *     sourceType: "geoJsonUrl",
+     *     url: "https://example.com/parcels.geojson",
+     *   },
+     *   name: "Parcels",
+     * ```
+     */
+    createLayersFromGeoJson(params: CreateLayersFromGeoJsonParams): Promise<{
+        /**
+         * The layer group that was created containing the created layers.
+         */
+        layerGroup: LayerGroup;
+        /**
+         * The layers that were created from the source.
+         */
+        layers: Array<Layer>;
+    } | null>;
+    /**
+     * Delete a layer from the map by its id.
+     *
+     * @remarks This only works for layers created via the SDK `createLayersFromGeoJson` method, not layers added via the Felt UI.
+     *
+     * @example
+     * ```typescript
+     * await felt.deleteLayer("layer-1");
+     * ```
+     */
+    deleteLayer(id: string): Promise<void>;
     /**
      * Get a layer group from the map by its id.
      *
      * @example
      * ```typescript
-     * felt.getLayerGroup("layer-group-1");
+     * const layerGroup = await felt.getLayerGroup("layer-group-1");
      * ```
      * @returns The requested layer group.
      */
@@ -426,7 +636,7 @@ interface LayersController {
      *
      * @example
      * ```typescript
-     * felt.setLayerFilters({
+     * await felt.setLayerFilters({
      *   layerId: "layer-1",
      *   filters: ["AREA", "gt", 30_000],
      * });
@@ -449,6 +659,41 @@ interface LayersController {
          */
         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.
      *
@@ -466,7 +711,209 @@ interface LayersController {
     /**
      * The constraints to apply to the features returned from the map.
      */
-    params?: GetRenderedFeaturesConstraint): Promise<Array<Feature>>;
+    params?: GetRenderedFeaturesConstraint): Promise<Array<LayerFeature>>;
+    /**
+     * Get a feature from the map by its ID and layer ID.
+     *
+     * The response is a {@link LayerFeature} object, which does not include the
+     * geometry of the feature.
+     *
+     * You may want to use this when you don't need the geometry of a feature,
+     * but you know the ID of the feature you need.
+     *
+     * @example
+     * ```typescript
+     * const feature = await felt.getFeature({ layerId: "layer-1", id: 123 });
+     * ```
+     */
+    getFeature(params: {
+        id: string | number;
+        layerId: string;
+    }): Promise<LayerFeature | null>;
+    /**
+     * Get a feature in GeoJSON format from the map by its ID and layer ID.
+     *
+     * The response is a GeoJSON Feature object with the complete geometry of the
+     * feature. Note that for some _very_ large geometries, the response may take a
+     * long time to return, and may return a very large object.
+     *
+     * @example
+     * ```typescript
+     * const feature = await felt.getGeoJsonFeature({ layerId: "layer-1", id: 123 });
+     * ```
+     */
+    getGeoJsonFeature(params: {
+        id: string | number;
+        layerId: string;
+    }): Promise<GeoJsonFeature | null>;
+    /**
+     * 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>>;
+    /**
+     * 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.
+     *
+     * @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"
+     *   }
+     * });
+     * ```
+     */
+    getAggregates<T extends AggregationMethod | "count">(params: GetLayerCalculationParams<T>): Promise<Record<T, number | null>>;
+    /**
+     * Get the schema for a layer.
+     *
+     * @remarks
+     * The schema describes the structure of the data in a layer, including the attributes
+     * that are available on the features in the layer.
+     *
+     * This can be useful to build generic UIs that need to know the structure of the data in
+     * a layer, such as a dropdown to choose an attribute.
+     *
+     * @example
+     * ```typescript
+     * const schema = await felt.getLayerSchema({ layerId: "layer-1" });
+     * const attributeIds = schema.attributes.map((attr) => attr.id);
+     * ```
+     */
+    getLayerSchema(layerId: string): Promise<LayerSchema>;
 }
 
 /**
@@ -503,8 +950,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...
@@ -523,6 +974,27 @@ interface InteractionsController {
     }): VoidFunction;
 }
 
+/**
+ * @group Controller
+ * @public
+ */
+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>;
+}
+
 /**
  * The Selection controller allows you to listen for changes to the selection on the map.
  *
@@ -637,12 +1109,12 @@ interface ToolsController {
      * @param tool - The tool to set.
      *
      * @example
-     * ```ts
+     * ```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;
@@ -652,7 +1124,7 @@ interface ToolsController {
      * @returns The current tool, or `null` if no tool is in use.
      *
      * @example
-     * ```ts
+     * ```typescript
      * const tool = await felt.getTool(); // "marker", "polygon", etc.
      * ```
      */
@@ -663,7 +1135,7 @@ interface ToolsController {
      * @returns A function to unsubscribe from the listener
      *
      * @example
-     * ```ts
+     * ```typescript
      * const unsubscribe = felt.onToolChange({
      *   handler: tool => console.log(tool),
      * });
@@ -683,18 +1155,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
+     *
+     * @example
+     * ```typescript
+     * const settings = await felt.getToolSettings("marker");
+     * ```
      *
-     * @returns The settings for the current tool.
+     * @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: {
@@ -841,8 +1336,10 @@ declare const UiOnMapInteractionsOptionsSchema: z.ZodObject<{
 }>;
 
 /**
- * The UI controller allows you to enable and disable UI controls on the
- * embedded map.
+ * The UI controller allows you to control various aspects of the Felt UI in your embedded map.
+ *
+ * This includes enabling/disabling UI controls, managing on-map interactions, and controlling
+ * the visibility of UI components like the data table.
  *
  * @group Controller
  * @public
@@ -851,6 +1348,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;
@@ -864,8 +1376,53 @@ 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;
+    /**
+     * Shows a data table view for the specified layer, optionally sorted by a given attribute.
+     *
+     * @example
+     * ```typescript
+     * // Show data table with default sorting
+     * await felt.showLayerDataTable({
+     *   layerId: "layer-1",
+     * });
+     *
+     * // Show data table sorted by height in descending order
+     * await felt.showLayerDataTable({
+     *   layerId: "layer-1",
+     *   sorting: {
+     *     attribute: "height",
+     *     direction: "desc",
+     *   },
+     * });
+     *
+     * // Show the data table pane with no table visible
+     * await felt.showLayerDataTable();
+     * ```
+     */
+    showLayerDataTable(params?: {
+        layerId: string;
+        sorting?: SortConfig;
+    }): Promise<void>;
+    /**
+     * Hides the data table.
+     *
+     * @example
+     * ```typescript
+     * await felt.hideLayerDataTable();
+     * ```
+     */
+    hideLayerDataTable(): Promise<void>;
 }
 
 /**
@@ -880,6 +1437,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>;
     /**
@@ -896,6 +1463,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>;
     /**
@@ -1025,7 +1607,7 @@ interface ViewportController {
  * @group Controller
  * @public
  */
-interface FeltController extends ViewportController, UiController, LayersController, ElementsController, SelectionController, InteractionsController, ToolsController {
+interface FeltController extends ViewportController, UiController, LayersController, ElementsController, SelectionController, InteractionsController, ToolsController, InteractionsController, MiscController {
     /**
      * The iframe element containing the Felt map, if it is an embedded map.
      *
@@ -1179,12 +1761,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>;
     /**
@@ -1193,7 +1776,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 { ConfigurableToolType, Element, ElementChangeCallbackParams, ElementGroup, ElementGroupChangeCallbackParams, type ElementsController, EntityNode, Feature, FeatureSelection, Felt, type FeltController, type FeltEmbedOptions, Filters, Geometry, GetElementGroupsConstraint, GetElementsConstraint, GetLayerGroupsConstraint, GetLayersConstraint, GetRenderedFeaturesConstraint, InputToolSettings, type InteractionsController, Layer, LayerChangeCallbackParams, LayerFilters, LayerGroup, LayerGroupChangeCallbackParams, type LayersController, LegendItem, LegendItemChangeCallbackParams, LegendItemIdentifier, LegendItemsConstraint, MapInteractionEvent, type UiOnMapInteractionsOptions as OnMapInteractionsOptions, type SelectionController, SetViewportCenterZoomParams, SetVisibilityRequest, ToolSettingsChangeEvent, ToolSettingsMap, ToolType, type ToolsController, type UiController, type UiControlsOptions, ViewportCenterZoom, ViewportConstraints, type ViewportController, ViewportFitBoundsParams, ViewportState };
+export { AggregationMethod, ConfigurableToolType, CreateLayersFromGeoJsonParams, Element, ElementChangeCallbackParams, ElementCreate, ElementGroup, ElementGroupChangeCallbackParams, ElementUpdate, type ElementsController, EntityNode, FeatureSelection, Felt, type FeltController, type FeltEmbedOptions, Filters, GeoJsonFeature, GeoJsonGeometry, GetElementGroupsConstraint, GetElementsConstraint, GetLayerCalculationParams, GetLayerCategoriesGroup, GetLayerCategoriesParams, GetLayerGroupsConstraint, GetLayerHistogramBin, GetLayerHistogramParams, GetLayersConstraint, GetRenderedFeaturesConstraint, InputToolSettings, type InteractionsController, Layer, LayerChangeCallbackParams, LayerFeature, LayerFilters, LayerGroup, LayerGroupChangeCallbackParams, LayerSchema, 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 };