@arcgis/map-components 6.0.0-next.16 → 6.0.0-next.17

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

@@ -17,11 +17,164 @@ import type { ArcgisUtilityNetworkTraceFunctionsResultItem } from "../arcgis-uti
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
 /**
- * This is a sub-component used by the **ArcgisUtilityNetworkTraceAnalysis** component.
- * It displays a subset of trace result types.
+ * The Utility Network Trace Results component displays the outcome of a single utility network trace, including its
+ * results, an empty result, or an error.
  *
- * @slot  - Default slot for adding trace result items or custom content to the component.
+ * This component displays results for the following trace result types:
+ * [elements](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements),
+ * [aggregated geometries](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#aggregatedGeometry),
+ * and [functions](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#globalFunctionResults).
+ *
+ * Each result type is displayed by a result item component. By default, this component displays the
+ * result items for the result types returned by the trace. To choose which result items are displayed
+ * or configure their properties individually, add the
+ * [elements result item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/),
+ * [aggregated geometry result item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/), or
+ * [functions result item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/) to this component's default slot.
+ * When the default slot has content, the component displays the slotted content instead of the default result items.
+ *
+ * ## Use in the trace analysis component's results slot
+ *
+ * By default, the [arcgis-utility-network-trace-analysis](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/) component displays aggregated geometry,
+ * elements, and functions in its results tab when those result types are returned by the trace.
+ * You do not need to slot a results component for this default display configuration. Only slot this component into
+ * the trace analysis component's `results` slot when you want to customize the result items in the results tab:
+ * choose which items are displayed, configure their properties, or add custom result items.
+ *
+ * When this component is slotted into the `results` slot of the trace analysis component,
+ * the parent trace analysis component sets the
+ * [trace result](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceResult),
+ * [trace error](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceError),
+ * [utility network](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#utilityNetwork), and
+ * [view](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#view) properties.
+ *
+ * See the [custom result items example](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#custom-result-items-example).
+ *
+ * ## Use in a custom app outside the trace analysis component
+ *
+ * To use the component outside of the trace analysis component, slot it into the default slot of
+ * [arcgis-utility-network-trace-results-pane](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results-pane/). This is useful in custom trace workflow applications
+ * that display multiple trace results at once or configure each results component independently. Add one trace results
+ * component for each trace result and set its properties directly. The pane provides the results container; it does
+ * not run traces or synchronize the results components' properties. Your application supplies each component's
+ * `traceResult`, `traceError`, `utilityNetwork`, and `view` and manages clearing them.
+ *
+ * The [view](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#view) property is required for elements and aggregated
+ * geometry results. The [utilityNetwork](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#utilityNetwork) property is required
+ * to query features for elements results.
+ *
+ * See the [multiple trace results example](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#multiple-trace-results-example).
+ *
+ * @slot
+ *  - Default slot for adding trace result items or custom content.
+ * Slotted content replaces the component's default result items.
  * @since 5.2
+ * @example
+ * <span id="custom-result-items-example"></span>
+ *
+ * The following example customizes the display of element results. Other result types are not displayed because the
+ * component's default slot contains only an element result item.
+ * ```html
+ * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+ *   <arcgis-utility-network-trace-analysis slot="bottom-left">
+ *     <arcgis-utility-network-trace-results slot="results">
+ *       <arcgis-utility-network-trace-elements-result-item
+ *         heading="Feature results"
+ *         hide-action-bar
+ *       ></arcgis-utility-network-trace-elements-result-item>
+ *     </arcgis-utility-network-trace-results>
+ *   </arcgis-utility-network-trace-analysis>
+ * </arcgis-map>
+ * ```
+ * @example
+ * Using the markup above, register these listeners before running a trace to respond to result and error changes and
+ * access queried features after all result items finish processing.
+ * ```js
+ * const results = document.querySelector("arcgis-utility-network-trace-results");
+ *
+ * results.addEventListener("arcgisPropertyChange", (event) => {
+ *   if (event.target !== results) {
+ *     return;
+ *   }
+ *
+ *   if (event.detail.name === "traceResult") {
+ *     console.log("Trace result:", results.traceResult);
+ *   } else if (event.detail.name === "traceError") {
+ *     if (results.traceError) {
+ *       console.error("Trace error:", results.traceError);
+ *     }
+ *   }
+ * });
+ *
+ * results.addEventListener("arcgisResultsReady", () => {
+ *   console.log("Result items ready:", results.traceResultFeatures);
+ * });
+ * ```
+ * @example
+ * <span id="multiple-trace-results-example"></span>
+ *
+ * Display two trace results in the default slot of a results pane, without a trace analysis component.
+ * Each results component has its own heading and display settings. Unlike the first example, neither component
+ * uses `slot="results"` because both are assigned to the pane's default slot.
+ * ```html
+ * <arcgis-utility-network-trace-results-pane id="trace-results-pane">
+ *   <arcgis-utility-network-trace-results
+ *     id="upstream-results"
+ *     heading="Upstream trace"
+ *     expandable
+ *     expanded
+ *     hide-action-bar
+ *   ></arcgis-utility-network-trace-results>
+ *   <arcgis-utility-network-trace-results
+ *     id="downstream-results"
+ *     heading="Downstream trace"
+ *     expandable
+ *     expanded
+ *     disable-highlight-feature-results
+ *   ></arcgis-utility-network-trace-results>
+ * </arcgis-utility-network-trace-results-pane>
+ * <calcite-button id="clear-trace-results">Clear results</calcite-button>
+ * ```
+ *
+ * In the following JavaScript, `view` is the application's ready MapView, `utilityNetwork` is its loaded utility
+ * network, and `upstreamTraceResult` and `downstreamTraceResult` are `TraceResult` objects returned by the application's
+ * trace workflow. Set the view and utility network before assigning each trace result.
+ * ```js
+ * const pane = document.getElementById("trace-results-pane");
+ * const upstreamResults = document.getElementById("upstream-results");
+ * const downstreamResults = document.getElementById("downstream-results");
+ * const resultsComponents = [upstreamResults, downstreamResults];
+ *
+ * await Promise.all([pane.componentOnReady(), ...resultsComponents.map((results) => results.componentOnReady())]);
+ *
+ * for (const results of resultsComponents) {
+ *   results.view = view;
+ *   results.utilityNetwork = utilityNetwork;
+ * }
+ *
+ * upstreamResults.traceResult = upstreamTraceResult;
+ * downstreamResults.traceResult = downstreamTraceResult;
+ *
+ * document.getElementById("clear-trace-results").addEventListener("click", () => {
+ *   for (const results of resultsComponents) {
+ *     results.clearResults();
+ *     results.traceResult = undefined;
+ *     results.traceError = undefined;
+ *   }
+ *   pane.flowItems.removeAll();
+ * });
+ * ```
+ *
+ * If a trace fails, clear the corresponding component's `traceResult` and assign the error to its `traceError`
+ * property. The other results component can continue displaying its result. Before displaying a subsequent
+ * successful result, reset that component's `traceError` to `undefined`.
+ * @see [arcgis-utility-network-trace-analysis](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/)
+ * @see [arcgis-utility-network-trace-results-pane](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results-pane/)
+ * @see [arcgis-utility-network-trace-aggregated-geometry-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/)
+ * @see [arcgis-utility-network-trace-elements-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/)
+ * @see [arcgis-utility-network-trace-functions-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/)
+ * @see [Trace a utility network](https://pro.arcgis.com/en/pro-app/latest/help/data/utility-network/trace-utility-network.htm)
+ * @see [Result types](https://pro.arcgis.com/en/pro-app/latest/help/data/utility-network/configure-a-trace.htm#ESRI_SECTION1_9F21343F66554B65B42A3359477D0D2E)
  */
 export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
   /** @internal */
