@arcgis/map-components 5.2.0-next.16 → 5.2.0-next.160

package/dist/components/arcgis-utility-network-trace-analysis/customElement.d.ts

@@ -1,10 +1,17 @@
 /// <reference path="../../index.d.ts" />
 import type Color from "@arcgis/core/Color.js";
+import type Collection from "@arcgis/core/core/Collection.js";
+import type EsriError from "@arcgis/core/core/Error.js";
 import type Graphic from "@arcgis/core/Graphic.js";
+import type TraceResult from "@arcgis/core/rest/networks/support/TraceResult.js";
 import type MapView from "@arcgis/core/views/MapView.js";
+import type { ActionEvent } from "@arcgis/core/widgets/Popup/types.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { FlowItem } from "@esri/calcite-components/components/calcite-flow-item";
+import type { ArcgisFeaturesNext } from "../arcgis-features-next/customElement.js";
 import type { ArcgisReferenceElement } from "../types.js";
-import type { SelectStartPayload } from "../arcgis-utility-network-trace-location/customElement.js";
+import type { ArcgisUtilityNetworkTraceInputs } from "../arcgis-utility-network-trace-inputs/customElement.js";
+import type { SelectStartPayload } from "../arcgis-utility-network-trace-locations/customElement.js";
 import type { ArcgisUtilityNetworkTraceResults } from "../arcgis-utility-network-trace-results/customElement.js";
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 import type { UtilityNetworkTraceAnalysisState } from "@arcgis/core/networks/UtilityNetworkTraceAnalysis.js";
@@ -12,6 +19,12 @@ import type { UtilityNetworkTraceAnalysisState } from "@arcgis/core/networks/Uti
 /**
  * ## Overview
  *
+ * > [!WARNING]
+ * > This component is the successor to the `utility-network-trace-analysis` component.
+ * > The `utility-network-trace-analysis` component is being substantially refactored to expose public trace sub-components in release 5.2 and 6.0.
+ * > To avoid destabilizing the public version of `utility-network-trace-analysis`, the refactoring work is being performed in this component.
+ * > At release, this "next" component will replace the original.
+ *
  * The Utility Network Trace Analysis component allows users to run traces and view trace results in a utility network.
  *
  * - The component supports selecting a utility network and a named trace configuration in that utility network. Both the utility network and trace configuration must be [stored in the map](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#utilityNetworks).
@@ -68,7 +81,7 @@ import type { UtilityNetworkTraceAnalysisState } from "@arcgis/core/networks/Uti
  *
  * ```html
  * <calcite-shell>
- *   <calcite-shell-panel slot="panel-start" position="start" width-scale="l">
+ *   <calcite-shell-panel slot="panel-start" position="start" width="l">
  *     <arcgis-utility-network-trace-analysis reference-element="#map-element"></arcgis-utility-network-trace-analysis>
  *   </calcite-shell-panel>
  *   <arcgis-map id="map-element" item-id="471eb0bf37074b1fbb972b1da70fb310"></arcgis-map>
@@ -77,6 +90,10 @@ import type { UtilityNetworkTraceAnalysisState } from "@arcgis/core/networks/Uti
  *
  * Note: Sign in to access the data in this demo, U/P: `viewer01`/`I68VGU^nMurF`
  *
+ * @slot
+ * [results] - Slot for instances of [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/),
+ * for displaying the results of one or more traces.
+ * @internal
  * @since 5.0
  */
 export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
@@ -100,11 +117,6 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
           noStartingPointsBody: string;
           noStartingPointsTitle: string;
       };
-      labels: {
-          traceConfiguration: string;
-          traceInputs: string;
-          utilityNetwork: string;
-      };
       runningTrace: string;
       tabs: {
           inputTab: string;
@@ -129,17 +141,22 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
           noStartingPointsBody: string;
           noStartingPointsTitle: string;
       };
-      labels: {
-          traceConfiguration: string;
-          traceInputs: string;
-          utilityNetwork: string;
-      };
       runningTrace: string;
       tabs: {
           inputTab: string;
           resultsTab: string;
       };
   }>;
