@arcgis/map-components 5.0.0-next.1 → 5.0.0-next.100

package/dist/components/arcgis-popup/customElement.d.ts

@@ -8,7 +8,6 @@ import { Alignment, DockOptions, PopupPositionResult, PopupPositionStyle, FetchF
 import { JsxNode, PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
 import { nil } from '@arcgis/toolkit/type';
 import { ArcgisFeature } from '../arcgis-feature/customElement.js';
-import { default as ActionButton } from '@arcgis/core/support/actions/ActionButton.js';
 declare const useFeaturesViewModel: (component: LitElement & Pick<FeaturesViewModel, never> & import('../../controllers/useViewModel').ViewModelControllerUses<FeaturesViewModel>) => FeaturesViewModel;
 
 /**
@@ -17,16 +16,50 @@ declare const useFeaturesViewModel: (component: LitElement & Pick<FeaturesViewMo
  * by providing users with a simple way to interact with and view attributes in a layer.
  * They play an important role in relaying information to the user, which improves the storytelling capabilities of the application.
  *
+ * The [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/), [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/), and [arcgis-link-chart](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-link-chart/) components currently use the [Popup widget](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Popup.html) by default.
+ * To use the Popup component, add it to the [arcgis-map.popup](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/#popup), [arcgis-scene.popup](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#popup), or [arcgis-link-chart.popup](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-link-chart/#popup) component using the `popup` slot.
+ * The Popup component will be opened automatically to display the selected feature's popup template when features in the Map, Scene, or Link Chart are clicked.
+ *
+ * ```html
+ * <arcgis-map id="06ca49d0ddb447e7817cfc343ca30df9">
+ *   <!-- Add the popup component to the popup slot. -->
+ *   <arcgis-popup slot="popup"></arcgis-popup>
+ * </arcgis-map>
+ * ```
+ * The Popup component can also be opened manually at a specific location with custom content specified in the method parameters using the `open()` method.
+ * To prevent the popup from opening automatically when clicking on features within view components, set the `popup-disabled` attribute to `true`.
+ *
+ * ```html
+ * <!-- Set popup-disabled attribute -->
+ * <arcgis-map id="06ca49d0ddb447e7817cfc343ca30df9" popup-disabled>
+ *   <!-- Add the popup component to the popup slot. -->
+ *   <arcgis-popup slot="popup"></arcgis-popup>
+ * </arcgis-map>
+ * <script>
+ * const viewElement = document.querySelector("arcgis-map");
+ * const popupComponent = document.querySelector("arcgis-popup");
+ * // Listen for clicks on the view and open the popup at the clicked location with custom content.
+ * viewElement.addEventListener("arcgisViewClick", (event) => {
+ *   const { mapPoint } = event.detail;
+ *   popupComponent.open({
+ *     location: mapPoint,
+ *     heading: "You clicked here",
+ *     content: "Latitude: " + mapPoint.latitude.toFixed(3) + ", Longitude: " + mapPoint.longitude.toFixed(3)
+ *   });
+ * });
+ * </script>
+ * ```
+ *
  * ## Popup UI
  * The [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/), [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/), or [arcgis-link-chart](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-link-chart/) components contain a default popup.
  * This popup can display generic content, which is set in its [heading](#heading)
  * and [content](#content) properties.
  * When  content is set directly on the Popup instance it is not tied to a specific feature or layer.
  *
- * [![popup-basic-example](https://developers.arcgis.com/javascript/latest/assets/img/apiref/widgets/popup/popup-basic.png)](../sample-code/sandbox/?sample=intro-popup)
+ * ![popup-basic-example](https://developers.arcgis.com/javascript/latest/assets/img/apiref/widgets/popup/popup-basic.png)
  *
  * In the image above, the text "Marriage in Nassau County Census Tract 5177.01" is the popup's [heading](#heading).
- * The remaining text is the popup's [`content`](#content).
+ * The remaining text is the popup's [content](#content).
  * A dock button is displayed in the top right corner of the popup allowing the user to dock the popup to one of the sides or corners of the view.
  * The options for docking may be set in the [dockOptions](#dockOptions) property.
  * The popup may also be collapsed by clicking the collapse button (the down arrow icon) in the top right corner of the popup.
@@ -55,8 +88,7 @@ declare const useFeaturesViewModel: (component: LitElement & Pick<FeaturesViewMo
  *
  * @since 4.34
  * @beta
- * @see module :esri/PopupTemplate
- * @see [Guide - Esri Icon Font](../guide/esri-icon-font/index.html)
+ * @see [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html)
  */
 export declare class ArcgisPopup extends LitElement {
     /**
@@ -66,7 +98,7 @@ export declare class ArcgisPopup extends LitElement {
      * By default, popups have a `Zoom To` action styled with a magnifying glass icon.
      * When this icon is clicked, the view zooms in four LODs and centers on the selected feature.
      * You may remove this default action by setting [includeDefaultActionsDisabled](#includeDefaultActionsDisabled) to `true`, or by setting the
-     * [`overwriteActions`](esri-PopupTemplate.html#overwriteActions) property to `true` in a [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html).
+     * [`overwriteActions`](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html#overwriteActions) property to `true` in a [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html).
      *
      * The order of each action is the order in which they appear in the actions [Collection](https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Collection.html).
      *
@@ -74,9 +106,6 @@ export declare class ArcgisPopup extends LitElement {
      *
      * @autocast { "value": "Object[]", "typedCollection": true, "byTypeProperty": true }
      * @see [arcgisTriggerAction](#arcgisTriggerAction)
-     * @see [Sample - Popup actions](../sample-code/popup-actions/index.html)
-     * @see [Sample - Custom popup actions per feature](../sample-code/popup-custom-action/index.html)
-     * @see [Sample - Popup with edit action](../sample-code/popup-editaction/index.html)
      * @example
      * ```js
      * // Defines an action button to zoom out from the selected feature
@@ -92,8 +121,26 @@ export declare class ArcgisPopup extends LitElement {
      * // Adds the custom action to the popup.
      * popupComponent.actions.push(zoomOutAction);
      * ```
+     * @see [@trigger-action](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Features-FeaturesViewModel.html#event-trigger-action)
+     * @see [Sample - Popup actions](https://developers.arcgis.com/javascript/latest/sample-code/popup-actions/)
+     * @example
+     * // Defines an action button to zoom out from the selected feature
+     * const zoomOutAction = {
+     *   type: "button",
+     *   // This text is displayed as a tooltip
+     *   title: "Zoom out",
+     *   // The ID by which to reference the action in the event handler
+     *   id: "zoom-out",
+     *   // Sets the icon used to style the action button
+     *   icon: "magnifying-glass-minus"
+     * };
+     * // Adds the custom action to the popup.
+     * view.popup.viewModel.actions.push(zoomOutAction);
+     *
+     * // Adds the custom action to the Features widget
+     * featuresWidget.viewModel.actions.push(zoomOutAction);
      */
-    actions: __esri.Collection<ActionButton | __esri.ActionToggle>;
+    actions: import('@arcgis/core/core/Collection').default<import('@arcgis/core/widgets/Popup/types').PopupAction>;
     /**
      * Indicates if the component is active when it is visible and is not [waiting](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Popup-PopupViewModel.html#waitingForResult).
      *
@@ -106,12 +153,12 @@ export declare class ArcgisPopup extends LitElement {
      * to explicitly control where the popup displays in relation to the feature, choose
      * an option besides `auto`.
      *
+     * @default "auto"
      * @example
      * ```js
      * // Popup will display on the bottom-right of the selected feature regardless of where that feature is located
      * popupComponent.alignment = "bottom-right";
      * ```
-     * @default "auto"
      */
     alignment: Alignment;
     /**
@@ -143,16 +190,23 @@ export declare class ArcgisPopup extends LitElement {
      * [PopupTemplate.content](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html#content).
      *
      * @noautocast
-     * @see [Sample - Popup Docking](../sample-code/popup-docking-position/index.html)
-     * @see [Sample - Popup with DOM node](../sample-code/popup-domnode/index.html)
      * @example
      * ```js
      * // This sets generic instructions in the popup that will always be displayed
      * // unless it is overridden by a PopupTemplate
      * popupComponent.content = "Click a feature on the map to view its attributes";
      * ```
+     * @see [Sample - Popup Docking](https://developers.arcgis.com/javascript/latest/sample-code/popup-docking-position/)
+     * @example
+     * // This sets generic instructions in the popup that will always be displayed
+     * // unless it is overridden by a PopupTemplate.
+     * // This can be set on the Features widget view model
+     * featuresWidget.viewModel.content = "Click a feature on the map to view its attributes";
+     *
+     * // Or set on the Popup widget view model.
+     * view.popup.viewModel.content = "Click a feature on the map to view its attributes";
      */
-    content: string | HTMLElement | nullish | __esri.Widget;
+    content: string | HTMLElement | import('@arcgis/core/widgets/Widget').default<any> | null | undefined;
     /** Dock position in the [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/), [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/), or [arcgis-link-chart](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-link-chart/) component. */
     get currentDockPosition(): nil | PopupPositionResult;
     /**
@@ -193,7 +247,7 @@ export declare class ArcgisPopup extends LitElement {
      *
      * See [dockOptions](#dockOptions) to override default options related to docking the popup.
      *
-     * @see [Sample - Popup docking](../sample-code/popup-docking-position/index.html)
+     * @default false
      * @example
      * ```html
      * <!-- Setting this property in HTML -->
@@ -205,7 +259,6 @@ export declare class ArcgisPopup extends LitElement {
      * // The popup will automatically be dockEnabled when made visible
      * popupComponent.dockEnabled = true;
      * ```
-     * @default false
      */
     dockEnabled: boolean;
     /**
@@ -217,7 +270,6 @@ export declare class ArcgisPopup extends LitElement {
      *
      * See the object specification table below to override default docking properties on the popup.
      *
-     * @see [Sample - Popup docking](../sample-code/popup-docking-position/index.html)
      * @example
      * ```js
      * popupComponent.dockOptions = {
@@ -245,6 +297,7 @@ export declare class ArcgisPopup extends LitElement {
      * This value will only be honored if [`initialDisplayMode`](#initialDisplayMode) is set to "feature".
      *
      * @default false
+     * @since 4.32
      */
     featureMenuOpen: boolean;
     /**
@@ -277,8 +330,23 @@ export declare class ArcgisPopup extends LitElement {
      * let graphics = [g1, g2, g3, g4, g5];
      * popupComponent.features = graphics;
      * ```
+     * @example
+     * // When setting the features property, the graphics pushed to this property
+     * // must have a PopupTemplate set.
+     * let g1 = new Graphic();
+     * g1.popupTemplate = new PopupTemplate({
+     *   title: "Results title",
+     *   content: "Results: {ATTRIBUTE_NAME}"
+     * });
+     * // Create an array of graphics and set this to the features property. The content and title of
+     * // will be set depending on the PopupTemplate of the graphics.
+     * // Each graphic may share the same PopupTemplate or have a unique PopupTemplate.
+     * let graphics = [g1, g2, g3, g4, g5];
+     * // This value can be set on the popup  or Features view model.
+     * view.popup.viewModel.features = graphics;
+     * featuresWidget.viewModel.features = graphics;
      */
-    features: __esri.Graphic[];
+    features: import('@arcgis/core/Graphic').default[];
     /**
      * This function provides the ability to override either the [arcgis-map.goTo](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/#goTo) or [arcgis-scene.goTo](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#goTo) methods.
      *
@@ -291,8 +359,20 @@ export declare class ArcgisPopup extends LitElement {
      *   return viewElement.goTo(goToParams.target, goToParams.options);
      * };
      * ```
+     * @since 4.8
+     * @see [MapView#goTo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html#goTo)
+     * @see [SceneView#goTo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html#goTo)
+     * @example
+     * // The following snippet uses Search but can be applied to any
+     * // widgets that support the goToOverride property.
+     * search.goToOverride = function(view, goToParams) {
+     *   goToParams.options = {
+     *     duration: updatedDuration
+     *   };
+     *   return view.goTo(goToParams.target, goToParams.options);
+     * };
      */
-    goToOverride: nullish | __esri.GoToOverride;
+    goToOverride: import('@arcgis/core/widgets/support/types').GoToOverride | null | undefined;
     /**
      * The title of the popup. This can be set generically on the popup no
      * matter the features that are selected. If the [selected feature](#selectedFeature)
@@ -312,8 +392,12 @@ export declare class ArcgisPopup extends LitElement {
      * // PopupTemplate overrides it
      * popupComponent.title = "Population by zip codes in Southern California";
      * ```
+     * @example
+     * // This title will display in the popup unless a selected feature's
+     * // PopupTemplate overrides it.
+     * view.popup.viewModel.title = "Population by zip codes in Southern California";
      */
-    heading: string | nullish;
+    heading: string | null | undefined;
     /**
      * Indicates the heading level to use for the [heading](#heading) of the popup.
      * By default, the heading is rendered
@@ -321,6 +405,7 @@ export declare class ArcgisPopup extends LitElement {
      * in your app, you may need to adjust this heading for proper semantics. This is
      * important for meeting accessibility standards.
      *
+     * @default 2
      * @see [Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
      * @see [heading](#heading)
      * @example
@@ -328,7 +413,6 @@ export declare class ArcgisPopup extends LitElement {
      * <!-- Render the popup heading as a level 3 heading -->
      * <arcgis-popup heading="Popup title" heading-level="3"></arcgis-popup>
      * ```
-     * @default 2
      */
     headingLevel: HeadingLevel;
     /**
@@ -398,7 +482,7 @@ export declare class ArcgisPopup extends LitElement {
      *
      * @default "feature"
      */
-    initialDisplayMode: "list" | "feature";
+    initialDisplayMode: import('@arcgis/core/widgets/Popup/types').InitialDisplayOptions;
     /** The component's default label. */
     label?: string;
     /**
@@ -408,7 +492,6 @@ export declare class ArcgisPopup extends LitElement {
      * property before making the popup [visible](#visible) to the user.
      *
      * @autocast { "byTypeProperty": false }
-     * @see [Intro to popups](../sample-code/intro-popup/index.html)
      * @example
      * ```js
      * // Sets the location of the popup to the center of the view
@@ -431,8 +514,20 @@ export declare class ArcgisPopup extends LitElement {
      *   popupComponent.visible = true;
      * });
      * ```
+     * @see [Get started with popups](https://developers.arcgis.com/javascript/latest/sample-code/intro-popup/)
+     * @example
+     * // Sets the location of the popup to the center of the view
+     * view.popup.viewModel.location = view.center;
+     * // Displays the popup
+     * view.popup.visible =  true;
+     * @example
+     * // Display a popup when and where the user clicks the view.
+     * reactiveUtils.on(()=>view, "click", ({ mapPoint })=>{
+     *   view.popup.viewModel.location = mapPoint;
+     *   view.popup.visible = true;
+     * });
      */
-    location: nullish | __esri.Point;
+    location: import('@arcgis/core/geometry/Point').default | null | undefined;
     /** Overwrite localized strings for this component */
     messageOverrides?: typeof this.messages._overrides;
     /**
@@ -441,7 +536,7 @@ export declare class ArcgisPopup extends LitElement {
      * resolved they are removed from this array and the features they return
      * are pushed into the [features](#features) array.
      */
-    promises: Promise<__esri.Graphic[]>[];
+    promises: Promise<import('@arcgis/core/Graphic').default[]>[];
     /**
      * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
      *
@@ -458,7 +553,7 @@ export declare class ArcgisPopup extends LitElement {
      * determined based on the [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html) assigned to
      * this feature.
      */
-    readonly selectedFeature: nullish | __esri.Graphic;
+    readonly selectedFeature: import('@arcgis/core/Graphic').default | null;
     /**
      * Returns a reference to the current [arcgis-feature](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-feature/) that the Popup is using.
      * This is useful if needing to get a reference to the component in order to make any changes to it.
@@ -474,18 +569,27 @@ export declare class ArcgisPopup extends LitElement {
      *
      * @default "disabled"
      */
-    readonly state: "ready" | "disabled";
+    readonly state: import('@arcgis/core/widgets/Popup/types').State;
+    /**
+     * The view associated with the component.
+     *   > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the Popup component will be associated with a map or scene component rather than using the `view` property.
+     */
+    view?: import('@arcgis/core/views/MapViewOrSceneView').MapViewOrSceneView | null | undefined;
     /**
      * Indicates whether the popup is visible. This property is `true` when the popup is querying for results, even if it is not open.
-     * Use the property to check if the popup is visible and is not.
+     * Use the property to check if the popup is visible.
      *
+     * @default false
      * @name visible
      * @type {boolean}
-     * @default false
+     * @see [active](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Features-FeaturesViewModel.html#active)
      */
     visible: boolean;
-    /** @internal */
-    handleViewClick(event: Event): Promise<void>;
+    /**
+     * @param event
+     * @internal
+     */
+    handleViewClick(event: __esri.ViewClickEvent): Promise<__esri.FeaturesViewModelOpenOptions>;
     /**
      * Removes all [promises](#promises), [features](#features), [content](#content),
      * [heading](#heading) and [location](#location) from the Popup.
@@ -499,6 +603,8 @@ export declare class ArcgisPopup extends LitElement {
      * in the [view](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-View.html). In order to use this, a layer must already have an
      * associated [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html) and have its [popupEnabled](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-FeatureLayer.html#popupEnabled).
      *
+     * @param screenPoint
+     * @param options
      * @example
      * ```js
      * // Example showing how to use fetchFeatures in an application
@@ -537,6 +643,7 @@ export declare class ArcgisPopup extends LitElement {
      * The popup will only display if the [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/) or [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/) size constraints in [dockOptions](#dockOptions) are met or the [location](#location)
      * property is set to a geometry.
      *
+     * @param options
      * @see [visible](#visible)
      * @example
      * ```js
@@ -585,15 +692,17 @@ export declare class ArcgisPopup extends LitElement {
      * @see [selectedFeatureIndex](#selectedFeatureIndex)
      */
     previous(): Promise<FeaturesViewModel>;
-    /** Use this method to give focus to the Widget if the widget is able to be focused. */
+    /** Use this method to give focus to the component if the component is able to be focused. */
     setFocus(): Promise<void>;
     /**
      * Triggers the [arcgisTriggerAction](#arcgisTriggerAction) event and executes the [action](#actions)
      * at the specified index in the [actions](#actions) array.
+     *
+     * @param action
      */
     triggerAction(action: __esri.ActionButton | __esri.ActionToggle): Promise<void>;
     readonly arcgisPropertyChange: TargetedEvent<this, {
-        name: "state" | "active" | "collapsed" | "featureCount" | "visible" | "selectedFeature" | "featureMenuOpen" | "features" | "promises" | "selectedFeatureIndex" | "selectedDrillInFeature" | "selectedFeatureComponent" | "currentAlignment" | "dockEnabled";
+        name: "active" | "state" | "collapsed" | "featureCount" | "featureMenuOpen" | "features" | "promises" | "selectedDrillInFeature" | "selectedFeature" | "selectedFeatureComponent" | "selectedFeatureIndex" | "visible" | "currentAlignment" | "dockEnabled";
     }>;
     /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
     readonly arcgisReady: TargetedEvent<this, void>;
@@ -642,7 +751,7 @@ export declare class ArcgisPopup extends LitElement {
      * });
      * ```
      */
-    readonly arcgisTriggerAction: TargetedEvent<this, __esri.PopupTriggerActionEvent>;
+    readonly arcgisTriggerAction: TargetedEvent<this, import('@arcgis/core/widgets/Popup/types').ActionEvent>;
     private messages;
 }
 export {};