@feltmaps/js-sdk 1.7.0-next.21 → 1.7.0-next.22

package/dist/{controller-BPKMlMAI.d.ts → controller-Bf6iA9-c.d.ts}

@@ -4124,7 +4124,7 @@ interface ElementChangeCallbackParams {
      *
      * If the user is editing an existing element, this will be false.
      *
-     * For elements that are created programatically, this will be false.
+     * For elements that are created programmatically, this will be false.
      */
     isBeingCreated: boolean;
 }
@@ -4251,7 +4251,7 @@ interface ElementsController {
      * @example
      * ```typescript
      * const unsubscribe = felt.onElementCreate({
-     *   handler: (element) => console.log(element.id),
+     *   handler: ({isBeingCreated, element}) => console.log(element.id),
      * });
      *
      * // later on...
@@ -4262,7 +4262,7 @@ interface ElementsController {
         /**
          * The handler that is called when an element is created.
          *
-         * This will fire when elements are created programatically, or when the
+         * This will fire when elements are created programmatically, 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
@@ -4294,7 +4294,7 @@ interface ElementsController {
      * @event
      * @example
      * ```typescript
-     * const unsubscribe = felt.onToolCreatedElement({
+     * const unsubscribe = felt.onElementCreateEnd({
      *   handler: (params) => console.log(params),
      * });
      *
@@ -4316,7 +4316,7 @@ interface ElementsController {
      * 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.
+     * or programmatically.
      *
      * Like the {@link ElementsController.onElementCreate | `onElementCreate`} listener, this will fire when an element is
      * still being created by a drawing tool.
@@ -4416,19 +4416,21 @@ interface ElementsController {
      */
     createElement(element: ElementCreate): Promise<Element>;
     /**
-     * Update an element on the map.
+     * Update an element on the map. The element type must be specified.
      *
      * @example
      * ```typescript
      * // Update a place element's coordinates
      * await felt.updateElement({
      *   id: "element-1",
+     *   type: "Place",
      *   coordinates: [10, 20]
      * });
      *
      * // Update a polygon's style
      * await felt.updateElement({
      *   id: "element-2",
+     *   type: "Polygon",
      *   color: "#ABC123",
      *   fillOpacity: 0.5
      * });
@@ -4754,7 +4756,7 @@ interface GeoJsonUrlVectorSource extends zInfer<typeof GeoJsonUrlVectorSourceSch
 }
 /**
  * A GeoJSON data source is a layer that is populated from GeoJSON data, such as
- * from a local file, or programatically-created data.
+ * from a local file, or programmatically-created data.
  *
  * @group Layer sources
  */
@@ -6784,7 +6786,7 @@ interface LayersController {
      * // first get the current style
      * const oldStyle = (await felt.getLayer("layer-1")).style;
      *
-     * felt.setLayerStyle({ id: "layer-1", style: {
+     * await felt.setLayerStyle({ id: "layer-1", style: {
      *   ...oldStyle,
      *   paint: {
      *     ...oldStyle.paint,
@@ -6866,7 +6868,7 @@ interface LayersController {
      *
      * const layerFromUrl = await felt.createLayersFromGeoJson({
      *   source: {
-     *     sourceType: "geoJsonUrl",
+     *     type: "geoJsonUrl",
      *     url: "https://example.com/parcels.geojson",
      *   },
      *   name: "Parcels",
@@ -7447,15 +7449,18 @@ interface LayersController {
      * 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.
+     * When you request an aggregation other than count, you must specify an attribute to
+     * aggregate on.
      *
      * @example
      * ```typescript
      * // Count all residential buildings
      * const residentialCount = await felt.getAggregates({
      *   layerId: "buildings",
-     *   filters: ["type", "eq", "residential"]
+     *   filters: ["type", "eq", "residential"],
+     *   aggregation: {
+     *     methods: ["count"],
+     *   }
      * });
      *
      * // Calculate average home value in a specific neighborhood
@@ -7833,7 +7838,7 @@ interface SelectionController {
      */
     selectFeature(params: FeatureSelection): Promise<void>;
     /**
-     * Clears the current selection. This clears the selection of
+     * Clears the current selection (elements, features or both)
      *
      * @example
      * ```typescript
@@ -10354,70 +10359,54 @@ declare const uiPanelSchema: z.ZodObject<z.objectUtil.extendShape<z.objectUtil.e
     }, ...args: unknown[]) => void) | undefined;
 }>;
 /**
- * Represents a panel in the UI.
- * It can be added to the map by using the {@link UiController.createOrUpdatePanel} method.
- *
- * A panel is a container for other UI elements.
- * It can have a title, a body, a footer as well as a close button.
+ * A UI panel that can be added to the map using {@link UiController.createOrUpdatePanel}.
  *
- * The body and footer are arrays of UI elements and turn into vertical stacks of elements.
- *
- * The close button is a button rendered in the top right corner of the panel that can be
- * used to close the panel and is only visible if `onClickClose` is provided.
- * Usually, you want to call {@link UiController.deletePanel} when the close button is clicked,
- * e.g. `onClickClose: () => felt.deletePanel("my-panel")`.
+ * Panels are containers for UI elements with title, body, footer, and close button.
+ * Body and footer elements are arranged in vertical stacks.
  *
  * #### Body
- * Body is the main content of the panel. It is scrollable which means
- * that it can contain a lot of elements.
+ * Main content area that scrolls when content exceeds available space.
  *
  * #### Footer
- * Footer is sticky to the bottom of the panel, and can be used to add actions to the panel (e.g. save, cancel, etc.).
- *
- * @example
- * #### basic
- * ```typescript
- * {
- *   title: "My Panel",
- *   body: [
- *     { type: "Text", text: "Hello" },
- *   ],
- * }
- * ```
+ * Sticky bottom section for action buttons (e.g., Save, Cancel).
  *
- * @example
- * #### closable
- * ```typescript
- * {
- *   id: "my-panel",
- *   title: "My Panel",
- *   onClickClose: () => felt.deletePanel("my-panel"),
- * }
+ * #### Close Button
+ * Optional close icon in header. When `onClickClose` is provided, you must handle
+ * panel cleanup and removal.
  *
  * @example
- * #### form
  * ```typescript
- * {
- *   title: "My Panel",
- *   body: [
- *     { type: "Text", text: "Introduce your name and last name" },
- *     { type: "TextInput", label: "Name", value: "", placeholder: "John", onChange: (value) => setName(value) },
- *     { type: "TextInput", label: "Last name", value: "", placeholder: "Doe", onChange: (value) => setLastName(value) },
- *   ],
- *   footer: [
- *     {
- *       type: "Grid",
- *       grid: "auto-flow / 1fr auto auto",
- *       items: [
- *         { type: "FlexibleSpace" }, // this will make the buttons to be aligned to the end of the panel
- *         { type: "Button", label: "Reset", onClick: () => alert("Reset") },
- *         { type: "Button", label: "Save", onClick: () => alert("Save") },
- *       ],
- *     },
- *   ],
- * }
+ * // 1. Create panel ID
+ * const panelId = await felt.createPanelId();
+ *
+ * // 2. Create panel with close button and footer
+ * await felt.createOrUpdatePanel({
+ *   panel: {
+ *     id: panelId,
+ *     title: "My Panel",
+ *     body: [
+ *       { type: "Text", content: "Hello, world!" },
+ *       { type: "TextInput", label: "Name", placeholder: "Enter your name" }
+ *     ],
+ *     footer: [
+ *       {
+ *         type: "ButtonRow",
+ *         align: "end",
+ *         items: [
+ *           { type: "Button", label: "Cancel", onClick: () => handleCancel() },
+ *           { type: "Button", label: "Save", onClick: () => handleSave() }
+ *         ]
+ *       }
+ *     ],
+ *     onClickClose: (args) => {
+ *       // Clean up any state or resources
+ *       cleanupResources();
+ *       // Close the panel
+ *       felt.deletePanel(panelId);
+ *     }
+ *   }
+ * });
  * ```
- *
  */
 interface UIPanel extends UIElementBase, Omit<zInfer<typeof uiPanelSchema>, "onClickClose" | "body" | "footer" | "onCreate" | "onDestroy" | "id"> {
     /**
@@ -13086,10 +13075,10 @@ interface UiController {
      * ```typescript
      * await felt.createActionTrigger({
      *   actionTrigger: {
-     *     id: "layerTurnPurple", // not required but useful for further updates
-     *     label: "Turn layer purple",
+     *     id: "enablePolygonTool", // optional. Required if you want to update the action trigger later
+     *     label: "Draw polygon",
      *     onTrigger: async () => {
-     *       await felt.setLayerStyle("layer-1", { ..., paint: { color: "purple" } });
+     *       felt.setTool("polygon");
      *     },
      *     disabled: false, // optional, defaults to false
      *   },
@@ -13111,8 +13100,8 @@ interface UiController {
      * @example
      * ```typescript
      * await felt.updateActionTrigger({
-     *   id: "layerTurnPurple",
-     *   label: "Turn layer points purple", // only label changes
+     *   id: "enablePolygonTool",
+     *   label: "Enable polygon tool", // only label changes
      * });
      * ```
      */
@@ -13124,7 +13113,7 @@ interface UiController {
      *
      * @example
      * ```typescript
-     * await felt.deleteActionTrigger("layerTurnPurple");
+     * await felt.deleteActionTrigger("enablePolygonTool");
      * ```
      */
     deleteActionTrigger(id: string): void;
@@ -13142,66 +13131,72 @@ interface UiController {
     /**
      * Creates or updates a panel.
      *
-     * Panels are rendered on map's right sidebar and are useful to extend Felt UI for your own use cases
-     * (e.g. a form, a settings panel, etc.) using Felt UI elements (e.g. Text, Button, etc.).
-     * This way it is possible to cover new use cases while keeping the user experience consistent with the rest of Felt.
+     * Panels are rendered on the map's right sidebar and allow you to extend Felt UI
+     * for your own use cases using Felt UI elements (e.g., Text, Button, etc.).
      *
-     * A panel is identified by its ID and must come from {@link createPanelId}.
-     * Custom IDs are not supported in order to prevent conflicts with other panels.
+     * A panel is identified by its ID, which must be created using {@link createPanelId}.
+     * Custom IDs are not supported to prevent conflicts with other panels.
      *
-     * Panels have two sections:
-     *  - `body` - Body of the panel, scrollable.
-     *  - `footer` - It sticks to the bottom of the panel, useful to add submit buttons.
+     * Panels have two main sections:
+     *  - `body` - The main content area of the panel, which is scrollable.
+     *  - `footer` - A section that sticks to the bottom of the panel, useful for
+     *    action buttons like "Submit" or "Cancel".
      *
-     * Regarding panel placement, by default it is added to the end of the panels stack but you can
-     * specify a different placement by using the `initialPlacement` parameter.
-     * This placement cannot be updated later.
+     * Panel placement is controlled by the `initialPlacement` parameter. By default,
+     * panels are added to the end of the panel stack, but you can specify a different
+     * placement. Note that this placement cannot be changed after the panel is created.
      *
-     * When adding a panel, its elements' ids are optional though it is recommended to make
-     * it easier to update or delete them later.
+     * Element IDs are required for targeted updates and deletions using the other
+     * panel management methods. For complete panel refreshes with this method,
+     * element IDs are optional but recommended for consistency.
      *
-     * Once created, you can add elements to the panel by using the {@link createPanelElements} method,
-     * perform partial updates of elements by using the {@link updatePanelElements} method or
-     * delete elements by using the {@link deletePanelElements} method.
+     * For dynamic content management, consider these approaches:
+     *  - Use this method for complete panel refreshes (replaces all content)
+     *  - Use {@link createPanelElements} to add new elements to existing panels
+     *  - Use {@link updatePanelElements} to modify specific existing elements
+     *  - Use {@link deletePanelElements} to remove specific elements
      *
-     * @param args - The arguments for the method.
-     * @param args.panel - The panel to add.
-     * @param args.initialPlacement - The placement of the panel when added. Optional. Defaults to `{ at: "end" }`.
-     * - `{ at: "start" }` - Add the panel to the start of the stack.
-     * - `{ at: "end" }` - Add the panel to the end of the stack.
-     * - `{ after: "panel-1" }` - Add the panel after the panel with the id `panel-1`.
-     * - `{ before: "panel-1" }` - Add the panel before the panel with the id `panel-1`.
+     * @param args - The arguments for creating or updating the panel.
+     * @param args.panel - The panel configuration to create or update.
+     * @param args.initialPlacement - The placement of the panel when first added.
+     *   Optional. Defaults to `{ at: "end" }`.
+     *   - `{ at: "start" }` - Add the panel to the start of the stack.
+     *   - `{ at: "end" }` - Add the panel to the end of the stack.
+     *   - `{ after: "panel-1" }` - Add the panel after the panel with the id `panel-1`.
+     *   - `{ before: "panel-1" }` - Add the panel before the panel with the id `panel-1`.
      *
      * @example
      * ```typescript
-     * const id = await felt.createPanelId();
+     * // 1. Create panel ID first (required)
+     * const panelId = await felt.createPanelId();
      *
+     * // 2. Define reusable elements
+     * const SELECT = { id: "layer-select", type: "Select", label: "Layer", options: [...] };
+     * const ANALYZE_BTN = { id: "analyze-btn", type: "Button", label: "Analyze", onClick: handleAnalyze };
+     * const STATUS_TEXT = { id: "status-text", type: "Text", content: "" };
+     * const CLEAR_BTN = { id: "clear-btn", type: "Button", label: "Clear", onClick: handleClear };
+     *
+     * // 3. Initial state
      * await felt.createOrUpdatePanel({
-     *    panel: {
-     *       id,
-     *       title: "My Panel",
-     *       body: [
-     *          {
-     *             type: "Text",
-     *             content: "Hello, world!",
-     *          },
-     *          {
-     *             type: "TextInput",
-     *             label: "Name",
-     *             placeholder: "Enter your name",
-     *             value: "",
-     *             onChange: ({ value }) => setName(value),
-     *          },
-     *       ],
-     *       footer: [
-     *          {
-     *             type: "Button",
-     *             label: "Submit",
-     *             onClick: () => submitForm(),
-     *          },
-     *       ],
-     *    },
-     *    initialPlacement: { at: "start" }, // when added, the panel will be added to the start of the stack
+     *   panel: { id: panelId, title: "Data Analyzer", body: [SELECT, ANALYZE_BTN] }
+     * });
+     *
+     * // 4. Loading state (replaces entire panel)
+     * await felt.createOrUpdatePanel({
+     *   panel: {
+     *     id: panelId,
+     *     title: "Data Analyzer",
+     *     body: [SELECT, ANALYZE_BTN, { ...STATUS_TEXT, content: "Loading..." }]
+     *   }
+     * });
+     *
+     * // 5. Results state (replaces entire panel)
+     * await felt.createOrUpdatePanel({
+     *   panel: {
+     *     id: panelId,
+     *     title: "Data Analyzer",
+     *     body: [SELECT, ANALYZE_BTN, { ...STATUS_TEXT, content: "**Results:**\n- Found 150 features" }, CLEAR_BTN]
+     *   }
      * });
      * ```
      */
@@ -13254,22 +13249,36 @@ interface UiController {
      */
     createPanelElements(args: CreatePanelElementsParams): Promise<UIPanel>;
     /**
-     * Updates an element in a panel.
+     * Updates an existing element in a panel. This method can only update elements that
+     * already exist in the panel and have an ID.
      *
      * @param args - The arguments for the method.
      * @param args.panelId - The id of the panel to update the element in.
-     * @param args.elements - Array of elements to update (`id` and `type` are required to identify the element to update).
+     * @param args.elements - Array of elements to update. Each element must have an `id` and `type`
+     *   to identify which existing element to update. The element must already exist in the panel.
      *
      * @example
      * ```typescript
+     * // 1. Create panel with initial elements
+     * const panelId = await felt.createPanelId();
+     * const STATUS_TEXT = { id: "status-text", type: "Text", content: "Ready" };
+     *
+     * await felt.createOrUpdatePanel({
+     *   panel: {
+     *     id: panelId,
+     *     title: "My Panel",
+     *     body: [STATUS_TEXT]
+     *   }
+     * });
+     *
+     * // 2. Update the existing element
      * await felt.updatePanelElements({
      *   panelId,
      *   elements: [
      *     {
      *       element: {
-     *         id: "element-1",
-     *         type: "Text",
-     *         content: "Hello, world!",
+     *         ...STATUS_TEXT,                    // Reuse the same element structure
+     *         content: "Updated content"         // Only change what needs updating
      *       },
      *     },
      *   ],