+  /**
+   * A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of [action button](https://developers.arcgis.com/javascript/latest/references/core/support/actions/ActionButton/) or [action toggle](https://developers.arcgis.com/javascript/latest/references/core/support/actions/ActionToggle/) objects. Each action may be executed by clicking the icon or image symbolizing them.
+   * There is a default `Zoom To` action styled with a magnifying glass icon to zoom in four LODs and center the map on the selected feature. This default action can be removed by setting [includeDefaultActionsDisabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#includeDefaultActionsDisabled) to `true`, or by setting the [`overwriteActions`](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/#overwriteActions) property to `true` in a [PopupTemplate](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/).
+   *
+   * The order of each action is the order in which they appear in the actions [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/). The [@arcgisTriggerAction](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#event-arcgisTriggerAction) event fires each time an action is clicked.
+   *
+   * @see [@arcgisTriggerAction](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#event-arcgisTriggerAction)
+   * @see [Popup actions sample](https://developers.arcgis.com/javascript/latest/sample-code/popup-actions/)
+   */
+  accessor actions: ArcgisFeaturesNext["actions"] | undefined;
   /**
    * The color used to render graphics for aggregated geometries in trace results, specified as a
    * [Color](https://developers.arcgis.com/javascript/latest/references/core/Color/) object.
@@ -148,9 +165,40 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    *
    * Default color is #FFFF00.
    *
+   * @example
+   * Set the default aggregated geometry graphics color to lime green in JavaScript.
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.aggregatedGeometryResultsGraphicsColor = new Color("lime");
+   * ```
+   * @example
+   * Set the default aggregated geometry graphics color to red in HTML.
+   * ```html
+   * <arcgis-map item-id="967a4180aa6c46b68996ea9406e8a606">
+   *   <arcgis-utility-network-trace-analysis slot="bottom-left" aggregated-geometry-graphics-color="red">
+   *   </arcgis-utility-network-trace-analysis>
+   * </arcgis-map>
+   * ```
    * @see [Color constructor](https://developers.arcgis.com/javascript/latest/references/core/Color/#constructors-summary)
    */
-  accessor aggregatedGeometryGraphicsColor: Color;
+  accessor aggregatedGeometryResultsGraphicsColor: Color;
+  /**
+   * The size in points used to render graphics for aggregated geometries in trace results.
+   *
+   * Aggregated geometry is only rendered if the trace configuration specifies aggregated geometry as a result type.
+   *
+   * @default 12
+   * @example
+   * Set the default aggregated geometry graphics size to 8 points.
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.aggregatedGeometryResultsSize = 8;
+   * ```
+   * @since 5.2
+   * @see [SimpleMarkerSymbol size](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/#size)
+   * @see [SimpleLineSymbol width](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleLineSymbol/#width)
+   */
+  accessor aggregatedGeometryResultsSize: number;
   /**
    * If true, the component will not be destroyed automatically when it is
    * disconnected from the document. This is useful when you want to move the
@@ -159,6 +207,15 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    * prevent memory leaks.
    *
    * @default false
+   * @example
+   * ```html
+   * <arcgis-utility-network-trace-analysis auto-destroy-disabled></arcgis-utility-network-trace-analysis>
+   * ```
+   *
+   * ```js
+   * utilityNetworkTraceAnalysisElement.autoDestroyDisabled = true;
+   * ```
+   * 
    */
   accessor autoDestroyDisabled: boolean;
   /**
@@ -168,10 +225,10 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    * @example
    * ```js
    * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
-   * traceElement.beforeTraceLocationSelectStart = async () => await doAsyncWork();
+   * traceElement.beforeMapInteraction = async () => await doAsyncWork();
    * ```
    */
-  accessor beforeTraceLocationSelectStart: (() => Promise<void>) | undefined;
+  accessor beforeMapInteraction: (() => Promise<void>) | undefined;
   /**
    * Whether to disable highlighting trace result features on the map.
    *
@@ -188,15 +245,28 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    * ```
    */
   accessor disableHighlightFeatureResults: boolean;
+  /**
+   * Additional Calcite Flow Items displayed in the Results tab.
+   * Add or remove native `calcite-flow-item` elements through this Collection.
+   *
+   * @since 5.2
+   */
+  get flowItems(): Collection<FlowItem>;
   /**
    * Indicates whether to hide the action bar that holds the feature's
-   * [actions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features/#actions)
-   * when selecting trace locations and viewing trace result features.
+   * [arcgis-features-next.actions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/#actions) when selecting trace locations
+   * and viewing trace result features.
    *
    * @default false
-   * @internal
    */
   accessor hideActionBar: boolean;
+  /**
+   * Whether to hide the count of features next to the "Clear results" button in the Results tab for trace results
+   * which include [elements](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements).
+   *
+   * @default false
+   */
+  accessor hideClearResultsCount: boolean;
   /**
    * Whether to hide feature results in the results tab.
    *
@@ -221,14 +291,54 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    * ```
    */
   accessor hideFeatureResults: boolean;
-  /** The component's default label. */
+  /**
+   * Whether to hide the aggregated geometry [graphics](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#geometryGraphics)
+   * from the map when the trace result contains aggregated geometry results.
+   *
+   * @default false
+   */
+  accessor hideGraphics: boolean;
+  /**
+   * Whether to hide the placeholder string when feature results are hidden in the results tab.
+   *
+   * When this property and [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#hideFeatureResults) are both set to `true`,
+   * nothing is rendered for trace result elements. However, features are still queried and are available through
+   * [traceResultFeatures](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#traceResultFeatures).
+   *
+   * @default false
+   * @example
+   * Hide the placeholder when feature results are hidden.
+   * ```html
+   * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+   *   <arcgis-utility-network-trace-analysis
+   *     hide-feature-results
+   *     hide-placeholder
+   *     slot="top-right"
+   *   ></arcgis-utility-network-trace-analysis>
+   * </arcgis-map>
+   * ```
+   */
+  accessor hidePlaceholder: boolean;
+  /**
+   * Indicates whether default actions are disabled (hidden) when
+   * selecting trace locations and viewing trace result features.
+   * This property must be set to `true` to disable default actions.
+   *
+   * @default false
+   */
+  accessor includeDefaultActionsDisabled: boolean;
+  /**
+   * The component's default label.
+   *
+   * @deprecated since 5.2. This property has no effect.
+   */
   accessor label: string | undefined;
   /**
    * Replace localized message strings with your own strings.
    *
    * _**Note**: Individual message keys may change between releases._
    */
