/// <reference path="../../index.d.ts" />
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";

/**
 * ## 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, stopping 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` (deprecated), `path`, `subnetwork`, `subnetwork-controller`, `loops`, and `isolation`.
 *
 * > [!WARNING]
 * >
 * > The [shortest path trace type](https://pro.arcgis.com/en/pro-app/latest/help/data/trace-network/discover-the-shortest-path.htm) is deprecated with ArcGIS Pro 3.7 and ArcGIS Enterprise 12.1.
 * >
 * > While the shortest path trace will continue to function and be an option until the next major release, it is recommended to use the path trace to return the shortest path.
 * > The path trace provides the same functionality to return a shortest path result while offering additional capabilities to find paths in your network.
 *
 * 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 the following:
 * >
 * > 1. Proxied feature services or feature services that utilize stored credentials.
 * > 2. The `circuit` trace type or the `paths` and `circuits` result types.
 * > 3. Setting grouping properties `firstUnit` and `lastUnit` for trace locations in a [telecom domain network](https://pro.arcgis.com/en/pro-app/latest/help/data/utility-network/telecom-domain-networks.htm).
 * >    If a [grouped object](https://doc.esri.com/en/arcgis-pro/latest/help/data/utility-network/grouping.html) is used as a trace location, its `firstUnit` and `lastUnit` attributes are not used in the trace.
 *
 * ## 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;
          };
          missingTerminalBody: string;
          missingTerminalTitle: 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;
          };
          missingTerminalBody: string;
          missingTerminalTitle: 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-utility-network-trace-analysis>
   * </arcgis-map>
   * ```
   */
  accessor disableHighlightFeatureResults: boolean;
  /**
   * 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.
   *
   * @default false
   * @internal
   */
  accessor hideActionBar: 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-utility-network-trace-analysis>
   * </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;
          missingTerminalBody?: string | undefined;
          missingTerminalTitle?: string | 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"];
  };
}