@arcgis/map-components 5.0.0-next.99 → 5.0.0

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

@@ -1,129 +1,349 @@
 /// <reference path="../../index.d.ts" />
-import { default as Graphic } from '@arcgis/core/Graphic';
-import { default as UtilityNetworkTraceAnalysis } from '@arcgis/core/networks/UtilityNetworkTraceAnalysis.js';
-import { default as TraceResult } from '@arcgis/core/rest/networks/support/TraceResult.js';
-import { default as MapView } from '@arcgis/core/views/MapView';
-import { EventEmitter, JsxNode, ToElement, PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
-import { Use } from '@arcgis/lumina/controllers';
-import { ArcgisReferenceElement } from '../../utils/component-utils';
-import { SelectStartPayload } from '../arcgis-utility-network-trace-location/customElement.js';
+import type Color from "@arcgis/core/Color.js";
+import type Graphic from "@arcgis/core/Graphic.js";
+import type MapView from "@arcgis/core/views/MapView.js";
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { ArcgisReferenceElement } from "../types.js";
+import type { SelectStartPayload } from "../arcgis-utility-network-trace-location/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";
 
-declare const useUtilityNetworkTraceAnalysisViewModel: (component: LitElement & Pick<UtilityNetworkTraceAnalysis, never> & import('../../controllers/useViewModel').ViewModelControllerUses<UtilityNetworkTraceAnalysis>) => UtilityNetworkTraceAnalysis;
-/** [Read more...](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-utility-network-trace-analysis/) */
-export declare class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
-    /** @default false */
-    allowEditingDisabled: boolean;
-    /**
-     * 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
-     * component to a different place on the page, or temporarily hide it. If this
-     * is set, make sure to call the [destroy](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-utility-network-trace-analysis/#destroy) method when you are done to
-     * prevent memory leaks.
-     *
-     * @default false
-     */
-    autoDestroyDisabled: boolean;
-    /**
-     * A function to run before trace location selection starts.
-     *
-     * @experimental
-     * @example
-     * ```js
-     * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
-     * traceElement.beforeTraceLocationSelectStart = async () => await doAsyncWork();
-     * ```
-     */
-    beforeTraceLocationSelectStart?: () => Promise<void>;
-    /** @default false */
-    closable: boolean;
-    icon?: string;
-    label?: string;
-    /**
-     * Replace localized message strings with your own strings.
-     *
-     * _**Note**: Individual message keys may change between releases._
-     */
-    messageOverrides?: typeof this._messages._overrides;
-    mode?: string;
-    get traceResultFeatures(): Graphic[];
-    /**
-     * 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.
-     *
-     * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
-     */
-    referenceElement?: ArcgisReferenceElement | string;
-    /**
-     * The current state of the component.
-     *
-     * @since 5.0
-     */
-    readonly state: import('@arcgis/core/networks/UtilityNetworkTraceAnalysis.js').UtilityNetworkTraceAnalysisState;
-    /**
-     * This property defines the target [MapView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html).
-     *
-     * @since 5.0
-     */
-    view?: MapView | null | undefined;
-    /** Permanently destroy the component. */
-    destroy(): Promise<void>;
-    /**
-     * Fires when the user begins selection of a trace location.
-     * Event payload contains a callback method `cancelSelect` to cancel a selection in progress.
-     * The event can also be prevented with `event.preventDefault()` to stop the selection.
-     *
-     * @experimental
-     * @example
-     * ```js
-     * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
-     * traceElement.addEventListener("arcgisTraceLocationSelectStart", (event) => {
-     *   event.preventDefault();
-     * });
-     * ```
-     * @example
-     * ```js
-     * let cancelSelect;
-     * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
-     * traceElement.addEventListener("arcgisTraceLocationSelectStart", (event) => {
-     *   cancelSelect = event.detail.cancelSelect;
-     * });
-     *
-     * setTimeout(() => {
-     *   cancelSelect();
-     * }, 3000);*
-     * ```
-     */
-    readonly arcgisTraceLocationSelectStart: TargetedEvent<this, SelectStartPayload>;
-    /**
-     * Fires when the user completes the selection of a trace location.
-     *
-     * @experimental
-     * @example
-     * ```js
-     * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
-     * traceElement.addEventListener("arcgisTraceLocationSelectEnd", () => {
-     *   console.log("Selection finished!");
-     * });
-     * ```
-     */
-    readonly arcgisTraceLocationSelectEnd: TargetedEvent<this, void>;
-    /**
-     * Fires when the trace result features are ready.
-     * Check property `traceResultFeatures` for the trace result features.
-     *
-     * @experimental
-     * @example
-     * ```js
-     * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
-     * traceElement.addEventListener("arcgisTraceResultFeaturesReady", (event) => {
-     *   const resultFeatures = traceElement.traceResultFeatures;
-     *   console.log(resultFeatures);
-     * });
-     * ```
-     */
-    readonly arcgisTraceResultFeaturesReady: TargetedEvent<this, void>;
-    readonly arcgisPropertyChange: TargetedEvent<this, never>;
-    /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
-    readonly arcgisReady: TargetedEvent<this, void>;
-    private _messages;
-}
-export {};
+/**
+ * ## Overview
+ *
+ * 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).
+ * - Trace locations (starting points and barriers) are set by selecting features on the view.
+ * - When a subnetwork-based trace is selected, the component displays the domain, tier, and target tier specified by the selected named trace configuration.
+ * - If the user selects a subnetwork trace with a specified subnetwork name, the component provides an option to choose a subnetwork name instead of starting location(s) to run the trace with.
+ *
+ * Supported trace types are: `connected`, `upstream`, `downstream`, `shortest-path`, `subnetwork`, `subnetwork-controller`, `loops`, and `isolation`.
+ *
+ * The component can display the following from a trace result: elements (as [features](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#traceResultFeatures)), aggregated geometries, and function results.
+ * If the trace result includes elements that originate from a [feature layer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/)
+ * that is not included in the map, the Results tab displays an `Unknown` layer with a count of those elements.
+ * The component's [traceResultFeatures](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#traceResultFeatures) property also does not include these elements.
+ *
+ * > [!WARNING]
+ * >
+ * > The Utility Network Trace Analysis component does not support proxied feature services or feature services that utilize stored credentials.
+ * >
+ * > This component also does not support `path` and `circuit` trace types or the `paths` and `circuits` result types.
+ *
+ * ## Working with nonspatial objects
+ *
+ * The Utility Network Trace Analysis component supports selecting nonspatial objects as trace locations by traversing associations.
+ *
+ * When selecting a trace location or viewing a trace result feature, information about the feature is displayed according to the
+ * [PopupTemplate](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/) of the layer that the feature belongs to.
+ * If the feature's layer has no PopupTemplate, a default template is used to display the feature's attributes.
+ *
+ * To select a nonspatial object as a trace location, first select a spatial feature on the map that is associated with the target nonspatial object.
+ * The spatial feature's layer must have a PopupTemplate that includes a [UtilityNetworkAssociationsContent](https://developers.arcgis.com/javascript/latest/references/core/popup/content/UtilityNetworkAssociationsContent/).
+ * Navigate through the spatial feature's associations to the target nonspatial object, then add the object as a trace location.
+ *
+ * ## Examples
+ *
+ * This component can be used slotted into an [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/):
+ *
+ * ```html
+ * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+ *   <arcgis-utility-network-trace-analysis slot="bottom-left"></arcgis-utility-network-trace-analysis>
+ * </arcgis-map>
+ * ```
+ *
+ * Alternatively, this component can be used outside of a map by providing a [referenceElement](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#referenceElement):
+ *
+ * ```html
+ * <calcite-shell>
+ *   <calcite-shell-panel slot="panel-start" position="start" width-scale="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>
+ * </calcite-shell>
+ * ```
+ *
+ * Note: Sign in to access the data in this demo, U/P: `viewer01`/`I68VGU^nMurF`
+ *
+ * @since 5.0
+ */
+export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {
+  /** @internal */
+  protected _messages: {
+      buttons: {
+          clearResultsCustom: string;
+          clearResultsGeneric: string;
+          getResults: string;
+      };
+      componentLabel: string;
+      errors: {
+          loadErrors: {
+              noUserTypeExtension: string;
+              noUtilityNetwork: string;
+              noView: string;
+              sceneViewNotSupported: string;
+          };
+          noStartingPointsBody: string;
+          noStartingPointsTitle: string;
+      };
+      labels: {
+          traceConfiguration: string;
+          traceInputs: string;
+          utilityNetwork: string;
+      };
+      runningTrace: string;
+      tabs: {
+          inputTab: string;
+          resultsTab: string;
+      };
+  } & T9nMeta<{
+      buttons: {
+          clearResultsCustom: string;
+          clearResultsGeneric: string;
+          getResults: string;
+      };
+      componentLabel: string;
+      errors: {
+          loadErrors: {
+              noUserTypeExtension: string;
+              noUtilityNetwork: string;
+              noView: string;
+              sceneViewNotSupported: string;
+          };
+          noStartingPointsBody: string;
+          noStartingPointsTitle: string;
+      };
+      labels: {
+          traceConfiguration: string;
+          traceInputs: string;
+          utilityNetwork: string;
+      };
+      runningTrace: string;
+      tabs: {
+          inputTab: string;
+          resultsTab: string;
+      };
+  }>;
+  /**
+   * 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.
+   *
+   * Aggregated geometry is only rendered if the trace configuration specifies aggregated geometry as a result type.
+   *
+   * Default color is #FFFF00.
+   *
+   * @see [Color constructor](https://developers.arcgis.com/javascript/latest/references/core/Color/#constructors-summary)
+   */
+  accessor aggregatedGeometryGraphicsColor: Color;
+  /**
+   * 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
+   * component to a different place on the page, or temporarily hide it. If this
+   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#destroy) method when you are done to
+   * prevent memory leaks.
+   *
+   * @default false
+   */
+  accessor autoDestroyDisabled: boolean;
+  /**
+   * A function to run before trace location selection starts.
+   *
+   * @internal
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.beforeTraceLocationSelectStart = async () => await doAsyncWork();
+   * ```
+   */
+  accessor beforeTraceLocationSelectStart: (() => Promise<void>) | undefined;
+  /**
+   * Whether to disable highlighting trace result features on the map.
+   *
+   * If true, the features returned by a trace will not be highlighted on the map.
+   *
+   * @default false
+   * @example
+   * Disable highlighting trace result features.
+   * ```html
+   * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+   *   <arcgis-utility-network-trace-analysis disable-highlight-feature-results slot="top-right"/>
+   * </arcgis-map>
+   * ```
+   */
+  accessor disableHighlightFeatureResults: boolean;
+  /**
+   * Whether to hide feature results in the results tab.
+   *
+   * If true, when features are returned by a trace, they will not be visible in the results tab.
+   * A message will be displayed in its place indicating that features were returned by the trace, but are not visible in the results pane.
+   * This string can be overridden with the `messageOverrides` property.
+   *
+   * @default false
+   * @example
+   * Do not show features in the results tab.
+   * ```html
+   * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+   *   <arcgis-utility-network-trace-analysis hide-feature-results slot="top-right"/>
+   * </arcgis-map>
+   * ```
+   * @example
+   * Override the message displayed in the results tab when features are hidden.
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.messageOverrides = { resultFeaturesAreHidden: "Feature results were sent to the results window." };
+   * ```
+   */
+  accessor hideFeatureResults: boolean;
+  /** The component's default label. */
+  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"> & {
+      buttons?: {
+          clearResultsCustom?: string | undefined;
+          clearResultsGeneric?: string | undefined;
+          getResults?: string | undefined;
+      } | undefined;
+      componentLabel?: string | undefined;
+      errors?: {
+          loadErrors?: {
+              noUserTypeExtension?: string | undefined;
+              noUtilityNetwork?: string | undefined;
+              noView?: string | undefined;
+              sceneViewNotSupported?: string | undefined;
+          } | undefined;
+          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;
+          resultsTab?: string | undefined;
+      } | undefined;
+  };
+  /**
+   * 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.
+   *
+   * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
+   */
+  accessor referenceElement: ArcgisReferenceElement | string | undefined;
+  /** The current state of the component. */
+  get state(): UtilityNetworkTraceAnalysisState;
+  /**
+   * An array of features returned by the trace result.
+   *
+   * This array is populated if the trace returned [element](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements) results.
+   *
+   * When [@arcgisTraceResultFeaturesReady](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#event-arcgisTraceResultFeaturesReady) is raised, trace result features are available.
+   * When a new trace has been run, or the trace results are cleared, this array is cleared.
+   */
+  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.
+   */
+  accessor view: MapView | null | undefined;
+  /** Permanently destroy the component. */
+  destroy(): Promise<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.
+   *
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisHideGraphicsChange", (event) => {
+   *   const hideGraphics = event.detail;
+   *   console.log(hideGraphics);
+   * });
+   * ```
+   */
+  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. */
+  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when the user completes the selection of a trace location.
+   *
+   * @internal
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisTraceLocationSelectEnd", () => {
+   *   console.log("Selection finished!");
+   * });
+   * ```
+   */
+  readonly arcgisTraceLocationSelectEnd: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when the user begins selection of a trace location.
+   * Event payload contains a callback method `cancelSelect` to cancel a selection in progress.
+   * The event can also be prevented with `event.preventDefault()` to stop the selection.
+   *
+   * @internal
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisTraceLocationSelectStart", (event) => {
+   *   event.preventDefault();
+   * });
+   * ```
+   * @example
+   * ```js
+   * let cancelSelect;
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisTraceLocationSelectStart", (event) => {
+   *   cancelSelect = event.detail.cancelSelect;
+   * });
+   *
+   * setTimeout(() => {
+   *   cancelSelect();
+   * }, 3000);
+   * ```
+   */
+  readonly arcgisTraceLocationSelectStart: import("@arcgis/lumina").TargetedEvent<this, SelectStartPayload>;
+  /**
+   * Fires when the trace result is cleared from the results tab.
+   *
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisTraceResultClear", (event) => {
+   *   console.log("Trace result was cleared.");
+   * });
+   * ```
+   */
+  readonly arcgisTraceResultClear: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when the trace result features are ready.
+   * Check property [traceResultFeatures](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/#traceResultFeatures) for the trace result features.
+   *
+   * @example
+   * ```js
+   * const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
+   * traceElement.addEventListener("arcgisTraceResultFeaturesReady", (event) => {
+   *   const resultFeatures = traceElement.traceResultFeatures;
+   *   console.log(resultFeatures);
+   * });
+   * ```
+   */
+  readonly arcgisTraceResultFeaturesReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  readonly "@eventTypes": {
+    arcgisHideGraphicsChange: ArcgisUtilityNetworkTraceAnalysis["arcgisHideGraphicsChange"]["detail"];
+    arcgisReady: ArcgisUtilityNetworkTraceAnalysis["arcgisReady"]["detail"];
+    arcgisTraceLocationSelectEnd: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceLocationSelectEnd"]["detail"];
+    arcgisTraceLocationSelectStart: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceLocationSelectStart"]["detail"];
+    arcgisTraceResultClear: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceResultClear"]["detail"];
+    arcgisTraceResultFeaturesReady: ArcgisUtilityNetworkTraceAnalysis["arcgisTraceResultFeaturesReady"]["detail"];
+  };
+}