-  accessor messageOverrides: Pick<ArcgisUtilityNetworkTraceResults["_messages"], "resultFeaturesAreHidden"> & {
+  accessor messageOverrides: NonNullable<ArcgisUtilityNetworkTraceInputs["messageOverrides"]> & NonNullable<ArcgisUtilityNetworkTraceResults["messageOverrides"]> & {
       buttons?: {
           clearResultsCustom?: string | undefined;
           clearResultsGeneric?: string | undefined;
@@ -247,11 +357,6 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
           noStartingPointsBody?: string | undefined;
           noStartingPointsTitle?: string | undefined;
       } | undefined;
-      labels?: {
-          traceConfiguration?: string | undefined;
-          traceInputs?: string | undefined;
-          utilityNetwork?: string | undefined;
-      } | undefined;
       runningTrace?: string | undefined;
       tabs?: {
           inputTab?: string | undefined;
@@ -266,6 +371,8 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
   accessor referenceElement: ArcgisReferenceElement | string | undefined;
   /** The current state of the component. */
   get state(): UtilityNetworkTraceAnalysisState;
+  get traceError(): EsriError | undefined;
+  accessor traceResult: TraceResult | undefined;
   /**
    * An array of features returned by the trace result.
    *
@@ -276,17 +383,19 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    */
   get traceResultFeatures(): Graphic[];
   /**
-   * 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 arcgis-utility-network-trace-analysis component will be associated with a map or scene component rather than using the `view` property.
+   * 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 arcgis-utility-network-trace-analysis component will be associated with a map or scene component rather than using the `view` property.
    */
   accessor view: MapView | null | undefined;
   /** Permanently destroy the component. */
   destroy(): Promise<void>;
+  readonly arcgisError: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
    * Fires when the user toggles displaying aggregated geometry results in the result pane.
    * Event payload contains a boolean representing whether the aggregated geometry graphics are hidden.
    * If true, the aggregated geometry graphics are hidden on the view.
    *
+   * @deprecated since 5.2. Use [@arcgisPropertyChange](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#event-arcgisPropertyChange) instead.
    * @example
    * ```js
    * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
@@ -297,7 +406,9 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    * ```
    */
   readonly arcgisHideGraphicsChange: import("@arcgis/lumina").TargetedEvent<this, boolean>;
-  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
+  /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
+  readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "aggregatedGeometryResultsGraphicsColor" | "hideGraphics" | "state" | "traceError" | "traceResult"; }>;
+  /** Emitted when the component associated with a map or scene view is ready for user interaction. */
   readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
    * Fires when the user completes the selection of a trace location.
@@ -340,7 +451,7 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    */
   readonly arcgisTraceLocationSelectStart: import("@arcgis/lumina").TargetedEvent<this, SelectStartPayload>;
   /**
-   * Fires when the trace result is cleared from the results tab.
+   * Fires when trace results and errors are cleared from the results tab.
    *
    * @example
    * ```js
@@ -365,12 +476,30 @@ export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
    * ```
    */
   readonly arcgisTraceResultFeaturesReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when the trace result is ready.
+   *
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisTraceResultReady", (event) => {
+   *   console.log("Trace result is ready.");
+   * });
+   * ```
+   */
+  readonly arcgisTraceResultReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /** Emitted when an action is triggered on the component. */
+  readonly arcgisTriggerAction: import("@arcgis/lumina").TargetedEvent<this, ActionEvent>;
   readonly "@eventTypes": {
+    arcgisError: ArcgisUtilityNetworkTraceAnalysis["arcgisError"]["detail"];
     arcgisHideGraphicsChange: ArcgisUtilityNetworkTraceAnalysis["arcgisHideGraphicsChange"]["detail"];
+    arcgisPropertyChange: ArcgisUtilityNetworkTraceAnalysis["arcgisPropertyChange"]["detail"];
     arcgisReady: ArcgisUtilityNetworkTraceAnalysis["arcgisReady"]["detail"];
     arcgisTraceLocationSelectEnd: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceLocationSelectEnd"]["detail"];
     arcgisTraceLocationSelectStart: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceLocationSelectStart"]["detail"];
     arcgisTraceResultClear: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceResultClear"]["detail"];
     arcgisTraceResultFeaturesReady: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceResultFeaturesReady"]["detail"];
+    arcgisTraceResultReady: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceResultReady"]["detail"];
+    arcgisTriggerAction: ArcgisUtilityNetworkTraceAnalysis["arcgisTriggerAction"]["detail"];
   };
 }