@@ -77,14 +230,14 @@ export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
    * [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.
+   * The default is yellow with 0.6 opacity.
    */
   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.
+   * The default is `12`.
    *
    * @default 12
    */
@@ -110,37 +263,41 @@ export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
   accessor autoDestroyDisabled: boolean;
   /**
    * 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.
+   *
+   * Disabling highlights does not prevent the component from querying features or affect aggregated geometry graphics.
    *
    * @default false
    */
   accessor disableHighlightFeatureResults: boolean;
   /**
-   * When `true`, the component can be expanded and collapsed.
+   * Whether the component can be expanded and collapsed.
    *
    * @default false
    */
   accessor expandable: boolean;
   /**
-   * When `true`, expands the component and its contents.
+   * Whether the component and its contents are expanded when
+   * [expandable](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#expandable) is `true`.
    *
    * @default false
    */
   accessor expanded: boolean;
-  /** Specifies the component's heading text. */
+  /** The description displayed below the component's localized trace results heading. */
   accessor heading: string | undefined;
   /**
-   * Indicates whether to hide the action bar that holds the feature's
-   * [arcgis-features-next.actions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/#actions) when viewing trace result features.
+   * Whether to hide the action bar when viewing trace result features.
+   * The action bar contains the feature's [actions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/#actions).
    *
    * @default false
    */
   accessor hideActionBar: boolean;
   /**
-   * Whether to hide feature results.
+   * Whether to hide the elements result item and its features list.
    *
-   * A message will be displayed in its place indicating that features were returned by the trace, but are not visible in the component.
-   * This string can be overridden with the [messageOverrides](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#messageOverrides) property.
+   * When `true`, the component displays a placeholder instead. Features are still queried and remain available from
+   * [traceResultFeatures](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceResultFeatures). This property does not disable
+   * highlighting; use [disableHighlightFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#disableHighlightFeatureResults) to hide
+   * feature highlights.
    *
    * @default false
    */
@@ -149,11 +306,13 @@ export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
    * 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.
    *
+   * Hidden graphics remain available from the [arcgis-utility-network-trace-aggregated-geometry-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/) component.
+   *
    * @default false
    */
   accessor hideGraphics: boolean;
   /**
-   * Whether to hide the placeholder string when feature results are hidden.
+   * Whether to hide the placeholder shown when feature results are hidden.
    *
    * When this property and [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#hideFeatureResults) are both set to `true`,
    * nothing is rendered for trace result elements. However, features are still queried and are available through
@@ -163,13 +322,21 @@ export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
    */
   accessor hidePlaceholder: boolean;
   /**
-   * Indicates whether default actions are disabled (hidden) when viewing trace result features.
-   * This property must be set to `true` to disable default actions.
+   * Whether to hide the default actions when viewing trace result features.
    *
    * @default false
    */
   accessor includeDefaultActionsDisabled: boolean;
-  /** The layers and tables used to query trace result features. */
+  /**
+   * The utility network layers and tables used to query trace result features.
+   *
+   * When the array is empty, the component uses layers and tables in the map that belong to
+   * [utilityNetwork](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#utilityNetwork). Entries that do not belong to that utility
+   * network are ignored.
+   *
+   * Set this property before assigning a trace result. Changing it does not requery the current result or restrict
+   * highlighting.
+   */
   accessor layers: Layer[];
   /**
    * Replace localized message strings with your own strings.
@@ -196,11 +363,13 @@ export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
       traceFailedHeading?: string | undefined;
   };
   /**
-   * The number of unique network element results, including elements that did not match any layer in the map.
+   * The number of successfully queried features plus unique trace elements without a matching layer in the map.
    *
-   * If multiple slotted instances [arcgis-utility-network-trace-elements-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/) exist,
-   * this property returns the [number of feature results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#numResults)
-   * for the first instance.
+   * If the default slot contains multiple [arcgis-utility-network-trace-elements-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/)
+   * components, this property returns the
+   * [result count](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#numResults) from the first one.
+   * This value can be lower than the number of elements returned by the trace when feature queries fail or return no
+   * matching features.
    */
   get numFeatureResults(): number;
   /**
@@ -210,34 +379,70 @@ export abstract class ArcgisUtilityNetworkTraceResults extends LitElement {
    */
   accessor referenceElement: ArcgisReferenceElement | string | undefined;
   /**
-   * The current state of the trace results component.
+   * The processing state of the component: `"loading"` while result items process a trace result and `"ready"` when no
+   * processing is in progress. A `"ready"` state does not necessarily mean that every result item succeeded.
    *
    * @default "ready"
    */
   get state(): UtilityNetworkTraceResultItemState;
-  /** The error returned when the trace could not be completed. */
+  /**
+   * The error returned when the trace could not be completed.
+   *
+   * When set, the component displays the error instead of [traceResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceResult).
+   * Changes emit [@arcgisPropertyChange](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#event-arcgisPropertyChange).
+   */
   accessor traceError: EsriError<TraceErrorDetails> | undefined;
-  /** The trace result to display. */
+  /**
+   * The trace result to display.
+   *
+   * Assigning a new value clears side effects from the previous result and starts a new processing cycle. It does not
+   * emit [@arcgisTraceResultClear](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#event-arcgisTraceResultClear). Changes emit
+   * [@arcgisPropertyChange](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#event-arcgisPropertyChange).
+   */
   accessor traceResult: TraceResult | undefined;
   /**
-   * The features corresponding to the
-   * [https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements)
-   * returned by the trace result.
+   * The features successfully queried for the current trace result elements.
+   *
+   * Read this property after [@arcgisResultsReady](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#event-arcgisResultsReady) fires.
+   * Elements without a matching query layer are not included. If the default slot contains multiple
+   * [arcgis-utility-network-trace-elements-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/) components, this property returns features
+   * from the first one.
    */
   get traceResultFeatures(): Graphic[];
-  /** The utility network used to query trace result features. */
+  /** The utility network used to resolve trace result elements to features. */
   accessor utilityNetwork: UtilityNetwork | undefined;
+  /** The [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) used to display and highlight trace results. */
+  accessor view: MapView | undefined;
   /**
-   * 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-results component will be associated with a map or scene component rather than using the `view` property.
+   * Clears side effects created by the result items, resets
+   * [state](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#state) to `"ready"`, and emits
+   * [@arcgisTraceResultClear](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#event-arcgisTraceResultClear).
+   *
+   * When this component is managed by [arcgis-utility-network-trace-analysis](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/), using the parent
+   * component's clear results action also clears its synchronized
+   * [traceResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceResult) and
+   * [traceError](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceError) values. Calling this method directly does not
+   * change those properties; set them to `undefined` when using this component independently.
    */
-  accessor view: MapView | undefined;
   clearResults(): void;
   /** Permanently destroy the component. */
   destroy(): Promise<void>;
   /** 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" | "aggregatedGeometryResultsSize" | "hideGraphics" | "state" | "traceError" | "traceResult" | "utilityNetwork" | "view"; }>;
+  /**
+   * Fires when all participating result items finish processing the current
+   * [traceResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceResult), including when processing produces no results
+   * or a result item fails.
+   *
+   * Calling [clearResults()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#clearResults) during processing does not emit this
+   * event.
+   */
   readonly arcgisResultsReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when [clearResults()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#clearResults) is called.
+   * Replacing or clearing [traceResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/#traceResult) directly does not emit
+   * this event.
+   */
   readonly arcgisTraceResultClear: import("@arcgis/lumina").TargetedEvent<this, void>;
   /** Emitted when an action is triggered on the component. */
   readonly arcgisTriggerAction: import("@arcgis/lumina").TargetedEvent<this, ActionEvent>;